Provenance and Git — Clarification
Two separate ideas are referenced in the spec under "provenance and git." They are not the same thing, and neither means "use Git instead of an inbox."
1. Provenance (traceability of outputs)
What it is: Recording where an output came from — which inputs were used to create it — and, when AIR is enabled, who/what authorized the action.
- On export: When you run
knowtation export ..., the system records which vault notes were used as sources for that export (e.g. a list of paths or a manifest). That record is "provenance" for the exported artifact. Optional: store this in the memory layer (e.g. "last export used notes X, Y, Z") so agents can answer "what notes fed this blog post?" - On write (non-inbox): When an agent or user writes to a note outside the inbox (e.g.
vault/projects/foo/note.md), AIR can require an attestation before the write; the AIR id is then logged with that write. So you have a chain: "this note was written after attestation #xyz." - Governance: Logging, agent-generated tags, and this provenance chain support audit and trust: you can see what was used to create an export and what was approved before a write.
What it is not: Provenance is not "using Git as the inbox." The inbox is still a folder in the vault (vault/inbox/ or vault/projects/<project>/inbox/) where capture plugins and imports write notes. Provenance is about tagging outputs (exports and approved writes) with their sources and, when used, AIR ids.
2. Vault under Git (version history and backup) — crucial for production
We recommend treating GitHub (or another Git remote) as a core part of your setup. Backup and version history are not optional if your vault is important to you.
What it is: The vault (the folder of Markdown files that is the source of truth) can be placed inside a Git repository. You then get:
- History: Every change to any note is a commit; you can see who changed what and when, and revert.
- Audit trail: Git log is the history of your knowledge base.
- Backup / portability: Push to a remote (GitHub, GitLab, or a private server) for backup and sync across machines. The vault directory remains the same; Git is just the version-control layer around it.
What it is not: Git is not a replacement for the inbox. The inbox is still a location in the vault (vault/inbox/). You can put the whole vault (including the inbox) under Git. So:
- Capture plugins and importers write files into
vault/inbox/(or project inbox) as today. - You (or your workflow) commit those files to Git when you want a snapshot — e.g. after a capture run, or on a schedule, or manually. Git gives you history and backup; the inbox gives you a designated place for raw ingestion.
Optional auto-sync: In config/local.yaml under vault.git you can set auto_commit: true (and optionally auto_push: true). Then every Hub write (new note, capture, or approved proposal) triggers a git add, commit, and optionally push. So your GitHub backup stays up to date without running knowtation vault sync by hand. Manual knowtation vault sync remains available when you want to sync from the CLI.
Summary: "Vault under git" = recommend storing the vault folder in a Git repo so you have version history and an audit trail. It does not mean "use Git as the transport or storage for the inbox"; the inbox is still file-based inside the vault.
3. How they work together
| Concept | Role |
|---|---|
| Inbox | Folder(s) in the vault where captures and imports write new notes (with frontmatter source, date, etc.). |
| Provenance | When you export or write (non-inbox), we record which notes were used and, with AIR, which attestation authorized the action. |
| Vault under Git | The whole vault (including inbox and all other folders) lives in a Git repo so you have history, diff, and backup of all note changes. |
So: you keep an inbox for incoming content; you record provenance on exports and approved writes; and you put the vault in Git to get history and a golden thread of changes over time. All three can be used together.