@ericrisco/rsc 0.1.43 → 0.1.45

package/skills/fastapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fastapi
-description: "Use when building, reviewing, testing, securing or deploying a FastAPI / async Python service. Triggers: creating endpoints/routers, Pydantic v2 models (Create/Update/Response), dependency injection, async SQLAlchemy 2.0 + Alembic, OAuth2/JWT auth + RBAC, pytest + httpx ASGITransport tests, CORS / rate limiting / secret handling, uvicorn/gunicorn + structured logging + healthchecks + graceful shutdown, pyproject + ruff + mypy strict + uv. Any .py file importing fastapi, pydantic, sqlalchemy, starlette, or a pyproject.toml declaring those."
+description: "Use when building, reviewing, testing, securing or shipping a FastAPI / async Python service — routers, Pydantic v2 schemas, dependency injection, async SQLAlchemy 2.0, OAuth2/JWT, ASGITransport tests, production wiring. NOT language-level Python or packaging (that is `python`), NOT engine-level SQL (that is `postgresdb`), NOT framework-agnostic REST contracts (that is `api-design`)."
 tags: [python, api, async, backend, rest]
 recommends: [postgresdb, secure-coding, deployment]
 origin: risco
@@ -20,25 +20,16 @@ pytest 8 + pytest-asyncio 1.0+ (`asyncio_mode=auto`), ruff 0.7+, mypy 1.13+ stri
 uv 0.5+, uvicorn 0.32+ / gunicorn 23+ + uvicorn-worker 0.3+, PyJWT 2.10+, argon2-cffi 23+,
 pip-audit 2.7+, PostgreSQL 16. (All lower bounds; install the latest in each line.)
 
-## When to use
-
 > **⚠️ SDD new-feature gate — read this first.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP — do **not** write feature code yet. Hand off to `../specify/SKILL.md` first: it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build here directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
 
-- Writing or reviewing any FastAPI route, router, dependency, schema, or app factory.
-- Designing async DB access (SQLAlchemy 2.0), migrations (Alembic), or eager-loading.
-- Adding auth (OAuth2 password flow + JWT), RBAC, password hashing.
-- Writing pytest suites for an async API (ASGITransport, `dependency_overrides`, transactional DB).
-- Hardening (CORS, rate limit, secrets, log redaction, dependency audit) or productionizing.
-- Setting up `pyproject.toml`, ruff + mypy strict, uv/pip-tools dependency management.
-
-## When NOT to use
-
-- Django / Flask / DRF apps → not this skill.
-- Sync WSGI services, data-science notebooks, CLI-only scripts with no HTTP surface.
-- Pure REST contract questions (status codes, URL naming, versioning, cursor vs offset) → general REST-design territory (this skill covers the FastAPI *implementation* of those contracts).
-- Frontend/Next.js, Go, Flutter work → their own skills.
-- Generic secure-coding rules not specific to Python/FastAPI → **See Also `secure-coding`**.
-- Container/Compose/CI deploy mechanics → **See Also `deployment`** (this skill keeps only a Docker *note*).
+Out of scope, and where it goes instead: [`django`](../django/SKILL.md) for Django; Flask / sync WSGI,
+notebooks and CLI-only scripts (no skill); language-level Python, typing and packaging →
+[`python`](../python/SKILL.md); framework-agnostic REST contracts — status codes, URL naming, versioning,
+cursor vs offset → [`api-design`](../api-design/SKILL.md) (this skill covers their FastAPI *implementation*);
+engine-level schema, indexing, EXPLAIN, zero-downtime migrations, PgBouncer →
+[`postgresdb`](../postgresdb/SKILL.md); language-agnostic injection / secret / authz theory →
+[`secure-coding`](../secure-coding/SKILL.md); Dockerfile, Compose and CI/CD mechanics →
+[`deployment`](../deployment/SKILL.md) (this skill keeps only a Docker *note*).
 
 ## Decision rules
 
@@ -140,11 +131,11 @@ app = create_app()
 Accepting an optional `settings` argument lets tests build the app with overridden config
 without touching the `get_settings` cache. **Bad** = `allow_origins=["*"]` with
 `allow_credentials=True` — browsers reject it and Starlette refuses to echo `*` for
