@hypercli.com/cli 0.0.0-stage → 0.9.2

package/dist/core/skills-runtime.js

@@ -0,0 +1,101 @@
+/**
+ * Bundled-skills runtime.
+ *
+ * scripts/build-skills.mjs compiles the allowlisted skills into
+ * <pkg>/skills/: one <name>.json per skill (full record, markdown
+ * included) and an index.json with { skills: [{ name, description,
+ * commands }] } in display order.
+ *
+ * index.json is the single source of truth for listSkills() and name
+ * resolution — the skills directory is never scanned, so the build-time
+ * allowlist fully controls what `hyper skills` can see. getSkill()
+ * resolves an exact name or an unambiguous case-insensitive prefix against
+ * the index, then loads <name>.json for the full markdown record; failures
+ * list candidate skill names on the error.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CliError } from './errors.js';
+/** Resolve the generated catalog relative to the installed CLI artifact. */
+export function skillsDir() {
+    const relativePath = typeof HYPERCLI_SKILLS_RELATIVE_PATH === 'undefined'
+        ? '../../skills/'
+        : HYPERCLI_SKILLS_RELATIVE_PATH;
+    return fileURLToPath(new URL(relativePath, import.meta.url));
+}
+function isIndexEntry(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.name === 'string' &&
+        typeof v.description === 'string' &&
+        Array.isArray(v.commands));
+}
+function isBundledSkill(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.name === 'string' &&
+        typeof v.description === 'string' &&
+        typeof v.markdown === 'string' &&
+        Array.isArray(v.commands));
+}
+/**
+ * Index entries in display order. Empty when the dir or index is missing
+ * or corrupt.
+ */
+export function listSkills(dir = skillsDir()) {
+    const indexPath = join(dir, 'index.json');
+    if (!existsSync(indexPath))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(indexPath, 'utf8'));
+        const skills = parsed?.skills;
+        if (!Array.isArray(skills))
+            return [];
+        return skills.filter(isIndexEntry);
+    }
+    catch {
+        // Treat an unreadable/corrupt index as "no skills built".
+        return [];
+    }
+}
+/**
+ * Resolve a name or unambiguous prefix against candidate names.
+ * Returns the matched name, or throws CliError listing candidates.
+ */
+export function resolveSkillName(nameOrPrefix, names) {
+    const query = nameOrPrefix.toLowerCase();
+    if (!query) {
+        throw new CliError(`skill name required. Available skills: ${names.join(', ') || '(none built)'}`);
+    }
+    const exact = names.find((n) => n.toLowerCase() === query);
+    if (exact)
+        return exact;
+    const matches = names.filter((n) => n.toLowerCase().startsWith(query));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new CliError(`ambiguous skill prefix '${nameOrPrefix}' — matches: ${matches.join(', ')}`);
+    }
+    throw new CliError(`unknown skill '${nameOrPrefix}'. Available skills: ${names.join(', ') || '(none built)'}`);
+}
+/** Load one skill by exact name or unambiguous prefix. */
+export function getSkill(nameOrPrefix, dir = skillsDir()) {
+    const entries = listSkills(dir);
+    const name = resolveSkillName(nameOrPrefix, entries.map((e) => e.name));
+    const skillPath = join(dir, `${name}.json`);
+    if (existsSync(skillPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(skillPath, 'utf8'));
+            if (isBundledSkill(parsed))
+                return parsed;
+        }
+        catch {
+            // Fall through to the error below.
+        }
+    }
+    throw new CliError(`skill '${name}' is listed in the skills index but its data file is missing or corrupt — rebuild with scripts/build-skills.mjs`);
+}
+//# sourceMappingURL=skills-runtime.js.map

package/dist/core/skills-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-runtime.js","sourceRoot":"","sources":["../../src/core/skills-runtime.ts"],"names":[],"mappings":"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"}

package/dist/core/table.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tiny aligned-column table printer. No dependencies.
+ *
+ * formatTable(['NAME', 'STATUS'], [['alpha', 'running'], ['beta', null]])
+ * =>
+ *   NAME   STATUS
+ *   alpha  running
+ *   beta
+ *
+ * Columns are padded with spaces to the widest cell, separated by two spaces.
+ * No ANSI escapes are emitted, so widths are plain string lengths.
+ */
+export type TableCell = string | number | boolean | null | undefined;
+/** Render a cell to display text: null/undefined -> '', objects -> JSON. */
+export declare function cellText(cell: unknown): string;
+/** Format rows into aligned columns. Returns a single string, lines joined by '\n'. */
+export declare function formatTable(columns: readonly string[], rows: readonly (readonly unknown[])[]): string;

package/dist/core/table.js

@@ -0,0 +1,34 @@
+/**
+ * Tiny aligned-column table printer. No dependencies.
+ *
+ * formatTable(['NAME', 'STATUS'], [['alpha', 'running'], ['beta', null]])
+ * =>
+ *   NAME   STATUS
+ *   alpha  running
+ *   beta
+ *
+ * Columns are padded with spaces to the widest cell, separated by two spaces.
+ * No ANSI escapes are emitted, so widths are plain string lengths.
+ */
+/** Render a cell to display text: null/undefined -> '', objects -> JSON. */
+export function cellText(cell) {
+    if (cell === null || cell === undefined)
+        return '';
+    if (typeof cell === 'string')
+        return cell;
+    if (typeof cell === 'number' || typeof cell === 'boolean')
+        return String(cell);
+    return JSON.stringify(cell);
+}
+/** Format rows into aligned columns. Returns a single string, lines joined by '\n'. */
+export function formatTable(columns, rows) {
+    const header = columns.map((c) => cellText(c));
+    const body = rows.map((row) => row.map((cell) => cellText(cell)));
+    const widths = header.map((h, i) => Math.max(h.length, ...body.map((row) => (row[i] ?? '').length)));
+    const renderRow = (cells) => cells.map((cell, i) => (i < cells.length - 1 ? cell.padEnd(widths[i]) : cell)).join('  ').replace(/\s+$/, '');
+    const lines = [renderRow(header)];
+    for (const row of body)
+        lines.push(renderRow(row));
+    return lines.join('\n');
+}
+//# sourceMappingURL=table.js.map

