One canonical truth file per product: the problem, the approach, the decisions and their reasons, the positioning. Every AI you work with reads it before writing a word. One source, many renderings, zero re-coaching.
Every session starts from zero. You ask for a landing page, a pitch, an App Store description, and first you coach. No, it's for parents, not doctors. No, we killed that feature, and for a good reason. No, that's not how we talk about it. The knowledge exists; it's just scattered across old chats, tracker tickets, and your head. So you pay the explaining tax on every output, forever.
Trackers hold what you're doing. Nothing holds what's true.
Your agent interviews you once and writes the truth file: machine-readable frontmatter, four sections of prose. Ten minutes. It lives in a plain git repo you own.
A user-level convention makes any AI session read the file in full before generating anything product-facing. Facts come from the file; voice and format are per-output.
When a real decision happens mid-session, your agent flags it, folds it into the file, and rejects status noise. Contradictions get surfaced, never silently overwritten.
The file is the substrate; the AI is the transformer. Same facts, any shape, no coaching in between.
one_liner: AI-first food journal. Natural language in, structured safe/trigger tracking out. insight: input friction kills food journals; a kept journal is the only one that can find patterns decision: insights refuse to run below 5 entries / 2 dates; one bad early correlation destroys parent trust wedge: FPIES families. Highest pain, most underserved, founder is one of them.
"Mia had oatmeal with banana, seemed fussy after her nap." That's the whole entry. SafeYum turns it into a structured journal: the meal, the ingredients, who it was, while you get back to your kid. Built by an FPIES parent who lived the alternative: a paper diary and a guess.
Everyone in this space competes on better charts. I went after the reason the charts stay empty: nobody fills out forms mid-crisis. Conversational input, parse-confirm-save, and an insights engine that deliberately refuses to speak until the data can support it, because one bad early correlation costs the only asset that matters: trust.
FPIES families run food trials with a paper diary because every journaling app demands structured input at exactly the moment structure is impossible. SafeYum owns that moment with conversational capture the incumbents can't retrofit, then expands to the general food-journaling market from a position of earned trust.
All four generated from the same file. The tabs are the coaching you no longer do.
Your AI does the installing; you approve its plan. Agentic tools like Claude Code set up everything on your machine. Chat apps like ChatGPT connect through GitHub and walk you through it. Fifteen minutes later you own a truth file, and the installer was also the tutorial.
You are setting up sapho: a plain-files product source of truth. First, detect your own capabilities: full install if you can write files on the user's machine, GitHub-connected setup if you can only reach repos, guided walkthrough if you have no tools. Second, discover before you create: sapho may already be installed by another tool or in a non-default location — always ask the user ("have you used sapho before?"), check the user-level instruction files for a sapho section, and probe ~/sapho and ~/Projects/sapho. If a corpus exists you are CONNECTING, not installing: read the corpus's own CONNECT.md (it outranks this page), pull latest, report freshness, point your platform's conventions at the existing path. Never create a second corpus. Tool failures never lower the bar: fix mangled URLs (strip *, quotes, brackets) and resume the failed step, don't restart. Before writing anything, present the human a short plan of every file you will create or modify and get an explicit yes. Merge with existing configuration; never overwrite. All steps are idempotent. spec_version: 4. Full spec: /install.md
Ask where the corpus should live (default ~/sapho). Create it as a git repo with
products/ and a README describing the schema below and the two rules: (1) truth,
not state: no tasks, progress, or blockers in truth files; that belongs in their tracker;
(2) one product = one file. Offer to create a private GitHub remote so chat surfaces can
read and write the same corpus.
--- name: <product name> one_liner: <one sentence: what it is> audience: <who it's for> status: exploring | building | live | paused tracker: <link to tracker project> links: <optional: repo, domains> tags: [<...>] --- ## Problem & insight ## How it works ## Key decisions & rationale ## Positioning
Append a "Product Source of Truth (sapho)" section to the user's global agent instructions
(for Claude Code: ~/.claude/CLAUDE.md), stating: (a) every product has one truth
file at <corpus>/products/<slug>.md; (b) read it in full before generating
anything product-facing, and never invent product facts; (c) when starting substantive work in
a project with no SOT pointer in its instructions, offer to interview the user and create one,
then add a pointer line; (d) when a session surfaces a durable decision with a rationale, flag
it and offer to reconcile at a natural pause; (e) never write tasks, progress, or status into
a truth file.
Install a user-level skill named reconcile (for Claude Code:
~/.claude/skills/reconcile/SKILL.md) with these judgment rules: break input into
claims; classify each as confirms (no edit) / new truth (add to the one section it belongs) /
evolves (rewrite in place, don't append a duplicate) / conflicts (surface to the human, never
silently overwrite; record instructive reversals as decisions with the why) / state (reject;
point to the tracker) / noise (drop). Durability test: still true and worth knowing in six
months? Minimal edits only; decisions require a rationale; commit with
reconcile(<product>): <summary>; never push without being asked.
Interview the human about one product they're working on: the problem and the non-obvious
insight behind it; how it works and what makes the approach different; the decisions they'd
have to re-explain and why they made them; how they talk about it and what it's against.
Write products/<slug>.md per the schema, show it to them, then commit.
Do not push anywhere; do not send anything off the machine.
On your machine, in a git repo you own. Add a private GitHub remote and chat surfaces like ChatGPT can read and write the same corpus through their connectors. Nothing is hosted by sapho; there is no sapho server.
Claude Code and other agentic tools are first-class: the conventions install directly. ChatGPT and claude.ai connect through GitHub. Anything else works the moment it can read a file or a paste; each truth file is about 70 lines and self-contained by design.
You keep a folder of well-written markdown about your products. There's no export because there's no lock-in; the files were always the product.
The corpus is git-native, so multi-player is a remote away: pull requests become the gate on truth, code owners own product files, and agents propose instead of write. Add process when you need it; the files never change.