-credentialed requests. `→ references/production.md` for proxy headers / logging wiring at
+credentialed requests. → [`references/production.md`](references/production.md) for proxy headers / logging wiring at
 startup.
 
 To inject servers / security schemes / a logo into the generated OpenAPI doc, assign a
-custom builder to `app.openapi` inside `create_app()`. `→ references/production.md`
+custom builder to `app.openapi` inside `create_app()`. → [`references/production.md`](references/production.md)
 (Customizing the OpenAPI schema).
 
 ## Configuration (pydantic-settings)
@@ -229,7 +220,7 @@ v2 migration cheats: use `.model_dump()` not `.dict()`; `.model_validate(obj)` n
 `field_validator`/`model_validator` not `@validator`/`@root_validator`.
 
 **Bad** = a response model with `hashed_password: str` (leaks the hash). **Good** = the
-`UserResponse` above (no secret fields). `→ references/security.md`.
+`UserResponse` above (no secret fields). → [`references/security.md`](references/security.md).
 
 ## Dependency injection
 
@@ -275,7 +266,7 @@ def get_pagination(
 PageParams = Annotated[Pagination, Depends(get_pagination)]
 ```
 
-`→ references/database.md` for `async_session_factory` wiring; `→ references/security.md`
+→ [`references/database.md`](references/database.md) for `async_session_factory` wiring; → [`references/security.md`](references/security.md)
 for `get_current_user` and `require_roles`.
 
 ## Routers & endpoints
@@ -361,8 +352,9 @@ def register_exception_handlers(app: FastAPI) -> None:
 Keep this envelope identical across every handler — one `code`/`message`/`details` shape so
 clients parse errors once. Subclass `AppError` per failure (each fixes a `code` + status):
 `NotFoundError` (404), `ConflictError` (409), `Unauthorized` (401), `Forbidden` (403) — full
-hierarchy in `→ references/production.md` (AppError subclasses). **See Also `secure-coding`**
-for why error responses must never leak internals (stack traces, SQL, secrets).
+hierarchy in → [`references/production.md`](references/production.md) (AppError subclasses).
+[`secure-coding`](../secure-coding/SKILL.md) has the why: error responses must never leak internals
+(stack traces, SQL, secrets).
 
 ## Async SQLAlchemy 2.0 (essentials)
 
@@ -401,7 +393,9 @@ async def list_users(db: AsyncSession, limit: int, offset: int) -> list[User]:
     return list(result.scalars().all())
 ```
 
-`→ references/database.md` for relationships, N+1 / eager loading, repository, Alembic, pooling.
+Fetch by PK with `await db.get(Model, pk)`, by unique key with `.scalar_one_or_none()`; eager-load with
+`selectinload` (collections) / `joinedload` (many-to-one).
+→ [`references/database.md`](references/database.md) for relationships, N+1 / eager loading, repository, Alembic, pooling.
 
 ## Background tasks vs real queues
 
@@ -428,74 +422,48 @@ a transactional fixture — so every test rolls back. Use `pytest-asyncio` with
 `asyncio_mode = "auto"` (no `@pytest.mark.asyncio`), and assert secrets never serialize (e.g.
 `assert "hashed_password" not in resp.json()`). TDD red→green→refactor. Full fixtures
 (transactional `begin_nested`, auth overrides, respx, coverage gate) in
-`→ references/testing.md`.
+→ [`references/testing.md`](references/testing.md).
 
 ## Security
 
 Full hardening playbook — argon2 hashing, OAuth2 + JWT (claims validated, `algorithms`
 pinned), `get_current_user`/`require_roles` RBAC, CORS, shared-store rate limiting, injection,
 `SecretStr` + log redaction, security headers, `pip-audit` — lives in
-`→ references/security.md`. The non-negotiables also appear in the anti-patterns table below.
-**See Also `secure-coding`** for the language-agnostic theory.
+→ [`references/security.md`](references/security.md) — including the exact `argon2.PasswordHasher().hash(pw)` and
+`jwt.decode(t, key, algorithms=[...], audience=..., issuer=...)` calls. See
+[`secure-coding`](../secure-coding/SKILL.md) for the language-agnostic theory.
 
 ## Production
 
 ASGI/worker math, structured JSON logging + request-id, liveness vs readiness probes, graceful
 shutdown, keyset pagination, caching, `ORJSONResponse` and proxy headers all live in
-`→ references/production.md`. **See Also `deployment`** for the Dockerfile and CI/CD pipeline.
+→ [`references/production.md`](references/production.md). See [`deployment`](../deployment/SKILL.md) for the
+Dockerfile and CI/CD pipeline.
 
-## Anti-patterns / rationalizations → STOP
+## Anti-patterns
 
-| Rationalization | Reality → STOP |
-|---|---|
-| "I'll just call `requests` in this async route, it's one call" | Blocks the event loop → use `httpx.AsyncClient`. |
-| "`.dict()` still works" | Pydantic v2: use `.model_dump()`; `.dict()`/`from_orm` are deprecated. |
-| "Return the ORM object directly, FastAPI will handle it" | Leaks columns + lazy-loads in serializer → declare `response_model`. |
-| "`allow_origins=['*']` + credentials is fine for now" | Browser rejects it; Starlette blocks it. Pin origins. |
-| "I'll decode the JWT without checking `exp`/`aud`" | Forged/replayed tokens. Validate exp/iss/aud + pin alg. |
-| "Build the WHERE with an f-string, it's internal" | SQLi. Bound params / SQLAlchemy expressions only. |
-| "One global session for the whole app is simpler" | Cross-request data bleed + concurrency bugs. One session per request. |
-| "Catch `Exception` and return the message to the client" | Leaks internals. Log it, return generic 500. |
-| "`BackgroundTasks` is good enough for the payment webhook retry" | No durability/retry. Use a real broker. |
-| "mypy strict is too noisy, I'll skip it" | Strict catches the bugs FastAPI's runtime won't. Keep it. |
-| "Commit inside the handler so I control it" | Let `get_db` own commit/rollback; handlers stay thin. |
-| "Default-mutable arg / module-level engine at import is fine" | Mutable defaults bite; engine must live in lifespan. |
-
-## Quick reference
-
-| Task | Idiom |
+| Anti-pattern | Why it breaks → do this |
 |---|---|
-| Async route doing I/O | `async def` + `httpx.AsyncClient` / asyncpg |
-| Request DB session | `db: Annotated[AsyncSession, Depends(get_db)]` |
-| Run a query / get rows | `await db.execute(select(Model)...)` → `result.scalars().all()` / `.scalar_one_or_none()` |
-| Get by PK | `await db.get(Model, pk)` |
-| Eager-load | `selectinload(Model.items)` (collection) / `joinedload(Model.parent)` (many-to-one) |
-| Settings | `Annotated[Settings, Depends(get_settings)]` |
-| Serialize ORM → schema | `model_config = ConfigDict(from_attributes=True)` |
-| Created response | `status_code=201` + `Location` header |
-| Test client | `AsyncClient(transport=ASGITransport(app=app))` + `app.dependency_overrides[dep] = fake` |
-| Hash password / verify JWT | `argon2.PasswordHasher().hash(pw)` / `jwt.decode(t, key, algorithms=[...], audience=..., issuer=...)` |
-
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this project's API decisions in
-`02-DOCS/wiki/stack/fastapi.md` and index it in `02-DOCS/wiki/index.md` (the Knowledge map index; root
-`CLAUDE.md` points to it), so the next agent inherits the conventions instead of re-deriving them.
-
-- **Read it first** on every use and stay consistent; bump its `Updated` date when a
-  convention changes.
-- **Create/update it** with the project's real choices — auth model (JWT/OAuth2 provider,
-  token TTLs), DB session + migration tool, error-envelope shape, settings/secrets approach,
-  deployment target — indexing it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it) if absent.
-
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Technical conventions are
-*recorded, not gated* — never block the task on this.
-
-## See Also
-
-- [`secure-coding`](../secure-coding/SKILL.md) — language-agnostic injection / secret / authz hardening behind this skill's security rules.
-- [`postgresdb`](../postgresdb/SKILL.md) — engine-level schema design, indexing, EXPLAIN, zero-downtime migrations, PgBouncer (below the SQLAlchemy layer this skill drives).
-- [`deployment`](../deployment/SKILL.md) — Dockerfile, Compose, CI/CD, container runtime (this skill keeps only a Docker note).
-- References: [`references/testing.md`](references/testing.md), [`references/database.md`](references/database.md), [`references/security.md`](references/security.md), [`references/production.md`](references/production.md).
-- Verify gate: [`scripts/verify.sh`](scripts/verify.sh).
+| `requests` (or any blocking call) inside an `async def` route | Blocks the event loop → use `httpx.AsyncClient`. |
+| `.dict()` / `from_orm()` on a model | Pydantic v2: use `.model_dump()`; `.dict()`/`from_orm` are deprecated. |
+| Returning the ORM object with no `response_model` | Leaks columns + lazy-loads in serializer → declare `response_model`. |
+| `allow_origins=['*']` together with credentials | Browser rejects it; Starlette blocks it. Pin origins. |
+| Decoding a JWT without checking `exp`/`aud` | Forged/replayed tokens. Validate exp/iss/aud + pin alg. |
+| Building the WHERE clause with an f-string | SQLi. Bound params / SQLAlchemy expressions only. |
+| One global session shared by the whole app | Cross-request data bleed + concurrency bugs. One session per request. |
+| Catching `Exception` and returning its message | Leaks internals. Log it, return generic 500. |
+| `BackgroundTasks` for a payment-webhook retry | No durability/retry. Use a real broker. |
+| Skipping `mypy --strict` because it is noisy | Strict catches the bugs FastAPI's runtime won't. Keep it. |
+| Committing inside the handler | Let `get_db` own commit/rollback; handlers stay thin. |
+| Default-mutable arg / engine built at import time | Mutable defaults bite; engine must live in lifespan. |
+
+## Project grounding
+
+In a project with a `02-DOCS/` layer ([`harness`](../harness/SKILL.md)), read
+`02-DOCS/wiki/stack/fastapi.md` first and stay consistent with it; create or update it with this
+project's real choices — auth model (JWT/OAuth2 provider, token TTLs), DB session + migration tool,
+error-envelope shape, settings/secrets approach, deployment target — bump its `Updated` date, and index
+it in `02-DOCS/wiki/index.md`. No `02-DOCS/`? Skip silently. Conventions are *recorded, not gated* —
+never block the task on this.
+
+Verify gate: [`scripts/verify.sh`](scripts/verify.sh).