package/dist/core/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../../src/core/table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/E,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,OAA0B,EAAE,IAAqC;IAC3F,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAElE,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACjC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAChE,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,KAAe,EAAU,EAAE,CAC5C,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEhH,MAAM,KAAK,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The command contract every group implements against.
+ *
+ * ============================================================================
+ * ctx contract (verbatim — all feature agents implement against this)
+ * ============================================================================
+ *
+ *   ctx = {
+ *     client(): Promise<HyperCLI>,   // lazily-built SDK client (see below)
+ *     output: Output,                // see core/output.ts
+ *     format: 'table' | 'json',      // resolved from --json / --output
+ *   }
+ *
+ * In addition to ctx, run() receives:
+ *
+ *   args: string[],                  // raw argv remaining after the group name
+ *
+ * Rules for command implementers:
+ *
+ * - Parse `args` (the run() parameter, NOT ctx — ctx carries no argv) with
+ *   `parseCommandArgs(args, options)` from core/argv.ts. Universal flags
+ *   (--json, --help/-h, --output/-o) are always accepted; declare only
+ *   your command-specific options. Unknown flags and bad values throw
+ *   UsageError -> exit code 2.
+ * - If the parsed `--help` flag is set, print your group's help and return.
+ * - Call `ctx.client()` only when you actually need the API; it throws a
+ *   CliError (exit 1) when no credential is configured.
+ * - Emit results exclusively via `ctx.output.result(data, table?)`:
+ *   --json prints exactly one JSON.stringify of `data` on stdout;
+ *   table mode prints your aligned table. Progress goes to `ctx.output.info()`
+ *   (stderr). Never call console.log / process.stdout directly.
+ * - Throw `UsageError` for bad user input, `CliError` for expected failures.
+ *   Anything else bubbles to the entrypoint: `error: <message>` on stderr,
+ *   exit code 1.
+ * - `run()` returns void (exit 0) or an explicit exit code number.
+ *
+ * ============================================================================
+ */
+import type { HyperCLI } from '@hypercli.com/sdk';
+import type { Output, OutputFormat } from './output.js';
+export interface CommandContext {
+    /** Lazily-built SDK client. Construction is deferred until first call. */
+    client(): Promise<HyperCLI>;
+    /** Result/progress emitter honoring --json. See core/output.ts. */
+    readonly output: Output;
+    /** Resolved output format: 'table' (default) or 'json' (--json / -o json). */
+    readonly format: OutputFormat;
+}
+/**
+ * A registered command group (also used for root commands — a root command
+ * is just a group with no subcommands).
+ */
+export interface CommandGroup {
+    /** Group name as typed on the command line, e.g. 'agents'. */
+    readonly name: string;
+    /** One-line description shown in root help. */
+    readonly summary: string;
+    /** Syntax lines shown in `hyper <name> --help`, e.g. 'hyper agents ls'. */
+    readonly usage: readonly string[];
+    /**
+     * Execute the group. args = raw argv after the group name (the entrypoint
+     * splices the group token out). Parse it with parseCommandArgs.
+     */
+    run(ctx: CommandContext, args: string[]): Promise<number | void>;
+}

package/dist/core/types.js

@@ -0,0 +1,40 @@
+/**
+ * The command contract every group implements against.
+ *
+ * ============================================================================
+ * ctx contract (verbatim — all feature agents implement against this)
+ * ============================================================================
+ *
+ *   ctx = {
+ *     client(): Promise<HyperCLI>,   // lazily-built SDK client (see below)
+ *     output: Output,                // see core/output.ts
+ *     format: 'table' | 'json',      // resolved from --json / --output
+ *   }
+ *
+ * In addition to ctx, run() receives:
+ *
+ *   args: string[],                  // raw argv remaining after the group name
+ *
+ * Rules for command implementers:
+ *
+ * - Parse `args` (the run() parameter, NOT ctx — ctx carries no argv) with
+ *   `parseCommandArgs(args, options)` from core/argv.ts. Universal flags
+ *   (--json, --help/-h, --output/-o) are always accepted; declare only
+ *   your command-specific options. Unknown flags and bad values throw
+ *   UsageError -> exit code 2.
+ * - If the parsed `--help` flag is set, print your group's help and return.
+ * - Call `ctx.client()` only when you actually need the API; it throws a
+ *   CliError (exit 1) when no credential is configured.
+ * - Emit results exclusively via `ctx.output.result(data, table?)`:
+ *   --json prints exactly one JSON.stringify of `data` on stdout;
+ *   table mode prints your aligned table. Progress goes to `ctx.output.info()`
+ *   (stderr). Never call console.log / process.stdout directly.
+ * - Throw `UsageError` for bad user input, `CliError` for expected failures.
+ *   Anything else bubbles to the entrypoint: `error: <message>` on stderr,
+ *   exit code 1.
+ * - `run()` returns void (exit 0) or an explicit exit code number.
+ *
+ * ============================================================================
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * hyper — HyperCLI command line. Entrypoint and dispatcher.
+ *
+ *   hyper <group> <command> [flags]   e.g. hyper agents ls
+ *   hyper <command> [flags]           e.g. hyper me, hyper skills
+ *
+ * Dispatch: the first positional token names a registered group; everything
+ * after it is handed to that group's run(ctx, args) verbatim.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * hyper — HyperCLI command line. Entrypoint and dispatcher.
+ *
+ *   hyper <group> <command> [flags]   e.g. hyper agents ls
+ *   hyper <command> [flags]           e.g. hyper me, hyper skills
+ *
+ * Dispatch: the first positional token names a registered group; everything
+ * after it is handed to that group's run(ctx, args) verbatim.
+ */
+import { APP_VERSION } from './version.js';
+import { lazyClient } from './core/client.js';
+import { parseUniversal } from './core/argv.js';
+import { applyCliConfigFile } from './core/config-file.js';
+import { exitCodeFor, printError } from './core/errors.js';
+import { closestMatch, renderRootHelp } from './core/help.js';
+import { createOutput } from './core/output.js';
+import { findGroup, GROUPS, REGISTRY } from './registry.js';
+function buildContext(format) {
+    return {
+        client: lazyClient(),
+        output: createOutput(format),
+        format,
+    };
+}
+async function main() {
+    process.on('SIGINT', () => {
+        // Active commands own bounded cancellation before returning exit 130.
+        if (process.listenerCount('SIGINT') > 1)
+            return;
+        process.stderr.write('\n');
+        process.exit(130);
+    });
+    const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
+    if (nodeMajor < 22) {
+        process.stderr.write(`error: hyper requires Node.js >= 22 (found ${process.versions.node})\n`);
+        return 2;
+    }
+    applyCliConfigFile();
+    const argv = process.argv.slice(2);
+    const top = parseUniversal(argv);
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        process.stdout.write(`hyper ${APP_VERSION}\n`);
+        return 0;
+    }
+    const [groupName] = top.positionals;
+    if (!groupName || (top.help && groupName === undefined)) {
+        process.stdout.write(`${renderRootHelp(GROUPS)}\n`);
+        return 0;
+    }
+    const group = findGroup(groupName);
+    if (!group) {
+        const hint = closestMatch(groupName, [...REGISTRY.keys()]);
+        process.stderr.write(`error: unknown command '${groupName}'${hint ? ` — did you mean '${hint}'?` : ''}\n`);
+        process.stderr.write("Run 'hyper --help' for available commands.\n");
+        return 2;
+    }
+    // Everything typed after the group name belongs to the group. Splice at the
+    // first positional token index, not indexOf(groupName) — a global flag value
+    // could duplicate the word.
+    const groupArgs = [...argv];
+    groupArgs.splice(top.firstPositionalIndex, 1);
+    const ctx = buildContext(top.format);
+    const code = await group.run(ctx, groupArgs);
+    return typeof code === 'number' ? code : 0;
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    printError(err);
+    process.exitCode = exitCodeFor(err);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Command registry. To add a group: one import + one entry in GROUPS.
+ *
+ * Each module under src/commands/ exports { name, summary, usage, run } —
+ * run(ctx, args) is the entry point (see core/types.ts for the ctx contract).
+ */
+import type { CommandGroup } from './core/types.js';
+export declare const GROUPS: readonly CommandGroup[];
+export declare const REGISTRY: ReadonlyMap<string, CommandGroup>;
+export declare function findGroup(name: string): CommandGroup | undefined;

