daftari 1.32.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 (200) hide show
  1. package/CHANGELOG.md +123 -1
  2. package/README.md +472 -342
  3. package/dist/access/rbac.d.ts +1 -0
  4. package/dist/access/rbac.d.ts.map +1 -1
  5. package/dist/access/rbac.js +16 -0
  6. package/dist/access/rbac.js.map +1 -1
  7. package/dist/asof/index.d.ts.map +1 -1
  8. package/dist/asof/index.js +23 -2
  9. package/dist/asof/index.js.map +1 -1
  10. package/dist/asof/report.d.ts.map +1 -1
  11. package/dist/asof/report.js +24 -0
  12. package/dist/asof/report.js.map +1 -1
  13. package/dist/asof/snapshot.d.ts +7 -1
  14. package/dist/asof/snapshot.d.ts.map +1 -1
  15. package/dist/asof/snapshot.js +28 -1
  16. package/dist/asof/snapshot.js.map +1 -1
  17. package/dist/backfill/derive.d.ts.map +1 -1
  18. package/dist/backfill/derive.js +8 -0
  19. package/dist/backfill/derive.js.map +1 -1
  20. package/dist/canary/fixtures.d.ts +12 -0
  21. package/dist/canary/fixtures.d.ts.map +1 -0
  22. package/dist/canary/fixtures.js +132 -0
  23. package/dist/canary/fixtures.js.map +1 -0
  24. package/dist/canary/index.d.ts +16 -0
  25. package/dist/canary/index.d.ts.map +1 -0
  26. package/dist/canary/index.js +105 -0
  27. package/dist/canary/index.js.map +1 -0
  28. package/dist/canary/run.d.ts +39 -0
  29. package/dist/canary/run.d.ts.map +1 -0
  30. package/dist/canary/run.js +266 -0
  31. package/dist/canary/run.js.map +1 -0
  32. package/dist/canary/stats.d.ts +36 -0
  33. package/dist/canary/stats.d.ts.map +1 -0
  34. package/dist/canary/stats.js +143 -0
  35. package/dist/canary/stats.js.map +1 -0
  36. package/dist/canon/index.d.ts +15 -0
  37. package/dist/canon/index.d.ts.map +1 -0
  38. package/dist/canon/index.js +167 -0
  39. package/dist/canon/index.js.map +1 -0
  40. package/dist/canon/resolve.d.ts +12 -0
  41. package/dist/canon/resolve.d.ts.map +1 -0
  42. package/dist/canon/resolve.js +67 -0
  43. package/dist/canon/resolve.js.map +1 -0
  44. package/dist/canon/topic.d.ts +20 -0
  45. package/dist/canon/topic.d.ts.map +1 -0
  46. package/dist/canon/topic.js +81 -0
  47. package/dist/canon/topic.js.map +1 -0
  48. package/dist/canon/types.d.ts +37 -0
  49. package/dist/canon/types.d.ts.map +1 -0
  50. package/dist/canon/types.js +9 -0
  51. package/dist/canon/types.js.map +1 -0
  52. package/dist/cli.d.ts.map +1 -1
  53. package/dist/cli.js +6 -0
  54. package/dist/cli.js.map +1 -1
  55. package/dist/court/index.d.ts.map +1 -1
  56. package/dist/court/index.js +48 -0
  57. package/dist/court/index.js.map +1 -1
  58. package/dist/court/triage.d.ts +5 -0
  59. package/dist/court/triage.d.ts.map +1 -0
  60. package/dist/court/triage.js +71 -0
  61. package/dist/court/triage.js.map +1 -0
  62. package/dist/curation/lint-voice.d.ts +3 -0
  63. package/dist/curation/lint-voice.d.ts.map +1 -0
  64. package/dist/curation/lint-voice.js +87 -0
  65. package/dist/curation/lint-voice.js.map +1 -0
  66. package/dist/curation/lint.d.ts +5 -1
  67. package/dist/curation/lint.d.ts.map +1 -1
  68. package/dist/curation/lint.js +41 -5
  69. package/dist/curation/lint.js.map +1 -1
  70. package/dist/curation/read-heat.d.ts +16 -0
  71. package/dist/curation/read-heat.d.ts.map +1 -0
  72. package/dist/curation/read-heat.js +52 -0
  73. package/dist/curation/read-heat.js.map +1 -0
  74. package/dist/curation/structural.d.ts +1 -1
  75. package/dist/curation/structural.d.ts.map +1 -1
  76. package/dist/curation/structural.js +8 -7
  77. package/dist/curation/structural.js.map +1 -1
  78. package/dist/curation/tension-triage.d.ts +57 -0
  79. package/dist/curation/tension-triage.d.ts.map +1 -0
  80. package/dist/curation/tension-triage.js +155 -0
  81. package/dist/curation/tension-triage.js.map +1 -0
  82. package/dist/curation/validity.d.ts +20 -0
  83. package/dist/curation/validity.d.ts.map +1 -0
  84. package/dist/curation/validity.js +191 -0
  85. package/dist/curation/validity.js.map +1 -0
  86. package/dist/fence/detect.d.ts +10 -0
  87. package/dist/fence/detect.d.ts.map +1 -0
  88. package/dist/fence/detect.js +161 -0
  89. package/dist/fence/detect.js.map +1 -0
  90. package/dist/fence/index.d.ts +22 -0
  91. package/dist/fence/index.d.ts.map +1 -0
  92. package/dist/fence/index.js +117 -0
  93. package/dist/fence/index.js.map +1 -0
  94. package/dist/frontmatter/schema.d.ts.map +1 -1
  95. package/dist/frontmatter/schema.js +28 -1
  96. package/dist/frontmatter/schema.js.map +1 -1
  97. package/dist/frontmatter/types.d.ts +6 -1
  98. package/dist/frontmatter/types.d.ts.map +1 -1
  99. package/dist/frontmatter/types.js +8 -0
  100. package/dist/frontmatter/types.js.map +1 -1
  101. package/dist/holders/registry.d.ts +8 -0
  102. package/dist/holders/registry.d.ts.map +1 -0
  103. package/dist/holders/registry.js +18 -0
  104. package/dist/holders/registry.js.map +1 -0
  105. package/dist/holders/types.d.ts +10 -0
  106. package/dist/holders/types.d.ts.map +1 -0
  107. package/dist/holders/types.js +2 -0
  108. package/dist/holders/types.js.map +1 -0
  109. package/dist/index.d.ts.map +1 -1
  110. package/dist/index.js +10 -6
  111. package/dist/index.js.map +1 -1
  112. package/dist/interview/questions.d.ts.map +1 -1
  113. package/dist/interview/questions.js +41 -9
  114. package/dist/interview/questions.js.map +1 -1
  115. package/dist/resources.d.ts +27 -0
  116. package/dist/resources.d.ts.map +1 -0
  117. package/dist/resources.js +169 -0
  118. package/dist/resources.js.map +1 -0
  119. package/dist/search/current-source.d.ts +1 -0
  120. package/dist/search/current-source.d.ts.map +1 -1
  121. package/dist/search/current-source.js +3 -1
  122. package/dist/search/current-source.js.map +1 -1
  123. package/dist/search/hybrid.d.ts +6 -1
  124. package/dist/search/hybrid.d.ts.map +1 -1
  125. package/dist/search/hybrid.js +23 -4
  126. package/dist/search/hybrid.js.map +1 -1
  127. package/dist/search/reindex.d.ts.map +1 -1
  128. package/dist/search/reindex.js +48 -13
  129. package/dist/search/reindex.js.map +1 -1
  130. package/dist/search/valid-at-source.d.ts +25 -0
  131. package/dist/search/valid-at-source.d.ts.map +1 -0
  132. package/dist/search/valid-at-source.js +131 -0
  133. package/dist/search/valid-at-source.js.map +1 -0
  134. package/dist/serve/index.d.ts.map +1 -1
  135. package/dist/serve/index.js +58 -89
  136. package/dist/serve/index.js.map +1 -1
  137. package/dist/server.d.ts +3 -1
  138. package/dist/server.d.ts.map +1 -1
  139. package/dist/server.js +159 -11
  140. package/dist/server.js.map +1 -1
  141. package/dist/sleep/cycle.d.ts.map +1 -1
  142. package/dist/sleep/cycle.js +38 -6
  143. package/dist/sleep/cycle.js.map +1 -1
  144. package/dist/storage/index-db.d.ts +7 -1
  145. package/dist/storage/index-db.d.ts.map +1 -1
  146. package/dist/storage/index-db.js +133 -8
  147. package/dist/storage/index-db.js.map +1 -1
  148. package/dist/tools/canon.d.ts +3 -0
  149. package/dist/tools/canon.d.ts.map +1 -0
  150. package/dist/tools/canon.js +177 -0
  151. package/dist/tools/canon.js.map +1 -0
  152. package/dist/tools/consumes.d.ts.map +1 -1
  153. package/dist/tools/consumes.js +47 -1
  154. package/dist/tools/consumes.js.map +1 -1
  155. package/dist/tools/curation.d.ts +4 -0
  156. package/dist/tools/curation.d.ts.map +1 -1
  157. package/dist/tools/curation.js +647 -3
  158. package/dist/tools/curation.js.map +1 -1
  159. package/dist/tools/edge-staleness.d.ts.map +1 -1
  160. package/dist/tools/edge-staleness.js +115 -0
  161. package/dist/tools/edge-staleness.js.map +1 -1
  162. package/dist/tools/edges.d.ts.map +1 -1
  163. package/dist/tools/edges.js +94 -0
  164. package/dist/tools/edges.js.map +1 -1
  165. package/dist/tools/read.d.ts +14 -0
  166. package/dist/tools/read.d.ts.map +1 -1
  167. package/dist/tools/read.js +385 -6
  168. package/dist/tools/read.js.map +1 -1
  169. package/dist/tools/receipt.d.ts +1 -1
  170. package/dist/tools/receipt.d.ts.map +1 -1
  171. package/dist/tools/receipt.js +147 -2
  172. package/dist/tools/receipt.js.map +1 -1
  173. package/dist/tools/search.d.ts.map +1 -1
  174. package/dist/tools/search.js +456 -5
  175. package/dist/tools/search.js.map +1 -1
  176. package/dist/tools/staged-actions.d.ts +7 -0
  177. package/dist/tools/staged-actions.d.ts.map +1 -1
  178. package/dist/tools/staged-actions.js +106 -2
  179. package/dist/tools/staged-actions.js.map +1 -1
  180. package/dist/tools/themes.d.ts.map +1 -1
  181. package/dist/tools/themes.js +120 -0
  182. package/dist/tools/themes.js.map +1 -1
  183. package/dist/tools/tier1.d.ts.map +1 -1
  184. package/dist/tools/tier1.js +56 -0
  185. package/dist/tools/tier1.js.map +1 -1
  186. package/dist/tools/tier2.d.ts.map +1 -1
  187. package/dist/tools/tier2.js +111 -1
  188. package/dist/tools/tier2.js.map +1 -1
  189. package/dist/tools/witness.d.ts.map +1 -1
  190. package/dist/tools/witness.js +93 -0
  191. package/dist/tools/witness.js.map +1 -1
  192. package/dist/tools/write.d.ts +8 -0
  193. package/dist/tools/write.d.ts.map +1 -1
  194. package/dist/tools/write.js +391 -3
  195. package/dist/tools/write.js.map +1 -1
  196. package/dist/utils/config.d.ts +2 -0
  197. package/dist/utils/config.d.ts.map +1 -1
  198. package/dist/utils/config.js +74 -0
  199. package/dist/utils/config.js.map +1 -1
  200. package/package.json +5 -2
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`
@@ -93,6 +222,14 @@ deterministic summary flags, the vault's git HEAD as an as-of anchor, and a
93
222
  recomputable hash over the whole receipt. Attach it to the answer so any
94
223
  consumer can see what the answer stands on.
95
224
 
225
+ **Believe:** `vault_canon` — compute settled vs. contested belief across
226
+ holders over an emergent topic (params: `seed`, `holders?`, `as_of?`,
227
+ `depth?`). Returns a per-claim settled/contested classification, integrity
228
+ flags (`graph_completeness: "curated"`, `partial_visibility`, `unindexed`,
229
+ `ghost_holder_warning`), and an attached `vault_receipt` as the epistemic
230
+ anchor. Recorded, not omniscient: settled means no contradiction is on record,
231
+ not that none exists. Never auto-resolves.
232
+
96
233
  **Witness:** `vault_witness` — per-principal track records from the vault's
97
234
  own ledgers, priced by the wager schedule: write volume, live claims with
98
235
  open exposure, contested claims with stake at risk, the settled book
@@ -100,21 +237,30 @@ open exposure, contested claims with stake at risk, the settled book
100
237
  deterministic; includes the flat-curve monitor so a single-author vault is
101
238
  reported as uninformative rather than as signal.
102
239
 
240
+ <details>
241
+ <summary><b>The full per-category tool registry and the tool-tier config (▸ expand for full reference)</b></summary>
242
+
103
243
  **Search:** `vault_search` (hybrid BM25 + vector; hits carry their unresolved
104
244
  tensions inline and foreground the current source of superseded documents),
105
245
  `vault_search_related`, `vault_themes` (thematic clustering), `vault_reindex`
106
246
 
107
- **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)
108
250
 
109
- **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)
110
252
 
111
- **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)
112
254
 
113
255
  **Ratify:** `vault_stage_action`, `vault_ratify`
114
256
 
115
257
  The curation engine is advisory: `vault_lint` reports problems and
116
258
  `vault_tension_log` records contradictions. Neither auto-fixes anything. Every
117
- 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.
118
264
 
119
265
  ### Tool tiers
120
266
 
@@ -134,291 +280,157 @@ tools:
134
280
  `core` is the search-before-derive loop (`vault_search`, `vault_read`,
135
281
  `vault_write`, `vault_index`, `vault_lint`, `vault_status`); `standard` adds
136
282
  the full document lifecycle (append/promote/deprecate/supersede/merge,
137
- confidence and tier setters, propose/ratify) plus diagnostics; `full` is
138
- 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
139
285
  only changes what is *advertised* — calls to any registered tool still work,
140
286
  so an agent holding a cached tool name keeps working across a tier change.
141
287
  Unknown names in `include`/`exclude` warn at startup and are ignored, so a
142
288
  config written for a newer daftari still loads.
143
289
 
290
+ </details>
291
+
144
292
  **Evaluate (opt-in, requires an Anthropic API key):** `daftari eval` — scores how
145
293
  well an LLM can use the curation surface to answer multi-hop questions about the
146
294
  vault. See the [design spec](docs/superpowers/specs/2026-05-31-cortex-quality-metric-design.md)
147
295
  for the rationale and the cortex framing.
148
296
 
149
- ## Two kinds of knowledge
150
-
151
- Every document declares a `domain`. The distinction drives how the curation
152
- layer treats it.
297
+ ## Circadian memory
153
298
 
154
- **Accumulation** documents compile and compound. A competitive-intel note, a
155
- pricing breakdown, a researched comparison. Each write builds on the last.
156
- 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):
157
301
 
158
- **Generative** documents speculate. A moonshot sketch, a brainstorm, a “what
159
- 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
+ ```
160
306
 
