@3xhaust/oh-my-design 0.16.1

package/core/graphics/svg-geometric-patterns.md

@@ -0,0 +1,145 @@
+# SVG geometric patterns
+
+An SVG geometric pattern — dots, lines, or a grid — embedded as a data URI and applied
+as a repeating `background-image`. The pattern adds visual structure to backgrounds without
+imagery or illustration: it reads as a surface property rather than a content element.
+Unlike grain, which produces organic randomness, a geometric pattern produces deliberate
+order — it implies a system, a grid, an underlying precision.
+
+No external file is required. The SVG is a single small tile (16–40px square) that the
+browser repeats across the element. The result is a background that scales to any
+viewport size with no pixelation.
+
+## When it earns its place / When it does not
+
+Condition: backgrounds that need visual structure without imagery — code editors, technical
+product sites, engineering tools, documentation — where an organic texture would be
+mismatched to the product's register. A dot grid on a developer tool reads as graph paper:
+it signals precision and technical culture. A line pattern on an editorial layout can
+read as a reference to print production. `core/theory/layout.md` closure principle:
+a repeated grid element creates implied boundaries and structure that the eye reads as
+organisational even before content is added.
+
+Also appropriate as a hero background when the concept is systematic or ordered —
+architecture, infrastructure, planning tools — where the grid pattern reinforces the
+concept's governing metaphor.
+
+Condition against: warm or organic brand concepts where a geometric pattern reads as
+cold or over-engineered. Any context where the pattern's density competes with the text
+density above it — a tight dot grid under dense body text creates visual noise. On dark
+surfaces with low-contrast patterns, the pattern may not read at all; verify visibility.
+And: a geometric pattern is not a substitute for a considered background decision —
+it is a surface treatment on top of a colour choice. The colour must be chosen first.
+
+## Parameters
+
+```css
+:root {
+  /* Pattern type: set by choosing the appropriate background-image value below.
+     Three canonical patterns: dot grid, line grid, isometric grid. */
+
+  /* Pattern colour: the foreground element of the pattern.
+     Should be a low-contrast step above the background — typically 8–15% opacity
+     of the text colour. More contrast than this makes the pattern dominant. */
+  --pattern-color: rgba(0, 0, 0, 0.08);
+  --pattern-bg: #fafafa; /* the background colour beneath the pattern */
+
+  /* Tile size: the repeat interval.
+     20–32px: fine, dense pattern — reads as texture.
+     40–60px: medium grid — reads as structural grid.
+     80px+: coarse grid — reads as scaffolding, layout guide. */
+  --pattern-tile: 24px;
+
+  /* Element size within the tile: dot diameter, line stroke width. */
+  --pattern-dot-size: 1.5px;
+  --pattern-line-width: 0.5px;
+}
+```
+
+## Implementation
+
+**Dot grid pattern:**
+
+```css
+.pattern-dots {
+  background-color: var(--pattern-bg);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24'%3E%3Ccircle cx='12' cy='12' r='1' fill='rgba(0%2C0%2C0%2C0.12)'/%3E%3C/svg%3E");
+  background-size: var(--pattern-tile) var(--pattern-tile);
+  background-repeat: repeat;
+}
+```
+
+**Line grid pattern (horizontal lines only):**
+
+```css
+.pattern-lines {
+  background-color: var(--pattern-bg);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24'%3E%3Cline x1='0' y1='23.5' x2='24' y2='23.5' stroke='rgba(0%2C0%2C0%2C0.08)' stroke-width='0.5'/%3E%3C/svg%3E");
+  background-size: var(--pattern-tile) var(--pattern-tile);
+  background-repeat: repeat;
+}
+```
+
+**Full grid pattern (horizontal + vertical lines):**
+
+```css
+.pattern-grid {
+  background-color: var(--pattern-bg);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32'%3E%3Cpath d='M 32 0 L 0 0 0 32' fill='none' stroke='rgba(0%2C0%2C0%2C0.07)' stroke-width='0.5'/%3E%3C/svg%3E");
+  background-size: 32px 32px;
+  background-repeat: repeat;
+}
+```
+
+**Dark surface variants:** Replace `rgba(0,0,0,0.08)` with `rgba(255,255,255,0.06)` in the
+SVG fill/stroke value. The percent-encoding changes accordingly:
+- `rgba(255%2C255%2C255%2C0.06)` in the data URI.
+
+```html
+<!-- Apply to any section or container: -->
+<section class="pattern-dots">
+  <div class="section-inner">
+    <h2>Structured background.</h2>
+  </div>
+</section>
+
+<!-- Or as a decorative panel: -->
+<div class="panel pattern-grid">
+  <!-- Content above the pattern grid -->
+</div>
+```
+
+## Linter notes
+
+- Geometric patterns at opacity that makes them dominant over the content above them are a
+  defect. The pattern must never compete with text or UI elements for visual attention.
+  Run `omd check` to verify contrast between any text and the pattern background —
+  the checker uses the `background-color` value and the overlaid SVG pattern's effective
+  luminance. If text contrast fails, reduce pattern opacity or increase the gap between
+  background and pattern colour values.
+
+- A dot grid in the flagged SLOP-GRADIENT hue bands is not automatically a `SLOP-GRADIENT`
+  violation (the rule targets gradient fills, not patterns) — but a saturated coloured
+  dot grid reads as decoration pretending to be structure. Geometric patterns work as
+  neutral structure; adding hue to them converts them from structure to decoration and
+  they lose the technical signal that earns their place.
+
+- The SVG tile `width` and `height` attributes must match the `background-size` value or
+  the tile will scale with display density, producing a visible seam at HiDPI. Set both
+  the SVG dimensions and `background-size` to the same pixel value in `--pattern-tile`.
+
+## Do not combine with
+
+**gradient-mesh.md behind the same element** — a mesh gradient and a geometric pattern
+applied to the same surface produce two background systems: one ambient and organic, one
+ordered and geometric. They describe different things about the surface and the combination
+reads as indecision rather than depth.
+
+**noise-grain-texture.md at visible opacity** — grain and a geometric pattern both
+operate on the background texture register. One is organic randomness; the other is
+deliberate order. Combining them does not produce a richer surface — it obscures each
+technique's signal.
+
+**High-density body text sections** — a dot grid under dense text produces a visual
+texture that competes with the letter forms. Reserve geometric patterns for sections
+where content density is low and the pattern can read as structure rather than noise.

