@stonepandastudio/cairn 0.4.2 → 0.5.0

package/presets/EXTRACTION.md

@@ -0,0 +1,210 @@
+# Extraction record
+
+What was pulled into `presets/`, from where, and — more importantly — what was
+deliberately left in the repos. Measured 2026-08-01 by splitting each
+`code-guidelines.md` on `## ` headings and running cairn's own line differ over
+matching sections.
+
+The file-level numbers in `DESIGN.md` (backend 43% same, frontend 76%) turned out
+to be the wrong resolution. Per section the picture is much sharper.
+
+## Backend — glossr-api (828 ln) vs snap-backend (404 ln)
+
+| Section | Same | Disposition |
+|---|---|---|
+| General TypeScript Guidelines | 100% | → `nestjs` |
+| NestJS Module Structure | 100% | → `nestjs` |
+| Services | 100% | → `nestjs` |
+| Error Handling | 100% | → `nestjs` |
+| Security | 100% | → `nestjs` |
+| Constants | 100% | → `nestjs` |
+| Enums | 100% | → `nestjs` |
+| Code Quality | 100% | → `nestjs` |
+| File Organization | 93% | → `nestjs` (union; glossr's `interfaces/` kept) |
+| File Naming Conventions | 80% | → `nestjs`, DTO lines to `dto-naming` slot |
+| TypeORM Entities | 100% | → `typeorm` |
+| Database Query Decomposition Pattern | 100% | → `typeorm` |
+| Mappers | 100% | → `typeorm` — **but see finding 1** |
+| Database Operations | 85% | → `typeorm` (glossr's stronger wording) |
+| Query Configuration | 75% | → `typeorm` (glossr is a strict superset) |
+| Validation | 43% | spine → `nestjs`, rest → `validation-stack` slot |
+| DTOs | 28% | spine → `nestjs`, rest → `dto-definition` slot |
+| Controllers | 16% | spine → `nestjs`, rest → `controller-response` slot |
+| Response Transformation | disjoint | entirely `response-transformation` slot |
+| **Testing** | **7%** | **stays project-owned** |
+| Interfaces, Error Codes, No Magic Strings, Pagination | glossr only | → `nestjs` (promoted, generic) |
+| QueryBuilder Field Selection, Migrations | glossr only | → `typeorm` (promoted, generic) |
+| Redis Key Naming | glossr only | **stays project-owned** — names a specific app prefix |
+
+### The backend divergence is one axis, not entropy
+
+Controllers 16%, DTOs 28%, Validation 43% and the two mutually exclusive Response
+Transformation sections are all the same disagreement:
+
+```
+glossr-api    Zod          nestjs-zod, createZodDto, @ZodResponse
+snap-backend  class-*      class-validator, class-transformer, @ResponseMapper
+```
+
+That is a **choice with two known values**, not accumulated rot — so it is a slot
+with two variants, not a reason to fork the file. The file-level 43% reading
+suggested "leave it alone"; the section-level reading says most of the document is
+shareable and one decision is not.
+
+## Frontend — glossr-frontend (231 ln) vs snap-frontend (191 ln)
+
+| Section | Same | Disposition |
+|---|---|---|
+| Preamble (Angular rules) | 100% | → `angular` |
+| Theming and Colors (+ 4 subsections, 94 ln) | 100% | → `angular` |
+| Component Selectors | 100% | → `angular` |
+| Constants | 100% | → `angular` |
+| Enums | 100% | → `angular` |
+| Translation Key Naming / Examples | 100% | → `angular` |
+| Translations — sourcing | 48% | → `translation-source` slot |
+| Change detection, Comments | snap only | → `angular` (promoted, generic) |
+
+Cleaner than the backend: after the sourcing slot is carved out, essentially the
+whole document is shared.
+
+## CLI — glossr-cli (203 ln)
+
+Not extracted. It shares no section headings with either pair, and per
+`DESIGN.md` it is a stack of one, so nothing can be measured against it. A
+`presets/cli/` should wait for a second CLI repo or a deliberate hand-authored
+decision — not be reverse-engineered from a sample of one.
+
+## Deliberately not extracted
+
+- **Testing (7% same).** Two genuinely different regimes: glossr keeps all tests
+  under `test/` with integration helpers and factories; snap colocates `.spec.ts`
+  and targets >80% coverage. Extracting this would force one project onto the
+  other's layout.
+- **Redis Key Naming.** Correct guidance, but it hardcodes `REDIS_APP_PREFIX =
+  'glossr'`. Generalising it would leave a rule with no concrete value in it.
+- **`code-guidelines.md` as a whole remains `fork` mode** per `DESIGN.md`. These
+  presets are seeds. A repo that takes one owns its copy; cairn does not plan to
+  rewrite these files on upgrade.
+
+## Findings
+
+Two things surfaced only because the content was read section by section.
+
+### 1. glossr-api's Mappers section documents a decorator it does not have
+
+The section is byte-identical to snap-backend's and says:
+
+> Basic entity-to-DTO conversion (use `@ResponseMapper` decorator)
+
+`grep -rl ResponseMapper glossr-api/src` returns **nothing**. glossr moved to Zod;
+the Mappers section was copied and never updated. It has been instructing agents to
+reach for a decorator that does not exist in that codebase.
+
+**A 100%-identical section is not automatically a correct one.** Identical means
+"nobody has diverged", which includes "nobody has noticed". The preset version now
+points at the response-transformation slot instead of naming a decorator.
+
+### 2. Stale line-number cross-references
+
+`glossr-api` contains *"See **Query Configuration** section below (lines 232-325)"*
+— the section actually starts at line 323. Both repos contain *"Create Maps for O(1)
+lookup (per guideline line 122)"*. Line numbers in a document that gets edited are
+wrong the moment it is edited. Replaced with section-name references.
+
+Also fixed in passing, present identically in both frontend repos: the typos
+`cosntants` and `inrastructure`. Identical typos across two repos are the clearest
+possible proof of copy-paste, and are a decent cheap signal for finding more.
+
+## Agents, workflow, commands — 2026-09-09
+
+Second pass, `snap-proof/{backend,frontend}` again. The 2026-07-31 survey scored the
+reviewer contract at 85–92% and treated that as a ceiling. Reading them in full, the
+**structure** is closer to identical — the divergence is confined to stack-specific
+rule tables and reference lists, which are exactly slot-shaped.
+
+| artefact | disposition | measurement |
+|---|---|---|
+| `.claude/commands/*.md` | → `core/commands/_stub.md` | every stub byte-identical modulo `{{ step.agentName }}` + `{{ step.agentDoc }}` (frontend copies carry a stray BOM) |
+| `ai/agents/{node,angular}-reviewer.md` | contract → `core/agents/reviewer.md`; Dimension-2 table → `{nestjs,angular}/slots/review-checklist.md` | `diff` shows ~15 changed lines out of 160, all in the rule table, the model-check string, and agent names |
+| `ai/agents/{node,angular}-developer.md` | spine → `core/agents/developer.md`; "Implementation reference" → `{nestjs,angular}/slots/implementation-reference.md` | E.1–E.5 identical; frontend carried 3 safety notes the backend lacked (folded into core) |
+| `ai/agents/{node-architect,architect-lead}.md` | Mode A/B + file-roles + Plan format → `core/agents/architect.md`; the rest → 5 small `{nestjs,angular}/slots/architect-*.md` | whole scaffold shared; slots are the mandatory-doc list, discussion topics, plan-step ordering, A.1 references |
+| `ai/WORKFLOW.md` | → `core/WORKFLOW.md`, rendered from `workflow.steps[].tracker` + `tracker.*` | same document both sides; only the provider block, stage names, and sync-point actions differ — all config |
+| `ai/AGENTS.md` | → `core/AGENTS.md` skeleton | same structure; rendering it removes live drift (frontend's still says "Jira" while its `.env` and commands are on YouTrack) |
+
+### `react` + `drizzle` seeded from charityiq-app — 2026-09-09
+
+`charityiq-app` is a separate product (single founder, UK charity SaaS), Next.js 16
+App Router + Drizzle + Supabase + Inngest, at Sprint 0 — a scaffold with documented
+intent (`CLAUDE.md` hard rules, `docs/adr/0001-stack.md`) and almost no code
+(everything under `lib/` is a `TODO(Sprint N)` stub).
+
+So the seed is **conventions and structure, not code patterns** — and there is no
+second repo to diff against, so what is "React-generic" vs "charityiq-specific" is
+hand-judged, not measured. Same limit as `preset-cli`.
+
+- `presets/react/` — components (folder-by-role: `ui`/`feature`/`brand`), no
+  `localStorage`, Tailwind v4 `@theme` tokens (no `tailwind.config.ts`), Vitest +
+  Testing Library + MSW + Playwright, Biome (tabs, double quotes). **Not** in it:
+  RSC, Server Actions, route handlers, the App Router — those are Next.js-specific
+  and belong in a future `presets/nextjs` that composes on top.
+- `presets/drizzle/` — one schema module (`lib/db/schema.ts`), `drizzle-kit
+  generate` for mechanical migrations, hand-SQL only in `supabase/migrations/`, RLS
+  policies in the migration not the schema, server client never imported from a
+  `"use client"` module. Parallel to `presets/typeorm`.
+- `presets/nextjs/` — the App-Router framework layer, added on top of `react`
+  (`--stack nextjs,react,…`, nextjs first so its fullstack plan ordering wins). Owns
+  the server/client boundary (`"use client"` discipline, no server-only imports
+  across it), Server Actions (`'use server'`, validate args, revalidate after a
+  write), Route Handlers (webhooks, verify caller), the App-Router file conventions,
+  `next/font` / `next/image` / `Metadata`, and a "the framework moves fast, read the
+  installed docs" note. **Not** in it: `requireTier()` + `audit.log()` on every
+  mutation — that is charityiq's business rule, tier-3 fork, not Next.js-generic.
+- `presets/tailwind/` — styling is a third composable axis, orthogonal to the
+  framework (proof: Angular repos use SCSS `theme.$variable`, charityiq uses
+  Tailwind `@theme`, either could use either). The generic rules: tokens in a
+  `@theme` block not a `tailwind.config.ts`, no raw hex in markup, dark mode by
+  re-mapping semantic tokens. The React preset was made styling-agnostic to match.
+  Angular's SCSS theming stays inline in `presets/angular` for now — one system
+  across its two repos, not worth its own preset until a second SCSS-theming repo
+  appears (then: `presets/scss-theme`).
+
+Stays charityiq-owned (tier 3, `fork`): the hard business rules — `requireTier()` +
+`audit.log()` on every mutation, RAG-grounded AI through `lib/ai/client.ts`, the
+audit row in the same transaction as the state change — plus `docs/adr/`, the build
+guide, and the versioned-prompt registry (`docs/prompts/<name>/<version>.md`). Those
+are the project's constitution, not shareable scaffolding.
+
+### The nestjs slots were split nestjs / typeorm — 2026-09-09
+
+The first cut of `presets/nestjs/slots/*` (review-checklist, implementation-reference,
+key-patterns, architect-mandatory-docs, architect-discussion-topics) mixed framework
+rules with TypeORM rules. Split: the framework half stays in `nestjs/slots/`, the ORM
+half moved to `presets/typeorm/slots/` under the same filenames. The renderer appends
+one from each `stack[]` entry, so `--stack nestjs,typeorm` reconstitutes the original
+and `--stack nestjs,drizzle` would pair the framework rules with a Drizzle slot set
+instead. `plan-step-ordering` and `architect-references` are primary-stack-only (not
+concatenated) — noted in their headers.
+
+### QA agents — preset-level, not extracted
+
+Backend runs three (`qa-architect` / `qa-developer` / `qa-orchestrator`, ~630 ln
+of Jest + factories + `src/feature/` layout + `yarn test:db` scripts); frontend runs
+one (`angular-qa`, Playwright + `data-testid` + page objects). 33% similar at best,
+confirming the 2026-07-31 read. The bodies are one project's test setup, not
+shareable content — vendoring them as a "preset" would over-claim. They belong under
+`{nestjs,angular}/agents/` once a second repo on the same stack shows what is
+actually shared, the same "no peer" limit `preset-cli` has.
+
+### Rot the renderer removes
+
+- backend `node-reviewer.md` still requires `claude-sonnet-4-6` — frontend already says `claude-sonnet-5`
+- frontend `AGENTS.md` + `WORKFLOW.md` are entirely Jira; the repo is on YouTrack (`.env`, `.claude/commands/youtrack-*`)
+- same review step is `code_review` in backend, `review_plan` in frontend — one verb, rendered from `workflow.steps[].command`
+- backend reviewer/developer hard-code an `ai/tasks/PROOF-[task]/` path — breaks on `LOCAL-` folders; the core versions use `ai/tasks/[task]/`
+
+## Not wired up yet
+
+There is no renderer. Nothing consumes `{{> slot: … }}` or `{{> stack/… }}`, and no
+repo reads these files. They are the input for the agent-preset roadmap step
+(`DESIGN.md`, "### Sequencing" step 4), and are already useful as the canonical
+version of scaffolding that currently exists as two drifting copies.

package/presets/README.md

@@ -0,0 +1,86 @@
+# Presets
+
+Extracted guideline content shared across the repos. Internal only — an in-repo
+folder, deliberately package-shaped so promotion to `@stonepandastudio/cairn-preset-*` is
+adding a `package.json` rather than a refactor.
+
+Nothing here is wired into a renderer yet. These are the *inputs* the renderer will
+consume once the projects layer and extension mechanisms land (see `DESIGN.md`,
+"Multi-repo projects"). Until then they are seeds: readable, diffable, and already
+useful as the canonical version of guidance that currently exists in two drifting
+copies.
+
+## Layout
+
+```
+presets/
+  core/       stack-agnostic — agent role contracts, command stub, WORKFLOW/AGENTS skeletons
+    agents/   architect.md, developer.md, reviewer.md   (85–92% identical across stacks)
+    commands/ _stub.md                                  (renders one file per workflow step)
+  nestjs/     NestJS + TypeScript framework spine, validation-stack + ORM agnostic
+    variants/ validation-zod.md, validation-class-validator.md
+    slots/    the framework side of each {{> stack/… }} point
+  typeorm/    ORM add-on — entities, queries, migrations, decomposition
+    slots/    the ORM side of the same {{> stack/… }} points (appended to nestjs)
+  drizzle/    ORM add-on — Drizzle schema, drizzle-kit migrations, RLS in migrations
+    slots/    the ORM side, for a Postgres/Supabase stack
+  angular/    Angular spine + SCSS theming + i18n (styling still inline here — one system, two repos)
+    variants/ i18n-glossr.md, i18n-external-service.md
+    slots/    the Angular side of the same {{> stack/… }} points
+  react/      React frontend spine — components, hooks, state, testing (styling-agnostic)
+    slots/    the React side of the same {{> stack/… }} points
+  nextjs/     App-Router layer over `react` — server/client boundary, actions, route handlers
+    slots/    the Next.js side of the same {{> stack/… }} points
+  tailwind/   styling add-on — @theme tokens, no tailwind.config.ts, dark mode via token re-map
+    slots/    the styling side of the same {{> stack/… }} points
+  EXTRACTION.md   what was extracted from where, and what deliberately was not
+```
+
+Compose the slots a repo needs. Rough axes — **framework** (`nestjs`, `react`,
+`nextjs` on top of `react`), **ORM** (`typeorm` / `drizzle`), **styling** (`tailwind`):
+
+```
+--stack nestjs,typeorm                  snap-proof / glossr backend
+--stack angular                         snap-proof / glossr frontend (SCSS theming inline for now)
+--stack nextjs,react,tailwind,drizzle   charityiq — nextjs primary (owns plan ordering + fullstack refs)
+--stack react,tailwind                  a Vite SPA against a separate API
+```
+
+`typeorm` and `angular` are seeded from two repos; `drizzle`, `react`, `nextjs`,
+`tailwind` from one (charityiq). A single-consumer preset is hand-judged, not
+measured, and gets refined when a second repo on that axis appears — the
+`preset-cli` "no peer" limit.
+
+`nestjs` and `typeorm` are separate on purpose. Every backend repo composes both
+today, but the split is what proves the composition model works — a future backend
+on Prisma or Drizzle takes `nestjs` without `typeorm`, and a repo declares the
+composition as `--stack nestjs,typeorm`.
+
+## Slots
+
+A slot marks a point where a shared template knows a decision exists but not which
+way a repo (or a stack) went. Two flavours:
+
+- **`{{> slot: validation-stack }}`** in a `code-guidelines.md` — the repo picks a
+  file from `variants/` by name. Where a repo needs something no variant covers, it
+  supplies its own partial — the signal that a third variant may be warranted.
+- **`{{> stack/review-checklist }}`** in a `core/` agent contract — filled from each
+  stack entry's `slots/` folder. Two fill modes:
+  - **concatenated** — the renderer appends the slot from every entry in `stack[]`,
+    in order. `--stack nestjs,typeorm` → `review-checklist` is the nestjs framework
+    rows followed by the typeorm ORM rows. Used for checklists, doc lists, reference
+    lists.
+  - **primary-only** — the slot is taken from `stack[0]` alone, because it is one
+    coherent thing that cannot be concatenated. `plan-step-ordering` (a numbered
+    sequence) and `architect-references` are primary-only; their file header says so.
+
+Slots exist to keep the merge cheap. A template update that does not touch a slot
+never conflicts with a repo's choice, which is the whole reason the extension
+mechanisms are three rather than one.
+
+## What is deliberately absent
+
+Sections that are genuinely per-project stay per-project — they are listed in
+`EXTRACTION.md` with the measurement that justified leaving them out. Extracting
+content that *should* differ is the failure mode this whole exercise is designed to
+avoid: it would report every legitimate project difference as drift, forever.

package/presets/angular/code-guidelines.md

@@ -0,0 +1,197 @@
+# Code Guidelines
+
+<!-- cairn preset: angular -->
+
+* In angular templates use new template syntax instead of old `*ng` syntax.
+* Unsubscribe from observables in `ngOnDestroy`
+* Use standalone Angular components by default, refactor component to standalone if it's not standalone component
+* Every utility function, model, constant or mapping function should stay in separated file.
+* For file names use dash-case (Example: `my-long-module.module.ts`)
+* Use Reactive Forms for any new forms.
+* All data access is handled through dedicated services.
+* Complex data manipulation is placed in utils files
+
+## Theming and Colors
+
+The application uses a CSS variables-based theming system with the following architecture:
+
+**Chain**: Global CSS Variables → SCSS Palette Variables → Abstract SCSS Variables → Component `.scss` files
+
+### Architecture Layers
+
+1. **Global CSS Variables** (`src/scss/themes/default/colors.scss`)
+   - Defines actual color values as CSS custom properties
+   - Example: `--fotofixer-color-primary: #00aabc;`
+   - Changing these allows dynamic theme switching without page refresh
+
+2. **SCSS Palette Variables** (`src/scss/themes/colors.scss`)
+   - Maps CSS variables to SCSS variables using `var()` function
+   - Example: `$fotofixer-color-primary: var(--fotofixer-color-primary);`
+   - **DO NOT import this file directly in component SCSS**
+
+3. **Abstract SCSS Variables** (`src/scss/themes/theme.scss`)
+   - Provides semantic/abstract names for colors
+   - Example: `$font-color-secondary: colors.$main-color-main-10;`
+   - **This is the only file you should import in component SCSS files**
+
+### Rules for Using Colors in SCSS Files
+
+* **DO NOT** use hardcoded colors (e.g., `#ffffff`, `white`, `rgb(...)`)
+* **DO NOT** use CSS variables directly (e.g., `var(--main-color-main-11)`)
+* **DO NOT** import `colors.scss` directly
+* **DO** import `theme.scss` using `@use` directive
+* **DO** use abstract SCSS variables from `theme.scss`
+* **DO** add new abstract variables to `theme.scss` if needed
+
+### Example Usage
+
+```scss
+@use "themes/theme" as theme;
+
+.my-component {
+  background-color: theme.$background-color-white;
+  border: 1px solid theme.$border-color-secondary;
+  color: theme.$font-color;
+
+  .secondary-text {
+    color: theme.$font-color-secondary;
+  }
+
+  .muted-text {
+    color: theme.$font-color-muted;
+  }
+
+  .primary-action {
+    background-color: theme.$fotofixer-color-primary;
+
+    &:hover {
+      background-color: theme.$fotofixer-color-hover;
+    }
+  }
+}
+```
+
+### Available Abstract Variables (from `theme.scss`)
+
+**Primary Colors:**
+- `$fotofixer-color-primary` - Main brand color (cyan)
+- `$fotofixer-color-secondary` - Light brand color
+- `$fotofixer-color-tetriary` - Very light brand color
+- `$fotofixer-color-hover` - Brand hover state
+
+**Background Colors:**
+- `$background-color-main` - Main background (light gray)
+- `$background-color-secondary` - Secondary background
+- `$background-color-secondary-hover` - Secondary hover state
+- `$background-color-white` - White background
+
+**Font Colors:**
+- `$font-color` - Main text color (black)
+- `$font-color-navbar` - Navbar text
+- `$font-color-secondary` - Secondary text (dark gray)
+- `$font-color-muted` - Muted/disabled text (medium gray)
+- `$invert-font-color` - Inverted text (white)
+
+**Border Colors:**
+- `$border-color` - Main border color
+- `$border-color-secondary` - Secondary border (light gray)
+- `$divider-color` - Divider lines (very light gray)
+
+**Message Colors:**
+- `$error-message-color` - Error text
+- `$error-message-background-color` - Error background
+- `$success-message-color` - Success text
+
+**Other:**
+- `$disabled-color` - Disabled state
+- `$link-hover-color` - Link hover state
+
+## Component Selectors
+
+* Do NOT use `app-` prefix for component selectors in new components
+* Use descriptive, kebab-case selector names (Example: `popover`, `project-status-icon`, `connected-projects-popover`)
+* Selector should match the component's purpose without generic prefixes
+
+## Translations and Internationalization
+
+### General Rules
+
+* Always use translation keys for static text in templates.
+* For dynamic text in templates use translation keys when possible. If not possible, add a comment explaining why.
+* **Locale files are generated artifacts.** Never hand-edit them and never add a key to one to make a feature render — any manual change is destroyed by the next sync.
+
+Where translations come from, and how new keys are submitted, is project-specific:
+
+{{> slot: translation-source }}
+
+### Translation Key Naming Conventions
+
+* Use PascalCase for naming translation keys.
+* Key structure depends on context:
+  * **Common text (no specific context)**: Use 2 parts - `"Common.SaveButton"`, `"Common.CancelButton"`
+  * **Context-specific text**: Use nested structure - `"[PageName].[Subcontext].[TextDescription]"`
+
+### Examples
+
+**Common keys:**
+```json
+"Common": {
+  "SaveButton": "Save",
+  "CancelButton": "Cancel",
+  "Loading": "Loading..."
+}
+```
+
+**Page-specific keys:**
+```json
+"DevicesTable": {
+  "Title": "Devices Table",
+  "Header": {
+    "CityColumn": "City",
+    "DeviceColumn": "Device"
+  },
+  "Button": {
+    "DownloadReport": "Download Report"
+  }
+}
+```
+
+**Message keys:**
+```json
+"Messages": {
+  "Devices": {
+    "FailedLoadDevices": "Failed to load devices",
+    "FailedDownloadReport": "Failed to download report"
+  }
+}
+```
+
+### Checking Existing Keys
+
+Before creating new translation keys, check the existing English locale file for examples and to avoid duplication. Read it only — see the generated-artifact rule above.
+
+## Change detection
+
+* **Match the strategy used by nearby/similar components.** The codebase mixes `Default` and `OnPush`; don't default to `OnPush` unless the surrounding components use it. Most page-level components currently use `ChangeDetectionStrategy.Default`.
+* If you're adding a component to an area where everything is `Default`, use `Default`. If you're adding one next to `OnPush` components, use `OnPush`.
+* Don't "upgrade" an existing component from `Default` to `OnPush` as a drive-by change — that's a focused refactor, not part of a feature plan.
+
+## Comments
+
+* **Default to no comments.** Good names carry meaning; small functions are self-documenting.
+* Only write a comment when the *why* is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, behavior that would surprise a reader.
+* Don't explain *what* the code does — identifiers and structure already do that.
+* Don't reference task IDs, PR flows, or "added for feature X" in code comments — that context belongs in commit messages and PR descriptions, and rots as the codebase evolves.
+* No multi-paragraph docstrings or multi-line comment blocks — one short line is the ceiling.
+
+## Constants
+
+File name template: `xx-yy.constant.ts` for `XxYy` constant
+
+Files with constants should be placed in the `constants/` folder within the corresponding module (see `ai/infrastructure/project-structure.md` for module details)
+
+## Enums
+
+File name template: `xx-yy.enum.ts` for `XxYy` enum
+
+Files with enums should be placed in the `enums/` folder within the corresponding module (see `ai/infrastructure/project-structure.md` for module details)

package/presets/angular/slots/architect-discussion-topics.md

@@ -0,0 +1,10 @@
+<!-- cairn preset: angular — fills {{> stack/architect-discussion-topics }} (A.3). -->
+- **Ambiguities** — anything in the description that admits multiple reasonable interpretations
+- **UX / design tradeoffs** — popup vs. page, tabs vs. stacked sections, inline vs. separate component
+- **Integration tensions** — e.g. global company state vs. route-scoped company id
+
+**Optional aid — `frontend-design` skill.** When the discussion hinges on a
+visual/UX tradeoff, `frontend-design` can explore mockups. **Treat its output as
+inspiration only** — it does not know this project's conventions (Material UI,
+`theme.scss` variables, base classes, new template syntax, no `app-` prefix,
+translation keys). Never feed its generated code into the plan.

package/presets/angular/slots/architect-mandatory-docs.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: angular — fills {{> stack/architect-mandatory-docs }} (A.2). -->
+- `ai/infrastructure/code-guidelines.md`
+- `ai/infrastructure/project-structure.md`
+- `ai/infrastructure/patterns.md`
+- `ai/infrastructure/mappers.md`

package/presets/angular/slots/architect-references.md

@@ -0,0 +1,4 @@
+<!-- cairn preset: angular — fills {{> stack/architect-references }} (A.1). -->
+- Frontend source files (components, services, base classes)
+- The backend repo's context docs — entity definitions, business logic, controllers
+- Backend source files, for API-shape confirmation

package/presets/angular/slots/implementation-reference.md

@@ -0,0 +1,34 @@
+<!-- cairn preset: angular — fills {{> stack/implementation-reference }} in the core
+     developer. snap-proof/frontend/ai/agents/angular-developer.md has no block like
+     the nestjs one — it points at patterns.md + code-guidelines.md and stops.
+     This is a minimal synthesis from angular-developer + angular-reviewer; extend
+     it when a second Angular repo shows what is actually shared. -->
+
+The authoritative source is `ai/infrastructure/code-guidelines.md`; the base-class
+and header-flow catalogue is `ai/infrastructure/patterns.md`. Reminders:
+
+### Components
+- Standalone components — no `NgModule` declarations block
+- No `app-` prefix in the selector
+- Match the change-detection strategy of nearby components
+- Subscriptions collected in a `Subscription`, unsubscribed in `ngOnDestroy`
+- Complex data manipulation goes in a `utils/` file, not inlined
+
+### Templates
+- Control flow: `@if` / `@for` / `@switch` — never `*ngIf` / `*ngFor`
+- Every `@for` carries a `track` expression
+- Every static string is a translation key — no bare literals
+
+### Styles
+- Only `theme.$variable` from `@use "themes/theme" as theme` — no `#hex`, `rgb()`, or CSS custom properties
+
+### Forms
+- Reactive forms only — no `ngModel`
+
+### Files
+- Models, enums, constants, and mapper functions each in their own kebab-case file
+- `enums/`, `constants/`, `mappers/` folders per module
+- Mapper shapes: `EntityResponse → Entity`, `Entity ↔ EntityForm`, `Entity → EntityPayload`
+
+### Build
+- Run the project's production build before reporting completion; a failing build blocks the report

package/presets/angular/slots/key-patterns.md

@@ -0,0 +1,11 @@
+<!-- cairn preset: angular — fills {{> stack/key-patterns }} in the core architect
+     and developer. From architect-lead.md / angular-developer.md. -->
+
+Canonical catalogue: **`ai/infrastructure/patterns.md`** — base classes, the
+`x-admin-profile` header flow, routing. Plans should lean on these instead of
+reinventing them.
+
+Micro-level conventions (theming, translations, template syntax, change detection,
+file naming): **`ai/infrastructure/code-guidelines.md`**.
+
+Mapper conventions: **`ai/infrastructure/mappers.md`**.

package/presets/angular/slots/plan-step-ordering.md

@@ -0,0 +1,11 @@
+<!-- cairn preset: angular — fills {{> stack/plan-step-ordering }} in the core
+     architect's Plan format. architect-lead.md gives no explicit ordering beyond
+     "each step leaves the app working"; this is a synthesis, refine against a
+     second Angular repo. -->
+1. Models, enums, constants, mapper functions
+2. Service methods (API calls, state)
+3. Component logic (`.ts`)
+4. Template (`.html`) and styles (`.scss`)
+5. Routing and module wiring
+6. Translation keys
+7. Context doc updates

package/presets/angular/slots/review-checklist.md

@@ -0,0 +1,16 @@
+<!-- cairn preset: angular — fills {{> stack/review-checklist }} in the core reviewer.
+     Verbatim from snap-proof/frontend/ai/agents/angular-reviewer.md § Dimension 2. -->
+
+| New template syntax (`@if`, `@for`, `@switch`) — no `*ngIf`/`*ngFor` | `.html` files |
+| `@for` always includes a `track` expression — missing `track` is a compile error in Angular 17+ | `.html` files |
+| Standalone components — no `NgModule` declarations block | Component `.ts` files |
+| Observables subscribed inside components are collected in a `Subscription` and unsubscribed in `ngOnDestroy` | Component `.ts` files |
+| No hardcoded colors (`#hex`, `rgb()`, CSS custom properties) — only `theme.$variable` from `@use "themes/theme" as theme` | `.scss` files |
+| No `app-` prefix in component selectors | Component `.ts` files |
+| All static text in templates uses translation keys — no bare string literals | `.html` files |
+| `src/assets/i18n/*.json` never hand-edited — autogenerated, replaced during localization — **blocking** if the diff touches these files directly | `src/assets/i18n/*.json` |
+| Reactive forms only — no template-driven forms (`ngModel`) | Component `.ts` files |
+| Complex data manipulation goes in `utils/` files, not inlined in components | Component `.ts` files |
+| Mapper pattern respected: `EntityResponse → Entity`, `Entity ↔ EntityForm`, `Entity → EntityPayload` | `mappers/` files |
+| Models, enums, constants, and mapper functions each in their own kebab-case file | Module folder structure |
+| Enums in `enums/` folder, constants in `constants/` folder, mappers in `mappers/` folder | Module structure |

package/presets/angular/variants/i18n-external-service.md

@@ -0,0 +1,11 @@
+<!-- cairn variant: translation-source = external-service. Fills the
+     translation-source slot in presets/angular/code-guidelines.md.
+     In use by: snap-frontend. A third-party localization vendor owns the values. -->
+
+## slot: translation-source
+
+Never add or update translation values for translation keys in `src/assets/i18n/*.json` files directly. These are autogenerated files that will be replaced by a third-party service during the localization process.
+
+### Checking Existing Keys
+
+Before creating new translation keys, check existing keys in `src/assets/i18n/en-us.json` for examples and to avoid duplication.