create-pathfinder 4.2.0 → 4.3.0

package/CLAUDE.md

@@ -91,6 +91,8 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `to-tickets` — decompose one approved Feature into blocker-linked tickets
 - `ticket` — run one action of the ticket delivery loop: `load`, `start`, `review`, `complete`
 - `debug-issue` — diagnose an observed failure to its root cause, apply the smallest justified fix, and verify it
+- `render-artifact` — compile a typed specification into a deterministic, self-contained visual artifact
+- `map-system` — turn a plain request about a system into a semantic diagram artifact
 - `learn-feature` — create an interactive lesson for a completed feature
 - `learn-codebase` — create a modular learning portal for the repository
 - `teach-feature` — teach the verified current feature from its spec, diff, tests, and implementation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Install Pathfinder's ticket-first, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",

package/skills/learn-codebase/SKILL.md

@@ -5,29 +5,200 @@ description: Generate a modular, interactive learning portal that explains an en
 
 # Learn Codebase
 
-Use for onboarding, milestone review, handoff, or interview preparation—not after every feature.
+Use for onboarding, milestone review, handoff, or interview preparation — not
+after every feature.
 
-## Process
+You write what is true about the repository. `render-artifact` turns it into the
+page. Those are different jobs, and this skill only does the first one.
+
+## Read
+
+- the repository's own map: entry points, packages, workspaces, build and CI
+  configuration
+- architecture, major subsystems, and the boundaries between them
+- domain concepts and the vocabulary the code already uses
+- the flows that cross subsystems — a request, an install, a release, a build
+- tests, and what they are actually protecting
+- history and durable decisions, where they explain why the code is shaped this
+  way
 
-1. Establish learning goals and audience.
-2. Map the repository deliberately, excluding generated/vendor/build output.
-3. Identify architecture, modules, domain concepts, major flows, tests, deployment, and durable decisions.
-4. Generate modular lessons rather than one giant document.
-5. Include navigable diagrams, demonstrations, exercises, and quizzes.
-6. Cite source paths and distinguish current behavior from recommendations.
+Exclude generated, vendored, and build output deliberately, and say so if the
+exclusion is load-bearing.
 
-## Default Output
+Gather all of it **before** writing any specification. The specification is a
+record of what you found, so finding has to finish first — a portal assembled
+while still reading is a portal whose claims were chosen to fit the modules
+already written.
+
+## Output
+
+Two files, one repository:
 
 ```text
-learning/codebase/
-├── index.html
-├── modules/
-├── assets/
-└── README.md
+learning/codebase/lesson.json    the semantic specification — yours
+learning/codebase/lesson.html    the rendered artifact — the renderer's
 ```
 
