create-claude-cabinet 0.29.13 → 0.30.0

package/templates/handoff/schema.md

@@ -0,0 +1,92 @@
+# Handoff Checklist Schema
+
+The checklist YAML (`handoff.yaml`) defines what to collect from a client.
+It ships with the client's Claude Code plugin — the `/handoff` skill reads
+it and walks the client through each section conversationally.
+
+## Structure
+
+```yaml
+meta:
+  title: "Project Go-Live Credentials"   # shown to client at start
+  consultant: "Your Name"                 # who receives the credentials
+  public_key: "./keys/consultant.pub.jwk" # RSA public key for encryption
+
+transport:
+  type: email        # email | mcp | file
+  consultant: "you@example.com"   # client sends here
+  client: "client@example.com"    # consultant sends here
+
+sections:
+  - key: section_id
+    title: "Section Title"
+    items:
+      - key: item_id
+        prompt: "What the client sees"
+        kind: decide           # decide | provide | confirm | credential
+        options: [A, B, C]     # only for decide kind
+        help: "Optional help text"
+        visibility:
+          depends_on: other_item_key
+          value_in: [A, B]     # show this item only when parent matches
+```
+
+## Item Kinds
+
+| Kind | Captured via | Stored as | Use for |
+|------|-------------|-----------|---------|
+| `decide` | Conversation (choice) | Plaintext value | Decisions that drive visibility |
+| `provide` | Conversation (free text) | Plaintext value | Non-sensitive information |
+| `confirm` | Conversation (yes/no) | Boolean | Acknowledgments |
+| `credential` | OS dialog (hidden input) | Encrypted envelope ID | API keys, tokens, passwords |
+
+Credential values are captured through a secure OS dialog, encrypted
+immediately with the consultant's public key, and transported as opaque
+envelopes. The plaintext never enters Claude's context or Anthropic's API.
+
+## Visibility Rules
+
+Items with a `visibility` block are hidden until their dependency is met.
+Visibility is transitive: if B depends on A and C depends on B, hiding A
+hides both B and C.
+
+Cycles are rejected at load time (before any conversation starts). The
+checklist parser runs topological sort on the dependency graph and fails
+with a clear error if a cycle exists.
+
+## Transport Types
+
+**`email`** (default) — Auto-detects the connected email MCP server
+(Gmail, Outlook, etc.) and dispatches through it. Falls back to `file`
+if no email MCP is available.
+
+**`mcp`** — Calls a specific MCP tool to POST the encrypted payload.
+Requires additional config: `tool_name`, `payload_param`, `extra_params`.
+
+**`file`** — Writes encrypted envelopes to `./handoff-out/`. Also serves
+as automatic fallback when email transport has no MCP connected.
+
+## State File
+
+Progress is tracked in `handoff-state.json` (gitignored). Non-credential
+answers store the value directly. Credential items store only the
+envelope ID and delivery status — never the plaintext.
+
+```json
+{
+  "checklist": "handoff.yaml",
+  "started_at": "2026-05-30T12:00:00Z",
+  "updated_at": "2026-05-30T12:30:00Z",
+  "answers": {
+    "hosting_provider": {
+      "value": "Railway",
+      "answered_at": "2026-05-30T12:05:00Z"
+    },
+    "railway_token": {
+      "status": "sent",
+      "envelope_id": "env_abc123",
+      "sent_at": "2026-05-30T12:10:00Z"
+    }
+  }
+}
+```

package/templates/handoff/secure-input.mjs

