@@ -0,0 +1 @@
+CLAUDE.md
@@ -0,0 +1,64 @@
+# typstmcp — codebase notes for Claude
+
+## What this is
+
+Two products in one repo (see [README.md](./README.md) for the full picture):
+
+- **DocForge** — an MCP server (stdio) for agent-driven PDF production via Typst.
+  Engine spec: [DOCFORGE.md](./DOCFORGE.md). Entry point `src/index.ts` → `dist/index.js`.
+- **Forge** — a Slack agent (Bolt) that drives DocForge **over MCP as a stdio child
+  process**, not in-process (`src/forge/mcp-client.ts`; `FORGE_MCP=off` forces the
+  in-process fallback). Product spec: [FORGE.md](./FORGE.md). Entry `dist/slack/app.js`.
+
+Other docs: [AUDIT.md](./AUDIT.md) (security/correctness audit log),
+[HARDENING.md](./HARDENING.md), [DELIVERY.md](./DELIVERY.md),
+`.cursor/skills/docforge/SKILL.md` (agent-facing tool usage guide).
+
+## Stack
+
+- TypeScript, `strict`, **NodeNext ESM** — relative imports need the `.js` suffix.
+- Node ≥ 20. Runtime deps: `@modelcontextprotocol/sdk`, `@slack/bolt`, `ajv`, `zod`.
+- **Typst 0.14.2 pinned** (`TYPST_VERSION_PIN` in `src/config.ts`); the `typst` binary
+  must be on PATH. `@preview` packages are vendored in `vendor/typst-packages/` so
+  compiles need no network.
+- vitest, eslint (flat config + typescript-eslint), prettier (enforced in CI-style
+  via `format:check`).
+
+## Commands (verified 2026-07-13)
+
+```bash
+npm run build          # rm -rf dist && tsc — clean
+npm test               # vitest run — 73 files / 546 tests, ~10 s wall
+npm run lint           # eslint — clean
+npm run format:check   # prettier — clean (use `npm run format` to fix)
+npm run check:typst    # asserts local typst matches the 0.14.2 pin
+npm run check:packages # asserts vendored @preview packages present
+```
+
+Heavier gates (documented in README, **not** run during bootstrap):
+`npm run release:qa` (full local release gate), `npm run test:visual` (golden-PNG
+regression over 24 templates), `npm run forge:smoke`. Slack dev loop: `npm run slack`
+(needs `.env` from `.env.sample` with bot + app tokens).
+
+## Layout
+
+- `src/` — engine (`compile/`, `templates/`, `validation/`, `qa/`, `repair/`, `lint/`,
+  `sandbox/`, `security/`, `versioning/`), Slack agent (`slack/`), the Slack→engine
+  bridge (`forge/`), transcript→template-data mappers (`workflow-mappers/`).
+- `templates/<id>/` — 21 built-in Typst templates, each with `main.typ`,
+  `components.typ`, `theme.typ`, a JSON schema/README/sample, and a
+  `golden-page1.png` for visual regression. 3 more live in `marketplace/`.
+- `tests/` — flat `*.test.ts` files, vitest `describe`/`it`, shared helpers in
+  `tests/helpers.ts` (e.g. `templateDir()`). Tests import from `../src/**/*.js`
+  (compiled-style specifiers, resolved by vitest).
+- `scripts/*.mjs` — release/QA/dev tooling; syntax-checked by `npm run check:scripts`.
+
+## Conventions & quirks
+
+- Prettier is the formatter of record — run `npm run format` before committing;
+  `format:check` covers src, tests, scripts, key markdown, and Slack manifests.
+- Golden PNGs (`templates/*/golden-page1.png`) are committed binaries; template
+  visual changes require regenerating them (`npm run compile:golden`).
+- The package publishes `dist/` plus templates/vendor/docs (see `files` in
+  package.json); `bin` is `docforge-mcp`.
+- Docker image (Dockerfile) bundles Node 22 + pinned Typst for offline compiles.
@@ -111,6 +111,7 @@ Monorepo: Slack agent + DocForge engine.
 | Reviewers invited                         | ☐      |
 | Pinned `#general` instructions            | ☐      |
 | `forge:smoke` passes in CI/local          | ☐      |
