daftari 3.11.0 → 3.12.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 (97) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +210 -937
  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 +5 -0
  6. package/dist/access/rbac.js.map +1 -1
  7. package/dist/distill/state.d.ts +9 -1
  8. package/dist/distill/state.d.ts.map +1 -1
  9. package/dist/distill/state.js +58 -7
  10. package/dist/distill/state.js.map +1 -1
  11. package/dist/eval/llm-openrouter.d.ts.map +1 -1
  12. package/dist/eval/llm-openrouter.js +5 -22
  13. package/dist/eval/llm-openrouter.js.map +1 -1
  14. package/dist/index.d.ts +1 -1
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +47 -14
  17. package/dist/index.js.map +1 -1
  18. package/dist/integrations/distill.d.ts +16 -0
  19. package/dist/integrations/distill.d.ts.map +1 -0
  20. package/dist/integrations/distill.js +164 -0
  21. package/dist/integrations/distill.js.map +1 -0
  22. package/dist/integrations/engine.d.ts +134 -0
  23. package/dist/integrations/engine.d.ts.map +1 -0
  24. package/dist/integrations/engine.js +571 -0
  25. package/dist/integrations/engine.js.map +1 -0
  26. package/dist/integrations/google.d.ts +13 -0
  27. package/dist/integrations/google.d.ts.map +1 -0
  28. package/dist/integrations/google.js +551 -0
  29. package/dist/integrations/google.js.map +1 -0
  30. package/dist/integrations/notion.d.ts +16 -0
  31. package/dist/integrations/notion.d.ts.map +1 -0
  32. package/dist/integrations/notion.js +485 -0
  33. package/dist/integrations/notion.js.map +1 -0
  34. package/dist/integrations/oauth.d.ts +14 -0
  35. package/dist/integrations/oauth.d.ts.map +1 -0
  36. package/dist/integrations/oauth.js +141 -0
  37. package/dist/integrations/oauth.js.map +1 -0
  38. package/dist/integrations/queue.d.ts +30 -0
  39. package/dist/integrations/queue.d.ts.map +1 -0
  40. package/dist/integrations/queue.js +255 -0
  41. package/dist/integrations/queue.js.map +1 -0
  42. package/dist/integrations/review.d.ts +5 -0
  43. package/dist/integrations/review.d.ts.map +1 -0
  44. package/dist/integrations/review.js +36 -0
  45. package/dist/integrations/review.js.map +1 -0
  46. package/dist/integrations/routes.d.ts +26 -0
  47. package/dist/integrations/routes.d.ts.map +1 -0
  48. package/dist/integrations/routes.js +258 -0
  49. package/dist/integrations/routes.js.map +1 -0
  50. package/dist/integrations/runtime.d.ts +33 -0
  51. package/dist/integrations/runtime.d.ts.map +1 -0
  52. package/dist/integrations/runtime.js +280 -0
  53. package/dist/integrations/runtime.js.map +1 -0
  54. package/dist/integrations/state.d.ts +10 -0
  55. package/dist/integrations/state.d.ts.map +1 -0
  56. package/dist/integrations/state.js +238 -0
  57. package/dist/integrations/state.js.map +1 -0
  58. package/dist/integrations/types.d.ts +45 -0
  59. package/dist/integrations/types.d.ts.map +1 -0
  60. package/dist/integrations/types.js +4 -0
  61. package/dist/integrations/types.js.map +1 -0
  62. package/dist/lifecycle/lock.d.ts.map +1 -1
  63. package/dist/lifecycle/lock.js +15 -1
  64. package/dist/lifecycle/lock.js.map +1 -1
  65. package/dist/search/coverage.d.ts.map +1 -1
  66. package/dist/search/coverage.js +5 -5
  67. package/dist/search/coverage.js.map +1 -1
  68. package/dist/search/graph-expansion.d.ts +55 -0
  69. package/dist/search/graph-expansion.d.ts.map +1 -0
  70. package/dist/search/graph-expansion.js +160 -0
  71. package/dist/search/graph-expansion.js.map +1 -0
  72. package/dist/search/hybrid.d.ts +4 -0
  73. package/dist/search/hybrid.d.ts.map +1 -1
  74. package/dist/search/hybrid.js.map +1 -1
  75. package/dist/serve/index.d.ts +5 -0
  76. package/dist/serve/index.d.ts.map +1 -1
  77. package/dist/serve/index.js +239 -17
  78. package/dist/serve/index.js.map +1 -1
  79. package/dist/serve/limits.d.ts +13 -0
  80. package/dist/serve/limits.d.ts.map +1 -1
  81. package/dist/serve/limits.js +36 -0
  82. package/dist/serve/limits.js.map +1 -1
  83. package/dist/tools/board.test.js +1 -0
  84. package/dist/tools/board.test.js.map +1 -1
  85. package/dist/tools/search.d.ts.map +1 -1
  86. package/dist/tools/search.js +31 -3
  87. package/dist/tools/search.js.map +1 -1
  88. package/dist/utils/config.d.ts +15 -0
  89. package/dist/utils/config.d.ts.map +1 -1
  90. package/dist/utils/config.js +162 -4
  91. package/dist/utils/config.js.map +1 -1
  92. package/dist/utils/vault-gitignore.d.ts +1 -1
  93. package/dist/utils/vault-gitignore.d.ts.map +1 -1
  94. package/dist/utils/vault-gitignore.js +23 -3
  95. package/dist/utils/vault-gitignore.js.map +1 -1
  96. package/package.json +2 -2
  97. package/templates/config.yaml +3 -0
package/README.md CHANGED
@@ -2,157 +2,182 @@
2
2
 
