From 7e6063a8f789d7782f0c02f912b52599673250df Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 10:53:32 -0700 Subject: [PATCH 1/2] quest(m0): plan the chapter/epic rename, the design/ move, and dropping x86_64-darwin Co-Authored-By: Claude Opus 5.5 --- quest/m0/README.md | 2 ++ quest/m0/intel-mac.md | 15 +++++++++++++ quest/m0/release-proof.md | 4 +++- quest/m0/rename.md | 43 ++++++++++++++++++++++++++++++++++++ quest/m0/theme/README.md | 2 ++ quest/m0/theme/design-dir.md | 27 ++++++++++++++++++++++ 6 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 quest/m0/intel-mac.md create mode 100644 quest/m0/rename.md create mode 100644 quest/m0/theme/design-dir.md diff --git a/quest/m0/README.md b/quest/m0/README.md index 7969b5e..d69d8c0 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -30,7 +30,9 @@ ownership-manifest design: ## Required +- [Rename milestones and questlines](/quest/m0/rename.md) - milestones become chapters (`c0`, `c1`), questlines become epics, everywhere, before the demo - [Quest on Cloudflare](/quest/m0/cloudflare/README.md) - contributors lock quests and donate tokens to run them; maintainers review and merge in a web UI synced with GitHub - [Quest log theme](/quest/m0/theme/README.md) - an MMO-style identity, copy, board, landing page, and CLI output for the demo and launch +- [Drop x86_64-darwin](/quest/m0/intel-mac.md) - the flake lists only systems nixpkgs builds; Intel Macs use the release binary - [Release proof](/quest/m0/release-proof.md) - a fresh repository completes the whole lifecycle in CI, then v0.1.0 is tagged - [Launch material](/quest/m0/launch.md) - README, quickstart, demo, comparison, and launch-post drafts diff --git a/quest/m0/intel-mac.md b/quest/m0/intel-mac.md new file mode 100644 index 0000000..ba2026b --- /dev/null +++ b/quest/m0/intel-mac.md @@ -0,0 +1,15 @@ +# [XS] Drop x86_64-darwin from the flake + +## Goal + +`flake.nix` lists only systems that the pinned nixpkgs can build, so +`nix flake check` and flake pins don't advertise Intel Macs. Intel Mac users +install with the shell installer or mise, which use the Bun-compiled +`x86_64-apple-darwin` release binary, and `SETUP.md` says so. + +## Plan + +Decided while planning on 2026-10-07, after the Compiled releases PR (#70) +found that nixpkgs-unstable has dropped `x86_64-darwin`, so the Nix dev shell +won't start on Intel macOS. Release binaries for Intel Macs are unaffected, +since #70 compiles every target on Linux. diff --git a/quest/m0/release-proof.md b/quest/m0/release-proof.md index 50b525a..3230c2f 100644 --- a/quest/m0/release-proof.md +++ b/quest/m0/release-proof.md @@ -23,4 +23,6 @@ installs through mise and the shell installer on macOS and Linux. - Include a repository that already has an `AGENTS.md` or `CLAUDE.md` and a same-named skill, to prove init refuses rather than overwrites. - There's no rc tag. The Release workflow's install checks on v0.1.0 gate - this quest, and a broken install ships as a fixed v0.1.x. + this quest, and a broken install ships as a fixed v0.1.x. Reaffirmed on + 2026-10-07, after the #70 review noted that a release publishes before its + install check runs. diff --git a/quest/m0/rename.md b/quest/m0/rename.md new file mode 100644 index 0000000..2059965 --- /dev/null +++ b/quest/m0/rename.md @@ -0,0 +1,43 @@ +# [M] Rename milestones to chapters and questlines to epics + +## Goal + +The format uses one set of terms everywhere (`quest guide`, the skills, CLI +output, README, docs, the site, and the quest tree) and they fit the +quest-log voice, so no surface needs display-name aliases. A milestone becomes +a **chapter**, a questline becomes an **epic**, and the root directories `m0`, +`m1`, ... become `c0`, `c1`, .... Every other term stays: quest, `Goal`, +`Plan`, `Required`, `Closes`, `Related`, sizes, and claims. It lands before +the 2026-10-14 demo. + +## Plan + +Decided while planning on 2026-10-07: + +- This reverses the theme epic's 2026-10-05 decision that the format's terms + stay as they are. The user wanted consistent terms over display aliases. + #69 had just made the README use the format's terms throughout. +- "Chapter" was already the site's display name for a milestone, and it + reads as an ordered horizon (chapter 0, chapter 1). "Epic" replaces + "questline" for a directory of quests with a `README.md`. In agile, an epic + means a group of related work, which matches. +- Rename the directories too (`quest/m0` to `quest/c0`, and so on), so `m` + doesn't linger as an alias. Quest paths and branch names change with them. + The core treats the root's entries by position, not by name, so no logic + changes. Check for any `m0`-shaped examples or fixtures in tests and + `examples/`. +- The user authorized editing `assets/AGENTS.md` (the guide) and + `assets/skills/` for this rename. Change terms only, not the workflow. +- Update in the same PR: README, `docs/`, `docs/theme.md`'s glossary (drop + the alias table, since the terms are now the same), the site's copy and + tests (`cloudflare/src/`), CLI messages and help, every quest file, and + every root-absolute quest link. +- Open PRs that touch `quest/m0/...` (Cloudflare #40-#43) rebase onto the new + paths when they next iterate. List them in the PR. +- Land it before the theme epic's final consistency pass and the demo + recording, so both show the final vocabulary. + +## Related + +- [Quest log theme](/quest/m0/theme/README.md) - its glossary and final consistency pass follow this rename +- [Move the theme spec to design/](/quest/m0/theme/design-dir.md) - also edits `docs/theme.md`; whichever lands second merges diff --git a/quest/m0/theme/README.md b/quest/m0/theme/README.md index b0dd31f..8e9abd5 100644 --- a/quest/m0/theme/README.md +++ b/quest/m0/theme/README.md @@ -53,10 +53,12 @@ Decided while planning on 2026-10-05: ## Required +- [Move the theme spec to design/](/quest/m0/theme/design-dir.md) - `docs/` holds only user docs; the spec and assets move to `design/` - [Quest map](/quest/m0/theme/map.md) - the home page draws Quest's own tree as a left-to-right world map - [Social preview](/quest/m0/theme/social-preview.md) - a maintainer uploads `docs/theme/og.png` as the GitHub social preview - [Themed CLI output](/quest/m0/theme/cli.md) - `!`/`?` markers and difficulty colours on a terminal; piped output unchanged - [Landing page](/quest/m0/theme/landing.md) - the home page's map and calls to action link into the live board +- [Rename milestones and questlines](/quest/m0/rename.md) - the final consistency pass checks the final vocabulary ## Related diff --git a/quest/m0/theme/design-dir.md b/quest/m0/theme/design-dir.md new file mode 100644 index 0000000..908c950 --- /dev/null +++ b/quest/m0/theme/design-dir.md @@ -0,0 +1,27 @@ +# [S] Move the theme spec and assets to design/ + +## Goal + +`https://kixel.quest/docs` shows only user-facing documentation. The theme's +design spec, `docs/theme.md`, moves to `design/theme.md`, and its assets in +`docs/theme/` (mark, `theme.css`, `og.svg`, `og.png`) move to `design/theme/`. +The site still serves the assets at `/theme/`, and nothing links to the old +paths. + +## Plan + +Decided while planning on 2026-10-07: + +- The site renders every `docs/*.md` at `/docs`, so the internal spec is + published there. Moving the spec and its assets together keeps `docs/` + for user docs only, rather than adding a skip list to the site build. +- Update `cloudflare/scripts/build.ts`, which copies `docs/theme/` to the + site's `/theme/`, plus the README's logo path, `cloudflare/src/` comments + that cite `docs/theme.md`, and every quest that references either path + (grep for `docs/theme`). +- Ranked after the copy rewrite (#69, merged), which also touched the + README's logo path. + +## Related + +- [Rename milestones and questlines](/quest/m0/rename.md) - also edits `docs/theme.md`; whichever lands second merges From 71316641705899774e4a7a218127b91ccac334b4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 10:59:00 -0700 Subject: [PATCH 2/2] quest(m0): address review wording on the rename, design/, and Intel Mac quests Narrow the alias claims, list the full rename scope (core identifiers, fixtures, lifecycle script, examples, branch claims), widen the design/ grep to the whole repository, and note the rename in the theme questline. Co-Authored-By: Claude Opus 5.5 --- quest/m0/intel-mac.md | 7 +++++-- quest/m0/rename.md | 30 +++++++++++++++++++----------- quest/m0/theme/README.md | 5 ++++- quest/m0/theme/design-dir.md | 9 +++++---- 4 files changed, 33 insertions(+), 18 deletions(-) diff --git a/quest/m0/intel-mac.md b/quest/m0/intel-mac.md index ba2026b..4fbff63 100644 --- a/quest/m0/intel-mac.md +++ b/quest/m0/intel-mac.md @@ -2,8 +2,8 @@ ## Goal -`flake.nix` lists only systems that the pinned nixpkgs can build, so -`nix flake check` and flake pins don't advertise Intel Macs. Intel Mac users +`flake.nix` lists only systems that the pinned nixpkgs can build, so the +flake's outputs (packages, dev shell, checks) don't advertise Intel Macs. Intel Mac users install with the shell installer or mise, which use the Bun-compiled `x86_64-apple-darwin` release binary, and `SETUP.md` says so. @@ -13,3 +13,6 @@ Decided while planning on 2026-10-07, after the Compiled releases PR (#70) found that nixpkgs-unstable has dropped `x86_64-darwin`, so the Nix dev shell won't start on Intel macOS. Release binaries for Intel Macs are unaffected, since #70 compiles every target on Linux. + +`SETUP.md`'s nix flake bullet notes that Intel Macs pin with mise or the +shell installer instead. diff --git a/quest/m0/rename.md b/quest/m0/rename.md index 2059965..d7b6ca5 100644 --- a/quest/m0/rename.md +++ b/quest/m0/rename.md @@ -4,9 +4,10 @@ The format uses one set of terms everywhere (`quest guide`, the skills, CLI output, README, docs, the site, and the quest tree) and they fit the -quest-log voice, so no surface needs display-name aliases. A milestone becomes +quest-log voice, so no surface needs a display name for a milestone or +questline. A milestone becomes a **chapter**, a questline becomes an **epic**, and the root directories `m0`, -`m1`, ... become `c0`, `c1`, .... Every other term stays: quest, `Goal`, +`m1`, ... become `c0`, `c1`, and so on. Every other term stays: quest, `Goal`, `Plan`, `Required`, `Closes`, `Related`, sizes, and claims. It lands before the 2026-10-14 demo. @@ -14,7 +15,7 @@ the 2026-10-14 demo. Decided while planning on 2026-10-07: -- This reverses the theme epic's 2026-10-05 decision that the format's terms +- This reverses the theme questline's 2026-10-05 decision that the format's terms stay as they are. The user wanted consistent terms over display aliases. #69 had just made the README use the format's terms throughout. - "Chapter" was already the site's display name for a milestone, and it @@ -23,18 +24,25 @@ Decided while planning on 2026-10-07: means a group of related work, which matches. - Rename the directories too (`quest/m0` to `quest/c0`, and so on), so `m` doesn't linger as an alias. Quest paths and branch names change with them. - The core treats the root's entries by position, not by name, so no logic - changes. Check for any `m0`-shaped examples or fixtures in tests and - `examples/`. + The core treats the root's entries by depth (`permanent()` in + `src/core/doc.ts`), not by name, so no logic changes. - The user authorized editing `assets/AGENTS.md` (the guide) and `assets/skills/` for this rename. Change terms only, not the workflow. - Update in the same PR: README, `docs/`, `docs/theme.md`'s glossary (drop - the alias table, since the terms are now the same), the site's copy and - tests (`cloudflare/src/`), CLI messages and help, every quest file, and - every root-absolute quest link. + the `questline` and `milestone` rows, since those terms are now the same; + the site's "quest chain" copy becomes "epic"), the site's copy and tests + (`cloudflare/src/`), core identifiers and comments (`isQuestline`, exported + from `src/core/index.ts`; `src/core/{doc,ready,rules}.ts`), the "line" + shorthand for a questline in the guide and code, test names and fixtures + (`test/fixture.ts`, `test/tree.test.ts`, `test/init.test.ts`), + `scripts/lifecycle-check.sh` ("First milestone", `quest/m0`), + `examples/export/quest/m0` (the README's `--root examples/export` output + depends on it), every quest file, and every root-absolute quest link. - Open PRs that touch `quest/m0/...` (Cloudflare #40-#43) rebase onto the new - paths when they next iterate. List them in the PR. -- Land it before the theme epic's final consistency pass and the demo + paths when they next iterate. Their branches claim the old paths, so + rename them to `quest/c0/...` in the same change (GitHub's branch rename + retargets open PRs). List them in the PR. +- Land it before the theme questline's final consistency pass and the demo recording, so both show the final vocabulary. ## Related diff --git a/quest/m0/theme/README.md b/quest/m0/theme/README.md index 8e9abd5..71d9d28 100644 --- a/quest/m0/theme/README.md +++ b/quest/m0/theme/README.md @@ -6,7 +6,8 @@ By the 2026-10-14 Cloudflare demo, Quest presents itself as an original MMO-style quest log for your repository and your agents: themed README and docs copy, a shared identity (logo, palette, social image), a themed site at `https://kixel.quest` (home, docs, and quest board), and themed CLI output on -a terminal. The quest format, `quest guide`, and the skills do not change. +a terminal. The quest format, `quest guide`, and the skills do not change, +except for the [rename](/quest/m0/rename.md) of milestones and questlines. This README owns the work no child does: a final pass over every surface for consistency with `docs/theme.md` before the demo is recorded. @@ -22,6 +23,8 @@ Decided while planning on 2026-10-05: `Required`, `[XS]`-`[XL]`) stay as they are because agents and `quest check` rely on them. The theme lives in presentation only. A renamed format would break the guide, skills, and existing trees before v0.1.0. + Amended 2026-10-07: [Rename milestones and questlines](/quest/m0/rename.md) + renames milestone to chapter and questline to epic in the format itself. - Hook, then substance. The headline and visuals sell "a quest log for your repo and your agents". The next lines deliver the existing pitch: readable plans, explicit dependencies, and reviewable Git changes. diff --git a/quest/m0/theme/design-dir.md b/quest/m0/theme/design-dir.md index 908c950..5932df0 100644 --- a/quest/m0/theme/design-dir.md +++ b/quest/m0/theme/design-dir.md @@ -4,7 +4,7 @@ `https://kixel.quest/docs` shows only user-facing documentation. The theme's design spec, `docs/theme.md`, moves to `design/theme.md`, and its assets in -`docs/theme/` (mark, `theme.css`, `og.svg`, `og.png`) move to `design/theme/`. +`docs/theme/` (`logo.svg`, `theme.css`, `og.svg`, `og.png`) move to `design/theme/`. The site still serves the assets at `/theme/`, and nothing links to the old paths. @@ -16,9 +16,10 @@ Decided while planning on 2026-10-07: published there. Moving the spec and its assets together keeps `docs/` for user docs only, rather than adding a skip list to the site build. - Update `cloudflare/scripts/build.ts`, which copies `docs/theme/` to the - site's `/theme/`, plus the README's logo path, `cloudflare/src/` comments - that cite `docs/theme.md`, and every quest that references either path - (grep for `docs/theme`). + site's `/theme/`, plus the README's logo path, `cloudflare/README.md`'s + links, `cloudflare/src/` comments that cite `docs/theme.md`, the spec's own + paths and export commands, the asset files' comments, and every other file + that references either path (grep the whole repository for `docs/theme`). - Ranked after the copy rewrite (#69, merged), which also touched the README's logo path.