@mnmal-ai/cortext-opencode 0.0.0 → 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,121 @@
-# @mnmal-ai/cortext-opencode
+# @mnmal-ai/cortext-opencode — Cortext for OpenCode
 
-Reserved by MNMAL. Nothing here yet.
+The OpenCode skin for the [Cortext](../cortext/README.md) coordination
+capability: the same synoptic cold-start (Concepts, Agent Memory, Open Work,
+Agent Rules, Inbox) the Claude Code skin injects, delivered through a
+`context` session hook on first dispatch per session (OpenCode 2.x
+`Plugin.define({ id, setup })`; a V1 `server()` entrypoint is bundled for
+OpenCode 1.x compat).
+
+## Install
+
+1. Plugin entry in the repo's `opencode.json`. The object form carries
+   per-project identity — `options.kid` / `options.key` win over the
+   `SUBSTRATE_AGENT_*` env pair:
+
+   ```json
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugins": [
+       {
+         "package": "@mnmal-ai/cortext-opencode",
+         "options": {
+           "kid": "synoptic-opencode@YourHost",
+           "key": "/home/you/.config/substrate/keys/synoptic-opencode.key"
+         }
+       }
+     ]
+   }
+   ```
+
+   The plain string form (`"plugins": ["@mnmal-ai/cortext-opencode"]`) also
+   works — identity then comes from the env pair. **Keep exactly one entry
+   per package**: as of opencode v2.0.24 the `plugins`
+   arrays concatenate across global + project config and loads dedupe only
+   by exact source string, so a global string entry plus a project object
+   entry for the same package load the plugin twice and double-inject the
+   cold-start. When adding the object entry, remove the global string entry.
+
+   npm plugins install automatically via Bun at startup. This package is
+   public on npmjs.com, as is the `@mnmal-ai/substrate` dep; no token needed.
+
+2. MCP server — merge into the same `opencode.json` (see
+   `commands/substrate-setup.md` Step 4 for the full procedure). **The MCP server
+   must sign as the same identity as the plugin**: the plugin shows
+   mail for its `options.kid`, and only that kid may ack it. With
+   `options.kid`/`options.key`, give the MCP `environment` the same kid and
+   key, as literals in a user-level config rather than `{env:…}` refs that a
+   GUI launch leaves empty:
+
+   ```json
+   {
+     "mcp": {
+       "servers": {
+         "substrate": {
+           "type": "local",
+           "command": ["npx", "-y", "@mnmal-ai/substrate", "mcp"],
+           "codemode": false,
+           "environment": {
+             "SUBSTRATE_URL": "https://substrate.example.com:3100",
+             "SUBSTRATE_AGENT_KEY_PATH": "{env:SUBSTRATE_AGENT_KEY_PATH}",
+             "SUBSTRATE_AGENT_KEY_ID": "{env:SUBSTRATE_AGENT_KEY_ID}"
+           }
+         }
+       }
+     }
+   }
+   ```
+
+   `"codemode": false` matters: OpenCode 2.x otherwise hides the
+   server's tools behind its `execute` tool, so the agent never sees
+   them and cannot ack mail. With it off they arrive prefixed by the server
+   name: `substrate_query`, `substrate_whoami`, and so on. On OpenCode 1.x use bare `mcp.substrate`
+   without `codemode`.
+
+3. Conventions — nothing to do. The plugin injects the conventions from its
+   own package on every dispatch, so they always match the installed
+   version. An older hand-copied `.opencode/substrate-conventions.md` is named in
+   the session context as stale; delete it and its `"instructions"` entry.
+
+4. Restart opencode (config loads once at startup). Or run `/substrate-setup`
+   (copy `commands/substrate-setup.md` to `.opencode/commands/`) for the guided
+   version of all of the above plus capability probing, AgentRule seeding,
+   identity provisioning, and the first anchor.
+
+## Environment
+
+| Var | Meaning | Default |
+|---|---|---|
+| `SUBSTRATE_URL` | Substrate base URL (required for live context) | — (offline note) |
+| `SUBSTRATE_NAMESPACE` | Coordinator namespace | `cortext` |
+| `SYNOPTIC_PROJECT_SCOPE=all` | Cross-project scope (omit project filter) | repo basename |
+| `SUBSTRATE_AGENT_KEY_PATH` / `SUBSTRATE_AGENT_KEY_ID` | Ed25519 identity for signed reads + mail | anonymous |
+| plugin-config `options.kid` / `options.key` | V2 object plugin entry identity — wins over the env pair, per-project, survives GUI launch where shell env does not. **All or nothing**: setting either uses the options pair only, never half from env | falls back to the env pair |
+| plugin-config `options.url` / `options.ns` | Override `SUBSTRATE_URL` / `SUBSTRATE_NAMESPACE` for the plugin, for a launch whose process env carries neither | the env values |
+| `MEMORY_*` / `RULE_SALIENCE` | Recall tunables, same as the Claude hooks | host defaults |
+| `SYNOPTIC_INBOX_PUSH` | `off` disables mid-turn push (V2); the prompt and end-of-turn seams carry on | on |
+| `SYNOPTIC_INBOX_WAKE` | `on` lets new mail start a turn in an idle session (6 per hour, 2 per thread) | off |
+| `SYNOPTIC_INBOX_URGENT_FROM` | Comma-separated kids whose `priority:urgent` mail may interrupt a turn (3 per hour, 20 s grace for a running tool) | unset |
+
+## How it maps to the Claude skin
+
+| Claude (`cortext-plugin`) | OpenCode (this package) |
+|---|---|
+| `SessionStart` hook → `hooks/cold-start.mjs` | `prompt` prewarm + `context` session-hook inject (once per session, cached; V1 compat via `experimental.chat.system.transform`) |
+| `UserPromptSubmit` inbox re-check | V2: each prompt after the first re-reads unread mail, and every dispatch of that turn carries the same summary line. `SYNOPTIC_INBOX_PROMPT_CHECK=off` disables it |
+| `Stop` inbox check (blocks once) | V2: a `session.execution.succeeded` event with unread mail queues one synthetic message carrying the same reason, with `resume: true`. Each message id nudges once. `SYNOPTIC_INBOX_STOP_CHECK=off` disables it |
+| Mid-turn push (`inbox-bridge`) | V2: the watcher runs in-process; new mail is steered into every busy session, allowlisted urgent mail preempts the most recently prompted session, and idle wake is opt-in. While the watcher is live the per-prompt summary is skipped; the end-of-turn nudge stays |
+| `skills/{council,todos}` | `skills/{council,todos}` — byte-identical pointer bodies (`test/skills-sync.test.ts` enforces) |
+| `fragments/substrate-conventions.md` | `instructions/substrate-conventions.md` — shared body, own marker (`test/instructions-sync.test.ts` enforces) |
+| `/substrate-setup` skill | `commands/substrate-setup.md` — opencode paths + MCP dialect |
+| SessionStart `compact` re-run | `compaction` session hook: drops the cache (next dispatch rebuilds) + leaves a pointer in the summary |
+| Fragment-drift watchdog | **Deferred** — the check reads the `.claude/` install path; see `src/plugin.ts` header |
+
+## Build
+
+`dist/plugin.js` is a committed, byte-deterministic tsdown bundle with zero
+runtime deps (same convention as `cortext-plugin/hooks/*.mjs`): `pnpm build
+&& git diff --stat dist/` must return empty. The `@opencode-ai/plugin`
+import is type-only; `@opencode/plugin` is imported from its dependency-free
+`promise/plugin` deep module (`define` is an identity function), so the
+bundle stays self-contained.

