# Changelog

All notable changes to ontoref are documented here.
ADRs referenced below live in `adrs/` as typed Nickel records.

---

## [Unreleased]

### MCP tool catalog via proc-macro, validate ADR-018 mode hierarchy, UI vault/registry context

**Session 2026-05-12**

**`#[onto_mcp_tool]` proc-macro — link-time MCP catalog registration (`ontoref-derive`)**
- New attribute macro that registers an MCP tool unit-struct in the catalog at link time via
  `inventory::submit!(McpToolEntry{...})`. The annotated item is emitted unchanged — `ToolBase`
  and `AsyncTool` impls remain on the struct. Required keys: `name`, `description`, `input_schema`.
- All 34 MCP tools migrated from manual `catalog()` wiring to `#[onto_mcp_tool]`. The
  `catalog()` function is now generated automatically by `inventory::collect!`.
- Tool count: 29 → 34 (net: `ontoref_list_projects`, `ontoref_search`, `ontoref_describe`,
  `ontoref_list_ontology_extensions`, `ontoref_get_ontology_extension` added).

**`validate modes` — ADR-018 level hierarchy and strategy compliance (`reflection/modules/validate.nu`)**
- `validate modes [--check]` — reads `reflection/defaults/workflow.ncl::level_hierarchy` and
  checks every `.ncl` mode file against the declared levels: level declared, strategy declared,
  delegate chain coherent, compose `extends` references valid.
- `mode resolve <id>` — prints which hierarchy level handles the given mode id and why.
- `validate modes --self-test` — generates synthetic mode fixtures in a temp dir and runs checks
  against them; fast CI-safe smoke test for the validator itself.

**`validate run-cargo` — two-step Cargo.toml resolution**
- Resolves `Cargo.toml` in workspace layout first (`crates/<check.crate>/Cargo.toml`), then
  falls back to single-crate root when `[package].name` matches or `check.crate` equals the
  repo basename. Lets the same ADR constraint shape apply to workspace repos (stratumiops) and
  single-crate projects without per-repo special cases.

**UI — vault and registry context in project_picker**
- Each project card in the project picker now surfaces OCI state inline:
  - Registry badge (`⟳ <participant>`) when `manifest.ncl::registry_provides` is declared.
  - Vault badge (`⛁ <vault_id> · N`) coloured green (declarative) or amber (legacy) when
    `project.ncl::sops.enabled` is true.
- Expanded project details panel: collapsible **Registry** section listing namespaces, endpoint,
  and push/pull capability per namespace.

**UI — runtime service toggles in manage page**
- `manage.html` gains a **Runtime Services** card: MCP and GraphQL can be toggled on/off via
  HTMX `POST /ui/manage/services/{service}/toggle` without restarting the daemon.
- `insert_mcp_ctx` helper injects MCP and GraphQL runtime state + daemon version into every
  Tera template context that needs it.

**Manifest schema — registry topology contract (`ontology/schemas/manifest.ncl`)**
- New `registry_topology_type` contract: declares multi-registry coordination (which registries
  the project participates in, push targets, participant scopes, and per-namespace capability).
- `manifest_type` gains optional `registry_topology` field.

**Requirements — OCI tooling declared in `reflection/requirements/base.ncl`**
- `oras ≥ 1.2.0` (Hard), `cosign ≥ 2.0.0` (Hard), `sops ≥ 3.9.0` (Hard), `age ≥ 1.1.0`
  (Hard), `restic` (Soft) added as named requirements with `check_cmd`, `version_extract`,
  and `install_hint`. Surfaces in `describe requirements` and `ontoref_guides`.

**describe.nu + sync.nu expansion**
- `describe capabilities` JSON output now includes `registry_topology` and `vault_state` per
  project when declared.
- `sync diff --docs` drift check extended to detect `//!` absence on new crates added this
  session.

---

### Per-file recipient routing for tenant isolation (ADR-019)

**Session 2026-05-03** — credential vault model extended to support per-file
recipient routing, closing the multi-tenant gap without multi-vault.

**Schema additions** (`install/resources/schemas/ontoref-project.ncl`)
- `sops.recipient_groups` (record of group → list of age public keys, optional)
- `sops.recipient_rules` (array of `{ path, groups }` records, optional)

**Bootstrap behaviour**
- When `recipient_rules` declared, `secrets-bootstrap` generates `<vault_dir>/.sops.yaml`
  with sops `creation_rules` mapping each path_regex to the union of declared groups.
- Default `registry/ro+rw.sops.yaml` pair is skipped in declarative mode — the
  operator defines files matching their tenancy scheme (e.g. `clientA-ro.sops.yaml`).
- Legacy mode (no `recipient_rules`) keeps `SOPS_AGE_RECIPIENTS` env-var path.

**Operational locks**
- `secrets-add-key` and `secrets-remove-key` error in declarative mode and
  direct the operator to edit `project.ncl::sops.recipient_groups` plus `secrets-rekey`.
- `secrets-rekey` regenerates `.sops.yaml` from `project.ncl` then runs `sops updatekeys`
  on every `*.sops.yaml` in the vault.

**Adoption templates** (`install/resources/templates/sops/`)
- `single-team/` — one team, no tenant separation (legacy / Path A)
- `multi-tenant/` — clientA/clientB groups + path-routed credentials
- `agent-first/` — admin/developer/agents with `agent-readonly.sops.yaml` for AI access

**Integration templates** (`install/resources/templates/integration/`)
- `domain-producer/` — contract.ncl + example.json + manifest.ncl scaffold
- `mode-producer/` — provisioning.ncl + domains.lock.ncl + manifest.ncl scaffold
- `mode-consumer/` — cabling.ncl scaffold for binding pulled modes to workspace values

**Audit checks** (`secrets-audit`) — three new checks for ADR-019 constraints:
- `recipient-routing-coherent` — every group referenced by a rule must be declared;
  every rule must resolve to ≥ 1 recipient
- `recipient-routing-coverage` — every `*.sops.yaml` in the vault must match at
  least one declared rule
- `no-multi-vault` — rejects `sops.vaults =` declaration (multi-vault not implemented)

**FAQ entries** (`reflection/qa.ncl`) — six entries with diagrams:
- `credential-vault-best-practice` — layered model with data-flow diagram
- `credential-vault-templates` — three adoption paths (A/B/C)
- `credential-vault-troubleshooting` — 15 named errors and recovery steps
- `integration-what-and-why` — federated OCI artifacts (ADR-042) overview with diagram
- `integration-how-to-implement` — producer / consumer / both, with templates
- `integration-troubleshooting` — push/pull/invoke common failures

**ADR-019: Per-File Recipient Routing for Tenant Isolation in lieu of Multi-Vault**
Documents the decision, alternatives (multi-vault explicitly rejected), and 6
machine-checkable constraints. Each constraint is wired to either `secrets-audit`
(NuCmd), `Grep`, or `FileExists` — verifiable from CLI without a custom validator.

**Tests** — `reflection/tests/test_secrets.nu` covers 14/14 named errors of the
helper contract end-to-end (`sops-decrypt-failed` excluded — requires real age
keypair plumbing).

**Bug fixes**
- `_find-capabilities-ncl`: glob malformation when walking up to filesystem root
- cosign `--tlog-upload=false` deprecated in cosign 2+ → use `--signing-config`
  with `rekorTlogUrls`/`rekorTlogConfig` stripped
- cosign `sign` needed `DOCKER_CONFIG` to fetch manifest before signing
- Cache hit in `domain-pull` / `mode-pull` bypassed authorization gate (reordered)
- Per-file `(...)` interpolation traps in nu strings inside error messages
- `add-key` / `remove-key` only mutated `access.sops.yaml` instead of all sops
  files in the vault

---

### VCS abstraction layer and agent workspace orchestration

#### `'Framework` RepoKind

- `ontology/schemas/manifest.ncl`: `'Framework` added to `repo_kind_type` enum. Reserved for
  projects that define protocol schemas — no consumer obligation, no domain activation.