161
- The same curation rules applied uniformly would either nag about every
162
- brainstorm or quietly trust every stale fact. The domain split lets the system
163
- 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.
164
314
 
165
- ## 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.
166
320
 
167
- No user-management system. Roles live in config, the server starts with one:
321
+ ## Tension Court
168
322
 
169
- ```yaml
170
- roles:
171
- analyst:
172
- read: [competitive-intel, pricing]
173
- write: [competitive-intel, _drafts]
174
- researcher:
175
- read: ["*"]
176
- write: [moonshot, _drafts]
177
- admin:
178
- read: ["*"]
179
- write: ["*"]
180
- promote: true
181
- ratify: true # may approve/reject staged actions and contest edges
182
- ```
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.
183
329
 
184
- No `--role` or an unknown name falls back to deny-all. An agent identity is
185
- just a role too — e.g. a `curation-loop` role that reads and writes but leaves
186
- `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.
187
334
 
188
- ## File format
335
+ ```bash
336
+ # The docket — a 5-minute weekly ritual
337
+ daftari court --vault ./my-vault
189
338
 
190
- Markdown with YAML frontmatter. Frontmatter is the metadata layer; there is no
191
- separate database.
339
+ # One case's full brief (verbatim rationales from cited precedents)
340
+ daftari court --tension tension-abc123
192
341
 