+| `npm run release:qa` passed within 48h    | ☐      |
 | Cold QA script (§8) passed                | ☐      |
 | HTTP deploy up through Aug 6              | ☐      |
 
@@ -125,6 +126,30 @@ Monorepo: Slack agent + DocForge engine.
 | Impact    | Universal workflows (sales, SRE, leadership)                                       |
 | Idea      | Workflow completion vs summarize bots                                              |
 
+### Current verified evidence (2026-06-26)
+
+- `npm run release:qa` passed locally: Typst pin, template sync, vendored packages,
+  lint, script syntax, format, build, 545 tests, Forge smoke, visual regression,
+  Slack manifest validation, package inventory, and tracked-file secret scan.
+- Live sandbox workspace: `Workspace Sand` (`T0BA8FFE63T`), bot `forge`.
+- Live status PDF generated from `#campaign-nto` and uploaded to Slack:
+  `Status-campaign-nto-hero-polished.pdf` (`F0BDJAYP2JG`). Local QA copy:
+  `/tmp/forge-live-slack-qa/Status-campaign-nto-hero-polished.pdf`.
+- The status PDF render is 2 pages with 35 source snippets, zero lint errors,
+  zero preflight warnings, clean emoji shortcode handling, and a visible Forge
+  grounding proof/evidence ledger.
+- Reviewer seed/poll flow was executed against existing sandbox channels:
+  `#service-swarm`, `#acct-edge`, `#campaign-nto`, and `#general`.
+- Seeded-context document runs were executed in the same channels:
+  `Status-campaign-nto-seeded-run.pdf` (`F0BDJN7SXGC`, 7 seeded status
+  messages), `Incident-service-swarm-seeded-run.pdf` (`F0BE9BFESRE`, 10 seeded
+  incident messages), and `Northstar-Proposal-seeded-run.pdf` (`F0BDGUA7X1P`,
+  10 seeded sales discovery messages + reviewer pricing).
+
+Still open: full human Slack cold QA for all five workflows, public walkthrough
+video, reviewer invites, and hosted HTTP verification (`/health`, Slack event URL,
+interactivity URL, and uptime through the reviewer window).
+
 ---
 
 ## 5. Product walkthrough video script (~3:00)
@@ -235,6 +260,27 @@ Forge workflow commands
 4. `@forge status for #team-eng`
 5. `@forge draft Weekly update: pipeline improved, onboarding risk remains, recommendation is a setup wizard.`
 
+### Seed/poll utilities
+
+- `npm run seed:workspace` posts the reviewer channel fixtures above and prints the board CSV path.
+- `npm run poll:slack -- --channel #team-eng` verifies bot-visible channel history before recording or reviewer handoff.
+- `tests/reviewer-workspace-scripts.test.mjs` keeps the seed messages, command copy, and board CSV fixture aligned with this playbook.
+
+2026-06-26 sandbox run used existing channels:
+
+```bash
+SEED_INCIDENT_CHANNEL=service-swarm \
+SEED_SALES_CHANNEL=acct-edge \
+SEED_STATUS_CHANNEL=campaign-nto \
+SEED_GENERAL_CHANNEL=general \
+SEED_DELAY_MS=100 \
+npm run seed:workspace
+```
+
+Readback evidence was exported with `npm run poll:slack -- --channel ... --json`
+to `/tmp/forge-poll-service-swarm.json`, `/tmp/forge-poll-acct-edge.json`, and
+`/tmp/forge-poll-campaign-nto.json`.
+
 ---
 
 ## 8. Manual QA script
@@ -282,6 +328,7 @@ Run as someone other than the author. **All must pass.**
 ### Headless (before Slack)
 
 - [ ] `npm run forge:smoke` → 5 non-empty PDF files on disk
+- [ ] `npm run release:qa` → offline release gates, Slack manifest check, package inventory, and secret scan pass
 
 ---
 
@@ -373,7 +420,7 @@ Reviewers test **Jul 14 – Aug 6**. Laptop `slack run` is insufficient.
 Release the review package only when **all** true:
 
 - [ ] `forge:smoke` green
-- [ ] QA script passed within 48h
+- [ ] `npm run release:qa` passed within 48h
 - [ ] Video plays without login
 - [ ] Reviewers have workspace access
 - [ ] Deploy uptime 24h+
 
