@monoes/monodesign 1.2.3 → 1.2.5

package/README.md

@@ -8,9 +8,12 @@
 [![license](https://img.shields.io/npm/l/@monoes/monodesign?style=flat-square)](https://github.com/monoes/monomind/blob/main/LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
 
-**Frontend design intelligence for AI agents** — design tokens, CSS antipattern detection, and the monodesign skill. The unified design agent for the Monomind ecosystem.
+**Frontend design intelligence for AI agents** — OKLCH design tokens, a 51-rule AI-slop
+antipattern detector, and the `/monodesign` agent skill for Claude Code and Gemini agy.
 
-> Part of the [Monomind](https://github.com/monoes/monomind) ecosystem.
+> Part of the [Monomind](https://github.com/monoes/monomind) ecosystem. v1.2.4 · Apache-2.0
+
+---
 
 ## Install
 
@@ -18,38 +21,186 @@
 npm install @monoes/monodesign
 ```
 
-## What's inside
+---
+
+## What's Inside
+
+| Module | Export path | Purpose |
+|---|---|---|
+| Design tokens (TS) | `@monoes/monodesign` | Typed constants for font, spacing, color, motion |
+| Design tokens (CSS) | `@monoes/monodesign/tokens` | CSS custom properties (`tokens.css`) |
+| Detection engine | `@monoes/monodesign/engine` | Node-side 51-rule antipattern detector |
+| Browser bundle | `@monoes/monodesign/engine/browser` | Browser-compatible detector (no Node deps) |
+
+---
+
+## Design Tokens
+
+Source: [`src/tokens.ts`](packages/@monoes/monodesign/src/tokens.ts) + [`src/tokens.css`](packages/@monoes/monodesign/src/tokens.css)
+
+All color tokens are in **OKLCH** — no hex colors in the token system.
 
-| Export | Purpose |
+### Token Categories
+
+| Category | Key Values |
 |---|---|
-| `tokens` | Design token definitions (colors, spacing, typography, breakpoints) |
-| `rules` | Antipattern detection rules for CSS and component structure |
-| `antipatterns` | Detect and report common frontend antipatterns |
+| **Typography** | Fonts: `'Cormorant Garamond'` (display), `'Instrument Sans'` (body), `'Space Grotesk'` (mono). Scale: xs (12px) → 7xl (72px). Line-heights: 1.2–2.0 |
+| **Spacing** | 8px base grid: `--space-1` (4px) → `--space-30` (120px) |
+| **Color** | Neutrals: ink/charcoal/ash/mist/cream/paper/white. Accent: Editorial Magenta `oklch(60% 0.25 350)` with 9-stop tonal ramp |
+| **Motion** | Expo-out primary `cubic-bezier(0.16,1,0.3,1)`, plus quint, in-out, in. Durations: 0s → 1.2s |
+| **Shadows** | sm/md/lg/accent. Max 0.15 alpha. |
+| **Radius** | none(0) → sm(4px) → md(8px) → lg(12px) → xl(16px) → full(9999px) |
+| **Z-index** | Named scale: below(−1) → base(0) → raised(1) → overlay(10) → modal(20) → toast(30) → top(40) |
+
+### CSS Usage
+
+```css
+/* Import CSS custom properties */
+@import '@monoes/monodesign/tokens';
+
+.hero {
+  font-family: var(--font-display);
+  color: var(--color-ink);
+  padding: var(--space-8);
+  border-radius: var(--radius-lg);
+  transition: transform var(--duration-default) var(--easing-expo-out);
+}
+```
 
-## Design tokens
+### TypeScript Usage
 
 ```typescript
-import { tokens } from '@monoes/monodesign';
+import { fontFamily, fontSize, spacing, easing, duration, color, accentScale, shadow, radius } from '@monoes/monodesign';
 
-// Access design system values
-tokens.colors.primary     // brand colors
-tokens.spacing.md         // spacing scale
-tokens.typography.body    // font stacks and sizes
-tokens.breakpoints.tablet // responsive breakpoints
+console.log(color.accent);    // oklch(60% 0.25 350)
+console.log(spacing[8]);      // 32px
+console.log(radius.lg);       // 12px
 ```
 
-## Antipattern detection
+---
 
-```typescript
-import { detectAntipatterns } from '@monoes/monodesign';
+## Antipattern Detection (51 Rules)
+
+Source: [`cli/engine/registry/antipatterns.mjs`](packages/@monoes/monodesign/cli/engine/registry/antipatterns.mjs) — 564 lines, 51 entries.
+
+### Rule Categories
+
+**`slop`** (21 rules) — AI-generation tells that make UIs feel generic:
+
+`side-tab`, `border-accent-on-rounded`, `overused-font`, `single-font`, `flat-type-hierarchy`, `gradient-text`, `ai-color-palette`, `cream-palette`, `nested-cards`, `monotonous-spacing`, `bounce-easing`, `dark-glow`, `icon-tile-stack`, `italic-serif-display`, `hero-eyebrow-chip`, `repeated-section-kickers`, `numbered-section-markers`, `em-dash-overuse`, `marketing-buzzword`, `aphoristic-cadence`, `oversized-h1`, `extreme-negative-tracking`, `broken-image`
+
+**`quality`** (24 rules) — Accessibility and design principle violations:
+
+`gray-on-color`, `low-contrast`, `layout-transition`, `line-length`, `cramped-padding`, `body-text-viewport-edge`, `tight-leading`, `skipped-heading`, `justified-text`, `tiny-text`, `all-caps-body`, `wide-tracking`, `text-overflow`, `clipped-overflow-container`, `design-system-font`, `design-system-color`, `design-system-radius`, `design-system-font-size`, `missing-focus-visible`, `small-touch-target`, `hover-only-affordance`, `image-missing-dimensions`, `dark-scheme-contrast-blindspot`
+
+**Provider-gated** (4 advisory rules, opt-in via `--gpt`/`--gemini`): `gpt-thin-border-wide-shadow`, `repeating-stripes-gradient`, `codex-grid-background`, `theater-slop-phrase`
+
+### Detection Engines
+
+| Engine | Method | Optional dep |
+|---|---|---|
+| `regex` | Source text / CSS-in-JS scan | none |
+| `static-html` | HTMLparser2 static DOM parse | none |
+| `browser` | Puppeteer live-page scan | `puppeteer` (optional) |
+| `visual` | Visual contrast analysis | `@monoes/monobrowse` (optional) |
+
+### Auto-Fix
+
+`cli/engine/fix/fixers.mjs` implements safe per-rule codemods. `--dry-run` prints unified diffs. `--rule <id,...>` narrows the fix to specific rule IDs.
+
+---
+
+## OKLCH Palette Seed Library
+
+Source: [`packages/@monomind/cli/src/commands/design-palette.ts:29–417`](packages/@monomind/cli/src/commands/design-palette.ts#L29-L417)
+
+- **129 hand-curated seeds** spanning the full hue wheel (0°–360°)
+- Each seed: `{ id, oklch: [L, C, H], mood: string, strategy: string }`
+- **Hue-zone weighting**: inverse-frequency across 30° buckets — equal probability for all hue regions regardless of seed density
+- **Env var override**: `MONODESIGN_PALETTE_SEED`
+
+---
+
+## The `/monodesign` Agent Skill
+
+Source: [`skill/SKILL.src.md`](packages/@monoes/monodesign/skill/SKILL.src.md) · v2.0.0 · Apache-2.0
+
+Triggers: `/monodesign`, `/design`, `/frontend-design`, plus 40+ natural-language triggers.
+
+### 24 Skill Commands
+
+| Category | Commands |
+|---|---|
+| Build | `craft`, `shape`, `init`, `document`, `extract`, `components`, `images`, `palette` |
+| Evaluate | `critique`, `audit`, `research`, `detect` |
+| Refine | `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard` |
+| Enhance | `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive` |
+| Fix | `clarify`, `adapt`, `optimize` |
+| Iterate | `live` |
+| Management | `pin`, `unpin`, `hooks` |
+
+### Sub-Agents
+
+| Agent file | Role |
+|---|---|
+| `skill/agents/monodesign-asset-producer.md` | Image/asset generation |
+| `skill/agents/monodesign-manual-edit-applier.md` | Accepts live manual edits during `live` sessions |
+
+---
+
+## Hooks Integration
+
+When enabled (`.monodesign/config.json`), antipattern detection runs automatically after UI file edits:
+
+```json
+{
+  "hook": {
+    "enabled": true,
+    "limits": { "maxFindings": 5, "maxChars": 8000 }
+  }
+}
+```
+
+Manage via `monomind design ignores` or `/monodesign hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>`.
+
+---
+
+## CLI Subcommands (`monomind design`)
+
+| Command | Purpose |
+|---|---|
+| `monomind design detect [-t <path>] [--json]` | Scan HTML/CSS for antipatterns |
+| `monomind design fix [-t <path>] [--dry-run] [--json] [--rule <ids>]` | Auto-fix with safe codemods |
+| `monomind design ignores <list\|add-rule\|add-file\|add-value\|remove-rule>` | Manage detector ignores |
+| `monomind design palette [--id <id>] [--from <key>] [--random] [--json]` | Pick OKLCH brand seed |
+
+---
+
+## Design System Consistency
+
+Source: [`cli/engine/design-system.mjs`](packages/@monoes/monodesign/cli/engine/design-system.mjs) — 815 lines
+
+Parses `DESIGN.md` / `.monodesign/design.json` to enforce consistency rules (`design-system-font`, `design-system-color`, `design-system-radius`, `design-system-font-size`). The skill writes `DESIGN.md`; the detector reads it for drift detection.
+
+Search order: `DESIGN.md` → `.agents/context/DESIGN.md` → `docs/DESIGN.md`.
+
+---
+
+## Package Exports
 
-const issues = detectAntipatterns(cssSource);
-// [{ rule: 'no-magic-numbers', line: 42, message: '...' }, ...]
+```json
+{
+  ".":                   "./src/index.ts",
+  "./tokens":            "./src/tokens.css",
+  "./engine":            "./cli/engine/detect-antipatterns.mjs",
+  "./engine/browser":    "./cli/engine/detect-antipatterns-browser.js"
+}
 ```
 
-## The monodesign skill
+**Dependencies:** `css-select`, `css-tree`, `domutils`, `fflate`, `htmlparser2`, `marked`  
+**Optional:** `@monoes/monobrowse` (browser detection), `puppeteer` (live URL scanning)
 
-In Claude Code, monodesign is available as `/monodesign` — the single design agent handling UI/component systems, brand strategy, UX research, visual storytelling, CSS architecture, design critique, and more. This package provides the runtime intelligence that skill draws from.
+---
 
 ## Links
 
@@ -59,4 +210,4 @@ In Claude Code, monodesign is available as `/monodesign` — the single design a
 
 ## License
 
-MIT
+Apache-2.0

package/cli/engine/engines/browser/drivers.mjs

@@ -28,7 +28,20 @@
 // Selection: MONODESIGN_BROWSER_DRIVER=monobrowse|puppeteer forces one;
 // otherwise monobrowse is tried first and puppeteer is the fallback.
 
+import { createServer } from 'node:net';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
 const DRIVER_ENV = 'MONODESIGN_BROWSER_DRIVER';
+// Windows CI teardown is the slow case: Chrome acknowledges Browser.close long
+// before the process exits and hands the socket back, and closeBrowser()'s
+// force-kill safety net is itself a deferred 1s timer. 5s is comfortable
+// locally but cuts into a loaded runner's teardown, so give CI more runway —
+// same reasoning as launchTimeoutMs below.
+const CDP_PORT_RELEASE_TIMEOUT_MS = process.env.CI ? 15_000 : 5_000;
+const CDP_PORT_RELEASE_POLL_MS = 25;
+const PROFILE_CLEANUP_RETRY_MS = 2_000;
 
 // Ports we launch headless Chrome on for detection runs. Deliberately away
 // from 9222 (the default `monomind browse` port): we must never attach to a
@@ -56,6 +69,41 @@ function withTimeout(promise, ms, label) {
   return Promise.race([promise, timeout]).finally(() => clearTimeout(handle));
 }
 
+// "Released" has to mean BINDABLE, not merely unreachable. A connect probe
+// stops succeeding as soon as Chrome's listener socket closes, which happens
+// early in its shutdown — while the process is still alive holding both the
+// port and the --user-data-dir singleton lock for this port. On Windows that
+// gap is wide and the socket stays unbindable across it (node does not set
+// SO_REUSEADDR there), so close() reported success and the next launch on the
+// same forced port sat until its timeout: "Chrome failed to start on port N
+// within 30000ms". Binding is the question the next launch actually asks, so
+// ask it directly. A listener that never accepted a connection leaves no
+// TIME_WAIT behind, so probing this way does not itself hold the port.
+function isPortBindable(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once('error', () => resolve(false));
+    server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+  });
+}
+
+function removeProfileDir(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    /* reclaimed by the OS's temp cleanup instead */
+  }
+}
+
+async function waitForCdpPortRelease(port) {
+  const deadline = Date.now() + CDP_PORT_RELEASE_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (await isPortBindable(port)) return;
+    await new Promise(resolve => setTimeout(resolve, CDP_PORT_RELEASE_POLL_MS));
+  }
+  throw new Error(`Chrome did not release CDP port ${port} within ${CDP_PORT_RELEASE_TIMEOUT_MS}ms`);
+}
+
 // ---------------------------------------------------------------------------
 // monobrowse driver
 // ---------------------------------------------------------------------------
@@ -143,7 +191,27 @@ async function launchMonobrowseBrowser(options = {}) {
     if (port === null) throw new Error('Could not find a free CDP port for monobrowse');
   }
 
-  const launchedPort = await mb.launchBrowser({ port, headless, args: launchArgs });
+  // CI runners (observed on the Windows GH Actions runner) are slower to get
+  // Chrome's CDP port open than the 10s default — a batch of sequential
+  // headless launches in the same job intermittently misses that window and
+  // fails with "Chrome failed to start... within 10000ms" even though the
+  // browser starts fine, just later. Give CI more runway; local dev keeps
+  // the tighter default so a genuinely broken launch still fails fast.
+  const launchTimeoutMs = options.launchTimeoutMs ?? (process.env.CI ? 30000 : undefined);
+  // Throwaway profile per launch. monobrowse defaults --user-data-dir to
+  // tmpdir()/monomind-browser-<port>, which is right for `monomind browse`
+  // (a later process reattaches to the same session by port) but wrong here:
+  // detection launches are stateless, and keying the profile on the port
+  // means two launches on the SAME port share one profile. Chrome enforces
+  // single-instance-per-profile, so the second launch rendezvouses with the
+  // first instead of starting its own — it hands over its command line and
+  // exits without ever opening a debugging port, which surfaces as "Chrome
+  // failed to start on port N" after the full launch timeout. Windows is
+  // where this bites: its singleton lock survives the previous Chrome being
+  // force-killed, and outlives the port being released. A unique dir removes
+  // the sharing entirely rather than racing the lock's cleanup.
+  const userDataDir = mkdtempSync(join(tmpdir(), 'monodesign-cdp-'));
+  const launchedPort = await mb.launchBrowser({ port, headless, args: launchArgs, launchTimeoutMs, userDataDir });
   // Control connection (to the initial about:blank tab) — used for lifecycle
   // commands; detection pages get their own dedicated connections.
   const control = await mb.connectToTarget(launchedPort);
@@ -175,8 +243,21 @@ async function launchMonobrowseBrowser(options = {}) {
           // Browser.close command directly (best effort, short timeout).
           await withTimeout(control.client.send('Browser.close', {}), 3000, 'Browser.close').catch(() => {});
         }
+        // Browser.close is acknowledged before Chrome has actually exited. A
+        // following detection run on a forced port can otherwise attach to the
+        // shutting-down process and fail creating its first target. Do not
+        // expose close() as complete until that CDP listener is gone.
+        await waitForCdpPortRelease(launchedPort);
       } finally {
         control.client.close();
+        // Best effort, twice: Chrome is still flushing profile data when the
+        // port comes back, so an immediate delete gets a few files recreated
+        // under it. The unref'd retry lands after that (same pattern as
+        // monobrowse's own post-close force-kill net) and never holds the
+        // process open. Whatever still survives is a few KB under tmpdir that
+        // nothing reuses, so neither attempt may fail close().
+        removeProfileDir(userDataDir);
+        setTimeout(() => removeProfileDir(userDataDir), PROFILE_CLEANUP_RETRY_MS).unref?.();
       }
     },
   };