-Use self-contained HTML/CSS/JS by default; use an existing docs/MDX system when approved. Do not install a framework solely for the portal without approval.
+The JSON is the reviewable source. A human can read it, disagree with a claim,
+and see exactly what was asserted and what backs it. It is also what makes the
+artifact reproducible: the same specification through the same renderer version
+produces the same bytes.
+
+One artifact, not a directory. There is no `index.html`, no `modules/` folder,
+and no `assets/` — how a multi-module lesson is split, linked, and navigated is
+a presentation decision, and presentation is the renderer's. You supply module
+order and content; the renderer builds the navigation.
+
+Do not author the HTML. Do not author CSS, presentation JavaScript, or MDX. Do
+not stand up a docs system, a site generator, or a framework for this. There is
+one visual-artifact path in Pathfinder and it runs through `render-artifact`.
+
+## Process
+
+1. **Gather the evidence** — the reading above.
+2. **Pick the commit.** `source.commit` is the milestone the portal is *about*.
+   Look it up and pin it; do not use whatever `HEAD` happens to be, which is
+   only the same thing by accident and stops being the same thing the moment
+   anything else merges. Evidence resolves against this commit and never against
+   the working tree, so a later refactor cannot silently change what the portal
+   claims.
+3. **Write the specification** to `lesson.json`. Read
+   `skills/render-artifact/engine/references/specification.md` for the fields
+   and `engine/examples/lesson.json` for the shape. Many modules: this skill
+   teaches a whole repository.
+4. **Validate.**
+
+   ```sh
+   node skills/render-artifact/engine/bin/render.mjs validate \
+     learning/codebase/lesson.json
+   ```
+
+5. **Deliver.**
+
+   ```sh
+   node skills/render-artifact/engine/bin/render.mjs deliver \
+     learning/codebase/lesson.json \
+     learning/codebase/lesson.html --json
+   ```
+
+6. **Report the receipt**, and report it honestly. See "What to say afterwards".
+
+## Modules
+
+One module per subsystem or concern, ordered so a reader can start at the top
+and keep going. Modules may include: orientation, architecture, domain and data
+flow, interfaces, services and integrations, testing, deployment and operations,
+security boundaries, extension exercises, and a cumulative quiz.
+
+Use `requires` when a module genuinely builds on another. That is the learning
+graph, and it is semantic: it says what a reader needs first, not where a box
+sits on a page. Leave it out when the modules are independent — a flat list is a
+legitimate shape, not a missing field.
+
+Keep each module a unit someone can finish. A module that has become a second
+portal is two modules.
+
+## Flows, not diagrams
+
+Express a sequence, a relationship, or an architecture walkthrough as a `flow`
+section. Its steps carry the order and the dependencies, which is the part that
+teaches, and the renderer decides how that looks.
+
+There is no diagram section, and this skill no longer promises navigable
+diagrams. Do not hand-author SVG, do not describe coordinates or layout, and do
+not reach for a drawing tool to fill the gap. A picture whose meaning is carried
+by a `flow` loses nothing that teaches; a picture this skill draws itself is
+presentation it does not own. Semantic diagram artifacts do exist — `map-system`
+produces them, as a separate artifact of its own — and that is still not this
+skill's output: a lesson gains no diagram section and references no diagram.
+
+## Evidence
+
+Every claim about the source carries a citation, in the one shape the renderer
+uses everywhere:
+
+```json
+{ "path": "packages/create-pathfinder/src/kit.mjs", "lines": [97, 105] }
+```
+
+Every `concept` section must cite at least one. That is not a style preference:
+a concept is an assertion about the code, and an uncited assertion is this skill
+putting words in the renderer's mouth. Validation rejects it.
+
+A repository-wide portal makes this easier to get wrong than a feature lesson
+does, because the claims are broader. "The installer never ships tests" is a
+claim about a specific list in a specific file — cite that list, not the package
+it lives in. Breadth is not permission to cite loosely.
+
+`lines` is optional and, when present, must lie inside that file at that commit.
+Cite the range a reader should actually look at.
+
+`source.generated_at` is yours to supply if you want a date on the page. The
+renderer never reads a clock, so if no date appears in the specification, none
+appears in the artifact.
+
+## Quiz
+
+Questions are multiple choice: a prompt, two to eight distinct options, and the
+index of the correct one. An explanation and evidence are worth adding.
+
+That one shape covers more than it looks:
+
+| To ask | Write |
+| --- | --- |
+| true/false | a question with two options |
+| predict the output or the state | a `code` section, then a question about it |
+| a debugging scenario | the symptom as the prompt, candidate causes as options |
+| recall or discrimination | an ordinary multiple-choice question |
+
+For something a reader should *do* rather than answer, use an `exercise`
+section, with `hints` when a nudge helps more than a solution. A cumulative
+quiz at the end works well; so does one per module.
+
+## What you cannot ask for
+
+The specification carries no presentation. There is no field for a colour, a
+class, a width, a layout, an icon, a theme, or a template, and the schema
+rejects the attempt rather than ignoring it. Interface language — navigation
+labels, theme controls, accessibility text, the evidence and citation UI — is
+the renderer's, in its words.
+
+Text is text. No field is Markdown and no field is HTML: every string you write
+is escaped on the way out, so `<b>bold</b>` in a title renders as those nine
+characters. Content that smuggles markup is this skill reaching for
+presentation by another route.
+
+There is also no field for whether the specification was validated or whether
+its evidence checked out. Those are claims about work the engine performs, and
+the engine is the only thing entitled to make them.
+
+## What to say afterwards
+
+The receipt names the renderer version and the SHA-256 and byte count of both
+the specification and the artifact. Report it. It supports one real claim: this
+specification, compiled by this renderer, produced these bytes, and its evidence
+resolved at the commit it names.
+
+It says nothing about whether the portal reads well, teaches well, or looks
+right. Nobody has looked at it. So report the validation result and say
+separately that perceptual review has not happened. If a human then opens it,
+that is their finding, in their words — and it is not evidence for the
+validation result any more than the validation result is evidence for it.
+
+## When the renderer cannot run
+
+Check with:
+
+```sh
+node skills/render-artifact/engine/bin/render.mjs doctor
+```
 
