@rallycry/conveyor-agent 10.13.72 → 11.0.1

package/skills/conveyor-build/references/pack-path.md

@@ -0,0 +1,224 @@
+# Pack path — a feature-branch pack, start to one PR
+
+The pack execution core of [conveyor-build](../SKILL.md). Read that first;
+ground rules, environment differences, verification, and aftercare live there.
+
+A feature-branch pack is a parent card whose children branch from and PR into a
+shared **pack branch**, and which lands on `dev` as ONE final PR. Children that
+PR straight into `dev` are not this — build those individually via the task
+path.
+
+**You are both the coordinator and every child's implementer.** One session
+owns all the state, serially. That is the whole point: the distributed
+alternative is where pack incidents come from.
+
+## Setup (first iteration only)
+
+1. Confirm the shape: the parent has (or will have) children, its status is
+   neither InProgress nor ReviewPR, and no agent session is live on it. A
+   parent already InProgress/ReviewPR has a coordinator — report and stop
+   rather than compete.
+2. **Ensure the pack branch exists on origin.** Use the card's `githubBranch`
+   if set; otherwise cut `ft/<parent-slug>` from `origin/dev`, push `-u`, and
+   IMMEDIATELY record it: `mcp__conveyor__update_task` with
+   `githubBranch: <branch>`.
+
+   That write is load-bearing, not bookkeeping. Identification mints a
+   competing `conveyor/*` branch name onto any branchless card it processes,
+   and every pack-child merge handler keys on the card's recorded branch
+   matching the PRs' real base — a drifted record strands merged children in
+   ReviewPR.
+
+   **Push the branch first, and verify it yourself.** The local surface
+   validates the ref; the pod's `update_task` does NOT — it writes the value
+   through with no check that the branch exists on origin, and no guard
+   against repointing the record away from the branch the pod is actually
+   running on, which strands the compute. A successful write is not evidence
+   the branch is pushed.
+3. **No children yet?** Break the work down first: explore, save the
+   parent-level plan with `mcp__conveyor__update_task`, then
+   `mcp__conveyor__create_subtask` each child with a standalone plan
+   (file:line citations, verification steps) and `dependsOn` edges wherever one
+   blocks another.
+4. Post the claim marker to the PARENT chat, naming the pack branch. Use a
+   stable, greppable prefix — `[pack] claimed — …` — because the Recover tier
+   above finds your in-flight work by searching for it. (Under
+   `conveyor-local-loop`, its `[local-loop]` prefix replaces this.)
+
+**Locally, the parent card stays PARKED for the entire run** — never set it
+InProgress, never Build it; the final `create_pull_request` is what moves it to
+ReviewPR. The mechanism: the pack watchdog and the child-event notifier both
+ignore a parked parent, whereas an ACTIVE parent treats a headless InProgress
+child as a dead agent environment and "recovers" it onto a cloud pod —
+duplicate implementation of a child you are already writing (observed
+2026-07-28).
+
+> **Environment.** In a pod the parent is honestly InProgress with a live
+> session, and this parking rule does not apply — it exists specifically to
+> dodge cloud recovery of headless children, which is not a risk when the
+> parent's own session is the thing implementing them.
+
+## Each iteration: re-derive, then do the first thing that applies
+
+Re-read the parent and `mcp__conveyor__list_subtasks` every time. Never trust
+session memory for pack state.
+
+1. **Recover** — a child carrying your claim marker, InProgress, with no PR.
+   Its branch may already exist locally or on origin; audit what landed before
+   re-implementing.
+2. **Merge** — a child in ReviewPR. See "Merge a child" below.
+3. **Promote** — a `Planning` child whose plan is solid →
+   `mcp__conveyor__update_subtask` to `Open`. Genuinely not plannable →
+   escalate to parent chat.
+4. **Implement** — the next `Open` child whose dependencies are all met.
+   **A dependency counts as met only at ReviewDev/Complete (merged into the
+   pack) or Cancelled. ReviewPR is NOT met** — an unmerged PR is not a
+   foundation to build on. No `dependsOn` anywhere → ordinal order.
+5. **Finale** — every child at ReviewDev/Complete. See below.
+6. **Babysit** — the final PR is open. Fix red CI and answer review comments
+   directly on the pack branch; never claim or work children once the parent is
+   in ReviewPR. **Green and quiet is the end:** post the wrap-up to parent chat
+   and stop.
+
+Work children **one at a time**. Interleaving them thrashes branch state.
+
+## Pacing — a pack is many turns, not one
+
+A pack of any size will not fit in a single turn, and there is no partial
+credit for a tree left mid-child. Treat **one iteration = one step** (implement
+one child, or merge one, or the finale) and end the turn on a committed,
+pushed state.
+
+- Driven by `/loop` (locally) or woken by events (in a pod): do one step, then
+  end the turn. Under `/loop` with no interval, arm the next wake before
+  ending — short (60–90s) while there is a child ready to work, long
+  (1200–1800s) while waiting on something external, and **stop the loop** once
+  the finale PR is open and quiet.
+- Invoked bare with no loop: do one step, report where the pack stands and what
+  the next step is, and stop. Do not self-schedule.
+
+`conveyor-local-loop` supplies its own pacing table and its own claim-marker
+prefix; when running under it, those govern.
+
+## Implement a child
+
+Reload the child's full plan fresh every time (`mcp__conveyor__get_task` +
+`read_task_chat`) — never work from what you remember of it. **A plan too thin
+for a context-free reader does not halt the pack:** post what is missing to
+parent chat, skip that child, and take the next ready one.
+
+Then follow [task-path.md](task-path.md), with one substitution: the child
+branches from the **pack branch**, not `dev`, and its PR's base is the pack
+branch. Name that base explicitly — the default is `dev`, and the two surfaces
+spell the argument differently (`base:` locally, `baseBranch:` in a pod).
+
+> **Environment — a pod has no child branches and no child PRs.** Everything
+> above describes the LOCAL model, where each child gets its own branch and its
+> own PR into the pack branch. A pod pack runner has one checkout and one
+> branch, so a child's work is simply **commits on the pack branch**. Do not cut
+> a child branch, and do not call `create_pull_request` for a child: that call
+> always opens the PR for the card the session is bound to, so mid-pack it would
+> open the PARENT's PR early and strand every remaining child. One commit per
+> child keeps the single final PR reviewable child by child.
+
+Before opening the child's PR, re-check the parent's status. If it went
+InProgress or ReviewPR, a coordinator took over: post that you are yielding,
+leave the branch pushed, and stop.
+
+## Merge a child
+
+> **Environment — in a pod there is nothing to merge.** The child's commits are
+> already on the pack branch, so "merge a child" collapses to one write:
+> `update_task(task_id: <child>, status: "ReviewDev")`. Nothing else moves a
+> child — no per-child build fires — so a status you do not write is a board
+> that silently lies. The reviewer-of-record pass below still applies to the
+> commits; only the PR mechanics drop away.
+
+1. **Reviewer-of-record pass.** The automated reviewer skips PRs that target a
+   pack branch, so this is the only review that child gets — the independent
+   review happens later, on the pack's final PR into `dev`. Re-read the child's
+   plan, then read the FULL diff (`git diff origin/<pack>...origin/<child>`)
+   with reviewer eyes: plan coverage, stray files, pattern consistency, and
+   whether the gate pass actually happened. Found a real problem → fix it on
+   the child branch (you are also the implementer), re-gate, then continue.
+
+   You wrote this code, which makes self-review the weak point. Consider an
+   independent reviewer — a subagent with the diff and no memory of writing it
+   catches what you cannot.
+2. **Merge** via `mcp__conveyor__approve_and_merge_pr`. That call QUEUES the
+   merge (a ~30s sweep) rather than merging inline, so always confirm the PR
+   actually landed instead of trusting the response.
+
+   A pack-branch PR carries no CI checks. **Give the queue a couple of minutes
+   before concluding it cannot land it** — `passesCheckGate` treats
+   `zero_checks` as passed once past `isPastZeroCheckSettling`, and the
+   pack-child skip writes a terminal `approved` that satisfies the review gate.
+   Confirmed 2026-08-20 (PR #4224, ~4 min) and again 2026-08-27 (two pack-child
+   PRs, ~2 min each). The `merge-queue` tag has carried this since 2026-08-20;
+   this file and the `pack` tag were the surfaces still asserting otherwise. Checking once
+   and falling back immediately costs a rejected push and a reset.
+
+   Note the merge is a **squash**, so the child's commits are not ancestors of
+   the pack branch: `git merge-base --is-ancestor` reads false even when every
+   byte landed. Compare content (`git diff origin/<pack> <child-head>`), not
+   ancestry.
+
+   If it genuinely stalls, merge locally instead — GitHub then marks the PR
+   merged:
+
+   ```bash
+   git checkout <pack> && git pull && git merge --no-ff <child-branch> && git push
+   ```
+
+   (Observed 2026-08-26: zero-check pack-branch PRs merged straight through the
+   queue twice in a row, so treat the fallback as a fallback, not the expected
+   path. Older guidance said the queue could NEVER merge them; that is not what
+   the queue does today.)
+
+   Either way, CONFIRM the child reached ReviewDev (allow ~1 minute for the
+   merge webhook). **Still ReviewPR after a local merge is an escalation, not a
+   shrug** — it means the parent's recorded `githubBranch` has drifted from the
+   real pack branch. Fix the parent record (`mcp__conveyor__update_task` with
+   `githubBranch: <pack>`), advance the child by hand (`update_task` →
+   `ReviewDev`), and post the drift to parent chat so it is visible.
+3. **Sync `dev` into the pack branch — yours to do, in either environment.**
+   (The fan-out cloud path had the server do this before each child launch; a
+   session driving the pack itself gets no such help and resolves conflicts
+   in-session.)
+
+   ```bash
+   git checkout <pack> && git pull && git fetch origin dev && git merge origin/dev --no-edit && git push
+   ```
+
+   **Merge, never rebase** — the pack branch is shared with open child PRs and
+   WIP refs, and rewriting it breaks them. Conflicts are yours to resolve
+   properly; you wrote the code.
+
+   If the merge drags in unrelated changes or errors, `dev` may have been
+   rewound (a revert or force-push). Verify the previous sync point is still an
+   ancestor of `origin/dev` (`git merge-base --is-ancestor`); if it is not,
+   abort the merge and escalate rather than chasing the noise.
+4. Report the merge to parent chat in a line or two.
+
+## Finale
+
+1. **Cross-reference.** For the parent plan and EVERY child plan, check the
+   pack branch's actual state against the acceptance and verification criteria
+   — a real checklist pass, not a vibe. Small gap → fix on the pack branch.
+   Substantial gap → a new child card with a plan, and the loop continues.
+2. Pre-PR protocol on the pack branch: sync `origin/dev` FIRST, then ONE
+   verification pass scoped to the pack's cumulative diff against `dev`
+   (cross-package packs earn the full suite).
+3. `mcp__conveyor__create_pull_request` on the PARENT: `head:` the pack branch,
+   `base:` `dev`. The parent moves to ReviewPR. Post the pack summary: what
+   shipped per child, how it was verified, what reviewers should look at.
+4. Confirm CI started. **Never approve or merge this PR** — it is the one that
+   gets independent review.
+
+## Parked protocol
+
+After two genuinely different failed approaches on a child, or a decision only
+the user can make: post the reason and the specific question to the child AND
+parent chats, set the child back to `Open`, restore the tree, and take the next
+child whose dependency chain does not run through the parked one. Everything
+remaining blocked → report and stop; the user's reply is the un-park signal.

