Build the evaluated personal learning skill pack

AGENTS.md

@@ -1,15 +1,35 @@
 # Repository Instructions
 
-This repository owns the canonical PathMX skills.
-
-- `pathmx` owns PathMX authoring and tooling.
-- `path` owns the personal learning workflow and uses `pathmx` for syntax.
-- `work-log/` holds design briefs for reference; it is not synced skill content.
-- Keep all checked-in content self-contained. Do not depend on another checkout.
-- Keep prose short and plain.
-- Add only syntax supported by the pinned PathMX version and a local fixture.
-- Add question syntax only when it passes the pinned fixture.
-- Do not add general actions or spaceholders until they are ready for this skill.
-- Test sync changes with temporary repositories, including check mode, conflicts,
-  containment, and rollback.
-- Run `bun run check` before handoff.
+This repository owns the canonical PathMX skills and the hosted bootstrap
+instructions for a personal learning space.
+
+- `bootstrap.md` gets a nontechnical learner from an agent prompt to a working
+  learning repository.
+- `pathmx` owns PathMX authoring, tooling, Player use, annotations, and review.
+- `path` owns the agent-led personal learning workflow and uses `pathmx` for
+  authoring.
+- `work-log/` keeps design history. It is not installed as skill content.
+- The public `pathmx-learning-starter` is a consumer, not a source of truth.
+
+Keep checked-in content self-contained. Keep prose short and plain. Put core
+procedure in `SKILL.md`; put detailed syntax and examples in references.
+
+Add only syntax supported by the pinned PathMX version and a local fixture.
+Treat Player interactions, annotations, questions, components, routes, and CLI
+claims as version-sensitive. Verify them against fixtures or the installed CLI.
+The exact dependency in `package.json` is the fixture baseline. Keep bootstrap
+instructions pointed at latest, but update this baseline only after the complete
+suite passes.
+
+The learning workflow is buffered, not Block-at-a-time:
+
+- map the whole path as visible milestones;
+- fully author the current 2–4-session module;
+- let a learner finish a session without waiting for an agent;
+- adapt at useful session or module boundaries;
+- keep annotations and durable evidence in Sources.
+
+Keep learner fixtures fictional. Do not add real personal or sensitive data.
+
+Test sync changes with temporary repositories, including check mode, conflicts,
+containment, and rollback. Run `bun run check` before handoff.

README.md

@@ -1,48 +1,70 @@
 # PathMX Skills
 
-This is the canonical, self-contained collection of PathMX agent skills.
+Canonical agent instructions for authoring PathMX and running a personal
+learning space.
+
+Give an agent [the bootstrap instructions](./bootstrap.md) to create a new
+learning repository. After setup, repository instructions and these two skills
+carry the workflow:
 
 | Skill | Use |
 | --- | --- |
-| `/pathmx` | PathMX syntax, tooling, authoring, review, Play, and verification. |
-| `/path` | One opinionated, adaptive personal learning path. Uses `/pathmx` for authoring. |
+| `/pathmx` | Author, play, review, and verify PathMX. Invoked automatically for PathMX work. |
+| `/path` | Start or resume a buffered adaptive learning path for one learner. |
+
+Skills install under `.agents/skills/`. Codex discovers that directory
+directly. Claude Code uses the matching `.claude/skills` discovery link and a
+small `CLAUDE.md` that imports `AGENTS.md`.
 
 ## Develop
 
-Requires Bun. Dependencies include a pinned PathMX CLI.
+Requires Bun. The repository pins a published PathMX version so every syntax
+claim and fixture is reproducible. `package.json` names that exact compatibility
+baseline. It is the safe fallback for latest-after-verification updates, not
+the version of this skills repository.
 
 ```sh
 bun install --frozen-lockfile
 bun run check
 ```
 
-Examples and syntax claims must pass the local checks.
-
-## Evals
-
-Use [the agent rubric](./evals/pathmx-skills.rubric.md) to score task output and
-verification evidence.
-
-## Work log
-
-Design briefs that informed `/path` live under [work-log/](./work-log/). They
-are reference notes, not synced skill packages.
-
 ## Sync
 