-## Modules May Include
+If the engine is unavailable, or delivery fails, you may still explain the
+codebase in conversation or in Markdown where that is useful. That answer is not
+a Pathfinder visual artifact. Do not call it one, do not hand-author HTML or MDX
+to stand in for one, and do not reach for a second way to produce a page. A
+non-zero exit is never reported as success, and a failed delivery leaves any
+previously delivered artifact exactly as it was.
 
-orientation, architecture, domain/data flow, UI or interfaces, services/integrations, testing, deployment/operations, security boundaries, extension exercises, and cumulative quiz.
+This skill reads widely by design. For one completed feature, use
+`learn-feature` instead.

package/skills/learn-feature/SKILL.md

@@ -7,6 +7,9 @@ description: Generate a rich, interactive, feature-scoped lesson and quiz from c
 
 Use after a feature is completed and accepted.
 
+You write what is true about the feature. `render-artifact` turns it into the
+page. Those are different jobs, and this skill only does the first one.
+
 ## Read
 
 - completed feature spec and history entry
@@ -14,17 +17,60 @@ Use after a feature is completed and accepted.
 - only the implemented files and direct dependencies needed to explain the feature
 - tests and durable decisions
 
-## Output Format
+Gather all of it **before** writing any specification. The specification is a
+record of what you found, so finding has to finish first — a lesson assembled
+while still reading is a lesson whose claims were chosen to fit the paragraphs
+already written.
 
-Use the project's learning preference. Default to self-contained HTML/CSS/JS. Use MDX only when the repository already supports it or the human selects it.
+## Output
 
-Place output under:
+Two files, one per feature:
 
 ```text
-learning/features/[feature-slug]/
+learning/features/[feature-slug]/lesson.json    the semantic specification — yours
+learning/features/[feature-slug]/lesson.html    the rendered artifact — the renderer's
 ```
 
-## Lesson Content
+The JSON is the reviewable source. A human can read it, disagree with a claim,
+and see exactly what was asserted and what backs it. It is also what makes the
+artifact reproducible: the same specification through the same renderer version
+produces the same bytes, so the page can be delivered again after a renderer
+release without re-deriving anything.
+
+Do not author the HTML. Do not author CSS, presentation JavaScript, or MDX.
+There is one visual-artifact path in Pathfinder and it runs through
+`render-artifact`.
+
+## Process
+
+1. **Gather the evidence** — the reading above.
+2. **Pick the commit.** `source.commit` is the commit the lesson is *about*:
+   the one that landed the feature. Look it up; do not use whatever `HEAD`
+   happens to be, which is only the same thing by accident and stops being the
+   same thing the moment anything else merges. Evidence resolves against this
+   commit and never against the working tree.
+3. **Write the specification** to `lesson.json`. Read
+   `skills/render-artifact/engine/references/specification.md` for the fields
+   and `engine/examples/lesson.json` for the shape. One module: this skill
+   teaches one feature.
+4. **Validate.**
+
+   ```sh
+   node skills/render-artifact/engine/bin/render.mjs validate \
+     learning/features/[feature-slug]/lesson.json
+   ```
+
+5. **Deliver.**
+
+   ```sh
+   node skills/render-artifact/engine/bin/render.mjs deliver \
+     learning/features/[feature-slug]/lesson.json \
+     learning/features/[feature-slug]/lesson.html --json
+   ```
+
+6. **Report the receipt**, and report it honestly. See "What to say afterwards".
+
+## Lesson content
 
 - what changed and why
 - architecture and data/control flow