193
- ```yaml
194
- ---
195
- title: "Aurora Pipelines — Positioning Overview"
196
- domain: accumulation
197
- collection: competitive-intel
198
- status: canonical
199
- confidence: medium
200
- created: 2026-05-17
201
- updated: 2026-05-17
202
- updated_by: agent:claude-code
203
- provenance: synthesized
204
- sources:
205
- - aurora-product-page
206
- ttl_days: 120
207
- tags: [aurora, ingestion, competitive]
208
- questions_answered:
209
- - "How does Aurora frame the ingestion/transformation boundary?"
210
- questions_raised:
211
- - "Does an authored-pipeline model slow teams down at small scale?"
212
- ---
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."
213
345
  ```
214
346
 
215
- Documents can make their epistemic edges explicit: `questions_answered` is what
216
- later agents can take as settled, `questions_raised` is where to build next.
217
- `vault_lint` turns the open questions across the vault into a coverage map.
218
-
219
- Full field reference in <docs/file-format.md>.
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.
220
353
 
221
- ## Adopting an existing vault
354
+ ## The principal interview
222
355
 
223
- Already have a wiki or an Obsidian vault? Daftari adopts it **in place** — it
224
- indexes and curates the same markdown files you already edit, not a separate copy.
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:
225
361
 
226
362
  ```bash
227
- # Dry run — see what would change, write nothing
228
- daftari import obsidian ~/my-vault --plan
363
+ # The sheet — read-only, priority-ordered
364
+ daftari interview --vault ./my-vault
229
365
 
230
- # Adopt one folder at a time (per-folder ratification; --yes to skip the prompt)
231
- daftari import obsidian ~/my-vault --apply --scope notes
366
+ # Sit for it. Answers are recorded VERBATIM; empty skips, 'q' ends.
367
+ daftari interview ask --vault ./my-vault
232
368
  ```