@@ -389,15 +389,26 @@ Scripts (in `package.json`):
 ```json
 {
   "slack": "npm run build && node --env-file=.env dist/slack/app.js",
-  "forge:smoke": "npm run build && node scripts/forge-smoke.mjs"
+  "forge:smoke": "npm run build && node scripts/forge-smoke.mjs",
+  "test:visual": "node scripts/visual-regression.mjs",
+  "compile:golden": "node scripts/compile-golden.mjs",
+  "seed:workspace": "node --env-file=.env scripts/seed-workspace.mjs",
+  "poll:slack": "node --env-file=.env scripts/poll-slack.mjs",
+  "release:qa": "node scripts/release-qa.mjs"
 }
 ```
 
 ---
 
 ## 13. Definition of done
 
-- [ ] `forge:smoke` produces 5 PDFs via helpers/inference + pipeline (no Slack)
+- [x] `forge:smoke` produces 5 PDFs via helpers/inference + pipeline (no Slack)
+- [x] `npm run release:qa` passes locally, including visual regression, Slack
+      manifest validation, package inventory, and secret scan
+- [x] Reviewer workspace seed/poll utilities are script-backed, test-covered,
+      and executed against the sandbox Slack workspace
+- [x] Project status hero workflow has live Slack PDF evidence from
+      `#campaign-nto` with clean emoji handling and evidence ledger
 - [ ] All 5 workflows work in workspace via `@forge` commands
 - [ ] RTS used in ≥1 workflow; history fallback in all
 - [ ] Confirm-before-export on all workflows
 
@@ -22,6 +22,7 @@ npm run check:typst       # verify Typst pin (0.14.2)
 npm run check:packages    # verify vendored offline @preview packages
 npm run lint              # eslint
 npm test                  # unit/integration tests