- `.ontology/manifest.ncl`: `repo_kind` corrected from `'DevWorkspace` to `'Framework`.
  ontoref is the protocol definition; the provisioning domain activating for its own repo
  was semantically incorrect.

#### VCS abstraction layer (`reflection/modules/vcs.nu`)

- New module exporting a uniform VCS API over jj and git: `detect`, `is-repo`,
  `show-committed`, `restore-file`, `remote-url`, `current-branch`, `uncommitted-files`,
  `commit-count`.
- Detection is filesystem-based (`.jj/` vs `.git/`) — no config, no env var.
- `reflection/modules/opmode.nu` and `reflection/hooks/git-event.nu` migrated to consume
  `vcs.nu` instead of hardcoded `^git` calls.
- jj is strictly opt-in: all commands degrade to git when `.jj/` is absent.
  `jj` and `rad` are NOT listed as requirements in ontoref's manifest — they belong
  in the manifest of orchestration projects (e.g. vapora) that depend on them.

#### Agent workspace orchestration (`reflection/bin/jjw.nu`)

- New orchestration wrapper: `jjw agent create | step | publish | merge | discard`.
  Wraps jj workspace commands, `ontoref run/step` calls, and optional `rad patch open`.
- `jjw agent create`: creates a jj workspace at `.agents/<run_id>/`, writes `.ontoref-run`
  metadata, starts an ontoref run for the given mode.
- `jjw agent publish`: validates uncommitted changes, pushes to remote, opens a Radicle
  patch if a `rad` remote is configured; falls back to `git push` otherwise.
- `jjw agent merge`: advances main, cleans the workspace, marks the ontoref run complete.
- `reflection/bin/jjw-ncl-merge.nu`: jj custom merge tool for `.ontology/` NCL conflicts.
  Register via `~/.config/jj/config.toml` `[merge-tools.ncl]` — not auto-installed.
- `reflection/bin/init-repo.nu`: VCS-aware repo initializer called by the `new_project`
  mode `init_repo` step. Detects jj/git state; defaults to `jj git init --colocate`
  (preferred for Radicle) when no VCS is present.

#### ADR-013

- `adrs/adr-013-vcs-abstraction-layer.ncl`: documents the decision, two hard constraints
  (no direct ^git/^jj outside vcs.nu; jj/rad must not be required=true in ontoref manifest),
  and three rejected alternatives (env var, per-module inline detection, command-translation shim).

#### on+re update

- `core.ncl`: `vcs-abstraction` (adrs: ["adr-013"]) and `agent-workspace-orchestration`
  Practice nodes added with `artifact_paths` and edges into `reflection-modes`,
  `project-onboarding`, `no-enforcement`.
- `manifest.ncl`: `vcs-abstraction` and `agent-workspace-orchestration` capabilities added
  (21 total). `reflection/bin/init-repo.nu` added to `project-onboarding` artifacts.

---

### Rust doc authoring pattern — canonical `///` convention

#### `#[onto_api]` — `description` now optional

- `description = "..."` parameter is no longer required when a `///` doc comment exists
  above the handler. The proc-macro reads the first `///` line as the fallback description.
- Same fallback applied to `#[derive(OntologyNode)]` — `///` first line used when
  `description` attribute is absent.
- `ontoref-daemon/src/api.rs`: 42 handlers migrated — `description = "..."` removed from
  all `#[onto_api]` blocks, canonical `///` first line added above each handler.

#### `sync diff --docs --fail-on-drift`

- New `--fail-on-drift` flag on `sync diff`: exits 1 when any crate `//!` has drifted
  from its ontology node description. Intended for pre-commit enforcement; without the
  flag, the command remains non-destructive and returns the table as before.

#### mdBook `crates/` chapter

- `generator.nu`: two helpers added — `read-crate-module-doc` (parses `//!` from
  `lib.rs`/`main.rs`) and `count-pub-coverage` (ratio of documented pub items).
- `render-mdbook` generates `docs/src/crates/<name>.md` per workspace member: `//!`
  content, pub item coverage badge, feature flags from `Cargo.toml`, and which practice
  nodes list the crate as primary `artifact_paths`. Missing `//!` renders a warning block.
- `SUMMARY.md` gains a `# Crates` section with links to all generated pages.

#### Pre-commit hooks

- `.pre-commit-config.yaml`: `docs-links` hook runs rustdoc broken-link check
  (`RUSTDOCFLAGS` with `-D rustdoc::broken-intra-doc-links`) on `.rs` changes.
- `.pre-commit-config.yaml`: `docs-drift` hook runs
  `sync diff --docs --fail-on-drift` on `.rs` changes.

#### Agent and developer directives

- `.claude/CLAUDE.md`: `### Documentation Authoring (Rust)` section added — three-layer
  table, four authoring rules, agent discovery commands (`describe workspace`,
  `describe features`, `sync diff --docs`), crate registration procedure.

#### Migration

- `0012-rust-doc-authoring-pattern`: consumer projects receive the
  `### Documentation Authoring (Rust)` section for their `CLAUDE.md` and optional
  pre-commit hooks (`docs-links`, `docs-drift`).

---

### Mode guards, convergence loops, and manifest coverage enforcement

#### Mode schema extension (ADR-011)

- **Guard type** added to `reflection/schema.ncl`: pre-flight executable checks with
  `Block` (abort) or `Warn` (continue) severity. Guards run before any step — the
  protocol pushes back on invalid state instead of failing silently mid-execution.
- **Converge type** added to `reflection/schema.ncl`: post-execution convergence loop
  with `condition` command, `max_iterations` cap, and `RetryFailed`/`RetryAll` strategy.
  Modes iterate until a condition is met rather than running once blindly.
- Both types exposed in `reflection/defaults.ncl` as `Guard` and `Converge`.
- Reference implementation: `sync-ontology.ncl` gains 3 guards (ontology-exists,
  nickel-available, manifest-capabilities) and converge (iterate until zero drift,
  max 2 iterations).
- `coder-workflow.ncl` gains guard (coder-dir-exists) and new `novelty-check` step
  (anti-slop Jaccard overlap detection between pending entries and published+QA).
- Nushell executor (`reflection/nulib/modes.nu`): guard execution before steps,
  convergence loop after steps.
- Rust types: `Guard`, `GuardSeverity`, `Converge`, `ConvergeStrategy` in
  `ontoref-reflection/src/mode.rs`.
- Rust executor: guards evaluated pre-execution (Block returns error, Warn logs),
  convergence loop post-execution.
- Backward compatible: `guards` defaults to `[]`, `converge` is optional.
  All 19 existing modes export unchanged.

#### Manifest capability completeness (19 capabilities)

- `.ontology/manifest.ncl` expanded from 3 to 19 declared capabilities covering the
  full action surface: protocol spec, daemon API, reflection modes, run/step tracking,
  Agent Task Composer, backlog graduation, notifications, coder process memory, QA store,
  form system, template generation, describe query layer, drift detection, quick actions,
  protocol migration, config surface, search bookmarks, project onboarding, web presence.
- `audit-manifest-coverage` function in `reflection/modules/sync.nu`: cross-references
  Practice nodes, reflection modes, and daemon UI pages against declared capabilities.
- `sync manifest-check` exported command for pre-commit hooks and CI.
- `validate-project.ncl` gains 6th validation category: `manifest-cov`.
- Pre-commit hook `manifest-coverage`: fires on `.ontology/`, `reflection/modes/`,
  `reflection/forms/` changes.
- SessionStart hook (`session-context.sh`): shows manifest coverage status at session start.
- Agent consumption mode description updated in manifest.

#### Bug fixes

- `find-unclaimed-artifacts` in `sync.nu`: fixed absolute vs relative path comparison
  for modes and forms. `path relative-to $root` applied before `starts-with` check.
  19 phantom MISSING items resolved.
