{"_id":"@3xhaust/oh-my-design","_rev":"3-20289613f5a73eb7f7566121452b57e0","name":"@3xhaust/oh-my-design","dist-tags":{"latest":"0.18.0"},"versions":{"0.16.1":{"name":"@3xhaust/oh-my-design","version":"0.16.1","license":"MIT","_id":"@3xhaust/oh-my-design@0.16.1","maintainers":[{"name":"3xhaust","email":"me@3xhaust.dev"}],"bin":{"omd":"bin/omd.ts","oh-my-design":"bin/omd-install.ts"},"dist":{"shasum":"22451c50cedc46e09f5fa6692e5ad6642584cb44","tarball":"https://registry.npmjs.org/@3xhaust/oh-my-design/-/oh-my-design-0.16.1.tgz","fileCount":131,"integrity":"sha512-fLyynX73He1k1wkHvYTZ6fOXEIo9W+6nG2PLY4G6zkmfPCmKA9NRk0MMxjCVPCZ+3naBqmIuBOxLjcUc4ia1kA==","signatures":[{"sig":"MEQCIGPV5/OmiSSAIATmy3Vpeje2HlMG/8yZ9y/+iTuSxIIpAiBSzXlwjLKLdpvyJTv10ZNqmHW5/IhJpn2fWKaGmzRHqg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1258042},"type":"module","engines":{"node":">=22.18"},"gitHead":"7c8933fd8e3af7177a15cf7f23534a6299e92eab","scripts":{"test":"node --test 'test/*.test.ts'","build":"node adapters/build.ts","typecheck":"tsc --noEmit","release:prep":"node scripts/bump.ts"},"_npmUser":{"name":"3xhaust","email":"me@3xhaust.dev"},"_npmVersion":"11.6.1","description":"Design cognition loop for Codex and Claude Code — frame, diverge, see, reframe","directories":{},"_nodeVersion":"24.11.0","dependencies":{"yaml":"^2.6.0","smol-toml":"^1.3.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"playwright":"^1.61.1","typescript":"^7.0.2","@types/node":"^26.1.1"},"_npmOperationalInternal":{"tmp":"tmp/oh-my-design_0.16.1_1784266300371_0.7020679869777249","host":"s3://npm-registry-packages-npm-production"}},"0.17.0":{"name":"@3xhaust/oh-my-design","version":"0.17.0","license":"MIT","_id":"@3xhaust/oh-my-design@0.17.0","maintainers":[{"name":"3xhaust","email":"me@3xhaust.dev"}],"bin":{"omd":"bin/omd.mjs","oh-my-design":"bin/omd-install.mjs"},"dist":{"shasum":"8f44ef1d300b8908e7811e24a0c0561449ab0d1e","tarball":"https://registry.npmjs.org/@3xhaust/oh-my-design/-/oh-my-design-0.17.0.tgz","fileCount":301,"integrity":"sha512-/5pCeaBnSX8hvTsMQIxb9hbNF3hDLwk1C+Z+lf0BUfj+MYW1T7e1eIhHqAG4JQFnpFWyycILc/NicWFuzWPw1Q==","signatures":[{"sig":"MEYCIQCr4oP17x4i5RFQ4ln/wUCaZsrWAk29Jg7ZQDyYG0l9cwIhALq0ta/TvV0m4hb0Z8yapcYbaE6ND6Ds63lMECIu2nBr","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2794410},"type":"module","engines":{"node":">=22.18"},"gitHead":"6ed666368898409e349d3f13cdfc92590df7f891","scripts":{"test":"node --test 'test/*.test.ts'","build":"node adapters/build.ts","typecheck":"tsc --noEmit","release:prep":"node scripts/bump.ts"},"_npmUser":{"name":"3xhaust","email":"me@3xhaust.dev"},"_npmVersion":"11.6.1","description":"Design cognition loop for Codex and Claude Code — frame, diverge, see, reframe","directories":{},"_nodeVersion":"24.11.0","dependencies":{"tsx":"^4.23.1","yaml":"^2.6.0","smol-toml":"^1.3.0","playwright":"^1.61.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2","@types/node":"^26.1.1"},"_npmOperationalInternal":{"tmp":"tmp/oh-my-design_0.17.0_1784460789030_0.8643569341023289","host":"s3://npm-registry-packages-npm-production"}},"0.18.0":{"name":"@3xhaust/oh-my-design","version":"0.18.0","description":"Design cognition loop for Codex and Claude Code — frame, diverge, see, reframe","type":"module","publishConfig":{"access":"public"},"bin":{"omd":"bin/omd.mjs","oh-my-design":"bin/omd-install.mjs"},"engines":{"node":">=22.18"},"scripts":{"test":"node --test 'test/*.test.ts'","typecheck":"tsc --noEmit","build":"node adapters/build.ts","release:prep":"node scripts/bump.ts"},"dependencies":{"playwright":"^1.61.1","smol-toml":"^1.3.0","tsx":"^4.23.1","yaml":"^2.6.0"},"license":"MIT","devDependencies":{"@types/node":"^26.1.1","typescript":"^7.0.2"},"gitHead":"8e9390fa0cace1f7b834d1dcb997ab766eeb5529","_id":"@3xhaust/oh-my-design@0.18.0","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-EkJXCNPAaJfudCUoRqZnZQ3vZBmLorUAZGzXbwdpmK5XP8xaI0bHk9wy/ScVFJGFdR82nISXoOBTceA7A7t+/Q==","shasum":"15f82ea74722114b7424a2c8cd0c78b770583734","tarball":"https://registry.npmjs.org/@3xhaust/oh-my-design/-/oh-my-design-0.18.0.tgz","fileCount":306,"unpackedSize":2878589,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBasPEeOp6OC1Y8u8x+DiJkZgyeWau9UU6SY93wtJnkmAiBLxN+ftZIjAn/NL4ryvd1a0anuXZG22IXUeHmbzlVS2w=="}]},"_npmUser":{"name":"3xhaust","email":"me@3xhaust.dev"},"directories":{},"maintainers":[{"name":"3xhaust","email":"me@3xhaust.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/oh-my-design_0.18.0_1784613973317_0.35992222909935645"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-17T05:31:40.182Z","modified":"2026-07-21T06:06:13.681Z","0.16.1":"2026-07-17T05:31:40.568Z","0.17.0":"2026-07-19T11:33:09.209Z","0.18.0":"2026-07-21T06:06:13.548Z"},"license":"MIT","description":"Design cognition loop for Codex and Claude Code — frame, diverge, see, reframe","maintainers":[{"name":"3xhaust","email":"me@3xhaust.dev"}],"readme":"# Oh My Design\n\nA design process for coding agents — not a visual style. OMD makes the model earn each decision: question the brief, gather evidence, write real copy, prove typography, compose deliberately, build once, inspect the render, and reframe.\n\n[한국어](README.ko.md)\n\n## Built with OMD — in one shot\n\n[![The OMD landing page, generated by OMD](docs/omd-landing.png)](https://3x-haust.github.io/oh-my-design/)\n\nThe landing page above was generated by OMD itself from a single one-shot prompt — the visual output was not hand-tuned. It is live at **[3x-haust.github.io/oh-my-design](https://3x-haust.github.io/oh-my-design/)**, and its source is in [`example/`](example/).\n\n## What it is\n\nHere, “design like a human” means accountable judgment, not a signature look. The goal is a repeatable process; the result can be quiet, expressive, conventional, or strange. What stays constant is the chain of decisions behind it.\n\nOh My Design (OMD) keeps a coding agent from jumping straight from a request to polished UI. It asks what problem is being solved, records evidence, separates writing from layout, compares anonymous structures, and critiques the rendered output without exposing the reviewer to the builder’s rationale.\n\nThe durable loop is:\n\n```text\nbrief → evidence → copy → typography proof → composition contract → isolated structure → one production build\n      → rendered critique and interaction evidence → reframe\n```\n\nOMD runs inside **Codex** and **Claude Code**. It ships six user-facing skills, nine internal pipeline agents, a local `omd` CLI, design theory and recipe packs, and a durable project record under `.omd/`.\n\n## Requirements\n\n- **Node.js 22.18 or newer** (the CLI runs the TypeScript entrypoints directly)\n- **Claude Code, Codex, or both**, with the host config directory already present\n- A browser provider: **browser-rs v0.1.10** is preferred on its two supported platforms; **Playwright + Chromium** remains the required fallback for rendering, probing, and typography proofs (see below)\n\n## Install\n\n### npm — global CLI (recommended)\n\n```bash\nnpm install -g @3xhaust/oh-my-design\noh-my-design install    # copy skills + agents into every detected host and patch its config\noh-my-design doctor     # verify the host install\nomd doctor              # verify the runtime, Chromium, project write access, and the theory pack\n```\n\n`oh-my-design install --host claude|codex` scopes install, doctor, and uninstall to one host. `uninstall` reverses exactly what `install` did and never touches your `.omd/` directory. Host installation also attempts browser-rs afterward and reports `present`, `installed`, `unsupported`, or `failed`; a browser-rs failure does not roll back an otherwise healthy OMD/Playwright host installation.\n\n> Install the **scoped** package `@3xhaust/oh-my-design`. The unscoped `oh-my-design` on npm is an unrelated project.\n\n### Claude Code — plugin marketplace\n\n```text\n/plugin marketplace add 3x-haust/oh-my-design\n/plugin install oh-my-design@omd\n```\n\nThen open a session and run `/ultradesign`.\n\n### From source (contributors)\n\n```bash\ngit clone https://github.com/3x-haust/oh-my-design\ncd oh-my-design\nnpm install\nnode bin/omd-install.ts install    # copy skills + agents into detected hosts\nnode bin/omd.ts doctor\n```\n\n### Browser provider and Chromium (after global installation)\n\nAfter globally installing `@3xhaust/oh-my-design`, OMD prefers the `browser-rs` MCP provider for interactive reference research, user-directed region captures, and visual QA. It is a deliberately narrow v0.1.10 integration, not a claim of universal browser compatibility:\n\n| Platform | browser-rs state | Exact SHA-256 |\n| --- | --- | --- |\n| Darwin arm64 | Supported; default interactive provider when healthy | `9a5895fc2f07b1010226d30f081d678fa2edcc15dd6f24cdf10074cfe1573749` |\n| Linux x64 | Supported; default interactive provider when healthy | `792ca76e5ce0423968763556e110900a3aa65737fc6227724914aa137e972589` |\n| Any other platform | Unsupported; no browser-rs download | Use the Playwright + Chromium fallback below. |\n\nThe managed binary, when installed, is `$HOME/.local/share/oh-my-design/browser-rs/v0.1.10/browser-rs` with a verified `receipt.json`. OMD verifies the exact checksum before publishing it. Resolution is `OMD_BROWSER_RS_BIN`, then `browser-rs` on `PATH`, then that receipt-owned target. OMD never overwrites a foreign override/PATH binary or an unreceipted/tampered managed-target file, and `oh-my-design browser uninstall` removes only matching OMD-owned receipt-and-digest bytes.\n\n```bash\n# Explicit provider lifecycle. `doctor` exits 1 when the selected provider is not healthy.\noh-my-design browser install\noh-my-design browser doctor --json\n\n# After global package installation, provide your own equivalent local HTML fixture.\noh-my-design browser smoke --fixture /absolute/path/to/local-probe.html --out /tmp/omd-browser-rs-smoke.png\n\n# Preserves foreign, unreceipted, or tampered bytes rather than deleting them.\noh-my-design browser uninstall\n```\n\nFrom a source checkout, use the proven TypeScript entrypoint instead of assuming a global bin:\n\n```bash\nnode bin/omd-install.ts browser install\nnode bin/omd-install.ts browser doctor --json\nnode bin/omd-install.ts browser smoke --fixture test/fixtures/probe.html --out /tmp/omd-browser-rs-smoke.png\nnode bin/omd-install.ts browser uninstall\n```\n\nOn a supported platform, missing, unowned, or bad browser-rs is unhealthy; first repair the intended binary/ownership (or intentionally set `OMD_BROWSER_RS_BIN`), then rerun `browser doctor`. On an unsupported platform, provider health is good only when the Playwright module and Chromium fallback are both available. Existing `omd render` and `omd probe` are the deterministic Playwright fallback after browser-rs initialization or capability failure.\n\nThe installer does not install Chromium. If `omd doctor` reports Playwright unavailable or its Chromium executable missing, install what the report names, then re-check:\n\n```bash\nnpm install -g playwright\nnpx playwright install chromium\nnode bin/omd.ts doctor\n```\n\n## Chat-first LEGO reference assembly\n\nOMD treats a reference as a set of traceable bricks selected for the approved brief, not as a whole-site style to copy. The canonical sequence is:\n\n```text\nbrief blocks → fragment inventory → brick analysis → candidate assemblies\n→ selected assembly → clean-room composite → production usage ledger → final provenance report\n```\n\nThe conversation is the interface. Codex/Claude shows the candidate table and the final Korean/English provenance table directly in chat. There is no `omd-board` executable, DESIGN UI, HTML board, or PNG board. `reference-board-v1` is only an internal, validated `.omd/reference-board.json` record; the package exposes only the public `omd` and `oh-my-design` bins.\n\nBehind the conversation, an agent can capture a component, validate the evidence, render the chat-ready candidates, and bind the user’s chat choice:\n\n```bash\n# Internal agent operations; the person reviews the resulting Markdown in chat.\nomd ref add <url-or-local-page> --as <component> --selector '<css>' --blueprint --shot\nomd ref import-image ./local-fragment-input.json\nomd ref check\nomd ref candidates\nomd ref select <candidate-id>\nomd ref check\n```\n\n`omd ref candidates` emits a Korean-first Markdown table with source site/page, captured UI or image part, proposed route/component, take, avoid, and adaptation. It does not open a board. The selection is hash-bound to both validated raw evidence and a sanitized `reference-assembly-v1` projection.\n\n### Captures, clean-room composition, and final traceability\n\nA component brick is a selector-scoped blueprint plus a local PNG. For Pinterest-like galleries and similar sources, browser-rs performs the **user-directed** region capture and `omd ref import-image` imports that local PNG. The input records absolute HTTP(S) `sourcePage`, optional `sourceImage`, human-readable `captureRegion`, optional `cropBox`, `licenseStatus` (`allowed`, `restricted`, or `unknown`), rights notes, visual role/principles, and canonical provenance time. OMD does not scrape, hotlink, download remote source images, or ship their pixels.\n\nThe composer receives only the sanitized selected assembly: transferable structure/principles/geometry, never a source URL, **source selector**, provenance, screenshot, local source image, or raw pixels. The assembly intentionally retains its **target `targetSelector`** so implementation can map a selected part to its destination. `.omd/reference-composite-lineage.json` records either a hash-bound `generated` clean-room composite or an `unavailable` reason. When host image generation is available, two or three independent concept drafts may be generated concurrently and compared; no image-provider or API-key layer is added. When unavailable, use a CSS/SVG/evidence fallback. Existing motion, `prefers-reduced-motion`, and WebGL/3D gates are unchanged.\n\nDuring implementation, each selected source part receives a `used`, `rejected`, or `anti-reference` row in `.omd/reference-usage.json`. `.omd/reference-report.md` and the final chat response contain Korean and English tables with: status; source site/page; exact captured UI/image region; shipped route/component/selector; borrowed properties; explicitly non-borrowed properties; transformation; and production evidence path, selector, and verification note.\n\nSee [`docs/lego-reference-audit.md`](docs/lego-reference-audit.md) for the code-backed Korean/English capability audit, source paths, provider limitations, and verification evidence.\n\n## The human design loop\n\n`omd-ultradesign` coordinates this order:\n\n1. **Preflight** — pin the project directory, run `omd doctor`, inspect the repository, and route Figma briefs to `omd-figma`.\n2. **Frame** — interrogate the brief and record the problem, reframe hypothesis, primary task, frequent action, and costliest error with cited evidence.\n3. **Concept** — choose a generator, visual register, typography direction, and the intended memorable moment.\n4. **Research** — collect measured references across the domain, competitors, audience language, components, typography, and relevant motion.\n5. **Write copy** — a dedicated writer creates a fact-traceable copy deck before layout begins.\n6. **Review copy blind** — a fresh reviewer sees the brief, copy, fact ledger, and voice evidence, but no render, code, layout, rationale, or authorship.\n7. **Prove typography blind** — a typesetter renders layout-neutral actual-copy specimens at 1280×900 and 390×844; a fresh eye reviews them without page structure or rationale, then the typesetter revises and rerenders.\n8. **Compose deliberately** — a fresh composer defines the experience spine, one dominant focal anchor, mass/rhythm, a lawful mechanism carrier or explicit alternate, responsive recomposition, and candidate axes. `omd composition --check` verifies input freshness.\n9. **Diverge structurally** — isolated agents receive the same composition contract and render fixed desktop/mobile plus supplemental full-page continuity proofs for each candidate.\n10. **Choose blind** — a fresh selector scores eight frozen 0–4 dimensions, rejects contract violations or any dimension below 2, and never equates a form above the fold with CTA reach.\n11. **Build once** — one selected structure becomes the production implementation. The builder does not generate another candidate set.\n12. **Reflect while building** — the builder records a semantic checkpoint, re-proves type in the selected desktop/mobile containers, then records the visual checkpoint before optional motion.\n13. **See the result** — desktop and mobile renders, squint views, applicable filmstrips, deterministic checks, and declared local probes supply the review evidence.\n14. **Triage source candidates** — after production source exists, a read-only scan proposes narrow candidates. The coordinator resolves each through rendered context; candidate presence alone is not a failure.\n15. **Critique, repair, and reframe** — a squint-only glance reports hierarchy first; a separate sharp reviewer judges craft and sanitized candidates, then repairs are rendered, checked, and rescanned.\n16. **Ship** — project tests, build checks, applicable design gates, and unresolved findings are reported with their evidence.\n\nFigma files and explicit visual targets already supply structural decisions, so the loop may skip structural divergence in those routes — but it records why.\n\n## Skills\n\nSix user-facing skills. Canonical names use the `omd-` prefix; Codex shows them as `(omd) <skill>`, and the Claude marketplace flavor references them as `oh-my-design:<skill>`.\n\n| Skill | Use it for |\n| --- | --- |\n| `omd-ultradesign` | Run the complete human design loop for a page, app, dashboard, blog, landing page, or redesign. |\n| `omd-figma` | Pull a Figma file, synthesize its system, implement frames, compare responsive pairs, and report measured fidelity. |\n| `omd-scout` | Build a measured LEGO fragment inventory and chat-ready Markdown candidate/usage tables without designing or implementing. It closes consequential coverage gaps and reports uncertainty instead of filling quotas. |\n| `omd-critique` | Review an existing design without changing it; group deterministic findings by root cause and judge rendered craft. |\n| `omd-humanize` | Preserve facts while locally repairing sound discourse or reconstructing a misshapen message from verified facts, voice, and surface action. |\n| `omd-coach` | Read accumulated check history, identify recurring problems and trends, and suggest what to practise next. It does not read taste records. |\n\n## Internal pipeline agents\n\nNine agents are implementation details of the loop, not public commands. They do not pin a concrete model — each inherits the model selected for the session.\n\n| Agent | Responsibility | Write boundary |\n| --- | --- | --- |\n| `omd-framer` | Questions the brief and records an evidence-backed frame. | Read-only; records through the frame CLI. |\n| `omd-scout` | Researches measured evidence for pipeline coverage. | Read-only; records through reference CLI commands. |\n| `omd-writer` | Writes or repairs the copy deck and fact ledger. | Only `.omd/copy-deck.md`. |\n| `omd-typesetter` | Builds and revises the pre-structure actual-copy typography proof. | `.omd/type-proof.md` and `.omd/.cache/type-proof/`. |\n| `omd-composer` | Converts sanitized evidence into the fresh composition contract before divergence. | Only `.omd/composition.md`. |\n| `omd-sketch` | Produces one isolated grayscale structural candidate with real copy. | Only its cache candidate directory. |\n| `omd-hand` | Builds the selected structure and records two craft checkpoints. | Production repository and declared OMD records. |\n| `omd-glance` | Reports hierarchy from squint renders only. | No writes. |\n| `omd-eye` | Selects anonymous structures, reviews copy or typography proof blind, or critiques sharp renders. | No writes. |\n\nClaude Code can enforce declared denied tools in agent metadata. Codex agent files have no equivalent tool-restriction field, so read-only limits there are prompt contracts rather than a hard sandbox. OMD does not describe those contracts as filesystem isolation.\n\n## Evidence boundaries and artifacts\n\n| Stage | Durable output | Boundary |\n| --- | --- | --- |\n| Frame | `.omd/frame.md` | Claims need a user sentence, research line, datum, or named observation. Internal OMD instructions are not evidence. |\n| Research | `.omd/refs/*.json` | Builders receive measurements and principles, not screenshots to imitate. Scouting stops on decision/component coverage, independence, and source trust — not a universal capture count or gallery quota. |\n| Copy | `.omd/copy-deck.md` | Each shipped factual claim points to a `verified` fact ID. `fixture` facts test density only; `open` facts cannot support shipped claims. |\n| Blind copy review | review handoff | The reviewer cannot inspect renders, source, layout, frame, decisions, or authorship and does not edit the deck. The writer applies the review, then `omd copy --check` runs again. |\n| Typography proof | `.omd/type-proof.md`; specimens in `.omd/.cache/type-proof/` | Actual target-language copy proves roles, source/licence, glyph coverage, requested/computed family and weight, axes, fallback/loading, wraps/clips, and rejected alternatives at both viewports. Browser evidence does not identify the physical font used for each glyph. |\n| Composition contract | `.omd/composition.md` | A clean-room composer receives sanitized evidence and defines a focal anchor, CTA path, mechanism carrier/alternate, and responsive relationships without requiring a photo or form above the fold. Exact hashes make stale inputs fail. |\n| Structural sketches | `.omd/.cache/sketches/<id>/` | Each candidate supplies fixed 1280×900 and 390×844 acceptance renders plus full-page desktop/mobile continuity evidence. Full-page captures inform dependency/rhythm only. |\n| Blind choice | `.omd/taste/preferences.jsonl` | The selector sees anonymous renders and sanitized task context, not candidate rationale or authorship. `omd choose` stores the selected candidate and its reason as an agent choice. |\n| Production build | repository source | One builder implements one selected structure and preserves the copy deck. Separate `omd decision` entries record implementation reasons in `.omd/decisions.md`. |\n| Production evidence | `.omd/attribution.md` | The builder records the sources behind shipped tokens, motion, composition, and graphics. |\n| Craft checkpoints | `.omd/craft.jsonl` | One semantic and one visual checkpoint each record an observation and the concrete change it caused. |\n| Source-candidate triage | raw JSON in `.omd/.cache/`; reasoning in `.omd/decisions.md` | `omd slop scan` exposes controlled signals without source excerpts. `needs-render` is transitional; final untriaged and needs-render counts are both zero. |\n| Rendered review | cache renders, filmstrip, probe output | The squint reviewer sees only squint renders. The sharp reviewer receives sanitized task context plus measured outputs, never the builder’s rationale. |\n| Reframe | `.omd/frame.md` revision | `omd frame reframe` appends what the render revealed instead of erasing the original framing. |\n| Final source seal | `.omd/source-seal.json` | `omd source --seal` records final copy/type/composition and sorted production-source hashes; `--check` proves byte freshness only, not semantic fidelity. |\n\nHuman approval checkpoints are separate from craft checkpoints. Projects default to `checkpoint: none`; concept, structure, or both can be enabled in `.omd/config.json`.\n\n## Stack routing\n\nEvery builder follows the same precedence:\n\n```text\nexplicit user request\n  > existing repository stack and toolchain\n  > React + Vite + TypeScript for a truly blank greenfield\n```\n\nExisting vanilla HTML is an existing stack. An unrecognized package or toolchain is investigated and preserved, not treated as an empty repository. Plain HTML for a new greenfield project is used only when the user explicitly asks for it. Greenfield scaffold dependencies are allowed; existing projects should not receive unnecessary ones.\n\n## Verification stack\n\nOMD combines deterministic checks with rendered review.\n\n| Layer | Commands and evidence |\n| --- | --- |\n| Contracts | `omd copy --check` validates deck structure and fact references. `omd composition --check` validates composition sections and input freshness. `omd source --seal/--check` validates final approved-input/source bytes without claiming semantic fidelity. `omd design --check` validates design-contract coverage. |\n| Typography proof | Layout-neutral desktop/mobile specimens run before sketches; selected-container reproof runs after semantic structure and before the visual checkpoint. Copy, font/file, weight/axis, or container-width changes invalidate the proof. |\n| Render evidence | `omd render` captures the exact viewport by default; `--full-page` is supplementary continuity evidence, `--squint` isolates hierarchy with grayscale and blur, `--filmstrip` captures load-time frames. |\n| Interaction | `omd probe` executes only a declared, safe local plan and reports expectation or tab-order failures. |\n| Source candidates | `omd slop scan [root] [--json]` reads supported production source without writing it. Candidates require contextual triage; they are not `omd check` warnings, scores, or authorship claims. |\n| Design lint | `omd check` evaluates `system`, `a11y`, `slop`, `motion`, and `ux` conditions. Contrast and hit-area rules are errors; slop and other quality-floor rules are warnings where authored that way. Any finding exits 1, so it is usable in CI. |\n| Site consistency | `omd check --site <dir>` or multi-page positional checks report cross-page ladder and token drift. |\n| Reference distance | `omd ref distance <page>` compares measured invariants against saved references and reports how close the build is, as an advisory fidelity signal — it never blocks shipping. |\n| Figma fidelity | `omd figma pull`, `system`, and `diff` connect a Figma snapshot to a measured implementation report. Requires `export FIGMA_TOKEN=…`; `omd doctor` treats a missing token as optional. |\n| Visual target | `omd target set <image-path-or-url> --as <name>` and `omd target diff` run a bounded image comparison against a registered PNG target. A URL must be a direct HTTP(S) image URL. |\n| Performance | `omd lighthouse <lighthouse-report.json>` gates a Lighthouse JSON report against a performance budget (default: performance ≥ 90 and Core Web Vitals within Google's \"good\" thresholds). You run Lighthouse (`npx lighthouse <url> --output=json`); OMD gates its report and exits non-zero on a breach. |\n\nSlop findings are a quality floor and warnings; they do not prove a design was generated by AI. A written overrule records intent but does not suppress a finding or change command status. Rendered critique remains necessary — a rule engine cannot safely judge optical balance, composition rhythm, typography craft, or whether the memorable moment belongs to the concept.\n\n## Interaction applicability\n\nThe copy deck declares exactly one interaction scope.\n\n| Scope | Required evidence |\n| --- | --- |\n| `stateful` | Primary and recovery copy, `.omd/probes/primary.json`, and `.omd/probes/recovery.json`. Both probes run. |\n| `navigation-only` | Primary copy and the primary probe. Recovery copy and recovery probe are `N/A` with concrete reasons. |\n| `static` | Primary copy. Recovery copy and both probes are `N/A` with concrete reasons. |\n\nLoading, empty, error, success, disabled, offline, and recovery states are designed only when the surface can reach them — the harness does not add fake states to satisfy a checklist. Probe plans use declared click, fill, and keypress steps with explicit expectations, are limited to local files and localhost/loopback URLs, and reject authenticated, remote, destructive, or undeclared actions. OMD never discovers controls and clicks them automatically.\n\n## Project state\n\nDurable, reviewable records live directly under `.omd/`:\n\n- `frame.md`, `copy-deck.md`, `type-proof.md`, `composition.md`, `source-seal.json`, `design.md`, `decisions.md`\n- `attribution.md`, `motion-spec.md`, `craft.jsonl`, `config.json`\n- `refs/*.json`, `reference-board.json`, `reference-selection.json`, `reference-composite-lineage.json`, `reference-usage.json`, `reference-report.md`, declared `probes/*.json`, `taste/preferences.jsonl`, and `history.jsonl`\n\nGenerated IR, renders, filmstrips, sketch candidates, probe results, and scratch output live under `.omd/.cache/`; deleting the cache should not erase design intent. `oh-my-design uninstall` removes installed OMD files and config changes while preserving the project’s `.omd/` directory.\n\n## CLI reference\n\nA compact map of `node bin/omd.ts --help`:\n\n```text\nomd ir <page> [-o file]\nomd render <page> -o shot.png [--viewport WxH] [--full-page] [--squint] [--filmstrip]\nomd probe <page> [--plan path] [--json] [--out path]\nomd check [<page>|--ir file] [--json] [--category slop] [--no-log]\nomd check --site <dir>\nomd check <page1> <page2> ...\nomd slop scan [root] [--json]\nomd coach\nomd composition --check [--json]\nomd source --seal [root]  |  omd source --check [root] [--json]\n\nomd frame show\nomd frame set --problem P --reframe R --why EVIDENCE [--task T --frequent-action A --costliest-error E]\nomd frame reframe --to \"...\" --because \"...\"\nomd frame generator --set \"metaphor\"\nomd choose c1 c2 --chose c2 --why \"...\"\nomd decision \"what\" --why \"why\"\nomd taste record \"subject\" --kind selection|praise|rejection|overrule --evidence \"verbatim\" --from-user\nomd taste profile [--all]\nomd config set checkpoint none|concept|structure|both  |  omd config show\nomd craft checkpoint semantic|visual --render path --observed \"...\" --changed \"...\"\nomd craft status [--json]\n\nomd ref add <url|file> --as <component> [--selector \"css\"] [--image] [--blueprint]\nomd ref list  |  omd ref distance <page>\nomd ref principles <source> --as <component> --add \"...\"\nomd ref show <source> --as <component>\nomd ref check [manifest] [--json]\nomd ref import-image <input.json> [--json]\nomd ref candidates [manifest]                 # chat-ready Korean-first Markdown; no board UI\nomd ref select <candidate-id> [--json]\n\nomd design  |  omd design --check\nomd copy --check [--json]\nomd pack dir | list | <relpath>\nomd doctor\n\nomd figma pull <file-url>  |  omd figma system  |  omd figma diff <frame-id> <page-or-url>\nomd target set <image-path-or-url> --as <name>  |  omd target list  |  omd target diff <page> [--target <name>] [--viewport WxH] [--threshold N] [--json]\n```\n\n## Architecture and contributing\n\nPrompt source of truth:\n\n- `src/agents/*.agent.yaml`\n- `src/skills/omd-*/SKILL.md`\n\nGenerated outputs — **do not edit directly**; `npm run build` regenerates them for direct hosts and plugin packaging:\n\n- `agents/`, `skills/`, `dist/`\n\nEdited directly: `core/`, `bin/`, `adapters/`, `test/`, `evals/`, `scripts/`, `README.md`, `README.ko.md`, and the theory and recipe packs under `core/`.\n\nBefore submitting a change:\n\n```bash\nnpm test\nnpx tsc --noEmit\nnpm run build\n```\n\nNew linter rules must remain narrow, include positive and negative tests, and always use warning severity.\n\n## Limits and trust\n\n- The prompts define a disciplined workflow; they do not guarantee strong design without real project evidence, usable copy, rendered inspection, and project-specific validation.\n- Probes are for local, non-authenticated, non-destructive paths — not a general browser automation layer.\n- Reference distance, lint, and image diff are measurements. They inform judgment rather than replace it.\n- Plugin/marketplace manifests are shipped artifacts; the from-source direct installer is the path covered by install-to-doctor regression tests.\n\nLicensed under the [MIT License](LICENSE).\n","readmeFilename":"README.md"}