mapples 0.2.0-beta.6 → 0.2.0-beta.8

package/templates/{claude → agent}/skills/mapples-design/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: mapples-design
-description: Build a Mapples-linked Expo app from a product brief the way the Creator's in-app AI does — design tokens, an implementation plan, one screen per phase from the design playbooks, wiring and a review — writing route files and mapples/theme.ts and pushing each phase with `mapples sync` while holding the project's agent lease. Use when the user asks to design, generate or build the app, its screens or its design system.
+description: Build a Mapples-linked Expo app from a product brief the way the Creator's in-app AI does — design tokens, an implementation plan, one screen per phase from the design playbooks, wiring and a review — writing route files and mapples/theme.ts and pushing each phase with `npx -y mapples@__CLI_VERSION__ sync` while holding the project's agent lease. Use when the user asks to design, generate or build the app, its screens or its design system.
 argument-hint: "<product brief> [--scope single|minimal|basic|advanced]"
 ---
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
-# /mapples-design — build the app from a brief
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# mapples-design — build the app from a brief
 
 You are the product designer and builder for this app. Your bar is a finished screen a
 designer would ship — not a wireframe. Everything you make is a file in this repo; every phase
-ends with `mapples sync --yes --json`, which pushes it to Creator where the user watches it land.
+ends with `npx -y mapples@__CLI_VERSION__ sync --yes --json`, which pushes it to Creator where the user watches it land.
 
-Read `.claude/mapples.md` and the `mapples-conventions` and `mapples-sync` skills before the
+Read `__CONVENTIONS_PATH__` and the `mapples-conventions` and `mapples-sync` skills before the
 first file. Reference material for this skill lives next to it:
 
 - `reference/style-guides.md` — art directions and style guides (phase 1)
@@ -24,11 +24,11 @@ first file. Reference material for this skill lives next to it:
 ## Preconditions
 
 1. `.mapples/config.json` must exist (the app is linked). If not: stop and ask the user to run
-   `npx mapples init --secret <key> --agent claude` — never run it yourself.
-2. `mapples agent status --json`. If `session` is non-null with `status: "active"` and
+   `npx -y mapples@__CLI_VERSION__ init --secret <key> --agent __AGENT_FLAG__` — never run it yourself.
+2. `npx -y mapples@__CLI_VERSION__ agent status --json`. If `session` is non-null with `status: "active"` and
    `holdsLease` is false, another agent is working on this project: stop and ask whether to take
    over (`--takeover` disconnects it). Never take over silently.
-3. `mapples sync --yes --json` — be current before designing. Exit 2 here means the repo already
+3. `npx -y mapples@__CLI_VERSION__ sync --yes --json` — be current before designing. Exit 2 here means the repo already
    had conflicts: resolve them (see `mapples-sync`) before going on.
 4. Read `mapples/design.md` if it exists: a previous run's brief, chosen style and plan. Resume
    from the first phase whose output is missing rather than redoing everything.
@@ -46,17 +46,17 @@ progress log:
 Start the session as soon as the brief and scope are known, pre-declaring every step title:
 
 ```bash
-mapples agent start --label "Claude Code" --steps "Brief,Style guides,Design tokens,Plan,Scaffold navigation & screens" --json
+npx -y mapples@__CLI_VERSION__ agent start --agent __AGENT_ID__ --label "__AGENT_LABEL__" --steps "Brief,Style guides,Design tokens,Plan,Scaffold navigation & screens" --json
 ```
 
 Exit 4 = busy (see precondition 2). After the plan exists (phase 3), the remaining titles are
