minutework 0.1.20 → 0.1.21

package/EXTERNAL_ALPHA.md

@@ -140,7 +140,7 @@ The CLI does not fabricate success. If the backend cannot materialize a hosted p
 
 ## Machine-readable output (`--json`)
 
-`validate`, `compile`, `codegen`, and `deploy --preview` accept `--json` for unattended, agent-driven use. The command prints a single result envelope to stdout (`{ cliJsonVersion, command, ok, status, result, error }`) and nothing else; `ok` mirrors the exit code (fail-closed). `deploy --preview --json` never prompts — pair it with `--yes` to authorize, otherwise it returns `status: "confirmation_required"` and exits non-zero. The automatic bug report is suppressed in `--json` mode.
+`validate`, `compile`, `codegen`, `deploy --preview`, and `publish` accept `--json` for unattended, agent-driven use. The command prints a single result envelope to stdout (`{ cliJsonVersion, command, ok, status, result, error }`) and nothing else; `ok` mirrors the exit code (fail-closed). `deploy --preview --json` and `publish --json` never prompt — pair them with `--yes` to authorize, otherwise they return `status: "confirmation_required"` and exit non-zero. For `publish`, a rejected publication-review attestation is reported as `ok: false` with the gate findings in `result.findings` (a real review outcome, not a transport error). The automatic bug report is suppressed in `--json` mode.
 
 ## Failure semantics
 

package/README.md

@@ -1,17 +1,17 @@
 # `minutework`
 
-MinuteWork CLI for initializing a workspace, authenticating against a MinuteWork platform, linking a repo to a tenant-scoped public-site property, launching developer-local session broker flows, running local preview/test loops, and submitting hosted preview deploys.
+MinuteWork CLI for initializing a workspace, authenticating against a MinuteWork platform, linking a repo to a tenant-scoped public-site property, launching developer-local session broker flows, running local preview/test loops, submitting hosted preview deploys, and publishing app packs to the marketplace through the publication-review gate.
 
 ## External alpha scope
 
 The current external alpha is intentionally narrow:
 
-- Starter: `tenant-app`
+- Starters: `tenant-app` (the deployable web surface) and `mobile` (init-only)
 - Developer-local broker surface: `minutework session start|resume|status`
 - Hosted release class: `ssr_container`
 - Deploy surface: `minutework deploy --preview`
-- Deferred: `--live`, additional local coding engines, sidecar/runtime-backed deploys, marketplace publish flows
-- Reserved verb: `minutework publish` is present but **fails closed** (a typed `not_implemented` result) until the marketplace publication-review + attestation backend lands
+- Deferred: `--live`, additional local coding engines, sidecar/runtime-backed deploys, and the commercial marketplace listing/pricing layer
+- Marketplace publish: `minutework publish` submits the compiled, digest-bound app pack through the platform publication-review + attestation gate and publishes it to the public marketplace catalog **only** on an approved (or approved-with-warnings) attestation; a rejected attestation prints the review findings and exits 1 without publishing
 
 The shipped `tenant-app` starter is the combined web surface: public routes at
 the root plus a private `/app` workspace. Public-site content follows the