package/cli/engine/rules/checks.mjs

@@ -2635,6 +2635,29 @@ function checkElementTextOverflowDOM(el) {
 // conditions can't be read off a resting element. Shared by the regex, static
 // and browser engines (each hands over its own CSS text).
 
+// Split a selector list on top-level commas only — i.e. commas inside a
+// functional pseudo-class's parens (`:is(a, button)`, `:where(a, b)`,
+// `:not(a, b)`, `:has(x, y)`) don't split. A naive `str.split(',')` breaks
+// `:is(a, button):focus { outline: none }` into `:is(a` and `button):focus`,
+// which both selectorTargetsInteractive() and the dark/light selector maps
+// below then treat as two unrelated (and malformed) selectors — producing
+// false-positive missing-focus-visible findings and double-counted rules.
+function splitTopLevelCommas(str) {
+  const parts = [];
+  let depth = 0, start = 0;
+  for (let k = 0; k < str.length; k++) {
+    const ch = str[k];
+    if (ch === '(') depth++;
+    else if (ch === ')') depth = Math.max(0, depth - 1);
+    else if (ch === ',' && depth === 0) {
+      parts.push(str.slice(start, k));
+      start = k + 1;
+    }
+  }
+  parts.push(str.slice(start));
+  return parts;
+}
+
 // Parse flat CSS into { selector, body, dark } tuples, tracking one level of
 // dark-scheme context (a `@media (prefers-color-scheme: dark)` ancestor).
 // @supports / @layer / @container / @scope are transparently descended.
@@ -2664,7 +2687,7 @@ function collectCssRules(css, dark = false, depth = 0) {
       }
       continue;
     }
