---
contract: cards_v2
filed: 2026-04-28
sprint: S152
sovereign: jr / John Reed (L4)
status: draft — awaiting sovereign sign-off before card prose work begins
supersedes: implicit V2 schema patterns spread across S143–S151
broadcast: pending (Hazel Dell, intake desk; daily comms)
---

# cards_v2 — the contract

This directory is the canonical home for the complete rewrite of the
26 simulation cards (40a–40z). The existing cards in
`~/garrison/gn-integrations/` and their sidecars in
`~/garrison/gn-integrations/walkthroughs/` are not deleted; they are
read-only reference for this rewrite and remain live until cards_v2
is promoted.

The rewrite is driven by one decision: **the cards stop asking the
visitor to choose and start letting the visitor watch.** Click-only
navigation, optional narration, real cryptography behind a calm
visual surface, and a per-card take-away the visitor accumulates as
they walk. A graduation bundle compiles everything they collected
into one signed package they can paste into their own LLM for an
independent read.

## Scope

In scope for this directory:

- 26 rewritten card prose files (`.md`), one per sim (40a–40z)
- 1 bonus card (`41_sim_one_million_first.md`) — builder's
  killer-app sim crediting DeAngelo's million-killer-apps
  framing as inspiration (not endorsement)
- 27 matching JSON sidecars carrying the V2-plus schema additions
- The CONTRACT (this file)
- The schema delta (`SCHEMA_V2_PLUS.md`)
- The card template (`TEMPLATE.md`, `TEMPLATE.json`)
- The builder-card skill at `skill/builder-card-skill/` —
  clone-friendly authoring kit with templates, governance, and a
  worked example. Lets authorized users (Garrison Node members,
  bitcoinarchive.org collaborators, UOX_rebuild contributors,
  L2/L3 trusted users) and council-recognized agents author new
  sims under the same contract.
- The verification report (`verification/CLAIMS_AUDIT.md`)
- The 26 source extracts from the uploaded RTF (`sources/`)
- The 40a HTML preview (`preview/40a_preview.html`)

Not in scope (separate engineering threads):

- The runtime changes in `walkthrough.js` that read the new schema fields
- The CSS for the per-card attestation strip
- The Web Speech API binding for narrate
- The Cloudflare endpoint that relays click events to JAR9 / Mini Mac
- The fingerprint-accumulator JS module
- The graduation-bundle compiler

The contract specifies what those engineering pieces consume; the
implementation is the next sprint's work.

## Interaction model — watch, then think out loud

Every card auto-plays. Cursor moves through waypoints, dwells, advances.
The visitor never has to type, never has to pick, never has to commit.
Two navigation affordances and two only:

- **Back arrow** — return to the previous card in the series
- **Next arrow** — advance to the next card in the series

Four optional surfaces, all at the visitor's discretion:

- **Narrate** — read the current card's prose aloud (Web Speech API,
  client-side, no audio leaves the device)
- **`.md`** — copy the current card's structured markdown module into
  the visitor's tag-along bundle (see "Tag-along — modular composition"
  below)
- **Attestation strip** — expand the cryptographic detail at the
  bottom of the card
- **Comment + Claude review** — one comment field per card. On
  submit, the runtime opens claude.ai in a new tab with the card's
  `.md` summary plus the visitor's comment pre-filled as a prompt.
  Claude returns its current independent opinion. The visitor is
  invited back to MerkleTrust to post the dialogue as: "this is me
  and Claude questioning / commenting on this sim." Round-trip
  critical review, the visitor's terms.

The four V2 interactive types (`text`, `choice`, `textarea`, `dropzone`)
are deprecated for cards_v2 in their forced-decision form. The cards
do not gate on visitor commitment to a path. If a sim's narrative
needs to show the visitor "and then they typed in their name," the
cursor types it via the existing autofill animation. The visitor
watches; the visitor does not perform.

The new interactive surface — comment plus Claude redirect — is the
inverse of the old: instead of asking the visitor to commit to one
of three options the designer wrote, it invites the visitor to put
their own thought against the card and run it past a critical
reviewer. The walkthrough is the test drive; the comment surface is
the test drive's onboard chat with a peer.

