Prepare Macs for the First Draft workshop

.claude-plugin/plugin.json

@@ -17,6 +17,7 @@
     "application-generation"
   ],
   "skills": [
-    "./skills/create-full-stack-app"
+    "./skills/create-full-stack-app",
+    "./skills/setup-first-draft"
   ]
 }

AGENTS.md

@@ -5,6 +5,7 @@
 | Task | Route |
 |---|---|
 | Plan authoring or Compile behavior | [`skills/create-full-stack-app/SKILL.md`](skills/create-full-stack-app/SKILL.md), then only its routed reference section |
+| Workshop prerequisites or local setup | [`docs/workshop-setup.md`](docs/workshop-setup.md), then [`skills/setup-first-draft/SKILL.md`](skills/setup-first-draft/SKILL.md) |
 | UI continuation or review | The consumer app's `UI.md`; [UI Skill auditions remain deferred](README.md#ui-continuation) |
 | Release work | [`RELEASING.md`](RELEASING.md) and [`release/compatibility.json`](release/compatibility.json) |
 | Evidence or prior rollout facts | [`evidence/README.md`](evidence/README.md), then one dated record |

CHANGELOG.md

@@ -29,6 +29,18 @@ Entries are newest first. Keep their headings stable. Publish material correctio
 new entries so readers who advanced their checkpoint see them. Entries explain what changed, why, when it applies,
 and any useful small example or verification; they need not reproduce commit logs.
 
+## 2026-09-27: Mac setup with your agent
+
+**Skills — unreleased source candidate.** The new `setup-first-draft` Skill pairs a Mac prerequisite installer with
+guidance for running a compiled app. The [workshop setup entry point](docs/workshop-setup.md) can be read before
+Node or the First Draft plugin is installed, avoiding a circular setup requirement.
+
+The installer uses Homebrew and mise, then reads runtime versions from the compiled app. An existing runtime
+manager stays in place; the agent uses it instead of migrating the user's projects. Application setup still belongs
+to the emitted `bin/setup` and `bin/dev`. This is workshop tooling, not another dependency for emitted applications.
+The [clean-Mac prerequisite trial](evidence/2026-09-27-mac-setup-prerequisites.md) verifies installation, a safe rerun,
+and Desktop tool discovery. Compilation and local Rails preview in that VM remain pending.
+
 ## 2026-09-27: Public Plan authoring references
 
 **Skills — merged source, unreleased 0.7.1 candidate.** The packaged authoring references now route to the existing

README.md

@@ -12,8 +12,8 @@ It preserves the planning workspace under `.firstdraft/design/` and defaults to
 Use explicit `--github` for server
 Publication. Its identities belong in
 [release compatibility](release/compatibility.json). The [public catalog](.claude-plugin/marketplace.json) owns the