-    for (const sel of prelude.split(',').map(s => s.trim()).filter(Boolean)) {
+    for (const sel of splitTopLevelCommas(prelude).map(s => s.trim()).filter(Boolean)) {
       out.push({ selector: sel, body, dark });
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monodesign",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Frontend design intelligence for AI agents — design tokens, antipattern detection, and the monodesign skill",
   "type": "module",
   "main": "./src/index.ts",
@@ -19,12 +19,6 @@
     "src/",
     "NOTICE.md"
   ],
-  "scripts": {
-    "build": "tsc",
-    "test": "node scripts/run-tests.mjs",
-    "sync": "node scripts/sync-skill.mjs",
-    "prepare": "node scripts/sync-skill.mjs"
-  },
   "keywords": [
     "design-system",
     "design-tokens",
@@ -45,7 +39,12 @@
     "marked": "^18.0.0"
   },
   "optionalDependencies": {
-    "@monoes/monobrowse": "^1.0.6",
+    "@monoes/monobrowse": "^1.0.7",
     "puppeteer": "^25.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node scripts/run-tests.mjs",
+    "sync": "node scripts/sync-skill.mjs"
   }
-}
+}

package/skill/reference/hooks.md

@@ -10,7 +10,7 @@ Declare server-side template extensions under **`detector.extensions`** when the
 
 Manual `monomind design detect` scans use the same project filter config by default: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. `hook.enabled` only controls automatic hook execution, not manual CLI scans. Use `monomind design detect --no-config ...` for a raw detector run that ignores project config/context. Use `monomind design ignores ...` for direct CLI CRUD on the same detector ignores.
 
