@davesheffer/hunch 1.32.7 → 1.33.0

package/README.md

@@ -1,289 +1,185 @@
 # Hunch
 
-## Agents are probabilistic. Organizations need deterministic state. Hunch is the state layer between them.
+## A shared record for AI agents: what was decided, what happened, and what still needs doing.
 
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
 
-Every employee is getting an agent. Each one reads the code, the CRM, the mail thread, the chat, and forms its own opinion about what was decided, what was done and what is still owed. Two agents, two slightly different realities. Neither is wrong. Both are guesses, made fresh, from raw material.
+A new agent session should not mean explaining the project all over again. A second agent should be able to check a recorded decision, see the evidence behind completed work, and find an outstanding commitment.
 
-An organization cannot run on guesses. It runs on state: this was decided, this rule is in force, this action happened and was verified, this promise is due Thursday, this summary is current and rests on these sources. Hunch holds that state in git, refuses it when it contradicts, and delivers it to Claude, Codex, Cursor, Copilot, Windsurf, Antigravity and any other MCP client before the agent answers or edits.
+Hunch keeps that record in Git and makes the relevant parts available to your agents. It started with **engineering memory**: why code exists, which approach failed before, and which rules a change must preserve. It also ships a **state server** for sharing decisions, action records, and commitments across authorized organization, team, user, and repository scopes.
 