-declared as they run: `mapples agent step --index 5 --title "Build the Home screen" --status running`
+declared as they run: `npx -y mapples@__CLI_VERSION__ agent step --index 5 --title "Build the Home screen" --status running`
 creates the step. Wrap **every** phase:
 
 ```bash
-mapples agent step --index <i> --title "<title>" --status running --json
+npx -y mapples@__CLI_VERSION__ agent step --index <i> --title "<title>" --status running --json
 # … the work …
-mapples agent step --index <i> --title "<title>" --status done --detail "<one line>" --json
+npx -y mapples@__CLI_VERSION__ agent step --index <i> --title "<title>" --status done --detail "<one line>" --json
 ```
 
 Exit 3 from any `agent` or `sync` command = the lease is gone (Creator disconnected you or the
@@ -65,8 +65,8 @@ lease expired). Stop immediately, do not sync again, and tell the user what was
 Always end the run — success or not:
 
 ```bash
-mapples agent stop --status done --json
-mapples agent stop --status failed --error "<what blocked the run>" --json
+npx -y mapples@__CLI_VERSION__ agent stop --status done --json
+npx -y mapples@__CLI_VERSION__ agent stop --status failed --error "<what blocked the run>" --json
 ```
 
 A phase's syncs are labelled with the running step in Creator's history automatically.
@@ -75,7 +75,7 @@ A phase's syncs are labelled with the running step in Creator's history automati
 
 Input: `$ARGUMENTS` (the brief, optionally `--scope single|minimal|basic|advanced`). If the
 brief is missing or too thin to name the audience, the core value and the mood, ask **one**
-round of questions (AskUserQuestion) — audience, the one thing the app must do well, the
+round of questions (with your multiple-choice question tool, when you have one) — audience, the one thing the app must do well, the
 feeling it should have, and the scope if absent (default `basic`). Then write
 `mapples/design.md`:
 
@@ -102,7 +102,7 @@ Follow `reference/design-tokens.md` exactly: write `mapples/theme.ts` (create it
 file and an empty project is a no-op, so the file is what pushes the tokens). Then
 
 ```bash
-mapples sync --yes --json
+npx -y mapples@__CLI_VERSION__ sync --yes --json
 ```
 
 Assert: `exitCode` 0, `pushedOps` ≥ 3 (Theme, Typography, Sizing updates) and no
@@ -116,10 +116,10 @@ Follow `reference/plan.md`: decisions, navigation (sections → screens), entry
 build steps. Append it to `design.md` under `## Plan` **and** declare the remaining steps:
 
 ```bash
-mapples agent step --index 5 --title "<plan step 1 title>" --status pending --json
+npx -y mapples@__CLI_VERSION__ agent step --index 5 --title "<plan step 1 title>" --status pending --json
 …
-mapples agent step --index <N-1> --title "Wiring" --status pending --json
-mapples agent step --index <N> --title "Review" --status pending --json
+npx -y mapples@__CLI_VERSION__ agent step --index <N-1> --title "Wiring" --status pending --json
+npx -y mapples@__CLI_VERSION__ agent step --index <N> --title "Review" --status pending --json
 ```
 
 Show the plan to the user in 6–10 lines; continue unless they object.
@@ -142,7 +142,7 @@ navigation:
   `pagesDir`.
 
 ```bash
-mapples sync --yes --json
+npx -y mapples@__CLI_VERSION__ sync --yes --json
 ```
 
 Assert no conflicts, then read `.mapples/pages.json`: every scaffolded file must be a value's
@@ -167,7 +167,7 @@ For each plan step, in order:
    every existing `$sid` on the element it is on, add none. Obey `reference/layout-contract.md`
    and the chosen style guide's instructions (they outrank the contract where they differ).
    Real copy from the brief; picsum photos in every hero/featured/thumb slot.
-4. `mapples sync --yes --json`. Assert `exitCode` 0; read `warnings` and fix what is yours
+4. `npx -y mapples@__CLI_VERSION__ sync --yes --json`. Assert `exitCode` 0; read `warnings` and fix what is yours
    (NON_LITERAL_PROP on a value you can make literal, UNKNOWN_ELEMENT). Exit 2 → resolve per
    `mapples-sync`, sync again.
 5. Re-read the file (it now carries `$sid`s), run it through `reference/lint-checklist.md`
