@acms-subir/core 0.3.3-next.20260929113209 → 0.3.3

package/docs/sections.md

@@ -0,0 +1,203 @@
+# Editable sections: code the look, leave the content editable
+
+This is the guide for agents (and people) building pages for an ACMS site. The rule is simple:
+
+> **Code decides how things look. Section fields decide what the owner can change.**
+
+The owner will update service times, events, prices, people and text long after you're gone, in Design → Pages, without touching code. So anything that might change must be a **field**, never hardcoded in the component.
+
+## The three layers
+
+| Layer | Lives in | Owned by |
+| --- | --- | --- |
+| Code | `src/themes/<theme>/sections/*.astro` | you (the agent). Rewrite freely |
+| Schema | `theme.json → sections.<type>.fields` | the contract between both |
+| Data | the site database (Design → Pages) | the owner. Never overwrite it |
+
+Changing code needs a build and deploy. Changing data never does.
+
+## Workflow
+
+```sh
+acms inspect --json                          # project, themes, capabilities
+acms docs sections                           # this guide
+acms section library                         # ready-made sections to start from
+acms section add service-times --theme church
+acms section add upcoming-events --theme church
+acms section new visit-banner --theme church # blank scaffold
+# edit theme.json fields + the .astro markup
+acms check --build                           # validate, refresh section-types.d.ts, compile
+```
+
+With a mobile app beside the site (`acms add mobile`), library sections render
+natively in the app out of the box; `acms section add <name> --theme <t> --native`
+copies an editable native version into `mobile/sections/`, `acms section new`
+also writes a typed native stub there, and `acms check` lists sections the app
+can only show as a web view. Keep a section's native version in step with its
+fields and variants.
+
+Then give the page starting content in one of two ways:
+
+1. **A preset** in `theme.json` (preferred for code-first work). The owner sees "Start from Church home" in Design → Pages and gets a copy they can edit:
+
+   ```json
+   "presets": {
+     "church-home": {
+       "name": "Church home",
+       "description": "Hero, service times, next events, visit info",
+       "sections": [
+         { "type": "hero-banner", "variant": "cover", "data": { "heading": "A church for the whole city." } },
+         { "type": "service-times", "data": { "services": [ { "title": "Sunday Worship", "day": "Sunday", "time": "10:00" } ] } },
+         { "type": "upcoming-events", "data": { "events": { "calendar": "youth", "limit": 3 } } }
+       ]
+     }
+   }
+   ```
+
+2. **MCP / agent API** when you're connected to a live site: `list_section_types`, `get_page_layout`, `set_page_layout`, `update_section_data`. Everything stages into the design draft. The owner publishes.
+
+## Defining a section
+
+```json
+"sections": {
+  "service-times": {
+    "name": "Service times",
+    "description": "Weekly gatherings with day, time and a short note.",
+    "version": 1,
+    "component": "sections/ServiceTimes.astro",
+    "variants": ["cards", "strip"],
+    "fields": {
+      "heading":  { "label": "Heading", "type": "text", "default": "Join us this week" },
+      "services": { "label": "Services", "type": "list", "itemLabel": "title", "max": 12, "fields": {
+        "title":    { "label": "Name", "type": "text" },
+        "day":      { "label": "Day", "type": "select", "options": ["Sunday", "Wednesday"], "default": "Sunday" },
+        "time":     { "label": "Time", "type": "time", "default": "10:00" },
+        "streamed": { "label": "Streamed online", "type": "toggle" }
+      } }
+    }
+  }
+}
+```
+
+Field keys are camelCase. Every field takes `label`, optional `help` (one line shown under the input) and `default`.
+
+### Field types
+
+| Type | Stored value | Component receives | Use for |
+| --- | --- | --- | --- |
+| `text` | string | string | headings, names, short lines |
+| `textarea` | string | string (keep newlines with `white-space: pre-line`) | paragraphs, addresses |
+| `richtext` | HTML | **sanitized** HTML: render with `set:html` | answers, notes with links/lists |
+| `image` | URL | safe URL or `''` | photos (owner picks from the media library) |
+| `url` | URL | safe URL or `''` | bare links |
+| `link` | `{ label, href, ref? }` | `LinkValue { label, href, external }` | buttons. `ref` follows a page/post/event/booking if its address changes |
+| `select` | string | one of `options` | small fixed choices |
+| `number` | number | number | counts |
+| `toggle` | boolean | boolean | show/hide flags |
+| `date` | `YYYY-MM-DD` | string. Format with `formatDay()` | one-off dates |
+| `time` | `HH:MM` | string. Format with `formatTime()` | times of day |
+| `list` | array of rows | array of rows (sub-fields resolved the same way) | repeating things: services, people, plans, photos |
+| `source` | `{ calendar?, collection?, tag?, resource?, limit }` | fresh `EventItem[]` / `PostItem[]` / `BookingItem[]` | content that must stay current on its own |
+
+`list` options: `fields` (scalar sub-fields only; a list can't contain a list or source), `itemLabel` (the sub-field shown on collapsed rows), `min`, `max` (default 50).
+
+`source` options: `source: "events" | "posts" | "bookings"`. The owner picks which calendar / collection + tag / resource, and how many (1–24).
+
+**When to use `source` instead of `list`:** if the thing already exists elsewhere in ACMS (calendar events, blog posts, booking links), link to it with `source`. Then the homepage updates itself when the calendar changes. Use a `list` only for content that lives nowhere else.
+
+### More schema options
+
+| Where | Option | What it does |
+| --- | --- | --- |
+| section | `category` | Groups it in the "Add a section" picker ("Intro", "Events & times", "People"…) |
+| section | `example` | Sample data: renders the picker thumbnail and fills **empty** fields in the admin preview (never saved, never shown to visitors). Always provide one |
+| section | `limit` | At most this many per page (e.g. `1` for a hero) |
+| section | `presets` | Extra ready-filled picker entries: `[{ "name": "Service times: holiday", "variant": "strip", "data": {…} }]` |
+| field | `visibleIf` | Show only when a sibling matches: `{ "field": "style", "equals": "image" }` (also `notEquals`, `in`, or no operator = "is filled in"). Works inside list rows against the row |
+| field | `required`, `maxLength` | Enforced in the editor (live counter), before publishing, and by `acms check` for examples/presets |
+| field | `aiHint` | Guidance for "Help me write" on that field ("friendly, under 12 words") |
+| field | `locked` | Only owners can change it; editors see it read-only |
+
+Owners can also lock a whole section, and schedule any section with **Show from / until** (site timezone). Image fields get a **focal point**: the component receives `<key>Focus` (e.g. `data.imageFocus`, or `row.photoFocus` in lists) ready for `style={`object-position:${data.imageFocus}`}`, or for `background-position`. Use it on every cropped image.
+
+## Writing the component
+
+```astro
+---
+import type { SectionProps } from '@acms-subir/core/theme';
+import { formatTime } from '@acms-subir/core/theme';
+import type { ServiceTimesData } from '../section-types';   // generated by acms check / acms theme types
+const { data, variant, settings } = Astro.props as SectionProps<ServiceTimesData>;
+---
+<div class:list={['times', `is-${variant}`]}>
+  <h2>{data.heading}</h2>
+  <ul>
+    {data.services.filter((s) => s.title).map((s) => (
+      <li><b>{s.title}</b> {s.day} · {formatTime(s.time, settings.locale)}</li>
+    ))}
+  </ul>
+</div>
+<style>/* scoped; anything goes */</style>
+```
+
+The component receives `data` (resolved values, defaults filled in), `variant`, `settings` and `page`. The core wraps it in `<section class="acms-section section-<type> variant-<variant>">`.
+
+Rules:
+
+- **Render empty values gracefully.** Every field can be empty; lists can have zero rows; sources can return nothing. Skip empty rows (`filter((s) => s.title)`), and show an "empty" line for sources.
+- **Only `richtext` is HTML.** Never `set:html` any other field.
+- Style with theme tokens (`--accent`, `--ink`, `--muted`, `--panel`, `--soft`, `--line`, `--bg`, `--r`, `--r-sm`, `--r-lg`, `--font-heading`, `--font-body`) so the section follows the theme and dark mode. Reuse `.w-btn primary|outline` for buttons.
+- No data fetching in components. Anything dynamic comes through a `source` field.
+- Text the owner might reword (headings, button labels, "See all" links, empty-state lines) is a field with a sensible `default`.
+
+## Responsive: phone *and* desktop, every time
+
+A section that only works at one width is broken. Design for both ends, not "mobile, stretched":
+
+- **The frame is wide.** Section pages break out of the article column to the theme's `--wide-width` (about 1080px, the same frame as the header). Use that room on desktop: multi-column grids, side-by-side copy and media, split layouts. A single narrow column floating on a wide screen is a bug. Cap only *prose* line length (`max-width: 60ch` on paragraphs), never the whole section.
+- **Grids adapt.** Prefer `repeat(auto-fit, minmax(min(100%, 15rem), 1fr))`, which fills desktop and stacks on phones with no media query. Fixed column counts (`repeat(3, …)`) need `@media` steps down to 2 and then 1.
+- **Split layouts stack.** Two-column (text | image, info | hours) collapses to one column below roughly 700px; decide what comes first on phones.
+- **No fixed widths.** No `width: 600px`. Use `%`, `fr`, `min()`, `clamp()` and `max-width`. Nothing may cause sideways scrolling at 360px.
+- **Type and spacing scale.** Headings and padding use `clamp()` so they're big on desktop and sensible on phones.
+- **Touch targets** are at least 44px tall on phones.
+
+Check every section at **390px (phone), 768px (tablet) and 1280–1440px (desktop)**. The Design screen's preview has all three (Mobile · Tablet · Desktop), and `acms theme dev` does too. `acms check` flags common desktop and phone traps (fixed pixel widths, fixed column counts without a breakpoint), but only looking at it proves it.
+
+## Other languages
+
+With `acms({ i18n: { locales: ['en', 'es'] } })`, a page keeps **one** layout. Each section stores its facts once (times, dates, photos, links, linked events) and, per extra language, only its **words**. `/es` renders the same sections with the Spanish words, falling back to English field by field. Owners translate in Design → Pages → Español, and AI drafts the Spanish automatically whenever the English changes (marked "AI draft" until someone reviews it).
+
+What translates by default: `text`, `textarea`, `richtext`, and the label of a `link`. Everything else is shared. Adjust per field:
+
+- `"translatable": false` on a text field that isn't words: phone numbers, emails, prices, street addresses, names of people.
+- `"translatable": true` on a `select` whose options are words (e.g. weekday names).
+
+Components need nothing special: they receive the data already in the visitor's language, and `settings.locale` is set to it, so format dates and times with it (`formatTime(s.time, settings.locale)`) and they come out right (`19:30`, `sáb, 3 oct`). Fixed words written into a component (a "See all" label) stay in the main language. Make them fields if they must translate.
+
+List rows get a hidden `_id` so their translations follow them when reordered. Keep `_id` when you rewrite rows in migrations.
+
+## Changing a section later without losing content
+
+Saved data is keyed by field key. So:
+
+- **Adding a field** is always safe. Give it a `default`.
+- **Removing a field** is safe. Its saved value is kept (the owner sees "kept in case the theme brings it back").
+- **Changing a textarea of `a | b` lines into a list** is automatic: stored strings become rows, cells map to sub-fields in order.
+- **Renaming or reshaping a field:** bump the section's `version` and add `migrations/<type>.mjs`:
+
+  ```js
+  // src/themes/church/migrations/service-times.mjs
+  export default function migrate(data, fromVersion) {
+    if (fromVersion < 2) data.services = (data.services ?? []).map(({ name, ...row }) => ({ ...row, title: name }));
+    return data;
+  }
+  ```
+
+  The site renders old data through the migration immediately. The owner's "Upgrade sections" button saves the upgraded copy. Without a migration, a version bump hides the section until one exists.
+
+## Check before you finish
+
+- `acms check --build` passes. It validates fields, list labels, select defaults, presets and migrations, and compiles.
+- Every piece of changeable content is a field; nothing the owner would edit is hardcoded.
+- Each section looks right with empty fields, one row and many rows, in light and dark, at **phone (390px), tablet (768px) and desktop (1280px+)** widths. On desktop it uses the wide frame (no lonely narrow column); on phones nothing scrolls sideways.
+- In Design → Pages (or the preview's **Edit** chips), every section opens a form that makes sense to a non-developer: clear labels, `help` where needed, `itemLabel` set on lists.

package/docs/theme-authoring.md

@@ -56,7 +56,7 @@ Custom definitions live in `theme.json`:
 }
 ```
 
-The component receives SectionProps. Supported field kinds: text, textarea, image, url, select (options required), number. Instances have stable id/type/version/variant/hidden/data fields. A page layout has mode and sections, persisted by page ID in `settings.sectionPages`. Section values and order have a design draft lifecycle distinct from rich-text/widget page drafts; publishing design does not publish pending page text. Theme switches preserve the map. To migrate a custom schema, transform a pulled draft to the new version, review it, and push it with its revision; incompatible versions never auto-convert silently. Existing widget pages continue using their original renderer.
+The component receives SectionProps<Data>; `acms theme types <slug>` (also run by `acms check`) writes `section-types.d.ts` with one Data interface per section. Field kinds: text, textarea, richtext, image, url, link, select (options required), number, toggle, date, time, list (a repeater of those) and source (live events, posts or booking links). The full guide, including presets, migrations and the starter library (`acms section library` / `acms section add`), is `acms docs sections`. Instances have stable id/type/version/variant/hidden/data fields. A page layout has mode and sections, persisted by page ID in `settings.sectionPages`. Section values and order have a design draft lifecycle distinct from rich-text/widget page drafts; publishing design does not publish pending page text. Theme switches preserve the map. To migrate a custom schema, transform a pulled draft to the new version, review it, and push it with its revision; incompatible versions never auto-convert silently. Existing widget pages continue using their original renderer.
 
 Images in template files should be imported using relative paths so Astro bundles them. Theme CSS can reference `url(assets/name.webp)`; ACMS resolves it through the bundled asset inventory. Brand images and editable section images use the media library. Packaged assets must be local files under assets; declare them in the manifest. Use `theme pack --optimize` to run current img-subir and rewrite references before packing. Original-image backup directories are excluded.
 

package/integration.mjs

@@ -1,3 +1,4 @@
+import { resolveMobile } from './src/lib/mobile/config.mjs';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -32,6 +33,8 @@ const ROUTES = [
   ['/go/[id]', 'go/[id].ts'],
   ['/media/[...key]', 'media/[...key].ts'],
   ['/embed/[pageId]/[blockId]', 'embed/[pageId]/[blockId].ts'],
+  // one published section for mobile apps without a native component for it
+  ['/embed/section/[...path]', 'embed/section/[...path].astro'],
   ['/preview/[type]/[id]', 'preview/[type]/[id].astro'],
   ['/rss.xml', 'rss.xml.ts'],
   ['/sitemap.xml', 'sitemap.xml.ts'],
@@ -40,6 +43,7 @@ const ROUTES = [
   // admin
   ['/admin', 'admin/index.astro'],
   ['/admin/design', 'admin/design.astro'],
+  ['/admin/section-preview', 'admin/section-preview.astro'],
   ['/admin/links', 'admin/links.astro'],
   ['/admin/login', 'admin/login.astro'],
   ['/admin/logout', 'admin/logout.ts'],
@@ -82,6 +86,8 @@ const ROUTES = [
   ['/api/design/keys', 'api/design/keys.ts'],
   ['/api/design/capabilities', 'api/design/capabilities.ts'],
   ['/api/design/media', 'api/design/media.ts'],
+  ['/api/design/ai', 'api/design/ai.ts'],
+  ['/api/design/translate', 'api/design/translate.ts'],
   ['/api/agent', 'api/agent/index.ts'],
   ['/api/agent/docs', 'api/agent/docs.ts'],
   ['/api/mcp', 'api/mcp.ts'],
@@ -379,6 +385,7 @@ export const homes = import.meta.glob('/src/themes/*/templates/home.astro', { ea
 export const postTpls = import.meta.glob('/src/themes/*/templates/post-*.astro', { eager: true });
 export const pageTpls = import.meta.glob('/src/themes/*/templates/page-*.astro', { eager: true });
 export const eventTpls = import.meta.glob('/src/themes/*/templates/event.astro', { eager: true });
+export const migrations = import.meta.glob('/src/themes/*/migrations/*.mjs', { eager: true });
 `;
 
 function acmsVitePlugin(userConfig) {
@@ -418,6 +425,13 @@ function acmsVitePlugin(userConfig) {
  *   Home page content per language is authored in /admin as a normal page
  *   marked "home" with that language selected. Omit for monolingual sites —
  *   nothing changes.
+ * @param {{ios?: {teamId: string, bundleId: string, paths?: string[]}, android?: {package: string, sha256CertFingerprints: string[]}, push?: boolean | {enabled?: boolean, retentionDays?: number}, editor?: {redirectUris: string[], name?: string, accessTokenMinutes?: number, refreshTokenDays?: number}}} [options.mobile]
+ *   Optional iOS Universal Links and Android App Links associations, and push
+ *   notifications for the site's own Expo apps (`push: true`; off by default):
+ *   /api/v1/devices, /api/v1/push/topics and Admin → Mobile app. `editor:
+ *   { redirectUris, name? }` turns on editor apps: staff sign in through the
+ *   browser (/admin/app-auth, OAuth 2.0 + PKCE; only the listed redirect URIs
+ *   receive codes) and edit through the bearer-token /api/v1/admin/* API.
  * @param {{enabled?: boolean}} [options.search]
  *   Public site search: the /search page, the /api/search JSON endpoint, and
  *   the header search modal. On by default — set `enabled: false` to remove
@@ -441,6 +455,7 @@ export default function acms(options = {}) {
   ]);
   const i18n = resolveI18n(options.i18n, contentBases);
   const search = resolveSearch(options.search);
+  const mobile = resolveMobile(options.mobile);
   const calendar = resolveCalendar(options.calendar, contentBases, i18n.locales);
   const legal = { enabled: true, operatorName: '', contactEmail: '', updatedAt: '', ...(options.legal === false ? { enabled: false } : options.legal ?? {}) };
   if (typeof legal.enabled !== 'boolean' || ['operatorName','contactEmail','updatedAt'].some(k => typeof legal[k] !== 'string')) throw new Error('acms: invalid legal configuration');
@@ -453,13 +468,52 @@ export default function acms(options = {}) {
     content,
     i18n,
     search,
+    mobile,
     calendar,
     legal,
   };
   const routes = [...ROUTES,
+    ['/api/v1/site', 'api/v1/site.ts'],
+    ['/api/v1/theme', 'api/v1/theme.ts'],
+    ['/api/v1/pages/home', 'api/v1/pages/home.ts'],
+    ['/api/v1/pages/[...slug]', 'api/v1/pages/[...slug].ts'],
+    ['/api/v1/openapi.json', 'api/v1/openapi.json.ts'],
     ['/api/v1/content', 'api/v1/content/index.ts'],
     ['/api/v1/content/[id]', 'api/v1/content/[id].ts'],
   ];
+  if (mobile.ios) routes.push(['/.well-known/apple-app-site-association', '.well-known/apple-app-site-association.ts']);
+  if (mobile.android) routes.push(['/.well-known/assetlinks.json', '.well-known/assetlinks.json.ts']);
+  if (mobile.push.enabled) {
+    routes.push(
+      ['/api/v1/devices', 'api/v1/devices/index.ts'],
+      ['/api/v1/devices/[token]', 'api/v1/devices/[token].ts'],
+      ['/api/v1/push/topics', 'api/v1/push/topics.ts'],
+      ['/api/push/admin', 'api/push/admin.ts'],
+      ['/admin/mobile', 'admin/mobile.astro'],
+    );
+  }
+  if (mobile.editor.enabled) {
+    // editor apps: browser sign-in (OAuth 2.0 + PKCE) and the bearer-only admin API
+    routes.push(
+      ['/admin/app-auth', 'admin/app-auth.astro'],
+      ['/api/v1/auth/token', 'api/v1/auth/token.ts'],
+      ['/api/v1/auth/revoke', 'api/v1/auth/revoke.ts'],
+      ['/api/v1/admin/me', 'api/v1/admin/me.ts'],
+      ['/api/v1/admin/documents', 'api/v1/admin/documents/index.ts'],
+      ['/api/v1/admin/documents/[kind]/[id]', 'api/v1/admin/documents/[kind]/[id]/index.ts'],
+      ['/api/v1/admin/documents/[kind]/[id]/[action]', 'api/v1/admin/documents/[kind]/[id]/[action].ts'],
+      ['/api/v1/admin/documents/[kind]/[id]/translations/[locale]', 'api/v1/admin/documents/[kind]/[id]/translations/[locale]/index.ts'],
+      ['/api/v1/admin/documents/[kind]/[id]/translations/[locale]/[action]', 'api/v1/admin/documents/[kind]/[id]/translations/[locale]/[action].ts'],
+      ['/api/v1/admin/sections', 'api/v1/admin/sections/index.ts'],
+      ['/api/v1/admin/sections/[pageId]/[sectionId]', 'api/v1/admin/sections/[pageId]/[sectionId]/index.ts'],
+      ['/api/v1/admin/sections/[pageId]/[sectionId]/publish', 'api/v1/admin/sections/[pageId]/[sectionId]/publish.ts'],
+      ['/api/v1/admin/sections/[pageId]/[sectionId]/translations/[locale]', 'api/v1/admin/sections/[pageId]/[sectionId]/translations/[locale]/index.ts'],
+      ['/api/v1/admin/sections/[pageId]/[sectionId]/translations/[locale]/[action]', 'api/v1/admin/sections/[pageId]/[sectionId]/translations/[locale]/[action].ts'],
+      ['/api/v1/admin/media', 'api/v1/admin/media/index.ts'],
+      ['/api/v1/admin/bookings', 'api/v1/admin/bookings/index.ts'],
+      ['/api/v1/admin/bookings/[id]/[action]', 'api/v1/admin/bookings/[id]/[action].ts'],
+    );
+  }
   if (legal.enabled) routes.push(['/privacy', 'legal/privacy.astro'], ['/terms', 'legal/terms.astro']);
   for (const c of Object.values(content.collections)) {
     routes.push([c.base, 'blog/index.astro'], [`${c.base}/[slug]`, 'blog/[slug].astro']);
@@ -529,7 +583,7 @@ export default function acms(options = {}) {
         if (config.root) {
           const discoveryDir = fileURLToPath(new URL('.astro/', config.root));
           mkdirSync(discoveryDir, {recursive:true});
-          writeFileSync(join(discoveryDir,'acms-project.json'), JSON.stringify({ themeApiVersion:1, collections:userConfig.content.collections, calendar:userConfig.calendar }));
+          writeFileSync(join(discoveryDir,'acms-project.json'), JSON.stringify({ themeApiVersion:1, collections:userConfig.content.collections, calendar:userConfig.calendar, mobile:userConfig.mobile ?? {} }));
         }
         updateConfig({ vite: { plugins: [acmsVitePlugin(userConfig)] } });
 

package/mobile-template/client/AGENTS.md

@@ -0,0 +1,97 @@
+# Agent rules for this app
+
+Full guide: run `npx acms docs mobile` from the **site** folder (the folder
+that contains this app; all `acms` commands run there, not in this folder). Finish
+every change with `npx acms mobile doctor` (no failures).
+
+This is the **client app** for the ACMS site at `__ACMS_SITE_URL__`: an Expo
+(React Native) app for iOS, Android and web that shows the site's content. The
+site owner edits everything in the site admin; the app only reads the public
+API. It lives beside the website but is a separate project (its own
+`package.json` and `node_modules`), not part of the site build.
+
+## Rules
+
+1. **Use the ACMS hooks, never raw fetch.** Import from `@acms-subir/native`
+   (`useSite`, `useTheme`, `useLocale`, `usePage`, `usePosts`, `usePost`,
+   `useEvents`, `useEvent`, `useResources`, `useAvailability`, `useBooking`,
+   `<Sections>`, `<RichText>`, `<EventDate>`). For anything else use the typed
+   client from `useAcms()` (`@acms-subir/client`) inside a TanStack Query hook.
+2. **Never hardcode content.** Names, times, text, events, prices, people and
+   images come from the site. If the app needs something the owner should be
+   able to change, it must be a section field or content in the admin, not a
+   string in this code. Only UI chrome ("Try again", "Book") belongs here.
+3. **Public API only.** No admin routes, no database, no agent or integration
+   keys, no admin password. There are no secrets in a mobile app:
+   `EXPO_PUBLIC_*` values are bundled and readable by anyone.
+4. **Style from the site's theme.** Colors, fonts and radius come from
+   `useTheme()` (`t.colors`, `t.styles`). Support light and dark mode. No
+   pill-shaped chips or badges (use 10–12px radius rectangles or plain text),
+   no colored left-edge accent stripes, no gradient-squircle logos.
+5. **Phones and tablets.** Use `useLayout()` / `useWindowDimensions` for
+   columns and gutters; never fixed widths. Content should use the width on a
+   tablet, not a stretched phone column.
+6. **Bookings are sensitive.** `useBooking()` handles idempotency. Never put a
+   booking's manage token, email or idempotency key in a URL, log or analytics
+   event; store the manage token with `expo-secure-store` if you keep it.
+7. **Links:** section links may be root-relative. Open them with
+   `useOpenLink()` (site pages go through `onNavigate`), or resolve with
+   `resolveUrl(href, baseUrl)`. To open your own screens for site pages, pass
+   `onNavigate={(path, url) => …}` to `<AcmsProvider>` in `app/_layout.tsx`
+   (e.g. `router.push` for `/events/<slug>` when the events recipe is in).
+8. **Sections mirror the website.** A native section uses the same fields and
+   variants as the site's `src/themes/<theme>/sections/*.astro` component and
+   renders empty fields the same way.
+
+## Where things are
+
+- `app/_layout.tsx` wires `<AcmsProvider>` (site URL from `EXPO_PUBLIC_ACMS_URL`),
+  theme colors and the language switch.
+- `app/index.tsx` renders the homepage sections with pull to refresh.
+- `sections/index.ts` is this app's section registry, passed to
+  `<Sections registry={sections}>`. Keys are a section type or `type:variant`.
+- Each section renders with the first match of: `sections/index.ts` → the
+  packaged library components (`@acms-subir/native/sections`: hero-banner,
+  service-times, upcoming-events, feature-grid, team, pricing, gallery,
+  questions, cta-band, contact, latest-posts) → the website's rendering in a
+  web view (react-native-webview; an iframe on web) → a generic view.
+- To change a library section, get an editable copy (from the site folder):
+  `npx acms section add team --theme <slug> --native` → `sections/Team.tsx`.
+- New coded sections: `npx acms section new <type> --theme <slug>` writes the
+  web component and a typed native stub here (`sections/<Type>.tsx`, types in
+  `sections/types.ts`). Finish the stub so it matches the web version.
+- `npx acms check` lists sections that only show as a web view; give the ones
+  people use most a native component. Build yours from the exported pieces
+  (`Grid`, `FocalImage`, `SectionHeader`, `ActionButton`, `TextLink`,
+  `useSectionMetrics`) so they stay responsive and themed.
+- Images: pass `<key>Focus` to `FocalImage` so crops keep the owner's focal point.
+
+## Recipes
+
+Add ready-made screens from the site folder instead of writing them from scratch:
+
+```sh
+npx acms mobile recipe list
+npx acms mobile recipe add events    # events list, detail, add to calendar
+npx acms mobile recipe add news      # posts list and article
+npx acms mobile recipe add booking   # resources → slots → form → confirmation
+npx acms mobile recipe add push      # notifications: turn on, topics, taps (site needs push on)
+```
+
+Each recipe prints the extra Expo packages to install (`npx expo install ...`).
+
+## Before you finish
+
+- `npm run typecheck` passes.
+- Check iOS and Android (and `npm run web`), in both light and dark mode, on a
+  phone-sized and a tablet-sized screen. Compare the home screen with the
+  website: same sections, same order, same words.
+- `npx expo export --platform web` bundles without errors.
+- `npx acms mobile dev` (from the site folder) runs the site and this app so a
+  real phone on the same network or Tailscale can reach it.
+- `npx acms mobile doctor` (from the site folder) passes: packages match the
+  site, the site address works, no secrets, sections covered, recipe
+  packages installed. Read its warnings too.
+- If the task needs content the site doesn't have yet (a page, a calendar),
+  read it by slug anyway, show an empty state, and tell the owner what to
+  create in the admin. Don't hardcode it.

package/mobile-template/client/README.md

@@ -0,0 +1,65 @@
+# __ACMS_APP_NAME__
+
+A blank Expo app connected to your ACMS site (`__ACMS_SITE_URL__`). It already
+shows your homepage sections, follows your site's Design colors in light and
+dark mode, and switches language when your site has more than one. Everything
+else is yours to build.
+
+## Run it
+
+From your **site** folder (starts the site too, and points the app at an
+address your phone can reach):
+
+```sh
+cd __ACMS_APP_DIR__ && npm install && cd ..
+npx acms mobile dev
+```
+
+Scan the QR code with Expo Go, or press `i` / `a` / `w` for the iOS simulator,
+Android emulator or a browser. Or run the app on its own:
+
+```sh
+npm start
+```
+
+The site address comes from `EXPO_PUBLIC_ACMS_URL` in `.env` (your production
+site) and `.env.local` (written by `acms mobile dev`, not committed).
+
+## Add screens
+
+```sh
+npx acms mobile recipe add events   # also: news, booking, push
+```
+
+Build your own with the hooks from `@acms-subir/native`. `AGENTS.md` has the
+rules coding agents follow here; `npx acms docs mobile` (from the site folder)
+is the full guide with a cookbook (tabs, events, native sections, booking).
+
+## Check it
+
+From the site folder:
+
+```sh
+npx acms mobile doctor            # --offline skips network checks, --json for tools
+```
+
+It checks the ACMS packages match your site's version, the site address works
+(and isn't localhost for a phone), app ids and deep links, sections the app
+can't show natively, secrets in the code, and recipe packages. It exits 1 when
+something fails.
+
+## Ship it
+
+Builds and store submission use [EAS](https://docs.expo.dev/build/introduction/):
+
+```sh
+npx eas-cli build --profile preview --platform all   # installable test builds
+npx eas-cli build --profile production --platform all
+npx eas-cli submit --platform ios
+```
+
+Before your first store build, run `npx acms mobile doctor` and check
+`app.json`: app name, `ios.bundleIdentifier`
+(`__ACMS_BUNDLE_ID__`) and `android.package` can't change after release. To open
+site links in the app, set `acms({ mobile: { ios, android } })` in the site's
+`astro.config.mjs` (see the site's mobile API docs).

package/mobile-template/client/app/_layout.tsx

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+import { Text, View } from 'react-native';
+import { DarkTheme, DefaultTheme, Stack, ThemeProvider } from 'expo-router';
+import { StatusBar } from 'expo-status-bar';
+import { AcmsProvider, useSite, useTheme } from '@acms-subir/native';
+import { LanguageSwitch } from '../components/LanguageSwitch';
+
+// Set in .env (production site) or .env.local (written by `npx acms mobile dev`).
+const baseUrl = process.env.EXPO_PUBLIC_ACMS_URL;
+
+export default function RootLayout() {
+  if (!baseUrl) return <MissingUrl />;
+  return (
+    <AcmsProvider baseUrl={baseUrl}>
+      <ThemedStack />
+    </AcmsProvider>
+  );
+}
+
+// Navigation chrome follows the site's Design tokens in light and dark mode.
+function ThemedStack() {
+  const t = useTheme();
+  const { data: site } = useSite();
+  const navTheme = useMemo(() => {
+    const base = t.scheme === 'dark' ? DarkTheme : DefaultTheme;
+    return { ...base, colors: { ...base.colors, primary: t.colors.accent, background: t.colors.bg, card: t.colors.bg, text: t.colors.ink, border: t.colors.line, notification: t.colors.accent } };
+  }, [t]);
+  return (
+    <ThemeProvider value={navTheme}>
+      <StatusBar style={t.scheme === 'dark' ? 'light' : 'dark'} />
+      <Stack
+        screenOptions={{
+          headerStyle: { backgroundColor: t.colors.bg },
+          headerTintColor: t.colors.ink,
+          headerTitleStyle: { fontFamily: t.styles.fonts.heading },
+          headerShadowVisible: false,
+          contentStyle: { backgroundColor: t.colors.bg },
+          headerRight: () => <LanguageSwitch />,
+        }}
+      >
+        <Stack.Screen name="index" options={{ title: site?.name ?? '' }} />
+      </Stack>
+    </ThemeProvider>
+  );
+}
+
+function MissingUrl() {
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', padding: 24, gap: 8 }}>
+      <Text style={{ fontSize: 18, fontWeight: '600' }}>Connect your site</Text>
+      <Text style={{ fontSize: 15, lineHeight: 22 }}>
+        Set EXPO_PUBLIC_ACMS_URL in .env (for example https://example.com), or run `npx acms mobile dev` from your site folder, then restart Expo.
+      </Text>
+    </View>
+  );
+}

package/mobile-template/client/app/index.tsx

@@ -0,0 +1,21 @@
+import { RefreshControl, ScrollView } from 'react-native';
+import { Sections, useRefresh, useTheme } from '@acms-subir/native';
+import { sections } from '../sections';
+
+// The home screen shows the site's published homepage sections. Owners edit
+// them in the site admin (Design → Pages); the app picks changes up on refresh.
+// Each section renders with: your components in sections/ → the packaged
+// library components → the website's rendering (web view) → a generic view.
+export default function Home() {
+  const t = useTheme();
+  const { refreshing, refresh } = useRefresh();
+  return (
+    <ScrollView
+      style={{ flex: 1, backgroundColor: t.colors.bg }}
+      contentInsetAdjustmentBehavior="automatic"
+      refreshControl={<RefreshControl refreshing={refreshing} onRefresh={refresh} tintColor={t.colors.muted} />}
+    >
+      <Sections page="home" registry={sections} />
+    </ScrollView>
+  );
+}

package/mobile-template/client/app.json

@@ -0,0 +1,21 @@
+{
+  "expo": {
+    "name": "__ACMS_APP_NAME__",
+    "slug": "__ACMS_APP_SLUG__",
+    "version": "1.0.0",
+    "scheme": "__ACMS_APP_SCHEME__",
+    "orientation": "default",
+    "userInterfaceStyle": "automatic",
+    "ios": {
+      "bundleIdentifier": "__ACMS_BUNDLE_ID__",
+      "supportsTablet": true
+    },
+    "android": {
+      "package": "__ACMS_BUNDLE_ID__"
+    },
+    "web": {
+      "output": "single"
+    },
+    "plugins": ["expo-router"]
+  }
+}

package/mobile-template/client/components/LanguageSwitch.tsx

@@ -0,0 +1,31 @@
+import { Pressable, Text, View } from 'react-native';
+import { useLocale, useTheme } from '@acms-subir/native';
+
+// Text buttons ("EN  ES") for sites with more than one language.
+export function LanguageSwitch() {
+  const t = useTheme();
+  const { locale, languages, setLocale } = useLocale();
+  if (languages.length < 2) return null;
+  return (
+    <View style={{ flexDirection: 'row', gap: 4 }}>
+      {languages.map((l) => {
+        const active = l.code === locale;
+        return (
+          <Pressable
+            key={l.code}
+            onPress={() => setLocale(l.code)}
+            accessibilityRole="button"
+            accessibilityState={{ selected: active }}
+            accessibilityLabel={l.name}
+            hitSlop={8}
+            style={{ paddingHorizontal: 6, paddingVertical: 4 }}
+          >
+            <Text style={{ color: active ? t.colors.ink : t.colors.muted, fontWeight: active ? '700' : '500', fontSize: 14 }}>
+              {l.code.toUpperCase()}
+            </Text>
+          </Pressable>
+        );
+      })}
+    </View>
+  );
+}