@crouton-kit/crouter 0.2.6 → 0.3.2

package/dist/builtin-skills/skills/crouter-development/marketplaces/SKILL.md

@@ -7,13 +7,13 @@ keywords: [marketplace, marketplace.json, plugin, index, publishing]
 
 # Authoring crtr marketplaces
 
-A **marketplace** is a git repo that indexes multiple plugins. Users register it once, then `crtr marketplace install <mkt>:<plugin>` symlinks any plugin from it. One `crtr marketplace update` pulls updates for every installed plugin at once.
+A **marketplace** is a git repo that indexes multiple plugins. Users register it once, then `crtr pkg market manage install --marketplace <mkt> --plugin <plugin>` symlinks any plugin from it. `crtr pkg market manage update --marketplace <mkt>` pulls updates for every installed plugin at once.
 
 Audience: LLM agents creating a marketplace or adding plugins to an existing one.
 
 ## When you need a marketplace (vs a single-plugin repo)
 
-A solo plugin ships from any git URL via `crtr plugin install <url>` — no marketplace needed.
+A solo plugin ships from any git URL via `crtr pkg plugin manage install <url> --scope user` — no marketplace needed.
 
 Reach for a marketplace when:
 - You want to publish ≥3 plugins under one brand or theme.
@@ -70,12 +70,12 @@ The `plugins[]` array IS the index — what's installable. A plugin on disk but
 
 ## Install mechanics — symlinks, not clones
 
-When a user runs `crtr marketplace install my-marketplace:plugin-a`:
+When a user runs `crtr pkg market manage install --marketplace my-marketplace --plugin plugin-a`:
 1. Crouter looks up `plugin-a` in the marketplace's manifest.
 2. **Symlinks** `<marketplace-clone>/plugins/plugin-a/` → `<user-scope>/plugins/plugin-a/`.
 3. Records the install in the scope config with `source_marketplace: my-marketplace`.
 
-Therefore one `crtr marketplace update my-marketplace` (which does `git pull` in the marketplace clone) updates every installed plugin from it — no per-plugin re-install, no second clone.
+Therefore `crtr pkg market manage update --marketplace my-marketplace` (which does `git pull` in the marketplace clone) updates every installed plugin from it — no per-plugin re-install, no second clone.
 
 ## Version-bump automation (recommended)
 
@@ -107,14 +107,14 @@ mkdir -p plugins/my-new-plugin/.crouter-plugin plugins/my-new-plugin/skills
 $EDITOR plugins/my-new-plugin/.crouter-plugin/plugin.json
 
 # Add at least one skill
-crtr skill new my-new-plugin:first-skill --type playbook --description "Use when …"
+crtr skill author scaffold my-new-plugin:first-skill --type playbook --description "Use when …"
 
 # Add the plugin to the marketplace index
 $EDITOR .crouter-marketplace/marketplace.json
 # (append to plugins[] with name, initial version, source, description)
 
 # Validate
-crtr doctor
+crtr sys doctor
 
 # Commit — CI bumps versions if you've wired up auto-bump
 git add -A
@@ -122,7 +122,7 @@ git commit -m "feat: add my-new-plugin"
 git push
 ```
 
-Existing users pick it up on their next `crtr marketplace update <marketplace-name>` (or on the next auto-update tick if they've set `auto_update.content: "apply"`).
+Existing users pick it up on their next `crtr pkg market manage update --marketplace <marketplace-name>` (or on the next auto-update tick if they've set `auto_update.content: "apply"`).
 
 ## Updating an existing plugin
 
@@ -141,11 +141,11 @@ A marketplace itself registers per-scope:
 | user | `~/.crouter/marketplaces/<name>/` | Private to your machine — your personal subscriptions |
 | project | `<project>/.crouter/marketplaces/<name>/` | Checked into the repo — anyone cloning gets the same marketplace pinned |
 
-`crtr marketplace add <git-url> --scope user` is the default. Use `--scope project` when the marketplace is integral to how the repo expects to be developed.
+`crtr pkg market manage add --url <git-url> --scope user` is the default. Use `--scope project` when the marketplace is integral to how the repo expects to be developed.
 
 ## Validation
 
-`crtr doctor` checks marketplaces:
+`crtr sys doctor` checks marketplaces:
 - `marketplace.json` is valid JSON.
 - Every entry in `plugins[]` corresponds to a real directory under `plugins/`.
 - Each plugin under `plugins/` passes plugin-level validation.

package/dist/builtin-skills/skills/crouter-development/plugins/SKILL.md

@@ -17,7 +17,7 @@ Scope-owned skills live at `~/.crouter/skills/` (user) or `<project>/.crouter/sk
 
 Reach for a **plugin** when:
 - You want to share skills across multiple projects or with other people.
