@freetesh/canon 0.16.0 → 0.18.0

package/standards/library/expo.md

@@ -0,0 +1,54 @@
+# Expo apps
+
+How an Expo app is created and laid out. Opt in with `standards: [expo]`.
+Code rules for the `.tsx` files are in `frontend`.
+
+## Read the versioned docs
+
+This project is on **Expo SDK {{expo.sdk}}** (from `expo.sdk` in
+`.claude/canon.yaml`). Read <https://docs.expo.dev/versions/v{{expo.sdk}}.0.0/>
+before writing any Expo or React Native code. APIs move between SDKs, and
+recalled shapes are often wrong.
+
+## Scaffold with the Expo CLI
+
+Create the app with `npx create-expo-app@latest`, on the latest Expo SDK. Never
+hand-assemble a React Native project, never copy another app's `node_modules`
+layout, never fork an old scaffold that is a major version behind.
+
+Set these up at scaffold time, before any feature work: expo-router, lucide
+icons (`lucide-react-native`), UniWind, RevenueCat (`react-native-purchases`),
+Firebase, and any AI integrations the app needs. Structure only — no features.
+Copy the lint rules in at the same time (`frontend`).
+
+## Layout
+
+```
+<app>/
+  CLAUDE.md        # stack, directory tree, monetization, persistence rules
+  AGENTS.md        # the agent contract; CLAUDE.md imports it with @AGENTS.md
+  CHANGELOG.md     # Keep a Changelog 1.1.0 — feeds the store release notes
+  .context/        # see context-layout
+  src/             # application code; routes in src/app/ (or apps/<name>/src/ in a monorepo)
+```
+
+- `/ios` and `/android` are **generated** and gitignored. Never hand-edit them —
+  change `app.config.ts` or a config plugin and prebuild again.
+- The store listing is in `.context/listing/` (see `store-listing`).
+
+## Styling
+
+UniWind only — the rule is `frontend` rule 5. The Tailwind tokens in the app
+mirror the design set's `tailwind.config.js` (`design-sets` §8), so a token
+means the same thing in the drawing and in the app.
+
+## Before calling work done
+
+On top of the repo's lint, typecheck and tests:
+
+1. For anything touching imports, dependencies or assets, also run
+   `npx expo-doctor` and `pnpm expo export --platform android`. They catch SDK
+   pin drift and runtime resolution failures that typecheck cannot.
+2. If a native dependency changed, it ships as a release
+   (`npm version patch && git push --follow-tags`), not an OTA update.
+   `scripts/check-ota-safe.mjs` blocks the OTA otherwise.

package/standards/library/frontend.md

@@ -0,0 +1,44 @@
+# Frontend code
+
+Rules for every `.tsx` file in a React Native or React app, new or touched.
+Opt in with `standards: [frontend]`.
+
+These are not style preferences and there is no "I'll split it later". **Plan
+the files before writing the screen**: list the components, hooks and helpers a
+screen needs, then write each in its own file. A screen written as one file and
+split afterwards is the failure this standard exists to stop.
+
+1. **One component per file, named after the file.** No private sub-component at
+   the bottom of a screen, however small. The only exception is a set of sibling
+   primitives always imported together (a type ramp, a layout trio), in a file
+   named for the set and listed in the lint config.
+2. **A route file is thin.** `app/**` reads params, finds the data, and renders
+   one screen component from `components/<feature>/`. No business logic, no
+   event handlers longer than a line, and under 200 lines.
+3. **Helpers live apart from what renders.** A pure function goes in `lib/` with
+   a test. Anything that touches React, a store or navigation goes in `hooks/`.
+   No lowercase function is declared in a `.tsx` file.
+4. **Constants live in `constants/`.** A number, a label map, a limit, a regex:
+   if it has a name, it has a home outside the component.
+5. **UniWind only** (`uniwind` + `tailwindcss`). `className` for everything a
+   class can express. No `StyleSheet`, no styled-components, no NativeWind, no
+   CSS files beyond the theme. `style={{ }}` only for a value computed at
+   runtime — a measured or animated number. A third-party native view that
+   ignores `className` (expo-image, expo-camera) is wrapped once with
+   `withUniwind` in `components/ui/` and used through the wrapper.
+6. **Props are a named `interface`**, declared above the component. No
+   `React.FC`, no anonymous inline prop types on an exported component.
+7. **Hooks hold the state and effects; components render.** A component that
+   fetches, navigates and lays out is three files.
+8. **Lowercase kebab-case file names, PascalCase component exports.**
+
+## The linter enforces these
+
+`pnpm lint` is a gate. Keep the rules in one ESLint file (for example
+`eslint/standards.js`): one component per file, no helpers in component files,
+no fixed inline styles, no `StyleSheet`, a line cap on routes. Copy it from the
+reference repo (`copies.source`) at scaffold time. A standard that is only
+written down gets broken; one that fails the build does not.
+
+Before reporting frontend work as done, run the linter and read the diff against
+this list. If a file breaks one of these, the work is not done.

