daftari 3.11.0 → 3.12.1
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.
- package/CHANGELOG.md +32 -0
- package/README.md +210 -937
- package/dist/access/rbac.d.ts +1 -0
- package/dist/access/rbac.d.ts.map +1 -1
- package/dist/access/rbac.js +5 -0
- package/dist/access/rbac.js.map +1 -1
- package/dist/distill/state.d.ts +9 -1
- package/dist/distill/state.d.ts.map +1 -1
- package/dist/distill/state.js +58 -7
- package/dist/distill/state.js.map +1 -1
- package/dist/eval/llm-openrouter.d.ts.map +1 -1
- package/dist/eval/llm-openrouter.js +5 -22
- package/dist/eval/llm-openrouter.js.map +1 -1
- package/dist/hooks/loader.d.ts.map +1 -1
- package/dist/hooks/loader.js +8 -0
- package/dist/hooks/loader.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +47 -14
- package/dist/index.js.map +1 -1
- package/dist/integrations/distill.d.ts +16 -0
- package/dist/integrations/distill.d.ts.map +1 -0
- package/dist/integrations/distill.js +164 -0
- package/dist/integrations/distill.js.map +1 -0
- package/dist/integrations/engine.d.ts +134 -0
- package/dist/integrations/engine.d.ts.map +1 -0
- package/dist/integrations/engine.js +571 -0
- package/dist/integrations/engine.js.map +1 -0
- package/dist/integrations/google.d.ts +13 -0
- package/dist/integrations/google.d.ts.map +1 -0
- package/dist/integrations/google.js +551 -0
- package/dist/integrations/google.js.map +1 -0
- package/dist/integrations/notion.d.ts +16 -0
- package/dist/integrations/notion.d.ts.map +1 -0
- package/dist/integrations/notion.js +485 -0
- package/dist/integrations/notion.js.map +1 -0
- package/dist/integrations/oauth.d.ts +14 -0
- package/dist/integrations/oauth.d.ts.map +1 -0
- package/dist/integrations/oauth.js +141 -0
- package/dist/integrations/oauth.js.map +1 -0
- package/dist/integrations/queue.d.ts +30 -0
- package/dist/integrations/queue.d.ts.map +1 -0
- package/dist/integrations/queue.js +255 -0
- package/dist/integrations/queue.js.map +1 -0
- package/dist/integrations/review.d.ts +5 -0
- package/dist/integrations/review.d.ts.map +1 -0
- package/dist/integrations/review.js +36 -0
- package/dist/integrations/review.js.map +1 -0
- package/dist/integrations/routes.d.ts +26 -0
- package/dist/integrations/routes.d.ts.map +1 -0
- package/dist/integrations/routes.js +258 -0
- package/dist/integrations/routes.js.map +1 -0
- package/dist/integrations/runtime.d.ts +33 -0
- package/dist/integrations/runtime.d.ts.map +1 -0
- package/dist/integrations/runtime.js +280 -0
- package/dist/integrations/runtime.js.map +1 -0
- package/dist/integrations/state.d.ts +10 -0
- package/dist/integrations/state.d.ts.map +1 -0
- package/dist/integrations/state.js +238 -0
- package/dist/integrations/state.js.map +1 -0
- package/dist/integrations/types.d.ts +45 -0
- package/dist/integrations/types.d.ts.map +1 -0
- package/dist/integrations/types.js +4 -0
- package/dist/integrations/types.js.map +1 -0
- package/dist/lifecycle/lock.d.ts.map +1 -1
- package/dist/lifecycle/lock.js +15 -1
- package/dist/lifecycle/lock.js.map +1 -1
- package/dist/resources.js +5 -1
- package/dist/resources.js.map +1 -1
- package/dist/search/coverage.d.ts.map +1 -1
- package/dist/search/coverage.js +5 -5
- package/dist/search/coverage.js.map +1 -1
- package/dist/search/graph-expansion.d.ts +55 -0
- package/dist/search/graph-expansion.d.ts.map +1 -0
- package/dist/search/graph-expansion.js +160 -0
- package/dist/search/graph-expansion.js.map +1 -0
- package/dist/search/hybrid.d.ts +4 -0
- package/dist/search/hybrid.d.ts.map +1 -1
- package/dist/search/hybrid.js.map +1 -1
- package/dist/serve/index.d.ts +16 -0
- package/dist/serve/index.d.ts.map +1 -1
- package/dist/serve/index.js +325 -18
- package/dist/serve/index.js.map +1 -1
- package/dist/serve/limits.d.ts +13 -0
- package/dist/serve/limits.d.ts.map +1 -1
- package/dist/serve/limits.js +47 -0
- package/dist/serve/limits.js.map +1 -1
- package/dist/serve/proxy-trust.d.ts +19 -0
- package/dist/serve/proxy-trust.d.ts.map +1 -0
- package/dist/serve/proxy-trust.js +167 -0
- package/dist/serve/proxy-trust.js.map +1 -0
- package/dist/storage/backends/fs.d.ts.map +1 -1
- package/dist/storage/backends/fs.js +13 -0
- package/dist/storage/backends/fs.js.map +1 -1
- package/dist/storage/sync.d.ts.map +1 -1
- package/dist/storage/sync.js +11 -0
- package/dist/storage/sync.js.map +1 -1
- package/dist/tools/board.test.js +3 -0
- package/dist/tools/board.test.js.map +1 -1
- package/dist/tools/read.d.ts.map +1 -1
- package/dist/tools/read.js +7 -1
- package/dist/tools/read.js.map +1 -1
- package/dist/tools/search.d.ts.map +1 -1
- package/dist/tools/search.js +31 -3
- package/dist/tools/search.js.map +1 -1
- package/dist/utils/config.d.ts +15 -0
- package/dist/utils/config.d.ts.map +1 -1
- package/dist/utils/config.js +172 -5
- package/dist/utils/config.js.map +1 -1
- package/dist/utils/realpath-confine.d.ts +4 -0
- package/dist/utils/realpath-confine.d.ts.map +1 -0
- package/dist/utils/realpath-confine.js +61 -0
- package/dist/utils/realpath-confine.js.map +1 -0
- package/dist/utils/vault-gitignore.d.ts +1 -1
- package/dist/utils/vault-gitignore.d.ts.map +1 -1
- package/dist/utils/vault-gitignore.js +23 -3
- package/dist/utils/vault-gitignore.js.map +1 -1
- package/package.json +2 -2
- package/templates/config.yaml +3 -0
package/README.md
CHANGED
|
@@ -2,157 +2,182 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://github.com/mavaali/daftari/actions/workflows/ci.yml) [](https://www.npmjs.com/package/daftari) [](LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
|
|
14
|
-
|
|
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
|
-
|
|
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
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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
|
-
|
|
55
|
-
none:
|
|
21
|
+
## Choose your path
|
|
56
22
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
-
|
|
63
|
-
law:
|
|
36
|
+
## Five-minute quickstart
|
|
64
37
|
|
|
65
|
-
|
|
38
|
+
**Prerequisite:** Node.js 20 or newer.
|
|
66
39
|
|
|
67
|
-
|
|
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
|
-
```
|
|
72
|
-
|
|
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
|
-
|
|
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
|
-
|
|
81
|
-
contradict?**
|
|
50
|
+
### 2. Connect an MCP client
|
|
82
51
|
|
|
83
|
-
|
|
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
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
|
|
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
|
-
|
|
79
|
+
### 3. Ask the vault a question
|
|
109
80
|
|
|
110
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
89
|
+
Next, ask it to write a draft:
|
|
123
90
|
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
|
|
130
|
-
|
|
131
|
-
|
|
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
|
-
##
|
|
98
|
+
## The problem Daftari solves
|
|
137
99
|
|
|
138
|
-
|
|
139
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
146
|
-
|
|
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
|
-
|
|
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
|
-
|
|
114
|
+
> **A tension may never masquerade as a supersession.**
|
|
153
115
|
|
|
154
|
-
|
|
155
|
-
|
|
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
|
|
198
|
+
- "How does Aurora frame the ingestion boundary?"
|
|
176
199
|
questions_raised:
|
|
177
|
-
- "Does an authored
|
|
200
|
+
- "Does an authored pipeline slow small teams down?"
|
|
178
201
|
---
|
|
179
202
|
```
|
|
180
203
|
|
|
181
|
-
|
|
182
|
-
|
|
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
|
-
|
|
207
|
+
## Run it where the work happens
|
|
186
208
|
|
|
187
|
-
|
|
188
|
-
when its resolution contract matters:
|
|
209
|
+
### Local MCP server
|
|
189
210
|
|
|
190
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
805
|
-
|
|
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
|
|
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
|
-
|
|
824
|
-
|
|
825
|
-
|
|
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
|
-
|
|
232
|
+
### Existing markdown
|
|
836
233
|
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
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
|
-
|
|
877
|
-
|
|
878
|
-
|
|
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
|
-
|
|
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
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
264
|
+
The [documentation map](docs/README.md) organizes the full set by task. The
|
|
265
|
+
main paths are:
|
|
971
266
|
|
|
972
|
-
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
-
|
|
976
|
-
-
|
|
977
|
-
-
|
|
978
|
-
|
|
979
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
996
|
-
`Result<T, Error>` rather than throwing; tests
|
|
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
|
-
|
|
1025
|
-
storage (local-only), the OpenAI opt-in, third-party integrations (none),
|
|
1026
|
-
retention, and contact.
|
|
297
|
+
## Privacy and license
|
|
1027
298
|
|
|
1028
|
-
|
|
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).
|