@horka/app-forge 0.1.0

package/templates/core/CLAUDE.md

@@ -0,0 +1,36 @@
+# {{PROJECT_NAME}} — Claude Code Operating Manual
+
+Scaffolded by **AppForge**: a Claude-Code-first project factory. You (Claude) are the team
+lead AND the primary developer. This manual encodes hard-won lessons — follow it exactly.
+
+## Identity
+- Project: **{{PROJECT_NAME}}** · Identifier: `{{BUNDLE_ID}}`
+- Platform pack: {{PACK_LABEL}}
+
+## Session protocol (MANDATORY)
+1. **Session start**: run the `restore-context` skill — read `.claude/memory/*.md` first. Never invent project facts.
+2. **Empty project / new idea**: run the `kickoff` skill — interview → PRD → slices → autonomous build.
+3. **After significant work**: run the `save-context` skill (PROJECT_STATE.md at minimum).
+
+## Knowledge base — read before coding
+`docs-architecture/` is law. Read the relevant doc BEFORE touching that area:
+- `ARCHITECTURE_PRINCIPLES.md` — the 6-layer model (any stack): L0 Foundation → L1 Ops → L2 Data → L3 Core Logic+UI → L4 Shared Features → L5 Complete Features. Imports point downward only.
+- `DELIVERY.md` — vertical slices, build loop, validation etiquette, memory protocol.
+- `MULTI_REPO_CONTRACT.md` — product spans repos (API + SDK + clients)? Implementation order + gates.
+- `SDK_CONTRACT.md` — shipping or consuming a typed SDK between backend and clients.
+- `SECURITY_USER_URLS.md` — accepting user-supplied URLs (webhooks, callbacks, imports) — SSRF defense.
+- `DOCS_PLACEMENT.md` — where knowledge lives (two-tier rule); read before writing any doc.
+- `ANTI_PATTERNS.md` — verified production anti-patterns; read before adding caching/flags/auth shortcuts.
+- Platform docs (from the pack) — conventions, build commands, platform gotchas. They refine,
+  never contradict, the files above.
+
+## Non-negotiable rules
+- **Dependency direction**: a layer imports only layers below it (sole exception: L2 implements L3 contracts). L3 logic stays pure (no UI/IO imports). Bricks communicate by callbacks, never by importing app state.
+- **Design tokens only** — no hardcoded colors/fonts/spacing in presentation code.
+- **Proof over claims**: layer tests green → app build green → eyes-on proof (screenshot/response) before anything is "done". Failures reported with output.
+- **Every domain rule ships with its test** in the same change.
+- **Memory is law**: contradictions between memory and code → code wins, then fix the memory file.
+
+## Git
+- Never push without explicit user approval. Feature branches; commit format `add/update/fix(scope) - description`.
+- No AI attribution in commits or file headers.

package/templates/core/claude/memory/ARCHITECTURE.md

@@ -0,0 +1,20 @@
+# {{PROJECT_NAME}} — Architecture Memory
+
+> Project-specific structure decisions. The generic 6-layer model lives in
+> `docs-architecture/ARCHITECTURE_PRINCIPLES.md` — this file records how THIS app instantiates
+> them in THIS stack's module system (packages / workspaces / modules — whatever the pack uses).
+
+## Layers (instantiated)
+> Filled at kickoff once the stack is known. Map each layer (L0–L5) to a concrete location in
+> this project's module system. Example shape — replace with the real paths:
+- **L0 Foundation** — design tokens, base utilities: _(location TBD at kickoff)_.
+- **L3 Core Logic** — domain entities + engines + repository contracts: _(location + entities TBD)_.
+- **L2 Data** — repository implementations, clients, mapping: _(location TBD)_.
+- **L4 Shared Features** — reusable feature bricks: _(none yet)_.
+- **L5 Complete Features** — screens/pages/endpoints + wiring: _(none yet)_.
+
+## Domain map
+_(filled at kickoff: entity → layer location/file)_
+
+## Deviations from the boilerplate
+_(record any conscious deviation + why)_

package/templates/core/claude/memory/COMMANDS.md

@@ -0,0 +1,13 @@
+# {{PROJECT_NAME}} — Commands
+
+> Only commands proven to work in THIS project, with exact flags.
+> Filled at kickoff once the stack's build/test/run loop is established.
+
+## Layer loop (fast — always first)
+_(per-layer build + test commands)_
+
+## App target
+_(full build / run commands)_
+
+## Validation
+_(how proof is captured: screenshot, curl, recording…)_

package/templates/core/claude/memory/DECISIONS.md

