@moifort/stack 0.0.0-stage → 0.1.0

package/rules/10-ios.md

@@ -0,0 +1,206 @@
+# iOS
+
+SwiftUI, Swift 6 strict concurrency, Apollo iOS for typed operations generated into
+`Generated/GraphQL/` (never edited), Firebase Auth with Sign in with Apple, Sentry. Xcode file
+system synchronised groups: a new file is picked up without touching the project. Long form in the
+`ios-feature` skill.
+
+## The one rule
+
+**A view is either pure or connected, and its name says which.**
+
+- **Pure**: receives values and actions, draws them. No API call, no fetching `.task`, no
+  `.shared` singleton, no notification centre. Renders in a `#Preview` from fixtures alone.
+  Everything under `components/` and `Shared/Components/` is pure, and
+  `bun run ios:components` fails the build when it is not.
+- **Connected**: the `{Feature}Screen` at the root of a feature. It owns the ViewModel, the
+  tasks, the change notices, the navigation and the sheets, and hands values and actions to its
+  `Page`. It draws nothing of its own.
+
+## Layout
+
+```
+Shared/Components/{atoms,molecules,organisms,styles}/   design system, pure
+Shared/Platform/            UIKit wrappers: camera, mail composer, web view
+Shared/Shell/               the app around the tabs: launch curtain, update-required screen
+Features/{Domain}/
+  {Feature}Screen.swift     connected
+  {Feature}ViewModel.swift  state and actions, init(client:)
+  {Domain}Client.swift      struct of async closures, .live and .preview
+  {Domain}API.swift         GraphQL operations to app models, the only file that sees Apollo types
+  {Domain}Models.swift      Sendable app models
+  {Domain}Fixtures.swift    preview and test data
+  components/{organisms,pages}/
+```
+
+- Domains follow the business, not the tabs. A component another domain needs is imported, not
+  copied.
+- Atoms and molecules live only in `Shared/`; a domain holds organisms and pages. A component
+  small enough to be an atom carries no business meaning.
+- Naming carries the category: `Screen` connected, `Page` pure whole screen, `Section`, `Card`,
+  `Strip`, `Row`, `Tile` for organisms and molecules. A file named `…View` says nothing; new
+  files never use it, except the UIKit wrappers named after what they wrap.
+- One component per file, named after it. A private helper only that file uses may stay.
+
+## Screen, page, action
+
+- **One `onAction` per page, over an `enum`.** The screen's `switch` is exhaustive: an action
+  added to the page and forgotten in the screen does not compile. A page with a dozen optional
+  closures compiles with one left unwired. An organism with one or two actions takes plain
+  closures.
+- An action the page waits on is `async`, awaited through `AsyncButton` / `AsyncToolbarButton`,
+  which draw the progress and disable the control. A page whose actions only open or switch takes
+  a plain closure.
+- Navigation state (which sheet, which destination) lives in the screen; the page only says what
+  was tapped.
+- Leaves take primitives (`String`, `Int?`, `Date?`, `Bool`, a logic-free enum, closures), never a
+  domain struct; an organism may take a domain model and is the mapping boundary. Beyond about
+  five parameters, a nested `Item` struct.
+
+## ViewModel and client
+
+- The client is a **struct of `@Sendable` closures** with `.live` and `.preview`, not a protocol:
+  a test builds the client it needs inline, overriding one closure.
+- The ViewModel is `@MainActor @Observable`, state `private(set)`, errors through the shared
+  `reportError()`, never a generated type in sight.
+- Business logic leaves the views: "look it up, then add it" exists once, as a client call or a
+  domain function; formatting a line is a pure function on the model.
+- No singleton read in a component: app services are read by the screen and passed down, or
+  injected through the environment.
+
+## Loading and failures
+
+Every network call shows that it runs, except a refresh over content already on screen. A list
+with nothing yet shows a `ProgressView` in its body, never full screen over the chrome. A button
+that triggers a mutation shows its progress and is disabled while it runs.
+
+- Over content already on screen, a failure says nothing: the rows stay. Replacing a good list
+  with an empty one reads as data loss. The error still goes to Sentry.
+- Over an empty screen, `EmptyState.failure(title, message, retry)`.
+- Every screen that loads is pullable: refresh is the retry.
+- A cancellation is not a failure: check it and return.
+
+## Snapshots
+
+**Only for a screen that changes slowly and that the person recognises** (a library, a list of
+series): it keeps what it showed last on disk and reopens on it. Never for a screen whose state
+must be exact at opening (a quota, a subscription, an inventory count, a cart): a stale snapshot
+there misleads. When it applies: read synchronously in the ViewModel's `init`, written after each
+successful load off the main actor, one file per view and filter, **never more than the first
+page**, versioned (bump when the type changes shape; an older file is ignored), cleared at
+sign-out and account deletion. The refresh that follows animates rows into place. Images are
+cached by what they are, not by their signed URL. No normalised client cache beyond this.
+
+## Pagination
+
+Long lists load by **cursor, never offset**: an offset shifts under a list that changed between
+two pages. Page size is sized to the screen, not the dataset; the server caps a page. Prefetch
+before the end, well below the page size. A load-more row closes the list while there is more,
+with a retry once a page failed. **A page asked before a reload is never appended to the list that
+replaced it**, and an edit deep in a list never shrinks it. The mechanisms Shiori uses for that
+(generation token, reload keeping depth, patching a named row) are in the `ios-feature` skill as
+a pattern to copy, not a requirement.
+
+## Change notices
+
+Every mutation goes through one helper that posts a single data-changed notice once the write
+landed, carrying what changed when it is one row. Only screens listen; a page never subscribes.
+Coming back to a tab asks nothing once the server has answered.
+
+## Previews and tests
+
+Every view has a `#Preview`: atoms, molecules, organisms, pages, one per state that matters.
+Fixtures sit beside their type as `static let preview` or in `{Domain}Fixtures.swift`; tests reuse
+them. A view that resists previewing is a design smell: pull the pure part out. Previews check
+how a view looks; unit tests check what the app decides: ViewModels with an inline fake client
+(state after a load, after a failure over rows and over nothing, a stale page dropped, a row
+patched), and pure functions on models. Never a test of a SwiftUI `body`. A cached ViewModel takes
+a no-cache option in tests. The unit test target runs in CI on every push.
+
+## Design conventions
+
+- Screens showing the same kind of object compose the same shared parts (the read-only header,
+  labelled info rows, the status banner); only known fields are drawn; never a bespoke layout.
+- An upcoming or announced date is orange, an available one green. A destructive button's icon is
+  red too (a row label style keeps it accent blue unless coloured).
+- Icons beside a title and a description sit at the **top** of the row, never centred.
+- **No hint text under sections**: no footer explaining a picker. A message that matters in one
+  state is a row inside the section, shown only in that state.
+- Toolbar actions are icon-only, titles kept for VoiceOver; cancel on the left, confirm on the
+  right.
+- A tappable row answers on its whole width: a `.plain` button whose label carries
+  `.contentShape(.rect)`, set in the row view. Never `onTapGesture` in place of a button.
+- Native components, no custom re-skins.
+- **Accessibility**: every icon without text carries a label; every component is checked once
+  at the largest Dynamic Type size (text wraps, nothing is clipped, nothing overlaps); colours
+  never carry a meaning alone (orange and green dates also say it in words).
+
+## Screen patterns
+
+The shapes every app repeats, so they are not re-explained per project. Code in the
+`ios-feature` skill and in the shared component package.
+
+**A list row.** Image or icon on the left; the text block **top-aligned** beside it: title, one
+secondary line, at most one tag; a status tag in the top corner when the list is not already
+sectioned by it. The whole row opens the detail page. The one frequent action is a swipe action;
+the context menu mirrors the detail page's menu. A row never carries more than three pieces of
+information below its title: the rest belongs to the detail page.
+
+**A detail page (fiche).** Opened from a row as a sheet, or pushed when it is the tab's own
+object. From top to bottom: a header section (image, title, one line under it, the state), the
+facts as labelled rows with an icon (long press copies the value), the long text, the actions
+that belong to the object. **The toolbar**: close (`xmark`) on the left; on the right, the one
+action the person takes over and over as its own icon (a favourite heart, a check), then a `…`
+menu with the rest, edit first, delete last and red. A single fact is edited **inline in its
+row** (tap, type, done), never through a form; the full edit form is one sheet from the menu.
+Only known fields are drawn: an absent fact has no row, not an empty one.
+
+**A tab's main screen.** Large title, icon-only actions on the right (add, filter, settings),
+search attached to the list when there is one, sections with plain headers, the empty state
+drawn in the list body with the one action that fills it.
+
+**A form or a sheet that asks something.** Cancel (`xmark`) left, confirm (`checkmark`) right as
+an `AsyncToolbarButton`; the first field focused on appear; a picker shows its current value in
+its row; destructive confirmation as a dialog, never a toggle.
+
+## Shared component package
+
+The pure atoms, molecules and styles that carry no business meaning live in the shared Swift
+package `PolyformsUI`, versioned by tag and tracked by Renovate like any dependency:
+`AsyncButton`, `AsyncToolbarButton`, `ToolbarIconButton`, `EmptyState`, `LabeledInfoRow`,
+`LoadMoreRow`, `MenuPicker`, `SegmentedBar`, `TagList`, `RowChip`, `WidgetCard`, star ratings,
+the row and caption label styles, `Copyable`, the edge-to-edge separator, the AI glow. Each ships
+with its preview, and the package carries a catalogue app showing every component in every
+state. An app's `Shared/Components/` holds only what is specific to that app; a component that
+turns out generic moves up to the package with a version bump. Organisms (a book row, a cover
+tile) stay in their app: they carry the product.
+
+## Build and capture
+
+```bash
+bun run ios:build
+```
+
+- Never clear the build cache to unblock a broken build; diagnose the cause.
+- A build into a fresh derived data path needs `SWIFT_ENABLE_EXPLICIT_MODULES=NO` when Sentry's
+  import fails on CoreTelephony. Use a derived data path unique to the session for screenshot
+  builds: parallel sessions share the simulators and `/tmp`.
+- `DEVELOPER_DIR` is required when `xcode-select` points at the Command Line Tools.
+- A fresh worktree lacks the gitignored generated client, secrets file, Firebase plist and
+  package resolution: copy them from the main checkout.
+- Apollo codegen is the CLI bundled in the package checkout under derived data, not on PATH; after
+  a `.graphql` change, run it before any build or install. Loop until the namespace file exists.
+
+## Physical device
+
+The install on the person's phone closes a task that touched the app, once the screenshot of the
+change is approved, never before:
+
+- **App only**: install right away, before any push. The phone talks to production, which has
+  not changed.
+- **Backend and app**: install after the push, once the Deploy workflow is green. Installing
+  earlier ships an app against a server that does not have its changes yet.
+
+Clean tree: run the install script in place. Dirty tree with another session's work: build HEAD
+from a worktree. Run the API codegen first after a schema change. Relay the raw build and install
+output; no success claim without it.