@@ -0,0 +1,99 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export class DialogCancelledError extends Error {
+  constructor() { super('User cancelled dialog'); this.code = 'CANCELLED'; }
+}
+
+export class DialogUnavailableError extends Error {
+  constructor(platform) {
+    super(`No secure input dialog available on ${platform}`);
+    this.code = 'NO_DIALOG';
+    this.platform = platform;
+  }
+}
+
+export function detectPlatform() {
+  switch (process.platform) {
+    case 'darwin': return 'macos';
+    case 'win32': return 'windows';
+    default: return 'linux';
+  }
+}
+
+function escapeAppleScript(str) {
+  return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+async function captureViaMacOS(prompt) {
+  const escaped = escapeAppleScript(prompt);
+  const script = `display dialog "${escaped}" with hidden answer default answer ""`;
+  try {
+    const { stdout } = await execFileAsync('osascript', ['-e', script]);
+    const match = stdout.match(/text returned:(.*)/);
+    if (!match) throw new Error('Dialog returned no value');
+    return match[1].trim();
+  } catch (err) {
+    if (err.stderr?.includes('User canceled') || err.stderr?.includes('(-128)')) {
+      throw new DialogCancelledError();
+    }
+    throw err;
+  }
+}
+
+async function captureViaZenity(prompt) {
+  try {
+    const { stdout } = await execFileAsync('zenity', ['--password', '--title', prompt]);
+    return stdout.trim();
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new DialogUnavailableError('linux');
+    if (err.status === 1) throw new DialogCancelledError();
+    throw err;
+  }
+}
+
+async function captureViaTerminal(prompt) {
+  process.stderr.write('Warning: No GUI dialog available — falling back to terminal input.\n');
+  process.stderr.write('Input will NOT be masked. Ensure no one is looking at your screen.\n');
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  process.stderr.write(`${prompt}: `);
+  return new Promise((resolve) => {
+    rl.question('', (answer) => {
+      rl.close();
+      process.stderr.write('\n');
+      resolve(answer);
+    });
+  });
+}
+
+async function captureViaPowerShell(prompt) {
+  const escaped = prompt.replace(/'/g, "''");
+  const script = `$s = Read-Host -Prompt '${escaped}' -AsSecureString; [System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))`;
+  try {
+    const { stdout } = await execFileAsync('powershell', ['-Command', script]);
+    return stdout.trim();
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new DialogUnavailableError('windows');
+    throw err;
+  }
+}
+
+export async function captureSecureInput(prompt) {
+  const platform = detectPlatform();
+  switch (platform) {
+    case 'macos': return captureViaMacOS(prompt);
+    case 'windows': return captureViaPowerShell(prompt);
+    case 'linux': {
+      try {
+        return await captureViaZenity(prompt);
+      } catch (err) {
+        if (err instanceof DialogUnavailableError) return captureViaTerminal(prompt);
+        throw err;
+      }
+    }
+    default: throw new DialogUnavailableError(process.platform);
+  }
+}

package/templates/site-audit-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-cabinet/site-audit",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Comprehensive deployed-site quality audit engine for Claude Cabinet. Runs checks across performance, accessibility, security, SEO, content, DNS, and privacy against a deployed URL; single-site and comparison modes; standalone HTML report.",
   "type": "module",
   "bin": {

package/templates/site-audit-runtime/src/checks/axe-core.mjs

@@ -33,12 +33,19 @@ export function normalize(raw, durationMs) {
   }
 
   const violations = Array.isArray(data) ? data.flatMap(p => p.violations || []) : (data.violations || []);
-  const findings = violations.map(v => ({
-    severity: IMPACT_TO_SEVERITY[v.impact] || 'info',
-    message: v.description || v.id,
-    url: v.helpUrl || undefined,
-    context: v.nodes?.[0]?.html?.slice(0, 200) || undefined,
-  }));
+  const findings = violations.map(v => {
+    const targets = (v.nodes || []).slice(0, 3).map(n =>
+      (n.target || []).flat().join(' > ')
+    ).filter(Boolean);
+    return {
+      severity: IMPACT_TO_SEVERITY[v.impact] || 'info',
+      message: v.description || v.id,
+      url: v.helpUrl || undefined,
+      context: targets.length
+        ? `Elements: ${targets.join(', ')}${v.nodes?.length > 3 ? ` (+${v.nodes.length - 3} more)` : ''}`
+        : (v.nodes?.[0]?.html?.slice(0, 200) || undefined),
+    };
+  });
 
   const worstSev = findings.length ? findings.reduce((w, f) => {
     const o = { critical: 0, serious: 1, moderate: 2, info: 3 };

package/templates/site-audit-runtime/src/checks/lighthouse.mjs

@@ -59,7 +59,21 @@ export function normalize(raw, durationMs) {
     return (order[f.severity] ?? 3) < (order[w] ?? 3) ? f.severity : w;
   }, 'info') : null;
 
-  const details = { categories: scores };
+  const cwvKeys = {
+    'largest-contentful-paint': 'LCP',
+    'cumulative-layout-shift': 'CLS',
+    'first-contentful-paint': 'FCP',
+    'total-blocking-time': 'TBT',
+    'speed-index': 'Speed Index',
+    'interactive': 'TTI',
+  };
+  const metrics = {};
+  for (const [auditId, label] of Object.entries(cwvKeys)) {
+    const a = audits[auditId];
+    if (a?.displayValue) metrics[label] = a.displayValue;
+  }
+
+  const details = { categories: scores, ...(Object.keys(metrics).length && { metrics }) };
   const passSummary = Object.entries(scores)
     .map(([k, v]) => `${k.replace(/-/g, ' ')}: ${v}`)
     .join(', ');

package/templates/site-audit-runtime/src/checks/pa11y.mjs

@@ -28,8 +28,8 @@ export function normalize(raw, durationMs) {
   const findings = issues.map(i => ({
     severity: TYPE_TO_SEVERITY[i.type] || 'info',
     message: i.message || i.code || 'unknown',
-    context: i.context?.slice(0, 200) || undefined,
-    url: i.selector || undefined,
+    context: [i.code, i.selector ? `Element: ${i.selector}` : null].filter(Boolean).join(' — ') || undefined,
+    url: i.context?.slice(0, 150) || undefined,
   }));
 
   const errors = findings.filter(f => f.severity === 'serious' || f.severity === 'critical').length;

package/templates/site-audit-runtime/src/report.mjs

@@ -132,6 +132,13 @@ function renderDetails(result) {
     });
     html += `<div style="margin-bottom:.75rem;font-size:.9rem">${items.join('')}</div>`;
   }
+  const metrics = result.details.metrics;
+  if (metrics && typeof metrics === 'object') {
+    const items = Object.entries(metrics).map(([label, value]) =>
+      `<span style="display:inline-block;margin-right:1.2rem"><strong>${esc(label)}</strong> ${esc(String(value))}</span>`
+    );
+    html += `<div style="margin-bottom:.75rem;font-size:.85rem;color:#555">Core Web Vitals: ${items.join('')}</div>`;
+  }
   const types = result.details.types;
   if (Array.isArray(types) && types.length) {
     html += `<div style="margin-bottom:.75rem;font-size:.85rem;color:#555">Schema types: ${types.map(t => `<strong>${esc(String(t))}</strong>`).join(', ')}</div>`;

package/templates/skills/cabinet-mantine-quality/SKILL.md

@@ -348,3 +348,24 @@ field-feedback. The CC maintainer adds it to this section. Project-specific
 patterns that don't generalize stay in `patterns-project.md`.
 
 <!-- Universal patterns below this line -->
+
+### Collapse with `in={true}` on mount renders invisible children
+
+**Pattern:** `<Collapse in={expr}>` where `expr` is truthy on initial
+render. Children exist in the DOM but have height 0 — completely
+invisible. Mantine's Collapse animates from closed→open, so mounting
+already-open skips the animation and the height never resolves.
+
+**Detection:** Flag any `<Collapse in={...}>` where the `in` prop can
+be truthy on first render — e.g., `in={data.length > 0}`, `in={true}`,
+`in={!!initialValue}`. Static `in={false}` or state that starts false
+(`useState(false)`) is safe.
+
+**Fix:** Replace `<Collapse in={opened}>...</Collapse>` with conditional
+rendering: `{opened && <>...</>}`. Use Collapse only when you need the
+open/close animation from a user interaction, not for initial-render
+conditional display.
+
+**Source:** claudeconsult-maginnis, 2026-05-30. Legal theory edit form's
+"Default Content" section auto-expanded when data existed but all fields
+were invisible. Required Playwright DOM inspection to diagnose.

package/templates/skills/handoff/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: handoff
+description: |
+  Walk through a consultant's handoff checklist conversationally. Collects
+  decisions, information, and credentials from the client with progressive
+  disclosure. Credentials are captured via secure OS dialog and encrypted
+  before Claude ever sees them. Use when: "handoff", "/handoff", or the
+  client needs to provide go-live credentials and configuration.
+manual: true
+---
+
+# /handoff — Complete Your Checklist
+
+## Purpose
+
+Walk the client through a structured checklist their consultant prepared.
+Each item is asked conversationally — decisions drive which follow-up
+items appear, credentials are captured securely, and progress is saved
+so the client can leave and come back.
+
+## Workflow
+
+### 1. Load and Validate
+
+1. Locate `handoff.yaml` — check in order:
+   a. Path provided as argument (the plugin's `/handoff` skill passes
+      the absolute path to the config — this is the primary path for
+      plugin-based handoffs)
+   b. Project root: `./handoff.yaml`
+   Use the first match found.
+   - **Missing:** "No handoff.yaml found — has the plugin been installed?"
+   - **Malformed:** Run validation via `handoff-checklist.mjs` and surface
+     specific errors before conversation starts.
+   - **Cycle detected:** "This checklist has a circular dependency between
+     [keys] — contact your consultant to fix it."
+   - **Public key missing:** Resolve `meta.public_key` relative to the
+     directory containing `handoff.yaml`. Check that it exists. A missing
+     key would only surface on the first credential item — catch it early.
+
+2. **State file co-location:** The state file (`handoff-state.json`)
+   lives in the same directory as `handoff.yaml`. Derive the state path
+   from the checklist path: replace the filename. This ensures the
+   plugin's config and state stay together regardless of install location.
+
+3. Read `handoff-state.json` if it exists (resume mode).
+   - **Corrupt state:** Offer "start fresh" vs "show me what's broken."
+     Never silently skip items.
+
+4. **Terminal state check:** If all items are complete/sent, warn:
+   "This checklist was completed on [date]. Re-running will send
+   duplicate credentials. Continue?" Do not silently re-prompt.
+
+5. Show progress summary: "You've completed N of M items. Let's pick up
+   with [next section]."
+
+### 2. Check for Incoming Messages
+
+Check the connected email MCP for incoming `[Handoff]` emails from the
+consultant (notes, checklist updates, questions). Process and display
+any new messages before starting the walk.
+
+If no email MCP is connected, skip with no warning — the client may
+be using file transport.
+
+### 3. Walk Through Sections
+
+Walk through sections in order. For each visible item:
+
+**`decide`** — Present options conversationally. Record answer. After
+answering, re-evaluate visibility — new items may appear. Tell the
+client: "Great, since you chose [X], I'll need a few things from you
+for that..."
+
+**`provide`** — Ask for the value. Record in state.
+
+**`confirm`** — Ask yes/no. Record in state.
+
+**`credential`** — Explain what's needed. Show `help` text if present.
+Invoke capture-and-encrypt:
+
+```bash
+node .claude/handoff/capture-and-encrypt.mjs \
+  --prompt "<item prompt>" \
+  --public-key <absolute path to meta.public_key, resolved relative to handoff.yaml's directory>
+```
+
+This returns ONLY the encrypted envelope (base64) on stdout. The
+plaintext credential never enters this conversation or Anthropic's API.
+
+**Important:** The stdout is a base64-serialized envelope. To send it
+with the correct `envelope_id` in the email subject, base64-decode and
+JSON-parse it to recover the envelope object before passing to
+transport. The `envelope_id` field (e.g., `env_abc123`) is needed for
+both the email subject and the state file entry.
+
+Then send the envelope object via transport (using `handoff-transport.mjs`).
+Pass `context.side = 'client'` so the transport addresses the email to
+the consultant.
+
+- **Transport failure:** Write `status: "send_failed"` + serialized
+  envelope to state so retry is possible without re-prompting.
+- **Dialog cancel (exit code 2):** Skip item, note in state, continue.
+- **Success:** Record `status: sent` + `envelope_id` in state. Tell
+  the client: "Got it — encrypted and sent. I never saw the value."
+
+Save state after every answer (atomic write via `handoff-checklist.mjs`).
+
+### 4. Completion
+
+Show final summary: "All done! N of N items complete. [Consultant] will
+be notified."
+
+Send a `session_summary` with all non-credential answers via transport.
+
+## Rules
+
+- **Never** echo or reference a credential value in conversation
+- **Never** store credential values in the state file
+- If the client asks where to find something, teach them — this is
+  Claude's advantage over a form
+- If the client needs to leave, reassure them progress is saved
+- Show a progress table at the start and end of each section

package/templates/skills/handoff-add/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: handoff-add
+description: |
+  Add items to an existing handoff checklist mid-engagement. Preserves
+  existing client progress. Use when: "handoff add", "/handoff-add",
+  "add items to the checklist", "I need something else from the client".
+manual: true
+---
+
+# /handoff-add — Add Items to an Existing Checklist
+
+## Purpose
+
+Amend a handoff checklist after the client has already started working
+on it. New items appear as "not started" without affecting existing
+progress.
+
+## Workflow
+
+1. Read existing `handoff.yaml`. If missing: "No checklist found. Run
+   `/handoff-create` to build one first."
+
+2. Show current structure: sections and item counts.
+
+3. Ask: "What do you need to add?"
+   - "Which section does this belong in?" (existing or new section)
+   - Same item-creation flow as `/handoff-create`: kind, prompt, help,
+     options, visibility rules.
+   - "Any more items to add?"
+
+4. Re-validate the updated checklist:
+   - Cycle detection (new visibility rules may create cycles)
+   - Orphan dependency check
+
+5. Write updated `handoff.yaml`.
+
+6. Send a `checklist_update` notification to the client via transport:
+   - **Email subject:** `[Handoff] N new items added`
+   - **Email body:** Structured JSON with the new items and their
+     sections, so the client's `/handoff` or `/handoff-progress` can
+     surface them.
+
+7. Confirm: "Added N items. [Client name] will see them next time they
+   run `/handoff` or `/handoff-progress`."

package/templates/skills/handoff-ask/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: handoff-ask
+description: |
+  Send a free-text message to the other side of a handoff engagement.
+  Works for both consultant and client. Use when: "handoff ask",
+  "/handoff-ask", "message the consultant", "message the client",
+  "ask Ed", "send a note".
+---
+
+# /handoff-ask — Send a Message
+
+## Purpose
+
+Send a free-text message to the other party in a handoff engagement.
+Works for both sides — the client can ask the consultant a question,
+and the consultant can send a note to the client.
+
+## Workflow
+
+1. Read `handoff.yaml` for transport config and party identifiers.
+   - Determine which side we are: if `keys/consultant.priv.jwk.enc`
+     exists locally, we're the consultant. Otherwise we're the client.
+     (The public key exists on both sides — only the private key
+     distinguishes them.)
+   - Recipient is the other side's email from `transport` config.
+
+2. Ask: "What do you want to say to [other party name]?"
+
+3. Send as a `question` payload via transport:
+   - **Email subject:** `[Handoff] Question from [sender name]`
+   - **Email body:** The free-text message as structured JSON:
+     ```json
+     {
+       "type": "question",
+       "from": "sender name",
+       "message": "the message text",
+       "sent_at": "ISO timestamp"
+     }
+     ```
+
+4. Confirm: "Message sent to [recipient name]."
+
+5. If email transport falls back to file: "Message written to
+   `handoff-out/`. Transfer it manually or connect an email MCP
+   server."

package/templates/skills/handoff-create/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: handoff-create
+description: |
+  Build a handoff checklist conversationally. Interviews the consultant
+  about what the client needs to provide, generates the YAML and keypair.
+  Use when: "handoff create", "/handoff-create", "create a handoff",
+  "build a checklist for the client", "set up handoff".
+manual: true
+---
+
+# /handoff-create — Build a Handoff Checklist
+
+## Purpose
+
+Interview the consultant to build the `handoff.yaml` checklist that
+drives the client's `/handoff` experience. Generates the keypair for
+credential encryption. This is where engagement-specific configuration
+gets created.
+
+## Workflow
+
+### 1. Gather Basics
+
+Ask one question at a time:
+
+1. "Who's the client? What's their name and email?"
+2. "What's this handoff for?" (becomes `meta.title`)
+3. "What transport should we use? Email is the default — it works
+   with Gmail, Outlook, or any email MCP. Or file-based if you'll
+   transfer manually." (becomes `transport.type`)
+4. "What's your email for receiving handoff items?" (consultant email)
+
+### 2. Build Sections
+
+"What categories of items does the client need to provide? For example:
+Hosting, Email Service, Domain, Analytics..."
+
+For each section:
+1. "What does the client need to provide for [section]?"
+2. For each item, determine:
+   - **Kind:** Is this a decision (choose from options), a credential
+     (API key, token, password), free-text information, or a
+     confirmation (yes/no)?
+   - **Prompt:** What should Claude ask the client?
+   - **Help text:** Where can the client find this? (optional)
+   - **Options:** If it's a decision, what are the choices?
+   - **Visibility:** "Does this item depend on a prior answer?"
+     If yes, which item and which value(s) make it visible?
+3. "Any more items in [section]? Or ready for the next section?"
+
+### 3. Validate
+
+Run validation on the constructed checklist:
+- Cycle detection on visibility graph
+- Orphan dependency check (depends_on references a non-existent key)
+- Duplicate key detection
+
+If issues found, surface them and help the consultant fix them
+interactively.
+
+### 4. Generate
+
+1. Write `handoff.yaml` to the project root
+2. Check if `keys/consultant.pub.jwk` exists. If not, generate a
+   keypair:
+
+   ```bash
+   node .claude/handoff/generate-keys.mjs
+   ```
+
+   A secure OS dialog will prompt the consultant for a passphrase
+   (never enters conversation). Explain: "A dialog will appear — create
+   a passphrase to protect your private key. You'll need it when
+   retrieving credentials via `/handoff-status`."
+
+3. Show summary:
+   ```
+   Checklist: "Maginnis Go-Live Credentials"
+   Sections: 4 | Items: 12 (3 credentials, 5 decisions, 4 info)
+   Transport: email
+   Public key: keys/consultant.pub.jwk
+   ```
+
+### 5. Deploy to Client Plugin
+
+Auto-detect the client plugin by scanning for `*/.claude-plugin/plugin.json`
+from the project root (one level deep). If multiple plugins found, ask
+which one. Always run this scan from the project root directory.
+
+If a plugin is found:
+
+1. Create a `handoff/` directory inside the plugin root (sibling to
+   `.claude-plugin/`, `skills/`, etc.):
+   ```
+   <plugin-root>/handoff/handoff.yaml
+   <plugin-root>/handoff/consultant.pub.jwk
+   ```
+
+2. **Rewrite `meta.public_key`** in the deployed `handoff.yaml` copy.
+   The original says `./keys/consultant.pub.jwk` (relative to the
+   consultant's project). The deployed copy must say
+   `./consultant.pub.jwk` (relative to the deployed `handoff/`
+   directory where the key file now lives). Read the deployed YAML,
+   update the path, write it back.
+
+3. Create a `/handoff` skill in the plugin's `skills/` directory.
+   This skill tells the client's Claude exactly where the config is
+   using a path relative to the skill file itself — this works
+   regardless of where Claude Code installs the plugin on the client's
+   machine:
+
+   **Write to `<plugin-root>/skills/handoff/SKILL.md`:**
+   ```markdown
+   ---
+   name: handoff
+   description: |
+     Provide go-live credentials and configuration for your consultant.
+     Credentials are captured via a secure dialog — they never enter
+     this conversation or reach Anthropic's servers.
+     Use when: "handoff", "/handoff", "provide credentials".
+   manual: true
+   ---
+
+   # /handoff — Provide Your Credentials
+
+   This plugin bundles a handoff checklist from your consultant.
+
+   ## Locating the config
+
+   This skill file lives at `skills/handoff/SKILL.md` within the
+   plugin. The handoff config is two levels up in the `handoff/`
+   directory:
+
+   - Checklist: `../../handoff/handoff.yaml` (relative to this file)
+   - Public key: `../../handoff/consultant.pub.jwk` (relative to this file)
+
+   To get the absolute paths: take this skill file's absolute path,
+   go up two directories, then into `handoff/`.
+
+   ## What to do
+
+   1. Resolve the absolute path to `handoff.yaml` as described above.
+   2. Follow the `/handoff` skill workflow (from the project's CC
+      installation) using that path as the config location.
+   3. Read and write `handoff-state.json` in the same directory as
+      `handoff.yaml` (the plugin's `handoff/` directory).
+   ```
+
+4. Confirm: "Deployed to [plugin-name]. When the client installs the
+   plugin and runs `/handoff`, everything is ready."
+
+If no plugin found:
+
+Surface the manual steps:
+```
+No client plugin found in this project. To deploy manually:
+1. Create a handoff/ directory in the client's plugin
+2. Copy handoff.yaml into it (update meta.public_key to ./consultant.pub.jwk)
+3. Copy keys/consultant.pub.jwk as handoff/consultant.pub.jwk
+4. Add a /handoff skill to the plugin's skills/ directory (see schema.md)
+```