oh-my-opencode 4.19.2 → 4.19.3

package/packages/omo-codex/plugin/shared/test/config-loader.test.ts

@@ -1,9 +1,14 @@
 import { afterEach, describe, expect, it } from "bun:test"
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
-import { join } from "node:path"
+import { join, posix } from "node:path"
 
-import { getCodexOmoConfig } from "../src/config-loader.ts"
+import { parse } from "jsonc-parser"
+
+import { runMigrations, type MigrationBoundary } from "../../../../omo-config-core/src/index.ts"
+import { createLegacyConfigMigrationPlans } from "../../../../omo-opencode/src/config-migration/index.ts"
+
+import { getCodexOmoConfig, runCodexStartupMigration } from "../src/config-loader.ts"
 
 const temporaryDirectories: string[] = []
 
@@ -14,11 +19,51 @@ function createTemporaryDirectory(prefix: string): string {
 }
 
 function writeOmoConfig(homeDir: string, content: string): void {
+	const configDir = join(homeDir, ".omo")
+	mkdirSync(configDir, { recursive: true })
+	writeFileSync(join(configDir, "omo.jsonc"), content)
+}
+
+function writeLegacyOmoConfig(homeDir: string, content: string): void {
 	const configDir = join(homeDir, ".omo")
 	mkdirSync(configDir, { recursive: true })
 	writeFileSync(join(configDir, "config.jsonc"), content)
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function readOmoJson(homeDir: string): Record<string, unknown> {
+	const value: unknown = parse(readFileSync(join(homeDir, ".omo", "omo.jsonc"), "utf-8"))
+	if (!isRecord(value)) throw new Error("Expected an omo JSONC object")
+	return value
+}
+
+function writeOpenCodeConfig(homeDir: string): void {
+	const configDir = join(homeDir, ".config", "opencode")
+	mkdirSync(configDir, { recursive: true })
+	writeFileSync(join(configDir, "oh-my-openagent.jsonc"), '{"agents":{"finder":{"model":"provider/finder"}}}')
+}
+
+function runOpenCodeMigration(homeDir: string, cwd: string, onBoundary?: (boundary: MigrationBoundary) => void): void {
+	runMigrations({
+		discover: () => createLegacyConfigMigrationPlans({
+			cwd,
+			environment: { HOME: homeDir, XDG_CONFIG_HOME: join(homeDir, ".config") },
+			homeDir,
+			pathOperations: posix,
+		}),
+		env: { HOME: homeDir },
+		...(onBoundary === undefined ? {} : { onBoundary }),
+	})
+}
+
+function migrationIds(homeDir: string): readonly string[] {
+	const migrations = readOmoJson(homeDir)["_migrations"]
+	return Array.isArray(migrations) ? migrations.filter((entry): entry is string => typeof entry === "string") : []
+}
+
 afterEach(() => {
 	for (const directory of temporaryDirectories.splice(0)) {
 		rmSync(directory, { recursive: true, force: true })
@@ -86,6 +131,20 @@ describe("getCodexOmoConfig", () => {
 		expect(result.codegraph?.excluded_roots).toEqual(["/tmp/omo-research", "/private/tmp/omo-research"])
 	})
 
+	it("#given codex SOT sets the SessionStart cooldown #when loading config #then the configured base interval is returned", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-shared-cooldown-home-")
+		const cwd = createTemporaryDirectory("omo-codex-shared-cooldown-project-")
+		writeOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { session_start_cooldown_ms: 900_000 } } }))
+
+		// when
+		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
+
+		// then
+		expect(result.codegraph?.session_start_cooldown_ms).toBe(900_000)
+		expect(result.warnings).toEqual([])
+	})
+
 	it("#given no codegraph.daemon key #when loading config #then daemon defaults to on", () => {
 		// given
 		const homeDir = createTemporaryDirectory("omo-codex-shared-daemon-default-home-")
@@ -125,24 +184,24 @@ describe("getCodexOmoConfig", () => {
 
 		// then
 		expect(result.codegraph?.daemon).toBe(true)
-		expect(result.warnings).toContain("config.[codex].codegraph.daemon must be a boolean")
+		expect(result.warnings).toContain(`Invalid omo config at ${join(homeDir, ".omo", "omo.jsonc")}: [codex].codegraph.daemon`)
 	})
 
 	it("#given legacy env override and SOT value #when loading config #then env wins over the SOT", () => {
 		// given
 		const homeDir = createTemporaryDirectory("omo-codex-shared-env-")
 		const cwd = createTemporaryDirectory("omo-codex-project-env-")
-		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: true } }))
+		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: false } }))
 
 		// when
 		const result = getCodexOmoConfig({
 			cwd,
 			homeDir,
-			env: { CODEX_CODEGRAPH_ENABLED: "0" },
+			env: { CODEX_CODEGRAPH_ENABLED: "1" },
 		})
 
 		// then
