@ze-norm/cli 0.14.2 → 0.15.0

package/README.md

@@ -4,10 +4,14 @@ Public command-line client for ZeNorm.
 
 ```sh
 npm install -g @ze-norm/cli
-zenorm login
-zenorm install-skills claude-code
+zenorm setup claude-code
 ```
 
+`zenorm setup <agent>` is the one-command onboarding path: it logs you in (or
+skips that if you already are), installs the bundled ZeNorm skills for the agent
+you name, and prints your next steps. Use `zenorm login` and
+`zenorm install-skills` directly if you want to run those steps separately.
+
 The CLI includes the ZeNorm agent skills in the npm package. `zenorm install-skills`
 installs those bundled skills through the `skills` package; it does not require
 a separate skills repository.

package/dist/commands/install-skills.d.ts

@@ -1,2 +1,30 @@
+/** Exported so tests can assert every advertised slug is one the skills package accepts. */
+export declare const INSTALL_SKILLS_USAGE = "Usage:\n  zenorm install-skills <agent|all|*> [--project|--global]\n\nExamples:\n  zenorm install-skills claude-code\n  zenorm install-skills codex --project\n  zenorm install-skills codex --project --force\n  zenorm install-skills '*' --project\n\nAgent names are the slugs supported by the skills package, such as\nclaude-code, codex, cursor, opencode, gemini-cli, github-copilot, windsurf,\nqwen-code, kiro-cli, cline, roo, and more. An unknown slug is rejected with the\nfull list of valid agents.";
+export declare function normalizeAgent(raw: string): string;
+/**
+ * Reject an agent slug the skills package does not know, before doing any work.
+ *
+ * The skills package keeps its agent registry private (no export, no
+ * list-agents subcommand), so the package itself is the only authority on which
+ * slugs are valid. `skills list --agent <slug>` consults that registry, is
+ * read-only, and exits non-zero with `Invalid agents: ... / Valid agents: ...`.
+ * Running it as a precheck means a typo fails in milliseconds with the real
+ * list, rather than after a browser sign-in round-trip.
+ */
+export declare function assertKnownAgent(agent: string): void;
+export interface InstallSkillsOptions {
+    /** Install into the current project rather than the global agent directories. */
+    project: boolean;
+    /** Overwrite ZeNorm skills that are already installed for this agent. */
+    force: boolean;
+}
+/**
+ * Install the bundled ZeNorm skills for one skills-package agent slug.
+ *
+ * The shared boundary behind both `zenorm install-skills <agent>` and
+ * `zenorm setup <agent>` — the slug is validated here, so a missing/unknown
+ * agent fails loud in either entry point rather than defaulting to anything.
+ */
+export declare function installSkillsForAgent(requestedAgent: string, opts: InstallSkillsOptions): void;
 export declare function installSkillsCommand(args: string[]): Promise<void>;
 //# sourceMappingURL=install-skills.d.ts.map

package/dist/commands/install-skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-skills.d.ts","sourceRoot":"","sources":["../../src/commands/install-skills.ts"],"names":[],"mappings":"AAqOA,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCxE"}
+{"version":3,"file":"install-skills.d.ts","sourceRoot":"","sources":["../../src/commands/install-skills.ts"],"names":[],"mappings":"AAiBA,4FAA4F;AAC5F,eAAO,MAAM,oBAAoB,0fAYN,CAAC;AAwC5B,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMlD;AAkID;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAgFD,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,oBAAoB,GACzB,IAAI,CAIN;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CxE"}

package/dist/commands/install-skills.js

@@ -3,11 +3,12 @@ import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, } from "n
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
-import { parseArgs } from "node:util";
+import { parseArgs } from "../util/parse-args.js";
 import { fileURLToPath } from "node:url";
 import { CliError } from "../util/errors.js";
 import { log } from "../util/logger.js";
-const USAGE = `Usage:
+/** Exported so tests can assert every advertised slug is one the skills package accepts. */
+export const INSTALL_SKILLS_USAGE = `Usage:
   zenorm install-skills <agent|all|*> [--project|--global]
 
 Examples:
@@ -18,7 +19,8 @@ Examples:
 
 Agent names are the slugs supported by the skills package, such as
 claude-code, codex, cursor, opencode, gemini-cli, github-copilot, windsurf,
-qwen, kiro, cline, roo, and more.`;
+qwen-code, kiro-cli, cline, roo, and more. An unknown slug is rejected with the
+full list of valid agents.`;
 const AGENT_SLUG_RE = /^[a-z0-9][a-z0-9-]*$|^\*$/;
 const require = createRequire(import.meta.url);
 function getBundledSkillsRoot() {
@@ -47,10 +49,10 @@ function getSkillsCliPath() {
         throw new CliError("Could not find the bundled `skills` package. Reinstall @ze-norm/cli and try again.");
     }
 }