package/dist/registry.js

@@ -0,0 +1,39 @@
+/**
+ * Command registry. To add a group: one import + one entry in GROUPS.
+ *
+ * Each module under src/commands/ exports { name, summary, usage, run } —
+ * run(ctx, args) is the entry point (see core/types.ts for the ctx contract).
+ */
+import * as agents from './commands/agents.js';
+import * as acp from './commands/acp.js';
+import * as configure from './commands/configure.js';
+import * as files from './commands/files.js';
+import * as flow from './commands/flow.js';
+import * as integrations from './commands/integrations.js';
+import * as jobs from './commands/jobs.js';
+import * as me from './commands/me.js';
+import * as memory from './commands/memory.js';
+import * as routines from './commands/routines.js';
+import * as skills from './commands/skills.js';
+import * as voice from './commands/voice.js';
+import * as websearch from './commands/websearch.js';
+export const GROUPS = [
+    acp,
+    me,
+    memory,
+    configure,
+    skills,
+    agents,
+    routines,
+    jobs,
+    flow,
+    files,
+    integrations,
+    voice,
+    websearch,
+];
+export const REGISTRY = new Map(GROUPS.map((g) => [g.name, g]));
+export function findGroup(name) {
+    return REGISTRY.get(name);
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,sBAAsB,CAAC;AAC/C,OAAO,KAAK,GAAG,MAAM,mBAAmB,CAAC;AACzC,OAAO,KAAK,SAAS,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAC;AAC7C,OAAO,KAAK,IAAI,MAAM,oBAAoB,CAAC;AAC3C,OAAO,KAAK,YAAY,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,IAAI,MAAM,oBAAoB,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,MAAM,MAAM,sBAAsB,CAAC;AAC/C,OAAO,KAAK,QAAQ,MAAM,wBAAwB,CAAC;AACnD,OAAO,KAAK,MAAM,MAAM,sBAAsB,CAAC;AAC/C,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAC;AAC7C,OAAO,KAAK,SAAS,MAAM,yBAAyB,CAAC;AAGrD,MAAM,CAAC,MAAM,MAAM,GAA4B;IAC7C,GAAG;IACH,EAAE;IACF,MAAM;IACN,SAAS;IACT,MAAM;IACN,MAAM;IACN,QAAQ;IACR,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,YAAY;IACZ,KAAK;IACL,SAAS;CACV,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAsC,IAAI,GAAG,CAChE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAC/B,CAAC;AAEF,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const APP_VERSION = "0.9.2";

package/dist/version.js

@@ -0,0 +1,3 @@
+// Generated by tools/sync_versions.py from versions.json.
+export const APP_VERSION = '0.9.2';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@hypercli.com/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.2",
+  "description": "HyperCLI command line \u2014 product APIs, managed agents, compute, flows, knowledge, voice.",
+  "type": "module",
+  "bin": {
+    "hyper": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "npm run build:skills && tsc -p tsconfig.json",
+    "build:skills": "node scripts/build-skills.mjs",
+    "test": "exec python3 ../tools/run_unit_tests.py -- vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsx src/index.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@hypercli.com/sdk": "0.9.2",
+    "@modelcontextprotocol/sdk": "^1.31.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0",
+    "ws": "^8.16.0"
+  }
+}

package/skills/hypercli-account.json