## Tag-along — modular composition

Every card carries a `.md` button at the bottom. One click adds the
card's structured markdown to the visitor's session-scoped bundle.
The bundle accumulates across the whole 26-card walk. At graduation,
the bundle is compiled into one downloadable file — `journey.md` —
the visitor can paste into Claude, ChatGPT, Gemini, or any LLM they
trust for an independent review.

Each card's `.md` is self-contained. Title, audience, what happened,
what data moved, what cryptographic operation fired, what the visitor
can verify, where the foundation invites a build-on. Computer-optimized
for LLM consumption, not marketing-optimized.

The longer-term intent: the 26 .md files are modular blackboxes —
think Lego blocks. A future visitor returning with a real project can
mix and match: take 40e (legal evidence) + 40g (gov sunshine
disclosure) + 40m (asset-recovery chain) and hand the composite to an
LLM with the prompt: "compose a Garrison Node configuration that
covers what these three cards describe, at the minimum complexity
that satisfies all three." The cards are not a single linear story;
they are a vocabulary the visitor can recombine.

This is why the `.md` button does not lift the card's visitor-facing
prose. The prose is for humans walking the sim. The `.md` module is
the contract a future LLM (or future engineer) can read to reason
about the card's behavior cleanly.

The bundle never leaves the device unless the visitor exports it. It
is built in browser memory, appended-to per click, and either
downloaded at graduation or discarded when the tab closes. No server
round-trips, no cookies, no analytics.

## Comment + Claude review — round-trip critical reading

Every card carries one comment field at the bottom, just above the
attestation strip. Visitor types a sentence or paragraph — a question,
a doubt, a counter-example, a thought to test. On submit, the runtime
constructs a Claude.ai prompt that combines:

1. The card's `.md` module (computer-optimized summary, same content
   the tag-along produces)
2. The visitor's comment, verbatim
3. A short framing line: "Above is a Merkle Trust walkthrough card.
   The user has the following thought / question / objection. Give
   your current independent take. Be specific about what holds up
   and what doesn't."