-installed version; source compatibility does not establish publication. Only `create-full-stack-app` is packaged;
-the UI Skill auditions remain deferred source.
+installed version; source compatibility does not establish publication. The candidate packages `create-full-stack-app`
+and `setup-first-draft`. The UI Skill auditions remain deferred source.
 
 Trying First Draft as a tester? Start with the
 [local development guide](https://gist.github.com/raghubetina/3d424a97a1eaa6de8c406e67f32a237e). Start in an empty
@@ -39,6 +39,7 @@ behavior. This repository teaches an agent how to use those contracts without cr
 |---|---|
 | Change the Skill or repository | [Agent instructions](AGENTS.md), then [documentation map](docs/README.md) |
 | Understand the installed workflow | [Skill entrypoint](skills/create-full-stack-app/SKILL.md) |
+| Prepare a Mac for the workshop | [Setup entry point](docs/workshop-setup.md), then [setup Skill](skills/setup-first-draft/SKILL.md) |
 | Continue or review an app's UI | The app's `UI.md` and shared components; [UI Skill status](#ui-continuation) |
 | Review improvements for an existing app or workflow | [First Draft changelog](CHANGELOG.md) |
 | 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) |
@@ -84,6 +85,7 @@ conversation, run `codex resume` from the same workspace root.
 | Path | Responsibility |
 |---|---|
 | skills/create-full-stack-app/ | Canonical portable Skill and packaged references |
+| skills/setup-first-draft/ | Mac prerequisite installer and local-app setup guidance |
 | skills/extend-app-ui/, skills/review-ui-consistency/ | Deferred UI Skill sources, excluded from the package |
 | .claude-plugin/, packages/ | Release-gated public catalog selection and plugin assembly, not a second editable Skill copy |
 | evals/ | Behavioral cases and evaluator contracts |

docs/README.md

@@ -25,6 +25,7 @@ dated observation records an earlier value.
 
 ## Routes by task
 
+- **Workshop setup:** [public entry point](workshop-setup.md), then the [setup Skill](../skills/setup-first-draft/SKILL.md).
 - **Skill authoring:** read the relevant Skill's `SKILL.md`, then only its applicable reference. Packaged bytes are
   the product surface; changing any of them changes the candidate digest.
 - **Foundation Plan examples or schema:** start with `references/examples.md` or the relevant prose subsection. Pass

docs/examples/reading-list.foundation-plan.json

@@ -0,0 +1,238 @@
+{
+  "format": "firstdraft.foundation-plan.sketch/0.22",
+  "target": {
+    "id": "rails",
+    "profile": "rails-sketch/2026-09"
+  },
+  "application": {
+    "key": "reading_list",
+    "name": "Reading List",
+    "native": {
+      "ios": {},
+      "android": {}
+    },
+    "delivery": {},
+    "home_index": "book",
+    "entities": [
+      {
+        "subject_uuid": "01a0e512-df9a-7619-b775-835c95e82dad",
+        "key": "book",
+        "name": "Book",
+        "icon": "bookmark",
+        "primary_descriptor": {
+          "field": "book.title"
+        },
+        "fields": [
+          {
+            "subject_uuid": "01a0e512-dd36-7fd0-9163-5df02d9b3187",
+            "key": "title",
+            "name": "Title",
+            "type": "short_text",
+            "required": true,
+            "normalizations": [
+              "trim",
+              "blank_to_null"
+            ]
+          },
+          {
+            "subject_uuid": "01a0e512-dde1-7812-91b5-30af80dcbb94",
+            "key": "author",
+            "name": "Author",
+            "type": "short_text",
+            "required": true,
+            "normalizations": [
+              "trim",
+              "blank_to_null"
+            ]
+          },
+          {
+            "subject_uuid": "01a0e512-de5e-715c-9520-a372678ff8c3",
+            "key": "note",
+            "name": "Note",
+            "type": "long_text",
+            "required": false
+          },
+          {
+            "subject_uuid": "01a0e512-df0f-79e4-9879-27882ba6af93",
+            "key": "finished",
+            "name": "Finished",
+            "type": "boolean",
+            "required": true,
+            "default": {
+              "kind": "literal",
+              "value": false
+            }
+          }
+        ],
+        "scaffold": {
+          "resource_routes": [
+            "index",
+            "show",
+            "new",
+            "create",
+            "edit",
+            "update",
+            "destroy"
+          ],
+          "index": {
+            "authorization": "public",
+            "projection": [
+              {
+                "field": "book.title"
+              },
+              {
+                "field": "book.author"
+              },
+              {
+                "field": "book.note"
+              },
+              {
+                "field": "book.finished"
+              }
+            ]
+          },
+          "show": {
+            "authorization": "public",
+            "projection": [
+              {
+                "field": "book.title"
+              },
+              {
+                "field": "book.author"
+              },
+              {
+                "field": "book.note"
+              },
+              {
+                "field": "book.finished"
+              }
+            ]
+          },
+          "create": {
+            "authorization": "public",
+            "inputs": [
+              {
+                "field": "book.title"
+              },
+              {
+                "field": "book.author"
+              },
+              {
+                "field": "book.note"
+              },
+              {
+                "field": "book.finished"
+              }
+            ]
+          },
+          "update": {
+            "authorization": "public",
+            "inputs": [
+              {
+                "field": "book.title"
+              },
+              {
+                "field": "book.author"
+              },
+              {
+                "field": "book.note"
+              },
+              {
+                "field": "book.finished"
+              }
+            ]
+          },
+          "destroy": {
+            "authorization": "public"
+          }
+        }
+      }
+    ],
+    "development_data": [
+      {
+        "subject_uuid": "01a0e512-e047-7031-b879-8a51711f0562",
+        "key": "a_wizard_of_earthsea",
+        "entity": "book",
+        "fields": [
+          {
+            "field": "book.title",
+            "value": {
+              "kind": "literal",
+              "value": "A Wizard of Earthsea"
+            }
+          },
+          {
+            "field": "book.author",
+            "value": {
+              "kind": "literal",
+              "value": "Ursula K. Le Guin"
+            }
+          },
+          {
+            "field": "book.finished",
+            "value": {
+              "kind": "literal",
+              "value": false
+            }
+          }
+        ]
+      },
+      {
+        "subject_uuid": "01a0e512-e10c-7c17-afd5-7a4104878a85",
+        "key": "pride_and_prejudice",
+        "entity": "book",
+        "fields": [
+          {
+            "field": "book.title",
+            "value": {
+              "kind": "literal",
+              "value": "Pride and Prejudice"
+            }
+          },
+          {
+            "field": "book.author",
+            "value": {
+              "kind": "literal",
+              "value": "Jane Austen"
+            }
+          },
+          {
+            "field": "book.finished",
+            "value": {
+              "kind": "literal",
+              "value": true
+            }
+          }
+        ]
+      },
+      {
+        "subject_uuid": "01a0e512-e1b5-7efa-a6fa-c5b81bb1e7bc",
+        "key": "the_hobbit",
+        "entity": "book",
+        "fields": [
+          {
+            "field": "book.title",
+            "value": {
+              "kind": "literal",
+              "value": "The Hobbit"
+            }
+          },
+          {
+            "field": "book.author",
+            "value": {
+              "kind": "literal",
+              "value": "J. R. R. Tolkien"
+            }
+          },
+          {
+            "field": "book.finished",
+            "value": {
+              "kind": "literal",
+              "value": false
+            }
+          }
+        ]
+      }
+    ]
+  }
+}

docs/workshop-setup.md

@@ -0,0 +1,53 @@
+# First Draft workshop setup
+
+This is the agent entry point for local workshop setup. The student has installed Claude Desktop, signed in,
+opened the **Code** tab in a **Local** environment, and selected their project folder. A supported paid Claude
+subscription is required. Use the scope in their request; setup alone does not request a deployment.
+
+Lead setup from this session: inspect the machine, use the standard recipe where it fits, and diagnose failures
+from the install log. A Terminal handoff is only for steps that require it; the student should not have to
+troubleshoot their toolchain before returning to you.
+
+## Get the setup Skill before Node or Git is installed
+
+On a Mac, download this repository into a temporary directory outside the student's app folder. The system's curl,
+tar, and Bash are sufficient:
+
+```sh
+setup_download=$(mktemp -d -t firstdraft-setup)
+curl --fail --location --silent --show-error \
+  https://github.com/firstdraft/skills/archive/refs/heads/main.tar.gz \
+  -o "$setup_download/skills.tar.gz"
+tar -xzf "$setup_download/skills.tar.gz" -C "$setup_download"
+```
+
+Read `$setup_download/skills-main/skills/setup-first-draft/SKILL.md`, and use that directory for its script paths.
+Keep the resolved absolute path for later tool calls. This reads the canonical instructions directly; it does not
+register a plugin. The Skill then guides the normal plugin installation after Node is available.
+
+If working from a candidate checkout, use its setup Skill directly so the trial exercises that candidate. The
+published entry point above follows `main`; confirm the candidate is merged before directing students to it.
+
+For Windows, start with the [WSL reference](../skills/setup-first-draft/references/windows.md). The Mac script must
+not be run in PowerShell or WSL. The workshop can use [Codespaces](https://github.com/firstdraft/drawing-board)
+when local setup is unsuitable.
+
+## Continue the workshop
+
+The [setup Skill](../skills/setup-first-draft/SKILL.md) owns prerequisites and local startup. After it succeeds,
+follow the student's workshop guide for the [prepared Reading List Plan](examples/reading-list.foundation-plan.json),
+private GitHub publication, deployment, and Revyl. The Plan lives here so students can fetch it without access to
+the private lesson repository.
+Use the installed authoring Skill for the current Plan contract and Compilation commands, and the generated app's
+documentation for sample data, deployment, and native preview. Do not install Xcode, Android Studio, a local tunnel,
+or a separate editor merely to complete a preview that uses GitHub builds and the deployed app.
+
+## Maintainer smoke
+
+Replay the student's entry prompt in a clean Mac VM with a normal user account. Keep password prompts enabled.
+Record the OS/architecture, setup revision, versions, manual actions, and actual local create/edit result. Then
+rerun setup and repeat from a fresh agent session to check runtime discovery. An interrupted install should be
+recoverable by correcting the reported step and rerunning; it should not require deleting the project.
+
+Machine setup and localhost are separate observations from service Compilation, deployed Rails, and a Revyl
+session. Record untested boundaries explicitly. A Mac trial does not establish Windows/WSL compatibility.