@catchdrift/cli 0.1.18 → 0.1.20

package/commands/drift-sync.md

@@ -0,0 +1,229 @@
+---
+description: "Sync Figma and/or Storybook into drift.config.ts and regenerate CLAUDE.md, .cursorrules, and .windsurfrules. Run after adding new DS components or updating Figma."
+allowed-tools: Read, Glob, Grep, Bash, Edit, Write
+argument-hint: "[figma | storybook | tokens | status | --dry-run]"
+disable-model-invocation: true
+---
+
+# /drift-sync — Sync Figma + Storybook → update manifest
+
+Pull the latest component state from Figma and/or Storybook and keep
+`drift.config.ts`, `CLAUDE.md`, `.cursorrules`, and `.windsurfrules` in sync.
+Works with any product team — property management, SaaS, fintech, consumer, B2B.
+
+## Arguments: `$ARGUMENTS`
+- *(no args)* — sync from both Storybook and Figma, update all config files
+- `figma`     — pull component list from Figma only (all pages)
+- `storybook` — re-discover components from Storybook index only
+- `tokens`    — run figma-sync (design tokens + icons only, no component changes)
+- `status`    — report sync status without making changes (safe read-only audit)
+- `--dry-run` — show what would change without writing any files
+
+---
+
+## Step 1 — Read current state
+
+Read `drift.config.ts` (or `src/ds-coverage/config.ts`) to get:
+- **Figma source** — the config may use either shape:
+  - Single file: `figmaFileKey` + optional `figmaComponentPages` (one-file setup)
+  - Multi-file: `figmaFiles: [{ key: string, componentPages?: string[] }, ...]` (components spread across multiple Figma files, e.g. Core DS, Icons, Patterns)
+  - Normalise both into a working array: `const files = config.figmaFiles ?? (config.figmaFileKey ? [{ key: config.figmaFileKey, componentPages: config.figmaComponentPages }] : [])`
+- `storybookUrl`
+- `components` — the current registry (component name → storyPath / figmaLink)
+- `threshold`
+- Any `approvedGaps` entries
+
+**Component pages** are an inclusive filter — only pull components from these pages. If `componentPages` is not set for a file, include all pages (and flag any page whose name contains "wip", "in progress", "draft", "proposal", "graveyard", or "archive" as potentially unready so the team can review them).
+
+---
+
+## Step 2 — Dispatch
+
+### `status` → Read-only audit
+
+Report sync status across all sources without changing anything:
+
+```
+## Drift Sync Status — <date>
+
+Storybook: <storybookUrl>
+  Last successful sync: <date if known, else "unknown">
+  Reachable: ✅ / ❌
+
+Figma files: <N> configured
+  figma.com/design/<key1>  Reachable: ✅ / ❌
+  figma.com/design/<key2>  Reachable: ✅ / ❌   (if multi-file)
+  FIGMA_API_TOKEN: ✅ set / ❌ missing
+
+Config: drift.config.ts
+  Components registered: N
+  Missing storyPath: N
+  Missing figmaLink: N
+  Approved gaps: N
+
+AI rules files:
+  CLAUDE.md: ✅ / ❌ (stale — last component: <X>)
+  .cursorrules: ✅ / ❌
+  .windsurfrules: ✅ / ❌
+```
+
+---
+
+### `tokens` or no args → sync tokens from Figma
+
+Run:
+```bash
+npm run figma-sync
+```
+
+Requires `FIGMA_API_TOKEN`. If missing:
+```
+export FIGMA_API_TOKEN=your-token
+npm run figma-sync
+
+Get token: figma.com → Profile → Settings → Security → Personal access tokens
+```
+
+After running, report which token categories updated (colors added/changed, typography changes, spacing changes).
+
+---
+
+### `storybook` or no args → re-discover from Storybook
+
+Fetch `{storybookUrl}/index.json`. The response has a flat map of all stories
+across all story files. Parse it to get unique component names and story paths.
+
+If Storybook isn't reachable, try the deployed URL (`chromaticUrl`) from config. If
+neither is reachable, report:
+```
+⚠️  Storybook not reachable at <url>
+Run `npm run storybook` first, or provide your deployed Storybook URL in drift.config.ts:
+  chromaticUrl: 'https://main--abc123.chromatic.com'
+```
+
+Compare against `config.components` and report:
+
+```
+## Storybook sync
+
+New (in Storybook, not in config):
+  + DataTable    → story: data-table--default
+  + FilterBar    → story: filters-filter-bar--default
+
+Removed (in config, no matching story):
+  - OldWidget
+
+Unchanged: 34 components
+```
+
+Ask for each new/removed component before changing config. For removed components,
+ask whether to delete from config or keep with a `deprecated: true` flag.
+
+---
+
+### `figma` or no args → pull all published components from Figma
+
+**Key:** Figma components live on different pages. Use the dedicated
+`/components` endpoint — it returns ALL published components across ALL pages
+with page metadata included. Do NOT try to walk the file tree page by page.
+
+Iterate over every file in the normalised `files` array (see Step 1). For each:
+```
+GET https://api.figma.com/v1/files/{file.key}/components
+Headers: X-Figma-Token: {FIGMA_API_TOKEN}
+```
+
+Each component in the response has:
+- `name` — full path e.g. `"Button/Primary/Default"` or `"Forms/Input/Filled"`
+- `node_id` — unique ID for building the figmaLink URL
+- `containing_frame.name` — the frame it lives in
+- `containing_frame.pageName` — **the Figma page it's on**
+- `description` — designer's notes (preserve this — use as component description in config)
+
+Group and display results by file, then by page within each file. If multiple files are configured, prefix each section with the file key/URL so it's clear which file the components come from:
+```
+## Figma components found
+
+### figma.com/design/<key1>  (Core DS)
+📄 Primitives (12 components)
+  ✅ Button         → in config
+  ✅ Input          → in config
+  ❌ Toggle         → NOT in config  (node: 123:456)
+  ❌ Checkbox       → NOT in config  (node: 123:789)
+
+📄 🚧 In Progress (3 components)
+  ⚠️  SearchBar     → draft (will not be added)
+  ⚠️  FilterChip    → draft (will not be added)
+
+### figma.com/design/<key2>  (Icons & Patterns)
+📄 Patterns (8 components)
+  ✅ TenantsTable   → in config
+  ❌ DataGrid       → NOT in config  (node: 456:123)
+```
+
+For each file, apply the `componentPages` filter:
+- If `componentPages` is set: only include components from those pages; skip everything else
+- If not set: include all pages, but flag any page matching "wip/draft/graveyard/archive/proposal" in a separate "Unreviewed pages" section so the team can decide whether to add them
+
+For each component NOT in config (excluding draft pages), ask:
+```
+Add these to drift.config.ts?
+  - Toggle   (key1 / Primitives page)
+  - Checkbox (key1 / Primitives page)
+  - DataGrid (key2 / Patterns page)
+
+For each, I'll also add the figmaLink pointing to that node.
+Reply with which ones to add, or "all" / "none".
+```
+
+When adding, build the figmaLink URL using the file key that component came from:
+```
+https://www.figma.com/design/{file.key}?node-id={node_id}
+```
+
+Also report components in the codebase (from static scan of `src/`) that exist
+in Storybook but have NO matching Figma component — these are code-first gaps:
+```
+In code but not in Figma (consider pushing to Figma):
+  ⚡ OccupancyWidget  — used 1× — run /drift-push OccupancyWidget to add
+  ⚡ FMKPIRow         — used 1×
+```
+
+---
+
+## Step 3 — Update files
+
+After confirmation (or immediately if `--dry-run` was NOT passed), update:
+
+1. **`drift.config.ts`** — add components with storyPath + figmaLink where available; mark removed with `deprecated: true` rather than deleting (preserves history)
+2. **`CLAUDE.md`** — regenerate only the components table (preserve all other content — rules, workflow, etc.)
+3. **`.cursorrules`** — same regeneration (Cursor reads this automatically)
+4. **`.windsurfrules`** — same regeneration (Windsurf reads this automatically); create if it doesn't exist
+
+For AI rules files, regenerate ONLY the component table section, bounded by these markers:
+```
+<!-- drift:components-start -->
+...
+<!-- drift:components-end -->
+```
+If markers don't exist, append the table at the end of the file.
+
+Report:
+```
+## Sync complete — <date>
+
+drift.config.ts   — +3 added, 0 deprecated (37 total)
+CLAUDE.md         — components table updated (37 components)
+.cursorrules      — components table updated
+.windsurfrules    — created (37 components)
+
+New figmaLinks added: Toggle, Checkbox, DataGrid
+New storyPaths added: DataTable, FilterBar
+
+Storybook links: 37/37 ✅
+Figma links: 31/37 (6 missing — run /drift-push gaps to add them)
+
+Next: npm run dev and press D to see the updated overlay.
+```
+
+If `--dry-run` was passed, show what would change without writing anything.

