daftari 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +465 -366
  3. package/dist/backfill/derive.d.ts.map +1 -1
  4. package/dist/backfill/derive.js +1 -0
  5. package/dist/backfill/derive.js.map +1 -1
  6. package/dist/court/index.d.ts.map +1 -1
  7. package/dist/court/index.js +48 -0
  8. package/dist/court/index.js.map +1 -1
  9. package/dist/court/triage.d.ts +5 -0
  10. package/dist/court/triage.d.ts.map +1 -0
  11. package/dist/court/triage.js +71 -0
  12. package/dist/court/triage.js.map +1 -0
  13. package/dist/curation/lint-voice.js +1 -1
  14. package/dist/curation/lint-voice.js.map +1 -1
  15. package/dist/curation/lint.d.ts +1 -1
  16. package/dist/curation/lint.d.ts.map +1 -1
  17. package/dist/curation/lint.js +5 -5
  18. package/dist/curation/lint.js.map +1 -1
  19. package/dist/curation/read-heat.d.ts +16 -0
  20. package/dist/curation/read-heat.d.ts.map +1 -0
  21. package/dist/curation/read-heat.js +52 -0
  22. package/dist/curation/read-heat.js.map +1 -0
  23. package/dist/curation/structural.d.ts +1 -1
  24. package/dist/curation/structural.d.ts.map +1 -1
  25. package/dist/curation/structural.js +8 -7
  26. package/dist/curation/structural.js.map +1 -1
  27. package/dist/curation/tension-triage.d.ts +57 -0
  28. package/dist/curation/tension-triage.d.ts.map +1 -0
  29. package/dist/curation/tension-triage.js +155 -0
  30. package/dist/curation/tension-triage.js.map +1 -0
  31. package/dist/frontmatter/schema.d.ts.map +1 -1
  32. package/dist/frontmatter/schema.js +2 -1
  33. package/dist/frontmatter/schema.js.map +1 -1
  34. package/dist/frontmatter/types.d.ts +4 -1
  35. package/dist/frontmatter/types.d.ts.map +1 -1
  36. package/dist/frontmatter/types.js +6 -0
  37. package/dist/frontmatter/types.js.map +1 -1
  38. package/dist/search/hybrid.d.ts +1 -1
  39. package/dist/search/hybrid.d.ts.map +1 -1
  40. package/dist/sleep/cycle.d.ts.map +1 -1
  41. package/dist/sleep/cycle.js +27 -11
  42. package/dist/sleep/cycle.js.map +1 -1
  43. package/dist/tools/curation.d.ts +2 -0
  44. package/dist/tools/curation.d.ts.map +1 -1
  45. package/dist/tools/curation.js +141 -0
  46. package/dist/tools/curation.js.map +1 -1
  47. package/dist/tools/read.js +4 -4
  48. package/dist/tools/read.js.map +1 -1
  49. package/dist/tools/search.js +3 -3
  50. package/dist/tools/search.js.map +1 -1
  51. package/dist/tools/write.d.ts +7 -0
  52. package/dist/tools/write.d.ts.map +1 -1
  53. package/dist/tools/write.js +67 -6
  54. package/dist/tools/write.js.map +1 -1
  55. package/package.json +1 -1
package/README.md CHANGED
@@ -14,6 +14,20 @@ Daftari is the **long-term memory cortex for your LLM agents** — a persistent,
14
14
  structured vault they read, write, and curate over time, **portable across any
15
15
  model.** A cortex, not a clipboard.
16
16
 
