@animalabs/connectome-host 0.7.4 → 0.8.0

package/.env.example

@@ -23,11 +23,18 @@ ANTHROPIC_API_KEY=sk-ant-...
 # GITLAB_TOKEN=glpat-...
 # GITLAB_API_URL=https://gitlab.example.com/api/v4
 
-# Notion (knowledge-miner.json: syncntn)
+# Notion — only if you add a Notion MCP server block back to
+# knowledge-miner.json (none ships by default; see TRIUMVIRATE-SETUP.md Step 6)
 # NOTION_STORAGE_URL=http://localhost:8000
 # NOTION_WORKSPACE_ID=...
 
-# Scribe — audio/video transcription (knowledge-miner.json: scribe)
-# GEMINI_API_KEY=...           # REQUIRED if you keep the scribe server (recipe uses bare ${GEMINI_API_KEY}); powers transcription
-# NOTION_API_KEY=...           # optional (recipe uses ${NOTION_API_KEY:-}); only scribe--scribe_notion_page needs it
-# SCRIBE_GLOSSARY_URL=...      # optional (recipe uses ${SCRIBE_GLOSSARY_URL:-}); unset = transcribe without a glossary
+# Web UI credentials (triumvirate.json: webui). Defaults to admin:admin —
+# CHANGE THESE for anything reachable beyond your own machine.
+# WEBUI_USERNAME=admin
+# WEBUI_PASSWORD=admin
+
+# Scribe — audio/video transcription. Only if you add a scribe block back to
+# knowledge-miner.json (none ships by default; see TRIUMVIRATE-SETUP.md Step 6)
+# GEMINI_API_KEY=...           # required by the scribe block (bare ${GEMINI_API_KEY}); powers transcription
+# NOTION_API_KEY=...           # optional (block uses ${NOTION_API_KEY:-}); only scribe--scribe_notion_page needs it
+# SCRIBE_GLOSSARY_URL=...      # optional (block uses ${SCRIBE_GLOSSARY_URL:-}); unset = transcribe without a glossary

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -19,8 +19,9 @@
 
 ---
 
-- [ ] `CHANGELOG.md` updated under `## Unreleased` — or this change is
-      internal-only / test-only / docs-only (apply the `no-changelog` label).
+- [ ] Changelog fragment added — `changelog.d/<slug>.<breaking|added|changed|fixed>.md`
+      (see `changelog.d/README.md`) — or this change is internal-only /
+      test-only / docs-only (apply the `no-changelog` label).
 
 <!-- AI-assisted contributions are welcome and normal here — see
      CONTRIBUTING.md for the attribution convention (footer + Co-Authored-By). -->

package/.github/workflows/changelog.yml

@@ -14,19 +14,24 @@ jobs:
     if: "!contains(github.event.pull_request.labels.*.name, 'no-changelog')"
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           fetch-depth: 0
 
-      - name: Require CHANGELOG.md update when src/ changes
+      - name: Require changelog fragment when src/ changes
         run: |
           base="${{ github.event.pull_request.base.sha }}"
           head="${{ github.event.pull_request.head.sha }}"
           changed=$(git diff --name-only "$base...$head")
+          # Fragments must be *added* — a deleted or renamed fragment also
+          # appears in --name-only and must not satisfy the check.
+          added=$(git diff --name-only --diff-filter=A "$base...$head")
           echo "Changed files:"
           echo "$changed"
-          if echo "$changed" | grep -q '^src/' && ! echo "$changed" | grep -qx 'CHANGELOG.md'; then
-            echo "::error::This PR touches src/ but not CHANGELOG.md. Add an entry under 'Unreleased' (see CONTRIBUTING.md), or apply the 'no-changelog' label if the change is internal-only."
+          if echo "$changed" | grep -q '^src/' \
+             && ! echo "$added" | grep -Eq '^changelog\.d/[^/]+\.(breaking|added|changed|fixed)\.md$' \
+             && ! echo "$changed" | grep -qx 'CHANGELOG.md'; then
+            echo "::error::This PR touches src/ but carries no changelog entry. Add a fragment changelog.d/<slug>.<breaking|added|changed|fixed>.md (see CONTRIBUTING.md), or apply the 'no-changelog' label if the change is internal-only."
             exit 1
           fi
           echo "OK"

package/.github/workflows/ci.yml