@@ -0,0 +1,17 @@
+{
+  "name": "hypercli-account",
+  "description": "Inspect the active HyperCLI identity, capabilities, and entitlements with hyper me, and set up the local product API key with hyper configure. Use for who-am-I, capability, entitlement, and credential-setup questions.",
+  "markdown": "---\nname: hypercli-account\ndescription: >\n  Inspect the active HyperCLI identity, capabilities, and entitlements with\n  hyper me, and set up the local product API key with hyper configure. Use\n  for who-am-I, capability, entitlement, and credential-setup questions.\n---\n\n# HyperCLI Account\n\nLoad the `hypercli` and `hypercli-auth` skills before account work. This\nskill covers the two account-facing commands; `hypercli-auth` owns\ncredential precedence, environment selection, and failure diagnosis.\nReference: `/opt/hypercli/docs/cli/configuration.mdx`.\n\n## Complete command map\n\n| Area | Command |\n| --- | --- |\n| Identity, capabilities, entitlements | `hyper me` |\n| Account profile | `hyper user --json` |\n| Write the local product API key | `hyper configure` |\n| Agent onboarding and subscription | `hyper agent onboard`, `hyper agent subscribe` |\n| Balance, invoices, transactions | `hyper billing balance` |\n| API keys | `hyper keys list`, `hyper keys create` |\n| Wallet | `hyper wallet balance`, `hyper wallet topup` |\n\n## Identity and entitlements\n\n```bash\nhyper me\nhyper me --json\n```\n\n`hyper me` resolves the active credential and reports the account identity,\nthe capabilities that key holds, and entitlement state. Read the capability\nlist before assuming a key may run jobs, flows, agents, or voice: a working\nidentity does not prove every scope is present. Set `HYPER_API_BASE` to the dev API only when the\nuser intends the dev environment, and `--json` only in private automation —\nthe payload contains account and key identifiers.\n\n## Local credential configuration\n\n```bash\nhyper configure\n```\n\n`hyper configure` writes the product API key to `$HYPER_HOME/config`, or\n`~/.hypercli/config` when `HYPER_HOME` is unset, so it persists across\nsessions. Environment `HYPER_API_KEY` still overrides the saved value,\nand `HYPER_AGENTS_API_KEY` remains the shared client's final fallback; see\n`hypercli-auth` for the exact chain. After configuring, verify once with\n`hyper me` and report the resulting identity, never the key.\n\n## Failure and completion rules\n\n- A `401` means the resolved credential is rejected; follow `hypercli-auth`\n  and do not retry with guessed alternates.\n- A `403` means a valid identity lacks the capability; re-check the\n  capabilities reported by `hyper me` instead of swapping keys.\n- Never print the API key, saved config contents, or another account's\n  identifiers in a response.\n- Report the resolved environment (prod/dev), the identity, the\n  capabilities relevant to the task, and the entitlement state — never the\n  credential.",
+  "commands": [
+    "hyper me",
+    "hyper user --json",
+    "hyper configure",
+    "hyper agent onboard",
+    "hyper agent subscribe",
+    "hyper billing balance",
+    "hyper keys list",
+    "hyper keys create",
+    "hyper wallet balance",
+    "hyper wallet topup"
+  ]
+}

package/skills/hypercli-agents.json