package/commands/substrate-setup.md

@@ -0,0 +1,217 @@
+---
+description: Onboard this repo as a Cortext consumer under OpenCode. Probes the target Substrate, wires the substrate MCP server in opencode.json (identity-ready), installs the conventions instructions, and seeds baseline AgentRules. Run once per repo.
+---
+
+# /substrate-setup (OpenCode) — onboard a cortext-opencode consumer
+
+Run these steps in order. This command is **idempotent** — re-running it never duplicates config entries or rules.
+
+Steps 2, 5, 6, 8 are transport-agnostic and identical to the Claude skin's
+`/substrate-setup`; only the file paths and the MCP dialect differ. Where this
+document says "same as", it means it — do not improvise a second procedure.
+
+## Step 1 — get SUBSTRATE_URL + identity env
+
+Ask the user for their Substrate base URL (e.g. `https://substrate.example.com:3100`)
+unless it is already exported in their shell.
+
+The OpenCode skin reads `SUBSTRATE_URL`, `SUBSTRATE_NAMESPACE` (default `cortext`),
+`SUBSTRATE_AGENT_KEY_PATH` and `SUBSTRATE_AGENT_KEY_ID` from the **opencode process
+environment** — both for cold-start injection and, via `{env:VAR}` refs, for
+the MCP server below. The recommended arrangement is one block above all
+repos (same as the Claude skin's Step 7.2):
+
+```toml
+[env]
+SUBSTRATE_URL = "https://substrate.example.com:3100"
+SUBSTRATE_AGENT_KEY_ID = "{{ cwd | basename }}-opencode@YourHost"
+SUBSTRATE_AGENT_KEY_PATH = "{{ env.HOME }}/.config/substrate/keys/{{ cwd | basename }}-opencode.key"
+```
+
+With `mise activate` in the shell rc, every repo gets a derived kid and the
+opencode.json below stays portable. GUI-launched opencode (no shell env) gets
+no identity — same caveat as the Claude skin's npx note; prefer terminal
+launch when identity matters. **Exception:** the V2 skin also takes identity
+from plugin config — the object plugin entry's `options.kid` / `options.key`
+(Step 3) win over the env pair and survive GUI launch, since they ride in the
+config file instead of the process env.
+
+## Step 2 — probe capability
+
+Using the `substrate` MCP tools (or `curl -sfk` as fallback), check each of the
+following and report it as ✓/✗:
+
+1. **Reachable:** `GET <SUBSTRATE_URL>/health` → 200.
+2. **Coordinator present (hard prerequisite):** `schema` includes the
+   coordinator namespace — `cortext` by default, or whatever `SUBSTRATE_NAMESPACE`
+   names (look for `cortext/AgentRule`, `cortext/Todo`). If absent,
+   **STOP**: "The cortext coordinator isn't loaded on this Substrate. Install it
+   server-side before onboarding."
+   - The legacy `claude` namespace is **retired** — `unknown_namespace`.
+3. **Recall capability:** `GET <SUBSTRATE_URL>/substrate/v1/embed-stats` → `enabled`.
+   `true` = hybrid cold-start; `false` = structural-only (degrades cleanly).
+4. **MCP package resolvable** (only if Step 4 uses the npx server form):
+   `npm view @mnmal-ai/substrate version`. It is public on npmjs.com, so a
+   failure here is a network or registry-mirror problem, not missing auth.
+
+Print a capability summary block.
+
+## Step 3 — install the plugin + conventions instructions
+
+1. Add the plugin to the repo's `opencode.json` (create it if absent; never
+   clobber existing keys). Prefer the object form — it carries the per-project
+   identity through `options`, which wins over the Step-1 env pair:
+
+   ```json
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugins": [
+       {
+         "package": "@mnmal-ai/cortext-opencode",
+         "options": {
+           "kid": "<the Step-1 kid>",
+           "key": "<the Step-1 key file>"
+         }
+       }
+     ]
+   }
+   ```
+
+   The plain string form (`"plugins": ["@mnmal-ai/cortext-opencode"]`) also
+   works — identity then comes from the env pair. **Keep exactly one entry
+   per package**: as of opencode v2.0.24 the `plugins`
+   arrays concatenate across global + project config and loads dedupe only
+   by exact source string, so a global string entry plus a project object
+   entry for the same package load the plugin twice and double-inject the
+   cold-start. If the plugin is already in the global config as a string
+   entry, remove that entry when adding the project object entry.
+
+   npm plugins install automatically via Bun at startup (cached under
+   `~/.cache/opencode/`). No registry auth is needed.
+
+2. Conventions need no step: the plugin injects them from its own package
+   on every dispatch, so they track the installed version. If the
+   repo has an older `.opencode/substrate-conventions.md` copy, delete it and its
+   `"instructions"` entry; the session context names it while it is stale.
+   (`AGENTS.md` needs no import line: opencode auto-loads it, and nothing in
+   this setup writes to it.)
+
+## Step 4 — wire the substrate MCP server (opencode.json, identity-ready)
+
+Unlike the Claude skin (project `.mcp.json`), OpenCode servers live in
+`opencode.json` under `mcp.servers` — same file as the plugin entry. Merge
+this in (never clobber other servers).
+
+**Sign the MCP server as the plugin's identity**. The plugin shows
+mail for its identity and only that kid may ack it, so a mismatch shows mail
+the session cannot close. If Step 3 used `options.kid` / `options.key`, put
+the same kid and key in this server's `environment` as literals, in a
+user-level config, instead of the `{env:…}` refs below, which a GUI launch
+leaves empty:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "substrate": {
+        "type": "local",
+        "command": ["npx", "-y", "@mnmal-ai/substrate", "mcp"],
+        "codemode": false,
+        "environment": {
+          "SUBSTRATE_URL": "<the url>",
+          "SUBSTRATE_AGENT_KEY_PATH": "{env:SUBSTRATE_AGENT_KEY_PATH}",
+          "SUBSTRATE_AGENT_KEY_ID": "{env:SUBSTRATE_AGENT_KEY_ID}"
+        }
+      }
+    }
+  }
+}
+```
+
+**`"codemode": false` is required.** OpenCode 2.x defaults a local
+server to code mode, which hides its tools behind the generic `execute` tool:
+the server connects, but the model never sees `substrate_*` by name, so an agent
+following the conventions reports that it has no substrate tools and cannot ack
+its mail. OpenCode prefixes each tool with its server name, so they reach the
+model as `substrate_query`, `substrate_mutate`, `substrate_whoami` and so
+on. Confirm after a restart (bounce `opencode serve --service`, not just the
+TUI) that the session calls `substrate_whoami` directly and gets its kid.
+
+Dialect notes that bite Claude migrants: servers go under `mcp.servers`, not
+`mcpServers` (OpenCode 1.x used bare `mcp.<name>`, which 2.x still migrates;
+on 1.x, drop the `servers` level and the `codemode` key); `type: "local"` is
+required; `command` is an **array**; env
+rides under `environment`; interpolation is `{env:VAR}`, **not** `${VAR}`
+(which is passed through literally). The `{env:}` refs resolve against the
+Step-1 environment and stay inert until identity exists.
+
+- **Operator box** (local `@mnmal-ai/substrate` install): prefer
+  `"command": ["/abs/.../node", "/abs/.../substrate.js", "mcp"]` — no registry
+  dependency at session start. A committed file holding absolute paths is
+  machine-specific: gitignore `opencode.json` in that case, as with the
+  Claude skin's operator-box rule.
+- **Restart opencode** after writing: config loads once at startup.
+
+## Step 5 — seed baseline AgentRules (coverage-first, deselectable)
+
+Same catalogue and same procedure as the Claude skin:
+
+1. Query `<ns>/AgentRule` (active, `project: null` and this project) and read
+   the existing `rule` texts. There is no `key` field; compare **substance**,
+   not text equality — mature stores already cover these with richer wording.
+2. Baselines (universal tier → `project: null`): `mcp-call-style` (never echo
+   MCP payloads in chat), `concise-responses` (no trailing summaries),
+   `git-feature-branch` (PRs, never main), `mcp-first` (MCP tools, HTTP only
+   when unreachable), `cold-start-adherence` (read the injected context
+   before acting).
+3. Report coverage; ask only about the remainder; batch-create with
+   `<ns>/createAgentRule` in one mutation.
+
+## Step 6 — recall degradation notice
+
+If Step 2 found recall **disabled**, tell the user plainly: cold-start runs
+**structural-only** (recency/importance ordering) and **auto-upgrades** to
+hybrid recall when an embedder comes online — no re-run needed.
+
+## Step 7 — agent identity: DETECT first, provision only if needed
+
+`GET <SUBSTRATE_URL>/substrate/v1/whoami` from a signed shell (or `substrate-admin list`
+from the operator box, which reads postgres directly). If the Step-1 kid
+resolves to a registered row with a present key file, say so and skip.
+
+Otherwise — consent-gated, generate → register → restart as ONE unit (a
+generated-but-unregistered key 401s every read, strictly worse than none):
+
+```bash
+mkdir -p ~/.config/substrate/keys && chmod 700 ~/.config/substrate/keys
+KID="$(basename "$(git rev-parse --show-toplevel)")-opencode@$(hostname -s)"
+KEYFILE=~/.config/substrate/keys/$(basename "$(git rev-parse --show-toplevel)")-opencode.key
+if [ ! -f "$KEYFILE" ]; then
+  openssl genpkey -algorithm ed25519 -out "$KEYFILE"
+  chmod 600 "$KEYFILE"
+  openssl pkey -in "$KEYFILE" -pubout -out "${KEYFILE%.key}.pub"
+fi
+```
+
+Register (operator, admin — not via MCP tools): `substrate-admin register
+"$KID" --pubkey "${KEYFILE%.key}.pub" --ns "<ns>,recall"
+--caps read,mutate`, restart the binary, then seed the directory row
+(`<ns>/createAgentIdentity`) so the agent is routable for mail. Verify with
+a write and read its `_metadata.createdBy` — must be `{kind:'agent',
+id:'<KID>'}`.
+
+## Step 8 — write the first anchor, then confirm
+
+Onboarding does not seed an `AnchorIntent`, and a repo without one ranks its
+rules **structurally** (no semantic half). Write one real intent — never a
+placeholder (`"onboarded this repo"` is semantic noise aimed at the rule
+set):
+
+```
+<ns>/createAnchorIntent { project: "<project>", synopsis: "<what this repo is for and what is being worked on right now>" }
+```
+
+Then summarise: SUBSTRATE_URL source, plugin entry, instructions copy, MCP
+server form, rules created vs skipped, recall tier, identity (per-project
+kid vs fleet default). Tell the user to restart opencode — config loads once
+at startup, and the cold-start injects on the first dispatch after that.