@@ -199,10 +199,10 @@ path from the entry screen; every screen reachable, every flow with an exit. Syn
 ## Phase N — Review
 
 Load `reference/lint-checklist.md`. For every screen: re-read the file, check each item, fix.
-Then `mapples doctor --json` (no `duplicate`/`missing` issues; `drift` is fine before the final
-sync) and a final `mapples sync --yes --json` with exit 0. Update `design.md` with a `## Status`
+Then `npx -y mapples@__CLI_VERSION__ doctor --json` (no `duplicate`/`missing` issues; `drift` is fine before the final
+sync) and a final `npx -y mapples@__CLI_VERSION__ sync --yes --json` with exit 0. Update `design.md` with a `## Status`
 line (screens built, what was cut, the one decision the user may want to change). Then
-`mapples agent stop --status done`.
+`npx -y mapples@__CLI_VERSION__ agent stop --status done`.
 
 Reply to the user in 3–5 lines: what was built, where to look in Creator, the one decision to
 revisit. No headings.

package/templates/{claude → agent}/skills/mapples-design/reference/component-library.md

@@ -1,8 +1,8 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Component library — what to reach for
 
 Two packages, one canvas. Everything below is a registered canvas type: Creator renders it,
-its style panel edits it, and `mapples sync` round-trips it. Import primitives from
+its style panel edits it, and `npx -y mapples@__CLI_VERSION__ sync` round-trips it. Import primitives from
 `@mapples/ui`, the themed library from `@mapples/components`. Anything else you import is an
 opaque `Custom` node (allowed, but Creator cannot design inside it).
 

package/templates/{claude → agent}/skills/mapples-design/reference/design-tokens.md

@@ -1,9 +1,9 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Design tokens (phase 2) — `mapples/theme.ts`
 
 Ported from the Creator's full-variant generation (`generate.ts` `variantSystem` +
 `schemas.ts` `designVariantSchema`). The output is a file, not a JSON reply: `mapples/theme.ts`
-exports three **literal** objects — `theme`, `typography`, `sizing` — and `mapples sync` pushes
+exports three **literal** objects — `theme`, `typography`, `sizing` — and `npx -y mapples@__CLI_VERSION__ sync` pushes
 them as the project's Theme, Typography and Sizing documents.
 
 ## Rules
@@ -53,7 +53,7 @@ colors are anchors to build around), same fonts, same shape language, same iconF
 ## The file — copy this shape exactly, fill every value
 
 ```ts
-// mapples/theme.ts — design tokens, synced with Creator by `mapples sync`.
+// mapples/theme.ts — design tokens, synced with Creator by `npx -y mapples@__CLI_VERSION__ sync`.
 // Edit values freely; keys you add here are pushed to the canvas style config.
 
 export const theme = {
@@ -120,7 +120,7 @@ unreadable and the sync reports `NON_LITERAL_PROP … local style edits ignored`
 ## After writing
 
 ```bash