@@ -0,0 +1,23 @@
+{
+  "name": "hypercli-agents",
+  "description": "Create, run, inspect, and control managed HyperCLI agents across the openclaw, hermes, goose, opencode, and buzz runtimes. Use for hyper agents lifecycle and wait, logs, exec, shell, file copies, routines, grant activation with hyper agents activate, dynamic routes, archive and restore, and OpenClaw-only configuration through the hidden hyper agents config and hyper agents models commands.",
+  "markdown": "---\nname: hypercli-agents\ndescription: >\n  Create, run, inspect, and control managed HyperCLI agents across the\n  openclaw, hermes, goose, opencode, and buzz runtimes. Use for hyper\n  agents lifecycle and wait, logs, exec, shell, file copies, routines,\n  grant activation with hyper agents activate, dynamic routes, archive and\n  restore, and OpenClaw-only configuration through the hidden hyper agents\n  config and hyper agents models commands.\n---\n\n# HyperCLI Agents\n\nLoad the `hypercli` and `hypercli-auth` skills before remote work. The\nmanaged image command reference is\n`/opt/hypercli/docs/cli/commands/agents.mdx`. Run `hyper agents --help` and\n`hyper agents <command> --help` against the installed CLI when exact\noptions matter; hidden power commands appear only in the reference docs.\n\n## Complete command map\n\n| Area | Commands |\n| --- | --- |\n| Discovery | `ls`, `status` |\n| Lifecycle | `create`, `wait`, `start`, `stop`, `delete` |\n| Container access | `logs`, `exec`, `shell`, `cp` |\n| Routines | `routines list`, `routines create`, `routines delete` |\n| Grants | `activate` |\n| Hidden power | `token`, `routes`, `config get/set` (OpenClaw only), `models` (OpenClaw only), `archive`, `restore`, `routines update` |\n\nSelect product/inference with `HYPER_API_BASE` and direct Agent control\nindependently with `HYPER_AGENTS_API_BASE` in environment/config. Without an\nAgents base, Agent endpoints derive from the product base. Change either only\nwhen the user explicitly intends it. Public `hyper` has no `--dev`/`--prod` flags.\n\n## Inspect before changing\n\nResolve a user-supplied name with bounded reads:\n\n```bash\nhyper agents ls\nhyper agents status <agent>\nhyper agents logs <agent>\n```\n\nTable output is the safe default. `ls --json` can include launch\nenvironment values; keep it private and never paste it wholesale. Logs and\nconfig output can contain credentials or private user content, so query\nnarrowly and redact values when reporting.\n\n## Create and lifecycle\n\nRuntimes are `openclaw`, `hermes`, `goose`, `opencode`, and `buzz`. Confirm\nthe name, runtime, and target environment first, and dry-run the create:\n\n```bash\nhyper agents create docs-agent --runtime openclaw --dry-run\nhyper agents create docs-agent --runtime openclaw\nhyper agents wait <agent> --state running\n```\n\nDo not put secrets directly in command history; environment values passed\nat create time are sensitive even in a dry run.\n\nLifecycle commands are mutations — obtain approval and re-resolve the exact\ntarget immediately before acting:\n\n```bash\nhyper agents start <agent>\nhyper agents stop <agent>\nhyper agents delete <agent>\n```\n\n`stop` preserves the record and synced state; `delete` removes the runtime\nand record. A successful acknowledgement can be transitional:\n`hyper agents wait <agent>` (optionally with `--state`) confirms the target\nstate before dependent steps.\n\n## Container access\n\nUse the least powerful operation that answers the question:\n\n```bash\nhyper agents logs <agent> -f\nhyper agents exec <agent> -- uname -a\nhyper agents cp <agent>:/workspace/result.txt ./result.txt\nhyper agents shell <agent>\n```\n\n- `logs` prints recent output; `-f` follows. Log content can include\n  application secrets.\n- `exec` runs one remote command after `--` and is non-interactive. Avoid\n  environment or config dumps, and preserve the remote exit status and\n  stderr.\n- `cp` moves files in either direction with the `<agent>:<path>` syntax.\n  Confirm overwrites and obtain approval before writing remotely.\n- `shell` is an interactive session with broad authority, intended for\n  human operator work such as harness sign-in; keep transcripts private.\n\n`hyper agents token <agent>` (hidden) mints a fresh scoped key and prints\nit once: plain stdout carries only the key, `--json` carries the full\nrecord. Nothing is stored on disk, so treat stdout as secret-bearing, save\nthe key immediately, and never paste it into logs or replies.\n\n## Routines\n\nRoutines are the scheduled and recurring task surface for an agent:\n\n```bash\nhyper agents routines list --agent <agent>\nhyper agents routines create --cron \"0 9 * * *\" --prompt \"Summarize overnight progress\" --agent <agent>\nhyper agents routines create --run-at 2026-10-01T09:00:00Z --prompt \"One-shot reminder\"\nhyper agents routines delete <routine-id>\n```\n\n`routines create` takes no positionals: exactly one of `--cron EXPR` or\n`--run-at ISO`, plus `--prompt TEXT`, with optional `--agent ID`,\n`--name N`, and `--disabled`. `routines delete` takes the routine id (not\nthe agent id). Check `hyper agents routines create --help` for the exact\npayload shape before submitting, and treat routine mutations as\napproval-gated remote changes. `hyper agents routines update` (hidden)\nedits an existing routine in place.\n\n## Activate a grant code\n\n```bash\nhyper agents activate <code>\n```\n\n`activate` redeems a grant code for the current account and updates the\nentitlements visible in `hyper me`. Codes are secrets: do not place an\nunredeemed code in logs, issues, or responses, and confirm the resolved\nidentity with `hyper me` before redeeming.\n\n## OpenClaw configuration\n\nNew OpenClaw agents come from `hyper agents create <name> --runtime openclaw`;\nthere is no separate setup helper. For agents on\nthat runtime, two hidden commands expose the runtime configuration and\nmodel catalog:\n\n```bash\nhyper agents config get <agent>\nhyper agents models <agent>\n```\n\n`hyper agents config set <agent>` applies changes to the live OpenClaw\nruntime. Obtain approval first, keep payloads exact (validate JSON locally\nwhen a payload is required), and treat config output as sensitive. These\ncommands are OpenClaw-only; they do not apply to hermes, goose, opencode,\nor buzz agents.\n\n## Routes, archive, and restore\n\n`hyper agents routes list <agent>` (hidden) shows the agent's dynamic HTTPS\nroutes; `hyper agents routes add <agent> <name> --port N` (optional\n`--prefix P`, `--no-auth`) adds one, and `hyper agents routes remove <agent> <name>`\ndeletes one. Inspect current routes before mutating, and change one named\nroute at a time.\n\n`hyper agents archive <agent>` and `hyper agents restore <agent>` (hidden)\nmove an agent out of and back into active use. Both are mutations: resolve\nthe exact target and get approval first.\n\n## Failure handling\n\n- Resolve ambiguous names through `hyper agents ls`; never choose a match\n  by guesswork.\n- On `401`/`403`, load the `hypercli-auth` skill; do not rotate tokens or\n  keys as an automatic retry.\n- Preserve remote exec exit status and stderr. Do not describe partial\n  output as command success.\n- A stop acknowledgement means cleanup was accepted, not that the slot is\n  released; confirm with `wait` when the next step depends on the state.\n- Report agent ID/name, requested action, resulting state, and whether a\n  wait reached its target state. Never report a token, key, or code value.",
+  "commands": [
+    "hyper agents --help",
+    "hyper agents <command> --help",
+    "hyper",
+    "hyper agents wait <agent>",
+    "hyper agents token <agent>",
+    "hyper agents routines create --help",
+    "hyper agents routines update",
+    "hyper me",
+    "hyper agents create <name> --runtime openclaw",
+    "hyper agents config set <agent>",
+    "hyper agents routes list <agent>",
+    "hyper agents routes add <agent> <name> --port N",
+    "hyper agents routes remove <agent> <name>",
+    "hyper agents archive <agent>",
+    "hyper agents restore <agent>",
+    "hyper agents ls"
+  ]
+}

package/skills/hypercli-auth.json