@@ -0,0 +1,5 @@
+# {{PROJECT_NAME}} — Decisions
+
+> One line per decision, dated. A future session must NOT re-litigate these.
+
+- (YYYY-MM-DD) _Example: persistence = local-only for v1, no backend — fastest path to a shippable slice._

package/templates/core/claude/memory/NEXT_STEPS.md

@@ -0,0 +1,11 @@
+# {{PROJECT_NAME}} — Next Steps
+
+## Now
+1. Run `/kickoff`.
+
+## Next
+_(slice backlog appears here after kickoff)_
+
+## Blockers
+_(waiting-on-user items: accounts/credentials, backend provisioning, store/registry setup,
+real-environment tests — whatever only the user can unblock for this stack)_

package/templates/core/claude/memory/PROJECT_STATE.md

@@ -0,0 +1,24 @@
+# {{PROJECT_NAME}} — Project State
+
+> Single source of truth for "where are we". Updated after every significant change.
+> Keep ≤ 300 lines: prune completed/stale entries into git history.
+
+## Status
+- Phase: ⏳ not started — run `/kickoff` to begin.
+- Current slice: —
+- Last session: —
+
+## Done ✅
+_(nothing yet)_
+
+## In progress 🚧
+_(nothing yet)_
+
+## Gotchas log
+> Format: **Symptom** → cause → fix. These save future sessions hours.
+
+_(none yet)_
+
+## Launch blockers
+_(filled during kickoff: things only the user can unblock — accounts/credentials, backend
+provisioning, store/registry setup, privacy policy, etc. The pack/kickoff names the specifics.)_