package/skills/conveyor-build/references/task-path.md

@@ -0,0 +1,67 @@
+# Task path — one card to a PR
+
+The single-card execution core of [conveyor-build](../SKILL.md). Read that
+first: ground rules, environment differences, routing, verification, and
+aftercare all live there and are not repeated here.
+
+Use this path when the card has no children, or when it is a pack child whose
+parent is parked.
+
+## 1. Claim
+
+Re-confirm via `mcp__conveyor__get_task` that the card is still claimable —
+`Open` (or whatever status the user explicitly overrode), no assignee you do
+not expect, no active session. Then:
+
+1. `mcp__conveyor__update_task` → `status: "InProgress"`
+2. `mcp__conveyor__post_to_chat` → `[build] claimed — <where you are running>`
+
+If the status changed under you between the read and the write, someone else
+took it. Stop rather than compete.
+
+## 2. Branch from the card's base — never blindly `dev`
+
+The base is the card's `baseBranch`. **A pack child's base is the parent's
+feature branch**, and getting this wrong silently retargets the whole PR.
+
+```bash
+git fetch origin <base>
+git checkout -B <feat|fix|chore>/<slug> origin/<base>
+```
+
+Two cases that are not a fresh branch:
+
+- **The card already has a `githubBranch` with commits on origin.** Resume THAT
+  branch. A prior session may have landed real work — audit what is there
+  before re-implementing anything.
+- **The remote-tracking ref does not exist locally.** Many checkouts only
+  auto-fetch `dev` and the task branch, so `origin/<pack-branch>` may be
+  absent even though the branch exists on the remote. Fetch it explicitly
+  (`git fetch origin <branch>`) rather than concluding the branch is missing —
+  and note that a failed `checkout` leaves you on your PREVIOUS branch, where a
+  follow-up `git push` will push the wrong thing.
+
+Reinstall dependencies if the lockfile changed.
+
+## 3. Implement
+
+**Read the plan's closing `## Builder briefing` first, when it has one.** The
+planner wrote it for you specifically — where to start, what is already decided
+and must not be reopened, which traps look correct and are not, and the order to
+verify in. It is the only part of the planner's context that crosses the handoff,
+so reading it after you have picked an approach wastes the thing it exists for.
+A plan without one is not a blocker; just work the plan.
+
+Work the plan. Push early — locally that is the only durable state, and in a
+pod it is still what survives independent of WIP autosync.
+
+Chat at milestones, not per step.
+
+## 4. Gate, PR, aftercare
+
+These are identical to the SKILL.md sections of the same names. In particular:
+sync the base BEFORE the verification pass, pass `base:` explicitly to
+`mcp__conveyor__create_pull_request`, and confirm CI started without waiting on
+it.
+
+Finish line: the card in ReviewPR with CI started. You do not merge it.

