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

@@ -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
+A Starlight-powered site rebuilt on every push to `main`. It covers
-of truth — on every push to `main`. It covers configuration variables, key
+configuration variables, key bindings, abbreviations, all functions, the
-bindings, abbreviations, all functions, the dependency catalog, customization,
+dependency catalog, customization, and more, with full-text search.
-and more, with full-text search.
 
-Contributing to the docs? Edit files under `docs/manual/**`, never the
+Contributing to the docs? There are two sources, split by content type:
-generated `docs/fish-config.md` — it's rebuilt from the manual tree and any
+
-hand-edits are discarded.
+- **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:
 

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.

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.