package/templates/core/claude/skills/kickoff/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: kickoff
+description: Turn a product idea into a built, running app — you are the team lead. Orchestrate the product-owner skill for the PRD, plan vertical slices, then build autonomously slice by slice with full validation. Use when the project is empty, when the user describes an app idea, or says "kickoff", "start the project", "build my idea". Do NOT use for adding features or fixes to an established codebase — that's the normal delivery loop (DELIVERY.md).
+---
+
+# Kickoff — idea → running app (you are the team lead)
+
+You own the whole delivery: product, architecture, code, validation. Earn that trust:
+follow every gate below. Do not skip phases. Do not start coding before Phase 3 is approved.
+
+## Phase 0 — Context
+1. Read `CLAUDE.md`, `docs-architecture/ARCHITECTURE_PRINCIPLES.md` and `docs-architecture/DELIVERY.md`.
+2. Read the **platform pack docs** in `docs-architecture/` (conventions, build commands, platform gotchas).
+   - **No platform pack installed?** Establish the stack's build/test/run loop yourself (verify the
+     commands actually work), write it to `.claude/memory/COMMANDS.md`, and tell the user best-practice
+     coverage is reduced for this stack.
+3. Read `.claude/memory/*.md` — if a PRD/slice plan already exists, resume instead of restarting.
+4. **Tooling gate** — split by severity:
+   - **Build/run tooling (hard STOP).** Verify the pack's **documented** requirements (read
+     them from its `CLAUDE.md` / `COMMANDS.md` — there is no `pack.json` in a generated project)
+     by RUNNING their commands (version checks). A missing build tool → STOP: give the one-line
+     install and ask the user to run it (or approve a reduced-proof plan — if the pack provides a
+     `WORKFLOW.md` / proof ladder, follow it; otherwise agree a plan and record it in
+     `.claude/memory/DECISIONS.md`). Building a whole project that ends with "zero pixels ever
+     seen" is not a default anyone chose.
+   - **Docs/MCP servers (WARNING, not STOP).** Check that MCP servers from `.mcp.json` respond.
+     A missing or non-responding **docs** MCP (e.g. context7) is a WARNING: note it, tell the
+     user docs lookups are degraded, and continue. (Caveat: a bare `npx` command can fail to
+     start on native Windows because npm installs a `.cmd` shim — if the docs MCP won't launch
+     there, that's the likely cause; it's not a blocker.) Only build tooling earns a hard STOP.
+
+## Phase 1–2 — Product (delegate to the PO)
+Run the **`product-owner` skill**: one focused interview → `docs/PRD.md` (lean, ≤150 lines, with
+domain glossary + epics/stories) → explicit user OK. If a full BMAD install is present, you may use
+its PM/PO workflows instead. You stay team lead: challenge the PO output if the domain glossary
+doesn't map cleanly onto the layer model.
+
+## Phase 3 — Slice plan
+Map the PRD onto the layers (`ARCHITECTURE_PRINCIPLES.md`) and write `docs/SLICES.md`:
+- **Slice 0 — skeleton runs**: app boots empty on the target (simulator/emulator/browser/server). Proof required.
+- **Slice 1 — domain heart**: L3 entities + main engine fully tested + the ONE main screen on InMemory data.
+- **Slice 2+**: one vertical feature each (persistence/cloud, screens, gamification, sharing…), always end-to-end, always shippable.
+Each slice lists: goal, files per layer, test plan, demo criterion ("what the user sees").
+Demo numbers/strings in the plan are ESTIMATES until executed — label them so, and correct the
+plan from real output when the slice lands (the executed-output rule applies to plans too).
+Show the plan; get explicit OK. **This is the last blocking approval.**
+
+**Gate template** (both blocking gates use this shape — short, decision-ready):
+```markdown
+## Gate: <PRD | Slice plan> ready for your OK
+- <3–6 bullets: the essence — core loop, the 5 features / the slices and their demo criteria>
+- Trade-offs made: <what was cut/parked and why>
+Reply "OK" to proceed, or tell me what to change. I will NOT build before your OK.
+```
+
+## Phase 4 — Autonomous build loop (per slice)
+Follow `DELIVERY.md` §"The build loop" exactly, with the platform pack's commands:
+1. L3 Core Logic: models/engines/contracts + tests → layer tests green.
+2. L2 Data: InMemory impl of the contracts (real backend only when the slice demands it — follow
+   the platform pack's backend guide and its gotchas religiously).
+3. L3 Core UI / L4 bricks: reusable components (L0 tokens only, callbacks as boundaries).
+4. L5 Feature: screen assembly, store wiring, navigation per the pack's navigation doc.
+5. Full app build; fix until green.
+6. **Eyes-on proof**: run it (simulator MCP / browser / curl), navigate to the feature, capture and
+   actually inspect the proof (layout, dark mode, empty states, error states). Full eyes-on proof
+   not possible (no simulator/emulator/headless runner) → if the pack provides a degraded/reduced-proof
+   ladder, climb down it; otherwise fall back to the strongest proof the stack allows (integration
+   test, logs, response capture) and SAY explicitly which rung you reached.
+   Any value you attribute to the code (counts, durations, demo strings) must come from executed
+   output — never fabricate a demo number.
+7. Memory update: `PROJECT_STATE.md` (done/todo/gotchas) + `DECISIONS.md` for any choice a future
+   session must not re-litigate. **Then commit** (`add/update/fix(scope) - description`) — every
+   gate and every slice leaves a commit; untracked delivered work is an audit failure.
+8. Report the slice with its proof — for a non-technical owner, translate it into product terms
+   ("your two requirements are now automated tests named X and Y", screenshot when possible),
+   not raw test logs. Then continue to the next slice.
+
+Stop and ask ONLY when: a slice's scope is genuinely ambiguous, a paid/external dependency appears,
+or the user must act (store consoles, certificates, cloud dashboard schema deploys, real-device tests).
+
+## Quality bars (every slice)
+- Layer tests green BEFORE app build. New domain rule ⇒ new test, same change.
+- Zero hardcoded visual values; zero UI/IO framework imports in Core; dependency arrows point one way.
+- Honest reporting: failures shown with output, not narrated away.

package/templates/core/claude/skills/product-owner/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: product-owner
+description: Act as the Product Owner — turn a raw idea into a validated PRD with epics and stories, through one focused interview. Use when the user wants a SPEC ONLY: says "PRD", "product brief", "spec my idea", "write the requirements", or when /kickoff reaches its product phase. The interview ALWAYS precedes any spec artifact. For an EMPTY project or "build my app / start the project" (idea → built running app, not just a doc), DEFER to the kickoff skill — kickoff owns the full delivery and calls this skill for its product phase.
+---
+
+# Product Owner — idea → validated PRD
+
+You are the PO on this project. Your output feeds an autonomous build, so vagueness here
+becomes wasted slices later. Be opinionated: challenge scope, cut ruthlessly, name trade-offs.
+If a full BMAD installation is present (`_bmad/` or `bmad-*` commands), you may use its
+PM/PO workflows instead — this skill is the lean built-in equivalent.
+
+## Step 1 — Interview (ONE round)
+Ask everything in a single message (AskUserQuestion when available). Cover only what you
+cannot infer:
+1. **Core loop** — what does the user do, and what do they get back? One sentence.
+2. **Persona** — who is this for; what's the single moment of delight?
+3. **v1 must-haves** — cap at 5 features. Everything else is v2 (say so explicitly).
+4. **Data reality** — local-only, cloud sync, shared/collaborative, external APIs?
+   **Always attach a recommended default** ("if unsure: private cloud sync — free, no server,
+   survives reinstalls"). Non-technical users can't answer this raw — a question without a
+   default stalls them; experts just override the default.
+5. **Differentiators** — gamification (ranks/streaks/achievements), social (groups/sharing),
+   monetization? (Proven patterns exist for these — flag which apply.)
+6. **Fixed constraints** — name, brand/visual vibe, deadlines, platforms.
+
+Challenge weak answers once ("feature 4 and 5 both serve power users — which one earns v1?").
+If the user signals they are non-technical ("je ne code pas", product-only vocabulary): phrase
+every technical question as a recommendation to accept or reject, never an open choice.
+
+**Example** — user says *"an app where friends share book recommendations"* → you ask (one message):
+core loop ("what does someone do daily — browse friends' shelves? log a book?"), persona, the 5
+v1 features, data reality (private groups → cloud sync?), differentiators (reading streaks?
+clubs?), constraints. You do NOT write a PRD yet — the answers shape it.
+
+## Step 2 — PRD (`docs/PRD.md`, ≤ 150 lines)
+```markdown
+# <App> — PRD
+## Problem & Persona        (3 lines max each)
+## Core Loop                (1 sentence + the delight moment)
+## V1 Features              (numbered, each: 1-line description + acceptance criterion)
+## V2 Parking Lot           (everything cut, so it stays cut)
+## Domain Glossary          (entities, fields, relationships — this seeds the Core layer)
+## Non-functional           (offline? privacy? performance budgets? age rating?)
+## Success Criteria         (3 measurable statements)
+```
+The **Domain Glossary is the contract** with the architecture: every entity named here maps
+to a Core model; every relationship hints at a repository.
+
+## Step 3 — Epics & stories (inside PRD or `docs/STORIES.md` if large)
+Break v1 features into stories of one-slice size: "As <persona>, I <action>, so <value>" +
+acceptance criteria (Given/When/Then, 2–4 each). Order by dependency, not excitement —
+domain heart first, polish last.
+
+## Step 4 — Validation gate
+Present a ≤ 10-line summary: loop, 5 features, key trade-offs made. Get an explicit OK.
+Record scope decisions in `.claude/memory/DECISIONS.md` (dated one-liners).
+**Do not let implementation start before the OK.**

package/templates/core/claude/skills/restore-context/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: restore-context
+description: Restore project context from memory files at session start or after losing the thread. Use on the first message of any session, or on "where were we", "resume", "catch up", "refresh context".
+---
+
+# Restore context (anti-hallucination)
+
+1. Read ALL 5 files: `.claude/memory/PROJECT_STATE.md`, `ARCHITECTURE.md`, `DECISIONS.md`,
+   `NEXT_STEPS.md`, `COMMANDS.md` — and **name each one in your summary's first line** (a missing
+   or empty file is said out loud, not skipped silently). COMMANDS.md counts: it's where the
+   build loop lives.
+2. Cross-check the 2–3 most load-bearing claims against the code (file exists? API matches?).
+   **Code wins** over memory: fix the stale memory entries FIRST, so your summary describes the
+   corrected state and mentions what was fixed.
+3. Summarize in ≤ 10 lines using this shape:
+   ```markdown
+   Context restored (read: PROJECT_STATE, ARCHITECTURE, DECISIONS, NEXT_STEPS, COMMANDS).
+   - Current slice: <n — title, status>
+   - Last done: <most recent completed work>
+   - Memory vs code: <"verified ✓" | "drift found + fixed: …">
+   - Open gotchas/blockers: <the ones that constrain what we do next>
+   - Next step: <the single next action>
+   ```
+4. If memory files are missing or empty: say so, offer to initialize them from a project scan —
+   never invent history.
+
+Rules:
+- NEVER assert a project fact that is not in memory or verifiable in code.
+- A memory file naming a function/flag that no longer exists = update the file, then proceed.

package/templates/core/claude/skills/save-context/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: save-context
+description: Persist session progress into the project memory files. Use after completing a slice or significant work, before ending a session, or on "save progress", "checkpoint", "update memory".
+---
+
+# Save context
+
+## Workflow
+1. **Inventory the session**: list what was built, what was decided (and why), what broke and how
+   it was fixed, what's now blocked. If the session contradicts an existing memory entry, that's a
+   decision change → record the new choice in `DECISIONS.md` (dated), don't silently overwrite.
+2. **Map each item to its file** using the table below. One fact, one home — no duplication.
+3. **Apply surgical edits, then verify integrity**: re-read your diff — no pre-existing fact, date
+   or gotcha may disappear. Updating an entry in place is fine; losing its date is not.
+
+| File | Write here |
+|---|---|
+| `PROJECT_STATE.md` | What changed this session (done ✅ / in-progress 🚧 / todo), new gotchas with symptom→cause→fix, current slice status. Most important file — keep it ≤ 300 lines, prune stale entries. |
+| `DECISIONS.md` | Choices a future session must not re-litigate ("we chose X over Y because Z"). One line each, dated. |
+| `NEXT_STEPS.md` | Reordered priorities, new blockers, launch checklist deltas. |
+| `ARCHITECTURE.md` | Only if the structure itself changed (new package, new layer rule). |
+| `COMMANDS.md` | Only when a new command proved useful (with the exact working flags). |
+
+**Example — a gotcha entry** (PROJECT_STATE.md, gotchas log):
+```markdown
+- **Records failed to save: "cannot use an empty list to initialize a new field (tags)"**
+  → backend rejects empty arrays on list fields → omit the field when the array is empty. Fixed 2026-06-09.
+```
+
+## Rules
+- Facts only — no narration, no praise. Convert relative dates to absolute (2026-06-09, not "today").
+- Gotchas are the most valuable entries: always symptom → cause → fix.
+- **Integrity**: never delete or rewrite pre-existing facts/dates; append or update in place.
+- Never log secrets, tokens, or personal data.
+- Finish with a one-line confirmation listing the files you touched.

package/templates/core/docs-architecture/ANTI_PATTERNS.md

@@ -0,0 +1,180 @@
+# Anti-Patterns Register — what NOT to do (each one paid for)
+
+Every entry below was found in production code and verified — none is hypothetical.
+Treat this as a pre-flight checklist: before shipping a cache layer, an auth middleware,
+a config provider or a doc, scan the matching section.
+
+> **This register is template-owned and curated.** It ships read-only and is refreshed when
+> you run `update --apply` — **edits made here are overwritten on the next update.** Do NOT add
+> your project's own incidents to this file. When you hit a real anti-pattern in THIS project,
+> record it in the **gotchas log in `.claude/memory/PROJECT_STATE.md`** (symptom → cause → fix) —
+> that file is yours and `update` never touches it. Worth-generalizing lessons can be proposed
+> upstream to this register; they don't live in your local copy.
+
+Layer references (L0–L5) follow ARCHITECTURE_PRINCIPLES.md. Proof discipline follows
+DELIVERY.md. Format per entry: **Symptom → Why it bites → Fix.**
+
+---
+
+## Caching & HTTP
+
+### 1. Process-seeded hash as ETag
+- **Symptom:** ETags computed from the language's built-in `hashValue`/`hash()` of the
+  response body. Cache hit rate near zero behind a load balancer; clients re-download
+  identical bodies.
+- **Why it bites:** Swift's `hashValue` (and Python's `hash()`) are seeded **per process**.
+  The same bytes produce a different ETag on every replica and every restart — conditional
+  requests can never match. Bonus damage: the middleware decoded the full JSON body on
+  every request just to decide cacheability.
+- **Fix:** ETags must be stable across processes: SHA-256 (truncated) of the body bytes,
+  or a version/updatedAt field from the resource. Decide cacheability from route + model
+  metadata, never by re-parsing the response you just serialized.
+
+> 📖 **War story:** a production team shipped ETag support and saw zero `304`s in the logs.
+> Cause: per-process hash seed — three replicas, three ETags for the same body. Fix: content
+> digest; conditional requests started matching the same day.
+
+## Auth & Routing (L5)
+
+### 2. Name-allowlist auth middleware
+- **Symptom:** a global route middleware holding a hand-maintained array of page names
+  that skip auth (`['index', 'pricing', 'features', …]`); everything else redirects to login.
+- **Why it bites:** every new public page must be *remembered* into the list. Forget one
+  and it silently vanishes behind auth — a public changelog page 302'd anonymous visitors
+  to the homepage for weeks before anyone noticed. The list also drifts from the actual
+  route table; nothing fails when they diverge.
+- **Fix:** derive auth from **route meta** declared next to the page
+  (`definePageMeta({ auth: false })` or equivalent): the middleware reads `to.meta`,
+  default-denies, and new pages carry their own policy. One source of truth, at L5 where
+  the route lives.
+
+## Contracts & Dependencies
+
+### 3. Deep imports into a dependency's internals
+- **Symptom:** app code importing `your-sdk/src/types/*` (internal paths) instead of the
+  package's public entry point — found in 22 files of one consumer.
+- **Why it bites:** it bypasses the public contract; any internal refactor of the SDK
+  (moving a file, renaming a folder) breaks 22 call sites in a *different repo*. The import
+  graph **is** the architecture — deep imports make it a lie.
+- **Fix:** import only from the package root / declared `exports`. Enforce: `exports` field
+  in the SDK's package.json (makes deep paths unresolvable) + `no-restricted-imports` lint
+  rule in consumers.
+
+### 4. `console.log` in SDK hot paths
+- **Symptom:** a shared SDK logging request/response details straight to `console.log`
+  (9 occurrences) on every call.
+- **Why it bites:** every consumer's console fills with another library's traffic — request
+  payloads included. No way to silence it, filter it, or route it. The log sink is an L1 Ops
+  decision owned by the app; an L2 library hardcoding it seizes a choice the consumer can
+  never override (and in pure L3 code, logging IO has no place at all).
+- **Fix:** inject a logger interface (default: no-op) and gate verbosity behind an explicit
+  `debug` flag the consumer sets. The SDK never decides where logs go.
+
+### 5. Unpinned git dependencies
+- **Symptom:** a package consumed via `git+ssh://…#main` — branch HEAD, no tag, no lockfile
+  protection across fresh installs.
+- **Why it bites:** every clean install pulls whatever the branch points to *today*. A
+  breaking SDK change lands silently in consumers' next CI run; "works on my machine"
+  becomes literally true and useless.
+- **Fix:** pin to a tag or commit SHA (`#v1.4.2`), or publish proper semver releases.
+  Upgrades become deliberate diffs, not surprises.
+
+## Configuration & Ops (L1)
+
+### 6. Test-detection heuristics in production config
+- **Symptom:** the global config provider sniffing for the test framework at runtime —
+  checking `XCTestConfigurationFilePath`, `xctest` in process arguments, `PackageTests`
+  in the binary name, plus a `CI` + database-hostname combo — and swapping the entire
+  config to mocks when any heuristic matches.
+- **Why it bites:** production behavior forks on *test-framework presence*, not on declared
+  intent. The heuristics rot as runners evolve, and a matching env-var combination in any
+  non-test context silently flips real config to mock values. Debugging this is archaeology.
+- **Fix:** one explicit variable (`APP_ENV=test`) set by the test harness; the provider
+  reads it and nothing else. Better: inject config into the composition root so tests pass
+  their own — no global singleton to fork.
+
+### 7. Hardcoded log level overriding the env var
+- **Symptom:** `app.logger.logLevel = .debug` hardcoded in `configure()`, executed *after*
+  logging bootstrap — the `LOG_LEVEL` env var exists, is documented, and does nothing.
+- **Why it bites:** debug logs in production: noise, log-storage cost, and request data in
+  plaintext. Worse, the config **lies about being configurable** — operators set the env
+  var, see no effect, and lose trust in every other knob.
+- **Fix:** read the level from the environment with a quiet production default
+  (`.info`/`.notice`). If a hardcode is ever needed for local work, gate it behind
+  `#if DEBUG` and a comment saying so.
+
+### 8. Feature flags that default OPEN
+- **Symptom:** flag parsing like `enabled = value.lowercased() != "false"` — anything that
+  isn't the exact string `false` (a typo, `"0"`, `"no"`, an empty default) turns the
+  feature **on**.
+- **Why it bites:** misconfiguration becomes silent activation. The dangerous failure mode
+  (feature unexpectedly live) is the *default* failure mode.
+- **Fix:** fail closed. Parse with an explicit truthy allowlist (`"true"`, `"1"`); missing
+  or unrecognized values mean **off**, and log a warning naming the variable.
+
+## Concurrency & Lifecycle (L2)
+
+### 9. Detached background task on a request-scoped resource
+- **Symptom:** a fire-and-forget `Task { … }` spawned inside a request handler, capturing
+  the request's database connection to do slow work after the response is sent.
+- **Why it bites:** the request-scoped connection returns to the pool when the response
+  completes; the background task then races a closed — or worse, *reused* — connection.
+  Intermittent failures, occasionally someone else's transaction.
+- **Fix:** background work uses **application-scoped** resources (the app's database
+  handle, an injected context) or a proper job queue. Rule of thumb: anything outliving
+  the response must not hold anything scoped to the request.
+
+## Testing
+
+### 10. Testing theater
+- **Symptom:** `package.json` scripts invoking Playwright with **no Playwright dependency
+  installed** — the scripts cannot run from a clean checkout. A stale `playwright-report/`
+  committed to the repo as "proof" the tests once passed.
+- **Why it bites:** test claims that can't be executed are worse than no tests: they grant
+  false confidence and rot invisibly. DELIVERY.md's contract is *proof over claims* — a
+  committed report is a claim, a green run is proof.
+- **Fix:** every test script must run from a clean checkout in CI, or be deleted. Generated
+  reports go in `.gitignore`, never in version control.
+
+## Documentation
+
+### 11. Docs that restate code
+- **Symptom:** static mapping tables, per-folder `AGENTS.md` inventories listing what each
+  directory contains — every instance checked was stale.
+- **Why it bites:** a doc that mirrors structure drifts the moment the structure moves, and
+  agents/newcomers trust the stale copy over the code. On conflict, code wins — so the doc
+  was only ever a liability.
+- **Fix:** document *intent and invariants*, never inventory. Placement rules in
+  **DOCS_PLACEMENT.md** decide what deserves prose at all.
+
+### 12. Two documentation roots
+- **Symptom:** both `docs/` and `documentations/` at the repo root, with overlapping,
+  diverging content.
+- **Why it bites:** nobody knows where truth lives, so contributors update one (or neither)
+  and readers trust whichever they find first. Two roots = zero canonical sources.
+- **Fix:** one root (`docs/`), one redirect commit to merge the other, done. See
+  DOCS_PLACEMENT.md for what goes where inside it.
+
+### 13. Hand-written docs that look generated
+- **Symptom:** an `ERROR_CODES.md` formatted like tool output, maintained by hand — and
+  drifted from the error enum it claimed to mirror.
+- **Why it bites:** readers assume generated docs are exact, so drift here is actively
+  misleading — worse than no doc. The enum was the truth all along.
+- **Fix:** if a doc mirrors code, **generate it from code** (build step or CI check that
+  fails on drift). If generating isn't worth it, delete the doc and link to the source file.
+
+---
+
+## Recording an anti-pattern you hit
+
+Your incidents go in **`.claude/memory/PROJECT_STATE.md`** (gotchas log), never in this
+template-owned file — `update --apply` would erase an edit here.
+
+1. It happened **here**, in real code — link the commit or file.
+2. Write it as symptom → cause → fix, 3–6 lines. Generic names, no blame.
+3. If the fix changed a layer rule or convention, record it in `.claude/memory/DECISIONS.md` too.
+4. If the lesson is broadly reusable across projects, propose it upstream so a future `update`
+   ships it to this curated register for everyone.
+
+> ⚠️ **Gotcha:** an entry only works if it stays falsifiable. "Avoid bad caching" teaches
+> nothing; "per-process hash seed broke ETags across replicas" prevents a repeat.