@@ -44,7 +44,20 @@ npx minutework login
 npx minutework link
 ```
 
-After `link`, the current alpha has two supported lanes.
+After `link`, the current alpha has two supported lanes (both `tenant-app`).
+
+For a native mobile client, scaffold the **`mobile`** starter instead:
+
+```bash
+npx minutework init my-app --starter mobile
+```
+
+It is **init-only** and bring-your-own-UI: a minimal Expo (React Native) client
+that authenticates **directly** against the platform with a native device-flow
+session token (PKCE authorize -> exchange -> bearer + refresh in the device
+keychain), not the `tenant-app` BFF cookie path. There is no `link`/`deploy`
+lane for it — distribution is your own EAS pipeline (`eas build`/`eas submit`,
+EAS Update), not `minutework deploy`.
 
 ### Developer-local broker lane
 

package/assets/claude-local/skills/README.md

@@ -32,6 +32,7 @@ Generated-workspace-first guidance should live here, especially:
 - `vuilder-public-site-authoring/SKILL.md`
 - `workspace-guidance-refresh/SKILL.md`
 - `shell-architecture/SKILL.md`
+- `standalone-mobile-client/SKILL.md`
 - `runtime-capability-inventory/SKILL.md`
 - `layering-and-import-modes/SKILL.md`
 - `capability-gap-reporting/SKILL.md`

package/assets/claude-local/skills/generated-workspace-architecture/SKILL.md

@@ -19,9 +19,17 @@ the monorepo or a live tenant runtime.
   - app packs
   - skills
   - tenant overlays
-- `tenant-app` and optional `sidecar` are implementation surfaces inside the
-  tenant product, not the whole architecture.
+- `tenant-app`, optional `sidecar`, and the optional `mobile` starter are
+  implementation surfaces inside the tenant product, not the whole architecture.
 - `tenant-app` is the combined public plus private web starter.
+- A mobile / native client (Expo, React Native, native iOS/Android) is a
+  standalone-client exception authored in the `mobile` starter, not in
+  `tenant-app` or `sidecar`. It is a direct platform API client that consumes
+  the platform native-token API (`/api/v1/native/...`) directly with a
+  platform-issued native session token, rather than the `tenant-app` BFF cookie
+  session.
+- If the `mobile` starter is enabled (`starters.mobile.enabled`), read
+  `standalone-mobile-client/SKILL.md` before proposing the mobile surface.
 - `vuilder-public-site` is a Vuilder-owned public-site authoring workspace for
   landing, blog, and onboarding routes backed by public-dj CMS manifests.
 - If `template_kind` is `vuilder-public-site`, or the workspace profile says

package/assets/claude-local/skills/shell-architecture/SKILL.md

@@ -44,6 +44,9 @@ threads, channels, inboxes, guest collaboration, approvals, dashboards, or
   - the surface is public marketing
   - the surface is public intake for non-members
   - the surface is an embeddable widget
+  - the surface is a mobile app (Expo / React Native / native iOS/Android) ->
+    author in the `mobile` starter, not `tenant-app`; see
+    `standalone-mobile-client/SKILL.md`
 - If shell fit is correct but this generated workspace cannot directly author
   the shell extension, keep the shell-first recommendation and record a
   capability gap instead of silently converting the request into standalone

package/assets/claude-local/skills/standalone-mobile-client/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: standalone-mobile-client
+description: "Building a native mobile app (Expo / React Native / native iOS/Android). It is a standalone-client exception authored in the mobile starter as a direct platform API client using a native session token, not in tenant-app or sidecar."
+---
+
+# Standalone Mobile Client
+
+Use this skill when the request is "can I build a mobile app?", or anything
+that involves a native iOS/Android surface (Expo, React Native, or fully native).
+The answer is yes, and the shape is fixed. Do not flip-flop on it.
+
+## Where it lives
+
+- A native mobile app is a **standalone-client exception**. It is authored in
+  the `mobile` starter (`destinationDirectory: mobile`), enabled via the
+  workspace config key `starters.mobile = { enabled: true, path: "mobile" }`.
+- It is **not** part of `tenant-app`, and **not** part of `sidecar`. Do not put
+  native code, Expo config, or React Native screens inside either of those
+  surfaces.
+- `tenant-app` stays web-only. The mobile app is a sibling client, not a tab or
+  route inside the web BFF.
+
+## What it is
+
+- The mobile app is a **direct platform API client**. It talks to the platform
+  HTTP API at `/api/v1/native/session/...` and nothing else. It does not go
+  through the `tenant-app` BFF.
+- Authentication uses a platform-issued **native session token** -- a distinct
+  principal class, the "native app session token holder". This is exactly what
+  the auth contract anticipates: non-browser clients must mint explicit scoped
+  tokens after browser-assisted login or a device flow
+  (`reference/mwv3-dj6-docs/auth_and_credential_contract.md`, Rule 7).
+- The app reads the platform base URL from `EXPO_PUBLIC_MW_PLATFORM_BASE_URL`.
+
+## Endpoints (shipped)
+
+All native endpoints live under `/api/v1/native/session/`:
+
+- `authorize/` -- browser-assisted consent (GET renders the login/consent page
+  or redirects to the onboarding host; POST confirms and 302-redirects to the
+  app `redirect_uri` with `?code=...&state=...`).
+- `token-exchange/` -- POST `{code, code_verifier, redirect_uri}` -> `{access,
+  refresh, expires_at, ...}`. No bearer required.
+- `refresh/` -- POST `{refresh_token}` -> a new `{access, refresh}` pair. No
+  bearer required.
+- `me/` and `context/` -- GET (bearer) -> the tenant session payload for the
+  bound user/tenant. `context/` is currently identical to `me/`.
+- `logout/` -- POST (bearer) -> revokes the presented token's access/refresh
+  family.
+
+## Auth flow
+
+The native token flow mirrors the existing CLI developer-token flow
+(PKCE authorize -> exchange -> opaque scoped tokens):
+
+1. **Authorize (browser-assisted device flow):** the app generates a PKCE
+   verifier and opens `GET /api/v1/native/session/authorize/` (with
+   `code_challenge`, `state`, `redirect_uri`) in a system browser. The user logs
+   in and confirms on the platform; the platform POSTs the confirmation and
+   302-redirects back to the app's `redirect_uri` with a one-time `code` and the
+   `state`.
+2. **Exchange:** the app POSTs that one-time `code` plus the matching PKCE
+   `code_verifier` and the same `redirect_uri` to
+   `/api/v1/native/session/token-exchange/`, receiving an **access token +
+   refresh token** (opaque, scoped; access ~15 min, refresh ~30 days).
+3. **Store:** both tokens are persisted in `expo-secure-store` (the device
+   keystore), never in plain React/web state.
+4. **Call:** every request to `/api/v1/native/session/...` carries
+   `Authorization: Bearer <access>`.
+5. **Refresh:** on access-token expiry (`401`), POST the refresh token to
+   `/api/v1/native/session/refresh/` to mint a new pair, then retry. Refresh is
+   **rotating** -- the old access/refresh family is revoked, so persist the
+   freshly returned pair. Re-run the browser-assisted authorize step only when
+   the refresh token itself is invalid or revoked.
+
+The browser/BFF cookie path belongs to `tenant-app` and is **web-only**. The
+mobile app does not ride the `tenant-app` cookie jar, and it does not read or
+forward CSRF -- native uses the bearer token directly against the platform.
+
+### Token binding (what is and isn't enforced)
+
+The token is bound to one tenant + membership, and that binding **is** enforced:
+a request that names a different tenant is rejected, and a token whose membership
+has been deactivated stops authenticating. The optional `audience` and
+`device_id` fields are **informational only** -- the platform carries them
+through authorize -> exchange (and preserves them across refresh) but does **not**
+validate or compare them. Do not treat `audience` or `device_id` as a security
+boundary.
+
+## What not to do
+
+- Do not build a parallel auth stack.
+- Do not mint a JWT inside the app or stand up a local user table / token issuer.
+- Do not expose access or refresh tokens to web pages or generic React state;
+  keep them in `expo-secure-store`.
+- Do not route the mobile app through the `tenant-app` BFF cookie session.
+- Do not read or forward CSRF from native; bearer-token auth does not use it.
+- Do not put native code inside `tenant-app` or `sidecar`.
+
+## Distribution
+
+- The `mobile` starter is **init-only**. Scaffolding it lands the app in the
+  workspace; it does not deploy it.
+- Distribution is the developer's own pipeline: EAS Build, TestFlight, and the
+  Play Store. It is **not** `minutework deploy`.

package/assets/templates/mobile-app/.env.example

@@ -0,0 +1,16 @@
+# DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.
+#
+# Copy this file to `.env` and set the values for your environment.
+#
+# Only EXPO_PUBLIC_* variables are exposed to the app bundle. They are NOT
+# secret — anyone with the app binary can read them. Put only non-secret config
+# here. Never add API keys, client secrets, or tokens as EXPO_PUBLIC_* values;
+# the platform issues short-lived bearer tokens at runtime via the native
+# device flow.
+
+# Base URL of the MinuteWork platform this app talks to directly
+# (e.g. https://platform.minutework.dev). The app calls /api/v1/native/... here.
+EXPO_PUBLIC_MW_PLATFORM_BASE_URL=https://<your-platform-base-url>
+
+# Optional display name shown in the UI. Defaults to "MinuteWork".
+# EXPO_PUBLIC_MW_APP_NAME=MinuteWork

package/assets/templates/mobile-app/AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md — mobile-app starter
+
+You are working in a **bring-your-own-UI Expo (React Native + Expo Router)**
+app. **You own all UI/UX.** The only MinuteWork-managed code is the thin
+substrate under `src/mw/`.
+
+## The one rule
+
+**Only `src/mw/` is MinuteWork substrate.** Build your product in `app/` and your
+own components/modules. Do not move product logic into `src/mw/`, and do not
+build a parallel/local auth stack — the platform owns identity. The mobile app
+is a **direct platform native API client** (bearer token to `/api/v1/native/...`),
+**not** a `tenant-app` BFF cookie client and **not** a `sidecar`.
+
+## Use your IDE's Expo skills
+
+For the native craft (UI, data, build/release), lean on your local IDE skills:
+
+- `building-native-ui` — Expo Router UI, styling, navigation, animations
+- `native-data-fetching` — fetch/React Query/SWR, caching, offline, loaders
+- `expo-deployment` — App Store / Play Store / EAS distribution
+- `expo-dev-client` — custom dev client (needed for the browser-assisted auth flow)
+- `expo-tailwind-setup` — NativeWind/Tailwind if you want utility styling
+- `push-notification-setup` — APNs/FCM push
+- `upgrading-expo` — SDK upgrades and dependency fixes
+- `expo-cicd-workflows` — EAS build/deploy pipelines (`.eas/workflows/`)
+
+## MinuteWork integration shape
+
+For how this app fits the platform (the standalone-client exception, the native
+session token, and the device flow), read the Builder skill
+**`standalone-mobile-client`** (in the Builder bundle) and the auth contract
+`reference/mwv3-dj6-docs/auth_and_credential_contract.md` (Rule 7: non-browser
+clients mint explicit scoped tokens after browser-assisted login / a device
+flow).
+
+## Status
+
+`src/mw/client.ts` and `src/mw/session.ts` are **implemented**: a real
+browser-assisted PKCE device flow against the platform native session endpoints
+(`/api/v1/native/session/*`), with tokens persisted in the device keychain via
+`expo-secure-store`. Wire your UI against the documented client methods
+(`authorize` -> `exchange`, `loadSession`, `logout`). Set `app.json` `expo.scheme`
+to your own unique scheme — that is the OAuth-style redirect target.

package/assets/templates/mobile-app/README.md

@@ -0,0 +1,123 @@
+# Mobile App Starter (Expo, bring-your-own-UI)
+
+A minimal **Expo (React Native + Expo Router)** starter for building a native
+MinuteWork client. **You own all of the UI/UX.** The only MinuteWork-managed
+code is the thin substrate under `src/mw/`. Everything else in this template is
+a deliberately plain placeholder meant to be replaced.
+
+There is **no MinuteWork design system here** — bring your own. Style with
+whatever you like (plain `StyleSheet`, NativeWind/Tailwind, Tamagui, etc.). The
+plain screens use `StyleSheet` only so there is nothing to rip out.
+
+## What's substrate vs. yours
+
+| Path | Owner | Notes |
+| --- | --- | --- |
+| `src/mw/env.ts` | **MinuteWork substrate** | Validates `EXPO_PUBLIC_MW_PLATFORM_BASE_URL` (+ optional app name) |
+| `src/mw/endpoints.ts` | **MinuteWork substrate** | Builds platform `/api/v1/native/...` URLs |
+| `src/mw/contracts.ts` | **MinuteWork substrate** | Zod schemas for native session + token payloads |
+| `src/mw/client.ts` | **MinuteWork substrate** | Native token client — real browser-assisted PKCE device flow |
+| `src/mw/session.ts` | **MinuteWork substrate** | Secure-store token wrapper (`expo-secure-store`) |
+| `tools/template/` | **MinuteWork substrate** | Template-governance tooling, not shipped app code |
+| `app/**` | **You** | Expo Router screens — replace freely |
+| `package.json`, `app.json`, `eas.json` | **You** | App config — replace freely |
+| `tsconfig.json`, `babel.config.js`, `metro.config.js` | **You** | Tooling config — replace freely |
+
+Rule of thumb: **only `src/mw/` is MinuteWork substrate.** If you find yourself
+editing `src/mw/` to add product behavior, that behavior probably belongs in
+your own `app/` / components instead.
+
+## Auth model (read this)
+
+This app authenticates as a **direct platform native client**:
+
+- The platform issues a **bearer token** to the device through a
+  **browser-assisted PKCE device flow**: `GET /api/v1/native/session/authorize/`
+  (with a PKCE `code_challenge`) opens in a system browser; after login/consent
+  the platform redirects back with a one-time `code`, which you exchange at
+  `POST /api/v1/native/session/token-exchange/` (with the PKCE `code_verifier`)
+  for an `{access, refresh, expires_at}` pair, then store in the device keychain
+  via `expo-secure-store`.
+- The app then calls the platform **directly** (e.g.
+  `GET /api/v1/native/session/me/` or `.../context/`) with
+  `Authorization: Bearer <access>`, and on `401` mints a fresh pair at
+  `POST /api/v1/native/session/refresh/` (rotating — persist the new pair) before
+  retrying. `POST /api/v1/native/session/logout/` revokes the token family.
+
+This is **NOT** the Next.js `tenant-app` model. The tenant-app uses a
+server-owned **BFF session cookie** (`platform_session_bff`) because a browser
+can't safely hold tokens. A native app has secure device storage and no
+per-app server in front of it, so it talks to the platform API directly with a
+token instead of a cookie. **Do not** try to reuse the BFF cookie path here, and
+**do not** build a parallel/local auth stack (no JWT minting, no local user
+table) — the platform owns identity.
+
+The token is bound to a single tenant + membership, and that binding **is**
+enforced. The optional `audience` and `device_id` fields are **informational
+only**: the platform carries them through the flow but does **not** validate or
+compare them, so do not rely on them as a security boundary.
+
+### The auth client is real — configure your redirect scheme
+
+`src/mw/client.ts` and `src/mw/session.ts` are **implemented**. The client:
+
+- generates a PKCE `code_verifier` + S256 `code_challenge` (`expo-crypto`),
+- opens the platform `authorize` URL in a system browser
+  (`expo-web-browser`'s `openAuthSessionAsync`) with an anti-forgery `state`,
+- captures the returned one-time `code` from the deep-link redirect, exchanges
+  it (plus the `code_verifier`) for a token pair, and stores it in the device
+  keychain (`expo-secure-store`),
+- sends `Authorization: Bearer <access>` on every platform call and
+  auto-refreshes once on a `401`, and
+- revokes + clears local storage on `logout()`.
+
+The redirect target is your app's deep-link scheme. The starter ships
+`"scheme": "mobileapp"` in `app.json`, so the redirect is
+`mobileapp://auth/native-callback` (built at runtime via `expo-linking`'s
+`createURL`). **Set `app.json` `expo.scheme` to your own unique scheme** before
+shipping; the client follows whatever you configure, and a unique scheme avoids
+collisions with other apps that could intercept the callback. The browser-based
+flow needs a custom dev client (not stock Expo Go) — see the `expo-dev-client`
+IDE skill.
+
+The full flow is documented in the doc-comment at the top of `src/mw/client.ts`.
+
+## Environment
+
+Copy `.env.example` to `.env` and set:
+
+```
+EXPO_PUBLIC_MW_PLATFORM_BASE_URL=https://<your-platform-base-url>
+```
+
+Only `EXPO_PUBLIC_*` variables are bundled into the app, and they are **not
+secret** — never put keys/tokens in them. `src/mw/env.ts` validates this value
+at startup with zod and fails fast if it's missing or not a URL.
+
+## Running locally
+
+```
+npm install        # or pnpm/yarn/bun
+npm run start       # Expo dev server (then press i / a, or scan with Expo Go)
+npm run ios
+npm run android
+npm run typecheck   # tsc --noEmit
+```
+
+The native auth flow opens a system browser, which needs a custom dev client
+rather than stock Expo Go; see the `expo-dev-client` IDE skill.
+
+## Distribution
+
+**Distribution is your EAS pipeline, not `minutework deploy`.** This starter is
+not a hosted web/sidecar deployable; it produces native binaries. Build and ship
+with EAS (`eas build`, `eas submit`, EAS Update). `eas.json` ships minimal
+`preview` and `production` profiles to start from. See the `expo-deployment` and
+`expo-cicd-workflows` IDE skills.
+
+## Template manifest
+
+`template.json` declares `template_kind: "mobile-app"` and `deployable: false`.
+Because mobile is not a web/sidecar deployable, it is validated by
+`tools/template/validate-template.mjs` (run `node tools/template/validate-template.mjs`),
+**not** the strict shared `runtime/builder/templates/template.schema.json`.

package/assets/templates/mobile-app/app/(app)/_layout.tsx

@@ -0,0 +1,10 @@
+// DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.
+//
+// Authed area layout. This is where you'd guard on a loaded MinuteWork session
+// (via `mwClient.loadSession()`) and redirect to /(auth)/login when there is no
+// valid token. Left as a plain Stack so you can build your own gating/UX.
+import { Stack } from "expo-router";
+
+export default function AppLayout() {
+  return <Stack screenOptions={{ headerShown: false }} />;
+}

package/assets/templates/mobile-app/app/(app)/index.tsx

@@ -0,0 +1,72 @@
+// DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.
+//
+// Trivial authed screen. Replace with your real product home. Build your data
+// fetching against the platform native API using the bearer token from
+// `src/mw/` (see the `native-data-fetching` IDE skill).
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { router } from "expo-router";
+
+import { mwClient } from "@/mw/client";
+
+export default function HomeScreen() {
+  async function onSignOut() {
+    try {
+      await mwClient.logout();
+    } finally {
+      router.replace("/(auth)/login");
+    }
+  }
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>You are in.</Text>
+      <Text style={styles.body}>
+        Replace this screen with your product. Only `src/mw/` is MinuteWork
+        substrate — everything else is yours.
+      </Text>
+
+      <Pressable
+        accessibilityRole="button"
+        onPress={onSignOut}
+        style={({ pressed }) => [styles.button, pressed && styles.buttonPressed]}
+      >
+        <Text style={styles.buttonText}>Sign out</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    padding: 24,
+    gap: 12,
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: "700",
+  },
+  body: {
+    fontSize: 15,
+    opacity: 0.7,
+    textAlign: "center",
+  },
+  button: {
+    marginTop: 16,
+    paddingVertical: 12,
+    paddingHorizontal: 20,
+    borderRadius: 10,
+    borderWidth: 1,
+    borderColor: "#111827",
+  },
+  buttonPressed: {
+    opacity: 0.6,
+  },
+  buttonText: {
+    fontSize: 15,
+    fontWeight: "600",
+    color: "#111827",
+  },
+});

package/assets/templates/mobile-app/app/(auth)/login.tsx

@@ -0,0 +1,91 @@
+// DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.
+//
+// This screen is intentionally plain and is meant to be REWRITTEN. It exists to
+// show the one integration seam you care about: kicking off MinuteWork's
+// browser-assisted native sign-in through `src/mw/client.ts`.
+//
+// Pressing "Sign in" runs the real device flow: authorize in a system browser ->
+// exchange the returned code for a platform bearer token pair -> route into the
+// authed stack. Wire your own UI/UX around this call.
+import { useState } from "react";
+import { Alert, Pressable, StyleSheet, Text, View } from "react-native";
+import { router } from "expo-router";
+
+import { mwClient } from "@/mw/client";
+import { mwEnv } from "@/mw/env";
+
+export default function LoginScreen() {
+  const [busy, setBusy] = useState(false);
+
+  async function onSignIn() {
+    setBusy(true);
+    try {
+      // Device flow: authorize (browser) -> exchange code+verifier for tokens
+      // (stored in the keychain by the client), then route into the authed stack.
+      const { code, codeVerifier, redirectUri } = await mwClient.authorize();
+      await mwClient.exchange(code, codeVerifier, redirectUri);
+      router.replace("/(app)");
+    } catch (error) {
+      Alert.alert(
+        "Sign in unavailable",
+        error instanceof Error ? error.message : "Unknown error",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>{mwEnv.appName}</Text>
+      <Text style={styles.subtitle}>Sign in to continue</Text>
+
+      <Pressable
+        accessibilityRole="button"
+        disabled={busy}
+        onPress={onSignIn}
+        style={({ pressed }) => [
+          styles.button,
+          (pressed || busy) && styles.buttonPressed,
+        ]}
+      >
+        <Text style={styles.buttonText}>
+          {busy ? "Opening sign in…" : "Sign in with MinuteWork"}
+        </Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    padding: 24,
+    gap: 12,
+  },
+  title: {
+    fontSize: 28,
+    fontWeight: "700",
+  },
+  subtitle: {
+    fontSize: 16,
+    opacity: 0.7,
+    marginBottom: 12,
+  },
+  button: {
+    backgroundColor: "#111827",
+    paddingVertical: 14,
+    paddingHorizontal: 24,
+    borderRadius: 10,
+  },
+  buttonPressed: {
+    opacity: 0.6,
+  },
+  buttonText: {
+    color: "#ffffff",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+});

package/assets/templates/mobile-app/app/_layout.tsx

@@ -0,0 +1,15 @@
+// DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.
+import { Stack } from "expo-router";
+import { StatusBar } from "expo-status-bar";
+
+export default function RootLayout() {
+  return (
+    <>
+      <Stack screenOptions={{ headerShown: false }}>
+        <Stack.Screen name="(auth)/login" />
+        <Stack.Screen name="(app)" />
+      </Stack>
+      <StatusBar style="auto" />
+    </>
+  );
+}

package/assets/templates/mobile-app/app.json

@@ -0,0 +1,31 @@
+{
+  "//": "DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.",
+  "//scheme": "expo.scheme is the OAuth-style redirect target for the native auth device flow (src/mw/client.ts builds <scheme>://auth/native-callback). Set a unique scheme before shipping.",
+  "expo": {
+    "name": "mobile-app",
+    "slug": "mobile-app",
+    "scheme": "mobileapp",
+    "version": "0.1.0",
+    "orientation": "portrait",
+    "userInterfaceStyle": "automatic",
+    "newArchEnabled": true,
+    "ios": {
+      "supportsTablet": true,
+      "bundleIdentifier": "com.example.mobileapp"
+    },
+    "android": {
+      "package": "com.example.mobileapp"
+    },
+    "web": {
+      "bundler": "metro",
+      "output": "static"
+    },
+    "plugins": [
+      "expo-router",
+      "expo-secure-store"
+    ],
+    "experiments": {
+      "typedRoutes": true
+    }
+  }
+}

package/assets/templates/mobile-app/babel.config.js

@@ -0,0 +1,7 @@
+// DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ["babel-preset-expo"],
+  };
+};

package/assets/templates/mobile-app/eas.json

@@ -0,0 +1,24 @@
+{
+  "//": "DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate. Distribution is YOUR EAS pipeline, not `minutework deploy`.",
+  "cli": {
+    "version": ">= 12.0.0",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal",
+      "channel": "preview"
+    },
+    "production": {
+      "channel": "production",
+      "autoIncrement": true
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}

package/assets/templates/mobile-app/expo-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="expo/types" />
+
+// DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.
+// NOTE: This file should not be edited and should be committed; Expo regenerates
+// it. It gives `process.env.EXPO_PUBLIC_*` string typings for `src/mw/env.ts`.

package/assets/templates/mobile-app/metro.config.js

@@ -0,0 +1,7 @@
+// DEVELOPER-OWNED — replace freely. Only src/mw/ is MinuteWork substrate.
+// Default Expo Metro config. Customize bundling/resolver here if you need to.
+const { getDefaultConfig } = require("expo/metro-config");
+
+const config = getDefaultConfig(__dirname);
+
+module.exports = config;