row 218 r3: the library-commit refusal row names a SHA-256 repository, not a moved HEAD (#1719 )

Webby round 2 N5.
row 218 r2: setup sheet gives the 1,200 character reply total, survey sheet escapes, library-commit refusal and node check (#1719 )
2026-10-21 07:01:38 -05:00 · 2026-10-21 06:57:20 -05:00 · 2026-10-21 06:43:17 -05:00 · 2026-10-21 06:39:33 -05:00 · 2026-10-21 06:28:49 -05:00
5 changed files with 401 additions and 0 deletions
@@ -0,0 +1,149 @@
+# Row 218 draft notes: claims and sources
+
+Drafts for `docs/case2/SETUP-SHEET.md` and `docs/case2/SURVEY-RUN.md`. Repo base: `refactor` at
+947101d8a, which holds 29ce1e360 (row 231). "Design" means
+`git show 75fb3e10e:agents/gosalyn/work/case2/DESIGN.md`, cited as `D:<line>`. "Brief" means
+`docs/plans/2026-10-20_case2-rows.md`. Code paths are relative to the repo root. Nothing was run
+except reads, greps and `git merge-base --is-ancestor 29ce1e360 HEAD`.
+
+## SETUP-SHEET.md
+
+| Claim | Source |
+|---|---|
+| She keeps writing in Obsidian, obsidian-git pushes to git.mosaicstack.dev, nothing changes on her machine, nothing commits to her repo | D:939-940 (7.1) |
+| Agents read what she pushed; a push reaches them in about a minute | D:1006-1007 (7.5); D:972-973 (60-second sync timer) |
+| Agents read `.md` notes inside book folders only | D:457-461 (1.2); `packages/library/src/scope.mjs:9-19` |
+| Not read: top-level notes, `.canvas`, `.base`, attachments, anything outside a book folder | D:461 |
+| Other repos under `~/src` are not read | D:489 (1.3), D:494-497 (N4) |
+| Agents can't write to her repo: canon, playground, anything | D:389 (D3); D:1008 |
+| Folder roles live in the `projects` entry of the business file, hand-edited, agents can't change it | D:409-429, D:443-451 (1.1, M9) |
+| Jason asks her to confirm the mapping first | D:431; D:1324-1328 (10 step 7) |
+| A folder named in `playground` is her playground | Brief:22; D:434 |
+| Each playground prefix sits inside one book folder | D:434-436; `packages/library/src/mapping.mjs:77-80` |
+| One per book, e.g. `<book>/playground/`; until then everything mapped is canon | D:438-439 |
+| Agents search canon unless they ask for the playground | D:463 |
+| Playground may back an idea or question, not a fact, finding or correction; refused before she sees it | D:858 (`playground-cited-as-canon`); D:378-382, D:835-839 (guard runs before store) |
+| Only the folder decides; a tag or property can't change scope | D:388 (D2); D:440-441; `scope.mjs:1` |
+| Graph colour group via Groups and a `path:` query, her own vault setting, changes nothing for agents | Brief:23; D:941-943. Obsidian UI steps from the task prompt, not the design |
+| Path starts with the books repo folder because the vault is `~/src` | D:939 |
+| N2: moving a note into a book folder makes it canon, agents may cite it as fact | D:944-945; D:259 |
+| Rough drafts outside the playground are canon | Inference from D:460 (scope rule) |
+| N4: Obsidian resolves short links across `~/src`, the reader sees one repo, the two can differ, the reader can't tell | D:494-497; D:262-263 |
+| A name only in another repo leads nowhere for agents | D:489 (R4); `packages/library/src/links.mjs:61-87` |
+| A full-path link resolves the same in both | D:497-498. Hub side: `links.mjs:77-78` (`vault-prefix` step) |
+| "New link format: Absolute path in vault" setting | Obsidian UI knowledge. Not in design or code. Reviewer may strike it |
+| `appears_in` and `relationships` links are read as links | D:489-490; `packages/library/src/reader.mjs:15`, `:153-162` |
+| Quoted flow list `["[[A]]", "[[B]]"]` parses | `reader.mjs:81-96` (flow), `:66-73` (quoted scalar), `:159` |
+| Block list with quoted items parses | `reader.mjs:117-122`, `:66-73` |
+| Unquoted `[[[A]], [[B]]]` is R3 | Brief:28-29; `reader.mjs:87` (bracket inside a flow list stops parsing), `:137` |
+| R3 effect: whole front matter unread, note still indexed by path, name and body, listed as a problem | D:480; `reader.mjs:103-105`, `:193`; `packages/library/README.md:69` |
+| Problems show in Mosaic's status | D:473-474; D:999-1000 (7.4 status line) |
+| A value without `[[ ]]` is a name | D:489-490; `reader.mjs:159` |
+| Bean and Chet keep names and personalities | D:660-661 (Q180) |
+| Hermes: free text and story text. Mosaic: short cited items, a prose request gets a question or idea | D:778-781 (design 4) |
+| Bean and Chet's item kinds: idea, question, finding, fact; web cites allowed | D:649 (`companion`); D:860 (`citation-unfetched`) |
+| Limits 10 items, 5 ideas of 200, others 300 | D:819 (M5) |
+| She or Jason can ask for lower limits | D:1329-1330 (10 step 8); D:831 |
+| "No cited answer" notice | D:870-871, D:996-997 |
+| One item can't mix two worlds | D:859 (`citation-cross-universe`) |
+| She talks to them in the Console; Hermes keeps running until she moves over; stopping it is her choice | D:381-382; D:1331 |
+| Five more helpers; she chooses the start set and can add one later | D:647-654; D:783-784; D:1327-1328 |
+| What Jason will ask | D:1325-1327 (10 step 7) |
+
+## SURVEY-RUN.md
+
+| Claim | Source |
+|---|---|
+| Runs on `<host>` 10.1.1.54 under design 10 step 7, after step 4 | D:1324; D:1266 (host) |
+| Prints names and counts, never note text, property values, file names or link targets | `packages/library/src/survey.mjs:1-6`; README:118-125 |
+| Sending to Melanie is Jason's call | Brief:36; D:1324-1328 |
+| Token slot `library-gitea` is step 4 | D:1314-1316 |
+| Run as `sudo -u mosaic -H` from `localadmin`; `mosaic` has no login shell | D:1195-1197; D:1281-1282 |
+| Copy at `/srv/mosaic/.local/share/mosaic-stack/copies/<id>`, `<id>` = commit in Jason's go | D:1286-1292 (2c); `docs/TOOLS.md:417`; home `/srv/mosaic` per D:1314-1315 |
+| The copy carries `packages/library/src` | `scripts/stack-copy.sh:36` |
+| Row 231 adds the control and bidi escapes | `git log` 29ce1e360; `survey.mjs:78-82`; README:121-122 |
+| `<node dir>` is the `--node` directory of step 2c; `scripts/mosaic` execs `node` from PATH | D:1290-1291; `scripts/mosaic:41` |
+| Dispatch: `mosaic library survey` goes to `survey.mjs` with `survey <args>` | `scripts/mosaic:37-41` (one `shift` leaves `survey` as argv[0]); `survey.mjs:102-103` |
+| Command and flags: `<repo>` plus optional `--mapping <file>` once; anything starting with `-` refuses | `survey.mjs:16`, `:104-110` |
+| No fetch; reads `HEAD` | `survey.mjs:5-6`, `:27`; `reader.mjs:22-24` |
+| Top folder only: ceiling is the path's parent | `packages/project/src/git.mjs:12`, `:62` |
+| Owner must be `mosaic`: git gets no global config | `packages/seat/src/checkout.mjs:79-89` (`GIT_CONFIG_GLOBAL=/dev/null`, `GIT_CONFIG_NOSYSTEM=1`). The dubious-ownership refusal is git's own behaviour |
+| Bus mirror path `<dataRoot>/projects/<business>/<project>` | Brief:300; `packages/project/src/paths.mjs:34-40` |
+| C2-04 and C2-03a not landed | `grep` of `packages/*/src` finds no library entry handling or `refs/heads/served`; `docs/guides/host-run-sheet.md:269` says "not landed" |
+| Served ref `refs/heads/served` | D:963 (7.2); Brief:676 |
+| Token kept out of URL, config, argv, logs | D:955-956 (7.2) |
+| Mapping file is the entry alone; `remote`, `branch` required | `survey.mjs:114-116`; `mapping.mjs:38-47` |
+| Output lines and fields | `survey.mjs:83-97`; data from `:26-76` |
+| Folder lines list folders that directly hold an entry, full path | `survey.mjs:30-35` |
+| Key names: short identifiers print, others as `(other key)` | `survey.mjs:17-20`, `:47` |
+| `unresolved` equals the R4 count | `survey.mjs:72` |
+| Scope counts cover all tree entries | `survey.mjs:66` |
+| Refusal exit codes 0, 2, 3, 4 | `survey.mjs:99-124`; README:127-129 |
+| Mapping checked before repo | `survey.mjs:112-121` |
+| stderr format `library survey: <message>` | `survey.mjs:101`; `problems.mjs:3-5` |
+| `(project-git)` suffix on git failures | `reader.mjs:18-20`; `paths.mjs:4-6` |
+| `library-playground-outside-book` message | `mapping.mjs:79-80` |
+| 100-second git timeout | `checkout.mjs:49`, `:52`; `git.mjs:68` |
+| Exit 127 when `node` is missing | `scripts/mosaic:18`, `:41` (bash `exec` failure). Not run |
+| Other errors rethrow as a stack trace | `survey.mjs:117`, `:123`, `:128-131` |
+| Don't work around a refusal | AGENTS.md invariant 6 |
+
+## Code and design disagreements
+
+1. Design 1.1 shows the mapping nested in `"projects": {"books": {...}}` (D:412-429). The survey's
+   `--mapping` file must be the inner entry alone (`survey.mjs:114-116`). The run sheet follows the code.
+2. Design 1.3 calls `vaultPrefix` part of the mapping (D:418). The code makes it optional
+   (`mapping.mjs:48`, README:30). Without it, a full vault path link, the N4 advice, resolves to
+   nothing in the hub (`links.mjs:73-87`: `root` fails, `vault-prefix` is skipped, `shortest` refuses a
+   `/`). The setup sheet's full-path advice holds only when Jason sets `vaultPrefix` to her books repo
+   folder name.
+3. The task prompt calls the unquoted form "refused". R3 is not a refusal. It is a reported problem,
+   and the note stays indexed (D:473, D:480). The sheet says what happens instead.
+
+## Open questions
+
+1. Where `<repo>` comes from on .54. The survey reads a local repo's `HEAD` and never fetches. The bus
+   mirror needs C2-04 and C2-03a, neither landed. C2-03a moves `refs/heads/served`, not `HEAD`, so the
+   mirror's `HEAD` may name no commit and the survey would refuse with exit 2. The sync also needs a
+   checked mapping with at least one book (`mapping.mjs:59`, `:70`), and the mapping's values are
+   meant to come from this survey (D:431). Sage needs to rule: a placeholder mapping for the first
+   sync, a `HEAD` the sync sets, a `--commit` flag on the survey, or another source.
+2. The brief says Obsidian's property editor writes `appears_in: ["[[A]]", "[[B]]"]` (Brief:28-29,
+   webby-0041 N4). I didn't read webby-0041 or check Obsidian's output. Both the flow and the block
+   quoted forms parse, so the sheet shows both and says only that the editor adds the quotes.
+3. Whether `/srv/mosaic/.npm-global/bin/mosaic` exists on .54. The run sheet uses the copy's
+   `scripts/mosaic` by full path to avoid depending on a wrapper.
+
+## Sage's rulings on the open questions (2026-10-21)
+
+1. Survey source: the bus's bare mirror after the first `library.sync`, the only copy on the host
+   (design 2.1). The C2-03a brief now requires the mirror's `HEAD` to be a symbolic ref to
+   `refs/heads/served`, with a test (5c6f73ed7), so the survey reads the served commit with no ref flag.
+2. Property list forms: the sheet shows both quoted forms, since both parse. Webby checks the claim
+   that Obsidian's property editor writes the quoted form.
+3. The "New link format: Absolute path in vault" tip stays. It is an Obsidian setting, not a design
+   claim, and Webby may strike it.
+4. The run sheet calls the copy's `scripts/mosaic` by full path. That holds whether or not a wrapper
+   is on `PATH`.
+5. `vaultPrefix`: the run sheet's step 4 tells Jason to set it, because the setup sheet's full-path
+   link advice depends on it.
+
+## Round 2 (2026-10-21), from Webby's round 1 notes (webby-0075, rev 2848)
+
+- N1, by Mos's ruling mos-1165 (fix before landing): SETUP-SHEET.md now gives the 1,200 character
+  total of item text per reply (design M5, step 8). The word "Today" is gone. No code enforces these
+  caps until C2-06 lands, so my ruling is that the sheet goes to Melanie only after C2-06 lands, and
+  then only on Jason's go (#419). The wording stays as is, because by then it holds.
+- N2: SURVEY-RUN.md says tab, newline, carriage return, backspace and form feed print as `\t`, `\n`,
+  `\r`, `\b` and `\f`, and other control and bidi characters as `\uXXXX` (survey.mjs quote()).
+- N3: SURVEY-RUN.md has a refusal row for `library-commit:` (reader.mjs listTree). survey.mjs turns
+  every LibraryError into exit 2 with its message.
+- N4: SURVEY-RUN.md's new step 2 checks `command -v node` under the same sudo and PATH before the
+  survey runs.
+
+## Round 3 (2026-10-21), from Webby's round 2 note N5 (webby-0077, rev 2856)
+
+- N5: the library-commit row no longer says a moved `HEAD` causes it. The survey reads `HEAD` once,
+  and listTree raises library-commit only for an id that isn't 40 hex or an object that isn't a
+  commit (reader.mjs:29, :31). In practice that means a SHA-256 repository, so a rerun doesn't help.
+  The row now says "for example in a SHA-256 repository" and "Report to Sage".
@@ -1409,3 +1409,4 @@ are never rewritten or removed; corrections are new entries.
 2026-10-21T08:52:06Z | Darkwing (Opus 5.5, 7525c8e4) | row 195 (#1693) build and manifest round 1 in review (rev 2756, request comment 29985, results 29987) | darkwing/row195-b 37171f65b on 4ced5e63d (ddf7dce6c build: scripts/case1-accept.sh, case1-accept.test.mjs, TOOLS.md entry, DESIGN r7 doc fixes per sage-1817; 37171f65b BUILD.md results); slot: single 22/22 (sage-1829), 12/12 mutants killed and gate cli 662/0 plus scripts 429/0 selftests (sage-1865), green per sage-1870; Duckworth reviews (sage-1872); Gosalyn 0087 Q4/Q5 match W10/W12; flock goes to DEFERRED with 215 (sage-1871); nothing touched .53
 2026-10-21T09:20:46Z | Sage (Opus 5.5, 1ef1e4f8) | 212+197 combined landing gate (node 981/0, selftests 429/0, 08:51-09:03Z); 197 lane proof stopped after two failures (try 1 lane-image base inspect, N7; try 3 solo-a process.test.mjs:82 under umask 077), recovered cf48efccf083; mos-1162: row 212 landed alone as ee7b2f137 (paths match a2c72ac95, patch-id ea84d3e35470), #1713 closed 29996, revs 2759-2760; DEFERRED N7 plus brief docs/plans/2026-10-21_gate-env-rows.md at fefd54e13, rows 243 (chmod) and 244 (fixture PI_AUTH_FILE) revs 2761-2762; row 66 rebuilt as sage/row66-r4b 49ad61963 on fefd54e13 (manifest 99cab8275af4, not yet requested); slots: Herb 215 focused 26/0, Gosalyn 231 singles 60/0, Herb 197 r6 focused granted; kept root ga-8I3iZc removed (sage-1827..1893) | in progress
 2026-10-21T10:12:45Z | Darkwing (Opus 5.5, 7525c8e4) | row 245 (#1693) built, slot asked (darkwing-0105) | claim rev 2795; darkwing/row245 0590a29fc pushed, on 62ddc96cc: 5273de0b7 cherry-pick of 1e3c4767c (case1-accept.sh, test, TOOLS.md blobs identical) and 0590a29fc notes to queue-245/BUILD.md (DESIGN.md:336-338 superseded by gosalyn-0087, unedited, sage-1877); slot scripts in /mnt/storage/scratch/darkwing-245-out pinned to 0590a29fc, nothing run; told Sage the untracked queue-195 DESIGN.md was r2 (fcbb4aa9b = 818b79696), nothing lost; flagged 245 and 246 both closing #1693
+2026-10-21T11:28:49Z | Sage (Opus 5.5, 1ef1e4f8) | 235 landing gate (bus 596/0, business 200/0, cli 666/0, scripts green) and landing b1fece6f0, #1741 closed 30026; 197 r6 D5 proof stopped at solo-a script-release (Compose run has no --no-build, reproduced in lane env), #1695 30031; 221 landed before 197 r7 (sage-1954): gate 11:07-11:19Z (test 11/0, harness 140/0, cli 677/0, scripts green), 300766450, #1722 closed 30033, revs 2812-2813; C2-20b brief and DEFERRED N3 in 335bb3e30, row 247 #1749 briefed; 197 r7 9c3166915 focused run on my slot (red 9/2, green 11/0, mutant killed), request rev 2819 (30036), proof candidates A 2be6d07fa and B cceb258ff ready; slots Herb sage-1956, Darkwing 245 sage-1961 (sage-1894..1962) | in progress
@@ -0,0 +1,125 @@
+# Your books in Mosaic: a setup sheet
+
+This sheet is for you, Melanie. You keep writing in Obsidian the way you do now. Mosaic reads your
+books repo after obsidian-git pushes it to git.mosaicstack.dev. It changes nothing on your machine and
+commits nothing to your repo.
+
+## What the agents read
+
+The agents read your books repo as you last pushed it. A push reaches them in about a minute.
+
+They read notes, the `.md` files, inside your book folders. They don't read:
+- notes at the top of the repo, outside any book folder
+- `.canvas` and `.base` files, even inside a book folder
+- images and other attachments
+- anything in your other repos under `~/src`
+
+They can't write to your repo at all. That covers canon, the playground and everything else.
+
+Which folders are book folders, and which hold characters, places, research, your tracker or chapter
+summaries, is set in one place. It is the `projects` entry of your business file in Mosaic. Jason
+edits it by hand, and the agents can't change it. He will ask you to confirm it before the agents start.
+
+## Your playground
+
+A folder named in the `playground` list of that entry is your playground. Each playground folder sits
+inside one book folder, so one per book works well, for example `<book>/playground/`. You choose the
+names and tell Jason. Until you have one, every note in a book folder is canon.
+
+What the playground means for the agents:
+- They search canon unless they ask for the playground on purpose.
+- An agent may quote a playground note in an idea or a question. It may not use one to back a fact,
+  a finding or a correction. Mosaic refuses that reply before you see it.
+- Only the folder decides. A tag or a property can't make a note playground or canon.
+
+### Colour the playground in your graph
+
+This is a setting of your own vault. It changes nothing for the agents.
+
+1. Open the graph view and open its settings panel.
+2. Under Groups, choose New group.
+3. In the query box, type the playground's path with `path:`. Your vault is `~/src`, so the path
+   starts with your books repo folder: `path:"<books repo folder>/<book>/<playground folder>"`.
+4. Pick a colour.
+
+Add one group per playground folder.
+
+## Two things you might not expect
+
+### Moving a note into a book folder makes it canon
+
+The folder decides, so a move changes what the agents may do with a note. Once you move a note out of
+the playground into a book folder and push, it is canon. The agents may then cite it as fact. A note
+that isn't settled yet belongs in the playground. Any note in a book folder outside the playground is
+canon, rough drafts included.
+
+### A short link can point somewhere else for the agents
+
+Obsidian looks up a short link like `[[Mara]]` across your whole vault, `~/src`. The agents see only
+your books repo. Say a note called `Mara` exists in your books repo and also in another of your repos.
+Obsidian and the agents can then open different notes for the same link, and the agents can't tell.
+If the name exists only in the other repo, the link leads nowhere for the agents.
+
+A link with the full path from the top of your vault reaches the same note in both:
+
+```
+[[<books repo folder>/<book>/<characters folder>/Mara]]
+```
+
+Obsidian can write new links this way. In Settings, open Files and links and set New link format to
+Absolute path in vault.
+
+## Lists of links in properties
+
+The agents read the links in two properties, `appears_in` and `relationships`. Put quotes around each
+link in the list:
+
+```yaml
+appears_in: ["[[A]]", "[[B]]"]
+```
+
+One link per line works too:
+
+```yaml
+appears_in:
+  - "[[A]]"
+  - "[[B]]"
+```
+
+Obsidian's property editor adds the quotes for you. If you type the list by hand, don't leave them out:
+
+```yaml
+appears_in: [[[A]], [[B]]]
+```
+
+The agents' reader can't read that form. It then ignores every property of that note and lists the
+note as a problem in Mosaic's status. It still finds the note by its path, its name and its text. A
+value written without `[[ ]]` counts as a plain name, not a link.
+
+## What changes for Bean and Chet
+
+They keep their names and personalities. How they answer changes.
+
+In Hermes they answer in free text and may write story text when you ask. In Mosaic every reply is a
+short list of items. Each item is an idea, a question, a finding or a fact. Each one quotes a line
+from your repo or from a web page the agent read for you.
+
+They don't write passages. If you ask for prose, you get a question or an idea instead.
+
+A reply holds at most 10 items and at most 1,200 characters of item text in all. It has at most 5
+ideas of up to 200 characters each. A question, finding or fact runs up to 300 characters. You or
+Jason can ask for lower limits. When an agent can't back an answer with a quote, you see "No cited
+answer" instead.
+
+Each book world stays separate. One item can't mix quotes from two worlds.
+
+You talk to them in the Console. Hermes keeps running until you have moved over, and stopping it is
+your choice.
+
+Five more helpers can join them: ideas, research, proofreader, fact-checker and continuity. You
+choose which ones to start with, and you can add one later.
+
+## What Jason will ask you
+
+He will ask you to confirm your book folders and type folders, which books share a world, the name of
+each playground folder, and which helpers to start with and when.
@@ -0,0 +1,122 @@
+# Survey run sheet for the library host
+
+This sheet is for whoever runs `mosaic library survey` on `<host>`, 10.1.1.54, under design 10 step
+7. The survey reads one commit of a git repo and prints names and counts. It never prints note text,
+property values, file names or link targets. Jason fills in the mapping for Melanie's books repo
+from its output and her answers.
+
+Out of scope: sending anything to Melanie. Design 10 step 7 makes that Jason's call.
+
+## Before you start
+
+- Jason's go for step 7. Step 4, the bot token in the `library-gitea` slot, comes first.
+- You run as `mosaic` with `sudo -u mosaic -H` from `localadmin`. `mosaic` has no login shell.
+- The stack copy from step 2 is in place at `/srv/mosaic/.local/share/mosaic-stack/copies/<id>`.
+  `<id>` is the full commit id in Jason's go. It must hold row 231, which escapes control and bidi
+  characters in folder names. In a canonical checkout, `git merge-base --is-ancestor 29ce1e360 <id>`
+  exits 0 when it does.
+- `<node dir>`, the directory that holds `node`. It is the directory of the `--node` path given to
+  `case2-unit.sh` in step 2c. `scripts/mosaic` runs `node` from `PATH`.
+- `<repo>`, an absolute path. See the next section.
+
+## The repo to survey
+
+The survey reads a local repo. It doesn't fetch. `<repo>` must:
+- be the repo's top folder, or a bare repo's own folder. A folder inside a repo refuses, because the
+  survey stops git from looking above the path's parent.
+- belong to `mosaic`. The survey gives git no global config, so a `safe.directory` entry can't
+  admit a repo another user owns.
+- have a `HEAD` that names a commit. The survey reads `HEAD` and has no flag for another ref.
+
+`<repo>` is the bus's bare mirror at `<dataRoot>/projects/<business>/<project>`, which C2-04 (row 215)
+creates and C2-03a (row 222) fetches into. It is the only copy of her repo on the host (design 2.1), and
+`mosaic` owns it. Survey it after the first `library.sync` succeeds. The mirror's `HEAD` points at
+`refs/heads/served` (C2-03a brief), so the survey reads the commit the agents are served.
+
+Don't survey anything else. A hand clone with the bot token would put the token where design 7.2 keeps
+it out, and the mirror's refs belong to the bus. If `HEAD` names no commit, stop and report to Sage.
+
+## Steps
+
+1. `ssh [email protected]`.
+2. Check which `node` runs. `PATH` ends in `/usr/bin:/bin`, so a wrong `<node dir>` would quietly run
+   another `node`:
+
+   ```sh
+   cd /
+   sudo -u mosaic -H env PATH="<node dir>:/usr/bin:/bin" sh -c 'command -v node; node --version'
+   ```
+
+   The first line must be `<node dir>/node`. If it isn't, fix `<node dir>` before going on.
+3. Run the survey without a mapping:
+
+   ```sh
+   cd /
+   sudo -u mosaic -H env PATH="<node dir>:/usr/bin:/bin" \
+     /srv/mosaic/.local/share/mosaic-stack/copies/<id>/scripts/mosaic library survey <repo>
+   echo "exit $?"
+   ```
+
+4. On exit 0, give the output to Jason. On any other exit, see "Refusals" below.
+5. When Jason has a draft mapping, run it again with `--mapping`. The file holds the library entry
+   alone, `{"kind": "library", "remote": ..., "branch": ..., ...}`, without the business file or the
+   `"projects"` wrapper around it. `remote` and `branch` are required even though the survey doesn't
+   fetch. `mosaic` must be able to read the file. Set `vaultPrefix` to her books repo's folder name
+   in her vault. Without it, a link with the full path from the top of her vault resolves to nothing,
+   and the setup sheet tells her to write links that way.
+
+   ```sh
+   sudo -u mosaic -H env PATH="<node dir>:/usr/bin:/bin" \
+     /srv/mosaic/.local/share/mosaic-stack/copies/<id>/scripts/mosaic library survey <repo> --mapping <file>
+   echo "exit $?"
+   ```
+
+The usage line is `mosaic library survey <repo> [--mapping <file>]`. `--mapping <file>` is the only
+flag, and it may appear once. `--mapping=<file>` and every other flag refuse.
+
+## What the output holds
+
+Plain text on stdout, one line per item:
+
+| Line | What it holds |
+|---|---|
+| `commit <id>` | the 40-hex commit `HEAD` names |
+| `entries <n>` | every entry in that commit's tree |
+| `folders (direct children: md canvas base other)` | then one line per folder that holds a file directly: its path as a JSON string and four counts. `(root)` is the repo's top |
+| `markdown <n> files, <n> read, ...` | `.md` files, how many were read, how many have no front matter, how many have front matter the reader can't fully parse |
+| `front matter key sets` | then `<count> [<keys>]` per set of property names. A name that isn't a short identifier prints as `(other key)` |
+| `body links plain .., label .., heading .., embed .., self .., markdown ..; attachment ..` | link forms in note bodies, and embeds of a target with an extension other than `.md` |
+| `field appears_in wikilink .., name ..` | values written as links and as plain names. A `relationships` line follows |
+
+With `--mapping` three lines follow:
+
+| Line | What it holds |
+|---|---|
+| `scopes canon .., playground .., unmapped ..; indexed ..` | tree entries per scope, and notes indexed |
+| `resolved root .., vault-prefix .., relative .., shortest .., unresolved ..` | links per resolver step. `unresolved` is the R4 count |
+| `problems R1 .., ..., R7 ..` | problems per rule |
+
+Folder paths and short property names are the only words from her repo in the output. In a folder
+name, tab, newline, carriage return, backspace and form feed print as `\t`, `\n`, `\r`, `\b` and `\f`.
+Any other control or bidi character prints as `\uXXXX`.
+
+## Refusals
+
+A refusal prints nothing on stdout and one line on stderr. The survey checks the mapping before the
+repo, so a bad mapping gives exit 3 even when the repo path is wrong too.
+
+| Exit | stderr | Cause | What to do |
+|---|---|---|---|
+| 4 | `library survey: usage: mosaic library survey <repo> [--mapping <file>]` | no repo, two repos, an unknown flag, `--mapping` without a file or twice | Fix the command |
+| 3 | `library survey: library-mapping-invalid: <file> is not a readable JSON file` | missing, unreadable by `mosaic`, or not JSON | Fix the file or its mode |
+| 3 | `library survey: library-mapping-invalid: <file> <reason>` | the entry breaks the schema. The reason names the key | Give it to Jason for the draft |
+| 3 | `library survey: library-playground-outside-book: <file> universes.<u>.playground "<prefix>" is not inside one of its books` | a playground prefix outside its universe's books | Give it to Jason for the draft |
+| 2 | `library survey: library-git: <repo> is not a directory` | wrong path | Check `<repo>` |
+| 2 | `library survey: library-git: repository has no readable HEAD commit (project-git)` | not a repo, a folder inside one, another owner, no commits, a `HEAD` with no commit, or no `git` on `PATH` | Check each. If `<repo>` is the bus mirror, stop and report to Sage |
+| 2 | `library survey: library-git: <other reason>`, such as `tree listing refused (project-git)` | git failed or ran past 100 seconds | Report to Sage |
+| 2 | `library survey: library-commit: <reason>` | `HEAD` names something the reader can't take as a commit, for example in a SHA-256 repository | Report to Sage |
+| 127 | a line ending `exec: node: not found` | `node` isn't in `<node dir>` | Fix `<node dir>` |
+| other | a Node stack trace | a fault in the survey | Stop and report the exit code to Sage |
+
+A refusal is the answer, not an obstacle. Don't run as another user, change modes on her repo or edit
+its refs to get past one.
@@ -675,6 +675,10 @@ Design 7.2's slice:
 - An `https://` URL only.
 - The served ref `refs/heads/served`, and `library-diverged`, held until a human `library.sync --accept
  <commit>`.
+- The mirror's `HEAD` is a symbolic ref to `refs/heads/served`, so `mosaic library survey <mirror>` reads
+  the served commit. The survey reads `HEAD` and has no ref flag, and design 10 step 7 surveys this mirror
+  (C2-12 run sheet; Sage, 2026-10-21). Test: after the first sync, `git symbolic-ref HEAD` in the mirror
+  prints `refs/heads/served` and the survey's `commit` line equals the served commit.
 - The sync state file, written atomically inside the mirror, and the 60-second timer.
 - `library.sync`, human only. A test reaches a local bare repo only through the module parameter that
  replaces `syncCommand`.
Author	SHA1	Message	Date
jason.woltje	89ba79d94b	row 218 r3: the library-commit refusal row names a SHA-256 repository, not a moved HEAD (#1719 ) Webby round 2 N5.	2026-10-21 07:01:38 -05:00
jason.woltje	5fcc2ec90e	row 218 r2: setup sheet gives the 1,200 character reply total, survey sheet escapes, library-commit refusal and node check (#1719 ) Webby round 1 N1 by mos-1165, and N2-N4.	2026-10-21 06:57:20 -05:00
jason.woltje	fc0d9c26fc	row 218: C2-12 setup sheet for Melanie and the library survey run sheet (#1719 ) Doc only. docs/case2/SETUP-SHEET.md and docs/case2/SURVEY-RUN.md, with claim sources and rulings in agents/sage/work/queue-218/BUILD.md. Survey flags, output lines and exit codes from packages/library/src/survey.mjs and scripts/mosaic:37-41.	2026-10-21 06:43:17 -05:00
jason.woltje	5c6f73ed75	plans: C2-03a brief, the mirror HEAD is a symbolic ref to refs/heads/served so the C2-12 survey reads the served commit The survey reads HEAD and has no ref flag, and design 10 step 7 surveys the bus mirror. Row 222 is not built yet, so this adds one requirement and one test to its brief before the build starts.	2026-10-21 06:39:33 -05:00
jason.woltje	947101d8a3	sessions: Sage 235, 221 and C2-20b landings, 197 r7 request and proof prep	2026-10-21 06:28:49 -05:00