package/templates/core/docs-architecture/ARCHITECTURE_PRINCIPLES.md

@@ -0,0 +1,134 @@
+# Architecture Principles — the 6-Layer Lego Model (every stack, every language)
+
+This is the universal contract. iOS, Android, web, API — the platform pack instantiates
+these layers for your language, but the layers themselves never change.
+
+## The layers
+
+```
+L5  COMPLETE FEATURES     final user-facing features: screens/pages/endpoints, app state,
+                          composition root. Assembles everything below. Throwaway by design.
+L4  SHARED FEATURES       feature bricks reused by several complete features
+                          (auth flow, paywall, media picker, share sheet, comment thread…)
+L3  CORE LOGIC + CORE UI  the heart, two siblings at the same level:
+                          · Core Logic — domain models, engines, services, repository CONTRACTS.
+                            Pure: no UI framework, no IO framework. Injected clocks/calendars.
+                          · Core UI — reusable, domain-blind components (buttons, cards, lists,
+                            inputs) built on the design tokens.
+L2  DATA                  IO: repository implementations, network/DB/cloud clients,
+                          DTO ↔ domain mapping, caching, sync.
+L1  OPS                   operational plumbing: remote config, feature flags, analytics,
+                          logging, crash reporting, monitoring, push registration.
+L0  FOUNDATION            primitives: design tokens (colors/spacing/typography), base
+                          extensions, formatters, tiny utilities. Zero dependencies.
+```
+
+## The dependency rule
+
+**A layer may only import layers strictly below it.** Never sideways (a feature never
+imports a sibling feature), never upward.
+
+```
+L5 → L4, L3, L2, L1, L0
+L4 → L3, L2, L1, L0
+L3 → L1, L0                       (L3 never imports L2 — it stays IO-free)
+L2 → L3 contracts*, L1, L0        (* the one sanctioned upward arrow — see below)
+L1 → L0
+L0 → nothing
+```
+
+> **The one sanctioned upward arrow — ports & adapters.** The only arrow that points up is
+> **L2 → L3**, and even that is narrow. Core Logic (L3) declares the repository **contracts**
+> (interfaces) and the domain models it needs; Data (L2) *implements* those contracts, so L2
+> imports them. **L3 itself never imports L2** — it knows nothing of the IO layer; it depends
+> only on its own contracts, which L2 satisfies. That implementation import (L2 → L3 contracts)
+> is the only upward arrow allowed, and it may touch **interfaces and models only — never
+> services or engines**.
+> Why: tests and previews run against an InMemory implementation of the contract without
+> dragging in CloudKit/HTTP/ORM; the real backend stays swappable.
+
+Everything else is absolute:
+- **L3 Core Logic is pure.** No UI imports, no IO imports. If it needs the network, it
+  declares a contract; L2 implements it. Injected `Calendar`/clock/randomness — never read
+  the system clock inside an engine.
+- **L3 Core UI is domain-blind.** A button doesn't know what an "Order" is. Domain-aware
+  composites belong to L4.
+- **L4/L5 communicate by callbacks/props/events** (`onSave`, `onDelete`) — a brick never
+  reaches into app state on its own.
+- **L0 tokens are the only source of visual values.** A hardcoded color in L4/L5 is a bug.
+
+## Placing a new brick — the algorithm
+
+The named bands above are the canonical shape, but a brick's level is not picked from a
+category — it is **computed from its dependencies**:
+
+> **Start at L0. Climb only when a dependency forces you up.**
+> A brick's level = (highest level among the bricks it imports) + 1. Place it as LOW as it
+> can possibly live.
+
+Worked example — adding a `RateLimiter` brick:
+1. Assume **L0**… but it needs base formatters from Foundation → it must sit above L0 → **L1**.
+2. At L1… but it reads its quotas from remote config, which lives in Ops (L1) → above L1 → **L2**.
+3. At L2 nothing else pushes it up → **it lands at L2.** Done — even though "rate limiting"
+   *sounds* like Ops, its dependencies decide, not its name.
+
+Corollaries:
+- A brick that keeps climbing is a smell: split it (the pure part stays low, the consuming
+  part moves up).
+- **~6 levels is the maximum.** If you need a 7th, you are over-slicing — merge bands.
+- Re-run the algorithm when a brick gains a dependency; it may need to move up (or the
+  dependency may belong lower).
+
+## This applies to EVERY stack — including APIs
+
+The layer discipline is not a UI concern. A backend has the exact same lattice:
+
+```
+L5  routes/controllers, app bootstrap, DI wiring
+L4  shared feature modules (auth flow, billing, webhooks)
+L3  use cases / domain services / entities / repository contracts
+L2  repository impls, DB access, external API clients (Stripe, auth provider…)
+L1  ops: remote config, feature flags, metrics, structured logging
+L0  primitives: shared types, formatters, base extensions
+```
+
+Same absolute rule downward-only: a repository (L2) never calls a use case (L3); a use case
+never imports a controller; **and no brick ever calls an SDK/client that lives above its own
+level** — if you need it, you are at the wrong level, or the SDK is.
+
+## Where does this file go? (decision table)
+
+Typical band per kind of file — **the placement algorithm above has the final word**:
+
+| You are adding… | Layer |
+|---|---|
+| A color, spacing, font, date formatter, small extension | **L0** Foundation |
+| Remote config, feature flag, analytics event, logger setup | **L1** Ops |
+| A repository implementation, API client, DB access, DTO mapping | **L2** Data |
+| A business rule, domain model, engine, service, repository contract | **L3** Core Logic |
+| A reusable domain-blind component (button, card, badge, empty state) | **L3** Core UI |
+| A feature brick used by ≥ 2 features (auth, paywall, picker) | **L4** Shared Features |
+| A screen/page/endpoint, navigation, app state, service wiring | **L5** Complete Features |
+
+When in doubt between L4 and L5: start in L5, promote to L4 on second use.
+
+## Physical mapping
+
+Each platform pack maps layers to its module system (packages, gradle modules, workspaces…).
+Two rules survive any mapping:
+1. **Lower layers must build & test standalone** — fast feedback without booting the app.
+2. **The import graph is the architecture.** If the module system can't enforce an arrow,
+   a grep must be able to detect the violation.
+
+## Why AI agents thrive in this model
+
+1. **Fast ground truth** — L0–L3 build/test in seconds; agents iterate there before paying
+   for full app builds.
+2. **Grep-visible violations** — a UI import in L3 logic or a hex color in L5 is one search away.
+3. **Small blast radius** — layers bound the context an agent must hold per change.
+4. **Tests are the spec** — every L3 rule ships with its test; intent survives sessions.
+
+## Naming
+- Names express intent, not technology (`ItemRepository`, not `ItemAPIManager`).
+- One type per file; the file is named after the type.
+- Feature namespacing: scoped types (`Item.DetailCard`, `App.Feed`) over prefix soup.