---
name: franksign-demo-inspection-stack
description: "Boot franksign's prod-shaped stack, seed all assignment lifecycle states through the real API, and open a headed inspection tour (platform + storybook) without squatting the e2e port."
---

Visual-inspection recipe for the franksign repo (Dank boxes). Proven 2026-10-20; use when asked to "show/open the platform" or tour a new slice.

## Boot (do NOT squat :3100 — the e2e seam curls whoever owns that port)
```bash
node --env-file=.env apps/api/dist/cli.js        # binds :3000 by default; use named service
cd apps/web/storybook-static && python3 -m http.server 6007   # gate seam 12 already built it
curl -s http://127.0.0.1:3000/health              # {"status":"ok","db":"up"}
```

## Seed lifecycle states through the real API (cookie jar, NOT bearer)
better-auth sign-up returns a bearer `token`, but the org routes resolve sessions
from **cookies only** (`Authorization: Bearer …` → get-session null → 401). Use
`-c /tmp/jar` at sign-up and `-b /tmp/jar` after; state-changing calls need an
`origin:` header. Keep auth headers out of argv via `curl -K <file>`.

1. `POST /api/auth/sign-up/email` `{"email","password"(>=8 chars),"name"}` → save cookies (`-c`)
2. `POST /api/orgs` `{"name"}` → `org.id`
3. `POST /api/orgs/:org/templates` `{"name","baseTemplateId":"sample"}` → `template.id`
4. `POST /api/orgs/:org/templates/:tpl/assignments` `{"email"}` → `{token, signUrl}` (repeat per demo signer)
5. signed state: `POST /api/releases/:token` `{"values":{"name":…,"date":…,"agreement":true},"signatureName":…}` — no auth needed (token seam)
6. voided state: `POST /api/orgs/:org/assignments/:assignmentId/void` (cookie session)
Remaining pending assignment → three inspectable pages: `/app/sign/:token` renders form / already-signed / cancelled.

## Byte-identity spot check (reconstruction contract, issue #18)
Fetch `GET /api/releases/:token/pdf` twice with `sleep 1.5` **between** fetches
and sha256-compare, plus the org door `GET /api/orgs/:org/assignments/:aid/pdf`
(cookie jar). Same-second-only comparisons are blind to clock leaks
(pdf-lib's `PDFDocument.load` restamps `/ModDate` unless `updateMetadata:false`).
To see printed text: inflate the content streams and unescape `\(`, `\)` —
pdf-lib writes hex-string `Tj` operands.

## Inspection browser (managed Chromium via browser eval)
- `viewport` must be `{width, height}` — string fails
- `tab.waitFor(ms)` does NOT exist (ms is parsed as selector) → `await Bun.sleep(900)`
- open with `headed: true, persist: true`; window lands on the desktop — confirm with `niri msg windows | grep -i chrome`

## Teardown (hard gate hazard)
A live demo API on :3000 **hangs the full `tests/run.sh` gate for ~10 minutes**
(observed 2026-10-21: >600s kill with the service up; 14/14 in ~15s without
it). Always `proc://franksign-demo-api/kill` BEFORE running the gate; verify
`pgrep -f apps/api/dist/cli.js` is empty so the next `tests/run.sh` e2e seam
owns :3100 honestly.

## Adjacent Gitea quirk (same fleet)
Closing an issue/PR: `PATCH {"state":"closed"}` → 201; `POST` → 405. Merging needs form-encoded lowercase `do=merge` (see gitea-merge-form-encoded). Label assignment: `PATCH /issues/N` with `labels:[id]` silently clears labels — use `POST /issues/N/labels` `{"labels":[id]}`.