docs: tighten note system docs

1 files changed, 19 insertions, 16 deletions

diff --git a/README.md b/README.md
index 3edcd7b..3578547 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,14 @@ This repository configures Emacs. It does not define, create, or validate the `~
 - The system optimises for speed of capture and minimal friction.
 - The system must prefer explicit rules over implicit behaviour and must avoid over-structuring, manual overhead, and inconsistency.
 
+## External Invariants
+
+These are external note-system invariants. The configuration assumes them, but it does not manage them.
+
+- `~/org` must exist.
+- `~/org/moc.org` must exist.
+- `~/org/areas/people/people.org` must exist.
+
 ## Emacs Setup
 
 ### Source of truth and generated files
@@ -51,7 +59,7 @@ The note system lives under `~/org/` and is organised like this:
 - `daily/` for plain daily Org files.
 - `projects/` for project notes.
 - `areas/` for area notes.
-- `areas/people/people.org` for the lightweight people rolodex.
+- `areas/people/people.org` for the structured people system.
 - `resources/` for reference material.
 - `archives/` for archived notes.
 
@@ -76,19 +84,19 @@ The minibuffer stack is intentionally small:
 
 ## People System
 
-The people system is a structured rolodex rooted at `~/org/areas/people/people.org`.
+The people system is a structured people system (lightweight CRM) rooted at `~/org/areas/people/people.org`.
 
 - Each top-level heading represents one person.
 - Entries are strictly structured around heading text and properties.
-- The system generates abbrevs from the rolodex.
+- The system generates abbrevs from the people file.
 - The system provides canonical-name completion through a CAPF.
 - The system provides reporting views grouped by person properties.
-- The system rebuilds on any rolodex change, whether the change comes from manual editing or from a command.
-- The rolodex must remain up to date after changes.
+- The system rebuilds on any people-file change, whether the change comes from manual editing or from a command.
+- The system must remain up to date after changes.
 - Failures must surface visibly. The system must not silently fall back to stale state.
 - `CURRENT_FOCUS` must stay short and phrase-like so summaries and completion annotations remain readable.
 
-Name entry uses fixed abbrevs plus the people rolodex:
+Name entry uses fixed abbrevs plus the structured people system:
 
 - `abbrev` provides deterministic one-shot shortcuts for fixed name expansions.
 - people-specific abbrevs are generated from top-level cards in `~/org/areas/people/people.org`.
@@ -96,7 +104,7 @@ Name entry uses fixed abbrevs plus the people rolodex:
 - Marginalia annotates person candidates with `role | location | engagement | current focus`.
 - `M-x ss/people-open` opens `~/org/areas/people/people.org` in overview mode through `ss/people-overview`.
 - `M-x ss/people-find` opens a person card narrowed to that subtree.
-- `M-x ss/people-overview` opens the rolodex in overview mode, resetting the file by widening and restoring the overview when leaving card view.
+- `M-x ss/people-overview` opens the people file in overview mode, resetting the file by widening and restoring the overview when leaving card view.
 - `M-x ss/people-insert-name` inserts the canonical name at point.
 - `M-x ss/people-insert-summary` inserts a compact single-line summary at point.
 - `M-x ss/people-add` adds a new person card directly to `~/org/areas/people/people.org`.
@@ -105,7 +113,7 @@ Name entry uses fixed abbrevs plus the people rolodex:
 ### Persistent abbrevs
 
 Persistent abbrevs live in `abbrev_defs` at the repository root. The config loads that file on startup, enables abbrev mode only in text-like buffers, and saves learned abbrevs back to the same file silently when buffers are saved.
-People-specific abbrevs are not stored in a separate file. They are rebuilt from `~/org/areas/people/people.org` whenever the rolodex changes, and missing `ABBREV` properties fall back to a generated default trigger.
+People-specific abbrevs are not stored in a separate file. They are rebuilt from `~/org/areas/people/people.org` whenever the people file changes, and missing `ABBREV` properties fall back to a generated default trigger.
 
 ### Babel tangle process
 
@@ -159,12 +167,7 @@ Durable notes use Denote and live in the PARA directories under `~/org/`.
 ### Agenda usage
 
 The agenda is opened through `ss/open-agenda`, bound to `C-c a`. That command explicitly loads `org-agenda`, and the config refreshes `org-agenda-files` immediately before each `org-agenda` invocation.
-
-The agenda scan is explicit:
-
-- It recursively includes `.org` files from `~/org/projects/`, `~/org/areas/`, and `~/org/resources/`.
-- It excludes `~/org/daily/` and `~/org/archives/`.
-- It does not rely on heuristics.
+Agenda file selection follows the canonical rules in the `Agenda Rules` section above.
 
 ### Capture flow
 
@@ -179,7 +182,7 @@ Daily task capture writes under `Tasks`. Daily note capture and daily meeting ca
 
 Denote captures still prompt for title, keywords, and subdirectory placement where appropriate, but folder placement does most of the classification work. The project capture template prepopulates the `project` keyword. Area and resource captures do not inject structural keywords automatically, and there is no Denote-backed meeting capture template.
 
-The people rolodex is intentionally outside `org-capture`: `M-x ss/people-add` writes a compact card directly into `~/org/areas/people/people.org`, keeping the rolodex as a fast reference file instead of another capture sink.
+The structured people system is intentionally outside `org-capture`: `M-x ss/people-add` writes a compact card directly into `~/org/areas/people/people.org`, keeping the people file as a fast reference file instead of another capture sink.
 
 ### Note creation and linking
 
@@ -194,7 +197,7 @@ Denote handles long-lived notes. The main bindings are:
 - `C-c n I` to insert a compact person summary.
 - `C-c n L` to show people grouped by location.
 - `C-c n d` to open today's daily note.
-- `C-c n o` to restore the rolodex overview.
+- `C-c n o` to restore the people overview.
 - `C-c n O` to show people grouped by role.
 - `C-c n p` to open `~/org/areas/people/people.org`.
 - `C-c n P` to add a new person card.