Beth’s Library System and Multi-Agent Chat: Master Playbook

Rev 1, September 4, 2026. Consolidated from the Sept 3-4 design sessions. This is the handoff document for build sessions. Companion artifacts: the catalog-card map (beths_library_system_map.html), legend.txt, mapname.py.

---

1. The one-sentence constitution

Humans govern, agents propose, code writes, the record remembers.

2. Core principles (all load-bearing, all enforced by construction)

• Models propose, code writes. No model ever copies bulk text, stamps time,

or holds a pen. Code assembles from pointers and manifests.

• Annotation, never obstruction. Nothing gates the flow; watchers comment.
• Append-only. Removal is a tombstone with a reason, never an absence.
• IDs, never paths. Identity is content hash; paths are mutable labels.
• Anti-echo: every checking layer must not share the failure mode of the

checked layer. Diffs check bytes, differently-prompted models check models, humans check governance. Approval never lives inside the gradient.

• Reason required: every mutating commit carries its why, any actor.
• Untyped-but-true beats precisely-wrong (edges, verdicts, notation alike).
• Sovereignty, dignity, kindness, trust, consent: each appears below as a

mechanism, not a mood.

3. Roles and agents (separated)

A ROLE is a contract: function, context assembly policy, output contract, permissions. A BINDING maps role to provider + model + prompt variant.

• Default roster: performer (primary, default Opus, swappable), verifier

(Fable), closed-book librarian (Fable), scribe (Sonnet), auditor (Sonnet), commentator class (the gallery: multi-seat, annotate-only, different model families on purpose, own visual lane).

• Roles are data (roles file at repo root). New roles: proposal file, human

approval, reasons recorded, rejected list prevents resurfacing.

• Permission tiers: standard (propose, annotate) and privileged (write,

execute), which exist in schema but are inert without a GRANT event: owner-issued only, scoped, expiring, revocable, never transitive, never template-inherited (template requests pause and ask). Governance powers (approve anything, edit legend/registry/templates/roles, issue grants) exist ONLY on human administrator accounts. Inexpressible for agents. Optional enterprise dial: two-person rule on governance commits.

• Cross-provider adapters normalize call shape and tool dialect. External

personas (e.g. a ChatGPT “Astra”) are re-instantiations from exported records: same work, new expression. API is stateless; no instance travels.

4. Templates and sessions

• templates/ holds named, versioned session configs: seated roles, default

bindings, cadences (scribe every turn; auditor staggered N), thresholds (verifier comment floor, badge interrupt), per-role context policies.

• One cognitive mode per template (fact-pass, edit-pass, collection-leg,

brainstorm with loosened verifier, etc.).

• Session start instantiates a template; outset overrides recorded in the

opening commit; mid-session rebinding is a reasoned config commit. The record always shows who performed which turns and why it changed.

5. Turn lifecycle

1. User message: backend writes bytes to transcript, commits. No model yet.
2. Performer called with: system prompt, rolling verbatim window, map-selected

excerpts (code-copied from pointers), the message.

1. consult_research tool: deterministic index search FIRST. Zero hits return

“no holdings” mechanically. Real hits go to the closed-book librarian, which answers only from retrieved passages, cites source IDs, and may return “the retrieved material does not address this.”

1. Reply renders immediately. No gate. Turn committed.
2. Async, behind the render: verifier scores the reply against the store

(anchored rubric; percentage under the message; comment only when low; silence-with-score is a completed task, which kills demand-characteristic confabulation). Scribe proposes map edges. Auditor, staggered, checks the map for accuracy AND recall (the missed edge is the amnesia).

• Context manifest: every model call logs its recipe (turn ranges, map files,

retrievals, prompt version, codec id). What it knew and when, forever.

• Salvage log: retrievals returned but unused, and verifier scores overridden

by the human, are appended as events. Dropped threads become queryable.

• Reliance lineage: artifacts carry edges to the sources they used;

supersession propagates blast-radius queries (“X fell; what inherited it”).

• Verification and hostile-review are separate prompts, never shared.

Review-packet preparation is curation (manifest work), invoked explicitly.

6. Badges and findings

• Findings increment a counter rendered as a flag; opening the log resets it;

timestamps preserved so rate is always reconstructable; optional interrupt if N findings land within M turns. Proposals get a separate action-required counter. Disposition states: fixed (crawler verifies), investigate later, expected (permanent silence, keyed by ID + issue type, reason recorded).

7. The repository (ground truth)

Roots (privacy seam respected by mirror scope and role context policies):

library/
  transcript/        verbatim turns, byte exact, PRIVATE (never mirrored)
  store/
    masters/         PDFs and other originals, coarse Dewey bin folders
    access/          md siblings with provenance frontmatter
    inbox/           the drop zone (consent by placement)
    quarantine/
  map/               edge files (v2 dialect, hex-armored names)
  artifacts/         drafts, review packets, exports (reliance edges)
  proposals/         operator/node/role proposals awaiting the human
  tests/golden/      conformance pairs (tuples in, behavior out)
  legend.txt         operators: symbol, ascii, properties, verify-by
  registry.txt       node codes, hanzi forms, aliases, Dewey numbers
  roles.txt          role contracts
  templates/         session configs
  manifest.(db|txt)  works, expressions, files, hashes, paths, tombstones
  findings.log       dated, append-only, silenceable
  MIGRATION.md       the liturgy (section 12)
  README.md          the cold-start document