-function normalizeAgent(raw) {
+export function normalizeAgent(raw) {
     const normalized = raw.toLowerCase() === "all" ? "*" : raw.toLowerCase();
     if (!AGENT_SLUG_RE.test(normalized)) {
-        throw new CliError(`Invalid agent "${raw}".\n\n${USAGE}`);
+        throw new CliError(`Invalid agent "${raw}".\n\n${INSTALL_SKILLS_USAGE}`);
     }
     return normalized;
 }
@@ -108,23 +110,83 @@ function skillBelongsToAgent(skill, agent) {
     const wanted = normalizeAgentLabel(agent);
     return skill.agents.some((label) => typeof label === "string" && normalizeAgentLabel(label) === wanted);
 }
-function listInstalledSkills(agent, project) {
-    const scopeArgs = project ? [] : ["--global"];
-    const agentArgs = agent === "*" ? [] : ["--agent", agent];
-    const args = [getSkillsCliPath(), "list", "--json", ...agentArgs, ...scopeArgs];
+/** Strip ANSI escapes so the skills CLI's colored output reads cleanly when we re-emit it. */
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\u001b\[[0-9;?]*[a-zA-Z]/g, "");
+}
+/**
+ * The stdout/stderr a failed `execFileSync` captured, as readable text.
+ *
+ * Node attaches the captured pipes to the thrown error. Without this the real
+ * diagnosis — e.g. `Invalid agents: qwen / Valid agents: ...` — is discarded and
+ * the user is left with a generic message that names the wrong problem.
+ */
+function capturedOutput(err) {
+    if (typeof err !== "object" || err === null)
+        return "";
+    const { stderr, stdout } = err;
+    return [stderr, stdout]
+        .map((stream) => typeof stream === "string"
+        ? stream
+        : Buffer.isBuffer(stream)
+            ? stream.toString("utf-8")
+            : "")
+        .map((text) => stripAnsi(text).trim())
+        .filter((text) => text.length > 0)
+        .join("\n");
+}
+/**
+ * Run the bundled skills CLI, surfacing its own output when it fails.
+ *
+ * Fail loud: the skills CLI already explains precisely what went wrong (unknown
+ * agent slug, and the full list of valid ones). Swallowing that and substituting
+ * a generic sentence masks the error, so its output is always re-emitted.
+ */
+function runSkillsCli(args, summary) {
     try {
-        const stdout = execFileSync(process.execPath, args, {
+        return execFileSync(process.execPath, [getSkillsCliPath(), ...args], {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
         });
+    }
+    catch (err) {
+        const detail = capturedOutput(err);
+        log.debug("skills cli failed", {
+            args,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw new CliError(detail.length > 0 ? `${summary}\n\n${detail}` : summary);
+    }
+}
+/**
+ * Reject an agent slug the skills package does not know, before doing any work.
+ *
+ * The skills package keeps its agent registry private (no export, no
+ * list-agents subcommand), so the package itself is the only authority on which
+ * slugs are valid. `skills list --agent <slug>` consults that registry, is
+ * read-only, and exits non-zero with `Invalid agents: ... / Valid agents: ...`.
+ * Running it as a precheck means a typo fails in milliseconds with the real
+ * list, rather than after a browser sign-in round-trip.
+ */
+export function assertKnownAgent(agent) {
+    if (agent === "*")
+        return;
+    runSkillsCli(["list", "--json", "--agent", agent, "--global"], `Unknown agent "${agent}".`);
+}
+function listInstalledSkills(agent, project) {
+    const scopeArgs = project ? [] : ["--global"];
+    const agentArgs = agent === "*" ? [] : ["--agent", agent];
+    const stdout = runSkillsCli(["list", "--json", ...agentArgs, ...scopeArgs], "Could not inspect existing installed skills before installing.");
+    try {
         const parsed = JSON.parse(stdout);
         return Array.isArray(parsed) ? parsed : [];
     }
     catch (err) {
-        log.debug("skills list failed", {
+        log.debug("skills list returned unparsable JSON", {
             error: err instanceof Error ? err.message : String(err),
         });
-        throw new CliError("Could not inspect existing installed skills before installing.");
+        throw new CliError(`Could not parse the skills package's list output.\n\n${stripAnsi(stdout).trim()}`);
     }
 }
 function assertNoInstalledZeNormSkills(agent, project, force) {
@@ -170,6 +232,18 @@ function runSkillsInstaller(agent, project, force) {
         throw new CliError("Failed to install ZeNorm skills. Check the output above for details.");
     }
 }
+/**
+ * Install the bundled ZeNorm skills for one skills-package agent slug.
+ *
+ * The shared boundary behind both `zenorm install-skills <agent>` and
+ * `zenorm setup <agent>` — the slug is validated here, so a missing/unknown
+ * agent fails loud in either entry point rather than defaulting to anything.
+ */
+export function installSkillsForAgent(requestedAgent, opts) {
+    const agent = normalizeAgent(requestedAgent);
+    assertKnownAgent(agent);
+    runSkillsInstaller(agent, opts.project, opts.force);
+}
 export async function installSkillsCommand(args) {
     const { positionals, values } = parseArgs({
         args,
@@ -181,7 +255,7 @@ export async function installSkillsCommand(args) {
             "target-dir": { type: "string" },
         },
         strict: true,
-    });
+    }, "install-skills");
     const targetDir = values["target-dir"];
     if (targetDir !== undefined) {
         if (positionals.length > 0) {
@@ -195,14 +269,16 @@ export async function installSkillsCommand(args) {
     }
     const requestedAgent = positionals[0];
     if (!requestedAgent) {
-        throw new CliError(`Missing agent.\n\n${USAGE}`);
+        throw new CliError(`Missing agent.\n\n${INSTALL_SKILLS_USAGE}`);
     }
     if (positionals.length > 1) {
-        throw new CliError(`Unexpected extra argument: ${positionals[1]}\n\n${USAGE}`);
+        throw new CliError(`Unexpected extra argument: ${positionals[1]}\n\n${INSTALL_SKILLS_USAGE}`);
     }
     if (values.global && values.project) {
         throw new CliError("Choose only one scope: --global or --project.");
     }
-    const agent = normalizeAgent(requestedAgent);
-    runSkillsInstaller(agent, values.project === true, values.force === true);
+    installSkillsForAgent(requestedAgent, {
+        project: values.project === true,
+        force: values.force === true,
+    });
 }

package/dist/commands/login.d.ts

@@ -1,2 +1,28 @@
+/**
+ * How an `ensureAuthenticated()` call resolved. `setup` uses this to report
+ * "already logged in, skipping" vs. "logged you in just now" honestly, without
+ * re-running the browser flow.
+ */
+export type AuthMode = "local-dev-bypass" | "already-authenticated" | "logged-in";
+export interface AuthResult {
+    mode: AuthMode;
+    userId: string;
+    orgId: string;
+}
+/**
+ * The single shared auth path used by both `zenorm login` and `zenorm setup`.
+ *
+ * Order of resolution:
+ *  1. Local dev-bypass target (localhost + bypass enabled) — no credentials.
+ *  2. Existing stored/env credentials that the API still accepts.
+ *  3. The real browser device-auth flow.
+ *
+ * `force` skips step 2 so an explicit `zenorm login` always re-authenticates.
+ */
+export declare function ensureAuthenticated(opts: {
+    force: boolean;
+}): Promise<AuthResult>;
+/** Print the human-readable result of an `ensureAuthenticated()` call. */
+export declare function reportAuthResult(result: AuthResult): void;
 export declare function loginCommand(argv: string[]): Promise<void>;
 //# sourceMappingURL=login.d.ts.map

package/dist/commands/login.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/commands/login.ts"],"names":[],"mappings":"AAMA,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChE"}
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/commands/login.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,kBAAkB,GAAG,uBAAuB,GAAG,WAAW,CAAC;AAElF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAyBvF;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAiBzD;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhE"}

package/dist/commands/login.js

@@ -1,24 +1,28 @@
-import { parseArgs } from "node:util";
+import { parseArgs } from "../util/parse-args.js";
 import { runDeviceAuthFlow } from "../auth/device-flow.js";
-import { saveCredentials } from "../auth/store.js";
+import { loadCredentials, saveCredentials } from "../auth/store.js";
 import { ZenormClient } from "../api/client.js";
 import { log } from "../util/logger.js";
-export async function loginCommand(argv) {
-    const { values } = parseArgs({
-        args: argv,
-        options: {
-            "skip-skills": { type: "boolean", default: false },
-        },
-        strict: true,
-    });
-    log.info("Logging in to ZeNorm...");
+/**
+ * The single shared auth path used by both `zenorm login` and `zenorm setup`.
+ *
+ * Order of resolution:
+ *  1. Local dev-bypass target (localhost + bypass enabled) — no credentials.
+ *  2. Existing stored/env credentials that the API still accepts.
+ *  3. The real browser device-auth flow.
+ *
+ * `force` skips step 2 so an explicit `zenorm login` always re-authenticates.
+ */
+export async function ensureAuthenticated(opts) {
     const localCtx = await tryLocalDevelopmentLogin();
     if (localCtx) {
-        log.success("Logged in using local development mode.");
-        log.info(`User:  ${localCtx.userId}`);
-        log.info(`Org:   ${localCtx.orgId}`);
-        log.dim("No credentials were stored; local API requests use development headers.");
-        return;
+        return { mode: "local-dev-bypass", userId: localCtx.userId, orgId: localCtx.orgId };
+    }
+    if (!opts.force) {
+        const existing = await tryExistingCredentials();
+        if (existing) {
+            return { mode: "already-authenticated", userId: existing.userId, orgId: existing.orgId };
+        }
     }
     // Run browser-based authorization flow for hosted environments.
     const creds = await runDeviceAuthFlow();
@@ -29,12 +33,58 @@ export async function loginCommand(argv) {
     creds.userId = ctx.userId;
     // Persist credentials
     saveCredentials(creds);
-    log.success("Logged in successfully.");
-    log.info(`User:  ${creds.userId}`);
-    log.info(`Org:   ${creds.orgId}`);
-    // Skill installation step
-    if (!values["skip-skills"]) {
-        log.debug("Skill installation will be added later.");
+    return { mode: "logged-in", userId: creds.userId, orgId: creds.orgId };
+}
+/** Print the human-readable result of an `ensureAuthenticated()` call. */
+export function reportAuthResult(result) {
+    switch (result.mode) {
+        case "local-dev-bypass":
+            log.success("Logged in using local development mode.");
+            break;
+        case "already-authenticated":
+            log.success("Already logged in — skipping the browser sign-in.");
+            break;
+        case "logged-in":
+            log.success("Logged in successfully.");
+            break;
+    }
+    log.info(`User:  ${result.userId}`);
+    log.info(`Org:   ${result.orgId}`);
+    if (result.mode === "local-dev-bypass") {
+        log.dim("No credentials were stored; local API requests use development headers.");
+    }
+}
+export async function loginCommand(argv) {
+    parseArgs({
+        args: argv,
+        options: {},
+        strict: true,
+    }, "login");
+    log.info("Logging in to ZeNorm...");
+    // `login` is an explicit "sign me in" request, so it always runs the flow
+    // rather than short-circuiting on existing credentials.
+    const result = await ensureAuthenticated({ force: true });
+    reportAuthResult(result);
+    if (result.mode !== "local-dev-bypass") {
+        log.dim("Next: run `zenorm setup <agent>` to install the ZeNorm skills for your coding agent.");
+    }
+}
+/**
+ * Probe already-stored (or env-provided) credentials against the API. Returns
+ * null when there is nothing stored or the API rejects what we have, so the
+ * caller falls through to the real sign-in flow instead of pretending we are
+ * authenticated.
+ */
+async function tryExistingCredentials() {
+    if (!process.env["ZENORM_API_TOKEN"] && !loadCredentials()) {
+        return null;
+    }
+    try {
+        const ctx = await new ZenormClient().getAuthContext();
+        return { userId: ctx.userId, orgId: ctx.orgId };
+    }
+    catch {
+        return null;
     }
 }
 async function tryLocalDevelopmentLogin() {

package/dist/commands/pull.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../src/commands/pull.ts"],"names":[],"mappings":"AAcA,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8F/D"}
+{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../src/commands/pull.ts"],"names":[],"mappings":"AAcA,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiG/D"}

package/dist/commands/pull.js

@@ -1,4 +1,4 @@
-import { parseArgs } from "node:util";
+import { parseArgs } from "../util/parse-args.js";
 import { writeFileSync } from "node:fs";
 import { ZenormClient } from "../api/client.js";
 import { CliError } from "../util/errors.js";
@@ -12,7 +12,7 @@ export async function pullCommand(argv) {
             output: { type: "string", short: "o" },
         },
         strict: true,
-    });
+    }, "pull");
     const specRef = positionals[0];
     if (!specRef) {
         throw new CliError("Missing spec key or id.\n\nUsage: zenorm pull <spec-key-or-id> [-o <file>]");

package/dist/commands/setup.d.ts

@@ -0,0 +1,18 @@
+import { type SupportedAgent } from "./work.js";
+/** Exported so tests can assert every advertised slug is one the skills package accepts. */
+export declare const SETUP_USAGE = "Usage:\n  zenorm setup <agent> [--project|--global] [--force]\n\nOne-shot onboarding: signs you in (if you aren't already), installs the bundled\nZeNorm skills for your coding agent, and prints what to do next.\n\nExamples:\n  zenorm setup claude-code\n  zenorm setup codex --project\n  zenorm setup cursor --force\n\nOptions:\n  --project   Install skills into the current project instead of globally\n  --global    Install skills into the global agent directories (default)\n  --force     Reinstall skills even if ZeNorm skills are already present\n\n<agent> is a skills-package slug, such as claude-code, codex, cursor, opencode,\ngemini-cli, github-copilot, windsurf, qwen-code, kiro-cli, cline, or roo. An\nunknown slug is rejected up front with the full list of valid agents.";
+/**
+ * Translate a skills-package slug into the `zenorm work --agent` value, or null
+ * when that agent has no daemon support. Exported for unit testing.
+ */
+export declare function workAgentForSkillsSlug(skillsSlug: string): SupportedAgent | null;
+/**
+ * The harness-native invocation each agent uses to trigger the ZeNorm skill
+ * from inside its own session. Every agent that can install skills has one;
+ * this is what we point non-`work` agents at. Exported for unit testing.
+ */
+export declare function harnessInvocation(skillsSlug: string): string;
+/** Print the closing "what to do next" block. Exported for unit testing. */
+export declare function nextStepsLines(skillsSlug: string): string[];
+export declare function setupCommand(argv: string[]): Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/commands/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAKA,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAElE,4FAA4F;AAC5F,eAAO,MAAM,WAAW,kxBAkB8C,CAAC;AAoBvE;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAiC3D;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhE"}

package/dist/commands/setup.js

@@ -0,0 +1,136 @@
+import { parseArgs } from "../util/parse-args.js";
+import { CliError } from "../util/errors.js";
+import { log } from "../util/logger.js";
+import { ensureAuthenticated, reportAuthResult } from "./login.js";
+import { assertKnownAgent, installSkillsForAgent, normalizeAgent } from "./install-skills.js";
+import { SUPPORTED_AGENTS } from "./work.js";
+/** Exported so tests can assert every advertised slug is one the skills package accepts. */
+export const SETUP_USAGE = `Usage:
+  zenorm setup <agent> [--project|--global] [--force]
+
+One-shot onboarding: signs you in (if you aren't already), installs the bundled
+ZeNorm skills for your coding agent, and prints what to do next.
+
+Examples:
+  zenorm setup claude-code
+  zenorm setup codex --project
+  zenorm setup cursor --force
+
+Options:
+  --project   Install skills into the current project instead of globally
+  --global    Install skills into the global agent directories (default)
+  --force     Reinstall skills even if ZeNorm skills are already present
+
+<agent> is a skills-package slug, such as claude-code, codex, cursor, opencode,
+gemini-cli, github-copilot, windsurf, qwen-code, kiro-cli, cline, or roo. An
+unknown slug is rejected up front with the full list of valid agents.`;
+/**
+ * The agent-slug mismatch, made explicit.
+ *
+ * `install-skills` speaks skills-package slugs (`claude-code`, `cursor`, ...)
+ * while `zenorm work --agent` accepts only the two agents it can actually
+ * spawn (`claude` | `codex` — see SUPPORTED_AGENTS). They are NOT the same
+ * vocabulary: `claude-code` is valid for one and rejected by the other.
+ *
+ * This map is the single translation point. A skills slug that is absent from
+ * it has no `zenorm work` equivalent, and `setup` says so instead of printing a
+ * command the CLI would reject. Typed against `SupportedAgent` so a value that
+ * `work` does not accept cannot be added here.
+ */
+const WORK_AGENT_BY_SKILLS_SLUG = {
+    "claude-code": "claude",
+    codex: "codex",
+};
+/**
+ * Translate a skills-package slug into the `zenorm work --agent` value, or null
+ * when that agent has no daemon support. Exported for unit testing.
+ */
+export function workAgentForSkillsSlug(skillsSlug) {
+    return WORK_AGENT_BY_SKILLS_SLUG[skillsSlug] ?? null;
+}
+/**
+ * The harness-native invocation each agent uses to trigger the ZeNorm skill
+ * from inside its own session. Every agent that can install skills has one;
+ * this is what we point non-`work` agents at. Exported for unit testing.
+ */
+export function harnessInvocation(skillsSlug) {
+    switch (skillsSlug) {
+        case "codex":
+            return "$zenorm <SPEC-KEY>";
+        case "cursor":
+            return "@zenorm <SPEC-KEY>";
+        default:
+            return "/zenorm <SPEC-KEY>";
+    }
+}
+/** Print the closing "what to do next" block. Exported for unit testing. */
+export function nextStepsLines(skillsSlug) {
+    const workAgent = workAgentForSkillsSlug(skillsSlug);
+    const invocation = harnessInvocation(skillsSlug);
+    const lines = [
+        "",
+        "Next steps:",
+        "  1. cd into the git repository you want to work in. Its `origin` remote must",
+        "     match a repository you have imported into ZeNorm — that is how ZeNorm",
+        "     knows which tasks belong to this checkout.",
+    ];
+    if (workAgent) {
+        lines.push(`  2. Run the task daemon there:  zenorm work --agent ${workAgent}`, `     It claims ready tasks for that repo and hands each one to ${skillsSlug}.`, `  3. Or, inside a ${skillsSlug} session, invoke a spec directly:  ${invocation}`);
+    }
+    else {
+        // Honest fallback: do NOT print a `zenorm work --agent <slug>` line that
+        // `work` would reject. `${skillsSlug}` has skills but no daemon runner.
+        lines.push(`  2. \`zenorm work\` does not support ${skillsSlug} — it can only run ` +
+            `${SUPPORTED_AGENTS.join(" or ")}.`, `     Instead, start a ${skillsSlug} session in that repo and invoke ZeNorm`, `     in-harness:  ${invocation}`, `     (To use the daemon, run \`zenorm setup ${Object.keys(WORK_AGENT_BY_SKILLS_SLUG).join("` or `zenorm setup ")}\` as well.)`);
+    }
+    return lines;
+}
+export async function setupCommand(argv) {
+    const { positionals, values } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            global: { type: "boolean", default: false },
+            project: { type: "boolean", default: false },
+            force: { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        strict: true,
+    }, "setup");
+    if (values.help === true) {
+        log.plain(SETUP_USAGE);
+        return;
+    }
+    const requestedAgent = positionals[0];
+    if (!requestedAgent) {
+        throw new CliError(`Missing agent.\n\n${SETUP_USAGE}`);
+    }
+    if (positionals.length > 1) {
+        throw new CliError(`Unexpected extra argument: ${positionals[1]}\n\n${SETUP_USAGE}`);
+    }
+    if (values.global && values.project) {
+        throw new CliError("Choose only one scope: --global or --project.");
+    }
+    // Validate the slug BEFORE the login round-trip, so a typo fails immediately
+    // instead of after a browser sign-in. Shape check first, then the real
+    // registry check against the skills package — a well-formed but unknown slug
+    // (`qwen` rather than `qwen-code`) must not survive until after auth.
+    const agent = normalizeAgent(requestedAgent);
+    if (agent === "*") {
+        throw new CliError(`\`zenorm setup\` takes a single agent, not "${requestedAgent}".\n` +
+            `Run \`zenorm install-skills '*'\` to install skills for every agent.\n\n${SETUP_USAGE}`);
+    }
+    assertKnownAgent(agent);
+    log.info(`Setting up ZeNorm for ${agent}...`);
+    log.plain("");
+    log.info("Step 1/2 — authentication");
+    const authResult = await ensureAuthenticated({ force: false });
+    reportAuthResult(authResult);
+    log.plain("");
+    log.info("Step 2/2 — skills");
+    installSkillsForAgent(agent, {
+        project: values.project === true,
+        force: values.force === true,
+    });
+    log.plain(nextStepsLines(agent).join("\n"));
+}

package/dist/commands/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/commands/task.ts"],"names":[],"mappings":"AA2OA,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/D"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/commands/task.ts"],"names":[],"mappings":"AA0PA,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/D"}

package/dist/commands/task.js

@@ -1,4 +1,4 @@
-import { parseArgs } from "node:util";
+import { parseArgs } from "../util/parse-args.js";
 import { ZenormClient } from "../api/client.js";
 import { CliError } from "../util/errors.js";
 import { log } from "../util/logger.js";
@@ -47,7 +47,7 @@ async function listTasks(argv) {
         args: argv,
         allowPositionals: true,
         strict: true,
-    });
+    }, "task list");
     const specKey = positionals[0];
     if (!specKey) {
         throw new CliError("Missing spec key.\n\nUsage: zenorm task list <spec-key>");
@@ -75,7 +75,7 @@ async function updateTask(argv) {
             status: { type: "string" },
         },
         strict: true,
-    });
+    }, "task update");
     const taskId = positionals[0];
     if (!taskId) {
         throw new CliError("Missing task ID.\n\nUsage: zenorm task update <task-id> --status=<status>");
@@ -105,7 +105,7 @@ async function completeTask(argv) {
             "session-id": { type: "string" },
         },
         strict: true,
-    });
+    }, "task complete");
     const taskId = positionals[0];
     if (!taskId) {
         throw new CliError("Missing task ID.\n\nUsage: zenorm task complete <task-id> --summary=\"...\"");
@@ -146,7 +146,7 @@ async function startSpec(argv) {
         args: argv,
         allowPositionals: true,
         strict: true,
-    });
+    }, "task start-spec");
     const specKey = positionals[0];
     if (!specKey) {
         throw new CliError("Missing spec key.\n\nUsage: zenorm task start-spec <spec-key>");
@@ -166,7 +166,7 @@ async function createTask(argv) {
             description: { type: "string" },
         },
         strict: true,
-    });
+    }, "task create");
     const specKey = positionals[0];
     if (!specKey) {
         throw new CliError("Missing spec key.\n\nUsage: zenorm task create <spec-key> --title=\"...\"");

package/dist/commands/work.d.ts

@@ -7,8 +7,8 @@ import { type TtyProbe } from "./interactive-agent.js";
  * unknown/missing `--agent` fails loud rather than silently defaulting (project
  * rule: no error-masking defaults).
  */
-declare const SUPPORTED_AGENTS: readonly ["codex", "claude"];
-type SupportedAgent = (typeof SUPPORTED_AGENTS)[number];
+export declare const SUPPORTED_AGENTS: readonly ["codex", "claude"];
+export type SupportedAgent = (typeof SUPPORTED_AGENTS)[number];
 /**
  * A pluggable per-task runner. The work loop calls `run(task)` after a
  * successful claim. The default is the real `AgentRunner` (which spawns the

package/dist/commands/work.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"work.d.ts","sourceRoot":"","sources":["../../src/commands/work.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"work.d.ts","sourceRoot":"","sources":["../../src/commands/work.ts"],"names":[],"mappings":"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"}

package/dist/commands/work.js

@@ -1,4 +1,5 @@
 import { parseArgs } from "node:util";
+import { parseArgsErrorMessage } from "../util/parse-args.js";
 import { execFileSync, spawn } from "node:child_process";
 import { ZenormClient } from "../api/client.js";
 import { CliError } from "../util/errors.js";
@@ -11,7 +12,7 @@ import { LineSplitter, claudeRenderer, codexRenderer, daemonBanner, failureBanne
  * unknown/missing `--agent` fails loud rather than silently defaulting (project
  * rule: no error-masking defaults).
  */
-const SUPPORTED_AGENTS = ["codex", "claude"];
+export const SUPPORTED_AGENTS = ["codex", "claude"];
 /**
  * The AC requires ready tasks to be picked up within 10 seconds, so the poll
  * interval is hard-capped at this value. Requests above the cap fail loud — we
@@ -623,8 +624,7 @@ function parseWorkArgs(argv) {
         }));
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new CliError(`Invalid zenorm work arguments: ${message}\n\n${USAGE}`);
+        throw new CliError(`Invalid zenorm work arguments: ${parseArgsErrorMessage(err)}\n\n${USAGE}`);
     }
     const agent = values["agent"];
     if (!agent) {

package/dist/index.js

@@ -9,6 +9,7 @@ import { taskCommand } from "./commands/task.js";
 import { workCommand } from "./commands/work.js";
 import { initCommand } from "./commands/init.js";
 import { installSkillsCommand } from "./commands/install-skills.js";
+import { setupCommand } from "./commands/setup.js";
 import { sessionCheckCommand } from "./commands/session-check.js";
 import { getCliVersion } from "./util/package.js";
 import { armSelfUpdate } from "./util/self-update.js";
@@ -18,6 +19,7 @@ Usage:
   zenorm <command> [options]
 
 Commands:
+  setup <agent>  One-shot onboarding: log in + install skills for an agent
   login          Authenticate with ZeNorm (device auth flow)
   logout         Clear stored credentials
   whoami         Show current auth context
@@ -38,6 +40,7 @@ Verbosity can also be set with the LOG_LEVEL env var
 `;
 const VERBOSE_FLAGS = new Set(["--verbose", "--debug"]);
 const commands = {
+    setup: setupCommand,
     login: loginCommand,
     logout: logoutCommand,
     whoami: whoamiCommand,
@@ -48,6 +51,13 @@ const commands = {
     "install-skills": installSkillsCommand,
     "session-check": sessionCheckCommand,
 };
+/**
+ * Commands that render their own `--help`. For these, the top-level handler
+ * forwards `--help` to the command rather than printing the global help.
+ * Anything not listed keeps the existing behaviour (global help), so this is
+ * additive and cannot change another command's output.
+ */
+const SELF_DOCUMENTING_COMMANDS = new Set(["setup"]);
 async function main() {
     const rawArgs = process.argv.slice(2);
     // Validate LOG_LEVEL (throws CliError on bad value, caught below).
@@ -72,7 +82,11 @@ async function main() {
         log.plain(`zenorm ${getCliVersion()}`);
         return;
     }
-    if (!commandName || args.includes("--help") || args.includes("-h")) {
+    const wantsHelp = args.includes("--help") || args.includes("-h");
+    // Top-level help: no command named, or a command that has no help of its own.
+    // When a command IS named and knows how to print its own usage, fall through
+    // so `zenorm <command> --help` shows that command's usage instead of this.
+    if (!commandName || (wantsHelp && !SELF_DOCUMENTING_COMMANDS.has(commandName))) {
         log.plain(helpText);
         return;
     }
@@ -83,9 +97,14 @@ async function main() {
     // Pass everything after the command name to the handler.
     // Routed to stderr (debugErr): `session-check` reserves stdout for the
     // Claude Code hook protocol, and this dispatch line runs for every command.
+    // Everything except the command token itself, so flags written BEFORE the
+    // command (`zenorm --help setup`) reach the handler just like trailing ones.
+    // Only the first occurrence is dropped — a later identical token is a real
+    // argument (e.g. `zenorm work work`), not the command name.
     const commandIndex = args.indexOf(commandName);
-    log.debugErr(`Dispatching command "${commandName}"`, { args: args.slice(commandIndex + 1) });
-    await handler(args.slice(commandIndex + 1));
+    const commandArgs = [...args.slice(0, commandIndex), ...args.slice(commandIndex + 1)];
+    log.debugErr(`Dispatching command "${commandName}"`, { args: commandArgs });
+    await handler(commandArgs);
 }
 main().catch((err) => {
     if (err instanceof CliError) {

package/dist/util/parse-args.d.ts

@@ -0,0 +1,27 @@
+import { parseArgs as nodeParseArgs } from "node:util";
+type NodeParseArgsConfig = NonNullable<Parameters<typeof nodeParseArgs>[0]>;
+/**
+ * Every command parses its flags with `strict: true`, so a typo like
+ * `zenorm login --skip-skills` makes Node throw an `ERR_PARSE_ARGS_*`
+ * TypeError. Those are not `CliError`s, so `index.ts` treats them as
+ * unexpected and dumps a raw stack trace at the user.
+ *
+ * This wrapper is the single place that translates them into a `CliError`
+ * with a one-line message naming the offending flag and pointing at `--help`.
+ * Exit code stays 1, same as any other CliError.
+ */
+export declare function parseArgs<T extends NodeParseArgsConfig>(config: T, 
+/**
+ * The command name used in the `--help` hint, e.g. `"login"` or
+ * `"task update"`. Required — a generic hint would send users to the wrong
+ * usage text.
+ */
+commandName: string): ReturnType<typeof nodeParseArgs<T>>;
+/**
+ * Node's messages carry a trailing hint about passing `--` for positionals
+ * that start with a dash, which is noise for a mistyped flag. Keep only the
+ * first sentence, which is the part that names the bad option.
+ */
+export declare function parseArgsErrorMessage(err: unknown): string;
+export {};
+//# sourceMappingURL=parse-args.d.ts.map

package/dist/util/parse-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../../src/util/parse-args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,WAAW,CAAC;AAGvD,KAAK,mBAAmB,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE5E;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,mBAAmB,EACrD,MAAM,EAAE,CAAC;AACT;;;;GAIG;AACH,WAAW,EAAE,MAAM,GAClB,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAMrC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAQ1D"}

package/dist/util/parse-args.js

@@ -0,0 +1,42 @@
+import { parseArgs as nodeParseArgs } from "node:util";
+import { CliError } from "./errors.js";
+/**
+ * Every command parses its flags with `strict: true`, so a typo like
+ * `zenorm login --skip-skills` makes Node throw an `ERR_PARSE_ARGS_*`
+ * TypeError. Those are not `CliError`s, so `index.ts` treats them as
+ * unexpected and dumps a raw stack trace at the user.
+ *
+ * This wrapper is the single place that translates them into a `CliError`
+ * with a one-line message naming the offending flag and pointing at `--help`.
+ * Exit code stays 1, same as any other CliError.
+ */
+export function parseArgs(config, 
+/**
+ * The command name used in the `--help` hint, e.g. `"login"` or
+ * `"task update"`. Required — a generic hint would send users to the wrong
+ * usage text.
+ */
+commandName) {
+    try {
+        return nodeParseArgs(config);
+    }
+    catch (err) {
+        throw new CliError(`${parseArgsErrorMessage(err)}\n\nRun \`zenorm ${commandName} --help\` for usage.`);
+    }
+}
+/**
+ * Node's messages carry a trailing hint about passing `--` for positionals
+ * that start with a dash, which is noise for a mistyped flag. Keep only the
+ * first sentence, which is the part that names the bad option.
+ */
+export function parseArgsErrorMessage(err) {
+    if (!(err instanceof Error))
+        throw err;
+    const code = err.code;
+    if (typeof code !== "string" || !code.startsWith("ERR_PARSE_ARGS_"))
+        throw err;
+    const firstSentence = err.message.split(". ")[0];
+    if (firstSentence === undefined || firstSentence.length === 0)
+        throw err;
+    return firstSentence.endsWith(".") ? firstSentence : `${firstSentence}.`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ze-norm/cli",
   "private": false,
-  "version": "0.14.2",
+  "version": "0.15.0",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
   "repository": {