The prompt is opened in claude.ai via a new tab (URL parameter handoff
where the platform supports it; clipboard pre-fill plus pasted-prompt
instructions where it doesn't). The visitor reads Claude's response
in their own claude.ai session — outside MerkleTrust's perimeter —
on infrastructure the visitor controls.

After the visitor reads Claude's take, MerkleTrust invites them back
with a single line at the comment field: "Bring it back if you want.
Paste your dialogue here as: 'this is me and Claude on this sim.'"
Returned dialogues become public discussion attached to the card,
visible to future visitors as peer review of the simulation.

This is the inverse of the V2 interactive arrays: rather than the
designer offering three options for the visitor to commit to, the
visitor brings their own thought and a critical reviewer scrutinizes
it. The walkthrough is the test drive; the comment surface is the
test drive's onboard chat with a peer the visitor trusts.

The comment never leaves MerkleTrust unless the visitor presses
submit. The Claude.ai redirect is opt-in, named, and routed through
the visitor's own logged-in session — Merkle Trust does not see the
response unless the visitor pastes it back.

## The attestation strip — where the real work shows up

Every card has a strip at the bottom that breaks away from the sim
and shows the visitor what just happened cryptographically. Three
states:

- **Online + GarrisonNode reachable** — the strip shows a real beacon
  hash, a real merkle leaf added to the day's tree, a real timestamp
  from the live ceremony. The visitor's clicks become real events on
  the running JAR9 instance.
- **Online + GarrisonNode unreachable** — the strip shows what would
  have happened, framed honestly: "If a Garrison Node were reachable,
  this click would emit leaf X to anchor Y at ceremony Z." No fake
  hashes; no pretending. The crypto runs locally via
  `crypto.subtle.digest`; the anchor reference is labeled as a
  simulation.
- **Offline (installed on visitor's metal)** — the strip shows the
  visitor's own local Garrison Node anchoring the click. No external
  dependency.

The visitor never has to know which mode they are in unless they
look. The framing chip at the top of every card carries the honest
default: "simulated data · code is real." If the visitor expands the
chip, the truth of the current mode is plain.

Mode detection is silent. Mode failure (e.g., Cloudflare endpoint
500s) degrades gracefully to the simulated state with a quiet note
in the strip — not a modal, not a warning, not an interruption. The
visitor's experience does not change because of network weather.

## Fingerprint accumulator — the click-path as identity

As the visitor walks the cards, the runtime hashes their click path
into an accumulating digest. The seed is the cards visited, in order,
with timestamps rounded to the second. At graduation, the digest is
sealed into a `cert.json` file the visitor downloads.

The cert is the visitor's identity for any future return. They drop
it on the login page; if it matches, they are signed in. If they
alter one byte of the cert and try again, login fails — until they
revert the byte. That round-trip demonstrates one Garrison Node
ability without any explanation needed: tamper-evidence of a single
sealed file.

The fingerprint runtime does not require a server. It uses
`crypto.subtle.digest` for SHA-256 and the visitor's local clock.
The cert is signed using a per-session keypair the runtime generates
in browser memory; the public key travels with the cert. Validation
on return is local first, then optionally cross-checked against the
public anchor chain if the visitor is online and the operator's
endpoint responds.

## Online vs. offline — the framing rule

The visitor never sees an alarm about being live. They never see
"warning: real cryptography is firing." The honest framing is the
default and lives in the simulation_posture chip at the top of every
card: **simulated data · code is real**. Expanded:

> This walkthrough uses simulated data so you can explore without
> registering anything real. The cryptographic operations are real
> — your browser is doing actual SHA-256, actual signature
> verification, actual merkle-leaf construction. If a Garrison Node
> is reachable, your clicks become real events on it. If not, the
> code still runs; only the anchor is simulated.

This sentence is the contract with the visitor. Every prose line in
every card must be consistent with it. Anything that overstates
("you are now a Garrison Node operator") or understates ("none of
this is real") is a violation.

## Truth-claim discipline

Every claim a card makes about Garrison Node capability must map to
a real component in `~/garrison/GN/`, `~/garrison/rustchain/`, or
`~/garrison/redpanda/`. The verification report at
`verification/CLAIMS_AUDIT.md` enumerates each claim and its backing
component, with file references.

Where a sim suggests future capability — Mr. Vega's closet Mac mini
(40x) hosting a guild, Sofía's sovereign inference wrapper (40y)
running on BitNet, the game-world social architecture (40o) — the
prose frames it as invitation, not promise. The pattern:

> What this walkthrough shows is what the foundation makes possible.
> Building on top of it is yours to do, or yours to ask the next
> Garrison Node operator to do for you.

No "patent pending." No "revolutionary blockchain." No "we have
already shipped X." If the foundation can do it today, the prose
says so plainly. If the foundation could do it next month, the
prose names it as a build-on opportunity.

## Voice rules — carried forward from S143/S151

These are not new; they are the existing playbook restated for cards_v2:

- TO the visitor (you / your)
- ABOUT the sims (Mrs. Alvarez, Mr. Marcus, Dr. Okafor, Sofía, Sasha,
  Tomás, Carmen, Hannah, Delia, Mr. Vega — third person)
- Never narrate the page itself. No "the visitor sees" / "this card
  surfaces" / "the panel reveals."
- Never induce catastrophe-mindset. No "Picture this:" / "Imagine
  the worst case."
- No italic markdown — neither `*…*` nor `_…_`. The renderer shows
  the asterisks as literal characters.
- Bold (`**…**`) is OK on bullet labels and button names.
- Inline quoted phrases use double quotes, not italic.
- The four-paths install template is audience-ordered (clinical →
  operator-first; legal → operator-first; IT → GitHub-first; civic
  → operator-first; technical research → GitHub + mesh first).

## Audience clusters — how the 26 cards group

| Cluster | Cards | Lead path | Tone |
|---|---|---|---|
| Clinical | 40a, 40b, 40c, 40h, 40j | operator | calm, peer-to-peer |
| Legal | 40e, 40f, 40k | operator | precise, court-aware |
| Government / civic | 40g, 40i, 40r | operator or GitHub | sober, sunshine-law |
| IT / technical | 40d, 40p, 40u, 40x, 40y, 40z | GitHub | dry, dev-tool aesthetic |
| Research / science | 40l, 40n, 40s | GitHub + mesh | careful, citation-friendly |
| Civic / consumer | 40o, 40q, 40t, 40v, 40w | operator | warm, household-scale |
| Recovery / accounting | 40m | operator | forensic, evidentiary |

This map drives the four-paths ordering at step 2 of every card.
It also drives the `mock_ui` theme selection.

## Schema additions — what cards_v2 needs from V2

See `SCHEMA_V2_PLUS.md` for the full delta. Summary of new top-level
and step-level fields:

- `card_id`, `title`, `estimated_minutes`, `finish_text` — unchanged
- `schema_version: 3` — new minor bump, additive
- `narrate` — top-level config for the read-aloud feature
- `tag_along` — top-level config for the per-card .md export
- `attestation_strip` — top-level config for the cryptographic surface
- `fingerprint` — top-level config for the click-path accumulator
- `step.cursor_path` — unchanged from V2 (carries over)
- `step.public_ceremony` — unchanged from V2 (carries over, with new
  `ceremony_kind: "fingerprint_seal"` for graduation)
- `step.attestation` — new per-step block describing what real
  cryptographic event fires when this step plays

The existing V2 fields (`mock_ui`, `data_recipients`, `transforms`,
`data_fate`, `simulation_posture`, `cursor`) carry over unchanged.

Step-level `interactive` arrays are deprecated for cards_v2 but
remain readable so that V1/V2 cards continue to work alongside cards_v3
during the migration.

## Build / run / verify

The cards_v2 directory is the source of truth for the rewrite. The
build pipeline is yet to be wired (separate sprint), but the
expected flow is:

1. Author / edit `cards/40X_sim_*.md`
2. The schema-aware build script reads the .md, applies the contract,
   merges with `sidecars/40X_sim_*.json` to produce a complete card.
3. The build emits one bundled JSON to `_built/walkthroughs_v3/`.
4. The runtime (after the engineering thread) reads the new bundle
   and renders click-only with the new affordances.

Until the runtime is updated, cards_v2 ships its own minimal
preview script (`scripts/preview_card.py`) that renders one card to
a static HTML file the sovereign can open directly in a browser. The
preview is for sovereign review, not for visitors.

## What this contract does not authorize

- Modification of the existing 26 cards in
  `~/garrison/gn-integrations/`. They remain canonical until cards_v2
  is promoted.
- Modification of the existing JSON sidecars in
  `~/garrison/gn-integrations/walkthroughs/`. Same rule.
- Modification of `walkthrough.js` or any runtime file. Engineering
  thread.
- Top-level directory creation under `~/garrison/`. cards_v2 lives
  inside the writeable `gn-integrations/` per the workspace contract.
- Promotion to `_built/`. The promote step happens after sovereign
  review, in a dedicated commit, and is the trigger for the next
  attestation ceremony to pick up the new tree.

## Sign-off

Sovereign reviews this CONTRACT before any card prose is written.
On approval, the rewrite proceeds in the order: 40a → 40g (polish
pass), then 40h → 40z (heavy pass), with sovereign pause-points at
the first card per audience cluster. The verification audit runs
last, before the broadcast.

If any clause in this contract conflicts with the workspace contract
at `~/garrison/CLAUDE.md`, CLAUDE.md wins. This file inherits and
specifies; it does not override.

---

*Filed: 2026-04-28 · Sprint S152 · Sovereign: jr / John Reed (L4)*
*Successor: rev when the runtime ships, when the schema delta is
finalized, or when the cards_v2 directory promotes to canonical.*