package/standards/library/performance.md

@@ -0,0 +1,45 @@
+# Performance
+
+For web and Expo apps. Opt in with `standards: [performance]`.
+
+Learned from an editor where every canvas edit redrew the whole screen, and each
+redraw cost 21 database round trips. Nothing was broken; it was just slow.
+
+1. **A local edit never redraws the screen.** When the UI already shows the
+   change (a canvas, a field, a toggle), save it and update only what the save
+   changed, from the mutation's answer. Next.js: no `router.refresh()`. Expo: no
+   refetch or invalidate-all of the screen's query. Redraw only when
+   server-drawn content changes shape (a row added or removed), and say why in
+   a comment.
+2. **Hot paths are guarded by lint.** The screens people edit on (an editor, a
+   canvas, a form that saves on every change) get a `no-restricted-syntax` rule
+   that bans the redraw call in their folders. Each allowed exception gets a
+   disable comment with its reason.
+3. **Count the round trips of a screen's loader.** Each query is one trip to
+   the database, and on the deployed app every trip waits on the network.
+   - Never look the same row up twice in one request. Pass on what you already
+     loaded.
+   - Never count rows you also read (`count` next to `findMany`). Use the
+     length.
+   - A nested Prisma select is one more query per relation. Fold reads into one
+     query where you can: all open refs at once, not main and then the
+     branches.
+   - **Separation of duties comes before speed.** Database roles, row
+     policies and column grants are not traded for fewer queries. Prisma's
+     `relationJoins` reads every column, so it fails where a column has its own
+     grant (a sealed password column, say). Change the data layer for speed
+     only when speed is make-or-break, measured, and the owner decides.
+4. **A navigation shows something at once.** Never put a whole screen inside
+   `<Suspense fallback={null}>`: the click looks dead, then the screen jumps.
+   The fallback is a drawn loading state, so where `design-sets` applies it is a
+   screen in the design set first. What every screen of a section shares (a
+   bar, a rail) lives in a layout, so it stays on screen while the screen inside
+   changes; data both the layout and the page need is loaded once per request
+   (React `cache`). Expo: the same with a shared navigator layout.
+5. **Measure before and after.** A performance change states a number: round
+   trips per screen (count Prisma `query` events in a throwaway test), or a
+   trace of the slow interaction. A guess is not a result.
+6. **Session reads may be cached, writes may not.** A signed session cookie
+   (Better Auth's `cookieCache`, a few minutes) spares each read a query. Every
+   write checks the session in the database, so a device signed out elsewhere
+   changes nothing. An e2e test proves it.

package/standards/library/pipeline.md

@@ -0,0 +1,42 @@
+# Pipeline
+
+How a new app is built: five stages, in order, with hard gates. Opt in with
+`standards: [pipeline]`.
+
+These are hard rules. There is no "quick prototype" exception and no "I'll add
+it later" exception.
+
+## The stages
+
+Each stage stops and waits for the owner's approval before the next starts.
+
+1. **HTML designs** → **hard gate: the owner reviews them by hand.**
+   Static HTML in `.context/designs/<surface>/`, built to `design-sets`. Every
+   screen and every state the screen has gets its own file (`design-sets` §5).
+   No app project, no schema, no components until the designs exist and are
+   approved.
+2. **Scaffold the app.** Structure only — no features. For an Expo app, see
+   `expo`. The stage does not end until every credential it produced is backed
+   up (see `secrets`).
+3. **Plan all features**, as `features/` pages.
+4. **Build the schema** → **hard gate: the owner reviews it.**
+5. **Build the app.**
+
+Present the stage, then stop. A plan approved is not code approved. Do not start
+with "a small piece", a spike, or a test harness because it looks useful.
+
+## Principles
+
+These join canon's constitution when a repo opts in. Verdicts cite them by ID.
+
+### C-16 Designs before code
+No app code for a screen that has no approved HTML design. A component in no
+HTML file does not ship. The wireframe is the spec; when code and wireframe
+disagree, fix the code or change the wireframe first and say so.
+*Source:* `pipeline`, `design-sets`.
+
+### C-17 Stages stop at their gates
+Designs, scaffold, plan, schema, build — in order, each waiting for approval.
+Approval of a plan is not approval to code. No "small piece", spike or harness
+to get ahead.
+*Source:* `pipeline`.

package/standards/library/secrets.md

@@ -0,0 +1,37 @@
+# Secrets
+
+Every secret is backed up the moment it exists. Opt in with
+`standards: [secrets]`. The principle is C-10.
+
+Keep one offline backup folder for every credential, outside every repo. It is
+not a repo and never will be — that is what makes it safe to hold plaintext
+credentials. It mirrors the path layout of the repos, so restoring a file is a
+straight `cp` back. The owner decides where it lives and writes that path in
+the `CLAUDE.md` above the repos.
+
+**Whenever a secret is created, rotated, or first needed, copy it into the
+backup folder in the same run and add its line to the folder's `INVENTORY.md`.**
+Not "later", not "once it works" — a secret that exists in only one place is
+already a lost secret. This covers:
+
+| Trigger | What lands in the backup |
+|---|---|
+| New app scaffolded | its `.env`, `eas.json`, `app.config.ts` skeleton |
+| EAS project created | `eas env:list --format long` per environment |
+| RevenueCat configured | the `EXPO_PUBLIC_REVENUECAT_*` keys |
+| iOS signing set up | `.p12`, `.p8`, `.mobileprovision`, `credentials.json` |
+| Play Console wired | `play-service-account.json` |
+| Android signing set up | `keystore.jks` and its passwords |
+| AdMob wired | the `*_AD_ID` values |
+| Firebase project added | `google-services.json`, `GoogleService-Info.plist` |
+| Any new API key or token | the `.env` it lives in |
+
+Rules that go with it:
+
+- `INVENTORY.md` records **key names only**. Never write a secret value into a
+  Markdown file, a commit message, or a chat reply.
+- Never commit a real secret to a repo. `.env.example` is committed; `.env` is
+  not. If one is already tracked, untrack it — do not just add it to
+  `.gitignore` and move on.
+- The folder is a snapshot, not a sync. Re-copy after every rotation.
+- A secret-leak scan must not start failing because of a new secret.

package/standards/library/store-listing.md

@@ -0,0 +1,122 @@
+# Store listing
+
+How an app's App Store and Play Store listing lives in `.context/listing/`.
+Opt in with `standards: [store-listing]`.
+
+`listing/` is outside the app's `assets/`, so it is never bundled into the app.
+
+## The tree is fastlane's, verbatim
+
+```
+.context/listing/
+├── listing.md                 the authored source — fenced blocks generate the .txt files
+├── goldie.config.ts           screenshot and preview capture
+├── android/metadata/          supply metadata_path — ONLY locale folders
+│   └── en-US/
+│       ├── title.txt ≤50 · short_description.txt ≤80
+│       ├── full_description.txt ≤4000 · video.txt (a YouTube URL)
+│       ├── changelogs/<versionCode>.txt · default.txt ≤500
+│       └── images/icon.png · featureGraphic.png
+│                  phoneScreenshots/NN-<screen>.png
+│                  sevenInchScreenshots/ · tenInchScreenshots/
+├── ios/
+│   ├── metadata/              deliver metadata_path — ONLY locale folders + review_information
+│   │   ├── copyright.txt · primary_category.txt · secondary_category.txt
+│   │   ├── app_rating_config.json    the advisory keys fastlane has no .txt for
+│   │   ├── review_information/*.txt
+│   │   └── en-US/name.txt ≤30 · subtitle.txt ≤30 · description.txt ≤4000
+│   │             keywords.txt ≤100 · promotional_text.txt ≤170 · release_notes.txt
+│   │             support_url.txt · marketing_url.txt · privacy_url.txt
+│   ├── screenshots/<locale>/      deliver screenshots_path
+│   ├── app-previews/<locale>/     15–30s, 886×1920 H.264
+│   └── iap.md
+└── out/                       gitignored — the capture tool's raw output, before the mapper
+```
+
+The leaf names are **not ours to choose**. `supply`, `deliver`, `screengrab`,
+F-Droid and IzzyOnDroid all parse these exact strings — `full_description.txt`,
+`phoneScreenshots`, `changelogs/<versionCode>.txt`. Rename one character and a
+zero-maintenance upload becomes a custom transform kept up in every repo
+forever.
+
+**Each store folder is self-contained, and `metadata/` is why.** Both tools
+treat every *directory* inside `metadata_path` as a locale — deliver's
+`Loader.language_folders` hard-errors on any subdirectory that is not a language
+name (`deliver/lib/deliver/loader.rb:167`), and supply's `all_languages` is
+literally `Dir.entries(metadata_path)`. Worse, deliver runs
+`FileUtils.mkdir_p(screenshots_path)` *before* it validates, so putting
+`screenshots/` directly inside `ios/` would have deliver create the offending
+folder and then abort on it, on a clean clone.
+
+So the locale tree gets its own `metadata/` level, and everything else a store
+needs is a sibling of it, inside that store's folder:
+
+```ruby
+supply(metadata_path: ".context/listing/android/metadata")
+deliver(metadata_path:     ".context/listing/ios/metadata",
+        screenshots_path:  ".context/listing/ios/screenshots",
+        app_previews_path: ".context/listing/ios/app-previews")
+```
+
+Files at `metadata/` root are fine — only directories are validated.
+
+## Rules
+
+1. **`listing.md` is authored; the `.txt` files are generated from it**,
+   committed, and never hand-edited.
+2. **`listing/ios/` is canonical for Apple.** A repo-root `store.config.json` is
+   generated from it or deleted. One format for both stores, and
+   `deliver download_metadata` pulls the **live** listing down so you can diff
+   it, which EAS metadata cannot do.
+3. **deliver infers the device from image resolution**, not folder name, so a
+   screenshot one pixel off lands on the wrong device silently.
+4. **Screenshot file names are `NN-<screen>.png`, zero-padded.** fastlane uploads
+   in alphanumeric file name order, so `10.png` sorting before `2.png` is a real
+   bug, not a cosmetic one.
+5. **A locale appears in `listing/*/metadata/<locale>/` and nowhere else**, and
+   adding one means adding it to *both* stores or writing down in `tasks.md` why
+   not. An app that ships three languages with an English-only listing is a gap,
+   and it has to look like one.
+6. **Store images are exports.** `listing/*/images/` is generated from
+   `designs/brand/` (see `design-sets` §1).
+
+## Screenshots and previews
+
+They are captured by **goldie** (`goldie all --config
+.context/listing/goldie.config.ts`). Its output axes are inverted from
+fastlane's, so a mapper moves them:
+
+| goldie output | fastlane destination |
+|---|---|
+| `out/screenshots/pixel-10-pro/<locale>/` | `android/metadata/<locale>/images/phoneScreenshots/` |
+| `out/screenshots/iphone-6.9/<locale>/` | `ios/screenshots/<locale>/` |
+| `out/previews/iphone-6.9/<locale>/preview.mp4` | `ios/app-previews/<locale>/` |
+
+Run it as `pnpm listing:capture`, never `goldie all` alone: goldie writes only
+to the gitignored `out/`, and the command's last step is the mapper.
+
+**The store art has a house style**, the same in every app: `template:
+"showcase"`, `layout: "classic"`, `screenOnly: true`, Merriweather, the
+`17-pro-silver` frame. Only the background is the app's own. It is written in
+`goldie.config.ts` and again in `goldie.design.json` — the file `goldie studio`
+saves and the CLI lays over the config. A repo check should fail when an app
+differs from the reference repo's style or when its two files disagree.
+
+## Release notes come from `features/`
+
+A feature page carries `release: x.y.z` and a `## Store copy` blockquote (see
+`context-layout`). `pnpm listing:notes` (`scripts/release-notes.mjs`, copied
+from the reference repo) collects the blockquote from every feature with that
+release and writes both `listing/ios/metadata/en-US/release_notes.txt` and
+`listing/android/metadata/en-US/changelogs/<versionCode>.txt`. That makes the
+board the *source* of the What's New text, so it earns its keep every release
+instead of rotting the way every roadmap document does.
+
+## Store files outside `listing/`
+
+- `legal/declaration.yml` — the single source for privacy declarations, in
+  Apple's `NSPrivacyCollectedDataType` vocabulary. The legal pages and
+  `legal/play-data-safety.csv` are produced from it, never hand-edited.
+- `metrics/aso/keywords.yml` (authored) and `metrics/aso/scans/<date>/ranks.csv`
+  — keyword tracking.
+- `listing/ios/iap.md` — the in-app purchases as the store shows them.