@rizom/ops 0.2.0-alpha.35 → 0.2.0-alpha.350

package/templates/rover-pilot/docs/onboarding-checklist.md

@@ -4,28 +4,39 @@
 2. Run `bunx brains-ops age-key:bootstrap <repo> --push-to gh`.
 3. Fill in `pilot.yaml`.
    - keep your pinned `brainVersion`
-   - confirm shared selectors for `aiApiKey`, `gitSyncToken`, and `mcpAuthToken`
+   - confirm shared selectors for `aiApiKey`, `gitSyncToken`, and `contentRepoAdminToken`
+   - use different tokens for `contentRepoAdminToken` and `gitSyncToken`: admin creates/checks content repos; sync is used by runtime directory-sync
    - confirm `agePublicKey`
-4. Add or edit `users/<handle>.yaml`.
-   - Discord is enabled by default for pilot users
-   - if the user should be an anchor there, set `discord.anchorUserId` to their Discord user ID
-5. Add the user to a cohort in `cohorts/*.yaml`.
+4. Run `bunx brains-ops user:add <repo> <handle> --cohort <cohort>`.
+   - Web chat is the primary interface; it needs no per-user setup beyond the passkey.
+   - `user:add` currently writes `discord: enabled: true`; set it to `false` unless the user's cohort actually uses Discord.
+   - if the user should be an anchor on Discord, add `--anchor-id <discord-user-id>`.
+   - the command creates `users/<handle>.yaml`, `users/<handle>.secrets.yaml`, and the cohort membership without duplicating existing entries.
+5. Edit the generated user file if the anchor profile needs richer metadata.
+   - Set `setup.delivery: email` and `setup.email` so the user gets the passkey setup email — this is the default onboarding path.
+   - For ATProto publishing, add `atproto.identifier` to the user file; put only `atprotoAppPassword` in the per-user secrets file.
+   - Ensure `SETUP_EMAIL_API_KEY` and `SETUP_EMAIL_FROM` exist as GitHub Secrets before deploying any email-setup user.
 6. Run `bunx brains-ops render <repo>`.
 7. Run `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`.
 8. Run `bunx brains-ops cert:bootstrap <repo> --push-to gh`.
-9. Keep raw user secret material locally for now (`.env.local`, file-backed env vars, or equivalent local inputs).
+9. Keep raw user secret material locally for now (`.env.local`, file-backed env vars, or equivalent local inputs), including `CONTENT_REPO_ADMIN_TOKEN` for operator onboarding.
 10. Run `bunx brains-ops secrets:encrypt <repo> <handle>`.
 11. Commit and push `users/<handle>.secrets.yaml.age`.
 12. Run `bunx brains-ops onboard <repo> <handle>`.
-13. Verify the deployed rover core contract:
-    - `https://<handle>.rizom.ai/health` returns `200`
-    - unauthenticated `POST https://<handle>.rizom.ai/mcp` returns `401`
-14. For fleet upgrades, edit `pilot.yaml.brainVersion` and push once; CI rebuilds the shared image tag, refreshes generated user env files, and redeploys affected users.
-15. Hand the Discord setup details to the user.
-16. Hand over the browser defaults:
+13. Verify the deployed canonical contract:
+    - `https://<handle>.rizom.ai/health/operate` returns `200`
+    - `https://<handle>.rizom.ai/chat` loads the web chat and accepts passkey sign-in
+    - unauthenticated `POST https://<handle>.rizom.ai/mcp` returns the expected auth failure
+    - content repo exists and runtime sync is healthy
+    - background jobs are not repeatedly failing, except for expected missing optional integrations
+    - when `site` is selected, the browser/Studio surfaces load and the initial app-managed site build completes
+14. For fleet upgrades, edit `pilot.yaml.brainVersion` and push once; CI rebuilds the required default/site image tags, refreshes generated user env files, and redeploys affected users. Every external site and theme package keeps its own required exact version pin and never follows the brain version implicitly.
+15. Confirm the user received the setup email, registered their passkey, and can sign in to web chat at `https://<handle>.rizom.ai/chat`. That completes the default onboarding; everything below is per-cohort extras.
+16. Hand over the browser surfaces:
+    - Chat (primary): `https://<handle>.rizom.ai/chat`
     - Dashboard: `https://<handle>.rizom.ai/`