17
+ ## Contents
18
+
19
+ **Why Daftari** — [Rent the brain, own the memory](#rent-the-brain-own-the-memory) · [Not a second brain](#not-a-second-brain) · [It remembers, it doesn't resolve](#it-remembers--it-doesnt-resolve-for-you) · [How it compares](#how-it-compares)
20
+
21
+ **Concepts** — [What it is](#what-it-is) · [The four layers](#the-four-layers) · [Two kinds of knowledge](#two-kinds-of-knowledge) · [File format](#file-format)
22
+
23
+ **The rituals** — [The tools](#the-tools) · [Circadian memory](#circadian-memory) · [Tension Court](#tension-court) · [The principal interview](#the-principal-interview) · [Belief archaeology](#belief-archaeology) · [The vault as witness](#the-vault-as-witness--and-the-wager-layer) · [Coherence audit](#coherence-audit)
24
+
25
+ **Running it** — [Access control](#access-control) · [Server mode](#server-mode-self-hosted) · [Storage backing](#storage-backing) · [Adopting a vault + OKF](#adopting-an-existing-vault)
26
+
27
+ **Reference** — [What's not in v1](#whats-not-in-v1) · [Development](#development) · [Documentation](#documentation) · [Integrations](#integrations) · [Privacy](#privacy) · [License](#license)
28
+
29
+ <!-- Why Daftari -->
30
+
17
31
  ## Rent the brain, own the memory
18
32
 
19
33
  LLMs are stateless; they forget. So memory is being bolted on everywhere — but
@@ -54,9 +68,46 @@ It resolves only by discovery — a real edge — never by invention. The agent
54
68
  compiles; the vault preserves; *you* keep the judgment. See
55
69
  [the manifesto](docs/manifesto.md) for the full argument.
56
70
 
71
+ ```mermaid
72
+ flowchart TD
73
+ A[Two docs disagree] --> B{Is there a real edge?<br/>source / supersession link}
74
+ B -- yes --> C[Supersede: one current,<br/>lineage preserved]
75
+ B -- no --> D[Tension: both held open, live]
76
+ ```
77
+
78
+ ## How it compares
79
+
80
+ The real question a memory layer has to answer: **what happens when two facts
81
+ contradict?**
82
+
83
+ | What happens to a contradiction? | Systems |
84
+ |---|---|
85
+ | Invisible | AGENTS.md, RAG |
86
+ | Synthesis-overwrite (association only) | Mem0 (OSS), ChatGPT / Claude memory, Glean |
87
+ | New wins, old tagged-invalid | Zep / Graphiti, Sentra |
88
+ | Resolved by graph / majority-vote | Cognee, ElephantBroker |
89
+ | **Held open, live & queryable** | **Daftari** |
90
+
91
+ And the honest cost, since compounding isn't free:
92
+
93
+ | Who has to do the curation work? | |
94
+ |---|---|
95
+ | RAG | Nobody — retrieval only, zero authoring cost |
96
+ | AGENTS.md | One file, hand-maintained |
97
+ | **Daftari** | **An agent (or human) curates — the heaviest of the three, and the reason knowledge compounds** |
98
+
99
+ > The nearest formal prior art is **TOKI** ([arXiv 2606.06240](https://arxiv.org/abs/2606.06240),
100
+ > with a [reference implementation](https://github.com/ZenAlexa/toki-bitemporal-memory)):
101
+ > a bitemporal operator algebra whose opt-in `await-confirmation` operator can hold a
102
+ > contradiction open. The line: TOKI resolves at write time (hold-open is one of four
103
+ > operators) and keeps the loser in an *archival* audit row; Daftari makes non-resolution
104
+ > the *default* and keeps both facts *live and queryable* in retrieval.
105
+
106
+ <!-- Concepts -->
107
+
57
108
  ## What it is
58
109
 
59
- A directory of markdown files with YAML frontmatter, exposed to agents as 27
110
+ A directory of markdown files with YAML frontmatter, exposed to agents as 35
60
111
  MCP tools over stdio. The vault is plain text: you can read it in any editor,
61
112
  `git log` it, grep it. Daftari adds the machinery agents need to treat it as a
62
113
  shared workspace.
@@ -82,6 +133,84 @@ layers 3 and 4.
82
133
  |**Write arbitration**|File-level locks (60s TTL), auto-commit to git, structured provenance log. |Concurrent agents write safely. Every mutation is attributable. |
83
134
  |**Curation** |Draft-to-canonical lifecycle, TTL-based staleness, tension logging, advisory linter. |Knowledge that stops being true gets surfaced, not silently trusted. |
84
135
 
136
+ ## Two kinds of knowledge
137
+
138
+ Every document declares a `domain`. The distinction drives how the curation
139
+ layer treats it.
140
+
141
+ **Accumulation** documents compile and compound. A competitive-intel note, a
142
+ pricing breakdown, a researched comparison. Each write builds on the last.
143
+ Going stale is a problem to fix.
144
+
145
+ **Generative** documents speculate. A moonshot sketch, a brainstorm, a “what
146
+ if.” Going stale is expected, not a defect.
147
+
148
+ Applied uniformly, the same curation rules would either nag about every
149
+ brainstorm or wave through every stale fact. The domain split lets the system
150
+ hold each to the right standard.
151
+
152
+ ## File format
153
+
154
+ Markdown with YAML frontmatter. Frontmatter is the metadata layer; there is no
155
+ separate database.
156
+
157
+ ```yaml
158
+ ---
159
+ title: "Aurora Pipelines — Positioning Overview"
160
+ domain: accumulation
161
+ collection: competitive-intel
162
+ status: canonical
163
+ confidence: medium
164
+ created: 2026-05-17
165
+ updated: 2026-05-17
166
+ updated_by: agent:claude-code
167
+ provenance: synthesized
168
+ sources:
169
+ - aurora-product-page
170
+ ttl_days: 120
171
+ valid_from: 2026-05-01
172
+ valid_until: null
173
+ tags: [aurora, ingestion, competitive]
174
+ questions_answered:
175
+ - "How does Aurora frame the ingestion/transformation boundary?"
176
+ questions_raised:
177
+ - "Does an authored-pipeline model slow teams down at small scale?"
178
+ ---
179
+ ```
180
+
181
+ Documents can make their epistemic edges explicit: `questions_answered` is what
182
+ later agents can take as settled, `questions_raised` is where to build next.
183
+ `vault_lint` turns the open questions across the vault into a coverage map.
184
+
185
+ `valid_from` / `valid_until` are the second temporal axis. Everything else in
186
+ the file records **transaction time** — when the vault came to believe
187
+ something; these record **valid time** — when the claim was true in the world. A
188
+ document edited this morning can describe a price that stopped applying in
189
+ March, and only the second axis can tell you so. That makes supersession
190
+ checkable rather than merely asserted:
191
+
192
+ ```bash
193
+ daftari asof 2026-04-01 --valid 2026-01-15
194
+ ```
195
+
196
+ "On April 1st, what did the vault believe was true on January 15th?"
197
+
198
+ <details>
199
+ <summary><b>Half-open valid-time intervals and the authoring rules (▸ expand for full reference)</b></summary>
200
+
201
+ The window is half-open — `[valid_from, valid_until)` — so `valid_until` is the
202
+ first day the claim no longer held, and a successor's `valid_from` is exactly
203
+ its predecessor's `valid_until`. Handoffs share no day and leave no gap. The
204
+ fields are optional and always authored: nothing derives them from git dates or
205
+ mtime, because that would manufacture a claim nobody made. Both null means
206
+ unknown, which is never read as "always true".
207
+
208
+ Full field reference in <docs/file-format.md>.
209
+
210
+ </details>
211
+
212
+ <!-- The rituals -->
213
+
85
214
  ## The tools
86
215
 
87
216
  **Read:** `vault_read`, `vault_index`, `vault_status`
@@ -108,21 +237,30 @@ open exposure, contested claims with stake at risk, the settled book
108
237
  deterministic; includes the flat-curve monitor so a single-author vault is
109
238
  reported as uninformative rather than as signal.
110
239
 
240
+ <details>
241
+ <summary><b>The full per-category tool registry and the tool-tier config (▸ expand for full reference)</b></summary>
242
+
111
243
  **Search:** `vault_search` (hybrid BM25 + vector; hits carry their unresolved
112
244
  tensions inline and foreground the current source of superseded documents),
113
245
  `vault_search_related`, `vault_themes` (thematic clustering), `vault_reindex`
114
246
 
115
- **Write:** `vault_write`, `vault_append`, `vault_promote`, `vault_deprecate`, `vault_supersede`, `vault_merge`, `vault_set_confidence`
247
+ **Write:** `vault_write`, `vault_append`, `vault_promote`, `vault_deprecate`, `vault_supersede`, `vault_merge`, `vault_set_confidence`, `vault_set_tier`
248
+
249
+ **Curate:** `vault_tension_log`, `vault_tension_resolve`, `vault_tension_clusters`, `vault_tension_blast`, `vault_tension_triage` (the unranked triage card / `court --triage`), `vault_lint`, `vault_provenance`, `vault_staleness` (edge-staleness: pending upstream changes / broken-read rate)
116
250
 
117
- **Curate:** `vault_tension_log`, `vault_tension_resolve`, `vault_tension_clusters`, `vault_tension_blast`, `vault_lint`, `vault_provenance`
251
+ **Edges:** `vault_edge_observe`, `vault_edge_contest`, `vault_edges`, `vault_consumes` (query the compiled dependency graph)
118
252
 
119
- **Edges:** `vault_edge_observe`, `vault_edge_contest`, `vault_edges`
253
+ **Dispatch:** `vault_tier1` (type-directed change dispatch), `vault_tier2_queue`, `vault_tier2_verdict` (semantic-review queue + verdict)
120
254
 
121
255
  **Ratify:** `vault_stage_action`, `vault_ratify`
122
256
 
123
257
  The curation engine is advisory: `vault_lint` reports problems and
124
258
  `vault_tension_log` records contradictions. Neither auto-fixes anything. Every
125
- change is a deliberate, attributable act.
259
+ change is a deliberate, attributable act. Retraction is surfaced, not enforced:
260
+ the `retiredStillLinked` lint check / `retired_still_linked` read-time advisory
261
+ flags canonical docs still citing a deprecated or superseded source, and
262
+ `vault_deprecate`/`vault_supersede` return a `dependents` advisory (the
263
+ downstream blast) at retraction time.
126
264
 
127
265
  ### Tool tiers
128
266
 
@@ -142,314 +280,157 @@ tools:
142
280
  `core` is the search-before-derive loop (`vault_search`, `vault_read`,
143
281
  `vault_write`, `vault_index`, `vault_lint`, `vault_status`); `standard` adds
144
282
  the full document lifecycle (append/promote/deprecate/supersede/merge,
145
- confidence and tier setters, propose/ratify) plus diagnostics; `full` is
146
- everything. `--tools <tier>` overrides the tier for one invocation. Filtering
283
+ confidence and tier setters, propose/ratify) plus `vault_search_related`,
284
+ `vault_provenance`, and diagnostics; `full` is everything. `--tools <tier>` overrides the tier for one invocation. Filtering
147
285
  only changes what is *advertised* — calls to any registered tool still work,
148
286
  so an agent holding a cached tool name keeps working across a tier change.
149
287
  Unknown names in `include`/`exclude` warn at startup and are ignored, so a
150
288
  config written for a newer daftari still loads.
151
289
 
290
+ </details>
291
+
152
292
  **Evaluate (opt-in, requires an Anthropic API key):** `daftari eval` — scores how
153
293
  well an LLM can use the curation surface to answer multi-hop questions about the
154
294
  vault. See the [design spec](docs/superpowers/specs/2026-05-31-cortex-quality-metric-design.md)
155
295
  for the rationale and the cortex framing.
156
296
 
157
- ## Two kinds of knowledge
158
-
159
- Every document declares a `domain`. The distinction drives how the curation
160
- layer treats it.
297
+ ## Circadian memory
161
298
 
162
- **Accumulation** documents compile and compound. A competitive-intel note, a
163
- pricing breakdown, a researched comparison. Each write builds on the last.
164
- Going stale is a problem to fix.
299
+ The vault sleeps. `daftari sleep` is the nightly metabolic pass — deterministic,
300
+ LLM-free, write-free (documents are never touched):
165
301
 
166
- **Generative** documents speculate. A moonshot sketch, a brainstorm, a “what
167
- if.” Going stale is expected, not a defect.
302
+ ```bash
303
+ # In cron (any scheduler works; daftari ships the cycle, not a daemon):
304
+ 0 3 * * * cd /path/to/vault && npx daftari sleep --output .daftari/morning-report.md
305
+ ```
168
306
 
169
- The same curation rules applied uniformly would either nag about every
170
- brainstorm or quietly trust every stale fact. The domain split lets the system
171
- hold each to the right standard.
307
+ The cycle sweeps expired staged actions, scores every document's decay, and
308
+ builds the **wake list**: canonical accumulation documents past their TTL
309
+ with downstream dependents, ranked by blast radius. The list is written to
310
+ `.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
311
+ document against its sources, stage the diff — because the vault never
312
+ re-verifies on its own. Generative documents going stale are expected, not a
313
+ defect: counted, never woken.
172
314
 
173
- ## Access control
315
+ The **Morning Report** ends where the human begins: tension aging and the
316
+ court docket head, the ratification queue with soon-to-expire proposals, and
317
+ the rubber-stamp monitor — zero rejections over a long decision history is
318
+ printed as a warning, not a compliment. The agent proposes overnight; you
319
+ ratify over coffee.
174
320
 
175
- No user-management system. Roles live in config, the server starts with one:
321
+ ## Tension Court
176
322
 
177
- ```yaml
178
- roles:
179
- analyst:
180
- read: [competitive-intel, pricing]
181
- write: [competitive-intel, _drafts]
182
- researcher:
183
- read: ["*"]
184
- write: [moonshot, _drafts]
185
- admin:
186
- read: ["*"]
187
- write: ["*"]
188
- promote: true
189
- ratify: true # may approve/reject staged actions and contest edges
190
- ```
323
+ Tensions wait in a log; the court turns them into decidable cases. `daftari
324
+ court` compiles a **docket** — every open tension briefed and ranked (stale
325
+ first, then by blast radius): both sides' claims, the present state of their
326
+ documents, the downstream stakes, cluster membership, and **precedents** —
327
+ past rulings on disputes that shared a document, a collection pair, or a
328
+ kind.
191
329
 
192
- No `--role` or an unknown name falls back to deny-all. An agent identity is
193
- just a role too — e.g. a `curation-loop` role that reads and writes but leaves
194
- `ratify` off: the agent proposes, humans ratify.
330
+ The **triage card** (`daftari court --triage` / `vault_tension_triage`) is the
331
+ deliberately **unranked**, cluster-grouped companion view — legibility, not a
332
+ severity score. Each contested side surfaces `criticality`, `provenance`, and
333
+ `updated_by`, so a resolver can judge trust without opening the documents.
195
334
 
196
- ## File format
335
+ ```bash
336
+ # The docket — a 5-minute weekly ritual
337
+ daftari court --vault ./my-vault
197
338
 
198
- Markdown with YAML frontmatter. Frontmatter is the metadata layer; there is no
199
- separate database.
339
+ # One case's full brief (verbatim rationales from cited precedents)
340
+ daftari court --tension tension-abc123
200
341
 
201
- ```yaml
202
- ---
203
- title: "Aurora Pipelines — Positioning Overview"
204
- domain: accumulation
205
- collection: competitive-intel
206
- status: canonical
207
- confidence: medium
208
- created: 2026-05-17
209
- updated: 2026-05-17
210
- updated_by: agent:claude-code
211
- provenance: synthesized
212
- sources:
213
- - aurora-product-page
214
- ttl_days: 120
215
- valid_from: 2026-05-01
216
- valid_until: null
217
- tags: [aurora, ingestion, competitive]
218
- questions_answered:
219
- - "How does Aurora frame the ingestion/transformation boundary?"
220
- questions_raised:
221
- - "Does an authored-pipeline model slow teams down at small scale?"
222
- ---
342
+ # Rule. The rationale is recorded verbatim and cited by future dockets.
343
+ daftari court rule tension-abc123 --kind corrected \
344
+ --rationale "Vendor pricing page confirmed the entry tier on 2026-07-10."
223
345
  ```
224
346
 
225
- Documents can make their epistemic edges explicit: `questions_answered` is what
226
- later agents can take as settled, `questions_raised` is where to build next.
227
- `vault_lint` turns the open questions across the vault into a coverage map.
228
-
229
- `valid_from` / `valid_until` are the second temporal axis. Everything else in
230
- the file records **transaction time** — when the vault came to believe
231
- something. These record **valid time**: when the claim was true in the world. A
232
- document edited this morning can describe a price that stopped applying in
233
- March, and only the second axis can tell you so.
347
+ Rulings go through the same `resolveTension` write path as
348
+ `vault_tension_resolve` — a ruling records the closure, it never edits the
349
+ disputed documents. Precedent retrieval is deterministic (shared-document >
350
+ collection-pair > same-kind; no LLM): the court retrieves how this house has
351
+ resolved similar disputes before, and whether a precedent applies stays the
352
+ human's judgment. Memory grows case law.
234
353
 
235
- The window is half-open — `[valid_from, valid_until)` — so `valid_until` is the
236
- first day the claim no longer held, and a successor's `valid_from` is exactly
237
- its predecessor's `valid_until`. Handoffs share no day and leave no gap. The
238
- fields are optional and always authored: nothing derives them from git dates or
239
- mtime, because that would manufacture a claim nobody made. Both null means
240
- unknown, which is never read as "always true".
354
+ ## The principal interview
241
355
 
242
- That makes supersession checkable rather than merely asserted:
356
+ The vault interrogates you. `daftari interview` assembles a question sheet
357
+ from what the vault already knows is unclear — open tensions (contested
358
+ first, longest-carried first), canonical accumulation docs past their TTL,
359
+ and `questions_raised` entries no document answers — deterministic and
360
+ LLM-free, like the circadian pass:
243
361
 
244
362
  ```bash
245
- daftari asof 2026-04-01 --valid 2026-01-15
363
+ # The sheet — read-only, priority-ordered
364
+ daftari interview --vault ./my-vault
365
+
366
+ # Sit for it. Answers are recorded VERBATIM; empty skips, 'q' ends.
367
+ daftari interview ask --vault ./my-vault
246
368
  ```
247
369
 
248
- "On April 1st, what did the vault believe was true on January 15th?"
370
+ Answered questions become a transcript document in an `interviews/`
371
+ collection — `tier: source` (your words, body immutable), `provenance:
372
+ direct`, no TTL (testimony doesn't expire) — committed like any other write,
373
+ with `sources` tracing each question back to the tension or document that
374
+ prompted it. The pattern is the companion interview on a living-summary
375
+ page: the compiler's highest-value move is not more compilation, it is
376
+ asking the principal about the unclear spots and folding the verbatim
377
+ answers back into the corpus.
249
378
 
250
- Full field reference in <docs/file-format.md>.
379
+ Recording testimony resolves nothing. The transcript is *evidence*: the CLI
380
+ ends by pointing at `daftari court rule <id> --references <transcript>` for
381
+ tensions it touched, and at re-verified writes for stale docs. Operator-only,
382
+ like the court — no MCP tool, no access context.
251
383
 
252
- ## Adopting an existing vault
384
+ ## Belief archaeology
253
385
 
254
- Already have a wiki or an Obsidian vault? Daftari adopts it **in place** — it
255
- indexes and curates the same markdown files you already edit, not a separate copy.
386
+ Git is the version layer, so the vault can answer **"what did we believe on
387
+ March 3?"** `daftari asof` is a read-only report over the repo's history — no
388
+ checkout, no index, no API key:
256
389
 
257
390
  ```bash
258
- # Dry run — see what would change, write nothing
259
- daftari import obsidian ~/my-vault --plan
260
-
261
- # Adopt one folder at a time (per-folder ratification; --yes to skip the prompt)
262
- daftari import obsidian ~/my-vault --apply --scope notes
263
- ```
264
-
265
- The import is non-destructive to your content. It fills only the *missing*
266
- Daftari frontmatter — collection from the folder, dates from git history (or file
267
- mtime), sensible defaults for the rest — and preserves everything you already
268
- had, including custom frontmatter fields. Obsidian specifics: inline `#tags` are
269
- merged into `tags`, a Web Clipper `source` is mapped into `sources`, and
270
- `[[wikilinks]]` are left untouched (Daftari resolves them as written). Filling
271
- frontmatter is deliberate, not automatic — re-run the import to pick up newly
272
- added notes.
391
+ # The vault's belief state at a date (or any git ref), plus the drift since
392
+ daftari asof 2026-03-03 --vault ./my-vault
273
393
 
274
- ### Cloud-synced vaults (iCloud, Dropbox, …)
394
+ # One document's trajectory: frontmatter then vs now, commits in between
395
+ daftari asof HEAD~20 --doc pricing/helios-consumption-pricing.md
275
396
 
276
- Daftari versions every change with git, and a `.git/` directory churning inside a
277
- cloud-synced folder can corrupt. For a synced vault, keep git's data outside it:
397
+ # Counterfactual replay: this fact turned out wrong — who had inherited it
398
+ # at the time, and where are they now?
399
+ daftari asof 2026-03-03 --blast pricing/helios-consumption-pricing.md
400
+ ```
278
401
 
279
- ```bash
280
- daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
281
- --apply --scope notes --external-git-dir
282
- ```
283
-
284
- This writes `git_dir: external` to `.daftari/config.yaml`, so Daftari uses
285
- `git init --separate-git-dir`: only a tiny static `.git` *file* stays in the vault
286
- (syncs harmlessly) while the repo data lives under `~/.local/share/daftari/git/`.
287
- Pass `--external-git-dir=/path` for an explicit location, or set `git_dir`
288
- directly in config to apply the same to any vault. History is per-device; your
289
- notes still sync everywhere.
290
-
291
- ### Lower-level: `backfill`
292
-
293
- `daftari import obsidian` is a thin, Obsidian-aware wrapper over `daftari
294
- backfill` — the git-driven frontmatter migration that works on any markdown wiki.
295
- Use it directly for non-Obsidian trees:
296
-
297
- ```bash
298
- daftari backfill --plan
299
- daftari backfill --apply --scope specs
300
- ```
301
-
302
- ## Open Knowledge Format (OKF)
303
-
304
- [OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
305
- is Google Cloud's vendor-neutral spec for the LLM-wiki pattern: a directory of
306
- markdown files with YAML frontmatter that any producer can emit and any consumer
307
- can read without translation. A Daftari vault *is* that pattern, so `daftari
308
- okf` bridges the two directions.
309
- [v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals/)
310
- adds opt-in **trust signals** — raw credibility indicators (provenance,
311
- verification, lifecycle, freshness), never computed scores — and Daftari maps
312
- them from/to its native metadata.
313
-
314
- **Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
315
- concept doc (the core `type` / `title` / `description` / `resource` / `tags`
316
- fields, plus a verbatim `daftari` sidecar for lossless round-trip), with
317
- generated `index.md` (progressive-disclosure listing) and `log.md`
318
- (chronological history). Trust signals derive from native metadata:
319
- `updated`/`updated_by` become `generated`, the lifecycle maps to
320
- `draft`/`stable`/`deprecated`, `ttl_days` becomes an absolute `stale_after`
321
- date, and `sources` become structured entries. `verified` is never fabricated —
322
- Daftari records authorship, not independent confirmations, so exported docs
323
- honestly read as unverified. The source vault is never mutated.
324
-
325
- ```bash
326
- daftari okf export ./my-vault --out ./okf-bundle
327
- daftari okf export ./my-vault --out ./okf-bundle --collection pricing
328
- ```
329
-
330
- **Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
331
- round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
332
- (docs land as `draft` in the `accumulation` domain, the original OKF `type` is
333
- preserved in an `okf_type` field). Trust signals inform the mapping: a
334
- human-reviewed doc (a `human:*` entry in `verified`) imports with `confidence:
335
- high`, `status: deprecated` stays `deprecated` (retired knowledge must not
336
- resurface as a fresh draft), and `stale_after` converts to `ttl_days`. An
337
- `Attested Computation` is surfaced in an import warning but **not**
338
- auto-write-protected: `tier: source` is enforcement, and its only sanctioned
339
- grant path is `vault_set_tier` (reason required, provenance-logged) — a foreign
340
- bundle's self-declared `type` doesn't buy it. Review the doc, then elevate
341
- deliberately. OKF fields with no lossless Daftari slot (the trust record,
342
- attestation machinery) are preserved under `okf_*` keys. Writes auto-commit and
343
- the index is rebuilt.
344
-
345
- ```bash
346
- daftari okf import ./okf-bundle --into ./my-vault --dry-run
347
- daftari okf import ./okf-bundle --into ./my-vault
348
- ```
349
-
350
- ## Server mode (self-hosted)
351
-
352
- By default daftari is a per-user stdio process. `daftari serve` starts the
353
- same vault as **one always-on instance over Streamable HTTP** — for a team, or
354
- for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
355
-
356
- ```bash
357
- daftari serve --vault ./my-vault # http://127.0.0.1:8787/mcp
358
- daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
359
- ```
360
-
361
- Identity is **per MCP session**, resolved when the session opens, so every
362
- RBAC and existence-disclosure rule applies per connection with zero tool
363
- changes. Two composable auth schemes, both declared in config:
364
-
365
- ```yaml
366
- server:
367
- transport_security: external # required off-loopback: TLS terminates upstream
368
- auth:
369
- tokens: # static bearer tokens (agents, ETL)
370
- - env: DAFTARI_TOKEN_ETL # the VALUE lives in this env var, never in config
371
- user: agent:etl
372
- role: admin
373
- oauth: # OAuth 2.1 resource server (humans via your IdP)
374
- issuer: https://idp.example.com
375
- audience: daftari
376
- jwks_uri: https://idp.example.com/.well-known/jwks.json
377
- subjects:
378
- "alice@example.com": { user: human:alice, role: analyst }
379
- ```
380
-
381
- The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
382
- to start without auth **and** the explicit `transport_security: external`
383
- acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
384
- balancer in front); with any auth configured, a bad or missing credential is
385
- a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
386
- neither ever becomes the guest. Guest sessions exist only in the no-auth
387
- loopback configuration. A running server also refuses to be silently killed:
388
- stray stdio invocations against the same vault refuse to start, and replacing
389
- a live holder requires a deliberate `daftari serve --takeover`.
390
-
391
- ## Storage backing
392
-
393
- A self-hosted vault can push to durable object storage (#6). The local git
394
- working copy stays canonical — reads, writes, auto-commits, locks, and the
395
- index all stay exactly as above — and the backing is a dumb sync target:
396
-
397
- ```yaml
398
- # .daftari/config.yaml
399
- storage:
400
- backend: s3 # fs | s3 | azure
401
- bucket: team-vault
402
- region: us-east-1
403
- # endpoint: https://… # MinIO / R2 / GCS S3-interop endpoints
404
- # sync_interval_minutes: 15 # daftari serve pushes on this cadence
405
- ```
406
-
407
- ```bash
408
- daftari sync --vault ./my-vault # incremental push
409
- daftari sync --vault ./my-vault --dry-run # show the diff only
410
- daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
411
- ```
412
-
413
- The push covers the markdown tree, the `.git` directory, and durable
414
- `.daftari` journals; the rebuildable SQLite index and lock files never sync.
415
- Neither do `.git/config` and `.git/hooks` — git *executes* what those
416
- declare, and a backup channel must not deliver code (`git clone` refuses to
417
- transmit them for the same reason), so re-add remotes and local git config
418
- by hand after a restore.
419
- Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
420
- as optional dependencies — install the one you use; credentials come from the
421
- SDK's standard environment chain, never from vault config. GCS is reached via
422
- its S3-interoperability endpoint. Restore refuses non-empty directories and
423
- reindexes when done.
424
-
425
- ## How it compares
426
-
427
- | |AGENTS.md |RAG |Daftari |
428
- |--------------------|-----------------|-----------------------------|-------------------------------------|
429
- |Who writes? |Humans |Nobody (retrieval only) |Agents + humans |
430
- |Scales? |One file, doesn’t|Scales storage, not coherence|Structured collections with lifecycle|
431
- |Knowledge compounds?|No |No |Yes, draft → canonical → deprecated |
432
- |Contradictions? |Invisible |Invisible |Tension log surfaces them |
433
- |Staleness? |Silent |Silent |TTL-based decay with advisory lint |
402
+ The default report shows the document and tension state at that point and
403
+ the drift since: documents added/removed, `status`/`confidence` transitions,
404
+ and tensions opened or resolved. `--blast` computes the blast radius of a
405
+ document over the tree *as of the commit* (same source/link edge semantics as
406
+ `vault_tension_blast`), annotating each downstream document with its status
407
+ today — the post-mortem view for a fact that was later corrected. Markdown to
408
+ stdout by default; `--output` / `--output-json` write files. Pairs with
409
+ `vault_receipt`: a receipt's `vaultHead` is exactly the anchor to hand back
410
+ to `asof`.
434
411
 
435
- ## What’s not in v1
412
+ ## The vault as witness — and the wager layer
436
413
 
437
- Deliberately deferred to keep the surface tight:
414
+ Every write already carries an identity, every proposal an outcome, every
415
+ tension a logger and a ruling. `vault_witness` aggregates that ledger into a
416
+ **track record per principal** — and prices it. Confidence is free to claim,
417
+ so the wager schedule makes it cost something: writing at `high` stakes 3
418
+ points, `medium` 1, `low` 0 (hedged claims are the honest default and are
419
+ never taxed). A claim later corrected by a ruling or retired by someone else
420
+ burns the stake; a claim maintained through a full TTL cycle earns credit.
421
+ The balance is arithmetic on recorded facts — advisory, provisional
422
+ constants, nothing enforced: routing a high-stakes write to the agent with
423
+ the earned balance is your policy, not the vault's.
438
424
 
439
- - **Cloud-hosted multi-tenant SaaS** (self-hosted server mode HAS shipped —
440
- see [Server mode](#server-mode-self-hosted) and
441
- [Storage backing](#storage-backing); the project itself hosts nothing)
442
- - **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
443
- - **Background curation agent** running lint on a cadence
444
- - **Enforced domain separation** (v1 documents the convention; v2 enforces it —
445
- advisory boundary warnings shipped in the meantime: `vault_lint`'s
446
- `domainLeaks` check and write-time `domain_warnings`)
425
+ <details>
426
+ <summary><b>The two kill conditions that travel with the tool (▸ expand for full reference)</b></summary>
447
427
 
448
- (LLM reranking, deferred here originally, has since shipped as the opt-in
449
- agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
450
- fused candidate pool and the protocol; the calling agent is the judge.)
428
+ Both kill conditions from the design travel with the tool: the flat-curve
429
+ monitor (one author ≥95% of writes → curves declared uninformative) and the
430
+ longitudinal write-volume series (if stake-fear suppresses honest claims, it
431
+ shows up here first).
451
432
 
452
- Each is a clean increment on a surface that already works.
433
+ </details>
453
434
 
454
435
  ## Coherence audit
455
436
 
@@ -516,6 +497,9 @@ staleness check still runs over the in-repo link graph.
516
497
  Catches the case where you keep touching an index page while the docs it
517
498
  links to are rotting.
518
499
 
500
+ <details>
501
+ <summary><b>Sample output, CI integration, exit codes, CLI flags, and the full <code>audit.yaml</code> schema (▸ expand for full reference)</b></summary>
502
+
519
503
  ### Sample output
520
504
 
521
505
  ```markdown
@@ -610,131 +594,245 @@ fail_on:
610
594
  transitive_staleness: 100 # default: generous; teams tune
611
595
  ```
612
596
 
613
- ## The vault as witness — and the wager layer
597
+ </details>
614
598
 
615
- Every write already carries an identity, every proposal an outcome, every
616
- tension a logger and a ruling. `vault_witness` aggregates that ledger into a
617
- **track record per principal** — and prices it. Confidence is free to claim,
618
- so the wager schedule makes it cost something: writing at `high` stakes 3
619
- points, `medium` 1, `low` 0 (hedged claims are the honest default and are
620
- never taxed). A claim later corrected by a ruling or retired by someone else
621
- burns the stake; a claim maintained through a full TTL cycle earns credit.
622
- The balance is arithmetic on recorded facts — advisory, provisional
623
- constants, nothing enforced: routing a high-stakes write to the agent with
624
- the earned balance is your policy, not the vault's. Both kill conditions
625
- from the design travel with the tool: the flat-curve monitor (one author ≥95%
626
- of writes → curves declared uninformative) and the longitudinal write-volume
627
- series (if stake-fear suppresses honest claims, it shows up here first).
599
+ <!-- Running it -->
628
600
 
629
- ## Circadian memory
601
+ ## Access control
630
602
 
631
- The vault sleeps. `daftari sleep` is the nightly metabolic pass — deterministic,
632
- LLM-free, write-free (documents are never touched):
603
+ No user-management system. Roles live in config, the server starts with one.
604
+ No `--role` or an unknown name falls back to deny-all. An agent identity is
605
+ just a role too — e.g. a `curation-loop` role that reads and writes but leaves
606
+ `ratify` off: the agent proposes, humans ratify.
607
+
608
+ <details>
609
+ <summary><b>Roles config example (▸ expand for full reference)</b></summary>
610
+
611
+ ```yaml
612
+ roles:
613
+ analyst:
614
+ read: [competitive-intel, pricing]
615
+ write: [competitive-intel, _drafts]
616
+ researcher:
617
+ read: ["*"]
618
+ write: [moonshot, _drafts]
619
+ admin:
620
+ read: ["*"]
621
+ write: ["*"]
622
+ promote: true
623
+ ratify: true # may approve/reject staged actions and contest edges
624
+ ```
625
+
626
+ </details>
627
+
628
+ ## Server mode (self-hosted)
629
+
630
+ By default daftari is a per-user stdio process. `daftari serve` starts the
631
+ same vault as **one always-on instance over Streamable HTTP** — for a team, or
632
+ for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
633
633
 
634
634
  ```bash
635
- # In cron (any scheduler works; daftari ships the cycle, not a daemon):
636
- 0 3 * * * cd /path/to/vault && npx daftari sleep --output .daftari/morning-report.md
635
+ daftari serve --vault ./my-vault # http://127.0.0.1:8787/mcp
636
+ daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
637
637
  ```
638
638
 
639
- The cycle sweeps expired staged actions, scores every document's decay, and
640
- builds the **wake list**: canonical accumulation documents past their TTL
641
- with downstream dependents, ranked by blast radius. The list is written to
642
- `.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
643
- document against its sources, stage the diff — because the vault never
644
- re-verifies on its own. Generative documents going stale are expected, not a
645
- defect: counted, never woken.
639
+ Identity is **per MCP session**, resolved when the session opens, so every
640
+ RBAC and existence-disclosure rule applies per connection with zero tool
641
+ changes. Two composable auth schemes, both declared in config.
646
642
 
647
- The **Morning Report** ends where the human begins: tension aging and the
648
- court docket head, the ratification queue with soon-to-expire proposals, and
649
- the rubber-stamp monitor — zero rejections over a long decision history is
650
- printed as a warning, not a compliment. The agent proposes overnight; you
651
- ratify over coffee.
643
+ <details>
644
+ <summary><b>Auth config (bearer tokens + OAuth 2.1) and the fail-loud posture (▸ expand for full reference)</b></summary>
652
645
 
653
- ## Tension Court
646
+ ```yaml
647
+ server:
648
+ transport_security: external # required off-loopback: TLS terminates upstream
649
+ auth:
650
+ tokens: # static bearer tokens (agents, ETL)
651
+ - env: DAFTARI_TOKEN_ETL # the VALUE lives in this env var, never in config
652
+ user: agent:etl
653
+ role: admin
654
+ oauth: # OAuth 2.1 resource server (humans via your IdP)
655
+ issuer: https://idp.example.com
656
+ audience: daftari
657
+ jwks_uri: https://idp.example.com/.well-known/jwks.json
658
+ subjects:
659
+ "alice@example.com": { user: human:alice, role: analyst }
660
+ ```
654
661
 
655
- Tensions wait in a log; the court turns them into decidable cases. `daftari
656
- court` compiles a **docket** — every open tension briefed and ranked (stale
657
- first, then by blast radius): both sides' claims, the present state of their
658
- documents, the downstream stakes, cluster membership, and **precedents** —
659
- past rulings on disputes that shared a document, a collection pair, or a
660
- kind.
662
+ The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
663
+ to start without auth **and** the explicit `transport_security: external`
664
+ acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
665
+ balancer in front); with any auth configured, a bad or missing credential is
666
+ a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
667
+ neither ever becomes the guest. Guest sessions exist only in the no-auth
668
+ loopback configuration. A running server also refuses to be silently killed:
669
+ stray stdio invocations against the same vault refuse to start, and replacing
670
+ a live holder requires a deliberate `daftari serve --takeover`.
671
+
672
+ </details>
673
+
674
+ ## Storage backing
675
+
676
+ A self-hosted vault can push to durable object storage (#6). The local git
677
+ working copy stays canonical — reads, writes, auto-commits, locks, and the
678
+ index all stay exactly as above — and the backing is a dumb sync target.
679
+
680
+ <details>
681
+ <summary><b>Storage config, <code>daftari sync</code> commands, and sync semantics (▸ expand for full reference)</b></summary>
682
+
683
+ ```yaml
684
+ # .daftari/config.yaml
685
+ storage:
686
+ backend: s3 # fs | s3 | azure
687
+ bucket: team-vault
688
+ region: us-east-1
689
+ # endpoint: https://… # MinIO / R2 / GCS S3-interop endpoints
690
+ # sync_interval_minutes: 15 # daftari serve pushes on this cadence
691
+ ```
661
692
 
662
693
  ```bash
663
- # The docket — a 5-minute weekly ritual
664
- daftari court --vault ./my-vault
694
+ daftari sync --vault ./my-vault # incremental push
695
+ daftari sync --vault ./my-vault --dry-run # show the diff only
696
+ daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
697
+ ```
665
698
 
666
- # One case's full brief (verbatim rationales from cited precedents)
667
- daftari court --tension tension-abc123
699
+ The push covers the markdown tree, the `.git` directory, and durable
700
+ `.daftari` journals; the rebuildable SQLite index and lock files never sync.
701
+ Neither do `.git/config` and `.git/hooks` — git *executes* what those
702
+ declare, and a backup channel must not deliver code (`git clone` refuses to
703
+ transmit them for the same reason), so re-add remotes and local git config
704
+ by hand after a restore.
705
+ Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
706
+ as optional dependencies — install the one you use; credentials come from the
707
+ SDK's standard environment chain, never from vault config. GCS is reached via
708
+ its S3-interoperability endpoint. Restore refuses non-empty directories and
709
+ reindexes when done.
668
710
 
669
- # Rule. The rationale is recorded verbatim and cited by future dockets.
670
- daftari court rule tension-abc123 --kind corrected \
671
- --rationale "Vendor pricing page confirmed the entry tier on 2026-07-10."
711
+ </details>
712
+
713
+ ## Adopting an existing vault
714
+
715
+ Already have a wiki or an Obsidian vault? Daftari adopts it **in place** — it
716
+ indexes and curates the same markdown files you already edit, not a separate copy.
717
+
718
+ ```bash
719
+ # Dry run — see what would change, write nothing
720
+ daftari import obsidian ~/my-vault --plan
721
+
722
+ # Adopt one folder at a time (per-folder ratification; --yes to skip the prompt)
723
+ daftari import obsidian ~/my-vault --apply --scope notes
672
724
  ```
673
725
 
674
- Rulings go through the same `resolveTension` write path as
675
- `vault_tension_resolve` — a ruling records the closure, it never edits the
676
- disputed documents. Precedent retrieval is deterministic (shared-document >
677
- collection-pair > same-kind; no LLM): the court retrieves how this house has
678
- resolved similar disputes before, and whether a precedent applies stays the
679
- human's judgment. Memory grows case law.
726
+ The import is non-destructive to your content. It fills only the *missing*
727
+ Daftari frontmatter — collection from the folder, dates from git history (or file
728
+ mtime), sensible defaults for the rest — and preserves everything you already
729
+ had, including custom frontmatter fields. Obsidian specifics: inline `#tags` are
730
+ merged into `tags`, a Web Clipper `source` is mapped into `sources`, and
731
+ `[[wikilinks]]` are left untouched (Daftari resolves them as written). Filling
732
+ frontmatter is deliberate, not automatic — re-run the import to pick up newly
733
+ added notes.
680
734
 
681
- ## The principal interview
735
+ ### Cloud-synced vaults (iCloud, Dropbox, …)
682
736
 
683
- The vault interrogates you. `daftari interview` assembles a question sheet
684
- from what the vault already knows is unclear — open tensions (contested
685
- first, longest-carried first), canonical accumulation docs past their TTL,
686
- and `questions_raised` entries no document answers — deterministic and
687
- LLM-free, like the circadian pass:
737
+ Daftari versions every change with git, and a `.git/` directory churning inside a
738
+ cloud-synced folder can corrupt. For a synced vault, keep git's data outside it:
688
739
 
689
740
  ```bash
690
- # The sheet — read-only, priority-ordered
691
- daftari interview --vault ./my-vault
741
+ daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
742
+ --apply --scope notes --external-git-dir
743
+ ```
692
744
 
693
- # Sit for it. Answers are recorded VERBATIM; empty skips, 'q' ends.
694
- daftari interview ask --vault ./my-vault
745
+ This writes `git_dir: external` to `.daftari/config.yaml`, so Daftari uses
746
+ `git init --separate-git-dir`: only a tiny static `.git` *file* stays in the vault
747
+ (syncs harmlessly) while the repo data lives under `~/.local/share/daftari/git/`.
748
+ Pass `--external-git-dir=/path` for an explicit location, or set `git_dir`
749
+ directly in config to apply the same to any vault. History is per-device; your
750
+ notes still sync everywhere.
751
+
752
+ ### Lower-level: `backfill`
753
+
754
+ `daftari import obsidian` is a thin, Obsidian-aware wrapper over `daftari
755
+ backfill` — the git-driven frontmatter migration that works on any markdown wiki.
756
+ Use it directly for non-Obsidian trees:
757
+
758
+ ```bash
759
+ daftari backfill --plan
760
+ daftari backfill --apply --scope specs
695
761
  ```
696
762
 
697
- Answered questions become a transcript document in an `interviews/`
698
- collection — `tier: source` (your words, body immutable), `provenance:
699
- direct`, no TTL (testimony doesn't expire) — committed like any other write,
700
- with `sources` tracing each question back to the tension or document that
701
- prompted it. The pattern is the companion interview on a living-summary
702
- page: the compiler's highest-value move is not more compilation, it is
703
- asking the principal about the unclear spots and folding the verbatim
704
- answers back into the corpus.
763
+ ## Open Knowledge Format (OKF)
705
764
 
706
- Recording testimony resolves nothing. The transcript is *evidence*: the CLI
707
- ends by pointing at `daftari court rule <id> --references <transcript>` for
708
- tensions it touched, and at re-verified writes for stale docs. Operator-only,
709
- like the court — no MCP tool, no access context.
765
+ [OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
766
+ is Google Cloud's vendor-neutral spec for the LLM-wiki pattern: a directory of
767
+ markdown files with YAML frontmatter that any producer can emit and any consumer
768
+ can read without translation. A Daftari vault *is* that pattern, so `daftari
769
+ okf` bridges the two directions.
770
+ [v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals/)
771
+ adds opt-in **trust signals** — raw credibility indicators (provenance,
772
+ verification, lifecycle, freshness), never computed scores — and Daftari maps
773
+ them from/to its native metadata.
710
774
 
711
- ## Belief archaeology
775
+ <details>
776
+ <summary><b>OKF export / import field-mapping and the <code>daftari okf</code> commands (▸ expand for full reference)</b></summary>
712
777
 
713
- Git is the version layer, so the vault can answer **"what did we believe on
714
- March 3?"** `daftari asof` is a read-only report over the repo's history — no
715
- checkout, no index, no API key:
778
+ **Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
779
+ concept doc (the core `type` / `title` / `description` / `resource` / `tags`
780
+ fields, plus a verbatim `daftari` sidecar for lossless round-trip), with
781
+ generated `index.md` (progressive-disclosure listing) and `log.md`
782
+ (chronological history). Trust signals derive from native metadata:
783
+ `updated`/`updated_by` become `generated`, the lifecycle maps to
784
+ `draft`/`stable`/`deprecated`, `ttl_days` becomes an absolute `stale_after`
785
+ date, and `sources` become structured entries. `verified` is never fabricated —
786
+ Daftari records authorship, not independent confirmations, so exported docs
787
+ honestly read as unverified. The source vault is never mutated.
716
788
 
717
789
  ```bash
718
- # The vault's belief state at a date (or any git ref), plus the drift since
719
- daftari asof 2026-03-03 --vault ./my-vault
790
+ daftari okf export ./my-vault --out ./okf-bundle
791
+ daftari okf export ./my-vault --out ./okf-bundle --collection pricing
792
+ ```
720
793
 
721
- # One document's trajectory: frontmatter then vs now, commits in between
722
- daftari asof HEAD~20 --doc pricing/helios-consumption-pricing.md
794
+ **Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
795
+ round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
796
+ (docs land as `draft` in the `accumulation` domain, the original OKF `type` is
797
+ preserved in an `okf_type` field). Trust signals inform the mapping: a
798
+ human-reviewed doc (a `human:*` entry in `verified`) imports with `confidence:
799
+ high`, `status: deprecated` stays `deprecated` (retired knowledge must not
800
+ resurface as a fresh draft), and `stale_after` converts to `ttl_days`. An
801
+ `Attested Computation` is surfaced in an import warning but **not**
802
+ auto-write-protected: `tier: source` is enforcement, and its only sanctioned
803
+ grant path is `vault_set_tier` (reason required, provenance-logged) — a foreign
804
+ bundle's self-declared `type` doesn't buy it. Review the doc, then elevate
805
+ deliberately. OKF fields with no lossless Daftari slot (the trust record,
806
+ attestation machinery) are preserved under `okf_*` keys. Writes auto-commit and
807
+ the index is rebuilt.
723
808
 
724
- # Counterfactual replay: this fact turned out wrong — who had inherited it
725
- # at the time, and where are they now?
726
- daftari asof 2026-03-03 --blast pricing/helios-consumption-pricing.md
809
+ ```bash
810
+ daftari okf import ./okf-bundle --into ./my-vault --dry-run
811
+ daftari okf import ./okf-bundle --into ./my-vault
727
812
  ```
728
813
 
729
- The default report shows the document and tension state at that point and
730
- the drift since: documents added/removed, `status`/`confidence` transitions,
731
- and tensions opened or resolved. `--blast` computes the blast radius of a
732
- document over the tree *as of the commit* (same source/link edge semantics as
733
- `vault_tension_blast`), annotating each downstream document with its status
734
- today — the post-mortem view for a fact that was later corrected. Markdown to
735
- stdout by default; `--output` / `--output-json` write files. Pairs with
736
- `vault_receipt`: a receipt's `vaultHead` is exactly the anchor to hand back
737
- to `asof`.
814
+ </details>
815
+
816
+ <!-- Reference / meta -->
817
+
818
+ ## What’s not in v1
819
+
820
+ Deliberately deferred to keep the surface tight:
821
+
822
+ - **Cloud-hosted multi-tenant SaaS** (self-hosted server mode HAS shipped —
823
+ see [Server mode](#server-mode-self-hosted) and
824
+ [Storage backing](#storage-backing); the project itself hosts nothing)
825
+ - **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
826
+ - **Background curation agent** running lint on a cadence
827
+ - **Enforced domain separation** (v1 documents the convention; v2 enforces it —
828
+ advisory boundary warnings shipped in the meantime: `vault_lint`'s
829
+ `domainLeaks` check and write-time `domain_warnings`)
830
+
831
+ (LLM reranking, deferred here originally, has since shipped as the opt-in
832
+ agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
833
+ fused candidate pool and the protocol; the calling agent is the judge.)
834
+
835
+ Each is a clean increment on a surface that already works.
738
836
 
739
837
  ## Development
740
838
 
@@ -756,7 +854,7 @@ Design tenets: functions and types, no classes; tool handlers return
756
854
  ## Integrations
757
855
 
758
856
  - [`integrations/langchain/`](integrations/langchain/) — `langchain-daftari`, a
759
- Python package that exposes the 14 daftari tools as LangChain `BaseTool`s
857
+ Python package that exposes all 35 daftari tools as LangChain `BaseTool`s
760
858
  for use with LangGraph / `create_react_agent`. Sync + async, schemas pulled
761
859
  live from `tools/list`.
762
860
  - [`packages/router`](packages/router) — multi-vault MCP router that fans out across N Daftari vaults
@@ -776,3 +874,4 @@ retention, and contact.
776
874
  ## License
777
875
 
778
876
  MIT.
877
+