@marcomigozzi/trailhead 0.16.1 → 0.17.0

package/README.it.md

@@ -26,7 +26,7 @@ Due approcci al lavoro di progetto guidato dagli agenti risolvono ciascuno una m
 
 Lavorando su entrambi, uno schema continuava a ripresentarsi: **usa una mappa e un onboarding in stile Wayfinder per decidere la forma del lavoro, poi un motore in stile GSD per costruire ogni pezzo, senza mai lasciare l'issue tracker.** `trailhead` è quello schema trasformato in un insieme di skill a cluster coesi su un core condiviso, una sua interpretazione autonoma di entrambe le idee anziché un wrapper attorno all'una o all'altra.
 
-> **trailhead è self-contained** nel senso che ha **zero dipendenze da plugin esterni**: gli agent di trailhead e i built-in dell'host vanno bene, e nessun'altra skill o plugin è richiesta. Wayfinder e GSD sono *ispirazione*, non dipendenze. Ogni tecnica che quei sistemi impacchettano come skill separata (grilling, TDD, debugging sistematico, codebase mapping, code review) è **integrata qui come protocollo inline**. Il core di trailhead non invoca nessun'altra skill; ogni tecnica del motore dispatcha al **proprio agent `trailhead-*`** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, più `trailhead-fix` e `trailhead-codebase-map`), scritto una volta come file `agents/trailhead-*.md` versionato e **proiettato su ogni host** (su Codex diventa `~/.codex/agents/trailhead-*.toml` generato dalla stessa sorgente). Questi agent sono **thin** (identità + tool policy + un modello guidato dalla config, con il protocollo della tecnica iniettato allo spawn) e girano sul toolkit di subagent nativo dell'host (il tool `Agent` integrato di Claude Code, oppure il toolkit `multi_agent` di Codex). L'unica cosa da installare è trailhead stesso. C'è un'unica eccezione opt-in: i mockup hosted. `design: artifacts` usa il tool `Artifact` integrato in Claude Code (niente da installare), e `design: stitch` usa l'MCP Google Stitch (offerto come installazione una tantum). Vedi [Mockup prima del codice](#-mockup-prima-del-codice).
+> **trailhead è self-contained** nel senso che ha **zero dipendenze da plugin esterni**: gli agent di trailhead e i built-in dell'host vanno bene, e nessun'altra skill o plugin è richiesta. Wayfinder e GSD sono *ispirazione*, non dipendenze. Ogni tecnica che quei sistemi impacchettano come skill separata (grilling, TDD, debugging sistematico, codebase mapping, code review) è **integrata qui come protocollo inline**. Il core di trailhead non invoca nessun'altra skill; ogni tecnica del motore dispatcha al **proprio agent `trailhead-*`** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, `trailhead-verify`, `trailhead-grill`, più `trailhead-fix` e `trailhead-codebase-map`), scritto una volta come file `agents/trailhead-*.md` versionato e **proiettato su ogni host** (su Codex diventa `~/.codex/agents/trailhead-*.toml` generato dalla stessa sorgente). Questi agent sono **thin** (identità + tool policy + un modello guidato dalla config, con il protocollo della tecnica iniettato allo spawn) e girano sul toolkit di subagent nativo dell'host (il tool `Agent` integrato di Claude Code, oppure il toolkit `multi_agent` di Codex). L'unica cosa da installare è trailhead stesso. C'è un'unica eccezione opt-in: i mockup hosted. `design: artifacts` usa il tool `Artifact` integrato in Claude Code (niente da installare), e `design: stitch` usa l'MCP Google Stitch (offerto come installazione una tantum). Vedi [Mockup prima del codice](#-mockup-prima-del-codice).
 
 Le scelte di design che ne derivano:
 
@@ -51,7 +51,7 @@ Le scelte di design che ne derivano:
 
 > **Gira su Claude Code e Codex CLI.** trailhead è scritto una volta sola; l'installer proietta artefatti nativi per l'host. Su **Claude Code**: una skill + comandi `/trailhead:*` + hook. Su **Codex CLI**: una skill nativa invocata `$trailhead`, una skill `$trailhead-<verb>` per ogni verbo per la discoverability, e le guardrail come hook nativi di Codex. Scegli l'host con `--claude` / `--codex`, o lascia che l'installer lo rilevi da solo. Altri host possono seguire (l'installer usa un descrittore per-host).
 
-**Prerequisiti:** una [`gh` CLI](https://cli.github.com) autenticata (il tracker è GitHub Issues) e un repo GitHub in cui lavorare. Il percorso npm richiede anche Node 18+.
+**Prerequisiti:** una [`gh` CLI](https://cli.github.com) autenticata (il tracker è GitHub Issues) e un repo GitHub in cui lavorare. Il percorso npm richiede anche Node 18+. Se un `GH_TOKEN`/`GITHUB_TOKEN` non valido nell'ambiente oscura un login `gh` funzionante, un controllo all'avvio della sessione lo segnala una volta, con la correzione.
 
 ### Come plugin Claude Code (nativo, gestito da `/plugin`)
 ```
@@ -69,7 +69,7 @@ npx @marcomigozzi/trailhead --symlink    # dev install (Claude; symlink al check
 npx @marcomigozzi/trailhead --uninstall  # rimuove tutto ciò che ha aggiunto (abbinalo a --claude / --codex)
 npx @marcomigozzi/trailhead --dir=<path> # punta a una config dir specifica
 ```
-Su **Claude Code** copia la skill (+ le sue `references/`), i comandi `/trailhead:*`, gli hook (in `hooks/`, registrati in `settings.json`) incluso un **update check** al SessionStart, e i template (workflow label-guard, statusline, l'hook git `commit-msg` e gli script di supporto che il motore esegue), in modo idempotente.
+Su **Claude Code** copia la skill (+ le sue `references/`), i comandi `/trailhead:*`, gli hook (in `hooks/`, registrati in `settings.json`) incluso un **update check** al SessionStart (che esegue anche il controllo del token `gh`), e i template (workflow label-guard, statusline, l'hook git `commit-msg` e gli script di supporto che il motore esegue), in modo idempotente.
 
 Su **Codex CLI** (`--codex`) proietta una skill nativa Codex invocata come **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), una skill sottile **`$trailhead-<verb>`** per ogni verbo per la discoverability, le otto guardrail come **hook** nativi di Codex (`~/.codex/hooks.json`, abilitando `features.hooks`; i cinque guard Bash condividono un solo processo dietro una singola registrazione; la search guard è solo per Claude Code e non è proiettata su Codex), e i pin di modello per-tecnica da **`models.codex.*`** in `~/.codex/agents/`. Serve Codex **0.145.0+** (l'installer fa un gate su `codex --version`). La modalità mockup `artifacts` (il tool `Artifact` di Claude Code) non è disponibile su Codex; lì l'opzione hosted è la modalità cross-host `design: stitch` (MCP Google Stitch), con il disco locale come ripiego.
 
@@ -230,7 +230,7 @@ La mod di trailhead (Claude Code 2.1.287+) è inclusa nel plugin e disegna il la
 
 ![Il pannello della mappa affiancato al transcript: mappe aperte, frontier con un pulsante work per ticket, in corso, bloccati e un footer con refresh e close](assets/screenshots/map-panel.png)
 
-Il pannello della mappa elenca le mappe aperte da consultare, i ticket che una run autonoma ha parcheggiato per te in un gruppo `Needs you` in cima, la frontier con un pulsante `work` per ogni ticket che pulisce il contesto e avvia il ticket, chi tiene cosa (il tuo ticket è segnato `this session`), i follow-up UAT in sospeso in un gruppo `UAT` (ognuno con il ticket che collauda), i ticket in pausa in un gruppo `Paused` e cosa è bloccato. Una riga dim sotto la riga Whiteboard somma i ticket aperti di tutte le mappe aperte più la whiteboard, lo stesso numero che dichiara `/trailhead:map` (`at least N` quando le mappe aperte sono più di quelle lette dal pannello). Il footer ha `refresh` e `close`. `/trailhead:panel` lo apre e lo chiude, e si apre da solo una volta in fullscreen.
+Il pannello della mappa elenca le mappe aperte da consultare, subito sotto di esse i tuoi ticket in lavorazione (in un gruppo `In progress`, da ogni mappa e dalla whiteboard), i ticket che una run autonoma ha parcheggiato per te in un gruppo `Needs you`, la frontier con un pulsante `work` per ogni ticket che pulisce il contesto e avvia il ticket (nel checkout della mappa; se quel checkout è stato spostato, viene ritrovato tramite il suo remote `origin`, e scegli tu quando ne corrispondono diversi), chi tiene cosa (il tuo ticket è segnato `this session`), i follow-up UAT in sospeso in un gruppo `UAT` (ognuno con il ticket che collauda), i ticket in pausa in un gruppo `Paused` e cosa è bloccato. Una riga dim sotto la riga Whiteboard somma i ticket aperti di tutte le mappe aperte più la whiteboard, lo stesso numero che dichiara `/trailhead:map` (`at least N` quando le mappe aperte sono più di quelle lette dal pannello). Il footer ha `refresh` e `close`. `/trailhead:panel` lo apre e lo chiude (se richiesto all'avvio della sessione, prima che lo schermo sia pronto, si apre appena lo è), e si apre da solo una volta in fullscreen.
 
 ![Il pannello che mostra un'altra mappa, con l'intestazione viewing e active e il pulsante back to active](assets/screenshots/map-panel-viewing.png)
 
@@ -407,13 +407,59 @@ Molte persone (e le loro sessioni di agente) condividono una mappa e la lavorano
 - **Dai scope ai ticket per path su un monorepo.** Un ticket può portare una riga `Scope:` che nomina il/i package/dir che tocca: scope disgiunti parallelizzano in sicurezza, e dà scope a build/test e ai commit del worktree limitandoli al package interessato. `/trailhead:adopt` rileva un monorepo e propone sia `isolation: worktree` sia la convenzione `Scope:`. Sotto `isolation: none`, `Scope:` **serializza** anche un'area condivisa: al momento del claim una sessione si trattiene se lo scope di un altro ticket in corso si sovrappone, così due ticket con scope sullo stesso submodule/package non possono girare insieme (è così che tieni due sessioni fuori da un'app legata a un path).
 - **I git submodule sono gestiti come repo separati.** Il lavoro che atterra dentro un submodule viene committato *dentro il submodule* (su un branch) e pubblicato prima che un bump del gitlink nel parent lo referenzi. Poiché i worktree del superproject condividono un unico git dir del submodule, un **repo con submodule risolve a `clone`** (sotto il default `auto`, o scalando un `worktree` esplicito), così ogni ticket ottiene uno stato del submodule indipendente; il clone provvede i suoi submodule al setup (`--recurse-submodules`) e il Verify controlla `git status` dentro ogni submodule toccato. Un ticket che copre due submodule resta atomico tramite un singolo commit del parent che bumpa entrambi i gitlink insieme; il suo `Scope:` li nomina entrambi, e lo stesso submodule conta come scope sovrapposto, quindi due ticket su di esso serializzano. `/trailhead:adopt` rileva `.gitmodules` e scrive la regola nelle conventions.
 - **Lo stato vive sui ticket** (claim, label, commenti; tutti conflict-free); il corpo della mappa è un indice ri-leggibile, non la fonte di verità. Il record durevole di una risoluzione è il commento del ticket stesso.
-- **Le label sono protette dagli esterni.** Le label `trailhead:*` guidano la mappa, quindi trailhead si fida di una issue etichettata solo quando un collaboratore con accesso in scrittura ha applicato la label e (per un ticket) porta un `Parent:` valido. Qualsiasi altra cosa è messa in quarantena come `trailhead:unverified`, fuori dalla frontier. GitHub già blocca gli utenti senza accesso in scrittura dall'applicare label; contro gli utenti di triage e le automazioni, trailhead può **installare per te la GitHub Action di label guard** (da `templates/trailhead-label-guard.yml`) nella `.github/workflows/` del tuo repo, dove rimuove alla fonte le label `trailhead:*` non autorizzate. Installare un workflow richiede un token con lo scope `workflow`, quindi trailhead esegue `gh auth refresh -s workflow` se il push viene rifiutato.
-- **Le issue aperte da altri vengono triage-ate, non fidate alla cieca.** `/trailhead:inbox` elenca le issue in ingresso (bug report, richieste, domande che non sono ancora trailhead ticket) e integra quelle valide **sul posto**: riformulandole come ticket, mantenendo l'autorialità di chi ha segnalato, e applicando le label all'adozione. Il resto viene instradato a fog, out-of-scope, duplicato, o needs-info.
+- **Le label sono protette dagli esterni.** Le label `trailhead:*` guidano la mappa, quindi trailhead si fida di una issue etichettata solo quando ogni sua label `trailhead:*` è stata applicata da un etichettatore fidato (un collaboratore con accesso in scrittura, `github-actions[bot]`, o un login nella variabile di repo `TRAILHEAD_LABEL_ALLOWLIST`: gli stessi etichettatori che la label guard non rimuove mai) e (per un ticket) porta un `Parent:` valido. Qualsiasi altra cosa è messa in quarantena come `trailhead:unverified`, fuori dalla frontier. GitHub già blocca gli utenti senza accesso in scrittura dall'applicare label; contro gli utenti di triage e le automazioni, trailhead può **installare per te la GitHub Action di label guard** (da `templates/trailhead-label-guard.yml`) nella `.github/workflows/` del tuo repo, dove rimuove alla fonte le label `trailhead:*` non autorizzate. Installare un workflow richiede un token con lo scope `workflow`, quindi trailhead esegue `gh auth refresh -s workflow` se il push viene rifiutato. Per le automazioni (CI, cron, bot) che aprono ticket senza una sessione di chat, `templates/trailhead-capture.js` cattura un bug, todo, seed o idea con tutte le label e si rifiuta di girare con un'identità che la guard strapperebbe, e su GitHub la composite Action [`actions/capture`](#catturare-da-ci) lo incapsula in poche righe di workflow.
+- **Le issue aperte da altri vengono triage-ate, non fidate alla cieca.** `/trailhead:inbox` elenca le issue in ingresso (bug report, richieste, domande che non sono ancora trailhead ticket) e integra quelle valide **sul posto**: riformulandole come ticket, mantenendo l'autorialità di chi ha segnalato, e applicando le label all'adozione. Il resto viene instradato a fog, out-of-scope, duplicato, o needs-info. Lì sono elencate anche le issue in quarantena `trailhead:unverified`, da adottare o rifiutare.
+
+### Catturare da CI
+
+`ToRvaLDz/trailhead/actions/capture` è una composite Action sottile sopra l'helper di cattura: ogni regola (trust, destinazione, dedupe, secret scan, label, edge, dashboard) resta nell'helper. Fissa un tag di release (l'Action è disponibile dalla 0.17.0).
+
+```yaml
+permissions:
+  issues: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # ... i tuoi step di build e test ...
+      - if: failure()
+        uses: ToRvaLDz/trailhead/actions/capture@v0.17.0
+        with:
+          type: bug
+          title: "CI fallita su ${{ github.ref_name }}"
+          body: "Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          dedupe-key: ci-failure-${{ github.job }}
+```
+
+Una variante manuale funziona uguale: avvia il job con `workflow_dispatch` e passa `type`, `title` e `body` da `github.event.inputs`.
+
+| Input | Obbligatorio | Significato |
+|---|---|---|
+| `type` | sì | `bug`, `todo`, `idea` o `seed` |
+| `title` | sì | titolo della issue |
+| `body` / `body-file` | uno dei due | corpo della issue, o un percorso file (`-` per stdin); non entrambi |
+| `map` / `of` | no | archivia sotto la mappa `<n>`, o eredita la mappa del ticket d'origine `<n>` (solo bug); esclusivi |
+| `trigger` | solo seed | il testo di `Trigger:` |
+| `unverified` | no | `true` aggiunge `trailhead:unverified` (non per `idea`) |
+| `dedupe-key` | no | chiave di idempotenza, da 1 a 100 caratteri `A-Za-z0-9._:-` (niente spazi né `/`) |
+| `no-dashboard` | no | `true` salta l'aggiornamento della dashboard della whiteboard |
+| `repo` | no | `owner/name` di destinazione (default: questo repo) |
+| `token` | no | token per l'helper (default: `github.token`) |
+
+Output: `issue`, `url` e `status` (`created`, `existing`, `partial`, `error`, `usage`).
+
+- Il token predefinito agisce come `github-actions[bot]`, di cui la label guard si fida; l'helper lo verifica dopo la creazione.
+- Un nuovo run con lo stesso `dedupe-key` restituisce `existing` e non crea nulla.
+- `partial` (exit 3, la issue esiste ma l'edge di sub-issue è fallito), `error` e `usage` (exit 2, input errati) fanno fallire lo step; `status` viene comunque impostato.
+- Il runner richiede bash, node e gh, presenti sui runner ospitati da GitHub; i runner self-hosted devono fornirli.
 
 ## ✅ Tenere i ticket onesti
 
 Un ticket è una singola Question a cui si può rispondere, dimensionata a una sessione, così non lo fai mai crescere in corsa. Quando nuovo scope emerge mentre lavori (i test soprattutto scatenano idee), decidi caso per caso: piccolo e parte della stessa Question → fallo e basta; gonfia il ticket oltre una sessione → **splittalo**; lavoro separato o un follow-up → **catturalo** (`idea`/`todo`/`ticket`/`bug`) e continua. Gli extra non diventano mai righe silenziose dentro il ticket su cui sei.
 
+Un ticket catturato finisce dove appartiene il suo argomento: sulla mappa corrente quando serve la sua destinazione, su un'altra mappa aperta quando serve chiaramente quella, e altrimenti trailhead chiede (ogni mappa aperta, poi la whiteboard). Con una mappa aperta non ripiega mai in silenzio sulla whiteboard, e ti dice in una riga cosa ha aperto e dove.
+
 I ticket che nascono da altro lavoro portano un puntatore di lignaggio nel loro corpo, così la mappa resta tracciabile:
 
 | Pointer | Significato |
@@ -445,8 +491,8 @@ Il passo **📊 statusline** offre di installare la status bar di trailhead per
 | Key | Values (default **bold**) | Effetto |
 |---|---|---|
 | `ticket.language` | un codice ISO 639-1 (**`en`**) | la lingua in cui trailhead **scrive** la sua prosa GitHub e le descrizioni dei commit, disaccoppiata dalla lingua in cui conversa |
-| `models.{plan,execute,research,review,debug,verify,codebase-map}` | un id modello completo **versionato** (**default del profilo Balanced**; `inherit session` è una scelta esplicita) | quale modello esegue ogni attività; `plan` ed `execute` sono sempre impostati separatamente |
-| `models.codex.{plan,execute,research,review,debug,verify,codebase-map}` | un id modello OpenAI, o `{model, effort}` (**inherit session**) | la stessa divisione per attività su Codex, indipendente da `models.*` (id Claude); riesegui l'installer per proiettarla in `~/.codex/agents/` |
+| `models.{plan,execute,research,review,debug,verify,codebase-map,grill}` | un id modello completo **versionato** (**default del profilo Balanced**; `inherit session` è una scelta esplicita) | quale modello esegue ogni attività; `plan` ed `execute` sono sempre impostati separatamente |
+| `models.codex.{plan,execute,research,review,debug,verify,codebase-map,grill}` | un id modello OpenAI, o `{model, effort}` (**inherit session**) | la stessa divisione per attività su Codex, indipendente da `models.*` (id Claude); riesegui l'installer per proiettarla in `~/.codex/agents/` |
 | `design` | **`disk`** \| `artifacts` \| `stitch` | dove vanno i mockup UI: HTML usa-e-getta locale, un canvas Design **Artifact** su claude.ai (solo Claude Code), o Google Stitch (cross-host, via l'MCP Stitch). Il vecchio valore `claude.ai/design` viene letto come `artifacts` |
 | `design.project` | URL del canvas Artifact / id del progetto Stitch | solo `artifacts` e `stitch`: il canvas o il progetto Stitch su cui finiscono i mockup; impostato alla prima schermata UI (scegli, incolla o crea), non a mano. Un vecchio progetto claude.ai/design non viene riutilizzato |
 | `design.surface` | **`canvas`** \| `design-system` | solo `stitch`: un progetto Stitch di schermate (default) o un design system Stitch condiviso |
@@ -468,10 +514,11 @@ Il passo **📊 statusline** offre di installare la status bar di trailhead per
 
 - `plan` ed `execute` sono i passi del motore build/bug. Execute è anch'esso un subagent, e committa su `main`.
 - `research`, `review`, `debug`, `verify` (il controllo goal-backward in Verify), e il fan-out della codebase-map girano ciascuno sulla propria chiave.
+- `grill` esegue i round di grilling sul subagent read-only `trailhead-grill`; se non impostata, usa lo stesso modello di `plan`, e una config esistente senza chiave `grill` fa grilling sul suo modello `plan`. La sessione ti fa comunque ogni domanda e tiene le risposte.
 
-Scegli `plan` ed `execute` separatamente, ciascuno per **id completo versionato** (mai un `opus` o `sonnet` nudo). Una chiave non impostata usa il default del profilo Balanced, e una uguale al modello della sessione gira semplicemente inline; imposta `inherit session` per usare il modello della sessione.
+Scegli `plan` ed `execute` separatamente, ciascuno per **id completo versionato** (mai un `opus` o `sonnet` nudo). Una chiave non impostata usa il default del profilo Balanced, e una uguale al modello della sessione gira semplicemente inline; imposta `inherit session` per usare il modello della sessione. Su Codex, un `models.codex.grill` non impostato segue `models.codex.plan` quando è pinnato (riesegui l'installer per proiettarlo), altrimenti eredita il modello della sessione; un pin uguale al modello della sessione gira inline. Un profilo non scrive mai una voce `grill`, quindi continua a seguire `plan`.
 
-La **sessione principale resta l'orchestratore**. Tiene i momenti interattivi (il Discuss di un build, e l'acceptance/UAT del Verify) e fa charting, grilling e scrittura dei ticket sul proprio modello. Nessuna chiave governa la qualità dei ticket, quindi esegui le sessioni di charting sul tuo modello forte.
+La **sessione principale resta l'orchestratore**. Tiene i momenti interattivi (il Discuss di un build, e l'acceptance/UAT del Verify) e fa charting e scrittura dei ticket sul proprio modello; per il grilling inoltra ogni domanda di `trailhead-grill` e te la pone lei stessa. Nessuna chiave governa la qualità dei ticket, quindi esegui le sessioni di charting sul tuo modello forte.
 
 Esempio di file di config (la stessa forma funziona per il `.trailhead/config.json` di progetto e il `trailhead/config.json` globale nella tua directory di config):
 

package/README.md

@@ -26,7 +26,7 @@ Two approaches to agent-driven project work each nail one half of the problem:
 
 Working across both, one pattern kept recurring: **use a Wayfinder-style map and onboarding to decide the shape of the work, then a GSD-style engine to build each piece, without ever leaving the issue tracker.** `trailhead` is that pattern made into a set of cohesion-clustered skills over a shared core, its own self-contained take on both ideas rather than a wrapper around either.
 
-> **trailhead is self-contained** in the sense that it has **zero external-plugin dependencies**: trailhead-owned agents and the host's built-ins are fine, and no other skill or plugin is required. Wayfinder and GSD are *inspiration*, not dependencies. Every technique those systems package as a separate skill (grilling, TDD, systematic debugging, codebase mapping, code review) is **built in here as an inline protocol**. trailhead's core invokes no other skill; each engine technique dispatches to **trailhead's own `trailhead-*` agent** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, plus `trailhead-fix` and `trailhead-codebase-map`), authored once as a committed `agents/trailhead-*.md` file and **projected to each host** (Codex gets `~/.codex/agents/trailhead-*.toml` generated from that same source). These agents are **thin** (identity + tool policy + a config-driven model, with the technique protocol injected at spawn) and run on the host's native subagent toolkit (Claude Code's built-in `Agent` tool, or Codex's `multi_agent` toolkit). The only thing to install is trailhead itself. There is one opt-in exception: hosted mockups. `design: artifacts` uses Claude Code's built-in `Artifact` tool (nothing to install), and `design: stitch` uses the Google Stitch MCP (offered as a one-time install). See [Mockups before code](#-mockups-before-code).
+> **trailhead is self-contained** in the sense that it has **zero external-plugin dependencies**: trailhead-owned agents and the host's built-ins are fine, and no other skill or plugin is required. Wayfinder and GSD are *inspiration*, not dependencies. Every technique those systems package as a separate skill (grilling, TDD, systematic debugging, codebase mapping, code review) is **built in here as an inline protocol**. trailhead's core invokes no other skill; each engine technique dispatches to **trailhead's own `trailhead-*` agent** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, `trailhead-verify`, `trailhead-grill`, plus `trailhead-fix` and `trailhead-codebase-map`), authored once as a committed `agents/trailhead-*.md` file and **projected to each host** (Codex gets `~/.codex/agents/trailhead-*.toml` generated from that same source). These agents are **thin** (identity + tool policy + a config-driven model, with the technique protocol injected at spawn) and run on the host's native subagent toolkit (Claude Code's built-in `Agent` tool, or Codex's `multi_agent` toolkit). The only thing to install is trailhead itself. There is one opt-in exception: hosted mockups. `design: artifacts` uses Claude Code's built-in `Artifact` tool (nothing to install), and `design: stitch` uses the Google Stitch MCP (offered as a one-time install). See [Mockups before code](#-mockups-before-code).
 
 The design choices that fall out of it:
 
@@ -51,7 +51,7 @@ The design choices that fall out of it:
 
 > **Runs on Claude Code and Codex CLI.** trailhead is authored once; the installer projects host-native artifacts. On **Claude Code**: a skill + `/trailhead:*` commands + hooks. On **Codex CLI**: a native skill invoked `$trailhead`, one `$trailhead-<verb>` skill per verb for discoverability, and the guardrails as native Codex hooks. Choose the host with `--claude` / `--codex`, or let the installer auto-detect. More hosts can follow (the installer uses a per-host descriptor).
 
-**Prerequisites:** an authenticated [`gh` CLI](https://cli.github.com) (the tracker is GitHub Issues) and a GitHub repo to work in. The npm path also needs Node 18+.
+**Prerequisites:** an authenticated [`gh` CLI](https://cli.github.com) (the tracker is GitHub Issues) and a GitHub repo to work in. The npm path also needs Node 18+. If an invalid `GH_TOKEN`/`GITHUB_TOKEN` in your environment shadows a working `gh` login, a check at session start says so once, with the fix.
 
 ### As a Claude Code plugin (native, managed by `/plugin`)
 ```
@@ -69,7 +69,7 @@ npx @marcomigozzi/trailhead --symlink    # dev install (Claude; symlink to the c
 npx @marcomigozzi/trailhead --uninstall  # remove everything it added (pair with --claude / --codex)
 npx @marcomigozzi/trailhead --dir=<path> # target a specific config dir
 ```
-On **Claude Code** it copies the skill (+ its `references/`), the `/trailhead:*` commands, the hooks (into `hooks/`, registered in `settings.json`) including a SessionStart **update check**, and the templates (label-guard workflow, statusline, the git `commit-msg` hook and the helper scripts the engine runs), idempotently.
+On **Claude Code** it copies the skill (+ its `references/`), the `/trailhead:*` commands, the hooks (into `hooks/`, registered in `settings.json`) including a SessionStart **update check** (which also runs the `gh` token check), and the templates (label-guard workflow, statusline, the git `commit-msg` hook and the helper scripts the engine runs), idempotently.
 
 On **Codex CLI** (`--codex`) it projects a native Codex skill invoked as **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), one thin **`$trailhead-<verb>`** skill per verb for discoverability, the eight guardrails as native Codex **hooks** (`~/.codex/hooks.json`, enabling `features.hooks`; the five Bash guards share one process behind a single registration; the search guard is Claude-Code-only and isn't projected to Codex), and per-technique subagent model pins from **`models.codex.*`** into `~/.codex/agents/`. Codex **0.145.0+** is required (the installer gates on `codex --version`). The `artifacts` mockup mode (Claude Code's `Artifact` tool) isn't available on Codex; the cross-host `design: stitch` mode (Google Stitch MCP) is the hosted option there, with local disk as the fallback.
 
@@ -230,7 +230,7 @@ The trailhead mod (Claude Code 2.1.287+) ships inside the plugin and draws the w
 
 ![The map panel docked beside the transcript: open maps, frontier with a work button per ticket, in progress, blocked, and a footer with refresh and close](assets/screenshots/map-panel.png)
 
-The map panel lists the open maps to view, the tickets an autonomous run parked for you in a `Needs you` group at the top, the frontier with a `work` button per ticket that clears the context and starts the ticket, who holds what (your own ticket is marked `this session`), the pending UAT follow-ups in a `UAT` group (each naming the ticket it tests), the paused ones in a `Paused` group, and what is blocked. A dim line under the Whiteboard row totals the open tickets across every open map plus the whiteboard, the same number `/trailhead:map` states (`at least N` when more open maps exist than the panel reads). The footer has `refresh` and `close`. `/trailhead:panel` toggles it, and it opens by itself once in fullscreen.
+The map panel lists the open maps to view, your tickets in progress right under them (in an `In progress` group, from every map and the whiteboard), the tickets an autonomous run parked for you in a `Needs you` group, the frontier with a `work` button per ticket that clears the context and starts the ticket (in the map's checkout; if that checkout has moved, it is found again by its `origin` remote, and you pick one when several match), who holds what (your own ticket is marked `this session`), the pending UAT follow-ups in a `UAT` group (each naming the ticket it tests), the paused ones in a `Paused` group, and what is blocked. A dim line under the Whiteboard row totals the open tickets across every open map plus the whiteboard, the same number `/trailhead:map` states (`at least N` when more open maps exist than the panel reads). The footer has `refresh` and `close`. `/trailhead:panel` toggles it (asked at session start, before the screen is ready, it opens as soon as it is), and it opens by itself once in fullscreen.
 
 ![The panel viewing another map, with a viewing and active header and a back to active button](assets/screenshots/map-panel-viewing.png)
 
@@ -407,13 +407,59 @@ Many people (and their agent sessions) share one map and work it concurrently:
 - **Scope tickets by path on a monorepo.** A ticket can carry a `Scope:` line naming the package/dir(s) it touches: disjoint scopes parallelize safely, and it scopes build/test and the worktree's commits to the affected package. `/trailhead:adopt` detects a monorepo and proposes both `isolation: worktree` and the `Scope:` convention. Under `isolation: none`, `Scope:` also **serializes** a shared area: at claim time a session holds off if another in-progress ticket's scope overlaps, so two tickets scoped to the same submodule/package can't run at once (how you keep two sessions off one path-bound app).
 - **Git submodules are handled as separate repos.** Work that lands inside a submodule is committed *inside the submodule* (on a branch) and published before a gitlink bump in the parent points at it. Because superproject worktrees share one submodule git dir, a **submodule-bearing repo resolves to `clone`** (under the default `auto`, or by escalating an explicit `worktree`), so each ticket gets independent submodule state; the clone provisions its submodules at setup (`--recurse-submodules`) and Verify checks `git status` inside each touched submodule. A ticket spanning two submodules stays atomic via a single parent commit that bumps both gitlinks together; its `Scope:` names both, and the same submodule counts as overlapping scope, so two tickets on it serialise. `/trailhead:adopt` detects `.gitmodules` and writes the rule into the conventions.
 - **State lives on the tickets** (claim, labels, comments; all conflict-free); the map body is a re-readable index, not the source of truth. The durable record of a resolution is the ticket's own comment.
-- **Labels are protected from outsiders.** `trailhead:*` labels drive the map, so trailhead trusts a labelled issue only when a write-access collaborator applied the label and (for a ticket) it carries a valid `Parent:`. Anything else is quarantined as `trailhead:unverified`, off the frontier. GitHub already blocks non-write users from labelling; against triage users and automations, trailhead can **install the label guard GitHub Action for you** (from `templates/trailhead-label-guard.yml`) into your repo's `.github/workflows/`, where it strips unauthorized `trailhead:*` labels at the source. Installing a workflow needs a token with the `workflow` scope, so trailhead runs `gh auth refresh -s workflow` if the push is rejected.
-- **Issues opened by others are triaged, not trusted blindly.** `/trailhead:inbox` lists inbound issues (bug reports, requests, questions that aren't yet trailhead tickets) and integrates the worthwhile ones **in place**: reframing them as tickets, keeping the reporter's authorship, and applying the labels on adoption. The rest routes to fog, out-of-scope, duplicate, or needs-info.
+- **Labels are protected from outsiders.** `trailhead:*` labels drive the map, so trailhead trusts a labelled issue only when every `trailhead:*` label on it was applied by a trusted labeller (a write-access collaborator, `github-actions[bot]`, or a login in the `TRAILHEAD_LABEL_ALLOWLIST` repo variable: the same labellers the label guard never strips) and (for a ticket) it carries a valid `Parent:`. Anything else is quarantined as `trailhead:unverified`, off the frontier. GitHub already blocks non-write users from labelling; against triage users and automations, trailhead can **install the label guard GitHub Action for you** (from `templates/trailhead-label-guard.yml`) into your repo's `.github/workflows/`, where it strips unauthorized `trailhead:*` labels at the source. Installing a workflow needs a token with the `workflow` scope, so trailhead runs `gh auth refresh -s workflow` if the push is rejected. For automations (CI, cron, bots) that open tickets without a chat session, `templates/trailhead-capture.js` captures a bug, todo, seed or idea with the full label wiring and refuses to run as an identity the guard would strip, and on GitHub the [`actions/capture`](#capture-from-ci) composite Action wraps it in a few lines of workflow.
+- **Issues opened by others are triaged, not trusted blindly.** `/trailhead:inbox` lists inbound issues (bug reports, requests, questions that aren't yet trailhead tickets) and integrates the worthwhile ones **in place**: reframing them as tickets, keeping the reporter's authorship, and applying the labels on adoption. The rest routes to fog, out-of-scope, duplicate, or needs-info. Quarantined `trailhead:unverified` issues are listed there too, to adopt or reject.
+
+### Capture from CI
+
+`ToRvaLDz/trailhead/actions/capture` is a thin composite Action over the capture helper: every rule (trust, destination, dedupe, secret scan, labels, edge, dashboard) stays in the helper. Pin a release tag (the Action ships from 0.17.0).
+
+```yaml
+permissions:
+  issues: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # ... your build and test steps ...
+      - if: failure()
+        uses: ToRvaLDz/trailhead/actions/capture@v0.17.0
+        with:
+          type: bug
+          title: "CI failed on ${{ github.ref_name }}"
+          body: "Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          dedupe-key: ci-failure-${{ github.job }}
+```
+
+A manual variant works the same way: trigger the job with `workflow_dispatch` and pass `type`, `title` and `body` from `github.event.inputs`.
+
+| Input | Required | Meaning |
+|---|---|---|
+| `type` | yes | `bug`, `todo`, `idea` or `seed` |
+| `title` | yes | issue title |
+| `body` / `body-file` | one of | issue body, or a file path (`-` for stdin); not both |
+| `map` / `of` | no | file under map `<n>`, or inherit the map of origin ticket `<n>` (bug only); exclusive |
+| `trigger` | seed only | the `Trigger:` text |
+| `unverified` | no | `true` adds `trailhead:unverified` (not for `idea`) |
+| `dedupe-key` | no | idempotency key, 1 to 100 characters of `A-Za-z0-9._:-` (no spaces or `/`) |
+| `no-dashboard` | no | `true` skips the whiteboard dashboard refresh |
+| `repo` | no | target `owner/name` (default: this repo) |
+| `token` | no | token for the helper (default: `github.token`) |
+
+Outputs: `issue`, `url` and `status` (`created`, `existing`, `partial`, `error`, `usage`).
+
+- The default token acts as `github-actions[bot]`, which the label guard trusts; the helper verifies it after the create.
+- A re-run with the same `dedupe-key` returns `existing` and creates nothing.
+- `partial` (exit 3, the issue exists but the sub-issue edge failed), `error` and `usage` (exit 2, bad inputs) fail the step; `status` is still set.
+- The runner needs bash, node and gh, all present on GitHub-hosted runners; self-hosted runners must provide them.
 
 ## ✅ Keeping tickets honest
 
 A ticket is one answerable Question, sized to one session, so you never grow it in flight. When new scope surfaces while you're working (testing especially sparks ideas), you decide per idea: small and part of the same Question → just do it; balloons the ticket past one session → **split** it; separate work or a follow-up → **capture** it (`idea`/`todo`/`ticket`/`bug`) and keep going. Extras never become silent lines inside the ticket you're on.
 
+A captured ticket lands where its topic belongs: on the current map when it serves that map's destination, on another open map when it plainly serves that one, and otherwise trailhead asks (every open map, then the whiteboard). While a map is open it never falls back to the whiteboard silently, and it tells you in one line what it opened and where.
+
 Tickets that spin off from other work carry a lineage pointer in their body, so the map stays traceable:
 
 | Pointer | Meaning |
@@ -445,8 +491,8 @@ The **📊 statusline** step offers to install trailhead's Claude Code status ba
 | Key | Values (default **bold**) | Effect |
 |---|---|---|
 | `ticket.language` | an ISO 639-1 code (**`en`**) | the language trailhead **writes** its GitHub prose & commit descriptions in, decoupled from the language it converses in |
-| `models.{plan,execute,research,review,debug,verify,codebase-map}` | a full **versioned** model id (**Balanced-profile default**; `inherit session` is an explicit choice) | which model runs each activity; `plan` and `execute` are always set separately |
-| `models.codex.{plan,execute,research,review,debug,verify,codebase-map}` | an OpenAI model id, or `{model, effort}` (**inherit session**) | the same per-activity split on Codex, independent of `models.*` (Claude ids); re-run the installer to project it into `~/.codex/agents/` |
+| `models.{plan,execute,research,review,debug,verify,codebase-map,grill}` | a full **versioned** model id (**Balanced-profile default**; `inherit session` is an explicit choice) | which model runs each activity; `plan` and `execute` are always set separately |
+| `models.codex.{plan,execute,research,review,debug,verify,codebase-map,grill}` | an OpenAI model id, or `{model, effort}` (**inherit session**) | the same per-activity split on Codex, independent of `models.*` (Claude ids); re-run the installer to project it into `~/.codex/agents/` |
 | `design` | **`disk`** \| `artifacts` \| `stitch` | where UI mockups go: local throwaway HTML, a Design canvas **Artifact** on claude.ai (Claude Code only), or Google Stitch (cross-host, via the Stitch MCP). The legacy `claude.ai/design` value is read as `artifacts` |
 | `design.project` | canvas Artifact URL / Stitch project id | `artifacts` and `stitch` only: the canvas or Stitch project the mockups land on; set at the first UI screen (pick, paste or create), not by hand. A leftover claude.ai/design project is not reused |
 | `design.surface` | **`canvas`** \| `design-system` | `stitch` only: a Stitch project of screens (default) or a shared Stitch design system |
@@ -468,10 +514,11 @@ The **📊 statusline** step offers to install trailhead's Claude Code status ba
 
 - `plan` and `execute` are the build/bug engine's steps. Execute is a subagent too, and it commits to `main`.
 - `research`, `review`, `debug`, `verify` (the goal-backward Verify check), and the codebase-map fan-out each run on their own key.
+- `grill` runs the Grilling rounds on the read-only `trailhead-grill` subagent; unset, it uses the same model as `plan`, and an existing config with no `grill` key simply grills on its `plan` model. The session still asks you each question and keeps the answers.
 
-Choose `plan` and `execute` separately, each by **full versioned id** (never a bare `opus` or `sonnet`). A key left unset uses its Balanced-profile default, and one equal to the session model simply runs inline; set `inherit session` to use the session model.
+Choose `plan` and `execute` separately, each by **full versioned id** (never a bare `opus` or `sonnet`). A key left unset uses its Balanced-profile default, and one equal to the session model simply runs inline; set `inherit session` to use the session model. On Codex, an unset `models.codex.grill` follows `models.codex.plan` when that is pinned (re-run the installer to project it), else inherits the session model; a pin equal to the session model runs inline. A profile never writes a `grill` entry, so it keeps following `plan`.
 
-The **main session stays the orchestrator**. It holds the interactive moments (a build's Discuss, and Verify's acceptance/UAT) and it does charting, grilling, and ticket-writing on its own model. No key governs ticket quality, so run charting sessions on your strong model.
+The **main session stays the orchestrator**. It holds the interactive moments (a build's Discuss, and Verify's acceptance/UAT) and it does charting and ticket-writing on its own model; for grilling it relays each question from `trailhead-grill` and asks you itself. No key governs ticket quality, so run charting sessions on your strong model.
 
 Example config file (the same shape works for the project `.trailhead/config.json` and the global `trailhead/config.json` in your config directory):
 

package/bin/capture-action.test.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// Test for #334: the composite Action actions/capture is a thin wrapper over the capture
+// helper. Checks the input/output mirror, injection safety, the run block against a stub
+// helper, and the docs. Plain asserts, no framework, no YAML dependency.
+// Run: node bin/capture-action.test.js
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = path.resolve(__dirname, '..');
+const actionPath = path.join(root, 'actions', 'capture', 'action.yml');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const eq = (name, a, b) => { assert.deepStrictEqual(a, b, name); passed++; };
+const EMDASH = String.fromCharCode(0x2014);
+
+const yml = fs.readFileSync(actionPath, 'utf8');
+const lines = yml.split('\n');
+
+// Top-level keys under a section (2-space indented names) of the minimal YAML.
+function sectionKeys(name) {
+  const i = lines.findIndex((l) => l === `${name}:`);
+  ok(`action.yml has a ${name}: section`, i >= 0);
+  const keys = [];
+  for (let j = i + 1; j < lines.length; j++) {
+    if (lines[j] !== '' && !lines[j].startsWith(' ')) break;
+    const m = /^ {2}([A-Za-z0-9_-]+):/.exec(lines[j]);
+    if (m) keys.push(m[1]);
+  }
+  return keys;
+}
+
+// Mirror
+eq('inputs mirror the helper flags plus token',
+  sectionKeys('inputs').sort(),
+  ['body', 'body-file', 'dedupe-key', 'map', 'no-dashboard', 'of', 'repo', 'title', 'token', 'trigger', 'type', 'unverified']);
+eq('outputs are issue, url, status', sectionKeys('outputs').sort(), ['issue', 'status', 'url']);
+for (const name of ['issue', 'url', 'status']) {
+  ok(`output ${name} reads the capture step`, yml.includes(`value: \${{ steps.capture.outputs.${name} }}`));
+}
+ok('composite action', /^ {2}using: composite$/m.test(yml));
+ok('the step has id: capture', /^ {4}- id: capture$/m.test(yml));
+ok('description notes issues: write', /issues: write/.test(yml.split('\ninputs:')[0]));
+ok('branding present', /^branding:/m.test(yml));
+
+// Extract the literal run block (fixed indentation: `run: |` then 8-space lines).
+const runIdx = lines.findIndex((l) => /^ {6}run: \|$/.test(l));
+assert.ok(runIdx >= 0, 'run: | literal block not found in action.yml');
+const runLines = [];
+for (let j = runIdx + 1; j < lines.length; j++) {
+  if (lines[j] === '') { runLines.push(''); continue; }
+  if (!lines[j].startsWith('        ')) break;
+  runLines.push(lines[j].slice(8));
+}
+const script = runLines.join('\n');
+ok('run block is non-empty', script.trim().length > 0);
+
+// Injection safety
+ok('no ${{ expression inside the run script', !script.includes('${{'));
+ok('inputs reach the script through env:', /^ {6}env:$/m.test(yml) && /INPUT_BODY: \$\{\{ inputs\.body \}\}/.test(yml));
+
+// Runtime against a stub helper
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'capture-action-'));
+const actionDir = path.join(tmp, 'actions', 'capture');
+const tplDir = path.join(tmp, 'plugins', 'trailhead', 'templates');
+fs.mkdirSync(actionDir, { recursive: true });
+fs.mkdirSync(tplDir, { recursive: true });
+fs.writeFileSync(path.join(tmp, 'run.sh'), script);
+fs.writeFileSync(path.join(tplDir, 'trailhead-capture.js'), `
+const fs = require('fs');
+fs.writeFileSync(process.env.STUB_ARGV_FILE, JSON.stringify({ argv: process.argv.slice(2), token: process.env.GH_TOKEN || null }));
+if (process.env.STUB_RAW !== undefined) process.stdout.write(process.env.STUB_RAW);
+else console.log(process.env.STUB_JSON || '{"status":"created","issue":7,"url":"https://github.com/o/r/issues/7"}');
+process.exit(Number(process.env.STUB_EXIT || 0));
+`);
+
+const baseInputs = { INPUT_TYPE: 'bug', INPUT_TITLE: 'T', INPUT_REPO: 'o/r', INPUT_TOKEN: 'tok' };
+function run(inputs, stub = {}) {
+  const out = path.join(tmp, 'output.txt');
+  const argvFile = path.join(tmp, 'argv.json');
+  fs.rmSync(out, { force: true });
+  fs.rmSync(argvFile, { force: true });
+  const env = {
+    PATH: process.env.PATH,
+    GITHUB_ACTION_PATH: actionDir,
+    GITHUB_OUTPUT: out,
+    STUB_ARGV_FILE: argvFile,
+    GH_TOKEN: inputs.INPUT_TOKEN || '',
+    ...inputs,
+    ...stub,
+  };
+  const r = spawnSync('bash', ['--noprofile', '--norc', '-eo', 'pipefail', path.join(tmp, 'run.sh')], { env, encoding: 'utf8' });
+  const outputs = {};
+  if (fs.existsSync(out)) {
+    for (const l of fs.readFileSync(out, 'utf8').split('\n')) {
+      const m = /^([a-z]+)=(.*)$/.exec(l);
+      if (m) outputs[m[1]] = m[2];
+    }
+  }
+  const seen = fs.existsSync(argvFile) ? JSON.parse(fs.readFileSync(argvFile, 'utf8')) : null;
+  return { status: r.status, outputs, seen, stderr: r.stderr };
+}
+
+let r = run(baseInputs);
+eq('minimal argv: empty optionals omitted', r.seen.argv, ['--type', 'bug', '--title', 'T', '--repo', 'o/r']);
+eq('exit 0 on created', r.status, 0);
+eq('outputs from the JSON line', r.outputs, { issue: '7', url: 'https://github.com/o/r/issues/7', status: 'created' });
+eq('GH_TOKEN reaches the helper', r.seen.token, 'tok');
+
+r = run({ ...baseInputs, INPUT_BODY: 'a\nb "c" $HOME\n', INPUT_BODY_FILE: 'f.md', INPUT_MAP: '5', INPUT_OF: '9', INPUT_TRIGGER: 'x y',
+  INPUT_UNVERIFIED: 'true', INPUT_DEDUPE_KEY: 'k1', INPUT_NO_DASHBOARD: 'true' });
+eq('full argv maps 1:1, multi-line body intact, booleans bare',
+  r.seen.argv,
+  ['--type', 'bug', '--title', 'T', '--body', 'a\nb "c" $HOME\n', '--body-file', 'f.md', '--repo', 'o/r', '--map', '5', '--of', '9',
+    '--trigger', 'x y', '--unverified', '--dedupe-key', 'k1', '--no-dashboard']);
+
+r = run({ ...baseInputs, INPUT_UNVERIFIED: 'false', INPUT_NO_DASHBOARD: '' });
+ok('false/empty booleans are absent', !r.seen.argv.includes('--unverified') && !r.seen.argv.includes('--no-dashboard'));
+
+r = run(baseInputs, { STUB_JSON: '{"status":"existing"}' });
+eq('status only when JSON lacks issue/url', r.outputs, { issue: '', url: '', status: 'existing' });
+eq('existing exits 0', r.status, 0);
+
+for (const code of [3, 1, 2]) {
+  r = run(baseInputs, { STUB_EXIT: String(code), STUB_JSON: `{"status":"x${code}","issue":4,"url":"u"}` });
+  eq(`helper exit ${code} propagates`, r.status, code);
+  eq(`status still written on exit ${code}`, r.outputs.status, `x${code}`);
+}
+
+for (const [label, raw] of [['malformed', 'not json\n'], ['empty', '']]) {
+  r = run(baseInputs, { STUB_RAW: raw, STUB_EXIT: '3' });
+  eq(`${label} stdout never masks exit 3`, r.status, 3);
+  eq(`${label} stdout leaves outputs empty`, { issue: r.outputs.issue || '', url: r.outputs.url || '', status: r.outputs.status || '' }, { issue: '', url: '', status: '' });
+  r = run(baseInputs, { STUB_RAW: raw, STUB_EXIT: '0' });
+  eq(`${label} stdout with exit 0 exits 1`, r.status, 1);
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+
+// Docs
+const readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+const readmeIt = fs.readFileSync(path.join(root, 'README.it.md'), 'utf8');
+for (const [name, doc] of [['README.md', readme], ['README.it.md', readmeIt]]) {
+  ok(`${name} names the Action`, doc.includes('ToRvaLDz/trailhead/actions/capture@'));
+  ok(`${name} names issues: write`, doc.includes('issues: write'));
+  ok(`${name} names dedupe-key`, doc.includes('dedupe-key'));
+}
+const capDoc = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'skills', 'trailhead-capture', 'references', 'capture.md'), 'utf8');
+ok('capture.md names the Action', capDoc.includes('actions/capture'));
+for (const [name, text] of [['action.yml', yml], ['README.md', readme], ['README.it.md', readmeIt], ['capture.md', capDoc], ['test', fs.readFileSync(__filename, 'utf8').replace(/String\.fromCharCode\(0x2014\)/g, '')]]) {
+  ok(`no em-dash in ${name}`, !text.includes(EMDASH));
+}
+ok('real helper path used by the run block exists',
+  fs.existsSync(path.join(root, 'actions/capture', '../../plugins/trailhead/templates/trailhead-capture.js')));
+for (const [name, doc] of [['README.md', readme], ['README.it.md', readmeIt]]) {
+  const keys = [...doc.matchAll(/^\s*dedupe-key: (.+)$/gm)].map((m) => m[1]);
+  ok(`${name} has a dedupe-key example`, keys.length > 0);
+  for (const k of keys) {
+    ok(`${name} dedupe-key example avoids unsafe contexts`, !/github\.(ref_name|workflow|head_ref|ref)\b/.test(k));
+    // job ids are [A-Za-z0-9_-]; run_id and run_number are digits
+    const resolved = k.replace(/\$\{\{\s*github\.(job|run_id|run_number)\s*\}\}/g, 'x1');
+    ok(`${name} dedupe-key example matches the helper regex`, /^[A-Za-z0-9._:-]{1,100}$/.test(resolved));
+  }
+}
+console.log(`capture-action.test.js: ${passed} checks passed`);

package/bin/capture-docs.test.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Docs test for #332: capture.md documents the scripted capture helper (CLI, statuses,
+// exit codes, trust, idea as fog, dedupe, dashboard). Plain asserts, no framework.
+// Run: node bin/capture-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const doc = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'skills', 'trailhead-capture', 'references', 'capture.md'), 'utf8');
+const start = doc.indexOf('## Scripted capture for automations');
+const section = start < 0 ? '' : doc.slice(start);
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+ok('capture.md has the scripted capture section', section !== '');
+ok('names the helper', section.includes('trailhead-capture.js'));
+for (const flag of ['--type', '--title', '--body-file', '--repo', '--map', '--of', '--trigger', '--unverified', '--dedupe-key', '--no-dashboard']) {
+  ok(`names ${flag}`, section.includes(flag));
+}
+for (const status of ['created', 'existing', 'partial', 'error', 'usage']) {
+  ok(`documents status ${status}`, section.includes(`"status":"${status}"`));
+}
+ok('documents exit codes 0, 1, 2 and 3', ['exit 0', 'exit 1', 'exit 2', 'exit 3'].every((c) => section.includes(c)));
+ok('partial names prune', /partial[^]*\/trailhead:prune/.test(section));
+ok('trust: allowlist is the repo variable, not the local env', section.includes('TRAILHEAD_LABEL_ALLOWLIST') && /never consults its local environment/.test(section));
+ok('trust: installation tokens are verified post-create', section.includes('github-actions[bot]'));
+ok('idea is parked fog', /`idea` is parked fog/.test(section) && section.includes('`trailhead:fog`'));
+ok('dedupe: marker, cap fallback and the lag residual', section.includes('trailhead-dedupe') && section.includes('1000-result cap') && /search-index lag/.test(section));
+ok('dashboard rule: whiteboard only, update-only', /whiteboard ticket refreshes the dashboard/.test(section) && section.includes('--update-only'));
+ok('no em-dash', !doc.includes(String.fromCharCode(0x2014)));
+console.log(`capture-docs.test.js: ${passed} checks passed`);