package/core/history/index.ts

@@ -0,0 +1,39 @@
+import { mkdirSync, appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Run, Violation } from '../types.ts';
+
+const historyPath = (cwd: string): string => join(cwd, '.omd', 'history.jsonl');
+
+/**
+ * Appends one run to the history log, creating `.omd/` if needed. A run with zero
+ * violations is still recorded — zero findings is the evidence that the user improved.
+ */
+export function logRun(cwd: string, page: string, violations: Violation[], ts?: string): void {
+  const counts: Record<string, number> = {};
+  for (const v of violations) counts[v.id] = (counts[v.id] ?? 0) + 1;
+
+  const run: Run = { ts: ts ?? new Date().toISOString(), page, counts, total: violations.length };
+
+  mkdirSync(join(cwd, '.omd'), { recursive: true });
+  appendFileSync(historyPath(cwd), `${JSON.stringify(run)}\n`);
+}
+
+/**
+ * Reads every logged run in file order. Missing history -> []. A corrupt line is skipped
+ * rather than losing the whole log.
+ */
+export function readHistory(cwd: string): Run[] {
+  const path = historyPath(cwd);
+  if (!existsSync(path)) return [];
+
+  const lines = readFileSync(path, 'utf8').split('\n').filter((line) => line.trim().length > 0);
+  const runs: Run[] = [];
+  for (const line of lines) {
+    try {
+      runs.push(JSON.parse(line) as Run);
+    } catch {
+      // corrupt line — skip, keep the rest of the log
+    }
+  }
+  return runs;
+}

