@moifort/stack 0.0.0-stage → 0.1.0

package/rules/02-commits.md

@@ -0,0 +1,71 @@
+# Commits
+
+## The history is the golden source
+
+The commit history is the source of truth for what was done and why. Every message is written for
+the reader who comes back months later, Claude included: what changed, the decision behind it, the
+alternative rejected, the cost of a paid call, the issue or feedback that triggered it. Before
+taking a decision, read the history (`git log`, `git log -S`, `git blame`): what was tried, what was
+reverted and why, which direction was chosen. A good split (one decision, one commit) and a good
+message are what make that reading possible.
+
+## Format
+
+Conventional commits: `type(scope): subject`, English, lowercase, imperative, no trailing period.
+Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `ci`. The scope is the business
+domain deduced from the paths touched, never an invented taxonomy; a cross-cutting change takes
+`deps`, `ci`, `config`. A commit needing two scopes is probably two commits.
+
+The body explains the why, the decision taken and the alternative rejected, and states the cost of
+a paid API call. It never paraphrases the diff. Every commit ends with the `Co-Authored-By`
+trailer.
+
+A commit that touches only documentation, a README, specs, or anything that does not change the
+code, the served content or the app's strings ends its subject with `[skip ci]`: a full pipeline
+with a deployment is not spent on prose. Never on a commit that touches the site (Pages would not
+publish) or the served changelogs. See [04-push.md](04-push.md#no-ci-for-prose).
+
+## Never ask
+
+Neither the message nor the split is submitted for approval. Decide, write, commit.
+
+## Granularity
+
+One finished task, one commit, as soon as its verification passes. Group coherently; never bundle
+unrelated tasks, so that a rollback is a clean revert. Stage explicit paths only: never `git add
+-A`, `git add .` or `commit -a`.
+
+## Amend
+
+Prefer a new commit to an amend, even when an earlier message has become inaccurate: an extra
+commit costs nothing, a clobbered one costs someone else's work. When an amend is warranted,
+re-read `git log -1` in the same command as the amend, never from a HEAD observed earlier.
+
+## Branch
+
+Work lands on `main`. No feature branch, no pull request, unless asked.
+
+## Several sessions on one project
+
+When several Claude sessions work on the same project at once, **each session works in its own git
+worktree** and merges into `main` when its task is done. A fresh worktree lacks the
+gitignored files the build needs (app secrets, Firebase plist, package resolution, generated API
+client): copy them from the main checkout first, see [15-tooling.md](15-tooling.md).
+
+Fallback rules when two sessions share a checkout anyway:
+
+- commit with an explicit pathspec (`git commit -- <files>`), and before that, check `git diff`
+  of every file outside your own folders: a file carrying someone else's changes is never staged
+  into the shared index;
+- never split the hunks of a generated file (an exported schema): a zero-context patch applies at
+  the wrong place silently. Parse the staged blob before committing, or regenerate it whole;
+- after committing, once other sessions have committed on top, grep `main` for your
+  change before reporting it done: a stale copy of a file committed by another session can undo
+  it.
+
+## Push
+
+Never on your own initiative. Commits accumulate locally until the person says "push"; then the
+checklist of [04-push.md](04-push.md) applies. The one exception: a scheduled routine the person
+has explicitly authorised to push (see [16-routines.md](16-routines.md)) pushes its own fixes and
+watches CI like any push.

package/rules/03-code-review.md

@@ -0,0 +1,25 @@
+# Code review
+
+Every finished task is reviewed before its commit, inline, by re-reading the actual diff
+(`git diff`, `git diff --staged`), never the memory of what was meant.
+
+## The grid
+
+| Axis | What to look for |
+|---|---|
+| Correctness | Does the code do what the task asked, entirely, and nothing more |
+| Edge cases | Empty, absent, zero, duplicate, concurrency, network failure, partial data |
+| Security | Unvalidated input at the boundary, secrets in clear, one user's data reachable by another |
+| Cost | Reads in a loop, one query per row, work redone on every call, a paid call sized to a dataset |
+| Consistency | The project's conventions: naming, structure, error handling, style |
+| Debt | Duplication introduced, premature abstraction, dead code left behind |
+| Tests | Would a test fail if the regression came back |
+| Documentation | A surface the person sees changed without the documentation following |
+
+Fix what must be fixed, then commit.
+
+## Receiving a review remark
+
+A remark is neither an order nor a truth. Verify it in the code before applying it. If right, fix
+without a long comment. If wrong, say so with the fact that proves it. Agreeing with a wrong
+remark costs more than contradicting it.

package/rules/04-push.md

@@ -0,0 +1,75 @@
+# Push
+
+A push never starts on its own: only when the person asks for it explicitly. Then this checklist
+applies in order, then the push, then the watch, then the cleanup.
+
+## Before
+
+1. **Generated code.** If an API contract moved, regenerate and commit the produced files, so the
+   typed clients match what is deployed.
+2. **Linter in write mode.** `bun run lint:fix`, commit what it fixed. CI is not a linter: a
+   lint error is never discovered from a red pipeline.
+3. **Preflight.** `bun run preflight` green, the test families run separately
+   ([01-workflow.md](01-workflow.md#verification-before-a-commit)).
+4. **Nothing else moves.** No changelog (written at release only), no README, no screenshots:
+   captures are regenerated at release, not at push.
+
+The format of a generated artefact belongs to its generator, not to the linter: every generated
+file added to the repository is excluded from the linter in the same commit.
+
+## Workflow files
+
+Pushing a change under `.github/workflows` needs a token with the `workflow` scope. If the push is
+refused, push over SSH (`git push git@github.com:<owner>/<repo>.git main`); the lasting
+fix is `gh auth refresh -s workflow`, interactive, the person's to run.
+
+## After
+
+The push is not finished until every pipeline run for the pushed commit has been watched to the
+end, Deploy included, and the result stated per workflow.
+
+```bash
+gh run list --limit 10 --json databaseId,name,status,conclusion,headSha --jq '.[] | select(.headSha | startswith("<sha>"))'
+gh run watch <id> --exit-status
+gh run view <id> --log-failed
+```
+
+- `gh run list --commit <sha>` returns nothing on some machines: filter on `headSha` client side.
+- zsh does not word-split an unquoted variable in a `for`: loop over `${(f)ids}` or paste the ids.
+  Never report CI green without the final per-run status list.
+- `gh run view --log` reads a local cache (`~/.cache/gh/run-log-*.zip`) even after the logs were
+  deleted on GitHub: verify a deletion against the API.
+
+A failure is **fixed forward**: find the cause, fix it with a new verified commit, push, watch
+again until green. Never force-push, never amend a pushed commit. If the cause is outside the code
+(infrastructure, a secret), say so instead of guessing.
+
+## Cleanup after the push
+
+A successful push closes the session's working set:
+
+- the `shutdown-simulators-after-push` hook shuts every booted simulator and quits Simulator.app
+  (they otherwise hold 50 to 70 % of the CPU); do not relaunch them unless asked;
+- stop every process started for the task that is no longer useful: dev server, watcher,
+  preview, background build;
+- delete what the session generated and that is not meant to be kept: screenshot harness builds
+  and their derived data under `/tmp`, capture files, scratch scripts, temporary clones and
+  worktrees (`git worktree remove`, then `git worktree prune`), backups of files taken before an
+  edit;
+- leave the working tree with nothing untracked that belongs to the session.
+
+What is kept is what the repository holds; everything else was scaffolding.
+
+## Install on the phone
+
+When the push carried app changes next to backend changes, the install on the person's phone
+follows the push, once Deploy is green ([10-ios.md](10-ios.md#physical-device)). An app-only
+change was installed before the push.
+
+## No CI for prose
+
+Deploy, schema and test workflows carry `paths-ignore` for `site/**`, `docs/**`,
+`screenshots/**`, `README.md`, `CLAUDE.md`: a push touching only those runs nothing but the
+Pages workflow. For prose outside those paths, end the subject with `[skip ci]`. Never `[skip ci]`
+on a commit that touches the site (it would stop Pages), and never put the served changelogs in
+`paths-ignore`: the server deploys them.

package/rules/05-release.md

@@ -0,0 +1,40 @@
+# Release
+
+A release is a git tag `ios-v<version>`. The tag does everything: build, upload,
+TestFlight, submission.
+
+## The order
+
+1. **Deprecations.** `bun run deprecations` lists the schema fields and arguments no build on
+   sale for two weeks still asks for, and the build floor to set. One commit removes them and
+   raises `MINIMUM_SUPPORTED_BUILD` to the proposed value, which sends older builds to the update
+   screen. Never raise the floor by hand. See [11-ops.md](11-ops.md#api-evolution).
+2. **Release notes** written in the source language and translated into each served language,
+   version headings everywhere, see [06-changelog.md](06-changelog.md).
+3. **Approval.** The notes in `{{REVIEW_LANGUAGE}}` are shown in the conversation and approved
+   explicitly. Corrections are carried into every language. No push on unapproved notes.
+4. **Push of `main`**: it deploys the backend, which serves the notes to the app.
+5. **Captures and store panels**, only when the person asks for them: regenerated on the
+   machine, never in CI (far too slow there), committed to the repository, and uploaded by the
+   release workflow from what the repository holds. See [07-appstore.md](07-appstore.md).
+6. **Tag**, posted and pushed as soon as the notes are approved. Do not hold it for outside
+   conditions (a CI outage, a red run): a missing run is relaunched by hand, an unposted tag
+   blocks the chain. Never tag before the approval of step 3.
+
+## Versioning
+
+The marketing version is manual and explicit: the one in the tag is the one in the notes. The
+build number derives from the pipeline run, never edited by hand, and is the key every
+comparison uses (the build floor, the deprecation report), never the marketing version.
+
+## End-to-end gate
+
+A project with the `e2e` stack runs its end-to-end scenarios first, and they condition the rest:
+no build nor publication if a user journey is broken. They also run locally on a disposable stack,
+never against production, one run at a time. A red scenario on a posted tag is fixed, then
+re-tagged; the gate is never disabled to rescue a release.
+
+## Red pipeline on a posted tag
+
+Fix forward and re-tag. Rerunning only the failed job (`gh run rerun --failed`) resubmits without
+rebuilding when the failure was on the store side.

package/rules/06-changelog.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## Two files in lockstep
+
+`CHANGELOG.md` in `{{SOURCE_LANGUAGE}}` is the source of truth; one translation per served
+language (`CHANGELOG.<lang>.md`), kept in lockstep. Newest first. Each version carries the store
+version and its release date: `## 1.0 (2026.10.01)`.
+
+Under a version, at most three subsections, only those with content: new, fixes, performance. If
+the parser serving the content ignores them, the app shows a flat list, and that is fine.
+
+## Written at release time, never before
+
+A feature, a fix or a push leaves both files untouched: no `## Unreleased` section, not even as a
+placeholder. The entries are written when a store release is cut, from the commits since the
+previous one, under that release's version and date.
+
+## What to write
+
+The reader is not technical. An entry says what changed **for them**, in their words, and nothing
+else. Two tests before writing a line: does the person notice it while using the app, and would
+they understand the sentence without knowing how the app is built. No on both, no entry.
+
+What goes in:
+
+- a new feature or a new capability the person can use, named where it is in the interface;
+- a problem they could meet, now fixed, described by its effect;
+- a change in speed or behaviour they will feel.
+
+What stays out, whatever the effort behind it:
+
+- infrastructure, deployment, CI, scripts, README, dependencies, refactors: invisible, so absent;
+- micro changes: a corrected label, a reworded sentence, a replaced image, a moved button;
+- anything the person does not know exists (a cache, a quota mechanism, a model switch).
+
+How to write it:
+
+- the visible effect, never the mechanism. Raising the number of concurrent reads on the
+  database becomes "Performance: the library and the series now open faster";
+- a fix is one short sentence saying what now works. No cause, no frequency ("one time in
+  three"), no model, call, search or API named. The technical story is in the commit message;
+- never the app's name in an entry; never a line about which languages the app is available in;
+- the tone of [08-copy.md](08-copy.md) applies in every language.
+
+## Approval
+
+The `{{REVIEW_LANGUAGE}}` entry is shown in the conversation and approved before the commit and
+the tag. See [05-release.md](05-release.md).

package/rules/07-appstore.md

@@ -0,0 +1,77 @@
+# App Store
+
+Complement of [05-release.md](05-release.md) for the store side.
+
+## Toolchain
+
+Build with the latest **final** Xcode, never a beta or release candidate, never a version
+superseded once a newer one is out: both are rejected at upload for an unsupported SDK. If the
+build machine runs a beta OS, the archive carries a prerelease machine build that triggers the same
+rejection: archive on a final-version machine, or patch `BuildMachineOSBuild` in the archive's
+Info.plist before export (export re-signs on top).
+
+## Signing
+
+Manual signing end to end, archive included: a dedicated certificate and an explicit provisioning
+profile. The store API key uploads and submits, it does not sign. The certificate's expiry date is
+written in `project-context.md`: an unanticipated expiry breaks the release chain with an
+unreadable authentication error. Without an Xcode account, `xcodebuild` signs with the API key
+(`-authenticationKeyPath`, `-authenticationKeyID`, `-authenticationKeyIssuerID`).
+
+## TestFlight
+
+Two groups: an internal one ("Nightly") that receives the nightly build of `main`, and
+an external one ("Public"). The notes job of the nightly workflow adds each build to the external
+group and submits it to Beta App Review, never to App Review. A change can be tried on a phone the
+next morning without tagging a release that is not one. Adding a tester who already belongs to another app's group answers
+409: create the tester with the group relationship instead.
+
+## Captures and panels
+
+Captures and marketing panels are produced **on the machine**, never in CI (a run that boots
+emulators, backend and simulator for every language adds half an hour to a release for images that
+rarely change), every served language at once, and committed; the release workflow uploads what
+the repository holds. They are regenerated **only when the person asks for it**, never at push and
+not automatically at release. A stale panel in the repository is a stale panel in the store: when
+a screen changed, propose the regeneration.
+
+- Captures come from in-app showcase fixtures (`-showcase` launch argument, Debug builds only),
+  on a dedicated simulator, never from a seeded server.
+- The app's interface, the captions and the device frame never go through an image model: the
+  model produces plausible but wrong text, and a different device size at every try. Generate the
+  backdrop with reserved zones, compose the real captures, draw captions in the system font of
+  each language, draw the device at the same place on every panel.
+- One panel per generated image: asking for two yields a dividing line. Even the backdrop out.
+- Backdrops are cached and committed: adding a language or rewording a caption costs no API call.
+- The product page header (16:9) lives outside the panel folders: the upload script sends every
+  PNG there as a screenshot.
+- `simctl addmedia` hangs on a fresh simulator until Photos has been launched once.
+- Covers or product images for the showcase come from a keyless public API (iTunes Search for
+  books), rate-limited; some queries answer an HTML page every time, treat it as no result.
+
+Panels upload **before** the submission: a version already in review refuses new captures.
+
+## Listing
+
+The listing, its translations, its subscription names and the privacy answers live in the
+repository (`infra/fastlane/metadata/<locale>/`) and are pushed by a script; what is written only
+in a console is lost at the first account migration.
+
+What the release pipeline cannot do, done once in the browser where the person is signed in: the
+app's price schedule, the App Privacy answers, accepting a new developer agreement (the account
+holder only). An app name already held by another account in a locale answers 409: plan a
+compound name ("Name: What it does"). Keywords are capped at 100 characters.
+
+## First subscription
+
+The first subscription must be submitted with an app version, and the API refuses every direct
+route. The sequence that works: create a draft review submission holding the version through the
+API, then in the browser open the subscription **group** page, "add for review" into that draft,
+then each subscription's page, same action, then submit the draft. The version page itself shows
+no subscriptions section. Cancelling a submission takes a minute; a draft with no items cannot be
+cancelled, delete its items instead.
+
+## Site
+
+The project's site, privacy policy and support page are served from the repository (`site/`)
+through Pages, on the project's domain.

package/rules/08-copy.md

@@ -0,0 +1,52 @@
+# Copy
+
+Applies to everything the person using the product sees: on-screen text, release notes, the
+store listing, the landing page ([17-landing.md](17-landing.md)).
+
+## Tone
+
+Impersonal. Describe what is in place without addressing the reader. "The cellar size can now be
+changed from Settings" rather than "You can now change your cellar size". Name where the feature
+is, with the exact words of the interface. Give an example wherever it saves an explanation. Full
+sentences, normal punctuation, to the point.
+
+## Forbidden
+
+- **Never an em dash or an en dash.** They read as a machine signature. Rephrase, or use a period,
+  a comma, a colon.
+- No filler: "at any time", "simply", "also", "well".
+- No chopped sentences, no technical jargon, no file or service names.
+- Never the word "unlimited" for a metered plan with an anti-abuse ceiling: "without counting".
+
+## Localisation
+
+The source language is `{{SOURCE_LANGUAGE}}`, the served languages `{{SERVED_LANGUAGES}}`. The tone
+above holds in each, in the natural register of the language.
+
+One list of supported languages in the whole system, shared by the client and the server. A
+third-party service's output depends on the language asked: its cache is keyed by language.
+
+The iOS model:
+
+- Strings are written in the source language in the Swift code and are the catalogue keys
+  (`sourceLanguage` = source). The development language of the target is English: the fallback for
+  every phone in another language.
+- With that setup, the catalogue compiler emits the source-language table only when **each key
+  carries an explicit source-language unit**; a key without one falls back to English on a
+  source-language phone.
+- After any on-screen text change: build, then `bun run ios:strings --write` (fills the
+  source unit, drops stale keys, lists what lacks English), fill the English, rerun without
+  `--write` until it reports every string translated, commit the catalogue with the UI change. CI
+  runs the same check without `--write`.
+- The catalogue tool files strings by catalogue **file name**: a copy under another name marks
+  every key stale.
+- `Accept-Language` sends the app's language (`Bundle.main.preferredLocalizations.first`), not the
+  phone's first one.
+- A component property typed as a raw string that carries static copy is never extracted and stays
+  in the source language: type it as a localised key, so a computed string is refused.
+
+## README and store description
+
+Same principles for the entry documentation: say what the project does, not how it is built; why
+before how; numbered steps. Deep architecture has no place in a README, and a README embeds no
+screenshot that ages.

package/rules/09-backend.md

@@ -0,0 +1,132 @@
+# Backend
+
+A TypeScript backend on Bun and Nitro, Firebase preset, GraphQL through Apollo Server and Pothos,
+native Firestore, Zod and branded types. Long form in the `domain` and `graphql` skills.
+
+## Architecture
+
+One folder per domain under `server/domain/{domain}/`: `types.ts`, `primitives.ts`,
+`command.ts`, `query.ts`, optional
+`business-rules.ts` (pure functions, full test coverage) and `use-case.ts` (orchestration across
+domains, no business logic of its own), and `infrastructure/{repository.ts, graphql/}`.
+
+- Commands change state, queries change nothing.
+- `command.ts` and `query.ts` export bare functions, and the caller imports the module under
+  the domain's name: `import * as BookCommand from '~/domain/book/command'`, then
+  `BookCommand.rate(...)`. The prefix lives at the import site, so `BookCommand.rate` and
+  `SeriesCommand.rate` never clash and no TypeScript `namespace` block is needed (an older
+  construct the linter flags). Existing projects that use `namespace` move over through a
+  migration of this package.
+- The repository is bare exported functions (`import * as repository`), private to its domain. A
+  domain that needs another goes through that domain's `Query` or `Command`, never its storage.
+- A function's name carries the business concept, never the technical pattern: `versionToOpen`,
+  not `computeVersion` or `handleX`. One concept, one word, at every layer: domain, schema, app,
+  tests.
+- Functional style: no class, no object interface. Polymorphism is a discriminated union on a
+  literal field; on the API side a union, never an interface.
+
+## Types
+
+No bare primitive in a domain model: every field carries a branded type (`ts-brand`) with its
+validating Zod constructor in `primitives.ts` and one GraphQL scalar per brand, which reuses the
+constructor rather than restating the rule. Generic brands (user id, amount, year, percentage)
+live in the shared domain. Dates stay native. Validation happens once, at the boundary, at
+construction: the rest of the code works on valid values. Never `as MyType` on untrusted input.
+
+No `null` in the domain: absence is an optional field, converted only at the API and storage
+boundaries.
+
+## Errors
+
+A command returns the domain value or a bare string-literal outcome (`'not-found' as const`), one
+distinct literal per expected failure. The resolver maps them exhaustively with
+`match().exhaustive()` and the `notFound` / `badUserInput` helpers; a new outcome that is not
+mapped fails to compile. `throw` only for an impossible state. If the caller can do nothing with
+an absence, it is an inconsistent state, throw; if it is a normal scenario, return the outcome.
+
+## Storage
+
+Native Firestore through `db()`, only inside `infrastructure/repository.ts`, with the shared
+helpers (converter, transactional read-modify-write, bulk save, delete in batches, per-request
+memoisation).
+
+- **Collections are flat.** Never a subcollection: every document sits in a top-level collection
+  and names its owner in a `userId` field. Accounts live in `users/{userId}`. Every query filters
+  on `userId`.
+- A shared document (a catalogue two users converge on) holds no reference to any user and is
+  keyed deterministically by what identifies it, so the paid call that produced it is paid once.
+- **A field for a decided feature is added before production data exists.** Before the first
+  release, adding a field costs nothing; after it, it costs a migration on every record. So a
+  field a feature on the roadmap will need (a `hidden` flag for sharing planned next month) is
+  added now with its default. Only for a decided feature: a field "in case" is dead weight to
+  maintain in fixtures and to migrate away later.
+- Renames, restructures and value changes go through a migration, see
+  [11-ops.md](11-ops.md#migrations).
+- Filtering, sorting and pagination happen in Firestore, never in memory after loading all.
+- Multiple writes go through one batch; mass deletions through successive batches.
+
+## Reads and cost
+
+No nested field triggers one read per parent row. Either a per-request loader groups the reads by
+parent id, or the data is denormalised on purpose (a book carries its series name and volume, so
+sectioning a library reads no catalogue document). When a nested field needs the catalogue, add a
+loader before shipping it. The only server-side cache is per incoming request: a domain query
+called several times during one call reads once.
+
+## Scheduled routes
+
+A route called by Cloud Scheduler is **idempotent**: the scheduler retries on failure and a
+replayed pass must neither pay a call twice nor notify twice. The route records what it did (a
+document per pass or per item, keyed deterministically) and skips what is already done; a
+notification carries an id that makes a second send a no-op. The route is protected by a token and
+answers quickly, doing the work in bounded batches.
+
+## Observability
+
+Never `console.*`. One logger per component, `createLogger(tag)`. Three levels with a meaning:
+
+| Level | Meaning | Goes to Sentry |
+|---|---|---|
+| `error` | Our code is broken or an invariant failed; someone must fix it | Yes |
+| `warn` | Recovered, but a human should look one day (a fallback taken, a limit approached) | Yes |
+| `info` | Expected, including expected failures: a third-party 503, an item a provider lacks, a cancelled request. Counted, never alerted | No |
+
+A caught-and-recovered failure is logged at the level its meaning says, never swallowed. An
+expected failure logged as `warn` creates a Sentry issue nobody can fix and trains the triage
+routine to ignore warnings. Keep the message
+constant and pass the rest apart (`logger.warn('cover lookup failed', { error, isbn13 })`), so
+Sentry groups one problem into one issue and keeps the stack. Sentry activates only in a built
+bundle with its DSN set, never in local development. The logger's extras appear under `.context`
+in the event.
+
+## Tests
+
+Three suffixes, three CI workflows, co-located with the code:
+
+| Suffix | Scope |
+|---|---|
+| `*.unit.test.ts` | Primitives and business rules, pure functions |
+| `*.int.test.ts` | Commands and queries against the in-memory fake Firestore, through the real repository code: converters, date transposition, batches |
+| `*.feat.test.ts` | The API contract through the built GraphQL schema: for each operation, the shape and values of its answer, its error codes, its gates, its read budget. A change in what an operation returns fails here before an app notices |
+
+- Only `db()` is faked (`mock.module('~/system/firebase', () => ({ db: fakeDb }))`): the
+  repository runs as in production, with its typed converters and its date handling, so a test
+  proves the real storage code. The fake has no subcollections, matching the flat layout.
+- Read budgets are asserted with the split counters `docReads` and `queryReads`, never the total.
+- The per-request memoisation is active inside a test and reset between tests: reseeding between
+  two calls of the same query in one test returns the stale result. Use two tests.
+- Under Bun, `toMatchObject({ at: someDate })` matches any Date: assert a date with `toEqual` on
+  the field.
+- The three families run separately before a commit ([01-workflow.md](01-workflow.md)).
+
+## Generated code
+
+An exported schema, a typed client, a compiled asset belong to their generator: never edited by
+hand, regenerated, committed when the repository needs them, excluded from the linter.
+
+## Local development
+
+A dev-only auth bypass (`DEV_USER_ID`) lets the schema explorer work without a token, and a
+stub answers paid calls with a fixed result; both are `import.meta.dev` gated and tree-shaken out
+of a production bundle. A dev server on real data runs real mutations. `.env.example` is updated
+with every new variable, in the same commit.