{"id":"115d1aee-c8ae-4e8d-bd41-fa8e18938201","entityType":"agent","slug":"clawhub-kaisersong-kai-report-creator","name":"Kai Report Creator V1.23.3 Publish","canonicalUrl":"https://www.xpersona.co/agent/clawhub-kaisersong-kai-report-creator","canonicalPath":"/agent/clawhub-kaisersong-kai-report-creator","generatedAt":"2026-10-09T22:31:13.654Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T22:07:20.968Z","emptyReason":null},"description":"Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and Eng... Skill: Kai Report Creator V1.23.3 Publish Owner: kaisersong Summary: Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and Eng... Tags: latest:1.23.3 Version history: v1.23.3 | 2026-05-17T09:51:54.143Z | user No-agent eval gate release: release verification now uses fixture skill evals by default, requires no Codex/Cla","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17e36cy6y9drqxrb49xdqh05d83hqde:kai-report-creator","sourceUrl":"https://clawhub.ai/kaisersong/kai-report-creator","homepage":"https://clawhub.ai/kaisersong/skills/kai-report-creator","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/kaisersong/kai-report-creator","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/kaisersong/skills/kai-report-creator","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":53,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and Eng..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T22:07:20.968Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T22:07:20.968Z","emptyReason":null},"stars":null,"forks":null,"downloads":1946,"packageName":null,"latestVersion":"1.23.3","tractionLabel":"1.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T22:07:20.968Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T22:07:20.968Z","lastCrawledAt":"2026-10-09T22:07:20.968Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T22:07:20.968Z","lastVerifiedAt":null,"highlights":[{"version":"1.23.3","createdAt":"2026-05-17T09:51:54.143Z","changelog":"No-agent eval gate release: release verification now uses fixture skill evals by default, requires no Codex/Claude/Qoder/model auth/network access, and rejects non-fixture runners unless a recorded trace or explicit live flag is supplied.","fileCount":178,"zipByteSize":492030},{"version":"1.23.2","createdAt":"2026-05-17T09:40:47.569Z","changelog":"Complete fixture rubric release: adds positive-case style rubric fixtures, requires eval_complete for green captured-run evals, compares completeness regressions, and refreshes the deterministic fixture baseline to 100.0.","fileCount":177,"zipByteSize":490029},{"version":"1.23.1","createdAt":"2026-05-17T09:34:10.059Z","changelog":"Captured-run skill eval release: adds OpenAI-style skill eval prompts, fixture/Codex trace runners, saved baselines, baseline comparison, and release-verification integration.","fileCount":173,"zipByteSize":485637},{"version":"1.23.0","createdAt":"2026-05-01T02:35:03.359Z","changelog":"Final HTML quality gate: validates shell IDs, theme fidelity, typography/layout markers, and KPI values; removes placeholder/status-only KPIs.","fileCount":142,"zipByteSize":442706},{"version":"1.22.0","createdAt":"2026-04-29T18:26:37.279Z","changelog":"Reference split and validator profile release: split shell/rendering contracts into route-specific references, add validator-facing artifacts and golden cases, and include generated-cache cleanup in release verification.","fileCount":137,"zipByteSize":432011},{"version":"1.21.0","createdAt":"2026-04-25T11:15:51.140Z","changelog":"Late-context isolation and release hardening: single-IR context extraction, late-context eval runner, stronger release verification, deterministic shell metadata, and repo docs sync.","fileCount":129,"zipByteSize":469580},{"version":"1.18.0","createdAt":"2026-04-23T06:11:20.525Z","changelog":"Fix theme routing for work reports: priority-ordered keyword matching now correctly routes weekly/daily/monthly reports to regular-lumen and generic work progress reports to corporate-blue fallback instead of dark-tech/dark-board.","fileCount":103,"zipByteSize":380534},{"version":"1.16.1","createdAt":"2026-04-22T01:59:55.672Z","changelog":"Tighten poster summary guardrails, tune title width/size to avoid broken wraps, add explicit poster_note support, and add release verification plus regression tests for summary-card and narrative-rhythm guardrails.","fileCount":95,"zipByteSize":370445}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17e36cy6y9drqxrb49xdqh05d83hqde:kai-report-creator","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T22:31:13.646Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-report-creator/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T22:07:20.968Z","emptyReason":null},"readme":"Skill: Kai Report Creator V1.23.3 Publish\n\nOwner: kaisersong\n\nSummary: Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and Eng...\n\nTags: latest:1.23.3\n\nVersion history:\n\nv1.23.3 | 2026-05-17T09:51:54.143Z | user\n\nNo-agent eval gate release: release verification now uses fixture skill evals by default, requires no Codex/Claude/Qoder/model auth/network access, and rejects non-fixture runners unless a recorded trace or explicit live flag is supplied.\n\nv1.23.2 | 2026-05-17T09:40:47.569Z | user\n\nComplete fixture rubric release: adds positive-case style rubric fixtures, requires eval_complete for green captured-run evals, compares completeness regressions, and refreshes the deterministic fixture baseline to 100.0.\n\nv1.23.1 | 2026-05-17T09:34:10.059Z | user\n\nCaptured-run skill eval release: adds OpenAI-style skill eval prompts, fixture/Codex trace runners, saved baselines, baseline comparison, and release-verification integration.\n\nv1.23.0 | 2026-05-01T02:35:03.359Z | user\n\nFinal HTML quality gate: validates shell IDs, theme fidelity, typography/layout markers, and KPI values; removes placeholder/status-only KPIs.\n\nv1.22.0 | 2026-04-29T18:26:37.279Z | user\n\nReference split and validator profile release: split shell/rendering contracts into route-specific references, add validator-facing artifacts and golden cases, and include generated-cache cleanup in release verification.\n\nv1.21.0 | 2026-04-25T11:15:51.140Z | user\n\nLate-context isolation and release hardening: single-IR context extraction, late-context eval runner, stronger release verification, deterministic shell metadata, and repo docs sync.\n\nv1.18.0 | 2026-04-23T06:11:20.525Z | user\n\nFix theme routing for work reports: priority-ordered keyword matching now correctly routes weekly/daily/monthly reports to regular-lumen and generic work progress reports to corporate-blue fallback instead of dark-tech/dark-board.\n\nv1.16.1 | 2026-04-22T01:59:55.672Z | user\n\nTighten poster summary guardrails, tune title width/size to avoid broken wraps, add explicit poster_note support, and add release verification plus regression tests for summary-card and narrative-rhythm guardrails.\n\nv1.15.0 | 2026-04-21T04:12:39.231Z | user\n\nIR contract hardening, eval workflow, and 125 passing Windows tests.\n\nv1.14.2 | 2026-04-19T12:58:01.444Z | user\n\nEnforce full export menu completeness in the standard generate flow.\n\nv1.14.1 | 2026-04-19T11:50:18.615Z | user\n\nPrint/PDF export fix: preserve report background and keep animated KPI/data blocks visible in PDF output.\n\nv1.13.0 | 2026-04-13T14:52:25.647Z | user\n\nfix: remove XML-like <file> tag from SKILL.md description to fix Claude Desktop install\n\nv1.9.0 | 2026-04-06T15:52:14.881Z | user\n\nAdded report review system with one-pass automatic refinement, silent final review during generate, review checklist/template, doc-sync checks, and reviewed demo assets.\n\nv1.8.3 | 2026-04-04T11:37:51.884Z | auto\n\nkai-report-creator v1.8.3\n\n- Added new sample templates, example reports, and enhanced theme documentation.\n- Expanded built-in and custom theme support with updated theme and template files.\n- Improved IR/component rendering references and business/tech sample outputs.\n- General refinements to documentation and command usage instructions.\n- Test and script files updated to support new examples and image export scenarios.\n\nv1.8.2 | 2026-04-04T03:53:38.301Z | user\n\nRestrained color system, warm premium business theme, and synced docs.\n\nv1.8.1 | 2026-04-03T18:15:53.006Z | user\n\nFix export background fallback for PNG/mobile/IM capture and add transparent-background regression coverage.\n\nv1.8.0 | 2026-04-03T03:57:50.750Z | user\n\nfeat: custom theme support — add themes/<name>/reference.md for AI-derived styles or themes/<name>/theme.css for direct CSS variables; sample theme _example-warm-editorial included\n\nv1.7.0 | 2026-04-03T03:44:19.551Z | user\n\nfeat: content-aware component selection — narrative reports no longer get forced KPI/chart placeholders; numeric density classification routes visual anchors to callout/timeline/diagram for text-heavy content\n\nv1.6.0 | 2026-03-27T03:06:11.334Z | user\n\nfeat: sankey chart component — node labels show name+value with rich text styling, edge labels show flow values inline, --plan mode auto-selects sankey for branching flow data\n\nv1.5.2 | 2026-03-25T10:25:22.992Z | auto\n\nkai-report-creator v1.5.2\n\n- Documentation updates and clarifications in README, SKILL.md, and related docs\n- Improved consistency across English and Chinese documentation\n- No functional or command changes; this is a documentation-focused update\n\nv1.5.1 | 2026-03-24T11:19:55.053Z | auto\n\nkai-report-creator 1.5.1\n\n- Added new reference: references/design-quality.md for improved report design and consistency.\n- Updated documentation in README.md, README.zh-CN.md, and SKILL.md for clearer usage, flags, and theme guidelines.\n- Enhanced theme and rendering guidelines in references/html-shell-template.md and references/rendering-rules.md.\n- Made minor CSS improvements in templates/themes/shared.css.\n- Improved clarity of supported features, flags, and report format in all documentation.\n\nv1.4.1 | 2026-03-24T03:46:00.218Z | user\n\nSummary card redesign: editorial two-column layout, export fix\n\nv1.4.0 | 2026-03-24T02:36:49.117Z | user\n\nSummary card overlay: every report now has a ⊞ Summary button next to the title. Click to open an editorial-style card with title, abstract, KPIs, and section chips. Close via ✕, Escape, or backdrop click.\n\nv1.3.0 | 2026-03-24T02:03:53.745Z | user\n\nGSAP-inspired zero-dependency animation upgrade: KPI card spring-bounce stagger, timeline slide-in stagger, power3.out easing curves. No new libraries.\n\nv1.2.3 | 2026-03-19T04:45:37.963Z | user\n\nfix: :::list 等 IR 指令泄漏到最终 HTML 的 bug，新增渲染前验证规则\n\nv1.2.2 | 2026-03-18T05:36:56.290Z | auto\n\nVersion 1.2.2\n\n- Documentation update only: SKILL.md updated to version 1.2.2.\n- No functionality or code changes.\n\nv1.2.1 | 2026-03-17T10:28:13.823Z | auto\n\nkai-report-creator v1.2.1\n\n- Updated version number to 1.2.1 in SKILL.md.\n- No functional or feature changes; documentation version bump only.\n\nv1.2.0 | 2026-03-17T10:27:20.347Z | auto\n\nkai-report-creator 1.2.0\n\n- Added comprehensive reference documentation in the references/ directory, including guides on template HTML, rendering rules, theme CSS, and table of contents/template usage.\n- Updated SKILL.md to improve documentation clarity and support for new references.\n- No functional or breaking changes introduced; documentation enhancements only.\n\nv1.1.5 | 2026-03-17T07:21:51.217Z | auto\n\nkai-report-creator 1.1.5\n\n- Updated documentation to reflect current version (v1.1.5) in SKILL.md.\n- No functional or code logic changes; documentation/metadata update only.\n\nv1.1.4 | 2026-03-17T07:15:19.949Z | auto\n\nVersion 1.1.4 of kai-report-creator\n\n- No changes to any files were detected in this release.\n- Behavior, features, and documentation remain the same as version 1.1.3.\n\nv1.1.3 | 2026-03-17T07:14:46.510Z | auto\n\nkai-report-creator 1.1.3\n\n- Added automated test suite, including pytest configs and sample tests.\n- Introduced requirements-test.txt and test scripts for reproducible testing.\n- Improved export-image script handling; increased robustness.\n- Expanded documentation for clearer usage and flag routing.\n- Adjusted description to clarify scope and related skills.\n\nv1.1.2 | 2026-03-16T22:08:05.104Z | user\n\ndocs: add OpenClaw daily report use case — generate dark-board report and send as IM image to Telegram/Discord\n\nv1.1.1 | 2026-03-16T21:48:46.370Z | user\n\nFix: auto-disable animations in headless/screenshot environments. navigator.webdriver detection added to all 12 templates — fade-in-up content now shows correctly in screenshots taken by Playwright/Puppeteer/OpenClaw.\n\nv1.1.0 | 2026-03-16T16:03:06.237Z | user\n\nAdd IM image export (800px JPEG for messaging apps), CLI tool scripts/export-image.py, KPI accent palette (6 colors), kpi-delta badges, badge/chip components, serif font-variant-numeric fix\n\nv1.0.1 | 2026-03-16T14:27:50.308Z | user\n\nOpenClaw support (user-invocable, metadata.openclaw emoji); fix skill description CSO compliance; fix themes count 8→6; fix TOC padding; fix PNG export fade-in-up reveal\n\nv1.0.0 | 2026-03-16T14:11:12.912Z | user\n\nInitial release: 6 themes, 9 component types, built-in PDF/PNG export, inline edit mode, AI-readable 3-layer output, bilingual zh/en\n\nArchive index:\n\nArchive v1.23.3: 178 files, 492030 bytes\n\nFiles: check-doc-sync.py (5869b), CLAUDE.md (1723b), evals/__init__.py (49b), evals/baselines/2026-05-17-baseline-summary.md (4455b), evals/baselines/2026-05-17-late-context-evals.json (11926b), evals/baselines/2026-05-17-report-evals.json (5255b), evals/baselines/2026-05-17-skill-evals-codex-live.json (160772b), evals/baselines/2026-05-17-skill-evals-fixture.json (9886b), evals/cases/en-ops-weekly/noise-context.md (1694b), evals/cases/en-ops-weekly/report.report.md (1273b), evals/cases/en-ops-weekly/source.md (535b), evals/cases/guard-broken-chart-schema/report.report.md (496b), evals/cases/guard-broken-chart-schema/source.md (56b), evals/cases/guard-narrative-placeholder-kpi/report.report.md (1471b), evals/cases/guard-narrative-placeholder-kpi/source.md (374b), evals/cases/zh-ai-collaboration/noise-context.md (2285b), evals/cases/zh-ai-collaboration/report.report.md (1805b), evals/cases/zh-ai-collaboration/source.md (804b), evals/cases/zh-quarterly-growth/noise-context.md (1785b), evals/cases/zh-quarterly-growth/report.report.md (1385b), evals/cases/zh-quarterly-growth/source.md (406b), evals/contract_checks.py (8970b), evals/failure-map.md (1940b), evals/golden_cases.yaml (2856b), evals/report-cases.csv (862b), evals/report-skill-prompts.csv (886b), evals/rubric.schema.json (2127b), evals/skill-prompts/boundary-blueprint-report.md (734b), evals/skill-prompts/contextual-research.md (806b), evals/skill-prompts/explicit-generate.md (582b), evals/skill-prompts/implicit-weekly-progress.md (608b), evals/skill-prompts/negative-html-export.md (118b), evals/skill-prompts/negative-slide-deck.md (114b), evals/skill-run-rubric.schema.json (1182b), examples/business-report.report.md (1650b), examples/do-not-use.md (508b), examples/en/business-report-reviewed-demo.html (22220b), examples/en/business-report.html (24153b), examples/en/monthly-progress-reviewed-demo.html (17571b), examples/en/monthly-progress.html (16538b), examples/research-report.report.md (1718b), examples/review-reports/business-report-demo-review-report.md (3376b), examples/review-reports/monthly-progress-demo-review-report.md (3125b), examples/review-reports/monthly-progress-zh-review-report.md (3221b), examples/tech-doc.report.md (1706b), examples/when-to-use.md (799b), examples/zh/business-report.html (23702b), examples/zh/kai-report-creator-guide.html (32103b), examples/zh/kai-report-creator-guide.report.md (4833b), examples/zh/monthly-progress-reviewed-demo.html (17632b), examples/zh/monthly-progress.html (15933b), pytest.ini (125b), README.md (31229b), README.zh-CN.md (28970b), references/anti-patterns.md (4303b), references/design-quality.md (15801b), references/diagram-decision-rules.md (1317b), references/generate-flow.md (1863b), references/html-shell-template.md (5060b), references/html-shell/core-structure.md (7024b), references/html-shell/export.md (9371b), references/html-shell/print-responsive.md (1509b), references/html-shell/shared-component-css.md (12342b), references/html-shell/summary-card.md (10413b), references/html-shell/toc-edit-summary.md (11506b), references/impeccable-anti-patterns.md (5625b), references/INDEX.md (3497b), references/ir-contract.md (1833b), references/plan-flow.md (1544b), references/regular-report-content-rules.md (1726b), references/rendering-rules.md (3547b), references/rendering/chart.md (8595b), references/rendering/kpi.md (8359b), references/rendering/media-code-callout.md (2088b), references/rendering/plain-markdown.md (1449b), references/rendering/table-list.md (1304b), references/rendering/timeline-diagram.md (3486b), references/review-checklist.md (10468b), references/review-report-template.md (2069b), references/spec-loading-matrix.md (1939b)\n\nFile v1.23.3:SKILL.md\n\n---\nname: kai-report-creator\ndescription: Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and English equally. Supports generating from raw notes, data, URLs, or an approved plan file. Use for --plan (structure first), --generate (render to HTML), --review (one-pass automatic refinement), --themes (preview styles), --from FILE, --bundle, --export-image flags. Does NOT apply to exporting finished HTML to PPTX/PNG (use kai-html-export) or creating slide decks (use kai-slide-creator).\nversion: 1.23.3\nuser-invocable: true\nmetadata: {\"openclaw\": {\"emoji\": \"📊\"}}\n---\n\n# kai-report-creator\n\nGenerate single-file HTML reports from source notes or `.report.md` IR. Keep this file as a thin router: load only the references needed for the current path.\n\n## Core Principles\n\n1. **Zero Dependencies** — generated reports are self-contained HTML, with CDN or bundled assets only when needed.\n2. **User Provides Data, AI Provides Structure** — never fabricate facts or numbers; use `[数据待填写]` / `[INSERT VALUE]` when data is missing.\n3. **Plan Before Generate** — complex reports should become `.report.md` IR first, then HTML.\n4. **Progressive Disclosure for AI** — output keeps `report-summary`, section annotations, and component data machine-readable.\n5. **Thin Routing Over Prompt Growth** — `SKILL.md` routes work; detailed rules live in references.\n6. **Contracts and Gates Beat Prompt Soup** — prefer IR, guard validation, shell tests, and post-render review over adding more prose to this hot path.\n\n## Command Routing\n\nWhen invoked as `/report [flags] [content]`, parse flags first:\n\n| Flag | Action |\n|------|--------|\n| `--plan \"topic\"` | Write `.report.md` IR only. Stop after saving it. |\n| `--generate [file]` | Render one `.report.md` IR to HTML. With no file given, treat as IR from context: extract exactly one valid IR block from context. Never render the surrounding conversation. |\n| `--review [file]` | Refine an existing HTML report with `references/review-checklist.md`. |\n| `--themes` | Write the themes preview HTML. |\n| `--from <file>` | If the file starts with frontmatter, treat as IR; otherwise create IR, then render. |\n| `--theme <name>` | Override the theme. Built-ins: `corporate-blue`, `minimal`, `dark-tech`, `dark-board`, `data-story`, `newspaper`, `regular-lumen`, `fangsong`. |\n| `--template <file>` | Use a custom HTML template. See `references/toc-and-template.md`. |\n| `--output <file>` | Save to this path instead of the default. |\n| `--bundle` | Inline CDN assets where supported. |\n| `--export-image [mode]` | After HTML generation, run `scripts/export-image.py`; mode is `im`, `mobile`, `desktop`, or `all`. |\n| no flags + text | Create IR internally, then render HTML. |\n| no flags + IR in context | Treat as `--generate` from context. |\n\nDefault output filename: `report-<YYYY-MM-DD>-<slug>.html`. Slug: lowercase ASCII, non-alphanumeric to hyphens, collapse hyphens, trim, max 30 chars.\n\n## Reference Loading\n\nLoad reference files minimally by route; do not read every reference by default. In short: load only the references that materially help the current render path.\n\n| Route | Always load | Conditional load |\n|-------|-------------|------------------|\n| `--plan` | `references/spec-loading-matrix.md`, `references/plan-flow.md`, `references/theme-routing.md` | `references/regular-report-content-rules.md` for periodic reports |\n| `--generate` | `references/generate-flow.md`, `references/html-shell-template.md` + every `references/html-shell/*.md`, `references/theme-css.md`, `references/review-checklist.md` | `references/rendering-rules.md` then only the `references/rendering/*.md` files required by the IR; `references/anti-patterns.md` for visual anchors; `references/diagram-decision-rules.md` for diagrams; `references/regular-report-content-rules.md` for periodic reports |\n| `--review` | `references/review-checklist.md` | `references/review-report-template.md` if a structured change summary is requested |\n| custom theme/template | `references/theme-css.md`, `references/toc-and-template.md` | custom theme `reference.md` or `theme.css` |\n\nLoad `references/spec-loading-matrix.md` before `--plan` and `--generate` as a silent classifier. It covers optional archetypes: `brief`, `research`, `comparison`, `update`.\n\nAlways load `references/anti-patterns.md` before `--generate`. Load `references/diagram-decision-rules.md` whenever a diagram or diagram-like structure is being considered.\n\n## IR Contract\n\nLoad `references/ir-contract.md` for the full frontmatter spec, validity terms, and compatibility anchors.\n\nQuick reference:\n- Three parts: YAML frontmatter, Markdown prose (`##`/`###`), component fences `:::tag [param=value]`.\n- `:::kpi` uses `items:`; Use **ECharts** for ALL charts.\n- Badges are optional visual enhancements, not a first-class IR tag.\n- Validity taxonomy: `invalid_syntax`, `invalid_semantics`, `contract_conflict`, `auto_downgrade_target`.\n- Timeline details live in rendering references; Allowed `Date` tokens must be real time markers, not decorative labels.\n- Canonical component routing: `references/rendering-rules.md`; component details: `references/rendering/*.md`.\n\nMinimal frontmatter example:\n```yaml\ntheme: corporate-blue                  # Optional. Default: corporate-blue\nreport_class: mixed                    # Optional. Values: narrative, mixed, data\narchetype: research                    # Optional lightweight archetype hint for silent classification.\n```\nSupported archetypes: `brief`, `research`, `comparison`, `update`.\n\n## Language And Theme\n\nLoad `references/theme-routing.md` for the full theme-selection table and report-class rules.\n\nQuick reference: auto-detect `zh` when CJK is material; apply to placeholders, TOC labels, date display, and shell labels.\n\n## `--plan` Flow\n\nLoad `references/plan-flow.md` for the full 10-step procedure and narrative rhythm rules.\n\nKey gates: save as `report-<slug>.report.md`; do not generate HTML; use real quantitative KPI values only.\n\nPoster summary mode is opt-in. Do not infer `poster_title` or `poster_subtitle` from punctuation in `title`.\n\nNarrative cadence blocks (`lead-block`, `section-quote`, `action-grid`) follow claim -> explanation -> scan anchor. These are optional prose upgrades, not default required blocks. If uncertain, keep normal paragraphs and add one clearer scan anchor instead of forcing a cadence block. Do not add more than one of `lead-block` / `section-quote` / `action-grid` by default inside the same section unless the source material clearly warrants it.\n\n## `--generate` Flow\n\nLoad `references/generate-flow.md` for steps 1-8 (input parsing, guard validation, render, shell assembly, CSS).\n\nThen run these quality gates in sequence — do not skip:\n\n9. Run pre-write validation and fix all violations:\n   - no raw `:::` in HTML\n   - valid `ir-hash`\n   - no generic/template h2 headings\n   - short, real quantitative `.kpi-value` and `report-summary` KPI values; no placeholder or status-only KPI values\n   - `.number` body numerals use tabular lining numerals\n   - badges clarify status/category/entity, never quota-fill\n   - timeline dates are real time markers\n   - no U+FE0F\n   - no `text-align: justify`, black-background flood, body letter-spacing > `0.05em`, or mobile-hidden critical controls\n10. Run the final HTML quality gate with `scripts/html_quality_gate.py` on the rendered HTML. It must pass standard shell IDs, theme fidelity, and KPI value checks. If it fails, fix the HTML and rerun it before reporting success.\n11. Run L2 shell checks. Required: `data-template=\"kai-report-creator\"`, `data-version`, `data-theme`, `id=\"toc-toggle-btn\"`, `id=\"toc-sidebar\"`, `id=\"card-mode-btn\"`, `id=\"sc-overlay\"`, `id=\"export-btn\"`, `id=\"export-menu\"`, `id=\"export-print\"`, `id=\"export-png-desktop\"`, `id=\"export-png-mobile\"`, `id=\"export-im-share\"`, `id=\"report-summary\"`, plus the JS bindings for print/desktop/mobile/IM export. If any export item or binding is missing, rebuild the whole export block from `references/html-shell/export.md`.\n12. Run the silent final review pass from `references/review-checklist.md`, then write the HTML and report the path.\n\nWhen the report is explicitly comparing named vendors, models, or tools, set `data-report-mode=\"comparison\"` on the outer report container and use `.badge--entity-a/.badge--entity-b/.badge--entity-c` only for entity identity.\n\n## `--review` Flow\n\n1. Read the HTML file.\n2. Load `references/review-checklist.md`.\n3. Apply hard rules automatically; apply AI-advised rules only when confidence is high and factual accuracy is preserved.\n4. One-pass automatic refinement; no confirmation window.\n5. Use `references/review-report-template.md` when the user wants a structured summary.\n6. Write back unless the user asked for diagnosis only.\n7. Tell the user what changed and what was intentionally left untouched.\n\n## `--themes` And `--export-image`\n\nFor `--themes`, read the theme preview template and write `report-themes-preview.html` verbatim.\n\nFor `--export-image`, after HTML generation run:\n\n```bash\npython <skill-dir>/scripts/export-image.py <output.html> --mode <mode>\n```\n\nIf Playwright is unavailable, print install instructions and skip image export without failing HTML generation.\n\n## Shell And Template Boundary\n\nGenerate complete self-contained HTML. Shell entry contract: `references/html-shell-template.md`; full shell structure, inline JS, export behavior, summary card, edit mode, TOC, print rules, Shell metadata, version/theme metadata, duplicate-date guard, and footer/watermark degradation rules: `references/html-shell/*.md`.\n\nAll scripts are inline in the shell template. Never load nonexistent files such as `templates/scripts/*.js`.\n\nFor custom templates and TOC slug rules, use `references/toc-and-template.md`.\n\n## Final Output\n\nAlways end with the file path and a one-sentence summary. If a validation, guard, or export step could not run, say exactly which step was skipped and why.\n\nFile v1.23.3:README.md\n\n# kai-report-creator\n\n> You have data, decisions, and deadlines — but decision makers don't have time to read everything. AI can generate reports, but they often look instantly AI-made: template headings, primary color flooding every element, 3-column KPI grids regardless of count. kai-report-creator gives you polished, async-friendly reports in one command: drop a document or URL, pick a theme, and get a single HTML file that survives first-contact reading. Downstream AI agents can also parse it — the output embeds a 3-layer machine-readable structure.\n>\n> **[See the guide as a report →](https://kaisersong.github.io/kai-report-creator/examples/zh/kai-report-creator-guide.html)** — this document was generated by kai-report-creator itself.\n\nA skill for [Claude Code](https://claude.ai/claude-code) and [OpenClaw](https://openclaw.ai) that turns plain text or structured outlines into polished HTML reports.\n\nEnglish | [简体中文](README.zh-CN.md)\n\n---\n\n## Live Demo\n\nClick any screenshot to open the live demo:\n\n<table>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/corporate-blue.html\"><img src=\"templates/screenshots/corporate-blue.png\" width=\"360\" alt=\"corporate-blue\"/><br/><b>corporate-blue</b></a><br/><sub>Warm Premium · Business</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/minimal.html\"><img src=\"templates/screenshots/minimal.png\" width=\"360\" alt=\"minimal\"/><br/><b>minimal</b></a><br/><sub>Research · Academic</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/dark-tech.html\"><img src=\"templates/screenshots/dark-tech.png\" width=\"360\" alt=\"dark-tech\"/><br/><b>dark-tech</b></a><br/><sub>Engineering · Ops</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/dark-board.html\"><img src=\"templates/screenshots/dark-board.png\" width=\"360\" alt=\"dark-board\"/><br/><b>dark-board</b></a><br/><sub>Dashboards · Architecture</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/data-story.html\"><img src=\"templates/screenshots/data-story.png\" width=\"360\" alt=\"data-story\"/><br/><b>data-story</b></a><br/><sub>Annual Reports · Growth</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/newspaper.html\"><img src=\"templates/screenshots/newspaper.png\" width=\"360\" alt=\"newspaper\"/><br/><b>newspaper</b></a><br/><sub>Editorial · Industry Analysis</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/regular-lumen.html\"><img src=\"templates/screenshots/regular-lumen.png\" width=\"360\" alt=\"regular-lumen\"/><br/><b>regular-lumen</b></a><br/><sub>Periodic Reports · Weekly/Daily/Monthly</sub></td>\n</tr>\n</table>\n\nPreview the theme gallery: `/report --themes` → opens `report-themes-preview.html`\n\n---\n\n## Design Philosophy: Skills as Domain Harness Engineering\n\nThis section explains the principles behind report-creator — both as a user tool and as a Claude Code skill. These principles are reusable for anyone building skills.\n\n### 1. Progressive Disclosure\n\nA skill file loads entirely into the AI's context on every invocation. Size directly affects focus.\n\nreport-creator solves this with **rules in the skill, assets in files**:\n\n```\n--plan        → only IR rules + component syntax; no CSS, no HTML shell\n--generate    → one theme CSS + one shared CSS; other theme files stay on disk\n--themes      → pre-built preview HTML; skill doesn't parse internals\n```\n\n**Result:** `--plan` never touches CSS. Single-theme generation only loads the selected theme.\n\nThis is progressive disclosure applied to AI context: **reveal information at the moment it's needed, not before.**\n\n### 2. Capability Growth Must Reduce Context Load\n\nWhen adding a new capability, the first question is not \"what else can we stuff into context?\" It is \"can we reduce prompt/context burden on the generation path?\"\n\nreport-creator should prefer three moves:\n\n- **Thin routing in `SKILL.md`.** Keep the skill file as a router plus contract boundary. Load only the files needed for the selected path. Do not drag long planning conversations directly into the render phase.\n- **Structured compression over raw prose.** Prefer `.report.md`, `BRIEF.json`-style briefs, explicit contracts, and routing metadata over more prompt paragraphs. If information matters repeatedly, give it a field, a schema, or a deterministic transform.\n- **Move quality checks off the hot path.** If a new quality mechanism increases generation-time cognitive load, it belongs in guard validation, post-render review, or evals instead of the prompt chain.\n\nThis is not minimalism for its own sake. It is reliability work. Prompt bloat makes routing fuzzy, hides the real contract, and causes the model to drop constraints exactly when rendering needs precision.\n\n### 3. Silicon-Carbon Collaboration Design\n\nreport-creator is designed for human-AI collaboration at both input and output ends.\n\n**Input: IR as Human-AI Contract**\n\nThe `.report.md` Intermediate Representation is the contract between human intent and AI rendering:\n\n```\n---                         ← Frontmatter: document identity\ntitle: Q3 Sales Report         What is this? Who made it? How should it look?\ntheme: corporate-blue          Declares intent, not content.\n---\n\n## Section Heading         ← Prose: human narrative\nPlain Markdown text...        Written naturally. AI renders to semantic HTML.\n\n:::kpi                     ← Component blocks: structured data\n- Revenue: $2.45M ↑12%       Machine-parseable. AI renders deterministically.\n:::\n```\n\nHumans write naturally without knowing HTML. AI renders each layer with different rules — prose gets Markdown, components get templates. IR is inspectable and version-controllable.\n\n**Output: Three-Layer AI-Readable Structure**\n\nEvery generated HTML embeds machine-readable structure:\n\n```\nLayer 1 — <script id=\"report-summary\">    Document-level: title, abstract, all KPIs\nLayer 2 — data-section data-summary       Section-level: heading + one-sentence summary\nLayer 3 — data-component data-raw         Component-level: raw KPI/chart/table data\n```\n\nAn AI agent reads Layer 1 for a 3-second overview, drills to Layer 2 for section-level understanding, reaches Layer 3 only for specific data.\n\n**Progressive disclosure for both species:** IR reveals structure to humans; HTML reveals data to machines. The same principle applied twice — once for carbon-based readers, once for silicon-based ones.\n\n### 4. Visual Rhythm as Cognitive Pacing\n\nReports that work follow a rhythm: **prose sets context, components deliver data, prose interprets it**.\n\nThe skill enforces this: never 3+ consecutive prose-only sections. Every 4–5 sections must include a visual anchor chosen for the content type — callout, timeline, diagram, KPI grid, or chart. Dense prose fatigues; data without context loses. Alternation creates flow.\n\nThis is why IR's component syntax (`:::tag ... :::`) is visually obvious: authors scan IR files and see data-heavy sections immediately.\n\n### 5. Reports Are Asynchronous Decision Support\n\nSlides have a presenter. Reports don't. A report must survive first contact with a busy reader who skims the opening, scans headings, glances at data, and decides in under a minute whether to continue.\n\nThis constraint drives product design:\n\n- `--review` is **one-pass automatic refinement**, not interactive editing\n- `--generate` runs the same checklist as a **silent final pass**\n- Checklist split into **L0 visual quality** and **L1 content quality**\n- Only rules AI can judge and repair reliably are included\n\n**Rule of thumb:** A generated report should reduce reader effort. If a stakeholder can understand the point, evidence, and next action from a fast skim, the report works.\n\n### 6. Design Quality Baseline: Against AI Slop\n\nThe enemy: instantly recognizable AI output — uniform borders, primary color flooding everything, 3-column KPI grids regardless of count, template-sounding headings.\n\n`references/design-quality.md` encodes four disciplines:\n\n**90/8/2 Color Law.** 90% neutral surface, 8% structural accent, 2% bullet-point hits. When `--primary` floods headings, KPIs, charts, callouts, TOC, and badges — it becomes noise.\n\n**10:1 Typography Tension.** Largest element ≥10× smallest. Report titles should feel like anchors (2.8–4rem), not labels. Pages without hierarchy look like spreadsheet exports.\n\n**KPI Grid Rules.** Default isn't always 3 columns. 4 KPIs → 2×2. Hero metric → `2fr 1fr 1fr`. 7+ KPIs need dividers. Rigid 3-column grids signal AI wasn't paying attention.\n\n**Content-Tone Color Calibration.** Different emotional registers deserve different palettes:\n\n| Tone | `primary_color` | Feel |\n|------|-----------------|------|\n| Contemplative / Research | `#7C6853` warm brown | Grounded, editorial |\n| Technical / Engineering | `#3D5A80` navy | Precise, authoritative |\n| Business / Data | `#0F7B6C` deep teal | Confident, forward |\n| Narrative / Annual | `#B45309` amber | Warm, momentum |\n\n**Pre-output check:** *\"If you told someone 'an AI wrote this', would they believe it? If yes — find the most generic-looking part and redesign it.\"*\n\n### 7. Contract Enforcement Before Render\n\nv1.20.0's guard validation pipeline introduces a new principle: **intercept invalid IR before rendering, not repair after.**\n\n```\nIR → Guard (validate + downgrade) → Renderer → HTML\n              ↑\n              Block invalid input\n```\n\nThree sub-principles:\n\n| Principle | Implementation | Meaning |\n|-----------|----------------|---------|\n| **Zero-Drift Resolution** | Guard and renderer share the same `resolve_report_class` logic | Validation and rendering never diverge |\n| **Graceful Degradation** | Invalid components auto-downgrade (kpi→callout, chart→table, timeline→list) | Don't fail outright; fall back to safe substitute |\n| **Traceability** | `<meta name=\"ir-hash\">` embeds IR hash in HTML | Output is traceable to source IR |\n\n**Why it matters:**\n- Earlier `--review` was post-hoc repair; guard is pre-hoc interception\n- Prevents invalid IR from entering the render pipeline and producing unpredictable output\n- Zero-drift ensures guard's judgment and renderer's behavior stay aligned\n\nv1.23.0 extends this boundary to final HTML with `scripts/html_quality_gate.py`: rendered files must keep the standard shell controls, the declared theme's CSS fingerprint, typography/layout markers, and only real quantitative KPI values. This catches failures where IR is legal but the HTML hand-rolls a theme, drops summary/export controls, or smuggles placeholder/status text into KPI cards.\n\n### 8. Eval as Quality Boundary, Not Quality Score\n\nv1.15.0's eval workflow embodies this principle: **evals define boundaries, not scores.**\n\n```\ncompression → ir_contract → async_readability → render_integrity\n     ↓             ↓              ↓                  ↓\n   Source→IR     IR Spec        Reading UX          HTML Integrity\n```\n\n| Layer | What it checks | Where to fix |\n|-------|----------------|--------------|\n| compression | report_class, audience, decision_goal declared | SKILL.md |\n| ir_contract | timeline is real time, kpi is short value, chart schema legal | rendering-rules.md + contract_checks.py |\n| async_readability | BLUF, heading stack, takeaway after data | review-checklist.md |\n| render_integrity | shell IDs, report-summary JSON, no `:::` leak, theme fidelity | html-shell-template.md + html_quality_gate.py |\n\n**Failure Map rule:** Every real production failure → one new eval case. Not post-hoc discussion about \"feels wrong\", but direct pointer to the layer that needs fixing.\n\n**Rubric design:** Output structured JSON (verdict + scores + findings), not fuzzy scores. Downstream agents can parse and auto-repair.\n\n### 9. Contract Checks as Programmable Guardrails\n\n`contract_checks.py` makes IR spec executable:\n\n```python\n# Timeline must be real dates\nDATE_PATTERNS = [YYYY-MM-DD, YYYY-MM, Q1-4 YYYY, Day N, Week N]\n\n# KPI value must be a short real quantitative value; placeholders/status-only words fail\ndef is_short_kpi_value(value): ...\n\n# Placeholder pattern recognition\nPLACEHOLDER_RE = r\"\\[(INSERT VALUE|数据待填写)\\]\"\n```\n\n**Design principles:**\n- Spec declared in SKILL.md, validated in contract_checks.py\n- Guard calls contract_checks, zero drift\n- Every component has `auto_downgrade_target`: safe fallback path when invalid\n\nFinal HTML has a separate gate:\n\n```bash\npython scripts/html_quality_gate.py report.html\n```\n\n---\n\n## Install\n\n### Claude Code\n\nTell Claude: \"Install https://github.com/kaisersong/kai-report-creator\"\n\nOr manually:\n```bash\ngit clone https://github.com/kaisersong/kai-report-creator ~/.claude/skills/kai-report-creator\n```\n\nRestart Claude Code. Use as `/report`.\n\n### OpenClaw\n\n```bash\n# Via ClawHub (recommended)\nclawhub install kai-report-creator\n\n# Or manually\ngit clone https://github.com/kaisersong/kai-report-creator ~/.openclaw/skills/kai-report-creator\n```\n\n### Release Downloads\n\nThe current release is **v1.23.3**. Download source bundles from GitHub Releases:\n\n- https://github.com/kaisersong/kai-report-creator/releases/tag/v1.23.3\n- https://github.com/kaisersong/kai-report-creator/archive/refs/tags/v1.23.3.zip\n\n---\n\n## Usage\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `/report --from file.md` | Generate from an existing document |\n| `/report --from URL` | Generate from a web page |\n| `/report --plan \"topic\"` | Create a `.report.md` outline first |\n| `/report --generate file.report.md` | Render an outline to HTML |\n| `/report --review file.html` | Refine an existing report |\n| `/report --themes` | Preview the bundled theme gallery |\n| `/report --bundle --from file.md` | Offline HTML with inlined CDN assets |\n| `/report --theme <name> --from file.md` | Use a built-in or custom theme |\n| `/report [content]` | One-step: generate from description |\n\n### Typical Workflows\n\n**One-step generation:**\n```\n/report --from meeting-notes.md\n/report --from https://example.com/data-page --output market-analysis.html\n```\n\n**Two-stage workflow (complex content):**\n```\n/report --plan \"Q3 Sales Summary\" --from q3-data.csv\n# edit q3-sales-summary.report.md if needed\n/report --generate q3-sales-summary.report.md\n```\n\n**Review and refine:**\n```\n/report --review market-analysis.html\n```\n\n### Review Mode\n\nRun `--review` to improve existing reports with 13 checkpoints:\n\n```\n/report --review market-analysis.html\n```\n\n**Behavior:**\n1. Load `references/review-checklist.md`\n2. Apply hard rules automatically\n3. Apply AI-advised rules when confidence is high\n4. Save refined HTML back to file\n\nIf you want a structured change summary after review, use `references/review-report-template.md`.\n\n**One-pass automatic refinement** — not interactive approval.\n\n`--generate` also runs this checklist as a **silent final review** before writing HTML.\n\nThis review flow is the built-in **13-checkpoint review system**.\n\n**13 Checkpoints:**\n- KPI value length\n- Badge coverage\n- Summary card poster hierarchy\n- Timeline content validity\n- Export menu completeness\n- BLUF opening (Bottom Line Up Front)\n- Heading stack logic\n- Anti-template section headings\n- Prose-wall cleanup\n- Takeaway-after-data\n- Insight-over-data\n- Scan-anchor coverage\n- Conditional reader guidance\n\n---\n\n## Eval Workflow\n\nThis repo now includes a small, repo-contained eval harness focused on **async reading quality**, not slide-style presenter flow.\n\nRun it with:\n\n```bash\npython scripts/run-report-evals.py --root . --packet-dir .tmp/eval-packets\n```\n\nWhat it does:\n\n- Runs deterministic checks for `compression`, `ir_contract`, and `render_integrity`\n- Emits rubric-ready JSON packets for `async_readability` instead of hiding quality behind vibes\n- Uses repo-contained cases from `evals/report-cases.csv`\n\nKey files:\n\n- `evals/report-cases.csv` — living case set\n- `evals/rubric.schema.json` — structured grader output contract\n- `evals/failure-map.md` — where to fix each layer when a case fails\n- `evals/cases/*` — source + IR artifacts for each case\n\n### Captured-Run Skill Evals\n\n`scripts/run-report-evals.py` checks repo-contained source/IR/HTML artifacts. It is a deterministic regression gate, not a full agent-run skill eval.\n\nFor OpenAI-style skill evals, run the captured-run harness against checked-in\nfixtures or recorded traces:\n\n```bash\npython scripts/run-skill-evals.py --runner fixture --format json --json-out .tmp/skill-evals/results.json\n```\n\nThe harness reads `evals/report-skill-prompts.csv`, replays deterministic\nfixture metrics by default, and scores each case across four categories:\n\n- Outcome: report task completion and valid artifacts.\n- Process: skill flow, reference loading, guard validation, and HTML quality gate evidence from normalized runner metrics.\n- Style: template/theme/content conventions plus structured rubric grading for positive captured-run cases.\n- Efficiency: shell command count, repeated failures, token budgets, and wall-clock budget.\n\nRelease verification also uses fixture mode by default, so it does not require\nCodex, Claude, Qoder, network access, model auth, or any live agent environment:\n\n```bash\npython scripts/verify-release.py --include-skill-evals\n```\n\nPositive fixture cases use checked-in `tests/fixtures/skill-evals/*-style-rubric.json`.\nIf a positive case has no rubric, the harness marks it `eval_complete: false`\nand fails the case instead of hiding the coverage gap behind a green score.\n\nSaved baselines live under `evals/baselines/`. Compare a fresh run against the\nchecked-in baseline before changing skill behavior:\n\n```bash\npython scripts/run-skill-evals.py --runner fixture \\\n  --artifact-dir .tmp/check-skill-evals-fixture-artifacts \\\n  --format json \\\n  --json-out .tmp/check-skill-evals-fixture.json\n\npython scripts/compare-skill-eval-baseline.py \\\n  --old evals/baselines/2026-05-17-skill-evals-fixture.json \\\n  --new .tmp/check-skill-evals-fixture.json \\\n  --format text\n```\n\n`evals/baselines/2026-05-17-baseline-summary.md` records the saved scores:\nthe deterministic fixture baseline passes 6/6 with `incomplete: 0`,\n`average_score: 100.0`, and Style `25.0`, while the hardened Codex live\nbaseline is archival evidence of one manual runner sample. It is not part of\ndefault release verification. The comparator checks pass/fail state,\n`eval_complete`, total score, and each category score.\n\nManual live sampling is still possible, but it must be explicit because it\ndepends on the local runner environment:\n\n```bash\npython scripts/run-skill-evals.py --runner codex --run-live --format json --json-out .tmp/skill-evals/codex-live.json\n```\n\nFor complex reports, keep these IR frontmatter fields so evals can measure compression quality directly: `report_class`, `audience`, `decision_goal`, `must_include`, `must_avoid`.\n\nMaintainers can run the full release verification chain from one entry point:\n\n```bash\npython scripts/verify-release.py --root .\n```\n\nFor a single generated report, run the final HTML gate directly:\n\n```bash\npython scripts/html_quality_gate.py report.html\n```\n\n---\n\n## Features\n\n### Core\n\n- **Zero dependencies** — single `.html` file, works offline with `--bundle`\n- **8 built-in themes** — corporate-blue, minimal, dark-tech, dark-board, data-story, newspaper, regular-lumen, fangsong\n- **9 component types** — KPIs, charts (ECharts), tables, timelines, diagrams, code blocks, callouts, images, lists\n- **Report Review System** — 13-checkpoint automatic refinement\n- **AI-readable output** — 3-layer machine-readable structure for downstream agents\n\n### Interaction\n\n- **Summary card overlay** — `⊞ Summary` button opens a poster-style title card with abstract, KPIs, and section summaries\n- **Built-in export** — Print/PDF, PNG (Desktop), PNG (Mobile) via ↓ Export button\n- **Mobile responsive** — adapts to any screen size\n- **Bilingual** — full zh/en support with auto-detection\n\n### Output\n\n- **Custom themes** — `themes/<name>/theme.css` + `--theme <name>`\n- **Custom templates** — `template: ./my-brand-template.html` with placeholders\n- **Theme overrides** — `theme_overrides.primary_color` in frontmatter\n- **Offline bundles** — `--bundle` inlines all CDN assets\n\n---\n\n## Themes\n\n| Theme | Vibe | Best For |\n|-------|------|----------|\n| **corporate-blue** | Warm premium | Business reports, executive summaries |\n| **minimal** | Clean, academic | Research papers, analysis |\n| **dark-tech** | Engineering feel | Ops reports, technical docs |\n| **dark-board** | Dashboard style | Architecture, metrics dashboards |\n| **data-story** | Narrative-driven | Annual reports, growth stories |\n| **newspaper** | Editorial | Industry analysis, newsletters |\n| **regular-lumen** | Poster-style, warm-toned | Periodic work reports (日报/周报/月报 · 本周期复盘 + 下周期规划) · Kami-style reading experience |\n| **fangsong** | Traditional Chinese, warm brown | Formal reports with FangSong typography (标题衬线仿宋 + 正文非衬线仿宋) |\n\n### corporate-blue\n\nWarm business theme with subtle gradients. Default for executive-facing reports. Uses restrained primary color on key elements only — KPI values, section links, and one accent block per report.\n\n**Why it works:** Primary color appears on ≤3 element types, creating clear visual hierarchy without the \"AI flooded everything with blue\" look.\n\n---\n\n## Creating Custom Themes\n\n1. Create `themes/your-theme/` directory\n2. Write `theme.css` with CSS custom properties:\n```css\n:root {\n  --primary: #B45309;\n  --bg: #FAFAF9;\n  --text: #1C1917;\n  --font-heading: \"Merriweather\", serif;\n}\n```\n3. Run: `/report --theme your-theme --from file.md`\n\n**Example theme bundled:** `themes/warm-editorial/`\n\n---\n\n## Report Format (IR)\n\nFor complex reports, use `--plan` to generate a `.report.md` intermediate file.\n\n**Frontmatter:**\n```yaml\n---\ntitle: Q3 Sales Report\ntheme: corporate-blue\nauthor: Sales Team\ndate: 2024-10-08\nlang: en\ntoc: true\nabstract: \"Q3 revenue grew 12% YoY with record new customer acquisition.\"\n---\n```\n\n**Component blocks:**\n```\n:::kpi\nitems:\n  - label: Revenue\n    value: $2.45M\n    delta: ↑12%\n  - label: New Clients\n    value: 183\n    delta: ↑8%\n:::\n\n:::chart type=line title=\"Monthly Revenue\"\nlabels: [Jul, Aug, Sep]\ndatasets:\n  - label: Actual\n    data: [780000, 820000, 850000]\n:::\n\n:::timeline\n- 2024-10-15: Q4 targets released\n- 2024-10-31: Product launch\n:::\n\n:::callout type=tip\nKey insight goes here.\n:::\n```\n\nBadges remain optional HTML chips for scanability; they are not standalone IR tags. Timelines are strict chronological components and should use explicit time tokens such as `2024-10-15` or `Q4 2024`.\n\n---\n\n## For AI Agents\n\nOther agents can call report-creator programmatically:\n\n```\n# From document\n/report --from ./analysis.md --output summary.html\n\n# From URL\n/report --from https://example.com/report-page --theme data-story\n\n# Two-step with review\n/report --plan \"Market Analysis\" --from ./raw-data.md\n/report --generate market-analysis.report.md\n/report --review report.html\n```\n\n**Extracting structured data:**\n```python\nfrom bs4 import BeautifulSoup\nimport json\n\nsoup = BeautifulSoup(open(\"report.html\"), \"html.parser\")\nsummary = json.loads(soup.find(\"script\", {\"id\": \"report-summary\"}).string)\nprint(summary[\"title\"], summary[\"kpis\"])\n```\n\n---\n\n## Export\n\nEvery report has a built-in **↓ Export** button (bottom-right):\n\n| Option | How it works |\n|--------|--------------|\n| Print / PDF | Opens browser print dialog → Save as PDF |\n| PNG (Desktop) | Full page at 2× resolution |\n| PNG (Mobile) | Report body at 1170px wide (≈3× iPhone) |\n\n**Tip:** Uncheck \"Headers and footers\" in print dialog for clean PDFs.\n\n---\n\n## Use Case: Daily Work Report → Telegram\n\n```\nGenerate a report of today's work in dark-board style, export as IM image, send via Telegram.\n```\n\nOpenClaw will:\n1. Summarize tasks, decisions, next steps\n2. Render to `dark-board` HTML with KPIs and timeline\n3. Screenshot as 800px JPEG (animations auto-disabled for headless capture)\n4. Send directly to your Telegram channel\n\n---\n\n## Examples\n\n| File | Description |\n|------|-------------|\n| [examples/en/business-report.html](examples/en/business-report.html) | Q3 Sales Report (EN) |\n| [examples/en/business-report-reviewed-demo.html](examples/en/business-report-reviewed-demo.html) | Reviewed demo with stronger BLUF (EN) |\n| [examples/zh/business-report.html](examples/zh/business-report.html) | Q3 销售业绩报告（中文）|\n| [examples/review-reports/](examples/review-reports/) | Structured review report examples |\n\n---\n\n## Requirements\n\nNo dependencies. Works in any modern browser.\n\nFor offline bundles with `--bundle`: internet connection needed once to inline CDN assets.\n\n---\n\n## Compatibility\n\n| Platform | Version | Install path |\n|----------|---------|--------------|\n| Claude Code | any | `~/.claude/skills/kai-report-creator/` |\n| OpenClaw | ≥ 0.9 | `~/.openclaw/skills/kai-report-creator/` |\n\n---\n\n## Version History\n\n**v1.23.3** — No-agent eval gate release: make release verification use fixture skill evals by default, document that skill evals do not require Codex/Claude/Qoder/model auth/network access, and reject non-fixture runners unless a recorded trace or explicit live flag is provided.\n\n**v1.23.2** — Complete fixture rubric release: add checked-in positive-case style rubrics, require `eval_complete` for green captured-run results, compare completeness regressions, and refresh the deterministic fixture baseline to 6/6 passing at 100.0 average with Style 25.0.\n\n**v1.23.1** — Captured-run skill eval release: add OpenAI-style skill eval prompts, fixture and Codex trace runners, normalized timeout handling, baseline comparison, saved fixture/live baselines, release-verification integration, and README guidance for comparing future skill changes against the saved scores.\n\n**v1.23.0** — Final HTML quality gate release: add `scripts/html_quality_gate.py` to validate rendered shell IDs, theme CSS fidelity, regular-lumen/fangsong typography and layout markers, and KPI values; require every KPI card to use a real quantitative value; remove forced placeholder KPIs from periodic reports; fix dark-board status KPI examples; and add regression coverage for the failure modes.\n\n**v1.22.0** — Reference split and validator profile release: split oversized shell and rendering contracts into route-specific child references, add a reference index and validator-facing usage boundary artifacts, add a generated-cache cleanup gate to release verification, and document golden eval cases for external validators.\n\n**v1.21.2** — Packaging cleanup: remove the tracked `docs/` directory from GitHub and ClawHub packages, ignore the local docs symlink, and keep project documentation in `/Users/song/projects/mydocs/report-creator`.\n\n**v1.21.1** — Skill prompt budget release: compress `SKILL.md` into a thin routing contract under 320 lines, move shell metadata and duplicate-date details into references, add a size-budget regression test, and include that test in the fast verification path.\n\n**v1.21.0** — Late-context isolation and release hardening: require `--generate` to extract exactly one IR block from context, add context isolation helpers plus late-context eval runner, expand release verification and fast-test coverage, normalize footer/watermark shell metadata, and tighten bilingual doc-sync guardrails.\n\n**v1.20.1** — Design philosophy expansion: added §6 (Contract Enforcement Before Render), §7 (Eval as Quality Boundary), §8 (Contract Checks as Programmable Guardrails) documenting the guard pipeline and eval workflow principles.\n\n**v1.20.0** — Guard validation pipeline: Python guard (`scripts/guard_validate.py`) runs before HTML rendering with zero-drift report_class resolution, auto-downgrade invalid blocks (kpi→callout, chart→table, timeline→list, diagram→callout), IR hash embedding in `<meta name=\"ir-hash\">` for traceability, and guard integration tests.\n\n**v1.18.0** — Theme routing fixed for work reports: priority-ordered keyword matching now correctly routes weekly/daily/monthly reports to `regular-lumen` (first priority) and generic work progress reports to `corporate-blue` (fallback), instead of misrouting to dark-tech/dark-board due to overlapping keywords like \"项目/进展/状态\".\n\n**v1.17.1** — Resolve ClawHub version conflict (merge ClawHub v1.16.1 updates).\n\n**v1.17.0** — Merge ClawHub v1.16.1 updates + add watermark feature.\n\n**v1.16.0** — Minimal Kami borrowing, fully landed: add hard `anti-patterns.md` and `diagram-decision-rules.md`, introduce silent `spec-loading-matrix.md` plus optional `archetype` routing hints, add maintainer-side `scripts/verify-release.py`, and raise the Windows release suite to 134 passing tests.\n\n**v1.15.0** — IR contract hardening and eval foundation: split failures into `invalid_syntax` / `invalid_semantics` / `contract_conflict`, formalize `kpi` / `chart` / `timeline` / `diagram` schemas, demote `badge` to optional enhancement, add repo-contained eval cases plus `run-report-evals.py`, fix install paths to `kai-report-creator`, and bring the Windows release suite to 125 passing tests.\n\n**v1.14.2** — Export menu completeness enforced in the standard generate flow: require print/desktop/mobile/IM export entries plus JS bindings during pre-write shell validation and silent final review; add shell contract coverage so reports no longer regress to partial export menus.\n\n**v1.14.1** — Print/PDF export fix: preserve report background and force animated KPI/data blocks visible during print export; add print export regression coverage.\n\n**v1.14.0** — ECharts standard: unified all charts on ECharts (was Chart.js), added bar/line/radar/pie ECharts templates, grid bottom rule for rotated labels, line data integrity rule, 14 new chart rendering contract tests.\n\n**v1.13.0** — L2 HTML shell structure validation: 10 mandatory elements check in SKILL.md pre-write, design-quality.md §8, 30 new HTML shell contract tests (BUG-001 fix).\n\n**v1.9.0** — Report Review System: `--review` with 13 checkpoints; silent final review in `--generate`; L0/L1 quality layering.\n\n**v1.8.3** — KPI overflow fix: `.kpi-suffix` for long units; rendering rules updated.\n\n**v1.8.2** — Restrained color system: shared badges default to neutral; `data-report-mode=\"comparison\"` for entity colors.\n\n**v1.8.1** — Export background fix: resolve `--bg` before fallback.\n\n**v1.8.0** — Custom themes: `--theme <name>` loads `themes/<name>/`.\n\n**v1.6.0** — Sankey chart: `:::chart type=sankey` for flow diagrams.\n\n**v1.5.0** — Design Quality Baseline: 90/8/2 color law, KPI grid rules, content-tone calibration.\n\n**v1.4.0** — Summary card overlay with poster entry card behavior and KPI/section summaries.\n\n**v1.3.0** — Zero-dependency animations: staggered KPI bounce, timeline slide-in.\n\n**v1.0.0** — Initial release with 6 themes and 9 component types.\n\nFile v1.23.3:tests/fixtures/skill-evals/README.md\n\n# Captured Runner Trace Fixtures\n\nThese fixtures document the real Codex JSONL shape used by\n`scripts/run-skill-evals.py`. Parser support must be based on captured traces\nlike these, not guessed runner event names.\n\nObserved Codex JSONL shape:\n\n- Top-level events include `thread.started`, `turn.started`, `item.started`,\n  `item.completed`, and `turn.completed`.\n- Tool calls appear under `item` objects. Shell commands use\n  `item.type == \"command_execution\"` with `command`, `exit_code`, and `status`.\n- File reads and writes are not guaranteed to appear in the captured trace; the\n  current adapter only consumes explicit `file_read` and `file_write` items if a\n  future Codex trace includes them.\n- Token usage appears on `turn.completed` as `usage.input_tokens` and\n  `usage.output_tokens`.\n- Runner warnings can come from `item.type == \"error\"` events or from a nonzero\n  return code in a manually captured `codex exec` trace.\n\nNormalized fixture files use the runner-agnostic `normalized-v1` schema. Unit\ntests should score these normalized metrics directly so ordinary pytest never\ninvokes a live agent or network-backed runner.\n\nFile v1.23.3:themes/README.md\n\n# Custom Themes\n\nPlace folders here to add your own themes to kai-report-creator.\n\n## Directory Structure\n\n```\nthemes/\n  your-theme-name/\n    reference.md   ← Style description (AI reads and generates CSS variables)\n    theme.css      ← Direct CSS definitions (optional, takes priority over reference.md)\n```\n\nBoth files are optional and can be used independently or together:\n\n| Case | Behavior |\n|------|----------|\n| Only `reference.md` | AI reads style description and derives `:root` CSS variables |\n| Only `theme.css` | CSS variables used directly, fully predictable output |\n| Both present | `theme.css` takes priority; `reference.md` serves as style documentation |\n\n## Usage\n\n```bash\n/report --theme your-theme-name \"Report topic\"\n```\n\nOr specify in `.report.md` frontmatter:\n\n```yaml\ntheme: your-theme-name\n```\n\n## reference.md Format\n\n```markdown\n# Theme Name — Style Reference\n\nOne sentence description. Inspiration / aesthetic / mood.\n\n---\n\n## Colors\n\n​```css\n:root {\n  --primary:      #...;   /* Main color: headings, links, accents */\n  --bg:           #...;   /* Page background */\n  --surface:      #...;   /* Card background */\n  --text:         #...;   /* Body text */\n  --text-muted:   #...;   /* Secondary text */\n  --border:       #...;   /* Borders / dividers */\n}\n​```\n\n## Typography\n\nFont choices. Serif or sans-serif? Geometric or humanist? Google Fonts links.\n\n## Layout\n\nWhitespace style, card border-radius, max-width preferences.\n\n## Best For\n\nBrand reports, research docs, internal newsletters...\n```\n\n## theme.css Format\n\nDefine `:root` CSS variables to override the base theme defaults.\n\n```css\n:root {\n  --primary:      #C2410C;\n  --primary-light:#FFF7ED;\n  --accent:       #EA580C;\n  --bg:           #FFFBF7;\n  --surface:      #FFFFFF;\n  --text:         #1C1917;\n  --text-muted:   #78716C;\n  --border:       #E7E5E4;\n  --font-sans:    'Inter', system-ui, sans-serif;\n  --font-mono:    'JetBrains Mono', monospace;\n  --radius:       6px;\n}\n```\n\nSee `templates/themes/corporate-blue.css` for all available variables.\n\n## Notes\n\n- Directories starting with `_` (e.g. `_example-warm-editorial`) are ignored and won't appear in theme lists\n- Theme names support only letters, numbers, and hyphens: `my-brand`, `warm-editorial`\n- Custom themes take priority over built-in themes with the same name\n\n## Sharing Themes\n\nPublish your theme folder as a git repo — others clone it into their `themes/` directory:\n\n```bash\ngit clone https://github.com/yourname/report-theme-mybrand \\\n  ~/.claude/skills/report-creator/themes/mybrand\n```\n\nFile v1.23.3:_meta.json\n\n{\n  \"ownerId\": \"kn7bjv9d2ccsjqk1m4edthgtgx82fem8\",\n  \"slug\": \"kai-report-creator\",\n  \"version\": \"1.23.3\",\n  \"publishedAt\": 1779011514143\n}\n\nFile v1.23.3:references/anti-patterns.md\n\n# Report Anti-Patterns\n\nLoad this file before `--generate`. It is the report-specific anti-pattern layer on top of `references/design-quality.md` and `references/review-checklist.md`.\n\nThese rules are intentionally blunt. If a draft triggers one of these patterns, rewrite it before writing HTML.\n\n## Contract Shape\n\nEach anti-pattern entry should answer the same four questions.\n\n## Symptom\n\nWhat the bad output usually looks like in IR, prose, or HTML.\n\n## Why It Hurts\n\nWhy the pattern makes async reading slower, noisier, or less trustworthy.\n\n## Preferred Replacement\n\nWhich component or prose pattern should replace the bad pattern.\n\n## Rewrite Rule\n\nOne direct instruction that the generator or reviewer can apply without debate.\n\n## `fake-kpi`\n\n- Symptom: KPI cards are filled with placeholders, status words, long explanatory sentences, or qualitative claims that are not actually metrics.\n- Why It Hurts: It creates a fake visual anchor and tells the reader that the report has hard numbers when it does not.\n- Preferred Replacement: `callout`, prose, or `table`.\n- Rewrite Rule: If the source does not provide a short real numeric metric, do not emit `:::kpi`; downgrade to `callout`, `timeline`, or `table`.\n\n## `decorative-chart`\n\n- Symptom: A chart appears mainly to decorate a section, restate obvious text, or visualize placeholder-only values.\n- Why It Hurts: It adds scanning cost without increasing understanding and can imply false analytical rigor.\n- Preferred Replacement: prose, `table`, or a short `callout`.\n- Rewrite Rule: If the reader learns nothing new from the chart shape, remove the chart and state the takeaway directly.\n\n## `pseudo-timeline`\n\n- Symptom: A timeline is used for parallel principles, capability buckets, or unordered stages that are not truly chronological.\n- Why It Hurts: The component communicates sequence and causality that the content does not actually have.\n- Preferred Replacement: `list`, prose, or `callout`.\n- Rewrite Rule: If items can be reordered without changing meaning, do not use `:::timeline`.\n\n## `template-heading`\n\n- Symptom: Section headings read like empty labels such as \"Overview\", \"Summary\", \"核心能力\", or \"Next Steps\".\n- Why It Hurts: Headings stop carrying argument structure, so the document becomes harder to skim and harder to remember.\n- Preferred Replacement: information-bearing headings that state a claim, implication, or contrast.\n- Rewrite Rule: Rewrite noun-label headings into content-specific statements before render.\n\n## `badge-quota-thinking`\n\n- Symptom: Badges are inserted just to hit a count or to make the page feel \"busy enough\".\n- Why It Hurts: Optional scan anchors turn into noise, and the reader can no longer tell which chips actually matter.\n- Preferred Replacement: no badge at all, or one status/category/entity badge only where it clarifies the content.\n- Rewrite Rule: Add a badge only when it disambiguates status, category, or entity identity; never fill a quota.\n\n## `color-flood`\n\n- Symptom: Accent colors spread across headings, KPI values, badges, charts, dividers, and callouts at the same time.\n- Why It Hurts: The page loses hierarchy because everything is trying to be the focal point.\n- Preferred Replacement: neutral text with one restrained structural accent.\n- Rewrite Rule: Keep the main reading surface neutral and reserve accent color for one clear job at a time.\n\n## `summary-without-judgment`\n\n- Symptom: The opening summary repeats background or facts but never states what matters or why the reader should care.\n- Why It Hurts: Async readers do not know the report's conclusion, decision frame, or next action within the first screen.\n- Preferred Replacement: BLUF-style opening prose.\n- Rewrite Rule: Open with purpose plus judgment, not background plus scene-setting.\n\n## `action-without-decision-context`\n\n- Symptom: The report ends with recommendations or next steps that are detached from any stated decision, tradeoff, or threshold.\n- Why It Hurts: The actions feel generic because the reader cannot tell what decision they are supposed to support.\n- Preferred Replacement: action block tied to a named decision, condition, or trigger.\n- Rewrite Rule: Every action section must state what decision it supports, what signal triggers it, or what risk it addresses.\n\nFile v1.23.3:references/design-quality.md\n\n# Design Quality Baseline\n\nThis file defines the design quality rules for every generated report. Load alongside `rendering-rules.md` during `--generate` mode. These rules exist to prevent AI-slop patterns and enforce visual discipline.\n\n## 1. The 90/8/2 Color Law\n\nEvery report must follow this color allocation:\n\n| Share | Role | Variable | Usage |\n|-------|------|----------|-------|\n| **90%** | Neutral surface | `--bg`, `--surface`, `--text` | Background, body text, cards |\n| **8%** | Structural color | `--primary` | Section borders, one accent block, h2 underlines |\n| **2%** | Bullet point | `--accent-pop` (default = `--primary` at full opacity) | At most 1-2 precise hits: a single KPI value, one callout border, one chart series |\n\n**Violations to avoid:**\n- `var(--primary)` used on heading text, KPI values, chart bars, callout borders, TOC links, AND badges simultaneously → this is a primary-color flood\n- Every KPI card a different accent color → accent system should feel like seasoning, not confetti\n- Using more than 2 accent colors per page (chart series excluded)\n\n## 2. Typography: 10:1 Scale Ratio\n\nThe largest text element on any page must be ≥ 10× the smallest readable element.\n\n| Element | Min size | Max size |\n|---------|----------|---------|\n| Fine print, badges, meta | 11px | — |\n| Body text | 15px | — |\n| h3 | 17px | — |\n| h2 | 20px | — |\n| Report title | 2.6rem+ | — |\n\n**Apply to report title:** Minimum `font-size: 2.8rem`. For strong content topics, push to `3.5–4rem` with `line-height: 1.05` and `letter-spacing: -0.03em`. The title should feel like an anchor, not a label.\n\n**Apply to section headings:** `h2` gets a subtle left border or underline using `--primary` at 8% allocation — not a background color.\n\n**Letter-spacing upper limit:** Body text and prose must never exceed `letter-spacing: 0.05em`. Wide letter-spacing on body text (>0.05em) breaks word shape recognition and slows reading. Negative letter-spacing is acceptable for titles (`-0.03em`) and headings (`-0.02em`).\n\n## 3. KPI Grid Column Rules\n\nDo not default all KPI grids to 3 columns. Match columns to KPI count for better proportion:\n\n| KPI count | Grid columns | CSS |\n|-----------|-------------|-----|\n| 1–2 | 2 columns | `grid-template-columns: repeat(2, 1fr)` |\n| 3 | 3 columns | `grid-template-columns: repeat(3, 1fr)` |\n| 4 | 2×2 | `grid-template-columns: repeat(2, 1fr)` |\n| 5–6 | 3 columns (last row 2) | `grid-template-columns: repeat(3, 1fr)` |\n| 7+ | 3 columns with dividers between groups | `grid-template-columns: repeat(3, 1fr)` + `gap: 0.5rem 1rem` |\n\n**Non-equal widths:** When one KPI is the \"hero\" metric, use `grid-template-columns: 2fr 1fr 1fr` or `1.5fr 1fr` to create visual hierarchy.\n\n## 4. Forbidden Patterns (Anti-AI-Slop)\n\nThese patterns make a report look instantly AI-generated. Do not produce them:\n\n| ❌ Forbidden | ✅ Instead |\n|---|---|\n| Every section starts with a one-sentence definition: \"X is a...\" | Start sections in the middle of the idea, with data or a claim |\n| 3-equal-column KPI grid when you have 4 KPIs | Use 2×2 grid |\n| All h2 headings are 3–4 words (\"Overview\", \"Key Findings\", \"Next Steps\") | Allow longer, specific headings that reflect actual content |\n| `border-radius: 12px` on every card and button | Mix radii: sharp (2px) for data elements, soft (8px) for prose cards |\n| Callout boxes for every key insight | Use `.highlight-sentence` for inline highlights; reserve callout for truly exceptional notes |\n| Same font size for every paragraph | Vary prose density: lead paragraphs slightly larger (16px), supporting detail smaller (14px) |\n| Symmetrical two-column layouts everywhere | Use `2fr 1fr` or `3fr 1fr` — asymmetry implies hierarchy |\n| Inter as body font | Use system-ui / -apple-system stack (already in themes) |\n| `:::kpi` block with placeholder values (`[INSERT VALUE]` / `[数据待填写]`) in any report | Use `:::callout`, `:::timeline`, or `:::table` as the visual anchor instead |\n| `:::kpi` value is status-only or contains a full sentence/descriptive paragraph (e.g. \"通过\" or \"支持CSV/Excel等表格文件的统计汇总、趋势分析、数据可视化\") | KPI value = short real number only. Status goes in badges; explanations go in prose, callout, or table cell |\n| `:::chart` with all-placeholder data in a text-heavy (narrative/mixed) section | Use `:::diagram` (flowchart/mindmap) or a `highlight-sentence` paragraph |\n| Nested cards (card inside a card) | Flatten hierarchy — use indentation, sub-lists, or adjacent blocks instead |\n| Default text alignment centered everywhere | Left-align body text; center only the title and hero metrics |\n| Glassmorphism (blur/backdrop-filter) as decoration | Solid or subtly tinted backgrounds; blur signals no information |\n| `text-align: justify` on body text | Left-align — justified text creates rivers of whitespace |\n| Using monospace fonts to signal \"technical/developer\" vibes | System sans-serif for all prose; reserve monospace for actual code blocks only |\n| Icon tile (small rounded-square icon container) stacked above section heading | Inline icon in heading or skip entirely — decorative icon squares add no information |\n| `text-transform: uppercase` on body text (all-caps paragraphs) | Normal case for body; all-caps only for small labels or chips |\n\n## 5. Content-Tone Color Calibration\n\nWhen generating `theme_overrides` in `--plan` mode, suggest a tone-appropriate primary color based on content keywords:\n\n| Content tone | Trigger keywords | Suggested `primary_color` override | Feel |\n|---|---|---|---|\n| **Contemplative / Research** | 认知、思维、本质、意义、哲学、研究、白皮书、学术 / philosophy, cognition, research, academic | `#7C6853` (warm brown) | Grounded, editorial |\n| **Technical / Engineering** | 架构、系统、API、性能、部署、代码、工程 / architecture, system, API, performance, engineering | `#3D5A80` (navy blue) | Precise, authoritative |\n| **Business / Data** | 销售、营收、KPI、增长、季报、业绩 / sales, revenue, KPI, growth, quarterly | `#1F6F50` (pine green) | Restrained, commercial, premium |\n| **Narrative / Annual** | 故事、增长、复盘、年度 / story, growth, retrospective, annual | `#B45309` (amber) | Warm, momentum |\n| **Editorial / News** | 新闻、行业、趋势、观察 / news, industry, trend | `#1C1C1E` (near-black) | Authoritative, print |\n\nNo override needed if the default theme color already matches the tone.\n\n## 6. Semantic Highlight Extraction\n\nWhen rendering prose sections, identify **key-insight sentences** and apply `.highlight-sentence`:\n\nA sentence qualifies if it meets ALL of:\n- Stands alone as its own paragraph\n- ≤ 45 characters (Chinese) or ≤ 80 characters (English)\n- Declarative/conclusive tone (states a fact, principle, or finding)\n- Not already inside a `:::callout` or `:::kpi` block\n\n```html\n<p class=\"highlight-sentence\">真正的增长来自产品本身，而非渠道。</p>\n```\n\nCSS for `.highlight-sentence` (add to shared.css section in html-shell-template.md):\n```css\n.highlight-sentence {\n  font-size: 1.15rem;\n  font-weight: 700;\n  color: var(--primary);\n  border-left: 3px solid var(--primary);\n  padding-left: 1rem;\n  margin: 1.5rem 0;\n  line-height: 1.5;\n}\n```\n\n### Narrative Cadence Blocks\n\nFor `narrative` and `mixed` reports, do not stop at \"shorter paragraphs\". The better rhythm is:\n\n`claim -> explanation -> scan anchor`\n\nUse these render-time prose upgrades when the section supports them:\n\n- `lead-block` — for a decisive opening sentence that frames the section before detail.\n- `section-quote` — for a short judgment or implication that should read like a pull-quote.\n- `action-grid` — for 2-5 concrete moves, contrasts, or recommendations that scan better as cards than as one long list.\n\nThese are **prose/HTML patterns, not IR tags**. Narrative cadence blocks are optional upgrades, not a quota. The renderer should promote qualifying prose into these blocks instead of leaving every narrative section as paragraph + list.\n\n- Never use them just to break up a page visually.\n- Do not stack multiple cadence blocks in one section unless the source clearly contains multiple distinct beats.\n- If uncertain, keep plain prose plus one stronger scan anchor instead of forcing a cadence block.\n\n```html\n<div class=\"lead-block\">先抓主线：这部分讨论的不是聊天入口，而是委托边界。</div>\n<div class=\"section-quote\">真正决定信任的，不是入口，而是编排层。</div>\n<div class=\"action-grid\">\n  <div class=\"action-card\"><strong>先做</strong><p>先把意图和边界收清楚。</p></div>\n  <div class=\"action-card\"><strong>再做</strong><p>再把行动回执和恢复路径补上。</p></div>\n</div>\n```\n\n### Summary Card Hierarchy\n\nSummary cards should read like posters, not metadata panels.\n\n- Prefer `poster_title` + `poster_subtitle` only when the report's core judgment is stronger than the document title.\n- The poster title should dominate the card visually.\n- After fixing wrap quality, do not leave the poster title undersized; it should still feel like the dominant visual mass on the left panel.\n- Keep subtitle below the poster title, not merged into one dense headline.\n- On the left panel, keep only the title hierarchy and one short closing sentence near the bottom.\n- Leave visible breathing room around the title; do not let the left panel turn into a paragraph block.\n- Do not artificially squeeze the subtitle or closing sentence into a narrow column that wastes available width.\n- Do not duplicate audience, author/date byline, or explanatory filler inside the summary card.\n- Remove chips, bottom notes, and metadata filler if they weaken the poster read.\n\n## 7. Pre-Output Self-Check\n\nBefore writing the final HTML, answer each question. Fix any \"no\":\n\n- [ ] Does the report title feel like an anchor, or just a label? (target: anchor — at least 2.8rem)\n- [ ] Is `var(--primary)` used in more than 4 distinct element types? If yes → reduce\n- [ ] Are any KPI grids 3 columns when the count is 4 or 7+? If yes → fix column rule\n- [ ] Are there 3+ consecutive all-prose sections with no component? If yes → insert visual anchor\n- [ ] Do all section headings feel like AI-generated template phrases? If yes → make them content-specific\n- [ ] Is every card's `border-radius` identical? If yes → vary radii between data elements and prose cards\n- [ ] Does any `:::kpi` or `:::chart` block contain placeholder values (`[INSERT VALUE]` / `[数据待填写]`)? If yes → replace with `:::callout`, `:::timeline`, `:::table`, or `:::diagram`\n- [ ] Does any `.kpi-value` lack a real number, or contain a sentence/paragraph longer than 8 Chinese chars / 3 English words? If yes → move status/explanation to badges, prose, callout, or table; keep KPI value quantitative\n- [ ] Does the report use `.badge` elements in at least 2 locations (section headers, KPI cards, table cells, timeline items)? If no → add badges at appropriate locations\n- [ ] **If you told someone \"an AI wrote this\", would they immediately believe it?** If yes → find the most generic-looking part and redesign it\n- [ ] Is any prose line wider than ~75 characters (Chinese: ~50 chars)? If yes → constrain with `max-width` or `max-inline-size` in CSS\n- [ ] Is any `text-align: justify` applied to body text? If yes → change to left-align\n- [ ] Is any background `#000000` or `#000`? If yes → use `#111` or `#181818` instead — pure black is harsh and unnatural\n- [ ] Is any gray text (`#888`, `#999`, `var(--text-muted)`) placed on a colored background? If yes → darken text or lighten background for WCAG AA contrast\n- [ ] Is any body text `letter-spacing` greater than `0.05em`? If yes → reduce or remove\n- [ ] Are there nested cards (a `.kpi-card`, `.callout`, or `.table-wrapper` inside another card)? If yes → flatten hierarchy\n- [ ] Is any card or container padding less than `0.75rem` (data elements) or `0.9rem` (prose)? If yes → increase — cramped padding makes reports feel cheap\n\n## 8. L2 HTML Shell Structure (MANDATORY)\n\nThese checks verify the HTML shell was built according to `references/html-shell-template.md`. **This is NOT about content quality — it's about the container itself.**\n\n**Root cause:** BUG-001 (2026-04-13). AI skipped template structure, generated obsolete TOC implementation and lost summary card + export buttons. Prevention: check the shell before writing.\n\n### 8.1 Required Elements\n\nEvery generated report HTML **MUST** contain these elements. If any are missing, reconstruct from `html-shell-template.md`:\n\n| Element | Required ID/class | Purpose |\n|---------|------------------|---------|\n| TOC toggle button | `id=\"toc-toggle-btn\"` + class `toc-toggle` | Visible `☰` button, top-left corner |\n| TOC sidebar nav | `id=\"toc-sidebar\"` + class `toc-sidebar` | Sliding sidebar with section links |\n| Summary card button | `id=\"card-mode-btn\"` + class `card-mode-btn` | `⊞ 摘要卡` button next to h1 title |\n| Summary card overlay | `id=\"sc-overlay\"` + class `sc-overlay` | Modal overlay for summary card |\n| Summary card | `id=\"sc-card\"` + class `sc-card` | Two-panel summary card (injected by JS) |\n| Export button | `id=\"export-btn\"` + class `export-btn` | `↓ 导出` button, bottom-right |\n| Export menu | `id=\"export-menu\"` + class `export-menu` | Dropdown with Print/PNG/IM options |\n| Export item: print | `id=\"export-print\"` | `打印 / PDF` entry |\n| Export item: desktop | `id=\"export-png-desktop\"` | `桌面截图` entry |\n| Export item: mobile | `id=\"export-png-mobile\"` | `手机长图` entry |\n| Export item: IM | `id=\"export-im-share\"` | `IM 长图` entry |\n| JSON summary block | `type=\"application/json\" id=\"report-summary\"` | Machine-readable report metadata |\n| Report mode attribute | `data-report-mode=\"[default\\|comparison]\"` on `<body>` | Semantic mode flag |\n\n**Important:** `id=\"export-menu\"` by itself is not enough. The menu is incomplete unless all four export items above exist. If any one is missing, rebuild the entire export block from `html-shell-template.md` rather than leaving a partial menu.\n\n### 8.2 TOC JavaScript Contract\n\nThe TOC JS logic **MUST** include:\n\n- `scheduleClose` function with **≥100ms delay** (prevents instant-close bug)\n- Both `tocBtn` and `tocSidebar` must have `mouseenter` / `mouseleave` handlers\n- `locked` state with click-to-lock toggle on `tocBtn`\n\n### 8.3 Edit Mode (always present)\n\n- `id=\"edit-hotzone\"` — bottom-left corner hotzone\n- `id=\"edit-toggle\"` — edit toggle button\n\n### 8.4 CSS Assembly Verification\n\nBefore writing, verify CSS includes:\n\n- `.toc-toggle` and `.toc-sidebar` styles (from html-shell-template.md §163-198)\n- `.sc-card`, `.sc-left`, `.sc-right`, `.sc-overlay` styles (summary card)\n- `.export-btn`, `.export-menu`, `.export-item` styles\n- `.edit-hotzone`, `.edit-toggle` styles\n- `@media print` rules hiding UI chrome\n- Export JS bindings for all four entries: `export-print`, `export-png-desktop`, `export-png-mobile`, `export-im-share`\n\n## L1 Content Review\n\nFor content, structure, and reading-flow checks, see [review-checklist.md](review-checklist.md).\n\n**L0 (Visual)**: This file — color, typography, layout, anti-slop presentation rules.\n**L1 (Content)**: `review-checklist.md` — BLUF opening, heading logic, prose walls, takeaways, scan anchors.\n**L2 (Shell Structure)**: This file §8 — HTML shell element existence, TOC JS contract, edit mode, CSS assembly.\n\n**When to apply:**\n\n- `--generate`: run a **silent final review pass** using the L1 checklist before writing HTML, then run L2 shell structure checks before writing\n- `--review`: run the same one-pass automatic refinement explicitly against an existing report\n\nFile v1.23.3:references/diagram-decision-rules.md\n\n# Diagram Decision Rules\n\nLoad this file whenever a diagram or diagram-like structure is being considered.\n\n## Core Rule\n\nOnly draw a diagram when it materially reduces comprehension cost.\n\nIf the same idea is already clear in one short paragraph or list, keep it as prose.\n\n## Go / No-Go Check\n\nUse a diagram only when the content is primarily about one or more of these relationship types:\n\n- `directionality`\n- `dependency`\n- `branching`\n\nThese are the cases where a diagram can remove ambiguity instead of adding visual ceremony.\n\n## No-Go Cases\n\nParallel points should stay as prose or list.\n\nThree to five principles should stay as prose or list.\n\nIf prose explains it clearly, do not draw a diagram.\n\nIf the structure is only \"a few named buckets\", prefer prose, `callout`, or `list`.\n\n## Type Selection\n\n- Use `sequence` only when the message flow between actors matters.\n- Use `flowchart` only when the reader must follow a path, branch, or decision tree.\n- Use `tree` only when the hierarchy itself is the message.\n- Use `mindmap` only when the center-to-branch expansion is truly the useful structure.\n\n## Downgrade Rule\n\nPreferred downgrade: `callout` or `list`.\n\nWhen the content is still useful but not diagram-worthy, keep the content and downgrade the component rather than forcing a schematic shape.\n\nFile v1.23.3:references/generate-flow.md\n\n# Generate Flow\n\nSteps for `--generate` mode:\n\n1. Read IR input only. With no file given, extract exactly one valid IR block from context. Treat this as IR from context, not chat history. If zero or multiple are present, stop and ask for an explicit file or single IR block. Never render the surrounding conversation.\n2. Load reference files minimally but reliably; load only the references that materially help the current render path. Standard HTML shell generation always loads the shell entry plus all `references/html-shell/*.md`; component rules load by IR inventory via `references/rendering-rules.md`.\n3. Parse frontmatter and resolve `lang`, `theme`, `report_class: mixed` default, `archetype`, date display, chart mode, TOC, animation, template, and theme overrides.\n4. Run guard validation before rendering:\n   - Use `scripts/guard_validate.py` with IR text from file or extracted context.\n   - If fatal metadata is missing, stop and report the error.\n   - If a block is invalid, apply its `auto_downgrade_target` (`kpi -> callout`, `chart -> table`, `timeline -> list`, `diagram -> callout`) and mention the downgrade.\n5. Render components using `references/rendering-rules.md`, `references/design-quality.md`, and the path-specific `references/rendering/*.md` files selected from the IR.\n6. Build the standard shell from `references/html-shell-template.md` plus all `references/html-shell/*.md`; follow Shell metadata, version/theme metadata, export completeness, and the duplicate-date guard.\n7. Compute and embed `<meta name=\"ir-hash\" content=\"sha256:[ir-hash]\">` from the exact IR text, not the file path.\n8. Assemble CSS through `references/theme-css.md`: theme before-marker, shared CSS, theme post-shared override, TOC/shell CSS, frontmatter overrides.\nSteps 9-12 (quality gates) are defined in SKILL.md and always run after these setup steps.\n\nFile v1.23.3:references/html-shell-template.md\n\n# HTML Shell Template\n\nEntry point for generating the final self-contained HTML report. Keep this file small and load it before shell child references. It owns the non-negotiable shell contract; child files carry the detailed CSS/HTML/JS fragments.\n\n## Standard Shell Load Set\n\nFor every standard `--generate` render, load all of these shell references:\n\n- `references/html-shell-template.md` — this entry contract and load map\n- `references/html-shell/core-structure.md` — document skeleton, title/meta, report-summary, sections, footer/watermark\n- `references/html-shell/shared-component-css.md` — shared component and rhythm CSS\n- `references/html-shell/toc-edit-summary.md` — TOC overlay, edit mode, and motion JS\n- `references/html-shell/summary-card.md` — summary card CSS/HTML/JS\n- `references/html-shell/export.md` — export button/menu, print/PDF, desktop PNG, mobile image, IM image bindings\n- `references/html-shell/print-responsive.md` — print and mobile constraints\n- `references/theme-css.md` — selected theme CSS\n\nDo not make `html-shell/export.md` optional in the standard shell. Export has regressed before and must remain part of the default render path.\n\n## Minimal Skeleton\n\n    <!DOCTYPE html>\n    <!-- kai-report-creator v[version] -->\n    <html lang=\"[lang]\" data-template=\"kai-report-creator\" data-version=\"[version]\" data-theme=\"[theme]\">\n    <head>\n      <meta charset=\"UTF-8\">\n      <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n      <meta name=\"generator\" content=\"kai-report-creator [theme-display] v[version]\">\n      <meta name=\"ir-hash\" content=\"sha256:[ir-hash]\">\n      <title>[title]</title>\n      <style>\n        [selected theme CSS]\n        [shared shell CSS from child references]\n      </style>\n    </head>\n    <body data-report-mode=\"[default|comparison]\" class=\"[add no-toc/no-animations flags only when requested]\">\n      [required shell controls]\n      <div class=\"main-with-toc\"><div class=\"report-wrapper\">[report content]</div></div>\n      [required shell scripts]\n    </body>\n    </html>\n\n## Required IDs and Attributes\n\nEvery standard shell must include these markers:\n\n- `data-template=\"kai-report-creator\"`\n- `data-version=\"[version]\"`\n- `data-theme=\"[theme]\"`\n- `<meta name=\"generator\" content=\"kai-report-creator [theme-display] v[version]\">`\n- `<meta name=\"ir-hash\" content=\"sha256:[ir-hash]\">`\n- `id=\"report-summary\"`\n- `id=\"toc-toggle-btn\"`\n- `id=\"toc-sidebar\"`\n- `id=\"card-mode-btn\"`\n- `id=\"sc-overlay\"`\n- `id=\"edit-hotzone\"`\n- `id=\"edit-toggle\"`\n- `id=\"export-btn\"`\n- `id=\"export-menu\"`\n- `id=\"export-print\"`\n- `id=\"export-png-desktop\"`\n- `id=\"export-png-mobile\"`\n- `id=\"export-im-share\"`\n\nIf any export item or JS binding is missing, rebuild the whole export block from `references/html-shell/export.md` instead of patching one button.\n\n## Duplicate-Date Guard\n\nThe shell owns title/date metadata. Do not pass through Pandoc title metadata such as `<header id=\"title-block-header\">` or `<p class=\"date\">...</p>`; passing both through creates duplicate date output.\n\nStandard title/meta structure lives in `references/html-shell/core-structure.md`.\n\n## Footer and Watermark Metadata\n\nStandard shell metadata is `kai-report-creator v[version] [theme]`.\n\n- Standard shell emits both visible footer and hidden `data-watermark` with that deterministic string.\n- Degradation is allowed for constrained or custom templates: keep at least one footer or watermark carrier with version/theme metadata.\n- Replace stale prose such as `Generated by kai-report-creator` because it loses version/theme metadata.\n\nRequired standard markers:\n\n    <div class=\"report-footer\">kai-report-creator v[version] [theme]</div>\n    data-watermark=\"kai-report-creator v[version] [theme]\"\n\n## Report Summary JSON\n\nAlways include `id=\"report-summary\"` as `<script type=\"application/json\">`. It must contain at least `title`, `sections`, and `kpis`. Optional poster fields are `poster_title`, `poster_subtitle`, and `poster_note`; see `references/html-shell/toc-edit-summary.md` for rendering.\n\n## Entry-Only Fallback\n\nIf only this entry file is available, do not improvise. Preserve the red lines:\n\n1. No raw Pandoc title block or duplicate date.\n2. Export menu must include all four items and their JS bindings.\n3. `report-summary` JSON must exist.\n4. At least one footer or watermark carrier must include version/theme metadata.\n5. Load the child references before generating the full standard shell.\n\n## Final HTML Gate\n\nAfter assembling the HTML, validate the actual output with `scripts/html_quality_gate.py <output.html>`.\n\nThis catches failures that IR validation cannot see:\n\n- missing standard shell controls such as summary card, TOC, edit mode, and export entries\n- a `data-theme` value that does not match the embedded theme CSS\n- font/layout drift caused by hand-written body styles\n- KPI cards or `report-summary.kpis` containing placeholders or status-only values\n\nIf the gate fails, rebuild from the standard shell and selected theme CSS before reporting the file as complete.\n\nFile v1.23.3:references/html-shell/core-structure.md\n\n# HTML Shell Core Structure\n\n# HTML Shell Template\n\nWhen generating the final HTML report, produce a complete self-contained HTML file using this structure. Replace all `[...]` placeholders with actual content.\n\n    <!DOCTYPE html>\n    <!-- kai-report-creator v[version] -->\n    <html lang=\"[lang]\" data-template=\"kai-report-creator\" data-version=\"[version]\" data-theme=\"[theme]\">\n    <head>\n      <meta charset=\"UTF-8\">\n      <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n      <meta name=\"generator\" content=\"kai-report-creator [theme-display] v[version]\">\n      <meta name=\"ir-hash\" content=\"sha256:[ir-hash]\">\n      <title>[title]</title>\n\n      <!-- CDN libraries (add only what's needed; omit if --bundle, inline instead) -->\n      <!-- If any :::chart blocks present: -->\n      <!-- <script src=\"https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js\"></script> -->\n      <!-- If any :::code blocks present: -->\n      <!-- <link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/highlight.js@11/styles/github.min.css\"> -->\n      <!-- (use github-dark.min.css for dark-tech theme) -->\n      <!-- <script src=\"https://cdn.jsdelivr.net/npm/highlight.js@11/lib/highlight.min.js\"></script> -->\n      <!-- <script>document.addEventListener('DOMContentLoaded', () => hljs.highlightAll());</script> -->\n\n      <!-- AI Readability Layer 1: Report Summary JSON -->\n      <!-- Always present, even if not visible to humans -->\n      <script type=\"application/json\" id=\"report-summary\">\n      {\n        \"title\": \"[title]\",\n        \"author\": \"[author or empty string]\",\n        \"date\": \"[date]\",\n        \"abstract\": \"[abstract from frontmatter, or auto-generate a 1-sentence summary of the report content]\",\n        \"poster_title\": \"[optional stronger summary-card title; opt-in only when the core judgment should read like a poster headline]\",\n        \"poster_subtitle\": \"[optional subtitle shown below the poster title; only used when poster_title is present]\",\n        \"poster_note\": \"[optional one-sentence closing line for the left panel; falls back to a short sentence from abstract]\",\n        \"sections\": [\"[heading of section 1]\", \"[heading of section 2]\", \"...\"],\n        \"kpis\": [\n          {\"label\": \"[label]\", \"value\": \"[display value]\", \"trend\": \"[trend text or empty]\"}\n        ]\n      }\n      </script>\n\n      <!-- Edit mode (always present) -->\n      <div class=\"edit-hotzone\" id=\"edit-hotzone\"></div>\n      <button class=\"edit-toggle\" id=\"edit-toggle\" title=\"Edit mode (E)\">✏ Edit</button>\n\n      <!-- Export (always present) -->\n      <!-- lang:en labels: \"↓ Export\" / \"🖨 Print / PDF\" / \"🖥 Save PNG (Desktop)\" / \"📱 Save PNG (Mobile)\" / \"💬 IM Image\" -->\n      <!-- lang:zh labels: \"↓ 导出\"  / \"🖨 打印 / PDF\"  / \"🖥 保存图片（桌面）\"    / \"📱 保存图片（手机）\"  / \"💬 IM 分享长图\"   -->\n      <div class=\"export-menu\" id=\"export-menu\">\n        <button class=\"export-item\" id=\"export-print\">[🖨 Print / PDF|🖨 打印 / PDF]</button>\n        <button class=\"export-item\" id=\"export-png-desktop\">[🖥 Save PNG (Desktop)|🖥 保存图片（桌面）]</button>\n        <button class=\"export-item\" id=\"export-png-mobile\">[📱 Save PNG (Mobile)|📱 保存图片（手机）]</button>\n        <button class=\"export-item\" id=\"export-im-share\">[💬 IM Image|💬 IM 长图]</button>\n      </div>\n      <button class=\"export-btn\" id=\"export-btn\" title=\"Export\">[↓ Export|↓ 导出]</button>\n\n      <!-- Floating TOC (omit entirely if toc:false) -->\n      <!-- TOC label localization: lang:en → aria-label=\"Contents\" / \"Table of Contents\" / <h4>Contents</h4> -->\n      <!--                         lang:zh → aria-label=\"目录\" / \"报告目录\" / <h4>目录</h4> -->\n      <button class=\"toc-toggle\" id=\"toc-toggle-btn\" aria-label=\"[Contents|目录]\" aria-expanded=\"false\">☰</button>\n      <nav class=\"toc-sidebar\" id=\"toc-sidebar\" aria-label=\"[Table of Contents|报告目录]\">\n        <h4>[Contents|目录]</h4>\n        <!-- Generate one <a> per ## heading and one per ### heading in the report -->\n        <!-- Example (lang:en): <a href=\"#section-core-metrics\" data-section=\"Core Metrics\">Core Metrics</a> -->\n        <!-- For ### heading: add class=\"toc-h3\" -->\n        [TOC links generated from all ## and ### headings in the IR]\n      </nav>\n\n      <div class=\"main-with-toc\">\n        <div class=\"report-wrapper\">\n\n          <!-- Report title and meta -->\n          <!-- lang:en card button label: \"⊞ Summary\" | lang:zh: \"⊞ 摘要卡\" -->\n          <div class=\"title-row\">\n            <h1>[title]</h1>\n            <button class=\"card-mode-btn\" id=\"card-mode-btn\" title=\"[Summary card|摘要卡片]\">[⊞ Summary|⊞ 摘要卡]</button>\n          </div>\n          [if abstract: <p class=\"report-subtitle\">[abstract]</p>]\n          [if author or date: <p class=\"report-meta\">[author] · [date]</p>]\n\n          <!-- Summary card overlay (always present) — left+right panels injected by buildCard() -->\n          <div class=\"sc-overlay\" id=\"sc-overlay\">\n            <div class=\"sc-card\" id=\"sc-card\">\n              <button class=\"sc-close\" id=\"sc-close\" aria-label=\"Close\">✕</button>\n              <!-- .sc-left and .sc-right injected by JS -->\n            </div>\n          </div>\n\n          <!-- AI Readability Layer 2: Section annotations are on each <section> element -->\n          <!-- Rendered sections — each ## becomes: -->\n          <!-- <section data-section=\"[heading]\" data-summary=\"[1-sentence summary]\"> -->\n          <!--   <h2 id=\"section-[slug]\">[heading]</h2> -->\n          <!--   [section content] -->\n          <!-- </section> -->\n\n          <!-- Shell metadata contract:\n               - Do not pass through Pandoc title metadata such as <header id=\"title-block-header\"> or <p class=\"date\">...</p>; the shell owns title/date metadata. Passing both through creates duplicate date output.\n               - Standard shell metadata is: kai-report-creator v[version] [theme].\n               - Standard shell emits both visible footer and hidden data-watermark with that string.\n               - Degradation is allowed for constrained/custom templates: keep at least one footer or watermark carrier with version/theme metadata.\n               - Replace stale prose such as \"Generated by kai-report-creator\" because it loses version/theme metadata. -->\n\n          [All rendered section content here]\n\n          <!-- Visible footer (deterministic shell metadata only; do not add debug hashes, source notes, or extra prose) -->\n          <div class=\"report-footer\">kai-report-creator v[version] [theme]</div>\n\n          <!-- Invisible watermark uses the same deterministic metadata string in the standard shell. -->\n          <div style=\"display:none;visibility:hidden;opacity:0;font-size:0;line-height:0;height:0;overflow:hidden;\" aria-hidden=\"true\" data-watermark=\"kai-report-creator v[version] [theme]\">\n            kai-report-creator v[version] [theme]\n          </div>\n\n        </div>\n      </div>\n\nFile v1.23.3:references/html-shell/export.md\n\n# Export Menu and Image Export\n\n        /* Export */\n        .export-btn { position: fixed; bottom: 16px; right: 16px; z-index: 10001; background: var(--primary); color: #fff; border: none; border-radius: 6px; padding: .45rem .9rem; font-size: .82rem; cursor: pointer; font-weight: 600; box-shadow: 0 2px 8px rgba(0,0,0,.2); font-family: var(--font-sans, system-ui); letter-spacing: .02em; }\n        .export-menu { position: fixed; bottom: 52px; right: 16px; z-index: 10001; background: var(--surface, #fff); border: 1px solid var(--border, #e5e7eb); border-radius: 6px; overflow: hidden; display: none; box-shadow: 0 4px 16px rgba(0,0,0,.15); min-width: 148px; }\n        .export-menu.open { display: block; }\n        .export-item { display: block; width: 100%; padding: .55rem 1rem; font-size: .84rem; background: none; border: none; cursor: pointer; text-align: left; color: var(--text, #111); font-family: var(--font-sans, system-ui); white-space: nowrap; border-bottom: 1px solid var(--border, #e5e7eb); }\n        .export-item:last-child { border-bottom: none; }\n        .export-item:hover { background: var(--primary-light, #e3edff); }\n\n      <!-- Export (always present) -->\n      <!-- lang:en labels: \"↓ Export\" / \"🖨 Print / PDF\" / \"🖥 Save PNG (Desktop)\" / \"📱 Save PNG (Mobile)\" / \"💬 IM Image\" -->\n      <!-- lang:zh labels: \"↓ 导出\"  / \"🖨 打印 / PDF\"  / \"🖥 保存图片（桌面）\"    / \"📱 保存图片（手机）\"  / \"💬 IM 分享长图\"   -->\n      <div class=\"export-menu\" id=\"export-menu\">\n        <button class=\"export-item\" id=\"export-print\">[🖨 Print / PDF|🖨 打印 / PDF]</button>\n        <button class=\"export-item\" id=\"export-png-desktop\">[🖥 Save PNG (Desktop)|🖥 保存图片（桌面）]</button>\n        <button class=\"export-item\" id=\"export-png-mobile\">[📱 Save PNG (Mobile)|📱 保存图片（手机）]</button>\n        <button class=\"export-item\" id=\"export-im-share\">[💬 IM Image|💬 IM 长图]</button>\n      </div>\n      <button class=\"export-btn\" id=\"export-btn\" title=\"Export\">[↓ Export|↓ 导出]</button>\n\n      <script>\n        // Export: Print/PDF via prepared print mode; images via html2canvas (preloaded on page open)\n        // Desktop PNG : full-page, adaptive scale (2× short / 1.5× long pages), PNG\n        // Mobile PNG  : .report-wrapper 750px wide (iPhone 2× Retina), JPEG 92%\n        // IM Share    : .report-wrapper 800px wide (WeChat/Feishu/DingTalk), JPEG 92%\n        (function() {\n          const exportBtn  = document.getElementById('export-btn');\n          const exportMenu = document.getElementById('export-menu');\n          const printBtn   = document.getElementById('export-print');\n          const pngDesktop = document.getElementById('export-png-desktop');\n          const pngMobile  = document.getElementById('export-png-mobile');\n          const pngIM      = document.getElementById('export-im-share');\n          if (!exportBtn || !exportMenu) return;\n          const LABEL = exportBtn.textContent;\n          const PRINT_MODE_CLASS = 'print-exporting';\n\n          exportBtn.addEventListener('click', e => { e.stopPropagation(); exportMenu.classList.toggle('open'); });\n          document.addEventListener('click', e => {\n            if (!exportBtn.contains(e.target) && !exportMenu.contains(e.target))\n              exportMenu.classList.remove('open');\n          });\n\n          /* Preload html2canvas immediately — ready before first click */\n          let libPromise = null;\n          function loadLib() {\n            if (libPromise) return libPromise;\n            libPromise = new Promise(resolve => {\n              if (window.html2canvas) { resolve(); return; }\n              const s = document.createElement('script');\n              s.src = 'https://cdn.jsdelivr.net/npm/html2canvas@1/dist/html2canvas.min.js';\n              s.onload = resolve; document.head.appendChild(s);\n            });\n            return libPromise;\n          }\n          loadLib(); /* fire immediately */\n\n          function restore() { exportBtn.style.visibility = ''; exportBtn.textContent = LABEL; }\n          function preparePrintExport() {\n            exportMenu.classList.remove('open');\n            exportBtn.style.visibility = 'hidden';\n            exportBtn.textContent = '…';\n            document.documentElement.classList.add(PRINT_MODE_CLASS);\n            document.documentElement.style.setProperty('--print-bg-color', exportBackgroundColor());\n          }\n          function cleanupPrintExport() {\n            document.documentElement.classList.remove(PRINT_MODE_CLASS);\n            document.documentElement.style.removeProperty('--print-bg-color');\n            restore();\n          }\n          function filename(suffix, ext) {\n            const d = new Date(), pad = n => String(n).padStart(2,'0');\n            const date = `${d.getFullYear()}${pad(d.getMonth()+1)}${pad(d.getDate())}`;\n            return (document.title||'report').replace(/[/\\\\:*?\"<>|]/g,'_') + `_${date}${suffix}.${ext}`;\n          }\n          function exportBackgroundColor() {\n            const rootStyles = getComputedStyle(document.documentElement);\n            const cssVar = (rootStyles.getPropertyValue('--bg') || '').trim();\n            if (cssVar) return cssVar;\n            const bodyColor = getComputedStyle(document.body).backgroundColor;\n            if (bodyColor && bodyColor !== 'rgba(0, 0, 0, 0)' && bodyColor !== 'rgba(0,0,0,0)' && bodyColor !== 'transparent') {\n              return bodyColor;\n            }\n            return '#ffffff';\n          }\n          function saveBlob(canvas, fname, jpeg) {\n            canvas.toBlob(blob => {\n              const a = Object.assign(document.createElement('a'), { href: URL.createObjectURL(blob), download: fname });\n              a.click(); URL.revokeObjectURL(a.href); restore();\n            }, jpeg ? 'image/jpeg' : 'image/png', jpeg ? 0.92 : 1);\n          }\n          function capture(el, cfg, fname, jpeg) {\n            exportMenu.classList.remove('open');\n            exportBtn.style.visibility = 'hidden';\n            exportBtn.textContent = '…';\n            const cardBtn = document.getElementById('card-mode-btn');\n            if (cardBtn) cardBtn.style.visibility = 'hidden';\n            // When summary card is open, capture .sc-card directly\n            // (html2canvas cannot capture position:fixed overlays)\n            if (document.body.classList.contains('card-mode')) {\n              const card = document.getElementById('sc-card');\n              const cardFname = filename('-摘要卡', jpeg ? 'jpg' : 'png');\n              loadLib().then(() => html2canvas(card, { scale: 2, useCORS: true, allowTaint: true, backgroundColor: '#ffffff' }).then(c => {\n                if (cardBtn) cardBtn.style.visibility = '';\n                restore();\n                saveBlob(c, cardFname, jpeg);\n              }));\n              return;\n            }\n            const tocSidebar = document.getElementById('toc-sidebar');\n            const tocToggle = document.getElementById('toc-toggle-btn');\n            const tocIsOpen = tocSidebar && tocSidebar.classList.contains('open');\n            if (tocToggle && !tocIsOpen) tocToggle.style.visibility = 'hidden';\n            document.querySelectorAll('.fade-in-up').forEach(e => e.classList.add('visible'));\n            loadLib().then(() => html2canvas(el, cfg).then(c => {\n              if (tocToggle && !tocIsOpen) tocToggle.style.visibility = '';\n              if (cardBtn) cardBtn.style.visibility = '';\n              saveBlob(c, fname, jpeg);\n            }));\n          }\n          window.addEventListener('afterprint', cleanupPrintExport);\n\n          printBtn && printBtn.addEventListener('click', () => {\n            preparePrintExport();\n            requestAnimationFrame(() => {\n              requestAnimationFrame(() => {\n                window.print();\n              });\n            });\n          });\n\n          pngDesktop && pngDesktop.addEventListener('click', () => {\n            const H = document.documentElement.scrollHeight;\n            capture(document.documentElement, {\n              scale: H > 4000 ? 2.5 : 3, useCORS: true, allowTaint: true,\n              scrollX: 0, scrollY: 0,\n              width: document.documentElement.scrollWidth, height: H,\n              windowWidth: document.documentElement.scrollWidth, windowHeight: H\n            }, filename('', 'png'), false);\n          });\n\n          pngMobile && pngMobile.addEventListener('click', () => {\n            const el = document.querySelector('.report-wrapper') || document.documentElement;\n            capture(el, {\n              scale: (750 / el.offsetWidth) * 2, useCORS: true, allowTaint: true,\n              backgroundColor: exportBackgroundColor(),\n              scrollX: 0, scrollY: 0, width: el.scrollWidth, height: el.scrollHeight\n            }, filename('-mobile', 'jpg'), true);\n          });\n\n          pngIM && pngIM.addEventListener('click', () => {\n            const el = document.querySelector('.report-wrapper') || document.documentElement;\n            capture(el, {\n              scale: (800 / el.offsetWidth) * 2, useCORS: true, allowTaint: true,\n              backgroundColor: exportBackgroundColor(),\n              scrollX: 0, scrollY: 0, width: el.scrollWidth, height: el.scrollHeight\n            }, filename('-im', 'jpg'), true);\n          });\n        })();\n      </script>\n\nArchive v1.23.2: 177 files, 490029 bytes\n\nFiles: check-doc-sync.py (5869b), CLAUDE.md (1723b), evals/__init__.py (49b), evals/baselines/2026-05-17-baseline-summary.md (4372b), evals/baselines/2026-05-17-late-context-evals.json (11926b), evals/baselines/2026-05-17-report-evals.json (5255b), evals/baselines/2026-05-17-skill-evals-codex-live.json (160772b), evals/baselines/2026-05-17-skill-evals-fixture.json (9886b), evals/cases/en-ops-weekly/noise-context.md (1694b), evals/cases/en-ops-weekly/report.report.md (1273b), evals/cases/en-ops-weekly/source.md (535b), evals/cases/guard-broken-chart-schema/report.report.md (496b), evals/cases/guard-broken-chart-schema/source.md (56b), evals/cases/guard-narrative-placeholder-kpi/report.report.md (1471b), evals/cases/guard-narrative-placeholder-kpi/source.md (374b), evals/cases/zh-ai-collaboration/noise-context.md (2285b), evals/cases/zh-ai-collaboration/report.report.md (1805b), evals/cases/zh-ai-collaboration/source.md (804b), evals/cases/zh-quarterly-growth/noise-context.md (1785b), evals/cases/zh-quarterly-growth/report.report.md (1385b), evals/cases/zh-quarterly-growth/source.md (406b), evals/contract_checks.py (8970b), evals/failure-map.md (1940b), evals/golden_cases.yaml (2856b), evals/report-cases.csv (862b), evals/report-skill-prompts.csv (886b), evals/rubric.schema.json (2127b), evals/skill-prompts/boundary-blueprint-report.md (734b), evals/skill-prompts/contextual-research.md (806b), evals/skill-prompts/explicit-generate.md (582b), evals/skill-prompts/implicit-weekly-progress.md (608b), evals/skill-prompts/negative-html-export.md (118b), evals/skill-prompts/negative-slide-deck.md (114b), evals/skill-run-rubric.schema.json (1182b), examples/business-report.report.md (1650b), examples/do-not-use.md (508b), examples/en/business-report-reviewed-demo.html (22220b), examples/en/business-report.html (24153b), examples/en/monthly-progress-reviewed-demo.html (17571b), examples/en/monthly-progress.html (16538b), examples/research-report.report.md (1718b), examples/review-reports/business-report-demo-review-report.md (3376b), examples/review-reports/monthly-progress-demo-review-report.md (3125b), examples/review-reports/monthly-progress-zh-review-report.md (3221b), examples/tech-doc.report.md (1706b), examples/when-to-use.md (799b), examples/zh/business-report.html (23702b), examples/zh/kai-report-creator-guide.html (32103b), examples/zh/kai-report-creator-guide.report.md (4833b), examples/zh/monthly-progress-reviewed-demo.html (17632b), examples/zh/monthly-progress.html (15933b), pytest.ini (125b), README.md (30813b), README.zh-CN.md (28653b), references/anti-patterns.md (4303b), references/design-quality.md (15801b), references/diagram-decision-rules.md (1317b), references/generate-flow.md (1863b), references/html-shell-template.md (5060b), references/html-shell/core-structure.md (7024b), references/html-shell/export.md (9371b), references/html-shell/print-responsive.md (1509b), references/html-shell/shared-component-css.md (12342b), references/html-shell/summary-card.md (10413b), references/html-shell/toc-edit-summary.md (11506b), references/impeccable-anti-patterns.md (5625b), references/INDEX.md (3497b), references/ir-contract.md (1833b), references/plan-flow.md (1544b), references/regular-report-content-rules.md (1726b), references/rendering-rules.md (3547b), references/rendering/chart.md (8595b), references/rendering/kpi.md (8359b), references/rendering/media-code-callout.md (2088b), references/rendering/plain-markdown.md (1449b), references/rendering/table-list.md (1304b), references/rendering/timeline-diagram.md (3486b), references/review-checklist.md (10468b), references/review-report-template.md (2069b), references/spec-loading-matrix.md (1939b)\n\nFile v1.23.2:SKILL.md\n\n---\nname: kai-report-creator\ndescription: Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and English equally. Supports generating from raw notes, data, URLs, or an approved plan file. Use for --plan (structure first), --generate (render to HTML), --review (one-pass automatic refinement), --themes (preview styles), --from FILE, --bundle, --export-image flags. Does NOT apply to exporting finished HTML to PPTX/PNG (use kai-html-export) or creating slide decks (use kai-slide-creator).\nversion: 1.23.2\nuser-invocable: true\nmetadata: {\"openclaw\": {\"emoji\": \"📊\"}}\n---\n\n# kai-report-creator\n\nGenerate single-file HTML reports from source notes or `.report.md` IR. Keep this file as a thin router: load only the references needed for the current path.\n\n## Core Principles\n\n1. **Zero Dependencies** — generated reports are self-contained HTML, with CDN or bundled assets only when needed.\n2. **User Provides Data, AI Provides Structure** — never fabricate facts or numbers; use `[数据待填写]` / `[INSERT VALUE]` when data is missing.\n3. **Plan Before Generate** — complex reports should become `.report.md` IR first, then HTML.\n4. **Progressive Disclosure for AI** — output keeps `report-summary`, section annotations, and component data machine-readable.\n5. **Thin Routing Over Prompt Growth** — `SKILL.md` routes work; detailed rules live in references.\n6. **Contracts and Gates Beat Prompt Soup** — prefer IR, guard validation, shell tests, and post-render review over adding more prose to this hot path.\n\n## Command Routing\n\nWhen invoked as `/report [flags] [content]`, parse flags first:\n\n| Flag | Action |\n|------|--------|\n| `--plan \"topic\"` | Write `.report.md` IR only. Stop after saving it. |\n| `--generate [file]` | Render one `.report.md` IR to HTML. With no file given, treat as IR from context: extract exactly one valid IR block from context. Never render the surrounding conversation. |\n| `--review [file]` | Refine an existing HTML report with `references/review-checklist.md`. |\n| `--themes` | Write the themes preview HTML. |\n| `--from <file>` | If the file starts with frontmatter, treat as IR; otherwise create IR, then render. |\n| `--theme <name>` | Override the theme. Built-ins: `corporate-blue`, `minimal`, `dark-tech`, `dark-board`, `data-story`, `newspaper`, `regular-lumen`, `fangsong`. |\n| `--template <file>` | Use a custom HTML template. See `references/toc-and-template.md`. |\n| `--output <file>` | Save to this path instead of the default. |\n| `--bundle` | Inline CDN assets where supported. |\n| `--export-image [mode]` | After HTML generation, run `scripts/export-image.py`; mode is `im`, `mobile`, `desktop`, or `all`. |\n| no flags + text | Create IR internally, then render HTML. |\n| no flags + IR in context | Treat as `--generate` from context. |\n\nDefault output filename: `report-<YYYY-MM-DD>-<slug>.html`. Slug: lowercase ASCII, non-alphanumeric to hyphens, collapse hyphens, trim, max 30 chars.\n\n## Reference Loading\n\nLoad reference files minimally by route; do not read every reference by default. In short: load only the references that materially help the current render path.\n\n| Route | Always load | Conditional load |\n|-------|-------------|------------------|\n| `--plan` | `references/spec-loading-matrix.md`, `references/plan-flow.md`, `references/theme-routing.md` | `references/regular-report-content-rules.md` for periodic reports |\n| `--generate` | `references/generate-flow.md`, `references/html-shell-template.md` + every `references/html-shell/*.md`, `references/theme-css.md`, `references/review-checklist.md` | `references/rendering-rules.md` then only the `references/rendering/*.md` files required by the IR; `references/anti-patterns.md` for visual anchors; `references/diagram-decision-rules.md` for diagrams; `references/regular-report-content-rules.md` for periodic reports |\n| `--review` | `references/review-checklist.md` | `references/review-report-template.md` if a structured change summary is requested |\n| custom theme/template | `references/theme-css.md`, `references/toc-and-template.md` | custom theme `reference.md` or `theme.css` |\n\nLoad `references/spec-loading-matrix.md` before `--plan` and `--generate` as a silent classifier. It covers optional archetypes: `brief`, `research`, `comparison`, `update`.\n\nAlways load `references/anti-patterns.md` before `--generate`. Load `references/diagram-decision-rules.md` whenever a diagram or diagram-like structure is being considered.\n\n## IR Contract\n\nLoad `references/ir-contract.md` for the full frontmatter spec, validity terms, and compatibility anchors.\n\nQuick reference:\n- Three parts: YAML frontmatter, Markdown prose (`##`/`###`), component fences `:::tag [param=value]`.\n- `:::kpi` uses `items:`; Use **ECharts** for ALL charts.\n- Badges are optional visual enhancements, not a first-class IR tag.\n- Validity taxonomy: `invalid_syntax`, `invalid_semantics`, `contract_conflict`, `auto_downgrade_target`.\n- Timeline details live in rendering references; Allowed `Date` tokens must be real time markers, not decorative labels.\n- Canonical component routing: `references/rendering-rules.md`; component details: `references/rendering/*.md`.\n\nMinimal frontmatter example:\n```yaml\ntheme: corporate-blue                  # Optional. Default: corporate-blue\nreport_class: mixed                    # Optional. Values: narrative, mixed, data\narchetype: research                    # Optional lightweight archetype hint for silent classification.\n```\nSupported archetypes: `brief`, `research`, `comparison`, `update`.\n\n## Language And Theme\n\nLoad `references/theme-routing.md` for the full theme-selection table and report-class rules.\n\nQuick reference: auto-detect `zh` when CJK is material; apply to placeholders, TOC labels, date display, and shell labels.\n\n## `--plan` Flow\n\nLoad `references/plan-flow.md` for the full 10-step procedure and narrative rhythm rules.\n\nKey gates: save as `report-<slug>.report.md`; do not generate HTML; use real quantitative KPI values only.\n\nPoster summary mode is opt-in. Do not infer `poster_title` or `poster_subtitle` from punctuation in `title`.\n\nNarrative cadence blocks (`lead-block`, `section-quote`, `action-grid`) follow claim -> explanation -> scan anchor. These are optional prose upgrades, not default required blocks. If uncertain, keep normal paragraphs and add one clearer scan anchor instead of forcing a cadence block. Do not add more than one of `lead-block` / `section-quote` / `action-grid` by default inside the same section unless the source material clearly warrants it.\n\n## `--generate` Flow\n\nLoad `references/generate-flow.md` for steps 1-8 (input parsing, guard validation, render, shell assembly, CSS).\n\nThen run these quality gates in sequence — do not skip:\n\n9. Run pre-write validation and fix all violations:\n   - no raw `:::` in HTML\n   - valid `ir-hash`\n   - no generic/template h2 headings\n   - short, real quantitative `.kpi-value` and `report-summary` KPI values; no placeholder or status-only KPI values\n   - `.number` body numerals use tabular lining numerals\n   - badges clarify status/category/entity, never quota-fill\n   - timeline dates are real time markers\n   - no U+FE0F\n   - no `text-align: justify`, black-background flood, body letter-spacing > `0.05em`, or mobile-hidden critical controls\n10. Run the final HTML quality gate with `scripts/html_quality_gate.py` on the rendered HTML. It must pass standard shell IDs, theme fidelity, and KPI value checks. If it fails, fix the HTML and rerun it before reporting success.\n11. Run L2 shell checks. Required: `data-template=\"kai-report-creator\"`, `data-version`, `data-theme`, `id=\"toc-toggle-btn\"`, `id=\"toc-sidebar\"`, `id=\"card-mode-btn\"`, `id=\"sc-overlay\"`, `id=\"export-btn\"`, `id=\"export-menu\"`, `id=\"export-print\"`, `id=\"export-png-desktop\"`, `id=\"export-png-mobile\"`, `id=\"export-im-share\"`, `id=\"report-summary\"`, plus the JS bindings for print/desktop/mobile/IM export. If any export item or binding is missing, rebuild the whole export block from `references/html-shell/export.md`.\n12. Run the silent final review pass from `references/review-checklist.md`, then write the HTML and report the path.\n\nWhen the report is explicitly comparing named vendors, models, or tools, set `data-report-mode=\"comparison\"` on the outer report container and use `.badge--entity-a/.badge--entity-b/.badge--entity-c` only for entity identity.\n\n## `--review` Flow\n\n1. Read the HTML file.\n2. Load `references/review-checklist.md`.\n3. Apply hard rules automatically; apply AI-advised rules only when confidence is high and factual accuracy is preserved.\n4. One-pass automatic refinement; no confirmation window.\n5. Use `references/review-report-template.md` when the user wants a structured summary.\n6. Write back unless the user asked for diagnosis only.\n7. Tell the user what changed and what was intentionally left untouched.\n\n## `--themes` And `--export-image`\n\nFor `--themes`, read the theme preview template and write `report-themes-preview.html` verbatim.\n\nFor `--export-image`, after HTML generation run:\n\n```bash\npython <skill-dir>/scripts/export-image.py <output.html> --mode <mode>\n```\n\nIf Playwright is unavailable, print install instructions and skip image export without failing HTML generation.\n\n## Shell And Template Boundary\n\nGenerate complete self-contained HTML. Shell entry contract: `references/html-shell-template.md`; full shell structure, inline JS, export behavior, summary card, edit mode, TOC, print rules, Shell metadata, version/theme metadata, duplicate-date guard, and footer/watermark degradation rules: `references/html-shell/*.md`.\n\nAll scripts are inline in the shell template. Never load nonexistent files such as `templates/scripts/*.js`.\n\nFor custom templates and TOC slug rules, use `references/toc-and-template.md`.\n\n## Final Output\n\nAlways end with the file path and a one-sentence summary. If a validation, guard, or export step could not run, say exactly which step was skipped and why.\n\nFile v1.23.2:README.md\n\n# kai-report-creator\n\n> You have data, decisions, and deadlines — but decision makers don't have time to read everything. AI can generate reports, but they often look instantly AI-made: template headings, primary color flooding every element, 3-column KPI grids regardless of count. kai-report-creator gives you polished, async-friendly reports in one command: drop a document or URL, pick a theme, and get a single HTML file that survives first-contact reading. Downstream AI agents can also parse it — the output embeds a 3-layer machine-readable structure.\n>\n> **[See the guide as a report →](https://kaisersong.github.io/kai-report-creator/examples/zh/kai-report-creator-guide.html)** — this document was generated by kai-report-creator itself.\n\nA skill for [Claude Code](https://claude.ai/claude-code) and [OpenClaw](https://openclaw.ai) that turns plain text or structured outlines into polished HTML reports.\n\nEnglish | [简体中文](README.zh-CN.md)\n\n---\n\n## Live Demo\n\nClick any screenshot to open the live demo:\n\n<table>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/corporate-blue.html\"><img src=\"templates/screenshots/corporate-blue.png\" width=\"360\" alt=\"corporate-blue\"/><br/><b>corporate-blue</b></a><br/><sub>Warm Premium · Business</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/minimal.html\"><img src=\"templates/screenshots/minimal.png\" width=\"360\" alt=\"minimal\"/><br/><b>minimal</b></a><br/><sub>Research · Academic</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/dark-tech.html\"><img src=\"templates/screenshots/dark-tech.png\" width=\"360\" alt=\"dark-tech\"/><br/><b>dark-tech</b></a><br/><sub>Engineering · Ops</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/dark-board.html\"><img src=\"templates/screenshots/dark-board.png\" width=\"360\" alt=\"dark-board\"/><br/><b>dark-board</b></a><br/><sub>Dashboards · Architecture</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/data-story.html\"><img src=\"templates/screenshots/data-story.png\" width=\"360\" alt=\"data-story\"/><br/><b>data-story</b></a><br/><sub>Annual Reports · Growth</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/newspaper.html\"><img src=\"templates/screenshots/newspaper.png\" width=\"360\" alt=\"newspaper\"/><br/><b>newspaper</b></a><br/><sub>Editorial · Industry Analysis</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/regular-lumen.html\"><img src=\"templates/screenshots/regular-lumen.png\" width=\"360\" alt=\"regular-lumen\"/><br/><b>regular-lumen</b></a><br/><sub>Periodic Reports · Weekly/Daily/Monthly</sub></td>\n</tr>\n</table>\n\nPreview the theme gallery: `/report --themes` → opens `report-themes-preview.html`\n\n---\n\n## Design Philosophy: Skills as Domain Harness Engineering\n\nThis section explains the principles behind report-creator — both as a user tool and as a Claude Code skill. These principles are reusable for anyone building skills.\n\n### 1. Progressive Disclosure\n\nA skill file loads entirely into the AI's context on every invocation. Size directly affects focus.\n\nreport-creator solves this with **rules in the skill, assets in files**:\n\n```\n--plan        → only IR rules + component syntax; no CSS, no HTML shell\n--generate    → one theme CSS + one shared CSS; other theme files stay on disk\n--themes      → pre-built preview HTML; skill doesn't parse internals\n```\n\n**Result:** `--plan` never touches CSS. Single-theme generation only loads the selected theme.\n\nThis is progressive disclosure applied to AI context: **reveal information at the moment it's needed, not before.**\n\n### 2. Capability Growth Must Reduce Context Load\n\nWhen adding a new capability, the first question is not \"what else can we stuff into context?\" It is \"can we reduce prompt/context burden on the generation path?\"\n\nreport-creator should prefer three moves:\n\n- **Thin routing in `SKILL.md`.** Keep the skill file as a router plus contract boundary. Load only the files needed for the selected path. Do not drag long planning conversations directly into the render phase.\n- **Structured compression over raw prose.** Prefer `.report.md`, `BRIEF.json`-style briefs, explicit contracts, and routing metadata over more prompt paragraphs. If information matters repeatedly, give it a field, a schema, or a deterministic transform.\n- **Move quality checks off the hot path.** If a new quality mechanism increases generation-time cognitive load, it belongs in guard validation, post-render review, or evals instead of the prompt chain.\n\nThis is not minimalism for its own sake. It is reliability work. Prompt bloat makes routing fuzzy, hides the real contract, and causes the model to drop constraints exactly when rendering needs precision.\n\n### 3. Silicon-Carbon Collaboration Design\n\nreport-creator is designed for human-AI collaboration at both input and output ends.\n\n**Input: IR as Human-AI Contract**\n\nThe `.report.md` Intermediate Representation is the contract between human intent and AI rendering:\n\n```\n---                         ← Frontmatter: document identity\ntitle: Q3 Sales Report         What is this? Who made it? How should it look?\ntheme: corporate-blue          Declares intent, not content.\n---\n\n## Section Heading         ← Prose: human narrative\nPlain Markdown text...        Written naturally. AI renders to semantic HTML.\n\n:::kpi                     ← Component blocks: structured data\n- Revenue: $2.45M ↑12%       Machine-parseable. AI renders deterministically.\n:::\n```\n\nHumans write naturally without knowing HTML. AI renders each layer with different rules — prose gets Markdown, components get templates. IR is inspectable and version-controllable.\n\n**Output: Three-Layer AI-Readable Structure**\n\nEvery generated HTML embeds machine-readable structure:\n\n```\nLayer 1 — <script id=\"report-summary\">    Document-level: title, abstract, all KPIs\nLayer 2 — data-section data-summary       Section-level: heading + one-sentence summary\nLayer 3 — data-component data-raw         Component-level: raw KPI/chart/table data\n```\n\nAn AI agent reads Layer 1 for a 3-second overview, drills to Layer 2 for section-level understanding, reaches Layer 3 only for specific data.\n\n**Progressive disclosure for both species:** IR reveals structure to humans; HTML reveals data to machines. The same principle applied twice — once for carbon-based readers, once for silicon-based ones.\n\n### 4. Visual Rhythm as Cognitive Pacing\n\nReports that work follow a rhythm: **prose sets context, components deliver data, prose interprets it**.\n\nThe skill enforces this: never 3+ consecutive prose-only sections. Every 4–5 sections must include a visual anchor chosen for the content type — callout, timeline, diagram, KPI grid, or chart. Dense prose fatigues; data without context loses. Alternation creates flow.\n\nThis is why IR's component syntax (`:::tag ... :::`) is visually obvious: authors scan IR files and see data-heavy sections immediately.\n\n### 5. Reports Are Asynchronous Decision Support\n\nSlides have a presenter. Reports don't. A report must survive first contact with a busy reader who skims the opening, scans headings, glances at data, and decides in under a minute whether to continue.\n\nThis constraint drives product design:\n\n- `--review` is **one-pass automatic refinement**, not interactive editing\n- `--generate` runs the same checklist as a **silent final pass**\n- Checklist split into **L0 visual quality** and **L1 content quality**\n- Only rules AI can judge and repair reliably are included\n\n**Rule of thumb:** A generated report should reduce reader effort. If a stakeholder can understand the point, evidence, and next action from a fast skim, the report works.\n\n### 6. Design Quality Baseline: Against AI Slop\n\nThe enemy: instantly recognizable AI output — uniform borders, primary color flooding everything, 3-column KPI grids regardless of count, template-sounding headings.\n\n`references/design-quality.md` encodes four disciplines:\n\n**90/8/2 Color Law.** 90% neutral surface, 8% structural accent, 2% bullet-point hits. When `--primary` floods headings, KPIs, charts, callouts, TOC, and badges — it becomes noise.\n\n**10:1 Typography Tension.** Largest element ≥10× smallest. Report titles should feel like anchors (2.8–4rem), not labels. Pages without hierarchy look like spreadsheet exports.\n\n**KPI Grid Rules.** Default isn't always 3 columns. 4 KPIs → 2×2. Hero metric → `2fr 1fr 1fr`. 7+ KPIs need dividers. Rigid 3-column grids signal AI wasn't paying attention.\n\n**Content-Tone Color Calibration.** Different emotional registers deserve different palettes:\n\n| Tone | `primary_color` | Feel |\n|------|-----------------|------|\n| Contemplative / Research | `#7C6853` warm brown | Grounded, editorial |\n| Technical / Engineering | `#3D5A80` navy | Precise, authoritative |\n| Business / Data | `#0F7B6C` deep teal | Confident, forward |\n| Narrative / Annual | `#B45309` amber | Warm, momentum |\n\n**Pre-output check:** *\"If you told someone 'an AI wrote this', would they believe it? If yes — find the most generic-looking part and redesign it.\"*\n\n### 7. Contract Enforcement Before Render\n\nv1.20.0's guard validation pipeline introduces a new principle: **intercept invalid IR before rendering, not repair after.**\n\n```\nIR → Guard (validate + downgrade) → Renderer → HTML\n              ↑\n              Block invalid input\n```\n\nThree sub-principles:\n\n| Principle | Implementation | Meaning |\n|-----------|----------------|---------|\n| **Zero-Drift Resolution** | Guard and renderer share the same `resolve_report_class` logic | Validation and rendering never diverge |\n| **Graceful Degradation** | Invalid components auto-downgrade (kpi→callout, chart→table, timeline→list) | Don't fail outright; fall back to safe substitute |\n| **Traceability** | `<meta name=\"ir-hash\">` embeds IR hash in HTML | Output is traceable to source IR |\n\n**Why it matters:**\n- Earlier `--review` was post-hoc repair; guard is pre-hoc interception\n- Prevents invalid IR from entering the render pipeline and producing unpredictable output\n- Zero-drift ensures guard's judgment and renderer's behavior stay aligned\n\nv1.23.0 extends this boundary to final HTML with `scripts/html_quality_gate.py`: rendered files must keep the standard shell controls, the declared theme's CSS fingerprint, typography/layout markers, and only real quantitative KPI values. This catches failures where IR is legal but the HTML hand-rolls a theme, drops summary/export controls, or smuggles placeholder/status text into KPI cards.\n\n### 8. Eval as Quality Boundary, Not Quality Score\n\nv1.15.0's eval workflow embodies this principle: **evals define boundaries, not scores.**\n\n```\ncompression → ir_contract → async_readability → render_integrity\n     ↓             ↓              ↓                  ↓\n   Source→IR     IR Spec        Reading UX          HTML Integrity\n```\n\n| Layer | What it checks | Where to fix |\n|-------|----------------|--------------|\n| compression | report_class, audience, decision_goal declared | SKILL.md |\n| ir_contract | timeline is real time, kpi is short value, chart schema legal | rendering-rules.md + contract_checks.py |\n| async_readability | BLUF, heading stack, takeaway after data | review-checklist.md |\n| render_integrity | shell IDs, report-summary JSON, no `:::` leak, theme fidelity | html-shell-template.md + html_quality_gate.py |\n\n**Failure Map rule:** Every real production failure → one new eval case. Not post-hoc discussion about \"feels wrong\", but direct pointer to the layer that needs fixing.\n\n**Rubric design:** Output structured JSON (verdict + scores + findings), not fuzzy scores. Downstream agents can parse and auto-repair.\n\n### 9. Contract Checks as Programmable Guardrails\n\n`contract_checks.py` makes IR spec executable:\n\n```python\n# Timeline must be real dates\nDATE_PATTERNS = [YYYY-MM-DD, YYYY-MM, Q1-4 YYYY, Day N, Week N]\n\n# KPI value must be a short real quantitative value; placeholders/status-only words fail\ndef is_short_kpi_value(value): ...\n\n# Placeholder pattern recognition\nPLACEHOLDER_RE = r\"\\[(INSERT VALUE|数据待填写)\\]\"\n```\n\n**Design principles:**\n- Spec declared in SKILL.md, validated in contract_checks.py\n- Guard calls contract_checks, zero drift\n- Every component has `auto_downgrade_target`: safe fallback path when invalid\n\nFinal HTML has a separate gate:\n\n```bash\npython scripts/html_quality_gate.py report.html\n```\n\n---\n\n## Install\n\n### Claude Code\n\nTell Claude: \"Install https://github.com/kaisersong/kai-report-creator\"\n\nOr manually:\n```bash\ngit clone https://github.com/kaisersong/kai-report-creator ~/.claude/skills/kai-report-creator\n```\n\nRestart Claude Code. Use as `/report`.\n\n### OpenClaw\n\n```bash\n# Via ClawHub (recommended)\nclawhub install kai-report-creator\n\n# Or manually\ngit clone https://github.com/kaisersong/kai-report-creator ~/.openclaw/skills/kai-report-creator\n```\n\n### Release Downloads\n\nThe current release is **v1.23.2**. Download source bundles from GitHub Releases:\n\n- https://github.com/kaisersong/kai-report-creator/releases/tag/v1.23.2\n- https://github.com/kaisersong/kai-report-creator/archive/refs/tags/v1.23.2.zip\n\n---\n\n## Usage\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `/report --from file.md` | Generate from an existing document |\n| `/report --from URL` | Generate from a web page |\n| `/report --plan \"topic\"` | Create a `.report.md` outline first |\n| `/report --generate file.report.md` | Render an outline to HTML |\n| `/report --review file.html` | Refine an existing report |\n| `/report --themes` | Preview the bundled theme gallery |\n| `/report --bundle --from file.md` | Offline HTML with inlined CDN assets |\n| `/report --theme <name> --from file.md` | Use a built-in or custom theme |\n| `/report [content]` | One-step: generate from description |\n\n### Typical Workflows\n\n**One-step generation:**\n```\n/report --from meeting-notes.md\n/report --from https://example.com/data-page --output market-analysis.html\n```\n\n**Two-stage workflow (complex content):**\n```\n/report --plan \"Q3 Sales Summary\" --from q3-data.csv\n# edit q3-sales-summary.report.md if needed\n/report --generate q3-sales-summary.report.md\n```\n\n**Review and refine:**\n```\n/report --review market-analysis.html\n```\n\n### Review Mode\n\nRun `--review` to improve existing reports with 13 checkpoints:\n\n```\n/report --review market-analysis.html\n```\n\n**Behavior:**\n1. Load `references/review-checklist.md`\n2. Apply hard rules automatically\n3. Apply AI-advised rules when confidence is high\n4. Save refined HTML back to file\n\nIf you want a structured change summary after review, use `references/review-report-template.md`.\n\n**One-pass automatic refinement** — not interactive approval.\n\n`--generate` also runs this checklist as a **silent final review** before writing HTML.\n\nThis review flow is the built-in **13-checkpoint review system**.\n\n**13 Checkpoints:**\n- KPI value length\n- Badge coverage\n- Summary card poster hierarchy\n- Timeline content validity\n- Export menu completeness\n- BLUF opening (Bottom Line Up Front)\n- Heading stack logic\n- Anti-template section headings\n- Prose-wall cleanup\n- Takeaway-after-data\n- Insight-over-data\n- Scan-anchor coverage\n- Conditional reader guidance\n\n---\n\n## Eval Workflow\n\nThis repo now includes a small, repo-contained eval harness focused on **async reading quality**, not slide-style presenter flow.\n\nRun it with:\n\n```bash\npython scripts/run-report-evals.py --root . --packet-dir .tmp/eval-packets\n```\n\nWhat it does:\n\n- Runs deterministic checks for `compression`, `ir_contract`, and `render_integrity`\n- Emits rubric-ready JSON packets for `async_readability` instead of hiding quality behind vibes\n- Uses repo-contained cases from `evals/report-cases.csv`\n\nKey files:\n\n- `evals/report-cases.csv` — living case set\n- `evals/rubric.schema.json` — structured grader output contract\n- `evals/failure-map.md` — where to fix each layer when a case fails\n- `evals/cases/*` — source + IR artifacts for each case\n\n### Captured-Run Skill Evals\n\n`scripts/run-report-evals.py` checks repo-contained source/IR/HTML artifacts. It is a deterministic regression gate, not a full agent-run skill eval.\n\nFor OpenAI-style skill evals, run the captured-run harness explicitly:\n\n```bash\npython scripts/run-skill-evals.py --runner codex --run-live --format json --json-out .tmp/skill-evals/results.json\n```\n\nThe harness reads `evals/report-skill-prompts.csv`, stores raw/normalized traces under `evals/artifacts/current/skill-runs/`, and scores each case across four categories:\n\n- Outcome: report task completion and valid artifacts.\n- Process: skill flow, reference loading, guard validation, and HTML quality gate evidence from normalized runner metrics.\n- Style: template/theme/content conventions plus structured rubric grading for positive captured-run cases.\n- Efficiency: shell command count, repeated failures, token budgets, and wall-clock budget.\n\nUse fixture mode for deterministic local tests without calling any live agent:\n\n```bash\npython scripts/run-skill-evals.py --runner fixture --format json\n```\n\nPositive fixture cases use checked-in `tests/fixtures/skill-evals/*-style-rubric.json`.\nIf a positive case has no rubric, the harness marks it `eval_complete: false`\nand fails the case instead of hiding the coverage gap behind a green score.\n\nSaved baselines live under `evals/baselines/`. Compare a fresh run against the\nchecked-in baseline before changing skill behavior:\n\n```bash\npython scripts/run-skill-evals.py --runner fixture \\\n  --artifact-dir .tmp/check-skill-evals-fixture-artifacts \\\n  --format json \\\n  --json-out .tmp/check-skill-evals-fixture.json\n\npython scripts/compare-skill-eval-baseline.py \\\n  --old evals/baselines/2026-05-17-skill-evals-fixture.json \\\n  --new .tmp/check-skill-evals-fixture.json \\\n  --format text\n```\n\n`evals/baselines/2026-05-17-baseline-summary.md` records the saved scores:\nthe deterministic fixture baseline passes 6/6 with `incomplete: 0`,\n`average_score: 100.0`, and Style `25.0`, while the hardened Codex live\nbaseline passes 0/6 at 64.5 average because incomplete timed-out runs are gated\nby `runner.run_incomplete`. The comparator checks pass/fail state,\n`eval_complete`, total score, and each category score.\n\nCodex is only the first live runner adapter. Other agents such as Claude Code or Qoder need their own trace adapter before they can be compared with the same prompt set and scoring rules.\n\nFor complex reports, keep these IR frontmatter fields so evals can measure compression quality directly: `report_class`, `audience`, `decision_goal`, `must_include`, `must_avoid`.\n\nMaintainers can run the full release verification chain from one entry point:\n\n```bash\npython scripts/verify-release.py --root .\n```\n\nFor a single generated report, run the final HTML gate directly:\n\n```bash\npython scripts/html_quality_gate.py report.html\n```\n\n---\n\n## Features\n\n### Core\n\n- **Zero dependencies** — single `.html` file, works offline with `--bundle`\n- **8 built-in themes** — corporate-blue, minimal, dark-tech, dark-board, data-story, newspaper, regular-lumen, fangsong\n- **9 component types** — KPIs, charts (ECharts), tables, timelines, diagrams, code blocks, callouts, images, lists\n- **Report Review System** — 13-checkpoint automatic refinement\n- **AI-readable output** — 3-layer machine-readable structure for downstream agents\n\n### Interaction\n\n- **Summary card overlay** — `⊞ Summary` button opens a poster-style title card with abstract, KPIs, and section summaries\n- **Built-in export** — Print/PDF, PNG (Desktop), PNG (Mobile) via ↓ Export button\n- **Mobile responsive** — adapts to any screen size\n- **Bilingual** — full zh/en support with auto-detection\n\n### Output\n\n- **Custom themes** — `themes/<name>/theme.css` + `--theme <name>`\n- **Custom templates** — `template: ./my-brand-template.html` with placeholders\n- **Theme overrides** — `theme_overrides.primary_color` in frontmatter\n- **Offline bundles** — `--bundle` inlines all CDN assets\n\n---\n\n## Themes\n\n| Theme | Vibe | Best For |\n|-------|------|----------|\n| **corporate-blue** | Warm premium | Business reports, executive summaries |\n| **minimal** | Clean, academic | Research papers, analysis |\n| **dark-tech** | Engineering feel | Ops reports, technical docs |\n| **dark-board** | Dashboard style | Architecture, metrics dashboards |\n| **data-story** | Narrative-driven | Annual reports, growth stories |\n| **newspaper** | Editorial | Industry analysis, newsletters |\n| **regular-lumen** | Poster-style, warm-toned | Periodic work reports (日报/周报/月报 · 本周期复盘 + 下周期规划) · Kami-style reading experience |\n| **fangsong** | Traditional Chinese, warm brown | Formal reports with FangSong typography (标题衬线仿宋 + 正文非衬线仿宋) |\n\n### corporate-blue\n\nWarm business theme with subtle gradients. Default for executive-facing reports. Uses restrained primary color on key elements only — KPI values, section links, and one accent block per report.\n\n**Why it works:** Primary color appears on ≤3 element types, creating clear visual hierarchy without the \"AI flooded everything with blue\" look.\n\n---\n\n## Creating Custom Themes\n\n1. Create `themes/your-theme/` directory\n2. Write `theme.css` with CSS custom properties:\n```css\n:root {\n  --primary: #B45309;\n  --bg: #FAFAF9;\n  --text: #1C1917;\n  --font-heading: \"Merriweather\", serif;\n}\n```\n3. Run: `/report --theme your-theme --from file.md`\n\n**Example theme bundled:** `themes/warm-editorial/`\n\n---\n\n## Report Format (IR)\n\nFor complex reports, use `--plan` to generate a `.report.md` intermediate file.\n\n**Frontmatter:**\n```yaml\n---\ntitle: Q3 Sales Report\ntheme: corporate-blue\nauthor: Sales Team\ndate: 2024-10-08\nlang: en\ntoc: true\nabstract: \"Q3 revenue grew 12% YoY with record new customer acquisition.\"\n---\n```\n\n**Component blocks:**\n```\n:::kpi\nitems:\n  - label: Revenue\n    value: $2.45M\n    delta: ↑12%\n  - label: New Clients\n    value: 183\n    delta: ↑8%\n:::\n\n:::chart type=line title=\"Monthly Revenue\"\nlabels: [Jul, Aug, Sep]\ndatasets:\n  - label: Actual\n    data: [780000, 820000, 850000]\n:::\n\n:::timeline\n- 2024-10-15: Q4 targets released\n- 2024-10-31: Product launch\n:::\n\n:::callout type=tip\nKey insight goes here.\n:::\n```\n\nBadges remain optional HTML chips for scanability; they are not standalone IR tags. Timelines are strict chronological components and should use explicit time tokens such as `2024-10-15` or `Q4 2024`.\n\n---\n\n## For AI Agents\n\nOther agents can call report-creator programmatically:\n\n```\n# From document\n/report --from ./analysis.md --output summary.html\n\n# From URL\n/report --from https://example.com/report-page --theme data-story\n\n# Two-step with review\n/report --plan \"Market Analysis\" --from ./raw-data.md\n/report --generate market-analysis.report.md\n/report --review report.html\n```\n\n**Extracting structured data:**\n```python\nfrom bs4 import BeautifulSoup\nimport json\n\nsoup = BeautifulSoup(open(\"report.html\"), \"html.parser\")\nsummary = json.loads(soup.find(\"script\", {\"id\": \"report-summary\"}).string)\nprint(summary[\"title\"], summary[\"kpis\"])\n```\n\n---\n\n## Export\n\nEvery report has a built-in **↓ Export** button (bottom-right):\n\n| Option | How it works |\n|--------|--------------|\n| Print / PDF | Opens browser print dialog → Save as PDF |\n| PNG (Desktop) | Full page at 2× resolution |\n| PNG (Mobile) | Report body at 1170px wide (≈3× iPhone) |\n\n**Tip:** Uncheck \"Headers and footers\" in print dialog for clean PDFs.\n\n---\n\n## Use Case: Daily Work Report → Telegram\n\n```\nGenerate a report of today's work in dark-board style, export as IM image, send via Telegram.\n```\n\nOpenClaw will:\n1. Summarize tasks, decisions, next steps\n2. Render to `dark-board` HTML with KPIs and timeline\n3. Screenshot as 800px JPEG (animations auto-disabled for headless capture)\n4. Send directly to your Telegram channel\n\n---\n\n## Examples\n\n| File | Description |\n|------|-------------|\n| [examples/en/business-report.html](examples/en/business-report.html) | Q3 Sales Report (EN) |\n| [examples/en/business-report-reviewed-demo.html](examples/en/business-report-reviewed-demo.html) | Reviewed demo with stronger BLUF (EN) |\n| [examples/zh/business-report.html](examples/zh/business-report.html) | Q3 销售业绩报告（中文）|\n| [examples/review-reports/](examples/review-reports/) | Structured review report examples |\n\n---\n\n## Requirements\n\nNo dependencies. Works in any modern browser.\n\nFor offline bundles with `--bundle`: internet connection needed once to inline CDN assets.\n\n---\n\n## Compatibility\n\n| Platform | Version | Install path |\n|----------|---------|--------------|\n| Claude Code | any | `~/.claude/skills/kai-report-creator/` |\n| OpenClaw | ≥ 0.9 | `~/.openclaw/skills/kai-report-creator/` |\n\n---\n\n## Version History\n\n**v1.23.2** — Complete fixture rubric release: add checked-in positive-case style rubrics, require `eval_complete` for green captured-run results, compare completeness regressions, and refresh the deterministic fixture baseline to 6/6 passing at 100.0 average with Style 25.0.\n\n**v1.23.1** — Captured-run skill eval release: add OpenAI-style skill eval prompts, fixture and Codex trace runners, normalized timeout handling, baseline comparison, saved fixture/live baselines, release-verification integration, and README guidance for comparing future skill changes against the saved scores.\n\n**v1.23.0** — Final HTML quality gate release: add `scripts/html_quality_gate.py` to validate rendered shell IDs, theme CSS fidelity, regular-lumen/fangsong typography and layout markers, and KPI values; require every KPI card to use a real quantitative value; remove forced placeholder KPIs from periodic reports; fix dark-board status KPI examples; and add regression coverage for the failure modes.\n\n**v1.22.0** — Reference split and validator profile release: split oversized shell and rendering contracts into route-specific child references, add a reference index and validator-facing usage boundary artifacts, add a generated-cache cleanup gate to release verification, and document golden eval cases for external validators.\n\n**v1.21.2** — Packaging cleanup: remove the tracked `docs/` directory from GitHub and ClawHub packages, ignore the local docs symlink, and keep project documentation in `/Users/song/projects/mydocs/report-creator`.\n\n**v1.21.1** — Skill prompt budget release: compress `SKILL.md` into a thin routing contract under 320 lines, move shell metadata and duplicate-date details into references, add a size-budget regression test, and include that test in the fast verification path.\n\n**v1.21.0** — Late-context isolation and release hardening: require `--generate` to extract exactly one IR block from context, add context isolation helpers plus late-context eval runner, expand release verification and fast-test coverage, normalize footer/watermark shell metadata, and tighten bilingual doc-sync guardrails.\n\n**v1.20.1** — Design philosophy expansion: added §6 (Contract Enforcement Before Render), §7 (Eval as Quality Boundary), §8 (Contract Checks as Programmable Guardrails) documenting the guard pipeline and eval workflow principles.\n\n**v1.20.0** — Guard validation pipeline: Python guard (`scripts/guard_validate.py`) runs before HTML rendering with zero-drift report_class resolution, auto-downgrade invalid blocks (kpi→callout, chart→table, timeline→list, diagram→callout), IR hash embedding in `<meta name=\"ir-hash\">` for traceability, and guard integration tests.\n\n**v1.18.0** — Theme routing fixed for work reports: priority-ordered keyword matching now correctly routes weekly/daily/monthly reports to `regular-lumen` (first priority) and generic work progress reports to `corporate-blue` (fallback), instead of misrouting to dark-tech/dark-board due to overlapping keywords like \"项目/进展/状态\".\n\n**v1.17.1** — Resolve ClawHub version conflict (merge ClawHub v1.16.1 updates).\n\n**v1.17.0** — Merge ClawHub v1.16.1 updates + add watermark feature.\n\n**v1.16.0** — Minimal Kami borrowing, fully landed: add hard `anti-patterns.md` and `diagram-decision-rules.md`, introduce silent `spec-loading-matrix.md` plus optional `archetype` routing hints, add maintainer-side `scripts/verify-release.py`, and raise the Windows release suite to 134 passing tests.\n\n**v1.15.0** — IR contract hardening and eval foundation: split failures into `invalid_syntax` / `invalid_semantics` / `contract_conflict`, formalize `kpi` / `chart` / `timeline` / `diagram` schemas, demote `badge` to optional enhancement, add repo-contained eval cases plus `run-report-evals.py`, fix install paths to `kai-report-creator`, and bring the Windows release suite to 125 passing tests.\n\n**v1.14.2** — Export menu completeness enforced in the standard generate flow: require print/desktop/mobile/IM export entries plus JS bindings during pre-write shell validation and silent final review; add shell contract coverage so reports no longer regress to partial export menus.\n\n**v1.14.1** — Print/PDF export fix: preserve report background and force animated KPI/data blocks visible during print export; add print export regression coverage.\n\n**v1.14.0** — ECharts standard: unified all charts on ECharts (was Chart.js), added bar/line/radar/pie ECharts templates, grid bottom rule for rotated labels, line data integrity rule, 14 new chart rendering contract tests.\n\n**v1.13.0** — L2 HTML shell structure validation: 10 mandatory elements check in SKILL.md pre-write, design-quality.md §8, 30 new HTML shell contract tests (BUG-001 fix).\n\n**v1.9.0** — Report Review System: `--review` with 13 checkpoints; silent final review in `--generate`; L0/L1 quality layering.\n\n**v1.8.3** — KPI overflow fix: `.kpi-suffix` for long units; rendering rules updated.\n\n**v1.8.2** — Restrained color system: shared badges default to neutral; `data-report-mode=\"comparison\"` for entity colors.\n\n**v1.8.1** — Export background fix: resolve `--bg` before fallback.\n\n**v1.8.0** — Custom themes: `--theme <name>` loads `themes/<name>/`.\n\n**v1.6.0** — Sankey chart: `:::chart type=sankey` for flow diagrams.\n\n**v1.5.0** — Design Quality Baseline: 90/8/2 color law, KPI grid rules, content-tone calibration.\n\n**v1.4.0** — Summary card overlay with poster entry card behavior and KPI/section summaries.\n\n**v1.3.0** — Zero-dependency animations: staggered KPI bounce, timeline slide-in.\n\n**v1.0.0** — Initial release with 6 themes and 9 component types.\n\nFile v1.23.2:tests/fixtures/skill-evals/README.md\n\n# Captured Runner Trace Fixtures\n\nThese fixtures document the real Codex JSONL shape used by\n`scripts/run-skill-evals.py`. Parser support must be based on captured traces\nlike these, not guessed runner event names.\n\nObserved Codex JSONL shape:\n\n- Top-level events include `thread.started`, `turn.started`, `item.started`,\n  `item.completed`, and `turn.completed`.\n- Tool calls appear under `item` objects. Shell commands use\n  `item.type == \"command_execution\"` with `command`, `exit_code`, and `status`.\n- File reads and writes are not guaranteed to appear in the captured trace; the\n  current adapter only consumes explicit `file_read` and `file_write` items if a\n  future Codex trace includes them.\n- Token usage appears on `turn.completed` as `usage.input_tokens` and\n  `usage.output_tokens`.\n- Runner warnings can come from `item.type == \"error\"` events or from a nonzero\n  live `codex exec` return code.\n\nNormalized fixture files use the runner-agnostic `normalized-v1` schema. Unit\ntests should score these normalized metrics directly so ordinary pytest never\ninvokes a live agent or network-backed runner.\n\nFile v1.23.2:themes/README.md\n\n# Custom Themes\n\nPlace folders here to add your own themes to kai-report-creator.\n\n## Directory Structure\n\n```\nthemes/\n  your-theme-name/\n    reference.md   ← Style description (AI reads and generates CSS variables)\n    theme.css      ← Direct CSS definitions (optional, takes priority over reference.md)\n```\n\nBoth files are optional and can be used independently or together:\n\n| Case | Behavior |\n|------|----------|\n| Only `reference.md` | AI reads style description and derives `:root` CSS variables |\n| Only `theme.css` | CSS variables used directly, fully predictable output |\n| Both present | `theme.css` takes priority; `reference.md` serves as style documentation |\n\n## Usage\n\n```bash\n/report --theme your-theme-name \"Report topic\"\n```\n\nOr specify in `.report.md` frontmatter:\n\n```yaml\ntheme: your-theme-name\n```\n\n## reference.md Format\n\n```markdown\n# Theme Name — Style Reference\n\nOne sentence description. Inspiration / aesthetic / mood.\n\n---\n\n## Colors\n\n​```css\n:root {\n  --primary:      #...;   /* Main color: headings, links, accents */\n  --bg:           #...;   /* Page background */\n  --surface:      #...;   /* Card background */\n  --text:         #...;   /* Body text */\n  --text-muted:   #...;   /* Secondary text */\n  --border:       #...;   /* Borders / dividers */\n}\n​```\n\n## Typography\n\nFont choices. Serif or sans-serif? Geometric or humanist? Google Fonts links.\n\n## Layout\n\nWhitespace style, card border-radius, max-width preferences.\n\n## Best For\n\nBrand reports, research docs, internal newsletters...\n```\n\n## theme.css Format\n\nDefine `:root` CSS variables to override the base theme defaults.\n\n```css\n:root {\n  --primary:      #C2410C;\n  --primary-light:#FFF7ED;\n  --accent:       #EA580C;\n  --bg:           #FFFBF7;\n  --surface:      #FFFFFF;\n  --text:         #1C1917;\n  --text-muted:   #78716C;\n  --border:       #E7E5E4;\n  --font-sans:    'Inter', system-ui, sans-serif;\n  --font-mono:    'JetBrains Mono', monospace;\n  --radius:       6px;\n}\n```\n\nSee `templates/themes/corporate-blue.css` for all available variables.\n\n## Notes\n\n- Directories starting with `_` (e.g. `_example-warm-editorial`) are ignored and won't appear in theme lists\n- Theme names support only letters, numbers, and hyphens: `my-brand`, `warm-editorial`\n- Custom themes take priority over built-in themes with the same name\n\n## Sharing Themes\n\nPublish your theme folder as a git repo — others clone it into their `themes/` directory:\n\n```bash\ngit clone https://github.com/yourname/report-theme-mybrand \\\n  ~/.claude/skills/report-creator/themes/mybrand\n```\n\nFile v1.23.2:_meta.json\n\n{\n  \"ownerId\": \"kn7bjv9d2ccsjqk1m4edthgtgx82fem8\",\n  \"slug\": \"kai-report-creator\",\n  \"version\": \"1.23.2\",\n  \"publishedAt\": 1779010847569\n}\n\nFile v1.23.2:references/anti-patterns.md\n\n# Report Anti-Patterns\n\nLoad this file before `--generate`. It is the report-specific anti-pattern layer on top of `references/design-quality.md` and `references/review-checklist.md`.\n\nThese rules are intentionally blunt. If a draft triggers one of these patterns, rewrite it before writing HTML.\n\n## Contract Shape\n\nEach anti-pattern entry should answer the same four questions.\n\n## Symptom\n\nWhat the bad output usually looks like in IR, prose, or HTML.\n\n## Why It Hurts\n\nWhy the pattern makes async reading slower, noisier, or less trustworthy.\n\n## Preferred Replacement\n\nWhich component or prose pattern should replace the bad pattern.\n\n## Rewrite Rule\n\nOne direct instruction that the generator or reviewer can apply without debate.\n\n## `fake-kpi`\n\n- Symptom: KPI cards are filled with placeholders, status words, long explanatory sentences, or qualitative claims that are not actually metrics.\n- Why It Hurts: It creates a fake visual anchor and tells the reader that the report has hard numbers when it does not.\n- Preferred Replacement: `callout`, prose, or `table`.\n- Rewrite Rule: If the source does not provide a short real numeric metric, do not emit `:::kpi`; downgrade to `callout`, `timeline`, or `table`.\n\n## `decorative-chart`\n\n- Symptom: A chart appears mainly to decorate a section, restate obvious text, or visualize placeholder-only values.\n- Why It Hurts: It adds scanning cost without increasing understanding and can imply false analytical rigor.\n- Preferred Replacement: prose, `table`, or a short `callout`.\n- Rewrite Rule: If the reader learns nothing new from the chart shape, remove the chart and state the takeaway directly.\n\n## `pseudo-timeline`\n\n- Symptom: A timeline is used for parallel principles, capability buckets, or unordered stages that are not truly chronological.\n- Why It Hurts: The component communicates sequence and causality that the content does not actually have.\n- Preferred Replacement: `list`, prose, or `callout`.\n- Rewrite Rule: If items can be reordered without changing meaning, do not use `:::timeline`.\n\n## `template-heading`\n\n- Symptom: Section headings read like empty labels such as \"Overview\", \"Summary\", \"核心能力\", or \"Next Steps\".\n- Why It Hurts: Headings stop carrying argument structure, so the document becomes harder to skim and harder to remember.\n- Preferred Replacement: information-bearing headings that state a claim, implication, or contrast.\n- Rewrite Rule: Rewrite noun-label headings into content-specific statements before render.\n\n## `badge-quota-thinking`\n\n- Symptom: Badges are inserted just to hit a count or to make the page feel \"busy enough\".\n- Why It Hurts: Optional scan anchors turn into noise, and the reader can no longer tell which chips actually matter.\n- Preferred Replacement: no badge at all, or one status/category/entity badge only where it clarifies the content.\n- Rewrite Rule: Add a badge only when it disambiguates status, category, or entity identity; never fill a quota.\n\n## `color-flood`\n\n- Symptom: Accent colors spread across headings, KPI values, badges, charts, dividers, and callouts at the same time.\n- Why It Hurts: The page loses hierarchy because everything is trying to be the focal point.\n- Preferred Replacement: neutral text with one restrained structural accent.\n- Rewrite Rule: Keep the main reading surface neutral and reserve accent color for one clear job at a time.\n\n## `summary-without-judgment`\n\n- Symptom: The opening summary repeats background or facts but never states what matters or why the reader should care.\n- Why It Hurts: Async readers do not know the report's conclusion, decision frame, or next action within the first screen.\n- Preferred Replacement: BLUF-style opening prose.\n- Rewrite Rule: Open with purpose plus judgment, not background plus scene-setting.\n\n## `action-without-decision-context`\n\n- Symptom: The report ends with recommendations or next steps that are detached from any stated decision, tradeoff, or threshold.\n- Why It Hurts: The actions feel generic because the reader cannot tell what decision they are supposed to support.\n- Preferred Replacement: action block tied to a named decision, condition, or trigger.\n- Rewrite Rule: Every action section must state what decision it supports, what signal triggers it, or what risk it addresses.\n\nFile v1.23.2:references/design-quality.md\n\n# Design Quality Baseline\n\nThis file defines the design quality rules for every generated report. Load alongside `rendering-rules.md` during `--generate` mode. These rules exist to prevent AI-slop patterns and enforce visual discipline.\n\n## 1. The 90/8/2 Color Law\n\nEvery report must follow this color allocation:\n\n| Share | Role | Variable | Usage |\n|-------|------|----------|-------|\n| **90%** | Neutral surface | `--bg`, `--surface`, `--text` | Background, body text, cards |\n| **8%** | Structural color | `--primary` | Section borders, one accent block, h2 underlines |\n| **2%** | Bullet point | `--accent-pop` (default = `--primary` at full opacity) | At most 1-2 precise hits: a single KPI value, one callout border, one chart series |\n\n**Violations to avoid:**\n- `var(--primary)` used on heading text, KPI values, chart bars, callout borders, TOC links, AND badges simultaneously → this is a primary-color flood\n- Every KPI card a different accent color → accent system should feel like seasoning, not confetti\n- Using more than 2 accent colors per page (chart series excluded)\n\n## 2. Typography: 10:1 Scale Ratio\n\nThe largest text element on any page must be ≥ 10× the smallest readable element.\n\n| Element | Min size | Max size |\n|---------|----------|---------|\n| Fine print, badges, meta | 11px | — |\n| Body text | 15px | — |\n| h3 | 17px | — |\n| h2 | 20px | — |\n| Report title | 2.6rem+ | — |\n\n**Apply to report title:** Minimum `font-size: 2.8rem`. For strong content topics, push to `3.5–4rem` with `line-height: 1.05` and `letter-spacing: -0.03em`. The title should feel like an anchor, not a label.\n\n**Apply to section headings:** `h2` gets a subtle left border or underline using `--primary` at 8% allocation — not a background color.\n\n**Letter-spacing upper limit:** Body text and prose must never exceed `letter-spacing: 0.05em`. Wide letter-spacing on body text (>0.05em) breaks word shape recognition and slows reading. Negative letter-spacing is acceptable for titles (`-0.03em`) and headings (`-0.02em`).\n\n## 3. KPI Grid Column Rules\n\nDo not default all KPI grids to 3 columns. Match columns to KPI count for better proportion:\n\n| KPI count | Grid columns | CSS |\n|-----------|-------------|-----|\n| 1–2 | 2 columns | `grid-template-columns: repeat(2, 1fr)` |\n| 3 | 3 columns | `grid-template-columns: repeat(3, 1fr)` |\n| 4 | 2×2 | `grid-template-columns: repeat(2, 1fr)` |\n| 5–6 | 3 columns (last row 2) | `grid-template-columns: repeat(3, 1fr)` |\n| 7+ | 3 columns with dividers between groups | `grid-template-columns: repeat(3, 1fr)` + `gap: 0.5rem 1rem` |\n\n**Non-equal widths:** When one KPI is the \"hero\" metric, use `grid-template-columns: 2fr 1fr 1fr` or `1.5fr 1fr` to create visual hierarchy.\n\n## 4. Forbidden Patterns (Anti-AI-Slo\n\nArchive v1.23.1: 173 files, 485637 bytes\n\nFiles: check-doc-sync.py (5869b), CLAUDE.md (1723b), evals/__init__.py (49b), evals/baselines/2026-05-17-baseline-summary.md (4259b), evals/baselines/2026-05-17-late-context-evals.json (11926b), evals/baselines/2026-05-17-report-evals.json (5255b), evals/baselines/2026-05-17-skill-evals-codex-live.json (160772b), evals/baselines/2026-05-17-skill-evals-fixture.json (8991b), evals/cases/en-ops-weekly/noise-context.md (1694b), evals/cases/en-ops-weekly/report.report.md (1273b), evals/cases/en-ops-weekly/source.md (535b), evals/cases/guard-broken-chart-schema/report.report.md (496b), evals/cases/guard-broken-chart-schema/source.md (56b), evals/cases/guard-narrative-placeholder-kpi/report.report.md (1471b), evals/cases/guard-narrative-placeholder-kpi/source.md (374b), evals/cases/zh-ai-collaboration/noise-context.md (2285b), evals/cases/zh-ai-collaboration/report.report.md (1805b), evals/cases/zh-ai-collaboration/source.md (804b), evals/cases/zh-quarterly-growth/noise-context.md (1785b), evals/cases/zh-quarterly-growth/report.report.md (1385b), evals/cases/zh-quarterly-growth/source.md (406b), evals/contract_checks.py (8970b), evals/failure-map.md (1940b), evals/golden_cases.yaml (2856b), evals/report-cases.csv (862b), evals/report-skill-prompts.csv (886b), evals/rubric.schema.json (2127b), evals/skill-prompts/boundary-blueprint-report.md (734b), evals/skill-prompts/contextual-research.md (806b), evals/skill-prompts/explicit-generate.md (582b), evals/skill-prompts/implicit-weekly-progress.md (608b), evals/skill-prompts/negative-html-export.md (118b), evals/skill-prompts/negative-slide-deck.md (114b), evals/skill-run-rubric.schema.json (1182b), examples/business-report.report.md (1650b), examples/do-not-use.md (508b), examples/en/business-report-reviewed-demo.html (22220b), examples/en/business-report.html (24153b), examples/en/monthly-progress-reviewed-demo.html (17571b), examples/en/monthly-progress.html (16538b), examples/research-report.report.md (1718b), examples/review-reports/business-report-demo-review-report.md (3376b), examples/review-reports/monthly-progress-demo-review-report.md (3125b), examples/review-reports/monthly-progress-zh-review-report.md (3221b), examples/tech-doc.report.md (1706b), examples/when-to-use.md (799b), examples/zh/business-report.html (23702b), examples/zh/kai-report-creator-guide.html (32103b), examples/zh/kai-report-creator-guide.report.md (4833b), examples/zh/monthly-progress-reviewed-demo.html (17632b), examples/zh/monthly-progress.html (15933b), pytest.ini (125b), README.md (30115b), README.zh-CN.md (27993b), references/anti-patterns.md (4303b), references/design-quality.md (15801b), references/diagram-decision-rules.md (1317b), references/generate-flow.md (1863b), references/html-shell-template.md (5060b), references/html-shell/core-structure.md (7024b), references/html-shell/export.md (9371b), references/html-shell/print-responsive.md (1509b), references/html-shell/shared-component-css.md (12342b), references/html-shell/summary-card.md (10413b), references/html-shell/toc-edit-summary.md (11506b), references/impeccable-anti-patterns.md (5625b), references/I...","readmeExcerpt":"Skill: Kai Report Creator V1.23.3 Publish Owner: kaisersong Summary: Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and Eng... Tags: latest:1.23.3 Version history: v1.23.3 | 2026-05-17T09:51:54.143Z | user No-agent eval gate release: release verification now uses fixture skill evals by default, requires no Codex/Cla","codeSnippets":[],"executableExamples":[{"language":"yaml","snippet":"theme: corporate-blue                  # Optional. Default: corporate-blue\nreport_class: mixed                    # Optional. Values: narrative, mixed, data\narchetype: research                    # Optional lightweight archetype hint for silent classification."},{"language":"bash","snippet":"python <skill-dir>/scripts/export-image.py <output.html> --mode <mode>"},{"language":"text","snippet":"--plan        → only IR rules + component syntax; no CSS, no HTML shell\n--generate    → one theme CSS + one shared CSS; other theme files stay on disk\n--themes      → pre-built preview HTML; skill doesn't parse internals"},{"language":"text","snippet":"---                         ← Frontmatter: document identity\ntitle: Q3 Sales Report         What is this? Who made it? How should it look?\ntheme: corporate-blue          Declares intent, not content.\n---\n\n## Section Heading         ← Prose: human narrative\nPlain Markdown text...        Written naturally. AI renders to semantic HTML.\n\n:::kpi                     ← Component blocks: structured data\n- Revenue: $2.45M ↑12%       Machine-parseable. AI renders deterministically.\n:::"},{"language":"text","snippet":"Layer 1 — <script id=\"report-summary\">    Document-level: title, abstract, all KPIs\nLayer 2 — data-section data-summary       Section-level: heading + one-sentence summary\nLayer 3 — data-component data-raw         Component-level: raw KPI/chart/table data"},{"language":"text","snippet":"IR → Guard (validate + downgrade) → Renderer → HTML\n              ↑\n              Block invalid input"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: kai-report-creator\ndescription: Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and English equally. Supports generating from raw notes, data, URLs, or an approved plan file. Use for --plan (structure first), --generate (render to HTML), --review (one-pass automatic refinement), --themes (preview styles), --from FILE, --bundle, --export-image flags. Does NOT apply to exporting finished HTML to PPTX/PNG (use kai-html-export) or creating slide decks (use kai-slide-creator).\nversion: 1.23.3\nuser-invocable: true\nmetadata: {\"openclaw\": {\"emoji\": \"📊\"}}\n---\n\n# kai-report-creator\n\nGenerate single-file HTML reports from source notes or `.report.md` IR. Keep this file as a thin router: load only the references needed for the current path.\n\n## Core Principles\n\n1. **Zero Dependencies** — generated reports are self-contained HTML, with CDN or bundled assets only when needed.\n2. **User Provides Data, AI Provides Structure** — never fabricate facts or numbers; use `[数据待填写]` / `[INSERT VALUE]` when data is missing.\n3. **Plan Before Generate** — complex reports should become `.report.md` IR first, then HTML.\n4. **Progressive Disclosure for AI** — output keeps `report-summary`, section annotations, and component data machine-readable.\n5. **Thin Routing Over Prompt Growth** — `SKILL.md` routes work; detailed rules live in references.\n6. **Contracts and Gates Beat Prompt Soup** — prefer IR, guard validation, shell tests, and post-render review over adding more prose to this hot path.\n\n## Command Routing\n\nWhen invoked as `/report [flags] [content]`, parse flags first:\n\n| Flag | Action |\n|------|--------|\n| `--plan \"topic\"` | Write `.report.md` IR only. Stop after saving it. |\n| `--generate [file]` | Render one `.report.md` IR to HTML. With no file given, treat as IR from context: extract exactly one valid IR block from context. Never render the surrounding conversation. |\n| `--review [file]` | Refine an existing HTML report with `references/review-checklist.md`. |\n| `--themes` | Write the themes preview HTML. |\n| `--from <file>` | If the file starts with frontmatter, treat as IR; otherwise create IR, then render. |\n| `--theme <name>` | Override the theme. Built-ins: `corporate-blue`, `minimal`, `dark-tech`, `dark-board`, `data-story`, `newspaper`, `regular-lumen`, `fangsong`. |\n| `--template <file>` | Use a custom HTML template. See `references/toc-and-template.md`. |\n| `--output <file>` | Save to this path instead of the default. |\n| `--bundle` | Inline CDN assets where supported. |\n| `--export-image [mode]` | After HTML generation, run `scripts/export-image.py`; mode is `im`, `mobile`, `desktop`, or `all`. |\n| no flags + text | Create IR internally, then render HTML. |\n| no flags + IR in context | Treat as `--generate` from context. |\n\nDefault output filename: `report-<YYYY-MM-DD>-<slug>.html`. Slug: lowercase ASCII, non-alphanumeric to hyphens, collapse"},{"path":"README.md","content":"# kai-report-creator\n\n> You have data, decisions, and deadlines — but decision makers don't have time to read everything. AI can generate reports, but they often look instantly AI-made: template headings, primary color flooding every element, 3-column KPI grids regardless of count. kai-report-creator gives you polished, async-friendly reports in one command: drop a document or URL, pick a theme, and get a single HTML file that survives first-contact reading. Downstream AI agents can also parse it — the output embeds a 3-layer machine-readable structure.\n>\n> **[See the guide as a report →](https://kaisersong.github.io/kai-report-creator/examples/zh/kai-report-creator-guide.html)** — this document was generated by kai-report-creator itself.\n\nA skill for [Claude Code](https://claude.ai/claude-code) and [OpenClaw](https://openclaw.ai) that turns plain text or structured outlines into polished HTML reports.\n\nEnglish | [简体中文](README.zh-CN.md)\n\n---\n\n## Live Demo\n\nClick any screenshot to open the live demo:\n\n<table>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/corporate-blue.html\"><img src=\"templates/screenshots/corporate-blue.png\" width=\"360\" alt=\"corporate-blue\"/><br/><b>corporate-blue</b></a><br/><sub>Warm Premium · Business</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/minimal.html\"><img src=\"templates/screenshots/minimal.png\" width=\"360\" alt=\"minimal\"/><br/><b>minimal</b></a><br/><sub>Research · Academic</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/dark-tech.html\"><img src=\"templates/screenshots/dark-tech.png\" width=\"360\" alt=\"dark-tech\"/><br/><b>dark-tech</b></a><br/><sub>Engineering · Ops</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/dark-board.html\"><img src=\"templates/screenshots/dark-board.png\" width=\"360\" alt=\"dark-board\"/><br/><b>dark-board</b></a><br/><sub>Dashboards · Architecture</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/data-story.html\"><img src=\"templates/screenshots/data-story.png\" width=\"360\" alt=\"data-story\"/><br/><b>data-story</b></a><br/><sub>Annual Reports · Growth</sub></td>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/newspaper.html\"><img src=\"templates/screenshots/newspaper.png\" width=\"360\" alt=\"newspaper\"/><br/><b>newspaper</b></a><br/><sub>Editorial · Industry Analysis</sub></td>\n</tr>\n<tr>\n<td align=\"center\"><a href=\"https://kaisersong.github.io/kai-report-creator/templates/en/regular-lumen.html\"><img src=\"templates/screenshots/regular-lumen.png\" width=\"360\" alt=\"regular-lumen\"/><br/><b>regular-lumen</b></a><br/><sub>Periodic Reports · Weekly/Daily/Monthly</sub></td>\n</tr>\n</table>\n\nPreview the theme gallery: `/report --themes` → opens `report-themes-preview.html`\n\n---\n\n## Design Philosophy: Skil"},{"path":"tests/fixtures/skill-evals/README.md","content":"# Captured Runner Trace Fixtures\n\nThese fixtures document the real Codex JSONL shape used by\n`scripts/run-skill-evals.py`. Parser support must be based on captured traces\nlike these, not guessed runner event names.\n\nObserved Codex JSONL shape:\n\n- Top-level events include `thread.started`, `turn.started`, `item.started`,\n  `item.completed`, and `turn.completed`.\n- Tool calls appear under `item` objects. Shell commands use\n  `item.type == \"command_execution\"` with `command`, `exit_code`, and `status`.\n- File reads and writes are not guaranteed to appear in the captured trace; the\n  current adapter only consumes explicit `file_read` and `file_write` items if a\n  future Codex trace includes them.\n- Token usage appears on `turn.completed` as `usage.input_tokens` and\n  `usage.output_tokens`.\n- Runner warnings can come from `item.type == \"error\"` events or from a nonzero\n  return code in a manually captured `codex exec` trace.\n\nNormalized fixture files use the runner-agnostic `normalized-v1` schema. Unit\ntests should score these normalized metrics directly so ordinary pytest never\ninvokes a live agent or network-backed runner."},{"path":"themes/README.md","content":"# Custom Themes\n\nPlace folders here to add your own themes to kai-report-creator.\n\n## Directory Structure\n\n```\nthemes/\n  your-theme-name/\n    reference.md   ← Style description (AI reads and generates CSS variables)\n    theme.css      ← Direct CSS definitions (optional, takes priority over reference.md)\n```\n\nBoth files are optional and can be used independently or together:\n\n| Case | Behavior |\n|------|----------|\n| Only `reference.md` | AI reads style description and derives `:root` CSS variables |\n| Only `theme.css` | CSS variables used directly, fully predictable output |\n| Both present | `theme.css` takes priority; `reference.md` serves as style documentation |\n\n## Usage\n\n```bash\n/report --theme your-theme-name \"Report topic\"\n```\n\nOr specify in `.report.md` frontmatter:\n\n```yaml\ntheme: your-theme-name\n```\n\n## reference.md Format\n\n```markdown\n# Theme Name — Style Reference\n\nOne sentence description. Inspiration / aesthetic / mood.\n\n---\n\n## Colors\n\n​```css\n:root {\n  --primary:      #...;   /* Main color: headings, links, accents */\n  --bg:           #...;   /* Page background */\n  --surface:      #...;   /* Card background */\n  --text:         #...;   /* Body text */\n  --text-muted:   #...;   /* Secondary text */\n  --border:       #...;   /* Borders / dividers */\n}\n​```\n\n## Typography\n\nFont choices. Serif or sans-serif? Geometric or humanist? Google Fonts links.\n\n## Layout\n\nWhitespace style, card border-radius, max-width preferences.\n\n## Best For\n\nBrand reports, research docs, internal newsletters...\n```\n\n## theme.css Format\n\nDefine `:root` CSS variables to override the base theme defaults.\n\n```css\n:root {\n  --primary:      #C2410C;\n  --primary-light:#FFF7ED;\n  --accent:       #EA580C;\n  --bg:           #FFFBF7;\n  --surface:      #FFFFFF;\n  --text:         #1C1917;\n  --text-muted:   #78716C;\n  --border:       #E7E5E4;\n  --font-sans:    'Inter', system-ui, sans-serif;\n  --font-mono:    'JetBrains Mono', monospace;\n  --radius:       6px;\n}\n```\n\nSee `templates/themes/corporate-blue.css` for all available variables.\n\n## Notes\n\n- Directories starting with `_` (e.g. `_example-warm-editorial`) are ignored and won't appear in theme lists\n- Theme names support only letters, numbers, and hyphens: `my-brand`, `warm-editorial`\n- Custom themes take priority over built-in themes with the same name\n\n## Sharing Themes\n\nPublish your theme folder as a git repo — others clone it into their `themes/` directory:\n\n```bash\ngit clone https://github.com/yourname/report-theme-mybrand \\\n  ~/.claude/skills/report-creator/themes/mybrand\n```"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7bjv9d2ccsjqk1m4edthgtgx82fem8\",\n  \"slug\": \"kai-report-creator\",\n  \"version\": \"1.23.3\",\n  \"publishedAt\": 1779011514143\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and Eng... Skill: Kai Report Creator V1.23.3 Publish Owner: kaisersong Summary: Use when the user wants to CREATE or GENERATE a report, business summary, data dashboard, or research doc — 报告/数据看板/商业报告/研究文档/KPI仪表盘. Handles Chinese and Eng... Tags: latest:1.23.3 Version history: v1.23.3 | 2026-05-17T09:51:54.143Z | user No-agent eval gate release: release verification now uses fixture skill evals by default, requires no Codex/Cla","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1852,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T22:07:20.968Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T22:07:20.968Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T22:31:13.654Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}