ctxr-cli 0.13.0 → 0.15.0

package/templates/skills/ctxr-publish.md

@@ -18,6 +18,9 @@ an unintended note slips in unnoticed:
 - `--note <path>` — a single note
 - `--entity <name>` — every note linking to a concept, the same enumeration `ctxr rollup gather` uses
 
+It answers where the page belongs as well as what it is drawn from: the path it reports is what step
+4 files the page at, so run it once and keep the output.
+
 ## 3. Decide what belongs on the page
 
 The store does not decide this for you. Read the resolved set and judge, note by note, whether its
@@ -25,21 +28,39 @@ content belongs in front of this page's intended readers — a page written for
 not carry material written about that party, or about anyone else who did not expect to be quoted.
 When you are unsure about a note, leave it out and name it to the operator rather than guessing.
 
-## 4. Fix the identity once, and file it where its subject lives
-
-`ctxr publish new <slug>` creates the page's folder. The slug is a path, and its shape carries
-meaning: file the page under the top-level folder its subject's notes live in, and name it for the
-subject — `<top-level-folder>/<subject>`, never `<subject>` alone at the root. Two levels, no more:
-the first says where in the store this belongs, the second says what it is. That is what makes the
-published-pages navigation read like the store instead of like one long list, and
-`ctxr publish check` reports a page filed flat at the publish root as a failing check.
-
-When the notes step 2 gathered span more than one top-level folder — or the store's taxonomy declares
-none at all — no folder is derivable and the choice is yours to make and to own: pick the one that
-best names the subject to the reader, write that choice and your reason into the page's README, and
-name it to the operator. Nothing checks this for you, by design. A page whose sources aren't
-co-located is exactly the kind step 1 says most earns a page, and filing it under a word that names
-nothing serves nobody who reads it.
+## 4. Fix the identity once, at the path `gather` reported
+
+Step 2 reported the path under the store's published-pages location at which a page for this subject
+belongs, derived from where the subject's notes live. Take it verbatim, append the page's own name,
+and hand the result to `ctxr publish new <slug>`, which creates the folder and its sibling README:
+
+```sh
+ctxr publish new <reported path>/<page-name>
+```
+
+The depth is the store's own, not a fixed number of levels — a subject whose notes live four folders
+deep files four folders deep. That is what makes the published-pages navigation read like the store
+instead of like one long list. `ctxr publish check` reports a page filed flat at the published-pages
+root as a failing check, and checks nothing further about the location, because which folder is
+right is the question `gather` already answered.
+
+Name the page for what it *is*, never for its subject. The folders above it already carry the
+subject, so `<reported path>/<subject>` says one word twice while `<reported path>/decision-board`
+says something.
+
+When `gather` reports that an existing page belongs at the reported path too, it is because this
+subject is acquiring a second page, and a subject's pages collect under one folder naming it. Move
+that page there before you scaffold the new one, and tell the operator its URL changed — somebody
+may already be holding that link. `gather` moves nothing itself, and it names which signal counted
+the page as this subject's; read that before you move anything, because the signal is a reading of
+the page's README and can be wrong. Lead a page's source notes with the note it is a representation
+of — that lead link is what says whose page this is, and everything after it is a citation.
+
+When `gather` reports that no path derives — the subject names the store root itself, so no folder
+names it — the choice is yours to make and to own: pick the folder that best names the subject to
+the reader, write that choice and your reason into the page's README, and name it to the operator.
+Nothing checks this for you, by design. Filing a page under a word that names nothing serves nobody
+who reads it.
 
 A slug starting with a date (`YYYY-` or `YYYY-MM-DD-`) is reserved for a frozen snapshot — never used
 for a page you intend to keep updating. That rule binds the page's own final segment, not the folders