package/skills/conveyor-consensus/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: conveyor-consensus
+description: Sweep everything a Conveyor project is connected to — work channels, cards, tags, meetings, Drive, logs, analytics, the repo — count what actually happened, score the proposals on the table against those counts, and ship an HTML verdict onto the card. Use when the user says "/conveyor-consensus <question>", "get us to consensus on X", "what are people actually complaining about", "does this plan hit the pain", "score these proposals", or when a new stakeholder proposal lands mid-thread and needs scoring against the evidence. Discovers its sources at runtime, so it runs the same in a pod and in a local MCP session.
+---
+
+# Conveyor Consensus
+
+The genre: **an uninterested observer pulls every relevant source, counts what actually happened, scores what people are proposing against those counts, and ships a doc the team can converge on.** The deliverable is a verdict with receipts, not a summary.
+
+## The stance
+
+- Write as the outside party with no stake. Verdicts, not summaries: "covered / partial / missed", "possible / not possible by design", "this suggestion doesn't solve anything, here's why."
+- Every claim carries a count and a receipt (card link, permalink, PR link, quote with author + date). Approximate tallies are fine when labeled as such; fabricated precision is not.
+- The evidence outranks the proposals: score proposals against the data, never the other way around.
+- Counter-analysis is part of the job. When a stakeholder idea doesn't survive the data, say so plainly, show the receipt that kills it, and name the nearest thing that does work.
+
+## Phase 0: discover what this project actually has
+
+**Do this before planning the sweep.** Which sources exist is a per-project fact, not a constant, and guessing wrong wastes a phase either way — assuming a channel that isn't registered, or skipping a Drive that is.
+
+1. `get_connection_context` — who and where. Same call in a pod and a local MCP session; it reports the card in a pod and the account/board in an MCP client.
+2. `list_project_integrations` — which of repository, Slack/Discord, email, GCP, Grafana, Google Analytics, Drive, Cloudflare, incidents are configured, plus the registered work channels. Credential-free booleans; this is the map.
+3. `list_project_channels` — the channels an admin registered as agent-reachable, each with a description of what happens there. **The description is the routing signal**: it is how you tell the channel where support complaints land from the one where releases are announced. Only registered channels are reachable at all; an unregistered channel does not exist for this skill regardless of what the bot can see.
+4. **ToolSearch for the optional surfaces** rather than assuming them: `drive_*`, meeting tools, `query_gcp_logs` / `query_grafana_logs`, `get_analytics_summary`. Also probe for supplemental local MCPs the user may have connected — a user-token Slack MCP is the notable one, because it enables true keyword search that Conveyor's own tools cannot do (see the Slack search note below).
+
+Announce a one-line plan naming the sources you found, then sweep. **Say what you did not find**, too: "no Drive, no meetings, no Grafana on this project" is information the reader needs to weigh the verdict.
+
+## Phase 1: sweep every spot that exists
+
+| Source | How |
+| ------ | --- |
+| Work channels | `read_channel_messages` per registered readable channel, paging back with `olderCursor` until the window covers the question. `authorIsBot` separates the team's discussion from Conveyor's own card feed — check it before treating a message as a teammate's. Read thread replies (`threadTs`) where a thread carries the argument. |
+| Conveyor cards | `search_tasks` with ALL `typeFilters` (task, incident, suggestion) and several keyword variants — the term, the term plus symptom words, the adjacent nouns people actually use. Incidents carry fingerprint dedup, so an incident's upvote count is itself a frequency signal. Check whether a decision card already exists; the doc is usually its input. |
+| Tags | `list_tags` then `get_tag` on the relevant ones — the overview is the project's own domain vocabulary, and it names the subsystems your categories should line up with. |
+| Card chat | `read_task_chat` on the cards the search surfaced. The argument usually lives in the chat, not the description. |
+| Meetings | If the meeting tools exist, list and read the ones in the window. A transcript is the densest source of "what people actually said" you will find. |
+| Drive | `drive_list_files` + `drive_read_file` when the project has a folder — specs, retros, and operational sheets live there. A spreadsheet's columns are the incumbent data model and its stalest rows are the pain. |
+| Logs | `query_gcp_logs` / `query_grafana_logs` when the question is about failures rather than opinions. A frequency count from logs outranks any recollection of how often something breaks. |
+| Analytics | `get_analytics_summary` when the question touches traffic, adoption, or "did anyone use it". |
+| Repo | Prior-art check: has someone already built or started this? `rg`, `git log`, branches, the knowledge graph when present. **A negative result — "no trace of X in the codebase" — is a finding worth printing.** |
+| Vendor / product docs | Try `https://<docs-host>/llms.txt` first; many doc sites ship a full index. Verify every "possible / impossible" ruling against a primary page fetched THIS session and link it. Vendors often have more than one API surface (legacy + current); check both before ruling a capability gap. |
+
+**Slack keyword search is not available to this skill.** `search.messages` requires a USER token; Conveyor's bot cannot call it. `read_channel_messages` is history paging, not search. So either page the relevant channels and filter model-side, or — when the user has a personal Slack MCP connected — use that for search and say so. **The method footnote must state which mode ran**, because "I read the last 300 messages in two channels" and "I searched the workspace" are different evidence bases and a reader deserves to know which one is behind the counts.
+
+Sweep hygiene:
+
+- **Delegate bulk sweeps to a subagent** so oversized pages never enter the main thread. Give it the exact queries, pagination instructions, the tool-loading line, and a strict deliverable spec: categorized findings with counts, sources, a few dated example incidents each with a link, a raw-coverage note (queries run, volume reviewed, date range, dominant sources), and a surprises section. Cap the report length.
+- Record who reported each incident and when. Attribution splits ("their side vs ours", "process vs code defect") and time windows ("only since <month>") are the follow-up questions every single time; keep the underlying dated list so re-slicing is cheap.
+
+## Phase 2: analysis
+
+1. **Bin the evidence into named categories** with incident tallies — not message counts; one saga is one incident. Rank by frequency. Pull a few verbatim quotes that carry the tone, each with author, source, and date.
+2. **Capability map** when a vendor or tool is involved: their surface versus our wants, item by item, each with a link.
+3. **Score every stakeholder proposal** against the FULL category list: COVERED / PARTIAL (symptom yes, root cause no) / MISSED, with one sentence of why each. Score proposals separately, then head-to-head.
+4. **Verify the ambitious claims.** Any proposal line hinging on "the API can (or can't) do X" gets a primary-source check before scoring — these checks regularly flip verdicts.
+5. **Build the merged plan**: the union of the proposals plus the gaps nobody wrote down, every line carrying a feasibility ruling — supported by the vendor (with the doc link), configuration not code, our build, or not possible (say why, and whether the impossibility is actually desirable).
+6. **Separate policy decisions from features.** Some open items are rulings only humans can make; flag them explicitly rather than designing around them silently.
+
+## Phase 3: the doc
+
+Build from `references/doc-template.html` — a working skeleton with three-state theme tokens, a div bar chart, stacked scoreboards, verdict-chip tables, quote blocks, and a method footnote already styled. In a local session, load `artifact-design` and `dataviz` first; in a pod those skills are absent, and the template carries enough of their decisions to stand alone.
+
+**The template is self-contained on purpose and must stay that way.** The report is served from the API under a sandbox CSP (`sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:`), which blocks external stylesheets, webfonts, scripts, and remote images. A JS charting library cannot run; a linked font fails silently and the doc renders in a fallback face with no error. Inline CSS, div/CSS charts, and `data:` URIs only.
+
+Doc anatomy (drop sections that don't apply, keep the order):
+
+1. **Eyebrow + name + dek + meta line** — corpus size, date range, source count, what decision it feeds.
+2. **TL;DR box** — the verdict in 2-3 bold-led paragraphs. A reader who stops here can act.
+3. **The evidence** — frequency bar chart (single hue, direct value labels), a note naming dominant sources, then the tone quotes.
+4. **What already exists** — incumbent systems and prior art, including negative results.
+5. **Proposal scorecards** — one chip table per proposal, then a head-to-head stacked scoreboard including a "merged" row; it sells the synthesis.
+6. **The merged plan** with per-item feasibility chips and links.
+7. **The two cents** — a handful of numbered recommendations, each an argument, not a platitude.
+8. **Method footnote** — queries, counts, date range, which channels were paged versus searched, what was verified against primary sources, and **what was not done**.
+
+Chart rules that repeatedly matter: plain div/CSS charts over JS; one strong chart beats two mushy ones; never chart numbers you had to invent — a chip list or prose with "~" beats a fake-precise graph; status chips always carry text, never colour alone.
+
+## Phase 4: ship it onto the card
+
+1. **`upload_attachment`** with the HTML file — title it with the question, so the card's attachment list reads as a question rather than a filename. This is the required path and the only one that works in a pod.
+2. **Post the verdict to card chat**: the returned link plus a three-bullet summary. Someone scanning the card should get the answer without opening the report.
+3. **When the ask was "align the channel"**, post the summary and link into the relevant work channel with `post_channel_message` — but only into a channel whose registration grants posting, and only when the user asked for that. A consensus doc arriving unbidden in a team's channel is a different act from one attached to a card.
+4. **Local sessions may also publish an Artifact** for a shareable URL, and `SendUserFile` the HTML — both are additive. In a pod neither exists; the attachment is the deliverable.
+5. **Revisions re-upload to the SAME card.** The doc is living; never fork it into `report-v2.html`.
+
+## Phase 5: the consensus loop
+
+The doc is the midpoint, not the end. Expect and serve:
+
+- **Follow-up slices**: "table of every incident with details", "only this quarter", "how many were X versus Y", "day-by-day with what would have prevented it". Answer from the kept evidence list; fold into the doc only what changes a verdict.
+- **Proposal reactions**: score new and revised proposals as they land, including negatively, with receipts, and re-upload.
+
+## Environment honesty
+
+State degradations in the method footnote rather than skipping them silently:
+
+- **No WebSearch/WebFetch in a pod** — vendor-doc claims cannot be verified against primary sources there. Print "not verified against primary docs" on the affected lines instead of dropping the check quietly.
+- **No registered work channels** — say so. It usually means the team's discussion is somewhere this skill cannot see, which is the single most important caveat a reader can have.
+- **Bot-visible history only** — the bot reads channels it was invited to. A channel the team talks in but never invited the bot to is invisible, and that absence does not show up as an error anywhere.

package/skills/conveyor-consensus/references/doc-template.html

@@ -0,0 +1,204 @@
+<!-- Consensus doc skeleton. Proven treatment: observer-memo, banker-blue accent.
+     Swap palette/type ONLY if the subject demands a different identity.
+     Replace every UPPERCASE placeholder. Delete sections that don't apply; keep the order.
+
+     SELF-CONTAINED ON PURPOSE — do not add external references.
+     This file is uploaded to a card and served by the API under a sandbox CSP
+     ("sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:").
+     That blocks webfont stylesheets, external CSS/JS, and remote images. The
+     upstream grimoire template linked Google Fonts; it is replaced here with a
+     system stack, because under this CSP the link fails silently and the doc
+     renders in a fallback font with no error. Same rule for charts: the div/CSS
+     bars below work, a JS charting library cannot run at all.
+
+     Images, if you truly need one, must be data: URIs. -->
+<title>DOC NAME</title>
+<style>
+  :root {
+    --bg: #f7f9fb; --surface: #ffffff;
+    --ink: #16222e; --ink-2: #48596a; --ink-3: #74838f;
+    --line: #d9e0e7; --line-soft: #e8edf1;
+    --accent: #20618f; --accent-soft: #dcebf5;
+    --bar: #2e6f9e; --bar-hover: #20618f;
+    --good-ink: #176a44; --good-bg: #ddf0e5;
+    --warn-ink: #8a5d00; --warn-bg: #f6ecd2;
+    --miss-ink: #a13529; --miss-bg: #f9e2de;
+    --neutral-ink: #55606b; --neutral-bg: #e8ecf0;
+    --quote-rail: #c3d5e2;
+  }
+  /* Three-state theming: bare :root = light; media block guarded against explicit light; data-theme block wins for the toggle. */
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --bg: #101720; --surface: #161f2a;
+      --ink: #e4ebf2; --ink-2: #a4b3c1; --ink-3: #7d8c9a;
+      --line: #2b3947; --line-soft: #223040;
+      --accent: #6fadd9; --accent-soft: #1d3346;
+      --bar: #4c88b4; --bar-hover: #6fadd9;
+      --good-ink: #57c48f; --good-bg: #16311f;
+      --warn-ink: #d9a94a; --warn-bg: #34290f;
+      --miss-ink: #e2857a; --miss-bg: #3a1d18;
+      --neutral-ink: #a4b3c1; --neutral-bg: #222d38;
+      --quote-rail: #33506a;
+    }
+  }
+  :root[data-theme="dark"] {
+    --bg: #101720; --surface: #161f2a;
+    --ink: #e4ebf2; --ink-2: #a4b3c1; --ink-3: #7d8c9a;
+    --line: #2b3947; --line-soft: #223040;
+    --accent: #6fadd9; --accent-soft: #1d3346;
+    --bar: #4c88b4; --bar-hover: #6fadd9;
+    --good-ink: #57c48f; --good-bg: #16311f;
+    --warn-ink: #d9a94a; --warn-bg: #34290f;
+    --miss-ink: #e2857a; --miss-bg: #3a1d18;
+    --neutral-ink: #a4b3c1; --neutral-bg: #222d38;
+    --quote-rail: #33506a;
+  }
+
+  body { background: var(--bg); color: var(--ink); font-family: ui-sans-serif, system-ui, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 16px; line-height: 1.6; margin: 0; padding: 3rem 1.25rem 5rem; }
+  .doc { max-width: 46rem; margin: 0 auto; }
+
+  .eyebrow { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.72rem; letter-spacing: 0.14em; text-transform: uppercase; color: var(--ink-3); margin: 0 0 0.75rem; }
+  h1 { font-family: ui-serif, Georgia, "Times New Roman", serif; font-weight: 700; font-size: 2.3rem; line-height: 1.15; margin: 0 0 0.5rem; text-wrap: balance; }
+  .dek { color: var(--ink-2); font-size: 1.05rem; max-width: 40rem; margin: 0 0 0.75rem; }
+  .meta { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.75rem; color: var(--ink-3); margin: 0 0 2.5rem; }
+
+  h2 { font-family: ui-serif, Georgia, "Times New Roman", serif; font-weight: 600; font-size: 1.45rem; line-height: 1.25; margin: 3rem 0 0.9rem; text-wrap: balance; }
+  h2 .sec { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-weight: 500; font-size: 0.78rem; color: var(--accent); display: block; letter-spacing: 0.12em; margin-bottom: 0.35rem; }
+  p { margin: 0 0 1rem; max-width: 42rem; }
+  a { color: var(--accent); text-decoration-thickness: 1px; text-underline-offset: 2px; }
+  strong { font-weight: 600; }
+
+  .tldr { background: var(--surface); border: 1px solid var(--line); border-left: 3px solid var(--accent); border-radius: 6px; padding: 1.15rem 1.35rem; margin: 0 0 1rem; }
+  .tldr p { margin: 0 0 0.7rem; }
+  .tldr p:last-child { margin: 0; }
+
+  figure { background: var(--surface); border: 1px solid var(--line); border-radius: 6px; margin: 1.5rem 0; padding: 1.25rem 1.35rem 1.1rem; }
+  figcaption { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.72rem; letter-spacing: 0.1em; text-transform: uppercase; color: var(--ink-3); margin-bottom: 1rem; }
+  .fignote { font-size: 0.78rem; color: var(--ink-3); margin-top: 0.9rem; }
+
+  /* Frequency bar chart: single hue (one series = no legend), direct value labels, hover emphasis + title tooltips. */
+  .barchart { display: flex; flex-direction: column; gap: 7px; }
+  .barrow { display: grid; grid-template-columns: 13.5rem 1fr 2rem; gap: 0.7rem; align-items: center; font-size: 0.85rem; }
+  .barrow .lbl { color: var(--ink-2); text-align: right; line-height: 1.25; }
+  .track { background: var(--line-soft); border-radius: 3px; height: 16px; }
+  .fill { background: var(--bar); border-radius: 3px 4px 4px 3px; height: 100%; transition: background 120ms ease; }
+  .barrow:hover .fill { background: var(--bar-hover); }
+  .barrow .val { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-variant-numeric: tabular-nums; font-size: 0.8rem; color: var(--ink-2); }
+  .barrow:hover .lbl, .barrow:hover .val { color: var(--ink); }
+
+  /* Head-to-head stacked coverage bars, one row per proposal (+ a Merged row). */
+  .compare { display: flex; flex-direction: column; gap: 10px; }
+  .cmprow { display: grid; grid-template-columns: 8.5rem 1fr; gap: 0.8rem; align-items: center; }
+  .cmprow .who { font-size: 0.85rem; font-weight: 600; text-align: right; color: var(--ink-2); }
+  .scoreboard { display: flex; height: 26px; border-radius: 5px; overflow: hidden; gap: 2px; }
+  .scoreboard div { display: flex; align-items: center; justify-content: center; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.76rem; font-weight: 500; min-width: 1.4rem; }
+  .sc-good { background: var(--good-bg); color: var(--good-ink); }
+  .sc-warn { background: var(--warn-bg); color: var(--warn-ink); }
+  .sc-miss { background: var(--miss-bg); color: var(--miss-ink); }
+  .sc-legend { display: flex; gap: 1.4rem; margin-top: 0.8rem; font-size: 0.78rem; color: var(--ink-2); flex-wrap: wrap; }
+  .sc-legend span { display: inline-flex; align-items: center; gap: 0.4rem; }
+  .swatch { width: 10px; height: 10px; border-radius: 2px; display: inline-block; }
+
+  /* Verdict + feasibility chips: text always, never color alone. */
+  .chip { display: inline-block; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.68rem; font-weight: 500; letter-spacing: 0.06em; padding: 0.15rem 0.5rem; border-radius: 999px; white-space: nowrap; }
+  .chip-good { background: var(--good-bg); color: var(--good-ink); }     /* COVERED / API &check; */
+  .chip-warn { background: var(--warn-bg); color: var(--warn-ink); }     /* PARTIAL */
+  .chip-miss { background: var(--miss-bg); color: var(--miss-ink); }     /* MISSED / NOT POSSIBLE */
+  .chip-api  { background: var(--accent-soft); color: var(--accent); }   /* vendor-supported rulings */
+  .chip-ours { background: var(--neutral-bg); color: var(--neutral-ink); } /* OUR BUILD / CONFIG */
+
+  .tablewrap { overflow-x: auto; margin: 1.5rem 0; border: 1px solid var(--line); border-radius: 6px; background: var(--surface); }
+  table { border-collapse: collapse; width: 100%; font-size: 0.86rem; }
+  th { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.68rem; letter-spacing: 0.1em; text-transform: uppercase; color: var(--ink-3); font-weight: 500; text-align: left; padding: 0.7rem 1rem; border-bottom: 1px solid var(--line); }
+  td { padding: 0.6rem 1rem; border-bottom: 1px solid var(--line-soft); vertical-align: top; color: var(--ink-2); }
+  td:first-child { color: var(--ink); font-weight: 600; }
+  tr:last-child td { border-bottom: none; }
+  td.nowrap { white-space: nowrap; }
+
+  blockquote { border-left: 3px solid var(--quote-rail); margin: 1.1rem 0; padding: 0.1rem 0 0.1rem 1.1rem; color: var(--ink-2); font-style: italic; max-width: 40rem; }
+  blockquote cite { display: block; font-style: normal; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.72rem; color: var(--ink-3); margin-top: 0.35rem; }
+
+  ol.twocents { padding-left: 1.3rem; max-width: 42rem; }
+  ol.twocents li { margin-bottom: 0.85rem; }
+  ol.twocents li::marker { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; color: var(--accent); font-size: 0.85rem; }
+
+  .method { border-top: 1px solid var(--line); margin-top: 3.5rem; padding-top: 1.25rem; font-size: 0.8rem; color: var(--ink-3); max-width: 42rem; }
+</style>
+
+<div class="doc">
+  <p class="eyebrow">Outside read &middot; No stake in the outcome</p>
+  <h1>DOC NAME</h1>
+  <p class="dek">ONE-SENTENCE FRAME: who pulled what, and what this doc rules on.</p>
+  <p class="meta">~N messages &middot; DATE &rarr; DATE &middot; N channels/sources &middot; input to DECISION/CARD</p>
+
+  <div class="tldr">
+    <p><strong>VERDICT SENTENCE.</strong> Two to three bold-led paragraphs; a reader who stops here can act.</p>
+  </div>
+
+  <h2><span class="sec">01</span>What the evidence says</h2>
+  <p>How findings were binned; what a count means.</p>
+  <figure>
+    <figcaption>FINDINGS BY INCIDENT COUNT, RANGE</figcaption>
+    <div class="barchart">
+      <!-- width = count / max * 100%. title attr = one-line version for hover. -->
+      <div class="barrow" title="ONE-LINER"><span class="lbl">CATEGORY</span><div class="track"><div class="fill" style="width:100%"></div></div><span class="val">15</span></div>
+      <div class="barrow" title="ONE-LINER"><span class="lbl">CATEGORY</span><div class="track"><div class="fill" style="width:60%"></div></div><span class="val">9</span></div>
+    </div>
+    <div class="fignote">Dominant sources; hover note.</div>
+  </figure>
+  <blockquote>"VERBATIM QUOTE"<cite>WHO &middot; #channel &middot; DATE</cite></blockquote>
+
+  <h2><span class="sec">02</span>What already exists</h2>
+  <p>Incumbent system, prior art, negative results ("no payout code in the repo").</p>
+
+  <h2><span class="sec">03</span>PROPOSAL A, scored</h2>
+  <div class="tablewrap">
+    <table>
+      <thead><tr><th>Pain / need</th><th>Verdict</th><th>Why</th></tr></thead>
+      <tbody>
+        <tr><td>ITEM</td><td class="nowrap"><span class="chip chip-good">COVERED</span></td><td>ONE SENTENCE.</td></tr>
+        <tr><td>ITEM</td><td class="nowrap"><span class="chip chip-warn">PARTIAL</span></td><td>Symptom yes, root cause no.</td></tr>
+        <tr><td>ITEM</td><td class="nowrap"><span class="chip chip-miss">MISSED</span></td><td>ONE SENTENCE.</td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <!-- Repeat 03 per proposal, then head-to-head: -->
+  <figure>
+    <figcaption>Head to head: N items each</figcaption>
+    <div class="compare">
+      <div class="cmprow"><span class="who">Proposal A</span>
+        <div class="scoreboard"><div class="sc-good" style="flex:3">3</div><div class="sc-warn" style="flex:5">5</div><div class="sc-miss" style="flex:3">3</div></div>
+      </div>
+      <div class="cmprow"><span class="who">Merged</span>
+        <div class="scoreboard"><div class="sc-good" style="flex:10">10</div><div class="sc-warn" style="flex:1">1</div></div>
+      </div>
+    </div>
+    <div class="sc-legend">
+      <span><span class="swatch" style="background:var(--good-bg);border:1px solid var(--good-ink)"></span>covered</span>
+      <span><span class="swatch" style="background:var(--warn-bg);border:1px solid var(--warn-ink)"></span>symptom yes, root cause no</span>
+      <span><span class="swatch" style="background:var(--miss-bg);border:1px solid var(--miss-ink)"></span>not in the plan</span>
+    </div>
+  </figure>
+
+  <h2><span class="sec">04</span>The merged plan, with rulings</h2>
+  <div class="tablewrap">
+    <table>
+      <thead><tr><th>Blueprint item</th><th>Feasibility</th><th>Detail</th></tr></thead>
+      <tbody>
+        <tr><td>ITEM</td><td class="nowrap"><span class="chip chip-api">API &check;</span></td><td>Ruling + <a href="ENDPOINT-DOC-URL">endpoint link</a>.</td></tr>
+        <tr><td>ITEM</td><td class="nowrap"><span class="chip chip-ours">OUR BUILD</span></td><td>Ruling.</td></tr>
+        <tr><td>ITEM</td><td class="nowrap"><span class="chip chip-miss">NOT POSSIBLE</span></td><td>Why, and whether the impossibility is desirable.</td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <h2><span class="sec">05</span>The two cents</h2>
+  <ol class="twocents">
+    <li><strong>RECOMMENDATION.</strong> The argument for it.</li>
+  </ol>
+
+  <div class="method">
+    <p><strong>Method.</strong> Queries run, counts, date range, what was reviewed in full, what was verified against primary sources, and what was NOT done.</p>
+  </div>
+</div>