PRIME PRODUCTS · MISSION CONTROL
AI-first transformation · by TPL · vanos.tpl.one

Docs / 06-decisions/012-raw-source-layer

ADR-012 Raw source layer — committed to the repo, never part of the wiki

Original source material (meeting transcripts, client documents) lives under raw/, committed for provenance, but is never knowledge — it is ingested into vault docs and excluded from Mission Control, the graph, and the chat corpus.

type: adr updated: 2026-07-06 owner: taranas

ADR-012 — Raw source layer: committed to the repo, never part of the wiki

Status

accepted — 2026-07-06 (decided by: taranas; first instance: the pilot-interview Fathom transcript)

Context

Discovery produces original source material — Fathom call transcripts, client-provided documents, sample exports. The Karpathy LLM-wiki model separates sources from the wiki: raw material is kept for provenance and re-reading, but the wiki holds only distilled, curated knowledge. Until now this vault had no defined home for sources; the first transcript arrived on 2026-07-06.

Decision

  1. raw/ is the source layer. Original material goes under raw/<category>/… (e.g. raw/meetings/transcript/), in its original form and language — the only place where non-English content is allowed (ADR-003 applies to knowledge docs, not sources).
  2. Committed to the repo — sources are part of the project’s provenance and must survive machines and people. The repo is private; raw material inherits the vault’s confidentiality (treat as data_sensitivity: high by default).
  3. Never part of the wiki. Raw files carry no OKF frontmatter and are never linked as knowledge from published docs. They are automatically excluded from Mission Control, the OKF graph, and the wiki-chat corpus, because all three only take Markdown docs with publish: mission-control (ADR-005, ADR-008).
  4. Ingestion is mandatory. A source is only useful once distilled: every file landing in raw/ gets a corresponding English knowledge doc (interview note, requirement update, etc.) that cites the raw path as its source. A raw file with no distilled counterpart is an open task, not done.
  5. raw/README.md documents the layer rules at the point of use.

Consequences

  • Provenance: every captured fact can be traced back to its source (“per the 2026-07-06 pilot interview”).
  • The wiki stays curated — no transcript noise in search, graph, chat, or the published site.
  • Repo size will grow with sources; acceptable for text. Large binaries (recordings) stay on their platform (e.g. Fathom link inside the transcript) — do not commit media files.
  • No secrets exception: credentials must not appear even in raw material; redact before committing if a source contains one.