claude-dev-env 8.55.0 → 8.56.1

package/docs/account-broker.md

@@ -15,12 +15,12 @@ python scripts/account_broker.py accounts --product claude
 python scripts/account_broker.py choose --product codex
 python scripts/account_broker.py choose --product codex --spent account-name:1790000000
 python scripts/account_broker.py check --product codex
-python scripts/account_broker.py run --product claude --report report.json -- claude --output-format json -p "prompt"
+printf "%s" "prompt" | python scripts/account_broker.py run --product claude --report report.json -- claude --output-format json -p
 ```
 
 `accounts` prints the roster without reading meters. `choose` prints `decision`, `accounts`, and `state_path`. Each decision contains `action`, `account`, `home`, `reason`, `tier`, and `resets_at`. A wait decision has no account or home and includes the soonest reset in UTC. A failed meter read excludes the account for that choice. `--spent` saves an exclusion until the supplied Unix reset, the account's soonest known meter reset, or one hour when neither is available. A `--spent` name absent from the roster is saved until the supplied Unix reset, or for one hour when no reset is given. While any such mark is still in the future, `choose` waits until the soonest mark and exits 3, and with no Codex roster `--spent default` waits until that mark passes. Meter reads younger than 60 seconds are reused.
 
-`check` prints nothing and exits 3 while every account is below its floor. `run` sets `CLAUDE_CONFIG_DIR` or `CODEX_HOME` for each attempt. A Claude job also starts without the parent session's variables, such as `CLAUDE_CODE_SESSION_ID` and `CLAUDECODE`, so a child started from inside a Claude Code session runs as its own session. `ALL_PARENT_CLAUDE_SESSION_VARIABLES` lists them. It replays the same stdin bytes when a usage limit or start failure leads to another account. It writes the command's stdout to stdout and diagnostics to stderr. A resumed Claude session uses the account bound to its session when that account has room.
+`check` prints nothing and exits 3 while every account is below its floor. `run` sets `CLAUDE_CONFIG_DIR` or `CODEX_HOME` for each attempt. A Claude job also starts without the parent session's variables, such as `CLAUDE_CODE_SESSION_ID` and `CLAUDECODE`, so a child started from inside a Claude Code session runs as its own session. `ALL_PARENT_CLAUDE_SESSION_VARIABLES` lists them. It replays the same stdin bytes when a usage limit or start failure leads to another account. Send the prompt on stdin. When the command resolves to a `.cmd` or `.bat` file, the broker refuses an argument that holds a cmd.exe metacharacter and records `start_failed`. It writes the command's stdout to stdout and diagnostics to stderr. A resumed Claude session uses the account bound to its session when that account has room.
 
 The broker stores cached meters, spent marks, and Claude session bindings in one JSON file under `~/.claude/account-broker`. Every broker process for the same user reads that file, so a spent mark pauses that account for every job. A write holds an exclusive lock on the sibling `state.json.lock`, re-reads the file, merges, and swaps in a sibling temporary file with `os.replace`. The merge keeps the latest reset for each spent mark and the newest meter read for each account.
 

package/docs/templates/artifact-page/README.md

@@ -0,0 +1,25 @@
+# Artifact page template
+
+`template.html` is the reference page for any artifact an agent builds: a tracker, a board, a review page, a dashboard. Start from it, keep its structure and house style, and replace the sample data and the parts the new page does not need.
+
+## What it demonstrates
+
+| Part | How the template does it |
+|---|---|
+| One file | The page, its styles, its script and its data live in one HTML file. It opens with no build step and no companion files. |
+| Data block | The sample data sits in `<script type="application/json" id="tracker-data">`. Swap that block for new data. Escape every `</` inside it as `<\/`. |
+| Board first | A board of colored lanes shows where every item stands. Each lane chip jumps to its card. |
+| Picture cards | Each item is a card with a status band, a four-step progress track, a next-step line, a folded summary, links and a copy button. |
+| Filters | Two tabs, a project filter row and a search box narrow the list. The tab and the filter persist per viewer through `localStorage`, wrapped in `try`. |
+| Themes | Every color is a token on `:root`. Dark values apply under `prefers-color-scheme: dark` and under `data-theme="dark"`. |
+| Phone width | One column, at most 640px wide, with a 16px side gutter and no horizontal scroll at 400px. |
+| Readable text | Text is 16px or larger and uses the full text color. Gray stays on lines and borders only. Text holds a 7:1 contrast ratio against its background. |
+| Touch targets | Buttons and chips are 40px or taller, with a visible focus ring. |
+| Copy fallback | The copy button uses the clipboard API and falls back to a hidden text area, then says when the copy is blocked. |
+
+## House rules for a page built from it
+
+- A control that sends anything selects first, and a separate Send button confirms. A second tap on a picked answer clears it.
+- A page that needs extra files publishes them beside the page through the Artifact `files` field, and links them by relative path.
+- A page that needs live data or saved answers declares the matching runtime capability. `localStorage` holds only per-viewer conveniences.
+- Render the page at 400px in light and dark, and exercise every control, before publishing.

package/docs/templates/artifact-page/template.html

@@ -0,0 +1,465 @@
+<title>Work Tracker</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700;800&display=swap">
+<style>
+:root {
+  --bg: #f4f5f7; --surface: #ffffff; --fg: #1b2230; --edge: #6b7383; --line: #dde1e8;
+  --accent: #2245a2; --accent-soft: #e6ecfb; --accent-ink: #ffffff;
+  --ok: #165737; --ok-soft: #e3f3ea; --bad: #8b2621; --bad-soft: #fbe5e3; --warn: #6f4100; --warn-soft: #fbf0dc;
+  --violet: #553b95; --violet-soft: #efe9fa;
+  --font-body: "Manrope", system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) {
+  --bg: #12151b; --surface: #1a1f28; --fg: #e6e9ef; --edge: #6d7891; --line: #2b3240;
+  --accent: #a8bfff; --accent-soft: #1f2a45; --accent-ink: #0d1424;
+  --ok: #6fd3a0; --ok-soft: #173327; --bad: #ffa8a0; --bad-soft: #3a1c1a; --warn: #f0b860; --warn-soft: #362a14;
+  --violet: #c5b1f2; --violet-soft: #251f38;
+  color-scheme: dark } }
+:root[data-theme="dark"] {
+  --bg: #12151b; --surface: #1a1f28; --fg: #e6e9ef; --edge: #6d7891; --line: #2b3240;
+  --accent: #a8bfff; --accent-soft: #1f2a45; --accent-ink: #0d1424;
+  --ok: #6fd3a0; --ok-soft: #173327; --bad: #ffa8a0; --bad-soft: #3a1c1a; --warn: #f0b860; --warn-soft: #362a14;
+  --violet: #c5b1f2; --violet-soft: #251f38;
+  color-scheme: dark }
+* { box-sizing: border-box }
+body { background: var(--bg); color: var(--fg); font-family: var(--font-body); font-size: 17px; line-height: 1.4; padding-inline: 16px; padding-block: 24px 48px; margin: 0 }
+button { font: inherit; color: inherit; touch-action: manipulation; cursor: pointer }
+a { color: var(--accent) }
+:focus-visible { outline: 3px solid var(--accent); outline-offset: 2px }
+.wrap { max-width: 640px; margin: 0 auto; display: grid; gap: 16px }
+header { display: grid; gap: 4px }
+h1 { font-size: 26px; font-weight: 800; letter-spacing: -0.02em; margin: 0 }
+.stamp { font-size: 16px; font-weight: 600 }
+.tabs { display: grid; grid-template-columns: 1fr 1fr; gap: 8px }
+.tab { min-height: 52px; border-radius: 12px; border: 2px solid var(--edge); background: var(--surface); font-weight: 800; font-size: 18px; display: flex; align-items: center; justify-content: center; gap: 8px }
+.tab[aria-pressed="true"] { border: 3px solid var(--accent); background: var(--accent-soft); color: var(--accent) }
+.tab .n { font-size: 18px; border-radius: 999px; padding: 0 10px; background: var(--fg); color: var(--bg) }
+.tab[aria-pressed="true"] .n { background: var(--accent); color: var(--accent-ink) }
+.board { display: grid; gap: 8px }
+.lane { border-radius: 14px; padding: 12px; display: grid; gap: 10px; border: 2px solid transparent }
+.lane.you { background: var(--warn-soft) } .lane.you .lh { color: var(--warn) }
+.lane.blocked { background: var(--bad-soft) } .lane.blocked .lh { color: var(--bad) }
+.lane.doing { background: var(--violet-soft) } .lane.doing .lh { color: var(--violet) }
+.lane.ready { background: var(--accent-soft) } .lane.ready .lh { color: var(--accent) }
+.lane.done { background: var(--ok-soft) } .lane.done .lh { color: var(--ok) }
+.lh { display: flex; align-items: center; gap: 10px; font-weight: 800; font-size: 19px }
+.lh .ic { font-size: 22px; line-height: 1 }
+.lh .count { margin-left: auto; font-size: 26px; font-variant-numeric: tabular-nums }
+.lchips { display: flex; flex-wrap: wrap; gap: 6px }
+.lchip { background: var(--surface); border: 2px solid var(--line); border-radius: 999px; padding: 4px 12px; font-size: 16px; font-weight: 700; min-height: 40px; text-align: left }
+.filters { display: flex; gap: 6px; overflow-x: auto; padding-bottom: 4px; scrollbar-width: thin }
+.fchip { flex: none; min-height: 44px; border-radius: 999px; border: 2px solid var(--edge); background: var(--surface); padding: 4px 14px; font-weight: 700; font-size: 16px; display: flex; align-items: center; gap: 6px; white-space: nowrap }
+.fchip[aria-pressed="true"] { border: 3px solid var(--accent); background: var(--accent-soft); color: var(--accent); padding: 3px 13px }
+input[type="search"] { font: inherit; font-size: 17px; width: 100%; min-height: 48px; background: var(--surface); color: var(--fg); border: 2px solid var(--edge); border-radius: 12px; padding: 8px 14px }
+input[type="search"]::placeholder { color: var(--fg); opacity: 1 }
+.section-h { font-size: 20px; font-weight: 800; margin: 8px 0 0; display: flex; align-items: center; gap: 8px }
+.list { display: grid; gap: 12px }
+.card { background: var(--surface); border: 2px solid var(--line); border-radius: 16px; overflow: hidden; display: grid; min-width: 0; scroll-margin-top: 16px }
+.card.you { border: 3px solid var(--warn) }
+.card.blocked { border: 3px solid var(--bad) }
+.card.flash { box-shadow: 0 0 0 4px var(--accent) }
+.band { display: flex; align-items: center; gap: 8px; padding: 8px 12px; font-weight: 800; font-size: 16px }
+.band.you { background: var(--warn-soft); color: var(--warn) }
+.band.blocked { background: var(--bad-soft); color: var(--bad) }
+.band.doing { background: var(--violet-soft); color: var(--violet) }
+.band.ready { background: var(--accent-soft); color: var(--accent) }
+.band.done { background: var(--ok-soft); color: var(--ok) }
+.band .proj { margin-left: auto; display: flex; align-items: center; gap: 6px; color: var(--fg); font-weight: 700; text-align: right }
+.body { padding: 12px; display: grid; gap: 12px; min-width: 0 }
+.title { font-size: 21px; font-weight: 800; margin: 0; overflow-wrap: anywhere }
+.track { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); position: relative }
+.track::before { content: ""; position: absolute; left: 12.5%; right: 12.5%; top: 15px; height: 3px; background: var(--edge) }
+.track li { display: grid; justify-items: center; gap: 4px; text-align: center; font-size: 16px; font-weight: 700; position: relative; min-width: 0 }
+.track .dot { width: 32px; height: 32px; border-radius: 50%; display: grid; place-items: center; font-weight: 800; font-size: 16px; background: var(--surface); border: 3px solid var(--edge) }
+.track li.done .dot { background: var(--ok); border-color: var(--ok); color: var(--surface) }
+.track li.now .dot { background: var(--accent); border-color: var(--accent); color: var(--accent-ink); box-shadow: 0 0 0 4px var(--accent-soft) }
+.track li.now { color: var(--accent); font-weight: 800 }
+.card.you .track li.now { color: var(--warn) }
+.card.you .track li.now .dot { background: var(--warn); border-color: var(--warn); color: var(--surface); box-shadow: 0 0 0 4px var(--warn-soft) }
+.next { display: flex; gap: 10px; align-items: flex-start; background: var(--bg); border-radius: 12px; padding: 10px 12px; font-weight: 600; overflow-wrap: anywhere }
+.next .ic { font-size: 20px; line-height: 1.2; flex: none }
+details.what { border-top: 2px solid var(--line); padding-top: 8px }
+details.what summary { font-weight: 800; cursor: pointer; min-height: 40px; display: flex; align-items: center; gap: 8px; list-style: none }
+details.what summary::-webkit-details-marker { display: none }
+details.what summary::before { content: "▸"; font-size: 18px }
+details.what[open] summary::before { content: "▾" }
+.points { margin: 6px 0 0; padding: 0; list-style: none; display: grid; gap: 8px }
+.points li { display: flex; gap: 8px; overflow-wrap: anywhere }
+.points li::before { content: "✓"; color: var(--ok); font-weight: 800; flex: none }
+.actions { display: flex; flex-wrap: wrap; gap: 8px; align-items: center }
+.link { display: inline-flex; align-items: center; gap: 6px; min-height: 44px; border: 2px solid var(--accent); border-radius: 999px; padding: 4px 14px; font-weight: 700; font-size: 16px; text-decoration: none; color: var(--accent); background: var(--surface) }
+.copy { min-height: 44px; border-radius: 999px; border: 2px solid var(--fg); background: var(--surface); padding: 4px 14px; font-weight: 800; font-size: 16px; margin-left: auto }
+.copy.ok { border-color: var(--ok); color: var(--ok) }
+.when { font-size: 16px; font-weight: 600 }
+.steps { display: grid; gap: 8px; border-top: 2px solid var(--line); padding-top: 10px }
+.steps .sh { font-weight: 800 }
+.step { display: flex; gap: 10px; align-items: flex-start }
+.step .num { flex: none; width: 30px; height: 30px; border-radius: 50%; background: var(--warn); color: var(--surface); display: grid; place-items: center; font-weight: 800 }
+.empty { background: var(--surface); border: 2px dashed var(--edge); border-radius: 14px; padding: 20px; font-weight: 600 }
+@media (hover: hover) { .lchip:hover, .fchip:hover, .tab:hover, .copy:hover { border-color: var(--accent) } }
+</style>
+
+<div class="wrap">
+  <header>
+    <h1>Work Tracker</h1>
+    <div class="stamp" id="stamp"></div>
+  </header>
+  <div class="tabs" role="group" aria-label="Show open or finished items">
+    <button class="tab" data-tab="open" aria-pressed="true">Open <span class="n" id="n-open"></span></button>
+    <button class="tab" data-tab="done" aria-pressed="false">Done <span class="n" id="n-done"></span></button>
+  </div>
+  <section class="board" id="board" aria-label="Where items stand"></section>
+  <div class="filters" id="filters" role="group" aria-label="Filter by project"></div>
+  <input type="search" id="search" placeholder="Search items" aria-label="Search items">
+  <main class="list" id="list"></main>
+</div>
+
+<script type="application/json" id="tracker-data">
+{
+ "updated": "2026-01-15T17:30:00Z",
+ "owners": [
+  {
+   "key": "web",
+   "name": "Web App",
+   "icon": "🌐"
+  },
+  {
+   "key": "platform",
+   "name": "Platform",
+   "icon": "🧩"
+  },
+  {
+   "key": "docs",
+   "name": "Documentation",
+   "icon": "📚"
+  },
+  {
+   "key": "new-project",
+   "name": "New projects",
+   "icon": "✨"
+  }
+ ],
+ "items": [
+  {
+   "title": "Pick a release date",
+   "owner": "web",
+   "status": "open",
+   "needs_you": true,
+   "card": true,
+   "next": "choose between the two dates in the linked plan.",
+   "summary": [
+    "One release date everyone plans around",
+    "The launch checklist dated backward from it",
+    "A reminder a week before"
+   ],
+   "added": "2026-01-14T15:05:00Z",
+   "links": [
+    {
+     "label": "Release plan",
+     "url": "https://example.com/release-plan"
+    }
+   ],
+   "starter": "Pick a release date. Read the release plan, list both dates with what each one moves, and ask for the choice."
+  },
+  {
+   "title": "Flaky login test",
+   "owner": "web",
+   "status": "blocked",
+   "card": true,
+   "next": "wait for the staging database to come back online.",
+   "summary": [
+    "The login test passes ten runs in a row",
+    "The root cause written in the pull request"
+   ],
+   "added": "2026-01-13T19:20:00Z",
+   "links": [
+    {
+     "label": "Issue 42",
+     "url": "https://example.com/issues/42"
+    }
+   ],
+   "starter": "Fix the flaky login test. Reproduce it, find the cause, and open a draft pull request with the proof."
+  },
+  {
+   "title": "Faster search page",
+   "owner": "platform",
+   "status": "doing",
+   "card": true,
+   "next": "finish the index change and rerun the timing check.",
+   "summary": [
+    "Search answers in under one second",
+    "A timing check that guards it",
+    "No change to the results people see"
+   ],
+   "added": "2026-01-12T14:00:00Z",
+   "links": [
+    {
+     "label": "Pull request 108",
+     "url": "https://example.com/pulls/108"
+    }
+   ],
+   "starter": "Make the search page faster. Measure first, change the index, and prove the new time."
+  },
+  {
+   "title": "Setup guide refresh",
+   "owner": "docs",
+   "status": "open",
+   "card": true,
+   "next": "start a builder on the card.",
+   "summary": [
+    "Every setup step runs as written on a clean machine",
+    "Screens match the current app"
+   ],
+   "added": "2026-01-15T16:45:00Z",
+   "starter": "Refresh the setup guide. Run each step on a clean machine and fix every step that fails."
+  },
+  {
+   "title": "Status page",
+   "owner": "new-project",
+   "status": "open",
+   "card": false,
+   "next": "create the project, then hand it the setup brief.",
+   "summary": [
+    "A public page that shows service health",
+    "An alert when a check fails"
+   ],
+   "added": "2026-01-15T17:10:00Z",
+   "proposal": {
+    "name": "Status Page"
+   },
+   "owner_steps": [
+    "Create a project named Status Page.",
+    "Attach the repository it should watch.",
+    "Paste the copied starter as its first message."
+   ],
+   "starter": "Set up the Status Page project from its brief, then build the first health check."
+  },
+  {
+   "title": "Dark mode colors",
+   "owner": "web",
+   "status": "done",
+   "card": true,
+   "next": "merged; every screen passes the contrast check in both themes.",
+   "summary": [
+    "Every color token has a dark value",
+    "Text keeps a 7:1 contrast ratio"
+   ],
+   "added": "2026-01-08T13:00:00Z",
+   "done_at": "2026-01-11T21:40:00Z",
+   "links": [
+    {
+     "label": "Pull request 97",
+     "url": "https://example.com/pulls/97"
+    }
+   ]
+  },
+  {
+   "title": "Changelog automation",
+   "owner": "platform",
+   "status": "done",
+   "card": true,
+   "next": "merged; each release writes its own changelog.",
+   "summary": [
+    "Release notes come from merged pull requests",
+    "No hand-edited changelog"
+   ],
+   "added": "2026-01-05T15:30:00Z",
+   "done_at": "2026-01-09T18:15:00Z",
+   "links": [
+    {
+     "label": "Pull request 90",
+     "url": "https://example.com/pulls/90"
+    }
+   ]
+  }
+ ]
+}
+</script>
+<script>
+const TRACKER = JSON.parse(document.getElementById("tracker-data").textContent);
+const STAGES = [
+  { key: "you", label: "Needs you", icon: "✋" },
+  { key: "blocked", label: "Blocked", icon: "⛔" },
+  { key: "doing", label: "In progress", icon: "🔨" },
+  { key: "ready", label: "Ready to build", icon: "📋" },
+  { key: "done", label: "Done", icon: "✅" }
+];
+const STAGE_BY_KEY = Object.fromEntries(STAGES.map(s => [s.key, s]));
+const TRACK = ["Card", "Builder", "Pull request", "Merged"];
+const state = { tab: "open", owner: "all", query: "" };
+try { const saved = JSON.parse(localStorage.getItem("work-tracker-view") || "{}"); if (saved.tab) state.tab = saved.tab; if (saved.owner) state.owner = saved.owner; } catch (e) {}
+const ownerByKey = Object.fromEntries(TRACKER.owners.map(o => [o.key, o]));
+const isDone = it => it.status === "done";
+function stageOf(it) {
+  if (it.status === "done") return "done";
+  if (it.status === "blocked") return "blocked";
+  if (it.needs_you) return "you";
+  if (it.status === "doing") return "doing";
+  return "ready";
+}
+const slug = it => "item-" + it.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+const fmt = iso => { if (!iso) return ""; try { return new Date(iso).toLocaleString(undefined, { month: "long", day: "numeric", hour: "numeric", minute: "2-digit" }); } catch (e) { return iso; } };
+const el = (tag, cls, text) => { const n = document.createElement(tag); if (cls) n.className = cls; if (text != null) n.textContent = text; return n; };
+function save() { try { localStorage.setItem("work-tracker-view", JSON.stringify({ tab: state.tab, owner: state.owner })); } catch (e) {} }
+function inView(it) {
+  if ((state.tab === "done") !== isDone(it)) return false;
+  if (state.owner !== "all" && it.owner !== state.owner) return false;
+  const q = state.query.trim().toLowerCase();
+  return !q || (it.title + " " + [].concat(it.summary || []).join(" ") + " " + (it.next || "")).toLowerCase().includes(q);
+}
+function jumpTo(it) {
+  const card = document.getElementById(slug(it));
+  if (!card) return;
+  card.scrollIntoView({ behavior: "smooth", block: "start" });
+  card.classList.add("flash");
+  setTimeout(() => card.classList.remove("flash"), 1600);
+}
+function renderBoard(items) {
+  const board = document.getElementById("board"); board.textContent = "";
+  const keys = state.tab === "done" ? ["done"] : ["you", "blocked", "doing", "ready"];
+  for (const key of keys) {
+    const mine = items.filter(i => stageOf(i) === key);
+    if (!mine.length && (key === "blocked" || key === "you")) continue;
+    const s = STAGE_BY_KEY[key];
+    const lane = el("div", "lane " + key);
+    const head = el("div", "lh");
+    head.append(el("span", "ic", s.icon), el("span", null, s.label));
+    head.append(el("span", "count", String(mine.length)));
+    lane.append(head);
+    if (mine.length) {
+      const chips = el("div", "lchips");
+      for (const it of mine) {
+        const b = el("button", "lchip", it.title);
+        b.setAttribute("aria-label", "Go to " + it.title);
+        b.onclick = () => jumpTo(it);
+        chips.append(b);
+      }
+      lane.append(chips);
+    }
+    board.append(lane);
+  }
+}
+function renderFilters() {
+  const f = document.getElementById("filters"); f.textContent = "";
+  const pool = TRACKER.items.filter(i => (state.tab === "done") === isDone(i));
+  const opts = [{ key: "all", name: "All projects" }].concat(TRACKER.owners.filter(o => pool.some(i => i.owner === o.key)));
+  if (!opts.some(o => o.key === state.owner)) state.owner = "all";
+  for (const o of opts) {
+    const b = el("button", "fchip");
+    if (o.key !== "all") b.append(el("span", null, (ownerByKey[o.key].icon || "📁")));
+    b.append(el("span", null, o.name));
+    if (o.key !== "all") b.append(el("b", null, String(pool.filter(i => i.owner === o.key).length)));
+    b.setAttribute("aria-pressed", String(state.owner === o.key));
+    b.onclick = () => { state.owner = o.key; save(); render(); };
+    f.append(b);
+  }
+}
+function trackFor(it) {
+  const ol = el("ol", "track");
+  ol.setAttribute("aria-label", "Progress");
+  let now;
+  if (it.status === "done") now = TRACK.length;
+  else if (it.status === "doing") now = 2;
+  else now = it.card ? 1 : 0;
+  TRACK.forEach((label, i) => {
+    const li = el("li", i < now ? "done" : i === now ? "now" : "");
+    li.append(el("span", "dot", i < now ? "✓" : String(i + 1)), el("span", null, label));
+    ol.append(li);
+  });
+  return ol;
+}
+function copyButton(it) {
+  const cp = el("button", "copy", "Copy starter");
+  cp.setAttribute("aria-label", "Copy the handoff for " + it.title);
+  const reset = () => { cp.textContent = "Copy starter"; cp.classList.remove("ok"); };
+  cp.onclick = () => {
+    const text = it.starter || it.title;
+    const done = () => { cp.textContent = "Copied ✓"; cp.classList.add("ok"); setTimeout(reset, 1800); };
+    const fallback = () => {
+      const area = document.createElement("textarea");
+      area.value = text; area.setAttribute("readonly", ""); area.style.position = "fixed"; area.style.opacity = "0";
+      document.body.append(area); area.select();
+      let copied = false; try { copied = document.execCommand("copy"); } catch (e) {}
+      area.remove();
+      if (copied) done(); else cp.textContent = "Copy blocked";
+    };
+    if (navigator.clipboard) navigator.clipboard.writeText(text).then(done, fallback); else fallback();
+  };
+  return cp;
+}
+function itemCard(it) {
+  const key = stageOf(it), s = STAGE_BY_KEY[key], owner = ownerByKey[it.owner] || { name: it.owner };
+  const card = el("article", "card " + key);
+  card.id = slug(it);
+  const band = el("div", "band " + key);
+  band.append(el("span", null, s.icon), el("span", null, s.label));
+  const proj = el("span", "proj");
+  proj.append(el("span", null, (owner.icon || "📁")), el("span", null, owner.name));
+  band.append(proj);
+  card.append(band);
+  const body = el("div", "body");
+  body.append(el("h3", "title", it.title));
+  body.append(trackFor(it));
+  if (it.next) {
+    const next = el("div", "next");
+    next.append(el("span", "ic", isDone(it) ? "✅" : "👉"), el("span", null, it.next.charAt(0).toUpperCase() + it.next.slice(1)));
+    body.append(next);
+  }
+  const points = [].concat(it.summary || []);
+  if (points.length) {
+    const d = el("details", "what");
+    d.append(el("summary", null, "What it delivers"));
+    const ul = el("ul", "points");
+    for (const p of points) ul.append(el("li", null, p));
+    d.append(ul);
+    body.append(d);
+  }
+  if (it.proposal && !isDone(it) && it.owner_steps && it.owner_steps.length) {
+    const st = el("div", "steps");
+    st.append(el("div", "sh", "Your steps to create " + it.proposal.name));
+    it.owner_steps.forEach((text, i) => { const row = el("div", "step"); row.append(el("span", "num", String(i + 1)), el("span", null, text)); st.append(row); });
+    body.append(st);
+  }
+  const actions = el("div", "actions");
+  for (const l of it.links || []) {
+    const a = el("a", "link");
+    a.append(el("span", null, "🔗"), el("span", null, l.label));
+    a.href = l.url; a.target = "_blank"; a.rel = "noopener";
+    actions.append(a);
+  }
+  if (!isDone(it)) actions.append(copyButton(it));
+  body.append(actions);
+  body.append(el("div", "when", isDone(it) ? "Done " + fmt(it.done_at) : "Added " + fmt(it.added)));
+  card.append(body);
+  return card;
+}
+function render() {
+  document.querySelectorAll(".tab").forEach(t => t.setAttribute("aria-pressed", String(t.dataset.tab === state.tab)));
+  const open = TRACKER.items.filter(i => !isDone(i));
+  document.getElementById("stamp").textContent = "Updated " + fmt(TRACKER.updated);
+  document.getElementById("n-open").textContent = open.length;
+  document.getElementById("n-done").textContent = TRACKER.items.length - open.length;
+  renderFilters();
+  const items = TRACKER.items.filter(inView);
+  renderBoard(items);
+  const list = document.getElementById("list"); list.textContent = "";
+  if (!items.length) {
+    list.append(el("div", "empty", TRACKER.items.length ? (state.tab === "done" ? "No finished items match." : "No open items match.") : "Nothing tracked yet. Add an item to the data block and it shows up here."));
+    return;
+  }
+  const order = state.tab === "done" ? ["done"] : ["you", "blocked", "doing", "ready"];
+  for (const key of order) {
+    const mine = items.filter(i => stageOf(i) === key);
+    if (!mine.length) continue;
+    mine.sort((a, b) => key === "done" ? (b.done_at || "").localeCompare(a.done_at || "") : (a.added || "").localeCompare(b.added || ""));
+    const s = STAGE_BY_KEY[key];
+    const h = el("h2", "section-h");
+    h.append(el("span", null, s.icon), el("span", null, s.label + " · " + mine.length));
+    list.append(h);
+    mine.forEach(i => list.append(itemCard(i)));
+  }
+}
+document.querySelectorAll(".tab").forEach(t => t.onclick = () => { state.tab = t.dataset.tab; save(); render(); });
+document.getElementById("search").oninput = e => { state.query = e.target.value; render(); };
+render();
+</script>

package/hooks/features/session-context.md

@@ -1,6 +1,6 @@
 # Session context
 
-This family injects reminders and task guidance when an agent starts, resumes, submits a prompt, spawns a helper, or hits an auto mode denial. The startup scripts leave the session quiet when their opt-in conditions fail.
+This family injects reminders and task guidance when an agent starts, resumes, submits a prompt, spawns a helper, starts an artifact page, or hits an auto mode denial. The startup scripts leave the session quiet when their opt-in conditions fail.
 
 ## Checks
 
@@ -10,12 +10,14 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
 - `session/issue_tracker_session_starter.py` injects issue tracker guidance when enabled for a registered repository.
+- `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/artifact-page/template.html`.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
 ## When it fires
 
 - `session/skill_loaded_reminder.py` runs on `PreToolUse` matcher `Agent|Task` at `10` seconds, `UserPromptSubmit` matcher empty at `10` seconds, `SessionStart` matcher `compact` at `10` seconds, and `SubagentStart` matcher `workflow-subagent` at `10` seconds in `hooks.json`.
 - `session/task_tool_prompt.py`, `session/working_style_prompt.py`, `session/advisor_rules_prompt.py`, `session/orchestrator_auto_starter.py`, and `session/issue_tracker_session_starter.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.