@@ -25,15 +25,17 @@ jobs:
         os: [ubuntu-latest, macos-latest]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
 
       - name: Setup Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           node-version: 24
 
       - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: 1.3.14
 

package/.github/workflows/publish.yml

@@ -15,15 +15,17 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
 
       - name: Setup Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           node-version: 24
 
       - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: 1.3.14
 
@@ -51,7 +53,9 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
 
       - name: Require changelog section for this release
         run: |
@@ -63,7 +67,7 @@ jobs:
           fi
 
       - name: Setup Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           # node 24 ships npm >= 11.5.1, required for OIDC publishing.
           node-version: 24
@@ -91,7 +95,9 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
 
       - name: Mirror changelog section into release notes
         env:

package/CHANGELOG.md

@@ -1,7 +1,252 @@
 # Changelog
 
+Entries land with the change that causes them, as fragment files in
+[`changelog.d/`](changelog.d/) that are folded into a version section at
+release time — see [CONTRIBUTING.md](CONTRIBUTING.md#changelog).
+
 ## Unreleased
 
+## 0.8.0 — 2026-09-05
+
+### Added
+
+- Recipes accept `agent.proseRouting: "disabled"` for tool-only external publication when paired with a supporting Agent Framework release.
+- **`modules.instructions`** — a shared living-instructions file (a CLAUDE.md
+  analogue kept in a workspace mount) injected into every agent's context on
+  every turn, ephemeral subagents included. `true` for defaults
+  (`instructions/AGENTS.md`, 32 KB cap, `system` position) or
+  `{ path, header, maxBytes, position }`. Reads resolve through the workspace
+  mount (scoping + traversal guard apply), are bounded to `maxBytes`, reject
+  symlinks leading outside the mount (realpath containment), are cached by
+  `(realpath, mtime, size)`, and fail open — a missing file never blocks
+  inference. Recipe validation cross-checks the path's mount prefix against
+  the effective workspace mounts (explicit and implicit alike) at load time,
+  requires `autoMaterialize: true` on a read-write instructions mount so
+  agent curation edits actually reach the disk-side injection, and rejects
+  the host-managed `_config` mount (it materializes only on branch-changing
+  commands). Validation and the runtime share one mount builder
+  (`src/workspace-mounts.ts`), so the two cannot drift.
+
+- Recipes accept the default-off `agent.strategy.compressionSourceOnly` flag and pass it through to Context Manager's residence-scoped L1 compression request builder (#103).
+
+- Gate telemetry stamps why the turn fired: `x-gate-origin` (heartbeat |
+  event | mail | operator | raw reason), `x-gate-channel` and
+  `x-gate-counterparty` (adapter-namespaced ids, never content or display
+  names) ride the stream lane under the same `GATE_TELEMETRY=1` + base-URL
+  gate as the debt stamp; background calls on the complete lane carry debt
+  only (#113).
+
+- Gate-bound Anthropic calls carry an `x-gate-debt-chunks` header with the
+  live compression-debt pending-chunk count (membrane `dynamicHeaders`,
+  antra-tess/membrane#65) — the gateway records it per ledger row and strips
+  it before the vendor. Double-gated on `GATE_TELEMETRY=1` AND a configured
+  `ANTHROPIC_BASE_URL`, so the stamp can never reach a vendor endpoint;
+  unreadable state sends no header rather than a guess (#109).
+
+- Health tab renders the per-agent compression-debt reduction (state, pending
+  chunks, oldest age, merge queue) and says "not reported by this stack" when
+  absent — the queue is now distinct from context composition, and the top
+  line reads "inference queued" (#110).
+
+- Add complete fail-closed recipe validation and strategy passthrough for `foldingStrategy: "kv-unified"`; partial policies, invalid occupancy bands, unsafe approximation grids, and implicit treeification are rejected at load time.
+
+- **`agent.provider: 'openai-compatible'`** — run an agent against any
+  OpenAI chat-completions endpoint (Ollama, vLLM, Together, Groq, NanoGPT,
+  ...) via membrane's existing `OpenAICompatibleAdapter`, which no host ever
+  wired. The recipe names the endpoint (`agent.baseUrl`, validated as an
+  absolute http(s) URL at load) and the model (required — no default for an
+  arbitrary endpoint); the key comes from `OPENAI_COMPATIBLE_API_KEY`
+  only (no `OPENAI_API_KEY` fallback — `baseUrl` is recipe-controlled, so a
+  fallback would silently send a real OpenAI credential to an arbitrary
+  endpoint) and may be absent for local servers.
+  `agent.baseUrl` with any other provider is rejected at load time.
+
+- Recipes can pass the Context Manager source-only compression controls through Host/FKM, including the new default-off L1 and merge final-fallback modes, with boolean validation and cross-agent isolation.
+
+### Added
+
+- **`agent.cacheKeepalive` — hold an idle agent's 1h prompt cache warm.** With
+  `cacheTtl: "1h"`, an idle agent's cached prefix expires after an hour and its
+  next wake pays a **2x cache write** over the entire context. Reading an entry
+  restarts its clock, so membrane now replays the last request with
+  `max_tokens: 0` (prefill only) to refresh it at cache-**read** price (0.1x).
+  On by default for the anthropic provider; `{ "enabled": false }` opts out.
+  - **Cost is proportional to actual idleness, not to `maxIdleHours`.** A poke
+    fires only when the entry is genuinely near expiry, so a busy agent never
+    fires one — its own traffic already refreshed the TTL. Measured on mythos
+    llm-calls over 36h: 563 of 637 gaps were under 5 minutes, only 5 exceeded
+    1h.
+  - Knobs: `maxIdleHours` (default 24, measured from the last **real** request
+    so pokes cannot extend their own mandate) and `refreshAfterMinutes`
+    (default 45). Recipe validation **rejects `refreshAfterMinutes >= the cache
+    TTL`** — such a keepalive always fires after the entry has already expired,
+    paying a full cache write on every poke while still looking like a healthy
+    successful call.
+  - Events land in `service-stderr.log`, warn-level for `ineffective` and
+    `disabled`, so a background spender is legible without opening a billing
+    dashboard.
+  - Sizing, from fable-cm's 11-day log (~500k-token prefix): 49.7M tokens of
+    `cache_creation` landed on turns following a >1h idle gap — ~$944 of write
+    premium at fable-5 rates that this converts to ~$308 of reads.
+
+- **`provider: "mock"` — run the whole host with zero provider spend and no
+  credentials.** Wires membrane's existing `MockAdapter` (previously
+  unreachable from any recipe) as a first-class provider: echoes the last
+  user message by default, or returns `agent.mock.defaultResponse` with
+  `agent.mock.echoMode: false` for deterministic scripted output. No API
+  key is required or read. Mock calls still ride the generic logging
+  decorator, so `llm-calls.*.jsonl` receipts work exactly as they do for
+  real providers. `recipes/mock-test.json` is a ready-made offline smoke
+  recipe (loopback webui, everything else off).
+
+### Added
+
+- **Hybrid prose routing.** Recipes may set `agent.proseRouting: "hybrid"`: unprefixed text keeps ordinary frozen-locus delivery, while a leading `>>>destination` publication envelope routes through Agent Framework’s existing authorized cross-surface resolver. Source text retains the envelope; recipients see only the body; success/failure returns to resident context.
+
+- **`conversations` recipe block — per-channel conversation forks.** Maps to
+  agent-framework's `ConversationRouter`: the recipe's agent becomes a dormant
+  trunk template, and qualifying incoming channel messages spawn per-channel
+  fork agents seeded from the trunk's current context. Recipe surface: `bind` /
+  `trigger` rules per channel kind (`dm`/`groupDm`/`channel`), `idleTtlMs`
+  (default 12h), `closurePrompt`, and `agentPrefix`. The host fills
+  `templateAgent` from the recipe and creates a fresh stateful strategy instance
+  for each fork. Absent block means no routing and no behavior change.
+
+- **Protective reaction-suppression baseline for Discord adapters.** Stdio
+  MCPL children now receive `DISCORD_SUPPRESSED_REACTIONS_BASELINE` — the
+  agent-framework's exported refusal-annotation set (`REFUSAL_REACTION_BASELINE`,
+  comma-joined) — so a never-configured Discord adapter defaults to
+  suppressing exactly the markers this host's framework stamps, instead of
+  defaulting to nothing. An operator-set value on the server entry
+  supersedes the house baseline, and the adapter's own precedence (filters-file
+  key including explicit `[]` → legacy operator env → baseline) governs
+  enforcement; lost configuration stays stale rather than re-defaulting.
+  Requires an agent-framework release carrying the `REFUSAL_REACTION_BASELINE`
+  export.
+
+- **Standing autobiographical production target.** Recipes may set `agent.strategy.productionBudgetTokens` to keep the summary forest deep enough for a later live context-budget descent without a fold storm. This is a context-token target passed through to Context Manager, not a provider-spend ceiling; omission preserves Context Manager defaults.
+
+- **`mcpl_list` reports manifest freshness.** Each loaded server now shows the
+  last validated manifest revision plus fetch and grant-negotiation timestamps.
+  Older Agent Framework versions remain legible as `manifest=unknown`, and the
+  server-authored revision is quoted and bounded before reaching model-facing
+  text.
+
+- **`BEDROCK_BASE_URL` env hook** for the bedrock provider — mirrors
+  `ANTHROPIC_BASE_URL`, routing bedrock-runtime calls through an inference
+  gateway (gate.animalabs.ai/bedrock/<credSet>). The gate reads the agent
+  token from the SigV4 Credential (`AWS_ACCESS_KEY_ID` slot), discards the
+  client signature, and re-signs with real AWS creds. First user: Princess,
+  moved off the first-party Anthropic API (classifier "bio" false-positive
+  streak) onto Bedrock Sonnet 4.5 via gate apse1 — needs membrane ≥1dcd4e3
+  for `global.` inference-profile id pass-through.
+
+### Changed
+
+- **Dependency floor: agent-framework `^0.10.0`, chronicle `^0.3.0`,
+  membrane `^0.5.78`.** af 0.10.0 brings `ConversationRouter` (the
+  per-channel conversation-fork machinery this release’s `conversations`
+  recipe surface targets, and includes the current `hybrid` prose router) and exports `nudgeAgent`, which `/nudge` has
+  called since it landed — on every published af before 0.9.0 that call
+  was a guaranteed `TypeError`, so the floor also makes `/nudge` actually
+  work. Chronicle `^0.3.0` aligns the whole tree on one chronicle copy
+  (previously context-manager `0.6.3` nested its own `0.3.0` next to the
+  host's `0.2.x`). Operators: run a clean `npm ci` — a stale
+  `node_modules` predating the lock is the known failure mode here.
+
+- **The public triumvirate recipes boot from a fresh clone.**
+  `knowledge-miner.json` no longer ships a `syncntn` (Notion) block pointing at
+  an org-internal adapter that isn't publicly available — with `NOTION_*` env
+  vars unset the block failed recipe load, and with them set it died at spawn
+  on the dangling `../syncntn` path. The `scribe` block is dropped for the
+  same reason: it hard-required `GEMINI_API_KEY` and a `../scribe-mcp`
+  sibling checkout, neither mentioned anywhere in the setup guides — a
+  guide-following fresh install always got a crashed miner. Notion and
+  Scribe are now add-a-block opt-ins, documented in SETUP.md and
+  TRIUMVIRATE-SETUP.md (the miner prompt's tool-name contracts are
+  unchanged). `triumvirate.json` declares
+  webui Basic-Auth defaulting to `admin`/`admin` (override via
+  `WEBUI_USERNAME` / `WEBUI_PASSWORD` in `.env`) instead of bare
+  `"webui": true`, which the non-loopback bind guard refuses to start.
+
+- **agent-framework `^0.11.0`** (was `^0.10.0`). Activates `proseRouting:
+  "disabled"` for recipes that set it (#100 accepted the key; the runtime now
+  implements it — generated prose is never published externally, only explicit
+  tools speak), plus AF 0.11's Windows workspace-mount fix and the
+  org-acceleration 429 cooldown. Clears the last two standing cross-package
+  `tsc` errors — the typecheck is fully clean at this lock.
+
+- Changelog entries now land as per-change fragment files in `changelog.d/`
+  (`<slug>.<breaking|added|changed|fixed>.md`), folded into the version
+  section at release time — concurrent PRs no longer conflict in
+  `CHANGELOG.md`. Editing `## Unreleased` directly still works and is merged
+  at the same point.
+
+- **membrane `^0.5.80`** (was `^0.5.78`, lockfile-resolved 0.5.79). Two
+  latent cache behaviors the host already configures become ACTIVE with this
+  relock: the prompt-cache keepalive (`agent.cacheKeepalive`, on by default —
+  previously passed to an adapter version with no such field and silently
+  ignored, so idle gaps over the 1h TTL repaid a full cache write on wake)
+  and the floating cache marker (incremental prompt caching inside the native
+  tool loop, membrane's default-on). Both reduce cost; neither changes
+  visible agent behavior. Also clears two of the four standing cross-package
+  `tsc` errors (the membrane-typing pair).
+
+- Depend on `@animalabs/agent-framework` ^0.12.0 and `@animalabs/membrane` ^0.5.82 —
+  the published versions that implement the active-turn trigger and the
+  lane-aware `dynamicHeaders` the wake-cause stamp (#113) relies on; the
+  compatibility cast and optional lookup are gone, and an adapter-level test
+  proves a stream call carries the origin trio while a complete call carries
+  debt only.
+
+### Fixed
+
+- **Prompt-cache keepalive events all go to stderr**, so every one of them lands
+  in `service-stderr.log` beside `[inference-refusal]` instead of being split by
+  severity across two sinks. Routine `refreshed` events previously went to
+  stdout — which the host unit leaves on the journal — so the log an operator
+  actually greps showed nothing. Observed on fable-cm 2026-08-23: the keepalive
+  refreshed a 523,102-token prefix three times, correctly and with zero cache
+  writes, while a monitor tailing `service-stderr.log` reported no activity for
+  three hours. A background spender that can't be found in the operator's log is
+  indistinguishable from one that never ran.
+
+- Plumb `agent.strategy.compressionRecallBudgetTokens` through recipe validation and Framework strategy construction, with positive-integer validation instead of silently accepting an inert key.
+
+- **Saved recipe snapshots no longer contain resolved secrets.** `loadRecipe`
+  substitutes every `${VAR}` — API tokens included — and the host then wrote
+  that fully resolved recipe to `$DATA_DIR/.recipe.json` at default file mode:
+  plaintext credentials in the exact directory deployments bind-mount and back
+  up (found by an external recipe review that verified live tokens in a backed
+  up `data/` directory on a production VM). The snapshot now keeps the
+  pre-substitution form — `${VAR}` references literal, a URL `systemPrompt`
+  kept as the URL — and a resumed session re-runs substitution, validation,
+  and the prompt fetch against the *current* environment, so secret rotation
+  and remote prompt updates take effect on restart without re-cooking. The
+  file is written 0600 and re-chmod'd 0600 on every save. Legacy resolved
+  snapshots (no `$unresolved` marker) still load verbatim, with no
+  substitution, so a literal `${...}` surviving in prose cannot fail them;
+  resuming an unresolved snapshot whose required env var has since disappeared
+  fails loudly naming the variable instead of silently starting the default
+  recipe.
+
+- **Ephemeral subagents inherit the caller's `proseRouting` mode.** They
+  previously always ran AF's `'locus'` default regardless of the recipe, so a
+  resident running `proseRouting: "disabled"` still spawned subagents whose
+  between-tool-calls prose published live into its open channel as parent
+  speech (field-confirmed on a deployed resident, 2026-08-26 — including
+  after the recipe adopted `"disabled"`, which reached only the resident).
+
+### Fixed
+
+- **`mcpServers.<id>.source` accepts cook's npm registry form.**
+  `validateRecipe` demanded `source.url`, but connectome-cook's source grammar
+  also has `{ "npm": "pkg@version" }` — which the shipped knowledge-miner
+  recipe uses for its gitlab server, so that recipe failed to load
+  (`mcpServers.gitlab.source.url must be a non-empty string`). Exactly one of
+  `url` / `npm` is now required; the field remains build-tooling metadata,
+  ignored at runtime.
+
 ## 0.7.4 — 2026-08-03
 
 ### Changed

package/CONTRIBUTING.md

@@ -43,7 +43,7 @@ plus, when applicable, **Not verified**, **Out of scope**, and
 - **Tests accompany behavior changes.** Review scrutinizes test substance,
   not mere presence — a test that can't fail on the unfixed code will be
   called out.
-- **Changelog entry** under `## Unreleased` for anything behavior-affecting
+- **Changelog fragment** in `changelog.d/` for anything behavior-affecting
   (see below).
 
 Conventional-commit-style titles (`feat(recipe): …`, `fix(subagent): …`) are
@@ -80,33 +80,61 @@ that don't fail on unfixed code, or with claims the branch itself disproves.
 
 ## Changelog
 
-`CHANGELOG.md` keeps a standing `## Unreleased` section with
-`### Breaking` / `### Added` / `### Changed` / `### Fixed` subsections
-(loosely [Keep a Changelog](https://keepachangelog.com/)).
-
-- **The entry lands with the change** — same commit, or at least the same
+Changelog entries land as **fragment files** in
+[`changelog.d/`](changelog.d/) — one file per change — and are folded into
+`CHANGELOG.md` (loosely [Keep a Changelog](https://keepachangelog.com/)) at
+release time. One file per change is what keeps concurrent work from
+conflicting: when every PR edited the same `## Unreleased` section, any PR
+that outlived another merge hit a conflict in `CHANGELOG.md`; distinct files
+never do.
+
+- **Format:** `changelog.d/<slug>.<breaking|added|changed|fixed>.md`, a flat
+  file directly in `changelog.d/`, containing one or more markdown bullets
+  (`- …`) written exactly as they should appear in `CHANGELOG.md`:
+  continuation lines indent two spaces, nested bullets are fine, headings
+  and horizontal rules are refused (even indented — a heading inside a
+  fragment would corrupt the section structure). The slug just has to be
+  unique among pending fragments and filesystem-safe — the PR number works,
+  and so does the branch name with `/` replaced by `-`
+  (`100-prose-routing.added.md`, `fix-retry-backoff.fixed.md`). The release
+  script scans the directory fail-closed: a subdirectory, an unrecognized
+  category suffix, or any other stray file aborts the release rather than
+  silently stranding an entry.
+
+- **The fragment lands with the change** — same commit, or at least the same
   PR. This binds direct pushes to `main` just as much as PRs. On PRs, CI
-  enforces it softly: touching `src/` without touching `CHANGELOG.md` fails
-  the `changelog` check unless the `no-changelog` label is applied.
+  enforces it softly: touching `src/` without adding a fragment (or editing
+  `CHANGELOG.md`) fails the `changelog` check unless the `no-changelog`
+  label is applied.
 - **What needs an entry:** anything an operator, recipe author, or module
   developer would notice — behavior, config/recipe schema, CLI, tool
   surfaces, defaults. Internal refactors, test-only, and docs-only changes
   don't.
-- **Breaking entries are audience-scoped.** Name the audience in the heading
-  (`### Breaking (recipe authors only)`) and cover: **who needs to act**,
+- **Breaking entries are audience-scoped.** Open the bullet by naming who
+  needs to act (`- **Recipe authors:** …`) and cover: **who needs to act**,
   **migration**, and **unchanged** (what readers might fear broke but
   didn't). The fleet recipe-path entry in `CHANGELOG.md` is the canonical
   example of the format.
+- **Editing `## Unreleased` in `CHANGELOG.md` directly still works** and is
+  merged with the fragments at release time — it remains the right place to
+  restructure pending entries, and the escape hatch for anything the
+  fragment format can't express (e.g. an audience-qualified
+  `### Breaking (recipe authors only)` heading, which `breaking` fragments
+  will then join). Keep one `## Unreleased` heading — the release script
+  refuses more than one, since only the first is ever cut.
 - **Releases** (maintainers): `npm version <patch|minor|major>` does the
-  whole cut — the `version` hook retitles `Unreleased` to
-  `## X.Y.Z — YYYY-MM-DD` (keeping a fresh `Unreleased` above it, and
-  refusing to release when there are no entries), then npm commits and tags.
-  `git push --follow-tags` triggers CI, which refuses a tag with no matching
-  changelog section, publishes `@animalabs/connectome-host` to npm, and
-  creates the GitHub release with that section as its notes. The two release
-  jobs are independent: some consumers run github-clone checkouts, so
-  release notes must exist even when npm publish fails. Version bumps are a
-  maintainer release-time action, not part of feature PRs.
+  whole cut — the `version` hook folds the pending fragments plus any
+  entries filed directly under `Unreleased` into `## X.Y.Z — YYYY-MM-DD`
+  (subsections emitted in `### Breaking` / `### Added` / `### Changed` /
+  `### Fixed` order), deletes the consumed fragments, keeps a fresh empty
+  `Unreleased` above, and refuses to release when there is nothing to
+  release; npm then commits and tags. `git push --follow-tags` triggers CI,
+  which refuses a tag with no matching changelog section, publishes
+  `@animalabs/connectome-host` to npm, and creates the GitHub release with
+  that section as its notes. The two release jobs are independent: some
+  consumers run github-clone checkouts, so release notes must exist even
+  when npm publish fails. Version bumps are a maintainer release-time
+  action, not part of feature PRs.
 
 ## Building and testing
 

package/README.md

@@ -118,6 +118,31 @@ device-code flow if needed. No `OPENAI_API_KEY` is used for this provider. Use
 warns if the service reports that it fell back to Standard; Fast mode consumes
 subscription credits at a higher rate when applied.
 
+### OpenAI-compatible endpoints (Ollama, vLLM, Together, Groq, NanoGPT, ...)
+
+Any server speaking the OpenAI chat-completions API works through the generic
+`openai-compatible` provider — the recipe names the endpoint and the model:
+
+```json
+{
+  "agent": {
+    "provider": "openai-compatible",
+    "baseUrl": "http://localhost:11434/v1",
+    "model": "qwen3:32b",
+    "systemPrompt": "You are a helpful assistant."
+  }
+}
+```
+
+The API key is read from `OPENAI_COMPATIBLE_API_KEY` only — deliberately no
+`OPENAI_API_KEY` fallback: `baseUrl` is recipe-controlled, and a real OpenAI
+credential must never be sent silently to an arbitrary endpoint. Local
+servers usually need none. `agent.model` is required —
+there is no default model for an arbitrary endpoint. Tool calls use the
+standard `tool_calls` format, so the endpoint must support function calling
+for tool-using recipes. Provider-side prompt caching and cache accounting
+depend on what the endpoint reports.
+
 ## What it provides
 
 - **Web UI**: browser operator console (`modules.webui`) — live chat with full interiority (thinking, tool calls, streaming), agent/fleet tree, context makeup + compression coverage, call ledger with cache verdicts and billing-grade costs, health/ops alerts, Chronicle branch tree, lessons, MCPL config, workspace files; scoped read-only observer access via device keys
@@ -128,6 +153,7 @@ subscription credits at a higher rate when applied.
 - **Session management**: Isolated sessions with auto-naming
 - **MCPL support**: Connect any MCP/MCPL server; wake subscriptions for selective event triggering
 - **File products**: Write reports and documents, materialize to disk
+- **Shared instructions** (opt-in, `modules.instructions`): a living instructions document (CLAUDE.md analogue) kept in a workspace mount and injected into every agent's context on every turn — the resident agent and all ephemeral subagents. Edits take effect on the next turn; nothing is persisted to history. Defaults: path `instructions/AGENTS.md`, `position: "system"`, 32 KiB cap (reads are bounded to the cap); a missing file is fail-open (no injection, warn once), while a path naming a nonexistent mount fails at recipe load — including on the implicit default workspace (`input` + `products`), whose mount set can never satisfy the default path, so declare an `instructions` mount explicitly. **Who edits, and how it propagates**: the module reads *disk*; agent `workspace--write`/`edit` land in Chronicle and reach disk only on an `autoMaterialize: true` mount — validation therefore requires it on a read-write instructions mount. On a read-only mount the flow reverses: human/deploy edits to disk reach the injection, but not `workspace--read` (which serves Chronicle) — prefer routing human feedback through conversation and letting the agent make the edit. Symlinks that lead outside the mount are rejected (realpath containment), never injected. **Cache note**: at `position: "system"` the block lives in every agent's prompt-cache prefix, so each edit is a fleet-wide cache cold start on the next turn — curate in batches, or use `afterUser` for cache-cheap, lower-salience injection. Compared to **lessons** (`modules.lessons`): lessons are a structured, confidence-scored store with model-driven retrieval; instructions are one free-form curated document, always present verbatim
 
 For `openai-responses` and `openai-codex`, an object-valued
 `modules.retrieval` can set `reasoningEffort` (`none`, `minimal`, `low`,
@@ -156,6 +182,7 @@ npm install
 |----------|---------|-------------|
 | `ANTHROPIC_API_KEY` | (required) | Anthropic API key |
 | `OPENAI_API_KEY` | — | OpenAI Platform key for `openai-responses` recipes |
+| `OPENAI_COMPATIBLE_API_KEY` | — | Key for `openai-compatible` recipes (no `OPENAI_API_KEY` fallback by design); omit for local servers |
 | `CODEX_BINARY` | `codex` | Codex CLI executable for `openai-codex` subscription auth |
 | `CODEX_HOME` | `~/.codex` | Codex credential/config directory |
 | `CODEX_BASE_URL` | ChatGPT Codex backend | Optional subscription transport override |