@@ -32,17 +78,92 @@ learning/features/[feature-slug]/
 - key implementation decisions and tradeoffs
 - tests and verification
 - common mistakes and safe extension points
-- visual diagrams or interactive demonstrations when useful
 
-## Quiz Variety
+Express a sequence or a set of relationships as a `flow` section — its steps
+carry the order and the dependencies, which is the part that teaches. The
+renderer decides how a flow looks.
+
+## Evidence
+
+Every claim about the source carries a citation, in the one shape the renderer
+uses everywhere:
+
+```json
+{ "path": "packages/create-pathfinder/src/kit.mjs", "lines": [97, 105] }
+```
+
+Every `concept` section must cite at least one. That is not a style preference:
+a concept is an assertion about the code, and an uncited assertion is this skill
+putting words in the renderer's mouth. Validation rejects it.
+
+`lines` is optional and, when present, must lie inside that file at that commit.
+Cite the range a reader should actually look at.
+
+`source.generated_at` is yours to supply if you want a date on the page. The
+renderer never reads a clock, so if no date appears in the specification, none
+appears in the artifact.
 
-Include a useful mix when appropriate:
+## Quiz
+
+Questions are multiple choice: a prompt, two to eight distinct options, and the
+index of the correct one. An explanation and evidence are worth adding.
+
+That one shape covers more than it looks:
+
+| To ask | Write |
+| --- | --- |
+| true/false | a question with two options |
+| predict the output or the state | a `code` section, then a question about it |
+| a debugging scenario | the symptom as the prompt, candidate causes as options |
+| recall or discrimination | an ordinary multiple-choice question |
+
+For something a reader should *do* rather than answer, use an `exercise`
+section, with `hints` when a nudge helps more than a solution.
+
+## What you cannot ask for
+
+The specification carries no presentation. There is no field for a colour, a
+class, a width, a layout, an icon, a theme, or a template, and the schema
+rejects the attempt rather than ignoring it. Interface language — navigation
+labels, theme controls, accessibility text, the evidence and citation UI — is
+the renderer's, in its words.
+
+Text is text. No field is Markdown and no field is HTML: every string you write
+is escaped on the way out, so `<b>bold</b>` in a title renders as those nine
+characters. Content that smuggles markup is this skill reaching for
+presentation by another route.
+
+There is also no field for whether the specification was validated or whether
+its evidence checked out. Those are claims about work the engine performs, and
+the engine is the only thing entitled to make them.
+
+## What to say afterwards
+
+The receipt names the renderer version and the SHA-256 and byte count of both
+the specification and the artifact. Report it. It supports one real claim: this
+specification, compiled by this renderer, produced these bytes, and its evidence
+resolved at the commit it names.
+
+It says nothing about whether the lesson reads well, teaches well, or looks
+right. Nobody has looked at it. So report the validation result and say
+separately that perceptual review has not happened. If a human then opens it,
+that is their finding, in their words — and it is not evidence for the
+validation result any more than the validation result is evidence for it.
+
+## When the renderer cannot run
+
+Check with:
+
+```sh
+node skills/render-artifact/engine/bin/render.mjs doctor
+```
 
-- multiple choice
-- true/false with explanation
-- ordering or matching
-- predict-the-output/state
-- debugging scenario
-- short reflection or implementation challenge
+If the engine is unavailable, or delivery fails, you may still explain the
+feature in conversation or in Markdown where that is useful. That answer is not
+a Pathfinder visual artifact. Do not call it one, do not hand-author HTML or MDX
+to stand in for one, and do not reach for a second way to produce a page. A
+non-zero exit is never reported as success, and a failed delivery leaves any
+previously delivered artifact exactly as it was.
 
-Provide immediate feedback and explanations. Keep the lesson scoped and avoid reading the whole repository.
+Keep the lesson scoped, and avoid reading the whole repository — use
+`learn-codebase` for that.