+- `session/artifact_template_pointer.py` runs on `PreToolUse` matcher `Artifact|Skill` at `10` seconds in `hooks.json`. It speaks only on an `Artifact` call with action `quickstart` or a `Skill` call that loads `artifact-design`.
 - `advisory/auto_mode_denial_quick_fix.py` runs on `PermissionDenied`, matcher `*`, timeout `10` seconds in `hooks.json`.
 
 ## Proving it
@@ -30,6 +32,7 @@ Preconditions:
 - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
 - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
 - **Issue tracker start.** Input is SessionStart with its opt-in flag and a registered checkout. Run `python -m pytest packages/claude-dev-env/hooks/session/test_issue_tracker_session_starter.py -q`. The adjacent test observes issue tracker context.
+- **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 
 ## Gotchas

package/hooks/hooks.json

@@ -127,6 +127,16 @@
           }
         ]
       },
+      {
+        "matcher": "Artifact|Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/artifact_template_pointer.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "mcp__hearthbot__start_thread_session",
         "hooks": [

package/hooks/hooks_constants/artifact_template_pointer_constants.py

@@ -0,0 +1,27 @@
+"""Names and pointer text for the artifact_template_pointer PreToolUse hook."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = [
+    "ARTIFACT_ACTION_INPUT_KEY",
+    "ARTIFACT_QUICKSTART_ACTION",
+    "ARTIFACT_TEMPLATE_PATH",
+    "ARTIFACT_TOOL_NAME",
+    "POINTER_TEXT_PREFIX",
+    "SKILL_NAME_INPUT_KEY",
+    "SKILL_TOOL_NAME",
+    "ALL_ARTIFACT_DESIGN_SKILL_NAMES",
+]
+
+ARTIFACT_TOOL_NAME = "Artifact"
+ARTIFACT_ACTION_INPUT_KEY = "action"
+ARTIFACT_QUICKSTART_ACTION = "quickstart"
+SKILL_TOOL_NAME = "Skill"
+SKILL_NAME_INPUT_KEY = "skill"
+ALL_ARTIFACT_DESIGN_SKILL_NAMES = frozenset({"artifact-design"})
+ARTIFACT_TEMPLATE_PATH = (
+    Path(__file__).resolve().parents[2] / "docs" / "templates" / "artifact-page" / "template.html"
+)
+POINTER_TEXT_PREFIX = "Build this artifact page from the template at "

package/hooks/hooks_constants/test_artifact_template_pointer_constants.py

@@ -0,0 +1,8 @@
+"""Behavioral tests for the artifact template pointer's path."""
+
+from hooks_constants.artifact_template_pointer_constants import ARTIFACT_TEMPLATE_PATH
+
+
+def test_template_path_names_the_packaged_template_file() -> None:
+    assert ARTIFACT_TEMPLATE_PATH.is_file()
+    assert ARTIFACT_TEMPLATE_PATH.parent.joinpath("README.md").is_file()

package/hooks/session/artifact_template_pointer.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: point an agent about to build an artifact page at the template.
+
+Registered on ``Artifact|Skill``. It adds one line of ``additionalContext``
+naming ``docs/templates/artifact-page/template.html`` when a session starts a
+new artifact page:
+
+::
+
+    Artifact {"action": "quickstart", ...}   -> the pointer line
+    Skill    {"skill": "artifact-design"}    -> the pointer line
+    Artifact {"action": "publish", ...}      -> no output
+    Skill    {"skill": "pr-lifecycle"}       -> no output
+
+The call runs with its normal permission flow.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.artifact_template_pointer_constants import (
+    ALL_ARTIFACT_DESIGN_SKILL_NAMES,
+    ARTIFACT_ACTION_INPUT_KEY,
+    ARTIFACT_QUICKSTART_ACTION,
+    ARTIFACT_TEMPLATE_PATH,
+    ARTIFACT_TOOL_NAME,
+    POINTER_TEXT_PREFIX,
+    SKILL_NAME_INPUT_KEY,
+    SKILL_TOOL_NAME,
+)
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.spawn_readiness_hook_constants import (
+    ADDITIONAL_CONTEXT_KEY,
+    PRE_TOOL_USE_EVENT_NAME,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+)
+
+
+def starts_an_artifact_page(tool_name: object, tool_input: object) -> bool:
+    """Return True when the call is the first step of building an artifact page.
+
+    Args:
+        tool_name: The tool the session called.
+        tool_input: The tool input.
+    """
+    if not isinstance(tool_input, dict):
+        return False
+    if tool_name == ARTIFACT_TOOL_NAME:
+        return tool_input.get(ARTIFACT_ACTION_INPUT_KEY) == ARTIFACT_QUICKSTART_ACTION
+    if tool_name == SKILL_TOOL_NAME:
+        return tool_input.get(SKILL_NAME_INPUT_KEY) in ALL_ARTIFACT_DESIGN_SKILL_NAMES
+    return False
+
+
+def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object] | None:
+    """Return the pointer as additionalContext output, or None to stay quiet.
+
+    Args:
+        all_hook_fields: The parsed PreToolUse payload.
+    """
+    if not starts_an_artifact_page(
+        all_hook_fields.get(TOOL_NAME_KEY), all_hook_fields.get(TOOL_INPUT_KEY)
+    ):
+        return None
+    return {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
+            ADDITIONAL_CONTEXT_KEY: f"{POINTER_TEXT_PREFIX}{ARTIFACT_TEMPLATE_PATH}.",
+        }
+    }
+
+
+def main() -> int:
+    """Read the PreToolUse payload and print the pointer when the call starts a page.
+
+    Returns:
+        0 in every case; the pointer travels in the JSON output.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return 0
+    hook_output = decide_hook_output(hook_payload)
+    if hook_output is not None:
+        sys.stdout.write(json.dumps(hook_output))
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/session/test_artifact_template_pointer.py

@@ -0,0 +1,65 @@
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import artifact_template_pointer
+from hooks_constants.artifact_template_pointer_constants import ARTIFACT_TEMPLATE_PATH
+
+HOOK_SCRIPT = Path(__file__).resolve().parent / "artifact_template_pointer.py"
+
+
+def _payload(tool_name: str, tool_input: object) -> dict[str, object]:
+    return {"hook_event_name": "PreToolUse", "tool_name": tool_name, "tool_input": tool_input}
+
+
+def _run_hook(payload: dict[str, object]) -> str:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return completed.stdout
+
+
+def test_artifact_quickstart_gets_the_template_pointer() -> None:
+    hook_output = json.loads(_run_hook(_payload("Artifact", {"action": "quickstart", "intent": "other"})))
+    specific_output = hook_output["hookSpecificOutput"]
+    assert specific_output["hookEventName"] == "PreToolUse"
+    assert str(ARTIFACT_TEMPLATE_PATH) in specific_output["additionalContext"]
+    assert "permissionDecision" not in specific_output
+
+
+def test_artifact_design_skill_gets_the_template_pointer() -> None:
+    hook_output = artifact_template_pointer.decide_hook_output(
+        _payload("Skill", {"skill": "artifact-design"})
+    )
+    assert hook_output is not None
+    assert str(ARTIFACT_TEMPLATE_PATH) in hook_output["hookSpecificOutput"]["additionalContext"]
+
+
+def test_artifact_publish_stays_quiet() -> None:
+    assert _run_hook(_payload("Artifact", {"action": "publish", "file_path": "page.html"})) == ""
+
+
+def test_other_skill_stays_quiet() -> None:
+    assert artifact_template_pointer.decide_hook_output(_payload("Skill", {"skill": "pr-lifecycle"})) is None
+
+
+def test_tool_input_that_is_not_an_object_stays_quiet() -> None:
+    assert artifact_template_pointer.decide_hook_output(_payload("Artifact", "quickstart")) is None
+
+
+def test_empty_stdin_stays_quiet() -> None:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)], input="", capture_output=True, text=True, check=True
+    )
+    assert completed.stdout == ""

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.55.0",
+    "version": "8.56.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {