@horka/app-forge 0.1.0

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

@@ -0,0 +1,68 @@
+# Delivery Method — vertical slices, proof over claims (platform-agnostic)
+
+How work ships, regardless of stack. This file is the method. The concrete build/run/proof
+commands come from the platform pack if it provides them (e.g. a `WORKFLOW.md` and a proof
+ladder); if the pack ships none, establish that loop yourself and record it in
+`.claude/memory/COMMANDS.md`.
+
+## Vertical slices
+
+Never build horizontally ("all the models, then all the screens"). Ship **vertical slices**:
+thin end-to-end features that a user can see working.
+
+- **Slice 0 — skeleton runs**: empty app boots on the target (simulator/emulator/browser/server
+  responds). Proof: screenshot or curl output.
+- **Slice 1 — domain heart**: core entities + the main engine, exhaustively tested, plus the ONE
+  main screen reading from InMemory data. Proof: tests green + screenshot.
+- **Slice N**: one feature each, always end-to-end (L3 logic → L2 data → L3/L4 UI bricks → L5
+  screen), always leaving the app shippable.
+
+Each slice gets a short blueprint before code: goal, files per layer, test plan, demo criterion
+("what the user sees"). Blueprints live in `docs/`.
+
+## The build loop (per slice)
+
+1. **L3 Core Logic first**: models/engines + contracts + their tests. Layer tests green before moving on.
+2. **L2 Data**: InMemory impl of the contracts (real backend impl only when the slice demands it).
+3. **L3 Core UI / L4 bricks**: reusable components — L0 tokens only, callbacks as boundaries.
+4. **L5 Feature**: assemble screen + state + navigation.
+5. **Full build** of the app target; fix until green.
+6. **Eyes-on validation**: run it, navigate to the feature, capture proof (screenshot/recording/
+   response), and actually inspect it — layout, empty states, error states.
+7. **Memory update**: PROJECT_STATE.md (done/todo/gotchas), DECISIONS.md if a choice was made.
+
+## Validation etiquette (the trust contract)
+
+- **Executed-output only**: any value presented as produced by the code (durations, counts, demo
+  strings) must come from actually executed output. Didn't run it? Label it an estimate.
+- **Commit at every gate and slice completion** (`add/update/fix(scope) - description`). Gate
+  discipline must be provable from git history — two delivered slices sitting untracked on main
+  is an audit failure.
+
+- **Never claim done without proof.** Tests green + build green + visual/behavioral proof.
+- **Failures are reported with output**, not narrated away. A skipped step is stated as skipped.
+- **Layer tests before app builds** — they're orders of magnitude faster and more precise.
+- **Every new domain rule ships with its test in the same change.** No test, no rule.
+- **Gotchas get written down** the moment they're solved: symptom → cause → fix, in
+  PROJECT_STATE.md. The next session must not pay for them again.
+
+## Memory protocol
+
+`.claude/memory/` is the project's long-term brain:
+
+| File | Contains |
+|---|---|
+| PROJECT_STATE.md | Current slice, done/in-progress/todo, gotchas log, launch blockers |
+| ARCHITECTURE.md | How THIS project instantiates the layers; deviations + why |
+| DECISIONS.md | Dated one-liners a future session must not re-litigate |
+| NEXT_STEPS.md | Ordered backlog, blockers waiting on the user |
+| COMMANDS.md | Commands proven to work here, exact flags |
+
+Restore at session start; save after significant work. On conflict, **code wins over memory** —
+then fix the memory file.
+
+## When to stop and ask the user
+
+Only for: genuine scope ambiguity, paid/external dependencies, irreversible actions
+(deleting data, publishing), or actions only they can perform (store consoles, certificates,
+real-device tests). Everything else: decide, note it in DECISIONS.md, keep moving.

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