package/skills/flutter/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flutter
-description: "Use when building, structuring, testing or optimizing a Flutter app (Dart 3, Riverpod 3 / Bloc, go_router, Material 3, freezed, widget & golden tests). Triggers: creating a Flutter feature, choosing state management, wiring navigation/auth guards, modeling async/error state, JSON/dio data layer, killing widget rebuilds/jank, or writing widget/golden/integration tests. Stack: Flutter 3.44 / Dart 3.12."
+description: "Use when building, structuring, testing or optimizing a Flutter app — feature-first layering, Riverpod 3 or Bloc, typed go_router, freezed models, a dio data layer, Material 3, jank hunting, widget/golden tests. Targets Flutter 3.44 / Dart 3.12. NOT React Native (that is `react-native`), NOT Compose Multiplatform (that is `compose-multiplatform`)."
 tags: [flutter, dart, mobile, app, ios, android]
 recommends: [design, deployment]
 origin: risco
@@ -8,35 +8,28 @@ origin: risco
 
 # Flutter & Dart app architecture
 
-## What this skill is
+The opinionated default stack for a production Flutter app: **feature-first + layered** folders,
+**Riverpod 3** with codegen for shared/async state, a **typed go_router**, **freezed** immutable
+models, a **dio** data layer, and explicit `Result<T, Failure>` error modeling — all on **Material 3**.
+Escape hatches are first-class: **Bloc/Cubit** instead of Riverpod when the team already runs Bloc,
+and raw `http`/`get_it` are allowed — but **pick one of each per app, never mix two**. Pinned versions
+this skill targets: **Flutter 3.44 / Dart 3.12**, **Riverpod 3.0**, **go_router 17.2.x**
+(+ `go_router_builder 4.3.x`), **freezed 3.x** / `json_serializable`, **dio 5.x**, **mocktail 1.x**.
 
