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

package/docs/mobile.md

@@ -0,0 +1,527 @@
+# Mobile apps: build the owner's own Expo app on their ACMS site
+
+This is the guide for agents (and people) working on an ACMS mobile app. The
+site owner edits content in the site admin; the app is **their own** Expo
+(React Native) app that shows it on iOS, Android and the web. ACMS ships the
+foundation (API, client, hooks, native sections, starter, recipes); you build
+the app.
+
+> **The site owns the content. The app owns the look and the navigation.**
+
+Run every `acms` command from the **site folder** (the one that contains the
+app folder, normally with `astro.config.mjs`), not from the app folder:
+`npx acms …`. The app is a
+separate project beside the site (default `mobile/`, its own `package.json`
+and `node_modules`), found by the `"acms": { "app": "client" }` marker in its
+`package.json`.
+
+## Start and finish
+
+```sh
+npx acms inspect --json          # site, themes, mobile apps (dir, kind, bundle ids, versions)
+npx acms docs mobile             # this guide
+npx acms add mobile              # only when there is no app yet (acms mobile list)
+cd mobile && npm install && cd ..
+npx acms mobile dev              # site + Expo on an address a phone can reach
+# … work …
+cd mobile && npx tsc --noEmit && cd ..
+npx acms mobile doctor           # must end with 0 failed; read every warning
+```
+
+Read the app's `AGENTS.md` too: it holds the same rules, next to the code.
+
+## Rules
+
+1. **Public API only, through `@acms-subir/client`.** Use the hooks from
+   `@acms-subir/native` (they wrap the client). For anything without a hook,
+   call the typed client from `useAcms()` inside a TanStack Query hook. Never
+   raw `fetch`, never `/api/agent`, `/api/design`, `/api/media` or any other
+   admin route, never the database.
+2. **No secrets in the app.** Everything in the bundle is public, including
+   every `EXPO_PUBLIC_*` value. No `ACMS_TOKEN`, API keys (`acms_key_…`,
+   `acms_agent_…`), admin passwords or `Authorization: Bearer …` literals. The
+   only setting is `EXPO_PUBLIC_ACMS_URL`: `.env` (committed) is the address
+   baked into builds, set by `acms add mobile --url`, and must be the https
+   production site before a store build (it may be a dev address until then);
+   `.env.local` (git-ignored) is the dev address `acms mobile dev` writes, and
+   wins while developing.
+3. **Content comes from the site, never hardcoded.** Names, times, text,
+   events, prices, people, images, links, giving details, addresses: all read
+   through hooks. If the owner should be able to change it, it lives in the
+   admin (a page, its sections, events, posts, resources). Only UI chrome
+   belongs in code: "Try again", "Book", tab titles, empty-state wording.
+   If the content the task needs doesn't exist on the site yet, build the
+   screen to read it anyway (by page slug, calendar slug, …), show a clear
+   empty state, and tell the user exactly what the owner must create in the
+   admin. Don't invent the content in code.
+4. **Sections render through `<Sections>` and the registry.** A page's
+   sections come from `usePage(slug)` / `<Sections page="slug" registry={sections}>`.
+   Each section uses the first match of: `sections/index.ts` (yours) →
+   the packaged library (`@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 → a generic view. Keys are a type or `type:variant`.
+5. **Native twins mirror the web.** Same fields, same variants, same
+   empty-field behaviour as `src/themes/<theme>/sections/<Type>.astro`.
+   - Change a library section: `npx acms section add team --theme <slug> --native`
+     → `mobile/sections/Team.tsx`, registered. Edit that copy.
+   - New coded section: `npx acms section new <type> --theme <slug>` writes the
+     web component **and** a typed native stub (`sections/<Type>.tsx`, types in
+     `sections/types.ts`). Finish the stub.
+   - Build from the exported pieces (`Grid`, `FocalImage`, `SectionHeader`,
+     `ActionButton`, `TextLink`, `useSectionMetrics`) so it stays themed and
+     responsive. `npx acms check` refreshes `sections/types.ts` and lists
+     sections that only show as a web view.
+6. **Web-view fallback** covers the site's own coded sections until a native
+   version exists (needs `react-native-webview`; an iframe on web). Leave it on
+   unless every section has a native component. `webFallback={false}` /
+   `<AcmsProvider webSectionFallback={false}>` switches to the generic view.
+7. **Internal links go through `onNavigate`.** Section and rich-text links may
+   be root-relative. Open them with `useOpenLink()`; site pages go to
+   `<AcmsProvider onNavigate={(path, url) => …}>` in `app/_layout.tsx`, where
+   you `router.push` to your own screen (`/events/<slug>` → `app/events/[slug].tsx`)
+   and fall back to `Linking.openURL(url)`. External, `mailto:` and `tel:`
+   links always leave the app.
+8. **Languages via `useLocale()`.** `{ locale, defaultLocale, languages, setLocale }`.
+   Every hook re-fetches in the chosen language; the starter's
+   `LanguageSwitch` shows when the site has more than one. Translate words in
+   the admin, not in the app. Date/number formatting: `<EventDate>`,
+   `formatEventDate`, `Intl` with `locale`.
+9. **Theme via `useTheme()`, light and dark.** `t.colors` (`bg`, `ink`,
+   `muted`, `line`, `accent`, `onAccent`, …), `t.styles` (`text.*`, `card`,
+   `button`, `space(n)`, `fonts`), `t.radius` (≤12), `t.scheme`. No literal
+   colors. Check both schemes. No pill shapes (10–12px radius rectangles or
+   plain text), no colored left-edge stripes, no gradient-squircle logos.
+10. **Phones and tablets.** Lay out from `useLayout()` (`columns`, `gutter`,
+    `contentWidth`, `wide`) or `useWindowDimensions()`; never fixed widths.
+    On a tablet use the width (grids, split panes, `maxWidth` content column),
+    not a stretched phone column. `supportsTablet` is on.
+11. **Touch targets ≥ 44pt** (`minHeight: 44`, or `hitSlop` on small icons);
+    `accessibilityRole` and labels on custom buttons; text scales with the
+    system font size.
+12. **Offline.** `offlinePersister()` from `@acms-subir/native/persist` keeps
+    content reads for 7 days (install `@react-native-async-storage/async-storage`
+    and `@tanstack/query-async-storage-persister` with `npx expo install`).
+    Every screen needs loading, error (`<ErrorView error retry>`) and empty states,
+    and pull to refresh (`useRefresh()`).
+13. **Bookings are idempotent.** Use `useBooking({ createKey: randomUUID })`
+    (expo-crypto): the same details reuse one Idempotency-Key until success,
+    so retries never double-book. Never put the manage token, email or key in
+    a URL, log or analytics; keep the manage token in `expo-secure-store`.
+
+## Hooks at a glance
+
+| Hook | For |
+| --- | --- |
+| `useSite()` | name, menu, languages, features (`calendar`, `bookings`, `blog`) |
+| `usePage(slug)` | a published page: `mode` (`sections`/`content`), `sections`, `body.html`; 404 when missing |
+| `usePosts({ collection, limit })` / `usePost(slug)` | posts (infinite: `items`, `fetchNextPage`) |
+| `useEvents({ calendar, from, to, limit, q })` | `data.occurrences[]` (`start`, `end`, `allDay`, `event`) in a window (default 30 days, max 90) |
+| `useEvent(slug)` | one event |
+| `useResources()` / `useAvailability({ resource, link })` / `useBooking()` | bookings |
+| `useLocale()`, `useTheme()`, `useLayout()`, `useRefresh()`, `useOpenLink()` | language, tokens, layout, refresh, links |
+| `usePushRegistration({ topics })` / `usePushTopics()` / `useNotificationTaps()` | push notifications (see Push notifications) |
+| `useAcms()` | the typed client (e.g. `calendars()`) for your own `useQuery` |
+
+Components: `<Sections>`, `<RichText html>`, `<EventDate start end allDay timezone>`,
+`<Button>`, `<ErrorView error retry>`, `<GenericSection>`. Full reference:
+`@acms-subir/native` README; API contract: the site's `docs/mobile-api-v1.md`
+and `<site>/api/v1/openapi.json`.
+
+## Recipes
+
+Ready-made screens; add them instead of writing from scratch:
+
+```sh
+npx acms mobile recipe list
+npx acms mobile recipe add events    # list, detail, add to calendar  (expo-calendar)
+npx acms mobile recipe add news      # posts list, article
+npx acms mobile recipe add booking   # resources → slots → form → confirmation  (expo-crypto)
+npx acms mobile recipe add push      # notifications: turn on, topic toggles, taps open the page  (expo-notifications, expo-device)
+```
+
+Each prints the `npx expo install …` line for its packages: run it (doctor
+fails when a recipe's packages are missing). Recipes never overwrite files.
+
+## Common tasks
+
+**Add a tab.** The starter is a Stack. Move the home screen into a tab group.
+On Expo SDK 57+ import `Tabs` from `expo-router/js-tabs` (the `expo-router`
+export is deprecated):
+
+```
+app/_layout.tsx            Stack: <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+app/(tabs)/_layout.tsx     <Tabs screenOptions={{ tabBarActiveTintColor: t.colors.accent,
+                              tabBarInactiveTintColor: t.colors.muted,
+                              tabBarStyle: { backgroundColor: t.colors.bg, borderTopColor: t.colors.line },
+                              headerStyle: { backgroundColor: t.colors.bg }, headerTintColor: t.colors.ink,
+                              headerRight: () => <LanguageSwitch /> }}>
+app/(tabs)/index.tsx       the old app/index.tsx (delete the original; one route per path)
+app/(tabs)/giving.tsx      the new tab
+```
+
+Keep detail screens (e.g. `app/events/[slug].tsx`) outside `(tabs)` so they
+push over the tabs. The header title moves to the tab screen
+(`options={{ headerTitle: site?.name }}`). Tab icons: `react-native-svg` is
+already installed (draw small `Path` icons), or run
+`npx expo install @expo/vector-icons` first and use
+`tabBarIcon: ({ color, size }) => <Ionicons name="heart-outline" color={color} size={size} />`.
+To open the tab from site links, map its path in `onNavigate`
+(`router.navigate('/giving')`).
+
+**A tab that shows an owner-editable page** (giving, visit, about). Ask the
+owner for (or check for) a page with that slug; render it whichever way it is
+built, and explain what's missing when it isn't there:
+
+```tsx
+export default function Giving() {
+  const t = useTheme();
+  const page = usePage('giving');
+  const { refreshing, refresh } = useRefresh();
+  if (page.isPending) return <ActivityIndicator style={{ marginTop: 48 }} color={t.colors.muted} />;
+  if (page.error instanceof AcmsError && page.error.status === 404) return <MissingPage slug="giving" />; // your empty state
+  if (page.error) return <ErrorView error={page.error} retry={() => page.refetch()} />;
+  return (
+    <ScrollView style={{ backgroundColor: t.colors.bg }} refreshControl={<RefreshControl refreshing={refreshing} onRefresh={refresh} />}>
+      {page.data.mode === 'sections'
+        ? <Sections page="giving" registry={sections} />
+        : <View style={{ padding: t.styles.space(5) }}><RichText html={page.data.body.html} /></View>}
+    </ScrollView>
+  );
+}
+```
+
+`AcmsError` (from `@acms-subir/client`) has `status` and `code`; show a
+friendly note for `404` rather than a raw error (`isAcmsError(e)` narrows it).
+Fixed chrome (the tab title "Giving") is fine in code; amounts, fund names,
+bank details and links are not.
+
+**Show the next 3 events of one calendar on home.** Calendars are addressed
+by slug (`useAcms().calendars()` lists public ones; the site's
+`/api/v1/calendars`). Keep the slug in one named constant, and render the
+page's own sections below it. The events window starts at **midnight UTC
+today** and `from` takes only a date, so the response can include occurrences
+that already ended: ask for a few extra and filter by `end`:
+
+```tsx
+const YOUTH_CALENDAR = 'youth'; // a calendar slug from the site, not content
+const day = (offset: number) => new Date(Date.now() + offset * 86_400_000).toISOString().slice(0, 10);
+
+function NextEvents() {
+  const t = useTheme();
+  const open = useOpenLink();
+  const to = useMemo(() => day(90), []); // the API's maximum window
+  const events = useEvents({ calendar: YOUTH_CALENDAR, to, limit: 8 });
+  const next = (events.data?.occurrences ?? []).filter((o) => Date.parse(o.end || o.start) > Date.now()).slice(0, 3);
+  // loading / error (404 = calendar renamed or private) / empty states …
+  return next.map((o) => (
+    <Pressable key={o.id} onPress={() => open(o.event.url)} style={{ minHeight: 44 }} accessibilityRole="link">
+      <Text style={t.styles.text.heading}>{o.event.title}</Text>
+      <EventDate start={o.start} end={o.end} allDay={o.allDay} timezone={o.event.timezone} />
+    </Pressable>
+  ));
+}
+```
+
+A weekly event may fill all three slots; that is correct. If the owner should
+choose the calendar, better still: they add an **Upcoming events** section
+(its events source has a calendar and a limit) to the home page in the admin,
+and `<Sections>` renders it with no app code at all. Say so in your summary.
+
+**A native version of a coded section.** From the site folder:
+`npx acms section new visit-banner --theme <slug>` (new) or, for an existing
+coded section, write `mobile/sections/VisitBanner.tsx` typed with
+`SectionComponentProps<VisitBannerData>` from `./types` and register it in
+`sections/index.ts` (`'visit-banner': VisitBanner`). Run `npx acms check` to
+refresh `sections/types.ts`.
+
+**Translate.** Nothing to translate in the app beyond chrome: content
+languages come from the site (`useLocale`, the `LanguageSwitch`). The owner
+translates in the admin. For chrome strings, keep a tiny `{ en, es }` map
+keyed by `locale`.
+
+**Add a booking flow.** `npx acms mobile recipe add booking` then
+`npx expo install expo-crypto`; bookings must be enabled on the site
+(`useSite().data.features.bookings`) with a public booking link. Link to it:
+`<Link href="/book">`.
+
+## Push notifications
+
+Optional; the owner sends them from **Admin → Mobile app** (manual messages
+plus automatic ones: new post, new event, "starting soon"). The app only
+registers and chooses topics; it never sends.
+
+1. Site: `acms({ mobile: { push: true } })` in `astro.config.mjs` (off by
+   default; `/api/v1/devices` and `/api/v1/push/topics` 404 until then).
+   Optional secret `EXPO_ACCESS_TOKEN` when "enhanced push security" is on for
+   the Expo project.
+2. App: `npx acms mobile recipe add push`, `npx expo install expo-notifications expo-device`,
+   add `"expo-notifications"` to `plugins` in app.json, `npx eas-cli init`
+   (push tokens need `extra.eas.projectId`), and mount `<PushSetup />` inside
+   `<AcmsProvider>` in `app/_layout.tsx`. Link to `/notifications`.
+3. Taps carry `data.url` / `data.path` and go through the provider's
+   `onNavigate`, so route `/events/<slug>` and post paths to your screens there.
+
+Rules: ask for permission from a button after saying why (the recipe does),
+never on first launch. Topic ids and names come from the site
+(`usePushTopics()`); don't hardcode labels. `usePushRegistration` re-registers
+quietly each start and sends the app's language, so notices arrive in the
+reader's language when a translation exists. Test on a real device (simulators
+get no push); doctor checks the plugin, the project id and that the site has
+push on.
+
+## Editor apps (staff sign-in)
+
+A second, separate Expo app for the people who run the site: owners and
+other staff write posts, edit section text, review translations, upload media and
+answer bookings from their phone. It signs in through the site (OAuth 2.0 +
+PKCE in the system browser, never a password in the app) and uses the
+bearer-only `/api/v1/admin/*` API (docs/mobile-api-v1.md → Editor apps). We
+ship building blocks, a blank signed-in shell and optional recipes; the app
+itself is the owner's to shape.
+
+### Start
+
+```sh
+npx acms add mobile editor --url https://example.com   # → mobile-editor/
+cd mobile-editor && npm install && cd ..
+npx acms mobile recipe add editor-content              # and more, below
+npx acms mobile dev --dir mobile-editor
+```
+
+`add mobile editor` picks a reverse-DNS bundle id (`org.example.staff`), uses
+it lowercased as the app's scheme, and its sign-in return address is
+`<scheme>://auth`. It adds that address to
+`acms({ mobile: { editor: { name, redirectUris } } })` in `astro.config` when
+the file has a shape it can edit safely (`acms()`, `acms({ … })` without a
+`mobile` key, a `mobile: {…}` without `editor`, or an existing
+`redirectUris: [...]`); otherwise it prints the exact snippet (`--no-config`
+never touches the file). Restart or deploy the site afterwards. Other
+addresses to list:
+
+- the web build: `https://<where it is hosted>/auth`; `http://localhost/auth`
+  covers local development on any port (loopback rule);
+- Expo Go while testing: `exp://<lan ip>:8081/--/auth` (remove before release).
+
+`create-acms-subir --mobile editor` (or `both`, `client,editor`) does the same
+while scaffolding.
+
+### The starter
+
+- `app/_layout.tsx`: `<EditorProvider baseUrl clientId redirectUri>` and the
+  signed-out / signed-in switch (`useAuth().status`).
+- `components/SignIn.tsx`: site name and logo from `/api/v1/site`, "Sign in
+  with ‹site›", errors and "you were signed out" notices.
+- `app/index.tsx`: Home — "Signed in as … · role", the app's tools (one file
+  per entry in `tools/`), Light / Dark / Auto, sign out.
+- `app/auth.tsx`: the return-address route; `completeAuthRedirect()` lets the
+  web sign-in popup hand back its result.
+- `components/Screen.tsx`: `Screen`, `SplitView` (list + detail on ≥ 768),
+  `useWide`, `HeaderActions`; `components/TextTabs.tsx`; `lib/format.ts`.
+
+The look is the admin's Inset Paper (light and dark): `useEditorTheme()`
+(`colors.panel/raised/sel/line/text/muted/accent/green/blue/amber/red`,
+`text.screenTitle/title/row/body/meta/label/section`, `radius`). Change tokens
+with `<EditorProvider theme={{ colors: { light: { accent: '#0a7' } } }}>`.
+
+### `@acms-subir/native/editor`
+
+No hard dependencies. Optional peers, loaded only if installed (a missing one
+throws a message naming the package): `expo-secure-store` (tokens),
+`expo-web-browser` (sign-in), `expo-crypto` (PKCE; Web Crypto otherwise),
+`expo-image-picker` (uploads), `expo-device` (device name).
+
+`<EditorProvider>` props: `baseUrl`, `clientId`, `redirectUri` (use
+`redirectUriFor(scheme)`: `<scheme>://auth` on devices, `<origin>/auth` on the
+web), `storage` (default: expo-secure-store with
+`WHEN_UNLOCKED_THIS_DEVICE_ONLY`; sessionStorage on the web; or
+`memoryTokenStorage()` / your own `{ get, set }`), `storageKey`,
+`openAuthSession`, `crypto`, `deviceName`, `queryClient` (default: the
+surrounding one or a new one), `colorScheme`, `theme`, `fetch`. It refreshes
+tokens before they expire (single flight), signs out locally when a refresh is
+rejected or a request is still 401 after a refresh, and drops all cached admin
+data on sign-out.
+
+| Hook | Gives you |
+| --- | --- |
+| `useAuth()` | `status` (`loading`/`signedOut`/`signingIn`/`signedIn`), `user`, `role`, `device`, `error`, `signedOutReason`, `signIn()`, `signOut()` |
+| `useSiteInfo()` / `useMe()` | public site name + logo / the person, site features and `permissions` |
+| `useDocuments(query)` | infinite list (`kind`, `status`, `collection`, `q`); flat `items`, `total` |
+| `useCreateDocument()` | mutation: `{ kind, title, collection? \| start? }` |
+| `useDocument(kind, id)` | `document`, `save(fields)` (sends the loaded revision), `saving`, `conflict` (`server`, `mine`), `keepMine()`, `keepTheirs()` |
+| `usePublish(kind, id)` | `publish()` (Update for live docs with staged edits), `unpublish()`, `schedule(at)`, `discard()`, `action` |
+| `useSectionLayouts({ stage, pageId })` | pages with sections, definitions, revision, role |
+| `useSectionEditor(pageId, sectionId)` | `data`, `setField`, `dirty`, `issues`, `permissions`, `canEdit(key, sub?)`, `save()` (only changed fields), `publish()` (this section), `conflict`/`keepMine`/`keepTheirs`, `reset()` |
+| `useTranslations(target, locale)` | `units` (source, value, `missing`/`ai`/`reviewed`/`outdated`), `summary`, `set(values)`, `markReviewed(paths?)`, `aiDraft(paths?)` |
+| `useTranslationQueue(locale)` | sections + newest documents that still need a person |
+| `useMedia(query)` | infinite library, `upload(file)`, `pickAndUpload({ source, quality, aspect })` |
+| `useBookingsInbox({ status })` | infinite inbox, `pending`, `approve/decline/cancel(id, message?)` |
+| `useEditorClient()` | the typed bearer client for anything else |
+
+`target` is `{ kind, id }` for a post/page/event or `{ pageId, sectionId }`.
+Errors: `errorMessage(e)`, `isConflict(e)` (409), `isForbidden(e)` (403).
+
+Section saves are guarded by the design revision, which changes whenever
+anyone saves anything. `useSectionEditor` re-applies your changed fields on
+the latest copy automatically; only when someone changed the **same** fields
+does `conflict` ask. Documents never auto-merge.
+
+**Forms.** `<FieldInput field value onChange siblings role readOnly>` renders
+any section field type — `text`, `textarea`, `richtext`, `url`, `number`,
+`toggle`, `select` (option buttons, a sheet over 8 options), `date`, `time`,
+`link` (label, address, "Pick" a page/post/event → `ref`), `image` (media
+library or upload, tap to set the focal point `<key>__focus`), `list` (add,
+remove, reorder rows; `_id`s kept so translations follow rows), `source`
+(calendar / collection / resource from the site, tag, how many) — with the
+label, `required` marker, `maxLength` counter, help text, validation after
+blur, `visibleIf`, and read-only for editors when a field is `locked`.
+`<SectionFields definition data onChange permissions role>` renders a whole
+section. The rules are the server's (a dependency-free copy of
+`theme-sdk/fields.mjs` with a drift test): `normalizeData`, `valueIssues`,
+`fieldVisible`, `formIssues`, `sectionPermissions`, `translationUnits`, …
+
+**Rich text** edits "markdown-lite" and stores a safe HTML subset
+(`<p> <br> <strong> <em> <a href> <ul> <ol> <li> <h2> <h3> <blockquote>`):
+`**bold**`, `*italic*`, `[label](https://…)`, `- ` bullets, `1. ` numbers,
+`## ` headings, `> ` quotes, with a B / I / Link / List / H toolbar. HTML with
+anything richer (images, embeds, cards, tables, classes, nested lists) opens
+read-only with "Edit this on the website" (`richTextSupport(html)`), so the
+phone never silently drops content.
+
+Building blocks: `EditorButton`, `EditorInput`, `Segmented`, `Notice`,
+`StatusText`, `SectionLabel`, `ListRow`, `Card`, `Sheet`, `OptionGrid`,
+`MediaPicker`, `DocumentPicker`.
+
+### Cookbook (editor apps)
+
+**A screen of your own** (add `tools/notices.ts` so Home lists it):
+
+```tsx
+// app/notices.tsx: edit one section's "notice" text from Home
+import { EditorButton, FieldInput, Notice, errorMessage, useAuth, useSectionEditor } from '@acms-subir/native/editor';
+import { Screen } from '../components/Screen';
+
+export default function Notices() {
+  const { role } = useAuth();
+  const ed = useSectionEditor(PAGE_ID, SECTION_ID); // from useSectionLayouts(), never hardcoded content
+  if (!ed.definition) return null;
+  return (
+    <Screen>
+      <FieldInput field={ed.definition.fields.text} value={ed.data.text} onChange={(v) => ed.setField('text', v)}
+        role={role ?? undefined} readOnly={!ed.canEdit('text')} />
+      {!!ed.saveError && <Notice tone="error">{errorMessage(ed.saveError)}</Notice>}
+      <EditorButton variant="primary" label="Save and publish" busy={ed.saving || ed.publishing} onPress={() => ed.publish()} />
+    </Screen>
+  );
+}
+```
+
+**Only owners see a button:** `const { data: me } = useMe(); me?.permissions.sections.editLocked && <EditorButton … />`.
+
+**A data call the hooks don't cover:** `const api = useEditorClient();`
+then `useQuery({ queryKey: editorKey(baseUrl, user?.id, 'bookings-week'), queryFn: ({ signal }) => api.listBookings({ from }, { signal }) })`;
+keep keys under `editorKey(...)` so sign-out clears them.
+
+**Test sign-in on the web:** list `http://localhost/auth` in `redirectUris`,
+`npx expo start --web` in the app, sign in in the popup.
+
+### Recipes (editor apps)
+
+```sh
+npx acms mobile recipe add editor-content        # list, kind/status filters, search, publish/unpublish/discard
+npx acms mobile recipe add editor-writer         # new post/page/event, title/summary/body/tags/address, save, publish, schedule, conflicts
+npx acms mobile recipe add editor-sections       # page → section → form → save → publish this section (expo-image-picker)
+npx acms mobile recipe add editor-translations   # "Review Español": missing / AI drafts / outdated; edit beside the original, approve, AI draft
+npx acms mobile recipe add editor-media          # grid + upload from library or camera (expo-image-picker)
+npx acms mobile recipe add editor-bookings       # inbox: approve / decline / cancel with a message
+```
+
+Recipes know their app kind: client recipes refuse editor apps and the other
+way round; with both apps in the site, `recipe add` picks the matching one.
+Each adds a `tools/<name>.ts` entry, so it shows on Home. Tablets get list +
+detail side by side. Push for editors ("new booking", "draft to review") is
+not supported yet: the push API registers anonymous visitor devices only.
+
+### Rules for editor apps
+
+- Never ask for or store a password; never put the owner password, API keys
+  or agent keys in an app. Sign-in is `useAuth().signIn()`.
+- Tokens live only in secure storage through `<EditorProvider>` (never
+  AsyncStorage, files, logs, analytics or crash reports; only the
+  `Authorization` header). Don't read them into React state.
+- Hide what the role can't do (`useMe().data.permissions`, `canEdit`,
+  `permissions.canEditRows`), but always let the server decide; show 403 as
+  "your role can't do that".
+- Every write sends the revision you loaded; on 409 show the conflict and let
+  the person choose — never retry blindly over someone's work.
+- Same design rules as the client app: no pill shapes (8–12px rectangles,
+  text tabs, marker + text), no colored left-edge stripes, no gradient-squircle
+  logos; phones and tablets (≥ 768 uses the width).
+
+### Without the starter
+
+`@acms-subir/client` alone: `createEditorAuth` (authorize URL, `parseRedirect`
+with the state check, code exchange, refresh, revoke), `createEditorSession`
+(storage adapter, single-flight refresh) and `createEditorClient`. Pass
+expo-crypto as `crypto` when Web Crypto isn't available.
+
+`acms mobile doctor` checks editor apps too: expo-secure-store,
+expo-web-browser and expo-crypto installed; app.json's scheme gives a return
+address the site lists (from `.astro/acms-project.json`) and the running site
+has editor apps on; no tokens in AsyncStorage, no logged tokens, no password
+fields.
+
+## Deep links (universal / app links)
+
+1. Site: `acms({ mobile: { ios: { teamId, bundleId, paths }, android: { package, sha256CertFingerprints } } })`
+   in `astro.config.mjs`. The site then serves
+   `/.well-known/apple-app-site-association` and `/.well-known/assetlinks.json`.
+   `bundleId` / `package` must equal `app.json`. The Android fingerprint comes
+   from `npx eas-cli credentials` (the release signing key).
+2. App (`app.json`): `ios.associatedDomains: ["applinks:example.com"]`;
+   `android.intentFilters: [{ "action": "VIEW", "autoVerify": true, "data": [{ "scheme": "https", "host": "example.com" }], "category": ["BROWSABLE", "DEFAULT"] }]`;
+   `scheme` for `myapp://` links (the starter sets it).
+3. Expo Router opens `https://example.com/events/x` at the route
+   `app/events/[slug].tsx` when the file path matches. Map other site paths in
+   `app/+native-intent.tsx` (`export function redirectSystemPath({ path })`).
+
+Doctor checks that ids match and the files serve.
+
+## Test
+
+- iOS simulator, Android emulator and `npm run web` (web preview), light and
+  dark, phone and tablet sizes. Compare with the website: same sections,
+  same order, same words.
+- A real phone: `npx acms mobile dev` (same Wi-Fi or Tailscale).
+- `npx tsc --noEmit` in the app; `npx expo export --platform web` bundles.
+- `npx acms mobile doctor` (add `--offline` without network).
+
+## Release (EAS)
+
+```sh
+cd mobile
+npx eas-cli init                                     # links an EAS project
+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                    # and android
+```
+
+Store checklist: real `ios.bundleIdentifier` / `android.package` (can't change
+after release; doctor warns on `com.example.*`); app name, `icon` (1024×1024)
+and splash in `app.json`; `version` and build numbers bumped; `.env` points at
+the **https** production site; privacy policy URL; screenshots for phone and
+tablet; deep-link config deployed on the site; a production build tested on
+real devices; `acms mobile doctor` clean.
+
+## Doctor
+
+`npx acms mobile doctor [--dir mobile] [--url https://site] [--offline] [--json]`
+checks every app (or `--dir`): packages and versions compatible with the
+site's core, Expo SDK; the site URL is set, reachable from a phone and on the
+same API version; app ids and scheme; deep-link files; sections on the site's
+pages the app can't render; pages and calendars the app reads by slug that
+the site doesn't publish; secrets in source or env files; recipe packages
+(and for push: the `expo-notifications` plugin, `extra.eas.projectId`, and
+push turned on for the site).
+Exit 1 when anything fails. Network checks become warnings when the site is
+unreachable; `--offline` skips them.