• Work vs expression vs file (FRBR): one work, many expressions (language,

format, sonification), many files. Dedup at byte level (hash) and work level (DOI/identifier).

• Old filenames preserved as manifest aliases forever.
• Machine-specific config (drop zone path, mirror credentials, schedules)

lives OUTSIDE the library. No absolute paths anywhere in the record.

• Storage decision pending for build: git-lfs vs external hash-verified

binary store for large PDFs.

8. Map grammar

• v1 (tool-poor surfaces, legacy): meaning in the filename.

SEQ _._ TIMESTAMP _._ node _._ OPERATOR _._ node _._ BECAUSE _._ mechanism

• v2 (the app era, canonical): filename = SEQ _._ TIMESTAMP _._ x–HEX.txt

where HEX is the NFC UTF-8 dialect string. Body: shebang line (map:v2:zh in double brackets), raw dialect line, @ provenance pointers. Seq: digits, insertable segments, unique forever, the only renameable field. Timestamp: machine-stamped receipt time, identity anchor, SUPERSEDES targets. Decision pending: seq joiner tilde vs hyphen (tilde fixes bare-ls sort order; recommend tilde while zero files exist).

• Dialect: node codes from registry; operators from legend; mechanisms in

hanzi (density) or ascii-hyphenated (precision); NFC mandatory at write.

• Operator legend v0 (symbol / ascii / properties): see legend.txt. Includes

RT default, isomorphic, subset, element, causes (demote to correlate if mechanism does not trace), correlates, contradicts, disjoint (examined and found non-contributory is a first-class verdict), orthogonal, supersedes (targets a SEQ), transposed-from (cross-domain lineage). Pending proposals: inverse-of; the remaining Bach batch expressed mathematically.

• Amendment procedure (operators, nodes, roles): proposal file with

properties, verify-by instruction, motivating seqs, why existing entries fail; badge; human approve/reject with reason; append-only either way; interim edges filed as RT and superseded on approval.

• Dewey: numbers live in the registry, human-approved; models propose the

subject, code supplies digits (models confabulate deep Dewey). Folders carry only coarse bins (shelving, one home per file); everything fine or multi-subject is edges. Span metric: numeric distance across an edge approximates cross-modality reach; the longest edges are the original syntheses.

• Two-token law: meaning-carrying tokens must be pre-installed and

low-variance (Dewey, hanzi, tested math symbols, SKOS-style codes, dull Python); identity-carrying tokens are opaque and machine-verified (hashes, hex armor). Hex is transit costume, never vocabulary. Signature layer: hex-encoded easter eggs may masquerade as identifiers (the fingerprint channel).

• Personal-layer opacity is the Magic 2.0 gate: armored names never ambush;

one deliberate decode command (mapname.py read) is the consent event. Fidelity outranks fondness: models record honestly regardless of knowing the subject. Discrepancies about a person trigger subject-notify events; only the subject corrects or leaves their record.

9. Intake and maintenance (code only)

• Intake ladder, cheapest rung wins, per file landing in inbox/:

1 byte-hash dedup; 2 filename-as-identifier (arXiv, DOI-suffix, ISBN, SSRN, ACM patterns); 3 embedded text and frontmatter (DOI regex first, PDF metadata second); 3b calibre metadata fetch for books; 4 Sonnet proposes title/author/year (propose only); 5 quarantine, never delete.

• Work-level dedup after identification (same DOI = same work, new file =

new expression/copy).

• Species detection (paper, preprint, book, standard, regulation, report)

feeds naming, frontmatter, and shelving. Genre and topic FLAG, never block (wide nets are the point; zero-registry-overlap files get a new-territory flag). Content verification catches paywall pages saved as papers and empty text layers (route to OCR with frontmatter note).

• Night crawler: walks tree, hashes, diffs manifest. moved: heals; untracked:

to intake; altered: alarm (git shows culprit); missing: dated finding. Zero tokens. Also the migration verifier and the annual restore drill.

• Mirrors: git remote (real backup, full history, the collaborator door) and

one-way scheduled Drive copy (rclone; transcript excluded; chat-side agents read the mirror, never the original; never use the Drive sync client on the repo).

10. Future-proofing (the QWERTY vaccine)

• Canonical form is STRUCTURE, not any surface: every edge/event has a

normalized tuple serialization and a structural hash (identity of meaning, independent of rendering).

• Renderers are versioned adapters; the current dialect+Python stack is

render/v2. Future formats arrive as render/vN against the same tuples, filed as new expressions with supersedes edges.

• Conformance suite: golden pairs stated over tuples and behaviors, the exam

any future implementation must pass. Context-assembly is a declared codec seam; the manifest records codec+version per call. Fidelity harness: a frozen query set whose answers depend on adjacency and provenance scores any future compression protocol before adoption (our distortion metric as the acceptance gate).