package/rules/11-ops.md

@@ -0,0 +1,114 @@
+# Operations
+
+## Deployment goes through CI only
+
+Never `terraform apply`, never a backend deploy, never a migration from the local machine. The
+Deploy workflow on a push to `main` is the only path to production: build, `terraform
+apply`, then `POST /admin/migrate`. If production looks stale, `gh run list --workflow deploy.yml`
+first; fix the pipeline, never the machine.
+
+## Migrations
+
+Forward-only, sequential, no rollback, in `server/system/migration/migrations/`, registered in
+its index, tracked in a `migration-meta` collection, triggered by `POST /admin/migrate` from the
+Deploy workflow right after `terraform apply`. After a push that adds one, read that step's log
+line (`{"outcome":"migrated","from":7,"to":8,"applied":1}`) instead of telling anyone to run it.
+
+Between the push and the end of the deploy, a local server runs new code against unmigrated data:
+errors in that window are expected.
+
+**Migrate when** renaming a field, changing its structure, changing enum values, removing stale
+data. **No migration** for a new optional field, a new collection, or changed query logic. Every
+migration has its `.int.test.ts`.
+
+## Indexes
+
+Indexes follow queries: when a query changes, add the indexes it needs and drop the dead ones.
+Only the necessary: a sort done in memory after the read needs none. The index file is the source
+of truth read by Terraform, not a console action.
+
+## API evolution
+
+The GraphQL schema is not versioned: installed builds keep asking for what they were built
+against, for weeks after a release. So the schema only grows, and what the app stops using leaves
+in two steps.
+
+1. **Deprecate, in the commit where the app stops asking.** The operations stop selecting the
+   field or argument; the server marks it with a `deprecationReason` that names the version and
+   the date it was deprecated and what replaces it (`"since 1.3 (2026-10-21): use coverSources"`).
+   The resolver keeps working. `bun run schema:check` in CI refuses any breaking change that
+   was not deprecated first.
+2. **Remove, once no build on sale asks for it.** `bun run deprecations` finds, for each
+   deprecated element, the first build whose operations no longer select it and compares it
+   with what the store sells: removable when a build without it has been on sale for **fourteen
+   days**, in grace until then, waiting while the store still sells a build that asks for it.
+   One commit removes the removable elements (schema, resolver, the code and tests only they
+   used) and raises the minimum supported build to the floor the script proposes, which sends
+   older builds to the update screen at their next launch. Several releases in one day change
+   nothing: the fourteen days count from the release that stopped asking, not from the next one.
+
+The removal runs as a **scheduled routine** (monthly by default, see
+[16-routines.md](16-routines.md)), and may be run by hand at a release. The comparison key is the
+build number, never the marketing version. The gate fails open: if the configuration is
+unreachable, the app stays usable. A deploy whose floor is above the build on sale fails: readers
+must never be blocked with no update to install.
+
+| Change | Breaks installed builds | What to do |
+|---|---|---|
+| Added field, query, mutation, optional argument, enum value | No | Nothing: an unknown enum value is read as a neutral one by the app |
+| Field or argument the app stops using | No | Deprecate it in the same commit |
+| Removal, rename, type change, argument made required, non-null made nullable | Yes | Deprecate first; the routine removes it fourteen days after a build without it is on sale |
+
+## Scale to zero
+
+Never a warm instance (`min_instance_count`), whatever the p95 says. Scaling to zero is the point;
+cold starts are absorbed by the launch screen, and when traffic grows the users keep instances
+warm. A p95 driven by cold starts is a figure to report, not an action item.
+
+## Monitoring and Sentry
+
+One Sentry project per side (`<app>-node`, `<app>-ios`), org `polyforms`. Triage of an issue:
+
+1. Load the token from the local environment, never print or commit it.
+2. Read the issue and its latest event through the API.
+3. Walk the stack to the domain code, fix the cause, not the symptom.
+4. For a serious functional bug, write the failing test before the fix.
+5. Verify locally, commit.
+6. Mark the issue `resolvedInNextRelease` (never plain `resolved`, so a regression is flagged)
+   only after the push **and** a green pipeline.
+
+Source maps upload is part of the release workflow, never asked again.
+
+## Backups and recovery
+
+The `(default)` database has delete protection and seven-day point-in-time recovery. Until the
+app has paying users, there is no backup outside it; from the first paying user, a weekly
+managed export of the database to a bucket of the project (`gcloud firestore export`, run by
+Cloud Scheduler, 90-day lifecycle on the bucket) is provisioned by Terraform: a deletion found on
+the eighth day is then still recoverable. When data is lost (deleted documents, a failed
+migration, a deleted database or project) follow the project's `docs/data-recovery.md` before
+acting, and never restore the whole database over live writes.
+
+## Secrets
+
+A secret lives in the gitignored local `.env`, with `.env.example` beside it, and in the CI's
+secret store. The chain to production: GitHub secret, Terraform variable, Secret Manager, function
+environment. Every place a token is replicated is listed in `project-context.md`; a rotation that
+forgets one is found by an outage. A local API key is distinct from production's; keys are
+compared by fingerprint (`printf '%s' "$k" | shasum`), never displayed.
+
+## Dependencies
+
+Renovate, self-hosted in a nightly workflow: `config:recommended`, non-major updates grouped in
+one pull request automerged when CI is green, weekly lockfile maintenance. Every
+`allowedVersions` bound carries its reason in `description` (a peer dependency the deploy's
+stricter package manager rejects, a framework not yet on the new major). A strict install
+replayed on the build artefact catches what the permissive local install let through.
+
+**Majors are never automerged.** The upgrade routine ([16-routines.md](16-routines.md)) takes
+every open major pull request each morning: it reads the dependency's changelog and migration
+guide, applies the code changes the new major requires, deploys the branch to the project's
+staging environment ([14-infra.md](14-infra.md#staging)) to prove the build and the deploy, and
+merges when CI and the staging deploy are green; otherwise it leaves the pull request open with a
+comment saying what blocks. The package of this stack follows the same path with its own label,
+`stack`.

package/rules/12-ci.md

@@ -0,0 +1,32 @@
+# Continuous integration
+
+One workflow per concern, so a red run names its cause and a change touches one file. Templates
+in `templates/.github/workflows/`.
+
+| Workflow | Trigger | What it does |
+|---|---|---|
+| `test-unit`, `test-int`, `test-feat` | push, pull request | One test family each, run separately on purpose |
+| `schema` | push, pull request | Schema compatibility against `main`: a removal without a prior deprecation fails |
+| `build-ios` | push touching `ios/**` or the schema | Builds the app, runs the unit test target, the strings catalogue check and the pure-components check; on `main`, also produces the signed archive and keeps it as a short-lived artifact |
+| `deploy` | push to `main`; pull request labelled `staging` | Build, `terraform apply`, migrations; to production from the branch, to staging from a labelled pull request; `paths-ignore` for prose |
+| `testflight-ios` | nightly, manual | The nightly: takes the archive `build-ios` produced for the latest green commit of `main` (no second build), uploads it once a night when `main` moved since the last upload, to the internal group, then to the external group through Beta App Review, under the version under development read from the changelog |
+| `release-ios` | tag `ios-v<version>` | Version guard against the changelog, panels upload, submission, source maps |
+| `pages` | push touching `site/` | Publishes the site |
+| `renovate` | nightly, manual | Self-hosted Renovate with its own token |
+
+## Rules
+
+- The build number is the run number. The marketing version is read from the project.
+- `paths-ignore` on deploy, schema and the tests for `site/**`, `docs/**`, `screenshots/**`,
+  `README.md`, `CLAUDE.md`; never for the served changelogs.
+- A workflow authenticates to Google Cloud through Workload Identity Federation, never a key file.
+- Secrets are repository secrets; configuration that is not secret (a billing table, an analytics
+  property) is a repository variable.
+- The iOS archive signs manually with the certificate and profile stored as secrets; the store API
+  key uploads and submits.
+- **One build per commit.** The app is compiled once per commit of `main`, by
+  `build-ios`, as the archive; the nightly uploads that artifact and runs no macOS job of its
+  own. Only the release workflow archives again, on its tag. (Shiori still builds twice today:
+  this is a migration of the package.)
+- A failing lint or test in CI is a process failure: it should have been caught before the push
+  ([04-push.md](04-push.md)).

package/rules/13-ai.md

@@ -0,0 +1,71 @@
+# AI and paid calls
+
+## State the cost before building
+
+Any feature that calls a paid API states its cost in its design document and in its commit
+message before it is built: how many calls the first run makes, how many per day or month after,
+multiplied out (rows × formats × languages × searches per call) and priced. A background pass is
+sized to what a reader is shown, never to a whole dataset: looking up every winner since 1953 to
+show a dozen books cost 526 calls and 25 euros in four hours.
+
+## Gemini
+
+- A grounded call bills about **four searches**, not one; the logged search count undercounts
+  them. Searches are billed from the first one on a project that has spent its monthly free
+  allowance (5,000 per GCP project).
+- One API key per GCP project, on the project's own prepaid billing account, carried GitHub
+  secret → Terraform → Secret Manager. Never a key shared between apps: one app's burst cuts
+  every other.
+- A local key, distinct from production's, set for every Claude session on the machine; before
+  blaming production for a bill, compare fingerprints.
+- Two limits, two errors: 402 when the prepaid balance is spent, 429 when the monthly cap is
+  reached. The logged error says which.
+- The invoice is the truth: read spend from the billing export in BigQuery, grouped by day and
+  SKU; the grounded-search SKU is the one that costs. Structured logs (`jsonPayload.message`)
+  with the step and the search count let a spike be attributed to a device and an hour.
+- Past the free searches, grounded steps switch to Claude Haiku with web search capped at two
+  searches per call; a monthly counter decides.
+- Image generation for store panels: prototype at 1K or 2K, 4K only for a kept scene; the model
+  draws dividing lines when asked for several panels in one image.
+
+## Choosing a model
+
+The method is the rule; the choices are a dated table, revisited at every major version of this
+package and whenever a provider changes its prices or models.
+
+- **A quality test before any change of model**, upgrade included, and before adopting a new
+  one: the project keeps a bench script that runs the real task on about thirty real items
+  (`scripts/bench-*.ts`), compares the candidates on quality and on cost per item, and the result
+  goes into the commit message. A blind test by the person decides when quality is a matter of
+  taste (recommendations, copy).
+- **The cheapest model that gives the same quality wins.** At every change, the next cheaper
+  model is in the bench; a more expensive one is adopted only when the bench shows the quality
+  the cheaper one does not reach.
+- A source that is free (a national library's catalogue) is benched against the paid model
+  before the paid model is kept.
+
+Choices as of 2026-10-21:
+
+| Need | Model | Why |
+|---|---|---|
+| Structured extraction from a photo or a page | Gemini Flash-Lite | Cheapest with vision, good enough for fields |
+| Edition data with web grounding | Gemini grounded, then Claude Haiku + web search past the free tier | Cost of searches |
+| Editorial recommendation from the person's own data | Claude Sonnet | Blind test won against Haiku, Opus and Gemini Pro; about 0.035 euro per generation |
+| Choosing a month's picks, text only | Claude Sonnet | Same |
+
+Google Books and Open Library are not edition sources (503 on most calls, wrong ISBNs, no French
+editions); BnF's SRU serves French named books for free.
+
+## A cap in production
+
+Estimating before building does not protect from a loop or a burst. Every paid call, whether a
+background pass or a user action triggers it, goes through a counter with a **daily cap per
+project and per step** (Shiori's release watch: 30 a day); past the cap the step logs an `error`
+and stops instead of continuing, and the daily health routine reports the counter. A user-facing
+action is metered per user as well (a monthly quota on the free plan, an anti-abuse ceiling on the
+paid one).
+
+## Keys in the app
+
+The app never holds an AI key: every call goes through the backend, which meters it (a free
+monthly quota per user, an anti-abuse ceiling on the paid plan the app never shows).

package/rules/14-infra.md

@@ -0,0 +1,90 @@
+# Infrastructure
+
+Terraform in `infra/`, one GCP project per app named `<app>-polyforms`, region `europe-west3`,
+Firestore `eur3`. Templates in `templates/infra/`.
+
+| File | What it provisions |
+|---|---|
+| `project.tf`, `versions.tf`, `state.tf`, `backend.tf` | The project, the providers, the remote state bucket |
+| `firebase.tf`, `auth.tf` | The Firebase app, Sign in with Apple |
+| `firestore.tf` | The database with delete protection and point-in-time recovery, the indexes |
+| `function.tf` | The Cloud Function gen 2 (Node 22) serving the Nitro build, scale to zero |
+| `secrets.tf`, `variables.tf` | Secret Manager entries fed by Terraform variables from GitHub secrets |
+| `cicd.tf` | Workload Identity Federation for the GitHub workflows |
+| `scheduler.tf` | Cloud Scheduler jobs calling the backend's scheduled routes |
+| `storage.tf` | Buckets for uploads, signed URLs |
+| `ios.tf` | Resources the app needs (APNs key, bundle configuration) |
+| `observer.tf` | A read-only service account for unattended production reads |
+| `outputs.tf` | What the workflows and the app read back |
+
+## Staging
+
+Every app has a second GCP project, `<app>-staging-polyforms`, provisioned by the same Terraform
+(a workspace, same files, smaller quotas), scale to zero so it costs nothing idle. It is the
+production-like environment where anything is proven before production: a pull request labelled
+`staging` (every major dependency bump, every stack upgrade, anything touching infrastructure) is
+deployed there by the Deploy workflow; the end-to-end scenarios and any test that needs a real
+stack run against it; a seeded dataset and its own Sentry environment; the app points at it
+through its server-URL override. Nothing in staging is ever production data.
+
+It exists from the moment an app has real users to protect, and in any case before the first
+paid plan: with a handful of readers, production is the staging. Bazar is built with it from the
+start.
+
+## Bootstrap: one line creates a project
+
+`bunx @moifort/stack bootstrap <app>` runs once from the person's machine and leaves a project
+that deploys itself. It is a command of the package's CLI (TypeScript on Bun, like the rest), not
+a shell script: it reads the keychain, drives `terraform` (installed once on the machine, see
+[15-tooling.md](15-tooling.md)), `gh` and `git`, and reports. Two Terraform roots, because two
+kinds of credentials:
+
+| Root | Runs | Credentials | Creates |
+|---|---|---|---|
+| `infra/org/` | From the machine, at bootstrap and when the organisation-level setup changes | The person's organisation tokens, read from the macOS keychain for the duration of the run | The GitHub repository (settings, Pages, labels, branch rules), its secrets and variables, the Sentry projects (`<app>-node`, `<app>-ios`) with their DSNs written straight into the GitHub secrets, the Renovate installation, the GCP project and the state bucket |
+| `infra/` | By the Deploy workflow, through Workload Identity Federation | None on the machine | Everything in the table above |
+
+- **Keychain, not files.** The organisation tokens (GitHub, Sentry, App Store Connect) live in
+  the macOS keychain under fixed item names (`polyforms.github`, `polyforms.sentry`,
+  `polyforms.asc`), read with `security find-generic-password -w` into the environment of the
+  bootstrap process only, never written to a file, never printed, never committed. Each token is
+  fine-grained and scoped to the organisation, with an expiry, and its creation date is in the
+  person's `project-context.md`.
+- **The CI never holds a personal token.** What a workflow needs at run time is a repository
+  secret Terraform wrote (a DSN, a store API key) or a token it mints itself: Renovate runs
+  with a GitHub App installed on the organisation (the workflow mints a short-lived token from
+  the app's private key, stored once as an organisation secret), not with a personal token
+  that expires.
+- **Replayable.** Every step of the bootstrap checks whether it is already done and skips it,
+  so a run that failed halfway is simply run again. It never deploys the backend itself: it
+  ends by pushing the first commit and letting the Deploy workflow do the first deploy.
+- **What it cannot do, it lists.** The bootstrap ends with a numbered list of the steps that
+  need the person: the App Store Connect app record and the Sign in with Apple key (no API),
+  the Apple developer agreement, the DNS of the project's domain, the GA4 link when the API
+  refuses it. Each item says where to click and what value to paste back.
+- `bunx @moifort/stack teardown <app>` destroys both roots, after a typed confirmation of the
+  app's name.
+
+## Rules
+
+- The Terraform state is remote and never committed. `terraform.tfvars` is gitignored, with its
+  `.example`.
+- Secrets reach the function through Secret Manager only; the workflow never writes a key into
+  an environment file.
+- **One observer account for Claude, across every project** of the organisation
+  (`claude-observer`, in the neutral `polyforms-billing` project below), granted the read roles
+  (logging, monitoring, scheduler, functions, run, Firestore viewer, BigQuery job user and data
+  viewer) on each app project by that project's Terraform. Writes answer permission denied,
+  checked. It lives in its own `gcloud` configuration (`CLOUDSDK_CONFIG`) so the person's
+  account is untouched and routines do not depend on their login, which expires. Its key is on
+  the machine only, outside every repository.
+- **A neutral `polyforms-billing` GCP project** holds the billing export dataset and the
+  observer account, so that deleting an app never takes the invoice or the reader of every
+  other app with it. Each project's runtime account gets `dataViewer` on the dataset through SQL
+  `GRANT`, the IAM binding command being allowlisted. (Today the export lives in Vinarium's
+  project: moving it is a migration of this package.)
+- Analytics: the Firebase project is linked to a GA4 property at creation, or sessions go
+  nowhere; the property id is a repository variable.
+- Never a warm instance, see [11-ops.md](11-ops.md#scale-to-zero).
+- APNs keys and Sign in with Apple keys live in `infra/`, gitignored; they are not the store API
+  key.

package/rules/15-tooling.md

@@ -0,0 +1,81 @@
+# Tooling on the development machine
+
+## What a machine needs
+
+Installed once; the bootstrap checks they are there and names what is missing.
+
+| Tool | Install | Used for |
+|---|---|---|
+| Bun | `curl -fsSL https://bun.sh/install \| bash` | Backend, scripts, this package's CLI |
+| Xcode, latest final | Mac App Store | The app; `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer` once, the person's to run |
+| `gh` | `brew install gh`, then `gh auth login` | GitHub: runs, pull requests, secrets |
+| `gcloud` | `brew install --cask google-cloud-sdk` | Production reads through the observer configuration |
+| Terraform | `brew install terraform` | The bootstrap and local plans |
+| `apollo-ios-cli` | Bundled in the app's Swift package checkout, never a global install | GraphQL codegen for the app |
+| JDK and Firebase CLI | Only with the `e2e` stack | The emulators |
+
+## Runtime
+
+Always `bun` / `bunx`, never `npm` / `npx`. Biome for formatting and linting: spaces, single
+quotes, no semicolons, line width 100.
+
+## Xcode and simulators
+
+- Build with the latest final Xcode. `DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer`
+  is required for `xcodebuild`, `simctl` and `xcstringstool` while `xcode-select` points at the
+  Command Line Tools; switching it needs the person's password.
+- **Always the simulator runtime already on the machine.** The reference device is the iPhone of
+  the runtime `xcrun simctl list runtimes` shows installed; a build or a capture targets that
+  one. Never download another runtime or platform without asking: each is several gigabytes.
+  When one is needed: only the version matching the installed SDK, from the command line
+  (`xcodebuild -downloadPlatform <name>`), never through Xcode's UI, one download at a time
+  (`pgrep -f downloadPlatform` first; several block each other on "Preparing to download").
+  Progress is the size of `/Library/Developer/CoreSimulator/Volumes`, not the program's messages.
+- A download stuck on "Preparing to download" with no byte transferred is the network first:
+  macOS suspends system asset downloads on a connection it considers cellular, an iPhone
+  hotspot included, silently. Check the interface and the Wi-Fi name before anything else; the
+  daemon is not broken.
+- **One simulator at a time on the machine.** Every session and every project uses the same
+  reference device, booted on demand if it is not, and never shut down by a session: the push
+  hook shuts it, with Simulator.app. A session installs its own build into it right before each
+  launch, from a derived data path unique to the session, so two sessions sharing the device
+  never launch each other's build. Two booted simulators is the exception that needs a reason
+  (a capture on a second size).
+- `simctl io <udid> screenshot` works when the simulator tool's own capture fails.
+
+## Browser, and doing things end to end
+
+Always the built-in browser of the Claude app, never Claude in Chrome, even when asked to "go to
+Chrome". When the person says "go to the browser and click here", Claude goes and clicks: it
+drives the browser, fills the forms, runs the commands, and goes to the end of the task. When a
+page needs a sign-in, it asks the person to sign in there, then continues. Some console actions
+have no API (a price schedule, privacy answers, a subscription submission): they are done in that
+browser, signed in as the person.
+
+The only things that wait for a go, said in one message with what will be done and why:
+**reading production data** and **anything that changes production** (a deploy, a console
+setting, a store submission, a purchase). Everything else (code, commands, builds, the person's
+own sites and consoles in read mode, GitHub, CI) is done without asking.
+
+## Git and GitHub
+
+- `gh` authenticates with a keyring token; a push changing workflow files may need SSH
+  ([04-push.md](04-push.md#workflow-files)).
+- Worktrees for parallel sessions, with the gitignored files copied in
+  ([02-commits.md](02-commits.md#several-sessions-on-one-project)).
+- The App Store Connect API key for scripts lives in `~/.appstoreconnect/private_keys/`, shared
+  by every app of the team; its id and issuer are in each project's `project-context.md`.
+
+## Remote control
+
+Driving a project from the Claude app on a phone is a CLI process per project
+(`claude remote-control --name <app> --permission-mode auto --spawn same-dir`), with its own
+`claude auth login`, relaunched after a reboot. Check it with `pgrep -fl "claude remote-control"`.
+
+## Reading production
+
+Unattended reads (logs, metrics, billing, Firestore) go through the **Claude observer account**,
+one for every Polyforms project ([14-infra.md](14-infra.md)), in its own `gcloud` configuration;
+`gcloud auth login` is the person's and expires. In an interactive session, a production read
+is announced and waits for the go; a routine the person configured has its go in its prompt.
+Firestore's REST API needs `Content-Type: application/json` or answers a misleading 400.