-Supported harnesses: Claude Code (`.claude/settings.local.json` in the project, which is gitignored so the hook stays machine-local; a hook you move into the shared `settings.json` is honored in place too), Codex (`.codex/hooks.json` in the project), Cursor (`.cursor/hooks.json` in the project), and GitHub Copilot (`.github/hooks/monodesign.json` in the project, a team-shared committed file that both the Copilot CLI and the cloud agent read). For the Copilot CLI, repo-level hooks fire once `.github/hooks/monodesign.json` is committed to the repository's default branch.
+Supported harnesses: Claude Code (`.claude/settings.local.json` in the project, which is gitignored so the hook stays machine-local; a hook you move into the shared `settings.json` is honored in place too), Codex (`.codex/config.toml` in the project), Cursor (`.cursor/hooks.json` in the project), and GitHub Copilot (`.github/hooks/monodesign.json` in the project, a team-shared committed file that both the Copilot CLI and the cloud agent read). For the Copilot CLI, repo-level hooks fire once `.github/hooks/monodesign.json` is committed to the repository's default branch.
 
 On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
 
@@ -84,7 +84,7 @@ node {{scripts_path}}/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
 - Never modify `.monodesign/config.json` or `.monodesign/config.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent. One exception: `detector.extensions` has no admin action, so when the user asks to cover a template stack, edit that one field in `.monodesign/config.json` directly and leave the rest of the file untouched.
 - Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
 - Cursor can block a proposed write when the detector finds a real issue. Claude Code, Codex, and GitHub Copilot do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
-- The hook is bundled with the Monodesign skill and installed through project-local manifests: `.claude/settings.local.json`, `.codex/hooks.json`, `.cursor/hooks.json`, and `.github/hooks/monodesign.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads `.github/hooks/monodesign.json` once it is committed to the repository's default branch, and the cloud agent reads it from the repo directly.
+- The hook is bundled with the Monodesign skill and installed through project-local manifests: `.claude/settings.local.json`, `.codex/config.toml`, `.cursor/hooks.json`, and `.github/hooks/monodesign.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads `.github/hooks/monodesign.json` once it is committed to the repository's default branch, and the cloud agent reads it from the repo directly.
 
 ## Failure modes
 

package/skill/scripts/hook-admin.mjs

@@ -74,24 +74,20 @@ const HOOK_MANIFEST_TARGETS = [
   {
     provider: '.agents',
     skillRel: '.agents/skills/monodesign',
-    destRel: '.codex/hooks.json',
-    manifest: () => ({
-      hooks: {
-        PostToolUse: [
-          {
-            matcher: 'Edit|Write|apply_patch',
-            hooks: [
-              {
-                type: 'command',
-                command: 'node ".agents/skills/monodesign/scripts/hook.mjs"',
-                timeout: TIMEOUT_SECONDS,
-                statusMessage: STATUS_MESSAGE,
-              },
-            ],
-          },
-        ],
-      },
-    }),
+    destRel: '.codex/config.toml',
+    format: 'toml',
+    manifest: () => [
+      '# monodesign:start native-hook',
+      '[[hooks.PostToolUse]]',
+      'matcher = "Edit|Write|apply_patch"',
+      '[[hooks.PostToolUse.hooks]]',
+      'type = "command"',
+      'command = "node .agents/skills/monodesign/scripts/hook.mjs"',
+      `timeout = ${TIMEOUT_SECONDS}`,
+      `statusMessage = "${STATUS_MESSAGE}"`,
+      '# monodesign:end native-hook',
+      '',
+    ].join('\n'),
   },
   {
     provider: '.cursor',
@@ -335,6 +331,19 @@ function repairHookManifests(cwd) {
     const dest = path.join(cwd, target.destRel);
     const sharedDest = target.sharedDestRel ? path.join(cwd, target.sharedDestRel) : null;
 
+    if (target.format === 'toml') {
+      const current = fs.existsSync(dest) ? safeReadText(dest) : '';
+      const next = mergeCodexHookConfig(current || '', target.manifest());
+      if (current === next) {
+        result.already.push(target.provider);
+        continue;
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, next);
+      result.written.push(target.provider);
+      continue;
+    }
+
     if (sharedDest && fileHasMonodesignHookMarker(sharedDest)) {
       pruneMonodesignHookFromManifest(dest);
       result.already.push(target.provider);
@@ -366,6 +375,30 @@ function repairHookManifests(cwd) {
   return result;
 }
 
+function mergeCodexHookConfig(existing, hookBlock) {
+  const completeBlock = /# monodesign:start native-hook[\s\S]*?# monodesign:end native-hook\n?/m;
+  const incompleteBlock = /# monodesign:start native-hook[\s\S]*$/m;
+  let merged = existing;
+  if (completeBlock.test(merged)) merged = merged.replace(completeBlock, hookBlock);
+  else if (incompleteBlock.test(merged)) merged = merged.replace(incompleteBlock, hookBlock);
+  else merged = `${merged.trimEnd()}${merged.trim() ? '\n\n' : ''}${hookBlock}`;
+  return enableCodexHooks(merged);
+}
+
+function enableCodexHooks(config) {
+  if (!/^\[features\]\s*$/m.test(config)) {
+    return `[features]\nhooks = true\n\n${config}`;
+  }
+  const lines = config.split(/\r?\n/);
+  const start = lines.findIndex((line) => /^\[features\]\s*$/.test(line));
+  let end = start + 1;
+  while (end < lines.length && !/^\[\[?[^\]]+\]\]?\s*$/.test(lines[end])) end++;
+  const hookIndex = lines.slice(start + 1, end).findIndex((line) => /^hooks\s*=/.test(line));
+  if (hookIndex === -1) lines.splice(end, 0, 'hooks = true');
+  else lines[start + 1 + hookIndex] = 'hooks = true';
+  return lines.join('\n');
+}
+
 function safeReadText(filePath) {
   try {
     return fs.readFileSync(filePath, 'utf-8');

package/skill/scripts/live/sveltekit-adapter.mjs

@@ -36,14 +36,17 @@ export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   };
 }
 
-export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, config = null } = {}) {
+export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, authCred, config = null } = {}) {
   if (!Number.isFinite(Number(port))) {
     throw new Error('SvelteKit live adapter requires a numeric port');
   }
+  if (!authCred) {
+    throw new Error('SvelteKit live adapter requires an auth credential');
+  }
   const detected = detectSvelteKitProject(cwd, config);
   if (!detected) return null;
 
-  ensureSvelteLiveRootComponent(cwd, Number(port));
+  ensureSvelteLiveRootComponent(cwd, Number(port), authCred);
 
   const layoutRel = detected.layoutFile;
   const layoutAbs = path.join(cwd, layoutRel);
@@ -136,18 +139,20 @@ export function unpatchSvelteLayout(content) {
   return out.replace(/\n{3,}/g, '\n\n');
 }
 
-export function ensureSvelteLiveRootComponent(cwd, port) {
+export function ensureSvelteLiveRootComponent(cwd, port, authCred) {
   const file = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, buildSvelteLiveRootComponent(port), 'utf-8');
+  fs.writeFileSync(file, buildSvelteLiveRootComponent(port, authCred), 'utf-8');
   return file;
 }
 
-export function buildSvelteLiveRootComponent(port) {
+export function buildSvelteLiveRootComponent(port, authCred) {
+  const authQuery = new URLSearchParams();
+  authQuery.set('token', String(authCred ?? ''));
   return `<script>
   import { onMount } from 'svelte';
 