-Check a target without writing:
+Check a target repository without writing:
 
 ```sh
 bun run sync-skills -- --check <target-repository>
 ```
 
-Apply the canonical copies:
+Apply the canonical packages:
 
 ```sh
 bun run sync-skills -- --write <target-repository>
 ```
 
-Write mode manages only the skill packages declared in
-`skills/manifest.json` and their Claude discovery links. It leaves unrelated
-target content and skills alone. Edit canonical skill content here; a later
-sync replaces edits made inside managed target copies.
+Write mode owns only the packages declared in `skills/manifest.json` and their
+Claude discovery links. It leaves unrelated target content and skills alone.
+
+## Evals
+
+The [eval harness](./evals/README.md) drives the real Codex CLI through a
+multi-turn bootstrap and learning flow, grades the resulting repository, and
+can add an independent structured model judge.
+
+```sh
+bun run eval:check
+bun run eval -- list
+bun run eval -- run sql-beginner
+bun run eval -- run sql-beginner --profile instruction-floor
+```
+
+## Design history and contributors
+
+Design briefs live under [work-log](./work-log/). They are reference notes, not
+installed skill content.
+
+The buffered adaptive learning loop grew from early hands-on testing by Tram Le
+and Mark Johnson, which exposed the limits of Block-by-Block curriculum
+generation. Tram also contributed the original math, media, code, tooling,
+styling, and adaptive-path reference work that this repository continues to
+build on.

ROADMAP.md

@@ -1,7 +1,39 @@
 # Roadmap
 
-- Refine durable question authoring through starter tests and evals.
-- Add general actions after their authoring contract is ready.
-- Add spaceholders after their authoring and generation flow is stable.
-- Test scheduled learning check-ins after the `/path` loop has real use.
-- Add more learning-path examples only when they cover a distinct scenario.
+## Release gates
+
+- After the skill pack and learning starter pass candidate and published-flow
+  evals, audit their commit history and remove unwanted Claude-generated commit
+  attribution or trailers before the public release. Confirm the exact history
+  rewrite and affected remotes before changing published history.
+- Sync the canonical skills and `AGENTS.md` instructions into
+  `pathmx-build-week-2026` and `pathmx-learning-starter`. Replace stale managed
+  copies in both repositories and verify them with the sync checker and each
+  repository's own checks.
+- Rewrite or replace
+  `pathmx-build-week-2026/paths/guides/self-learning-manual-test.guide.md` so a
+  teammate can manually reproduce the automated scenario from `bootstrap.md`
+  in a fresh Codex Desktop task. Keep its learner messages and phase checks
+  aligned with the scored eval, then add Desktop-only observations for
+  permission requests, integrated Browser routing, Player appearance and Play
+  mode, annotations, waiting time, and the learner's sense of progress. Remove
+  the old direct-init flow and stale minimum-version language.
+- Verify bootstrap and installed skills against the latest stable PathMX
+  release before publishing. The current candidate is `0.1.21`; keep the
+  bootstrap on `latest`, advance fixture baselines only after the full suite
+  passes, and do not leave prose or examples pinned to an older release.
+- Review `evals/profiles.json` against the current Codex Desktop model guide
+  before release so the primary experience lane still matches the documented
+  default Power setting.
+
+## Later work
+
+- Forward-test bootstrap and both implicit skill triggers in clean Codex and
+  Claude Code sessions.
+- Expand stable annotation review and reply workflows after field use.
+- Add more learning-path examples only when they cover a distinct domain or
+  learner need.
+- Explore an optional, more playful home and milestone map without making it a
+  dependency of the minimal starter.
+- Add general actions or spaceholders only after their public authoring
+  contracts are stable and fixture-backed.

bootstrap.md