package/core/install/detect.ts

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Host } from '../types.ts';
+
+export interface Detected {
+  host: Host;
+  home: string;
+  version?: string;
+}
+
+export interface DetectOpts {
+  /** Override for `os.homedir()`, so detection is testable without touching the real home. */
+  homedir?: string;
+}
+
+/**
+ * Global, not per-project: a host is "present" when its config directory exists on disk,
+ * honouring the env vars each host itself uses to relocate that directory.
+ */
+export function detectHosts(env: NodeJS.ProcessEnv = process.env, opts: DetectOpts = {}): Detected[] {
+  const home = opts.homedir ?? homedir();
+  const detected: Detected[] = [];
+
+  const claudeHome = env['CLAUDE_CONFIG_DIR'] || join(home, '.claude');
+  if (existsSync(claudeHome)) detected.push({ host: 'claude', home: claudeHome });
+
+  const codexHome = env['CODEX_HOME'] || join(home, '.codex');
+  if (existsSync(codexHome)) detected.push({ host: 'codex', home: codexHome });
+
+  return detected;
+}

package/core/install/install.ts

@@ -0,0 +1,321 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, rmSync, readdirSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { parse as parseToml } from 'smol-toml';
+import { build } from '../../adapters/build.ts';
+import type { Detected } from './detect.ts';
+import { unpatchSettings, patchSettings, unpatchHooks } from './patch-claude.ts';
+import type { Settings } from './patch-claude.ts';
+import { patchConfigToml, unpatchConfigToml } from './patch-codex.ts';
+import type { Host } from '../types.ts';
+
+// core/install/install.ts -> core/install -> core -> package root
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const MARKETPLACE_URL = 'https://github.com/3x-haust/oh-my-design.git';
+// Derived from what the build emitted, never hardcoded: a hardcoded list is how
+// omd-sketch survived its own deletion, twice.
+function shippedSkillNames(): string[] {
+  return readdirSafe(join(pkgRoot, 'dist', 'codex', 'skills'));
+}
+
+function pkgVersion(): string {
+  const pkg = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')) as { version: string };
+  return pkg.version;
+}
+
+function readdirSafe(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** Every config we are about to patch gets backed up first, unconditionally. */
+function backupFile(path: string, home: string): void {
+  if (!existsSync(path)) return;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dest = join(home, 'backups', `${basename(path)}.${stamp}.bak`);
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(path, dest);
+}
+
+// Every omd subcommand the skill invokes. A loop that raises a permission prompt ten times
+// per iteration is a loop nobody finishes.
+const OMD_ALLOW = [
+  'Bash(omd check:*)', 'Bash(omd ir:*)', 'Bash(omd render:*)',
+  'Bash(omd frame:*)', 'Bash(omd ref:*)', 'Bash(omd choose:*)',
+  'Bash(omd decision:*)', 'Bash(omd taste:*)', 'Bash(omd coach:*)',
+  'Bash(omd probe:*)', 'Bash(omd config:*)', 'Bash(omd craft:*)', 'Bash(omd copy:*)',
+  'Bash(omd composition:*)',
+  'Bash(omd text-slop:*)', 'Bash(omd visual-richness:*)', 'Bash(omd stack:*)',
+  'Bash(omd source:*)', 'Bash(omd pack:*)', 'Bash(shasum:*)',
+];
+
+// Pre-namespace skill directory names that predate the `omd-` prefix. Pruned on install so a
+// legacy bare directory cannot shadow the `oh-my-design:` plugin.
+const LEGACY_SKILLS = ['ultradesign', 'critique'];
+
+/**
+ * Claude Code loads OMD as the marketplace plugin `oh-my-design@omd` (marketplace `omd` ->
+ * github `3x-haust/oh-my-design`). Everything resolves under the `oh-my-design:` namespace,
+ * so the installer registers the plugin in settings.json and prunes any bare-name `omd-*`
+ * skills/agents a previous direct install left behind — one surface, never a duplicate.
+ */
+function installClaude(d: Detected, changes: string[]): void {
+  // Claude Code installs OMD as the marketplace plugin `oh-my-design@omd`, so every skill and
+  // agent resolves under the `oh-my-design:` namespace (e.g. `oh-my-design:ultradesign`). The
+  // older bare-name copy under ~/.claude/skills and ~/.claude/agents is pruned here so a stale
+  // `omd-*` surface can never shadow the plugin with a duplicate.
+  const skillsDest = join(d.home, 'skills');
+  for (const name of readdirSafe(skillsDest)) {
+    if (!name.startsWith('omd-') && !LEGACY_SKILLS.includes(name)) continue;
+    rmSync(join(skillsDest, name), { recursive: true, force: true });
+    changes.push(`claude: removed direct skill ${name}`);
+  }
+  const agentsDest = join(d.home, 'agents');
+  for (const file of readdirSafe(agentsDest)) {
+    if (!file.startsWith('omd-')) continue;
+    rmSync(join(agentsDest, file), { force: true });
+    changes.push(`claude: removed direct agent ${file}`);
+  }
+
+  const settingsPath = join(d.home, 'settings.json');
+  backupFile(settingsPath, d.home);
+  const current: Settings = existsSync(settingsPath)
+    ? (JSON.parse(readFileSync(settingsPath, 'utf8')) as Settings)
+    : {};
+  // Register the marketplace + enable the plugin (patchSettings) and clear the legacy gate.
+  const next = unpatchHooks(patchSettings(current, { marketplaceUrl: MARKETPLACE_URL, allow: OMD_ALLOW }));
+  mkdirSync(d.home, { recursive: true });
+  writeFileSync(settingsPath, `${JSON.stringify(next, null, 2)}\n`);
+  changes.push(`claude: registered oh-my-design@omd plugin and patched ${settingsPath}`);
+}
+
+function uninstallClaude(d: Detected, changes: string[]): void {
+  const settingsPath = join(d.home, 'settings.json');
+  if (existsSync(settingsPath)) {
+    const current = JSON.parse(readFileSync(settingsPath, 'utf8')) as Settings;
+    const next = unpatchHooks(unpatchSettings(current));
+    writeFileSync(settingsPath, `${JSON.stringify(next, null, 2)}\n`);
+    changes.push(`claude: unpatched ${settingsPath}`);
+  }
+
+  // Remove any bare-name skill directory a previous direct install left, by prefix. The
+  // user's own skills (no omd- prefix) live beside them and are never touched.
+  const skillsDir = join(d.home, 'skills');
+  for (const name of readdirSafe(skillsDir)) {
+    if (!name.startsWith('omd-') && !LEGACY_SKILLS.includes(name)) continue;
+    rmSync(join(skillsDir, name), { recursive: true, force: true });
+    changes.push(`claude: removed ${join(skillsDir, name)}`);
+  }
+
+  for (const file of readdirSafe(join(d.home, 'agents'))) {
+    if (!file.startsWith('omd-')) continue;
+    rmSync(join(d.home, 'agents', file), { force: true });
+    changes.push(`claude: removed ${join(d.home, 'agents', file)}`);
+  }
+
+  // NEVER delete .omd/ — that is the user's own work.
+  const pluginRoot = join(d.home, 'plugins', 'omd');
+  if (existsSync(pluginRoot)) {
+    rmSync(pluginRoot, { recursive: true, force: true });
+    changes.push(`claude: removed ${pluginRoot}`);
+  }
+}
+
+function installCodex(d: Detected, version: string, changes: string[]): void {
+  const pluginDir = join(d.home, 'plugins', 'cache', 'omd', 'oh-my-design', version);
+  mkdirSync(pluginDir, { recursive: true });
+  cpSync(join(pkgRoot, 'dist', 'codex'), pluginDir, { recursive: true });
+  changes.push(`codex: installed plugin -> ${pluginDir}`);
+
+  const agentsDir = join(d.home, 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+  const srcAgentsDir = join(pkgRoot, 'dist', 'codex', 'agents');
+  const agentNames: string[] = [];
+  for (const file of readdirSafe(srcAgentsDir)) {
+    if (!file.endsWith('.toml')) continue;
+    cpSync(join(srcAgentsDir, file), join(agentsDir, file));
+    agentNames.push(file.replace(/\.toml$/, ''));
+  }
+  changes.push(`codex: registered agents -> ${agentsDir} (${agentNames.join(', ') || 'none'})`);
+
+  const skillsSrc = join(pkgRoot, 'dist', 'codex', 'skills');
+  const skillsDest = join(d.home, 'skills');
+  if (existsSync(skillsSrc)) {
+    mkdirSync(skillsDest, { recursive: true });
+    cpSync(skillsSrc, skillsDest, { recursive: true });
+    changes.push(`codex: installed skills -> ${skillsDest}`);
+  }
+
+  const configPath = join(d.home, 'config.toml');
+  backupFile(configPath, d.home);
+  const currentText = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+  const patched = patchConfigToml(currentText, { agents: agentNames });
+  mkdirSync(d.home, { recursive: true });
+  writeFileSync(configPath, patched);
+  changes.push(`codex: patched ${configPath}`);
+}
+
+function uninstallCodex(d: Detected, changes: string[]): void {
+  const configPath = join(d.home, 'config.toml');
+  if (existsSync(configPath)) {
+    writeFileSync(configPath, unpatchConfigToml(readFileSync(configPath, 'utf8')));
+    changes.push(`codex: unpatched ${configPath}`);
+  }
+
+  const pluginRoot = join(d.home, 'plugins', 'cache', 'omd');
+  if (existsSync(pluginRoot)) {
+    rmSync(pluginRoot, { recursive: true, force: true });
+    changes.push(`codex: removed ${pluginRoot}`);
+  }
+
+  const agentsDir = join(d.home, 'agents');
+  for (const file of readdirSafe(agentsDir)) {
+    if (!file.startsWith('omd-') || !file.endsWith('.toml')) continue;
+    rmSync(join(agentsDir, file), { force: true });
+    changes.push(`codex: removed ${join(agentsDir, file)}`);
+  }
+
+  // NEVER delete .omd/ anywhere — only our own skill copies live under ~/.codex/skills/.
+  const skillsDir = join(d.home, 'skills');
+  for (const name of shippedSkillNames()) {
+    const path = join(skillsDir, name);
+    if (!existsSync(path)) continue;
+    rmSync(path, { recursive: true, force: true });
+    changes.push(`codex: removed skill ${name}`);
+  }
+}
+
+export function install(hosts: Detected[]): string[] {
+  build();
+  const version = pkgVersion();
+  const changes: string[] = [];
+  for (const d of hosts) {
+    if (d.host === 'claude') installClaude(d, changes);
+    else installCodex(d, version, changes);
+  }
+  return changes;
+}
+
+export function uninstall(hosts: Detected[]): string[] {
+  const changes: string[] = [];
+  for (const d of hosts) {
+    if (d.host === 'claude') uninstallClaude(d, changes);
+    else uninstallCodex(d, changes);
+  }
+  return changes;
+}
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  detail?: string;
+}
+
+export interface DoctorResult {
+  host: Host;
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
+function check(name: string, ok: boolean, detail?: string): DoctorCheck {
+  return detail === undefined ? { name, ok } : { name, ok, detail };
+}
+
+function omdVersionRuns(): DoctorCheck {
+  try {
+    execFileSync(process.execPath, [join(pkgRoot, 'bin', 'omd.ts'), '--version'], { stdio: 'pipe' });
+    return check('omd --version runs', true);
+  } catch (err) {
+    return check('omd --version runs', false, err instanceof Error ? err.message : String(err));
+  }
+}
+
+function doctorClaude(d: Detected): DoctorCheck[] {
+  const checks: DoctorCheck[] = [];
+  const settingsPath = join(d.home, 'settings.json');
+  let settings: Settings | undefined;
+  try {
+    settings = existsSync(settingsPath) ? (JSON.parse(readFileSync(settingsPath, 'utf8')) as Settings) : {};
+    checks.push(check('settings.json parses', true));
+  } catch (err) {
+    checks.push(check('settings.json parses', false, err instanceof Error ? err.message : String(err)));
+  }
+
+  const legacyHookPresent = settings?.hooks?.PreToolUse?.some(
+    (entry) => entry.hooks.some((hook) => hook.command.includes('omd.ts')),
+  ) ?? false;
+  checks.push(check('legacy PreToolUse hook absent', settings !== undefined && !legacyHookPresent));
+
+  const pluginEnabled = settings?.enabledPlugins?.['oh-my-design@omd'] === true;
+  checks.push(check('oh-my-design@omd plugin enabled', pluginEnabled));
+
+  const marketplaces = settings?.extraKnownMarketplaces as Record<string, unknown> | undefined;
+  checks.push(check('omd marketplace registered', Boolean(marketplaces && marketplaces['omd'])));
+
+  const strayAgents = readdirSafe(join(d.home, 'agents')).filter((file) => file.startsWith('omd-') && file.endsWith('.md')).sort();
+  checks.push(check('no duplicate direct agents', strayAgents.length === 0, strayAgents.length ? `found ${strayAgents.join(', ')}` : undefined));
+
+  const straySkills = readdirSafe(join(d.home, 'skills')).filter((name) => name.startsWith('omd-') || LEGACY_SKILLS.includes(name)).sort();
+  checks.push(check('no duplicate direct skills', straySkills.length === 0, straySkills.length ? `found ${straySkills.join(', ')}` : undefined));
+
+  const copyPermission = settings?.permissions?.allow?.includes('Bash(omd copy:*)') ?? false;
+  checks.push(check('copy check permission present', copyPermission));
+  const compositionPermission = settings?.permissions?.allow?.includes('Bash(omd composition:*)') ?? false;
+  checks.push(check('composition check permission present', compositionPermission));
+  const shasumPermission = settings?.permissions?.allow?.includes('Bash(shasum:*)') ?? false;
+  checks.push(check('composition hash permission present', shasumPermission));
+  const sourcePermission = settings?.permissions?.allow?.includes('Bash(omd source:*)') ?? false;
+  checks.push(check('source seal permission present', sourcePermission));
+
+  return checks;
+}
+
+function doctorCodex(d: Detected): DoctorCheck[] {
+  const checks: DoctorCheck[] = [];
+  const configPath = join(d.home, 'config.toml');
+  let config: { agents?: Record<string, { config_file?: string }> } | undefined;
+  try {
+    config = existsSync(configPath)
+      ? parseToml(readFileSync(configPath, 'utf8')) as { agents?: Record<string, { config_file?: string }> }
+      : {};
+    checks.push(check('config.toml parses', true));
+  } catch (err) {
+    checks.push(check('config.toml parses', false, err instanceof Error ? err.message : String(err)));
+  }
+
+  const omdAgents = readdirSafe(join(d.home, 'agents')).filter((f) => f.startsWith('omd-') && f.endsWith('.toml'));
+  checks.push(check('agents registered', omdAgents.length > 0));
+  const typesetterRegistered = config?.agents?.['omd-typesetter']?.config_file === './agents/omd-typesetter.toml'
+    && existsSync(join(d.home, 'agents', 'omd-typesetter.toml'));
+  checks.push(check('typesetter agent registered', typesetterRegistered));
+  const composerRegistered = config?.agents?.['omd-composer']?.config_file === './agents/omd-composer.toml'
+    && existsSync(join(d.home, 'agents', 'omd-composer.toml'));
+  checks.push(check('composer agent registered', composerRegistered));
+
+  const skillsPresent = shippedSkillNames().some((name) => existsSync(join(d.home, 'skills', name)));
+  checks.push(check('skills present', skillsPresent));
+
+  // Not a pass/fail: we could not confirm Codex's trusted_hash key format against a real
+  // install, so this must read as unverified rather than claim success.
+  checks.push(check(
+    'hook trust: unverified',
+    true,
+    'trusted_hash key format (see core/install/patch-codex.ts) has not been confirmed against a real Codex session',
+  ));
+
+  return checks;
+}
+
+export function doctor(hosts: Detected[]): DoctorResult[] {
+  const versionCheck = omdVersionRuns();
+  return hosts.map((d) => {
+    const checks = d.host === 'claude' ? doctorClaude(d) : doctorCodex(d);
+    checks.push(versionCheck);
+    return { host: d.host, ok: checks.every((c) => c.ok), checks };
+  });
+}

package/core/install/patch-claude.ts

@@ -0,0 +1,109 @@
+const ALLOW_PREFIX = 'Bash(omd ';
+const PLUGIN_KEY = 'oh-my-design@omd';
+// Identifies our hook among any others in PreToolUse: anything invoking omd.ts is ours.
+const HOOK_MARKER = 'omd.ts';
+
+export interface HookCommandEntry {
+  type: 'command';
+  command: string;
+  timeout: number;
+}
+
+export interface HookMatcherEntry {
+  matcher: string;
+  hooks: HookCommandEntry[];
+}
+
+/** What Claude Code's settings.json actually loads: event -> ordered matcher entries. */
+export interface HooksBlock {
+  PreToolUse?: HookMatcherEntry[];
+  [event: string]: HookMatcherEntry[] | undefined;
+}
+
+export interface Settings {
+  permissions?: { allow?: string[]; [k: string]: unknown };
+  enabledPlugins?: Record<string, boolean>;
+  extraKnownMarketplaces?: Record<string, unknown>;
+  hooks?: HooksBlock;
+  [k: string]: unknown;
+}
+
+const clone = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
+
+export function patchSettings(settings: Settings, opts: { marketplaceUrl: string; allow?: string[] }): Settings {
+  const out = clone(settings ?? {});
+
+  out.extraKnownMarketplaces = {
+    ...out.extraKnownMarketplaces,
+    omd: { source: { source: 'git', url: opts.marketplaceUrl } },
+  };
+  out.enabledPlugins = { ...out.enabledPlugins, [PLUGIN_KEY]: true };
+
+  const existing = out.permissions?.allow ?? [];
+  const merged = [...existing];
+  for (const entry of opts.allow ?? []) if (!merged.includes(entry)) merged.push(entry);
+  out.permissions = { ...out.permissions, allow: merged };
+
+  return out;
+}
+
+export function unpatchSettings(settings: Settings): Settings {
+  const out = clone(settings ?? {});
+
+  if (out.extraKnownMarketplaces) {
+    delete out.extraKnownMarketplaces['omd'];
+    if (Object.keys(out.extraKnownMarketplaces).length === 0) delete out.extraKnownMarketplaces;
+  }
+  if (out.enabledPlugins) {
+    delete out.enabledPlugins[PLUGIN_KEY];
+    if (Object.keys(out.enabledPlugins).length === 0) delete out.enabledPlugins;
+  }
+  if (out.permissions) {
+    if (Array.isArray(out.permissions.allow)) {
+      out.permissions.allow = out.permissions.allow.filter((a) => !a.startsWith(ALLOW_PREFIX));
+      if (out.permissions.allow.length === 0) delete out.permissions.allow;
+    }
+    if (Object.keys(out.permissions).length === 0) delete out.permissions;
+  }
+  return out;
+}
+
+/**
+ * Grants the `omd` subcommands the skill needs, without claiming a marketplace. Every
+ * Bash call the model makes would otherwise raise a permission prompt, and a loop that
+ * prompts ten times per iteration is a loop nobody finishes.
+ */
+export function patchAllow(settings: Settings, allow: string[]): Settings {
+  const out = clone(settings ?? {});
+
+  // We own the `Bash(omd ...)` namespace, so we replace it wholesale rather than appending.
+  // Appending leaves permissions for subcommands that no longer exist — an upgrade that
+  // removed `omd session` would otherwise grant it forever. Foreign entries keep their order.
+  const foreign = (out.permissions?.allow ?? []).filter((e) => !e.startsWith(ALLOW_PREFIX));
+  out.permissions = { ...out.permissions, allow: [...foreign, ...allow] };
+  return out;
+}
+
+/**
+ * Removes the PreToolUse gate that earlier versions installed, and only that: every other
+ * hook, on PreToolUse or any other event, is left exactly as it was.
+ *
+ * Nothing installs a hook any more. The gate made a human sign off on the reframing before
+ * anything could be built, which meant nothing could be rendered, which meant nothing could
+ * reveal that the reframing was wrong. It solved by signature a problem that is only ever
+ * solved by looking.
+ */
+export function unpatchHooks(settings: Settings): Settings {
+  const out = clone(settings ?? {});
+  if (!out.hooks) return out;
+  const hooks: HooksBlock = { ...out.hooks };
+  const existing = hooks.PreToolUse;
+  if (existing) {
+    const filtered = existing.filter((entry) => !entry.hooks.some((h) => h.command.includes(HOOK_MARKER)));
+    if (filtered.length) hooks.PreToolUse = filtered;
+    else delete hooks.PreToolUse;
+  }
+  if (Object.keys(hooks).length === 0) delete out.hooks;
+  else out.hooks = hooks;
+  return out;
+}