-  const LIVE_URL = 'http://localhost:${Number(port)}/live.js';
+  const LIVE_URL = 'http://localhost:${Number(port)}/live.js?${authQuery.toString()}';
   const HOST_ID = 'monodesign-live-root';
 
   onMount(() => {

package/skill/scripts/live-inject.mjs

@@ -16,7 +16,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveLiveConfigPath } from './lib/monodesign-paths.mjs';
+import { resolveLiveConfigPath, readLiveServerInfo } from './lib/monodesign-paths.mjs';
 import {
   applySvelteKitLiveAdapter,
   detectSvelteKitProject,
@@ -27,6 +27,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
 const MARKER_OPEN_TEXT = 'monodesign-live-start';
 const MARKER_CLOSE_TEXT = 'monodesign-live-end';
+// Query param name live-server.mjs checks on every protected route.
+const AUTH_QUERY_KEY = 'token';
 const IGNORE_MARKER_OPEN = '# monodesign-live-ignore-start';
 const IGNORE_MARKER_CLOSE = '# monodesign-live-ignore-end';
 
@@ -145,10 +147,19 @@ Output (JSON):
     console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
     process.exit(1);
   }
+  // The injected tag must authenticate like every other server route does —
+  // read the per-process credential live-server.mjs persisted at startup.
+  const liveInfo = readLiveServerInfo(process.cwd());
+  const credentialFields = liveInfo?.info ?? {};
+  const authCred = credentialFields['token'];
+  if (!authCred) {
+    console.error(JSON.stringify({ ok: false, error: 'missing_auth_credential', detail: 'no running live server info found for this project — start it before injecting' }));
+    process.exit(1);
+  }
   const gitIgnore = ensureLiveGitIgnores(process.cwd());
 
   if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
+    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, authCred, config });
     console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
     return;
   }