-- You want versioning + update mechanics (`crtr plugin update`).
+- You want versioning + update mechanics (`crtr pkg plugin manage update --name <name>`).
 - You want a marketplace to index the work — see [[crouter-development/marketplaces]].
 
 If it's a one-off note for yourself, scope-owned skills are simpler. Promote to a plugin later.
@@ -43,7 +43,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 {
   "name": "my-plugin",
   "version": "0.1.0",
-  "description": "One sentence — shown in `crtr plugin list`.",
+  "description": "One sentence — shown in `crtr pkg plugin inspect list`.",
   "source": "https://github.com/<owner>/<repo>",
   "owner": {
     "name": "Your Name",
@@ -57,7 +57,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 | `name` | yes | Must match the directory name. Lowercase kebab. |
 | `version` | yes | Semver. Marketplace CI may bump automatically — see marketplaces skill. |
 | `description` | yes | One sentence. |
-| `source` | recommended | Git URL where the plugin lives. Used by `crtr plugin update`. |
+| `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin manage update --name <name>`. |
 | `owner` | optional | Author info. |
 
 ## Scopes
@@ -75,19 +75,19 @@ Project-scope plugins outrank user-scope on resolution. Both outrank marketplace
 
 Three ways a plugin lands in a scope:
 
-1. **From a git URL** (`crtr plugin install <url> --scope user`):
+1. **From a git URL** (`crtr pkg plugin manage install <url> --scope user`):
    - Clones into `<scope>/plugins/<name>/` using the manifest's name.
-   - `crtr plugin update <name>` does `git pull`.
+   - `crtr pkg plugin manage update --name <name>` does `git pull`.
    - Independent of any marketplace.
 
-2. **From a marketplace** (`crtr marketplace install <mkt>:<name> --scope user`):
+2. **From a marketplace** (`crtr pkg market manage install --marketplace <mkt> --plugin <name>`):
    - **Symlinks** the marketplace's `plugins/<name>/` into `<scope>/plugins/<name>/`.
-   - One `crtr marketplace update <mkt>` pulls updates for every installed plugin from that marketplace.
+   - `crtr pkg market manage update --marketplace <mkt>` pulls updates for every installed plugin from that marketplace.
    - See [[crouter-development/marketplaces]].
 
 3. **Authored in place** (you're writing the plugin in a working repo):
    - Symlink for tight dev loop: `ln -s $(pwd) ~/.crouter/plugins/<name>`.
-   - Or `crtr plugin install file://$(pwd) --scope project` to clone-install.
+   - Or `crtr pkg plugin manage install file://$(pwd) --scope project` to clone-install.
 
 ## Local development loop
 
@@ -96,19 +96,19 @@ Three ways a plugin lands in a scope:
 mkdir -p my-plugin/.crouter-plugin my-plugin/skills
 $EDITOR my-plugin/.crouter-plugin/plugin.json      # write the manifest
 cd my-plugin
-crtr skill new my-plugin:my-first-skill --type playbook --description "Use when …"
+crtr skill author scaffold my-plugin:my-first-skill --type playbook --description "Use when …"
 
 # Symlink for fast iteration — no clone, edits land immediately
 ln -s $(pwd) ~/.crouter/plugins/my-plugin
 
 # Verify
-crtr plugin list                      # my-plugin appears
-crtr plugin show my-plugin            # lists its skills
-crtr skill list --plugin my-plugin
-crtr doctor                           # validates manifest + every skill
+crtr pkg plugin inspect list                       # my-plugin appears
+crtr pkg plugin inspect show my-plugin             # lists its skills
+crtr skill find list --plugin my-plugin            # just my-plugin's skills
+crtr sys doctor                                    # validates manifest + every skill
 ```
 
-When ready to share: push to a git remote; anyone can `crtr plugin install <url>`.
+When ready to share: push to a git remote; anyone can `crtr pkg plugin manage install <url> --scope user`.
 
 ## Versioning
 
@@ -120,13 +120,13 @@ Standard semver:
 | New skill, new section, new example | minor (0.1.0 → 0.2.0) |
 | Removed skill, renamed skill, changed manifest schema | major (0.1.0 → 1.0.0) |
 
-`crtr plugin update <name>` reads the new version after pulling and updates the local config. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[crouter-development/marketplaces]].
+`crtr pkg plugin manage update --name <name>` reads the new version after pulling and updates the local config. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[crouter-development/marketplaces]].
 
 ## Enable/disable
 
-`crtr plugin disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr skill list` and don't resolve via `crtr skill show <name>`. Re-enable with `crtr plugin enable <name>`.
+`crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr skill find list` and don't resolve via `crtr skill read show <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
 
-Individual skills inside an enabled plugin can also be disabled: `crtr skill disable <plugin>:<skill>`.
+Individual skills inside an enabled plugin can also be disabled: `crtr skill state disable <plugin>:<skill>`.
 
 ## What goes in a plugin
 
@@ -145,10 +145,10 @@ If your skill conceptually depends on another plugin's skill, link via `## Relat
 
 ## Validation
 
-`crtr doctor` checks every plugin:
+`crtr sys doctor` checks every plugin:
 - Manifest exists and is valid JSON.
 - Manifest `name` matches the directory name.
-- Every skill under `skills/` passes the skill-validation contract (frontmatter parses, `name` matches dir path, `type` in enum). Run `crtr skill` (no args) for the full format reference.
+- Every skill under `skills/` passes the skill-validation contract (frontmatter parses, `name` matches dir path, `type` in enum). Run `crtr skill author guide` for the authoring workflow + SKILL.md format reference.
 - Sibling artifact dirs (`commands/`, `hooks/`, etc.) — validated by their respective specs as those land.
 
 ## Cross-publishing with Claude Code

package/dist/cli.js

@@ -1,46 +1,51 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { registerSkillCommands } from './commands/skill.js';
-import { registerPluginCommands } from './commands/plugin.js';
-import { registerMarketplaceCommands } from './commands/marketplace.js';
-import { registerConfigCommands } from './commands/config.js';
-import { registerUpdateCommand } from './commands/update.js';
-import { registerDoctorCommand } from './commands/doctor.js';
-import { registerPlanCommand } from './commands/plan.js';
-import { registerSpecCommand } from './commands/spec.js';
-import { registerAgentCommand } from './commands/agent.js';
+import { defineRoot, runCli } from './core/command.js';
+import { registerFlow } from './commands/flow.js';
+import { registerSkill } from './commands/skill.js';
+import { registerPkg } from './commands/pkg.js';
+import { registerJob } from './commands/job.js';
+import { registerHuman } from './commands/human.js';
+import { registerSys } from './commands/sys.js';
 import { maybeAutoUpdate } from './core/auto-update.js';
 import { ensureBootSkill, ensureOfficialMarketplace, ensureProjectScope } from './core/bootstrap.js';
-function readPackageVersion() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkgPath = join(here, '..', 'package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-    if (typeof pkg.version === 'string')
-        return pkg.version;
-    return '0.0.0';
-}
-const program = new Command();
-program
-    .name('crtr')
-    .description('crtr — fast access to skills, plugins, and marketplaces')
-    .version(readPackageVersion(), '-v, --version');
-registerSkillCommands(program);
-registerPluginCommands(program);
-registerMarketplaceCommands(program);
-registerConfigCommands(program);
-registerUpdateCommand(program);
-registerDoctorCommand(program);
-registerPlanCommand(program);
-registerSpecCommand(program);
-registerAgentCommand(program);
+const root = defineRoot({
+    help: {
+        tagline: 'crtr: agentic planning runtime.',
+        concepts: [
+            { name: 'flow', desc: 'spec → plan → debug: the development process' },
+            { name: 'skill', desc: 'loadable SKILL.md document an agent reads to adopt a workflow' },
+            { name: 'pkg', desc: 'plugins and marketplaces that supply skills' },
+            { name: 'job', desc: 'a running agent worker and its logs and result' },
+            { name: 'human', desc: 'human-in-the-loop decisions, document review, and live display' },
+            { name: 'sys', desc: 'crtr configuration, diagnostics, and self-management' },
+        ],
+        subtrees: [
+            { name: 'flow', desc: 'spec, plan, and debug workflows', useWhen: 'capturing requirements, planning work, or root-causing a bug' },
+            { name: 'skill', desc: 'discover, read, author, and manage skills', useWhen: 'working with SKILL.md documents' },
+            { name: 'pkg', desc: 'manage plugins and marketplaces', useWhen: 'installing or browsing skill collections' },
+            { name: 'job', desc: 'spawn, monitor, and collect from agent workers', useWhen: 'running or watching agent jobs' },
+            { name: 'human', desc: 'ask, approve, review, notify, show, inbox, list', useWhen: 'putting a decision or document in front of a person' },
+            { name: 'sys', desc: 'config, doctor, update, version', useWhen: 'managing the crtr installation' },
+        ],
+        globals: [
+            { name: '-h', desc: 'print help for any node — append to any subcommand path' },
+        ],
+    },
+    subtrees: [
+        registerFlow(),
+        registerSkill(),
+        registerPkg(),
+        registerJob(),
+        registerHuman(),
+        registerSys(),
+    ],
+});
 ensureOfficialMarketplace(process.argv);
 ensureBootSkill(process.argv);
 ensureProjectScope(process.argv);
 maybeAutoUpdate(process.argv);
-program.parseAsync().catch((err) => {
-    process.stderr.write(`crtr: ${err instanceof Error ? err.message : String(err)}\n`);
+runCli(root, process.argv).catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`crtr: ${msg}\n`);
     process.exit(1);
 });

package/dist/commands/__tests__/human.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/human.test.js

@@ -0,0 +1,214 @@
+// Tests for the human subtree argv-model migration.
+// Run with: node --import tsx/esm --test 'src/commands/__tests__/human.test.ts'
+//
+// These tests exercise the leaf param schemas via parseArgv (framework) and
+// spot-check the leaf definitions directly — no subprocess spawning, no tmux.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { parseArgv } from '../../core/command.js';
+// ---------------------------------------------------------------------------
+// Helper: write a temp JSON file and return its path.
+// ---------------------------------------------------------------------------
+function tmpJson(obj) {
+    const dir = join(tmpdir(), `crtr-human-test-${randomBytes(4).toString('hex')}`);
+    mkdirSync(dir, { recursive: true });
+    const p = join(dir, 'deck.json');
+    writeFileSync(p, JSON.stringify(obj));
+    return p;
+}
+// ---------------------------------------------------------------------------
+// human approve — positional title + optional flags
+// ---------------------------------------------------------------------------
+describe('human approve: params', () => {
+    const params = [
+        { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'The question.' },
+        { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'One-line context.' },
+        { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Markdown body.' },
+    ];
+    test('parses positional title', async () => {
+        const result = await parseArgv(params, ['Deploy to prod?']);
+        assert.equal(result['title'], 'Deploy to prod?');
+    });
+    test('parses title with optional flags', async () => {
+        const result = await parseArgv(params, ['Deploy?', '--subtitle', 'v1.2.3', '--body', 'LGTM']);
+        assert.equal(result['title'], 'Deploy?');
+        assert.equal(result['subtitle'], 'v1.2.3');
+        assert.equal(result['body'], 'LGTM');
+    });
+    test('flags absent → undefined', async () => {
+        const result = await parseArgv(params, ['Deploy?']);
+        assert.equal(result['subtitle'], undefined);
+        assert.equal(result['body'], undefined);
+    });
+    test('missing title throws missing_parameter', async () => {
+        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
+    });
+});
+// ---------------------------------------------------------------------------
+// human review — positional file (path) + optional --output
+// ---------------------------------------------------------------------------
+describe('human review: params', () => {
+    const params = [
+        { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Existing .md file.' },
+        { kind: 'flag', name: 'output', type: 'path', required: false, constraint: 'Where to write feedback.' },
+    ];
+    test('parses positional file path', async () => {
+        const result = await parseArgv(params, ['/tmp/plan.md']);
+        assert.equal(result['file'], '/tmp/plan.md');
+    });
+    test('parses file + --output', async () => {
+        const result = await parseArgv(params, ['/tmp/plan.md', '--output', '/tmp/fb.json']);
+        assert.equal(result['file'], '/tmp/plan.md');
+        assert.equal(result['output'], '/tmp/fb.json');
+    });
+    test('missing file throws missing_parameter', async () => {
+        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
+    });
+});
+// ---------------------------------------------------------------------------
+// human notify — positional title + optional --body
+// ---------------------------------------------------------------------------
+describe('human notify: params', () => {
+    const params = [
+        { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'Headline.' },
+        { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Markdown body.' },
+    ];
+    test('parses positional title', async () => {
+        const result = await parseArgv(params, ['Build done']);
+        assert.equal(result['title'], 'Build done');
+    });
+    test('parses title + --body', async () => {
+        const result = await parseArgv(params, ['Done', '--body', 'All tests pass.']);
+        assert.equal(result['title'], 'Done');
+        assert.equal(result['body'], 'All tests pass.');
+    });
+});
+// ---------------------------------------------------------------------------
+// human show — positional path + --watch bool + --window enum
+// ---------------------------------------------------------------------------
+describe('human show: params', () => {
+    const params = [
+        { kind: 'positional', name: 'path', type: 'path', required: true, constraint: 'File to render.' },
+        { kind: 'flag', name: 'watch', type: 'bool', required: false, constraint: 'Presence = true.' },
+        { kind: 'flag', name: 'window', type: 'enum', choices: ['auto', 'split', 'new'], required: false, default: 'auto', constraint: 'Placement.' },
+    ];
+    test('parses positional path', async () => {
+        const result = await parseArgv(params, ['/tmp/doc.md']);
+        assert.equal(result['path'], '/tmp/doc.md');
+    });
+    test('--watch absent → false (presence-only bool default)', async () => {
+        const result = await parseArgv(params, ['/tmp/doc.md']);
+        assert.equal(result['watch'], false);
+    });
+    test('--watch present → true', async () => {
+        const result = await parseArgv(params, ['/tmp/doc.md', '--watch']);
+        assert.equal(result['watch'], true);
+    });
+    test('--watch=true is rejected (bool takes no value)', async () => {
+        await assert.rejects(() => parseArgv(params, ['/tmp/doc.md', '--watch=true']), (err) => { assert.match(err.message, /takes no value/); return true; });
+    });
+    test('--window default is auto', async () => {
+        const result = await parseArgv(params, ['/tmp/doc.md']);
+        assert.equal(result['window'], 'auto');
+    });
+    test('--window accepts valid enum value', async () => {
+        const result = await parseArgv(params, ['/tmp/doc.md', '--window', 'split']);
+        assert.equal(result['window'], 'split');
+    });
+    test('--window rejects invalid value', async () => {
+        await assert.rejects(() => parseArgv(params, ['/tmp/doc.md', '--window', 'float']), (err) => { assert.match(err.message, /must be one of/); return true; });
+    });
+});
+// ---------------------------------------------------------------------------
+// human ask — --context-file (context-file kind, key=deckFile) + --wait bool
+//
+// NOTE: The argv parser hardcodes the CLI token as `--context-file` regardless
+// of the param's `name` field. The `name` field ("deckFile") becomes the key
+// in the input record. So the correct invocation is:
+//   crtr human ask --context-file deck.json
+// not --deck-file. Tests use --context-file accordingly.
+// ---------------------------------------------------------------------------
+describe('human ask: params', () => {
+    const params = [
+        { kind: 'context-file', name: 'deckFile', required: true, constraint: 'Humanloop deck JSON.' },
+        { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'Presence-only.' },
+    ];
+    test('--context-file parses JSON file and yields input.deckFile', async () => {
+        const deck = { interactions: [{ id: 'q', title: 'Go?', options: [{ id: 'yes', label: 'Yes' }] }] };
+        const path = tmpJson(deck);
+        const result = await parseArgv(params, ['--context-file', path]);
+        assert.deepEqual(result['deckFile'], deck);
+    });
+    test('--context-file missing → missing_parameter', async () => {
+        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
+    });
+    test('--context-file with nonexistent file → invalid_type', async () => {
+        await assert.rejects(() => parseArgv(params, ['--context-file', '/no/such/deck.json']), (err) => { assert.match(err.message, /cannot read file/); return true; });
+    });
+    test('--context-file with non-JSON file → invalid_type', async () => {
+        const dir = join(tmpdir(), `crtr-human-test-${randomBytes(4).toString('hex')}`);
+        mkdirSync(dir, { recursive: true });
+        const p = join(dir, 'bad.json');
+        writeFileSync(p, 'not json at all');
+        await assert.rejects(() => parseArgv(params, ['--context-file', p]), (err) => { assert.match(err.message, /not valid JSON/); return true; });
+    });
+    test('--wait absent → false', async () => {
+        const deck = { interactions: [] };
+        const path = tmpJson(deck);
+        const result = await parseArgv(params, ['--context-file', path]);
+        assert.equal(result['wait'], false);
+    });
+    test('--wait present → true', async () => {
+        const deck = { interactions: [] };
+        const path = tmpJson(deck);
+        const result = await parseArgv(params, ['--context-file', path, '--wait']);
+        assert.equal(result['wait'], true);
+    });
+});
+// ---------------------------------------------------------------------------
+// human list — --limit int + --cursor string
+// ---------------------------------------------------------------------------
+describe('human list: params', () => {
+    const params = [
+        { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Default 20.' },
+        { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Pagination token.' },
+    ];
+    test('defaults: limit=20, cursor=undefined', async () => {
+        const result = await parseArgv(params, []);
+        assert.equal(result['limit'], 20);
+        assert.equal(result['cursor'], undefined);
+    });
+    test('--limit parses integer', async () => {
+        const result = await parseArgv(params, ['--limit', '5']);
+        assert.equal(result['limit'], 5);
+    });
+    test('--limit rejects non-integer', async () => {
+        await assert.rejects(() => parseArgv(params, ['--limit', 'abc']), (err) => { assert.match(err.message, /must be an integer/); return true; });
+    });
+    test('--cursor passes through as string', async () => {
+        const result = await parseArgv(params, ['--cursor', 'tok_abc123']);
+        assert.equal(result['cursor'], 'tok_abc123');
+    });
+});
+// ---------------------------------------------------------------------------
+// human _run — no params (reads CRTR_HUMAN_DIR from env)
+// ---------------------------------------------------------------------------
+describe('human _run: no params', () => {
+    const params = [];
+    test('empty argv yields empty result (no params declared)', async () => {
+        const result = await parseArgv(params, []);
+        assert.deepEqual(result, {});
+    });
+    test('positional token throws bad_invocation (no positionals declared)', async () => {
+        await assert.rejects(() => parseArgv(params, ['some-value']), (err) => { assert.match(err.message, /takes no positional/); return true; });
+    });
+    test('CRTR_HUMAN_DIR env var contract: _run reads it from env, not argv', () => {
+        // Structural check: the params array is empty, confirming no argv surface.
+        // The actual env-var read is in the run handler and verified by inspection.
+        assert.equal(params.length, 0);
+    });
+});

package/dist/commands/__tests__/skill.test.d.ts

@@ -0,0 +1 @@
+export {};