A single source of truth for your products.

## To the installing agent

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

## 1 · Corpus repo

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

## 2 · User-level conventions

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.

## 3 · Reconcile skill

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.

## 4 · First product

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.