package/commands/drift.md

@@ -0,0 +1,252 @@
+---
+description: "Analyze DS coverage across the codebase. Find gaps, suggest DS replacements, migrate components, approve exceptions, promote candidates. Sub-commands: fix, approve, promote, manifest, check, history, audit."
+allowed-tools: Read, Glob, Grep, Bash, Edit
+argument-hint: "[fix <ComponentName> | approve <Name> \"<reason>\" | promote <Name> | manifest | check | history | audit]"
+---
+
+# /drift — Design System Drift Analyzer
+
+Analyze design system coverage for this codebase. Identify components that drift from
+the DS, suggest replacements, and optionally migrate code. Works with any React
+product team — property management, SaaS, fintech, e-commerce, etc.
+
+## Arguments: `$ARGUMENTS`
+
+Supported sub-commands:
+- *(no args)* — full coverage report + top gap analysis
+- `fix <ComponentName>` — migrate one custom component to its DS equivalent
+- `approve <ComponentName> "<rationale>"` — approve a gap with documented rationale
+- `promote <ComponentName>` — flag a high-frequency custom component for DS promotion
+- `manifest` — print the DS component registry with story + Figma links
+- `check` — run the headless drift-check script and parse results
+- `history` — show coverage trend over last N scans (from saved reports)
+- `audit` — full audit mode: coverage + token violations + rationale gaps + promotion candidates
+
+---
+
+## Step 1 — Read the DS registry
+
+Read `src/ds-coverage/config.ts` (or `drift.config.ts` at project root) to understand:
+- Every registered DS component, its story path, and Figma link
+- `threshold` — the CI pass/fail threshold
+- `storybookUrl` and `figmaFileKey`
+
+---
+
+## Step 2 — Dispatch on $ARGUMENTS
+
+### No arguments → Full Coverage Report
+
+1. Glob `src/**/*.tsx` (excluding `src/stories/`, `src/tokens/`, `node_modules/`, `*.stories.*`, `*.test.*`, `*.spec.*`) to find all screens, views, and feature files.
+2. Grep each file for JSX component usage. Classify every component as:
+   - **DS** — name is in `config.components`
+   - **Approved gap** — custom, but has an approval entry (check for `// drift-approved:` comment or approval record)
+   - **Custom** — name is not in `config.components` and not approved
+3. Compute per-file and overall DS coverage %.
+4. List the top custom components by frequency (the gap map).
+5. For any custom component used ≥ 3 times:
+   - Check whether a DS equivalent exists → suggest it
+   - If used ≥ 5 times → flag as **promotion candidate**
+6. Print a report in this format:
+
+```
+## Drift Report — <date>
+
+Overall DS coverage: XX% (threshold: XX%)
+Status: ✅ PASS  or  🔴 FAIL
+
+### By file
+| File | DS | Custom | Approved | Coverage |
+|------|----|--------|----------|----------|
+| ...  | .. | ...    | ...      | ...%     |
+
+### Top gaps (custom components not in DS)
+| Component | Uses | Status | Suggested DS replacement |
+|-----------|------|--------|--------------------------|
+| BtnGrp    | 6    | ⚠️ Gap  | Use `<Tabs>` (segmented variant) |
+| LinkBtn   | 5    | 🔁 Promote candidate | Use `<Button variant="ghost">` |
+| AvatarRow | 3    | ✅ Approved — "needed for nav micro-interaction" | — |
+
+### Token violations
+| File | Violation | Line |
+|------|-----------|------|
+| ... | Hardcoded `#3b82f6` — use `var(--ds-color-brand-500)` | 42 |
+
+### Promotion candidates (used ≥5× with no DS equivalent)
+These components appear frequently enough to justify adding to the DS:
+1. <ComponentName> — used N× across N files
+   → Run `/drift promote <ComponentName>` to create a promotion request
+
+### Recommendations
+1. Highest impact: migrate <X> → saves N% coverage across N files
+2. ...
+```
+
+---
+
+### `fix <ComponentName>`
+
+1. Find all usages of `<ComponentName>` across `src/` (excluding stories and tests).
+2. Read the DS equivalent component file to understand its props API.
+3. For each usage, generate a code diff that replaces the custom component with the DS component, preserving existing behavior.
+4. Show a summary first:
+   ```
+   Found 6 usages of <ComponentName> across 3 files.
+   DS equivalent: <DSName> — props mapping:
+     old.size="large"  → new.size="lg"
+     old.color="red"   → new.variant="danger"
+
+   Estimated coverage improvement: +2.3%
+
+   Apply changes? (yes/no/preview)
+   ```
+5. After applying, re-run coverage calculation and show before/after.
+
+---
+
+### `approve <ComponentName> "<rationale>"`
+
+Approve a custom component as an intentional exception to DS coverage rules.
+
+Use this when a custom component is genuinely needed and cannot be replaced by a DS component. Rationale must include:
+- Why no DS component covers this need
+- Whether it should be proposed for DS inclusion in the future
+
+1. Verify the component is actually used in the codebase.
+2. Check it's not already approved.
+3. Add an approval entry to `drift.config.ts`:
+   ```ts
+   approvedGaps: {
+     '<ComponentName>': {
+       rationale: '<rationale>',
+       approvedBy: '<ask for name>',
+       approvedAt: '<today ISO date>',
+       promoteToDS: true/false,  // ask: "Should this be proposed for DS inclusion?"
+     }
+   }
+   ```
+4. Also add an inline comment convention to the usage site so rationale travels with the code:
+   ```tsx
+   {/* drift:ignore reason="<rationale>" approvedBy="<name>" */}
+   <ComponentName ... />
+   ```
+   This is visible in code review without needing to cross-reference config.
+5. Confirm: "Approved. This component will show as ✅ Approved in drift reports and will not count against coverage."
+
+---
+
+### `promote <ComponentName>`
+
+Flag a high-frequency custom component as a DS promotion candidate.
+
+1. Read the component file (or search for it if it's a one-off inline component).
+2. Count its usage frequency and list the files it appears in.
+3. Generate a promotion brief:
+   ```
+   ## DS Promotion Request: <ComponentName>
+
+   **Usage:** N× across N files
+   **Files:** list up to 5 most common locations
+
+   **Props API (current):**
+   <extracted interface or inferred from usage>
+
+   **Suggested DS entry:**
+   <ComponentName>: {
+     storyPath: '<suggested-story-path>',
+   }
+
+   **Design request:** This component appears frequently enough to warrant a
+   Figma design + DS review. Recommend filing a design request.
+
+   Next steps:
+   1. Designer creates the spec in Figma
+   2. Run /drift-push <ComponentName> to attach implementation notes
+   3. After Figma review, run /drift-sync to register it officially
+   ```
+4. Ask if user wants to open a Jira ticket (if `jiraBaseUrl` is configured).
+
+---
+
+### `manifest`
+
+Print a formatted table of all DS components from `config.components`:
+
+```
+## DS Component Registry — <date>
+
+| Component          | Story | Figma | Status |
+|--------------------|-------|-------|--------|
+| Button             | ✅    | ✅    | Stable |
+| Tabs               | ✅    | —     | Needs Figma |
+| ...                | ...   | ...   | ...    |
+
+Approved gaps (N):
+| Component    | Rationale | Approved by |
+|--------------|-----------|-------------|
+| CustomHeader | "..." | Michelle, 2026-01-15 |
+
+Missing story paths: X components
+Missing Figma links: X components
+Run /drift-sync to fill gaps automatically.
+```
+
+---
+
+### `check`
+
+Run the headless drift check and parse results:
+
+```bash
+npm run build && npx vite preview --port 4173 &
+npx wait-on http://localhost:4173 --timeout 30000
+node scripts/drift-check.mjs --url http://localhost:4173 --json > /tmp/drift-report.json
+```
+
+Then read `/tmp/drift-report.json` and print the full report format including:
+- Coverage % vs threshold
+- Per-route breakdown
+- Token violations (hardcoded colors, spacing)
+- Gap map with promotion candidates
+
+---
+
+### `history`
+
+Read any saved `drift-report-*.json` files or GitHub Actions artifacts from `.github/`.
+Show coverage trend:
+
+```
+## Coverage History
+
+Date         Coverage   Delta    Status
+2026-03-30   78%        +2%      🔴 Below threshold
+2026-03-23   76%        +1%      🔴 Below threshold
+2026-03-16   75%        —        🔴 Below threshold
+
+Trend: ↑ improving (+3% over 3 weeks)
+At current rate, threshold (80%) reached in ~2 weeks.
+```
+
+---
+
+### `audit`
+
+Full audit combining all modes:
+1. Run `check` (headless scan)
+2. Run the static analysis (no-args path)
+3. Cross-reference: flag any component approved as a gap that now has a DS equivalent
+4. List components that have been custom for ≥ 30 days (from git log if available)
+5. Output a single comprehensive report suitable for a DS quarterly review
+
+---
+
+## Style rules for output
+
+- Lead with the numbers — coverage %, counts, file names
+- Use exact component names from the codebase (case-sensitive)
+- When suggesting a DS replacement, always show a before/after code snippet
+- If coverage is below threshold, surface the 3 highest-impact gaps first with estimated improvement per fix
+- Never suggest creating new components — only DS components from `config.components`
+- For teams unfamiliar with the DS, always explain *why* a replacement is better, not just *what* to use
+- Approved gaps always show ✅ and are excluded from failure calculations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catchdrift/cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "CLI for Drift — install, check, and manage design system coverage for any React app.",
   "keywords": [
     "design-system",
@@ -31,6 +31,7 @@
     "bin",
     "src",
     "scripts",
+    "commands",
     "LICENSE",
     "README.md"
   ],

package/src/commands/init.mjs

@@ -32,6 +32,7 @@ import {
 import {
   writeDriftConfig,
   writeAIRulesFiles,
+  writeClaudeSkills,
   patchAppEntry,
   writeGithubAction,
 } from '../lib/writers.mjs'
@@ -349,7 +350,8 @@ export async function init(argv) {
     storybookUrl: storybookUrl || '',
     figmaFiles:   figmaFiles.length ? figmaFiles : undefined,
   })
-  spinner.stop(`Written: ${rulesFiles.join(', ')}`)
+  const skillFiles = writeClaudeSkills(cwd)
+  spinner.stop(`Written: ${rulesFiles.join(', ')}${skillFiles.length ? ` + ${skillFiles.length} Claude skills` : ''}`)
 
   // ── Step 8: Install @catchdrift/overlay ──────────────────────────────────────
   const pkgJson = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'))
@@ -395,66 +397,72 @@ export async function init(argv) {
   console.log('')
   p.outro(pc.green('Drift is set up ✓'))
 
-  // Build next steps dynamically based on what was configured
-  const nextSteps = []
-
-  if (dsPackages?.length) {
-    nextSteps.push(`  ${pc.cyan('npx catchdrift sync')}   Auto-populate registry from ${dsPackages.join(', ')}`)
-  } else if (!sources.includes('storybook') || Object.keys(components).length === 0) {
-    nextSteps.push(`  ${pc.cyan('npx catchdrift sync')}   Auto-populate registry once you have a DS package`)
-  }
+  // ── What was set up (human-readable) ────────────────────────────────────────
+  const patchedShort = patched ? patched.replace(cwd + '/', '').replace(cwd, '') : null
+  console.log(`
+${pc.bold('What was set up:')}
+  ${pc.green('✓')} Overlay added to your app ${patchedShort ? pc.dim('(' + patchedShort + ')') : pc.yellow('— see manual step below')}
+  ${pc.green('✓')} AI rules written ${pc.dim('— your AI tools will use DS components by default')}
+  ${pc.green('✓')} Claude skills added ${pc.dim('— /drift-sync, /drift-scaffold, /drift-context, ...')}
+  ${addCI ? pc.green('✓') + ' GitHub check added ' + pc.dim('— every PR will show a coverage score') : pc.dim('○  GitHub check skipped')}`)
 
-  nextSteps.push(`  ${pc.cyan('npm run dev')}            Start your app, then press ${pc.bold('D')} to open Drift`)
-  nextSteps.push(`  ${pc.cyan('npx catchdrift check')}   Run a coverage scan ${pc.dim('(app must be running)')}`)
-  nextSteps.push(`  ${pc.cyan('git push')}               First PR will show a drift delta comment`)
+  // ── Immediate next step — specific to what was configured ───────────────────
+  console.log(`\n${pc.bold('Do this now:')}`)
 
-  if (!sources.includes('storybook') && !storybook.found) {
-    nextSteps.push(`\n  ${pc.yellow('Storybook not set up')} — run ${pc.bold('npx storybook@latest init')} when ready,`)
-    nextSteps.push(`  then re-run ${pc.bold('npx catchdrift init')} to complete the coverage loop.`)
-  }
+  if (figmaFiles.length > 0 && skillFiles.length > 0) {
+    console.log(`
+  Your components are in Figma. Pull them into the registry now:
 