@@ -158,7 +169,7 @@ Output (JSON):
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile);
+    const withTag = insertTag(withoutOld, config, port, authCred, relFile);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
@@ -356,16 +367,18 @@ function validateConfig(cfg) {
 function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
 function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
 
-function buildTagBlock(syntax, port, filePath) {
+function buildTagBlock(syntax, port, authCred, filePath) {
   const open = commentOpen(syntax);
   const close = commentClose(syntax);
   // Astro processes <script> tags by default and rewrites src to its own
   // bundled URL. is:inline opts out so the literal external src survives.
   const isAstro = typeof filePath === 'string' && filePath.endsWith('.astro');
   const scriptAttrs = isAstro ? 'is:inline ' : '';
+  const authQuery = new URLSearchParams();
+  authQuery.set(AUTH_QUERY_KEY, authCred);
   return (
     open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="http://localhost:' + port + '/live.js"></script>\n' +
+    '<script ' + scriptAttrs + 'src="http://localhost:' + port + '/live.js?' + authQuery.toString() + '"></script>\n' +
     open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
   );
 }
@@ -387,9 +400,9 @@ function readLineEndingAt(content, index) {
   return '';
 }
 
-function insertTag(content, config, port, filePath) {
+function insertTag(content, config, port, authCred, filePath) {
   const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath), lineEnding);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, authCred, filePath), lineEnding);
   // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
   // belong at the end, and the same literal can appear earlier in code blocks
   // within rendered documentation pages.

