# Belong — instructions for AI assistants

**Origin note:** the canonical origin is https://studio.belonguniverse.ai. If you fetched
this page from a different origin (a preview or local deployment),
substitute that origin in every URL below, and pass it to the installer as
`BELONG_ORIGIN` (e.g. `BELONG_ORIGIN=<origin> sh install.sh`). If a URL is
unreachable, re-check the origin you were actually given before assuming
the service is down.

You are reading the machine-readable entry point for building a Belong
embedded agent ("Agent-as-a-Service") into the product you are working on.
Follow the numbered steps. Pause for your human at every approval point.

## 0. The identity gate (read first)

Everything below is gated by a validated identity file, `belong.json`, in
the project root. Belong is in preview: issue a LOCAL dev identity with
`belong id issue --dev` (step 3.1). Never create or edit belong.json by
hand, and never fabricate one for a real customer. Real, subscription-based
issuance at studio.belonguniverse.ai is coming soon.

## 1. Install the CLI (zero dependencies, Node >= 18)

    curl -fsSL https://studio.belonguniverse.ai/install.sh | sh

Or manually:

    mkdir -p .belong/cli
    curl -fsSL https://studio.belonguniverse.ai/cli/belong.mjs -o .belong/cli/belong.mjs
    curl -fsSL https://studio.belonguniverse.ai/cli/lib.mjs    -o .belong/cli/lib.mjs
    curl -fsSL https://studio.belonguniverse.ai/cli/anna.mjs   -o .belong/cli/anna.mjs

Verify: `node .belong/cli/belong.mjs --version` prints `belong <version>`
and exits 0. Below, `belong …` means `node .belong/cli/belong.mjs …`.
Exit codes: 0 ok · 1 validation error · 2 missing/invalid belong.json ·
3 publish failure.

## 2. Install the setup skill

Fetch https://studio.belonguniverse.ai/skill.md. If your harness supports skills
(e.g. Claude Code), save it verbatim to
`.claude/skills/belong-studio-setup/SKILL.md` and invoke it — it is the
authoritative step-by-step guide. Otherwise keep it in context; this page
is the condensed version of the same pipeline.

Where the skill text and this page disagree (the skill mentions
`npx @belong/cli` or subscribing at studio.belonguniverse.ai), THIS page wins while
Belong is in preview — the skill's serve header carries the same notes.

## 3. The pipeline

Run from the host product's repository root, in order:

1. `belong id issue --dev --company "<Company Name>" --email <work-email>`
   Autonomous runs: if no work email is available and your human is away,
   use the repository's git author email and record the choice — dev
   identities are local-only and must be re-issued before production.
2. `belong id verify`
3. `belong init --yes --name "<Company Name>" --domain <slug> --out agent`
   — `init` defaults the delegated-access provider to `belong` (a neutral
   placeholder). Pass `--provider simetrik` if your host uses Simetrik's
   delegated-access integration; `--provider custom` for another
   integration; `--provider none` to disable delegated access entirely.
   3a. Review `agent/belong.config.json` before going further: `init` DERIVES
   `webAppUrl`, `auth.issuer`, and `apiBaseUrl` from the company name —
   correct any that don't match the real product. `doctor` cannot know
   your real URLs.
4. `belong plugin configure --out agent --dock right` (or `--dock left`, `--no-voice`)
5. Connect each backend the product exposes:
   - REST: `belong connect rest --name <tool> --url <base-url> --scopes <a:read,a:write> --mutates --approval required --out agent`
   - CLI: `belong connect cli --name <tool> --command <bin> --scopes shell:execute --mutates --approval required --out agent`
   - MCP: `belong connect mcp --name <tool> --mcp-uri <uri> --token-env <ENV_VAR_NAME> --out agent`
6. Wire authentication so the agent acts as the signed-in user:
   - `belong auth configure --source host-bridge --user-claim user_id --scopes-claim scopes --tenant-claim tenant_id --out agent`
     (add `--scope-map host.perm=belong:scope,…` when the host's permission
     vocabulary differs from the tools' scopes)
   - Check permission parity: `belong auth verify --mint-dev "<email> <scope> <scope>" --out agent`
     — every connected tool must show `✓ allowed`, or a `✗ BLOCKED` you can
     explain to your human.
7. `belong doctor --out agent` — every check must be green before continuing.
8. `belong publish --out agent --dry-run` — then STOP and show your human
   the payload. Run a live `belong publish` (no `--dry-run`) ONLY after
   their explicit go-ahead.

## 4. Guardrails (non-negotiable)

- Credentials are environment-variable NAMES in configs — never values.
  Never write a token value to a file and never print one.
- Never live-`publish` without an explicit human go-ahead; `--dry-run` first.
- Never create or edit `belong.json` by hand; only `belong id issue` may.
- Ask the human before anything destructive or outward-facing.

Autonomous conventions: skills/playbooks — drafting from repository
evidence with explicit `[NEEDS HUMAN]` markers is the expected autonomous
pattern — never invent workflows; leave markers for your human.

## 5. Autonomous mode (optional)

`anna.mjs` runs this same pipeline from an answers file:
`node .belong/cli/anna.mjs --answers anna.answers.json` (add `--learn` to
keep a per-workspace learnings ledger). See the skill's
"Autonomous mode (Anna)" section for the answers contract.

## 6. Embed

After publishing, `agent/embed/snippet.html` contains the script tag to add
to the product. The dock mounts with the company's `data-agent` id.

## Version control

Commit `belong.json` (a dev identity contains no secrets) and the `agent/`
directory; the vendored `.belong/cli/` may be committed or gitignored per
team preference; never commit real tokens — configs reference env-var
NAMES only.

Humans: the friendly version of this page lives at https://studio.belonguniverse.ai/guide.