@@ -0,0 +1,11 @@
+{
+  "name": "hypercli-auth",
+  "description": "Diagnose and configure HyperCLI credentials, API bases, and inactive keys, and authenticate hosted Buzz coding-runtime harnesses. Use when choosing between HYPER_API_KEY and HYPER_AGENTS_API_KEY, running hyper me safely, applying hyper configure, or signing OpenCode, Goose, Claude Code, Codex, or Kimi Code into a hosted runtime.",
+  "markdown": "---\nname: hypercli-auth\ndescription: >\n  Diagnose and configure HyperCLI credentials, API bases, and inactive keys,\n  and authenticate hosted Buzz coding-runtime harnesses. Use when choosing\n  between HYPER_API_KEY and HYPER_AGENTS_API_KEY, running hyper me safely,\n  applying hyper configure, or signing OpenCode, Goose, Claude Code, Codex,\n  or Kimi Code into a hosted runtime.\n---\n\n# HyperCLI Authentication\n\nLoad the `hypercli` skill for the operation itself. Use this skill before\nchanging a credential, API base, or coding-harness login.\n\nKeep these authorities separate:\n\n- **HyperCLI product auth** covers identity, jobs, uploads, flows, and\n  voice — everything resolves through the product key chain below.\n- **HyperCLI agent/runtime auth** covers the managed-agent APIs and is\n  normally narrower than product auth.\n- **Harness/vendor sign-in** belongs to Claude Code, Codex, OpenCode,\n  Goose, or Kimi Code. A HyperCLI key is not automatically an Anthropic,\n  OpenAI, or Moonshot login.\n\nNever invent a credential bridge between these authorities.\n\n## Resolve Credentials Exactly\n\nThe shared SDK/CLI credential resolves in this order:\n\n1. Explicit canonical credential, where supported.\n2. Environment `HYPER_API_KEY`.\n3. The canonical `HYPER_API_KEY` saved by `hyper configure` in\n   `$HYPER_HOME/config`, or `~/.hypercli/config` when `HYPER_HOME` is unset.\n4. Environment `HYPER_AGENTS_API_KEY`, only when no canonical source\n   provides a key.\n\nA saved canonical key beats the managed runtime environment fallback.\nThis fallback applies to the shared client, including product requests;\nthe key's scopes still determine which operations are allowed. Writing a\nlower-priority source does not change the active credential. Unset or\nreplace the actual winning source.\n\n`hyper configure` is the preferred way to set the local product key; it\nwrites the active config file with owner-only read/write permissions. Do not pass key\nliterals on other command lines — they leak through shell history and\nprocess lists.\n\n## API Base and Environment Selection\n\n`HYPER_API_BASE` selects product/inference; `HYPER_AGENTS_API_BASE` independently\nselects direct Agent control and never inference. Both are customer\nenvironment/config settings. Without an Agents base, Agent endpoints derive\nfrom the product base. Namespace-specific base overrides remain unsupported.\nSelect dev product/inference with `HYPER_API_BASE=https://api.dev.hypercli.com`\nin environment/config. If an Agents base is already configured, also set\n`HYPER_AGENTS_API_BASE=https://api.agents.dev.hypercli.com` when the intent is\nto move Agent control to dev. Public TS/Python/ACP CLIs do not support `--dev` or\n`--prod`; those flags are reserved for admin tooling. Do not select another API base unless\nthe user explicitly intends that environment. Read the\n[configuration reference](/opt/hypercli/docs/cli/configuration.mdx) before\nchanging a base URL setting.\n\n## Diagnose Without Revealing Secrets\n\nPrint source names, never values:\n\n```bash\ntest -n \"${HYPER_API_KEY:-}\" && echo HYPER_API_KEY present || echo HYPER_API_KEY missing\ntest -n \"${HYPER_AGENTS_API_KEY:-}\" && echo HYPER_AGENTS_API_KEY present || echo HYPER_AGENTS_API_KEY missing\ntest -s ~/.hypercli/config && echo config present || echo config missing\n```\n\nThen test identity once:\n\n```bash\nhyper me\n```\n\n`hyper me` prints identity, capability, and entitlement fields for the\nactive key. Its output can include account and key identifiers; keep it\nprivate and use `hyper me --json` only for private automation. A `401`\nthere means the resolved credential is rejected, not that one group is\nmisconfigured.\n\n## Handle Inactive Or Under-Scoped Keys\n\nA `401` detail such as `API key is inactive` means the selected key was\nrecognized but deactivated. Stop; retrying cannot reactivate it.\n\n1. Record only the winning source name, resolved environment (prod/dev),\n   status, and server detail.\n2. Replace or activate the key at the highest-priority source.\n3. Run `hyper me` once more before retrying the original operation.\n\nA `403` usually means a valid identity lacks the requested capability.\nInspect the capabilities shown by `hyper me`; do not substitute another\ncredential without the user's authorization.\n\nHosted runtime keys are injected by the control plane and revoked during\nruntime cleanup. Do not copy an injected runtime key into persistent config\nor vendor sign-in files.\n\n## Keep Secrets Out Of State And Output\n\n- Prefer `hyper configure` for a normal local product key; it writes\n  the active config file with restrictive permissions. Environment\n  `HYPER_API_KEY` still wins; environment `HYPER_AGENTS_API_KEY` does not.\n- Treat `~/.hypercli/config`, `~/.hypercli/agents.json`, and harness\n  sign-in files as secrets.\n- Do not dump `env`, `printenv`, config files, or `hyper agents ls --json`\n  while debugging. Agent inventory can include launch environment values.\n- Never send a credential through source control, an issue, or a shell\n  command recorded in history.\n\nHosted Buzz images are not a general secret vault: launch environment can\nbe exposed through management APIs and egress is not restricted. Do not\ninject a valuable long-lived vendor key when creating or starting Buzz\nruntimes.\n\n## Authenticate Hosted Buzz Runtimes\n\nIdentify the runtime from the deployment's runtime label, then use that runtime's\nnative authentication interface below. The Buzz plugin exposes no auth-method or\nmodel probe commands. SDK auth helpers offer native OpenCode, Codex and Claude\nlogin methods. Other runtimes return no SDK login methods, and unsupported status\nreturns an explicit error rather than launching a probe child.\n\nRunner and Lagoon inject consistent defaults for `HYPER_API_BASE`,\n`HYPER_AGENTS_API_BASE`, the appropriate ACP URL, and scoped `HYPER_AGENTS_API_KEY`.\nCustomers may override either base through launch `env` or `secrets`. A customer\n`HYPER_API_KEY` in either map is preserved and overrides the default runtime key;\nbroader uses such as managing other agents are supported. The launch owner's\nauth key is never automatically forwarded. The default runtime key typically\npermits file, flow, model, and voice routes while denying agent management.\n\nExplicit `HYPER_ACP_WS_URL` wins; otherwise derive it from the Agents base,\nfalling back to the product base only if no Agents base is supplied. Images\nmust not bake in a production Agents base that selects the wrong plane.\nExternal inference URLs/keys must not implicitly redirect platform callbacks\nor reconnects. ACP transport uses the separate platform runtime key.\n\n| Runtime | What works in the hosted image | What does not happen |\n| --- | --- | --- |\n| OpenCode | A seeded HyperCLI provider reads the runtime key and API base. Zero entries from `opencode auth list` does not invalidate this env-backed provider. | The runtime key is not converted into an OpenCode vendor login. |\n| Goose | A seeded `hypercli` custom provider reads the runtime key and agents base; no vendor login is required for that provider. | The runtime's provider method does not grant new HyperCLI scopes. |\n| Claude Code | The image exposes `claude-ai-login` and `console-login`; inspect with `claude auth status --json`. | `HYPER_AGENTS_API_KEY` is not Anthropic Console, Claude subscription, or SSO auth. |\n| Codex | The image exposes API-key and OpenAI account sign-in methods; inspect with `codex login status`. | The runtime key is not an OpenAI key or account login. Do not seed `.codex/auth.json` with it as an inferred bridge. |\n| Kimi Code | The image exposes upstream `login`; inspect with `kimi login --help`. | The runtime key is not a Moonshot/Kimi login. |\n\nOpenCode and Goose should normally start with the injected HyperCLI\nprovider. If native ACP session setup fails, check presence only with the\n`test -n` form above; do not print the values or copy the runtime key into\nanother file.\n\nClaude Code, Codex, and Kimi Code require upstream human-owned sign-in\nstate. An operator may enter the runtime through an approved interactive\nsession:\n\n```bash\nhyper agents shell <agent>\n```\n\nInside that private terminal, use the vendor's installed help and human\nflow, for example `claude auth status --json` and `claude auth login`,\n`codex login status`, or `kimi login`. The human must complete browser,\ndevice, subscription, SSO, or secret prompts. The remote agent must not ask\nfor a token in-band, select a different account, or claim success before\nthe vendor status command succeeds. A running harness process may need an\noperator-approved restart to read newly written sign-in state; do not\nrestart it implicitly.\n\nIf installed versions disagree with this matrix, stop and inspect their\ncurrent `--help` output and `/opt/hypercli/skills`. Do not improvise a\nlogin bridge.",
+  "commands": [
+    "hyper configure",
+    "hyper me",
+    "hyper me --json",
+    "hyper agents ls --json"
+  ]
+}

