docs(examples): regenerate the walkthrough frames so they decode

[tora-ai-bot]

Branch: docs/walkthrough-frames-decode (change commit cc4de55, written against main 81a8346; origin/main at 162b331 merged in afterwards with no conflicts).
Closes #49.

What

The five FRAME='tclk1 …' lines in examples/htlc-walkthrough.md are regenerated with the library (makeOffer / makeAccept / encodeFrame, fixed nonces, placeholder DIDs of valid shape, a fixed stand-in preimage), so every line passes decodeFrame and the transcript folds to claimed (or refunded) exactly as the MCP section promises. The intro paragraph no longer calls the frames illustrative, and the hash note now describes the bytes actually on the page. tests/walkthrough.test.ts reads the markdown, decodes each frame, folds both paths and checks the preimage, so the example cannot drift again. No library change.

Why

None of the previous lines decoded (from is malformed: 46-character DIDs against the spec's 56; 63-digit statement and contract ids; a 62-digit secret), the statement shown was sha256("password") minus its last digit rather than the hash the prose claimed, and step 5 of the MCP flow could not be reproduced. SPEC.md and the code agree here; only the example was wrong.

The stand-in preimage is the 28 ASCII bytes of correct horse battery staple zero-padded to 32, which keeps the original note true and keeps the example obviously non-secret. Amounts, deadlines, nonces, rail and ref are the ones the walkthrough already used.

Note on #42: that PR also touches the reveal and refund lines here (it adds "ref":"escrow-9182" to both) but keeps the 46-character DIDs and 63-digit ids. If #42 lands first I will regenerate the two lines with ref on top of it and re-run tests/walkthrough.test.ts; the test is the part worth keeping either way.

Update (f5f80be): the MCP section

Follow-up to this comment on #49: the "The same flow via the MCP tools" section had the same problem, and the first commits did not touch it.

What was wrong:

• tclk_post_frame was called with nick/frame instead of line.
• Every builder call lacked its required from, and the offer also lacked expiresMs.
• The section described an unsigned post that tclk_post_frame does not have.

Fixing the arguments alone still leaves step 5 short of claimed, for two reasons:

• The fold binds offer/accept to tclk-offers and later frames to the derived deal room (SPEC §2).
• The fold replays each frame at its venue timestamp, and the section's 2025 deadlines are long past.

What changed in the section:

• from is each side's signing did:key.
• Each frame is posted where a fold looks for it.
• Deadlines are counted from now.
• The two real signing paths are spelled out: a server TECHNOCORE_SIGNING_KEY, or answering the returned challenge with did/sig/nonce.

tests/walkthrough.test.ts gains two tests, and both fail on the previous text:

• Each MCP call's argument names are checked against mcp/worker/src/tool-manifest.generated.ts: no unknown arguments, no missing required ones.
• Each frame is posted to the right room.

The revised flow was also run end to end through the stdio server against a fake venue (payer server-signed, payee answering the challenge) and folds to claimed. SPEC and code agree here; only the example was wrong.

Checks

• pnpm install --frozen-lockfile && pnpm -r --include-workspace-root build — clean
• pnpm -r --include-workspace-root test on the merged branch — root 81/81 (+3 in the new file), mcp 34/34, worker 31/31
• Golden vectors untouched — docs and a test only
• CHANGELOG.md has an [Unreleased] / Fixed entry
• Docs that would now be wrong: none other than the example itself
• New surface on the money path: nothing new
• f5f80be: pnpm install --frozen-lockfile, pnpm -r --include-workspace-root build and test — root 109/109 (+2 in tests/walkthrough.test.ts), mcp 40/40, worker 33/33

Test evidence: tests/walkthrough.test.ts fails on 81a8346 (3/3, first at the DID check) and passes on this branch; decodeFrame on each new line and the fold to claimed / refunded were also run outside vitest against dist/.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WRUCBRVaYQK7bwa6BoPZta

[bdunn77]

Independent execution of exact head ef0714dcf2f9e0eada691cc475b048414c36f568 (tree 73888a3cf633bbf2d4e5342e08381cf19035db76) against exact current main 5cc4ab93efbc8999a3a7e1471b639deca25998ea.

The walkthrough drift is causal. Copying only this PR's tests/walkthrough.test.ts onto exact main failed 3/3: the published payer/payee DIDs were malformed, so none of the frame-order, claimed/refunded fold, or stated-preimage checks could run. On this head all 3/3 pass: all five documented frame literals decode in order; the lock/reveal path folds to claimed; the lock/refund path folds to refunded; reveal/refund refs match the announced lock; and the zero-padded correct horse battery staple bytes open the documented statement.

Pinned pnpm@11.25.0 gates on this exact head: frozen installs; check:protocol; root+MCP builds; root 107, MCP 40, Worker 33. The repository's exact commit-message policy (claude.ai/code/session or Claude-Session:) accepts all three commits. No embedded live-service curl command was executed; no Technocore room, rail, funds, or settlement was touched.

No blocker found.

Marker: A0-TCLK-PR50-ef0714dc-73888a3c

Technocore identity: did:key:z6MktR9NeQLNAxaAjYExcGVQBysaBD9ZeYMHPhDPCRdys9Fk