@wacht/bench 0.1.1 → 0.1.3

package/dist/commands.js

@@ -16,6 +16,7 @@ import { completionScript } from './completion.js';
 import { configApply, configDiff, configPull, configSchemaCommand, printConfigTemplate, } from './config-workflow.js';
 import { clearDeployment, createDeploymentCommand, createProjectCommand, currentDeployment, selectDeployment, } from './deployment-context.js';
 import { initProject, initStarter } from './init.js';
+import { envPull } from './env-pull.js';
 import { apiCommand, listProjects } from './machine-api.js';
 import { openApiCall, openApiDescribe, openApiList, openApiRefresh } from './openapi.js';
 import { installMcp, listMcp, printMcpConfig, uninstallMcp } from './mcp.js';
@@ -168,10 +169,22 @@ export async function runCli(args) {
     const skills = program.command('skills').description('install Wacht agent skills');
     skills
         .command('install')
-        .description('install the Wacht skills pack')
+        .description('install the Wacht skills pack into one or more AI agents')
         .option('--skill <name>', 'install one skill from the pack')
+        .option('--agent <ids>', 'comma-separated agent ids (e.g. claude-code,cursor,codex); skips the agent picker', (value) => value.split(',').map((s) => s.trim()).filter(Boolean))
+        .option('--all-agents', "install into every supported agent (passes -a '*')")
+        .option('--global', 'install at user scope instead of project scope')
+        .option('--yes', 'do not prompt for confirmation')
+        .option('--copy', 'copy skill files instead of symlinking')
         .action(async (options) => {
-        await installSkills(options.skill);
+        await installSkills({
+            skill: options.skill,
+            agents: options.agent,
+            allAgents: options.allAgents,
+            global: options.global,
+            yes: options.yes,
+            copy: options.copy,
+        });
     });
     const mcp = program.command('mcp').description('configure Wacht Docs MCP across AI clients');
     mcp
@@ -206,6 +219,15 @@ export async function runCli(args) {
         .action((options) => {
         printMcpConfig(options.client);
     });
+    const env = program.command('env').description('manage deployment credentials and environment files');
+    env
+        .command('pull')
+        .description('mint a fresh backend API key for the active deployment and write keys to .env.local')
+        .option('--file <path>', 'env file path; defaults to .env.local in the current directory')
+        .option('--print', 'print credentials to stdout instead of writing the env file')
+        .action(async (options) => {
+        await envPull(context(program), options);
+    });
     const config = program.command('config').description('manage Wacht deployment settings as code');
     config
         .command('pull')
@@ -285,14 +307,18 @@ export async function runCli(args) {
         .argument('<operation>', 'OpenAPI operation id')
         .option('--deployment <id>', 'deployment id override; defaults to active deployment')
         .option('--param <key=value>', 'path or query parameter; repeatable', collect, [])
-        .option('--body <json>', 'JSON request body')
+        .option('--body <json>', 'JSON request body; pass @path/to/file.json to read from disk')
         .option('--field <key=value>', 'URL-encoded form field; repeatable', collect, [])
         .option('--form <key=value>', 'multipart form field; value @path is treated as a file; repeatable', collect, [])
         .option('--file <key=path>', 'multipart file field; key=path or key=@path; repeatable', collect, [])
         .option('--header <key=value>', 'request header; repeatable', collect, [])
         .option('--refresh', 'refresh the cached OpenAPI schema first')
-        .action(async (operation, options) => {
-        await openApiCall(context(program), operation, options);
+        .option('--no-validate', 'skip local JSON Schema validation of the request body')
+        .action(async (operation, _options, cmd) => {
+        // The parent `api` command also declares --body / --field / --form / --file / --header
+        // so `optsWithGlobals()` is what actually surfaces them through this subcommand.
+        // Commander does not merge clashing options automatically.
+        await openApiCall(context(program), operation, cmd.optsWithGlobals());
     });
     const schema = api.command('schema').description('manage cached OpenAPI schema');
     schema

package/dist/env-pull.js

@@ -0,0 +1,105 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { machineRequest } from './machine-api.js';
+import { detectProject } from './project-detect.js';
+import { field, log, printBannerFor, printJson, section } from './ui.js';
+function isCredentialsResponse(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (typeof v.publishable_key !== 'string')
+        return false;
+    if (typeof v.frontend_host !== 'string')
+        return false;
+    if (typeof v.backend_host !== 'string')
+        return false;
+    if (typeof v.api_key !== 'object' || v.api_key === null)
+        return false;
+    const k = v.api_key;
+    return typeof k.secret === 'string';
+}
+function publishableKeyVar(frameworks) {
+    if (frameworks.has('Next.js'))
+        return 'NEXT_PUBLIC_WACHT_PUBLISHABLE_KEY';
+    if (frameworks.has('React Router') || frameworks.has('TanStack Router')) {
+        return 'VITE_WACHT_PUBLISHABLE_KEY';
+    }
+    return 'NEXT_PUBLIC_WACHT_PUBLISHABLE_KEY';
+}
+function upsertEnvLines(existing, updates) {
+    const lines = existing.length === 0 ? [] : existing.split(/\r?\n/);
+    const matched = new Set();
+    const next = lines.map((line) => {
+        const eqIdx = line.indexOf('=');
+        if (eqIdx <= 0)
+            return line;
+        const key = line.slice(0, eqIdx).trim();
+        if (!(key in updates))
+            return line;
+        matched.add(key);
+        return `${key}=${updates[key]}`;
+    });
+    const missing = Object.entries(updates).filter(([key]) => !matched.has(key));
+    if (missing.length) {
+        if (next.length && next[next.length - 1].trim() !== '')
+            next.push('');
+        for (const [key, value] of missing)
+            next.push(`${key}=${value}`);
+    }
+    let out = next.join('\n');
+    if (!out.endsWith('\n'))
+        out += '\n';
+    return out;
+}
+export async function envPull(ctx, options = {}) {
+    const data = await machineRequest('/credentials', { method: 'POST' });
+    if (!isCredentialsResponse(data)) {
+        throw new Error('Unexpected response shape from /credentials.');
+    }
+    if (options.print || ctx.json) {
+        if (ctx.json) {
+            printJson({ ok: true, data });
+        }
+        else {
+            printBannerFor(ctx);
+            log(ctx, section('Deployment Credentials'));
+            log(ctx, field('Publishable key', data.publishable_key));
+            log(ctx, field('API key', data.api_key.secret));
+            log(ctx, field('API key suffix', `${data.api_key.prefix}…${data.api_key.suffix}`));
+            log(ctx, field('Frontend host', data.frontend_host));
+            log(ctx, field('Backend host', data.backend_host));
+        }
+        return;
+    }
+    const root = process.cwd();
+    const profile = await detectProject(root);
+    const frameworks = new Set(profile.frameworks);
+    const pubVar = publishableKeyVar(frameworks);
+    // Vite-based frameworks read `.env`; Next.js reads `.env.local`.
+    const defaultFile = frameworks.has('React Router') || frameworks.has('TanStack Router')
+        ? '.env'
+        : '.env.local';
+    const filePath = options.file
+        ? path.resolve(root, options.file)
+        : path.join(root, defaultFile);
+    const existing = await readFile(filePath, 'utf8').catch((err) => {
+        if (err.code === 'ENOENT')
+            return '';
+        throw err;
+    });
+    const updated = upsertEnvLines(existing, {
+        [pubVar]: data.publishable_key,
+        WACHT_API_KEY: data.api_key.secret,
+    });
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, updated, 'utf8');
+    printBannerFor(ctx);
+    log(ctx, section('Wrote credentials'));
+    log(ctx, field('File', path.relative(root, filePath) || filePath));
+    log(ctx, field(pubVar, `${data.publishable_key.slice(0, 12)}…`));
+    log(ctx, field('WACHT_API_KEY', `${data.api_key.prefix}…${data.api_key.suffix}`));
+    log(ctx, field('Frontend host', data.frontend_host));
+    log(ctx, field('Backend host', data.backend_host));
+    log(ctx, '');
+    log(ctx, 'Note: the API key secret is only shown once. Subsequent calls mint a new key.');
+}

package/dist/init.js

@@ -43,7 +43,7 @@ This project is configured for AI-assisted Wacht development.
 - Detected project shape: \`${frameworks}\`.
 - Suggested Wacht skills for this project: \`${skills}\`.
 - Active skill router: \`wacht\` (always start there). For CLI work specifically, use the \`wacht-bench-cli\` skill.
-- Install or update skills with \`wacht skills add\`.
+- Install or update skills with \`wacht skills install\`.
 
 ### Where to look (single source of truth)
 
@@ -96,6 +96,13 @@ async function upsertAgentsBlock(root, profile) {
     return agentsPath;
 }
 async function writeEnvTemplate(root, profile) {
+    // If the project already ships a `.env.local.example` / `.env.example` (typical for
+    // scaffolded starters), don't drop a second redundant file alongside it.
+    for (const existing of ['.env.local.example', '.env.example']) {
+        if (await pathExists(path.join(root, existing))) {
+            return null;
+        }
+    }
     const envPath = path.join(root, '.env.wacht.example');
     const frameworks = new Set(profile.frameworks);
     const isVite = frameworks.has('React Router') || frameworks.has('TanStack Router');
@@ -105,7 +112,8 @@ async function writeEnvTemplate(root, profile) {
             ? 'VITE_WACHT_PUBLISHABLE_KEY'
             : 'NEXT_PUBLIC_WACHT_PUBLISHABLE_KEY';
     const lines = [
-        '# Wacht SDK environment. Fill these from your Wacht deployment.',
+        '# Wacht SDK environment. Run `wacht env pull` to populate these automatically,',
+        '# or copy values from https://console.wacht.dev.',
         '',
         '# Client-safe publishable key. Encodes deployment + frontend host.',
         `${publishableKeyVar}=`,
@@ -129,7 +137,9 @@ export async function initProject(args, ctx) {
     log(ctx, field('Suggested skills', profile.suggestedSkills.join(', ')));
     log(ctx, '');
     if (!options.skipEnv) {
-        written.push(await writeEnvTemplate(root, profile));
+        const envPath = await writeEnvTemplate(root, profile);
+        if (envPath)
+            written.push(envPath);
     }
     if (!options.skipAgents) {
         written.push(await upsertAgentsBlock(root, profile));
@@ -140,11 +150,7 @@ export async function initProject(args, ctx) {
     if (options.installSkills) {
         log(ctx, '');
         log(ctx, section('Install Skills'));
-        await installSkills();
-    }
-    else {
-        log(ctx, '');
-        log(ctx, field('Skills', `run ${command('wacht skills add')} when you want to install/update the pack`));
+        await installSkills({ yes: true });
     }
     if (ctx.json) {
         printJson({
@@ -162,6 +168,22 @@ export async function initProject(args, ctx) {
     log(ctx, '');
     log(ctx, success('Wacht Bench project bootstrap complete.'));
 }
+function printAgentBootstrapSteps(ctx, opts) {
+    log(ctx, '');
+    log(ctx, section('Next'));
+    const cd = opts.starterDir ? `cd ${opts.starterDir} && ` : '';
+    if (!opts.installedSkills) {
+        log(ctx, `  ${command('wacht skills install --agent claude-code --global --yes')}`);
+    }
+    log(ctx, `  ${command('wacht mcp install --client claude-code-user --yes')}`);
+    log(ctx, `  ${command('wacht login && wacht deployments select')}`);
+    log(ctx, `  ${command(`${cd}wacht env pull`)}`);
+    if (opts.starterDir) {
+        log(ctx, `  ${command(`${cd}pnpm install && pnpm dev`)}`);
+    }
+    log(ctx, '');
+    log(ctx, '(Restart your AI client after installing skills/MCP so they load.)');
+}
 // ─── Starter mode ───────────────────────────────────────────────────
 const STARTERS = {
     nextjs: {
@@ -232,7 +254,10 @@ export async function initStarter(options, ctx) {
     }
     log(ctx, '');
     log(ctx, success(`Starter ready at ${path.relative(process.cwd(), absoluteTarget) || '.'}`));
-    log(ctx, `Next: ${command(`cd ${path.relative(process.cwd(), absoluteTarget) || '.'} && pnpm install && pnpm dev`)}`);
+    printAgentBootstrapSteps(ctx, {
+        starterDir: path.relative(process.cwd(), absoluteTarget) || '.',
+        installedSkills: options.install,
+    });
 }
 export function listStarters() {
     return Object.entries(STARTERS).map(([framework, info]) => ({ framework, description: info.description, repo: info.repo }));

package/dist/machine-api.js

@@ -1,12 +1,40 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { MACHINE_API_URL } from './config.js';
+import { readBenchContext } from './context-store.js';
 import { getValidAuth } from './oauth.js';
 import { promptChoice, promptOptionalList, promptText } from './prompts.js';
 import { field, log, printBannerFor, printJson, section } from './ui.js';
+function isProjectScopedPath(p) {
+    if (p === '/projects' || p === '/project')
+        return true;
+    if (p.startsWith('/projects/') || p.startsWith('/project/'))
+        return true;
+    return false;
+}
+function isAlreadyDeploymentScoped(p) {
+    return p === '/deployments' || p.startsWith('/deployments/');
+}
+async function applyDeploymentPrefix(pathname) {
+    const normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+    if (isProjectScopedPath(normalized) || isAlreadyDeploymentScoped(normalized)) {
+        return normalized;
+    }
+    const context = await readBenchContext();
+    if (!context?.deployment_id) {
+        throw new Error('No active deployment selected. Run `wacht deployments select`.');
+    }
+    const splitIdx = normalized.search(/[?#]/);
+    const prefix = `/deployments/${context.deployment_id}`;
+    const pathPart = splitIdx === -1 ? normalized : normalized.slice(0, splitIdx);
+    const suffix = splitIdx === -1 ? '' : normalized.slice(splitIdx);
+    const joinedPath = pathPart === '/' ? prefix : `${prefix}${pathPart}`;
+    return `${joinedPath}${suffix}`;
+}
 export async function machineRequest(pathname, options = {}) {
     const auth = await getValidAuth();
-    const url = new URL(pathname, auth.machine_api_url || MACHINE_API_URL);
+    const resolvedPath = await applyDeploymentPrefix(pathname);
+    const url = new URL(resolvedPath, auth.machine_api_url || MACHINE_API_URL);
     const headers = new Headers(options.headers);
     headers.set('authorization', `Bearer ${auth.access_token}`);
     headers.set('accept', 'application/json');
@@ -211,9 +239,16 @@ export async function requestBody(options) {
         headers.set(key, value);
     }
     if (options.body) {
+        // `--body @path/to/file.json` reads the JSON from disk so prompt files and
+        // larger configuration blobs don't have to be inlined in the shell.
+        let source = options.body;
+        if (source.startsWith('@')) {
+            const filePath = path.resolve(source.slice(1));
+            source = await readFile(filePath, 'utf8');
+        }
         headers.set('content-type', 'application/json');
         return {
-            body: JSON.stringify(JSON.parse(options.body)),
+            body: JSON.stringify(JSON.parse(source)),
             headers,
         };
     }

package/dist/openapi-validate.js

@@ -0,0 +1,193 @@
+import { Ajv } from 'ajv';
+/**
+ * Validate a JSON request body against an operation's `requestBody` schema using
+ * the cached OpenAPI spec. Returns `null` on success; an array of human-readable
+ * error strings on failure.
+ *
+ * The validator handles OpenAPI 3.0 `nullable: true` (rewritten to JSON-Schema
+ * `type: [..., "null"]`), `$ref` resolution against `components.schemas`, and
+ * discriminated unions via `oneOf` + `discriminator`.
+ */
+export function validateBody(spec, schema, body) {
+    if (!isRecord(schema))
+        return null;
+    const componentSchemas = readComponentSchemas(spec);
+    const ajv = buildAjv(componentSchemas);
+    const compiled = compileSafely(ajv, schema);
+    if (!compiled)
+        return null;
+    if (compiled(body))
+        return null;
+    return summariseErrors(compiled.errors ?? [], body);
+}
+/**
+ * The raw ajv error stream is noisy:
+ *   - `anyOf` / `oneOf` umbrellas restate "doesn't match" without specifics.
+ *   - The `type: null` branches our `nullable` rewrite introduces are never what
+ *     the user is trying to send.
+ *   - oneOf-with-discriminator emits per-variant required errors from every
+ *     non-matching branch, drowning out the actual problem.
+ *
+ * Strategy:
+ *   1. Drop nullable + anyOf/oneOf umbrellas.
+ *   2. When an `oneOf` umbrella was present at a path, collapse all required/const
+ *      errors under that path into a single "doesn't match any variant" line with
+ *      the discriminator value found in the body (if any). Tell the user to run
+ *      `wacht api describe` for the variant payload — avoids guessing wrong.
+ *   3. Pass everything else through unchanged.
+ */
+function summariseErrors(rawErrors, body) {
+    // Discover oneOf failure points by looking for the `oneOf` umbrella error.
+    const oneOfPaths = new Set();
+    for (const e of rawErrors) {
+        if (e.keyword === 'oneOf')
+            oneOfPaths.add(e.instancePath);
+    }
+    const collapsed = [];
+    const skip = new Set();
+    for (const path of oneOfPaths) {
+        const value = readJsonPointer(body, path);
+        // The variant tag is conventionally `type`; if absent, just describe the path.
+        const tag = isRecord(value) && typeof value.type === 'string'
+            ? `, got type "${value.type}"`
+            : '';
+        collapsed.push(`${path || '(body root)'}: doesn't match any variant of the discriminated union${tag}. ` +
+            `Run \`wacht api describe <operation>\` to see each variant's required fields.`);
+        // Drop every error at the union path; the user fixes the variant first.
+        for (const e of rawErrors) {
+            if (e.instancePath === path || e.instancePath.startsWith(path + '/'))
+                skip.add(e);
+        }
+    }
+    const out = [...collapsed];
+    for (const e of rawErrors) {
+        if (skip.has(e))
+            continue;
+        if (e.keyword === 'anyOf' || e.keyword === 'oneOf')
+            continue;
+        if (e.keyword === 'type' && e.params?.type === 'null')
+            continue;
+        out.push(formatError(e));
+    }
+    // Dedupe identical lines (e.g. two variants both miss the same field).
+    return [...new Set(out)];
+}
+/**
+ * When a `oneOf` discriminated union mismatches, ajv emits a "must be equal to constant"
+ * error for every variant whose const failed, plus the required-field errors from each
+ * variant's payload schema. That's overwhelming. If the input has a discriminator value
+ * that matches *no* variant, surface a single "X must be one of [...]"; if it matches
+ * exactly one, drop the per-variant required errors from the other variants.
+ */
+function readJsonPointer(value, pointer) {
+    if (!pointer || pointer === '/')
+        return value;
+    const segments = pointer.split('/').slice(1).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+    let cur = value;
+    for (const seg of segments) {
+        if (Array.isArray(cur)) {
+            const idx = Number.parseInt(seg, 10);
+            if (Number.isNaN(idx))
+                return undefined;
+            cur = cur[idx];
+        }
+        else if (isRecord(cur)) {
+            cur = cur[seg];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+function readComponentSchemas(spec) {
+    if (!isRecord(spec))
+        return {};
+    const components = isRecord(spec.components) ? spec.components : undefined;
+    const schemas = components && isRecord(components.schemas) ? components.schemas : undefined;
+    return schemas ?? {};
+}
+function buildAjv(componentSchemas) {
+    // OpenAPI 3.1 schemas are JSON Schema draft 2020-12, but the spec we generate
+    // also leans on draft-7 `nullable: true` shorthand. Rewrite to draft-7 unions
+    // and run Ajv permissively — we're validating user payloads, not enforcing
+    // the spec itself.
+    const ajv = new Ajv({
+        strict: false,
+        allErrors: true,
+        coerceTypes: false,
+        allowUnionTypes: true,
+        validateFormats: false,
+    });
+    // Make every component schema addressable by its $ref so nested references resolve.
+    for (const [name, raw] of Object.entries(componentSchemas)) {
+        const rewritten = rewriteNullable(raw);
+        try {
+            ajv.addSchema(rewritten, `#/components/schemas/${name}`);
+        }
+        catch {
+            // Bad schemas shouldn't break the CLI — skip and keep going.
+        }
+    }
+    return ajv;
+}
+function compileSafely(ajv, schema) {
+    try {
+        return ajv.compile(rewriteNullable(schema));
+    }
+    catch {
+        return null;
+    }
+}
+/** Walk a schema and rewrite `{type: X, nullable: true}` → `{type: [X, "null"]}`. */
+function rewriteNullable(value) {
+    if (Array.isArray(value))
+        return value.map(rewriteNullable);
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    let nullable = false;
+    for (const [key, v] of Object.entries(value)) {
+        if (key === 'nullable' && v === true) {
+            nullable = true;
+            continue;
+        }
+        out[key] = rewriteNullable(v);
+    }
+    if (nullable && typeof out.type === 'string') {
+        out.type = [out.type, 'null'];
+    }
+    else if (nullable && Array.isArray(out.type)) {
+        if (!out.type.includes('null'))
+            out.type = [...out.type, 'null'];
+    }
+    else if (nullable) {
+        // No `type`; allow null alongside whatever shape the schema describes.
+        out.anyOf = [{ ...out }, { type: 'null' }];
+        for (const k of Object.keys(out))
+            if (k !== 'anyOf')
+                delete out[k];
+    }
+    return out;
+}
+function formatError(err) {
+    const path = err.instancePath || '(body root)';
+    const reason = err.message ?? 'invalid';
+    const extras = err.params ? formatParams(err.params) : '';
+    return `${path}: ${reason}${extras}`;
+}
+function formatParams(params) {
+    // Skim the most useful bits — missingProperty, allowedValues — without
+    // dumping every Ajv internal.
+    const bits = [];
+    if (typeof params.missingProperty === 'string')
+        bits.push(`missing "${params.missingProperty}"`);
+    if (Array.isArray(params.allowedValues))
+        bits.push(`allowed: ${params.allowedValues.map((v) => JSON.stringify(v)).join(', ')}`);
+    if (typeof params.additionalProperty === 'string')
+        bits.push(`unknown property "${params.additionalProperty}"`);
+    return bits.length ? ` (${bits.join('; ')})` : '';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/openapi.js

@@ -1,7 +1,9 @@
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { AUTH_DIR, OPENAPI_CACHE_FILE, PLATFORM_OPENAPI_URL } from './config.js';
 import { readBenchContext } from './context-store.js';
 import { entries, requestBody, machineRequest } from './machine-api.js';
+import { validateBody } from './openapi-validate.js';
 import { field, log, printBannerFor, printJson, section, warning } from './ui.js';
 const OPENAPI_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
@@ -74,6 +76,7 @@ function operations(spec) {
                 tags: typed.tags ?? [],
                 parameters: typed.parameters ?? [],
                 requestBody: typed.requestBody,
+                responses: typed.responses,
             });
         }
     }
@@ -95,14 +98,170 @@ function findOperation(spec, target, maybePath) {
 function schemaType(schema) {
     if (!schema)
         return 'unknown';
-    if (typeof schema.type === 'string')
+    if (typeof schema.type === 'string') {
+        if (schema.type === 'array' && isRecord(schema.items)) {
+            return `array<${schemaType(schema.items)}>`;
+        }
+        if (Array.isArray(schema.enum) && schema.enum.length) {
+            return `${schema.type}<${schema.enum.map((v) => JSON.stringify(v)).join(' | ')}>`;
+        }
+        if (typeof schema.const === 'string')
+            return `const "${schema.const}"`;
+        // Surface common formats like `binary` (file uploads) so multipart fields
+        // are recognisable at a glance vs plain strings.
+        if (typeof schema.format === 'string')
+            return `${schema.type} (${schema.format})`;
         return schema.type;
+    }
     if (typeof schema.$ref === 'string')
         return schema.$ref.split('/').pop() ?? schema.$ref;
     if (Array.isArray(schema.anyOf))
         return schema.anyOf.map((item) => isRecord(item) ? schemaType(item) : 'unknown').join(' | ');
+    if (Array.isArray(schema.oneOf))
+        return schema.oneOf.map((item) => isRecord(item) ? schemaType(item) : 'unknown').join(' | ');
     return 'object';
 }
+const REF_PREFIX = '#/components/schemas/';
+function resolveSchemaRef(spec, schema, seen = new Set()) {
+    if (!schema)
+        return undefined;
+    if (typeof schema.$ref !== 'string')
+        return schema;
+    const name = schema.$ref.startsWith(REF_PREFIX) ? schema.$ref.slice(REF_PREFIX.length) : '';
+    if (!name || seen.has(name))
+        return schema;
+    const schemas = isRecord(spec.components) && isRecord(spec.components.schemas) ? spec.components.schemas : undefined;
+    const target = schemas?.[name];
+    if (!isRecord(target))
+        return schema;
+    seen.add(name);
+    return resolveSchemaRef(spec, target, seen);
+}
+/**
+ * Merge an `allOf` chain into a single object schema. Used for our generator's
+ * internally-tagged enum encoding: `allOf: [{$ref: Payload}, {properties: {<tag>: const}}]`.
+ */
+function flattenAllOf(spec, schema) {
+    if (!Array.isArray(schema.allOf))
+        return schema;
+    const props = {};
+    const required = new Set();
+    for (const part of schema.allOf) {
+        if (!isRecord(part))
+            continue;
+        const resolved = resolveSchemaRef(spec, part) ?? part;
+        if (isRecord(resolved.properties)) {
+            for (const [key, value] of Object.entries(resolved.properties))
+                props[key] = value;
+        }
+        if (Array.isArray(resolved.required)) {
+            for (const key of resolved.required) {
+                if (typeof key === 'string')
+                    required.add(key);
+            }
+        }
+    }
+    return { type: 'object', properties: props, required: Array.from(required) };
+}
+/** How many levels of nested object schemas to inline before falling back to the type name. */
+const MAX_BODY_DEPTH = 3;
+/** Pull the schema-component name out of a `$ref`, if any. */
+function refName(schema) {
+    if (!schema || typeof schema.$ref !== 'string')
+        return undefined;
+    return schema.$ref.startsWith(REF_PREFIX) ? schema.$ref.slice(REF_PREFIX.length) : undefined;
+}
+/** True when a resolved schema carries structure worth expanding inline. */
+function isStructural(schema) {
+    if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf) || Array.isArray(schema.allOf))
+        return true;
+    if (isRecord(schema.properties) && Object.keys(schema.properties).length > 0)
+        return true;
+    return false;
+}
+function printSchema(pctx, raw, indent, depth) {
+    // Stop recursing if we're already too deep — caller has shown the type name.
+    if (depth > MAX_BODY_DEPTH)
+        return;
+    const name = refName(raw);
+    if (name && pctx.seen.has(name)) {
+        log(pctx.ctx, `${indent}(circular reference to ${name})`);
+        return;
+    }
+    const resolved = resolveSchemaRef(pctx.spec, raw) ?? raw;
+    const flat = Array.isArray(resolved.allOf) ? flattenAllOf(pctx.spec, resolved) : resolved;
+    if (Array.isArray(flat.oneOf)) {
+        if (depth >= MAX_BODY_DEPTH) {
+            log(pctx.ctx, `${indent}(oneOf — drill further with \`wacht api describe ${name ?? '<schema>'}\`)`);
+            return;
+        }
+        if (depth === 0)
+            log(pctx.ctx, `${indent}(oneOf — pick exactly one variant)`);
+        if (name)
+            pctx.seen.add(name);
+        for (const variant of flat.oneOf) {
+            if (!isRecord(variant))
+                continue;
+            const variantInner = resolveSchemaRef(pctx.spec, variant) ?? variant;
+            const variantFlat = Array.isArray(variantInner.allOf) ? flattenAllOf(pctx.spec, variantInner) : variantInner;
+            const variantProps = isRecord(variantFlat.properties) ? variantFlat.properties : {};
+            const tagEntry = Object.entries(variantProps).find(([, val]) => isRecord(val) && typeof val.const === 'string');
+            const label = tagEntry
+                ? `variant "${tagEntry[1].const}"`
+                : 'variant';
+            log(pctx.ctx, `${indent}  ${label}:`);
+            printObjectFields(pctx, variantFlat, `${indent}    `, depth + 1);
+        }
+        if (name)
+            pctx.seen.delete(name);
+        return;
+    }
+    printObjectFields(pctx, flat, indent, depth);
+}
+function printObjectFields(pctx, schema, indent, depth) {
+    const expanded = Array.isArray(schema.allOf) ? flattenAllOf(pctx.spec, schema) : schema;
+    const props = isRecord(expanded.properties) ? expanded.properties : {};
+    const required = new Set(Array.isArray(expanded.required)
+        ? expanded.required.filter((k) => typeof k === 'string')
+        : []);
+    if (Object.keys(props).length === 0) {
+        log(pctx.ctx, `${indent}(no fields)`);
+        return;
+    }
+    for (const [key, raw] of Object.entries(props)) {
+        if (!isRecord(raw))
+            continue;
+        const tag = required.has(key) ? 'required' : 'optional';
+        const inlineType = schemaType(raw);
+        log(pctx.ctx, `${indent}${key} (${tag}, ${inlineType})`);
+        // Drill into nested structures one indent deeper, guarded by depth + cycle.
+        if (depth >= MAX_BODY_DEPTH)
+            continue;
+        const target = refName(raw) ?? refName(isRecord(raw.items) ? raw.items : undefined);
+        const nested = resolveSchemaRef(pctx.spec, raw) ?? raw;
+        // Array element refs: descend into the items' resolved schema.
+        const arrayItem = nested.type === 'array' && isRecord(nested.items)
+            ? (resolveSchemaRef(pctx.spec, nested.items) ?? nested.items)
+            : undefined;
+        const next = arrayItem ?? nested;
+        if (!isStructural(next))
+            continue;
+        if (target && pctx.seen.has(target)) {
+            log(pctx.ctx, `${indent}  (circular reference to ${target})`);
+            continue;
+        }
+        if (target)
+            pctx.seen.add(target);
+        printSchema(pctx, next, `${indent}  `, depth + 1);
+        if (target)
+            pctx.seen.delete(target);
+    }
+}
+function printBodySchema(ctx, spec, schema) {
+    if (!schema)
+        return;
+    printSchema({ ctx, spec, seen: new Set() }, schema, '', 0);
+}
 function requestContent(operation) {
     return Object.keys(operation.requestBody?.content ?? {});
 }
@@ -177,8 +336,40 @@ export async function openApiDescribe(ctx, target, maybePath, options) {
     if (contentTypes.length) {
         log(ctx, '');
         log(ctx, section('Request Body'));
-        for (const contentType of contentTypes)
-            log(ctx, contentType);
+        const required = operation.requestBody?.required ? ' (required)' : ' (optional)';
+        for (const contentType of contentTypes) {
+            log(ctx, `${contentType}${required}`);
+            const bodySchema = operation.requestBody?.content?.[contentType]?.schema;
+            if (!isRecord(bodySchema))
+                continue;
+            // JSON, multipart, and url-encoded bodies all surface as object schemas
+            // with `properties` once form annotations are in place; render uniformly.
+            const isStructured = contentType === 'application/json'
+                || contentType === 'multipart/form-data'
+                || contentType === 'application/x-www-form-urlencoded';
+            if (isStructured) {
+                printBodySchema(ctx, loaded.spec, bodySchema);
+            }
+        }
+    }
+    if (operation.responses && Object.keys(operation.responses).length) {
+        log(ctx, '');
+        log(ctx, section('Responses'));
+        const statuses = Object.keys(operation.responses).sort();
+        for (const status of statuses) {
+            const response = operation.responses[status];
+            const description = response?.description ? ` — ${response.description}` : '';
+            log(ctx, `${status}${description}`);
+            // Only drill the 2xx success body; error responses share a common
+            // `{errors: [{message, code}]}` envelope and just clutter the output.
+            const isSuccess = status.startsWith('2');
+            if (!isSuccess)
+                continue;
+            const successJson = response?.content?.['application/json']?.schema;
+            if (isRecord(successJson)) {
+                printBodySchema(ctx, loaded.spec, successJson);
+            }
+        }
     }
 }
 function applyPathParams(path, params) {
@@ -218,13 +409,46 @@ export async function openApiCall(ctx, target, options) {
         file: options.file,
         header: options.header,
     };
+    // Validate the JSON body against the operation's request schema first —
+    // local check, useful regardless of deployment state. Skips multipart
+    // (JSON Schema can't validate FormData) and anything not parseable as JSON.
+    if (apiOptions.body && options.validate !== false) {
+        const sourceBody = apiOptions.body.startsWith('@')
+            ? await readFile(path.resolve(apiOptions.body.slice(1)), 'utf8')
+            : apiOptions.body;
+        let parsed;
+        try {
+            parsed = JSON.parse(sourceBody);
+        }
+        catch {
+            parsed = undefined;
+        }
+        const bodySchema = operation.requestBody?.content?.['application/json']?.schema;
+        if (parsed !== undefined && bodySchema) {
+            const errors = validateBody(loaded.spec, bodySchema, parsed);
+            if (errors && errors.length) {
+                log(ctx, warning(`Request body did not match schema for ${operation.operationId}:`));
+                for (const e of errors)
+                    log(ctx, `  - ${e}`);
+                log(ctx, '');
+                log(ctx, `Pass --no-validate to skip local validation, or \`wacht api describe ${operation.operationId}\` to see the schema.`);
+                throw new Error('Validation failed.');
+            }
+        }
+    }
     const pathWithParams = appendQueryParams(applyPathParams(operation.path, params), params, operation);
-    const machinePath = pathWithParams.startsWith('/project') || pathWithParams === '/projects'
-        ? pathWithParams
-        : `/deployments/${deploymentId ?? ''}${pathWithParams}`;
-    if (machinePath.includes('/deployments//')) {
+    const isProjectScoped = pathWithParams.startsWith('/project') || pathWithParams === '/projects';
+    let machinePath;
+    if (isProjectScoped) {
+        machinePath = pathWithParams;
+    }
+    else if (!deploymentId) {
         throw new Error('Select an active deployment first, or pass raw paths with `wacht api METHOD /path`.');
     }
+    else {
+        const base = `/deployments/${deploymentId}`;
+        machinePath = pathWithParams === '/' ? base : `${base}${pathWithParams}`;
+    }
     const { body, headers } = await requestBody(apiOptions);
     const data = await machineRequest(machinePath, {
         method: operation.method,

package/dist/skills.js

@@ -1,10 +1,22 @@
 import { spawn } from 'node:child_process';
 import { SKILLS_SOURCE } from './config.js';
 import { valueAfter } from './util.js';
-export function installSkills(skill) {
+export function installSkills(options = {}) {
     const installArgs = ['skills', 'add', SKILLS_SOURCE];
-    if (skill)
-        installArgs.push('--skill', skill);
+    if (options.allAgents) {
+        installArgs.push('-a', '*');
+    }
+    else if (options.agents && options.agents.length > 0) {
+        installArgs.push('-a', ...options.agents);
+    }
+    if (options.skill)
+        installArgs.push('-s', options.skill);
+    if (options.global)
+        installArgs.push('-g');
+    if (options.yes)
+        installArgs.push('-y');
+    if (options.copy)
+        installArgs.push('--copy');
     return new Promise((resolve, reject) => {
         const child = spawn('npx', installArgs, {
             stdio: 'inherit',
@@ -25,5 +37,5 @@ export function installSkills(skill) {
     });
 }
 export async function skillsInstall(args) {
-    await installSkills(valueAfter(args, '--skill'));
+    await installSkills({ skill: valueAfter(args, '--skill') });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wacht/bench",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for Wacht Bench, the AI development workbench for Wacht.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "ajv": "^8.20.0",
     "commander": "^12.1.0"
   },
   "devDependencies": {