@@ -0,0 +1,151 @@
+# Docs Placement — where knowledge lives (the two-tier rule)
+
+Documentation here is not for humans browsing a wiki — it is **loaded into AI agent context**
+and treated as ground truth. A wrong doc is worse than no doc: the agent acts on it.
+This file defines where each kind of knowledge must live so it stays true.
+
+## The two-tier rule
+
+**Tier 1 — umbrella / root docs** (`docs-architecture/`, root `CLAUDE.md`):
+hold ONLY knowledge that survives refactors —
+
+- **Contracts**: what each component promises the others (API shapes, SDK boundaries,
+  event formats). The L3 repository contracts of ARCHITECTURE_PRINCIPLES.md are the model.
+- **Ordering**: in what sequence work flows across components
+  (e.g. "API first, then SDK, then clients" — the *rule*, never the file list).
+- **Invariants**: the rules that make the system safe to change
+  ("L3 Core Logic is pure", "tokens are the only source of visual values").
+- **Infra topology**: what runs where, what talks to what, deployment shape.
+
+**Tier 2 — colocated docs** (per-repo/per-module `CLAUDE.md` or `AGENTS.md`, `docs/`
+folders next to code, doc comments): hold **every file-path fact** — module layout,
+where a feature lives, which command builds this package, local conventions.
+
+**The placement test:** *if a refactor could move a file and silently make the sentence
+false, the sentence belongs next to that file — Tier 2.* A root doc must never name a
+path inside a child component. Point at the component's own docs and stop.
+
+## Why — a two-year natural experiment
+
+> 📖 **War story:** A production team ran a multi-component product (API, web app,
+> mobile app, JS SDK) for two years with both doc styles side by side.
+> **Symptom:** agents kept editing the wrong files, "fixing" code that didn't exist, and
+> citing a frontend stack two major versions out of date.
+> **Cause:** the umbrella docs were path inventories. A root "component mapping" file —
+> tables mapping every feature to exact file paths across four repos — was audited and
+> found **~90% fiction**: the API's `Controllers/` directory had been dissolved into use
+> cases and multi-target packages; the SDK had moved under another repo's umbrella and its
+> service files renamed; the web framework's major upgrade had relocated the entire pages
+> tree. The root "architecture" doc still claimed a static-CDN frontend (it had become
+> SSR), the previous framework major version, and an HTTP library that was no longer a
+> dependency. Nobody updates a doc they don't see while editing the code it describes.
+> **Fix:** the team deleted the mapping tables outright. The colocated rule-style docs —
+> per-repo conventions, invariants, gotcha logs — had stayed accurate the whole time,
+> because *rules don't move when files do*. That asymmetry is this file's entire thesis.
+
+## What goes where
+
+| Knowledge | Lives in | Tier |
+|---|---|---|
+| Layer rules, dependency arrows (L0–L5) | `docs-architecture/ARCHITECTURE_PRINCIPLES.md` | 1 |
+| Delivery method, memory protocol | `docs-architecture/DELIVERY.md` | 1 |
+| Cross-component contracts & work ordering | `docs-architecture/` | 1 |
+| Infra/deploy topology (what runs where) | `docs-architecture/` or `deploy/docs/` | 1 |
+| "Component X handles Y — see `X/CLAUDE.md`" | root `CLAUDE.md` (pointer only) | 1 |
+| Module layout, where features live | that module's `CLAUDE.md` / `docs/` | 2 |
+| Build/test/run commands for a component | that component's docs + `.claude/memory/COMMANDS.md` | 2 |
+| Per-repo conventions, naming, local rules | that repo's `CLAUDE.md` | 2 |
+| Feature debriefs, gotchas | next to the code + PROJECT_STATE.md gotcha log | 2 |
+| Slice blueprints | `docs/` of the component being sliced | 2 |
+
+## Anti-pattern: the feature→file mapping table
+
+**Docs that restate code rot the fastest.** A table mapping features to file paths is a
+cache of the file tree with no invalidation — every refactor, rename, or framework upgrade
+silently corrupts it, and nothing fails when it does.
+
+Never write:
+
+```markdown
+| Feature | Backend | Frontend |
+|---|---|---|
+| Login | /api/src/controllers/AuthController.ts | /web/pages/login.vue |
+```
+
+The codebase already IS this table, always up to date. Agents have grep, glob, and LSP;
+a stale map is strictly worse than a 2-second search. Write instead:
+
+```markdown
+Auth lives in the api component (L4 shared feature). Conventions and entry points:
+see `api/CLAUDE.md`. Invariant: clients never mint tokens — only the API issues them
+via the auth provider.
+```
+
+The same ban covers prose inventories ("the engine lives in `src/core/engine.ts`"),
+directory-tree ASCII art for *other* components, and root docs listing another repo's
+commands.
+
+## Write invariants and war stories — never inventories
+
+The durable doc sentences are the ones a refactor cannot falsify:
+
+- **Invariant:** "L2 never imports L3 services — contracts and models only." True in any
+  file layout. ✅
+- **Contract:** "The SDK is the only sanctioned HTTP path for web clients; bypassing it
+  to call the API directly is a bug." ✅
+- **War story:** symptom → cause → fix (format below). Pays rent every time someone
+  hits the same wall. ✅
+- **Inventory:** "Controllers are in `Sources/App/Controllers/`." One restructure away
+  from fiction. ❌ — move it to that package's own doc, where the person moving the
+  files is staring at it.
+
+> ⚠️ **Gotcha:** "But the inventory helps the agent find things faster."
+> **Symptom:** it does — for the first month. **Cause:** after that it actively misleads:
+> in the experiment above the agent confidently edited paths that had not existed for a
+> year, and burned sessions reconciling doc vs reality. **Fix:** ship the *search recipe*
+> instead ("routes are registered in one file per component — grep for the route
+> registrar"), which stays true across renames.
+
+## The staleness loop — code wins
+
+Any doc line that claims a **path, command, version, or flag** is a liability with a
+maintenance contract:
+
+1. **On touch, spot-check.** Whenever a session reads such a claim before acting,
+   verify it against the code first (one `ls`/grep). Never act on the claim directly.
+2. **On conflict, code wins.** Same rule as DELIVERY.md's memory protocol: the doc is
+   wrong, not the code. No exceptions.
+3. **Fix in the same change.** Correct the line — or better, demote it to Tier 2 or
+   delete it — in the very commit that revealed the rot. Stale claims found and left
+   in place are bugs you chose to ship.
+4. **On refactor, sweep.** Moving or renaming files? Grep the docs of *that component*
+   for the old paths. The two-tier rule makes this tractable: only colocated docs can
+   name paths, so the sweep never leaves the component.
+
+## The feature debrief
+
+After a hairy feature — anything that fought back — write a **short colocated debrief**
+before moving on: 10–20 lines, next to the code it concerns (the module's `CLAUDE.md`
+or `docs/`), with the durable parts mirrored into the memory files (DELIVERY.md):
+
+- **What broke** — the 2–3 real obstacles, as gotcha blocks (symptom → cause → fix).
+- **What to know** — the non-obvious decisions and the invariants they created.
+- **What NOT to try** — dead ends, so the next session doesn't pay for them again.
+
+A short debrief next to the code beats a wiki page every time: it loads into context
+exactly when an agent works on that code, and it dies with the code when the code is
+deleted — which is correct. Wiki pages outlive their subject and become Tier-1 fiction.
+
+Wire it into the memory system: gotchas land in `PROJECT_STATE.md`'s gotcha log,
+decisions in `DECISIONS.md`, newly-proven commands in `COMMANDS.md`. Memory files obey
+the same staleness loop — they claim paths and commands, so they get spot-checked and
+code wins.
+
+## Summary card
+
+1. Root docs: contracts, ordering, invariants, infra. **Zero child-component paths.**
+2. Every file-path fact lives next to the code it describes.
+3. No feature→file mapping tables — docs that restate code rot the fastest.
+4. Write invariants and war stories; the codebase is its own inventory.
+5. Path/command claims get spot-checked on touch; code wins; fix in the same change.
+6. Hairy feature done → short colocated debrief + memory update, not a wiki page.

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

@@ -0,0 +1,158 @@
+# Multi-Repo Contract — backend → SDK → clients, one order, no exceptions
+
+When {{PROJECT_NAME}} spans several repos (API, SDK, web, mobile…), the repos form a
+dependency graph exactly like layers inside one codebase. This file is the cross-repo
+analog of ARCHITECTURE_PRINCIPLES.md: **imports point downward — between repos too.**
+
+## The repo lattice
+
+```
+CLIENTS   web app, mobile app, CLI, integrations     consume the SDK's public surface only
+   ↓ depends on
+SDK       typed client library: services, DTOs,      the API contract, made importable
+          auth/session handling, error normalization
+   ↓ depends on (wire protocol only — HTTP/GraphQL/gRPC)
+BACKEND   the API: routes, domain, persistence        knows nothing about SDK or clients
+```
+
+Mapping to the 6-layer model:
+- Each repo internally runs its **own full L0–L5 lattice** (the API too — see
+  "This applies to EVERY stack" in ARCHITECTURE_PRINCIPLES.md).
+- From a client's point of view, **the SDK is its L2 Data brick**: network client +
+  DTO ↔ domain mapping. The in-repo rule "a layer imports only layers strictly below it"
+  becomes "a client imports only the SDK's public surface."
+- The backend is *below* everything: it never imports the SDK, never special-cases a
+  client. Upward knowledge is a violation, same as L2 calling L5.
+
+## Implementation order — backend first, SDK second, clients last
+
+Every cross-repo change follows dependency order. No parallel starts, no "I'll stub it":
+
+| Step | Repo | Work | Gate before the next step starts |
+|---|---|---|---|
+| 1 | **Backend** | model/migration, use case, route, DTOs, tests | backend tests green; endpoint reachable (curl proof); DTOs frozen for this slice |
+| 2 | **SDK** | types mirroring the DTOs, service method, error mapping, tests | SDK builds + type-checks; tests green; version bumped; new surface exported from the public entry point; **tagged** |
+| 3 | **Clients** | upgrade pinned SDK tag, wire UI/state, integrate | client builds against the tag; feature verified eyes-on (DELIVERY.md validation etiquette) |
+
+Rules around the order:
+- **A gate failing blocks the next layer.** Never start SDK work against a backend whose
+  tests are red; never start client work against an SDK that doesn't build or type-check.
+- **Bug fixes follow the same arrow.** Locate the most upstream repo that owns the defect,
+  fix it there with a regression test, then propagate downstream. Patching around a backend
+  bug inside a client creates two bugs.
+- **Dependency upgrades propagate in the same order**: backend → SDK → clients, validating
+  each repo before touching the next.
+- **Business rules live in the backend, once.** The SDK transports them, clients render
+  them. Client-side validation is UX sugar; the backend is the source of truth. Duplicated
+  domain logic across repos *will* diverge.
+
+## Never bypass the SDK
+
+The SDK's public surface **is** the contract. Two absolute prohibitions for clients:
+
+1. **No direct API calls.** A `fetch`/HTTP call to the backend from client code is a
+   violation, even "just for this one endpoint." If the SDK lacks the method, the SDK is
+   behind — fix step 2 before step 3, never around it.
+2. **No deep imports.** Clients import the SDK's published entry point only — never
+   `sdk/src/*`, never `sdk/dist/internal/*`. Enforce mechanically: the SDK's package
+   manifest declares an `exports` map with a single public entry; anything not exported
+   does not exist. Deep-importing internals is the cross-repo version of L5 reaching into
+   L2's private parts.
+
+Both violations are grep-visible (rule 2 of "Physical mapping" in
+ARCHITECTURE_PRINCIPLES.md): `grep` clients for the raw API base URL and for deep-import
+paths in CI.
+
+> ⚠️ **Gotcha:** Symptom — a client's build explodes after an SDK *patch* release, errors
+> deep inside `node_modules`. Cause — the client deep-imported an internal module the SDK
+> moved during a refactor; internals carry no compatibility promise. Fix — consume only the
+> public entry point; if you need something internal, promote it to the public surface via
+> an SDK release.
+
+**One SDK per language ecosystem.** A client platform with no SDK in its language (e.g. a
+native mobile app next to a TypeScript SDK) builds a dedicated API-client module in its own
+L2 — a mini-SDK. Same rules apply to it: single API surface in one place, typed DTOs,
+normalized errors, no scattered HTTP calls from feature code.
+
+## Breaking-change protocol
+
+Repos deploy independently — there is **no atomic cross-repo merge**. Design for the window
+where old clients talk to the new backend:
+
+1. **Backend lands the change first.** Prefer expand/contract: add the new field/endpoint,
+   keep the old one serving until all clients have migrated, remove it later. Version the
+   route (`/v2/...`) when the shape change can't be additive. Backend tests green.
+2. **SDK adapts**: types and services updated, error mapping verified, **semver bump**
+   matching the impact (breaking → major, or minor below 1.0 — pick one convention and
+   write it in the SDK README), plus a dated **MIGRATION.md entry**: what broke,
+   before/after snippets, why. Tag the release.
+3. **Each client upgrades deliberately**: bump the pinned tag in its own PR, follow the
+   MIGRATION.md entry, run the client's full gate. Clients migrate at their own pace —
+   that's the point of the contract.
+
+Never: merging a backend breaking change and "fixing the clients later today." Later today
+is when production traffic from yesterday's mobile build hits the new shape.
+
+> 📖 **War story:** Symptom — users logged out every time they returned from an external
+> payment page; no client code had changed. Cause — a session-cookie policy change shipped
+> from the SDK's auth layer without a migration note, so client teams couldn't connect the
+> regression to the upgrade. Fix — the change was re-released with a MIGRATION.md entry
+> (before/after config, the cross-domain redirect rationale), and "breaking change ⇒
+> MIGRATION entry + version bump" became a hard gate on SDK releases.
+
+## Pin SDK versions by tag — never branch HEAD
+
+Clients pin the SDK to an **immutable reference**: a published registry version or a git
+tag (`#v0.12.0`). Never a branch, never an implicit HEAD.
+
+- A branch reference makes every fresh install (CI, deploy server, new laptop) resolve to
+  *whatever the branch is that day*. Your client's behavior changes with zero diff in its
+  own repo — unreproducible builds, undebuggable regressions.
+- Upgrading the SDK is always an **explicit, reviewable diff** in the client repo: one line,
+  one PR, one changelog entry to read.
+- Lockfiles help but don't save you: they're bypassed by fresh resolution paths and they
+  hide *intent* — the manifest must state the exact version you mean.
+
+> 📖 **War story:** Symptom — a production frontend deploy broke on a Friday with an empty
+> diff; the same commit had deployed fine on Monday. Cause — the SDK dependency was a git
+> URL pointing at a branch with no tag; a breaking SDK change merged mid-week, and the
+> deploy's fresh `install` silently pulled the new HEAD. Fix — pin by tag, upgrade via
+> explicit PRs; the team also added a CI check rejecting any git dependency without a
+> pinned ref.
+
+**Local development linking.** While building an SDK change you need the client to consume
+your working copy. Use your package manager's link/workspace mechanism or a `file:` path,
+behind two scripts in the client (`sdk:local` switches to the local path, `sdk:prod`
+restores the pinned tag). The local link **never gets committed** — CI should fail on a
+`file:` or `link:` SDK dependency reaching the main branch.
+
+## How this composes with vertical slices (DELIVERY.md)
+
+A vertical slice doesn't stop at a repo boundary — **a slice crosses all repos, in
+contract order**:
+
+```
+Slice N:  BACKEND (its own L3 → L2 → L5 loop, tests + curl proof)
+        → SDK     (types + service + tests, build, bump, tag)
+        → CLIENT  (upgrade pin, L3/L4 bricks, L5 screen, eyes-on proof)
+```
+
+- The slice blueprint (DELIVERY.md) lists **files per repo per layer**, not just per layer.
+- A cross-repo slice typically means one PR per repo, merged in dependency order, **each
+  leaving its repo shippable** — the backend with the new endpoint live is shippable even
+  before any client uses it (that's expand/contract working for you).
+- The slice is **done** only on end-to-end proof: the feature visible in at least one real
+  client, against the deployed backend — not when the backend tests pass.
+- InMemory caveat: inside a client, early slices may run on an InMemory L2 implementation
+  (DELIVERY.md build loop step 2). That's fine *within* the client repo — but the moment
+  the slice goes live, the real L2 is the SDK, under all the rules above.
+
+## Checklist (per cross-repo change)
+
+- [ ] Backend tests green + endpoint proven before SDK work started
+- [ ] SDK builds, type-checks, tests green; version bumped; release tagged
+- [ ] Breaking change ⇒ MIGRATION.md entry with before/after
+- [ ] Clients consume the public SDK surface only (no raw API calls, no deep imports)
+- [ ] Client SDK pins are immutable tags; upgrade is an explicit PR
+- [ ] No `file:`/`link:`/branch SDK reference on the main branch
+- [ ] Slice proven end-to-end in a real client before being called done

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

@@ -0,0 +1,214 @@
+# SDK Contract — shipping a typed SDK between your API and your clients
+
+When several frontends (web, SSR, CLI, CI) consume one API, the API client becomes its own
+package: a typed SDK. This file is the contract for building and distributing it. It assumes
+the layer model from ARCHITECTURE_PRINCIPLES.md and the proof discipline from DELIVERY.md.
+
+**Where the SDK sits**: inside the consumer app, the SDK is an **L2 Data brick** — it is the
+network client behind the repository implementations. L3 Core Logic declares repository
+contracts; L2 implements them by calling the SDK and mapping wire types → domain models.
+No L3+ brick ever instantiates the SDK directly; only the composition root (L5) wires it.
+
+## 1. Package layout
+
+```
+sdk/
+  src/
+    types/        # wire types, enums, type guards — imports NOTHING else in the package
+    errors/       # ApiError + normalization (fromResponse)
+    core/         # http transport, session manager, token service, secure-request use case
+    ports/        # storage port (SDKContext) + adapters: browser, SSR
+    clients/      # one client per resource (ProjectClient, UserClient…) — thin, typed methods
+    index.ts      # composition root: wires transport → auth → clients; re-exports types/errors
+  tests/          # transport, token, concurrency tests (see §3)
+  MIGRATION.md    # one section per breaking change (see §7)
+  CHANGELOG.md
+```
+
+Internally the SDK obeys the same lattice in miniature: `types` ≈ L0, `errors` ≈ L0,
+`core`/`clients` ≈ L2, `index.ts` ≈ L5. `types/` importing from `clients/` is a bug.
+
+**Exports map — a types-only subpath is mandatory** so consumer L3 code can reference wire
+types without dragging the HTTP client into the pure layer (type imports erase at compile
+time; runtime client imports stay in L2/L5):
+
+```jsonc
+{
+  "name": "@{{PROJECT_NAME}}/sdk",
+  "type": "module",
+  "files": ["dist"],
+  "exports": {
+    ".":        { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" },
+    "./types":  { "types": "./dist/types/index.d.ts", "import": "./dist/types/index.js" }
+  },
+  "dependencies": {},                  // target: zero — fetch-based transport
+  "devDependencies": { "typescript": "…", "vite": "…", "vite-plugin-dts": "…" }
+}
+```
+
+> ⚠️ **Gotcha:** build tooling in `dependencies`. Symptom: every consumer `npm install`
+> pulls the SDK's bundler plugin into their tree. Cause: `vite-plugin-dts` (or similar)
+> added under `dependencies` instead of `devDependencies`. Fix: an SDK's `dependencies`
+> must contain only what its *runtime* imports — audit it at every release; ideally empty.
+
+## 2. Error normalization — the contract crosses repos
+
+Errors are part of the API contract, and the contract spans two repositories. Freeze the
+wire shape, normalize once in the SDK, map to UX once in the consumer.
+
+**SDK side** — every non-2xx response becomes one typed error, never a raw fetch error:
+
+```ts
+class ApiError extends Error {
+  readonly code: number; readonly errorName: string;
+  readonly statusCode: number; readonly rawMessage?: string;
+  static fromResponse(statusCode: number, responseText: string): ApiError {
+    // 1. try JSON.parse → expect { code, name, description } (the wire contract)
+    // 2. shape mismatch or parse failure → standard error built from statusCode
+  }
+}
+```
+
+**Consumer side** — one shared handler maps `statusCode` → severity + i18n message, with
+per-call overrides. UI code catches and delegates; it never inspects response bodies:
+
+```ts
+const { handleError } = useApiErrorHandler()
+try { await repo.createTeam(input) }
+catch (e) { handleError(e, { 409: t('team.alreadyExists') }) }   // 409 → warning, rest → error
+```
+
+Rules: renaming a wire error field is a **major** version bump in both repos. The SDK never
+swallows status codes; the consumer never re-parses raw responses.
+
+## 3. Auth tokens — single-flight refresh, injected storage
+
+### Single-flight refresh
+
+With rotating, **single-use** refresh tokens, two concurrent 401s must produce exactly one
+refresh call. Keep one inflight promise; latecomers await it; always bound the wait:
+
+```ts
+private refreshing: Promise<void> | null = null;
+
+// on 401 inside the secure-request use case:
+if (!this.refreshing) {
+  this.refreshing = this.doRefresh().finally(() => { this.refreshing = null; });
+}
+await withTimeout(this.refreshing, REFRESH_TIMEOUT_MS);  // reject, don't hang forever
+return retryOriginalRequest();                            // retry ONCE with the new token
+```
+
+On refresh failure: clear tokens, fail all waiters — a half-authenticated session is worse
+than a logout.
+
+> 📖 **War story:** a production team shipped refresh-on-401 without synchronization. Any
+> page firing parallel requests after token expiry sent N simultaneous refreshes; the
+> rotating refresh token was single-use, so N−1 calls failed and randomly logged users out.
+> Fix: the shared inflight promise above — plus the regression test below, because this bug
+> reappears every time someone "simplifies" the use case.
+
+**The concurrency regression test is non-negotiable** (DELIVERY.md: every rule ships with
+its test):
+
+```ts
+test('concurrent 401s trigger exactly ONE refresh', async () => {
+  // arrange: two requests that 401 first, succeed after refresh
+  await Promise.all([sdk.projects.list(), sdk.users.me()]);
+  expect(tokenService.refresh).toHaveBeenCalledTimes(1);
+});
+// also test: refresh timeout rejects waiters; refresh failure clears tokens
+```
+
+### Storage is an injected port
+
+The SDK never touches `document.cookie` or framework internals directly. It receives a
+storage port; adapters live beside it:
+
+```ts
+interface SDKContext {
+  getCookie(name: string): string | null;
+  setCookie(name: string, value: string, opts?: CookieOptions): void;
+  removeCookie(name: string): void;
+}
+createBrowserContext(): SDKContext                       // document.cookie adapter
+createSSRContext(get, set, remove): SDKContext           // delegate to framework cookie utils
+```
+
+This is the ports & adapters arrow from ARCHITECTURE_PRINCIPLES.md applied across a package
+boundary — and it is what makes the SDK testable and SSR-safe.
+
+### Token-storage tradeoff — decide, write it down, never copy a default
+
+| Option | Pros | Cons |
+|---|---|---|
+| httpOnly cookies + BFF proxy | JS can never read tokens (XSS-resistant) | needs a server tier; SDK stops managing tokens |
+| JS-readable cookie (browser adapter) | pure SPA works; survives cross-site redirects | XSS can exfiltrate; demands short-lived access + rotating single-use refresh tokens |
+
+The browser adapter above is the second option. If it also sets `SameSite=None` (cross-site
+payment/auth redirects), CSRF protection moves to the API (origin validation, CSRF tokens).
+Record the choice and its mitigations in `DECISIONS.md` — inheriting this template's default
+silently is a finding in review.
+
+## 4. Distribution — tags, no dist/ in git, verify the types
+
+- **Tagged releases only.** Semver tag per release; consumers pin the tag:
+  `"@{{PROJECT_NAME}}/sdk": "git+ssh://git@HOST/ORG/sdk.git#v1.4.2"` (or a registry pin).
+  A consumer pointing at a branch is a build that changes under your feet.
+- **Never commit `dist/`.** Gitignore it; build in CI at tag time. Committed artifacts go
+  stale, hide build breakage, and poison code review.
+- **Verify the published types after every build.** CI step: `npm pack`, install the tarball
+  in a fixture project, `tsc --noEmit` on a file importing every public type (or run
+  `@arethetypeswrong/cli`). "It built" is not proof the types shipped — see DELIVERY.md.
+
+> ⚠️ **Gotcha:** declaration plugins skip `.d.ts` source files. Symptom: consumers hit
+> "module has no exported member" for roughly half the public types. Cause: types were
+> authored as `.d.ts` files; the dts generator treats those as already-compiled and emits
+> nothing — 13 of 21 type modules silently missing from `dist/`, masked for months because
+> a stale `dist/` was committed to git. Fix: author all types as plain `.ts`, never commit
+> `dist/`, and gate releases on the type-verification step above.
+
+## 5. Logging — injected, silent by default
+
+Zero `console.*` in `src/`. The SDK accepts a logger port with a debug flag; default is a
+no-op:
+
+```ts
+interface SDKLogger { debug(msg: string, meta?: object): void; error(msg: string, meta?: object): void; }
+new SDK({ baseURL, sdkContext, logger: myLogger, debug: false })
+```
+
+Enforce with lint: `no-console: error` on `src/`.
+
+> ⚠️ **Gotcha:** a production team left 9 `console.*` calls in the request hot path — every
+> single API call logged method, URL and which auth tokens were present, into every
+> consumer's production console. Unfilterable by consumers, noisy in tests, and a free map
+> of the auth topology for anyone opening devtools. Fix: the injected logger above; debug
+> output exists, but the *consumer* owns the switch.
+
+## 6. Local-dev loop — link scripts in the consumer
+
+Iterating on SDK + app simultaneously must be one command, not manual `package.json` edits:
+
+```jsonc
+// consumer package.json scripts
+"sdk:local":  "npm pkg set dependencies.@{{PROJECT_NAME}}/sdk='file:../sdk' && npm install",
+"sdk:prod":   "npm pkg set dependencies.@{{PROJECT_NAME}}/sdk='git+ssh://git@HOST/ORG/sdk.git#vX.Y.Z' && npm install",
+"sdk:status": "npm pkg get dependencies.@{{PROJECT_NAME}}/sdk"
+```
+
+Guard rail: CI fails the consumer build if the SDK dependency is a `file:` path — local
+links must never reach a commit on a shared branch.
+
+## 7. Docs discipline — MIGRATION.md, and samples must compile
+
+- Every breaking change gets a `MIGRATION.md` section: what changed (before/after code),
+  why, impact, and the security implications if auth/cookies are involved.
+- **Every code sample must compile against the real SDK surface.** Keep samples as actual
+  `.ts` files type-checked in CI, or extract fenced blocks and run `tsc` over them.
+
+> 📖 **War story:** a migration guide illustrated CSRF mitigation with a sample passing
+> `headers` inside a resource-creation payload — an option no client method ever accepted.
+> The sample was invented, it type-checked nowhere, and teams who pasted it shipped a no-op
+> "security measure" believing they were protected. Docs with invented samples are worse
+> than no docs: they convert a knowledge gap into false confidence.