package/skills/hypercli-compute.json

@@ -0,0 +1,20 @@
+{
+  "name": "hypercli-compute",
+  "description": "Browse the live HyperCLI GPU catalog and create, inspect, and control GPU jobs. Use for hyper jobs gpus inventory, job submission preflighted with --dry-run, job list/get/logs, cancellation, and the hidden extend and exec power commands.",
+  "markdown": "---\nname: hypercli-compute\ndescription: >\n  Browse the live HyperCLI GPU catalog and create, inspect, and control GPU\n  jobs. Use for hyper jobs gpus inventory, job submission preflighted with\n  --dry-run, job list/get/logs, cancellation, and the hidden extend and\n  exec power commands.\n---\n\n# HyperCLI Compute\n\nLoad the `hypercli` and `hypercli-auth` skills first. Use the managed image\nreference at `/opt/hypercli/docs/cli/commands/jobs.mdx`, then confirm flags\nwith `hyper jobs --help`. GPU availability and pricing are live data; never\nquote remembered values.\n\n## Complete command map\n\n| Area | Commands |\n| --- | --- |\n| Catalog | `hyper jobs gpus` |\n| Submit | `hyper jobs create` (supports `--dry-run`) |\n| Inspect | `hyper jobs list`, `hyper jobs get`, `hyper jobs logs` |\n| Control | `hyper jobs cancel` |\n| Hidden power | `hyper jobs extend`, `hyper jobs exec` |\n| Instances | `hyper instances gpus`, `hyper instances launch`; root shortcut `hyper launch <image>` |\n\n## Browse the catalog\n\n```bash\nhyper jobs gpus\nhyper jobs gpus --json\n```\n\nThe catalog reports current GPU types, availability, and pricing. Use it\nimmediately before submitting; do not hard-code stale GPU names or prices.\nUse `--json` only when a machine will parse the result.\n\n## Submit once\n\nCompose the create call from current help output — the image, GPU type, and\ncommand are the minimum to confirm with the user:\n\n```bash\nhyper jobs create --help\n```\n\nPreflight with a dry run, then submit once and record the returned job ID:\n\n```bash\nhyper jobs create --dry-run\nhyper jobs create\n```\n\nA dry run validates without billing; re-check the live catalog entry, GPU\ntype, runtime, and cost before the real call. Never resubmit after an\nambiguous timeout or transport failure: check `hyper jobs list` under the\nsame auth context first, because one create can start billable compute.\n\n## Inspect jobs\n\n```bash\nhyper jobs list\nhyper jobs list --json\nhyper jobs get <job>\n```\n\nPass the full job ID; if you only have a prefix, confirm the match against\n`hyper jobs list` instead of guessing. Job detail can include the image,\ncommand, networking, and environment inputs; keep it private when the\nsubmission contained sensitive values.\n\n## Logs\n\n```bash\nhyper jobs logs <job>\nhyper jobs logs <job> -f\n```\n\n`-f` follows output until the job exits. Log content may contain\napplication secrets or user data; query narrowly and redact when reporting.\n\n## Control\n\n```bash\nhyper jobs cancel <job>\n```\n\n`cancel` is immediate; obtain approval and confirm the target and current\nstate with `hyper jobs get <job>` first. A job in a transitional state can\nstill accrue cost until cancellation is accepted. Fetch the job again if\nthe user needs confirmation of terminal state.\n\nHidden power commands:\n\n```bash\nhyper jobs extend <job>\nhyper jobs exec <job> -- nvidia-smi\n```\n\n`extend` changes the job's runtime budget and can change cost — confirm the\nnew value and the exact job with the user first. `exec` runs a one-shot\nremote command after `--`; preserve its exit status and stderr, obtain\napproval before execution, and apply the same secrecy rules as agent exec\n(see the `hypercli-agents` skill).\n\n## Operational rules\n\n- One create can start billable compute. Never submit duplicates while\n  polling or after an ambiguous timeout.\n- Use `--dry-run` to validate, then re-check live GPU type, availability,\n  runtime, and cost before the real call.\n- Cancel only the intended job, and only with approval.\n- Report job ID, state, GPU type, and whether an operation was a dry run or\n  real. Redact environment values, credentials, and authenticated URLs.",
+  "commands": [
+    "hyper jobs --help",
+    "hyper jobs gpus",
+    "hyper jobs create",
+    "hyper jobs list",
+    "hyper jobs get",
+    "hyper jobs logs",
+    "hyper jobs cancel",
+    "hyper jobs extend",
+    "hyper jobs exec",
+    "hyper instances gpus",
+    "hyper instances launch",
+    "hyper launch <image>",
+    "hyper jobs get <job>"
+  ]
+}

