Author Plan 0.21 theme preferences

README.md

@@ -6,7 +6,7 @@ canonical Skills and bundled CLI are packaged once for Claude Code and Codex. UI
 app's own design and components. The public catalog and Drawing Board pins determine what an installed workspace
 actually receives.
 
-Source candidate `0.4.0` requires CLI `0.4.0`, Service API `0.4`, and Foundation Plan `0.20`. It preserves the planning
+Source candidate `0.5.0` requires CLI `0.5.0`, Service API `0.5`, and Foundation Plan `0.21`. It preserves the planning
 workspace under `.firstdraft/design/` and defaults to current-folder local output. Use explicit `--github` for server
 Publication. Its identities belong in
 [release compatibility](release/compatibility.json). The [public catalog](.claude-plugin/marketplace.json) owns the
@@ -22,7 +22,7 @@ local folder; a Drawing Board clone and GitHub push are unnecessary. The
 
 - the portable create-full-stack-app Skill and its task routing;
 - deferred UI extension and consistency-review Skill auditions;
-- beginner-to-machine-reference authoring guidance for Foundation Plan 0.20;
+- beginner-to-machine-reference authoring guidance for Foundation Plan 0.21;
 - the exact schema, examples, and review checklists packaged with the Skill;
 - behavioral evaluations for agent workflow changes;
 - shared Claude/Codex plugin assembly around the canonical Skills and reviewed CLI package; and
