Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Register a New Solution

This is the canonical checklist for starting a new solution on CRAFT. Follow these steps when you’re past the Quickstart prototype and ready to make the solution real.
Most decisions here are conventions — the platform doesn’t force you, but solutions that follow the conventions get free deployment, observability, and CI integration.

​
Registration sequence

The dashed sequence is the order, not the schedule — most solutions land steps 1–4 in one PR, 5 in the next, and 6/7/8 incrementally. Steps 6 and 7 are conditional; only Tier 3 agentic solutions need them up front.

​
Pre-flight checklist

Lowercase, alphanumeric + hyphens only, ≤ 30 chars. Used as the Helm release name, the namespace suffix (em-<name>), and the package prefix in your monorepo.
One repo per solution. Monorepo layout from day one — even with a single component — so adding a worker later is a 3-step diff. See Architecture for Solution Developers.
Any OCI registry your target cluster can pull from. Internal solutions use ghcr.io/emergenceai/. Partners typically use their own registry.
Your own Postgres database. No cross-service foreign keys. Migrations versioned with Alembic from day one.
Agents, data connections, files, and models registered through the platform’s Assets API are discoverable to other solutions and the UI. Decide upfront what your solution exposes.

​
Steps

1

Pick a name

Match the solution name across:
  • Repo name (e.g. em-talk2data)
  • Helm release name (e.g. talk2data)
  • Namespace (e.g. em-talk2data)
  • Database (e.g. talk2data)
Existing examples: em-talk2data (Data Insights), em-data-readiness (Data Governance), em-semi (Semiconductor). Stick to this rhythm — it makes ops searches and grep-based audits trivial.
2

Apply the namespace convention

NamespaceUsed by
em-runtimePlatform services (Governance, Assets, Utils, Keycloak, OpenFGA)
em-<solution>Your solution’s pods, services, and config
em-<solution>-systemCluster-scoped sidecars or operators owned by your solution (rare)
Create the namespace explicitly with a label so the platform’s NetworkPolicy / Reloader / cost-attribution pick it up:
kubectl create namespace em-<solution>
kubectl label namespace em-<solution> emergence.ai/solution=<solution>
3

Choose your container image registry

Configure image.repository in your chart’s values.yaml. For private registries, also configure imagePullSecrets:
api:
  image:
    repository: <your-registry>/<solution>-api
    tag: 0.1.0
  imagePullSecrets:
    - name: <your-pull-secret>
4

Wire the Helm chart

Single component? See Quickstart Step 4. Multi-component (api + worker + scheduler + agent…)? See Package and Deploy for the alias pattern.The minimum is one em-service subchart per component, with each component aliased so its values live under that key:
charts/<solution>/Chart.yaml
dependencies:
  - { name: em-service, alias: api,    version: 0.0.16, repository: oci://ghcr.io/emergenceai/em-charts }
  - { name: em-service, alias: worker, version: 0.0.16, repository: oci://ghcr.io/emergenceai/em-charts }
5

Register your database (your own, not platform's)

Your solution owns its database. Two non-negotiable rules:
  1. No cross-service foreign keys. Each service must be backup-restorable independently. Cross-service consistency is by API contract, not joins.
  2. Migrations from day one — Alembic is the platform standard. Migrations are immutable once committed; never edit a published migration, write a new one.
Provision via your chart (the Postgres subchart pattern) or via Crossplane claims for managed databases. Connection string injected as a secret-backed env var (see Manage Secrets).
6

Register agents (optional)

If your solution exposes A2A agents (the Data Insights pattern), register each with the Assets API so other services and the UI can discover them. Follow Register Your First Agent — that walkthrough covers Agent Card authoring (/.well-known/agent-card.json), validation, registration, listing, and update with optimistic concurrency.
7

Register data connections (optional)

If your solution reads customer data (databases, object stores, file shares), the customer registers a Data Connection and grants your solution permission. Your code fetches the connection at runtime — credentials never live in your config.
8

Wire integrations

Step through these in order:

Authenticate

Validate JWTs and propagate X-Project-ID.

Secrets

Inject runtime secrets via the chart.

Storage

Use obstore for cross-cloud blob access.

LLMs

Call the LiteLLM gateway (never providers directly).

​
What you get when you follow the conventions

If you…You get…
Follow em-<solution> namespaceAuto-applied NetworkPolicy, Reloader watching your Secrets, cost attribution by solution
Wrap em-service with one alias per componentStandard probes, env var deduplication, Gateway API ingress, HPA — all configurable but with sane defaults
Register agents in AssetsDiscoverability from the UI shell + other solutions; permission integration with OpenFGA
Use Connections for data sourcesCredential rotation handled by the platform; never in your code
Call LLMs via LiteLLM gatewayPer-project cost attribution, rate limits enforced centrally, traces in Langfuse

​
Verification

# Namespace label set
kubectl get namespace em-<solution> -o jsonpath='{.metadata.labels}'

# Helm release lives in the right place
helm list -n em-<solution>

# Image pulls succeed (no ImagePullBackOff)
kubectl -n em-<solution> get pods

# DB migration ran (if applicable)
kubectl -n em-<solution> logs job/<solution>-migrate
If anything is unhealthy, see Troubleshooting.

​
Next steps

Package and deploy

Multi-component charts, env overlays, image publish.

Local development

Test changes locally before pushing.

Authenticate users

The first integration most solutions need.

Troubleshooting

Common errors at registration time.