-    - CMS: `https://<handle>.rizom.ai/cms`
-    - GitHub token guidance for CMS access to the user's private content repo
-17. If they need direct client access, also hand over the MCP connection details.
-18. If you are also giving them a content repo workflow, describe it as optional and frame git/Obsidian as an advanced file-based path, not the default.
-19. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.
+    - Studio: `https://<handle>.rizom.ai/studio`, plus GitHub token guidance if Studio editing is part of their cohort
+17. For Discord-enabled cohorts, hand the Discord setup details to the user as a secondary chat surface.
+18. If they need direct client access (MCP), use OAuth/passkey-capable clients where possible.
+19. If you are also giving them a content repo workflow, describe it as optional and frame git/Obsidian as an advanced file-based path, not the default.
+20. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.

package/templates/rover-pilot/docs/operator-playbook.md

@@ -9,30 +9,145 @@ Treat these as checked-in deploy artifacts in the pilot repo:
 - `deploy/scripts/`
 - `.github/workflows/build.yml`
 - `.github/workflows/deploy.yml`
+- `.github/workflows/directory-sync-stress.yml`
+- `.github/workflows/health-watchdog-smoke.yml`
 - `.github/workflows/reconcile.yml`
 
 `.env.schema` is the single source of truth for required and sensitive deploy vars.
 The deploy scripts and workflows should read from that contract instead of inventing a second list.
 
-The shared pilot image tag is `brain-${brainVersion}`:
+The default pilot image tag is `brain-${brainVersion}`:
 
-- build publishes `brain-${brainVersion}`
+- build publishes `brain-${brainVersion}` for users without a site override
+- a site override gets an isolated `brain-${brainVersion}-sites-${packageHash}` image
 - generated `users/<handle>/.env` carries `BRAIN_VERSION=<brainVersion>`
-- deploy sets `VERSION=brain-${brainVersion}`
+- build and deploy derive the same effective image tag from the resolved registry
 
 ## Version bump flow
 
 When `pilot.yaml.brainVersion` changes and you push:
 
-1. build publishes the new shared image tag
+1. build publishes the new default image and any required site images
 2. reconcile refreshes generated `users/<handle>/.env`
 3. deploy runs for handles whose generated config changed
 4. generated file commits happen once in a final aggregation step after the deploy matrix finishes
 
+Every external site and theme package has its own exact version pin. A cohort or
+pilot brain-version bump never changes those package versions implicitly; update each
+pin deliberately from reviewed package and image evidence.
+
 When a push changes only deploy contract files and no generated `users/<handle>/.env` or `users/<handle>/brain.yaml` files, the deploy workflow exits through its explicit no-op path and prints `No affected user configs; skipping deploy.`
 
 They are scaffolded from `@rizom/ops`, then versioned in this repo like any other deploy contract.
 