package/skill/scripts/live-server.mjs

@@ -63,6 +63,8 @@ const DESIGN_MD_PATH = PROJECT_CONTEXT.designPath
   : null;
 const DEFAULT_POLL_TIMEOUT = 600_000;   // 10 min — agent re-polls on timeout anyway
 const SSE_HEARTBEAT_INTERVAL = 30_000;  // keepalive ping every 30s
+// Query param name every protected route checks against the per-process credential.
+const AUTH_QUERY_KEY = 'token';
 
 // ---------------------------------------------------------------------------
 // Port detection
@@ -383,6 +385,20 @@ function statOrNull(filePath) {
   try { return fs.statSync(filePath); } catch { return null; }
 }
 
+// Shared gate for every protected route, including /live.js (see its call
+// site for why that one needs it too). Writes the 401 itself and returns
+// false so callers can `if (!requireAuthQueryCred(url, res)) return;`.
+function requireAuthQueryCred(url, res) {
+  const provided = url.searchParams.get(AUTH_QUERY_KEY);
+  const expected = state[AUTH_QUERY_KEY];
+  if (provided !== expected) {
+    res.writeHead(401);
+    res.end('Unauthorized');
+    return false;
+  }
+  return true;
+}
+
 // HTTP request handler
 // ---------------------------------------------------------------------------
 
