v3.0.0.0 feat: branded HTML reports + per-course export folder (#28)

* feat(templates): branded HTML report skeleton + slug helper

Add the foundation for branded, self-contained HTML reports:

- templates/report.html.tmpl - per-skill report skeleton (visual contract)
- templates/index.html.tmpl - course dashboard skeleton (pipeline output)
- templates/assets/idstack.css - brand stylesheet (auto light/dark, print-
  friendly, scholarly serif, severity + tier badges, matches idstack.org)
- bin/idstack-slugify - course_name -> filesystem-safe slug helper used by
  every report-producing skill to land outputs under
  .idstack/exports/<course-slug>/

These files are pure additions; nothing else references them yet. Skills
are wired in the next commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(reports): switch human-facing reports to branded HTML

The human-facing report format moves from Markdown to HTML, and every per-
course artifact (per-skill reports, pipeline dashboard, LMS packages) lives
under one self-describing folder: .idstack/exports/<course-slug>/.

Spec changes:
- report-format.md becomes the content contract (what each field must
  carry); the visual contract lives in templates/report.html.tmpl.
- manifest-schema.md documents the new report_path semantics
  (.idstack/exports/<course-slug>/<skill>.html) and the slug derivation
  rule.
- agent-context.md mirrors CLAUDE.md's dual-output description for Codex
  sessions; AGENTS.md regenerated.

Skill changes (all 9 report-producing skills + pipeline orchestrator):
- needs-analysis, learning-objectives, assessment-design, course-builder,
  course-quality-review, accessibility-review, red-team, course-export,
  course-import: switch report write from .idstack/reports/<skill>.md to
  .idstack/exports/<course-slug>/<skill>.html; each prep block computes
  the slug via bin/idstack-slugify and copies templates/assets/idstack.css
  into the course folder so the deliverable is self-contained.
- course-export additionally moves LMS artifacts (.imscc, scorm-export.zip)
  into the same course folder, and now produces a course-export.html
  report alongside the LMS package.
- pipeline orchestrator writes an index.html course dashboard at the
  folder root with readiness scores, links to every per-skill report, and
  a where-to-start pointer; replaces the old pipeline.md aggregate.

Both Claude and Codex flavors regenerated from the same templates via
bin/idstack-gen-skills.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(cli): generator checks new templates; status reads new layout

- bin/idstack-gen-skills sanity-checks that templates/report.html.tmpl,
  templates/index.html.tmpl, and templates/assets/idstack.css exist at
  startup. Missing files would silently break every skill that produces a
  report, so fail loud at the generator.
- bin/idstack-status surfaces reports from .idstack/exports/<course-slug>/
  instead of the legacy .idstack/reports/. Auto-resolves the slug from
  project_name; falls back to the only .idstack/exports/* subfolder when
  exactly one exists (handles legacy folders left behind after rename).
  Lists the course dashboard first, then per-skill HTML reports, then LMS
  packages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: smoke assertions for HTML pipeline + slug edge cases

Pin the new contract so regressions get caught:

- Every report-producing skill .tmpl must reference .idstack/exports/, call
  idstack-slugify, and copy templates/assets/idstack.css.
- pipeline .tmpl must produce index.html under exports/<slug>/.
- bin/idstack-slugify must be installed and executable.
- Slug rule pinned with four cases: "Introduction to Biology 101" ->
  introduction-to-biology-101; "Géographie I" -> geographie-i (NFKD-fold);
  "" -> untitled-course; "!!!" -> untitled-course.
- Templates exist and carry expected placeholders.

Total: 255 checks (was 225).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: sync README/CLAUDE/CONTRIBUTING/ROADMAP/landing for HTML reports

- README.md: skill table cites new HTML report paths; architecture diagram
  shows the .idstack/exports/<course-slug>/ folder layout; "How idstack
  reports back to you" leads with branded HTML and the self-contained
  folder mental model; pipeline produces an index.html dashboard.
- CLAUDE.md: dual-output contract is now JSON + HTML; spells out the slug
  derivation and the bundled CSS rule; report-write rules list the CSS
  hooks skills must use.
- CONTRIBUTING.md: matching update to the dual-output contract.
- ROADMAP.md: new "Just shipped" entry for v3.0.0.0; preserves historical
  v2.5.0.0 (Codex) and v2.4 (dual-output) entries.
- docs/index.html: the Output section on the landing page shows an HTML
  report path and an index.html dashboard pointer; sample manifest JSON
  uses the new report_path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: bump version to 3.0.0.0 (vX.Y.Z.W)

Breaking: report_path semantics moved from .idstack/reports/<skill>.md to
.idstack/exports/<course-slug>/<skill>.html. LMS packages also move into
the same course folder. Manifest schema version unchanged (still 1.4) -
field shape is identical, only the path the field points to changed.

CHANGELOG: full entry for v3.0.0.0 covering the HTML report format, the
per-course exports folder, the brand stylesheet, the slug helper, and the
breaking-change list.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(test): portable grep alternation in pipeline check (BSD compat)

The pipeline orchestrator assertion used \| alternation inside grep without
-E. That's a GNU grep extension to basic regex; under BSD grep (macOS
default before /usr/local) it matches the literal pipe character instead
of acting as alternation, silently making the check unable to distinguish
the two valid patterns.

Switch to grep -qE and unescape the |. Per gemini-code-assist review on
PR #28.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(landing): promote v3.0.0 in hero strip + What's new section

The landing page still pointed at v2.5.0. Update the hero meta strip
("v3.0.0 — Branded HTML reports") and rewrite the "What's new" release
card so the latest-shipped feature matches CHANGELOG/VERSION/plugin.json
(all already at 3.0.0.0).

Per /document-release Step 6 (cross-doc consistency).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: savvides

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "idstack",
-  "version": "2.5.0.0",
+  "version": "3.0.0.0",
   "description": "Evidence-based instructional design pipeline. 11 skills backed by peer-reviewed research across 11 domains. Analyze, design, build, review, and export courses with every recommendation citing its evidence tier.",
   "author": {
     "name": "Philippos Savvides",

AGENTS.md

@@ -44,17 +44,26 @@ Every skill that produces findings writes **both**:
 
 1. **JSON section** in `.idstack/project.json` — system state for downstream skills, the
    pipeline orchestrator, and `bin/idstack-status`.
-2. **Markdown report** at `.idstack/reports/<skill>.md` — the human view, structured per
-   `templates/report-format.md`. The skill writes the relative path back into its
-   section's `report_path` field.
-
-The Markdown is what the instructional designer reads. The JSON is for the system. The
-two stay in sync — every finding in the report corresponds to a finding in the manifest's
-structured arrays.
-
-`pipeline` additionally produces `.idstack/reports/pipeline.md` — the cross-cutting
-aggregate over per-skill reports. Regenerated on every pipeline run (including partial
-runs and explicit re-runs when all skills are already complete).
+2. **HTML report** at `.idstack/exports/<course-slug>/<skill>.html` — the human view,
+   branded and self-contained. Visual contract: `templates/report.html.tmpl` plus
+   `templates/assets/idstack.css`. Content contract: `templates/report-format.md`. The
+   skill writes the relative path back into its section's `report_path` field.
+
+The HTML is what the instructional designer reads (open in any browser; the folder is
+self-contained with CSS bundled). The JSON is for the system. The two stay in sync —
+every finding in the report corresponds to a finding in the manifest's structured arrays.
+
+`<course-slug>` is derived from the manifest's `project_name` via `bin/idstack-slugify`
+(NFKD-fold, lowercase, kebab-case, ASCII-safe; empty → `untitled-course`). All per-course
+artifacts — every per-skill HTML report, the pipeline `index.html` dashboard, and LMS
+packages (`course-export.imscc`, `scorm-export.zip`) — live under the same
+`.idstack/exports/<course-slug>/` folder, so the deliverable is self-describing when
+zipped, emailed, or handed off.
+
+`pipeline` produces `.idstack/exports/<course-slug>/index.html` — the cross-cutting
+course dashboard with readiness scores, links to every per-skill report, and a where-to-
+start pointer. Regenerated on every pipeline run (including partial runs and explicit
+re-runs when all skills are already complete).
 
 Manifest write rules:
 
@@ -68,9 +77,15 @@ Manifest write rules:
 
 Report write rules:
 
-- Follow `templates/report-format.md` — observation → evidence → why-it-matters →
+- Follow the **visual contract** in `templates/report.html.tmpl` and the **content
+  contract** in `templates/report-format.md` — observation → evidence → why-it-matters →
   suggestion, with severity (`critical|warning|info`) and evidence tier (`T1`–`T5`) on
-  every finding.
+  every finding. Use the CSS hooks the stylesheet styles: `<article class="finding
+  sev-{severity}">`, `<span class="sev-badge sev-{severity}">`, `<span class="tier-badge
+  tier-T{N}">`, `<cite class="citation">[Domain-N] [TN]</cite>`.
+- Every skill that writes a report copies `$_IDSTACK/templates/assets/idstack.css` into
+  `.idstack/exports/<course-slug>/assets/idstack.css` so the folder is self-contained
+  when zipped or moved.
 - Phrase recommendations as suggestions ("consider…"), not directives. idstack is a
   collaborator.
 - Cite every recommendation. Findings without a `[Domain-N] [Tier]` citation belong in

CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## v3.0.0.0 (2026-05-13)
+
+### Changed — branded HTML reports + per-course export folder
+
+The human-facing report format is now HTML. The container is now a per-course folder. Every artifact that belongs to a course — every per-skill report, the pipeline dashboard, the bundled stylesheet, and any LMS packages — lives under one self-describing folder: `.idstack/exports/<course-slug>/`. Zip the folder to hand the whole deliverable to a stakeholder.
+
+- **HTML replaces Markdown for the human view.** Every skill that produces findings now writes a branded, self-contained HTML report at `.idstack/exports/<course-slug>/<skill>.html`. Visual contract: `templates/report.html.tmpl` (the HTML skeleton) plus `templates/assets/idstack.css` (the brand stylesheet). Content contract is unchanged: observation → evidence → why-it-matters → suggestion, severity (`critical|warning|info`) and evidence tier (`T1`–`T5`) on every finding.
+- **Brand stylesheet matches `idstack.org`.** Scholarly serif body, ink-on-parchment palette, severity-colored finding cards (rust/amber/slate), tier badges weighted by strength (T1 heaviest, T5 lightest), citation marks in mono. Print-friendly. Auto light/dark via `prefers-color-scheme`. No JavaScript, no external fonts, no network — open and read.
+- **Course folder, by name.** `<course-slug>` is derived from `project_name` via `bin/idstack-slugify` (NFKD-fold, lowercase, kebab-case, ASCII-safe; empty input → `untitled-course`). Renaming a course's `project_name` moves future exports to a new folder; older folders are left in place.
+- **`/idstack:pipeline` produces a course dashboard.** `.idstack/exports/<course-slug>/index.html` carries readiness scores (Quality / Accessibility / Red-team confidence), a pipeline status table with links to every per-skill report, top cross-cutting issues, evidence themes, the LMS artifact list, and a where-to-start pointer. Same structure as `templates/index.html.tmpl`. Replaces the old `pipeline.md` aggregate.
+- **LMS packages move into the course folder.** `course-export.imscc` and `scorm-export.zip` now write to `.idstack/exports/<course-slug>/`, not the root `.idstack/`. The `export_metadata.destination` field reflects the new path.
+- **`course-export` now writes a report.** Previously the only pipeline skill without a human-facing report. Now produces `.idstack/exports/<course-slug>/course-export.html` alongside the LMS package.
+- **`bin/idstack-status` reads the new layout.** Surfaces the dashboard first, then per-skill HTML reports, then LMS packages — all from the course folder. Auto-resolves the slug from `project_name`; falls back to the only `.idstack/exports/*` subfolder when present.
+- **`bin/idstack-slugify` is a new CLI helper.** Standalone bash + python3 script implementing the slug rule. Documented in `templates/manifest-schema.md`; called by every skill that writes a report.
+
+### Added
+
+- `templates/report.html.tmpl` — per-skill HTML skeleton (visual contract).
+- `templates/index.html.tmpl` — course dashboard skeleton.
+- `templates/assets/idstack.css` — branded stylesheet matching `idstack.org` tone.
+- `bin/idstack-slugify` — `project_name` → course slug.
+- `bin/idstack-gen-skills` now sanity-checks that the three new template files exist; fails loud if any is missing.
+
+### Breaking
+
+- `report_path` semantics moved from `.idstack/reports/<skill>.md` to `.idstack/exports/<course-slug>/<skill>.html`. Existing `.idstack/reports/*.md` files from previous runs are left in place but treated as legacy — re-run the pipeline (or any skill) to migrate. Manifest schema version is unchanged (still 1.4) since field shape is identical; only the path the field points to has changed.
+- LMS package paths moved: `.idstack/course-export.imscc` → `.idstack/exports/<course-slug>/course-export.imscc`; `.idstack/scorm-export.zip` → `.idstack/exports/<course-slug>/scorm-export.zip`. Tooling and docs that hard-coded the old paths need updating.
+
+### Notes
+
+- `bin/idstack-status` reads from the new location; legacy `.idstack/reports/*.md` are not surfaced in the dashboard listing.
+- Plugin manifest version bumped to `3.0.0.0` (major: breaking `report_path` semantics).
+
 ## v2.5.0.0 (2026-05-09)
 
 ### Added — OpenAI Codex CLI support

CLAUDE.md

@@ -56,11 +56,13 @@ Any skill also works standalone (asks questions directly if no manifest exists).
 Every skill that produces findings writes **both**:
 
 1. **JSON section** in `.idstack/project.json` — system state for downstream skills, the pipeline orchestrator, and `bin/idstack-status`.
-2. **Markdown report** at `.idstack/reports/<skill>.md` — the human view, structured per `templates/report-format.md`. The skill writes the relative path back into its section's `report_path` field.
+2. **HTML report** at `.idstack/exports/<course-slug>/<skill>.html` — the human view, branded and self-contained. Visual contract: `templates/report.html.tmpl` + `templates/assets/idstack.css`. Content contract: `templates/report-format.md`. The skill writes the relative path back into its section's `report_path` field.
 
-The Markdown is what the instructional designer reads. The JSON is for the system. The two stay in sync: every finding in the report corresponds to a finding in the manifest's structured arrays.
+The HTML is what the instructional designer reads (open in any browser; the folder is self-contained, with CSS bundled). The JSON is for the system. The two stay in sync: every finding in the report corresponds to a finding in the manifest's structured arrays.
 
-`/idstack:pipeline` additionally produces `.idstack/reports/pipeline.md` — the cross-cutting aggregate over per-skill reports. It surfaces the top issues that recur across multiple skills, evidence themes, and where to start. Regenerated on every pipeline run (including partial runs and explicit re-runs when all skills are already complete).
+`<course-slug>` is derived from the manifest's `project_name` via `bin/idstack-slugify` (NFKD-fold, lowercase, kebab-case, ASCII-safe; empty input → `untitled-course`). All per-course artifacts — every per-skill HTML report, the pipeline `index.html` dashboard, and LMS packages (`course-export.imscc`, `scorm-export.zip`) — live under the same `.idstack/exports/<course-slug>/` folder, so the deliverable is self-describing when zipped, emailed, or handed off.
+
+`/idstack:pipeline` produces `.idstack/exports/<course-slug>/index.html` — the cross-cutting course dashboard. It surfaces readiness scores, top issues that recur across multiple skills, evidence themes, links to every per-skill report, and where to start. Regenerated on every pipeline run (including partial runs and explicit re-runs when all skills are already complete).
 
 Rules for writing the manifest:
 
@@ -71,7 +73,8 @@ Rules for writing the manifest:
 
 Rules for writing the report:
 
-- Follow the canonical structure in `templates/report-format.md` — observation → evidence → why-it-matters → suggestion, with severity (`critical|warning|info`) and evidence tier (`T1`–`T5`) on every finding.
+- Follow the **visual contract** in `templates/report.html.tmpl` and the **content contract** in `templates/report-format.md` — observation → evidence → why-it-matters → suggestion, with severity (`critical|warning|info`) and evidence tier (`T1`–`T5`) on every finding. Use the CSS hooks the stylesheet styles: `<article class="finding sev-{severity}">`, `<span class="sev-badge sev-{severity}">`, `<span class="tier-badge tier-T{N}">`, `<cite class="citation">[Domain-N] [TN]</cite>`.
+- Every skill that writes a report copies `$_IDSTACK/templates/assets/idstack.css` into `.idstack/exports/<course-slug>/assets/idstack.css` so the folder is self-contained when zipped or moved.
 - Phrase recommendations as suggestions ("consider…"), not directives. idstack is a collaborator.
 - Cite every recommendation. Findings without a `[Domain-N] [Tier]` citation belong in *Limitations* or *Notes*, not *Findings*.
 

CONTRIBUTING.md

@@ -65,7 +65,7 @@ The smoke test includes a freshness check that fails if any `SKILL.md` is stale.
 Every skill that produces findings writes **both**:
 
 1. **JSON section** in `.idstack/project.json` — system state for downstream skills, the pipeline orchestrator, and `bin/idstack-status`.
-2. **Markdown report** at `.idstack/reports/<skill>.md` — the human view. Follow `templates/report-format.md`: observation → evidence → why-it-matters → suggestion, with severity (`critical|warning|info`) and evidence tier (`T1`–`T5`) on every finding. The skill writes the relative path back into its section's `report_path` field.
+2. **HTML report** at `.idstack/exports/<course-slug>/<skill>.html` — the branded, self-contained human view. Follow the visual contract in `templates/report.html.tmpl` and the content contract in `templates/report-format.md`: observation → evidence → why-it-matters → suggestion, with severity (`critical|warning|info`) and evidence tier (`T1`–`T5`) on every finding. The skill writes the relative path back into its section's `report_path` field, and copies `templates/assets/idstack.css` into the course folder so the deliverable is self-contained when zipped.
 
 Phrase recommendations as suggestions ("consider…"), not directives. Cite every recommendation with `[DomainCode-N] [Tier]`; uncited claims belong in *Limitations* or *Notes*, not *Findings*.