233
369
 
234
- The import is non-destructive to your content. It fills only the *missing*
235
- Daftari frontmatter — collection from the folder, dates from git history (or file
236
- mtime), sensible defaults for the rest — and preserves everything you already
237
- had, including custom frontmatter fields. Obsidian specifics: inline `#tags` are
238
- merged into `tags`, a Web Clipper `source` is mapped into `sources`, and
239
- `[[wikilinks]]` are left untouched (Daftari resolves them as written). Filling
240
- frontmatter is deliberate, not automatic — re-run the import to pick up newly
241
- added notes.
242
-
243
- ### Cloud-synced vaults (iCloud, Dropbox, …)
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.
244
378
 
245
- Daftari versions every change with git, and a `.git/` directory churning inside a
246
- cloud-synced folder can corrupt. For a synced vault, keep git's data outside it:
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.
247
383
 
248
- ```bash
249
- daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
250
- --apply --scope notes --external-git-dir
251
- ```
384
+ ## Belief archaeology
252
385
 
253
- This writes `git_dir: external` to `.daftari/config.yaml`, so Daftari uses
254
- `git init --separate-git-dir`: only a tiny static `.git` *file* stays in the vault
255
- (syncs harmlessly) while the repo data lives under `~/.local/share/daftari/git/`.
256
- Pass `--external-git-dir=/path` for an explicit location, or set `git_dir`
257
- directly in config to apply the same to any vault. History is per-device; your
258
- notes still sync everywhere.
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:
259
389
 