-		expect(result.codegraph?.enabled).toBe(false)
+		expect(result.codegraph?.enabled).toBe(true)
 	})
 
 	it("#given no SOT files #when loading config #then returns built-in defaults and missing global source", () => {
@@ -163,8 +222,8 @@ describe("getCodexOmoConfig", () => {
 		expect(result.sources).toContainEqual({
 			exists: false,
 			loaded: false,
-			path: join(homeDir, ".omo", "config.jsonc"),
-			scope: "global",
+			path: join(homeDir, ".omo", "omo.jsonc"),
+			scope: "user",
 		})
 	})
 
@@ -180,4 +239,122 @@ describe("getCodexOmoConfig", () => {
 		// then
 		expect(result.warnings).toContain("codegraph.watch_debounce_ms is not supported for harness codex")
 	})
+
+	it("#given only legacy config.jsonc #when codex starts #then migrates once with a backup before loading the unified codex view", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-legacy-upgrade-")
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		const legacyPath = join(homeDir, ".omo", "config.jsonc")
+
+		// when
+		const first = getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
+		const backupDirectories = readdirSync(join(homeDir, ".omo")).filter((entry) => entry.startsWith("migration-backup-"))
+		const second = getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
+
+		// then
+		expect(first.codegraph?.daemon).toBe(false)
+		expect(first.warnings.some((warning) => warning.startsWith("omo-codex: migrated legacy configuration from ")
+			&& warning.endsWith("/.omo/config.jsonc"))).toBe(true)
+		expect(readOmoJson(homeDir)["_migrations"]).toEqual(["2026-07-codex-config-jsonc"])
+		expect(existsSync(legacyPath)).toBe(false)
+		expect(backupDirectories).toHaveLength(1)
+		expect(existsSync(join(homeDir, ".omo", backupDirectories[0] ?? "", ".omo", "config.jsonc"))).toBe(true)
+		expect(second.warnings.some((warning) => warning.startsWith("omo-codex: migrated legacy configuration from "))).toBe(false)
+		expect(readdirSync(join(homeDir, ".omo")).filter((entry) => entry.startsWith("migration-backup-"))).toEqual(backupDirectories)
+	})
+
+	it("#given a legacy migration conflict #when codex starts #then exposes the migration summary and conflict through loader warnings", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-legacy-conflict-")
+		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: true } }))
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: false } }))
+
+		// when
+		const result = getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
+
+		// then
+		expect(result.warnings.some((warning) => warning.startsWith("omo-codex: migrated legacy configuration from ")
+			&& warning.endsWith("/.omo/config.jsonc"))).toBe(true)
+		expect(result.warnings).toContain("omo-codex: configuration migration: skipped: codegraph.enabled legacy=false kept=true")
+	})
+
+	it("#given overlapping [omo] and [senpi] blocks in legacy config #when Codex migrates #then the transform conflict is reported", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-legacy-senpi-conflict-")
+		writeLegacyOmoConfig(homeDir, JSON.stringify({
+			"[omo]": { agents: { oracle: { model: "legacy" } } },
+			"[senpi]": { agents: { oracle: { model: "current" } } },
+		}))
+
+		// when
+		const result = runCodexStartupMigration({ cwd: homeDir, environment: { HOME: homeDir }, homeDir })
+
+		// then
+		expect(result.results[0]?.diagnostics).toContain("conflict: [senpi] legacy [omo] kept [senpi]")
+	})
+
+	it("#given a malformed migration journal #when codex starts #then exposes the recovery failure through loader warnings", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-recovery-warning-")
+		const migrationDir = join(homeDir, ".omo")
+		mkdirSync(migrationDir, { recursive: true })
+		writeFileSync(join(migrationDir, ".migration-journal.json"), "not-json")
+
+		// when
+		const result = getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
+
+		// then
+		expect(result.warnings.some((warning) => warning.startsWith("omo-codex: configuration migration: "))).toBe(true)
+	})
+
+	it("#given codex starts before opencode #when both legacy source groups exist #then each distinct migration id is applied once", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-order-codex-first-")
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		writeOpenCodeConfig(homeDir)
+		const openCodeSource = join(homeDir, ".config", "opencode", "oh-my-openagent.jsonc")
+
+		// when
+		getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
+		const remainsAfterCodexStartup = existsSync(openCodeSource)
+		runOpenCodeMigration(homeDir, homeDir)
+
+		// then
+		expect(remainsAfterCodexStartup).toBe(true)
+		expect(existsSync(openCodeSource)).toBe(false)
+		expect(migrationIds(homeDir)).toEqual(["2026-07-codex-config-jsonc", "2026-07-opencode-config-unification"])
+	})
+
+	it("#given opencode starts before codex #when both legacy source groups exist #then each distinct migration id is applied once", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-order-opencode-first-")
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		writeOpenCodeConfig(homeDir)
+
+		// when
+		runOpenCodeMigration(homeDir, homeDir)
+		getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
+
+		// then
+		expect(migrationIds(homeDir)).toEqual(["2026-07-opencode-config-unification", "2026-07-codex-config-jsonc"])
+	})
+
+	it("#given concurrent codex and opencode starts #when opencode owns the shared lock #then both migration ids are applied exactly once", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-order-concurrent-")
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		writeOpenCodeConfig(homeDir)
+		let codexResult: ReturnType<typeof runCodexStartupMigration> | undefined
+
+		// when
+		runOpenCodeMigration(homeDir, homeDir, (boundary) => {
+			if (boundary !== "journal-written" || codexResult !== undefined) return
+			codexResult = runCodexStartupMigration({ cwd: homeDir, homeDir })
+		})
+
+		// then
+		if (codexResult === undefined) throw new Error("Expected concurrent Codex migration attempt")
+		expect(codexResult.error).toBe("Configuration migration is already running")
+		expect(migrationIds(homeDir)).toEqual(["2026-07-opencode-config-unification", "2026-07-codex-config-jsonc"])
+	})
 })

package/packages/omo-codex/plugin/skills/frontend/ATTRIBUTION.md

@@ -210,6 +210,13 @@ no Lazyweb source, documentation text, or screenshot content is vendored. Lazywe
 remain the property of their owner, and the guide grants no license to ship, trace, or
 commit reference screenshots harvested through it.
 
+`frontend/references/design/interaction-skill.md` is a project-original, curl-only
+operating guide for consulting the beui.dev animated-component registry during interaction
+and motion work, written from live endpoint verification; no beui.dev source code,
+documentation text, or component implementations are vendored. beui.dev names remain the
+property of their owner, and the guide instructs reading component source for mechanism
+extraction only, not vendoring it into references or projects.
+
 `frontend/references/design/clone-from-url.md` is a project-original runtime-extraction
 workflow guide. Its browser + `getComputedStyle` clone approach follows the same
 MIT-licensed `JCodesMore/ai-website-cloner-template` clone-website workflow that `aside.md`