@@ -39,8 +39,8 @@ behavior. This repository teaches an agent how to use those contracts without cr
 | Understand the installed workflow | [Skill entrypoint](skills/create-full-stack-app/SKILL.md) |
 | Continue or review an app's UI | The app's `UI.md` and shared components; [UI Skill status](#ui-continuation) |
 | Change Plan authoring guidance | [Skill entrypoint](skills/create-full-stack-app/SKILL.md), then [modeling guide](skills/create-full-stack-app/references/modeling-guide.md) |
-| Check current Foundation Plan capability | [Foundation Plan reference](skills/create-full-stack-app/references/foundation-plan-020.md) |
-| Inspect exact Plan structure | [Bundled schema](skills/create-full-stack-app/references/foundation-plan-0.20.schema.json) |
+| Check current Foundation Plan capability | [Foundation Plan reference](skills/create-full-stack-app/references/foundation-plan-021.md) |
+| Inspect exact Plan structure | [Bundled schema](skills/create-full-stack-app/references/foundation-plan-0.21.schema.json) |
 | Add or run behavioral evaluations | [Evaluation guide](evals/README.md) |
 | Inspect a dated observation | [Evidence archive](evidence/README.md) |
 | Prepare or promote a release | [Release runbook](RELEASING.md) |

RELEASING.md

@@ -8,11 +8,15 @@ longer part of an ordinary release. Coordinate the service, CLI, and Skills thro
 
 [`release/compatibility.json`](release/compatibility.json) owns the candidate version, compatible CLI/API/Plan
 identities, and deterministic package SHA-256. The current source candidate is
-`@firstdraft.com/claude-code@0.4.0` with CLI `0.4.0`, API `>= 0.4.0`, `< 0.5.0`, and Plan `sketch/0.20`.
+`@firstdraft.com/claude-code@0.5.0` with CLI `0.5.0`, API `>= 0.5.0`, `< 0.6.0`, and Plan `sketch/0.21`.
 The [marketplace manifest](.claude-plugin/marketplace.json) independently selects a published plugin version;
 retain its selection until the intended new version is actually published. Source compatibility is not public
 catalog selection. Query npm when releasing rather than treating a dated distribution snapshot as current.
 
+Plan `0.21` adds `appearance.theme: "toggle"` and replaces the sole accepted `0.20` input format. API, CLI, and
+plugin `0.5.0` record that input and artifact compatibility break. Target `rails-sketch/2026-09`, local-output
+defaults, and `.firstdraft/design/` stay the same. There is no retained-Project migration or compatibility bridge.
+
 Use an ordinary pre-1.0 minor bump for a breaking compatibility change and a patch bump for a compatible change.
 Never reuse a published npm version, protected release tag, or marketplace version for different package bytes.
 An unpublished, unpromoted candidate may be revised at a new commit and digest without another version bump.

docs/README.md

@@ -13,8 +13,8 @@ historical observations intentionally have different owners.
 | How do I repair an existing npm default? | [npm default repair](npm-promotion.md) |
 | What does the agent execute? | [`SKILL.md`](../skills/create-full-stack-app/SKILL.md) |
 | How does an agent extend or review generated UI? | The app's `UI.md`; [deferred Skill status](../README.md#ui-continuation) |
-| What is exact Plan syntax? | [JSON Schema](../skills/create-full-stack-app/references/foundation-plan-0.20.schema.json) |
-| What capability is currently described? | [Foundation Plan reference](../skills/create-full-stack-app/references/foundation-plan-020.md) |
+| What is exact Plan syntax? | [JSON Schema](../skills/create-full-stack-app/references/foundation-plan-0.21.schema.json) |
+| What capability is currently described? | [Foundation Plan reference](../skills/create-full-stack-app/references/foundation-plan-021.md) |
 | What happened in a particular run? | [`evidence/README.md`](../evidence/README.md), then one dated record |
 | What behavior should a fresh agent exhibit? | [`evals/README.md`](../evals/README.md), then one case |
 | Why do historical pins or limitations exist? | [Repository history](../evidence/repository-history.md) or [release history](../evidence/release-history.md) |

evals/README.md

@@ -4,7 +4,8 @@
 fixtures are review inputs, not execution evidence. Each case declares whether the Skill should trigger and which
 artifacts are attached, staged into the project, or retained only as expected output.
 
-Current authoring cases use Foundation Plan `firstdraft.foundation-plan.sketch/0.20` and target
+The current Plan/analysis fixtures below are synthetic contract inputs, not new Service observations.
+Current authoring cases use Foundation Plan `firstdraft.foundation-plan.sketch/0.21` and target
 `rails-sketch/2026-09`. The `appearance-current` Plan/analysis and `resume-current` Plan fixtures replace their older
 inputs for new evaluations. The original `appearance-issues` Plan/analysis and `resume` Plan retain the exact bytes
 declared by the [September 14 qualification receipt](../evidence/2026-09-14-ui-authoring-skill-0.2.4-qualification.json).
@@ -87,6 +88,7 @@ or live transport of implementation notes through GitHub Publication.
 - `private-native-request-preserves-current-boundary`
 - `android-preview-respects-provider-limit`
 - `preserve-partially-realized-appearance-intent`
+- `preserve-browser-theme-and-native-residual`
 - `correct-source-issue-alongside-capability-gap`
 - `analysis-failed-stop`
 - `standalone-status-binds-accepted-generation`

evals/create-full-stack-app/cases.json

@@ -502,7 +502,7 @@
       "should_trigger": true,
       "prompt": "The staged Plan's domain, selected iPhone client, Movie icon and Field, and public-index Scaffold are intentional. A successful plan push was followed by plan status --wait, which printed the attached valid analysis. Review the result, but do not compile it.",
       "expectations": [
-        "Branches on analysis.status valid and reports analyzer release foundation-plan-rails/application-2026-09-19-conventions, graph version 1, and the absence of diagnostics.",
+        "Branches on analysis.status valid and reports analyzer release foundation-plan-rails/application-2026-09-22-theme, graph version 1, and the absence of diagnostics.",
         "Reports the complete empty firstdraft.foundation-gaps/2 object and exact attached analysis.gap_set_sha256, which the CLI validated against the attached GapSet bytes, rather than omitting the reviewed support result; never substitutes a fixture, historical, or other Project's digest.",
         "Preserves the complete staged Plan unchanged, including its domain, native.ios request, semantic icon, required title Field, and exact public-index Scaffold.",
         "Recognizes that the prepared 2026-09 boundary admits this bounded web public-index and selected iPhone request, while analysis alone does not prove generated output.",
@@ -557,7 +557,7 @@
       "expectations": [
         "Branches on analysis.status valid while explaining that valid applies to the admitted graph and Compilation is not proved.",
         "Reports the complete GapSet and the exact attached analysis.gap_set_sha256, which the CLI validated against the attached GapSet bytes; does not substitute a fixture, historical, or other Project's digest; and includes the partially_generated target_support_gap foundation_plan.gap.appearance.icon_assets.not_generated record at /application/appearance with its reason and consequence.",
-        "Distinguishes the attached historical analysis from current target behavior: the authored theme applies across clients, tint and background colors style native shells and Web icon branding, web components retain stock Zinc tokens, and the selected-iOS AppIcon remains stock.",
+        "Distinguishes the attached analysis from generated or runtime proof: the authored auto theme applies across clients, tint and background colors style native shells and Web icon branding, web components retain stock Zinc tokens, and the selected-iOS AppIcon remains stock.",
         "Preserves the complete Appearance request and every otherwise admitted Application and Entity member without editing, removing, or weakening them.",
         "Does not run plan push or plan status again, compile, or claim generated Appearance, web, or iPhone output."
       ],
@@ -578,6 +578,35 @@
         }
       ]
     },