260
- ### Lower-level: `backfill`
390
+ ```bash
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
261
393
 
262
- `daftari import obsidian` is a thin, Obsidian-aware wrapper over `daftari
263
- backfill` — the git-driven frontmatter migration that works on any markdown wiki.
264
- Use it directly for non-Obsidian trees:
394
+ # One document's trajectory: frontmatter then vs now, commits in between
395
+ daftari asof HEAD~20 --doc pricing/helios-consumption-pricing.md
265
396
 
266
- ```bash
267
- daftari backfill --plan
268
- daftari backfill --apply --scope specs
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
269
400
  ```
270
401
 
271
- ## Open Knowledge Format (OKF)
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`.
272
411
 
273
- [OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
274
- is Google Cloud's vendor-neutral spec for the LLM-wiki pattern: a directory of
275
- markdown files with YAML frontmatter that any producer can emit and any consumer
276
- can read without translation. A Daftari vault *is* that pattern, so `daftari
277
- okf` bridges the two directions.
278
- [v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals/)
279
- adds opt-in **trust signals** — raw credibility indicators (provenance,
280
- verification, lifecycle, freshness), never computed scores — and Daftari maps
281
- them from/to its native metadata.
282
-
283
- **Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
284
- concept doc (the core `type` / `title` / `description` / `resource` / `tags`
285
- fields, plus a verbatim `daftari` sidecar for lossless round-trip), with
286
- generated `index.md` (progressive-disclosure listing) and `log.md`
287
- (chronological history). Trust signals derive from native metadata:
288
- `updated`/`updated_by` become `generated`, the lifecycle maps to
289
- `draft`/`stable`/`deprecated`, `ttl_days` becomes an absolute `stale_after`
290
- date, and `sources` become structured entries. `verified` is never fabricated —
291
- Daftari records authorship, not independent confirmations, so exported docs
292
- honestly read as unverified. The source vault is never mutated.
293
-
294
- ```bash
295
- daftari okf export ./my-vault --out ./okf-bundle
296
- daftari okf export ./my-vault --out ./okf-bundle --collection pricing
297
- ```
298
-
299
- **Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
300
- round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
301
- (docs land as `draft` in the `accumulation` domain, the original OKF `type` is
302
- preserved in an `okf_type` field). Trust signals inform the mapping: a
303
- human-reviewed doc (a `human:*` entry in `verified`) imports with `confidence:
304
- high`, `status: deprecated` stays `deprecated` (retired knowledge must not
305
- resurface as a fresh draft), and `stale_after` converts to `ttl_days`. An
306
- `Attested Computation` is surfaced in an import warning but **not**
307
- auto-write-protected: `tier: source` is enforcement, and its only sanctioned
308
- grant path is `vault_set_tier` (reason required, provenance-logged) — a foreign
309
- bundle's self-declared `type` doesn't buy it. Review the doc, then elevate
310
- deliberately. OKF fields with no lossless Daftari slot (the trust record,
311
- attestation machinery) are preserved under `okf_*` keys. Writes auto-commit and
312
- the index is rebuilt.
313
-
314
- ```bash
315
- daftari okf import ./okf-bundle --into ./my-vault --dry-run
316
- daftari okf import ./okf-bundle --into ./my-vault
317
- ```
318
-
319
- ## Server mode (self-hosted)
320
-
321
- By default daftari is a per-user stdio process. `daftari serve` starts the
322
- same vault as **one always-on instance over Streamable HTTP** — for a team, or
323
- for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
324
-
325
- ```bash
326
- daftari serve --vault ./my-vault # http://127.0.0.1:8787/mcp
327
- daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
328
- ```
329
-
330
- Identity is **per MCP session**, resolved when the session opens, so every
331
- RBAC and existence-disclosure rule applies per connection with zero tool
332
- changes. Two composable auth schemes, both declared in config:
333
-
334
- ```yaml
335
- server:
336
- transport_security: external # required off-loopback: TLS terminates upstream
337
- auth:
338
- tokens: # static bearer tokens (agents, ETL)
339
- - env: DAFTARI_TOKEN_ETL # the VALUE lives in this env var, never in config
340
- user: agent:etl
341
- role: admin
342
- oauth: # OAuth 2.1 resource server (humans via your IdP)
343
- issuer: https://idp.example.com
344
- audience: daftari
345
- jwks_uri: https://idp.example.com/.well-known/jwks.json
346
- subjects:
347
- "alice@example.com": { user: human:alice, role: analyst }
348
- ```
349
-
350
- The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
351
- to start without auth **and** the explicit `transport_security: external`
352
- acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
353
- balancer in front); with any auth configured, a bad or missing credential is
354
- a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
355
- neither ever becomes the guest. Guest sessions exist only in the no-auth
356
- loopback configuration. A running server also refuses to be silently killed:
357
- stray stdio invocations against the same vault refuse to start, and replacing
358
- a live holder requires a deliberate `daftari serve --takeover`.
359
-
360
- ## Storage backing
361
-
362
- A self-hosted vault can push to durable object storage (#6). The local git
363
- working copy stays canonical — reads, writes, auto-commits, locks, and the
364
- index all stay exactly as above — and the backing is a dumb sync target:
365
-
366
- ```yaml
367
- # .daftari/config.yaml
368
- storage:
369
- backend: s3 # fs | s3 | azure
370
- bucket: team-vault
371
- region: us-east-1
372
- # endpoint: https://… # MinIO / R2 / GCS S3-interop endpoints
373
- # sync_interval_minutes: 15 # daftari serve pushes on this cadence
374
- ```
375
-
376
- ```bash
377
- daftari sync --vault ./my-vault # incremental push
378
- daftari sync --vault ./my-vault --dry-run # show the diff only
379
- daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
380
- ```
381
-
382
- The push covers the markdown tree, the `.git` directory, and durable
383
- `.daftari` journals; the rebuildable SQLite index and lock files never sync.
384
- Neither do `.git/config` and `.git/hooks` — git *executes* what those
385
- declare, and a backup channel must not deliver code (`git clone` refuses to
386
- transmit them for the same reason), so re-add remotes and local git config
387
- by hand after a restore.
388
- Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
389
- as optional dependencies — install the one you use; credentials come from the
390
- SDK's standard environment chain, never from vault config. GCS is reached via
391
- its S3-interoperability endpoint. Restore refuses non-empty directories and
392
- reindexes when done.
412
+ ## The vault as witness — and the wager layer
393
413
 
394
- ## How it compares
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.
395
424
 
396
- | |AGENTS.md |RAG |Daftari |
397
- |--------------------|-----------------|-----------------------------|-------------------------------------|
398
- |Who writes? |Humans |Nobody (retrieval only) |Agents + humans |
399
- |Scales? |One file, doesn’t|Scales storage, not coherence|Structured collections with lifecycle|
400
- |Knowledge compounds?|No |No |Yes, draft → canonical → deprecated |
401
- |Contradictions? |Invisible |Invisible |Tension log surfaces them |
402
- |Staleness? |Silent |Silent |TTL-based decay with advisory lint |
425
+ <details>
426
+ <summary><b>The two kill conditions that travel with the tool (▸ expand for full reference)</b></summary>
403
427
 
404
- ## What’s not in v1
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).
405
432
 