+## Verified pre-deploy rollback snapshots
+
+Deploy creates and verifies one target-scoped rollback snapshot after SSH and image readiness, immediately before optional stale-lock release and `kamal setup`. A snapshot failure stops the workflow before container replacement. A genuinely new server with no runtime or persistent state reports `not applicable`; persistent state without an identifiable runtime fails closed.
+
+Each snapshot contains transaction-consistent online captures of the six canonical SQLite databases, database hashes and `quick_check` results, the deployed `brain.yaml`, sanitized container and mount metadata, and the Directory Sync checkout. Git capture includes all refs, an observed remote head, staged and unstaged binary patches, and mode-preserving archives of untracked and ignored files. Capture performs no checkout mutation or remote write.
+
+Verified snapshots are finalized atomically under:
+
+```text
+/opt/brain-state/backups/predeploy-<handle>-<target>-<UTC timestamp>/
+```
+
+Files use mode `0600` and the directory uses `0700`. A `.incomplete` directory is diagnostic evidence, never a rollback point. Checksums and the versioned manifest must verify before finalization. The default retention is five verified snapshots per target; incomplete or unverified directories do not count, and the snapshot created by the current deployment is never pruned.
+
+These are same-server rollback snapshots, not off-host disaster recovery. There is no normal skip and no automatic restore. Restoration requires separate approval: stop replacement/application processes, recheck the selected snapshot's checksums, preserve the current state, restore databases and exact Git state, then validate health, queues, Git checkpoints, durable export intents, preview, and production output before reopening the target.
+
+## Retired projection job recovery
+
+A pre-scheduler projection job can remain active after its handler type is retired. Current runtime health reports active job types missing from the finalized execution inventory as degraded. Do not restart repeatedly or relax the snapshot idle gate.
+
+Use the recovery command only after read-only evidence proves all of the following for one exact row:
+
+- its type is one of the command's fixed legacy projection types;
+- the installed runtime no longer contains that handler;
+- attempt, worker-session, lease, and heartbeat ownership are all absent;
+- no durable progress snapshot or result exists.
+
+Preview the exact row first:
+
+```sh
+bunx --package @rizom/ops@<exact-version> brains-ops \
+  recover:retire-legacy-projection-job \
+  /data/brain-jobs.db <job-id> --type <legacy-type> --dry-run
+```
+
+After separate operator review, replace `--dry-run` with the exact confirmation `--confirm retire:<job-id>`. The command atomically fences against ownership or progress appearing between inspection and retirement, and fails closed if the row changed. It is not a general job cancellation API and cannot retire arbitrary job types. Require operational health and a fully idle queue afterward, then run the unchanged canonical predeploy snapshot and Deploy workflow.
+
+## Canonical contract crossover maintenance window
+
+Do not run this procedure without explicit operator approval. The canonical desired state, canonical `@rizom/ops`, and unified runtime image form one contract and must move or roll back together. Complete `docs/canonical-crossover-record.md` as the approval evidence without adding secret values.
+
+Before the window, record and review:
+
+- the prior pilot commit and exact `@rizom/ops` version;
+- every prior runtime image tag and immutable digest;
+- the reviewed canonical pilot commit;
+- the exact unified `@rizom/brain` and `@rizom/ops` versions;
+- every unified image tag and immutable digest;
+- canary-first rollout order, followed by the remaining cohorts;
+- expected `/health/operate` version, unauthenticated MCP response, site marker, and content repository identity for each posture.
+
+Run `bunx brains-ops reconcile-all <canonical-review-copy> --dry-run` against the isolated review copy. The command blocks external content-repository access, leaves the review copy untouched, lists both passes' changed files, and must report second-pass zero drift. Reconciliation owns generated per-user config; only `render` owns the observational `views/users.md` projection.
+
+During the approved window:
+
+1. Freeze unrelated merges and releases. Wait for active Build, Reconcile, and Deploy runs to finish, then disable all three pilot workflows with `gh workflow disable build.yml`, `gh workflow disable reconcile.yml`, and `gh workflow disable deploy.yml`.
+2. Publish and verify the reviewed unified runtime and matching ops artifacts. Do not update pilot desired state until the exact versions are installable and the expected images can be built.
+3. Apply the reviewed canonical pilot revision while automation remains disabled. Confirm repository names, server/domain identity, content repositories, secret selectors, image names, and tag identity against the review diff.
+4. Enable only Build, run it for the canonical desired-state revision, and record every resulting image digest. Stop if the observed digest set differs from the cutover record.
+5. Enable only Reconcile, run it once, and review its generated per-user config commit. It must not rewrite `views/users.md`, and no generated file may combine canonical config with a retired image version.
+6. Enable Deploy and deploy one handle at a time in the approved order. After each deploy, run `bunx brains-ops verify-user . <handle>`, render observed fleet status, and complete the manual identity, content-sync, and app-managed site checks.
+7. Run Reconcile a second time. Require no reconciler-owned generated diff and no deploy work before re-enabling normal automation and lifting the merge/release freeze. Observed status rendering remains separate from this convergence gate.
+
+If any gate fails, disable all three workflows again. Restore the prior pilot desired-state and dependency revision, reconcile with the prior ops version, and redeploy the prior image tag/digest as one rollback pair. Verify the prior `/health/operate` version and identity/content/site checks before re-enabling automation. Never restore only config or only an image.
+
+## Directory-sync stress gate
+
+Use the manual `Directory Sync Stress` workflow only against a disposable smoke user. It refuses a target unless the handle, domain, and content repository all identify smoke, the confirmation input exactly matches `stress:<handle>`, and the user desired state declares the hermetic posture below. Reconcile and deploy this posture before running the workload:
+
+```yaml
+embeddingEnabled: false
+topicExtractionEnabled: false
+skillDerivationEnabled: false
+swotDerivationEnabled: false
+```
+
+Before authorizing a workload, dispatch the workflow once with `verify_only: true`. That mode loads the same Bitwarden/Varlock content credential, clones the smoke content repository, and runs `git push --dry-run` against a temporary stress ref. It creates no ref, performs no content write, does not contact the deployed runtime, and skips cleanup because no probes were created.
+
+Profiles are deterministic and reversible:
+
+- `regression`: 20 probes;
+- `load`: ramps to 350 probes, updates all, renames 100, updates again, then deletes all;
+- `stress`: ramps to 700 probes and renames 200 before cleanup.
+
+The workflow loads operator credentials through Bitwarden/Varlock, but it is separate from Deploy and cannot deploy an image. It creates a rollback branch before the first content write, gates on health timeouts, watchdog restarts, and external AI usage during the monitored workload window, preserves warmup and cleanup samples as evidence, uploads JSON/Markdown/runtime artifacts, and runs an independent idempotent cleanup job with `if: always()`. Once cleanup confirms that no probes remain, it also prunes retained `ops/directory-sync-stress-backup-*` branches; if probes remain, the branches stay available for recovery.
+
+Treat any gated health failure, restart, OOM, residual probe, or entity-baseline drift as a failed gate. Do not restart the target during measurement. Recovery is a separate operator action after evidence collection.
+
+## Health watchdog smoke gate
+
+Use the manual `Health Watchdog Smoke` workflow only after the `smoke` fleet user has completed a normal Deploy run. The workflow shares the `deploy-<handle>` concurrency group, resolves the server from pilot desired state through Hetzner, loads the existing deploy SSH key through Bitwarden/Varlock, and refuses targets whose handle and domain do not identify smoke. Confirm with `watchdog-smoke:<handle>`.
+
+The smoke does not deploy or replace the installed systemd units. It verifies that the installed watchdog exactly matches the packaged canonical payload, then exercises that installed script. It also verifies the deployed rover image label, exact-label selector, active timer, and `/health/live` Docker healthcheck. While holding the timer's global lock, it creates temporary containers for eligible unhealthy, unrelated service-labelled unhealthy, false-labelled unhealthy, and eligible healthy cases. It then requires exactly three eligible restarts followed by budget suppression, diagnostics and state only for the eligible fixture, and no restart of the deployed rover or ineligible fixtures.
+
+The primary job uploads remote incident, state, and command evidence. An independent `if: always()` cleanup job removes deterministic fixture names and remote temporary files using the same workflow run ID. Treat missing evidence, unexpected eligibility, deployed-container movement, cleanup failure, or any non-smoke target rejection as a failed gate.
+
+## Stale deploy lock recovery
+
+Kamal intentionally leaves its remote deploy lock in place when a deployment is cancelled or interrupted. Confirm that no deployment for the user is still active before releasing the lock, then use the deploy workflow's explicit recovery input:
+
+```sh
+gh workflow run Deploy --ref main \
+  -f handle=<handle> \
+  -f release_stale_lock=true
+```
+
+Recovery is opt-in and scoped to one handle. Normal push, reconcile, and manual deploy runs never remove a lock automatically.
+
 ## Bootstrap flow
 
 For this fleet, operator-local secret material remains the source of truth during onboarding and rotation. The repo stores encrypted per-user secrets, not raw values.
