docs: define canonical documentation hierarchy (#299)

flyingrobots · flyingrobots · commit f37d938fb6af · 2026-03-24T21:14:34.000-07:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -3,7 +3,8 @@
 ## CROSS-REFERENCE
 
 - Code standards and contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
-- User-facing documentation: [GUIDE.md](GUIDE.md)
+- Documentation map and canonical docs: [docs/README.md](docs/README.md)
+- CLI/user reference: [GUIDE.md](GUIDE.md)
 
 ## FORBIDDEN ACTIONS
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 All notable changes to this project will be documented in this file.
 
+This is release history, not the canonical product frame.
+Older entries will naturally reflect prior roadmap eras and product language.
+
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -3,7 +3,8 @@
 ## CROSS-REFERENCE
 
 - Code standards and contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
-- User-facing documentation: [GUIDE.md](GUIDE.md)
+- Documentation map and canonical docs: [docs/README.md](docs/README.md)
+- CLI/user reference: [GUIDE.md](GUIDE.md)
 
 ## FORBIDDEN ACTIONS
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,6 +2,19 @@
 
 Thanks for your interest in contributing. This document covers the essentials.
 
+Before changing product-facing behavior or docs, read these first:
+
+- [README.md](README.md)
+- [docs/README.md](docs/README.md)
+- [docs/design/git-mind.md](docs/design/git-mind.md)
+- [ROADMAP.md](ROADMAP.md)
+
+Current product frame:
+
+- `git-mind` is a Git-native semantic intelligence layer for software repositories
+- current work should be judged against low-input semantic bootstrap, provenance-backed query, and living-map upkeep
+- personal cognition tooling belongs in `think`, not here
+
 ## Prerequisites
 
 - Node.js >= 20.0.0
diff --git a/GRAPH_SCHEMA.md b/GRAPH_SCHEMA.md
@@ -3,6 +3,9 @@
 > **Authoritative contract for git-mind's knowledge graph.**
 > All validators, importers, and views implement against this document.
 > Ref: #180 (BDK-001)
+>
+> This document is the graph contract, not the canonical product narrative.
+> Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain supported, but they are not the current center of the product story.
 
 ---
 
diff --git a/GUIDE.md b/GUIDE.md
@@ -5,7 +5,7 @@
 > The CLI reference in this guide is still useful, but parts of the framing and examples reflect Git Mind's earlier manual graph-authoring story.
 > For the current product direction, start with [README.md](README.md), [ROADMAP.md](ROADMAP.md), [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md), and [docs/design/git-mind.md](docs/design/git-mind.md).
 
-Everything you need to know — from zero to power user.
+CLI reference and usage guide.
 
 ---
 
@@ -31,6 +31,9 @@ Everything you need to know — from zero to power user.
 
 git-mind adds a **semantic knowledge graph** to any Git repository. You create **nodes** (files, concepts, tasks, modules — anything) and connect them with **typed edges** (implements, depends-on, documents, etc.). The graph lives inside Git — no external databases, no servers.
 
+Manual graph authoring is still supported, but it is no longer the primary product story.
+The current direction is inference-first semantic repository intelligence: Git Mind should increasingly extract and surface repository meaning before it asks users to model the graph by hand.
+
 **Why?**
 
 Code tells a computer what to do. Comments tell a human what the code does. But neither captures *why* things are connected — which spec does this file implement? What does this module depend on? What task does this commit address?
diff --git a/README.md b/README.md
@@ -82,7 +82,7 @@ Manual edge creation remains supported, but it should increasingly be treated as
 
 ```bash
 git mind link file:src/auth.js spec:auth --type implements
-git mind link adr:0007 task:M11 --type blocks
+git mind link adr:0007 task:auth-rollout --type blocks
 ```
 
 ## Product Doctrine
@@ -130,8 +130,9 @@ The repository is in a stabilize-and-clarify phase:
 
 ## Documentation
 
-Start here:
+Canonical docs:
 
+- [docs/README.md](docs/README.md)
 - [GUIDE.md](GUIDE.md)
 - [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md)
 - [ROADMAP.md](ROADMAP.md)
diff --git a/TECH-PLAN.md b/TECH-PLAN.md
@@ -6,8 +6,6 @@
 > It still contains useful substrate and architecture detail, but it is not the active product roadmap or control plane.
 > The current product frame lives in [README.md](README.md), [ROADMAP.md](ROADMAP.md), and [docs/design/git-mind.md](docs/design/git-mind.md).
 
-> **"A knowledge graph that thinks alongside you."**
-
 A technical analysis of git-mind's architecture, data model, runtime behavior, invariants, and roadmap trajectory. This is a reference artifact — not a changelog, not a tutorial.
 
 ---
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -3,6 +3,9 @@ _Last updated: 2026-02-15_
 
 This document defines non-negotiable engineering laws for Git Mind.
 
+These laws are canonical engineering guardrails.
+They are not the product roadmap, and some of the terms here come from broader platform work that predates the current product narrowing.
+
 ---
 
 ## Law 1: Graph Truth Is Canonical
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,62 @@
+# Documentation Map
+
+This file defines which documents are canonical, which are transitional, and which are historical references.
+
+Use it to avoid treating old planning artifacts as the active product story.
+
+## Canonical Product Docs
+
+These describe what Git Mind is now and how work should be judged:
+
+- [README.md](../README.md) — current product summary
+- [ROADMAP.md](../ROADMAP.md) — active Hills, supporting lanes, and playback cadence
+- [Git Mind Product Frame](./design/git-mind.md) — IBM Design Thinking style product frame
+- [Git Mind North Star](./VISION_NORTH_STAR.md) — longer-form strategic articulation
+
+## Canonical Engineering Guardrails
+
+These define constraints and contracts that remain in force:
+
+- [GRAPH_SCHEMA.md](../GRAPH_SCHEMA.md) — graph contract
+- [Architecture Laws](./ARCHITECTURE.md) — non-negotiable engineering laws
+- [Review Rubric](./REVIEW_RUBRIC.md) — architectural review gates
+- [ADRs](./adr/README.md) — durable architecture decisions
+- [Contracts](./contracts/CLI_CONTRACTS.md) and related schemas — machine-facing contracts
+
+## Transitional Docs
+
+These are still useful, but they carry some older framing and should not be treated as the primary product narrative:
+
+- [GUIDE.md](../GUIDE.md) — CLI and usage reference; still contains manual graph-authoring examples
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — contributor workflow with current frame pointers added
+
+## Historical Reference Docs
+
+These should not drive planning or product identity without explicit review:
+
+- [CHANGELOG.md](../CHANGELOG.md) — release history, not product strategy
+- [TECH-PLAN.md](../TECH-PLAN.md) — deep technical artifact from an earlier planning era
+- [Risk Register](./RISK_REGISTER.md) — bridge/platform-era risk control document
+- [Risk Review Checklist](./RISK_REVIEW_CHECKLIST.md) — bridge/platform-era operating checklist
+- [Strategic Conversation Summary](./notes/Git%20Mind%20Strategic%20Conversation%20Summary.md) — historical context
+- [Dogfood Session](./notes/dogfood-session.md) — historical evidence, not current plan
+
+## Practical Rule
+
+When documents disagree:
+
+1. trust the canonical product docs first
+2. then trust canonical engineering guardrails
+3. treat transitional docs as implementation help, not product truth
+4. treat historical docs as reference only
+
+## Planning Rule
+
+GitHub issues are the execution backlog.
+
+Hills and Playbacks live in:
+
+- [ROADMAP.md](../ROADMAP.md)
+- [Git Mind Product Frame](./design/git-mind.md)
+
+GitHub milestones are not the primary planning system for this repository.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -2,6 +2,9 @@
 
 This directory captures durable architecture decisions for Git Mind.
 
+These ADRs are architecture references, not the canonical product narrative.
+Some of them were written during a broader platform and bridge planning phase, but they still matter where they establish substrate or invariants that remain in force.
+
 Use ADRs for decisions that are hard to reverse, cross-cut multiple subsystems, or define platform invariants.
 
 ---
@@ -108,4 +111,4 @@ Prevents git-mind from duplicating CRDT, time-travel, observer, and provenance g
 - Keep ADRs concise but specific.
 - Avoid ambiguous wording (“usually”, “maybe”) in core invariants.
 - Include explicit consequences and operational impact.
-- Link milestone(s), contracts, and tooling gates affected by the decision.
+- Link relevant Hill(s), issue(s), contracts, and tooling gates affected by the decision.
diff --git a/docs/notes/Git Mind Strategic Conversation Summary.md b/docs/notes/Git Mind Strategic Conversation Summary.md
@@ -3,6 +3,11 @@
 **Scope:** End-to-end summary of this chat session  
 **Purpose:** Capture all major topics, decisions, rationale, and resulting direction for Git Mind
 
+> Historical note:
+> This file is preserved as strategic history.
+> It should not be treated as the active product frame, roadmap, or backlog control plane.
+> For the current direction, use [README.md](../../README.md), [ROADMAP.md](../../ROADMAP.md), [docs/VISION_NORTH_STAR.md](../VISION_NORTH_STAR.md), and [docs/design/git-mind.md](../design/git-mind.md).
+
 ---
 
 ## Executive Summary
diff --git a/docs/notes/dogfood-session.md b/docs/notes/dogfood-session.md
@@ -3,6 +3,10 @@
 > **Date**: 2026-02-11
 > **Seed**: `test/fixtures/echo-seed.yaml` — Echo ecosystem (55 nodes, 70 edges)
 > **Runtime**: Node.js 20, vitest 3.2.4
+>
+> Historical note:
+> This transcript captures an earlier dogfood pass against a roadmap-oriented graph model.
+> It is useful as historical evidence, but it is not the active product plan or canonical workflow description.
 
 ## Setup
 