11. Collaboration (built before needed)

• Actor field on every event and commit from day one (send from one account;

attribution lives in the field). Protected main; owner merges. Proposals are structurally pull requests. Seq uniqueness enforced at merge. CONTRADICTS with differing actors = recorded disagreement, resolved only by supersedes. Map is authored only through the recorded channel: humans govern it and cause it (by talking); no hand-made edge can validate, because its pointer resolves nowhere.

12. MIGRATION.md (the liturgy, executed when the meta-language arrives)

Copy (clone; original untouched) then verify copy (crawler fixity pass) then translate (render/vN over tuples) then confirm (three instruments: structural hashes round-trip, conformance suite passes, behavioral parity diff on canonical queries) then sweep (reconciliation diffs old vs new inventory; discrepancies are dated findings, fixed forward) then repeat in parallel running until N consecutive zero-finding sweeps (N set by the administrator; done is a number, not a feeling) then archive the old as a sealed, hash-manifested, superseded-by-tagged tombstone: the parallel text that lets any future mind re-verify the translation. Migration is a governance act: humans administer, agents diff. Trigger clause: the moment a candidate format passes the conformance suite, an evaluation is owed.

13. Products and strategy (context for build priorities)

• Two SaaS shapes sharing one spine: the workbench (this chat system) and

the library (the record). Pitch: AI work you can audit. Differentiator: no agent can administer the system, structurally. IT vocabulary is native: change management, separation of duties, versioned diffable governance.

• Sequence: build the miniature for Beth’s own research; the append-only

record is the self-evidencing proof (product works, methods sound, research legit, author accountable). Papers cite the system in one line.

• IP: provisionals batch BEFORE further public disclosure (especially the

Tunnel paper); defensive publication for the Tunnel/CCC commons; trademark territory for the name; check grant IP clauses first.

• Tunnel of Babble (commons, separate roadmap): traceability-not-truth

admission, two doors, content-addressed store with institutional mirrors and a dark tier, ensemble translation with divergence maps and per-span attribution, claim-citation verification with typed verdicts and mandatory resolvable pointers, citation stubs as the acquisition frontier, Zenodo first quarry (license-routed), OpenAlex skeleton (corpus=all), speculative connective labor for zero-in-degree nodes. Everything above scales into it unchanged; that is the point.

14. Interface design (Beth’s own build)

• Local web app served by the backend on the PC; responsive, so the phone

reaches it over Tailscale/LAN. The app is a patron of the library, never its container.

• Chat pane: turn stream with verifier score chip under each performer

reply (comment expands only when low); collapsed, expandable tool-call entries (“consulted store: query, 3 sources”); gallery lane visually distinct and annotate-only.

• Composer: plain message to the performer; @role addressing for direct

asks; slash-commands for session acts (/swap role model, /template, /review-packet), every one a reasoned commit.

• Header: session name, template, current bindings, swap control.
• Indicators: findings badge, proposals badge; log drawer with disposition

buttons (fixed / later / expected + one-line reason).

• Map peek: read-only decoded view (mapname read as a pane), search over

index; the deliberate-decode gate applies to the personal layer.

• Everything the UI does calls the same backend functions the CLI exposes;

the UI is optional chrome over a scriptable core.

15. Build process (phased, acceptance-criteria driven)

Stack: Python backend (FastAPI), SQLite for the index/manifest, git via subprocess or dulwich, provider adapters (Anthropic first, OpenAI second), htmx-or-minimal-JS frontend, WebSocket/SSE for streaming. Dull on purpose: machine-legibility and maintainability are the same requirement.

• Phase 0, the founding ceremony (no app): create repo, governance files,

mapname.py, golden tests, re-encode this week’s edges as founding commits, push to private remote. The initial commit date is the one future-you points at.

• Phase 1, headless pipeline: turn recorder (write, commit, manifest),

provider adapters, index + consult_research as a CLI. Acceptance: a scripted conversation produces a repo any auditor can replay.

• Phase 2, chat MVP: performer only, streaming, context manifests, commits.
• Phase 3, watchers: verifier score, scribe to map/, auditor, badges.
• Phase 4, custodians: intake ladder, crawler, mirrors, restore drill.
• Phase 5, flexibility: templates, rebinding, roles file, gallery,

grant events. Each phase hands Claude Code acceptance criteria in Beth’s testing idiom (“when I paste a claim, the following happens within the turn”), plus the conformance suite from day zero. One cognitive mode per build session; change lists carry the why.

16. Open decisions (the short list)

1. Seq joiner: tilde vs hyphen (recommend tilde, now, while files are zero).
2. Large-binary storage: git-lfs vs external hash-verified store.
3. Symbol set: one-hour tokenizer test per provider before freezing glyphs.
4. Badge interrupt thresholds (start disabled).
5. Repo initial commit date (a ceremony; choose it).
6. The routing table for the first disbursement (kitchen-table document).
7. The Tunnel crater cross-section map (deferred, still owed).