-  console.log(`
-${pc.bold('What was created:')}
-  drift.config.ts                    ${pc.dim('DS component registry')}
-  ${rulesFiles.map(f => f.padEnd(34)).join('\n  ')}${pc.dim('AI constraints')}
-  ${addCI ? '.github/workflows/drift-check.yml  ' + pc.dim('CI drift check on every PR') : ''}
-  ${patched ? patched.padEnd(34) + pc.dim('DriftOverlay added (dev-only)') : ''}
-
-${pc.bold('Next steps:')}
-${nextSteps.join('\n')}
-
-${pc.bold('Your team\'s daily commands (Claude Code):')}
-  ${pc.blue('/drift-context')}    ${pc.dim('See DS state at a glance — run this first')}
-  ${pc.blue('/drift-prd')}        ${pc.dim('Generate a component inventory for a PRD')}
-  ${pc.blue('/drift-scaffold')}   ${pc.dim('Scaffold a new screen using only DS components')}
-  ${pc.blue('/drift check')}      ${pc.dim('Verify coverage before submitting a PR')}
-  ${pc.blue('/drift-sync')}       ${pc.dim('Re-sync registry after adding DS components')}
-  ${pc.blue('/drift fix <X>')}    ${pc.dim('Migrate a custom component to its DS equivalent')}
-
-${pc.dim('Docs: https://catchdrift.ai  ·  Issues: https://github.com/dyoon92/design-drift/issues')}
+  ${pc.cyan('1.')} Open ${pc.bold('Claude Code')} in this project folder
+  ${pc.cyan('2.')} Run: ${pc.blue('/drift-sync figma')}
+       This reads your Figma file and registers all your DS components.
+  ${pc.cyan('3.')} Run: ${pc.bold('npm run dev')}  →  press ${pc.bold('D')}  →  see live coverage
 `)
