mapples 0.2.0-beta.1 → 0.2.0-beta.12

package/templates/agent/mapples.md

@@ -0,0 +1,124 @@
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# Mapples conventions
+
+This app is linked to a **Mapples Creator** project (visual editor at creator.mapples.io).
+The link is the `mapples` CLI: screens, components and design tokens are TSX and TS files in
+this repo, and `npx -y mapples@__CLI_VERSION__ sync` pushes your edits to Creator and pulls Creator's edits back
+(two-way, 3-way merged). Every write to the project goes through `npx -y mapples@__CLI_VERSION__ sync` — there is no
+other write path from here. The `mapples` MCP server (`.mcp.json`) is **read-only**: use it to
+look at the project (style tokens, assets); never expect it to change anything.
+
+## Skills
+
+- `__DESIGN_COMMAND__` — build the whole app from a product brief (tokens → plan → screens → wiring → review).
+- `mapples-conventions` — how Mapples files are written (auto-applies when you edit them).
+- `mapples-sync` — running `npx -y mapples@__CLI_VERSION__ sync`, reading its JSON report, handling conflicts and exit codes.
+
+## Where things live
+
+| What | Where | Owner |
+| --- | --- | --- |
+| A screen in the navigation | `__ROUTES_DIR__/<segment>.tsx` (expo-router route file) | you + Creator (merged) |
+| A screen outside the navigation | `__PAGES_DIR__/<Name>.tsx` | you + Creator (merged) |
+| A navigator (stack / tabs / drawer) | `__ROUTES_DIR__/**/_layout.tsx` | **CLI** — regenerated every sync |
+| A reusable Creator component | `__COMPONENTS_DIR__/<Name>.tsx` | you + Creator (merged) |
+| Design tokens (theme, typography, sizing) | `mapples/theme.ts` | you + Creator (merged per key) |
+| Assets | `mapples/assets/` + `assetMap.ts` | **CLI** |
+| Project state (ids, base, head) | `.mapples/` | **CLI** — never edit |
+| Product brief, chosen style, plan | `mapples/design.md` | you |
+
+Read `.mapples/config.json` for the real `routesDir` / `pagesDir` / `componentsDir` of this app.
+
+## The rules that cannot be broken
+
+1. **`$sid` is opaque.** Every element Creator knows carries `$sid="nd_…"`. Never invent,
+   renumber, duplicate, move between elements or delete a `$sid`. New elements get **no**
+   `$sid` — `npx -y mapples@__CLI_VERSION__ sync` tags them and rewrites the file. Deleting an element deletes it in
+   Creator on the next sync (that is a real delete — say so when you do it).
+2. **Never touch CLI-owned files**: `_layout.tsx` under the routes dir, `assetMap.ts`, anything
+   in `.mapples/`, and `_depr_*` files. The one exception is the handshake for a new route
+   group: a `_layout.tsx` you create in a new `(group)/` directory must start with
+   `// GENERATED by Mapples` so the CLI adopts its navigator kind and owns it from then on.
+3. **Never delete `.mapples/head`, `.mapples/base/` or `.mapples/pages.json`** — they are the
+   sync base; losing them turns the next sync into a cold bootstrap.
+4. **Sync after every meaningful step** — `npx -y mapples@__CLI_VERSION__ sync --yes --json` — and read the report.
+   Exit 2 means conflicts (your file was kept as `_depr_<ts>_<name>.tsx.old`, the file was
+   regenerated from Creator: re-apply your intent onto the new file, never restore the old one).
+5. **A `_depr_` file is a signal, not a resource.** Diff it against the regenerated file, carry
+   the intent over, leave the `.old` file alone (the user deletes it).
+
+## Writing a screen
+
+```tsx
+// __ROUTES_DIR__/index.tsx — route files get a `// mapples-route:` marker from the CLI; keep it.
+import { ScrollView, Typography, View } from '@mapples/ui';
+import { Button, Card, SectionHeader } from '@mapples/components';
+import { Styler } from '@mapples/style';
+
+export default function Home() {
+  return (
+    <ScrollView styled={{ contentContainerStyle: styles.content }}>
+      <Typography text="Good morning, Alex" variant="Headline" styled={{ style: styles.title }} />
+      <SectionHeader title="Today" actionLabel="See all" />
+      <Card variant="elevated" styled={{ style: styles.card }}>
+        <Typography text="Two habits left" variant="Body" />
+      </Card>
+      <Button
+        label="Start a session"
+        variant="filled"
+        size="lg"
+        fullWidth
+        $actions={{ onPress: { type: 'mapples:navigate', staticData: { pageUuid: '<uuid>' } } }}
+      />
+    </ScrollView>
+  );
+}
+
+const styles = Styler.create({
+  content: { padding: 'sizing.screenPadding', gap: 'sizing.lg', paddingBottom: 32 },
+  title: { color: 'theme.text.primary' },
+  card: { gap: 'sizing.sm' },
+});
+```
+
+- Primitives (`View`, `ScrollView`, `Typography`, `Image`, `Icon`, `Pressable`, `TextInput`, …)
+  come from `@mapples/ui`; the themed library (`Button`, `Card`, `ListItem`, `InputField`, …)
+  from `@mapples/components` — the full table is in the `mapples-conventions` skill.
+- Every style is a literal object hoisted into `const styles = Styler.create({...})` and
+  referenced as `styled={{ style: styles.x }}` (slots: `style`, `styleTypography`, `styleSvg`,
+  `styleImage`, `contentContainerStyle`, `placeholderTextColor`). Creator reads the dictionary.
+- Token strings replace raw values: colors `'theme.primary.main'`, `'theme.text.secondary'`,
+  `'theme.background.card'`; spacing `'sizing.md'`, `'sizing.screenPadding'`, or `'*4'` (4 × base).
+  Raw hex only inside gradients (tokens do not resolve there).
+- Text is always `Typography` with `text` + `variant` (`Headline`, `Subtitle`, `Body`, `Caption`,
+  `Overline`, `Button`, `Link`, `Label`, `Code`). Never `Text`, never JSX children text.
+- Props are literals. An expression prop (`{count}`) is kept in code only and reported as
+  `NON_LITERAL_PROP`; Creator shows the last literal value.
+- Navigation from code: `$actions={{ onPress: { type: 'mapples:navigate', staticData: { pageUuid } } }}`
+  on the element's primary event. The target's `pageUuid` is the `uuid` field of
+  `.mapples/base/pages/<pageId>.json`; `<pageId>` is the key in `.mapples/pages.json` whose
+  `file` is the target route file. Add a `router.push('/<segment>')` `onPress` handler too so
+  the built app navigates.
+- Images: `<Image source="https://picsum.photos/seed/<topic>/<w>/<h>" contentFit="cover" />`
+  with an explicit width/height in `styled.style`. Creator asset references (`$refs`) are
+  Creator-side; do not invent them.
+
+## Design tokens
+
+`mapples/theme.ts` exports three literal objects — `theme`, `typography`, `sizing` — with the
+exact shape documented in `__SKILLS_DIR__/mapples-design/reference/design-tokens.md`. Creating
+or editing the file and syncing pushes the tokens to Creator (missing file + empty project = no-op).
+
+## The agent lease
+
+Creator shows "__AGENT_LABEL__ is working" and locks its own chat while you hold the project's
+lease. You do not manage it for ordinary requests: this app's hooks take the lease as soon as
+the user sends a prompt and release it when you finish responding, even when you change
+nothing. Do not call `agent start` or `agent stop` yourself for a normal request.
+
+The first thing `__DESIGN_COMMAND__` does — before syncing or asking the user anything — is
+`npx -y mapples@__CLI_VERSION__ agent start`, which holds a lease on the project so Creator shows
+"__AGENT_LABEL__ is working" and locks its own chat for the whole run, questions included. `npx -y mapples@__CLI_VERSION__ agent step` reports progress;
+`npx -y mapples@__CLI_VERSION__ agent stop` releases. `.mapples/agent.json` exists while the lease is held and labels
+every sync commit "__AGENT_LABEL__: <step>". Exit codes: `3` = the lease is gone (Creator
+disconnected you or it expired — stop and tell the user), `4` = another agent holds the project.

package/templates/agent/skills/mapples-conventions/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: mapples-conventions
+description: How Mapples-managed files are written — file layout, $sid rules, $actions/$data/$refs, the @mapples/ui vs @mapples/components import table, token strings and Styler dictionaries. Use whenever editing a route file, mapples/pages, mapples/components or mapples/theme.ts in a Mapples-linked Expo app.
+---
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# Mapples conventions
+
+Read `__CONVENTIONS_PATH__` first (the summary). This skill is the reference.
+
+## File layout
+
+| File | Role | Editable |
+| --- | --- | --- |
+| `__ROUTES_DIR__/<segment>.tsx`, `__ROUTES_DIR__/(group)/<segment>.tsx` | a screen that is in the navigation; `index.tsx` is the section's first screen | yes — merged with Creator |
+| `__ROUTES_DIR__/**/_layout.tsx` | the navigator (Stack/Tabs/Drawer); regenerated from Creator's navigation on every sync | **no** (handshake only, below) |
+| `__PAGES_DIR__/<Name>.tsx` | a screen not (yet) in the navigation; moves into the routes dir when placed | yes |
+| `__COMPONENTS_DIR__/<Name>.tsx` | a reusable Creator component; instances are `import X from '…/<Name>'` + `<X styled />` | yes |
+| `mapples/theme.ts` | design tokens (`theme`, `typography`, `sizing`) | yes — merged per key |
+| `mapples/assets/`, `mapples/assetMap.ts` | Creator assets | **no** |
+| `mapples/sid.d.ts` | types for the `$sid`/`$refs`/`$data`/`$actions`/`$fallback` attributes | no |
+| `.mapples/` | config, secret, head, base, pages.json, components.json, outbox, agent.json | **no** |
+| `_depr_<ts>_<name>.tsx.old` | your version of a file the CLI had to regenerate | read, never restore |
+
+The route marker `// mapples-route: <id> — “<Name>”` on line 1 of a route file is the route's
+identity: keep it verbatim. Renaming the file renames the route in Creator.
+
+## `$sid`
+
+- `$sid="nd_…"` is the canvas node id. Opaque: never parse beyond the prefix, never invent,
+  never renumber, never copy to another element, never reuse a deleted one.
+- New elements carry **no** `$sid`. `npx -y mapples@__CLI_VERSION__ sync` tags them (report: `tagged N new element(s)`)
+  and rewrites the file with the ids — re-read the file after a sync before editing again.
+- Wrapping an existing element (moving it inside a new `View`) keeps its `$sid`; the sync sees a
+  move. Removing an element with a `$sid` deletes it in Creator.
+- `$fallback={{ w, h }}` sits on `Custom` nodes (a non-Mapples component the canvas cannot
+  render); leave it as the CLI wrote it.
+
+## Transient attributes
+
+| Attribute | Shape | Meaning |
+| --- | --- | --- |
+| `$actions` | `{ onPress: { type: 'mapples:navigate', staticData: { pageUuid: '<uuid>' } } }` | Creator prototype connection on that event. Other action types (`mapples:setState`, `mapples:goBack`, `mapples:switchTab`) exist; navigate is the one you write. |
+| `$data` | `{ visible: { key: 'vars.sheetOpen', active: true } }` | a data binding of a prop to a project variable — only when the project already has the variable |
+| `$refs` | `{ source: 'ref(image:<uuid>)' }` | a Creator asset reference — Creator-side; never invent one |
+
+`pageUuid` lookup: `.mapples/pages.json` maps `pageId → { file, name, route, routeId }`; the
+uuid the action needs is the `uuid` field of `.mapples/base/pages/<pageId>.json`. Both are
+rewritten by every sync — read them fresh.
+
+## Imports
+
+`@mapples/ui` — primitives (the canvas' base element types):
+
+`View`, `Container`, `SafeAreaView`, `ScrollView`, `HorizontalScrollView`, `FlatList`,
+`GridTwoColumns`, `GridThreeColumns`, `GridFourColumns`, `GradientBackground`,
+`ImageBackgroundView`, `Typography`, `Text` (never on a screen — use Typography), `Image`,
+`Icon`, `Svg`, `Vector`, `Video`, `QRCode`, `BarCode`, `Pressable`, `IconButton`, `TextInput`,
+`Select`, `FormView`, `TextField`, `SubmitButton`, `Button` (themed like the library below, but
+imported from `@mapples/ui`).
+
+`@mapples/components` — the themed library (paints itself from the tokens; prefer it):
+
+| Group | Types |
+| --- | --- |
+| actions | `ButtonGroup`, `Fab`, `TextLink`, `BottomActionBar` (`Button` is an `@mapples/ui` import) |
+| input | `InputField`, `SelectField`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `NumberStepper`, `PinInput`, `SearchBar`, `ChatComposer`, `SegmentedControl`, `Rating`, `ChipGroup`, `Chip` |
+| content | `Card`, `MediaCard`, `List`, `ListItem`, `SectionHeader`, `Divider`, `Avatar`, `AvatarGroup`, `Badge`, `StatTile`, `Table`, `Timeline`, `ImageCarousel`, `MessageBubble`, `Accordion`, `Skeleton` |
+| navigation | `TopAppBar`, `BottomNavigationBar`, `Tabs`, `Breadcrumbs`, `Steps`, `PageControl` |
+| feedback | `ProgressBar`, `ProgressCircle`, `Spinner`, `Banner`, `Snackbar`, `EmptyState` |
+| overlays | `Dialog`, `BottomSheet`, `ActionSheet` |
+
+Anything else you import (a third-party or hand-written component) becomes an opaque `Custom`
+node on the canvas with a `$fallback` size — allowed, but Creator cannot design inside it.
+
+`Styler` comes from `@mapples/style`; `router` from `expo-router`.
+
+## Styling
+
+```tsx
+<View styled={{ style: styles.row }}>
+  <Icon iconName="checkmark-circle" styled={{ styleSvg: styles.icon }} />
+  <Typography text="Done" variant="Label" styled={{ styleTypography: styles.done }} />
+</View>
+
+const styles = Styler.create({
+  row: { flexDirection: 'row', alignItems: 'center', gap: 'sizing.sm' },
+  icon: { width: 20, height: 20, color: 'theme.system.success' },
+  done: { color: 'theme.text.secondary' },
+});
+```
+
+- `styled={{ style }}` is the element's own box; `styleTypography` the text of a control
+  (Button label, ListItem title); `styleSvg` an Icon's glyph (`color`, `width`, `height`);
+  `styleImage` the picture inside an Image; `contentContainerStyle` the scrolling content of a
+  ScrollView/FlatList/HorizontalScrollView; `placeholderTextColor` a TextInput's placeholder.
+- One `Styler.create` dictionary per file, below the component; keys say what the element shows
+  and is (`signInText`, `heroImage`, `listContent`). A `StyleSheet.create` dictionary is also
+  read, but write `Styler.create`.
+- A style may be a single dictionary reference (`styles.card`) or a literal; never an array,
+  never a computed expression (Creator cannot read it → `NON_LITERAL_PROP`).
+- Token strings: colors `'theme.<group>.<key>'` (`theme.primary.main`, `theme.primary.contrast`,
+  `theme.background.primary`, `theme.background.card`, `theme.text.primary|secondary|tertiary`,
+  `theme.neutral.n200`, `theme.system.error`); spacing `'sizing.<key>'` (`xs sm md lg xl
+  screenPadding gap radius radiusLarge control card icon`) or `'*N'` (N × base). Gradients take
+  literal hex/rgba only.
+- `boxShadow` is an object `{ x, y, radius, color }`, never a CSS string.
+- Library components set their own defaults; change their look through `variant`, `size`,
+  `tone` props and the slots — never rebuild one from Views.
+
+## Layouts (`_layout.tsx`)
+
+The CLI generates every layout from Creator's navigation document. Do not edit or style them
+(header/tab-bar options are set in Creator). To add a **new** section, create the directory
+with a layout whose first line is `// GENERATED by Mapples`:
+
+```tsx
+// GENERATED by Mapples — this layout is owned by the CLI and regenerated from the navigation document.
+import { Tabs } from 'expo-router';
+
+export default function MainLayout() {
+  return <Tabs />;
+}
+```
+
+`npx -y mapples@__CLI_VERSION__ sync --yes` then adopts the directory as a tabs navigator (`<Stack>` → stack,
+`<Drawer>` from `expo-router/drawer` → drawer; no layout → stack) and regenerates the file. A
+layout **without** the header is treated as yours and deprecated on the first sync.
+
+## What not to do
+
+- Do not run `npx -y mapples@__CLI_VERSION__ init`, `npx -y mapples@__CLI_VERSION__ create`, or edit `.mapples/config.json`.
+- Do not restore a `_depr_` file over the regenerated one.
+- Do not hand-write `$sid`s, `$refs`, or navigator options.
+- Do not put JSX children text inside `Typography` (`text` prop only), and do not use `Text`.
+- Do not spread props or map arrays into JSX inside a managed element tree — Creator reads
+  literal trees; put dynamic lists behind a `FlatList`/`List` with literal `items` where
+  possible, or accept the `NON_LITERAL_PROP` note.

package/templates/agent/skills/mapples-design/SKILL.md

@@ -0,0 +1,235 @@
+---
+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 `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 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 `npx -y mapples@__CLI_VERSION__ sync --yes --json`, which pushes it to Creator where the user watches it land.
+
+## First: take the project's lease
+
+Do this **before anything else** — before reading references, syncing, or asking the user a
+single question. While you hold the lease Creator locks its own AI chat and refuses Save, so
+nobody changes the project from the browser while you are still asking about the brief.
+
+1. `.mapples/config.json` must exist (the app is linked). If not: stop and ask the user to run
+   `npx -y mapples@__CLI_VERSION__ init --secret <key> --agent __AGENT_FLAG__` — never run it yourself.
+2. Take the lease, pre-declaring the fixed step titles:
+
+   ```bash
+   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: another agent session holds the project. That is the only question you may
+   ask before holding the lease — whether to take over (re-run with `--takeover`, which
+   disconnects the other session). Never take over silently; if the user says no, stop.
+3. Mark the brief running at once — the brief questions happen inside this step:
+
+   ```bash
+   npx -y mapples@__CLI_VERSION__ agent step --index 0 --title "Brief" --status running --json
+   ```
+
+Only then:
+
+4. Read `__CONVENTIONS_PATH__` and the `mapples-conventions` and `mapples-sync` skills.
+5. `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.
+6. 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.
+
+If the user stops the run at any point — including while you are still asking questions —
+release the lease before you reply (`agent stop --status failed --error "stopped by the user"`).
+
+Reference material for this skill lives next to it:
+
+- `reference/style-guides.md` — art directions and style guides (phase 1)
+- `reference/design-tokens.md` — the `mapples/theme.ts` contract and template (phase 2)
+- `reference/plan.md` — scopes and the implementation plan (phase 3)
+- `reference/layout-contract.md` — the rules every screen obeys (phases 5…)
+- `reference/component-library.md` — what to reach for, by need
+- `reference/lint-checklist.md` — the review pass (phase N)
+- `reference/playbooks/<name>.md` — screen-kind playbooks, loaded per screen
+
+## Steps and the lease
+
+The lease taken above covers the whole run. Steps have a **fixed index convention** shared
+with Creator's progress log:
+
+```
+0 Brief · 1 Style guides · 2 Design tokens · 3 Plan · 4 Scaffold navigation & screens ·
+5…N-2 one per plan step ("Build the Home screen", …) · N-1 Wiring · N Review
+```
+
+After the plan exists (phase 3), the remaining titles are 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
+npx -y mapples@__CLI_VERSION__ agent step --index <i> --title "<title>" --status running --json
+# … the work …
+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
+lease expired). Stop immediately, do not sync again, and tell the user what was finished.
+
+Always end the run — success or not:
+
+```bash
+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.
+
+## Phase 0 — Brief and scope
+
+Step 0 is already running (you marked it right after taking the lease).
+
+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 (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`:
+
+```md
+# <App name>
+## Brief
+<the brief, cleaned up, 3–8 lines: audience, core value, mood, must-haves, non-goals>
+## Scope
+<single|minimal|basic|advanced> — <one line why>
+```
+
+Report the step done with the scope in `--detail`.
+
+## Phase 1 — Style guides
+
+Follow `reference/style-guides.md`: propose 3 art directions **for this product**, then 3
+compact style guides. Show them to the user as a table (name, direction, palette swatches as
+hex, headline/body fonts, radius, elevation language, one don't) and ask which one — or accept
+the user's pick from the brief. Append the chosen guide to `design.md` under `## Style guide`.
+
+## Phase 2 — Design tokens
+
+Follow `reference/design-tokens.md` exactly: write `mapples/theme.ts` (create it — a missing
+file and an empty project is a no-op, so the file is what pushes the tokens). Then
+
+```bash
+npx -y mapples@__CLI_VERSION__ sync --yes --json
+```
+
+Assert: `exitCode` 0, `pushedOps` ≥ 3 (Theme, Typography, Sizing updates) and no
+`conflicts`. If `pushedOps` is 0, the file did not parse as three literal exports — fix the
+file, do not move on. Record the token summary (primary, background, fonts, radius) in
+`design.md` under `## Tokens`.
+
+## Phase 3 — Plan
+
+Follow `reference/plan.md`: decisions, navigation (sections → screens), entry screen, ordered
+build steps. Append it to `design.md` under `## Plan` **and** declare the remaining steps:
+
+```bash
+npx -y mapples@__CLI_VERSION__ agent step --index 5 --title "<plan step 1 title>" --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.
+
+## Phase 4 — Scaffold navigation and screens
+
+Read `.mapples/config.json` for `routesDir` (`__ROUTES_DIR__` here). Then, for the plan's
+navigation:
+
+- The root layout already exists and is CLI-owned — leave it.
+- One directory per section: `<routesDir>/(<section-slug>)/` with a `_layout.tsx` whose first
+  line is `// GENERATED by Mapples` and whose body renders `<Stack />`, `<Tabs />` (from
+  `expo-router`) or `<Drawer />` (from `expo-router/drawer`) per the section's type. This header
+  is the handshake: the CLI adopts the navigator kind from it and owns the file from then on.
+- One **minimal** route file per screen: `index.tsx` for the section's first screen, `<slug>.tsx`
+  for the rest — a `View` with one `Typography` (`variant="Headline"`, the screen name). Real
+  content comes per screen later; the scaffold only mints ids. When the plan has a single
+  section, put its files at the root of the routes dir instead of a group.
+- Do not write to `.mapples/`, do not touch the root `_layout.tsx`, do not create pages under
+  `pagesDir`.
+
+```bash
+npx -y mapples@__CLI_VERSION__ sync --yes --json
+```
+
+Assert no conflicts, then read `.mapples/pages.json`: every scaffolded file must be a value's
+`file` with a `routeId`. Note the `pageId` per screen; the `uuid` for `$actions` is in
+`.mapples/base/pages/<pageId>.json`. Screens now exist as empty pages in Creator. Re-read each
+route file — the CLI added the `// mapples-route:` marker and `$sid`s.
+
+Navigator and route options (headers, tab icons, initial route, modal presentation) are set in
+Creator, not from code, in this version: describe the intended chrome in `design.md` under
+`## Navigation chrome` so the user can apply it.
+
+## Phases 5…N-2 — one screen step at a time
+
+For each plan step, in order:
+
+1. `agent step … --status running`.
+2. Load the matching playbook(s) from `reference/playbooks/` (read the file; once per run):
+   `onboarding-flow`, `home-dashboard`, `list-and-detail`, `forms-and-auth`, `empty-states`,
+   `stats-and-progress`, `settings-profile`, `navigation-chrome`; `visual-hierarchy` and
+   `microcopy` with the first screen step.
+3. Re-read the route file. Write the **whole screen** in one edit: keep the marker line, keep
+   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. `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`
+   mentally, fix, sync again if you changed anything.
+6. `agent step … --status done --detail "<screen>: <what it shows>"`.
+
+Two screens in one plan step: do them one after the other inside the step, syncing after each.
+
+## Phase N-1 — Wiring
+
+Load `playbooks/screen-flow-wiring.md`. For every navigation the plan names, add to the source
+element's primary event both the Creator connection and the runtime handler:
+
+```tsx
+<Button
+  label="Get started"
+  variant="filled"
+  size="lg"
+  fullWidth
+  onPress={() => router.push('/(main)')}
+  $actions={{ onPress: { type: 'mapples:navigate', staticData: { pageUuid: '<uuid from base>' } } }}
+/>
+```
+
+(`import { router } from 'expo-router'`.) Rows and cards use their own `onPress`. Walk the golden
+path from the entry screen; every screen reachable, every flow with an exit. Sync; the report's
+`pushedOps` must cover every action you added.
+
+## Phase N — Review
+
+Load `reference/lint-checklist.md`. For every screen: re-read the file, check each item, fix.
+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
+`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.
+
+## Working style
+
+- One screen, one edit — never element by element across many edits (each sync tags ids; many
+  partial syncs mean many rewrites).
+- After every sync, re-read before editing. Never keep a stale copy of a file in your head.
+- Prefer fewer screens fully designed over more screens sketched.
+- Ask only when a product decision is genuinely ambiguous; otherwise decide, state it in
+  `design.md`, move on.
+- Never emoji. Never lorem ipsum. Never `Text`. Never a hand-written `$sid`.

package/templates/agent/skills/mapples-design/reference/component-library.md

@@ -0,0 +1,128 @@
+<!-- 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 `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).
+
+## `@mapples/ui` — primitives
+
+| Type | Use | Notes |
+| --- | --- | --- |
+| `Container` | the screen root or a flex: 1 region | full-size column by default |
+| `View` | any column/row | width 100% in a column; content-sized in a row |
+| `SafeAreaView` | root that respects the notch | or paddingTop ≥ 48 on the root |
+| `ScrollView` | vertical scrolling content | spacing in `styled.contentContainerStyle` |
+| `HorizontalScrollView` | a rail of cards | full-bleed; `contentContainerStyle: { gap: 12, paddingHorizontal: 20 }` |
+| `FlatList` | long uniform lists | prefer `List` + `ListItem` for designed rows |
+| `GridTwoColumns` / `GridThreeColumns` / `GridFourColumns` | tile grids | children tile automatically |
+| `GradientBackground` | the one gradient accent per screen | `gradient` prop with literal hex stops |
+| `ImageBackgroundView` | photo with content over it | `source` + `overflow: 'hidden'` + a scrim child |
+| `Typography` | every piece of text | `text` + `variant` (Headline, Subtitle, Body, Caption, Overline, Button, Link, Label, Code) |
+| `Text` | never on a screen | bypasses the type scale |
+| `Image` | a picture | `source` (picsum URL), `contentFit="cover"`, explicit width/height |
+| `Icon` | a glyph from the project icon family | `iconName`; color/size in `styled.styleSvg` |
+| `IconButton` | icon-only tap target | `iconName`, `accessibilityLabel` (required), `badgeCount` |
+| `Pressable` | a custom tappable region | only when no library control fits |
+| `TextInput` | raw input | in forms use `InputField` instead |
+| `Select` | raw select | in forms use `SelectField` instead |
+| `Svg` / `Vector` / `Video` / `QRCode` / `BarCode` | media specials | as needed |
+| `FormView` / `TextField` / `SubmitButton` | form primitives | the library's `InputField`/`Button` are the designed versions |
+
+## `@mapples/components` — the themed library
+
+Library types paint themselves from the tokens; change their look through `variant`, `size`
+and `tone` props and the style slots — never rebuild one from Views. Array props (`options`,
+`items`, `columns`) are literal arrays.
+
+### actions
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `Button` | `label`, `variant` filled\|outlined\|text\|tonal, `size` sm\|md\|lg, `fullWidth`, `leadingIconName`, `tone` | the primary action (filled lg fullWidth), secondary actions (outlined/text) — **imported from `@mapples/ui`**, not `@mapples/components` |
+| `ButtonGroup` | `options` [{label, value}], `value` | a segmented pair of actions |
+| `Fab` | `iconName`, `accessibilityLabel`, `label`, `extended` | one floating primary action |
+| `TextLink` | `label`, `tone`, `underline` | Skip, Forgot password?, Sign in |
+| `BottomActionBar` | `sticky`; children | the sticky bar holding price + CTA on detail/checkout screens |
+
+### input
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `InputField` | `label`, `placeholder`, `helperText`, `errorText`, `leadingIconName`, `keyboardType`, `autoCapitalize`, `secureTextEntry`, `showPasswordToggle`, `variant` outlined\|filled | every text field in a form |
+| `SelectField` | `label`, `options`, `placeholder`, `value` | dropdowns |
+| `Checkbox` | `label`, `value` | yes/no that lists |
+| `RadioGroup` | `options`, `value` | one exclusive choice |
+| `Switch` | `label`, `value` | a toggle |
+| `Slider` | `min`, `max`, `value`, `showValue` | a range |
+| `NumberStepper` | `min`, `max`, `value` | quantity |
+| `PinInput` | `length` | one-time codes |
+| `SearchBar` | `placeholder`, `value` | search (a filled pill by default) |
+| `ChatComposer` | `placeholder`, `leadingIconName` | the chat input pinned to the bottom |
+| `SegmentedControl` | `options`, `value` | switching a view mode |
+| `Rating` | `value`, `max`, `readOnly` | stars |
+| `ChipGroup` | `options` [{label, value, iconName?}], `value`, `variant` filter\|choice, `scrollable` | filters and tags |
+| `Chip` | `label`, `variant` assist\|filter\|suggestion, `selected` | a single tag (content-sized; inside a row) |
+
+### content
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `Card` | `variant` elevated\|filled\|outlined; children | any surface that groups content |
+| `MediaCard` | `source`, `title`, `subtitle`, `meta`, `aspectRatio` | a photo-topped tile (rails, grids) |
+| `List` | `variant` plain\|inset\|card, `header`; `ListItem` children | rows — the List draws dividers and the surface |
+| `ListItem` | `title`, `subtitle`, `leading` icon\|avatar\|image\|none, `leadingIconName`, `leadingName` (the name whose initials fill a `leading="avatar"` with no `source`), `source`, `trailing` chevron\|text\|switch\|checkbox\|none, `trailingText`, `tone` | one row |
+| `SectionHeader` | `title`, `actionLabel` | "Popular · See all" |
+| `Divider` | `inset` | a hairline between groups |
+| `Avatar` | `name` or `source`, `size` sm\|md\|lg\|xl, `badgeCount` | a person |
+| `AvatarGroup` | `items` [{name, source}], `max` | several people |
+| `Badge` | `label` or `count`, `variant` text\|dot\|count, `tone` | a status pill or a count |
+| `StatTile` | `label`, `value`, `unit`, `caption`, `trend`, `trendValue`, `iconName`, `variant` | a KPI |
+| `Table` | `columns` [{key, title}], `rows` | tabular data |
+| `Timeline` | `items` [{title, subtitle, time, status}] | a sequence of events |
+| `ImageCarousel` | `items` [{source, caption}] | swipeable photos |
+| `MessageBubble` | `text`, `direction` in\|out, `time`, `status` | a chat message |
+| `Accordion` | `items` [{title, content}] | FAQ / expandable rows |
+| `Skeleton` | `variant` text\|rect\|circle, `width`, `height` | a loading placeholder |
+
+### navigation (in-content)
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `TopAppBar` | `title`, `showBack`, `actions` [{iconName, value}], `variant` small\|large | an in-content header ONLY when the stack header is hidden |
+| `BottomNavigationBar` | `items` [{label, iconName, value}], `value` | a single-screen demo of a tab shell — real tabs are a navigator |
+| `Tabs` | `items` [{label, value}], `value` | switching panels inside ONE screen |
+| `Breadcrumbs` | `items` [{label, value}], `separator`, `maxItems` | a path |
+| `Steps` | `items` [{label}], `current` | a multi-step progress |
+| `PageControl` | `count`, `value`, `variant` dots\|bars | onboarding page dots |
+
+### feedback
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `ProgressBar` | `value`, `max`, `showLabel` | a goal or an upload |
+| `ProgressCircle` | `value`, `size`, `showLabel` | a ring |
+| `Spinner` | `size` | loading |
+| `Banner` | `title`, `message`, `tone`, `actionLabel` | an inline notice |
+| `Snackbar` | `message`, `actionLabel`, `visible` | a toast (last in the root, `visible={false}` unless bound) |
+| `EmptyState` | `iconName` or `imageSource`, `title`, `message`, `actionLabel`, `secondaryActionLabel`, `tone` | nothing to show |
+
+### overlays (last in the page root; `visible={false}` unless bound to a variable)
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `Dialog` | `title`, `message`, `primaryActionLabel`, `secondaryActionLabel`, `tone`, `visible` | a confirmation |
+| `BottomSheet` | `title`, `visible`; children | a picker or a quick detail |
+| `ActionSheet` | `options` [{label, value, iconName?, destructive?}], `visible` | a list of actions |
+
+## Style slots
+
+`styled={{ style, styleTypography, styleSvg, styleImage, contentContainerStyle, placeholderTextColor }}` —
+`style` is the element's box; `styleTypography` its text (Button label, ListItem title, StatTile
+value); `styleSvg` its glyph; `contentContainerStyle` the scrolling content. Library components
+expose the same slots; use them for one-off tweaks (a card's `gap`, a rail's padding) and
+props for everything the component already knows how to do.
+
+> Prop names above follow the Creator's component digest; when unsure, keep to the ones listed
+> here — an unknown prop is ignored (and reported by the Creator lint as `unknown-prop`).