406
- Deliberately deferred to keep the surface tight:
407
-
408
- - **Cloud-hosted multi-tenant SaaS** (self-hosted server mode HAS shipped —
409
- see [Server mode](#server-mode-self-hosted) and
410
- [Storage backing](#storage-backing); the project itself hosts nothing)
411
- - **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
412
- - **Background curation agent** running lint on a cadence
413
- - **Enforced domain separation** (v1 documents the convention; v2 enforces it —
414
- advisory boundary warnings shipped in the meantime: `vault_lint`'s
415
- `domainLeaks` check and write-time `domain_warnings`)
416
-
417
- (LLM reranking, deferred here originally, has since shipped as the opt-in
418
- agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
419
- fused candidate pool and the protocol; the calling agent is the judge.)
420
-
421
- Each is a clean increment on a surface that already works.
433
+ </details>
422
434
 
423
435
  ## Coherence audit
424
436
 
@@ -485,6 +497,9 @@ staleness check still runs over the in-repo link graph.
485
497
  Catches the case where you keep touching an index page while the docs it
486
498
  links to are rotting.
487
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
+
488
503
  ### Sample output
489
504
 
490
505
  ```markdown
@@ -579,131 +594,245 @@ fail_on:
579
594
  transitive_staleness: 100 # default: generous; teams tune
580
595
  ```
581
596
 
582
- ## The vault as witness — and the wager layer
597
+ </details>
583
598
 
584
- Every write already carries an identity, every proposal an outcome, every
585
- tension a logger and a ruling. `vault_witness` aggregates that ledger into a
586
- **track record per principal** — and prices it. Confidence is free to claim,
587
- so the wager schedule makes it cost something: writing at `high` stakes 3
588
- points, `medium` 1, `low` 0 (hedged claims are the honest default and are
589
- never taxed). A claim later corrected by a ruling or retired by someone else
590
- burns the stake; a claim maintained through a full TTL cycle earns credit.
591
- The balance is arithmetic on recorded facts — advisory, provisional
592
- constants, nothing enforced: routing a high-stakes write to the agent with
593
- the earned balance is your policy, not the vault's. Both kill conditions
594
- from the design travel with the tool: the flat-curve monitor (one author ≥95%
595
- of writes → curves declared uninformative) and the longitudinal write-volume
596
- series (if stake-fear suppresses honest claims, it shows up here first).
599
+ <!-- Running it -->
597
600
 
598
- ## Circadian memory
601
+ ## Access control
599
602
 
600
- The vault sleeps. `daftari sleep` is the nightly metabolic pass — deterministic,
601
- 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):
602
633
 
603
634
  ```bash
604
- # In cron (any scheduler works; daftari ships the cycle, not a daemon):
605
- 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
606
637
  ```
607
638
 
608
- The cycle sweeps expired staged actions, scores every document's decay, and
609
- builds the **wake list**: canonical accumulation documents past their TTL
610
- with downstream dependents, ranked by blast radius. The list is written to
611
- `.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
612
- document against its sources, stage the diff — because the vault never
613
- re-verifies on its own. Generative documents going stale are expected, not a
614
- 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.
615
642
 
616
- The **Morning Report** ends where the human begins: tension aging and the
617
- court docket head, the ratification queue with soon-to-expire proposals, and
618
- the rubber-stamp monitor — zero rejections over a long decision history is
619
- printed as a warning, not a compliment. The agent proposes overnight; you
620
- 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>
621
645
 
622
- ## 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
+ ```
623
661
 
624
- Tensions wait in a log; the court turns them into decidable cases. `daftari
625
- court` compiles a **docket** — every open tension briefed and ranked (stale
626
- first, then by blast radius): both sides' claims, the present state of their
627
- documents, the downstream stakes, cluster membership, and **precedents** —
628
- past rulings on disputes that shared a document, a collection pair, or a
629
- 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
+ ```
630
692
 
631
693
  ```bash
632
- # The docket — a 5-minute weekly ritual
633
- 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
+ ```
634
698
 
635
- # One case's full brief (verbatim rationales from cited precedents)
636
- 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.
637
710
 
638
- # Rule. The rationale is recorded verbatim and cited by future dockets.
639
- daftari court rule tension-abc123 --kind corrected \
640
- --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
641
724
  ```
642
725
 
643
- Rulings go through the same `resolveTension` write path as
644
- `vault_tension_resolve` — a ruling records the closure, it never edits the
645
- disputed documents. Precedent retrieval is deterministic (shared-document >
646
- collection-pair > same-kind; no LLM): the court retrieves how this house has
647
- resolved similar disputes before, and whether a precedent applies stays the
648
- 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.
649
734
 
650
- ## The principal interview
735
+ ### Cloud-synced vaults (iCloud, Dropbox, …)
651
736
 
652
- The vault interrogates you. `daftari interview` assembles a question sheet
653
- from what the vault already knows is unclear — open tensions (contested
654
- first, longest-carried first), canonical accumulation docs past their TTL,
655
- and `questions_raised` entries no document answers — deterministic and
656
- 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:
657
739
 
658
740
  ```bash
659
- # The sheet — read-only, priority-ordered
660
- daftari interview --vault ./my-vault
741
+ daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
742
+ --apply --scope notes --external-git-dir
743
+ ```
661
744
 
662
- # Sit for it. Answers are recorded VERBATIM; empty skips, 'q' ends.
663
- 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
664
761
  ```
665
762
 
666
- Answered questions become a transcript document in an `interviews/`
667
- collection — `tier: source` (your words, body immutable), `provenance:
668
- direct`, no TTL (testimony doesn't expire) — committed like any other write,
669
- with `sources` tracing each question back to the tension or document that
670
- prompted it. The pattern is the companion interview on a living-summary
671
- page: the compiler's highest-value move is not more compilation, it is
672
- asking the principal about the unclear spots and folding the verbatim
673
- answers back into the corpus.
763
+ ## Open Knowledge Format (OKF)
674
764
 
675
- Recording testimony resolves nothing. The transcript is *evidence*: the CLI
676
- ends by pointing at `daftari court rule <id> --references <transcript>` for
677
- tensions it touched, and at re-verified writes for stale docs. Operator-only,
678
- 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.
679
774
 
680
- ## 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>
681
777
 
682
- Git is the version layer, so the vault can answer **"what did we believe on
683
- March 3?"** `daftari asof` is a read-only report over the repo's history — no
684
- 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.
685
788
 
686
789
  ```bash
687
- # The vault's belief state at a date (or any git ref), plus the drift since
688
- 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
+ ```
689
793
 
690
- # One document's trajectory: frontmatter then vs now, commits in between
691
- 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.
692
808
 
693
- # Counterfactual replay: this fact turned out wrong — who had inherited it
694
- # at the time, and where are they now?
695
- 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
696
812
  ```
697
813
 
698
- The default report shows the document and tension state at that point and
699
- the drift since: documents added/removed, `status`/`confidence` transitions,
700
- and tensions opened or resolved. `--blast` computes the blast radius of a
701
- document over the tree *as of the commit* (same source/link edge semantics as
702
- `vault_tension_blast`), annotating each downstream document with its status
703
- today — the post-mortem view for a fact that was later corrected. Markdown to
704
- stdout by default; `--output` / `--output-json` write files. Pairs with
705
- `vault_receipt`: a receipt's `vaultHead` is exactly the anchor to hand back
706
- 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.
707
836
 
708
837
  ## Development
709
838
 
@@ -725,7 +854,7 @@ Design tenets: functions and types, no classes; tool handlers return
725
854
  ## Integrations
726
855
 
727
856
  - [`integrations/langchain/`](integrations/langchain/) — `langchain-daftari`, a
728
- 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
729
858
  for use with LangGraph / `create_react_agent`. Sync + async, schemas pulled
730
859
  live from `tools/list`.
731
860
  - [`packages/router`](packages/router) — multi-vault MCP router that fans out across N Daftari vaults
@@ -745,3 +874,4 @@ retention, and contact.
745
874
  ## License
746
875
 
747
876
  MIT.
877
+