From cbd5faa66c3028b381bd715e541e91b3c81acea7 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Sun, 26 Jul 2026 04:15:21 -0400
Subject: [PATCH] docs: document the two-source SSOT split

Function documentation now comes from functions/*.fish comment headers;
everything else stays in docs/manual/**. Records that split in the three
places a contributor looks:

- AGENTS.md "Documentation Policy" and Coding Convention #4, which now
  spells out the full label set and flags CATEGORY as required-to-publish.
- Manual section 11, which pointed readers at docs/manual/ for everything.
- README, same.
---
 README.md                             | 19 ++++++++++++-------
 docs/fish-config.md                   | 11 +++++++++++
 docs/manual/11-viewing-this-manual.md | 11 +++++++++++
 3 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 53738ef..3b0256c 100644
--- a/README.md
+++ b/README.md
@@ -122,14 +122,19 @@ the watcher inert without uninstalling it.
 
 ### [📖 Documentation Site](https://fish-config-docs.pages.dev/)
 
-A Starlight-powered site generated from `docs/manual/**` — the single source
-of truth — on every push to `main`. It covers configuration variables, key
-bindings, abbreviations, all functions, the dependency catalog, customization,
-and more, with full-text search.
+A Starlight-powered site rebuilt on every push to `main`. It covers
+configuration variables, key bindings, abbreviations, all functions, the
+dependency catalog, customization, and more, with full-text search.
 
-Contributing to the docs? Edit files under `docs/manual/**`, never the
-generated `docs/fish-config.md` — it's rebuilt from the manual tree and any
-hand-edits are discarded.
+Contributing to the docs? There are two sources, split by content type:
+
+- **Function documentation** comes from the man-page-style comment header
+  above each function in `functions/*.fish`. Edit the function; the entry
+  and its site page are generated from the header.
+- **Everything else** lives under `docs/manual/**`.
+
+Never edit the generated `docs/fish-config.md` — it's rebuilt from both
+sources and any hand-edits are discarded.
 
 To browse the docs from the terminal:
 
diff --git a/docs/fish-config.md b/docs/fish-config.md
index dfd2bc2..d5794d8 100644
--- a/docs/fish-config.md
+++ b/docs/fish-config.md
@@ -3054,3 +3054,14 @@ editor, or from a shell:
 
     cd ~/.config/fish/docs/manual
     grep -rn "keybindings" .
+
+Section 5 is the exception. Function entries are generated from the
+man-page-style comment header above each function in `functions/*.fish`,
+so the documentation for a command lives beside the code that implements
+it and cannot drift from it. To read the source for a single function, or
+to correct its documentation, open the function itself:
+
+    functions/git-clean.fish
+
+The files under `docs/manual/05-functions/` carry only the category
+titles, ordering, and search keywords.
diff --git a/docs/manual/11-viewing-this-manual.md b/docs/manual/11-viewing-this-manual.md
index 40848e3..06df601 100644
--- a/docs/manual/11-viewing-this-manual.md
+++ b/docs/manual/11-viewing-this-manual.md
@@ -83,3 +83,14 @@ editor, or from a shell:
 
     cd ~/.config/fish/docs/manual
     grep -rn "keybindings" .
+
+Section 5 is the exception. Function entries are generated from the
+man-page-style comment header above each function in `functions/*.fish`,
+so the documentation for a command lives beside the code that implements
+it and cannot drift from it. To read the source for a single function, or
+to correct its documentation, open the function itself:
+
+    functions/git-clean.fish
+
+The files under `docs/manual/05-functions/` carry only the category
+titles, ordering, and search keywords.