- `audit-claude` session-hook check: accepts both `.claude/hooks/session-context.sh`
  and legacy `.claude/ontoref-session-start.sh`.
- `describe mode` now shows guards and converge sections.
- `scan-reflection-mode-dags` JSON output for agents now includes guards, converge,
  preconditions, postconditions, and step-level cmd/on_error/verify.

#### Infrastructure

- Justfile restructured: `justfiles/build.just`, `justfiles/test.just`,
  `justfiles/dev.just` added. CI recipes delegated to canonical modules.
  Manifest justfile convention updated to `Import` system with 5 modules.
- Manifest `claude` baseline declared: `["rust", "nushell", "nickel"]` guidelines, session_hook enabled.
- `.ontology/core.ncl`: `ci-pipelines` Practice node added. `reflection/forms/` added to `reflection-modes` artifact_paths.

#### Migrations

- `0010-manifest-capability-completeness`: consumer projects must declare ≥3 capabilities.
- `0011-manifest-coverage-hooks`: consumer projects must add pre-commit and SessionStart
  hooks for manifest coverage.

#### on+re update

| Artifact | Change |
|----------|--------|
| `.ontology/manifest.ncl` | 3 → 19 capabilities; justfile/claude baselines declared; agent consumption mode updated |
| `.ontology/core.ncl` | `ci-pipelines` node; `reflection/forms/` in reflection-modes; adr-011 in adr-lifecycle |
| `.ontology/state.ncl` | protocol-maturity catalyst updated (ADR-011, 19 caps, migrations 0010-0012); self-description-coverage catalyst updated (session 2026-03-30) |
| `adrs/adr-011-mode-guards-and-convergence.ncl` | New ADR: guards and converge extend mode schema rather than separate action subsystem |
| Health | 43.2% → 100.0% (31 OK / 0 MISSING / 0 STALE) |

---

### Browser-style panel navigation + repo file routing

Graph, search, and api_catalog pages now share a uniform browser-style navigation model:
back/forward history stack with cursor-into-array semantics. File artifact paths open in
external browser tabs rather than being loaded inline.

#### `crates/ontoref-daemon/templates/pages/graph.html`

- `.artifact-link` click handler changed from removed `openFile()` to `srcOpen()`.
- `panelNav._replay` `type: "file"` case changed to `srcOpen(e.id)`.

#### `crates/ontoref-daemon/templates/pages/search.html`

- `openFileInPanel` async function removed entirely (was loading file content inline via `/api/file`).
- `srcOpen(path)` function added: opens `{card_repo}/src/branch/main/{path}` for most files;
  opens `card_docs` for `.rs` files when configured.
- `CARD_REPO` / `CARD_DOCS` JS constants injected via Tera (`| safe` filter required — Tera
  auto-escapes all `{{ }}` interpolations regardless of `<script>` context).
- `.s-file-link` click delegation updated to call `srcOpen`.
- `dpNav._replay` `type: "file"` case calls `srcOpen`.

#### `crates/ontoref-daemon/templates/pages/api_catalog.html`

- `ensureFileModal` and `openFile` removed.
- `srcOpen` added with same logic as graph and search pages.
- `CARD_REPO` / `CARD_DOCS` constants injected.
- `#detail-source-btn` click delegation calls `srcOpen`.

#### `crates/ontoref-daemon/src/ui/handlers.rs`

- `insert_brand_ctx` reads `card.repo` and `card.docs` from config NCL and injects
  `card_repo` / `card_docs` into the Tera context for all pages.

#### `card.ncl`

- `repo = "https://repo.jesusperez.pro/jesus/ontoref"` added.

#### `reflection/migrations/0007-card-repo-field.ncl` — new migration

- Check: `card.ncl` absent → pass (not applicable); present + `repo =` found → pass; present
  without `repo =` → pending.
- Instructions: add `repo` and optionally `docs` fields; explains how `srcOpen` uses both.

#### on+re update

| Artifact | Change |
|----------|--------|
| `.ontology/core.ncl` | `ontoref-daemon` description updated — browser-style panel nav, file routing via `card.repo`/`card.docs` |
| `.ontology/state.ncl` | `self-description-coverage` catalyst updated with session 2026-03-29 |

---

### Protocol Migration System — progressive NCL checks for consumer project upgrades (ADR-010)

Replaces the template-prompt approach with an ordered, idempotent migration system. Applied state
determined by check result alone — no state file. 6 migrations shipped; runtime ships
`migrate list/pending/show` with interactive group dispatch.

#### `reflection/migrations/` — 6 ordered migrations

- `0001-ontology-infrastructure` — `.ontology/manifest.ncl` and `connections.ncl` present.
- `0002-adr-typed-checks` — no `check_hint` in ADR instance files (`adr-[0-9][0-9][0-9]-*.ncl`);
  check narrowed from `adrs/` broad scan to exclude schema/template infrastructure files.
- `0003-manifest-self-interrogation` — `capabilities[]` and `requirements[]` non-empty in manifest.ncl.
- `0004-just-convention` — justfile validates against canonical module convention (pending in this repo — documented gap).
- `0005-mode-step-schema` — all reflection mode steps declare `actor`, `on_error`, `depends_on`.
- `0006-claude-agent-entrypoint` — `Agent Entry-Point Protocol` section present in `.claude/CLAUDE.md`.

All NuCmd checks rewritten from bash to valid Nushell: `&&` removed, `$env.VAR` replacing `$VAR`,
no bash-style redirects. Grep checks on ADR files use `adr-[0-9][0-9][0-9]-*.ncl` glob.

#### `reflection/modules/migrate.nu` — new module

- `migrate list [--fmt] [--actor]` — all migrations with applied/pending status; JSON for agents.
- `migrate pending [--fmt] [--actor]` — pending only.
- `migrate show <id> [--fmt]` — runtime-interpolated instructions; accepts short ids (`002` → `0002`).
- Applied state: `run-migration-check` dispatches over `FileExists | Grep | NuCmd`.
- No state file — idempotent by construction.

#### `reflection/nulib/interactive.nu` + `help.nu` — `migrate` group wired

- `group-command-info` — `migrate` case added (list, pending, show).
- `run-group-command` — `migrate` dispatch added.
- `help-group` — `migrate` help section added; fallback "Available groups" updated.

#### `reflection/bin/ontoref.nu` — shims + aliases

- `main migrate`, `main migrate list/pending/show` added.
- Short aliases: `mg`, `mg l`, `mg p`.

#### `reflection/schemas/justfile-convention.ncl` — export fix

- Removed `Module` and `ModuleSystem` from the exported record (open contract fields with no default
  value caused `nickel export` to fail). Both remain as `let` bindings for internal NCL use.

#### on+re update

| Artifact | Change |
|----------|--------|
| `adrs/adr-010-...ncl` | Created — protocol migration system, progressive NCL checks |
| `.ontology/core.ncl` | `protocol-migration-system` node added; `adopt-ontoref-tooling` artifacts updated; `adr-lifecycle` updated with ADR-010; 4 new edges |
| `.ontology/state.ncl` | `protocol-maturity` catalyst updated (10 consumers, all features complete); blocker narrowed to `ontoref.dev not yet published` |

---

### Manifest Self-Interrogation Layer — capabilities, requirements, critical deps (ADR-009)

Three new typed arrays in `manifest_type` answering operational self-knowledge queries distinct from
ontology Practice nodes. `describe requirements` new subcommand; `describe guides` extended.

#### `ontology/schemas/manifest.ncl` — three new types

- `capability_type` — `id`, `name`, `summary`, `rationale`, `how`, `artifacts[]`, `adrs[]`, `nodes[]`.
  `nodes[]` cross-references ontology node IDs; `adrs[]` cross-references ADR IDs.
