@indigoai-us/hq-cli 5.103.21 → 5.103.23

package/dist/commands/integrations-manage.js

@@ -1,6 +1,6 @@
 /**
  * `hq integrations show | policy | grants | grant | ungrant | access | share |
- * unshare | audit | pending | disconnect`.
+ * unshare | audit | pending | disconnect | purge`.
  *
  * The govern-and-remove half of the lifecycle. Two different permission
  * surfaces live here and are easy to confuse, so they get separate verbs:
@@ -16,8 +16,8 @@ import readline from "node:readline";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
-import { IntegrationsCliError, bareProvider, fetchAdminSurface, printJson, resolveConnection, selectConnection, } from "./integrations-core.js";
-import { fetchPendingApprovals, getConnectionAccess, mutateConnectionAccess, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
+import { IntegrationsCliError, bareProvider, fetchConnections, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, selectConnection, } from "./integrations-core.js";
+import { fetchPendingApprovals, getConnectionAccess, mutateConnectionAccess, purgeConnection, setReadSafe, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
 const WRITE_POLICIES = ["auto-allow", "confirm", "deny"];
 const PERMISSIONS = ["read", "write", "admin"];
 /** Plain-English gloss for each write policy, used in every policy readout. */
@@ -97,6 +97,67 @@ function confirm(message) {
 function connectionLabel(connection) {
     return connection.installation?.displayName ?? bareProvider(connection.provider);
 }
+/**
+ * The category of match must mirror `selectConnection`: an exact provider id
+ * takes precedence over a display name, which takes precedence over its human
+ * slug. Unlike ordinary verbs, purge deliberately operates on historical
+ * revoked rows, so it must not inherit selectConnection's active-first policy.
+ */
+function purgeSelectorMatches(connections, selector) {
+    if (selector.connection) {
+        return connections.filter((connection) => connection.id === selector.connection);
+    }
+    if (selector.provider) {
+        const want = selector.provider.trim().toLowerCase();
+        const wantHumanSlug = humanSlug(selector.provider);
+        const providerMatches = connections.filter((connection) => bareProvider(connection.provider).toLowerCase() === want ||
+            connection.provider.toLowerCase() === want);
+        if (providerMatches.length > 0)
+            return providerMatches;
+        const displayNameMatches = connections.filter((connection) => connection.installation?.displayName?.trim().toLowerCase() === want);
+        if (displayNameMatches.length > 0)
+            return displayNameMatches;
+        if (wantHumanSlug) {
+            return connections.filter((connection) => {
+                const displayName = connection.installation?.displayName;
+                return displayName !== undefined && humanSlug(displayName) === wantHumanSlug;
+            });
+        }
+        return [];
+    }
+    return connections;
+}
+function humanSlug(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function purgeSelector(app, opts) {
+    if (app && !opts.provider && !opts.connection) {
+        return app.startsWith("acct_") ? { connection: app } : { provider: app };
+    }
+    return opts;
+}
+async function resolveRevokedPurgeConnection(token, companyUid, app, opts) {
+    const selector = purgeSelector(app, opts);
+    const connections = await fetchConnections(token, companyUid);
+    const matches = purgeSelectorMatches(connections, selector);
+    const revoked = matches.filter((connection) => connection.status === "revoked");
+    if (revoked.length === 1)
+        return revoked[0];
+    if (revoked.length > 1) {
+        const selected = selector.connection ?? selector.provider ?? "the supplied selector";
+        throw new IntegrationsCliError(`Multiple revoked connections match '${selected}'. Use --connection <acct_id> to choose one:\n` +
+            revoked.map((connection) => `  --connection ${connection.id} (${connectionLabel(connection)})`).join("\n"), { expected: true });
+    }
+    if (matches.length > 0) {
+        throw new IntegrationsCliError(`${connectionLabel(matches[0])} is still connected. Disconnect it first, then purge it.`, { expected: true });
+    }
+    // Keep the existing command group's not-found wording and error taxonomy.
+    return selectConnection(connections, selector);
+}
 /**
  * Governance writes are owner-only on hq-pro AND the allowlist PATCH is a
  * whole-list REPLACE. A non-owner reads an identity-redacted grant list, so
@@ -144,7 +205,9 @@ export function registerManageCommands(integrations) {
             ? selectConnection(surface.connections, app.startsWith("acct_") ? { connection: app } : { provider: app })
             : selectConnection(surface.connections, opts);
         if (opts.json) {
-            printJson(connection);
+            printJson(connection.status === "revoked"
+                ? { ...connection, ...revokedConnectionDetails(connection, opts.company) }
+                : connection);
             return;
         }
         const install = connection.installation;
@@ -153,6 +216,11 @@ export function registerManageCommands(integrations) {
         if (install?.id)
             console.log(chalk.dim(`  installation: ${install.id}`));
         console.log(chalk.dim(`  status:      ${connection.status}`));
+        if (connection.status === "revoked") {
+            const details = revokedConnectionDetails(connection, opts.company);
+            console.log(chalk.yellow(`  Revoked — ${details.reason}`));
+            console.log(chalk.yellow(`  Re-add: ${details.fixPath}`));
+        }
         if (install?.domain)
             console.log(chalk.dim(`  domain:      ${install.domain}`));
         if (install?.surface?.url)
@@ -218,6 +286,47 @@ export function registerManageCommands(integrations) {
         }
         console.log(chalk.green(`${connectionLabel(connection)}: ${writePolicy} — ${POLICY_BLURB[writePolicy]}`));
     });
+    integrations
+        .command("read-safe <tool>")
+        .description("Mark a read-only tool as safe to run without approval (owner only)")
+        .option("--company <slug>", "Company slug, e.g. indigo")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--unset", "Remove the read-safe override")
+        .option("--off", "Alias for --unset")
+        .option("--json", "Machine-readable output")
+        .action(async (tool, opts) => {
+        const toolName = tool.trim();
+        if (!toolName) {
+            throw new IntegrationsCliError("Tool name cannot be empty.", { expected: true });
+        }
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveConnection(token, companyUid, undefined, opts);
+        const readSafe = !(opts.unset || opts.off);
+        try {
+            await setReadSafe(token, companyUid, connection.id, toolName, readSafe);
+        }
+        catch (error) {
+            if (error instanceof IntegrationsCliError) {
+                if (error.status === 403) {
+                    throw new IntegrationsCliError("This command is owner only. Ask a company owner to manage read-safe tools.", { expected: true });
+                }
+                if (readSafe && (error.status === 409 || error.status === 422)) {
+                    throw new IntegrationsCliError(`${toolName} is a write tool and can't be marked read-safe (its changes always need approval).`, { expected: true });
+                }
+            }
+            throw error;
+        }
+        const outcome = { connectionId: connection.id, toolName, readSafe };
+        if (opts.json) {
+            printJson(outcome);
+            return;
+        }
+        console.log(chalk.green(readSafe
+            ? `${toolName} on ${connectionLabel(connection)} is now read-safe and skips approval.`
+            : `${toolName} on ${connectionLabel(connection)} is no longer read-safe; its override was removed.`));
+    });
     integrations
         .command("grants [app]")
         .description("Show who is authorized to run an app's change-making tools")
@@ -518,6 +627,52 @@ export function registerManageCommands(integrations) {
         }
         console.log(chalk.green(`Disconnected ${connectionLabel(connection)}.`));
     });
+    integrations
+        .command("purge [app]")
+        .description("Permanently remove a revoked connection from the list (owner only)")
+        .option("--company <slug>", "Company slug, e.g. indigo")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--yes", "Skip the permanent-removal confirmation prompt")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveRevokedPurgeConnection(token, companyUid, app, opts);
+        const label = connectionLabel(connection);
+        if (!opts.yes) {
+            // Warning + prompt go to stderr: with --json, stdout must stay parseable.
+            console.error(`Purging ${chalk.bold(label)} permanently removes its revoked connection record. It cannot be restored.`);
+            const ok = await confirm(`Permanently purge ${label}?`);
+            if (!ok) {
+                // A non-TTY run lands here too: refusing is the only safe default
+                // when nobody can confirm a permanent deletion.
+                throw new IntegrationsCliError("Not purged. Re-run with --yes if you are sure.", { expected: true });
+            }
+        }
+        try {
+            await purgeConnection(token, companyUid, connection.id);
+        }
+        catch (error) {
+            if (error instanceof IntegrationsCliError && error.status === 409) {
+                throw new IntegrationsCliError(`${label} is still connected. Disconnect it first, then purge it.`, { expected: true, status: 409, code: error.code });
+            }
+            if (error instanceof IntegrationsCliError && error.status === 403) {
+                throw new IntegrationsCliError("Purging a connection is owner only. Ask a company owner to run this.", { expected: true, status: 403, code: error.code });
+            }
+            throw error;
+        }
+        const outcome = {
+            connectionId: connection.id,
+            provider: bareProvider(connection.provider),
+            status: "purged",
+        };
+        if (opts.json) {
+            printJson(outcome);
+            return;
+        }
+        console.log(chalk.green(`Purged ${label}. It will no longer appear in \`hq integrations list\`.`));
+    });
 }
 /** Order-insensitive identity of an allowlist, for change detection. */
 export function allowlistFingerprint(grants) {

package/dist/commands/integrations.d.ts

@@ -26,10 +26,12 @@
  *
  * Govern and remove:
  *   hq integrations policy [app] --set <m>   Approval setting for changes.
+ *   hq integrations read-safe <tool>          Mark/unmark a trusted read-only tool.
  *   hq integrations grants|grant|ungrant     Per-tool authorization to run change-making tools.
  *   hq integrations access|share|unshare     Who may use the app.
  *   hq integrations audit                    Recent activity.
  *   hq integrations disconnect [app]         Remove it and its credentials.
+ *   hq integrations purge [app]              Permanently remove a revoked connection row.
  *
  * Governance: reads flow freely; calls that can change the app are subject to
  * the connection's write policy (default: a person approves first). A queued

package/dist/commands/integrations.js

@@ -26,10 +26,12 @@
  *
  * Govern and remove:
  *   hq integrations policy [app] --set <m>   Approval setting for changes.
+ *   hq integrations read-safe <tool>          Mark/unmark a trusted read-only tool.
  *   hq integrations grants|grant|ungrant     Per-tool authorization to run change-making tools.
  *   hq integrations access|share|unshare     Who may use the app.
  *   hq integrations audit                    Recent activity.
  *   hq integrations disconnect [app]         Remove it and its credentials.
+ *   hq integrations purge [app]              Permanently remove a revoked connection row.
  *
  * Governance: reads flow freely; calls that can change the app are subject to
  * the connection's write policy (default: a person approves first). A queued
@@ -50,11 +52,65 @@ import { randomUUID } from "node:crypto";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
 import { registerConnectCommands } from "./integrations-connect.js";
 import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
 export { IntegrationsCliError, callGateway, fetchConnections, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
+/**
+ * Gateway metadata is additive and may be absent when talking to an older
+ * gateway. Parse it defensively so an unknown or malformed value never breaks
+ * tool discovery.
+ */
+function effectiveToolMode(tool) {
+    const raw = tool._meta?.["hq/effective-mode"];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const mode = raw.mode;
+    const approvalRequired = raw.approvalRequired;
+    if ((mode !== "read" && mode !== "write") || typeof approvalRequired !== "boolean") {
+        return null;
+    }
+    const denied = raw.denied;
+    const policy = raw.policy;
+    return {
+        mode,
+        approvalRequired,
+        ...(denied === true ? { denied: true } : {}),
+        ...(policy === "deny" ? { policy: "deny" } : {}),
+    };
+}
+function toolBadge(tool) {
+    const effectiveMode = effectiveToolMode(tool);
+    if (!effectiveMode)
+        return null;
+    if (effectiveMode.mode === "read")
+        return "read";
+    if (effectiveMode.denied)
+        return "denied";
+    return effectiveMode.approvalRequired ? "approval-required" : "write";
+}
+function formatToolBadge(tool) {
+    const badge = toolBadge(tool);
+    if (!badge)
+        return "";
+    const label = `[${badge}]`;
+    switch (badge) {
+        case "read":
+            return chalk.green(label);
+        case "approval-required":
+            return chalk.yellow(label);
+        case "denied":
+            return chalk.red(label);
+        case "write":
+            return chalk.blue(label);
+    }
+}
+/** Add gateway policy metadata where scripts can consume it directly. */
+function toolJsonView(tool) {
+    const effectiveMode = effectiveToolMode(tool);
+    return effectiveMode ? { ...tool, effectiveMode } : tool;
+}
 /**
  * The gateway relays MCP tool schemas verbatim. Keep the default listing
  * compact, but make required inputs visible before a caller has to discover
@@ -86,6 +142,23 @@ function printToolSchema(tool) {
     console.log(chalk.dim("  Input schema:"));
     console.log(chalk.dim(schema.split("\n").map((line) => `  ${line}`).join("\n")));
 }
+function reportRevokedConnection(connection, opts) {
+    if (connection.status !== "revoked")
+        return false;
+    const details = revokedConnectionDetails(connection, opts.company);
+    if (opts.json) {
+        printJson(details);
+    }
+    else {
+        console.log(chalk.yellow(`${connectionLabel(connection)}: status=revoked`));
+        console.log(chalk.yellow(`  ${details.reason}`));
+        console.log(`  Re-add: ${details.fixPath}`);
+    }
+    if (opts.fail) {
+        throw new IntegrationsCliError(`status=revoked. ${details.reason} Re-add with: ${details.fixPath}`, { expected: true });
+    }
+    return true;
+}
 export function registerIntegrationsCommand(program) {
     const integrations = program
         .command("integrations")
@@ -132,6 +205,8 @@ export function registerIntegrationsCommand(program) {
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
         const connection = selectConnection(await fetchConnections(token, companyUid), opts);
+        if (reportRevokedConnection(connection, opts))
+            return;
         const prefix = toolPrefixForProvider(connection.provider);
         const message = await callGateway(token, {
             companyUid,
@@ -154,24 +229,26 @@ export function registerIntegrationsCommand(program) {
                 throw new IntegrationsCliError(`No tool named '${opts.describe}' on ${connectionLabel(connection)}.`, { expected: true });
             }
             if (opts.json) {
-                printJson(tool);
+                printJson(toolJsonView(tool));
                 return;
             }
-            console.log(`${chalk.bold(tool.name)}  ${chalk.dim(`on ${connectionLabel(connection)}`)}`);
+            const badge = formatToolBadge(tool);
+            console.log(`${chalk.bold(tool.name)}${badge ? `  ${badge}` : ""}  ${chalk.dim(`on ${connectionLabel(connection)}`)}`);
             if (tool.description)
                 console.log(chalk.dim(`  ${tool.description}`));
             printToolSchema(tool);
             return;
         }
         if (opts.json) {
-            printJson(payload);
+            printJson({ ...payload, tools: tools.map(toolJsonView) });
             return;
         }
         console.log(chalk.dim(`App: ${connectionLabel(connection)}`));
         for (const tool of tools) {
             const label = tool.title && tool.title !== tool.name ? `  ${chalk.dim(tool.title)}` : "";
             const required = requiredInputHint(tool.inputSchema);
-            console.log(`${chalk.bold(tool.name)}${label}${required ? `  ${chalk.dim(required)}` : ""}`);
+            const badge = formatToolBadge(tool);
+            console.log(`${chalk.bold(tool.name)}${badge ? `  ${badge}` : ""}${label}${required ? `  ${chalk.dim(required)}` : ""}`);
         }
         console.log(chalk.dim(`\n${tools.length} tools. Describe inputs: hq integrations tools --provider ${bareProvider(connection.provider)} --describe <tool>\nCall one with: hq integrations call <tool> --provider ${bareProvider(connection.provider)} --args '<json>'`));
     });
@@ -199,6 +276,8 @@ export function registerIntegrationsCommand(program) {
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
         const connection = selectConnection(await fetchConnections(token, companyUid), opts);
+        if (reportRevokedConnection(connection, { ...opts, fail: true }))
+            return;
         const prefix = toolPrefixForProvider(connection.provider);
         const idempotencyKey = opts.idempotencyKey ?? `hq-cli-${randomUUID()}`;
         const message = await callGateway(token, {

package/dist/commands/skill.d.ts

@@ -1,153 +1,55 @@
 /**
- * `hq skill` subcommand group (US-017).
+ * Company skill creation and comment-only improvements.
  *
- * Terminal / scriptable access to the skill collaboration loop:
- *
- *   hq skill suggest <uid|path>   Propose a change to a skill from working edits.
- *   hq skill list-suggestions     Show the review inbox (suggestions on skills you own).
- *   hq skill review <sgn_…>       Accept (merge) or decline a pending suggestion.
- *
- * This is a THIN front-end over the SAME wired hq-pro routes the MCP surface
- * (US-007) and the console merge path (US-009) use — there is NO forked
- * suggestion or merge logic here. The CLI reads the local working SKILL.md,
- * computes the proposed content (+ its base for a diff), and POSTs to:
- *
- *   CREATE  POST /v1/files/skills/company/{slug}/{skillUid}/suggestions
- *   LIST    POST /v1/files/skills/company/{slug}/suggestions/list
- *   ACCEPT  POST /v1/files/skills/company/{slug}/{skillUid}/suggestions/{id}/accept
- *   DECLINE POST /v1/files/skills/company/{slug}/{skillUid}/suggestions/{id}/decline
- *
- * The skill routes are keyed on the company SLUG (path param, resolved
- * server-side via findEntityBySlug) — NOT the companyUid the vault/ACL routes
- * use — so this module resolves a slug (from `--company` or the active company)
- * and passes it straight through.
- *
- * Lock semantics (AC3): a suggest against a skill the caller cannot WRITE still
- * SUCCEEDS as a proposal. The CREATE route is MEMBER-gated (never write-gated),
- * so this command performs NO client-side lock/permission pre-check — it always
- * posts and renders whatever the server returns. A locked-out member lands a
- * suggestion, never a hard permission error.
- *
- * Attribution (AC4): the invoking identity (from the Cognito JWT) is the server-
- * derived `authorPersonUid`; the CLI never sends an author. An optional
- * `--note` rides as `authorNote` (the change's rationale / failure context).
+ * `hq skill create <slug>` registers a canonical company skill, stamps its
+ * immutable UID, reindexes its generated runtime wrapper, and syncs it.
+ * `hq skill propose <uid|path> --message "…"` posts a whole-skill comment to
+ * the same improvement thread shown in HQ Console. It never uploads a modified
+ * SKILL.md and cannot overwrite live content. Structured suggest/list/review
+ * commands intentionally are not registered.
  */
 import { Command } from "commander";
-/**
- * A `skl_…` argument to `suggest` is a skill UID (resolve the local file from
- * it); anything else is a filesystem path. Lenient on the suffix (the strict
- * `skl_<ulid>` shape is `isSkillUid` on the server) so a hand-typed / fixture
- * uid still routes to the uid branch.
- */
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
 export declare const SKILL_UID_PATTERN: RegExp;
-/** A `sgn_…` suggestion id — the `review` target and the LIST row key. */
-export declare const SUGGESTION_ID_PATTERN: RegExp;
-/**
- * Read the top-level `skill_uid` from a SKILL.md's YAML frontmatter. Mirrors
- * hq-pro's `parseSkillFrontmatter` (block extraction → YAML parse → read the
- * top-level `skill_uid` string). Returns `undefined` when there is no
- * frontmatter, it fails to parse, or `skill_uid` is absent / not a `skl_…`
- * string. Never throws.
- */
-export declare function parseSkillUid(md: string): string | undefined;
-/** sha256 hex of a string — the base-version fingerprint the server records (AC2). */
-export declare function sha256Hex(content: string): string;
-export interface SuggestionCreateBody {
-    proposedContent: string;
-    baseContent?: string;
-    baseContentHash?: string;
-    authorNote?: string;
+export declare const SKILL_SLUG_PATTERN: RegExp;
+interface SkillSyncInput {
+    filePath: string;
+    companySlug: string;
+    hqRoot: string;
+    token: string;
 }
-/**
- * Build the CREATE request body from the resolved proposed content and an
- * optional base. Mirrors the server's two payload shapes:
- *   - `baseContent` present → the server derives the unified diff + base hash
- *     (the diff-by-default path). A no-op (base === proposed) is rejected here
- *     rather than round-tripped to an EmptySuggestion 400.
- *   - no base → a `full-file` proposal; the server REQUIRES a `baseContentHash`,
- *     so we fingerprint the proposed content (a "here is my whole file" proposal
- *     with no base to diff against).
- * An empty / whitespace-only note is dropped (kept absent, not blank).
- */
-export declare function buildSuggestionCreateBody(input: {
-    proposedContent: string;
-    baseContent?: string;
-    note?: string;
-}): SuggestionCreateBody;
-/**
- * Map an hq-pro skill route error to a single user-facing line. Pure so the
- * status → copy mapping is unit-tested independently of the network. Prefers the
- * server's own `error` / `message` (they carry the actionable specifics — e.g.
- * "Skill not found", "You need write access to this skill…").
- */
-export declare function mapSkillError(status: number, body: Record<string, unknown>): string;
-/** LIST inbox row shape returned by `suggestionToWire` on the server. */
-export interface SuggestionRow {
-    suggestionId: string;
-    skillUid: string;
-    authorPersonUid: string;
-    status: string;
-    baseChanged: boolean;
-    presentation?: string;
-    unifiedDiff?: string;
-    fullContent?: string;
-    baseContentHash?: string;
-    currentContentHash?: string;
-    authorNote?: string;
-    createdAt: string;
-    path: string;
+interface SkillSyncResult {
+    filesUploaded: number;
+    filesSkipped: number;
+    aborted: boolean;
 }
-/**
- * Render the review inbox as a table (one row per suggestion), optionally
- * printing each suggestion's unified diff (or full proposed file, when the base
- * drifted / the proposal is full-file) beneath its row. Pure → snapshot-testable.
- */
-export declare function formatSuggestionsList(suggestions: SuggestionRow[], opts?: {
-    showDiff?: boolean;
-}): string;
-/** Read `.hq/config.json`'s `activeCompany` (mirrors signals/sources). */
+export declare function parseSkillUid(markdown: string): string | undefined;
 export declare function readActiveCompanySlug(hqRoot: string): string | undefined;
-/**
- * The skill routes are keyed on the company SLUG. Precedence: explicit
- * `--company` → `.hq/config.json` activeCompany. Throws with actionable copy
- * when neither is available.
- */
 export declare function resolveCompanySlug(flag: string | undefined, hqRoot?: string): string;
-export interface ResolvedSkillTarget {
-    /** Absolute path to the SKILL.md. */
-    filePath: string;
-    /** The `skl_…` uid read from its frontmatter (or the uid arg). */
-    skillUid: string;
-    /** The working-tree SKILL.md content — the proposed content. */
-    content: string;
+/** Resolve a UID directly, or read the immutable UID from a local SKILL.md. */
+export declare function resolveSkillUid(target: string, cwd: string): string;
+export declare function canonicalCompanySkillPath(hqRoot: string, companySlug: string, skillSlug: string): string;
+export declare function makeSkillTemplate(input: {
+    slug: string;
+    name?: string;
+    description?: string;
+}): string;
+/** Replace SKILL.md without exposing a partially-written identity to agents. */
+export declare function writeSkillFileAtomically(filePath: string, content: string): void;
+export declare function mapSkillError(status: number, body: Record<string, unknown>): string;
+interface SkillCommandDeps {
+    ensureToken?: typeof ensureCognitoToken;
+    apiFetch?: typeof vaultApiFetch;
+    cwd?: () => string;
+    hqRoot?: string;
+    syncFile?: (input: SkillSyncInput) => Promise<SkillSyncResult>;
+    reindexFn?: (input: {
+        repoRoot: string;
+    }) => {
+        status: number | null;
+    };
 }
-/**
- * Recursively find a SKILL.md whose frontmatter `skill_uid` equals `uid`,
- * searching each root breadth-first with a bounded depth (skips VCS / build /
- * dependency dirs). Returns the first match's absolute path, or null.
- */
-export declare function findSkillFileByUid(roots: string[], uid: string, maxDepth?: number): string | null;
-/**
- * Resolve a `suggest` target (a `skl_…` uid OR a filesystem path) to the local
- * SKILL.md, its uid, and its content. A uid is resolved by scanning the company
- * skills dir and the cwd; a path is read directly (a directory → its SKILL.md),
- * with the uid read from the file's frontmatter.
- */
-export declare function resolveSkillTarget(target: string, deps: {
-    cwd: string;
-    hqRoot: string;
-    companySlug: string;
-}): ResolvedSkillTarget;
-/**
- * Read the committed (HEAD) version of a file from its git repo — the diff base
- * for "propose my working changes". Returns null when the file is untracked, not
- * in a repo, or git is unavailable (the caller then falls back to full-file, or
- * errors under `--diff`). Never throws.
- */
-export declare function readGitBase(filePath: string): Promise<string | null>;
-/** Injectable git-base seam so `suggest` is testable without a real repo. */
-export type GitBaseReader = (filePath: string) => Promise<string | null>;
-export declare function registerSkillCommand(program: Command, deps?: {
-    gitBase?: GitBaseReader;
-}): Command;
+export declare function registerSkillCommand(program: Command, deps?: SkillCommandDeps): Command;
+export {};
 //# sourceMappingURL=skill.d.ts.map