-The opinionated default stack for a production Flutter app: **feature-first + layered**
-folders, **Riverpod 3** with codegen for shared/async state, a **typed go_router**, **freezed**
-immutable models, a **dio** data layer, and explicit `Result<T, Failure>` error modeling — all on
-**Material 3**. Escape hatches exist and are first-class: use **Bloc/Cubit** instead of Riverpod when
-the team already runs Bloc, and raw `http`/`get_it` are allowed — but **pick one of each per app, never
-mix two**. Pinned versions this skill targets: **Flutter 3.44 / Dart 3.12**, **Riverpod 3.0**,
-**go_router 17.2.x** (+ `go_router_builder 4.3.x`), **freezed 3.x** / `json_serializable`, **dio 5.x**,
-**mocktail 1.x**. When you load this skill inside the user's repo, it touches only the `pubspec.yaml`
-subproject — never the FastAPI/Go/Next.js siblings.
-
-## When to use / When NOT to use
+## Boundaries
 
 > **⚠️ SDD new-feature gate — read this first.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP — do **not** write feature code yet. Hand off to `../specify/SKILL.md` first: it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build here directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
 
-**Use when:**
-
-- Building a new Flutter feature or screen, or choosing/refactoring state management.
-- Setting up routing, DI, theming, or the data layer; reviewing Dart for null-safety, sealed/pattern
-  matching, immutability, async-gap discipline, or rebuild hygiene.
-- Investigating performance/jank, wiring build flavors, or scaffolding unit/widget/golden/integration tests.
+This skill owns the `pubspec.yaml` subproject and nothing else in the repo. Hand off when the UI is
+Compose Multiplatform (`compose-multiplatform`), SwiftUI/native iOS (`swift-ios`) or React Native
+(`react-native`); when the work is on a FastAPI/Go/Next.js sibling in the same monorepo (use that
+skill). For a pure Dart **server/CLI** with no widget tree, general Dart applies but skip the
+UI/nav/perf references. For a single-file throwaway sample, say architecture is overkill and do not
+impose layering.
 