+    {
+      "id": "preserve-browser-theme-and-native-residual",
+      "should_trigger": true,
+      "prompt": "The staged Plan intentionally offers a Light/Dark/System selector in the browser and requests both iPhone and Android clients. The attached valid analysis came back from plan status --wait. Explain the default, persistence, and every gap before I decide whether to compile. Do not edit or submit the Plan.",
+      "expectations": [
+        "Explains that appearance.theme toggle offers Light, Dark, and System in the browser, initially System, persists only a browser-local preference across visits, and follows operating-system changes only while System is selected.",
+        "Reports both ordered GapSet records and the exact attached analysis.gap_set_sha256, which the CLI validated against the attached GapSet bytes; does not substitute a fixture, historical, or other Project's digest.",
+        "Explains the partially_generated target_support_gap foundation_plan.gap.appearance.native_theme_preference.not_generated at /application/appearance/theme: emitted iOS and Android clients and their embedded Rails responses use automatic appearance; browser selector and stored browser preferences cannot control native shells, and no native preference UI or bridge is generated.",
+        "Reports the separate stock native launcher icon residual, while retaining the authored tint and generated Web icon meaning.",
+        "Preserves toggle and both requested native clients without changing the choice to auto, dropping a client, inventing preference synchronization, or promising native runtime qualification. Valid applies only to the admitted graph and the attached result does not prove Compilation or device behavior.",
+        "Leaves the complete staged Plan and subject UUIDs unchanged, leaves private state unopened, and does not run plan init, plan push, plan status, or plan compile."
+      ],
+      "artifacts": [
+        {
+          "path": "evals/create-full-stack-app/fixtures/theme-toggle-analysis.json",
+          "role": "input"
+        },
+        {
+          "path": "evals/create-full-stack-app/fixtures/theme-toggle.foundation-plan.json",
+          "role": "input",
+          "stage_as": ".firstdraft/foundation-plan.json"
+        },
+        {
+          "path": "evals/create-full-stack-app/fixtures/state-placeholder.txt",
+          "role": "input",
+          "stage_as": ".firstdraft/state.json"
+        }
+      ]
+    },
     {
       "id": "correct-source-issue-alongside-capability-gap",
       "should_trigger": true,
@@ -819,7 +848,7 @@
       "should_trigger": true,
       "prompt": "Use First Draft to create and send a Foundation Plan for Scalar Showcase, application key scalar_showcase. Model one Movie Entity with one Field of each currently importable scalar type, using a required short_text title as its Primary Descriptor and a decimal rating defaulting to 7.5. The compatible firstdraft CLI is installed, but no JSON Schema 2020-12 validator is available. Do not install or implement one.",
       "expectations": [
-        "Uses Foundation Plan 0.20, the Modeling guide, and Examples for authoring without opening the complete bundled schema.",
+        "Uses Foundation Plan 0.21, the Modeling guide, and Examples for authoring without opening the complete bundled schema.",
         "Runs plan init with the provided application key and name, then runs generate uuid --count 11 through the Skill resolver exactly once for one Entity and ten Fields.",
         "Authors one Movie Entity with exactly one Field of each supported scalar type and a required movie.title Field Primary Descriptor.",
         "Authors movie.rating as a decimal with literal default value \"7.5\" as a canonical string, never the JSON number 7.5.",
@@ -1239,7 +1268,7 @@
     {
       "id": "compile-prepared-movie-catalog",
       "should_trigger": true,
-      "prompt": "I approve the exact pre-Compile semantic read-back and reviewed support result for the unchanged staged Movie Catalog with SHA-256 33b267693040b49b527cea77c4c60fcb490e035f9a52e55df5981d6c25a43dd8. Preserve its intentional Appearance request and publish that exact candidate to one private GitHub repository now.",
+      "prompt": "I approve the exact pre-Compile semantic read-back and reviewed support result for the unchanged staged Movie Catalog with SHA-256 025c7021ad31bdd64b01eb007632c000f96a84273d1a53ea41ab5f342d11aa3c. Preserve its intentional Appearance request and publish that exact candidate to one private GitHub repository now.",
       "expectations": [
         "Requires the installed CLI to expose both plan compile completion modes and no public plan publish command.",
         "In the same continuing session, treats the prompt as unambiguous approval of the complete semantic model and reviewed nonempty GapSet, rereads the exact local Plan, verifies its SHA-256 and semantic model are unchanged, and does not ask for a second confirmation or repeat the unchanged read-back.",
@@ -1265,7 +1294,7 @@
     {
       "id": "compile-prepared-drawing-board-application",
       "should_trigger": true,
-      "prompt": "I approve the exact pre-Compile Drawing Board semantic read-back and reviewed support result for the unchanged staged Movie Catalog with SHA-256 33b267693040b49b527cea77c4c60fcb490e035f9a52e55df5981d6c25a43dd8. Materialize that exact candidate into the absent ./application directory. Do not create a GitHub repository.",
+      "prompt": "I approve the exact pre-Compile Drawing Board semantic read-back and reviewed support result for the unchanged staged Movie Catalog with SHA-256 025c7021ad31bdd64b01eb007632c000f96a84273d1a53ea41ab5f342d11aa3c. Materialize that exact candidate into the absent ./application directory. Do not create a GitHub repository.",
       "expectations": [
         "Requires the installed CLI to expose plan compile --output as a direct local completion mode while retaining plan compile --github as the separate GitHub Publication mode.",
         "In the same continuing session as precompile-drawing-board-read-back, treats the prompt as unambiguous approval of the complete semantic model, reviewed nonempty GapSet, exact Plan bytes, and selected direct local mode; rereads the Plan, verifies its SHA-256 is unchanged, and asks for no second confirmation.",

evals/create-full-stack-app/fixtures/analysis-failed-analysis.json

@@ -6,9 +6,9 @@
   "analysis": {
     "id": "01900000-0000-7000-8000-000000000902",
     "graph_version": 1,
-    "head_source_sha256": "9cb632700a7bec3cbd8ca0492581237d8f3061e99cd1c5f148917d5eef60f714",
-    "analyzer_release": "foundation-plan-rails/application-2026-09-19-conventions",
-    "compiler_release": "foundation-plan-rails/compiler-application-2026-09-19-conventions",
+    "head_source_sha256": "e5d6ed13362d9cddd16a4294239e52761791c2eb52a1a5dbfe4b74f03cad2457",
+    "analyzer_release": "foundation-plan-rails/application-2026-09-22-theme",
+    "compiler_release": "foundation-plan-rails/compiler-application-2026-09-22-theme",
     "target": {
       "id": "rails",
       "profile": "rails-sketch/2026-09"

evals/create-full-stack-app/fixtures/appearance-current-analysis.json

@@ -6,9 +6,9 @@
   "analysis": {
     "id": "01900000-0000-7000-8000-000000000906",
     "graph_version": 1,
-    "head_source_sha256": "33b267693040b49b527cea77c4c60fcb490e035f9a52e55df5981d6c25a43dd8",
-    "analyzer_release": "foundation-plan-rails/application-2026-09-19-conventions",
-    "compiler_release": "foundation-plan-rails/compiler-application-2026-09-19-conventions",
+    "head_source_sha256": "025c7021ad31bdd64b01eb007632c000f96a84273d1a53ea41ab5f342d11aa3c",
+    "analyzer_release": "foundation-plan-rails/application-2026-09-22-theme",
+    "compiler_release": "foundation-plan-rails/compiler-application-2026-09-22-theme",
     "target": {
       "id": "rails",
       "profile": "rails-sketch/2026-09"
@@ -18,16 +18,16 @@
     "gap_set": {
       "format": "firstdraft.foundation-gaps/2",
       "source": {
-        "sha256": "33b267693040b49b527cea77c4c60fcb490e035f9a52e55df5981d6c25a43dd8"
+        "sha256": "025c7021ad31bdd64b01eb007632c000f96a84273d1a53ea41ab5f342d11aa3c"
       },
       "project": {
         "id": "01900000-0000-7000-8000-000000000021",
         "graph_version": 1
       },
       "analysis": {
-        "release": "foundation-plan-rails/application-2026-09-19-conventions"
+        "release": "foundation-plan-rails/application-2026-09-22-theme"
       },
-      "compiler_release": "foundation-plan-rails/compiler-application-2026-09-19-conventions",
+      "compiler_release": "foundation-plan-rails/compiler-application-2026-09-22-theme",
       "target": {
         "id": "rails",
         "profile": "rails-sketch/2026-09"
@@ -45,7 +45,7 @@
         }
       ]
     },
-    "gap_set_sha256": "1828d17230eb549098229bb0ae479e8abea8909058767daa1d82f73fee9cde1d",
+    "gap_set_sha256": "73a0f23d81563e4ea932874fb8af8b6ad4d819304b5917a9798086878a85c03c",
     "started_at": "2026-07-30T12:03:00.000Z",
     "completed_at": "2026-07-30T12:03:01.000Z"
   }

evals/create-full-stack-app/fixtures/appearance-current.foundation-plan.json

@@ -1,5 +1,5 @@
 {
-  "format": "firstdraft.foundation-plan.sketch/0.20",
+  "format": "firstdraft.foundation-plan.sketch/0.21",
   "target": {
     "id": "rails",
     "profile": "rails-sketch/2026-09"