+npm run release:qa        # full local release gate before reviewer handoff
 npm run test:visual       # golden PNG regression (24 templates)
 ```
 
@@ -151,3 +152,8 @@ template sync check → vendored-package check → lint + script syntax check
 check → build → unit/integration tests → Forge smoke → visual regression → package
 contents dry-run → Docker build. Golden drift fails CI; update with
 `npm run compile:golden`.
+
+For a local reviewer handoff gate, run `npm run release:qa`. It executes the
+offline CI-critical checks, verifies Slack manifest scopes/events, confirms the
+npm package carries Slack setup/deploy assets, and scans tracked files for common
+secret token patterns.
@@ -9,16 +9,19 @@
   "files": [
     "dist/",
     "templates/",
+    "slack/",
     "marketplace/",
     "brand_kits/",
     "packages/",
     "vendor/",
-    "scripts/check-typst-version.mjs",
-    "scripts/check-vendored-packages.mjs",
+    "scripts/",
     "README.md",
+    ".env.sample",
+    "DELIVERY.md",
     "FORGE.md",
     "DOCFORGE.md",
-    "HARDENING.md"
+    "HARDENING.md",
+    "Dockerfile"
   ],
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
@@ -31,10 +34,11 @@
     "check:typst": "node scripts/check-typst-version.mjs",
     "check:packages": "node scripts/check-vendored-packages.mjs",
     "check:scripts": "for f in scripts/*.mjs; do node --check \"$f\" || exit 1; done",
+    "release:qa": "node scripts/release-qa.mjs",
     "pack:check": "npm_config_cache=${TMPDIR:-/tmp}/docforge-npm-cache npm pack --dry-run --json",
     "lint": "eslint src tests scripts eslint.config.js vitest.config.ts",
-    "format": "prettier --write README.md FORGE.md DELIVERY.md \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\" \"slack/**/*.json\" \".github/**/*.yml\"",
-    "format:check": "prettier --check README.md FORGE.md DELIVERY.md \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\" \"slack/**/*.json\" \".github/**/*.yml\"",
+    "format": "prettier --write README.md FORGE.md DELIVERY.md \"src/**/*.ts\" \"tests/**/*.{ts,mjs}\" \"scripts/**/*.mjs\" \"slack/**/*.json\" \".github/**/*.yml\"",
+    "format:check": "prettier --check README.md FORGE.md DELIVERY.md \"src/**/*.ts\" \"tests/**/*.{ts,mjs}\" \"scripts/**/*.mjs\" \"slack/**/*.json\" \".github/**/*.yml\"",
     "slack": "npm run build && node --env-file=.env dist/slack/app.js",
     "seed:workspace": "node --env-file=.env scripts/seed-workspace.mjs",
     "poll:slack": "node --env-file=.env scripts/poll-slack.mjs"
 
@@ -103,7 +103,16 @@ for (const workflow of workflows) {
       workflow.templateId,
       workflow.data(),
       {
-        workflow: workflow.name === "kpi_report" ? "board" : workflow.name === "sales_proposal" ? "proposal" : workflow.name === "project_status" ? "status" : workflow.name === "incident_report" ? "incident" : "draft",
+        workflow:
+          workflow.name === "kpi_report"
+            ? "board"
+            : workflow.name === "sales_proposal"
+              ? "proposal"
+              : workflow.name === "project_status"
+                ? "status"
+                : workflow.name === "incident_report"
+                  ? "incident"
+                  : "draft",
         gather: { source_labels: ["forge-smoke"], source_count: 1, gather_method: "headless" },
       },
     );
 
@@ -10,22 +10,16 @@
  * for history (or channel membership).
  */
 import { writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
 import { WebClient } from "@slack/web-api";
 
-const token = process.env.SLACK_BOT_TOKEN?.trim();
-if (!token) {
-  console.error("SLACK_BOT_TOKEN missing — add to .env");
-  process.exit(1);
-}
-
-const client = new WebClient(token);
 const args = process.argv.slice(2);
 const jsonOut = args.includes("--json");
 const channelFilter = args.includes("--channel") ? args[args.indexOf("--channel") + 1] : undefined;
 const limit = Number(process.env.POLL_MESSAGE_LIMIT ?? 30);
 const outFile = process.env.POLL_OUTPUT;
 
-async function listChannels() {
+export async function listChannels(client) {
   const channels = [];
   let cursor;
   do {
@@ -52,7 +46,7 @@ async function listChannels() {
   return channels;
 }
 
-async function fetchHistory(channelId) {
+export async function fetchHistory(client, channelId) {
   try {
     const res = await client.conversations.history({
       channel: channelId,
@@ -77,14 +71,31 @@ async function fetchHistory(channelId) {
   }
 }
 
-function formatTranscript(messages) {
+export function normalizeChannelFilter(value) {
+  return value?.replace(/^#/, "");
+}
+
+export function applyChannelFilter(channels, filter) {
+  const normalized = normalizeChannelFilter(filter);
+  if (!normalized) return channels;
+  return channels.filter((c) => c.name === normalized);
+}
+
+export function formatTranscript(messages) {
   return messages
     .filter((m) => m.text?.trim())
     .map((m) => m.text.trim())
     .join("\n");
 }
 
 async function main() {
+  const token = process.env.SLACK_BOT_TOKEN?.trim();
+  if (!token) {
+    console.error("SLACK_BOT_TOKEN missing — add to .env");
+    process.exit(1);
+  }
+
+  const client = new WebClient(token);
   const auth = await client.auth.test();
   const workspace = {
     team: auth.team,
@@ -93,9 +104,9 @@ async function main() {
     polled_at: new Date().toISOString(),
   };
 
-  let channels = await listChannels();
+  let channels = await listChannels(client);
   if (channelFilter) {
-    channels = channels.filter((c) => c.name === channelFilter.replace(/^#/, ""));
+    channels = applyChannelFilter(channels, channelFilter);
     if (channels.length === 0) {
       console.error(`Channel not found: ${channelFilter}`);
       process.exit(1);
@@ -105,7 +116,7 @@ async function main() {
   const report = { workspace, channels: [] };
 
   for (const ch of channels) {
-    const history = await fetchHistory(ch.id, ch.name);
+    const history = await fetchHistory(client, ch.id);
     const entry = {
       ...ch,
       accessible: history.ok,
@@ -148,7 +159,9 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  console.error("poll failed:", err?.data?.error ?? err.message ?? err);
-  process.exit(1);
-});
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((err) => {
+    console.error("poll failed:", err?.data?.error ?? err.message ?? err);
+    process.exit(1);
+  });
+}