@@ -53,51 +168,214 @@ Preview hosts use the shape `<handle>-preview.rizom.ai`, so one wildcard origin
 
 ## Upgrading operator behavior
 
-When `@rizom/ops` changes the scaffolded deploy contract:
+The pilot repository pins `@rizom/ops` in `package.json`. The scheduled and manually dispatched Upgrade workflow owns routine upgrades to that pin. It refreshes the scaffold on a branch and opens a reviewable PR; it does not change runtime desired state or authorize a deployment.
+
+Because scaffold refreshes can update `.github/workflows/*`, the workflow must not push with its Actions `GITHUB_TOKEN`. Configure a dedicated GitHub App:
+
+1. Install it only on this pilot repository.
+2. Grant repository permissions `Contents: Read and write`, `Pull requests: Read and write`, and `Workflows: Read and write`; grant nothing else.
+3. Store its App ID as the repository Actions variable `OPS_UPGRADE_APP_ID`.
+4. Store its private key as the repository Actions secret `OPS_UPGRADE_APP_PRIVATE_KEY`.
+
+The workflow explicitly requests only those three permissions. Checkout persists no credential. After the freshly published `@rizom/ops` finishes, the workflow checks whether it produced a change; only then does it mint a short-lived, repository-scoped App token for the push-and-open-PR steps. A credential that can rewrite `.github/workflows/` therefore does not exist while upgraded package code runs.
+
+If `OPS_UPGRADE_APP_ID` is unset, or token creation, branch push, or PR creation fails, the run stops with a non-zero status. Repair the CI credential path; never fall back to an operator's personal SSH key or token.
+
+Adopting this credential flow in an existing pilot repository requires one explicitly reviewed bootstrap PR because the old Upgrade workflow cannot update itself. After that merge, routine upgrades run entirely in CI:
+
+1. dispatch Upgrade with an exact version, or let its schedule select `latest`;
+2. review the generated package, lockfile, deploy-script, and workflow diff;
+3. merge the upgrade PR only after its checks pass;
+4. change runtime desired state separately through the approved canary or fleet rollout flow.
 