-mapples sync --yes --json
+npx -y mapples@__CLI_VERSION__ sync --yes --json
 ```
 
 Expect `pushedOps` ≥ 3 and `exitCode` 0. The tokens are now the project's; every style token

package/templates/{claude → agent}/skills/mapples-design/reference/layout-contract.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Layout contract — every screen
 
 Ported from the Creator agent's system prompt (`agent/prompt.ts`: `LAYOUT_CONTRACT`,

package/templates/{claude → agent}/skills/mapples-design/reference/lint-checklist.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Review checklist — the layout lint, by hand
 
 Ported from the Creator's `designLint.ts`, which runs on every AI-authored tree before it is
@@ -43,8 +43,8 @@ photos (the scrim gradient is there), an emoji anywhere, placeholder copy ("Item
 The squint test: if you blur the screen you should still see WHERE to look first and WHAT is
 tappable. If everything is even grey noise, raise the focal point and quiet the rest.
 
-Finally, `mapples doctor --json` must show no `duplicate` or `missing` issues, and the last
-`mapples sync --yes --json` must exit 0 with no `warnings` of kind `UNKNOWN_ELEMENT_WITH_SID`.
+Finally, `npx -y mapples@__CLI_VERSION__ doctor --json` must show no `duplicate` or `missing` issues, and the last
+`npx -y mapples@__CLI_VERSION__ sync --yes --json` must exit 0 with no `warnings` of kind `UNKNOWN_ELEMENT_WITH_SID`.
 
 > Not ported (Creator-only): `strictProps` per-schematic hint lists, the icon-glyph set and
 > token set validation (both live in the Creator's registry), `aiLint` hints (`selfSpaced`,

package/templates/{claude → agent}/skills/mapples-design/reference/plan.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Implementation plan (phase 3)
 
 Ported from `generate.ts` `generatePlan` and `schemas.ts` `implementationPlanSchema`. Act as a

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/empty-states.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Empty states
 
 First-run and no-content screens: icon, copy formula, one clear action.

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/forms-and-auth.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Forms and auth
 
 Sign in/up and any input form: field anatomy, grouping, validation, CTA.

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/home-dashboard.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Home / dashboard
 
 Home screens: greeting header, search, featured card, rails and lists.

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/list-and-detail.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Lists and detail screens
 
 List rows, cards, detail screens with hero, meta pills and sticky CTA.

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/microcopy.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Microcopy
 
 Copy that sells: verbs on buttons, benefit headlines, product voice, error tone.

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/navigation-chrome.md

@@ -1,10 +1,10 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Navigation chrome
 
 Headers, tab bars, chips, badges and breadcrumbs: navigator options vs content-sized elements.
 
 Two kinds of chrome, two mechanisms — never mix them up:
-- Stack headers and tab bars belong to the NAVIGATOR. In this version they are set in Creator (navigator options: header visible/title/colors/back, tab bar colors/labels; route options: title, tab label, tab icon asset) and land in the CLI-owned `_layout.tsx` on the next sync — you cannot set them from code, and you must not edit the layouts. Describe the intended chrome per section in `design.md` under `## Navigation chrome` (which sections hide the header, tab labels and icon concepts, modal routes) so the user applies it. A hand-built header row on a screen whose stack also shows a header gives two headers: design for one — the default root layout hides headers (`headerShown: false`), so in-content `TopAppBar` is the norm for apps born from `mapples create`.
+- Stack headers and tab bars belong to the NAVIGATOR. In this version they are set in Creator (navigator options: header visible/title/colors/back, tab bar colors/labels; route options: title, tab label, tab icon asset) and land in the CLI-owned `_layout.tsx` on the next sync — you cannot set them from code, and you must not edit the layouts. Describe the intended chrome per section in `design.md` under `## Navigation chrome` (which sections hide the header, tab labels and icon concepts, modal routes) so the user applies it. A hand-built header row on a screen whose stack also shows a header gives two headers: design for one — the default root layout hides headers (`headerShown: false`), so in-content `TopAppBar` is the norm for apps born from `npx -y mapples@__CLI_VERSION__ create`.
 - Tab icons require an icon ASSET in Creator; an `Icon` element or a glyph name does nothing there. Note the icon concept per tab in `design.md`; keep tab labels short and distinct — never fake a tab bar from a row of buttons on the page.
 - Everything inside the content area (chips, pills, badges, breadcrumbs, in-content title rows) is a CONTENT-SIZED library element: never width 100% inside a row or a horizontal scroll; never a `Button` where a `Chip` is meant.
 

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/onboarding-flow.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Onboarding flow
 
 Welcome/intro flows: 2–3 value-prop screens with hero, dots and CTA arc.

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/screen-flow-wiring.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Screen flow wiring
 
 Wiring flows: every CTA connected, entries set, a walkable prototype.