@@ -0,0 +1,138 @@
+# Start a PathMX Learning Space
+
+Follow these instructions as an agent. Carry out the setup instead of only
+explaining it. Ask for permission when the environment requires it.
+
+The result is one private, local Git repository where one learner can keep
+multiple learning paths, use the PathMX Player, and return to an agent over
+time.
+
+## 1. Choose the location
+
+Ask where the learner wants the repository and what to call it. Suggest a short
+name such as `my-learning-space`. Do not replace or merge into an existing
+directory.
+
+## 2. Ensure Bun and PathMX are ready
+
+Check `bun --version`. If Bun is missing, ask to install it with the official
+installer for the learner's operating system:
+
+```sh
+# macOS or Linux
+curl -fsSL https://bun.com/install | bash
+```
+
+```powershell
+# Windows PowerShell
+powershell -c "irm bun.sh/install.ps1|iex"
+```
+
+Open a fresh shell or update the current shell path when the installer asks.
+Verify `bun --version` before continuing.
+
+If `pathmx` already exists, update its native command:
+
+```sh
+pathmx self-update
+```
+
+Otherwise install the current native command through the latest published
+package:
+
+```sh
+bunx @fellowhumans/pathmx@latest self-update
+```
+
+Verify `pathmx --version` and retain that version for the project comparison
+below.
+
+## 3. Create the learning repository
+
+Create the chosen directory from the official starter. This command also
+installs the current official `/path` and `/pathmx` skills:
+
+```sh
+pathmx init <learning-space> --template pathmx-learning-starter
+cd <learning-space>
+bun install --frozen-lockfile
+```
+
+Read `AGENTS.md` and, when present, the instructions for the current agent
+harness. Confirm that `.agents/skills/path/SKILL.md` and
+`.agents/skills/pathmx/SKILL.md` exist.
+
+Shell tool calls may not preserve a prior `cd`. Run every following project
+command from the new repository explicitly, either by setting its working
+directory or by using `cd <learning-space> && ...`.
+
+Initialize a fresh local history and make the scaffold commit. If Git identity
+is not configured, explain that clearly and keep the staged scaffold as the
+rollback point without inventing an identity.
+
+```sh
+git init
+git add .
+git commit -m "Create personal PathMX learning space"
+```
+
+Do not create or push a remote unless the learner asks. Treat the repository as
+private personal data.
+
+Compare the exact project dependency with the updated native `pathmx --version`.
+When they already match, do not reinstall the same package; run `bun run check`
+once and continue. When they differ, attempt to bring the project dependency
+to the latest release:
+
+```sh
+bun add --exact @fellowhumans/pathmx@latest
+bun run check:candidate
+```
+
+Keep and commit that update only if the full build succeeds and the Player
+tutorial, questions, annotations, and bundled component behavior pass a smoke
+test. Then set `pathmxCompatibility.baseline` in `package.json` to the exact
+installed dependency and run `bun run check` before committing. If verification
+fails, run `git restore package.json bun.lock` to recover those files from the
+scaffold commit or staged baseline, run `bun install --frozen-lockfile`, and
+continue on that verified baseline. Report the incompatibility; do not rewrite
+learner content to make an update pass.
+
+## 4. Start the Player
+
+Run the repository's Player command in a long-lived terminal. Reuse a healthy
+Player that already belongs to this repository; do not stop an unknown server.
+
+```sh
+bun run play
+```
+
+Use `bunx pathmx route` and the server's printed base URL to resolve the exact
+Source route with the project dependency. Prefer the most useful Source, Block,
+or Beat position instead of linking only to the home page.
+
+When an integrated browser is available, open and review the Player there. In
+Codex, prefer `@Browser`; in Claude Code, use its Chrome integration when it is
+already configured. Otherwise open the system browser. If no browser can be
+opened, give the learner a clickable URL.
+
+Open the bundled Player tutorial for a first-time learner. They may skip it.
+
+## 5. Begin learning
+
+Use `/path` implicitly. Ask a few questions at a time about:
+
+- what the learner wants to be able to do and why;
+- what they already know, with one small piece of evidence;
+- their available time and preferred pace;
+- the visual mood, color direction, light or dark preference, and any
+  readability or motion needs.
+
+Confirm the learner's profile, milestone map, and first module before teaching.
+When showing the proposed map, first write and link a proposed Path Source with
+3–7 visibly statused milestones and evidence targets. Give its exact Player
+URL, but do not create session, review, or checkpoint Sources yet. Wait for
+explicit confirmation, then fully prepare the current module so the learner
+can complete each session without waiting for another agent turn. Before
+handoff, verify the embedded help and give an exact Player URL with brief
+Play-mode and return instructions.