-**Do NOT use when:**
-
-- The UI is Compose Multiplatform, native Android-Kotlin, or SwiftUI — use the Compose/native skill.
-- It is a pure Dart **server/CLI** with no widget tree — general Dart applies, but skip the UI/nav/perf references.
-- The work is on a FastAPI/Go/Next.js sibling in the same monorepo — use that skill; this one only owns the Flutter subproject.
-- It is a single-file throwaway sample — note that architecture is overkill, do not impose layering.
+Around the edges: `harness` owns the workspace `01-TOOLS`/`02-DOCS` layer and flavor secrets; `fastapi`,
+`go` and `nextjs` build the backends this app talks to; `secure-coding` reviews token handling and
+deep-link validation; `deployment` handles store/CI release; `design` owns the Material 3 token system.
 
 ## Decision rules
 
@@ -379,70 +372,29 @@ encapsulation → `references/i18n-and-dependencies.md`.
 - Dependency hygiene: `pubspec.lock` committed for apps, `flutter pub outdated` audited on a cadence,
   dependencies vetted by pub points before adding.
 - No `print()` → `dart:developer` `log()`.
+- Gate the branch with `scripts/verify.sh`, run inside the Flutter project (format / codegen / analyze / tests).
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Why it fails / do instead |
 |---|---|