- `env_target_type` — `'Production | 'Development | 'Both` classification axis for requirements.
- `requirement_kind_type` — `'Tool | 'Service | 'EnvVar | 'Infrastructure`.
- `requirement_type` — `id`, `name`, `env`, `kind`, `version`, `required`, `impact`, `provision`.
- `critical_dep_type` — `id`, `name`, `ref`, `used_for`, `failure_impact` (required), `mitigation`.
- `manifest_type` gains `description | String | default = ""` (bug fix — `collect-identity` was reading
  a field that didn't exist), `capabilities[]`, `requirements[]`, `critical_deps[]` (all `default = []`).
- New exports: `EnvTarget`, `RequirementKind`, `Capability`, `Requirement`, `CriticalDep`.

#### `ontology/defaults/manifest.ncl` — three new builders

- `make_capability`, `make_requirement`, `make_critical_dep` added alongside existing builders.
- New type re-exports: `EnvTarget`, `RequirementKind`, `Capability`, `Requirement`, `CriticalDep`.

#### `reflection/modules/describe.nu` — new subcommand + extended outputs

- `describe requirements` — renders requirements grouped by env (Production / Development / Both) and
  critical deps table (name, ref, used_for, failure_impact, mitigation). `--environment` flag filters.
- `describe capabilities` extended — loads `manifest.capabilities?` and renders a `PROJECT CAPABILITIES
  (manifest)` section with name, summary, artifacts per entry.
- `describe guides` output gains `capabilities`, `requirements`, `critical_deps` keys — agents on cold
  start via `ontoref_guides` MCP tool receive full self-interrogation context without extra tool calls.
- Bug fix: `collect-identity` was reading `manifest.kind?` (field absent from schema, always returned
  `""`) — changed to `manifest.repo_kind?`. Same fix for `manifest.description?` (now exists).

#### `.ontology/manifest.ncl` — ontoref self-described

- `description` field populated.
- 3 capabilities: `protocol-spec`, `daemon-api`, `reflection-modes` — each with rationale, how,
  artifacts, adrs, nodes cross-references.
- 5 requirements: `nushell` (both), `nickel` (both), `rust-nightly` (dev), `surrealdb` (prod optional),
  `stratumiops` (dev optional) — each with impact and provision.
- 3 critical deps: `nickel-lang`, `inventory`, `axum` — each with failure_impact and mitigation.

#### on+re update

| Artifact | Change |
|----------|--------|
| `adrs/adr-009-...ncl` | Created — manifest self-interrogation layer, three semantic axes |
| `.ontology/core.ncl` | `manifest-self-description` node added (29 nodes, 59 edges); `adr-lifecycle` updated with ADR-009 |
| `.ontology/state.ncl` | `protocol-maturity` blocker + `self-description-coverage` catalyst updated |

---

### Config Surface — typed config, NCL contracts, override-layer mutation

Per-project config introspection, coherence verification, and audited mutation. NCL contracts are the single
validation gate; config mutation never modifies source NCL files.

#### `crates/ontoref-daemon/src/config.rs` — typed `DaemonNclConfig` (parse-at-boundary)

- `DaemonNclConfig` — top-level deserialize target for `nickel export .ontoref/config.ncl | daemon --config-stdin`;
  fields: `nickel_import_paths`, `ui: UiConfig`, `log: LogConfig`, `mode_run: ModeRunConfig`,
  `nats_events: NatsEventsConfig`, `actor_init: Vec<ActorInit>`, `quick_actions: Vec<QuickAction>`,
  `daemon: DaemonRuntimeConfig`. `#[cfg(feature = "db")] db: DbConfig`. All `#[serde(default)]`.
- Each section struct derives `#[derive(Deserialize, ConfigFields)]` + `#[config_section(id, ncl_file)]`
  — emits `inventory::submit!(ConfigFieldsEntry{...})` at link time.
- `DaemonRuntimeConfig` — optional port, timeouts, sweep intervals, `notification_ack_required: Vec<String>`.

#### `crates/ontoref-daemon/src/main.rs` — 3-tuple bootstrap block

- Bootstrap block changed to `(nickel_import_path, loaded_ncl_config, stdin_raw)` — `loaded_ncl_config: Option<DaemonNclConfig>`
  replaces raw `Option<serde_json::Value>`. `stdin_raw: Option<serde_json::Value>` retained only
  for service-mode `projects` extraction.
- `apply_stdin_config` now deserializes JSON to `DaemonNclConfig` before applying CLI overrides;
  `apply_ui_config` signature changed from `&serde_json::Value` to `&UiConfig`.
- `load_config_overrides` returns `(Option<String>, Option<DaemonNclConfig>)` — all `.get("daemon").and_then(...)` chains
  replaced with typed field access (`ncl.daemon.port`, etc.).
- NATS call site updated to `loaded_ncl_config.as_ref().map(|c| &c.nats_events)`.
- `resolve_asset_dir` gated with `#[cfg(feature = "ui")]`; `#[allow(unused_variables)]` on bootstrap tuple for `--no-default-features`.

#### `crates/ontoref-derive/src/lib.rs` — `#[derive(ConfigFields)]` macro

- New `proc_macro_derive` `ConfigFields` with helper attribute `config_section(id, ncl_file)`.
  Extracts serde-renamed field names; emits `inventory::submit!(ConfigFieldsEntry{section_id, ncl_file, struct_name, fields})`.
- Extracted `serde_rename_of(field)` helper to fix `clippy::excessive_nesting` (depth was 6).
  Field names collected via `.iter().map(|f| serde_rename_of(f).unwrap_or_else(|| f.ident...)).filter(|s| !s.is_empty())`.

#### `crates/ontoref-daemon/src/config_coherence.rs` — clippy fixes

- `and_then(|_| full_export.as_ref())` → `.and(full_export.as_ref())` (unnecessary lazy evaluation).
- Extracted `merge_meta_into_section` helper to reduce nesting depth for `_meta_*` record merging.

#### `crates/ontoref-daemon/src/api.rs` — `index_section_fields` helper

- Extracted `index_section_fields` to fix `clippy::excessive_nesting` at the cross-project field indexing loop.
  Skips `_meta_*` and `_overrides_meta` keys; indexes `(section_id, field) → Vec<(slug, value)>`.

#### `.ontoref/contracts.ncl` — new file

NCL contracts for ontoref's own config sections using `std.contract.from_validator` (not the deprecated `fun label value =>` pattern):

- `LogLevel` — enum validator: `error | warn | info | debug | trace`
- `LogRotation` — enum validator: `daily | hourly | never`
- `PositiveInt` — `value > 0 && is_number`
- `Port` — `value >= 1 && value <= 65535`
- `LogConfig` — applies per-field contracts + defaults (`level = "info"`, `rotation = "daily"`, `max_files = 7`)
- `DaemonConfig` — all fields optional (override-only); port, timeouts, intervals, `notification_ack_required`

#### `.ontoref/config.ncl` — contracts applied

- `let C = import "contracts.ncl"` added at top.
- `log | C.LogConfig = { ... }` — contract enforced before JSON reaches Rust.

#### `.ontology/manifest.ncl` — config surface enriched

- `contracts_path = ".ontoref"` added to `config_surface`.
- `log` section: `contract = "contracts.ncl → LogConfig"` added.
- New `daemon` section: `contract = "contracts.ncl → DaemonConfig"`, consumer `daemon-config` pointing to
  `crates/ontoref-daemon/src/config.rs → DaemonRuntimeConfig` with 7 declared fields.

### Protocol

- ADR-007 extended: `#[derive(ConfigFields)]` is a second application of the `inventory::submit!` / `inventory::collect!`
  linker registration pattern first established by `#[onto_api]`. Both are now referenced from the `config-surface` node.
- ADR-008 accepted: NCL-first config validation and override-layer mutation. NCL contracts are the single validation gate;
  Rust structs are contract-trusted with `#[serde(default)]`. Config mutation writes `{section}.overrides.ncl` with
  `_overrides_meta` audit record; original NCL source files are never modified. nickel export validates the merged
  result before commit; contract violations revert the override file.
  ([adr-008](adrs/adr-008-ncl-first-config-validation-and-override-layer.ncl))

### Self-Description — on+re Update

`.ontology/core.ncl` — new Practice node, updated nodes, 6 new edges:

| Change | Detail |
| --- | --- |
| New node `config-surface` | Yang — typed DaemonNclConfig, ConfigFields inventory registry, override-layer mutation API, NCL contracts, multi-consumer manifest schema; `adrs = ["adr-007", "adr-008"]` |
| Updated `adr-lifecycle` | ADR-007 + ADR-008 added to `artifact_paths` and `adrs` list (now 8 ADRs) |

New edges: `config-surface → ontoref-daemon` (ManifestsIn/High),
`config-surface → ontoref-ontology-crate` (DependsOn/High — ConfigFieldsEntry lives in zero-dep crate),
`config-surface → api-catalog-surface` (Complements/High — shared inventory pattern),
`config-surface → dag-formalized` (ManifestsIn/High),
`config-surface → self-describing` (Complements/High — ontoref validates its own config with its own contracts),
`config-surface → adopt-ontoref-tooling` (Complements/Medium).

`.ontology/state.ncl` — `protocol-maturity` blocker updated to record config surface completion.
`self-description-coverage` catalyst updated with session 2026-03-26 additions.

Previous: 4 axioms, 2 tensions, 27 practices. Current: 4 axioms, 2 tensions, 28 practices.

---

### API Catalog Surface — `#[onto_api]` proc-macro

Annotated HTTP surface discoverable at compile time via `inventory`.

- `crates/ontoref-derive/src/lib.rs` — `#[proc_macro_attribute] onto_api(method, path, description, auth, actors,
  params, tags)` emits `inventory::submit!(ApiRouteEntry{...})` for each handler; auth validated at compile time
  (`none | viewer | admin`); param entries parsed as `name:type:constraint:description` semicolon-delimited
- `crates/ontoref-daemon/src/api_catalog.rs` — `ApiRouteEntry` + `ApiParam` structs (`&'static str` fields for
  process lifetime); `inventory::collect!(ApiRouteEntry)`; `catalog()` returns sorted `Vec<&'static ApiRouteEntry>`
- `GET /api/catalog` — annotated with `#[onto_api]`; returns all registered routes as JSON sorted by path+method;
  no auth required
- `GET /projects/{slug}/ontology/versions` — per-file reload counters as `BTreeMap<filename, u64>`;
  counter bumped on every watcher-triggered NCL cache invalidation
- `describe api [--actor] [--tag] [--auth] [--fmt json|text]` — queries `/api/catalog`, groups by first tag,
  renders auth badges, param detail per route; available as `onref da` alias
- `describe diff [--file <ncl>] [--fmt json|text]` — semantic diff of `.ontology/` files vs HEAD via
  `git show HEAD:<rel> | mktemp | nickel export`; diffs nodes by id, edges by `from→to[kind]` key;
  available as `onref df` alias
- `ontoref_api_catalog` MCP tool — calls `api_catalog::catalog()` directly; filters by actor/tag/auth; returns `{ routes, total }`
- `ontoref_file_versions` MCP tool — reads `ProjectContext.file_versions` DashMap; returns per-filename counters
- Web UI: `/{slug}/api` page — table with client-side filtering (path, auth, method) + expandable detail panel; linked from nav and dashboard
- Dashboard: "Ontology File Versions" section showing per-file counters; "API Catalog" card
- `insert_mcp_ctx` in `handlers.rs` updated: 15 → 28 tools (previously stale for qa, bookmark, action, ontology extensions, validate, impact, guides)
- `HelpTool` JSON updated: 8 entries added (validate_adrs, validate, impact, guides, bookmark_list, bookmark_add, api_catalog, file_versions)
- `MCP ServerHandler::get_info()` instructions updated to mention `ontoref_guides`, `ontoref_api_catalog`, `ontoref_file_versions`, `ontoref_validate`

### Protocol Update Mode

- `reflection/modes/update_ontoref.ncl` — new mode bringing existing ontoref-adopted projects to protocol v2;
  9-step DAG: 5 parallel detect steps (manifest, connections, ADR check_hint scan, ADRs missing check, daemon
  /api/catalog probe), 2 parallel update steps (add-manifest, add-connections — both idempotent via
  `test -f || sed`), 2 validate steps (nickel export with explicit import paths), 1 aggregate report step
- `templates/ontology/manifest.ncl` — consumer-project stub; imports `ontology/defaults/manifest.ncl` via import-path-relative resolution
- `templates/ontology/connections.ncl` — consumer-project stub; imports `connections` schema; empty upstream/downstream/peers with format docs
- `reflection/modes/adopt_ontoref.ncl` — updated: adds `copy_ontology_manifest` and `copy_ontology_connections`
  steps (parallel, `'Continue`, idempotent); `validate_ontology` depends on both with `'Always`
- `reflection/templates/update-ontology-prompt.md` — 8-phase reusable prompt for full ontology enrichment:
  infrastructure update, audit, core.ncl nodes/edges, state.ncl dimensions, manifest.ncl assets,
  connections.ncl cross-project, ADR migration, final validation

### CLI — `describe` group extensions and aliases

- `main describe diff` and `main describe api` wrappers in `reflection/bin/ontoref.nu`
- `main d diff`, `main d api` — short aliases within `d` group
- `main df`, `main da` — toplevel aliases (consistent with `d`, `ad`, `bkl` pattern)
- QUICK REFERENCE: `describe diff`, `describe api`, `run update_ontoref` entries added
- `help describe` description updated to include `diff, api surface`

### Self-Description — on+re Update

`.ontology/core.ncl` — 1 new Practice node, 3 updated nodes, 3 new edges:

| Change | Detail |
| --- | --- |
| New node `api-catalog-surface` | Yang — #[onto_api] proc-macro + inventory catalog; GET /api/catalog; describe api; ApiCatalogTool; /ui/{slug}/api page |
| Updated `describe-query-layer` | Description extended: describe diff (semantic vs HEAD) and describe api (annotated surface) |
| Updated `adopt-ontoref-tooling` | Description extended: update_ontoref mode, manifest/connections templates, enrichment prompt; artifact_paths updated |
| Updated `ontoref-daemon` | 11 pages, 29 MCP tools, per-file versioning, API catalog endpoint; artifact_paths: api_catalog.rs, api_catalog.html, crates/ontoref-derive/ |
| New edge `api-catalog-surface → ontoref-daemon` | ManifestsIn/High |
| New edge `api-catalog-surface → describe-query-layer` | Complements/High |
| New edge `api-catalog-surface → protocol-not-runtime` | Complements/Medium — catalog is link-time, no runtime |

`.ontology/state.ncl` — `self-description-coverage` catalyst updated (session 2026-03-23).
`protocol-maturity` blocker updated to reflect protocol v2 completeness.

Previous: 4 axioms, 2 tensions, 20 practices. Current: 4 axioms, 2 tensions, 21 practices.

---

### Personal Ontology Schemas & Content Modes

Three new typed NCL schema families added to `ontology/schemas/` and `ontology/defaults/`:

| Schema | Types exported |
| --- | --- |
| `career.ncl` | `Skill`, `WorkExperience`, `Talk`, `Positioning`, `CompanyTarget`, `PublicationCard`, `CareerConfig` |
| `personal.ncl` | `Content` (BlogPost / ConferenceProposal / CV / Application / Email / Thread), `Opportunity` (Job / Conference / Grant / Collaboration / Podcast), `PersonalConfig` |
| `project-card.ncl` | `ProjectCard` — canonical display metadata (name, tagline, status, tags, tools, features, sort_order) for portfolio and cv_repo publication |

All types carry `linked_nodes | Array String` referencing `.ontology/core.ncl` node IDs.
`PublicationCard` is a career overlay referencing a canonical `project_node` from the portfolio repo.

Five NCL DAG reflection modes added to `reflection/modes/`:

| Mode | Purpose |
| --- | --- |
| `draft-application` | Job/grant/collaboration application anchored in personal ontology — gate alignment check, node selection, career trajectory render, status update |
| `draft-email` | Context-grounded email composition using ontology nodes as evidence |
| `generate-article` | Blog post / thread generation from project nodes and tensions |
| `update-cv` | CV refresh loop querying current career.ncl and core.ncl state |
| `write-cfp` | Conference proposal from Practice/Project nodes with gate alignment check |

### Search Bookmarks

Bookmark persistence for search results over the ontology graph. Mirrors Q&A NCL pattern (ADR-003).

- `reflection/schemas/search_bookmarks.ncl` — `BookmarkEntry` (id, node_id, kind, title, level, term, actor, created_at, tags) and `BookmarkStore` contracts
- `reflection/search_bookmarks.ncl` — typed store file; conforms to `BookmarkStore` contract
- `crates/ontoref-daemon/src/ui/search_bookmarks_ncl.rs` — `add_entry` / `remove_entry` via
  line-level NCL surgery; auto-incremented `sb-NNN` ids; concurrency-safe via `NclWriteLock`

Tests: `next_id_empty`, `next_id_increments`, `insert_into_empty_store`, `delete_first_entry`,
`delete_second_entry`, `delete_missing_id_errors`, `escape_quotes_and_backslashes`,
`concurrent_add_produces_unique_ids` (tokio, 6 concurrent tasks, asserts unique ids).

### Protocol

- ADR-006 accepted: Nushell 0.111 string interpolation compatibility fix. Four print statements in
  `reflection/bin/ontoref.nu` used `(identifier: expr)` patterns inside `$"..."` — parsed as
  command calls by Nu 0.111 parser. Fix: bare `identifier: (expr)` for label-value pairs; plain
  strings (no `$`) for zero-interpolation prints. Hard constraint: no `(label: expr)` inside
  `$"..."` in any `.nu` file. Soft constraint: zero-interpolation strings must not use `$"..."`.
  ([adr-006](adrs/adr-006-nushell-0111-string-interpolation-compat.ncl))

### Self-Description — on+re Update

`.ontology/core.ncl` — 3 new Practice nodes, updated `adr-lifecycle` and `ontoref-daemon` nodes:

| Change | Detail |
| --- | --- |
| New node `personal-ontology-schemas` | Yin — career/personal/project-card typed NCL schemas with linked_nodes DAG bridges |
| New node `content-modes` | Yang — 5 NCL DAG modes for personal content and career operations |
| New node `search-bookmarks` | Yin — bookmark persistence layer; NCL surgery via search_bookmarks_ncl.rs |
| `adr-lifecycle` | ADR-006 added to `artifact_paths` and `adrs` list |
| `ontoref-daemon` | `search_bookmarks_ncl.rs` added to `artifact_paths` |

New edges: `personal-ontology-schemas → dag-formalized` (ManifestsIn/High),
`personal-ontology-schemas → self-describing` (Complements/Medium),
`content-modes → reflection-modes` (ManifestsIn/High),
`content-modes → personal-ontology-schemas` (DependsOn/High),
`search-bookmarks → qa-knowledge-store` (Complements/High),
`search-bookmarks → ontoref-daemon` (ManifestsIn/High),
`ontoref-daemon → search-bookmarks` (Contains/High).

`.ontology/state.ncl` — `self-description-coverage` catalyst updated to include 2026-03-15 session
additions. `protocol-maturity` blocker updated to reflect Nu 0.111 fix and personal schema layer
completion.

Previous: 4 axioms, 2 tensions, 17 practices. Current: 4 axioms, 2 tensions, 20 practices.

---

### ADR–Node Declared Linkage

- `Node` schema extended with `adrs | Array String | default = []` (Nickel `ontology/schemas/core.ncl`
  and inline `CoreConfig` type).
- Rust `Node` struct gains `artifact_paths: Vec<String>` and `adrs: Vec<String>`, both
  `#[serde(default)]` — zero migration cost for existing nodes that omit the fields.
- `describe.nu` `build-howto` populates `adrs` from the node record; `render-howto` (ANSI),
  `render-howto-md`, and `howto-to-md-string` (clipboard) all emit a **Validated by** section
  when `adrs` is non-empty.
- New `GET /api/adr/{id}?slug=<slug>` endpoint — reads `adrs/<stem>.ncl`, exports via NCL
  cache, returns JSON. No auth required (read-only, loopback boundary).
- Graph UI (`graph.html`): `adrs` field passed into Cytoscape node data. Detail panel renders
  "Validated by" section with clickable `◆ <adr-id>` buttons that open a DaisyUI modal
  fetching full ADR content via the new endpoint.
- Fixed glob pattern error in `describe.nu:build-howto`: `glob $"($full)/*.rs"` replaced with
  `glob ($full | path join "*.rs")` — eliminates `//` in pattern when path has trailing separator.

### Self-Description — on+re Update

`.ontology/core.ncl` — new node, updated nodes, new edges:

| Change | Detail |
| --- | --- |
| New node `adr-node-linkage` | Practice: declares `adrs` field pattern, lists all 5 modified artifacts |
| `adr-lifecycle` | Description updated; `adrs = ["adr-001"…"adr-005"]` declared |
| `describe-query-layer` | Description updated to mention Validated by rendering |
| `ontoref-ontology-crate` | Description updated to mention `artifact_paths` + `adrs` fields; `adrs = ["adr-001"]` |
| New edge `adr-node-linkage → adr-lifecycle` | ManifestsIn/High |
| New edge `adr-node-linkage → describe-query-layer` | Complements/High |

Previous: 4 axioms, 2 tensions, 16 practices. Current: 4 axioms, 2 tensions, 17 practices.

### Ontology Three-File Split

- New Practice node `ontology-three-file-split` in `.ontology/core.ncl`: documents the
  `core.ncl` (what IS) / `state.ncl` (where we ARE vs want to BE) / `gate.ncl` (when READY
  to cross a boundary) separation and the role of `reflection/` in answering self-knowledge
  queries without reading code.
- `assets/presentation/slides.md` speaker note updated to English with reflection mention.
- `assets/web/src/index.html` "Scattered Project Knowledge" solution bullets updated (bilingual)
  to express the three-file split and `reflection/` self-knowledge layer.

### Auth & Session Model (ADR-005)

Unified key-to-session token exchange across all surfaces. All work gated on `#[cfg(feature = "ui")]`.

- `KeyEntry` gains `label: String` (`#[serde(default)]`) — audit trail for key-based sessions.
  NCL schema `install/resources/schemas/ontoref-project.ncl` updated accordingly.
- `verify_keys_list` returns `Option<KeyMatch { role, label }>` instead of `Option<Role>`.
- `SessionEntry` gains `id: String` — stable public identifier distinct from the bearer token,
  safe to expose in list responses. Prevents session enumeration by admins.
- `SessionStore` gains secondary `id_index: DashMap<id, token>` for O(1) `revoke_by_id`.
- New `SessionStore` methods: `list_for_slug`, `list_all`, `revoke_all_for_slug`,
  `revoke_by_id(id, acting_slug, acting_role) -> RevokeResult`.
- `POST /sessions` — key → UUID v4 token exchange. Accepts project keys or daemon admin password
  (`project: "_daemon"`). Rate-limited. No authentication required (it is the credential exchange endpoint).
- `GET /sessions?project=slug` — list active sessions for a project (viewer+). Without `?project=`
  param requires daemon admin and returns all sessions.
- `DELETE /sessions/{id}` — revoke by public id. Project admin: own project only. Daemon admin: any.
- `require_session()` helper: validates UUID v4 Bearer → `SessionEntry`, error boxed (`Box<Response>`)
  to satisfy `clippy::result_large_err`.
- `check_primary_auth` fast-path: UUID v4 bearer → session lookup (O(1)) before argon2 fallback (~100ms).
- `project_update_keys` (`PUT /projects/{slug}/keys`) now calls `sessions.revoke_all_for_slug` in
  addition to actor deregistration. All in-flight UI sessions for the rotated project are immediately
  invalidated.
- Daemon admin: `ONTOREF_ADMIN_TOKEN_FILE` (preferred — hash not visible in `ps aux`) or
  `ONTOREF_ADMIN_TOKEN`. Sessions use virtual slug `"_daemon"`.
- `manage_login_page` / `manage_login_submit` / `manage_logout` handlers for `/ui/manage/login`
  and `/ui/manage/logout`.
- `AdminGuard` redirects to `/ui/manage/login` when `daemon_admin_hash` is set.

### CLI Bearer Token

- `bearer-args` exported from `reflection/modules/store.nu`: returns `["-H" "Authorization: Bearer $token"]`
  when `ONTOREF_TOKEN` is set, `[]` otherwise.
- `http-get`, `http-post-json`, `http-delete` (new) in `store.nu` use `...$auth` — Bearer injected
  transparently, no behavior change when `ONTOREF_TOKEN` is unset.
- `notify-daemon-project-add` and `notify-daemon-project-remove` in `reflection/bin/ontoref.nu`
  use `bearer-args`.

### Project Setup & Onboarding

- `ontoref setup` is now the primary onboarding command (replaces manual `cp templates/` pattern).
- `--kind <K>` flag: `Service` (default) | `Library` | `DevWorkspace` | `PublishedCrate` |
  `AgentResource` | `Mixed`.
- `--parent <path>` flag: generates manifest with `implementation` layer + `<slug>-framework` layer
  and `<slug>-browse` op mode for implementation children.
- Logo auto-detection: `setup` scans `assets/` for `<slug>-logo.svg`, `<slug>.svg`, `logo.svg`
  (and `.png` variants); inserts `ui.logo` into generated `config.ncl` when found.
- `--gen-keys ["admin:label" "viewer:label"]` flag: idempotent bootstrap — skips if `role =` already
  present in `project.ncl`. Hashes via `ontoref-daemon.bin --hash-password`; prints passwords once
  to stdout.
- All `mkdir` calls in setup guarded by `if not (path | path exists)`.

### Self-Description — on+re Update

`.ontology/core.ncl` — 3 new Practice nodes, updated `ontoref-daemon` description and `artifact_paths`:

| Node | Pole | Description |
| --- | --- | --- |
| `unified-auth-model` | Yang | Key→session token exchange; session.id ≠ bearer; revoke on key rotation |
| `project-onboarding` | Yang | `ontoref setup` — idempotent scaffold, `--kind`, `--parent`, `--gen-keys` |

`ontoref-daemon` node updated: auth/session management added to description and `artifact_paths`
(`session.rs`, `auth.rs`, `login.rs`).

New edges: `unified-auth-model → ontoref-daemon`, `unified-auth-model → no-enforcement`
(Contradicts/Low — auth is opt-in), `ontoref-daemon → unified-auth-model` (Contains),
`project-onboarding → unified-auth-model` (DependsOn),
`project-onboarding → adopt-ontoref-tooling` (Complements),
`project-onboarding → daemon-config-management` (DependsOn).

`.ontology/state.ncl` — `self-description-coverage` transitions to `current_state = "fully-self-described"`.
Blocker resolved: `reflection/backlog.ncl` created, ADR-005 recorded.

`reflection/backlog.ncl` — created with 6 items: bl-001 (ontoref.dev), bl-002 (first external project),
bl-003 (`ontoref keys` CLI), bl-004 (session UI views), bl-005 (Syntaxis migration),
bl-006 (ADR-001 acceptance).

Previous state: 4 axioms, 2 tensions, 13 practices. Current: 4 axioms, 2 tensions, 15 practices.

### Protocol

- ADR-004 accepted: NCL pipe bootstrap pattern —
  `nickel export config.ncl | ontoref-daemon.bin --config-stdin`.
  Stages: Nickel evaluation → optional SOPS/Vault merge → binary via stdin.
  ([adr-004](adrs/adr-004-ncl-pipe-bootstrap-pattern.ncl))
- ADR-005 accepted: unified key-to-session auth model across CLI, UI, and MCP. Opaque UUID v4 tokens,
  `session.id ≠ bearer`, revocation on key rotation, daemon admin via `_daemon` slug.
  ([adr-005](adrs/adr-005-unified-auth-session-model.ncl))

---

### Install Infrastructure

- `install/` directory reorganized: binaries, bootstrapper, global CLI, resources, and validation
  scripts co-located.
- Binary installed as `ontoref-daemon.bin`; public entrypoint bootstrapper installed as `ontoref-daemon`.
  Users never call `.bin` directly.
- `install/ontoref-daemon-boot` (renamed from `ontoref-daemon-start`) — NCL pipe bootstrapper
  implementing ADR-004. Stages: `nickel export config.ncl` → optional SOPS/Vault secret merge →
  `ontoref-daemon.bin --config-stdin`. Supports `--dry-run`, `--sops`, `--vault`.
- `install/ontoref-daemon-boot` sets `NICKEL_IMPORT_PATH` (config dir + platform data dir schemas)
  and `NATS_STREAMS_CONFIG` (default `~/.config/ontoref/streams.json`) before launching the binary.
- `install/install.nu` — installs binary, bootstrapper, global `ontoref` CLI (ONTOREF_ROOT baked in
  at install time), UI assets, config skeleton, and global NATS topology.
  Hash-checked — unchanged files are not overwritten.
- `install/config-setup.nu` — standalone validation script: `nickel typecheck` + `nickel export`,
  path existence checks, DB and NATS liveness probes (`nc -z -w2`).
- `install/check-config-sync.nu` — CI guard asserting that every `nickel_path`-bearing field in
  `reflection/forms/config.ncl` has a matching `{{ name }}` reference in `reflection/forms/config.ncl.j2`,
  and vice versa. Wired into `just ci-lint` and `just ci-full`.

### Config Management

- `install/resources/config.ncl` — default global config skeleton with full Nickel contracts
  (`Port`, `LogLevel`, `Rotation`, `Actor`, `Severity`). Covers: daemon, db, nats_events, log,
  cache, ui, mode_run, actor_init, quick_actions, nickel_import_paths.
- `install/resources/streams.json` — global default NATS JetStream topology: ECOSYSTEM stream
  (`ecosystem.>`, 30-day retention), no project-specific consumers.
  Installed to `~/.config/ontoref/streams.json`.
- `nats/streams.json` — ontoref project-local topology with `daemon-ontoref` and `cli-notifications`
  consumers on ECOSYSTEM stream.
- `reflection/forms/config.ncl` + `reflection/forms/config.ncl.j2` — typedialog roundtrip for
  browser-based config editing (`ontoref config-edit`). Form populates fields from existing config
  via `nickel_path`; Tera template reconstructs full NCL with all contracts on save.
- `reflection/nulib/bootstrap.nu` — Nu bootstrapper helper updated: `nats-streams-config` function
  resolves `NATS_STREAMS_CONFIG` default; env var passed to daemon process via `with-env`.
- Daemon `nats.rs`: empty `streams_config` string → `None`, activating `TopologyConfig::load` fallback
  to `NATS_STREAMS_CONFIG` env var. Projects with a local `nats/streams.json` set `streams_config`
  explicitly in their config.

### Daemon Fixes

- `--config-stdin` now exclusively skips `.ontoref/config.ncl` — project config is never loaded when
  stdin config is active. Previously both paths could run.
- DB connection (`stratum-db`) only established when `db.enabled = true` in config. Previously
  connected regardless of `enabled` flag.
- NATS connection (`platform-nats`) only established when `nats_events.enabled = true`.
  "Connecting to NATS..." log moved after the enabled check.
- `NatsPublisher::connect` signature changed from `config_path: &PathBuf` (re-read file) to
  `config: Option<&serde_json::Value>` (already-loaded JSON). Eliminates double file read and ensures
  NATS uses the same config source as the rest of the daemon.
- `load_config_overrides` returns `(Option<String>, Option<serde_json::Value>)` — nickel import path
  and parsed config JSON returned together. `apply_stdin_config` returns `serde_json::Value` directly.

### Self-Description — on+re Update

`.ontology/core.ncl` — 1 new Practice node, updated `ontoref-daemon` description and artifact_paths:

| Node | Pole | Description |
| --- | --- | --- |
| `daemon-config-management` | Yang | Install + config form/template roundtrip, CI guard, global NATS topology, config-setup validation |

New edges: `daemon-config-management → ontoref-daemon` (DependsOn),
`daemon-config-management → adopt-ontoref-tooling` (Complements).

`.ontology/state.ncl` — `operational-mode` dimension description updated to reference ADR-004 bootstrap
and `NATS_STREAMS_CONFIG` mechanism. `protocol-maturity` blocker updated to reflect install pipeline
completion.

`.ontology/manifest.ncl` — `tooling` layer paths updated to include `install/` and `nats/`.

Previous state: 4 axioms, 2 tensions, 12 practices. Current: 4 axioms, 2 tensions, 13 practices.

### Protocol

- ADR-001 accepted: ontoref extracted as a standalone protocol project, independent of
  stratumiops versioning and release cycle. Consumer projects adopt via `scripts/ontoref`
  wrapper + `.ontoref/config.ncl`.
  ([adr-001](adrs/adr-001-protocol-as-standalone-project.ncl))
- ADR-002 accepted: `ontoref-daemon` introduced as optional persistent daemon for NCL export
  caching (keyed by path+mtime), actor registry (developer/agent/CI), and notification barrier
  (pre-commit hook, fail-open). Supersedes stratumiops ADR-007.
  ([adr-002](adrs/adr-002-daemon-for-caching-and-notification-barrier.ncl))
- ADR-003 accepted: Q&A and accumulated operational knowledge persist to `reflection/qa.ncl`
  — typed NCL, git-versioned, accessible via MCP tools and HTTP endpoints. localStorage
  eliminated. Q&A entries survive session boundaries and are queryable by any actor.
  ([adr-003](adrs/adr-003-qa-and-knowledge-persistence-as-ncl.ncl))

### Crates

- `ontoref-ontology`: Rust crate for loading `.ontology/*.ncl` as typed structs (`Core`, `Gate`,
  `State`). Zero stratumiops dependencies.
- `ontoref-reflection`: Rust crate for loading, validating, and executing Reflection modes as NCL
  DAG contracts. Optional `nats` feature (path dep: `platform-nats`).
- `ontoref-daemon`: Rust crate providing HTTP API (axum), DashMap-backed NCL export cache,
  notify-based file watcher, and actor registry. Optional `db` feature (path dep: `stratum-db`)
  and `nats` feature (path dep: `platform-nats`).

### Daemon — Q&A NCL Persistence (`crates/ontoref-daemon/src/ui/qa_ncl.rs`)

Line-level NCL surgery for `reflection/qa.ncl` — same pattern as `backlog_ncl.rs`. No AST parsing,
no nickel-lang-core dependency.

- `add_entry` — appends a typed `QaEntry` block before `],` array close; generates sequential `qa-NNN` ids
- `update_entry` — in-place field mutation via bidirectional scan (question + answer fields)
- `remove_entry` — removes the full block by id using backward scan for `{` and forward scan for `},`

HTTP endpoints (all under `#[cfg(feature = "ui")]` except read-only GET):

- `GET /qa-json` — export all Q&A entries as JSON (read-only, always enabled)
- `POST /qa/add` — append new entry; returns generated id
- `POST /qa/delete` — remove entry by id; invalidates NCL cache
- `POST /qa/update` — mutate question + answer fields by id; invalidates NCL cache
- `GET /actions/run` / `POST /actions/run` — execute a quick action by id; spawns `./ontoref <mode>`

Server-side hydration: `qa.html` receives `entries` as Tera context variable, embeds
`SERVER_ENTRIES` JSON literal in the page `<script>` — no fetch round-trip on load.

### Daemon — MCP Tools (`crates/ontoref-daemon/src/mcp/mod.rs`)

Four new MCP tools exposed to AI agents:

| Tool | Description |
| --- | --- |
| `ontoref_qa_list` | List Q&A entries with optional `filter` substring match. Never triggers ontology sync. |
| `ontoref_qa_add` | Append a new Q&A entry to `reflection/qa.ncl`; invalidates NCL cache. |
| `ontoref_action_list` | List all quick actions from `.ontoref/config.ncl` export. |
| `ontoref_action_add` | Create a new reflection mode at `reflection/modes/<id>.ncl` and register it as a quick action. |

Constraint: `ontoref_qa_list` and `ontoref_qa_add` never trigger `apply` steps or modify `.ontology/`
files (enforced by ADR-003).

### Daemon — Passive Drift Observation (`crates/ontoref-daemon/src/ui/drift_watcher.rs`)

Background observer bridging Yang code artifacts with Yin ontology declarations:

- Watches `crates/`, `.ontology/`, `adrs/`, `reflection/modes/` via `notify` file watcher
- 15-second debounce window before triggering scan
- Spawns `./ontoref sync scan && ./ontoref sync diff` as read-only subprocesses
- Parses stdout for MISSING / STALE / DRIFT / BROKEN markers
- Emits `ontology_drift` notification via `push_custom` when any drift is found
- Never applies changes automatically — `apply` remains a deliberate human or agent act

Started from `main.rs` under `#[cfg(feature = "ui")]`; failure to start is non-fatal (logged as warning).

### Tooling

- `reflection/modules/`: 16 Nushell operational modules (`adr.nu`, `backlog.nu`, `coder.nu`,
  `describe.nu`, `sync.nu`, etc.)
- `reflection/modes/`: 10 NCL DAG operational modes including `adopt_ontoref`, `sync-ontology`,
  `coder-workflow`, `create-pr`
- `reflection/forms/`: 7 interactive NCL forms for ADR lifecycle, backlog, and adoption
- `templates/`: Consumer-facing adoption templates (`ontoref-config.ncl`, `ontology/`, `scripts-ontoref`)
- `./ontoref`: Bash entry point with actor auto-detection, advisory file locking, and Nushell version
  guard (>= 0.110.0)

### Self-Description — on+re Update

`.ontology/core.ncl` updated with 3 new Practice nodes and 9 new edges:

| Node | Pole | Description |
| --- | --- | --- |
| `qa-knowledge-store` | Yin | Q&A entries as typed NCL — accumulated knowledge queryable by any actor |
| `quick-actions` | Yang | Runnable shortcuts over reflection modes; configured in `.ontoref/config.ncl` |
| `drift-observation` | Spiral | Passive bridge between Yang code artifacts and Yin ontology declarations |

New edges: `qa-knowledge-store → dag-formalized`, `qa-knowledge-store → coder-process-memory`,
`ontoref-daemon → qa-knowledge-store`, `quick-actions → reflection-modes`,
`quick-actions → ontoref-daemon`, `describe-query-layer → quick-actions`,
`drift-observation → ontoref-daemon`, `drift-observation → ontology-vs-reflection`,
`drift-observation → reflection-modes`.

Previous state: 4 axioms, 2 tensions, 9 practices. Current: 4 axioms, 2 tensions, 12 practices.

`reflection/schemas/qa.ncl` — `QaStore` and `QaEntry` types (id, question, answer, actor, created_at,
tags, related, verified).
`reflection/qa.ncl` — typed store file, conforms to `QaStore` contract, Nickel typecheck must pass.

---

*ontoref uses its own ADR system to track decisions. Architectural rationale lives in `adrs/`, not in this file.*