package/skills/hypercli-flows.json

@@ -0,0 +1,11 @@
+{
+  "name": "hypercli-flows",
+  "description": "Create, monitor, wait on, and cancel HyperCLI image and video flows, and upload reusable pipeline inputs with hyper files upload. Use for hyper flow create across the current flow types, flow list/status/wait tracking, and cancelled or failed render handling.",
+  "markdown": "---\nname: hypercli-flows\ndescription: >\n  Create, monitor, wait on, and cancel HyperCLI image and video flows, and\n  upload reusable pipeline inputs with hyper files upload. Use for hyper\n  flow create across the current flow types, flow list/status/wait\n  tracking, and cancelled or failed render handling.\n---\n\n# HyperCLI Flows\n\nLoad the `hypercli-auth` skill first for authentication, API-base checks,\nand credential safety. Load `hypercli-voice` instead for speech generation.\n\nThe checked-in references are:\n\n- `/opt/hypercli/docs/cli/commands/flow.mdx`\n- `/opt/hypercli/docs/cli/commands/files.mdx`\n\nRun `hyper flow --help` and `hyper flow create <type> --help` when installed\nhelp differs from these instructions. Do not guess flags or hard-code\nprices.\n\n## Use The Right Flow Type\n\n```bash\nhyper flow create <type> --help\n```\n\n| Need | Type |\n| --- | --- |\n| General image generation, including text in images | `text-to-image` |\n| HiDream image generation | `text-to-image-hidream` |\n| Video generated from a prompt | `text-to-video` |\n| Animate one image | `image-to-video` |\n| Edit or combine images | `image-to-image` |\n| Generate a transition between exact endpoint frames | `first-last-frame-video` |\n\nLegacy types `speaking-video`, `audio-to-text`, and `text-to-speech` remain\naccepted for existing workflows. For speech generation prefer\n`hyper voice clone` with reference audio from the `hypercli-voice` skill over the legacy\n`text-to-speech` flow type.\n\n## Submit with parameters\n\nCreation accepts per-type flags or generic key/value parameters:\n\n```bash\nhyper flow create text-to-image --param prompt=\"a neon sign reading HYPER\"\nhyper flow create text-to-video --param prompt=\"slow aerial move over a frozen lake\" --json\n```\n\nConfirm the exact per-type flags and parameter names from\n`hyper flow create <type> --help`; do not invent a resolution or sizing\ncontract. Where a type takes an input image, pass a readable local path or\na previously uploaded file ID exactly as the help describes.\n\n## Reusable file inputs\n\nEach submission that references a local path uploads it again. Upload once\nwhen an input will be reused:\n\n```bash\nhyper files upload ./source.png\nhyper files get <file-id>\nhyper files delete <file-id>\n```\n\nKeep the returned file ID from `upload`; poll `get` until processing is\ndone before referencing the ID in a flow, and read failure detail from the\nsame `get` output. `delete` needs approval: removing a file can break\npending or reproducible renders.\n\n## Submit once, then track the ID\n\nCreation returns before rendering finishes. A queued or running state is a\nsuccessful submission, not a reason to create another render. Record the\nreturned render ID immediately and use the same ID for the complete\nlifecycle:\n\n```bash\nhyper flow list\nhyper flow list --json\nhyper flow status <render-id>\nhyper flow wait <render-id>\n```\n\n- `status` reports the current state; after completion it carries the\n  result location from the render detail.\n- `wait` blocks until a terminal state and is the right call when the next\n  step depends on completion. Check whether it ended completed, failed, or\n  cancelled.\n- `list` queries remote renders under the active auth context. If\n  submission output was lost or a transport failure makes creation\n  ambiguous, inspect `hyper flow list --json` before any retry: there is no\n  idempotency flag, and an unverified retry can double a charge.\n\n## Cancel and terminal states\n\n```bash\nhyper flow cancel <render-id>\n```\n\n`cancel` is immediate with no confirmation prompt. Cancel only when the\nuser requested it or the established workflow requires it.\n\nOn `failed`, read the error from the render detail before resubmitting, and\nget approval before another paid attempt. On `cancelled`, no result will be\nproduced — do not poll indefinitely or resubmit implicitly.\n\n## Identity and billing\n\nBefore a paid operation, validate the intended product identity without\nprinting its credential:\n\n```bash\nhyper me --json\n```\n\nA `401` is an authentication failure, not a prompt or render failure.\nFollow the `hypercli-auth` skill; do not retry, reveal the key, or switch\nidentity automatically.",
+  "commands": [
+    "hyper flow --help",
+    "hyper flow create <type> --help",
+    "hyper voice clone",
+    "hyper flow list --json"
+  ]
+}