-| "I'll just `user!` here" | bang crashes in prod; use `?.`/`??` or an if-case pattern. |
-| "`_buildHeader()` is fine" | extract to a `const` widget class — enables element reuse + const propagation. |
-| "`bool isLoading` + `bool isError` is simpler" | allows impossible states; use `AsyncValue`/sealed. |
-| "I'll `setState` at the top of the page" | rebuilds the whole subtree; scope it or `.select()`. |
-| "global provider for this checkbox" | ephemeral UI state = local `setState`/`ValueNotifier`. |
-| "mix `Navigator.push` with go_router for one screen" | one router; mixing breaks deep links + back stack. |
-| "use `context` after `await`, it's fine" | guard `context.mounted` / `ref.mounted`; stale context crashes. |
-| "hardcode `Colors.blue` just here" | use `colorScheme`; breaks dark mode + theming. |
-| "`ListView(children: [...])` for the feed" | use `.builder`; the concrete form builds all children eagerly. |
-| "`catch (e)` everything" | use `on`-typed clauses; never catch `Error` (it is a bug). |
-| "ship raw `DioException.toString()` to the user" | map to a `Failure` with a localized message. |
-| "`print()` for logging" | use `dart:developer` `log()` — has levels and can be filtered. |
-| "use legacy `StateProvider`" | Riverpod 3 `Notifier`; legacy is `package:riverpod/legacy.dart` only. |
-| "`pumpAndSettle` will fix the flaky test" | hangs on infinite animations; use explicit `pump(Duration)`. |
-
-## Quick reference
-
-| Concern | Default API | Reference |
-|---|---|---|
-| model | `@freezed` | `references/architecture-and-state.md` |
-| sync state | `Notifier` / `Cubit` | `references/architecture-and-state.md` |
-| async state | `AsyncNotifier` / `AsyncValue` | `references/architecture-and-state.md` |
-| DI | `@riverpod` providers / `get_it` | `references/architecture-and-state.md` |
-| routing | typed `go_router` | `references/ui-and-navigation.md` |
-| errors | `Result` / sealed | `references/architecture-and-state.md` |
-| http | `dio` + interceptor | `references/architecture-and-state.md` |
-| long list | `ListView.builder` | `references/performance.md` |
-| off-thread | `Isolate.run` | `references/performance.md` |
-| unit test | `ProviderContainer.test()` | `references/testing.md` |
-| widget test | `ProviderScope` override | `references/testing.md` |
-| golden | `matchesGoldenFile` | `references/testing.md` |
-| l10n | ARB + `gen_l10n` + `intl` | `references/i18n-and-dependencies.md` |
-| deps | `flutter pub outdated` / `melos` | `references/i18n-and-dependencies.md` |
-| verify | `scripts/verify.sh` | `scripts/verify.sh` |
-
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's app decisions there and index them in `02-DOCS/wiki/index.md`, so the next
-agent inherits the conventions instead of re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/flutter.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with the project's real choices — the state-management choice (Riverpod/Bloc), the architecture layers, routing, the Material 3 token system, and codegen setup —
-   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
-3. **Read it first on every use** and stay consistent; when a convention changes, update the
-   article (bump its `Updated` date) in the same change.
-
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
-brand study, technical conventions are *recorded, not gated* — never block the task on this.
-
-## See Also
-
-- `references/architecture-and-state.md` — layering, DI, Result/Failure, Riverpod 3 & Bloc deep dives.
-- `references/ui-and-navigation.md` — widgets, Material 3 tokens, responsive, typed go_router, a11y.
-- `references/testing.md` — unit/widget/golden/integration + coverage.
-- `references/performance.md` — rebuilds, paint, jank, isolates, build flavors.
-- `references/i18n-and-dependencies.md` — ARB/ICU l10n, RTL, locale-aware formatting, pub points, `melos`.
-- `scripts/verify.sh` — run inside your Flutter project to gate format/codegen/analyze/tests.
-- Sibling skills: `harness` (workspace `01-TOOLS`/`02-DOCS`, flavor secrets); `fastapi`,
-  `go` and `nextjs` for the backends this app talks to; `secure-coding` for token handling and deep-link
-  validation; `deployment` for store/CI release; `design` for the Material 3 token system.
+| `user!` to unwrap | bang crashes in prod; use `?.`/`??` or an if-case pattern. |
+| `_buildHeader()` helper methods | extract to a `const` widget class — enables element reuse + const propagation. |
+| `setState` at the top of the page | rebuilds the whole subtree; scope it or `.select()`. |
+| `Navigator.push` mixed into go_router for one screen | one router; mixing breaks deep links + back stack. |
+| `context` used after an `await` | guard `context.mounted` / `ref.mounted`; a stale context crashes. |
+| hardcoded `Colors.blue` | use `colorScheme`; hardcoding breaks dark mode + theming. |
+| `ListView(children: [...])` for a feed | use `.builder`; the concrete form builds all children eagerly. |
+| `catch (e)` on everything | use `on`-typed clauses; never catch `Error` (it is a bug). |
+| raw `DioException.toString()` shown to the user | map to a `Failure` with a localized message. |
+| `print()` for logging | use `dart:developer` `log()` — has levels and can be filtered. |
+
+## Project grounding (02-DOCS)
+
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), this app's decisions
+live in `02-DOCS/wiki/stack/flutter.md`, indexed in `02-DOCS/wiki/index.md`. Read it first and stay
+consistent. Missing or stale? Write the real choices there — state management (Riverpod/Bloc), the
+architecture layers, routing, the Material 3 token system, codegen setup — index it, and bump its
+`Updated` date in the same change a convention changes, so the next agent inherits it instead of
+re-deriving it. No `02-DOCS/` layer? Skip silently: technical conventions are *recorded, not gated*,
+so never block the task on this.