daftari 1.29.0 → 1.31.0

package/CHANGELOG.md

@@ -7,6 +7,286 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.31.0] - 2026-07-22
+
+The self-hosted deployment release: one always-on `daftari serve` instance
+over Streamable HTTP with per-session identity (static tokens and/or OAuth
+2.1), plus durable object-storage backing (S3/Azure/GCS-interop) behind the
+canonical local git working copy. Design record:
+`docs/superpowers/specs/2026-07-20-self-hosted-server-mode-design.md`.
+
+### Added
+
+- **`daftari serve` — server mode over Streamable HTTP (#5).** One always-on
+  instance, many MCP clients, per-session RBAC identity resolved at session
+  open (zero tool changes — every existence-disclosure invariant applies per
+  connection). Static bearer tokens declared in config with values in env
+  vars. Fail-loud posture throughout: a non-loopback bind refuses without
+  auth AND an explicit `server.transport_security: external` declaration
+  (daftari never terminates TLS); with auth configured a bad credential is a
+  401 at session open, never a guest downgrade; loopback binds carry a
+  DNS-rebinding guard (Host/Origin validated before routing). The process
+  lock learns modes: a stray stdio invocation refuses against a live server,
+  a new serve refuses against any live holder, and deliberate replacement is
+  `daftari serve --takeover` (stdio-vs-stdio keeps its classic takeover;
+  stale locks are still overwritten silently).
+- **OAuth 2.1 resource-server auth for serve (#7).** Bearer JWTs verified
+  against your IdP's JWKS (issuer + audience + signature + expiry via
+  `jose`), with the subject claim mapped through a config-declared subjects
+  table. A valid token with an unmapped subject is 403 — authenticated, not
+  authorized — never a guest, never a default role. Composes with static
+  tokens (agents on tokens, humans through the IdP). Hardened: https-only
+  issuer/JWKS URLs (loopback http for test IdPs only), constant-time static
+  token matching, `Object.prototype`-collision-proof subject lookup.
+- **Pluggable storage backends as sync targets (#6).** The local git working
+  copy stays canonical; a backend is a dumb `get/put/list/delete` target.
+  Backends: `fs` (local/mounted directory), `s3` (S3, MinIO, R2, GCS via its
+  S3-interop endpoint), `azure` (Blob/ADLS Gen2) — cloud SDKs are optional
+  peer dependencies loaded on demand, credentials come only from the SDKs'
+  environment chains, custom endpoints must be https. `daftari sync` pushes
+  incrementally against a remote hash manifest (tree + `.git` + durable
+  `.daftari` journals; the rebuildable index/locks never sync) and
+  `daftari sync --restore` rebuilds a vault into an empty directory with
+  per-object hash verification and a reindex. `daftari serve` can push on a
+  cadence (`storage.sync_interval_minutes`). Security posture: `.git/config`
+  and `.git/hooks` are never synced or restored (git executes what they
+  declare — a backup channel must not deliver code), and restore re-enforces
+  every exclusion against the untrusted manifest.
+- **Agent-as-judge rerank pool on `vault_search` (#3).** Opt-in
+  `rerank_candidates`: the server prepares the fused candidate pool and the
+  protocol; the calling agent is the judge.
+- **Per-document theme distributions (#58).** True multi-theme membership via
+  chunk-level clustering.
+- **Configurable tool-exposure tiers (#103, #104).** `tools.tier`
+  (`core`/`standard`/`full`) plus `include`/`exclude` lists in config.
+- **Resumable reindex (#54).** Per-batch embedding commits so an interrupted
+  reindex resumes instead of restarting.
+- **`daftari eval prune` (#100)** — `results/` and `scores/` housekeeping —
+  and eval v1 polish (#102): honest exit codes, skipped-run reporting, resume
+  validation, tier-aware triviality, intra-call dedupe, `--max-nodes`.
+- **Advisory domain-boundary enforcement (#4)** and inline structural decay
+  checks (orphans, deprecated-still-linked) in the curation engine.
+- **Advisory supersede nudge** when overwriting an existing doc, and a YAML
+  config error hint for comment lines that lost their `#`.
+- **`daftari okf export|import` — Open Knowledge Format bridge.** OKF is Google
+  Cloud's vendor-neutral spec (v0.1) for the LLM-wiki pattern — a directory of
+  markdown files with YAML frontmatter — which is exactly Daftari's storage
+  model. `okf export` renders a vault as a portable OKF bundle: each doc becomes
+  an OKF concept doc carrying the core `type` / `title` / `description` /
+  `resource` / `tags` / `timestamp` fields plus a verbatim `daftari` sidecar for
+  lossless round-trip, alongside generated `index.md` and `log.md` reserved
+  files; the source vault is never mutated. `okf import` adopts an OKF bundle
+  into a vault — a bundle from `okf export` round-trips exactly via its sidecar,
+  while a foreign bundle is mapped conservatively (docs land as `draft` in the
+  `accumulation` domain, the source OKF `type` preserved in `okf_type`); writes
+  auto-commit and the index is rebuilt. `--dry-run` previews the import plan.
+
+- **The compilation pipeline (#232–#236, #141, #217).** Edge provenance
+  classes with type-directed change dispatch (tier 1), structure-first tier-0
+  lint checks with a ratify gate, a semantic-review queue with typed verdicts
+  (tier 2), the compiled `consumes` dependency graph (run-correlated reads ×
+  writes, #233), edge staleness classes and the broken-read rate (#234),
+  proposal deltas (write action type, `run_id` provenance, inter-proposal
+  tension, a propose-only role, #235), write-protection tiers
+  (source/compiled/manual with a demote-then-write escape hatch, #141), a
+  review-throughput lint aggregate, and edge-graph existence disclosure
+  (blast B′, edges/lint omission) extending the 2026-07-14 RBAC spec (#217).
+- **`sleep` tension-scan dream-type (#228)** closing the day-0 detection gap,
+  a langgraph-store adapter with the dedup-is-not-epistemics demo (#227),
+  the daftari.dev landing page (#226), and MCP Registry metadata (#222).
+- **Dev maturity (#238–#242):** e2e gate on the built server, tag-driven npm
+  release via OIDC trusted publishing, automated code + security review on
+  PRs, an `@claude` mention responder, and a nightly maintenance loop.
+
+### Fixed
+
+- Canonical-path tension/provenance gates in `vault_status`, `vault_receipt`,
+  and precedent lookups (#216), and tier-1 anchors that are unreadable leak
+  neither provenance metadata nor existence (#252).
+- `daftari audit` no longer flags on-disk assets and unaudited siblings as
+  missing (#255); eval exit codes and resume validation honesty (#102).
+
+### Performance
+
+- SQL-authoritative edge reads with write-through and stat-marker self-heal
+  (#236), FTS5 `snippet()` for lexical excerpts on the chunk path, and the
+  file watcher filters non-markdown events at watch time (#107).
+
+## [1.30.0] - 2026-07-13
+
+### Added
+
+- **`vault_receipt` — the epistemic receipt.** A new read-only MCP tool that
+  compiles, for the set of documents an answer cites, a single attachable
+  artifact: per-source status / confidence / provenance / freshness (decay),
+  the exact content-version hash, a filesystem-walked resolution of the
+  supersession chain (`resolved` / `restricted` / `dangling` / `cycle`), and
+  every unresolved tension touching the source — plus a deterministic summary
+  (`byStatus`, `openTensions`, oldest/newest `updated`, sorted
+  machine-readable flags such as `cites-stale`, `cites-contested`,
+  `cites-superseded`, `supersession-unresolved`; empty flags mean current,
+  grounded, and uncontested), the vault's git HEAD as an as-of anchor, and a
+  recomputable SHA-256 over the whole receipt. Discipline: the receipt only
+  reads (frontmatter, tension log, git); flags are deterministic derivations;
+  the optional caller-supplied `claim` rides verbatim and is never
+  interpolated into Daftari-authored text. RBAC mirrors the read path: a
+  receipt over an unreadable collection is denied, an unreadable supersession
+  hop degrades to `restricted`, and a tension is visible only when both
+  sources' collections are readable (the `vault_status` precedent). README
+  tool list updated to the full 26-tool surface (the "14 tools" count
+  predated the edge / staged-action / tension-graph tools).
+
+- **`daftari asof` — belief archaeology.** A read-only CLI report over the
+  vault's git history: `daftari asof <ref-or-date>` resolves a git ref or a
+  `YYYY-MM-DD` date (the last commit on or before that day) and reports the
+  vault's belief state at that point plus the drift since — documents
+  added/removed, `status`/`confidence` transitions, body-change counts, and
+  tensions opened or resolved (the committed `.daftari/tensions.md` is parsed
+  at both points with the live parser via the newly exported
+  `parseTensionLog`). `--doc <path>` adds a single-document trajectory
+  (frontmatter then vs now, every commit touching it since); `--blast <path>`
+  adds a **counterfactual replay** — the blast radius of the document
+  computed over the tree *as of the commit* (reusing `computeBlast` and the
+  reverse source/link maps from `vault_tension_blast`), each downstream
+  document annotated with its status today ("this fact turned out wrong — who
+  had inherited it, and where are they now?"). Strictly read-only plumbing:
+  `git ls-tree` + one `git cat-file --batch` process for the whole historical
+  tree — no checkout, no worktree, no index, no API key. Historical trees are
+  filtered with the live loader's exclusion rules (dotfiles, `.daftari/`,
+  `node_modules`, `.obsidian/`, `.trash/`) so then/now diffs can't report
+  phantom drift. Markdown to stdout, `--output` / `--output-json` to files;
+  audit-convention exit codes (0 report, 2 config/usage, 3 runtime). Pairs
+  with `vault_receipt`: a receipt's `vaultHead` is the anchor to hand back to
+  `asof`.
+
+- **`daftari court` — the Tension Court.** Common-law memory over the
+  tension log. `daftari court` compiles a **docket**: every open tension
+  briefed and ranked by priority (aging tier stale→fresh, then blast size,
+  then age) — both sides' claims verbatim with the present status and decay
+  of their documents ("gone" when a side was deleted), the union blast
+  radius a ruling would settle (reusing `computeBlast` and the
+  reverse-source/link maps from `vault_tension_blast`), tension-cluster
+  membership, and **precedents**: past rulings retrieved by a deterministic
+  three-tier match (shared-document > collection-pair > same-kind; newest
+  first within a tier, capped at 3, no LLM). `--tension <id>` renders a
+  single case's full brief including precedent rationales verbatim.
+  `daftari court rule <id> --kind superseded|corrected|accepted|invalid
+  [--rationale …] [--references …] [--by …]` records the ruling through the
+  same `resolveTension` write path as `vault_tension_resolve`; the rationale
+  is recorded verbatim and cited by future dockets — a ruling is precedent
+  the moment it lands, because a precedent IS a resolved tension. The court
+  retrieves and briefs; it never decides, and a ruling never edits the
+  disputed documents. Markdown to stdout, `--output` / `--output-json`;
+  audit-convention exit codes (0/2/3).
+
+- **`daftari sleep` — circadian memory** (positioning idea 6, gate cleared by
+  the CB7 result). A nightly metabolic pass composing machinery that already
+  exists — deterministic, LLM-free, and write-free with respect to documents:
+  sweeps expired staged actions, scores every document's decay, and builds
+  the **wake list** (canonical accumulation docs past TTL with downstream
+  dependents, ranked by blast radius via the `vault_tension_blast` reverse
+  maps), written to a gitignored `.daftari/wake-queue.jsonl` snapshot for an
+  external agent to re-verify against sources — the vault never re-verifies
+  on its own. The domain split is honored: generative docs going stale are
+  expected — counted, never woken; expired docs with no dependents are
+  reported as quiet decay, not woken. The **Morning Report** surfaces tension
+  aging and the court docket head, the ratification queue with
+  soon-to-expire proposals, and the rubber-stamp monitor (zero rejections
+  over ≥10 decisions prints a warning — the circadian design's kill-condition
+  instrumentation). Scheduling stays the OS's job (cron example in
+  `--help`); daftari ships the cycle, not a daemon. Markdown to stdout,
+  `--output` / `--output-json`, `--wake-limit` (report rows only — the queue
+  always carries the full list, no silent caps), `--no-queue`;
+  audit-convention exit codes. `.daftari/wake-queue.jsonl` added to the vault
+  gitignore template.
+
+- **`vault_witness` — agent track records + the wager layer** (positioning
+  ideas 4 and 9, gate cleared by the CB7 result). A read-only MCP tool that
+  aggregates the vault's own ledgers — provenance log, tension log, staged
+  actions — into a per-principal track record, priced by a provisional,
+  exported wager schedule (`low` 0 / `medium` 1 / `high` 3; survival credit
+  1; gone-doc burn 1 — calibration constants, like the §11.5 impact table).
+  Per principal: write volume and span (the longitudinal series for idea 9's
+  kill condition), docs authored (first provenance entry wins; authenticated
+  `principal` outranks the free-text `agent` claim), live claims with open
+  exposure, contested claims with stake at risk, the settled book (claims
+  corrected by ruling, retired, or deleted burn their stake; claims
+  maintained through a full TTL cycle earn credit; `balance` is the
+  difference), proposal outcomes, and tensions logged. Includes the
+  flat-curve monitor (idea 4's kill condition): one principal at ≥95% of
+  writes flags the records as uninformative instead of reporting them as
+  signal. RBAC follows the `vault_status` precedent — everything is scoped
+  to readable collections. Advisory and deterministic; nothing is enforced,
+  no document is touched, edge-observer attribution is deferred (the edge
+  log's collapse keeps observers internal). Tool surface is now 27.
+
+- **`vault_search` hits carry unresolved tensions inline** (`contested` /
+  `contestedCount`). Each annotation is the full two-sided marker — both
+  claims, kind, counterpart, tension id — post-joined from
+  `.daftari/tensions.md` in the same enrichment pass as `currentSource`,
+  capped at 3 per hit with an honest total. RBAC-gated on the counterpart's
+  collection (unreadable ⇒ omitted entirely, and excluded from the count).
+  Measured motivation: the tension-graph feud benchmark (2026-07-04) — on
+  feuds where retrieval buries one side, agents surface the contradiction
+  ~8% baseline vs ~46% with the tension inline; the dedicated-tool shape
+  loses to inline across all panel models. Tensions remain advisory and
+  never affect ranking.
+
+- **OpenRouter LLM transport for `daftari consolidate`** (`--transport
+  anthropic|openrouter`, env fallback `DAFTARI_LLM_TRANSPORT`). A second
+  model-family client (`createOpenRouterClient`) implementing the same
+  `LlmClient` contract as the Anthropic client, promoted from the
+  decorrelation shim. On the openrouter transport the CLI gates on
+  `OPENROUTER_API_KEY` (not `ANTHROPIC_API_KEY`), defaults the model to
+  `anthropic/claude-haiku-4.5`, and accepts any OpenRouter slug via `--model`.
+  This is the substrate for the Stage-5 multi-model graduation gate (spec §12
+  amendment, 2026-07-02): single-family panel votes are ~92% error-correlated,
+  so `k_survived` needs a second model family before any auto-write tier can
+  graduate. `completeWithTools` is deliberately unsupported on this transport
+  (only `daftari eval` drives tools; eval stays on anthropic).
+
+### Security
+
+- **Tension tools now enforce the both-sides visibility rule** (#212).
+  `vault_tension_clusters` and `vault_tension_blast` compute over only the
+  tensions whose BOTH sides the caller can read — filtered before
+  aggregation, so counts, cluster sizes, and blast seeds reveal nothing
+  about hidden entries. `vault_tension_log` refuses to record claims naming
+  a document the caller cannot read (denial names the caller-supplied path
+  only); `vault_tension_resolve` returns the exact not-found error for
+  invisible tensions, checked before the loop-authored ratify rule. This
+  closes the bypass around #211's contested-annotation gate: one rule
+  (`collectionForPath` + `canSeeTension`) now governs every tension
+  surface. No-RBAC deployments are unaffected. Known residual (accepted):
+  sequential tension ids still reveal the total entry count to callers who
+  can log. A follow-up consolidation (`sourceReadable`, exported from
+  `tension-access.ts`) then unified the canonicalize → reject-escape →
+  `canRead` sequence into a single predicate adopted by all four call
+  sites — the tension log/blast gates above and #211's contested-annotation
+  filter in `contested.ts` — so one guard now backs every tension-graph tool surface,
+  including contested annotations on `vault_search` hits. Further
+  residuals (accepted, tracked in follow-ups): `vault_status` /
+  `vault_receipt` / court-precedent tension summaries still filter by
+  uncanonicalized top-level segment, and `vault_lint`'s tension-health
+  aggregates count all entries (counts only, no content).
+
+### Internal
+
+- **CB7 decision-divergence bench** (`integrations/consensus-bench`,
+  benchmark tooling only). Implements the
+  2026-07-11 CB7 design: instance assembly from existing artifacts (CB6
+  tension pairs, CO2 stale-trap diffs, consensus-box supersession chains as
+  settled controls — CB6 tension items excluded from the control set),
+  condition renderer with locked validity invariants (task text
+  byte-identical across memory conditions; the collapsed block carries one
+  value and no epistemic language; settled controls give the foil the
+  governing value), deterministic enum scorer (divergence, calibration,
+  hedge tax — no LLM judge on primary metrics), and `cb7-runner.mjs` for the
+  live panel run (`--gate` mode runs the second-rater leakage check).
+  M-collapsed for tensions holds the challenger position (recency /
+  last-write-wins) rather than the spec's CB6-foil-verdict, a deterministic
+  deviation recorded in the module.
+
 ## [1.29.0] - 2026-06-25
 
 ### Changed
@@ -1202,6 +1482,7 @@ vault to AI agents, exposing 13 tools over stdio.
   example documents, git history, search index); `daftari --vault` serves it.
 - 160 tests covering all 13 tools and their supporting modules.
 
+[1.31.0]: https://github.com/mavaali/daftari/releases/tag/v1.31.0
 [1.5.1]: https://github.com/mavaali/daftari/releases/tag/v1.5.1
 [1.4.0]: https://github.com/mavaali/daftari/releases/tag/v1.4.0
 [1.1.1]: https://github.com/mavaali/daftari/releases/tag/v1.1.1

package/README.md

@@ -56,7 +56,7 @@ compiles; the vault preserves; *you* keep the judgment. See
 
 ## What it is
 
-A directory of markdown files with YAML frontmatter, exposed to agents as 14
+A directory of markdown files with YAML frontmatter, exposed to agents as 27
 MCP tools over stdio. The vault is plain text: you can read it in any editor,
 `git log` it, grep it. Daftari adds the machinery agents need to treat it as a
 shared workspace.
@@ -70,7 +70,10 @@ Point any MCP client (Claude Desktop, Claude Code, an agent SDK) at it.
 
 ## The four layers
 
-Storage and access control are table stakes. The moat is layers 3 and 4.
+All four implement one idea — *resolve only by discovery, never by invention.*
+Read [**The core idea**](docs/architecture.md#the-core-idea) first and the layers
+become its consequences. Storage and access control are table stakes; the moat is
+layers 3 and 4.
 
 |Layer                |What it does                                                                                          |Why it matters                                                         |
 |---------------------|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
@@ -83,16 +86,61 @@ Storage and access control are table stakes. The moat is layers 3 and 4.
 
 **Read:** `vault_read`, `vault_index`, `vault_status`
 
-**Search:** `vault_search` (hybrid BM25 + vector), `vault_search_related`, `vault_themes` (thematic clustering), `vault_reindex`
+**Attest:** `vault_receipt` — compile an epistemic receipt for the documents
+an answer cites: per-source status, confidence, provenance, freshness, exact
+content-version hash, supersession-chain resolution, and open tensions, plus
+deterministic summary flags, the vault's git HEAD as an as-of anchor, and a
+recomputable hash over the whole receipt. Attach it to the answer so any
+consumer can see what the answer stands on.
 
-**Write:** `vault_write`, `vault_append`, `vault_promote`, `vault_deprecate`
+**Witness:** `vault_witness` — per-principal track records from the vault's
+own ledgers, priced by the wager schedule: write volume, live claims with
+open exposure, contested claims with stake at risk, the settled book
+(burned vs credited), proposal outcomes, tensions logged. Advisory and
+deterministic; includes the flat-curve monitor so a single-author vault is
+reported as uninformative rather than as signal.
 
-**Curate:** `vault_tension_log`, `vault_lint`, `vault_provenance`
+**Search:** `vault_search` (hybrid BM25 + vector; hits carry their unresolved
+tensions inline and foreground the current source of superseded documents),
+`vault_search_related`, `vault_themes` (thematic clustering), `vault_reindex`
+
+**Write:** `vault_write`, `vault_append`, `vault_promote`, `vault_deprecate`, `vault_supersede`, `vault_merge`, `vault_set_confidence`
+
+**Curate:** `vault_tension_log`, `vault_tension_resolve`, `vault_tension_clusters`, `vault_tension_blast`, `vault_lint`, `vault_provenance`
+
+**Edges:** `vault_edge_observe`, `vault_edge_contest`, `vault_edges`
+
+**Ratify:** `vault_stage_action`, `vault_ratify`
 
 The curation engine is advisory: `vault_lint` reports problems and
 `vault_tension_log` records contradictions. Neither auto-fixes anything. Every
 change is a deliberate, attributable act.
 
+### Tool tiers
+
+Every advertised tool costs the agent context tokens and a decision branch.
+The `tools` block in `.daftari/config.yaml` picks how much of the registry
+`tools/list` advertises:
+
+```yaml
+tools:
+  tier: standard   # core | standard | full (default: full)
+  include:         # add tools the tier omits
+    - vault_tension_log
+  exclude:         # remove tools the tier includes — exclude wins
+    - vault_status
+```
+
+`core` is the search-before-derive loop (`vault_search`, `vault_read`,
+`vault_write`, `vault_index`, `vault_lint`, `vault_status`); `standard` adds
+the full document lifecycle (append/promote/deprecate/supersede/merge,
+confidence and tier setters, propose/ratify) plus diagnostics; `full` is
+everything. `--tools <tier>` overrides the tier for one invocation. Filtering
+only changes what is *advertised* — calls to any registered tool still work,
+so an agent holding a cached tool name keeps working across a tier change.
+Unknown names in `include`/`exclude` warn at startup and are ignored, so a
+config written for a newer daftari still loads.
+
 **Evaluate (opt-in, requires an Anthropic API key):** `daftari eval` — scores how
 well an LLM can use the curation surface to answer multi-hop questions about the
 vault. See the [design spec](docs/superpowers/specs/2026-05-31-cortex-quality-metric-design.md)
@@ -220,6 +268,110 @@ daftari backfill --plan
 daftari backfill --apply --scope specs
 ```
 
+## Open Knowledge Format (OKF)
+
+[OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
+is Google Cloud's vendor-neutral spec (v0.1) for the LLM-wiki pattern: a
+directory of markdown files with YAML frontmatter that any producer can emit and
+any consumer can read without translation. A Daftari vault *is* that pattern, so
+`daftari okf` bridges the two directions.
+
+**Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
+concept doc (the core `type` / `title` / `description` / `resource` / `tags` /
+`timestamp` fields, plus a verbatim `daftari` sidecar for lossless round-trip),
+with generated `index.md` (progressive-disclosure listing) and `log.md`
+(chronological history). The source vault is never mutated.
+
+```bash
+daftari okf export ./my-vault --out ./okf-bundle
+daftari okf export ./my-vault --out ./okf-bundle --collection pricing
+```
+
+**Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
+round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
+(docs land as `draft` in the `accumulation` domain, the original OKF `type` is
+preserved in an `okf_type` field). Writes auto-commit and the index is rebuilt.
+
+```bash
+daftari okf import ./okf-bundle --into ./my-vault --dry-run
+daftari okf import ./okf-bundle --into ./my-vault
+```
+
+## Server mode (self-hosted)
+
+By default daftari is a per-user stdio process. `daftari serve` starts the
+same vault as **one always-on instance over Streamable HTTP** — for a team, or
+for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
+
+```bash
+daftari serve --vault ./my-vault              # http://127.0.0.1:8787/mcp
+daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
+```
+
+Identity is **per MCP session**, resolved when the session opens, so every
+RBAC and existence-disclosure rule applies per connection with zero tool
+changes. Two composable auth schemes, both declared in config:
+
+```yaml
+server:
+  transport_security: external   # required off-loopback: TLS terminates upstream
+  auth:
+    tokens:                      # static bearer tokens (agents, ETL)
+      - env: DAFTARI_TOKEN_ETL   # the VALUE lives in this env var, never in config
+        user: agent:etl
+        role: admin
+    oauth:                       # OAuth 2.1 resource server (humans via your IdP)
+      issuer: https://idp.example.com
+      audience: daftari
+      jwks_uri: https://idp.example.com/.well-known/jwks.json
+      subjects:
+        "alice@example.com": { user: human:alice, role: analyst }
+```
+
+The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
+to start without auth **and** the explicit `transport_security: external`
+acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
+balancer in front); with any auth configured, a bad or missing credential is
+a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
+neither ever becomes the guest. Guest sessions exist only in the no-auth
+loopback configuration. A running server also refuses to be silently killed:
+stray stdio invocations against the same vault refuse to start, and replacing
+a live holder requires a deliberate `daftari serve --takeover`.
+
+## Storage backing
+
+A self-hosted vault can push to durable object storage (#6). The local git
+working copy stays canonical — reads, writes, auto-commits, locks, and the
+index all stay exactly as above — and the backing is a dumb sync target:
+
+```yaml
+# .daftari/config.yaml
+storage:
+  backend: s3            # fs | s3 | azure
+  bucket: team-vault
+  region: us-east-1
+  # endpoint: https://…  # MinIO / R2 / GCS S3-interop endpoints
+  # sync_interval_minutes: 15   # daftari serve pushes on this cadence
+```
+
+```bash
+daftari sync --vault ./my-vault              # incremental push
+daftari sync --vault ./my-vault --dry-run    # show the diff only
+daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
+```
+
+The push covers the markdown tree, the `.git` directory, and durable
+`.daftari` journals; the rebuildable SQLite index and lock files never sync.
+Neither do `.git/config` and `.git/hooks` — git *executes* what those
+declare, and a backup channel must not deliver code (`git clone` refuses to
+transmit them for the same reason), so re-add remotes and local git config
+by hand after a restore.
+Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
+as optional dependencies — install the one you use; credentials come from the
+SDK's standard environment chain, never from vault config. GCS is reached via
+its S3-interoperability endpoint. Restore refuses non-empty directories and
+reindexes when done.
+
 ## How it compares
 
 |                    |AGENTS.md        |RAG                          |Daftari                              |
@@ -234,12 +386,18 @@ daftari backfill --apply --scope specs
 
 Deliberately deferred to keep the surface tight:
 
-- **Cloud-hosted multi-tenant server** with S3/GCS backend and token auth
-- **Remote MCP transport** for claude.ai web, mobile, and Cowork (v1 is a local desktop extension for Claude Desktop and Claude Code)
+- **Cloud-hosted multi-tenant SaaS** (self-hosted server mode HAS shipped —
+  see [Server mode](#server-mode-self-hosted) and
+  [Storage backing](#storage-backing); the project itself hosts nothing)
 - **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
 - **Background curation agent** running lint on a cadence
-- **LLM reranking** of search results
-- **Enforced domain separation** (v1 documents the convention; v2 enforces it)
+- **Enforced domain separation** (v1 documents the convention; v2 enforces it —
+  advisory boundary warnings shipped in the meantime: `vault_lint`'s
+  `domainLeaks` check and write-time `domain_warnings`)
+
+(LLM reranking, deferred here originally, has since shipped as the opt-in
+agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
+fused candidate pool and the protocol; the calling agent is the judge.)
 
 Each is a clean increment on a surface that already works.
 
@@ -402,6 +560,102 @@ fail_on:
   transitive_staleness: 100          # default: generous; teams tune
 ```
 
+## The vault as witness — and the wager layer
+
+Every write already carries an identity, every proposal an outcome, every
+tension a logger and a ruling. `vault_witness` aggregates that ledger into a
+**track record per principal** — and prices it. Confidence is free to claim,
+so the wager schedule makes it cost something: writing at `high` stakes 3
+points, `medium` 1, `low` 0 (hedged claims are the honest default and are
+never taxed). A claim later corrected by a ruling or retired by someone else
+burns the stake; a claim maintained through a full TTL cycle earns credit.
+The balance is arithmetic on recorded facts — advisory, provisional
+constants, nothing enforced: routing a high-stakes write to the agent with
+the earned balance is your policy, not the vault's. Both kill conditions
+from the design travel with the tool: the flat-curve monitor (one author ≥95%
+of writes → curves declared uninformative) and the longitudinal write-volume
+series (if stake-fear suppresses honest claims, it shows up here first).
+
+## Circadian memory
+
+The vault sleeps. `daftari sleep` is the nightly metabolic pass — deterministic,
+LLM-free, write-free (documents are never touched):
+
+```bash
+# In cron (any scheduler works; daftari ships the cycle, not a daemon):
+0 3 * * * cd /path/to/vault && npx daftari sleep --output .daftari/morning-report.md
+```
+
+The cycle sweeps expired staged actions, scores every document's decay, and
+builds the **wake list**: canonical accumulation documents past their TTL
+with downstream dependents, ranked by blast radius. The list is written to
+`.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
+document against its sources, stage the diff — because the vault never
+re-verifies on its own. Generative documents going stale are expected, not a
+defect: counted, never woken.
+
+The **Morning Report** ends where the human begins: tension aging and the
+court docket head, the ratification queue with soon-to-expire proposals, and
+the rubber-stamp monitor — zero rejections over a long decision history is
+printed as a warning, not a compliment. The agent proposes overnight; you
+ratify over coffee.
+
+## Tension Court
+
+Tensions wait in a log; the court turns them into decidable cases. `daftari
+court` compiles a **docket** — every open tension briefed and ranked (stale
+first, then by blast radius): both sides' claims, the present state of their
+documents, the downstream stakes, cluster membership, and **precedents** —
+past rulings on disputes that shared a document, a collection pair, or a
+kind.
+
+```bash
+# The docket — a 5-minute weekly ritual
+daftari court --vault ./my-vault
+
+# One case's full brief (verbatim rationales from cited precedents)
+daftari court --tension tension-abc123
+
+# Rule. The rationale is recorded verbatim and cited by future dockets.
+daftari court rule tension-abc123 --kind corrected \
+  --rationale "Vendor pricing page confirmed the entry tier on 2026-07-10."
+```
+
+Rulings go through the same `resolveTension` write path as
+`vault_tension_resolve` — a ruling records the closure, it never edits the
+disputed documents. Precedent retrieval is deterministic (shared-document >
+collection-pair > same-kind; no LLM): the court retrieves how this house has
+resolved similar disputes before, and whether a precedent applies stays the
+human's judgment. Memory grows case law.
+
+## Belief archaeology
+
+Git is the version layer, so the vault can answer **"what did we believe on
+March 3?"** `daftari asof` is a read-only report over the repo's history — no
+checkout, no index, no API key:
+
+```bash
+# The vault's belief state at a date (or any git ref), plus the drift since
+daftari asof 2026-03-03 --vault ./my-vault
+
+# One document's trajectory: frontmatter then vs now, commits in between
+daftari asof HEAD~20 --doc pricing/helios-consumption-pricing.md
+
+# Counterfactual replay: this fact turned out wrong — who had inherited it
+# at the time, and where are they now?
+daftari asof 2026-03-03 --blast pricing/helios-consumption-pricing.md
+```
+
+The default report shows the document and tension state at that point and
+the drift since: documents added/removed, `status`/`confidence` transitions,
+and tensions opened or resolved. `--blast` computes the blast radius of a
+document over the tree *as of the commit* (same source/link edge semantics as
+`vault_tension_blast`), annotating each downstream document with its status
+today — the post-mortem view for a fact that was later corrected. Markdown to
+stdout by default; `--output` / `--output-json` write files. Pairs with
+`vault_receipt`: a receipt's `vaultHead` is exactly the anchor to hand back
+to `asof`.
+
 ## Development
 
 ```

package/dist/access/rbac.d.ts

@@ -12,6 +12,7 @@ export declare function canRead(role: RoleConfig | null, collection: string): bo
 export declare function canWrite(role: RoleConfig | null, collection: string): boolean;
 export declare function canPromote(role: RoleConfig | null): boolean;
 export declare function canRatify(role: RoleConfig | null): boolean;
+export declare function isProposeOnly(role: RoleConfig | null): boolean;
 export declare function hasAnyRead(role: RoleConfig | null): boolean;
 export declare function filterByReadPermission<T extends {
     collection: string;

package/dist/access/rbac.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rbac.d.ts","sourceRoot":"","sources":["../../src/access/rbac.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEpE,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,eAAO,MAAM,QAAQ,MAAM,CAAC;AAI5B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CACzB;AAKD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,aAAa,CAEf;AAID,wBAAgB,WAAW,CAAC,IAAI,SAAU,GAAG,aAAa,CAEzD;AAOD,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE5E;AAGD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE7E;AAGD,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAE3D;AAMD,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAE1D;AAID,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAE3D;AAID,wBAAgB,sBAAsB,CAAC,CAAC,SAAS;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EACrE,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,KAAK,EAAE,CAAC,EAAE,GACT,CAAC,EAAE,CAEL"}
+{"version":3,"file":"rbac.d.ts","sourceRoot":"","sources":["../../src/access/rbac.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEpE,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,eAAO,MAAM,QAAQ,MAAM,CAAC;AAI5B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CACzB;AAKD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,aAAa,CAEf;AAID,wBAAgB,WAAW,CAAC,IAAI,SAAU,GAAG,aAAa,CAEzD;AAOD,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE5E;AAGD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE7E;AAGD,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAE3D;AAMD,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAE1D;AAMD,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAE9D;AAID,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAE3D;AAID,wBAAgB,sBAAsB,CAAC,CAAC,SAAS;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EACrE,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,KAAK,EAAE,CAAC,EAAE,GACT,CAAC,EAAE,CAEL"}

package/dist/access/rbac.js

@@ -42,6 +42,13 @@ export function canPromote(role) {
 export function canRatify(role) {
     return role?.ratify ?? false;
 }
+// True if the role is propose-only (#235): its writes must land as staged
+// `write` proposals, never as direct mutations. vault_write coerces; every
+// other write tool denies. The write grant still scopes WHICH collections the
+// role may propose into.
+export function isProposeOnly(role) {
+    return role?.proposeOnly ?? false;
+}
 // True if the role has read access to at least one collection. Curation tools
 // (lint, tension log, provenance) are open to anyone with any read grant.
 export function hasAnyRead(role) {

package/dist/access/rbac.js.map

@@ -1 +1 @@
-{"version":3,"file":"rbac.js","sourceRoot":"","sources":["../../src/access/rbac.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,0EAA0E;AAI1E,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC;AAClC,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAC;AAU5B,+EAA+E;AAC/E,6EAA6E;AAC7E,2BAA2B;AAC3B,MAAM,UAAU,aAAa,CAC3B,MAAqB,EACrB,IAAY,EACZ,QAAgB;IAEhB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC;AAClE,CAAC;AAED,2EAA2E;AAC3E,0BAA0B;AAC1B,MAAM,UAAU,WAAW,CAAC,IAAI,GAAG,OAAO;IACxC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACpD,CAAC;AAED,SAAS,OAAO,CAAC,IAAc,EAAE,UAAkB;IACjD,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC9D,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,OAAO,CAAC,IAAuB,EAAE,UAAkB;IACjE,OAAO,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACzD,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,QAAQ,CAAC,IAAuB,EAAE,UAAkB;IAClE,OAAO,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AAC1D,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,OAAO,IAAI,EAAE,OAAO,IAAI,KAAK,CAAC;AAChC,CAAC;AAED,8EAA8E;AAC9E,4EAA4E;AAC5E,wEAAwE;AACxE,kDAAkD;AAClD,MAAM,UAAU,SAAS,CAAC,IAAuB;IAC/C,OAAO,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC;AAC/B,CAAC;AAED,8EAA8E;AAC9E,0EAA0E;AAC1E,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,OAAO,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,MAAM,UAAU,sBAAsB,CACpC,IAAuB,EACvB,KAAU;IAEV,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"rbac.js","sourceRoot":"","sources":["../../src/access/rbac.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,0EAA0E;AAI1E,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC;AAClC,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAC;AAU5B,+EAA+E;AAC/E,6EAA6E;AAC7E,2BAA2B;AAC3B,MAAM,UAAU,aAAa,CAC3B,MAAqB,EACrB,IAAY,EACZ,QAAgB;IAEhB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC;AAClE,CAAC;AAED,2EAA2E;AAC3E,0BAA0B;AAC1B,MAAM,UAAU,WAAW,CAAC,IAAI,GAAG,OAAO;IACxC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACpD,CAAC;AAED,SAAS,OAAO,CAAC,IAAc,EAAE,UAAkB;IACjD,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC9D,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,OAAO,CAAC,IAAuB,EAAE,UAAkB;IACjE,OAAO,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACzD,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,QAAQ,CAAC,IAAuB,EAAE,UAAkB;IAClE,OAAO,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AAC1D,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,OAAO,IAAI,EAAE,OAAO,IAAI,KAAK,CAAC;AAChC,CAAC;AAED,8EAA8E;AAC9E,4EAA4E;AAC5E,wEAAwE;AACxE,kDAAkD;AAClD,MAAM,UAAU,SAAS,CAAC,IAAuB;IAC/C,OAAO,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC;AAC/B,CAAC;AAED,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,yBAAyB;AACzB,MAAM,UAAU,aAAa,CAAC,IAAuB;IACnD,OAAO,IAAI,EAAE,WAAW,IAAI,KAAK,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,0EAA0E;AAC1E,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,OAAO,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,MAAM,UAAU,sBAAsB,CACpC,IAAuB,EACvB,KAAU;IAEV,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;AAChE,CAAC"}