package/packages/omo-codex/plugin/skills/frontend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend
-description: "MUST USE for frontend/web UI/UX/visual work: building, styling, redesigning pages/components, React setup, performance audits, visual QA, taste, and polish. Routes four rulesets: design taste router and brand references; perfection for Playwright/Chromium Lighthouse/Core Web Vitals; ui-ux-db palettes/fonts/guidelines; designpowers personas/accessibility/critique/handoff; plus curl-only lazyweb real-app-screen research for design direction. Triggers: frontend, UI, UX, design, redesign, styling, layout, animation, motion, premium, luxury, minimal, brutalist, Awwwards, DESIGN.md, mockup, React, Lighthouse, accessibility, WCAG, Core Web Vitals, looks generic, make it pretty, like X brand, lazyweb, design research."
+description: "MUST USE for frontend/web UI/UX/visual work: building, styling, redesigning pages/components, React setup, performance audits, visual QA, taste, and polish. Routes four rulesets: design taste router and brand references; perfection for Playwright/Chromium Lighthouse/Core Web Vitals; ui-ux-db palettes/fonts/guidelines; designpowers personas/accessibility/critique/handoff; plus curl-only lazyweb real-app-screen research and the beui.dev interaction catalog. Triggers: frontend, UI, UX, design, redesign, styling, layout, animation, motion, interaction, micro-interaction, make it feel alive, premium, luxury, minimal, brutalist, Awwwards, DESIGN.md, mockup, React, Lighthouse, accessibility, WCAG, Core Web Vitals, looks generic, make it pretty, like X brand, lazyweb, design research."
 ---
 
 # Frontend
@@ -14,6 +14,7 @@ This file is a router, not a rulebook. The rules live in four rulesets under `re
 | Request involves… | Read |
 |---|---|
 | ANY UI implementation, styling, redesign, mockup, or visual decision | `references/design/README.md` FIRST. It enforces two mandatory gates — the Design System Gate (a `DESIGN.md` must exist before any component is written) and the React Dev Tooling Gate (react-grab / react-scan / react-doctor installed by default) — then routes to the taste and brand references below. |
+| Interaction or motion work — micro-interactions, animated components, transitions, gestures, hover/press/state feedback, "make it feel alive" | ALSO `references/design/interaction-skill.md`. The beui.dev catalog is the mandatory interaction reference: find the nearest pattern, read its real source through the file's curl recipe, and adapt the mechanism to `DESIGN.md` motion tokens. It stacks on the routed style skill — never replaces it. |
 | Writing or modifying frontend code, OR auditing performance / SEO / accessibility / quality | ALSO `references/perfection/README.md`. Lighthouse 100 in every category, measured on real Playwright Chromium (never the `lighthouse` CLI), achieved through architecture — never by dropping animations or hiding content. |
 | Looking up a concrete style, color palette, font pairing, chart type, landing-page structure, or UX guideline — or generating a project design system from keywords | `references/ui-ux-db/README.md`. A searchable CSV database with a CLI; a lookup tool, not a posture. Load on demand; `design` stays the source of truth for taste and the `DESIGN.md` contract. |
 | ANY implementation or redesign that creates or updates `DESIGN.md` — plus explicit operating-layer asks (personas, critique, debt, handoff, synthetic user testing) | `references/designpowers/README.md` + `references/designpowers/lane-c-review.md`. An internal frontend ruleset, not a separate skill: lane-c is the Phase Final flatness/critique reviewer, and its accessibility-constraints and accepted-debt language fills the required `DESIGN.md` sections. Load other lanes only when their phase applies. |
@@ -61,6 +62,7 @@ The reference library has one architecture file, 12 taste skills (Layer A — *h
 | `image-to-code-skill.md` | "Generate the design first, then code it." Pair with one imagegen file below. |
 | `output-skill.md` | Stacks on any style skill when output is incomplete — placeholders, `// TODO`, half-done components. |
 | `stitch-skill.md` | Stacks on any style skill for Google Stitch compatibility or a `DESIGN.md` doc export. A complete worked export ships as `stitch-design-example.md`. |
+| `interaction-skill.md` | Stacks on any style skill when work adds or changes interaction or motion. beui.dev-anchored: read the mapped component's source before designing an interaction; reduced motion always. |
 | `imagegen-frontend-web.md` / `imagegen-frontend-mobile.md` / `imagegen-brandkit.md` | Image-only output (mockup, app-screen concepts, brand board). These NEVER write code — switch to `image-to-code-skill.md` if code is wanted. |
 
 ### Layer B — brand design systems (orthogonal to Layer A; stack freely)
@@ -113,6 +115,7 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
 | "Linear-style landing page" | `design/README.md` + `design/linear.app.md` + `design/taste-skill.md` + `perfection/README.md` |
 | "Premium SaaS hero like Stripe" | `design/README.md` + `design/stripe.md` + `design/soft-skill.md` + `perfection/README.md` |
 | "Improve this existing dashboard" | `design/README.md` + `design/redesign-skill.md` + `perfection/README.md` |
+| "Add micro-interactions" / "animate this" / "make it feel alive" / "polish the interactions" | `design/README.md` + `design/interaction-skill.md` on top of the current style skill + `perfection/README.md` |
 | "Build this screenshot / Imagen mock / Stitch output exactly" | `design/README.md` + `design/image-to-code-skill.md` + `perfection/README.md` + `/visual-qa` reference-fidelity mode |
 | "Audit my site" / "make this page faster" | `perfection/README.md` (+ `perfection/react-perf-tooling.md` if React) |
 | "Mockup image of a fintech app" — no code | `design/imagegen-frontend-mobile.md` (+ a Layer B brand if named) |