@@ -30,7 +30,7 @@ The contract:
 - Entries: the app must open on the value, not on a settings screen. The initial section/route is a navigator option set in Creator — state the intended entry in `design.md` under `## Navigation chrome` (the scaffold's `index.tsx` of the initial section is the natural default).
 - Presentation: multi-screen interruptions and create-flows present as modal ROUTES (a navigator option — describe them in `design.md`); browsing pushes. Confirmations, pickers and quick details stay on the screen as `Dialog` / `BottomSheet` / `ActionSheet` with `visible={false}`, or bound through `$data={{ visible: { key: 'vars.<name>', active: true } }}` when the project has the variable — an overlay nobody can open or close is a dead end.
 
-Verify like a user: after wiring, walk the golden path mentally from the entry screen — first open → core value → primary action → done. Name the connection chain; every hop must exist. Then `mapples sync --yes --json` and check that `pushedOps` covers every `$actions` you added (an action on an element without a `$sid` yet lands on the sync after the element is tagged).
+Verify like a user: after wiring, walk the golden path mentally from the entry screen — first open → core value → primary action → done. Name the connection chain; every hop must exist. Then `npx -y mapples@__CLI_VERSION__ sync --yes --json` and check that `pushedOps` covers every `$actions` you added (an action on an element without a `$sid` yet lands on the sync after the element is tagged).
 
 Pitfalls: wiring only the happy screen and leaving detail pages orphaned; two buttons navigating to the same place with different labels; a tab bar plus in-content navigation to the same sections.
 

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/settings-profile.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Settings and profile
 
 Settings and profile screens: grouped cards, icon rows, switches, sign out.

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/stats-and-progress.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Stats and progress
 
 Numbers, balances, goals: stat cards, progress bars, streaks — no fake charts.

package/templates/{claude → agent}/skills/mapples-design/reference/playbooks/visual-hierarchy.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Visual hierarchy
 
 Cross-screen craft: one focal point, the type ladder, grouping, squint-test review.

package/templates/{claude → agent}/skills/mapples-design/reference/style-guides.md

@@ -1,4 +1,4 @@
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
 # Style guides (phase 1)
 
 Ported from the Creator's design setup (`service--mapples-ai` `design/generate.ts`): first art

package/templates/{claude → agent}/skills/mapples-sync/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: mapples-sync
-description: Running `mapples sync` from an agent — the --yes --json invocation, the JSON report fields, exit codes 0/1/2/3/4, and what to do on conflicts, deprecated files, NON_LITERAL_PROP warnings, read-scoped keys and offline runs. Use before and after every sync in a Mapples-linked app.
+description: Running `npx -y mapples@__CLI_VERSION__ sync` from an agent — the --yes --json invocation, the JSON report fields, exit codes 0/1/2/3/4, and what to do on conflicts, deprecated files, NON_LITERAL_PROP warnings, read-scoped keys and offline runs. Use before and after every sync in a Mapples-linked app.
 ---
-<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
-# mapples sync
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# npx -y mapples@__CLI_VERSION__ sync
 
-`mapples sync` is the only way changes reach Creator. Run it from the app root as
+`npx -y mapples@__CLI_VERSION__ sync` is the only way changes reach Creator. Run it from the app root as
 
 ```bash
-mapples sync --yes --json
+npx -y mapples@__CLI_VERSION__ sync --yes --json
 ```
 
 - `--yes` accepts every adoption proposal (new route files, pages, components) without a prompt —
@@ -16,8 +16,9 @@ mapples sync --yes --json
   leave new files untouched (e.g. a helper you do not want on the canvas yet).
 - `--json` prints one JSON report and nothing else. Always parse it; never rely on the exit
   code alone.
-- The CLI is on the app's `devDependencies`; use `npx mapples …` (or `yarn mapples …`) when the
-  bare command is not on the PATH.
+- Always run the CLI exactly as written here, pinned to the version that generated these skills:
+  `npx -y mapples@__CLI_VERSION__ …`. Never a bare `mapples` and never an unpinned `npx mapples` — npm's
+  `latest` tag can be an older CLI without these commands, and a fallback silently runs it.
 
 ## What one run does
 
@@ -61,8 +62,8 @@ mapples sync --yes --json
 | 0 | synced | read `pushedOps`, `files`, `warnings` |
 | 1 | error (bad key, malformed file, server refusal) | read stderr; fix the cause; never retry blindly |
 | 2 | synced **with conflicts** | for every `conflicts[]` entry: diff `deprecatedTo` against the regenerated file, re-apply your intent onto the new file, sync again |
-| 3 | agent lease gone (from `mapples agent …`) | stop working, tell the user Creator disconnected the agent |
-| 4 | project busy (from `mapples agent start`) | another agent session holds the project — ask before `--takeover` |
+| 3 | agent lease gone (from `npx -y mapples@__CLI_VERSION__ agent …`) | stop working, tell the user Creator disconnected the agent |
+| 4 | project busy (from `npx -y mapples@__CLI_VERSION__ agent start`) | another agent session holds the project — ask before `--takeover` |
 
 ## After a sync
 
@@ -81,9 +82,9 @@ mapples sync --yes --json
 
 - `push rejected: API key is read-scoped …` — the `MAPPLES_SECRET` / `.mapples/secret` key can
   only read. Ask the user for a read & write key (Creator → Project → Settings → API keys) and
-  to restart with `MAPPLES_SECRET=<key> claude`; do not edit `.mapples/secret` yourself.
+  to restart with `__AGENT_RESTART__`; do not edit `.mapples/secret` yourself.
 - `no .mapples/config.json` — you are not in the app root, or the app is not linked; do not run
-  `mapples init` on your own — ask.
+  `npx -y mapples@__CLI_VERSION__ init` on your own — ask.
 - `HEAD_MISMATCH … could not be committed after 5 rebases` — Creator is being edited at the same
   time; wait a moment and sync again.
 

package/templates/app.json

@@ -6,7 +6,6 @@
     "orientation": "portrait",
     "scheme": "__APP_NAME__",
     "userInterfaceStyle": "automatic",
-    "newArchEnabled": true,
     "plugins": ["expo-router"],
     "experiments": {
       "typedRoutes": true

package/templates/package.json

@@ -35,16 +35,17 @@
     "@react-native-vector-icons/octicons": "^21.1.0",
     "@react-native-vector-icons/simple-line-icons": "^13.1.0",
     "@react-native-vector-icons/zocial": "^13.1.0",
-    "expo": "~57.0.19",
-    "expo-constants": "~57.0.17",
-    "expo-font": "~57.0.3",
-    "expo-linear-gradient": "~57.0.1",
-    "expo-linking": "~57.0.9",
-    "expo-router": "~57.0.18",
-    "expo-splash-screen": "~57.0.8",
+    "expo": "~57.0.23",
+    "expo-constants": "~57.0.18",
+    "expo-font": "~57.0.4",
+    "expo-image": "~57.0.5",
+    "expo-linear-gradient": "~57.0.2",
+    "expo-linking": "~57.0.10",
+    "expo-router": "~57.0.21",
+    "expo-splash-screen": "~57.0.9",
     "expo-status-bar": "~57.0.1",
-    "expo-system-ui": "~57.0.3",
-    "expo-web-browser": "~57.0.2",
+    "expo-system-ui": "~57.0.4",
+    "expo-web-browser": "~57.0.3",
     "jsbarcode": "^3.12.3",
     "react": "19.2.3",
     "react-dom": "19.2.3",
@@ -54,7 +55,7 @@
     "react-native-reanimated": "4.5.1",
     "react-native-safe-area-context": "~5.7.0",
     "react-native-screens": "~4.26.0",
-    "react-native-svg": "15.15.5",
+    "react-native-svg": "15.15.4",
     "react-native-web": "~0.21.0",
     "react-native-worklets": "0.10.1"
   },