Bundle
Bundle OKF 0.2 · 9 conceitos · gaberger/touchstone
Open source Repository Open in the app JSON README (API)
About
<!-- generated by `touchstone index` -- do not edit -->
# Bundle
## Sections
* [Adversarial](adversarial/index.md) - 10 concepts
* [Decisions](decisions/index.md) - 3 concepts
* [Metrics](metrics/index.md) - 1 concept
* [Notes](notes/index.md) - 3 concepts
* [People](people/index.md) - 1 concept
* [Projects](projects/index.md) - 1 concept
* [Runbooks](runbooks/index.md) - 1 concept
* [Systems](systems/index.md) - 1 concept
* [Terms](terms/index.md) - 4 concepts
Details
- Kind
- OKF bundles
- Topic
- Cloud & DevOps
- Publisher
- gaberger
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Last push
- 2026-08-02T19:52:36Z
- Repository state
- ativo
- Language
- Rust
- License
- MIT
- Added
- 2026-09-08 09:02:43
- Updated
- 2026-09-08 09:02:43
- Origin id
gaberger/touchstone:_fixture/index.md
README
# Touchstone
**Provenance and portability for machine-written knowledge.**
An agent reads your source material and compiles a knowledge base where every claim cites what
it came from, and the claims a human has actually checked are cryptographically signed.
Built on [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
v0.2 — Google Cloud's open spec for knowledge as a directory of markdown concepts with YAML
frontmatter.
## The problem
Once an LLM writes most of your knowledge base, two questions decide whether it is worth
anything, and most tools answer neither:
- **Which parts can you rely on?** Generated pages read exactly like verified ones. Without a
trust signal that cannot be forged, a knowledge base is a pile of plausible text.
- **Can you leave with it?** Hosted tools export lossily by design. A corpus you cannot take
with you is not yours.
Touchstone answers both by making them properties of the format rather than features of the
app: raw bytes on disk are the truth, provenance is signed and travels with the bundle, and
everything else — index, search, graph — is derived and disposable.
## How it works
```
raw/ source documents, immutable, never parsed on the way in
↓ an agent reads them and writes concepts that CITE them
concepts markdown + YAML frontmatter, one file per idea, path is identity
↓ a human signs the ones they have actually checked
attest/ signatures over content digests, travelling with the bundle
```
Everything above the bundle is derived. Delete the index and every generated `index.md`,
re-run `touchstone index`, and the result is byte-identical.
## Install
```bash
cargo install --git https://github.com/gaberger/touchstone touchstone-cli
```
Or a prebuilt binary from [Releases](https://github.com/gaberger/touchstone/releases) — each
ships with a `.sha256` and is only cut after the conformance suite passes on that platform.
## Use it
```bash
touchstone --bundle ~/brain init
touchstone --bundle ~/brain ingest ~/Documents/notes # recursive, deduplicated
touchstone --bundle ~/brain watch & # index stays current
```
Capture a thought — no editor, no title needed, 0.01s:
```console
$ touchstone --bundle ~/brain capture "Q4 was never restated. Only Q1 got the corrected basis."
notes/q4-was-never-restated.md
```
Ask a question months later, in the words you actually have:
```console
$ touchstone --bundle ~/brain search "why don't the quarterly figures agree"
* decisions/margin-restatement-is-incomplete.md
Margin restatement is incomplete [Decision]
Only Q1 was corrected; Q4 still uses the old basis.
* human-verified ~ machine-generated
```
You did not remember the title, the filename, or the word "margin". The `*` says a human
signed off on that one.
Ask something grep cannot express at all — a *field*, not a word:
```console
$ touchstone --bundle ~/brain search "margin" --type Decision --status stable --trust human
```
Then ask where the claim came from:
```console
$ touchstone --bundle ~/brain show decisions/margin-restatement-is-incomplete.md --json
{
"path": "decisions/margin-restatement-is-incomplete.md",
"trust": "human",
"sources": [
"raw/interview-priya.txt",
"raw/email-thread.eml"
]
}
```
An interview and an email you ingested weeks ago. Both still in the bundle, byte-identical,
and both travel with it when you leave.
Finally: is that `human` tier worth anything?
```console
$ touchstone --bundle ~/brain verify
0 of 1 human claims backed # a claim is just text until it is signed
$ touchstone --bundle ~/brain attest decisions/margin-...md --as human:gary --key ~/.ssh/id_ed25519
$ touchstone --bundle ~/brain verify
1 of 1 human claims backed
$ echo "an edit nobody verified" >> decisions/margin-...md
$ touchstone --bundle ~/brain verify
STALE: decisions/margin-restatement-is-incomplete.md
signed, but the concept changed since -- the verified bytes are not these bytes
```
The signature covers the content digest, not the path. Editing a signed concept invalidates its
attestation instead of carrying it along.
---
**→ [How to run this as a business brain](docs/USING.md)** — what to ingest and what to
ignore, when an email becomes a concept, which types to be strict about, what to sign, and the
anti-patterns that turn a knowledge base back into a folder of files.
## For agents
```bash
touchstone --bundle ~/brain mcp # stdio
touchstone --bundle ~/brain mcp --http 127.0.0.1:8765 # Streamable HTTP
```
Thirteen tools at MCP revision **2026-07-28**, each with input *and* output schemas and
annotations so a client knows which calls need a human in the loop. `touchstone_unprocessed`
returns the uncompiled sources *with their content*, so an agent gets the work and the material
in one call.
```json
{
"mcpServers": {
"touchstone": {
"command": "touchstone",
"args": ["--bundle", "/absolute/path/to/brain", "mcp"]
}
}
}
```
**No tool can write `verified`.** Signing needs a private key a human holds, and `attest` is
deliberately absent from the MCP surface — it is the one capability an agent must not have.
## Commands
| | |
|---|---|
| `init` | Create the bundle layout |
| `capture <text>` | Record a thought in one command |
| `ingest <path>...` | Copy sources into `raw/`, byte-exact, recursive, deduplicated |
| `unprocessed` | Raw documents nothing cites yet — the work queue |
| `index` | Rebuild the derived plane. Idempotent, incremental on content hash |
| `watch` | Reindex continuously as files change |
| `search <query>` | Structured prefilter → BM25 → one graph hop → trust rank |
| `show <path>` | One concept's derived view; `--json` for parsed frontmatter |
| `stats` | Counts by type, trust tier, status; links and broken links |
| `lint` | Conformance floor, duplicate checks, uncited machine-written concepts |
| `fmt [--check]` | Canonicalise frontmatter; refuses what it cannot reproduce |
| `attest <path>` | Sign a concept's `verified` claim |
| `verify` | Check every claim against the signed manifest |
| `export <dir>` | Write everything back out — concepts, artifacts, sources, signatures |
| `new <Type> <Title>` | Scaffold a conformant concept |
| `mcp` | Serve the tool surface |
Filters: `--type`, `--tag`, `--status`, `--trust`, `--limit`, `--no-expand`.
## Design rules
**Raw text is authoritative.** Frontmatter is parsed for querying, never treated as the truth.
`export` writes raw bytes, so there is no serializer in the write path that could drop an
unknown key — the failure mode is structurally impossible rather than merely tested for.
**Everything touchstone generates is derived and disposable.** An `index.md` in a directory
with no concepts is authored knowledge, not generated, and is left alone.
**The spec's tolerance is honoured, not narrowed.** Unknown types, unknown keys and broken
links are all preserved and indexed. A broken link is knowledge about a gap.
**Trust tiers are derived, never authored.** `verified[].by` starting with `human:` → trusted;
`generated` present without it → machine; neither → unattributed. Search ranks on this.
## How we prove it works
Correctness is a **conformance suite that drives the shipped binary as a black box** — it names
no internal crate, so the same drills can gate a different implementation:
```bash
TOUCHSTONE_BIN=/path/to/other/impl cargo test -p touchstone-conformance
```
40 drills run against five bundles — an adversarial fixture plus four vendored third-party ones
written by people who never saw this code:
| | |
|---|---|
| Byte-exact round trip | CRLF, unicode paths, YAML anchors, block scalars, PNG/PDF/MP4 |
| Deterministic rebuild | delete the derived plane; output is byte-identical |
| Spec tolerance | unknown types and keys preserved, broken links recorded |
| Signed provenance | unbacked, stale and forged claims each detected distinctly |
| CLI/MCP parity | the two surfaces produce identical bytes for the same operation |
| Scale | 50,000 concepts index in 11.85s; query in 0.11s |
Plus 184 unit and integration tests, a layering check that makes an architecture violation a
compile error, and the whole gate on every push.
**What is not proven, stated plainly:**
- **Does it beat `rg` + Obsidian?** Weak evidence. On a real corpus with a fairly-ranked
baseline, touchstone answered 18 of 20 questions against the baseline's 11 — but the
questions were not written by a disinterested party. See `a10/`.
- **Will anyone write into it unprompted?** Untested. Instrumented and waiting for three weeks
of real use. See `a3/`.
- **Who do you trust?** `attest/allowed_signers` is the bundle's own assertion about its
signers, not a PKI. It makes tampering detectable, not identity certain.
## Documents
| | |
|---|---|
| [docs/USING.md](docs/USING.md) | How to run one as a business brain — what to ingest, what to write, what to sign |
| [ARCHITECTURE.md](ARCHITECTURE.md) | The design as it is today |
| [docs/adrs/](docs/adrs/) | Why each decision was made — append-only |
| [PROTOTYPE.md](PROTOTYPE.md) | How to falsify it. Pre-registered kill criteria |
| [FINDINGS.md](FINDINGS.md) | Experimental results, including the claims that turned out false |
| [_sample/](_sample/) | A mixed-media corpus to try it against |
MIT licensed.