package/packages/omo-codex/plugin/skills/frontend/references/design/README.md

@@ -175,6 +175,12 @@ Triggers: dashboard, settings, mail/inbox, list-detail, command surface, split p
 
 **Action:** Add `layout-skill.md` on top of whatever style skill you selected in Steps 1-2. It carries scroll-ownership doctrine, the two silently-failing CSS contracts (`min-block-size: 0` scroll shells, `minmax(min(…),100%)` grids), the named-primitive vocabulary, container-vs-viewport routing, and the content-stress matrix. It adds no visual direction — the style skill still owns taste. Skip it for pure scroll-the-document marketing pages, where `taste-skill` layout guidance already fits.
 
+### Step 9 — Does the work add or change interaction or motion?
+
+Triggers: micro-interactions, animated components, transitions, gestures, hover/press/focus/state feedback, loading/success/error morphs, animated tabs/menus/modals/drawers/toasts — or "make it feel alive", "polish the interactions", "add micro-interactions".
+
+**Action:** Add `interaction-skill.md` on top of whatever style skill you selected. It anchors interaction design to the beui.dev catalog: find the nearest pattern, read its real source through the file's curl recipe, extract the mechanism (spring config, layout strategy, enter/exit order, reduced-motion path), and adapt the values to `DESIGN.md`. It owns interaction mechanics only — no visual direction — so it stacks cleanly, like `layout-skill.md`.
+
 ## Stacking rules (read this once, internalize it)
 
 1. **At most one Layer A *style* skill at a time.** A layout cannot be both `minimalist-skill` and `brutalist-skill` simultaneously — they encode opposite spacing and typography philosophies. Pick one.
@@ -184,6 +190,7 @@ Triggers: dashboard, settings, mail/inbox, list-detail, command surface, split p
 5. **`image-to-code-skill.md` pairs with one imagegen skill** for the full flow.
 6. **Layer B (brand DESIGN.md) is orthogonal to Layer A.** You can pair any Layer A skill with any Layer B brand. Use Layer B as the source of color/type/component tokens; let Layer A drive the execution discipline.
 7. **`layout-skill.md` stacks on top of any style skill** for app-shell / dashboard / split-pane work. It owns spatial structure and scroll ownership only — no visual direction — so it never conflicts with the style skill you picked.
+8. **`interaction-skill.md` stacks on top of any style skill** for interaction/motion work. It owns interaction mechanics — springs, layout morphs, enter/exit orchestration, reduced motion — and no visual direction, so it never conflicts with the style skill either.
 
 ## Anti-patterns — do not do these
 
@@ -227,6 +234,7 @@ Once references are loaded, before writing any UI code:
 | "Also output a DESIGN.md doc" | Add `stitch-skill.md` to current stack |
 | "Build a dashboard / settings / inbox / app shell" | one style skill (usually `taste-skill.md`) + `layout-skill.md` |
 | "Panel won't scroll / footer pushed off-screen / mobile overflow" | Add `layout-skill.md` to current stack |
+| "Add micro-interactions / animate this / make it feel alive" | Add `interaction-skill.md` to current stack |
 
 ## Phase Final — Design QA (MANDATORY, runs after implementation)
 

package/packages/omo-codex/plugin/skills/frontend/references/design/_INDEX.md

@@ -5,7 +5,7 @@ All reference files live flat in this directory. Three layers:
 - **Layer A — taste skills** (12 files): how to execute. Discipline, motion, spacing, anti-slop, output completeness.
 - **Layer B — design systems** (70 files): what it should look like. Brand-specific color/type/component tokens.
 
-**Phase 0 runs first** (check/create `DESIGN.md`), then most non-trivial tasks load **one Layer A + one Layer B** together. See the routing flow in the sibling `README.md`.
+**Phase 0 runs first** (check/create `DESIGN.md`), then most non-trivial tasks load **one Layer A + one Layer B** together. See the routing flow in the sibling `README.md`. Specialized phases (interaction and motion, app-shell layout, URL clones, real-product screen research) load the matching project-original operating reference — see the final section of this index.
 
 ---
 
@@ -52,6 +52,19 @@ From [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill).
 
 ---
 
+## Operating references — interaction, layout, and research workflows (project-original)
+
+Beyond the 12-file Layer A library, the design ruleset carries project-original operating references for specialized phases. They stack on the routed Layer A + Layer B pair; they never replace a style skill, and they are not counted in the library totals above.
+
+| File | Purpose | Load when |
+|---|---|---|
+| `interaction-skill.md` | Interaction mechanics anchored to the beui.dev catalog: find the nearest pattern, read its real source through the curl recipe, extract the mechanism (spring config, layout strategy, enter/exit order, reduced-motion path), and adapt it to `DESIGN.md` motion tokens. | Any work adding or changing interaction or motion — micro-interactions, animated components, transitions, gestures, hover/press/state feedback, loading/success/error morphs, "make it feel alive". |
+| `layout-skill.md` | Layout mechanics: scroll ownership, the two silent CSS contracts, named primitives, content-stress matrix. Zero visual direction. | App shells, dashboards, split panes, or a layout that breaks under real content. |
+| `lazyweb.md` | Curl-only real-product screen research for design direction. | Greenfield design research lanes. |
+| `clone-from-url.md` | Runtime extraction workflow (browser + `getComputedStyle`) for cloning a named site. | A live site or URL is the visual reference. |
+
+---
+
 ## Layer B — Design Systems (70)
 
 Most Layer B files are materialized from [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), based on [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/overview/). Project-original entries such as `aside.md` are listed here only when `ATTRIBUTION.md` and `frontend-refs-manifest.mjs` mark them as original. Each file captures one website's complete visual language: color palette, typography, components, layout principles, depth, do/don't, responsive behavior, and an agent prompt guide.

