@contextq/cli 0.0.1 → 0.1.0

package/README.md

@@ -1,7 +1,52 @@
 # @contextq/cli
 
-**This is a name-reservation placeholder. It contains no code and does nothing.**
+One-command installer for [ContextQ](https://github.com/HENIART/contextq). It wires the ContextQ MCP server, the contextq SessionStart boot hook, and the task manifest into a project — or prints a manual connect guide when the surface is Claude Desktop or Cowork, which have no project files to write into.
 
-The real ContextQ CLI is built at [HENIART/contextq](https://github.com/HENIART/contextq) under \`cli/\` (version 0.1.0 at the time of this reservation) and is not published yet.
+## Install
 
-The unscoped name \`contextq\` is permanently unavailable on npm -- the registry rejects it as too similar to the unrelated package \`context-q\`.
+```bash
+npx @contextq/cli init
+```
+
+Or install it globally and call the `contextq` binary directly:
+
+```bash
+npm install -g @contextq/cli
+contextq init
+```
+
+## `contextq init`
+
+Detects which agent surfaces the current directory is set up for (Claude Code, Codex, or both — a repo is often both at once) and writes the wiring each one needs.
+
+| Option | Meaning |
+|---|---|
+| `--key <sk_live_...>` | API key. Falls back to `CONTEXT_API_KEY` / `CTQ_API_KEY` in the environment, then to an interactive prompt. |
+| `--url <url>` | ContextQ API URL. Defaults to `https://app.contextq.dev`; point it at your own instance when self-hosting. |
+| `--workspace <slug>` | Workspace the boot hook reads from. Defaults to the repo basename, sanitized. Lowercase letters, digits, `-` and `_`; must start with a letter or digit; 64 chars max. Case is folded to lowercase, since workspace slugs always are. |
+| `--agent <slug>` | Agent identity the session boots and checkpoints under. Same defaulting and same character rules as `--workspace`. |
+| `--embed-key` | Write the literal API key into `.mcp.json` instead of the `${CONTEXT_API_KEY}` placeholder. Opt-in on purpose: it trades a secret sitting on disk for not having to export the variable. |
+| `--surface <s>` | Force detection to exactly one of `claude-code` or `codex`, skipping autodetection. |
+| `-h`, `--help` | Show usage. |
+
+The API key is a ContextQ key in the form `sk_live_<40 hex>`, issued from your tenant's dashboard. Without `--embed-key`, the generated config references `${CONTEXT_API_KEY}` and the key never lands in a file.
+
+## `contextq skills sync <dir>`
+
+Pulls this tenant's distilled procedures — the parametrized skills ContextQ mines from repeated, independently verified agent task patterns — into `<dir>` as standard Agent Skills folders, one `SKILL.md` per procedure.
+
+```bash
+contextq skills sync .claude/skills
+```
+
+Safe to re-run. An existing folder is matched by its own `metadata.cluster_key` and rewritten in place rather than duplicated. A folder whose source context no longer resolves is reported as an orphan and left on disk untouched, so nothing you wrote by hand is ever deleted.
+
+It accepts `--workspace`, `--key` and `--url` with the same meanings as `init`.
+
+## Requirements
+
+Node 18 or newer, and a reachable ContextQ instance — the hosted one at `app.contextq.dev` or your own.
+
+## License
+
+MIT. Source lives in the [contextq](https://github.com/HENIART/contextq) repository under `cli/`.

package/dist/desktop-guide.d.ts

@@ -0,0 +1,8 @@
+/**
+ * desktop-guide.ts — the Lane 2 (remote MCP) connect guide for Claude
+ * Desktop / Cowork / any client that only reads a manually-edited config
+ * file. There is no auto-connect path for these clients (verified
+ * impossible -- they only read their config on start), so this prints the
+ * exact 3-step manual flow instead of pretending to automate it.
+ */
+export declare function printDesktopGuide(apiUrl: string): void;

package/dist/desktop-guide.js

@@ -0,0 +1,40 @@
+/**
+ * desktop-guide.ts — the Lane 2 (remote MCP) connect guide for Claude
+ * Desktop / Cowork / any client that only reads a manually-edited config
+ * file. There is no auto-connect path for these clients (verified
+ * impossible -- they only read their config on start), so this prints the
+ * exact 3-step manual flow instead of pretending to automate it.
+ */
+export function printDesktopGuide(apiUrl) {
+    console.log(`
+No git repo or existing Claude Code project found here, so there is nothing on
+disk to scaffold. For Claude Desktop, Cowork, or any other MCP-capable client
+that reads a manually-edited config file, connect ContextQ in 3 steps:
+
+  1. Open the ContextQ dashboard -> Settings -> API keys -> create a key
+     ${apiUrl}/dashboard/api-keys
+
+  2. Add this to your client's MCP config file (e.g. claude_desktop_config.json):
+
+     {
+       "mcpServers": {
+         "contextq": {
+           "command": "npx",
+           "args": ["-y", "@contextq/mcp"],
+           "env": {
+             "CONTEXT_API_URL": "${apiUrl}",
+             "CONTEXT_API_KEY": "<your key from step 1>"
+           }
+         }
+       }
+     }
+
+  3. Restart the client so it picks up the new MCP server.
+
+There is no auto-connect for Desktop/Cowork today -- these clients only read
+their config file on start, so step 2 has to be a manual paste. Re-run
+"npx @contextq/cli init" inside a git repo (or an existing Claude Code project) to
+get the automatic .mcp.json + hook + task-manifest scaffolding instead.
+`);
+}
+//# sourceMappingURL=desktop-guide.js.map

package/dist/desktop-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-guide.js","sourceRoot":"","sources":["../src/desktop-guide.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO,CAAC,GAAG,CAAC;;;;;;OAMP,MAAM;;;;;;;;;;mCAUsB,MAAM;;;;;;;;;;;;;CAaxC,CAAC,CAAC;AACH,CAAC"}

package/dist/detect.d.ts

@@ -0,0 +1,42 @@
+/**
+ * detect.ts — surface detection.
+ *
+ * Claude Code lane: cwd is inside a git repo, OR a `.claude/` dir already
+ * exists at cwd -- either signal means there is a real project here the
+ * installer can safely scaffold into.
+ *
+ * Codex lane (T665): a project is treated as a Codex target when EITHER of
+ * two signals holds -- a `.codex/` dir at the repo root (covers both
+ * `.codex/config.toml` and `.codex/hooks.json`, since both live inside that
+ * one directory -- there is no separate "config at repo level" signal to
+ * check, it's the same dir), OR `~/.codex/` existing on this machine at all
+ * (Codex CLI installed here, even if this particular repo hasn't been
+ * opened with it yet -- the same breadth Claude Code's own `git repo OR
+ * .claude/` rule already uses). The write itself is low-risk (idempotent,
+ * additive-only, gitignored -- see session-hook.ts) so erring toward
+ * detecting Codex is deliberate, not an oversight.
+ *
+ * Claude Code and Codex are detected INDEPENDENTLY -- a repo can be (and
+ * commonly is) both, so `surfaces` is an array, not a single value. Only
+ * when NEITHER signal fires does detection fall back to the single
+ * `'desktop'` value (nothing on disk to scaffold -- print the manual guide).
+ *
+ * `forcedSurface` (wired from index.ts's `--surface` flag) bypasses
+ * autodetection entirely and pins exactly one surface -- e.g. `--surface
+ * codex` on a bare folder with neither a repo-level `.codex/` nor a
+ * `~/.codex/` install (a fresh CI sandbox, a machine where Codex isn't
+ * installed yet but the hooks file should still be scaffolded ahead of it).
+ */
+export type Surface = 'claude-code' | 'codex' | 'desktop';
+export interface DetectOptions {
+    /** Wired from `--surface` -- when set, skip autodetection and pin exactly this one surface. */
+    forcedSurface?: Exclude<Surface, 'desktop'>;
+    /** Override for os.homedir(), tests only -- production always uses the real home dir. */
+    homeDir?: string;
+}
+export interface DetectResult {
+    surfaces: Surface[];
+    root: string;
+}
+export declare function gitRoot(cwd: string): string;
+export declare function detectSurface(cwd: string, opts?: DetectOptions): DetectResult;

package/dist/detect.js

@@ -0,0 +1,70 @@
+/**
+ * detect.ts — surface detection.
+ *
+ * Claude Code lane: cwd is inside a git repo, OR a `.claude/` dir already
+ * exists at cwd -- either signal means there is a real project here the
+ * installer can safely scaffold into.
+ *
+ * Codex lane (T665): a project is treated as a Codex target when EITHER of
+ * two signals holds -- a `.codex/` dir at the repo root (covers both
+ * `.codex/config.toml` and `.codex/hooks.json`, since both live inside that
+ * one directory -- there is no separate "config at repo level" signal to
+ * check, it's the same dir), OR `~/.codex/` existing on this machine at all
+ * (Codex CLI installed here, even if this particular repo hasn't been
+ * opened with it yet -- the same breadth Claude Code's own `git repo OR
+ * .claude/` rule already uses). The write itself is low-risk (idempotent,
+ * additive-only, gitignored -- see session-hook.ts) so erring toward
+ * detecting Codex is deliberate, not an oversight.
+ *
+ * Claude Code and Codex are detected INDEPENDENTLY -- a repo can be (and
+ * commonly is) both, so `surfaces` is an array, not a single value. Only
+ * when NEITHER signal fires does detection fall back to the single
+ * `'desktop'` value (nothing on disk to scaffold -- print the manual guide).
+ *
+ * `forcedSurface` (wired from index.ts's `--surface` flag) bypasses
+ * autodetection entirely and pins exactly one surface -- e.g. `--surface
+ * codex` on a bare folder with neither a repo-level `.codex/` nor a
+ * `~/.codex/` install (a fresh CI sandbox, a machine where Codex isn't
+ * installed yet but the hooks file should still be scaffolded ahead of it).
+ */
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function gitRoot(cwd) {
+    try {
+        return execSync('git rev-parse --show-toplevel', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function hasCodexProjectDir(root) {
+    return existsSync(join(root, '.codex'));
+}
+function hasCodexHome(homeDir) {
+    return existsSync(join(homeDir, '.codex'));
+}
+export function detectSurface(cwd, opts = {}) {
+    const gitRootPath = gitRoot(cwd);
+    const root = gitRootPath || cwd;
+    if (opts.forcedSurface) {
+        return { surfaces: [opts.forcedSurface], root };
+    }
+    const hasClaudeDir = existsSync(join(cwd, '.claude'));
+    const claudeCode = Boolean(gitRootPath || hasClaudeDir);
+    const codex = hasCodexProjectDir(root) || hasCodexHome(opts.homeDir ?? homedir());
+    const surfaces = [];
+    if (claudeCode)
+        surfaces.push('claude-code');
+    if (codex)
+        surfaces.push('codex');
+    if (surfaces.length === 0)
+        surfaces.push('desktop');
+    return { surfaces, root: claudeCode || codex ? root : cwd };
+}
+//# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAgBjC,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,+BAA+B,EAAE;YAC/C,GAAG;YACH,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAY;IACtC,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,OAAsB,EAAE;IACjE,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,WAAW,IAAI,GAAG,CAAC;IAEhC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;IAClD,CAAC;IAED,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;IACtD,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,IAAI,YAAY,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC,CAAC;IAElF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,IAAI,UAAU;QAAE,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7C,IAAI,KAAK;QAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEpD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAC9D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * contextq — one-command installer.
+ *
+ * `npx @contextq/cli init` detects which surface(s) are present -- Claude Code
+ * project, Codex CLI project (T665), or neither (Desktop/Cowork) -- and
+ * scaffolds the matching wiring: for Claude Code, .mcp.json + the contextq
+ * SessionStart hook + .contextq/tasks/; for Codex, a `.codex/hooks.json`
+ * SessionStart hook (see cli/src/session-hook.ts for why the two harnesses
+ * share one command builder and one merge implementation). A repo can be
+ * (and often is) both at once -- both get wired in the same run unless
+ * `--surface` pins exactly one. Neither detected -> print the manual
+ * 3-step connect guide instead. Idempotent throughout: re-running reports
+ * "already configured" / "[skip]" for anything already wired and writes
+ * nothing new.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,421 @@
+#!/usr/bin/env node
+/**
+ * contextq — one-command installer.
+ *
+ * `npx @contextq/cli init` detects which surface(s) are present -- Claude Code
+ * project, Codex CLI project (T665), or neither (Desktop/Cowork) -- and
+ * scaffolds the matching wiring: for Claude Code, .mcp.json + the contextq
+ * SessionStart hook + .contextq/tasks/; for Codex, a `.codex/hooks.json`
+ * SessionStart hook (see cli/src/session-hook.ts for why the two harnesses
+ * share one command builder and one merge implementation). A repo can be
+ * (and often is) both at once -- both get wired in the same run unless
+ * `--surface` pins exactly one. Neither detected -> print the manual
+ * 3-step connect guide instead. Idempotent throughout: re-running reports
+ * "already configured" / "[skip]" for anything already wired and writes
+ * nothing new.
+ */
+import { basename } from 'node:path';
+import { detectSurface } from './detect.js';
+import { decideCredentialWrite, KEY_RE, readExistingCreds } from './platform-cred.js';
+import { wireMcpJson } from './mcp-config.js';
+import { wireCodexSessionHook, wireSessionHook } from './session-hook.js';
+import { initTasksDir } from './tasks-init.js';
+import { printDesktopGuide } from './desktop-guide.js';
+import { promptHidden } from './prompt.js';
+import { SLUG_PATTERN_DESCRIPTION, sanitizeSlugFallback, validateSlug } from './slug.js';
+import { syncSkills } from './skills-sync.js';
+const DEFAULT_URL = 'https://app.contextq.dev';
+function parseArgs(argv) {
+    const hasLeadingCommand = argv.length > 0 && !argv[0].startsWith('-');
+    const args = { command: hasLeadingCommand ? argv[0] : '', embedKey: false, help: false };
+    for (let i = hasLeadingCommand ? 1 : 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case '--key':
+                args.key = argv[++i];
+                break;
+            case '--url':
+                args.url = argv[++i];
+                break;
+            case '--workspace':
+                args.workspace = argv[++i];
+                break;
+            case '--agent':
+                args.agent = argv[++i];
+                break;
+            case '--embed-key':
+                args.embedKey = true;
+                break;
+            case '--surface': {
+                const v = argv[++i];
+                if (v !== 'claude-code' && v !== 'codex') {
+                    throw new Error(`--surface value "${v}" is invalid -- allowed: claude-code, codex`);
+                }
+                args.surface = v;
+                break;
+            }
+            case '-h':
+            case '--help':
+                args.help = true;
+                break;
+            default:
+                throw new Error(`unknown argument: ${a}`);
+        }
+    }
+    return args;
+}
+function printHelp() {
+    console.log(`contextq — one-command installer for ContextQ
+
+Usage:
+  npx @contextq/cli init [options]
+
+Options:
+  --key <sk_live_...>   API key (else CONTEXT_API_KEY/CTQ_API_KEY env, else prompt)
+  --url <url>            ContextQ API URL (default: ${DEFAULT_URL})
+  --workspace <slug>     Workspace slug for the contextq boot hook (default: repo basename,
+                         sanitized). Allowed: ${SLUG_PATTERN_DESCRIPTION}. Case is folded to
+                         lowercase automatically (workspace slugs are always lowercase).
+  --agent <slug>         Agent slug for the contextq boot hook (default: repo basename,
+                         sanitized). Allowed: ${SLUG_PATTERN_DESCRIPTION}.
+  --embed-key            Write the literal API key into .mcp.json instead of the
+                         safer \${CONTEXT_API_KEY} placeholder (opt-in: convenience
+                         vs. a secret sitting on disk)
+  --surface <s>          Force surface detection to exactly one of: claude-code, codex.
+                         Skips autodetection entirely (default: autodetect both --
+                         a repo can be, and often is, both at once).
+  -h, --help             Show this help
+
+Usage:
+  npx @contextq/cli skills sync <dir> [options]
+
+Pulls this tenant's distilled procedures (T376) as standard Agent Skills
+folders (<dir>/<slug>/SKILL.md). Safe to re-run: an existing folder is
+matched by its own metadata.cluster_key and rewritten in place, never
+duplicated; a folder whose context no longer resolves is reported as an
+orphan and left on disk untouched.
+
+Options:
+  --workspace <slug>     Limit to one workspace's procedures (default: every
+                         workspace visible to the tenant)
+  --key <sk_live_...>   API key (else CONTEXT_API_KEY/CTQ_API_KEY env, else the
+                         credential file written by \`contextq init\`)
+  --url <url>            ContextQ API URL (else the credential file, else
+                         CONTEXT_API_URL/CTQ_API_URL env, default: ${DEFAULT_URL})
+`);
+}
+function relative(root, path) {
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+}
+function label(action) {
+    const known = {
+        created: '[create]',
+        added: '[add]  ',
+        wired: '[create]',
+        rotated: '[rotate]',
+        skipped: '[skip] ',
+        verified: '[check]',
+        failed: '[check]',
+    };
+    return known[action] ?? `[${action}]`;
+}
+/**
+ * T474: the installer used to wire .mcp.json / the SessionStart hook / the
+ * task manifest and declare success without ever confirming the key + URL it
+ * just wrote actually authenticate against the server. Ping a cheap
+ * read-scoped endpoint so a typo'd key or URL fails loudly here instead of
+ * surfacing later as "the MCP tools aren't showing up".
+ */
+async function verifyConnection(apiUrl, apiKey) {
+    try {
+        const res = await fetch(`${apiUrl.replace(/\/$/, '')}/api/workspaces`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        return { ok: res.status === 200, status: res.status };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+async function runInit(args) {
+    const cwd = process.cwd();
+    const { surfaces, root } = detectSurface(cwd, { forcedSurface: args.surface });
+    console.log('ContextQ init');
+    console.log('=============');
+    if (surfaces.length === 1 && surfaces[0] === 'desktop') {
+        console.log(`Surface detected: desktop/other (no git repo, .claude/, or .codex/ found at ${cwd})`);
+        printDesktopGuide(args.url ?? DEFAULT_URL);
+        return;
+    }
+    console.log(`Surface(s) detected: ${surfaces.join(', ')} (root: ${root})`);
+    const existing = readExistingCreds();
+    const apiUrl = args.url || existing.apiUrl || process.env.CONTEXT_API_URL || DEFAULT_URL;
+    // T676: a demo run with only an AMBIENT env var set (direnv-exported
+    // CONTEXT_API_KEY from some repo's .env.local, say) used to be treated
+    // exactly like an explicit --key, silently overwriting a pre-existing
+    // machine-wide credential file with no backup. decideCredentialWrite()
+    // (platform-cred.ts) now requires --key for rotation, backs up before any
+    // real overwrite, and no-ops when nothing would change -- see its doc
+    // comment for the full branch table.
+    const ambientVarName = process.env.CONTEXT_API_KEY
+        ? 'CONTEXT_API_KEY'
+        : process.env.CTQ_API_KEY
+            ? 'CTQ_API_KEY'
+            : null;
+    const ambientKey = ambientVarName ? process.env[ambientVarName] : '';
+    let decision = decideCredentialWrite({ explicitKey: args.key, ambientVarName, ambientKey, apiUrl });
+    if (decision.action === null) {
+        // No --key, no ambient env var, and no existing file -- the only case
+        // decideCredentialWrite() can't resolve on its own.
+        const typed = await promptHidden('ContextQ API key (sk_live_...): ');
+        if (!KEY_RE.test(typed)) {
+            throw new Error('no valid API key available (expected sk_live_<40 hex chars>). Pass --key, set ' +
+                'CONTEXT_API_KEY, or re-run from an interactive terminal.');
+        }
+        decision = decideCredentialWrite({ explicitKey: typed, ambientVarName: null, ambientKey: '', apiUrl });
+    }
+    const apiKey = decision.apiKey;
+    console.log(decision.credLine);
+    // T656: --agent/--workspace (and the basename(root) fallback) end up
+    // interpolated into a shell command written to the SessionStart hook (see
+    // wireSessionHook below) -- validate/sanitize BEFORE that, on top of the
+    // shell-quoting session-hook.ts itself applies as defense in depth. An
+    // explicit flag value that doesn't fit the slug pattern is a hard error
+    // (no silent truncation); the basename(root) fallback is sanitized
+    // instead, since the user never typed it.
+    let agent;
+    if (args.agent) {
+        agent = validateSlug(args.agent, '--agent');
+    }
+    else {
+        agent = sanitizeSlugFallback(basename(root));
+    }
+    let workspace;
+    if (args.workspace) {
+        // Workspace slugs are always lowercase in this product (CLAUDE.md) --
+        // folding case is a documented convention, not a silent rewrite, so an
+        // explicit --workspace that differs from the API only by case is
+        // lowercased and then validated (never lowercased AWAY a genuine
+        // charset violation). --agent gets no such courtesy: it has no
+        // documented lowercase-only convention, so an explicit --agent value
+        // is validated as typed.
+        const lowered = args.workspace.toLowerCase();
+        workspace = validateSlug(lowered, '--workspace');
+        if (lowered !== args.workspace) {
+            console.log(`[info]   --workspace lowercased to match slug convention: "${args.workspace}" -> "${lowered}"`);
+        }
+    }
+    else {
+        workspace = sanitizeSlugFallback(basename(root));
+    }
+    console.log(`[info]   agent=${agent} workspace=${workspace}`);
+    let mcpResult;
+    if (surfaces.includes('claude-code')) {
+        mcpResult = wireMcpJson(root, apiUrl, args.embedKey, apiKey);
+        console.log(`${label(mcpResult.action)} ${relative(root, mcpResult.path)} (${mcpResult.detail})`);
+        const hookResult = wireSessionHook(root, agent, workspace);
+        console.log(`${label(hookResult.action)} ${relative(root, hookResult.path)} (${hookResult.detail})`);
+        const tasksResult = initTasksDir(root);
+        console.log(`${label(tasksResult.action)} ${relative(root, tasksResult.path)} (${tasksResult.detail})`);
+    }
+    if (surfaces.includes('codex')) {
+        console.log('');
+        console.log('[info]   Codex hooks -- assumptions this install makes:');
+        console.log('         - Sandbox/approval: the boot hook makes an outbound HTTP call to the ContextQ');
+        console.log('           API. Verified empirically (codex-cli 0.146.0, `codex exec --sandbox');
+        console.log('           workspace-write`, no approval flag): a TRUSTED hook\'s outbound call is NOT');
+        console.log('           gated by sandbox_mode/approval_policy the way model-issued shell commands');
+        console.log('           are -- the real gate is hook TRUST (see the note below), not the sandbox.');
+        console.log('           Once trusted, this should work under any sandbox_mode/approval_policy combo.');
+        console.log('           If it still produces no injected context, `codex doctor` shows current sandbox');
+        console.log('           + approval state as a starting point for diagnosis.');
+        console.log('         - Native Memories: Codex ships its own Memories feature (off by default). If you');
+        console.log('           turn it on, set memories.disable_on_external_context = true in config.toml (or');
+        console.log('           its older alias no_memories_if_mcp_or_web_search) -- otherwise a session that');
+        console.log('           used MCP tools (including ContextQ\'s own MCP server) still feeds Codex\'s native');
+        console.log('           memory extraction too, duplicating what ContextQ already captures.');
+        console.log('');
+        const codexHookResult = wireCodexSessionHook(root, agent, workspace);
+        console.log(`${label(codexHookResult.action)} ${relative(root, codexHookResult.path)} (${codexHookResult.detail})`);
+    }
+    const verifyResult = await verifyConnection(apiUrl, apiKey);
+    if (verifyResult.ok) {
+        console.log(`${label('verified')} connection to ${apiUrl} (GET /api/workspaces -> 200)`);
+    }
+    else {
+        const detail = verifyResult.status ? `HTTP ${verifyResult.status}` : verifyResult.error ?? 'unknown error';
+        console.log(`${label('failed')} connection to ${apiUrl} (${detail}) -- check your API key and --url`);
+        if (verifyResult.status === 401 || verifyResult.status === 403) {
+            process.exitCode = 1;
+        }
+    }
+    if (mcpResult && !args.embedKey && mcpResult.action !== 'skipped') {
+        console.log('');
+        console.log('NOTE: .mcp.json references ${CONTEXT_API_KEY} -- Claude Code expands that from');
+        console.log('its OWN process environment, not from the credential file just written.');
+        console.log('Export it in your shell profile before starting Claude Code:');
+        console.log('  export CONTEXT_API_KEY=<your key>');
+        console.log('...or re-run with --embed-key to write the literal key into .mcp.json instead.');
+    }
+    console.log('');
+    const doneSurfaces = surfaces.filter((s) => s !== 'desktop');
+    const doneNote = doneSurfaces
+        .map((s) => (s === 'claude-code' ? 'a new Claude Code session' : 'a new `codex` run'))
+        .join(' / start ');
+    console.log(`Done. Open ${doneNote} in this repo to pick up the wiring.`);
+    // Claude Code 2.1.268+ can install the same MCP server as a plugin, which
+    // collects the API key through the manifest's userConfig (secure storage,
+    // never settings.json) instead of needing CONTEXT_API_KEY exported into the
+    // shell. This installer still exists for Codex, Desktop, CI, and the
+    // contextq SessionStart hook, none of which the plugin covers -- so point
+    // at it rather than replacing this path.
+    if (surfaces.includes('claude-code')) {
+        console.log('');
+        console.log('Claude Code 2.1.268+ can install the MCP half of this as a plugin instead,');
+        console.log('with no CONTEXT_API_KEY to export:');
+        console.log('  claude plugin marketplace add https://app.contextq.dev/plugin/marketplace.json');
+        console.log('  claude plugin install contextq@contextq-plugins --config apiKey=<your key>');
+        console.log('See docs/mcp-setup.md. This installer stays the path for Codex and CI.');
+    }
+}
+/**
+ * Separate from parseArgs() on purpose: `skills sync <dir>` has a
+ * subcommand + a required positional argument, a shape parseArgs()'s
+ * single-command-token model doesn't fit. Dispatched from main() before
+ * parseArgs() ever sees the argv.
+ */
+function parseSkillsSyncArgs(argv) {
+    const positional = [];
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case '--workspace':
+                args.workspace = argv[++i];
+                break;
+            case '--key':
+                args.key = argv[++i];
+                break;
+            case '--url':
+                args.url = argv[++i];
+                break;
+            default:
+                if (a.startsWith('-')) {
+                    throw new Error(`unknown argument: ${a}`);
+                }
+                positional.push(a);
+        }
+    }
+    if (positional.length === 0) {
+        throw new Error('missing <dir> argument -- usage: contextq skills sync <dir>');
+    }
+    if (positional.length > 1) {
+        throw new Error(`unexpected extra argument: ${positional[1]}`);
+    }
+    return { ...args, dir: positional[0] };
+}
+/**
+ * Resolve credentials the SAME way `contextq init`'s verifyConnection() call
+ * does (explicit flag > ambient env var > the credential file `init`
+ * already wrote) but read-only -- `skills sync` never writes credentials,
+ * it only needs something to authenticate with.
+ */
+function resolveApiCreds(args) {
+    const existing = readExistingCreds();
+    const apiUrl = args.url || existing.apiUrl || process.env.CONTEXT_API_URL || process.env.CTQ_API_URL || DEFAULT_URL;
+    const apiKey = args.key || process.env.CONTEXT_API_KEY || process.env.CTQ_API_KEY || existing.apiKey;
+    if (!apiKey) {
+        throw new Error('no API key available -- pass --key, set CONTEXT_API_KEY, or run `contextq init` first to write the credential file');
+    }
+    return { apiUrl, apiKey };
+}
+/**
+ * `format=json` (not the default `zip`) so this never needs an unzip
+ * dependency in the published `contextq` npm package -- the bulk export
+ * route (src/routes/agent.ts) supports both from the same query.
+ */
+async function fetchSkillsFromApi(apiUrl, apiKey, workspace) {
+    const url = new URL('/api/agent/skills/export', apiUrl.replace(/\/$/, '') + '/');
+    url.searchParams.set('format', 'json');
+    if (workspace)
+        url.searchParams.set('workspace', workspace);
+    const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
+    if (!res.ok) {
+        throw new Error(`GET ${url.pathname}${url.search} -> HTTP ${res.status}`);
+    }
+    const body = (await res.json());
+    return body.skills;
+}
+async function runSkillsSync(args) {
+    console.log('contextq skills sync');
+    console.log('=====================');
+    const { apiUrl, apiKey } = resolveApiCreds(args);
+    console.log(`[info]   syncing to ${args.dir}${args.workspace ? ` (workspace: ${args.workspace})` : ''}`);
+    const result = await syncSkills({
+        dir: args.dir,
+        fetchSkills: () => fetchSkillsFromApi(apiUrl, apiKey, args.workspace),
+    });
+    for (const f of result.written)
+        console.log(`${label('created')} ${f}/SKILL.md`);
+    for (const f of result.updated)
+        console.log(`${label('added')} ${f}/SKILL.md (rewritten in place)`);
+    console.log(`[info]   ${result.written.length} written, ${result.updated.length} updated, ${result.unchanged.length} unchanged`);
+    if (result.orphans.length > 0) {
+        console.log(`[warn]   ${result.orphans.length} orphaned folder(s) -- left on disk, not deleted:`);
+        for (const f of result.orphans)
+            console.log(`         ${f}/ (its context no longer resolves)`);
+    }
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv[0] === 'skills') {
+        if (argv[1] === '-h' || argv[1] === '--help') {
+            printHelp();
+            return;
+        }
+        if (argv[1] !== 'sync') {
+            console.error(`contextq: unknown "skills" subcommand "${argv[1] ?? ''}" -- expected "sync"`);
+            printHelp();
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const skillsArgs = parseSkillsSyncArgs(argv.slice(2));
+            await runSkillsSync(skillsArgs);
+        }
+        catch (err) {
+            console.error(`contextq: ${err.message}`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (err) {
+        console.error(`contextq: ${err.message}`);
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
+    if (args.help || !args.command) {
+        printHelp();
+        return;
+    }
+    if (args.command !== 'init') {
+        console.error(`contextq: unknown command "${args.command}"`);
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        await runInit(args);
+    }
+    catch (err) {
+        console.error(`contextq: ${err.message}`);
+        process.exitCode = 1;
+    }
+}
+main();
+//# sourceMappingURL=index.js.map