# 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. The real path is `belong id login` (step 3.1) — a browser
device-code flow against belong-cloud that issues a signed, revocable
identity; pass `--origin <url>` for a non-default belong-cloud deployment.
`belong id issue --dev` remains the offline preview default when there is
no reachable belong-cloud (e.g. sandboxed/air-gapped runs) — it stays LOCAL
and unsigned. Never create or edit belong.json by hand, and never fabricate
one for a real customer. The R0 gate (`belong id verify` / the exit-2
check ahead of every other command) is structural for issued docs too — it
confirms shape and, for issued docs, signature/revocation; it is not a
substitute for verifying WHO is running the agent.

## 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 login --origin <belong-cloud-url>` — prints the device-flow
   verification URL and code (open the URL in a browser and approve), polls
   for approval, and writes the issued (signed, revocable) `belong.json`.
   The CLI never launches a browser itself. `--origin` defaults to
   `BELONG_API_URL` or `https://api.belonguniverse.ai`. If no human is
   available to approve in a browser (autonomous/sandboxed runs) or
   belong-cloud isn't deployed yet, fall back to the offline preview default:
   `belong id issue --dev --company "<Company Name>" --email <work-email>` —
   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, unsigned, and must be re-issued (via `id login`) before
   production.
2. `belong id verify` — checks belong.json shape for both issued and dev
   docs, plus signature + revocation for issued docs. The revocation check
   needs network access to the issuer and exits nonzero if unreachable —
   pass `--offline` deliberately in air-gapped/sandboxed re-checks (cached
   keys still verify the signature).
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.