@@ -398,6 +414,15 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
 
     // --- Scripts ---
     if (p === '/live.js') {
+      // This response embeds the shared bearer credential (below) — unlike
+      // /detect.js and the vendored scripts, it must be gated the same way
+      // every OTHER protected route already is. Without this, requesting this
+      // one route defeats every other route's check: whoever fetches it walks
+      // away with the value that's supposed to distinguish the legitimate
+      // preview tab from any other page. See requireAuthQueryCred() below —
+      // callers must supply the credential the running server printed at
+      // startup (also mirrored into the live-server info file for tooling).
+      if (!requireAuthQueryCred(url, res)) return;
       // Re-read from disk each request so edits to live-browser.js land on
       // the next tab reload. No-store headers prevent browser caching across
       // sessions — during iteration, a cached old script silently breaks
@@ -604,8 +629,19 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
       if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
       const filePath = url.searchParams.get('path');
       if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
-      const absPath = path.resolve(process.cwd(), filePath);
-      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
+      // Resolve symlinks on BOTH sides before comparing: a lexical prefix check
+      // (path.resolve + startsWith) can't tell a symlink that lexically resolves
+      // inside cwd from one that physically points outside it, and startsWith on
+      // its own also has no path-boundary — "/proj-evil" lexically "starts with"
+      // "/proj". realpath + path.relative closes both gaps (the same pattern
+      // already used correctly elsewhere in this package).
+      let root, absPath;
+      try {
+        root = fs.realpathSync(process.cwd());
+        absPath = fs.realpathSync(path.resolve(process.cwd(), filePath));
+      } catch { res.writeHead(404); res.end('File not found'); return; }
+      const rel = path.relative(root, absPath);
+      if (rel.startsWith('..') || path.isAbsolute(rel)) { res.writeHead(403); res.end('Forbidden'); return; }
       let content;
       try { content = fs.readFileSync(absPath, 'utf-8'); }
       catch { res.writeHead(404); res.end('File not found'); return; }