+  } else if (sources.includes('storybook') && Object.keys(components).length > 0) {
+    console.log(`
+  Your components were imported from Storybook ✓
 
-  if (!patched) {
-    console.log(`${pc.yellow('Manual step needed')} — add DriftOverlay to your app entry point:
+  ${pc.cyan('1.')} Run: ${pc.bold('npm run dev')}
+  ${pc.cyan('2.')} Press ${pc.bold('D')} to open the Drift overlay — you should see real coverage.
+`)
+  } else if (dsPackages?.length) {
+    console.log(`
+  ${pc.cyan('1.')} Run: ${pc.bold('npx catchdrift sync')}
+       Scans your codebase for imports from ${dsPackages.join(', ')} and registers them.
+  ${pc.cyan('2.')} Run: ${pc.bold('npm run dev')}  →  press ${pc.bold('D')}  →  see live coverage
+`)
+  } else {
+    console.log(`
+  ${pc.cyan('1.')} Run: ${pc.bold('npm run dev')}  →  press ${pc.bold('D')}  →  the overlay opens
+       Coverage will show 0% until you register your DS components.
+  ${pc.cyan('2.')} Add your components to ${pc.bold('drift.config.ts')} or connect a source:
+       • Figma:  re-run ${pc.bold('npx catchdrift init')} and select Figma
+       • npm:    add ${pc.bold('dsPackages')} to drift.config.ts, then run ${pc.bold('npx catchdrift sync')}
 `)
-    console.log(`  ${pc.dim('// src/main.tsx')}`)
-    console.log(`  import { DriftOverlay } from '@catchdrift/overlay'`)
-    console.log(`  import driftConfig from '../drift.config'`)
-    console.log('')
-    console.log(`  ${pc.dim('// Last child in your root render:')}`)
-    console.log(`  {import.meta.env.DEV && <DriftOverlay config={driftConfig} />}`)
-    console.log('')
   }
 
-  if (dsPackages?.length) {
-    console.log(`${pc.blue('Tip:')} Run ${pc.bold('npx catchdrift sync')} to auto-populate your component registry from ${dsPackages.join(', ')}.`)
-    console.log('')
+  // ── Ongoing daily commands ───────────────────────────────────────────────────
+  console.log(`${pc.bold('Daily workflow (Claude Code):')}
+  ${pc.blue('/drift-context')}     Check DS health — run this before starting work
+  ${pc.blue('/drift-scaffold')}    Build a new screen using only DS components
+  ${pc.blue('/drift-sync')}        Update registry after Figma or Storybook changes
+  ${pc.blue('npx catchdrift check')}   Check coverage before submitting a PR
+`)
+
+  if (!sources.includes('storybook') && !storybook.found) {
+    console.log(`${pc.yellow('Note:')} Storybook isn't set up yet. Run ${pc.bold('npx storybook@latest init')} when ready,`)
+    console.log(`  then re-run ${pc.bold('npx catchdrift init')} to complete the coverage loop.\n`)
   }
 
-  if (figmaFiles.length > 0) {
-    console.log(`${pc.blue('Tip:')} Open the Drift overlay (press D), go to Settings, and paste your Figma personal access token to enable Figma component sync.`)
-    console.log('')
+  if (!patchedShort) {
+    console.log(`${pc.yellow('Manual step needed')} — add the overlay to your app entry point:`)
+    console.log(`  import { DriftOverlay } from '@catchdrift/overlay'`)
+    console.log(`  import driftConfig from './drift.config'`)
+    console.log(`  // inside your root render, as the last child:`)
+    console.log(`  {import.meta.env.DEV && <DriftOverlay config={driftConfig} />}\n`)
   }
+
+  console.log(pc.dim('Docs: https://catchdrift.ai  ·  Issues: https://github.com/dyoon92/design-drift/issues'))
 }
 
 // ── Helpers ───────────────────────────────────────────────────────────────────