-1. bump `@rizom/ops` in `package.json`
-2. rerun the relevant scaffold/reconcile flow
-3. review the resulting changes to `.env.schema`, `deploy/scripts/`, and workflows in git
-4. commit the updated deploy artifacts together
+## Canonical verification notes
 
-## Rover-core verification notes
+Use the verification script after deploy:
 
-Rover core is MCP-only. Do not expect the bare domain to serve a website.
+```sh
+bunx brains-ops verify-user . <handle>
+```
 
-Use these checks after deploy:
+For every bundle posture it checks:
 
-- `https://<handle>.rizom.ai/health` should return `200`
-- unauthenticated `POST https://<handle>.rizom.ai/mcp` should return `401 Unauthorized: Bearer token required`
-- a bare `GET /` may also return `401`; that is expected for rover core and does not indicate a bad deploy
+- `https://<handle>.rizom.ai/health/operate` returns `200`;
+- unauthenticated `POST https://<handle>.rizom.ai/mcp` returns the expected auth failure;
+- background jobs are not repeatedly failing, except for missing optional integrations.
 
-## Discord bot token checklist
+A `core`-only instance is MCP-only; a bare `GET /` may return `401` without indicating a bad deploy. When `site` is selected, verification also checks the browser and Studio/login surfaces.
+
+Manual checks that remain:
+
+- initial app-managed site output is correct for the expected content/theme;
+- content repository identity and runtime sync are healthy;
+- passkey setup/handoff is completed from the setup email.
+
+## One-user canonical site canary
+
+Run this before adding custom site/theme packages or rolling a larger browser/Studio-first cohort.
+
+1. Create or choose a canary cohort with explicit bundles:
+
+   ```yaml
+   bundles:
+     - core
+     - site
+     - publishing
+   ```
+
+2. Add exactly one canary user to that cohort.
+3. For browser/Studio-first onboarding, configure setup email in `users/<handle>.yaml`:
+
+   ```yaml
+   setup:
+     delivery: email
+     email: user@example.com
+   ```
+
+4. Encrypt the user's secrets and commit only the `.age` file.
+5. Run `bunx brains-ops onboard . <handle>`.
+6. Run `bunx brains-ops verify-user . <handle>` with no custom site/theme overrides.
+7. Ask the user to complete passkey setup from the setup email.
+8. Continue to visual customization only after the canary is healthy.
+
+Rollback must restore the prior desired-state revision and prior runtime image together. Never pair canonical config with the retired image, or retired config with the canonical image.
+
+## Hosted site and theme package contract
+
+Start with the public [site mockup migration guide](https://github.com/rizom-ai/brains/blob/main/docs/site-mockup-migration.md), then apply these hosted-fleet requirements:
+
+- A site package must default-export `defineSite(...)` and import its authoring API only from `@rizom/site`.
+- A theme package must default-export its CSS as a string. Hosted custom themes currently use the `@rizom/*` scope so the fleet image installs them with the site package; `@brains/*` themes are bundled with `@rizom/brain`.
+- Site and custom theme packages must be public npm packages that install without registry credentials.
+- Site, theme, and brain packages publish independently. Hosted configuration requires exact site and external-theme version pins and never derives one package version from another.
+- Keep site structure and theme CSS in separate packages. Do not put private content or secrets in either package.
+
+Configure a user in `users/<handle>.yaml`:
+
+```yaml
+siteOverride:
+  package: "@rizom/site-example"
+  version: <exact-site-version>
+  theme: "@rizom/theme-example"
+  themeVersion: <exact-theme-version>
+```
+
+Missing external package versions fail desired-state validation. A site override
+produces an isolated per-instance image; it never changes the fleet's shared default
+image. Bundled `@brains/*` themes omit `themeVersion` because they are not installed as
+separate packages.
+
+### Custom-package canary and rollback
+
+1. Confirm the exact site/theme versions are public-installable without npm credentials.
+2. Apply the exact package names and versions to one healthy canonical site canary.
+3. Reconcile the canary, push the generated output, and let build/deploy create its site image.
+4. Run `bunx brains-ops verify-user . <handle>`.
+5. Manually verify the site, theme, Studio, content sync, and passkey sign-in before adding more users.
+
+To roll back, remove or change `siteOverride`, reconcile, and redeploy that user.
+The default image and other users remain untouched.
+
+## Setup email checklist
+
+Use this for browser/Studio-first users who should receive their own first-passkey setup link by email.
+
+1. Add setup delivery to the user file:
+
+   ```yaml
+   setup:
+     delivery: email
+     email: user@example.com
+   ```
+
+2. Configure these GitHub Secrets before deploy:
+   - `SETUP_EMAIL_API_KEY`
+   - `SETUP_EMAIL_FROM`
+
+3. Reconcile/deploy the user or cohort:
+   - `bunx brains-ops onboard . <handle>`
+   - or `bunx brains-ops reconcile-cohort . <cohort>`
+
+4. Verify the generated `users/<handle>/brain.yaml` contains `auth-service.setupEmail` and `email` interface config.
+5. Ask the user to complete passkey setup from the email link, then use:
+   - Dashboard: `https://<handle>.rizom.ai/`
+   - Studio: `https://<handle>.rizom.ai/studio`
+
+Notes:
+
+- The setup URL is generated and sent by the running brain; operators should not scrape logs or SSH into the instance to retrieve it.
+- The auth service owns setup email dedupe. It should not resend for the same persisted setup token after restart, but should retry failed delivery and resend after token rotation.
+- `SETUP_EMAIL_FROM` is not marked required because fleets without email setup can omit it, but it is required for users with `setup.delivery: email`.
+
+## AT Protocol smoke/config checklist
+
+Use this when enabling AT Protocol publishing for a single pilot user.
+
+1. Add the public PDS identifier to the user file. Prefer the account DID as
+   the identifier — it survives handle changes. Add `accountDid` too when the
+   member wants their handle verified against their subdomain
+   (`@<handle>.<domainSuffix>`): the brain then serves it at
+   `/.well-known/atproto-did` and Bluesky's "I have my own domain" HTTP
+   verification passes with no DNS records.
+
+   ```yaml
+   atproto:
+     identifier: did:plc:example123
+     accountDid: did:plc:example123
+   ```
+
+   Only for the PDS account designated by the protocol authority's `_lexicon`
+   DNS TXT record, also set `lexiconAuthority: true`. Every other fleet user
+   must omit it.
+
+2. Put the app password in `users/<handle>.secrets.yaml`:
+
+   ```yaml
+   atprotoAppPassword: <app-password>
+   ```
+
+3. Encrypt the per-user secret payload:
+   - `bunx brains-ops secrets:encrypt . <handle>`
+4. Reconcile/deploy the user or cohort:
+   - `bunx brains-ops onboard . <handle>`
+   - or `bunx brains-ops reconcile-cohort . <cohort>`
+5. Verify the generated `users/<handle>/brain.yaml` contains `plugins.atproto.identifier` (plus `accountDid` and `lexiconAuthority` when configured) and `appPassword: ${ATPROTO_APP_PASSWORD}`.
+
+Notes:
+
+- The ATProto identifier and authority flag are public instance config and belong in `users/<handle>.yaml`. Only the DNS-designated authority account may set `lexiconAuthority: true`.
+- The ATProto app password is secret and belongs only in the encrypted per-user secret payload.
+- For smoke deployments, pin only the smoke cohort/user to the released brain version that contains ATProto support.
+
+## Discord application credential checklist
 
 Use this when enabling Discord for a pilot user.
 
 1. Pick the user handle (for example `smoke`).
 2. Open the Discord Developer Portal.
-3. Create a **new application** for that user's rover.
+3. Create a **new application** for that user's brain.
 4. Add a **Bot** to the application.
-5. Copy the bot token.
-6. Put that value in `.env` or `.env.local` in this repo as `DISCORD_BOT_TOKEN=...` while onboarding that user.
+5. Copy the bot token, application public key, and application ID.
+6. Put those values in `.env` or `.env.local` while onboarding that user:
+   - `DISCORD_BOT_TOKEN=...`
+   - `DISCORD_PUBLIC_KEY=...`
+   - `DISCORD_APPLICATION_ID=...`
 7. Keep `discord.enabled: true` in `users/<handle>.yaml` unless you explicitly want to disable the primary pilot interface.
-8. Encrypt the current per-user secret payload:
+8. Encrypt the current per-user credential payload:
    - `bunx brains-ops secrets:encrypt . <handle>`
 9. Reconcile/deploy the user or cohort:
-
-- `bunx brains-ops onboard . <handle>`
-- or `bunx brains-ops reconcile-cohort . <cohort>`
-
-11. In the Discord Developer Portal, generate an install URL and invite the bot to the right server.
-12. Send a test message in Discord and confirm the rover responds.
+   - `bunx brains-ops onboard . <handle>`
+   - or `bunx brains-ops reconcile-cohort . <cohort>`
+10. In the Discord Developer Portal, generate an install URL and invite the bot to the right server.
+11. Send a test message in Discord and confirm the brain responds.
 
 Notes:
 
-- Use **one bot token per user/rover**.
-- Do not reuse the same Discord bot token across multiple pilot users.
+- Use **one Discord application credential set per user/brain**.
+- Do not reuse the same Discord application across multiple pilot users.
 - Discord is the default pilot interface moving forward.
 - The encrypted `users/<handle>.secrets.yaml.age` file is the durable checked-in deploy input; your local env is only the operator staging source.
-- MCP is optional and mainly for direct client access or specific testing workflows.
+- Direct MCP client access should use OAuth/passkey-capable clients where possible.
 - When explaining the content workflow, describe it first as a normal **git repo** of **markdown/text files**.
 - Position **Obsidian** as optional: it is just one possible editor for those same files, not the default requirement.