oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-explanation/resources/document-structure.md

@@ -0,0 +1,115 @@
+# Document Structure — oma-explanation
+
+> The structural and rhetorical contract for all generated HTML explainer documents.
+> Read this document to understand WHAT content is generated and in what tone.
+> For HOW the HTML is styled and behaves, see `html-contract.md`.
+
+> **Authoring path**: write a draft and render it with `oma explain render` (see
+> `draft-format.md`). The four sections below become panels in the same order; the renderer
+> supplies the page shell, so the TOC and diagram-markup rules in sections 1 and 6 apply
+> literally only to the hand-written HTML fallback. Topic-mode pages follow `draft-format.md`
+> and are not bound to the four sections.
+
+---
+
+## 1. Overall Shape
+
+Every explainer document must be a **single long scrolling page**.
+Do **not** use top-level tabs or multi-page navigation.
+The document must begin with a Table of Contents (TOC), followed strictly by these four fixed sections in order:
+1. **Background**
+2. **Intuition**
+3. **Code**
+4. **Quiz**
+
+---
+
+## 2. Background
+
+The Background section establishes context before presenting any code changes. It is composed of two tiers:
+
+- **Tier A (Deep Background)**: Broadly explains the surrounding system or architecture. Must be explicitly marked "skippable if you already know the system."
+- **Tier B (Narrow Background)**: Directly explains the context relevant to the specific change.
+
+*Note on Reader Level:* If the requested reader level is `reviewer`, aggressively condense Tier A (Deep Background).
+
+---
+
+## 3. Intuition
+
+The Intuition section conveys the core essence of the change without diving into full implementation details.
+
+- **Toy-Data Examples**: Concrete toy-data examples are **mandatory**. Show, don't just tell, how the inputs and outputs change.
+- **Visuals**: Liberally use diagrams (see Section 6) to establish mental models early.
+
+---
+
+## 4. Code
+
+The Code section is a high-level walkthrough of the changes.
+
+- **Comprehension Order**: Group and order the code walkthrough for human comprehension. Do **not** simply list files in alphabetical or git-diff order.
+- **Reference**: Reference code using `file:line` notation where useful.
+
+---
+
+## 5. Quiz
+
+The Quiz verifies understanding. While `html-contract.md` defines the interaction and JS behavior, this document governs question quality:
+
+- **Count**: 5 questions by default (this count is parameterizable).
+- **Difficulty**: Medium. Questions must be answerable only if the reader understood the substance of the change. No trick questions or gotchas.
+- **Coverage**: Each question must target a distinct aspect of the change.
+- **Distractors**: Wrong options (distractors) must be highly plausible.
+- **Feedback**: **Every** option (correct and incorrect) must have accompanying feedback text explaining exactly why it is right or wrong.
+
+---
+
+## 6. Diagram Families
+
+Visual consistency is critical. Pick **2–3 diagram families** per document and **reuse** them across sections to build continuity.
+
+### Family Catalog
+Choose from the following conceptual families:
+- **Simplified UI Mock**: Abstracted representation of what the user sees.
+- **System/Data-Flow Diagram**: Component interaction flows carrying **example data** directly on the arrows.
+- **Before/After State**: Visual comparison of the system state before and after the change.
+
+### Format & Responsiveness Constraints
+- Diagrams must be rendered using **HTML/CSS** or **inline SVG** only.
+- **ASCII art is strictly forbidden.**
+- **Responsive Container**: Every diagram must be wrapped in a `<div class="diagram-wrapper">` container with `overflow-x: auto; max-width: 100%;` to prevent horizontal clipping on mobile devices (375px+). Inline SVGs must declare `viewBox` and responsive width (`width="100%"`).
+- **Theme-Aware Colors**: All diagram elements (borders, text, arrows, node backgrounds) MUST use CSS variables (e.g. `var(--border-color)`, `var(--text-primary)`) or `currentColor` rather than hardcoded hex colors, ensuring seamless adaptation to Dark/Light theme toggling.
+- **Accessibility (a11y)**: Diagrams must include `role="img"` and a descriptive `aria-label` or `<title>` element summarizing the diagram flow for assistive technologies.
+- Use semantic HTML lists (`<ul>`, `<ol>`, `<dl>`) for textual lists.
+- **archify sidecar (optional)**: an interactive archify diagram is a *separate* `.archify.html` file linked by a plain `<a href>` — it is never embedded (no `<iframe>` / `<object>` / `<script src>`), and the inline SVG/CSS diagram above stays in place so the explainer remains complete offline. See `_shared/conditional/diagram-engine.md`.
+
+---
+
+## 7. Callouts
+
+Use styled callout blocks to highlight:
+- Key concepts and definitions.
+- Important edge cases and gotchas.
+
+These should visually interrupt the prose to draw the reader's attention to critical information.
+
+---
+
+## 8. Writing Style and Language
+
+The explainer must read with authoritative clarity, smooth transitions between sections, and an engaging tone.
+
+- **English Prose**: Aim for Martin Kleppmann-like clarity. Classic style, engaging, logically rigorous but accessible.
+- **Punctuation restraint**: Em-dashes are limited to a handful per document. Prefer commas, colons, parentheses, or a second sentence. CJK prose avoids em-dashes entirely (mirrors the repo's `cjk-em-dash` lint rule for translated docs).
+- **CJK Output**: Follow the `translation_voice` register configured in `.agents/oma-config.yaml`.
+- **i18n Rules**: Prose and quiz content must be in the user's requested language. However, following `.agents/rules/i18n-guide.md`, **code blocks, identifiers, and inline code are always in English**. Do not translate technical terms or variable names.
+
+---
+
+## 9. Provenance Footer
+
+Every document must end with a provenance footer containing:
+- **Generated-from reference**: The commit range, PR number, or branch used as input.
+- **Generation Date**: The date in the oma-config `timezone`, falling back to the system timezone when unset.
+- **Excluded Files**: If the diff was oversized and files were dropped, list the excluded files in a footnote. Never silently truncate.

package/skills/oma-explanation/resources/draft-format.md

@@ -0,0 +1,199 @@
+# Draft Format — `oma explain render`
+
+> The authoring contract for explanations. You write a Markdown draft; `oma explain render`
+> turns it into the HTML page. You never write HTML, CSS, SVG, or coordinates.
+> For WHAT a change explainer must contain, see `document-structure.md`.
+
+## 1. Why a draft
+
+Layout, theme, diagram geometry, responsiveness, escaping, and the quiz script are the
+renderer's job. They are the same on every page and they are tested. Your job is the content:
+which panels exist, what each one says, and which relations a diagram shows.
+
+```bash
+oma explain render draft.md            # → .agents/results/explain/{YYYY-MM-DD}-{slug}.html
+oma explain render - < draft.md        # draft from stdin
+oma explain components                 # list the components
+oma explain components flow            # one component's syntax and example
+oma explain lint draft.md              # prose check only, no page
+oma explain patch <page.html> --panel C panel.md   # replace one panel, keep the rest
+oma explain patch <page.html> --panel "Call order" panel.md   # or name it by title
+```
+
+Write the draft to a scratch location (or pipe it); the HTML is the artifact, and it embeds
+the draft so a later `patch` needs nothing else.
+
+## 2. Shape of a draft
+
+```markdown
+---
+title: How the row planner fills a page        # required (or start the body with "# Title")
+subtitle: One sentence that says what the reader will know afterwards
+slug: row-planner                               # file name; required when the title is not ASCII
+template: sheet                                 # sheet = grid of panels (default) | doc = one column with contents
+theme: blueprint                                # blueprint (default) | card; the reader can switch on the page
+mode: auto                                      # auto (default) | light | dark
+cols: 3                                         # grid the span hints refer to, 1-12
+style: warn                                     # prose check: off | warn (default) | strict
+Scope: cli/commands/explain/render              # any other key shows in the header meta line
+---
+
+One or two lead sentences: the answer first.
+
+## Panel title {span=2 note="12 nodes"}
+
+Markdown prose, lists, tables, and component blocks.
+
+## Next panel
+```
+
+- One `## ` heading starts one panel. Panels get letters A, B, C in order; a heading may
+  give its own (`## C Title`, `## B1 Title`), and ids must not repeat.
+- Panel attributes, all optional: `span=N` (width hint in grid columns; `span` equal to `cols`
+  keeps the panel on its own row), `rows=N` (height in the plain grid), `note="…"` (small text
+  at the right of the head), `bare` (no head), `archify` (this panel's diagram feeds the
+  interactive sidecar, see section 5).
+- You do not place panels. The page measures every panel and packs rows so they fill the
+  width with the least blank space, keeps the diagrams of one page at similar scales, and
+  falls back to one column on a phone. A wide table or diagram gets a wider span by itself,
+  so write `span` only for a panel that must stand out.
+- `template: sheet` suits an overview read at a glance: 4 to 9 panels. `template: doc` suits
+  a linear explanation read top to bottom; it adds a contents list from three panels up.
+- One idea per panel: a diagram with two sentences beats a wall of text.
+- Prose is GitHub-flavoured Markdown, parsed by remark: `###` headings, nested and task
+  lists, tables with alignment, quotes, rules, links (inline or reference style), footnotes. An image shows only as a `data:` URI; any other image
+  becomes a link, because the page loads nothing from outside.
+
+## 3. Components
+
+A fenced block named after a component renders that component. Any other fence
+(`ts`, `bash`, `json`, …) is shown as code; `diff` colours added and removed lines.
+
+| Component | Use it for | Draft content |
+| --- | --- | --- |
+| `flow` | architecture, pipelines, decisions | relations: `A -> B: label`, `group Name: A, B` |
+| `sequence` | calls between actors over time | `From -> To: message`, `note A, B: text`, `== Phase ==` |
+| `tree` | org chart, breakdown, file tree | indented names, `label \| note`, `*highlight` |
+| `timeline` | history, phases, rollout | `when \| title \| detail`, `*when` for the key event |
+| `limits` | a value against its limit | `label \| value / limit \| unit` |
+| `annot` | a command or line of code, part by part | `[span]{note}`, `[span]{!wrong}` |
+| `kv` | facts as a grid, or a title block | `key: value`, `* wide key: value`, `cols=N` |
+| `callout` | the one point not to miss | `callout info\|ok\|warn\|err\|key Title` + Markdown |
+| `quiz` | comprehension check | `? question`, `- wrong`, `+ right`, `> feedback` |
+
+Run `oma explain components <name>` for the exact grammar before the first use in a session.
+The essentials:
+
+````markdown
+```flow LR
+(User) -> API -> Service* -> [(Orders DB)]
+Service --> Queue: order.created
+{Valid?} -> Service: yes
+group Backend: API, Service
+```
+````
+
+- `->` solid, `-->` dashed. A chain creates its nodes. `A -> B & C` fans out.
+- Shapes: `(pill)` for actors and endpoints, `{diamond}` for decisions, `[(cylinder)]` for
+  stores, plain text or `[box]` for everything else. A `*` before the name marks the node
+  the panel is about. `name = Long label` gives a long label a short name.
+- `group Name: A, B` frames related nodes. The layout keeps every other node out of the frame.
+- A node name that holds a colon goes in brackets: `[step: one]`.
+- Write relations only. Do not order lines to "place" nodes, and never use ASCII art.
+- Keep a diagram under about 12 nodes and labels under about 20 characters. Split it otherwise.
+- Put example data on the arrows (`: {sid, kind}`) when the data is the point.
+
+````markdown
+```sequence num
+participants: Client, Server
+Client -> Server: SYN
+Server --> Client: SYN-ACK
+== Established ==
+note Client, Server: both sides can send
+```
+````
+
+- `participants:` fixes the left-to-right order; `num` numbers the messages; `== Title ==`
+  starts a phase; a note may span several participants.
+
+`tree` picks its shape from the content: one root with 2 to 4 children draws an org chart,
+several roots stand side by side, and a file tree (`src/`, `main.ts`) or the `list` argument
+gives an indented list. `timeline` runs left to right up to six events and top to bottom
+beyond (`h` / `v` force it).
+
+Fullwidth punctuation works wherever a colon or comma separates fields (`：`, `，`), so a
+Chinese, Japanese, or Korean draft needs no switch of input mode.
+
+Tables: a cell that starts with `ok`, `no`, or `warn` becomes a status badge
+(`| Retry | ok idempotent |`). Use this for comparisons and before/after tables.
+
+Text is always shown as written. `<sid>`, `<T>`, and HTML in a draft appear as characters;
+nothing in a draft can inject markup.
+
+## 4. Writing
+
+The renderer checks the prose (`style: warn` prints warnings, `strict` fails the render):
+
+- One fact per sentence. English: at most 25 words (20 in a numbered step). Korean: about
+  70 characters. Japanese 65, Chinese 45. At most 6 sentences in a paragraph.
+- Plain words: "use", not "utilize"; "to", not "in order to". Name who does what instead of
+  the passive.
+- Korean: no double passive (`되어진`, `보여지다`), no translationese (`~에 있어서`,
+  `~로부터`, `~하는 것이 가능하다`, `~에 의해`), verbs instead of `~을 수행/진행하다`, and
+  correct spellings (`됐`, `며칠`).
+- Chinese: no light verbs (`进行验证` → `验证`), no clichés (`赋能`, `闭环`), numbers
+  instead of `若干` / `尽快`, and `大于` / `不小于` instead of `10 次以上`.
+- Japanese: `できる` instead of `することができる`, the verb instead of `〜を行う`.
+- The page language is detected from the draft (Hangul → Korean). Set `lang:` only to override.
+- Fix warnings by rewriting the sentence, not by turning the check off. Counter-examples go
+  in `~~strikethrough~~` or a table row marked `no`; those are not checked.
+
+When the render fails, the error names the draft line and prints the component's syntax and
+an example. Fix that line and render again.
+
+## 5. archify sidecar
+
+`flow` and `sequence` blocks already hold a typed graph, so the renderer derives the archify
+spec itself:
+
+```bash
+oma explain render draft.md --archify      # or diagram.explain_sidecar: true in oma-config
+```
+
+- Source diagram: the first flow/sequence block of the panel marked `{archify}`, else the
+  first one in the draft. Mark the panel whose diagram is the main picture.
+- Output: `{stem}.archify.html` (and `.archify.json`) next to the page, linked by a plain
+  anchor under that panel and in the footer. Never embedded.
+- `flow` becomes an archify `architecture` grid and its groups become boundaries; `sequence`
+  becomes an archify `sequence` and its `== Phase ==` dividers become segments. Component
+  types come from the label and shape: name stores, queues, users, and UI as what they are.
+- A sidecar is an extra. If archify is not installed, the diagram is too small, or
+  `deliver` fails, the page is still written and the report says why. Do not hand-author a
+  spec to work around it unless the user asks; `--no-archify` skips it.
+
+## 6. Change explainer drafts
+
+For a diff / PR / branch (`document-structure.md`), set `template: doc` and write the four
+sections as panels in this order:
+
+1. **Background** panels: surrounding system (say it is skippable), then the narrow context.
+   A `flow` or `tree` usually carries the first one.
+2. **Intuition** panels: toy data in a table or on `flow` / `sequence` arrows; before/after
+   as a table with `no` / `ok` cells.
+3. **Code** panels in comprehension order: a `diff` (or language) fence per step, with
+   `file:line` in the panel `note` or the sentence above it. `annot` for a single line that
+   deserves a part-by-part reading.
+4. **Quiz** panel: one `quiz` block, 5 questions by default, feedback (`>`) on every option.
+
+Add the provenance facts as frontmatter keys (`Source: PR #640`, `Excluded: bun.lock`), so
+they show in the header.
+
+## 7. After rendering
+
+```bash
+oma explain validate <file>
+```
+
+The renderer already guarantees the self-contained rule, `<pre>` code containers, themes,
+focus states, and the quiz behaviour. The validator still matters for what you control:
+the file name and secrets quoted in prose or code.

package/skills/oma-explanation/resources/html-contract.md

@@ -0,0 +1,102 @@
+# HTML Explainer Contract
+
+This resource specifies HOW the generated HTML file behaves and is validated. For content requirements, refer to the sibling `document-structure.md` file.
+
+> Pages made by `oma explain render` meet sections 1–5 by construction (inline CSS and
+> script under a `default-src 'none'` policy, `<pre>` code, light/dark themes, shuffled quiz
+> with per-option feedback). For those pages this contract reduces to section 6
+> (`oma explain validate`) and section 7 (secret gates). Sections 1–5 remain the rules for
+> hand-written HTML.
+
+## 1. Self-contained Rule
+The generated HTML file MUST make ZERO external resource loads.
+- No CDN scripts or stylesheets.
+- No webfonts.
+- No external images (use inline SVG or data URIs).
+- Must open correctly offline via `file://`.
+- **Note:** Hyperlink anchors (`<a href="https://...">`) ARE allowed. The ban covers resource-LOADING only.
+
+## 2. Code Blocks
+- All code blocks must use `<pre>` tags.
+- Any custom-styled container holding code MUST declare `white-space: pre-wrap` (or `pre`).
+- Do NOT use external syntax-highlighting libraries. Use plain theme-aware colors only.
+
+## 3. Font Stack
+The `Self-contained rule` supersedes any webfont suggestion in the project `design.md`. Use the following font stack:
+1. Locally installed Pretendard, matched by family name — NOT the CSS `local()` function, which is only valid inside `@font-face src` (see the code comment below)
+2. System CJK fonts (`Apple SD Gothic Neo` / `Noto Sans CJK`)
+3. `system-ui` stack
+
+```css
+/* Locally installed Pretendard resolves by family name; local() is only valid
+   inside @font-face src, so never use it in font-family. */
+font-family: Pretendard, 'Pretendard Variable', 'Apple SD Gothic Neo', 'Noto Sans CJK KR', 'Noto Sans CJK JP', 'Noto Sans CJK SC', 'Noto Sans CJK TC', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+```
+
+## 4. Layout and Accessibility (a11y)
+- **Responsive:** Mobile-first, responsive from 375px up.
+- **Readable Measure & Line Height:** Body text containers MUST enforce a max-width (800px–880px / ~75ch) with centered margin (`margin: 0 auto`) and generous line-height (`1.6`–`1.7`) to prevent wide-screen line stretching and ensure optimal reading rhythm.
+- **Diagram Visuals:** Every diagram/visual MUST be wrapped in a `<div class="diagram-wrapper">` with `overflow-x: auto; max-width: 100%;` and use SVG `viewBox` / CSS variables (`var(...)`) to prevent mobile clipping and guarantee seamless Dark/Light theme switching.
+- **Contrast:** WCAG AA contrast in BOTH light and dark themes.
+- **Dark Mode:** Must support `prefers-color-scheme: dark` as well as explicit manual theme toggling via data attributes.
+- **Motion:** Animations are optional and must be subtle.
+- **Focus States:** Visible focus states are required on all interactive elements.
+
+## 5. Quiz JS Specification
+- Use **Vanilla JS only** (no frameworks).
+- Options must be rendered as `<button>` elements.
+- Clicking an option (or using Enter/Space) must reveal correct/incorrect immediately.
+- Include per-option feedback text (explain *why* wrong answers are wrong).
+- Feedback must be announced via an `aria-live="polite"` region for screen readers.
+- Quiz data lives in a JS array of `{question, options: [{text, correct, feedback}]}` objects. Options are shuffled client-side (Fisher-Yates) on EVERY page load, so positions change on each refresh and no position bias can survive. Feedback stays attached to its option object, never to a rendered position, and option labels (A/B/C/D) are assigned after the shuffle.
+- Display a final score summary at the end of the quiz.
+- The entire quiz must be fully keyboard-navigable.
+
+## 6. Validation Checklist (Post-generation)
+Use `oma explain validate <file>` as the primary post-generation check. Review its reported content and structure failures. The grep commands below are supplemental spot checks; a zero-match result does not replace the validator or review of actual secret values in code excerpts.
+Loop: fix and re-validate at most **3 iterations**, then STOP and surface the failing items to the user.
+
+**Known false positives — do not "fix" example code.** A hit located inside a `<pre>` block that merely *quotes* a matching pattern as illustrative text (a commented-out `@import` in a "what not to do" snippet, an example `api_key` in a config walkthrough) is not a live resource load or a real secret. Log such hits as reviewed false positives in the provenance footer instead of mangling the example, and do not count them against the 3-iteration budget. Live `<head>` / `<script src>` references and actual secret values must still be fixed or gated. Do not treat every `<pre>` or `<code>` value as a false positive: actual credentials are still secrets when quoted.
+
+- **No external resource loads** (zero matches required):
+  ```bash
+  grep -E -i 'src="http|<link rel="stylesheet" href="http|@import|url\(http' {file}
+  ```
+- **Code containers compliance** (must match if code exists):
+  ```bash
+  grep -E -i '<pre|white-space:\s*pre|white-space:\s*pre-wrap' {file}
+  ```
+- **Quiz script presence** (must match; `[ >]` covers attributed tags like `<script type="module">`):
+  ```bash
+  grep -i -E '<script[ >]' {file}
+  ```
+- **Filename matches format** (the pattern is anchored, so check the basename, not the full path):
+  Ensure filename follows `{YYYY-MM-DD}-{slug}.html` with the date in the oma-config `timezone` (system timezone when unset).
+  ```bash
+  basename "{file}" | grep -E '^[0-9]{4}-[0-9]{2}-[0-9]{2}-.+\.html$'
+  ```
+- **Final-HTML secret scan** (zero matches required, see §7):
+  ```bash
+  grep -E -i '(api_key|api-key|secret|password|token|private[-_]key|connection[-_]string)\s*[=:]\s*["'\'']?[A-Za-z0-9\-_]{16,}["'\'']?' {file}
+  ```
+
+## 7. Secret Gates
+Secrets must be gated at two stages:
+1. **Pre-generation:** Scan the collected diff.
+2. **Post-generation:** Scan the final HTML (as background prose may quote unchanged files, the diff scan alone is insufficient).
+
+### Secret Patterns
+*Note: the excluded-file globs below mirror `EXCLUDED_FILE_PATTERNS` in `cli/commands/docs/sync-propose.ts` — when those globs diverge, that file wins. Content checks are implemented in `cli/commands/explain/validate.ts` and include assigned secret-like values and vendor token patterns. The minimal regex below is a supplemental diff check; the current CLI implementation defines the HTML validation behavior.*
+
+Mirroring a MINIMAL pattern set for secret-like literal values (API keys, tokens, private keys, passwords, connection strings):
+- **Excluded Files:** `.env`, `.env.*`, `*.pem`, `*.key`, `id_rsa`, `id_rsa*`
+- **Regex Pattern:** `(api_key|api-key|secret|password|token|private[-_]key|connection[-_]string)\s*[=:]\s*["']?[A-Za-z0-9\-_]{16,}["']?`
+  (canonical pattern — the embedded quotes break naive single-quoted shell pasting; run it via the pre-escaped §6 "final-HTML secret scan" invocation)
+
+**On Any Hit:**
+- **STOP** immediately.
+- Report the masked locations only (NEVER echo the actual value).
+- Redacted continuation requires explicit user confirmation.
+
+## 8. Sharing Caution
+**Caution (informational, for the operator):** the artifact embeds code excerpts — treat it like source code when sharing externally. Embedding this caution inside the generated document itself is deferred to v2 (design 022 Tier 3); the generated footer's contract is `document-structure.md` §9 and does not include a sharing-caution line in v1.

package/skills/oma-frontend/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: oma-frontend
+description: Implement or modify web UI in React, Next.js, or Angular. Use for
+  components, pages, styles, forms, and frontend state or data flows.
+---
+
+# Frontend Agent - UI/UX Specialist
+
+## Scheduling
+
+### Goal
+Build, modify, and verify React/Next.js or Angular TypeScript user interfaces that follow project architecture, design-system constraints, accessibility expectations, and existing frontend conventions.
+
+### Intent signature
+- User asks for UI, component, page, layout, CSS, Tailwind, shadcn, form, interaction, client state, or frontend API integration work.
+- User needs browser-facing implementation in a React/Next.js or Angular TypeScript codebase.
+- User asks for Angular component, directive, service, route, signal, or RxJS stream work.
+
+### When to use
+- Building user interfaces and components
+- Client-side logic and state management
+- Styling and responsive design
+- Form validation and user interactions
+- Integrating with backend APIs
+
+### When NOT to use
+- Backend API implementation → use Backend Agent
+- Database access, migrations, or ORM setup → use Backend Agent
+- Auth server setup (better-auth server library, DB adapters) → use Backend Agent
+- Native mobile development → use Mobile Agent
+
+### Expected inputs
+- Target page, component, flow, or UI behavior
+- Existing app structure, design tokens, component library, i18n files, and API contracts
+- Acceptance criteria and target responsive states
+
+### Expected outputs
+- Frontend code changes in pages, components, hooks, styles, tests, or wrappers
+- UI that respects project tokens, i18n, server/client boundaries, and accessibility expectations
+- Verification results from relevant lint, typecheck, tests, or browser checks
+
+### Dependencies
+- React, Next.js, TypeScript, TailwindCSS v4, and `shadcn/ui` — or Angular + signals + RxJS in Angular projects (`resources/angular-rules.md`)
+- Project sources of truth such as `packages/design-tokens`, `packages/i18n`, and shared utilities
+- `resources/execution-protocol.md`, `resources/checklist.md`, snippets, and Tailwind rules
+- Conditional visual implementation routes and shared interaction-quality guidance; load only for the affected capability.
+
+### Control-flow features
+- Branches by server/client component boundary, responsive state, component library availability, and i18n/token requirements
+- Reads and writes frontend codebase files
+- May call shadcn registry tools or local verification commands
+
+## Structural Flow
+
+### Entry
+1. Identify target route, component, state boundary, and design-system constraints.
+2. Read existing patterns before adding components or utilities.
+3. Determine whether work belongs in Server Components, Client Components, wrappers, hooks, or styles.
+
+### Scenes
+1. **PREPARE**: Load relevant project conventions, UI requirements, and acceptance criteria.
+2. **ACQUIRE**: Inspect existing components, tokens, i18n keys, APIs, and shadcn availability.
+3. **ACT**: Implement UI, state, styles, validation, and integration.
+4. **VERIFY**: Run checklist, automated checks, and browser/responsive validation when applicable.
+5. **FINALIZE**: Summarize changed UI behavior and verification.
+
+### Transitions
+- If a strict shadcn primitive exists, use or wrap it before creating generic markup.
+- If UI text is user-facing and i18n exists, add strings through the i18n source of truth.
+- If interaction or hooks are needed, mark the boundary as Client Component.
+- If backend contracts are missing, coordinate with backend/API planning.
+- For a new or substantially changed admin console, dashboard, SaaS product UI, or internal tool, recommend a post-implementation `oma-design` review through `../oma-design/resources/product-interface-review.md`. This review is advisory unless the task explicitly requires design approval.
+- For a requested GPU effect, video-scroll scene, or selected GSAP implementation, use the matching conditional extension.
+
+### Failure and recovery
+- If design tokens or i18n sources are missing, state assumptions and follow existing local patterns.
+- If verification fails, fix before handoff or report the blocker.
+- If required shadcn registry access fails, use existing local components or document fallback.
+
+### Exit
+- Success: UI works across target responsive states and passes relevant checks.
+- Partial success: missing assets, backend contracts, or verification gaps are explicit.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Inspect existing frontend patterns | `READ` | Components, routes, hooks, styles |
+| Select component and state approach | `SELECT` | Server/client and shadcn workflow |
+| Implement UI code | `WRITE` | TSX, CSS, hooks, wrappers |
+| Validate form/data contracts | `VALIDATE` | Zod/forms/API schemas |
+| Call shadcn or verification tools | `CALL_TOOL` | Registry, lint, typecheck, tests |
+| Compare responsive states | `COMPARE` | Desktop/mobile behavior |
+| Report result | `NOTIFY` | Final summary |
+
+### Tools and instruments
+- React, Next.js, TypeScript, TailwindCSS v4, shadcn/ui
+- `ahooks` or `@mantine/hooks`, `es-toolkit`, `nuqs`, TanStack Query, Jotai/Zustand, TanStack React Form, `zod`
+- Angular (standalone + signals), RxJS + `rxjs/testing` (`TestScheduler` marble tests) in Angular projects
+- Lint, typecheck, tests, and browser inspection when applicable
+
+### Canonical workflow path
+Use the configured code-intelligence provider to locate files and inspect symbols
+or content. For Serena, use `find_file`, `search_for_pattern`,
+`get_symbols_overview`, and `find_symbol`. Native search is limited to the
+provider exclusions and non-code paths permitted by the project's search policy.
+
+
+For a specialized visual capability, use `resources/specialized-visual-implementation.md`.
+For affected motion, touch, component feedback, or interaction performance, use
+`../_shared/ui-interaction-quality.md`. Ordinary UI work does not preload these paths.
+
+Then run the project's frontend verification commands, typically lint, typecheck, tests, and browser/responsive checks when the UI changes.
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `CODEBASE` | Frontend routes, components, styles, hooks, tests |
+| `LOCAL_FS` | Design tokens, i18n files, resource references |
+| `PROCESS` | Build, lint, typecheck, test, browser commands |
+| `NETWORK` | Backend APIs or registry tools when required |
+
+### Preconditions
+- Target UI behavior and affected frontend area are identifiable.
+- Required design tokens, i18n, and API contracts are available or assumptions are stated.
+
+### Effects and side effects
+- Mutates frontend source, styles, tests, and possibly i18n keys.
+- May add dependencies or shadcn components only when justified by project conventions.
+- Does not edit `components/ui/*` directly.
+
+### Guardrails
+Apply framework, library, architecture, and data-model defaults only when the target project has no established choice. Scoped edits do not authorize a stack migration or unrelated infrastructure.
+1. Follow the existing React, Next.js, TypeScript, and FSD-lite architecture in the target project.
+2. Use `shadcn/ui` primitives and wrappers for UI work; treat `components/ui/*` as read-only.
+3. Keep server/client boundaries explicit: Server Components for static/layout work, Client Components for interaction and hooks.
+4. Use project sources of truth for design tokens, i18n strings, and shared utilities before adding local alternatives.
+5. Run the execution checklist before handoff and include relevant verification results.
+6. **Self-describing file names**: every new file follows the File Naming convention in `../../rules/frontend.md` §Naming Conventions — domain + role readable from the basename alone (`order-summary-card.tsx`, `use-order-polling.ts`, `cart.atoms.ts`). Grab-bag names (`utils.ts`, `helpers.ts`, `misc.ts`) and version suffixes (`*-v2`, `*-final`) are banned.
+7. **Request proxy convention**: when the target project uses Next.js 16+ with `proxy.ts`, preserve that convention. Check the installed framework version and routing before recommending a file rename. Diagnose wiring from code and tests.
+8. Use the project's Link prefetch policy; adjust specific routes only when measured behavior or the task requires it.
+9. **Angular projects follow `resources/angular-rules.md`**: standalone components + `OnPush` + signals-first, `inject()` DI, lazy routes, new control flow. **Any non-trivial RxJS pipeline MUST ship with a marble test (`TestScheduler` from `rxjs/testing`)** — a stream without a marble test fails review. React/Next.js-specific rules (shadcn workflow, `proxy.ts`, Libraries table below) do not apply in Angular projects.
+
+### Libraries
+
+React/Next.js projects only — Angular projects use the Angular-native equivalents in `resources/angular-rules.md` (signals, typed Reactive Forms, `HttpClient`/`httpResource`, RxJS with mandatory marble tests).
+
+| Category | Library |
+|----------|---------|
+| Framework | New-project default: `next@16+` (App Router) + `react@19+`; preserve existing project versions |
+| Date | `luxon` |
+| Styling | `TailwindCSS v4` + `shadcn/ui` (Base UI engine; see `resources/tech-stack.md`) |
+| Hooks | `ahooks` (default) or `@mantine/hooks` (standalone, SSR-safe; no Mantine UI required); pre-made hooks preferred; pick one per project, don't mix |
+| Utils | `es-toolkit` (first choice) |
+| Types | `type-fest` (TS type utilities not in the standard lib: `SetRequired`, `Merge`, `JsonValue`, `Promisable`, etc.; built-in `Partial`/`Pick`/`Omit` stay first choice) |
+| State (URL) | `nuqs` |
+| State (Server) | `TanStack Query`; default is `orval`-generated hooks from the OpenAPI spec (`client: react-query`); hand-write hooks only for spec-less endpoints (see `resources/tech-stack.md` §Server State) |
+| State (Client) | `Jotai` or `Zustand` (intent-based, no default; minimize use — see `resources/tech-stack.md`) |
+| Forms | `@tanstack/react-form` (v1+; pass zod schemas directly via Standard Schema; do not add the v0-only `@tanstack/zod-form-adapter` to v1 projects) + `zod` (v4) |
+| Auth | `better-auth`; client code imports only the client SDK, never server libraries or database adapters |
+| Animation | New-project default: `motion` with imports from `motion/react`; preserve an existing animation library for scoped edits |
+
+### Shadcn Workflow
+
+- **Engine default: Base UI** (`components.json` → `style: "base-*"`). Radix (`radix-*`) is a
+  reasoned fallback for existing Radix codebases only; no big-bang migration. Details in
+  `resources/tech-stack.md` §shadcn/ui Primitive Engine.
+
+1. Search: `shadcn_search_items_in_registries`
+2. Review: `shadcn_get_item_examples_from_registries`
+3. Install: `shadcn_get_add_command_for_items`
+
+### Server vs Client Components
+
+- **Server Components**: Layouts, marketing pages, SEO metadata (`generateMetadata`, `sitemap`)
+- **Client Components**: Interactive features and `useQuery` hooks
+- **Mutations**: one owner per write. Server Actions for form-shaped, revalidate-only flows; TanStack Query for cache-coupled or non-form writes (`resources/tech-stack.md` §Mutations)
+
+### UI Implementation (Shadcn/UI)
+
+- **Usage**: Prefer strict shadcn primitives (`Card`, `Sheet`, `Typography`, `Table`) over `div` or generic classes.
+- **Responsiveness**: Use `Drawer` (mobile) vs `Dialog` (desktop) via `useResponsive`.
+<!-- oma-docs:ignore-start -->
+- **Customization**: Treat `components/ui/*` as read-only. Create wrappers (e.g., `components/common/ProductButton.tsx`) or use `cva` composition. Never edit `components/ui/button.tsx` directly.
+<!-- oma-docs:ignore-end -->
+
+### Sources of Truth
+
+- **DESIGN.md** (project root): visual system source of truth; read Section 9 (Agent Prompt Guide) verbatim for component prompts when present
+- **Design Tokens**: `packages/design-tokens` (OKLCH); never hardcode colors
+- **i18n strings**: `packages/i18n`; never hardcode UI text
+- **Custom utilities**: check `es-toolkit` first; if implementing custom logic, use the project or task coverage target and risk-relevant tests
+
+### Designer Collaboration
+
+- **Sync**: Map code variables to Figma layer names
+- **UX**: Ensure key actions are visible "Above the Fold"
+
+### Stack Reference
+
+Project stack conventions live in dedicated files. **Read these before coding**; they are not optional appendix material.
+
+| File | Owns |
+|---|---|
+| `resources/tech-stack.md` | Framework versions, Next.js 16 `proxy.ts` + React Compiler conventions, Server Actions vs TanStack Query mutation policy, optional provider examples |
+| `resources/tailwind-rules.md` | Design tokens, focus states, Tailwind v4 `@theme` syntax |
+| `resources/snippets.md` | React 19 hook patterns, TanStack Query/Form, a11y card |
+| `resources/angular-rules.md` | Angular standalone/OnPush/signals conventions, RxJS marble-test policy (MANDATORY for streams) |
+
+To extend: add `resources/<name>.md` and append a row above.
+
+## References
+- `../oma-design/resources/product-interface-review.md`: recommended design review after substantial product-interface implementation.
+- Specialized visual implementation: `resources/specialized-visual-implementation.md` (requested CanvasUI GPU effect, Scroll World scene, or selected GSAP implementation)
+- Interaction quality: `../_shared/ui-interaction-quality.md` (motion, feedback, touch, interruption, or performance changes)
+- Local code tools: `../_shared/core/code-intelligence.md` (code search/navigation)
+
+- Project frontend rules (MUST load before review/implementation): `../../rules/frontend.md`
+- Execution steps (follow for the selected task): `resources/execution-protocol.md`
+- Checklist (run before handoff): `resources/checklist.md`
+- Error recovery: `resources/error-playbook.md`
+- Context loading: `../_shared/core/context-loading.md`
+- Clarification: `../_shared/core/clarification-protocol.md`
+- Context budget: `../_shared/core/context-budget.md`
+- Lessons learned: `../_shared/core/lessons-learned.md` (matching prior failure or requested retrospective)
+- Observability handoff: `../oma-observability/SKILL.md` §Integrations — Core Web Vitals, SSR→client trace propagation, INP profiling