package/packages/omo-codex/plugin/skills/frontend/references/design/interaction-skill.md

@@ -0,0 +1,144 @@
+---
+name: interaction-skill
+description: "Layer A interaction-mechanics reference anchored to the beui.dev catalog. Stacks on any style skill whenever work adds or changes motion or interaction — micro-interactions, animated components, transitions, gestures, hover/press/state feedback, loading/success/error morphs, 'make it feel alive'. Mandates reading the mapped beui.dev component source before designing an interaction; owns interaction mechanics and reduced-motion discipline; owns zero visual taste. Load it alongside a style skill; it does not replace one."
+---
+
+# Interaction Mechanics — beui.dev-Anchored
+
+Style skills decide how a surface looks. This file decides how it *moves and responds* — spring physics, layout morphs, enter/exit orchestration, gesture feel, and reduced-motion discipline. It stacks on top of any Layer A style skill and any Layer B brand, exactly like `layout-skill.md`, and adds ZERO visual direction: color, type, and material still come from the style skill and `DESIGN.md`.
+
+Load this whenever the deliverable includes interaction feel: micro-interactions, animated components, transitions, hover/press/focus/state feedback, gestures, loading/success/error morphs, animated tabs/menus/modals/drawers/toasts — or the user says "make it feel alive", "polish the interactions", "add micro-interactions".
+
+## 1. The reference contract — never design an interaction from memory
+
+[beui.dev](https://beui.dev) is the interaction benchmark: free, open-source animated React components (Motion + Tailwind CSS) where every component ships reduced-motion support and the full TypeScript source is one `curl` away. Improvised interaction design produces slop motion the same way freestyled styling produces generic SaaS slop, and the fix is the same: consult the reference before designing.
+
+The contract, in order:
+
+1. **Find the nearest pattern** in the catalog (section 3). The live catalog is `https://beui.dev/llms.txt`; refresh from it when a pattern seems missing from the tables below.
+2. **Read its real source** through the recipe (section 2). Never guess spring values, exit orchestration, or gesture thresholds from a preview description.
+3. **Extract the mechanism**, not the pixels: the spring config, the layout strategy (`layoutId` shared layout vs height morph vs clip-path), what animates in what order on enter/exit, where blur crossfades sit, and what the reduced-motion path swaps to.
+4. **Adapt to the project.** Concrete durations, easings, and spring params come from the project `DESIGN.md` Motion & Interaction section. Where beui.dev and `DESIGN.md` disagree, `DESIGN.md` wins. A value that is not in `DESIGN.md` gets added there first, then used.
+5. **No matching pattern?** Compose from the nearest two, or state explicitly that the interaction is novel and record its mechanism in `DESIGN.md` before building it.
+
+## 2. Consultation recipe (curl-only, verified 2026-07)
+
+All endpoints are public, no auth, no browser:
+
+```bash
+curl -s https://beui.dev/llms.txt                          # full catalog: every component + one-line feel
+curl -s https://beui.dev/r                                 # registry index (JSON): slugs, categories, endpoints
+curl -s https://beui.dev/r/{slug}                          # component detail (JSON): files, dependencies, dates
+curl -s https://beui.dev/r/{slug}/raw                      # component source (TypeScript) — the thing to read
+curl -s https://beui.dev/components/{category}/{slug}.md   # component doc page as markdown
+```
+
+Categories are `motion` (primitives) and `blocks` (composed patterns). When the user wants the component itself rather than the mechanism, a shadcn-style item registry exists at `https://beui.dev/r/{slug}.json`. Read source to learn; do not vendor beui.dev files into reference docs, and do not paste whole components into a project when only the mechanism is needed.
+
+## 3. Catalog — pattern routing map
+
+### Buttons, state feedback, and progress
+
+| Pattern (slug) | Mechanism | Reach for it when |
+|---|---|---|
+| `button` | Spring press; StatefulButton idle → loading → success/error with blur-swap slots and morphing width; MagneticButton cursor pull | Any submit/CTA that has async states — never leave a button state-less |
+| `action-swap` | Text/icon swap with blur motion | Copy → check, send → stop, any label that changes meaning in place |
+| `expanding-arrow-button` | Expanding, hold-to-confirm, and slide CTA interactions | Expressive marketing CTAs, destructive hold-to-confirm |
+| `animated-badge` | Animated state icons, pulse feedback | Connection/status dots, live activity indicators |
+| `loader` | 17 variants incl. terminal-ascii; reduced motion swaps every transform for an opacity pulse | Any loading state; copy its reduced-motion contract even when hand-rolling |
+| `otp-input` | Gliding focus ring, per-slot digit roll, error shake, success check draw | Code entry, verification flows |
+| `file-upload` | Progress rows, retry/remove, reduced-motion-safe state changes | Upload queues, long-running item lists |
+| `feedback-widget` | Trigger morphs into a popup with sending/success/retry states | Corner feedback affordances, inline report flows |
+
+### Selection and form controls
+
+| Pattern (slug) | Mechanism | Reach for it when |
+|---|---|---|
+| `switch` | Spring-driven thumb with press feedback | Boolean toggles |
+| `checkbox` | Draw-on checkmark, indeterminate support | Multi-select, tree selection |
+| `radio` | Gliding `layoutId` indicator dot | Single-select groups |
+| `input` | Label, icons, error shake, success check draw | Validated text entry |
+| `select` | Panel bouncily unfolds from the trigger; Morph variant grows the trigger into the panel | Dropdown selection with spatial continuity |
+| `range-slider` | Bouncy vertical-bar thumb gliding between snapped steps | Stepped value entry |
+| `wheel-picker` | iOS-style 3D drum on native momentum scroll with notch snap | Date/time or option drums, mobile-feel pickers |
+| `availability-scheduler` | Per-day spring toggles, blur-slide range add/remove | Schedule/slot editors |
+
+### Navigation and wayfinding
+
+| Pattern (slug) | Mechanism | Reach for it when |
+|---|---|---|
+| `tabs` | Pill/segment/underline with a spring `layoutId` indicator | Tab bars, view-mode selectors |
+| `expandable-tabs` | Active icon tab expands to a labelled pill; panel morphs height, slides direction-aware | Compact tab bars with rich panels |
+| `shared-layout-bg` | Pill glides between hovered items via shared layout, blur enter/exit | Sidebar/menu hover and active states |
+| `dock` | macOS-style grouped actions with a gliding active pill | Toolbars, grouped action rails |
+| `bounce-sidebar` | Active dot jumps between destinations on a curved spring path | Vertical navigation with a playful indicator |
+| `preview-rail` | Compact ticks form a hover pyramid and reveal a floating destination preview | Dense navigation rails, session/thread switchers |
+| `expandable-action-bar` | Icon actions expand into labelled controls on hover/focus | Compact action clusters |
+| `overflow-actions` | Connected pill rail springs open to reveal extra controls | Primary-plus-overflow action groups |
+| `command-palette` | Fuzzy filter with a spring-animated active row | Cmd-K surfaces |
+| `bloom-menu` | Button morphs into a menu blooming iris-out from center with radial stagger | Radial/launcher menus |
+
+### Overlays and surfaces
+
+| Pattern (slug) | Mechanism | Reach for it when |
+|---|---|---|
+| `tooltip` | Blur enter/exit, spring spawn | Hover/focus hints |
+| `popover` | Gooey SVG-filter ooze from the trigger; Morph variant clip-morphs from the trigger corner | Anchored panels that should feel attached to their trigger |
+| `context-menu` | Pointer-origin clip morph, gliding active row, keyboard nav, typeahead, long-press | Right-click and long-press menus |
+| `morphing-modal` | One panel morphs height between inner views, blur cross-fade on content | Multi-step dialogs, settings panes |
+| `center-morph-modal` | Surface unfolds from its exact center toward every edge and folds back | Focused confirm/detail modals |
+| `drawer` | Spring side panel, backdrop blur, body scroll lock, esc-to-close | Side panels, inspector panes |
+| `bottom-sheet` | Draggable sheet with snap points, inertia, glass surface | Mobile-feel sheets on any platform |
+| `dynamic-island` | Pill morphs between live-activity views with bouncy shell resize and blur crossfades | Live status surfaces, compact expanding widgets |
+| `notification-stack` | Cards spring from a stacked summary into a readable list on hover/focus/tap | Notification centers, grouped alerts |
+| `animated-toast-stack` | Status morphs, swipe dismissal, layout-aware stacking | Toast systems — layout-aware stacking is the bar |
+| `theme-toggle` | Full-page clip-path reveal via the View Transition API | Theme switching that should feel like one gesture |
+
+### Content, data, and gestures
+
+| Pattern (slug) | Mechanism | Reach for it when |
+|---|---|---|
+| `bouncy-accordion` | Single-open accordion with weighted spring layout, reduced-motion-safe reveals | Disclosure groups, expandable rows |
+| `table` | Virtualized 10k+ rows, sortable, resizable, minimal reduced-motion-safe motion | Data grids — proof that restraint is also a motion decision |
+| `infinite-masonry` | Virtualized variable-height masonry with progressive load | Media/card walls |
+| `swipeable-list` | Rows swipe to reveal contextual actions | Mobile-style lists with hidden actions |
+| `pull-to-refresh` | Drag resistance, threshold feedback, async refresh | Refreshable feeds |
+| `marquee` | Infinite horizontal/vertical scroll, pause on hover | Logo walls, tickers |
+| `text-animation` | Spring reveals, chromatic sweeps, shimmer loading, letter-cascade swaps | Hero copy, streaming/loading text |
+| `number` | Count-up values, rolling digit tickers | Metrics, token/cost counters |
+| `cylinder-carousel` | Items line a 3D cylinder with springy glide and snap | Showcase carousels |
+| `knockout-bracket` | Animated tournament fixtures paging through rounds | Bracket/progression views |
+| `prediction-market` / `swap` / `wallet-card` | Trade tickets, morphing swap views, morphing account surfaces | Finance-shaped composite widgets |
+| `not-found` | Five animated 404 styles | Error pages that keep the product's feel |
+
+### Ambience and scroll
+
+| Pattern (slug) | Mechanism | Reach for it when |
+|---|---|---|
+| `tilt-card` | 3D perspective tilt with cursor-tracked glare | Hero/product cards that should feel physical |
+| `shader-background` | Canvas shader variants (mesh gradient, grain, warp, waves…); reduced motion freezes them | Atmospheric backgrounds with dimension |
+| `scroll-animation` | Lenis smooth-scroll provider plus a reading-progress indicator | Scroll-driven storytelling |
+
+## 4. Mechanics rules
+
+These sharpen the shared axioms for interaction work; none of them replace the style skill.
+
+- **Motion serves meaning.** Every animation maps to a real interaction, state change, or affordance. A hover that changes nothing is slop — beui.dev patterns all animate *state*, never decoration.
+- **Reduced motion is part of the component, not an afterthought.** Every beui.dev component ships a reduced-motion path; match that bar. Web: `prefers-reduced-motion: reduce` disables or replaces every transform-based animation (the `loader` pattern's opacity-pulse swap is the model). React Native: respect the system reduce-motion setting.
+- **GPU-composited properties only** — `transform`, `opacity`, `filter`. Never animate layout properties; morph layout through shared-layout (`layoutId`) or measured height primitives instead.
+- **Springs move things; easings tint things.** Spatial movement (position, scale, layout morphs) wants spring physics so it stays interruptible and retargetable. Color, opacity, and blur want short duration + easing. Do not put a fixed-duration tween on a gesture-driven surface.
+- **Interruptibility is non-negotiable.** A press, hover-out, or route change mid-animation must retarget smoothly, never queue or block input. This is the practical reason beui.dev uses springs — copy that property, not just the bounce.
+- **Motion never regresses input latency or stream rendering.** Measure with the `perfection` ruleset when in doubt; a virtualized list's measurement contract beats a pretty reveal.
+- **Library choice is a project decision, not a default.** beui.dev assumes Motion (motion.dev) + Tailwind. If the project already has a motion stack, adapt the mechanism to it. If it has none: CSS transitions/WAAPI cover micro-interactions; adding a library is justified by shared-layout or spring-physics needs and gets recorded (with bundle cost) in `DESIGN.md`. Check `package.json` before importing anything.
+
+## 5. DESIGN.md integration
+
+`design-system-architecture.md` defines a Motion & Interaction section in every `DESIGN.md`. This file feeds it:
+
+- Extracted spring configs, durations, and easings land there as named tokens before components use them.
+- Each shipped interaction traces to a catalog pattern (or a recorded novel mechanism) plus its reduced-motion behavior.
+- New reusable interaction patterns (used 2+ times) get documented back into `DESIGN.md` Section 5 with their states, like any other primitive.
+
+## 6. Verification
+
+Interaction work is verified through `/visual-qa` with motion actually driven and inspected — hover, press, open/close, swipe, and theme transitions exercised on the rendered surface, plus a reduced-motion pass (emulate `prefers-reduced-motion: reduce`) proving the fallback exists. Timing-sensitive changes record a short screen capture, not just stills.

package/packages/omo-codex/plugin/skills/ulw-loop/SKILL.md

@@ -34,6 +34,23 @@ This skill is intentionally compact. The full workflow lives in `references/full
 - Fallback only when the child is completed without the deliverable, ack-only after `followup_task`, explicitly `BLOCKED:`, or no longer running. Then record inconclusive and respawn a smaller `fork_turns: "none"` task with the missing deliverable.
 - Use `git-master` for git-tracked edits: inspect recent and touched-path commit history, then commit each verified work unit atomically in the repository's observed language, scope, and message style with only that unit's files staged. Never carry verified units into a later omnibus commit.
 
+## Team mode: decide it, do not default to it
+
+Solo execution with parallel background `task` workers is the default. A team (`team_create`) adds per-member briefing, shared-state, and relay overhead, so it must be paid for by the work's shape. Decide ONCE, when the plan's work units are known, and record the verdict plus its reason in the notepad.
+
+Stand up a team when BOTH hold:
+
+1. **The units' scopes overlap in a way you cannot cleanly cut.** They touch the same module, contract, or migration, so one unit's discovery changes what another should do. Fire-and-forget workers cannot exchange that mid-flight; teammates can, because the lead relays it.
+2. **Running them at the same time actually finishes sooner.** The units are each substantial and none is merely waiting on another's output. Two units where the second only consumes the first's result are a sequence, not a team.
+
+When the units are genuinely independent — separate files, no shared contract — spawn parallel background `task` workers instead and avoid the team coordination overhead entirely. When the work is one cohesive unit, do it yourself. Overlap alone is not enough: near-identical units that would collide on the same lines are faster done in sequence by one worker.
+
+Under team mode, isolate and land per unit:
+
+- **One git worktree per member**, never a shared checkout — concurrent members editing one working tree corrupt each other's diffs and evidence. Give each member its own branch off the base and its own worktree path.
+- **Merge per work unit, as each unit is verified.** A member's unit lands when its own evidence is captured and its gates are green; it does not wait for the slowest sibling. Integrate each merged unit back into the base the others branch from, so overlapping members rebase onto real merged work rather than guessing at it.
+- **Conflicts are the lead's job.** When two members' units touch the same lines, the lead decides the order they land and tells the later member what changed; members never resolve a sibling's conflict blind.
+
 ## Codex Tool Mapping
 
 Codex exposes ONE subagent surface per session — check your tool list. GPT-5.6 (sol/terra) get the flat MultiAgentV2 tools (primary); GPT-5.5 and gpt-5.6-luna get the namespaced `multi_agent_v1.*` set (fallback row). The workflow's orchestration examples map to:

package/packages/omo-codex/scripts/install-dist/install-local.mjs

@@ -5903,7 +5903,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@oh-my-opencode/omo-codex",
-    version: "4.19.2",
+    version: "4.19.3",
     type: "module",
     private: true,
     description: "Codex harness adapter for oh-my-openagent. Vendored Codex plugin namespace (omo) + TypeScript installer + telemetry.",

package/packages/shared-skills/skills/frontend/ATTRIBUTION.md

@@ -210,6 +210,13 @@ no Lazyweb source, documentation text, or screenshot content is vendored. Lazywe
 remain the property of their owner, and the guide grants no license to ship, trace, or
 commit reference screenshots harvested through it.
 
+`frontend/references/design/interaction-skill.md` is a project-original, curl-only
+operating guide for consulting the beui.dev animated-component registry during interaction
+and motion work, written from live endpoint verification; no beui.dev source code,
+documentation text, or component implementations are vendored. beui.dev names remain the
+property of their owner, and the guide instructs reading component source for mechanism
+extraction only, not vendoring it into references or projects.
+
 `frontend/references/design/clone-from-url.md` is a project-original runtime-extraction
 workflow guide. Its browser + `getComputedStyle` clone approach follows the same
 MIT-licensed `JCodesMore/ai-website-cloner-template` clone-website workflow that `aside.md`

package/packages/shared-skills/skills/frontend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend
-description: "MUST USE for frontend/web UI/UX/visual work: building, styling, redesigning pages/components, React setup, performance audits, visual QA, taste, and polish. Routes four rulesets: design taste router and brand references; perfection for Playwright/Chromium Lighthouse/Core Web Vitals; ui-ux-db palettes/fonts/guidelines; designpowers personas/accessibility/critique/handoff; plus curl-only lazyweb real-app-screen research for design direction. Triggers: frontend, UI, UX, design, redesign, styling, layout, animation, motion, premium, luxury, minimal, brutalist, Awwwards, DESIGN.md, mockup, React, Lighthouse, accessibility, WCAG, Core Web Vitals, looks generic, make it pretty, like X brand, lazyweb, design research."
+description: "MUST USE for frontend/web UI/UX/visual work: building, styling, redesigning pages/components, React setup, performance audits, visual QA, taste, and polish. Routes four rulesets: design taste router and brand references; perfection for Playwright/Chromium Lighthouse/Core Web Vitals; ui-ux-db palettes/fonts/guidelines; designpowers personas/accessibility/critique/handoff; plus curl-only lazyweb real-app-screen research and the beui.dev interaction catalog. Triggers: frontend, UI, UX, design, redesign, styling, layout, animation, motion, interaction, micro-interaction, make it feel alive, premium, luxury, minimal, brutalist, Awwwards, DESIGN.md, mockup, React, Lighthouse, accessibility, WCAG, Core Web Vitals, looks generic, make it pretty, like X brand, lazyweb, design research."
 ---
 
 # Frontend
@@ -14,6 +14,7 @@ This file is a router, not a rulebook. The rules live in four rulesets under `re
 | Request involves… | Read |
 |---|---|
 | ANY UI implementation, styling, redesign, mockup, or visual decision | `references/design/README.md` FIRST. It enforces two mandatory gates — the Design System Gate (a `DESIGN.md` must exist before any component is written) and the React Dev Tooling Gate (react-grab / react-scan / react-doctor installed by default) — then routes to the taste and brand references below. |
+| Interaction or motion work — micro-interactions, animated components, transitions, gestures, hover/press/state feedback, "make it feel alive" | ALSO `references/design/interaction-skill.md`. The beui.dev catalog is the mandatory interaction reference: find the nearest pattern, read its real source through the file's curl recipe, and adapt the mechanism to `DESIGN.md` motion tokens. It stacks on the routed style skill — never replaces it. |
 | Writing or modifying frontend code, OR auditing performance / SEO / accessibility / quality | ALSO `references/perfection/README.md`. Lighthouse 100 in every category, measured on real Playwright Chromium (never the `lighthouse` CLI), achieved through architecture — never by dropping animations or hiding content. |
 | Looking up a concrete style, color palette, font pairing, chart type, landing-page structure, or UX guideline — or generating a project design system from keywords | `references/ui-ux-db/README.md`. A searchable CSV database with a CLI; a lookup tool, not a posture. Load on demand; `design` stays the source of truth for taste and the `DESIGN.md` contract. |
 | ANY implementation or redesign that creates or updates `DESIGN.md` — plus explicit operating-layer asks (personas, critique, debt, handoff, synthetic user testing) | `references/designpowers/README.md` + `references/designpowers/lane-c-review.md`. An internal frontend ruleset, not a separate skill: lane-c is the Phase Final flatness/critique reviewer, and its accessibility-constraints and accepted-debt language fills the required `DESIGN.md` sections. Load other lanes only when their phase applies. |
@@ -61,6 +62,7 @@ The reference library has one architecture file, 12 taste skills (Layer A — *h
 | `image-to-code-skill.md` | "Generate the design first, then code it." Pair with one imagegen file below. |
 | `output-skill.md` | Stacks on any style skill when output is incomplete — placeholders, `// TODO`, half-done components. |
 | `stitch-skill.md` | Stacks on any style skill for Google Stitch compatibility or a `DESIGN.md` doc export. A complete worked export ships as `stitch-design-example.md`. |
+| `interaction-skill.md` | Stacks on any style skill when work adds or changes interaction or motion. beui.dev-anchored: read the mapped component's source before designing an interaction; reduced motion always. |
 | `imagegen-frontend-web.md` / `imagegen-frontend-mobile.md` / `imagegen-brandkit.md` | Image-only output (mockup, app-screen concepts, brand board). These NEVER write code — switch to `image-to-code-skill.md` if code is wanted. |
 
 ### Layer B — brand design systems (orthogonal to Layer A; stack freely)
@@ -113,6 +115,7 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
 | "Linear-style landing page" | `design/README.md` + `design/linear.app.md` + `design/taste-skill.md` + `perfection/README.md` |
 | "Premium SaaS hero like Stripe" | `design/README.md` + `design/stripe.md` + `design/soft-skill.md` + `perfection/README.md` |
 | "Improve this existing dashboard" | `design/README.md` + `design/redesign-skill.md` + `perfection/README.md` |
+| "Add micro-interactions" / "animate this" / "make it feel alive" / "polish the interactions" | `design/README.md` + `design/interaction-skill.md` on top of the current style skill + `perfection/README.md` |
 | "Build this screenshot / Imagen mock / Stitch output exactly" | `design/README.md` + `design/image-to-code-skill.md` + `perfection/README.md` + `/visual-qa` reference-fidelity mode |
 | "Audit my site" / "make this page faster" | `perfection/README.md` (+ `perfection/react-perf-tooling.md` if React) |
 | "Mockup image of a fintech app" — no code | `design/imagegen-frontend-mobile.md` (+ a Layer B brand if named) |