-**Hunch started as engineering memory for coding agents** and still is: why the code is shaped this way, which alternative already failed, what an odd-looking line protects, what depends on the code about to change, and which trusted decisions, fixes and architectural boundaries a change must preserve. The same graph now holds organizational state for operations agents too (see [Deterministic organizational state](#deterministic-organizational-state)).
+The goal is simple: agents working from the same maintained record, with sources they can inspect. Hunch supplies memory and checks; the assistant still does the work.
 
-## Why Hunch, not another memory layer
+## Start with your coding assistant
 
-Memory optimizes recall. State optimizes refusal. Hunch competes for the deterministic state layer from the organizational side, and every point below is a property you can verify in this repository rather than a claim:
-
-- **Git is the source of truth.** Every fact is a JSON file under `.hunch/`, every change a commit: diffable, PR-reviewable, revertable, mergeable, never locked in a vendor database. SQLite is only a derived index.
-- **Refusal, not convergence.** One live decision per topic. A second contradicting record is refused at write time with the incumbent named, and a supersede target must still be open. Diverging writes are not merged later.
-- **Organization drawers with a key per agent.** Repository, user, team and organization partitions; the bearer key resolves the principal and decides visibility before anything is looked up.
-- **Receipts and commitments are facts.** What was actually done in an external system, verified or not, and who owes what by when, readable by any agent with the key.
-- **Never Twice.** A human correction becomes an enforced rule, not a one-session memory. Nothing blocks until a human deliberately trusts a precise rule and opts into strict enforcement.
-- **The code spoke.** Decisions, constraints and bug lineage are checked against the code deterministically, with no model in the block path. No state-layer peer has it.
-
-## Start in five minutes
-
-Requires Node 22.13+ and a Git repository.
+Requires **Node 22.13+** and a Git repository.
 
 ```bash
 npm i -g @davesheffer/hunch
 cd your-repo
 hunch init
-hunch backfill --since 90d   # optional: seed memory from recent history
-```
-
-Reload your coding assistant, then ask a normal question:
-
-> Why is this built this way?
-
-`hunch init` indexes the repository, installs local lifecycle hooks and connects supported assistants without replacing their existing configuration. The next session receives the relevant story with its sources, not a giant transcript or generic prompt wall.
-
-Lifecycle coverage depends on the harness; MCP connectivity alone does not establish automatic grounding or enforcement.
-
-To update Hunch and configured harness pins for the current repository:
-
-```sh
-hunch update
+hunch backfill --since 90d   # optional: draft memory from recent history
 ```
 
-Agents receive an instruction to run this when you ask **“update Hunch”** in generated Hunch guidance. Restart active harnesses afterward.
-
-Check integrations after upgrading Hunch or switching assistants:
+Reload your assistant, then ask:
 
-```sh
-hunch integrations check
-hunch integrations repair-pins
-hunch integrations check --harness claude --probe --require mcp
-hunch integrations check --harness codex --require context,edit-blocking
-```
+> Why is this built this way, and what should I preserve when changing it?
 
-Capabilities are reported as **verified**, **advisory-only**, **unsupported** or **untested**. `--require` fails unless every named capability is verified. `mcp` is verified by a fresh-server probe; hook capabilities become verified only from lifecycle events actually delivered to Hunch's hook on the expected version within the last 30 days (machine-local evidence, the same trust level as the served ledger), so a repository whose agent has actually run shows it, and one that only has configuration does not.
-
-Codex CLI 0.153+ gets a native lifecycle adapter (`.codex/hooks.json`: session orientation, prompt task IDs from `turn_id`, `apply_patch` pre-edit grounding and strict denial, native `Bash`/`PowerShell` post-tool observation, Stop cards); project-layer hooks load only for a trusted project and must be trusted once in Codex with `/hooks`. Failure capture is certified only by an explicit failed-tool lifecycle event; a successful `PostToolUse` observation does not prove it. The opt-in `--probe` verifies a fresh MCP process, not whether an existing host session or model actually followed the memory.
-
-Use `hunch integrations check` in CI to prevent pin drift; add `--require` for capabilities your workflow cannot operate without.
-
-## One evidence loop, not another model
-
-```text
-Git history + ADRs + corrections + tests + repository conventions
-                              │
-                              ▼
-                  Hunch's evidence graph
-                 /            │             \
-      engineering memory   Project DNA   reviewed landscape
-                 \            │             /
-                              ▼
-             role-shaped, budgeted context delivery
-                              │
-                              ▼
-             Claude / Codex / Cursor / any MCP agent
-                              │
-                              ▼
-                  deterministic change receipt
-```
+`hunch init` indexes the code, configures supported assistant integrations, and adds memory instructions while preserving existing settings. For Codex hooks, review and trust the commands in `/hooks`, then start a new session. **Memory is advisory by default.** Blocking requires an explicitly trusted rule and strict enforcement.
 
-Hunch is not the agent and is not the workflow engine. The model thinks; Hunch holds deterministic, evidence-backed state about the project and validates what must remain true.
+Hunch works with Claude Code, Codex, Cursor, VS Code/Copilot, Windsurf, Antigravity, and other MCP clients. Automatic context and hook coverage vary by assistant; a connected MCP server alone does not prove they are running. [Check your integration](https://www.hunchmemory.com/docs#update).
 
-## What Hunch understands
+## What you get today
 
-| Layer | What it adds |
+| Need | How Hunch helps |
 | --- | --- |
-| **Engineering Memory** | Decisions, rejected alternatives, corrections, bug lineage, findings and rationale a future session would otherwise miss. |
-| **Code Graph** | Symbols, calls, imports, dependencies, components, blast radius and architectural reachability across supported languages/configuration. Memory itself works with any language. |
-| **Project DNA** | Revision-specific, evidence-backed observations about how a repository communicates and works: vocabulary, contribution habits, review expectations, engineering conventions and culture. |
-| **Engineering Landscape** | Durable links from product/capability to system, repository, service, interface, data, delivery resources, runbooks, ownership, dashboards and SLOs. |
-| **Validated Delivery** | The smallest relevant evidence for the current builder/reviewer/architect, with provenance, currentness, omissions, authority and a content-addressed receipt. |
-| **Native Change Proof** | A sealed exact-change artifact binding revisions, DNA, base/result graphs, memory, blast radius, conformance, guard verdict and explicit gaps without granting workflow authority. |
-| **Change Gate + Constitution** | Deterministic checks for trusted constraints and architectural intent. Policies are compiled, proved, inspected and explicitly activated by a human. |
-
-Readable JSON in `.hunch/` is the repository-scoped source of truth. SQLite is a fast, rebuildable projection. Git keeps the state portable, reviewable and reversible.
-
-## Project DNA: help the agent work like it belongs here
-
-Project DNA is Hunch's evidence-bound model of **how a repository communicates and works**. It is not a persona, does not impersonate a maintainer and does not turn frequent behavior into policy.
-
-The deterministic baseline reads an exact Git revision, bounded commit history and committed convention files. The current release can also accept bounded, caller-authorized pull-request/review evidence. Every evidence batch is validated and sealed; raw collaboration text does not enter the profile.
-
-Each trait keeps its category, confidence, freshness, repository revision and evidence hash. Hunch can include only the relevant DNA in normal context, explain how an artifact matches repository conventions and show profile change between revisions.
-
-```bash
-hunch dna inspect
-hunch dna context
-hunch dna diff <older-ref> <newer-ref>
-```
-
-DNA may shape orientation, terminology and advisory Project Match checks. It cannot create or override a decision, constraint, finding, conformance rule, policy or permission.
-
-Read the [Project DNA contract](docs/project-dna.md) and broader [Project DNA vision](docs/project-dna-engine.md).
+| Stop explaining old decisions | Saves decisions, rejected alternatives, bug history, corrections, and open findings with their sources. |
+| Understand a change before making it | Connects memory to code symbols and dependencies; shows affected code and recorded architectural intent. |
+| Keep agents informed across sessions | Delivers a focused brief for a task through MCP and supported lifecycle hooks. |
+| Check the rules your team chose | Evaluates supported constraints and code relationships without a model in the blocking path. |
+| See what happened during a task | Separates delivered memory, the agent's reported use, rule results, and observed command results in a contribution report. |
+| Share project memory with teammates | Keeps repository memory in Git, with an optional dedicated private memory repository. |
+| Share work state across agents | Serves authorized records through HTTP, MCP, the state CLI, and typed TypeScript and Python clients. |
+| Inspect what the agents know | A read-only browser view shows current records, commitments, completed work and writer-supplied citations. |
+| Keep access and conventions explicit | Optional per-record audiences, key-bound credentials and sourced conventions use the same state contract. |
+
+For example, a team fixes a logout bug by keeping sessions on the server. Months later, an agent proposes removing that code. Hunch can surface the original reason and rejected alternative before the edit. A supported, trusted rule can flag the conflict; strict mode can block it. Recording the lesson and configuring the integration are what make this possible.
 
 ## Day-to-day
 
 | Command | Use it for |
 | --- | --- |
-| `hunch context "<task>" --profile builder` | Get a bounded builder/reviewer/architect brief before work starts |
-| `hunch why <file-or-symbol>` | See decisions, bugs, constraints and blast radius behind code |
-| `hunch structure [target]` | Inspect indexed repository shape without repeated search rounds |
-| `hunch findings [scope]` | Inherit known-but-unfixed gaps instead of rediscovering them |
-| `hunch check --working` | Review the current tree against trusted project rules |
-| `hunch conform` | Prove the code still satisfies recorded architectural intent |
-| `hunch impact origin/main` | See the dependency and memory surface of a branch |
-| `hunch compare branch-a branch-b` | Rank candidate changes by invariant/decision conflicts |
-| `hunch prove origin/main --public-only` | Produce a publication-safe `hunch.change-proof/1` artifact for an exact committed change |
-| `hunch landscape review` | Inspect a hash-bound repository landscape without writing authority |
-| `hunch task start "<title>"` · `hunch report <id> --html` | See what Hunch contributed to a task: the lesson recalled, the agent's stated application, whether the lesson's own rule held on the changed files, and the command Hunch observed — separate evidence grades, in a local evidence view |
-| `hunch now` | See recent memory and live decision-backed roadmap |
-| `hunch escalations` | See questions that genuinely require a human answer |
-| `hunch doctor` | Diagnose setup, provider, index or overlay problems |
-
-When you are ready for deterministic enforcement:
+| `hunch context "<task>" --profile builder` | Get a focused brief before starting |
+| `hunch why <file-or-symbol>` | Understand decisions and past bugs behind code |
+| `hunch structure [target]` | Inspect indexed files and symbols |
+| `hunch findings [scope]` | See known gaps that still need work |
+| `hunch impact origin/main` | See what a branch could affect |
+| `hunch check --working` | Check current changes against recorded rules |
+| `hunch conform` | Check supported architectural relationships |
+| `hunch now` | Read recent decisions and the recorded roadmap |
+| `hunch doctor` | Diagnose setup and storage problems |
+
+For enforcement after reviewing and trusting the relevant rules:
 
 ```bash
 hunch firmness strict
 hunch check --staged --strict
 ```
 
-Captured memory cannot silently hard-block on its own.
+Generated notes, observed habits, and imported documents do not silently gain blocking authority.
 
-## Deterministic organizational state
-
-Repository memory solves one version of a larger problem, and since 1.25.0 Hunch ships the larger one.
+## Update without losing your settings
 
-As organizations give every employee an agent that can work across CRM, email, messaging, repositories and other tools, the agents become probabilistic writers/readers of the same organization. If each one independently reconstructs what was decided, what was already done or what is still owed, the organization gets multiple conflicting realities.
+From each repository that uses Hunch:
 
-Hunch is the deterministic state layer between those agents and the organization:
+```bash
+hunch update
+```
 
-> **Agents are probabilistic. Organizations need deterministic state. Hunch is the state layer between them.**
+Or ask your agent to **“update Hunch.”** The command installs the latest release, aligns configured integration pins, repairs known legacy launch commands, and refreshes Hunch instructions. It preserves unrelated settings and intentionally disabled hooks.
 
-The target is **one product, one authorized state graph and one versioned state contract** across repository, user, team and organization scopes.
+- A standalone npm project keeps Hunch in its existing dependency section at an exact version. Without a repository dependency, the global CLI is updated. Add `--global` to update both.
+- For other package managers or workspaces, update the dependency with that package manager, then run `hunch integrations repair-pins`.
+- Restart or reconnect active assistants. In Codex, open `/hooks` to review and trust changed commands, then start a new session. A changed version pin changes the command and requires renewed trust.
 
-The state it holds:
+Verify the setup:
 
-- decisions currently in force;
-- verified action receipts / what was done;
-- commitments and due-state;
-- entities and relationships;
-- code/system changes with proof;
-- repository/user/team/org DNA;
-- derived current state with exact dependencies/invalidation.
+```bash
+hunch integrations check
+hunch integrations check --harness codex --probe --require mcp
+hunch integrations check --harness codex --require context
+```
 
-Agents continue to own live connector mechanics. Hunch must **not** become a managed proxy that fetches Gmail, CRM, WhatsApp or GitHub on an agent's behalf.
+The first command checks configuration. The probe starts a fresh MCP process and reads memory. The context check requires observed hook delivery on the expected version, so run it after the new assistant session begins. `--require` fails when the named capability is not verified; none of these checks proves that a model followed the advice.
 
-Instead:
+## See what Hunch contributed
 
-```text
-                  Hunch deterministic state
-                        ↑       ↓
-agent -> deterministic action gate -> connector -> source system
-```
+Task reports answer: what memory reached this task, what did the agent say it used, and what checks actually ran?
 
-Hunch may hold durable state **about** external work with credential-free provenance pointers, but should not mirror raw source-system contents into a universal cache.
+The normal agent instructions request a completion card with a link to a local evidence report. You can also inspect reports directly:
 
-The first real-world pilot is **Sofia**, a working operations agent over CRM, Gmail and WhatsApp. Sofia's approved actions, follow-ups, customer/source relationships and cited summaries map naturally to action receipts, commitments, entities/relationships and dependency-bound state.
+```bash
+hunch task list
+hunch report <task-id> --html
+```
 
-The pilot measures whether Sofia and a second, different agent stop re-deriving contradictory state when the deterministic state is delivered before they answer or act. First live number (2026-09-12, one user): after one CRM read, the next status questions were answered from held state under a receipt, 0 of 3 without a source; the [roadmap](ROADMAP.md) carries the gate table.
+A delivered lesson, an agent's claim, and a passing test are different evidence. Hunch keeps them separate. Automatic presentation depends on the host following the task lifecycle; missing evidence stays unverified. [Read the reporting guide](docs/task-reports.md).
 
-### The state contract, shipped
+## Share one living repository memory with your team
 
-As of 1.25.0 the contract exists as code: `nuryel.state/1` — three verbs (`read` under the
-delivery envelope's receipt, `write` with provenance and an idempotency key, `subscribe` to a
-strictly ordered change stream) over five new record facets: action receipts, commitments,
-derived state that names what it rests on, external entities and their relationships. Ids are
-derived from a record's facts, a replay returns the original, a second live decision on a topic is
-refused with the incumbent named, and derived state without dependencies is not state. Each scope
-keeps a git-native change ledger under `.hunch/changes/`; organization, team and user partitions
-are homed in an overlay, never in a repository. The MCP server binds it as `nuryel_capabilities`,
-`nuryel_read`, `nuryel_write` and `nuryel_subscribe`; every other transport will call the same
-store binding. Contract and evidence: [docs/nuryel-state-contract.md](docs/nuryel-state-contract.md).
+One maintainer connects a dedicated private Git repository:
 
-As of 1.26.0 the state layer is also **served**: `hunch serve --config <file>` hosts organization,
-team, user and repository partitions over HTTP on loopback with the same three verbs. A served
-partition is a directory whose `.hunch/partition.json` names the scope it is; the bearer token
-resolves the principal and grants come from the config only. `hunch serve init --partition
-user:david --root <dir> --principal sofia@david` declares a partition and mints a token. The typed
-client is `import { createStateClient } from "@davesheffer/hunch/state"`. This folds the separate
-Hunch Memory service into Hunch.
+```bash
+hunch shared --repo git@github.com:acme/project-hunch-memory.git
+git add .gitignore .hunch/team.json
+git commit -m "chore: connect shared Hunch memory"
+git push
+```
 
-As of 1.27.0 a fourth verb, `records`, lists a subject's records for the first writers, and the per-scope ledger compacts and merges across clones. As of 1.28.0 reads are a union across writers, a supersede target must still be open (two racing writers can no longer leave two current records), state records are searchable and delivered by subject, and subjects are keyed by the external record rather than by the agent. Proven on an emulated organization: three agents over ten clinics and a generated year of mail, chat and CRM, one organization drawer, 96 cited summaries, 24 verified receipts, 24 commitments, zero contradictions.
+Teammates install Hunch, pull the code, and run `hunch init`. Normal Git access controls the shared repository. Credentials, local clone paths, and private overlays stay out of the committed pointer. Use `hunch shared --sync` to retry synchronization; add `--no-auto-commit` when captures should wait for explicit sync.
 
-As of 1.30.0 subject identity is by external reference: one active entity per external record per partition, a subject written as an entity's external key refused with the entity id named, reads resolving one explicit hop — so two agents over one CRM record land on one subject. Replay determinism is a check, not a claim: `hunch serve replay --partition <kind:id>` (or `--root <dir>`) folds a partition's ledger into the state it implies and compares it hash for hash to the records on file, exits 1 on any divergence, runs inside `hunch drift` when the partition has a ledger, and runs on every agent-farm run; and a human correction outranks later agent writes — a record a human confirmed is never overwritten or superseded by an agent or service principal (replay, stale-with-cause and closure by receipt are the only agent moves, each keeping the human's provenance).
+This shares a project's engineering memory. The state server below adds authenticated access across multiple scopes.
 
-Read [Deterministic organizational state](docs/deterministic-state.md), the [roadmap](ROADMAP.md) and the dated [competitive landscape](docs/competitive-landscape.md).
+## Deterministic organizational state
 
-### Naming
+A coding agent needs to know why a module exists. An operations agent may need to know whether a customer action was completed or who owes the next follow-up. Both need a maintained record they can check.
 
-The product is still **Hunch**. A possible hosted-platform name, **Nuryel**, is intentionally deferred until the state contract and Sofia pilot have evidence. Rename work is not the deliverable.
+Hunch ships `hunch serve`: a self-hosted HTTP service for organization, team, user, and repository records. A configured identity determines which scopes an agent may access. Optional record audiences further restrict access; optional key-bound credentials require proof from the configured private key on each request.
 
-## Share one living repository memory with your team
+Open `/operator` on your server to inspect current records, completed work and commitments in a read-only browser view. Writer-supplied citations can point to an exact summary field or text passage and its recorded sources. They show traceability; they do not prove that a source supports a claim.
 
-The current release can keep a team's **repository-scoped** memory in a dedicated private Git repository, separate from the code.
+Agents can use the same contract through MCP, `hunch state read|write|records|subscribe`, the `@davesheffer/hunch/state` TypeScript client, or the [Python client](docs/python-state-client.md). The Python package is built and tested from this repository; it is not yet published to PyPI. [Scoped conventions](docs/scoped-conventions.md) let a person record sourced user, team or organization preferences. Those preferences remain advisory and do not silently become blocking rules.
 
-Today Hunch does not host that shared Git repository; teammates/CI use normal Git access and one maintainer connects it:
+Records can describe decisions, action outcomes, commitments, entities, relationships, and summaries that name their dependencies. Actions retain their status, including unknown or unverified outcomes. Repeated writes have stable identities, conflicting current decisions are refused, and confirmed human records receive protections against agent overwrites. These are defined checks on structured records; Hunch cannot establish every fact in the outside world on its own.
 
-```bash
-npm i -g @davesheffer/hunch@1.32.2
-hunch shared --repo git@github.com:acme/project-hunch-memory.git
-git add .gitignore .hunch/team.json
-git commit -m "chore: connect shared Hunch memory"
-git push
-```
+This is what **deterministic state** means here: explicit rules govern the stored record, rather than having each agent reconstruct it from scratch. Git holds the durable data; SQLite is a rebuildable index. The server binds to loopback and requires deployment and agent integration by its operator. Hunch does not provide a managed CRM or email connector service.
 
-Teammates then install the same version and run:
+[Set up and understand the state server](docs/deterministic-state.md) · [State contract and client reference](docs/nuryel-state-contract.md) · [Upgrade to 1.33](docs/upgrade-1.33.md)
 
-```bash
-npm i -g @davesheffer/hunch@1.32.2
-git pull
-hunch init
-hunch doctor
-```
+### The vision, and what is still being tested
 
-The committed pointer contains a credential-free repository locator and branch. Local clone paths, preferences and private overlays stay ignored. MCP sessions refresh shared memory at tool boundaries; failed pushes can be retried by later capture or `hunch shared --sync`.
+The vision is continuity across people, tools, and agents: an operations agent records a customer issue, a coding agent finds the relevant decision and fixes the cause, and the operations agent closes the commitment using evidence of the fix.
 
-Use `hunch firmness off` to pause hook enforcement without deleting history. Use `hunch shared --repo <url> --no-auto-commit` when captures should remain local until explicit `hunch shared --sync`.
+The underlying memory and state tools ship today. The broader claim—that different agents reliably use that shared state and avoid contradictory work—is still being measured in the Sofia pilot. Simulated results and a limited live pilot are not proof of that outcome across organizations. The [roadmap](ROADMAP.md) tracks the remaining acceptance gates.
 
-This existing Git-sharing feature is not the same thing as the planned organization/team/user state service. The roadmap extends the git-native model rather than declaring today's shared-memory repository to be an organization control plane.
+**Hunch remains the product name.** The `nuryel.state/1` protocol and `nuryel_*` tool names are existing technical identifiers; a possible future rename is undecided.
 
-## Trust boundaries that stay visible
+## Project DNA: help the agent understand how the project works
 
-- **Local-first today.** Repository Hunch works without a hosted service or telemetry. Git remains the repository-scoped authority.
-- **Hosted state is a roadmap extension, not a shipped claim.** Organization/team/user state will require authenticated scope/visibility, idempotency and durability while preserving git-native truth.
-- **Private when needed.** `hunch private --repo <url>` keeps sensitive repository reasoning in a separate overlay; public CI/documentation remain public-only.
-- **Human authority.** Observations, generated drafts, imported ADRs, discovered landscape records and proved policy candidates do not silently become trusted truth.
-- **Deterministic core.** Indexing, retrieval receipts, currentness, conformance, Project DNA discovery and policy evaluation do not require a model.
-- **Agents own execution.** Hunch state does not silently grant connector permissions, send messages or become a source-system proxy.
-- **No surprise synthesis bill.** Optional drafting can use a selected Claude Code, Codex or Cursor subscription CLI, a local OpenAI-compatible endpoint or deterministic fallback. Public remote endpoints require explicit opt-in.
-- **Traceable releases.** npm packages and the VS Code extension are content-addressed, verified against public registries and tied back to exact source tags.
+Project DNA describes observed repository conventions: terminology, contribution habits, review expectations, and engineering patterns. Engineering memory records decisions and their reasons. Both can inform a task, but frequent behavior does not become policy.
 
-## What changed after v1.19
+```bash
+hunch dna inspect
+hunch dna context
+hunch dna diff <older-ref> <newer-ref>
+```
 
-The v1.19 correction-search benchmark remains scoped evidence, but it no longer describes the whole product.
+Profiles retain their revision, sources, confidence, and freshness. [Project DNA contract](docs/project-dna.md) · [Broader DNA vision](docs/project-dna-engine.md)
 
-- **v1.20 — one validated path from reason to result.** Role-shaped context, reviewed Engineering Landscape fragments, exact change identity, PHP graph support and hash-bound ADR review moved source, provenance, currentness, omissions and human authority through one delivery contract.
-- **v1.21 — Project DNA.** Hunch gained deterministic, revision-specific repository profiles, bounded DNA context delivery, explainable Project Match checks and auditable profile deltas.
-- **v1.22 — authorized collaboration evidence.** Hosts can contribute bounded PR/review evidence to Project DNA through a typed, sealed contract without raw collaboration persistence or policy-authority change.
-- **v1.23 — native change proof and proof-carrying evidence work.** Exact Git change identity, graph before/after, decisions/constraints, blast radius and Change Gate result can be bound into a sealed evidence artifact without granting authority.
-- **v1.25 – v1.30 — the state layer.** `nuryel.state/1` as code, `hunch serve` partitions, union reads, subject identity by external reference, replay determinism, human corrections outranking agent writes.
-- **v1.32 — see what Hunch contributed.** Task contribution reports: what was delivered, what the agent reports it applied, what a rule verified, what a command observed; concise card, local evidence view.
+## Your data and your authority
 
-See the [changelog](CHANGELOG.md) for release detail and the [roadmap](ROADMAP.md) for active work.
+- Repository use is local-first and needs no hosted Hunch account. Shared memory uses Git access; the optional state server uses configured identities and grants.
+- `hunch private --repo <url>` keeps sensitive project reasoning in a private overlay. Public exports and CI should use public-only views.
+- Drafting can use a selected coding-assistant subscription, a local endpoint, or the deterministic fallback. Public metered endpoints require explicit opt-in. [Synthesis and billing](https://www.hunchmemory.com/docs#synthesis).
+- Agents keep responsibility for external actions and connector permissions. A stored record does not authorize an email, deployment, or CRM change.
+- npm and editor releases use separate publication gates with package integrity and provenance checks.
 
 ## Learn more
 
 - [Full documentation](https://www.hunchmemory.com/docs)
 - [Copy-paste cookbook](https://www.hunchmemory.com/cookbook)
-- [Turn PR review threads into scoped review rules](docs/review-memory.md)
-- [Keep agent launches with the initiating provider](docs/agent-origin.md)
+- [Task contribution reports](docs/task-reports.md)
 - [Deterministic organizational state](docs/deterministic-state.md)
 - [Project DNA](docs/project-dna.md)
 - [Native change proof](docs/change-proof.md)
-- [The autonomy ladder](docs/autonomy-ladder.md)
-- [Task contribution reports](docs/task-reports.md)
+- [Engineering Landscape](docs/engineering-landscape.md)
+- [Review memory](docs/review-memory.md)
+- [Agent-origin handling](docs/agent-origin.md)
+- [Autonomy ladder](docs/autonomy-ladder.md)
 - [Autonomous development](docs/autonomous-development.md)
-- [Local cookbook](docs/cookbook.md)
-- [Engineering Landscape Graph](docs/engineering-landscape.md)
-- [Hunch roadmap](ROADMAP.md)
+- [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md)
 - [VS Code extension](vscode-extension/README.md)
 - [Architecture benchmark](bench/architectural-conformance.md)
 - [Contributing](CONTRIBUTING.md)

package/dist/cli/index.js

@@ -26,6 +26,7 @@ import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { registerIntegrationCommands } from "./integrations.js";
 import { registerTaskReportCommands } from "./taskReport.js";
+import { registerStateCommands } from "./state.js";
 import { registerServeCommands } from "./serve.js";
 import { registerUpdateCommand } from "./update.js";
 import { registerReviewMemoryCommands } from "./reviewMemory.js";
@@ -164,6 +165,7 @@ registerIntegrationCommands(program, () => {
 });
 registerTaskReportCommands(program, () => { const { store, root } = storeFor(); return { store, root }; });
 registerServeCommands(program);
+registerStateCommands(program);
 registerUpdateCommand(program);
 registerReviewMemoryCommands(program, (records, repository, privateOnly) => {
     const { store, root } = storeFor();

package/dist/cli/integrations.js

@@ -26,11 +26,14 @@ export function registerIntegrationCommands(program, refreshGrounding) {
             process.exitCode = 1;
     });
     integrations.command("repair-pins")
-        .description("Align existing exact-version pins and refresh existing Hunch instructions; preserves other settings and does not enable hooks")
+        .description("Align pins, repair known Hunch launch commands and refresh instructions; preserves other settings and does not enable hooks")
         .action(() => {
         const root = findRoot();
         const files = repairIntegrationPins(root);
         console.log(files.length ? `Updated ${files.length} integration file(s): ${files.join(", ")}. Reconnect active MCP sessions.` : "Integration pins already aligned.");
+        if (files.includes(".codex/hooks.json")) {
+            console.log("Codex: open /hooks to review and trust the changed commands, then start a new session. Command changes require renewed trust; Hunch does not grant it automatically.");
+        }
         const grounding = refreshGrounding();
         if (grounding.length)
             console.log(`Updated Hunch instructions: ${grounding.join(", ")}. Reconnect the agent to load task reporting instructions.`);

package/dist/cli/serve.js

@@ -1,6 +1,8 @@
+import { readFileSync, statSync } from 'node:fs';
+import { proofPublicKey } from '../core/stateProof.js';
 import { resolve } from "node:path";
 import { createServeApp } from "../serve/app.js";
-import { initServeConfig, partitionFor, readServeConfig } from "../serve/config.js";
+import { initServeConfig, partitionFor, readServeConfig, writeServeConfig } from "../serve/config.js";
 import { compactLedger } from "../store/changeLedger.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { hunchPaths } from "../core/paths.js";
@@ -32,11 +34,23 @@ export function registerServeCommands(program) {
         // reverse proxy that terminates TLS and auth of its own. Folded-in decision from Hunch Memory.
         app.listen(port, "127.0.0.1", () => {
             console.log(`hunch ${HUNCH_VERSION} serving nuryel.state/1 on http://127.0.0.1:${port} — ${config.partitions.map((p) => scopePath(p.scope)).join(", ")} (${config.principals.length} principal(s))`);
+            console.log(`Shared state view: http://127.0.0.1:${port}/operator`);
         });
         const stop = () => { app.close(() => { app.closeStores(); process.exit(0); }); };
         process.on("SIGINT", stop);
         process.on("SIGTERM", stop);
     });
+    serve.command("revoke")
+        .description("Revoke a principal credential; current servers reload the config before each request")
+        .requiredOption("--principal <id>", "principal whose credential to revoke")
+        .action((opts) => {
+        const { file, ...config } = readServeConfig(resolve(serve.opts().config ?? DEFAULT_CONFIG));
+        if (!config.principals.some(p => p.id === opts.principal))
+            throw new Error('principal is not configured');
+        config.principals = config.principals.filter(p => p.id !== opts.principal);
+        writeServeConfig(file, config);
+        console.log(JSON.stringify({ revoked: opts.principal }));
+    });
     serve.command("compact")
         .description("Compact a served partition's change ledger: keep the newest N events, move the floor up; subscribers below the floor resynchronize")
         .requiredOption("--partition <kind:id>", "the partition whose ledger to compact")
@@ -105,6 +119,8 @@ export function registerServeCommands(program) {
         .requiredOption("--root <dir>", "directory whose .hunch/ holds the partition (created if missing)")
         .option("--config <file>", `serve config to create or extend; default ${DEFAULT_CONFIG}`)
         .option("--principal <id>", "principal to add or rotate, granted this partition")
+        .option("--proof-key-file <file>", "bind this token to an Ed25519 public PEM or JWK key")
+        .option("--public-origin <origin>", "external HTTPS origin of the reverse proxy; required for key-bound tokens")
         .option("--kind <kind>", "principal kind: human | agent | service", "agent")
         .option("--grant <kind:id...>", "additional partitions to grant the principal (must be served by this config)")
         .option("--port <n>", "port to record in a new config")
@@ -120,10 +136,20 @@ export function registerServeCommands(program) {
         const port = parent.port ?? opts.port;
         const scope = parseScopeArg(opts.partition);
         const grants = [scope, ...(opts.grant ?? []).map(parseScopeArg)];
+        let proofKey;
+        if (opts.proofKeyFile) {
+            if (!opts.principal)
+                throw new Error('--proof-key-file requires --principal');
+            const stat = statSync(opts.proofKeyFile);
+            if (!stat.isFile() || stat.size > 8192)
+                throw new Error('public proof key must be a regular file of at most 8 KiB');
+            proofKey = proofPublicKey(readFileSync(opts.proofKeyFile, 'utf8'));
+        }
         const result = initServeConfig({
             file: configFile, scope, root: resolve(opts.root),
-            ...(opts.principal ? { principal: { id: opts.principal, kind: opts.kind, grants } } : {}),
+            ...(opts.principal ? { principal: { id: opts.principal, kind: opts.kind, grants, proofKey } } : {}),
             ...(port ? { port: Number(port) } : {}),
+            ...(opts.publicOrigin ? { publicOrigin: opts.publicOrigin } : {}),
         });
         if (opts.json) {
             console.log(JSON.stringify({ config: configFile, partition: result.partition, token: result.token }));

package/dist/cli/state.d.ts

@@ -0,0 +1,3 @@
+/** JSON CLI over the existing HTTP client. The server owns authorization and state rules. */
+import type { Command } from 'commander';
+export declare function registerStateCommands(program: Command): void;