[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DBPCXNP13VHR84ZT8JYAQ3":3,"skill-same:01M7DBPCXNP13VHR84ZT8JYAQ3":46},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7DBPCXNP13VHR84ZT8JYAQ3","pi-artifacts-reports",null,"Create self-contained HTML analysis reports with the pi-artifacts house templates: a combined narrative-first report with synchronized evidence on demand, or standalone narrative and detailed reports. Use only for a deep technical audit whose readable explanation must link to detailed findings. For other deliverables, choose a format with the pi-artifacts-authoring skill (Markdown by default).","CenterForAgenticAI\u002Ftools","CenterForAgenticAI","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F250424195?v=4","01M7DBNBBRNZ6NT6WYSEPYK811","CAAIR","01M7DBNBCBH3B7HHWP0ACQW3F7",0,"MIT","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-artifacts\u002Fskills\u002Fpi-artifacts-reports\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: pi-artifacts-reports\ndescription: >\n  Create self-contained HTML analysis reports with the pi-artifacts house templates: a combined\n  narrative-first report with synchronized evidence on demand, or standalone narrative and detailed\n  reports. Use only for a deep technical audit whose readable explanation must link to detailed\n  findings. For other deliverables, choose a format with the pi-artifacts-authoring skill (Markdown\n  by default).\n---\n\n# pi-artifacts narrative-first reports\n\nThis is a specialized format, not the default output. Start with the **`pi-artifacts-authoring`**\nskill: most recommendations, experiment reports, runbooks, handoffs, and verification records are\nclearer as short Markdown. Use these templates only for a deep technical audit with two valid\nreading modes:\n\n1. a **narrative** that explains the result as a coherent story;\n2. **evidence** with the complete raw observations, tables, code, uncertainty, and severity.\n\nWhen both are needed, prefer the combined kind. It embeds both in one artifact. It opens narrative-first and reveals evidence on\ndemand. This is more reliable than a generated pair because separately registered artifacts do not\nshare sibling paths: their relative `companionHref` links can return 404. Use standalone\n`narrative` or `detailed` kinds only when one reading mode genuinely stands alone. Do not add an\nevidence layer to a brief answer or duplicate raw data merely to justify the format.\n\n## What each report owns\n\n### Narrative layer\n\nWrite for a person who wants the conclusion, the sequence of events, and the consequences.\n\n- Lead with the situation and why it matters.\n- Connect evidence in prose instead of copying tables.\n- Explain technical terms on first use.\n- End with decisions, consequences, or next steps.\n- Keep paragraphs short enough to hear comfortably.\n- Map each section to relevant evidence when verification material exists.\n\n### Optional audio reader\n\nGenerated reports have **no audio by default**. Set `\"audio\": true` in narrative or combined metadata\nonly when a reader has asked to listen. The flag is rejected for detailed reports and must be a\nboolean. Regenerating is the only way to change an existing report; stored artifact versions keep\ntheir bytes, including any player they already embed.\n\nWhen enabled, the report embeds the dependency-free Web Speech API reader. It provides whole-report\nplayback, per-section playback, read-from-here controls, pause\u002Fresume\u002Fstop, rate and voice choices,\nprogress, follow-along highlighting, reduced-motion-aware scrolling, keyboard help, and a polite live\nstatus. It creates no player when speech synthesis is unavailable.\n\nThe player is dismissible. **Hide** collapses it to a small **Listen** pill in the same corner, and\n`Alt+Shift+L` toggles it from anywhere outside a text field. The choice persists across reports and\nreloads, so a reader who never wants the player sees it once. Hiding never stops playback: the\ncollapsed pill reports `Listening` or `Paused`, and the live status region stays outside the\ncollapsed panel so a hidden player can still announce.\n\nThe evidence pane is independent of this player and works when audio is off or the Web Speech API is\nabsent.\nIt has three opening affordances: a mapped section's **Evidence** button, the header's global\n**Evidence** toggle, and `Alt+Shift+E` outside text-entry controls. The shortcut hint also appears in\nthe evidence header, not only in audio help. The pane starts `hidden` on every page load, so it is\noutside the accessibility tree and tab order. Unlike the audio-reader panel, its open state and\nfollow state are never written to browser storage.\n\nOpening moves focus to the pane. Closing returns focus to the exact opening control. Wide screens\nshow a fixed two-pane split; below 62rem, evidence replaces the narrative and **Back to the\nnarrative** restores both narrative scroll position and focus. The evidence pane has its own complete\ntable of contents. When a narrative section maps to multiple targets, it also shows links to the\nremaining related evidence.\n\n**Follow narrative** starts on. While it remains on, narrative scrolling synchronizes the evidence\npane to the visible mapped section's first target. A manual evidence scroll or an evidence table-of-\ncontents choice turns follow off and announces that change through a polite live region. Leave the\nvisible follow control available so the reader can resume synchronization. Opening or closing\nevidence must not stop, pause, restart, or otherwise change audio playback.\n\n### Evidence layer\n\nKeep the evidence complete and easy to inspect.\n\n- Preserve raw analysis, source excerpts, commands, output, and uncertainty.\n- Put wide tables inside `\u003Cdiv class=\"report-table-wrap\">`.\n- Give every table a `\u003Ccaption>` and use `\u003Cth scope=\"col\">` or `\u003Cth scope=\"row\">`.\n- Use `\u003Cpre>\u003Ccode>` for code and command output.\n- Use `.severity` with `.severity-critical`, `.severity-high`, `.severity-medium`,\n  `.severity-low`, or `.severity-note` where a compact severity label helps.\n- Keep evidence section IDs stable so narrative mappings remain valid.\n\n## Source files\n\nThe package owns these stable inputs:\n\n```text\ntemplates\u002Freport\u002F\n├── combined-template.html\n├── narrative-template.html\n├── detailed-template.html\n├── report-evidence.js\n├── report-gl-refs.js\n├── report-reader.css\n└── report-reader.js\n```\n\nDo not copy these assets into another project and edit them there. Use the generator so the output\ncontains the current versioned CSS and, when audio is enabled, the reader runtime.\n\nAuthor each body as an HTML fragment, not a complete document:\n\n```html\n\u003Cp>Optional opening context.\u003C\u002Fp>\n\n\u003Csection id=\"situation\">\n  \u003Ch2>The situation\u003C\u002Fh2>\n  \u003Cp>Story-form analysis…\u003C\u002Fp>\n\u003C\u002Fsection>\n\n\u003Csection id=\"consequence\">\n  \u003Ch2>What it means\u003C\u002Fh2>\n  \u003Cp>Consequence and next step…\u003C\u002Fp>\n\u003C\u002Fsection>\n```\n\nEvery section needs a unique, quoted `id` and a non-empty heading. IDs must also be unique across the\ntwo fragments in a combined report. The generator uses narrative IDs for the primary table of\ncontents and, when audio is enabled, section playback; evidence IDs go only into the evidence pane's\ntable of contents.\n\nCreate combined metadata with an `evidenceMap`. Every key must name a narrative `\u003Csection id>` and\nevery array value must name one or more evidence `\u003Csection id>` values. Omit a narrative section when\nit has no evidence affordance.\n\n```json\n{\n  \"title\": \"Analysis title\",\n  \"deck\": \"One-sentence description of this report.\",\n  \"date\": \"2026-08-05\",\n  \"provenance\": \"Agent analysis of repository state at commit abc1234\",\n  \"language\": \"en\",\n  \"audio\": false,\n  \"evidenceMap\": {\n    \"situation\": [\"event-log\", \"runtime-audit\"],\n    \"consequence\": [\"findings-register\"]\n  }\n}\n```\n\nThe generator fails closed when a map key or target is unknown and names both the bad ID and the\nfragment where it was expected. Do not add `companionHref` to combined metadata. If supplied, it is\nignored with a warning because evidence already lives in the same artifact.\n\n## Generate the combined report\n\nRun from the pi-artifacts repository:\n\n```bash\nnode scripts\u002Fmake-report.mjs \\\n  --kind combined \\\n  --body path\u002Fto\u002Fanalysis-narrative-body.html \\\n  --evidence path\u002Fto\u002Fanalysis-evidence-body.html \\\n  --meta path\u002Fto\u002Fanalysis-combined-meta.json \\\n  --references path\u002Fto\u002Fgl-references.json \\\n  --out path\u002Fto\u002Fanalysis.html\n```\n\nOmit `--references` only when the report has no GitLab references. The reference manifest is a\ncommitted build input, not a runtime cache:\n\n```json\n{\n  \"defaultProject\": \"group\u002Fproject\",\n  \"references\": {\n    \"#123\": {\n      \"kind\": \"issue\",\n      \"iid\": 123,\n      \"title\": \"Make report citations self-contained\",\n      \"state\": \"opened\",\n      \"url\": \"https:\u002F\u002Fgitlab.example\u002Fgroup\u002Fproject\u002F-\u002Fwork_items\u002F123\"\n    }\n  }\n}\n```\n\nUse these authoring forms:\n\n- `#123` for a same-project issue;\n- `!7` for a same-project merge request;\n- `group\u002Fproject!7` for a cross-project merge request;\n- `@abcdef1` for a commit;\n- `\u003Ca data-gl-ref=\"#123\">\u003C\u002Fa>` for an explicit reference whose visible text should be the token;\n- `\u003Ca data-gl-ref=\"#123\">the tracking issue\u003C\u002Fa>` to preserve custom visible text.\n\nThe generator also upgrades an existing anchor when its `href` matches a manifest URL. It treats\n`\u002F-\u002Fissues\u002F123` and `\u002F-\u002Fwork_items\u002F123` as the same target and keeps the authored link text. It\nwalks parsed text nodes to link known bare `#NNN` tokens in prose. It never changes text inside\n`code`, `pre`, `kbd`, or an existing anchor. Do not hand-edit code or command evidence to work\naround linking.\n\nAny GitLab-form token missing from the manifest stops generation and names the token and fragment\nfile, including bare `#NNN` prose outside the exclusion contexts. This is deliberate: add the correct\nsame-project entry or an explicit cross-project anchor instead of publishing a reference whose title\nand state were not baked in. Each generated anchor's accessible name contains kind, number, title,\nand state. Open, closed, and merged states\nalso use different inline SVG shapes, so color is not the only cue. The visual tooltip is\n`aria-hidden`. Never add `aria-describedby` alongside the complete `aria-label`; that would announce\nthe same information twice. With JavaScript disabled, `title` supplies a native fallback. With\nJavaScript enabled, the enhancement removes `title`, uses a fixed viewport-positioned tooltip that\ncannot be clipped by the evidence or table scrollers, and dismisses it on blur or Escape.\n\nBuild or refresh a manifest before report generation when references change:\n\n```bash\nnode scripts\u002Fgl-refs.mjs \\\n  --project group\u002Fproject \\\n  --out path\u002Fto\u002Fgl-references.json \\\n  path\u002Fto\u002Fnarrative-body.html path\u002Fto\u002Fevidence-body.html\n\nnode scripts\u002Fgl-refs.mjs \\\n  --project group\u002Fproject \\\n  --out path\u002Fto\u002Fgl-references.json \\\n  --refresh \\\n  path\u002Fto\u002Fnarrative-body.html path\u002Fto\u002Fevidence-body.html\n```\n\nThe helper authenticates `glab` first, bulk-loads both open and closed items with `--all`, and falls\nback to `glab issue view \u003Ciid>` when an issue or work-item type is absent from list output. It merges\nonly after every requested lookup succeeds and writes atomically. An authentication or lookup\nfailure leaves the prior manifest unchanged. Never refetch during a deterministic report build.\n\nMetadata can instead be passed with `--title`, `--deck`, `--date`, `--provenance`, `--language`,\n`--companion`, and `--companion-label`. The companion flags apply only to standalone narrative and\ndetailed reports. Command-line values override the metadata file. Run `node scripts\u002Fmake-report.mjs\n--help` for the compact reference.\n\nThe generator calculates reading time, builds the table of contents, escapes metadata, expands\nmanifest-backed references, and inlines the shared CSS and JavaScript. No runtime uses an external\nscript. Treat\ngenerated HTML as build output: revise the body or metadata, then regenerate instead of hand-editing\nthe final file.\n\nFor standalone output, keep using `--kind narrative` or `--kind detailed` with the existing\n`companionHref` metadata. See `examples\u002Freports\u002F` for all three generated forms. Regenerate them with:\n\n```bash\nnpm run reports:example\n```\n\n## Self-contained rule\n\nEach final report must work as one HTML file without the artifacts daemon or a network connection.\n\n- Never load a CDN, remote script, stylesheet, web font, image, audio file, video, or iframe.\n- Do not rely on an external URL for rendering, layout, playback, or meaning.\n- Inline small images as `data:` URLs or use authored inline SVG.\n- Keep source citations readable in the document itself. A citation link may be useful online, but\n  its label and surrounding text must still identify the source offline.\n- For a deep audit with linked prose and findings, use one combined artifact so registration cannot\n  break a relative sibling link.\n\nThe generator rejects body scripts, remote CSS resources, non-inline resource attributes, and\nexternal companion links. It runs the same self-containment check over both combined fragments and\nthe final HTML. Ordinary source links do not make the report dependent on the network. The\ngenerator gives every `http(s)` link `target=\"_blank\"` and adds `noopener noreferrer` to its `rel`,\nbecause most sites refuse to load inside the viewer frame. An authored `target` is kept.\n\n## Accessibility checklist\n\nBefore registering a report, confirm:\n\n- [ ] One `\u003Ch1>` comes from metadata; section headings begin at `\u003Ch2>` and do not skip levels.\n- [ ] Every top-level section has a stable, unique `id`.\n- [ ] Link text explains its destination without relying on “click here.”\n- [ ] Images have useful `alt` text; decorative images use empty `alt=\"\"`.\n- [ ] Tables have captions, scoped headers, and no layout-only cells.\n- [ ] Color is not the only way severity or status is communicated.\n- [ ] Every generated GitLab reference names its kind, number, title, and state; its tooltip is\n      `aria-hidden` and the anchor has no `aria-describedby`.\n- [ ] Bare issue tokens remain literal inside `code`, `pre`, `kbd`, and authored links.\n- [ ] The narrative makes sense as plain text and contains no instruction that depends only on\n      visual position.\n- [ ] Content remains normal semantic DOM text. Never add `aria-hidden` to report content to make\n      the audio reader easier to implement.\n- [ ] Evidence starts with the `hidden` attribute, enters the accessibility tree only when opened,\n      and contains no audio section buttons.\n- [ ] Opening evidence moves focus into its pane. Closing restores focus to the opener; narrow mode\n      also restores narrative scroll position.\n- [ ] Manual evidence scrolling and evidence table-of-contents choices turn follow off and announce\n      the change through a polite live region.\n- [ ] Audio is omitted unless a reader asked for it (`\"audio\": true`). When present, it does not\n      autoplay; playback starts only after a person activates a control.\n- [ ] Every authored interactive control has an accessible name and works from the keyboard.\n- [ ] At 200% zoom, content remains readable without horizontal scrolling except inside deliberate\n      table and code scrollers.\n- [ ] Print preview has readable contrast and does not include the floating audio controls.\n- [ ] Light and dark system themes both remain legible.\n\nThe browser reader supplements real screen readers. It does not replace normal headings, landmarks,\nlink text, table semantics, or alternative text.\n\n## Browser verification\n\nAlways open a generated combined report with default metadata in a current Chromium or Safari\nbrowser and verify:\n\n1. No audio player, **Listen** pill, **Read this section** button, empty reader script wrapper, or\n   claim that audio is present appears.\n2. The initial view is narrative-only; evidence is absent from the accessibility tree and tab order.\n3. Every mapped section has one **Evidence** button with the section title in its accessible name;\n   unmapped sections have no evidence button.\n4. Section buttons open the first mapped target and move focus to the pane. The global toggle uses\n   the visible mapped narrative section, then falls back to the first evidence section.\n5. Narrative scrolling follows mapped targets. A manual evidence scroll and an evidence table-of-\n   contents choice each turn follow off and produce a polite announcement; the follow control\n   resumes synchronization.\n6. Closing returns focus to the opening control. Below 62rem, **Back to the narrative** restores\n   narrative scroll and focus; at or above 62rem, both panes remain visible.\n7. A GitLab reference tooltip opens on hover and keyboard focus, closes on blur and Escape, flips\n   near viewport edges, and remains visible inside the evidence pane or a wide table scroller. The\n   native browser tooltip does not also appear.\n8. Print preview contains the narrative followed by every evidence section, with evidence controls\n   omitted.\n\nWhen `\"audio\": true` is set on either a standalone narrative or combined report, additionally verify:\n\n1. **Play** reads the title, description, and body. Pause, Resume, and Stop update state correctly.\n2. **Read this section** stops current speech and reads only that section. **Read from here** reads\n   that section and every later section.\n3. Rate and voice choices survive a reload when storage is available, including when the browser\n   loads voices after the page.\n4. Progress advances and the current passage is highlighted. Browsers without speech boundary\n   events still highlight the current paragraph.\n5. Follow-along scrolling becomes immediate, not smooth, when reduced motion is enabled.\n6. The Help dialog documents `Alt+Shift+Space`, `Alt+Shift+S`, `Alt+Shift+H`, and `Alt+Shift+L`.\n7. Navigating away cancels speech. With speech synthesis unavailable, no player or section audio\n   buttons appear.\n8. **Hide** collapses the player to the `Listen` pill, moves focus to it, and persists the choice;\n   the pill restores the panel and returns focus to **Play**. Hiding during playback keeps audio\n   running and reports the transport state.\n9. Print preview omits the reader controls.\n\nFor an audio-enabled combined report, also verify that opening, browsing, and closing evidence do\nnot change playback. These evidence checks do not apply to a standalone narrative report.\n\nVoice availability and boundary events depend on the browser and operating system. Do not promise a\nspecific installed voice or word-level boundary behavior.\n\n## Validate and register\n\nRun the repository checks after changing the template, helper, or source examples:\n\n```bash\nnpm run check\n```\n\nThen register the one generated combined file as an artifact and return its viewer URL. Keep the\nsource bodies and metadata in the producing project when the report may be regenerated later.\n","# pi-artifacts narrative-first reports\n\nThis is a specialized format, not the default output. Start with the **`pi-artifacts-authoring`**\nskill: most recommendations, experiment reports, runbooks, handoffs, and verification records are\nclearer as short Markdown. Use these templates only for a deep technical audit with two valid\nreading modes:\n\n1. a **narrative** that explains the result as a coherent story;\n2. **evidence** with the complete raw observations, tables, code, uncertainty, and severity.\n\nWhen both are needed, prefer the combined kind. It embeds both in one artifact. It opens narrative-first and reveals evidence on\ndemand. This is more reliable than a generated pair because separately registered artifacts do not\nshare sibling paths: their relative `companionHref` links can return 404. Use standalone\n`narrative` or `detailed` kinds only when one reading mode genuinely stands alone. Do not add an\nevidence layer to a brief answer or duplicate raw data merely to justify the format.\n\n## What each report owns\n\n### Narrative layer\n\nWrite for a person who wants the conclusion, the sequence of events, and the consequences.\n\n- Lead with the situation and why it matters.\n- Connect evidence in prose instead of copying tables.\n- Explain technical terms on first use.\n- End with decisions, consequences, or next steps.\n- Keep paragraphs short enough to hear comfortably.\n- Map each section to relevant evidence when verification material exists.\n\n### Optional audio reader\n\nGenerated reports have **no audio by default**. Set `\"audio\": true` in narrative or combined metadata\nonly when a reader has asked to listen. The flag is rejected for detailed reports and must be a\nboolean. Regenerating is the only way to change an existing report; stored artifact versions keep\ntheir bytes, including any player they already embed.\n\nWhen enabled, the report embeds the dependency-free Web Speech API reader. It provides whole-report\nplayback, per-section playback, read-from-here controls, pause\u002Fresume\u002Fstop, rate and voice choices,\nprogress, follow-along highlighting, reduced-motion-aware scrolling, keyboard help, and a polite live\nstatus. It creates no player when speech synthesis is unavailable.\n\nThe player is dismissible. **Hide** collapses it to a small **Listen** pill in the same corner, and\n`Alt+Shift+L` toggles it from anywhere outside a text field. The choice persists across reports and\nreloads, so a reader who never wants the player sees it once. Hiding never stops playback: the\ncollapsed pill reports `Listening` or `Paused`, and the live status region stays outside the\ncollapsed panel so a hidden player can still announce.\n\nThe evidence pane is independent of this player and works when audio is off or the Web Speech API is\nabsent.\nIt has three opening affordances: a mapped section's **Evidence** button, the header's global\n**Evidence** toggle, and `Alt+Shift+E` outside text-entry controls. The shortcut hint also appears in\nthe evidence header, not only in audio help. The pane starts `hidden` on every page load, so it is\noutside the accessibility tree and tab order. Unlike the audio-reader panel, its open state and\nfollow state are never written to browser storage.\n\nOpening moves focus to the pane. Closing returns focus to the exact opening control. Wide screens\nshow a fixed two-pane split; below 62rem, evidence replaces the narrative and **Back to the\nnarrative** restores both narrative scroll position and focus. The evidence pane has its own complete\ntable of contents. When a narrative section maps to multiple targets, it also shows links to the\nremaining related evidence.\n\n**Follow narrative** starts on. While it remains on, narrative scrolling synchronizes the evidence\npane to the visible mapped section's first target. A manual evidence scroll or an evidence table-of-\ncontents choice turns follow off and announces that change through a polite live region. Leave the\nvisible follow control available so the reader can resume synchronization. Opening or closing\nevidence must not stop, pause, restart, or otherwise change audio playback.\n\n### Evidence layer\n\nKeep the evidence complete and easy to inspect.\n\n- Preserve raw analysis, source excerpts, commands, output, and uncertainty.\n- Put wide tables inside `\u003Cdiv class=\"report-table-wrap\">`.\n- Give every table a `\u003Ccaption>` and use `\u003Cth scope=\"col\">` or `\u003Cth scope=\"row\">`.\n- Use `\u003Cpre>\u003Ccode>` for code and command output.\n- Use `.severity` with `.severity-critical`, `.severity-high`, `.severity-medium`,\n  `.severity-low`, or `.severity-note` where a compact severity label helps.\n- Keep evidence section IDs stable so narrative mappings remain valid.\n\n## Source files\n\nThe package owns these stable inputs:\n\n```text\ntemplates\u002Freport\u002F\n├── combined-template.html\n├── narrative-template.html\n├── detailed-template.html\n├── report-evidence.js\n├── report-gl-refs.js\n├── report-reader.css\n└── report-reader.js\n```\n\nDo not copy these assets into another project and edit them there. Use the generator so the output\ncontains the current versioned CSS and, when audio is enabled, the reader runtime.\n\nAuthor each body as an HTML fragment, not a complete document:\n\n```html\n\u003Cp>Optional opening context.\u003C\u002Fp>\n\n\u003Csection id=\"situation\">\n  \u003Ch2>The situation\u003C\u002Fh2>\n  \u003Cp>Story-form analysis…\u003C\u002Fp>\n\u003C\u002Fsection>\n\n\u003Csection id=\"consequence\">\n  \u003Ch2>What it means\u003C\u002Fh2>\n  \u003Cp>Consequence and next step…\u003C\u002Fp>\n\u003C\u002Fsection>\n```\n\nEvery section needs a unique, quoted `id` and a non-empty heading. IDs must also be unique across the\ntwo fragments in a combined report. The generator uses narrative IDs for the primary table of\ncontents and, when audio is enabled, section playback; evidence IDs go only into the evidence pane's\ntable of contents.\n\nCreate combined metadata with an `evidenceMap`. Every key must name a narrative `\u003Csection id>` and\nevery array value must name one or more evidence `\u003Csection id>` values. Omit a narrative section when\nit has no evidence affordance.\n\n```json\n{\n  \"title\": \"Analysis title\",\n  \"deck\": \"One-sentence description of this report.\",\n  \"date\": \"2026-08-05\",\n  \"provenance\": \"Agent analysis of repository state at commit abc1234\",\n  \"language\": \"en\",\n  \"audio\": false,\n  \"evidenceMap\": {\n    \"situation\": [\"event-log\", \"runtime-audit\"],\n    \"consequence\": [\"findings-register\"]\n  }\n}\n```\n\nThe generator fails closed when a map key or target is unknown and names both the bad ID and the\nfragment where it was expected. Do not add `companionHref` to combined metadata. If supplied, it is\nignored with a warning because evidence already lives in the same artifact.\n\n## Generate the combined report\n\nRun from the pi-artifacts repository:\n\n```bash\nnode scripts\u002Fmake-report.mjs \\\n  --kind combined \\\n  --body path\u002Fto\u002Fanalysis-narrative-body.html \\\n  --evidence path\u002Fto\u002Fanalysis-evidence-body.html \\\n  --meta path\u002Fto\u002Fanalysis-combined-meta.json \\\n  --references path\u002Fto\u002Fgl-references.json \\\n  --out path\u002Fto\u002Fanalysis.html\n```\n\nOmit `--references` only when the report has no GitLab references. The reference manifest is a\ncommitted build input, not a runtime cache:\n\n```json\n{\n  \"defaultProject\": \"group\u002Fproject\",\n  \"references\": {\n    \"#123\": {\n      \"kind\": \"issue\",\n      \"iid\": 123,\n      \"title\": \"Make report citations self-contained\",\n      \"state\": \"opened\",\n      \"url\": \"https:\u002F\u002Fgitlab.example\u002Fgroup\u002Fproject\u002F-\u002Fwork_items\u002F123\"\n    }\n  }\n}\n```\n\nUse these authoring forms:\n\n- `#123` for a same-project issue;\n- `!7` for a same-project merge request;\n- `group\u002Fproject!7` for a cross-project merge request;\n- `@abcdef1` for a commit;\n- `\u003Ca data-gl-ref=\"#123\">\u003C\u002Fa>` for an explicit reference whose visible text should be the token;\n- `\u003Ca data-gl-ref=\"#123\">the tracking issue\u003C\u002Fa>` to preserve custom visible text.\n\nThe generator also upgrades an existing anchor when its `href` matches a manifest URL. It treats\n`\u002F-\u002Fissues\u002F123` and `\u002F-\u002Fwork_items\u002F123` as the same target and keeps the authored link text. It\nwalks parsed text nodes to link known bare `#NNN` tokens in prose. It never changes text inside\n`code`, `pre`, `kbd`, or an existing anchor. Do not hand-edit code or command evidence to work\naround linking.\n\nAny GitLab-form token missing from the manifest stops generation and names the token and fragment\nfile, including bare `#NNN` prose outside the exclusion contexts. This is deliberate: add the correct\nsame-project entry or an explicit cross-project anchor instead of publishing a reference whose title\nand state were not baked in. Each generated anchor's accessible name contains kind, number, title,\nand state. Open, closed, and merged states\nalso use different inline SVG shapes, so color is not the only cue. The visual tooltip is\n`aria-hidden`. Never add `aria-describedby` alongside the complete `aria-label`; that would announce\nthe same information twice. With JavaScript disabled, `title` supplies a native fallback. With\nJavaScript enabled, the enhancement removes `title`, uses a fixed viewport-positioned tooltip that\ncannot be clipped by the evidence or table scrollers, and dismisses it on blur or Escape.\n\nBuild or refresh a manifest before report generation when references change:\n\n```bash\nnode scripts\u002Fgl-refs.mjs \\\n  --project group\u002Fproject \\\n  --out path\u002Fto\u002Fgl-references.json \\\n  path\u002Fto\u002Fnarrative-body.html path\u002Fto\u002Fevidence-body.html\n\nnode scripts\u002Fgl-refs.mjs \\\n  --project group\u002Fproject \\\n  --out path\u002Fto\u002Fgl-references.json \\\n  --refresh \\\n  path\u002Fto\u002Fnarrative-body.html path\u002Fto\u002Fevidence-body.html\n```\n\nThe helper authenticates `glab` first, bulk-loads both open and closed items with `--all`, and falls\nback to `glab issue view \u003Ciid>` when an issue or work-item type is absent from list output. It merges\nonly after every requested lookup succeeds and writes atomically. An authentication or lookup\nfailure leaves the prior manifest unchanged. Never refetch during a deterministic report build.\n\nMetadata can instead be passed with `--title`, `--deck`, `--date`, `--provenance`, `--language`,\n`--companion`, and `--companion-label`. The companion flags apply only to standalone narrative and\ndetailed reports. Command-line values override the metadata file. Run `node scripts\u002Fmake-report.mjs\n--help` for the compact reference.\n\nThe generator calculates reading time, builds the table of contents, escapes metadata, expands\nmanifest-backed references, and inlines the shared CSS and JavaScript. No runtime uses an external\nscript. Treat\ngenerated HTML as build output: revise the body or metadata, then regenerate instead of hand-editing\nthe final file.\n\nFor standalone output, keep using `--kind narrative` or `--kind detailed` with the existing\n`companionHref` metadata. See `examples\u002Freports\u002F` for all three generated forms. Regenerate them with:\n\n```bash\nnpm run reports:example\n```\n\n## Self-contained rule\n\nEach final report must work as one HTML file without the artifacts daemon or a network connection.\n\n- Never load a CDN, remote script, stylesheet, web font, image, audio file, video, or iframe.\n- Do not rely on an external URL for rendering, layout, playback, or meaning.\n- Inline small images as `data:` URLs or use authored inline SVG.\n- Keep source citations readable in the document itself. A citation link may be useful online, but\n  its label and surrounding text must still identify the source offline.\n- For a deep audit with linked prose and findings, use one combined artifact so registration cannot\n  break a relative sibling link.\n\nThe generator rejects body scripts, remote CSS resources, non-inline resource attributes, and\nexternal companion links. It runs the same self-containment check over both combined fragments and\nthe final HTML. Ordinary source links do not make the report dependent on the network. The\ngenerator gives every `http(s)` link `target=\"_blank\"` and adds `noopener noreferrer` to its `rel`,\nbecause most sites refuse to load inside the viewer frame. An authored `target` is kept.\n\n## Accessibility checklist\n\nBefore registering a report, confirm:\n\n- [ ] One `\u003Ch1>` comes from metadata; section headings begin at `\u003Ch2>` and do not skip levels.\n- [ ] Every top-level section has a stable, unique `id`.\n- [ ] Link text explains its destination without relying on “click here.”\n- [ ] Images have useful `alt` text; decorative images use empty `alt=\"\"`.\n- [ ] Tables have captions, scoped headers, and no layout-only cells.\n- [ ] Color is not the only way severity or status is communicated.\n- [ ] Every generated GitLab reference names its kind, number, title, and state; its tooltip is\n      `aria-hidden` and the anchor has no `aria-describedby`.\n- [ ] Bare issue tokens remain literal inside `code`, `pre`, `kbd`, and authored links.\n- [ ] The narrative makes sense as plain text and contains no instruction that depends only on\n      visual position.\n- [ ] Content remains normal semantic DOM text. Never add `aria-hidden` to report content to make\n      the audio reader easier to implement.\n- [ ] Evidence starts with the `hidden` attribute, enters the accessibility tree only when opened,\n      and contains no audio section buttons.\n- [ ] Opening evidence moves focus into its pane. Closing restores focus to the opener; narrow mode\n      also restores narrative scroll position.\n- [ ] Manual evidence scrolling and evidence table-of-contents choices turn follow off and announce\n      the change through a polite live region.\n- [ ] Audio is omitted unless a reader asked for it (`\"audio\": true`). When present, it does not\n      autoplay; playback starts only after a person activates a control.\n- [ ] Every authored interactive control has an accessible name and works from the keyboard.\n- [ ] At 200% zoom, content remains readable without horizontal scrolling except inside deliberate\n      table and code scrollers.\n- [ ] Print preview has readable contrast and does not include the floating audio controls.\n- [ ] Light and dark system themes both remain legible.\n\nThe browser reader supplements real screen readers. It does not replace normal headings, landmarks,\nlink text, table semantics, or alternative text.\n\n## Browser verification\n\nAlways open a generated combined report with default metadata in a current Chromium or Safari\nbrowser and verify:\n\n1. No audio player, **Listen** pill, **Read this section** button, empty reader script wrapper, or\n   claim that audio is present appears.\n2. The initial view is narrative-only; evidence is absent from the accessibility tree and tab order.\n3. Every mapped section has one **Evidence** button with the section title in its accessible name;\n   unmapped sections have no evidence button.\n4. Section buttons open the first mapped target and move focus to the pane. The global toggle uses\n   the visible mapped narrative section, then falls back to the first evidence section.\n5. Narrative scrolling follows mapped targets. A manual evidence scroll and an evidence table-of-\n   contents choice each turn follow off and produce a polite announcement; the follow control\n   resumes synchronization.\n6. Closing returns focus to the opening control. Below 62rem, **Back to the narrative** restores\n   narrative scroll and focus; at or above 62rem, both panes remain visible.\n7. A GitLab reference tooltip opens on hover and keyboard focus, closes on blur and Escape, flips\n   near viewport edges, and remains visible inside the evidence pane or a wide table scroller. The\n   native browser tooltip does not also appear.\n8. Print preview contains the narrative followed by every evidence section, with evidence controls\n   omitted.\n\nWhen `\"audio\": true` is set on either a standalone narrative or combined report, additionally verify:\n\n1. **Play** reads the title, description, and body. Pause, Resume, and Stop update state correctly.\n2. **Read this section** stops current speech and reads only that section. **Read from here** reads\n   that section and every later section.\n3. Rate and voice choices survive a reload when storage is available, including when the browser\n   loads voices after the page.\n4. Progress advances and the current passage is highlighted. Browsers without speech boundary\n   events still highlight the current paragraph.\n5. Follow-along scrolling becomes immediate, not smooth, when reduced motion is enabled.\n6. The Help dialog documents `Alt+Shift+Space`, `Alt+Shift+S`, `Alt+Shift+H`, and `Alt+Shift+L`.\n7. Navigating away cancels speech. With speech synthesis unavailable, no player or section audio\n   buttons appear.\n8. **Hide** collapses the player to the `Listen` pill, moves focus to it, and persists the choice;\n   the pill restores the panel and returns focus to **Play**. Hiding during playback keeps audio\n   running and reports the transport state.\n9. Print preview omits the reader controls.\n\nFor an audio-enabled combined report, also verify that opening, browsing, and closing evidence do\nnot change playback. These evidence checks do not apply to a standalone narrative report.\n\nVoice availability and boundary events depend on the browser and operating system. Do not promise a\nspecific installed voice or word-level boundary behavior.\n\n## Validate and register\n\nRun the repository checks after changing the template, helper, or source examples:\n\n```bash\nnpm run check\n```\n\nThen register the one generated combined file as an artifact and return its viewer URL. Keep the\nsource bodies and metadata in the producing project when the report may be regenerated later.\n",{"name":5,"description":7},"main","a341ec69437d028e71ea1de51b7f6d9c1238048b","packages\u002Fpi-artifacts\u002Fskills\u002Fpi-artifacts-reports","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI","https:\u002F\u002Fwww.centerforairesearch.org\u002F","CAAIR develops applied AI systems that support civil society, public accountability, and democratic infrastructure.","2026-11-12 02:15:25",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add CenterForAgenticAI\u002Ftools --skill pi-artifacts-reports",{"tool":38,"command":39},"bunx","bunx skills add CenterForAgenticAI\u002Ftools --skill pi-artifacts-reports",{"tool":41,"command":42},"pnpm","pnpm dlx skills add CenterForAgenticAI\u002Ftools --skill pi-artifacts-reports","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-artifacts\u002Fskills\u002Fpi-artifacts-reports\u002FSKILL.md",true,[],[47,54,61,68,75,82],{"skillNo":48,"name":49,"nameZh":6,"description":50,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":19},"01M7DBS96C51VE1KHCM1N0SR47","work-execution","Execute a validated pi-work node or wave when you need the ready-set, by-reference work_plan brief, Fabric default, pi-delegate fallback, explicit tree-bound verification, remediation, scope amendments, or a post-integration refactor pass. Use after decomposition and before claiming any node is done.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-work\u002Fskills\u002Fwork-execution\u002FSKILL.md",[],[],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M7DBS2SJ4ZND4SG77JX66BWK","work-decomposition","Turn a validated pi-work intent into a strict workspec work graph when the work is too large for one bounded worker. Use when assigning criterion homes, dependencies, honest write scopes, open decisions, or optional model-change nodes before planning execution.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-work\u002Fskills\u002Fwork-decomposition\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M7DBRXT98J0Q84K38FCFQ9VT","work-authoring","Draft a pi-work workspec when an outcome, scope, or proof obligation is still unclear. Use this before turning a conversation, issue, or design into a markdown draft, especially when acceptance criteria need to survive lossless promotion into strict YAML.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-work\u002Fskills\u002Fwork-authoring\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7DBRST29F8J729DHGCM55WJ","intent-records","Draft or approve an intent record when a person asks for a change, or describe existing behaviour before retrofitting compiled intent. Use before turning intent into a pi-work workspec.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-intent\u002Fskills\u002Fintent-records\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M7DBRNVNYBW7K25Y7W7CYVEA","intent-conformance","Connect an approved finite Bend model to actual application code with a language-neutral conformance manifest, app-language oracles and a broken-model control. Load when proving implementation parity or diagnosing decision drift.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-intent\u002Fskills\u002Fintent-conformance\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M7DBRH9KT2DMXVT16P1JCHQK","compiled-intent-model","Author or change a finite Bend model from an approved intent record, review its meaning, obtain human law approval, and produce an offline-verifiable Jev receipt. Load for model-change nodes, not for emergent runtime behaviour.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-intent\u002Fskills\u002Fcompiled-intent-model\u002FSKILL.md",[],[]]