3
3
  [![CI](https://github.com/mavaali/daftari/actions/workflows/ci.yml/badge.svg)](https://github.com/mavaali/daftari/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/daftari.svg)](https://www.npmjs.com/package/daftari) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
4
4
 
5
- *Daftari* (دفتری) is the Urdu word for a ledger-keeper: the person in a
6
- trading house who maintained the *daftar*, the bound register where every
7
- transaction was recorded, cross-referenced, and preserved. The daftar was not a
8
- filing cabinet. It was a living document. Entries referenced earlier entries.
9
- Corrections were noted, not erased. The ledger got more valuable the longer it
10
- was kept, because the accumulated record revealed patterns no single entry
11
- could.
5
+ **Durable, inspectable memory for AI agents.** Daftari exposes a markdown vault
6
+ over the Model Context Protocol (MCP), then adds the controls an agent needs to
7
+ use that vault without flattening its history: provenance, supersession,
8
+ staleness, open contradictions, access control, and Git-backed writes.
12
9
 
13
- Daftari is the **long-term memory cortex for your LLM agents** — a persistent,
14
- structured vault they read, write, and curate over time, **portable across any
15
- model.** A cortex, not a clipboard.
10
+ The model is replaceable. The memory stays yours: plain files on disk, readable
11
+ without Daftari and portable across MCP clients.
16
12
 
17
- ## Contents
13
+ *Daftari* (دفتری) is Urdu for a ledger-keeper. The model is deliberate: a
14
+ ledger records corrections instead of erasing them, and becomes more useful as
15
+ its cross-referenced history accumulates.
18
16
 
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) · [The viewer](#the-viewer) · [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) · [Cross-vault federation](#cross-vault-federation) · [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
-
31
- ## Rent the brain, own the memory
32
-
33
- LLMs are stateless; they forget. So memory is being bolted on everywhere — but
34
- *inside the model*: ChatGPT memory, Claude projects, Copilot, Gemini. Memory is
35
- becoming a feature of the provider, and whoever holds your memory holds you.
36
-
37
- Daftari takes the other path. The model is the rented part — swappable, obsolete
38
- in six months. Your memory is the durable asset, so it should belong to you and
39
- travel with you: plain markdown on your disk, under git, readable in any editor,
40
- queryable by any agent. **Compilation over retrieval** — the agent compiles an
41
- answer once and writes it back, so every later read starts from the compiled
42
- result instead of re-stitching chunks from zero.
43
-
44
- ## Not a second brain
45
-
46
- Second brains are memory for a *human* to think with — you catch the stale fact,
47
- you notice the contradiction. Daftari is memory for an *agent* to reason with:
48
- the persistence layer for a consumer that acts on what it is handed and cannot
49
- sanity-check it first. Same substrate (markdown, links); reversed purpose — and
50
- a higher bar, because the reliability has to live in the memory, not the reader.
51
-
52
- ## It remembers — it doesn't resolve for you
17
+ ```bash
18
+ npx daftari --init ./my-vault
19
+ ```
53
20
 
54
- Because the agent can't infer them, the vault carries three things and collapses
55
- none:
21
+ ## Choose your path
56
22
 
57
- - **what's current** — supersession follows a real edge to the latest source
58
- - **what's grounded** — provenance on every entry; the vault never mints a value
59
- - **what's contested** — contradictions surface as *tensions*, held open, not
60
- flattened into a false answer
23
+ | I want to… | Start here |
24
+ |---|---|
25
+ | Create a vault and connect an MCP client | [Five-minute quickstart](#five-minute-quickstart) |
26
+ | Adopt an Obsidian vault or existing markdown wiki | [Adopt existing notes](docs/adoption.md) |
27
+ | See how knowledge compounds instead of being repeatedly retrieved | [Worked example](docs/worked-example.md) |
28
+ | Run the curation loop | [Curation workflow](docs/curation-workflow.md) |
29
+ | Review tensions, stale beliefs, or historical state | [Operator workflows](docs/operator-workflows.md) |
30
+ | Configure access, HTTP serving, federation, or storage | [Deployment and access](docs/deployment.md) |
31
+ | Continuously distill Google Docs or Notion | [Source integrations](docs/integrations.md) |
32
+ | Understand the design and its boundaries | [Architecture](docs/architecture.md) |
33
+ | Look up frontmatter fields | [File format](docs/file-format.md) |
34
+ | Find the rest of the documentation | [Documentation map](docs/README.md) |
61
35
 
62
- The daftar noted corrections rather than erasing them. Daftari keeps that as a
63
- law:
36
+ ## Five-minute quickstart
64
37
 
65
- > **A tension may never masquerade as a supersession.**
38
+ **Prerequisite:** Node.js 20 or newer.
66
39
 
67
- It resolves only by discovery — a real edge — never by invention. The agent
68
- compiles; the vault preserves; *you* keep the judgment. See
69
- [the manifesto](docs/manifesto.md) for the full argument.
40
+ ### 1. Create a vault
70
41
 
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]
42
+ ```bash
43
+ npx daftari --init ./my-vault
76
44
  ```
77
45
 
78
- ## How it compares
46
+ Daftari creates a Git-backed vault with a config file, four starter
47
+ collections, and three fictional example documents. The markdown is the source
48
+ of truth; `.daftari/index.db` is a rebuildable search index.
79
49
 
80
- The real question a memory layer has to answer: **what happens when two facts
81
- contradict?**
50
+ ### 2. Connect an MCP client
82
51
 
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** |
52
+ Add Daftari to your MCP client configuration. For Claude Desktop on macOS,
53
+ edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
98
54
 
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.
55
+ ```json
56
+ {
57
+ "mcpServers": {
58
+ "daftari": {
59
+ "command": "npx",
60
+ "args": [
61
+ "-y",
62
+ "daftari@latest",
63
+ "--vault",
64
+ "/absolute/path/to/my-vault",
65
+ "--user",
66
+ "me",
67
+ "--role",
68
+ "admin"
69
+ ]
70
+ }
71
+ }
72
+ }
73
+ ```
105
74
 
106
- <!-- Concepts -->
75
+ Use an absolute vault path, then restart the client. The scaffolded config
76
+ includes an `admin` role. Omitting `--role`, or naming a role that does not
77
+ exist, starts Daftari as a deny-all guest.
107
78
 
108
- ## What it is
79
+ ### 3. Ask the vault a question
109
80
 
110
- A directory of markdown files with YAML frontmatter, exposed to agents as 38
111
- MCP tools over stdio. The vault is plain text: you can read it in any editor,
112
- `git log` it, grep it. Daftari adds the machinery agents need to treat it as a
113
- shared workspace.
81
+ Try a request that forces the agent to search before answering:
114
82
 
115
- ```
116
- npx daftari --init ./my-vault
117
- npx daftari --vault ./my-vault --user me --role admin
118
- ```
83
+ > Search my Daftari vault for the current Helios pricing model. Cite the source
84
+ > document and tell me whether it is stale or contested.
119
85
 
120
- Point any MCP client (Claude Desktop, Claude Code, an agent SDK) at it.
86
+ The agent should search the example vault, read the matching markdown, and
87
+ report the document's standing rather than returning an unqualified snippet.
121
88
 
122
- ## The four layers
89
+ Next, ask it to write a draft:
123
90
 
124
- All four implement one idea — *resolve only by discovery, never by invention.*
125
- Read [**The core idea**](docs/architecture.md#the-core-idea) first and the layers
126
- become its consequences. Storage and access control are table stakes; the moat is
127
- layers 3 and 4.
91
+ > Create a low-confidence draft that compares the Helios and Aurora examples.
92
+ > Preserve the source links and list the questions the draft cannot answer.
128
93
 
129
- |Layer |What it does |Why it matters |
130
- |---------------------|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
131
- |**Storage** |Markdown + frontmatter on disk, git history, rebuildable SQLite index for hybrid BM25 + vector search.|Plain text is the source of truth. Delete every `.db` file and rebuild.|
132
- |**Access control** |Config-driven RBAC. Roles and per-collection read/write/promote permissions in `.daftari/config.yaml`.|Multiple agents, scoped access, no user-management system. |
133
- |**Write arbitration**|File-level locks (60s TTL), auto-commit to git, structured provenance log. |Concurrent agents write safely. Every mutation is attributable. |
134
- |**Curation** |Draft-to-canonical lifecycle, TTL-based staleness, tension logging, advisory linter. |Knowledge that stops being true gets surfaced, not silently trusted. |
94
+ Every mutation is written to markdown, recorded in provenance, indexed, and
95
+ committed to Git. Continue through promotion, retirement, and tension handling
96
+ in the [full getting-started walkthrough](docs/getting-started.md).
135
97
 
136
- ## Two kinds of knowledge
98
+ ## The problem Daftari solves
137
99
 
138
- Every document declares a `domain`. The distinction drives how the curation
139
- layer treats it.
100
+ Agents do not merely need stored text. They need to know what they can trust
101
+ when the text changes, conflicts, or loses its grounding.
140
102
 
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.
103
+ Daftari keeps three judgments separate:
144
104
 
145
- **Generative** documents speculate. A moonshot sketch, a brainstorm, a “what
146
- if.” Going stale is expected, not a defect.
105
+ - **What is current.** A supersession follows an explicit edge to a successor;
106
+ recency alone does not make a claim true.
107
+ - **What is grounded.** Sources and provenance remain attached to the document;
108
+ the vault does not manufacture evidence.
109
+ - **What is contested.** When live claims disagree and neither replaces the
110
+ other, the contradiction remains visible as a tension.
147
111
 
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.
112
+ That gives the system one governing rule:
151
113
 
152
- ## File format
114
+ > **A tension may never masquerade as a supersession.**
153
115
 
154
- Markdown with YAML frontmatter. Frontmatter is the metadata layer; there is no
155
- separate database.
116
+ ```mermaid
117
+ flowchart TD
118
+ A[Two live claims disagree] --> B{Does one explicitly<br/>supersede the other?}
119
+ B -- yes --> C[Follow the successor<br/>preserve the lineage]
120
+ B -- no --> D[Keep both live<br/>surface an open tension]
121
+ ```
122
+
123
+ The longer argument—including why memory should outlive the model renting
124
+ it—lives in the [manifesto](docs/manifesto.md). The implementation boundaries
125
+ live in the [architecture guide](docs/architecture.md).
126
+
127
+ ## What using Daftari looks like
128
+
129
+ The basic loop is small:
130
+
131
+ 1. **Search before writing.** Find the current documents, their sources, and
132
+ any unresolved tensions.
133
+ 2. **Write a draft.** State confidence, provenance, sources, and open questions
134
+ in YAML frontmatter.
135
+ 3. **Curate deliberately.** Lint reports staleness, weak grounding, abandoned
136
+ drafts, unanswered questions, and broken relationships. It does not fix
137
+ them.
138
+ 4. **Ratify or retire.** Promote trustworthy drafts, supersede replaced
139
+ knowledge, and record why a claim changed.
140
+ 5. **Revisit.** Sleep runs, interviews, court dockets, and archaeology reports
141
+ turn accumulated history into a review queue.
142
+
143
+ This is **compilation over retrieval**: an agent writes a considered result
144
+ back into the vault so the next agent begins with the accumulated record, not
145
+ with the same pile of fragments. See the [worked example](docs/worked-example.md)
146
+ for the document lifecycle across three writes.
147
+
148
+ ## Capabilities by outcome
149
+
150
+ Configure the MCP registry in `core`, `standard`, or `full` tiers. The tier
151
+ changes what clients see in `tools/list`; it does not change the vault's data
152
+ model.
153
+
154
+ | Outcome | Main surfaces | What they provide |
155
+ |---|---|---|
156
+ | Find relevant knowledge | `vault_search`, `vault_search_related`, `vault_themes` | Hybrid lexical/vector retrieval, related documents, and thematic clusters |
157
+ | Read with context | `vault_read`, `vault_backlinks`, `vault_consumes` | Document content, inbound references, and compiled dependencies |
158
+ | Write and maintain documents | `vault_write`, `vault_append`, `vault_merge`, `vault_supersede` | Structured writes with locking, provenance, indexing, and Git history |
159
+ | Control lifecycle and confidence | `vault_promote`, `vault_deprecate`, `vault_set_confidence`, `vault_set_tier` | Explicit gates between draft, canonical, source, and retired knowledge |
160
+ | Keep contradictions visible | `vault_tension_log`, `vault_tension_triage`, `vault_positions`, `vault_canon` | Open tensions, attributed positions, and settled-versus-contested belief |
161
+ | Require human judgment | `vault_stage_action`, `vault_ratify`, `vault_consolidate` | Proposed actions and ratified organizational positions |
162
+ | Inspect trust and history | `vault_receipt`, `vault_provenance`, `vault_witness`, `daftari asof` | Evidence receipts, write history, principal track records, and past belief state |
163
+ | Operate the vault | `daftari sleep`, `court`, `interview`, `view`, `audit` | Review queues, rulings, elicited evidence, a read-only portal, and coherence checks |
164
+
165
+ Use `daftari --help` for the current CLI surface. MCP clients obtain the current
166
+ tool names and schemas directly from `tools/list`; the README does not duplicate
167
+ the complete registry.
168
+
169
+ ## How the vault is built
170
+
171
+ | Layer | Responsibility | Boundary |
172
+ |---|---|---|
173
+ | **Storage** | Markdown with YAML frontmatter, Git history, SQLite search index | Markdown is canonical; the index is disposable |
174
+ | **Access** | Config-driven roles and collection permissions | No separate user-management database |
175
+ | **Write safety** | Process lock, file locks, attributable writes, automatic commits | Concurrency protection does not resolve semantic conflicts |
176
+ | **Curation** | Lifecycle, staleness, tensions, provenance, staged actions | Advisory by default; judgment is never silently automated |
177
+
178
+ Every document remains readable in an editor and inspectable with ordinary Git
179
+ commands. Frontmatter is the metadata layer; Daftari does not introduce a
180
+ second document format. A typical accumulation document begins like this:
156
181
 
157
182
  ```yaml
158
183
  ---
@@ -166,865 +191,113 @@ updated: 2026-05-17
166
191
  updated_by: agent:claude-code
167
192
  provenance: synthesized
168
193
  sources:
169
- - aurora-product-page
194
+ - https://example.com/aurora-product-page
170
195
  ttl_days: 120
171
- valid_from: 2026-05-01
172
- valid_until: null
173
196
  tags: [aurora, ingestion, competitive]
174
197
  questions_answered:
175
- - "How does Aurora frame the ingestion/transformation boundary?"
198
+ - "How does Aurora frame the ingestion boundary?"
176
199
  questions_raised:
177
- - "Does an authored-pipeline model slow teams down at small scale?"
200
+ - "Does an authored pipeline slow small teams down?"
178
201
  ---
179
202
  ```
180
203
 
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.
204
+ Read the [file-format reference](docs/file-format.md) for validity intervals,
205
+ typed source references, lifecycle fields, positions, and extension rules.
184
206
 
185
- ### Typed source references
207
+ ## Run it where the work happens
186
208
 
187
- `sources` records provenance from more than one address space. Prefix a source
188
- when its resolution contract matters:
209
+ ### Local MCP server
189
210
 
190
- ```yaml
191
- # .daftari/config.yaml — for a vault nested inside its repository
192
- repo_root: ..
193
-
194
- # document frontmatter
195
- sources:
196
- - vault:canon/settled-claim.md
197
- - repo:research/raw-evidence.md
198
- - https://example.com/published-evidence
199
- - mailto:owner@example.com
200
- - distill:session-42#claim-7
201
- - doi:10.1000/182
202
- ```
203
-
204
- - `vault:path/to/note.md` is a strict, vault-root-relative dependency. A missing
205
- target is a tier-0 `brokenSourceRefs` finding and blocks ratification that
206
- would create the violation. Traversal and absolute paths never resolve.
207
- - `repo:path/to/file` resolves against `repo_root`. Lint verifies file metadata
208
- only—it does not read the file—and reports missing, unconfigured, invalid, or
209
- escaping references under advisory `unverifiableSourceRefs` findings. On MCP
210
- and board surfaces, the caller's role must explicitly set
211
- `verify_repo_sources: true`; vault read grants alone never authorize probing
212
- the larger repository tree.
213
- - `http:`, `https:`, `mailto:`, and other URI schemes are provenance, not vault
214
- dependency edges.
215
- - `distill:<source-id>#<claim-key>` is an audit breadcrumb, not a re-derivation
216
- source. Reads and advisory lint label it `born-unverifiable`: the external
217
- source was discarded by design, so re-derivation means re-presenting it.
218
- - Unprefixed values remain backward compatible: if they resolve to an existing
219
- vault document, they are dependency edges; otherwise they are opaque
220
- citations. Use `vault:` for dependencies whose disappearance must fail tier 0.
221
-
222
- `repo_root` may be the vault root or an ancestor containing a nested vault. It
223
- is resolved relative to the vault and must contain it. Repository targets are
224
- checked with lexical and real-path containment, including symlink escapes.
225
-
226
- `valid_from` / `valid_until` are the second temporal axis. Everything else in
227
- the file records **transaction time** — when the vault came to believe
228
- something; these record **valid time** — when the claim was true in the world. A
229
- document edited this morning can describe a price that stopped applying in
230
- March, and only the second axis can tell you so. That makes supersession
231
- checkable rather than merely asserted:
211
+ The default mode is one stdio process serving one writable vault:
232
212
 
233
213
  ```bash
234
- daftari asof 2026-04-01 --valid 2026-01-15
235
- ```
236
-
237
- "On April 1st, what did the vault believe was true on January 15th?"
238
-
239
- <details>
240
- <summary><b>Half-open valid-time intervals and the authoring rules (▸ expand for full reference)</b></summary>
241
-
242
- The window is half-open — `[valid_from, valid_until)` — so `valid_until` is the
243
- first day the claim no longer held, and a successor's `valid_from` is exactly
244
- its predecessor's `valid_until`. Handoffs share no day and leave no gap. The
245
- fields are optional and always authored: nothing derives them from git dates or
246
- mtime, because that would manufacture a claim nobody made. Both null means
247
- unknown, which is never read as "always true".
248
-
249
- Full field reference in <docs/file-format.md>.
250
-
251
- </details>
252
-
253
- <!-- The rituals -->
254
-
255
- ## The tools
256
-
257
- **Read:** `vault_read`, `vault_index`, `vault_status`
258
-
259
- **Attest:** `vault_receipt` — compile an epistemic receipt for the documents
260
- an answer cites: per-source status, confidence, provenance, freshness, exact
261
- content-version hash, supersession-chain resolution, and open tensions, plus
262
- deterministic summary flags, the vault's git HEAD as an as-of anchor, and a
263
- recomputable hash over the whole receipt. Attach it to the answer so any
264
- consumer can see what the answer stands on.
265
-
266
- **Believe:** `vault_canon` — compute settled vs. contested belief across
267
- holders over an emergent topic (params: `seed`, `holders?`, `as_of?`,
268
- `depth?`). Returns a per-claim settled/contested classification, integrity
269
- flags (`graph_completeness: "curated"`, `partial_visibility`, `unindexed`,
270
- `ghost_holder_warning`), and an attached `vault_receipt` as the epistemic
271
- anchor. Recorded, not omniscient: settled means no contradiction is on record,
272
- not that none exists. Never auto-resolves.
273
-
274
- **Witness:** `vault_witness` — per-principal track records from the vault's
275
- own ledgers, priced by the wager schedule: write volume, live claims with
276
- open exposure, contested claims with stake at risk, the settled book
277
- (burned vs credited), proposal outcomes, tensions logged. Advisory and
278
- deterministic; includes the flat-curve monitor so a single-author vault is
279
- reported as uninformative rather than as signal.
280
-
281
- <details>
282
- <summary><b>The full per-category tool registry and the tool-tier config (▸ expand for full reference)</b></summary>
283
-
284
- **Search:** `vault_search` (hybrid BM25 + vector; hits carry their unresolved
285
- tensions inline and foreground the current source of superseded documents),
286
- `vault_search_related`, `vault_themes` (thematic clustering), `vault_reindex`
287
-
288
- **Write:** `vault_write`, `vault_append`, `vault_promote`, `vault_deprecate`, `vault_supersede`, `vault_merge`, `vault_set_confidence`, `vault_set_tier`
289
-
290
- **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, and compiled-edge instrumentation coverage)
291
-
292
- **Edges:** `vault_edge_observe`, `vault_edge_contest`, `vault_edges`, `vault_consumes` (query the compiled dependency graph), `vault_backlinks` (the reverse knowledge-graph query — which documents reference a target; a code-path target lists the docs whose `describes` binds that file, and `verify:true` classifies each pin against its code repo)
293
-
294
- **Dispatch:** `vault_tier1` (type-directed change dispatch), `vault_tier2_queue`, `vault_tier2_verdict` (semantic-review queue + verdict)
295
-
296
- **Ratify:** `vault_stage_action`, `vault_ratify`
297
-
298
- **Positions:** `vault_assert` (a principal's assert/dispute/qualify stance on a claim doc; conflicting live stances mark it contested and cap confidence), `vault_positions` (query positions by doc or principal), `vault_consolidate` (ratify-gated org stance; clears the contested confidence cap, dissent computed server-side)
299
-
300
- The curation engine is advisory: `vault_lint` reports problems and
301
- `vault_tension_log` records contradictions. Neither auto-fixes anything. Every
302
- change is a deliberate, attributable act. Retraction is surfaced, not enforced:
303
- the `retiredStillLinked` lint check / `retired_still_linked` read-time advisory
304
- flags canonical docs still citing a deprecated or superseded source, and
305
- `vault_deprecate`/`vault_supersede` return a `dependents` advisory (the
306
- downstream blast) at retraction time.
307
-
308
- ### Tool tiers
309
-
310
- Every advertised tool costs the agent context tokens and a decision branch.
311
- The `tools` block in `.daftari/config.yaml` picks how much of the registry
312
- `tools/list` advertises:
313
-
314
- ```yaml
315
- tools:
316
- tier: standard # core | standard | full (default: full)
317
- include: # add tools the tier omits
318
- - vault_tension_log
319
- exclude: # remove tools the tier includes — exclude wins
320
- - vault_status
321
- ```
322
-
323
- `core` is the search-before-derive loop (`vault_search`, `vault_read`,
324
- `vault_write`, `vault_index`, `vault_lint`, `vault_status`); `standard` adds
325
- the full document lifecycle (append/promote/deprecate/supersede/merge,
326
- confidence and tier setters, propose/ratify) plus `vault_search_related`,
327
- `vault_provenance`, and diagnostics; `full` is everything. `--tools <tier>` overrides the tier for one invocation. Filtering
328
- only changes what is *advertised* — calls to any registered tool still work,
329
- so an agent holding a cached tool name keeps working across a tier change.
330
- Unknown names in `include`/`exclude` warn at startup and are ignored, so a
331
- config written for a newer daftari still loads.
332
-
333
- </details>
334
-
335
- **Evaluate (opt-in, requires an Anthropic API key):** `daftari eval` — scores how
336
- well an LLM can use the curation surface to answer multi-hop questions about the
337
- vault. See the [design spec](docs/superpowers/specs/2026-05-31-cortex-quality-metric-design.md)
338
- for the rationale and the cortex framing.
339
-
340
- ## Circadian memory
341
-
342
- The vault sleeps. `daftari sleep` is the nightly metabolic pass — deterministic,
343
- LLM-free, write-free (documents are never touched):
344
-
345
- ```bash
346
- # In cron (any scheduler works; daftari ships the cycle, not a daemon):
347
- 0 3 * * * cd /path/to/vault && npx daftari sleep --output .daftari/morning-report.md
348
- ```
349
-
350
- The cycle sweeps expired staged actions, scores every document's decay, and
351
- builds the **wake list**: canonical accumulation documents triggered by decay,
352
- ended validity, or retracted/vanished declared and compiled grounding, ranked
353
- by blast radius. For a deleted vault source, the operator report distinguishes
354
- recoverable Git history (with the last commit that contained the file) from a
355
- path absent in available history. The list is written to
356
- `.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
357
- document against its sources, stage the diff — because the vault never
358
- re-verifies on its own. Generative documents going stale are expected, not a
359
- defect: counted, never woken.
360
-
361
- The **Morning Report** ends where the human begins: tension aging and the
362
- court docket head, the ratification queue with soon-to-expire proposals, and
363
- the rubber-stamp monitor. It also reports compiled-edge instrumentation
364
- coverage separately from freshness: an absent machine-local `consumes.jsonl`
365
- is shown as `no compiled-edge data (N docs uninstrumented)`, not as an
366
- all-current vault. Zero rejections over a long decision history is printed as
367
- a warning, not a compliment. The agent proposes overnight; you ratify over
368
- coffee.
369
-
370
- Each completed pass appends a content-light summary (counts only, no document
371
- bodies) to a self-pruning `.daftari/runs.jsonl`; `daftari runs [list|show <id>]`
372
- reads that history back, so the loop's own liveness is legible over time.
373
-
374
- ## The viewer
375
-
376
- `daftari view` serves a read-only web portal over the vault — loopback only,
377
- no editing — that makes the vault's *epistemic state and knowledge graph*
378
- legible, not just its prose:
379
-
380
- - **Dashboard home** — vault metrics, a freshness distribution (fresh/aging/
381
- stale), open-tension and ratification-queue counts, and the recent sleep-run
382
- trend.
383
- - **Document pages** lead with a **standing strip** — status, a confidence
384
- meter, decay, and a contested flag — over rendered (sanitized) markdown, with
385
- epistemic banners (decay / structural / upstream / pins), a **Contested**
386
- panel, **backlinks**, a table of contents, and in-vault links resolved to
387
- their documents.
388
- - **Knowledge graph** (`/graph`) — an interactive map of the vault: nodes are
389
- documents (colored by status, flagged when decayed or contested), edges are
390
- source / link / derives-from / contested relations. Click a node to open it;
391
- every document links to its own neighborhood.
392
- - **Search** over the hybrid index, on every page.
393
-
394
- Read-only by construction (only GET, no mutation routes, a loopback Host
395
- allow-list against DNS-rebinding), built on `node:http` with one lazily loaded
396
- graph library — no web framework.
397
-
398
- ```bash
399
- daftari view --vault ./my-vault # then open http://127.0.0.1:8788
400
- ```
401
-
402
- ## Tension Court
403
-
404
- Tensions wait in a log; the court turns them into decidable cases. `daftari
405
- court` compiles a **docket** — every open tension briefed and ranked (stale
406
- first, then by blast radius): both sides' claims, the present state of their
407
- documents, the downstream stakes, cluster membership, and **precedents** —
408
- past rulings on disputes that shared a document, a collection pair, or a
409
- kind.
410
-
411
- The **triage card** (`daftari court --triage` / `vault_tension_triage`) is the
412
- deliberately **unranked**, cluster-grouped companion view — legibility, not a
413
- severity score. Each contested side surfaces `criticality`, `provenance`, and
414
- `updated_by`, so a resolver can judge trust without opening the documents.
415
-
416
- ```bash
417
- # The docket — a 5-minute weekly ritual
418
- daftari court --vault ./my-vault
419
-
420
- # One case's full brief (verbatim rationales from cited precedents)
421
- daftari court --tension tension-abc123
422
-
423
- # Rule. The rationale is recorded verbatim and cited by future dockets.
424
- daftari court rule tension-abc123 --kind corrected \
425
- --rationale "Vendor pricing page confirmed the entry tier on 2026-07-10."
426
- ```
427
-
428
- Rulings go through the same `resolveTension` write path as
429
- `vault_tension_resolve` — a ruling records the closure, it never edits the
430
- disputed documents. Precedent retrieval is deterministic (shared-document >
431
- collection-pair > same-kind; no LLM): the court retrieves how this house has
432
- resolved similar disputes before, and whether a precedent applies stays the
433
- human's judgment. Memory grows case law.
434
-
435
- ## The principal interview
436
-
437
- The vault interrogates you. `daftari interview` assembles a question sheet
438
- from what the vault already knows is unclear — open tensions (contested
439
- first, longest-carried first), canonical accumulation docs past their TTL,
440
- and `questions_raised` entries no document answers — deterministic and
441
- LLM-free, like the circadian pass:
442
-
443
- ```bash
444
- # The sheet — read-only, priority-ordered
445
- daftari interview --vault ./my-vault
446
-
447
- # Sit for it. Answers are recorded VERBATIM; empty skips, 'q' ends.
448
- daftari interview ask --vault ./my-vault
449
- ```
450
-
451
- Answered questions become a transcript document in an `interviews/`
452
- collection — `tier: source` (your words, body immutable), `provenance:
453
- direct`, no TTL (testimony doesn't expire) — committed like any other write,
454
- with `sources` tracing each question back to the tension or document that
455
- prompted it. The pattern is the companion interview on a living-summary
456
- page: the compiler's highest-value move is not more compilation, it is
457
- asking the principal about the unclear spots and folding the verbatim
458
- answers back into the corpus.
459
-
460
- Recording testimony resolves nothing. The transcript is *evidence*: the CLI
461
- ends by pointing at `daftari court rule <id> --references <transcript>` for
462
- tensions it touched, and at re-verified writes for stale docs. Operator-only,
463
- like the court — no MCP tool, no access context.
464
-
465
- ## Belief archaeology
466
-
467
- Git is the version layer, so the vault can answer **"what did we believe on
468
- March 3?"** `daftari asof` is a read-only report over the repo's history — no
469
- checkout, no index, no API key:
470
-
471
- ```bash
472
- # The vault's belief state at a date (or any git ref), plus the drift since
473
- daftari asof 2026-03-03 --vault ./my-vault
474
-
475
- # One document's trajectory: frontmatter then vs now, commits in between
476
- daftari asof HEAD~20 --doc pricing/helios-consumption-pricing.md
477
-
478
- # Counterfactual replay: this fact turned out wrong — who had inherited it
479
- # at the time, and where are they now?
480
- daftari asof 2026-03-03 --blast pricing/helios-consumption-pricing.md
481
- ```
482
-
483
- The default report shows the document and tension state at that point and
484
- the drift since: documents added/removed, `status`/`confidence` transitions,
485
- and tensions opened or resolved. `--blast` computes the blast radius of a
486
- document over the tree *as of the commit* (same source/link edge semantics as
487
- `vault_tension_blast`), annotating each downstream document with its status
488
- today — the post-mortem view for a fact that was later corrected. Markdown to
489
- stdout by default; `--output` / `--output-json` write files. Pairs with
490
- `vault_receipt`: a receipt's `vaultHead` is exactly the anchor to hand back
491
- to `asof`.
492
-
493
- ## The vault as witness — and the wager layer
494
-
495
- Every write already carries an identity, every proposal an outcome, every
496
- tension a logger and a ruling. `vault_witness` aggregates that ledger into a
497
- **track record per principal** — and prices it. Confidence is free to claim,
498
- so the wager schedule makes it cost something: writing at `high` stakes 3
499
- points, `medium` 1, `low` 0 (hedged claims are the honest default and are
500
- never taxed). A claim later corrected by a ruling or retired by someone else
501
- burns the stake; a claim maintained through a full TTL cycle earns credit.
502
- The balance is arithmetic on recorded facts — advisory, provisional
503
- constants, nothing enforced: routing a high-stakes write to the agent with
504
- the earned balance is your policy, not the vault's.
505
-
506
- <details>
507
- <summary><b>The two kill conditions that travel with the tool (▸ expand for full reference)</b></summary>
508
-
509
- Both kill conditions from the design travel with the tool: the flat-curve
510
- monitor (one author ≥95% of writes → curves declared uninformative) and the
511
- longitudinal write-volume series (if stake-fear suppresses honest claims, it
512
- shows up here first).
513
-
514
- </details>
515
-
516
- ## Coherence audit
517
-
518
- `daftari audit` is a read-only, deterministic check across one or more
519
- markdown repos for **broken cross-repo references** and **link-graph
520
- transitive staleness**. It works against any markdown tree — daftari-managed
521
- or not. The audit creates no `.daftari/` directory and writes nothing to the
522
- audited repos.
523
-
524
- ### Multi-repo (the headline use case)
525
-
526
- When two or more repos link to each other, the audit detects broken
527
- references that neither repo's own lint could see — because each repo only
528
- knows about itself.
529
-
530
- ```bash
531
- daftari audit \
532
- --repo ~/repos/service-a \
533
- --repo ~/repos/service-b
534
- ```
535
-
536
- That works for relative-path links (`../service-b/docs/api.md`). For
537
- GitHub-style URL links between repos (`https://github.com/org/service-b/...`),
538
- declare each repo's URL patterns in an `audit.yaml` so the resolver can map
539
- them back to the local repo:
540
-
541
- ```yaml
542
- # audit.yaml
543
- repos:
544
- - name: service-a
545
- path: ~/repos/service-a
546
- urls: ["github.com/org/service-a"]
547
- - name: service-b
548
- path: ~/repos/service-b
549
- urls: ["github.com/org/service-b"]
550
- ```
551
-
552
- ```bash
553
- daftari audit --config audit.yaml
554
- ```
555
-
556
- ### Single repo
557
-
558
- The same command, one `--repo`:
559
-
560
- ```bash
561
- daftari audit --repo ./docs
562
- ```
563
-
564
- In single-repo mode the cross-repo check trivially has no work, but the
565
- staleness check still runs over the in-repo link graph.
566
-
567
- ### What gets detected
568
-
569
- - **Missing files.** A link from `service-a/intro.md` to `../service-b/api.md`
570
- or `https://github.com/org/service-b/blob/main/api.md` — flagged if `api.md`
571
- doesn't exist in `service-b`.
572
- - **Missing anchors.** Same link with `#run` — flagged if `api.md` has no
573
- `## Run` heading.
574
- - **Direct staleness.** Any doc whose git mtime is older than
575
- `staleness.threshold_days` (default 540, ~18 months).
576
- - **Transitive staleness.** A fresh doc that links — directly or through a
577
- chain — to a stale doc is itself flagged, with the shortest chain reported.
578
- Catches the case where you keep touching an index page while the docs it
579
- links to are rotting.
580
-
581
- <details>
582
- <summary><b>Sample output, CI integration, exit codes, CLI flags, and the full <code>audit.yaml</code> schema (▸ expand for full reference)</b></summary>
583
-
584
- ### Sample output
585
-
586
- ```markdown
587
- # Coherence Audit Report
588
-
589
- ## Totals
590
- - repos scanned: **2**
591
- - docs scanned: **47**
592
- - broken cross-repo refs: **2**
593
- - directly stale docs: **3**
594
- - transitively stale docs: **5**
595
-
596
- ## Broken cross-repo references
597
- | kind | source | target | href |
598
- |----------------|---------------------------|-------------------------|------|
599
- | missing_anchor | service-a/intro.md | service-b/api.md#run | `https://github.com/org/service-b/blob/main/api.md#run` |
600
- | missing_file | service-a/architecture.md | service-b/deleted.md | `../service-b/deleted.md` |
601
-
602
- ## Staleness
603
- | kind | doc | mtime | chain |
604
- |------------|--------------------------|------------|-------|
605
- | transitive | service-a/onboarding.md | 2026-04-01 | service-a/onboarding.md → service-b/legacy-flow.md |
606
- ```
607
-
608
- JSON output (`--output-json` or `output.json` in config) carries the same
609
- structure with full detail in `brokenRefs[]` and `staleness[]` arrays plus a
610
- `totals` summary block for compact downstream rendering.
611
-
612
- ### CI integration
613
-
614
- The audit's exit code is designed to gate CI:
615
-
616
- ```yaml
617
- # .github/workflows/docs-audit.yml
618
- name: Docs audit
619
- on: [pull_request]
620
- jobs:
621
- audit:
622
- runs-on: ubuntu-latest
623
- steps:
624
- - uses: actions/checkout@v4
625
- with: { fetch-depth: 0 } # full history so git mtime works
626
- - run: npx daftari@latest audit --config audit.yaml
627
- ```
628
-
629
- Exit codes:
630
-
631
- | code | meaning |
632
- |------|---------|
633
- | `0` | clean run, all findings within `fail_on` thresholds |
634
- | `1` | clean run but a threshold was exceeded — CI fails |
635
- | `2` | config error (missing required fields, bad paths, malformed YAML) |
636
- | `3` | runtime error (IO failure during collection) |
637
-
638
- ### CLI flags
639
-
640
- `audit.yaml` and CLI flags overlap; CLI wins. A warning is printed to stderr
641
- when `--output` or `--output-json` displaces a value from the config.
642
-
643
- - `--repo <path>` — add a repo. May be repeated. Anonymous CLI repos get no
644
- URL patterns; URL-based cross-refs into them won't be detected. Use
645
- `--config` for URL-aware repos.
646
- - `--config <path>` — load an `audit.yaml`.
647
- - `--output <md>` — markdown report destination (default: stdout).
648
- - `--output-json <json>` — JSON report destination (default: not written).
649
- - `--help` — full help text.
650
-
651
- ### Full `audit.yaml` schema
652
-
653
- ```yaml
654
- repos:
655
- - name: service-a
656
- path: ~/repos/service-a
657
- docs_glob: "docs/**/*.md" # default: "**/*.md"
658
- urls: # optional; enables URL-pattern matching
659
- - "github.com/org/service-a"
660
-
661
- - name: service-b
662
- path: ~/repos/service-b
663
- urls:
664
- - "github.com/org/service-b"
665
-
666
- output:
667
- markdown: coherence-report.md # default: stdout
668
- json: coherence-report.json # default: not emitted
669
-
670
- staleness:
671
- threshold_days: 540 # default: 540 (18 months)
672
-
673
- fail_on:
674
- broken_refs: 1 # default: fail on any broken ref
675
- transitive_staleness: 100 # default: generous; teams tune
676
- ```
677
-
678
- </details>
679
-
680
- <!-- Running it -->
681
-
682
- ## Access control
683
-
684
- No user-management system. Roles live in config, the server starts with one.
685
- No `--role` or an unknown name falls back to deny-all. An agent identity is
686
- just a role too — e.g. a `curation-loop` role that reads and writes but leaves
687
- `ratify` off: the agent proposes, humans ratify.
688
-
689
- <details>
690
- <summary><b>Roles config example (▸ expand for full reference)</b></summary>
691
-
692
- ```yaml
693
- roles:
694
- analyst:
695
- read: [competitive-intel, pricing]
696
- write: [competitive-intel, _drafts]
697
- researcher:
698
- read: ["*"]
699
- write: [moonshot, _drafts]
700
- admin:
701
- read: ["*"]
702
- write: ["*"]
703
- promote: true
704
- ratify: true # may approve/reject staged actions and contest edges
705
- verify_repo_sources: true # may stat repo: provenance targets under repo_root
706
- ```
707
-
708
- </details>
709
-
710
- ## Cross-vault federation
711
-
712
- One process, one *writable* vault — but it can mount other vaults read-only
713
- and search across them. Reads and search compose over every mounted vault;
714
- writes, locks, git, and curation stay bound to the local one. The boundary in
715
- one line: **a mount exposes documents, not vault state** — you can read and
716
- search a mounted vault's markdown, but its tensions, edges, provenance, and
717
- lint never cross.
718
-
719
- Declare mounts in your own config:
720
-
721
- ```yaml
722
- # your vault's .daftari/config.yaml
723
- federation:
724
- mounts:
725
- - alias: research
726
- path: ../research-vault
727
- index: lexical # skip embeddings for this mount (default: full)
728
- ```
729
-
730
- Access is granted by the *other* vault, in its own config, keyed by your
731
- authenticated identity — deny-all until its owner says otherwise:
732
-
733
- ```yaml
734
- # the referenced vault's .daftari/config.yaml
735
- federation:
736
- principals:
737
- "human:mihir": { role: researcher } # a role defined in THAT vault
738
- ```
739
-
740
- Federated documents address as `research:notes/pricing.md`, every result
741
- carries a `vault` label, and `vault_search` fuses ranked hits across vaults
742
- (rank fusion, so differing corpus statistics can't skew scores). Nothing is
743
- ever written under a mounted vault — its search index lives inside *your*
744
- `.daftari/`, rebuilt from its markdown like any other derived cache. Mount
745
- freshness is checked at startup; `vault_reindex {mount: research}` refreshes
746
- on demand. stdio-only for now: `daftari serve` refuses a config with mounts.
747
-
748
- ## Server mode (self-hosted)
749
-
750
- By default daftari is a per-user stdio process. `daftari serve` starts the
751
- same vault as **one always-on instance over Streamable HTTP** — for a team, or
752
- for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
753
-
754
- ```bash
755
- daftari serve --vault ./my-vault # http://127.0.0.1:8787/mcp
756
- daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
757
- daftari serve --vault ./my-vault --legacy-http # also answer 2025-era MCP clients
758
- ```
759
-
760
- Identity is **per request**, resolved from the bearer on every request (MCP
761
- 2026-07-28 is stateless — there are no sessions), so every RBAC and
762
- existence-disclosure rule applies per caller with zero tool changes. Two
763
- composable auth schemes, both declared in config. `--legacy-http` is a
764
- temporary, opt-in migration flag for clients still on 2025-era MCP: same
765
- process, same per-request auth, no session table (removal tracked in #371).
766
-
767
- <details>
768
- <summary><b>Auth config (bearer tokens + OAuth 2.1) and the fail-loud posture (▸ expand for full reference)</b></summary>
769
-
770
- ```yaml
771
- server:
772
- transport_security: external # required off-loopback: TLS terminates upstream
773
- auth:
774
- tokens: # static bearer tokens (agents, ETL)
775
- - env: DAFTARI_TOKEN_ETL # the VALUE lives in this env var, never in config
776
- user: agent:etl
777
- role: admin
778
- oauth: # OAuth 2.1 resource server (humans via your IdP)
779
- issuer: https://idp.example.com
780
- audience: daftari
781
- jwks_uri: https://idp.example.com/.well-known/jwks.json
782
- subjects:
783
- "alice@example.com": { user: human:alice, role: analyst }
214
+ npx daftari --vault ./my-vault --user me --role admin
784
215
  ```
785
216
 
786
- The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
787
- to start without auth **and** the explicit `transport_security: external`
788
- acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
789
- balancer in front); with any auth configured, a bad or missing credential is
790
- a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
791
- neither ever becomes the guest. Guest sessions exist only in the no-auth
792
- loopback configuration. A running server also refuses to be silently killed:
793
- stray stdio invocations against the same vault refuse to start, and replacing
794
- a live holder requires a deliberate `daftari serve --takeover`.
795
-
796
- </details>
797
-
798
- ## Storage backing
217
+ This is the normal setup for Claude Desktop, Claude Code, and local agent SDKs.
799
218
 
800
- A self-hosted vault can push to durable object storage (#6). The local git
801
- working copy stays canonical — reads, writes, auto-commits, locks, and the
802
- index all stay exactly as above — and the backing is a dumb sync target.
219
+ ### Shared self-hosted server
803
220
 
804
- <details>
805
- <summary><b>Storage config, <code>daftari sync</code> commands, and sync semantics (▸ expand for full reference)</b></summary>
806
-
807
- ```yaml
808
- # .daftari/config.yaml
809
- storage:
810
- backend: s3 # fs | s3 | azure
811
- bucket: team-vault
812
- region: us-east-1
813
- # endpoint: https://… # MinIO / R2 / GCS S3-interop endpoints
814
- # sync_interval_minutes: 15 # daftari serve pushes on this cadence
815
- ```
221
+ For multiple clients, `daftari serve` exposes the same vault over Streamable
222
+ HTTP:
816
223
 
817
224
  ```bash
818
- daftari sync --vault ./my-vault # incremental push
819
- daftari sync --vault ./my-vault --dry-run # show the diff only
820
- daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
225
+ daftari serve --vault ./my-vault
821
226
  ```
822
227
 
823
- The push covers the markdown tree, the `.git` directory, and durable
824
- `.daftari` journals; the rebuildable SQLite index and lock files never sync.
825
- Neither do `.git/config` and `.git/hooks` — git *executes* what those
826
- declare, and a backup channel must not deliver code (`git clone` refuses to
827
- transmit them for the same reason), so re-add remotes and local git config
828
- by hand after a restore.
829
- Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
830
- as optional dependencies — install the one you use; credentials come from the
831
- SDK's standard environment chain, never from vault config. GCS is reached via
832
- its S3-interoperability endpoint. Restore refuses non-empty directories and
833
- reindexes when done.
228
+ Non-loopback deployments fail closed unless authentication and external
229
+ transport security are configured. See [deployment and access](docs/deployment.md)
230
+ for bearer tokens, OAuth 2.1, process takeover, federation, and storage backing.
834
231
 
835
- </details>
232
+ ### Existing markdown
836
233
 
837
- ## Adopting an existing vault
838
-
839
- Already have a wiki or an Obsidian vault? Daftari adopts it **in place** — it
840
- indexes and curates the same markdown files you already edit, not a separate copy.
841
-
842
- Inspect the wiki's existing metadata before filling anything in:
234
+ Daftari can inspect and adopt an Obsidian vault or other markdown wiki in
235
+ place. Schema inference and drift checks are read-only; import fills missing
236
+ frontmatter without replacing existing content.
843
237
 
844
238
  ```bash
845
- # What keys and value shapes actually exist? No config required.
846
239
  daftari schema infer --vault ~/my-vault
847
-
848
- # Compare those observations with built-ins + schema_extensions.
849
- # Single-use custom keys stay below the default evidence threshold of 2.
850
- daftari schema diff --vault ~/my-vault --json
851
-
852
- # Limit either report to one folder; nested folders are included.
853
- daftari schema infer --vault ~/my-vault --scope notes
854
- ```
855
-
856
- Both schema commands are read-only. `infer` reports occurrence/prevalence,
857
- observed types, bounded examples, distinct-value cardinality, and enum-likeness.
858
- `diff` reports widely used undeclared fields, declared-but-unused extensions,
859
- observed values that violate their declaration, and near-miss names such as
860
- `state` versus `status`. Use `--min-occurrences <n>` on `diff` to change the
861
- undeclared-field evidence threshold (default 2). Malformed or unreadable docs
862
- are listed as skipped evidence; drift problem categories and path/value examples
863
- are bounded. A missing vault or explicitly named scope fails loud, while an
864
- existing empty folder produces an empty report. Scope confinement follows real
865
- paths, so symlink aliases cannot escape the requested folder or double-count a
866
- document. No markdown, config, or index state is written.
867
-
868
- ```bash
869
- # Dry run — see what would change, write nothing
240
+ daftari schema diff --vault ~/my-vault
870
241
  daftari import obsidian ~/my-vault --plan
871
-
872
- # Adopt one folder at a time (per-folder ratification; --yes to skip the prompt)
873
- daftari import obsidian ~/my-vault --apply --scope notes
874
242
  ```
875
243
 
876
- The import is non-destructive to your content. It fills only the *missing*
877
- Daftari frontmatter — collection from the folder, dates from git history (or file
878
- mtime), sensible defaults for the rest — and preserves everything you already
879
- had, including custom frontmatter fields. Obsidian specifics: inline `#tags` are
880
- merged into `tags`, a Web Clipper `source` is mapped into `sources`, and
881
- `[[wikilinks]]` are left untouched (Daftari resolves them as written). Filling
882
- frontmatter is deliberate, not automatic — re-run the import to pick up newly
883
- added notes.
884
-
885
- ### Cloud-synced vaults (iCloud, Dropbox, …)
244
+ Cloud-synced folders need an external Git directory so sync software never
245
+ copies a live `.git/` database. Follow the safeguards in
246
+ [adopting existing notes](docs/adoption.md) before applying an import.
886
247
 
887
- Daftari versions every change with git, and a `.git/` directory churning inside a
888
- cloud-synced folder can corrupt. For a synced vault, keep git's data outside it:
889
-
890
- ```bash
891
- daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
892
- --apply --scope notes --external-git-dir
893
- ```
248
+ ## What Daftari does not do
894
249
 
895
- This writes `git_dir: external` to `.daftari/config.yaml`, so Daftari uses
896
- `git init --separate-git-dir`: only a tiny static `.git` *file* stays in the vault
897
- (syncs harmlessly) while the repo data lives under `~/.local/share/daftari/git/`.
898
- Pass `--external-git-dir=/path` for an explicit location, or set `git_dir`
899
- directly in config to apply the same to any vault. History is per-device; your
900
- notes still sync everywhere.
250
+ - It does not resolve contradictions by generating a compromise.
251
+ - It does not auto-fix lint findings or promote agent output on its own.
252
+ - It does not hide the canonical files behind a proprietary database.
253
+ - It does not provide a hosted multi-tenant service; server mode is
254
+ self-hosted.
255
+ - It does not replace the model or agent framework. It gives them a durable
256
+ memory substrate over MCP.
901
257
 
902
- ### Lower-level: `backfill`
258
+ For a longer comparison with adjacent memory patterns, see
259
+ [positioning](docs/positioning-2026-07.md). That analysis is kept outside the
260
+ onboarding path because competitor claims age faster than the product contract.
903
261
 
904
- `daftari import obsidian` is a thin, Obsidian-aware wrapper over `daftari
905
- backfill` — the git-driven frontmatter migration that works on any markdown wiki.
906
- Use it directly for non-Obsidian trees:
907
-
908
- ```bash
909
- daftari backfill --plan
910
- daftari backfill --apply --scope specs
911
- ```
912
-
913
- ## Open Knowledge Format (OKF)
914
-
915
- [OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
916
- is Google Cloud's vendor-neutral spec for the LLM-wiki pattern: a directory of
917
- markdown files with YAML frontmatter that any producer can emit and any consumer
918
- can read without translation. A Daftari vault *is* that pattern, so `daftari
919
- okf` bridges the two directions.
920
- [v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals/)
921
- adds opt-in **trust signals** — raw credibility indicators (provenance,
922
- verification, lifecycle, freshness), never computed scores — and Daftari maps
923
- them from/to its native metadata.
924
-
925
- <details>
926
- <summary><b>OKF export / import field-mapping and the <code>daftari okf</code> commands (▸ expand for full reference)</b></summary>
927
-
928
- **Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
929
- concept doc (the core `type` / `title` / `description` / `resource` / `tags`
930
- fields, plus a verbatim `daftari` sidecar for lossless round-trip), with
931
- generated `index.md` (progressive-disclosure listing) and `log.md`
932
- (chronological history). Trust signals derive from native metadata:
933
- `updated`/`updated_by` become `generated`, the lifecycle maps to
934
- `draft`/`stable`/`deprecated`, `ttl_days` becomes an absolute `stale_after`
935
- date, and `sources` become structured entries. `verified` is never fabricated —
936
- Daftari records authorship, not independent confirmations, so exported docs
937
- honestly read as unverified. The source vault is never mutated.
938
-
939
- ```bash
940
- daftari okf export ./my-vault --out ./okf-bundle
941
- daftari okf export ./my-vault --out ./okf-bundle --collection pricing
942
- ```
943
-
944
- **Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
945
- round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
946
- (docs land as `draft` in the `accumulation` domain, the original OKF `type` is
947
- preserved in an `okf_type` field). Trust signals inform the mapping: a
948
- human-reviewed doc (a `human:*` entry in `verified`) imports with `confidence:
949
- high`, `status: deprecated` stays `deprecated` (retired knowledge must not
950
- resurface as a fresh draft), and `stale_after` converts to `ttl_days`. An
951
- `Attested Computation` is surfaced in an import warning but **not**
952
- auto-write-protected: `tier: source` is enforcement, and its only sanctioned
953
- grant path is `vault_set_tier` (reason required, provenance-logged) — a foreign
954
- bundle's self-declared `type` doesn't buy it. Review the doc, then elevate
955
- deliberately. OKF fields with no lossless Daftari slot (the trust record,
956
- attestation machinery) are preserved under `okf_*` keys. Writes auto-commit and
957
- the index is rebuilt.
958
-
959
- ```bash
960
- daftari okf import ./okf-bundle --into ./my-vault --dry-run
961
- daftari okf import ./okf-bundle --into ./my-vault
962
- ```
963
-
964
- </details>
965
-
966
- <!-- Reference / meta -->
967
-
968
- ## What’s not in v1
262
+ ## Documentation
969
263
 
970
- Deliberately deferred to keep the surface tight:
264
+ The [documentation map](docs/README.md) organizes the full set by task. The
265
+ main paths are:
971
266
 
972
- - **Cloud-hosted multi-tenant SaaS** (self-hosted server mode HAS shipped —
973
- see [Server mode](#server-mode-self-hosted) and
974
- [Storage backing](#storage-backing); the project itself hosts nothing)
975
- - **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
976
- - **Background curation agent** running lint on a cadence
977
- - **Enforced domain separation** (v1 documents the convention; v2 enforces it —
978
- advisory boundary warnings shipped in the meantime: `vault_lint`'s
979
- `domainLeaks` check and write-time `domain_warnings`)
267
+ - [Getting started](docs/getting-started.md)
268
+ - [Worked example](docs/worked-example.md)
269
+ - [Curation workflow](docs/curation-workflow.md)
270
+ - [Operator workflows](docs/operator-workflows.md)
271
+ - [Deployment and access](docs/deployment.md)
272
+ - [Google Docs and Notion integrations](docs/integrations.md)
273
+ - [Adopting existing notes](docs/adoption.md)
274
+ - [Architecture](docs/architecture.md)
275
+ - [File format](docs/file-format.md)
276
+ - [Privacy](PRIVACY.md)
980
277
 
981
- (LLM reranking, deferred here originally, has since shipped as the opt-in
982
- agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
983
- fused candidate pool and the protocol; the calling agent is the judge.)
278
+ Integrations:
984
279
 
985
- Each is a clean increment on a surface that already works.
280
+ - [`integrations/langchain/`](integrations/langchain/) exposes Daftari tools as
281
+ LangChain `BaseTool`s for LangGraph and `create_react_agent`.
282
+ - [`packages/router/`](packages/router/) routes one MCP connection across
283
+ multiple writable Daftari vaults.
986
284
 
987
285
  ## Development
988
286
 
989
- ```
287
+ ```bash
990
288
  npm install
991
289
  npm run build
992
290
  npm test
993
291
  ```
994
292
 
995
- Design tenets: functions and types, no classes; tool handlers return
996
- `Result<T, Error>` rather than throwing; tests mirror the `src/` structure.
997
-
998
- The build board: the chain currently under construction — the derived-content
999
- critical path — is tracked with live progress in
1000
- [#428](https://github.com/mavaali/daftari/issues/428).
1001
-
1002
- ## Documentation
1003
-
1004
- - <docs/getting-started.md> — scaffold, write, search, lint, promote, deprecate
1005
- - <docs/architecture.md> — layered design, request path, accumulation vs. generative domains
1006
- - <docs/file-format.md> — complete frontmatter reference
1007
-
1008
- ## Integrations
1009
-
1010
- - [`integrations/langchain/`](integrations/langchain/) — `langchain-daftari`, a
1011
- Python package that exposes all 38 daftari tools as LangChain `BaseTool`s
1012
- for use with LangGraph / `create_react_agent`. Sync + async, schemas pulled
1013
- live from `tools/list`.
1014
- - [`packages/router`](packages/router) — multi-vault MCP router that fans out across N Daftari vaults
1015
-
1016
- ## Privacy
1017
-
1018
- Daftari is a local MCP server. It runs on your machine, against vault files on
1019
- your machine. The default configuration makes no network calls — vault content
1020
- stays on your local filesystem and is read or written only through tools the
1021
- MCP client invokes. The only optional egress is the OpenAI embedding provider,
1022
- which the user must explicitly opt into per vault.
293
+ The codebase is TypeScript and Node.js. Functions and types are preferred over
294
+ classes; tool handlers return `Result<T, Error>` rather than throwing; tests
295
+ mirror the `src/` structure.
1023
296
 
1024
- Full policy: [PRIVACY.md](./PRIVACY.md) — covers data collection (none),
1025
- storage (local-only), the OpenAI opt-in, third-party integrations (none),
1026
- retention, and contact.
297
+ ## Privacy and license
1027
298
 
1028
- ## License
299
+ Daftari runs locally by default and makes no network calls unless a vault opts
300
+ into an external provider or integration. Read the [privacy policy](PRIVACY.md)
301
+ for the complete boundary.
1029
302
 
1030
- MIT.
303
+ Daftari is available under the [MIT License](LICENSE).