@indigoai-us/hq-cli 5.103.22 → 5.103.24

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.103.24] — 2026-08-27
+
+## [5.103.23] — 2026-08-26
+
+### Changed
+
+- The bundled sync engine now requires `@indigoai-us/hq-cloud` 6.15.71, so new
+  company skills are registered and stamped with a stable skill UID before
+  their first upload while comment-only skill proposals remain available from
+  the CLI.
+
 ## [5.103.22] — 2026-08-25
 
 ### Fixed

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

package/dist/commands/skill.js

@@ -1,226 +1,67 @@
 /**
- * `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 * as fs from "node:fs";
 import * as path from "node:path";
-import { createHash } from "node:crypto";
 import chalk from "chalk";
 import yaml from "js-yaml";
-import simpleGit from "simple-git";
-import { ensureCognitoToken, DEFAULT_HQ_ROOT } from "../utils/cognito-session.js";
+import { reindex, share } from "@indigoai-us/hq-cloud";
+import { ensureCognitoToken, DEFAULT_HQ_ROOT, buildVaultConfig, } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
-// ---------------------------------------------------------------------------
-// Patterns
-// ---------------------------------------------------------------------------
-/**
- * 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.
- */
 export const SKILL_UID_PATTERN = /^skl_[A-Za-z0-9]+$/;
-/** A `sgn_…` suggestion id — the `review` target and the LIST row key. */
-export const SUGGESTION_ID_PATTERN = /^sgn_[A-Za-z0-9]+$/;
-const VALID_LIST_STATUSES = ["open", "accepted", "declined", "all"];
-// ---------------------------------------------------------------------------
-// Pure helpers (exported for unit tests)
-// ---------------------------------------------------------------------------
+export const SKILL_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const COMPANY_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-/**
- * 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 function parseSkillUid(md) {
-    const match = md.match(FRONTMATTER_RE);
+async function defaultSyncFile(input) {
+    const result = await share({
+        paths: [input.filePath],
+        company: input.companySlug,
+        hqRoot: input.hqRoot,
+        vaultConfig: buildVaultConfig(input.token),
+        onConflict: "abort",
+    });
+    return {
+        filesUploaded: result.filesUploaded,
+        filesSkipped: result.filesSkipped,
+        aborted: result.aborted,
+    };
+}
+export function parseSkillUid(markdown) {
+    const match = markdown.match(FRONTMATTER_RE);
     if (!match)
         return undefined;
-    let doc;
     try {
-        doc = yaml.load(match[1]);
+        const doc = yaml.load(match[1]);
+        if (!doc || typeof doc !== "object" || Array.isArray(doc))
+            return undefined;
+        const uid = doc.skill_uid;
+        return typeof uid === "string" && SKILL_UID_PATTERN.test(uid) ? uid : undefined;
     }
     catch {
         return undefined;
     }
-    if (!doc || typeof doc !== "object" || Array.isArray(doc))
-        return undefined;
-    const uid = doc.skill_uid;
-    return typeof uid === "string" && SKILL_UID_PATTERN.test(uid) ? uid : undefined;
-}
-/** sha256 hex of a string — the base-version fingerprint the server records (AC2). */
-export function sha256Hex(content) {
-    return createHash("sha256").update(content, "utf8").digest("hex");
-}
-/**
- * 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 function buildSuggestionCreateBody(input) {
-    const body = { proposedContent: input.proposedContent };
-    if (input.baseContent !== undefined) {
-        if (input.baseContent === input.proposedContent) {
-            throw new Error("No changes to propose — the working SKILL.md matches its base.");
-        }
-        body.baseContent = input.baseContent;
-    }
-    else {
-        body.baseContentHash = sha256Hex(input.proposedContent);
-    }
-    const note = input.note?.trim();
-    if (note)
-        body.authorNote = note;
-    return body;
-}
-/**
- * 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 function mapSkillError(status, body) {
-    const server = (typeof body.error === "string" && body.error) ||
-        (typeof body.message === "string" && body.message) ||
-        "";
-    if (status === 401)
-        return "Not authenticated — please run `hq login`";
-    if (status === 403)
-        return server || "Not authorized";
-    if (status === 404)
-        return server || "Not found";
-    if (status === 409)
-        return server || "Conflict — please retry";
-    if (status === 422)
-        return server || "Company vault not provisioned";
-    if (status >= 500)
-        return `Server error: ${server || status}`;
-    return server || `Request failed (${status})`;
-}
-function shortDate(iso) {
-    return typeof iso === "string" ? iso.slice(0, 10) : "";
-}
-/**
- * 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 function formatSuggestionsList(suggestions, opts = {}) {
-    if (suggestions.length === 0) {
-        return chalk.gray("No suggestions match — the review inbox is empty.");
-    }
-    const idW = Math.max(13, ...suggestions.map((s) => s.suggestionId.length));
-    const skillW = Math.max(8, ...suggestions.map((s) => s.skillUid.length));
-    const authW = Math.max(6, ...suggestions.map((s) => s.authorPersonUid.length));
-    const statusW = Math.max(6, ...suggestions.map((s) => s.status.length));
-    const lines = [];
-    lines.push(chalk.bold([
-        "SUGGESTION_ID".padEnd(idW),
-        "SKILL".padEnd(skillW),
-        "AUTHOR".padEnd(authW),
-        "STATUS".padEnd(statusW),
-        "BASE",
-        "CREATED",
-    ].join("  ")));
-    for (const s of suggestions) {
-        lines.push([
-            s.suggestionId.padEnd(idW),
-            s.skillUid.padEnd(skillW),
-            s.authorPersonUid.padEnd(authW),
-            s.status.padEnd(statusW),
-            s.baseChanged ? chalk.yellow("changed") : "ok".padEnd(7),
-            shortDate(s.createdAt),
-        ].join("  "));
-        if (s.authorNote) {
-            lines.push(chalk.dim(`    note: ${s.authorNote}`));
-        }
-        if (opts.showDiff) {
-            const diff = s.presentation === "diff" && s.unifiedDiff
-                ? s.unifiedDiff
-                : (s.fullContent ?? "");
-            const label = s.presentation === "diff" && s.unifiedDiff
-                ? "diff"
-                : `full file${s.baseChanged ? " (base changed)" : ""}`;
-            lines.push(chalk.dim(`    ── ${label} ──`));
-            for (const dl of diff.split("\n")) {
-                lines.push(colorizeDiffLine(`    ${dl}`));
-            }
-        }
-    }
-    return lines.join("\n");
 }
-/** Colour a unified-diff line (green add / red del / dim header). Pure. */
-function colorizeDiffLine(line) {
-    const trimmed = line.trimStart();
-    if (trimmed.startsWith("+"))
-        return chalk.green(line);
-    if (trimmed.startsWith("-"))
-        return chalk.red(line);
-    if (trimmed.startsWith("@@"))
-        return chalk.cyan(line);
-    return chalk.dim(line);
-}
-// ---------------------------------------------------------------------------
-// Company slug + local skill resolution
-// ---------------------------------------------------------------------------
-/** Read `.hq/config.json`'s `activeCompany` (mirrors signals/sources). */
 export function readActiveCompanySlug(hqRoot) {
     const configPath = path.join(hqRoot, ".hq", "config.json");
     if (!fs.existsSync(configPath))
         return undefined;
     try {
-        const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        return typeof cfg.activeCompany === "string" && cfg.activeCompany.length > 0
-            ? cfg.activeCompany
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        return typeof config.activeCompany === "string" && config.activeCompany.length > 0
+            ? config.activeCompany
             : undefined;
     }
     catch {
         return 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 function resolveCompanySlug(flag, hqRoot = DEFAULT_HQ_ROOT) {
     const slug = flag ?? readActiveCompanySlug(hqRoot);
     if (!slug) {
@@ -228,362 +69,214 @@ export function resolveCompanySlug(flag, hqRoot = DEFAULT_HQ_ROOT) {
     }
     return slug;
 }
-/**
- * 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 function findSkillFileByUid(roots, uid, maxDepth = 6) {
-    const SKIP = new Set([
-        "node_modules",
-        ".git",
-        "dist",
-        "build",
-        ".next",
-        "coverage",
-    ]);
-    const queue = [];
-    for (const r of roots) {
-        if (fs.existsSync(r))
-            queue.push({ dir: r, depth: 0 });
-    }
-    while (queue.length > 0) {
-        const { dir, depth } = queue.shift();
-        let entries;
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                if (depth < maxDepth && !SKIP.has(entry.name)) {
-                    queue.push({ dir: full, depth: depth + 1 });
-                }
-            }
-            else if (entry.isFile() && entry.name === "SKILL.md") {
-                let content;
-                try {
-                    content = fs.readFileSync(full, "utf-8");
-                }
-                catch {
-                    continue;
-                }
-                if (parseSkillUid(content) === uid)
-                    return full;
-            }
-        }
-    }
-    return 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 function resolveSkillTarget(target, deps) {
-    if (SKILL_UID_PATTERN.test(target)) {
-        const roots = Array.from(new Set([
-            path.join(deps.hqRoot, "companies", deps.companySlug, "skills"),
-            deps.cwd,
-        ]));
-        const filePath = findSkillFileByUid(roots, target);
-        if (!filePath) {
-            throw new Error(`Could not find a local SKILL.md with skill_uid '${target}' under ${roots.join(", ")}. ` +
-                "Pass the path to the edited SKILL.md instead.");
-        }
-        return { filePath, skillUid: target, content: fs.readFileSync(filePath, "utf-8") };
-    }
-    // Filesystem path — accept either a SKILL.md file or a directory containing one.
-    let filePath = path.resolve(deps.cwd, target);
+/** Resolve a UID directly, or read the immutable UID from a local SKILL.md. */
+export function resolveSkillUid(target, cwd) {
+    if (SKILL_UID_PATTERN.test(target))
+        return target;
+    let filePath = path.resolve(cwd, target);
     if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
         filePath = path.join(filePath, "SKILL.md");
     }
     if (!fs.existsSync(filePath)) {
-        throw new Error(`No SKILL.md found at '${target}'. Pass the path to a SKILL.md (or its directory), or a skl_… uid.`);
+        throw new Error(`No SKILL.md found at '${target}'. Pass a SKILL.md path, its directory, or a skl_… uid.`);
     }
-    const content = fs.readFileSync(filePath, "utf-8");
-    const skillUid = parseSkillUid(content);
-    if (!skillUid) {
-        throw new Error(`The SKILL.md at '${filePath}' has no skill_uid in its frontmatter — it is not registered yet. ` +
-            "Sync / reindex the skill first so it has a stable identity, then suggest against it.");
+    const uid = parseSkillUid(fs.readFileSync(filePath, "utf8"));
+    if (!uid) {
+        throw new Error(`The SKILL.md at '${filePath}' has no registered skill_uid. Register and stamp it with 'hq skill create <slug> --company <company>', then retry.`);
     }
-    return { filePath, skillUid, content };
+    return uid;
 }
-/**
- * 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 async function readGitBase(filePath) {
-    try {
-        const git = simpleGit(path.dirname(filePath));
-        const top = (await git.revparse(["--show-toplevel"])).trim();
-        const rel = path.relative(top, filePath);
-        return await git.show([`HEAD:${rel}`]);
+export function canonicalCompanySkillPath(hqRoot, companySlug, skillSlug) {
+    if (!COMPANY_SLUG_PATTERN.test(companySlug)) {
+        throw new Error("Company slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
     }
-    catch {
-        return null;
+    if (!SKILL_SLUG_PATTERN.test(skillSlug)) {
+        throw new Error("Skill slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
     }
+    return path.join(hqRoot, "companies", companySlug, "skills", skillSlug, "SKILL.md");
 }
-// ---------------------------------------------------------------------------
-// Network helpers
-// ---------------------------------------------------------------------------
-async function readJsonBody(res) {
-    return (await res.json().catch(() => ({})));
+function displayNameFromSlug(slug) {
+    return slug
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join(" ");
 }
-/** Print the mapped error for a non-2xx response and exit(1). Returns never. */
-async function failFromResponse(res) {
-    const body = await readJsonBody(res);
-    console.error(chalk.red(mapSkillError(res.status, body)));
-    process.exit(1);
+export function makeSkillTemplate(input) {
+    const name = input.name?.trim() || displayNameFromSlug(input.slug);
+    const description = input.description?.trim() ?? "";
+    return [
+        "---",
+        `name: ${JSON.stringify(name)}`,
+        `description: ${JSON.stringify(description)}`,
+        "tags: []",
+        "---",
+        "",
+        `# ${name}`,
+        "",
+        "Describe when and how to use this skill.",
+        "",
+    ].join("\n");
 }
-function skillRoutePrefix(slug) {
-    return `/v1/files/skills/company/${encodeURIComponent(slug)}`;
+/** Replace SKILL.md without exposing a partially-written identity to agents. */
+export function writeSkillFileAtomically(filePath, content) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const existingMode = fs.existsSync(filePath)
+        ? fs.statSync(filePath).mode
+        : 0o644;
+    const tempPath = path.join(dir, `.SKILL.md.${process.pid}.${Date.now()}.tmp`);
+    try {
+        fs.writeFileSync(tempPath, content, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: existingMode,
+        });
+        fs.renameSync(tempPath, filePath);
+    }
+    finally {
+        if (fs.existsSync(tempPath))
+            fs.rmSync(tempPath, { force: true });
+    }
+}
+export function mapSkillError(status, body) {
+    const server = (typeof body.error === "string" && body.error) ||
+        (typeof body.message === "string" && body.message) ||
+        "";
+    if (status === 401)
+        return "Not authenticated — please run `hq login`";
+    if (status === 403)
+        return server || "Not authorized";
+    if (status === 404)
+        return server || "Skill not found";
+    if (status >= 500)
+        return `Server error: ${server || status}`;
+    return server || `Request failed (${status})`;
 }
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
 export function registerSkillCommand(program, deps = {}) {
-    const gitBase = deps.gitBase ?? readGitBase;
+    const ensureToken = deps.ensureToken ?? ensureCognitoToken;
+    const apiFetch = deps.apiFetch ?? vaultApiFetch;
+    const cwd = deps.cwd ?? process.cwd;
+    const hqRoot = deps.hqRoot ?? DEFAULT_HQ_ROOT;
+    const syncFile = deps.syncFile ?? defaultSyncFile;
+    const reindexFn = deps.reindexFn ?? reindex;
     const skill = program
         .command("skill")
-        .description("Propose, review, and merge skill changes from the terminal")
-        .option("--company <slug>", "Company slug (defaults to the active company)");
-    // ── suggest ────────────────────────────────────────────────────────────────
+        .description("Create company skills and discuss improvements")
+        .option("--company <slug>", "Company slug (defaults to the active company)")
+        .option("--hq-root <path>", "Local HQ root", hqRoot);
     skill
-        .command("suggest <target>")
-        .description("Create a suggestion from a local SKILL.md (a skl_… uid or a path). Never blocked by a skill lock — a suggestion is always a proposal.")
-        .option("--diff", "Require a diff base (git HEAD, or --base): fail if none is found. Default falls back to a full-file proposal.")
-        .option("--base <file>", "Explicit base file to diff the working SKILL.md against")
-        .option("--note <text>", "Author note — the rationale / failure context attached to the suggestion")
-        .action(async (target, opts) => {
-        try {
-            const companySlug = resolveCompanySlug(skill.opts().company);
-            const resolved = resolveSkillTarget(target, {
-                cwd: process.cwd(),
-                hqRoot: DEFAULT_HQ_ROOT,
-                companySlug,
-            });
-            // Base resolution: explicit --base wins; otherwise diff against git
-            // HEAD when the file is tracked. No base + --diff → hard error; no
-            // base without --diff → a full-file proposal.
-            let baseContent;
-            let baseSource = "";
-            if (opts.base !== undefined) {
-                const basePath = path.resolve(process.cwd(), opts.base);
-                if (!fs.existsSync(basePath)) {
-                    console.error(chalk.red(`Base file not found: ${opts.base}`));
-                    process.exit(1);
-                }
-                baseContent = fs.readFileSync(basePath, "utf-8");
-                baseSource = opts.base;
-            }
-            else {
-                const fromGit = await gitBase(resolved.filePath);
-                if (fromGit !== null) {
-                    baseContent = fromGit;
-                    baseSource = "git HEAD";
-                }
-            }
-            if (baseContent === undefined && opts.diff) {
-                console.error(chalk.red(`--diff needs a base, but none was found for ${resolved.filePath}. ` +
-                    "Pass --base <file>, or commit a base version first."));
-                process.exit(1);
-            }
-            if (baseContent !== undefined && baseContent === resolved.content) {
-                console.error(chalk.red(`No changes to propose — the working SKILL.md matches its base (${baseSource}).`));
-                process.exit(1);
-            }
-            const body = buildSuggestionCreateBody({
-                proposedContent: resolved.content,
-                baseContent,
-                note: opts.note,
-            });
-            const token = await ensureCognitoToken();
-            const res = await vaultApiFetch({
-                token,
-                path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(resolved.skillUid)}/suggestions`,
-                method: "POST",
-                body: body,
+        .command("create <slug>")
+        .description("Register, stamp, reindex, and sync a company skill")
+        .option("--name <name>", "Display name when creating a new template")
+        .option("--description <text>", "Description when creating a new template")
+        .option("--no-sync", "Register locally without uploading the stamped file")
+        .action(async (slug, opts) => {
+        if (!SKILL_SLUG_PATTERN.test(slug)) {
+            throw new Error("Skill slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
+        }
+        const parentOpts = skill.opts();
+        const resolvedRoot = path.resolve(parentOpts.hqRoot ?? hqRoot);
+        const companySlug = resolveCompanySlug(parentOpts.company, resolvedRoot);
+        const filePath = canonicalCompanySkillPath(resolvedRoot, companySlug, slug);
+        if (fs.existsSync(filePath) && !fs.statSync(filePath).isFile()) {
+            throw new Error(`Expected a SKILL.md file at '${filePath}'.`);
+        }
+        const localContent = fs.existsSync(filePath)
+            ? fs.readFileSync(filePath, "utf8")
+            : makeSkillTemplate({
+                slug,
+                ...(opts.name !== undefined ? { name: opts.name } : {}),
+                ...(opts.description !== undefined
+                    ? { description: opts.description }
+                    : {}),
             });
-            if (!res.ok)
-                await failFromResponse(res);
-            const data = (await res.json());
-            console.log(chalk.green(`Suggestion created: ${data.suggestionId}`));
-            console.log(`  Skill:   ${data.skillUid}`);
-            console.log(`  Status:  ${data.status}`);
-            // AC4 — attribution is server-derived from the invoking identity.
-            console.log(`  Author:  ${data.authorPersonUid}`);
-            console.log(`  Change:  ${data.payloadFormat === "diff" ? `diff vs ${baseSource || "base"}` : "full file"}`);
-            if (data.authorNote)
-                console.log(`  Note:    ${data.authorNote}`);
-            console.log(chalk.dim(`  The skill owner can review it: hq skill review ${data.suggestionId} --accept|--decline`));
+        const token = await ensureToken();
+        const response = await apiFetch({
+            token,
+            path: `/v1/files/skills/company/${encodeURIComponent(companySlug)}/register`,
+            method: "POST",
+            body: {
+                path: `skills/${slug}/SKILL.md`,
+                content: localContent,
+            },
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            throw new Error(mapSkillError(response.status, body));
         }
-        catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-            process.exit(1);
+        const registered = (await response.json());
+        if (typeof registered.skillUid !== "string" ||
+            !SKILL_UID_PATTERN.test(registered.skillUid) ||
+            typeof registered.content !== "string" ||
+            parseSkillUid(registered.content) !== registered.skillUid) {
+            throw new Error("The server returned an invalid skill registration response; the local file was not changed.");
         }
-    });
-    // ── list-suggestions ─────────────────────────────────────────────────────────
-    skill
-        .command("list-suggestions")
-        .description("List the review inbox — open suggestions on skills you own (or one skill via --skill)")
-        .option("--skill <skillUid>", "Scope to one skill (skl_…); requires write access on it")
-        .option("--status <status>", "open | accepted | declined | all (default: open)")
-        .option("--show-diff", "Print each suggestion's unified diff / proposed file")
-        .option("--json", "Emit raw JSON instead of a table")
-        .action(async (opts) => {
+        writeSkillFileAtomically(filePath, registered.content);
+        let reindexStatus = null;
         try {
-            const companySlug = resolveCompanySlug(skill.opts().company);
-            const status = (opts.status ?? "open");
-            if (!VALID_LIST_STATUSES.includes(status)) {
-                console.error(chalk.red(`Invalid --status '${opts.status}': must be one of ${VALID_LIST_STATUSES.join(", ")}`));
-                process.exit(1);
-            }
-            if (opts.skill !== undefined && !SKILL_UID_PATTERN.test(opts.skill)) {
-                console.error(chalk.red(`Invalid --skill '${opts.skill}': must be a skl_… uid`));
-                process.exit(1);
-            }
-            const body = { status };
-            if (opts.skill !== undefined)
-                body.skillUid = opts.skill;
-            const token = await ensureCognitoToken();
-            const res = await vaultApiFetch({
-                token,
-                path: `${skillRoutePrefix(companySlug)}/suggestions/list`,
-                method: "POST",
-                body,
-            });
-            if (!res.ok)
-                await failFromResponse(res);
-            const data = (await res.json());
-            if (opts.json) {
-                console.log(JSON.stringify(data, null, 2));
-                return;
-            }
-            console.log(formatSuggestionsList(data.suggestions, { showDiff: opts.showDiff }));
+            reindexStatus = reindexFn({ repoRoot: resolvedRoot }).status;
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-            process.exit(1);
+            console.warn(chalk.yellow(`⚠ Skill registered, but HQ reindex failed: ${err instanceof Error ? err.message : String(err)}`));
         }
-    });
-    // ── review ─────────────────────────────────────────────────────────────────
-    skill
-        .command("review <suggestionId>")
-        .description("Accept (merge) or decline a pending suggestion")
-        .option("--accept", "Accept the suggestion — merges the proposed change into the skill")
-        .option("--decline", "Decline the suggestion — leaves the skill unchanged")
-        .option("--reason <text>", "Reason recorded on a decline")
-        .option("--skill <skillUid>", "Scope the lookup to one skill (skl_…)")
-        .option("--acknowledge-base-changed", "On accept: overwrite with the full proposed file even if the skill changed since the suggestion")
-        .action(async (suggestionId, opts) => {
-        try {
-            if (!SUGGESTION_ID_PATTERN.test(suggestionId)) {
-                console.error(chalk.red(`Invalid suggestion id '${suggestionId}': must be a sgn_… id`));
-                process.exit(1);
-            }
-            const accept = opts.accept === true;
-            const decline = opts.decline === true;
-            if (accept === decline) {
-                console.error(chalk.red("Pass exactly one of --accept or --decline."));
-                process.exit(1);
-            }
-            if (opts.skill !== undefined && !SKILL_UID_PATTERN.test(opts.skill)) {
-                console.error(chalk.red(`Invalid --skill '${opts.skill}': must be a skl_… uid`));
-                process.exit(1);
-            }
-            const companySlug = resolveCompanySlug(skill.opts().company);
-            const token = await ensureCognitoToken();
-            // Resolve the suggestion's skillUid + live path from the SAME LIST route
-            // the console uses — accept/decline are path↔uid guarded, so the path
-            // must come from the authoritative row, never guessed. `all` so an
-            // already-resolved suggestion yields a precise "already <status>" error.
-            const listBody = { status: "all" };
-            if (opts.skill !== undefined)
-                listBody.skillUid = opts.skill;
-            const listRes = await vaultApiFetch({
-                token,
-                path: `${skillRoutePrefix(companySlug)}/suggestions/list`,
-                method: "POST",
-                body: listBody,
-            });
-            if (!listRes.ok)
-                await failFromResponse(listRes);
-            const { suggestions } = (await listRes.json());
-            const row = suggestions.find((s) => s.suggestionId === suggestionId);
-            if (!row) {
-                console.error(chalk.red(`Suggestion ${suggestionId} is not in your review inbox. ` +
-                    "If it targets a skill you don't own, scope the lookup with --skill <skl_…>."));
-                process.exit(1);
-            }
-            if (row.status !== "open") {
-                console.error(chalk.yellow(`Suggestion ${suggestionId} is already ${row.status} — nothing to do.`));
-                process.exit(1);
-            }
-            if (accept) {
-                if (!row.path) {
-                    console.error(chalk.red("Could not resolve the live skill path for this suggestion — the skill may have been removed."));
-                    process.exit(1);
-                }
-                const acceptBody = { path: row.path };
-                if (opts.acknowledgeBaseChanged)
-                    acceptBody.acknowledgeBaseChanged = true;
-                const res = await vaultApiFetch({
+        if (reindexStatus !== null && reindexStatus !== 0) {
+            console.warn(chalk.yellow(`⚠ Skill registered, but HQ reindex exited ${reindexStatus}. Run 'hq reindex --repo-root ${resolvedRoot}' to retry discovery.`));
+        }
+        if (opts.sync !== false) {
+            let syncResult;
+            try {
+                syncResult = await syncFile({
+                    filePath,
+                    companySlug,
+                    hqRoot: resolvedRoot,
                     token,
-                    path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(row.skillUid)}/suggestions/${encodeURIComponent(suggestionId)}/accept`,
-                    method: "POST",
-                    body: acceptBody,
                 });
-                if (!res.ok) {
-                    const errBody = await readJsonBody(res);
-                    // AC4 (US-009): the base drifted — guide the operator to re-run
-                    // with acknowledgement rather than silently overwriting.
-                    if (res.status === 409 &&
-                        errBody.code === "WRITE_SKILL_SUGGESTION_BASE_CHANGED") {
-                        console.error(chalk.yellow("The skill changed since this suggestion was written. Re-run with " +
-                            "--acknowledge-base-changed to overwrite it with the full proposed file."));
-                        process.exit(1);
-                    }
-                    console.error(chalk.red(mapSkillError(res.status, errBody)));
-                    process.exit(1);
-                }
-                const data = (await res.json());
-                console.log(chalk.green("Suggestion accepted — merged and closed."));
-                console.log(`  Skill:       ${data.skillUid}`);
-                console.log(`  Suggestion:  ${data.suggestionId}`);
-                console.log(`  Accepted by: ${data.acceptedBy}`);
-                return;
             }
-            // Decline.
-            const declineBody = {};
-            if (opts.reason !== undefined)
-                declineBody.reason = opts.reason;
-            const res = await vaultApiFetch({
-                token,
-                path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(row.skillUid)}/suggestions/${encodeURIComponent(suggestionId)}/decline`,
-                method: "POST",
-                body: declineBody,
-            });
-            if (!res.ok)
-                await failFromResponse(res);
-            const data = (await res.json());
-            console.log(chalk.green("Suggestion declined — the skill was left unchanged."));
-            console.log(`  Skill:       ${data.skillUid}`);
-            console.log(`  Suggestion:  ${data.suggestionId}`);
-            console.log(`  Declined by: ${data.declinedBy}`);
-            if (data.reason)
-                console.log(`  Reason:      ${data.reason}`);
+            catch (err) {
+                throw new Error(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (syncResult.aborted) {
+                throw new Error(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync aborted because the remote file conflicts.`);
+            }
         }
-        catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-            process.exit(1);
+        console.log(chalk.green(`Skill ready: ${registered.skillUid}`));
+        console.log(`  File:     ${filePath}`);
+        console.log(`  Discovery: ${reindexStatus === 0 ? "reindexed" : "reindex needs attention"}`);
+        console.log(registered.accessPolicy === "open"
+            ? `  Access:   Open — every active ${companySlug} member can edit`
+            : "  Access:   preserved existing policy");
+        console.log(`  Sync:     ${opts.sync === false ? "not requested" : "complete"}`);
+    });
+    skill
+        .command("propose <target>")
+        .description("Post a comment-only improvement for a skill")
+        .requiredOption("-m, --message <text>", "The improvement to discuss")
+        .action(async (target, opts) => {
+        const message = opts.message.trim();
+        if (!message)
+            throw new Error("An improvement message is required.");
+        const parentOpts = skill.opts();
+        const resolvedRoot = path.resolve(parentOpts.hqRoot ?? hqRoot);
+        const companySlug = resolveCompanySlug(parentOpts.company, resolvedRoot);
+        const skillUid = resolveSkillUid(target, cwd());
+        const token = await ensureToken();
+        const response = await apiFetch({
+            token,
+            path: `/v1/files/skills/company/${encodeURIComponent(companySlug)}/${encodeURIComponent(skillUid)}/comments`,
+            method: "POST",
+            body: { anchor: { kind: "whole-skill" }, body: message },
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            throw new Error(mapSkillError(response.status, body));
         }
+        const posted = (await response.json());
+        console.log(chalk.green(`Improvement posted: ${posted.commentId}`));
+        console.log(`  Skill:    ${posted.skillUid}`);
+        console.log(`  Author:   ${posted.authorPersonUid}`);
+        console.log(`  Message:  ${posted.body}`);
+        console.log(chalk.dim("  Review it in HQ Console → Skills → Improvements"));
     });
     return skill;
 }

package/dist/main.js

@@ -72,6 +72,7 @@ import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import { isAuthError } from "./utils/auth-error.js";
+import { browserLoginAbandonedMessage } from "./utils/browser-login-abandoned.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { canOfferTeamUpgrade, formatPlanGateError, isPlanGateError, offerTeamUpgrade, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
@@ -206,9 +207,8 @@ registerGroupGrantsCommand(program);
 // browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
 const filesCmd = registerFilesCommand(program);
 registerFilesBrowseCommands(filesCmd);
-// Skill collaboration loop (subcommand group — hq skill suggest|list-suggestions|review).
-// A thin terminal front-end over the SAME wired hq-pro skill suggestion + merge
-// routes the MCP (US-007) and console merge (US-009) surfaces use — no forked logic.
+// Comment-only skill improvement loop. Structured suggestion/review commands are
+// intentionally absent; live content changes remain governed by FILE_ACL sync.
 registerSkillCommand(program);
 // Membership management (subcommand group — hq members invite|list|revoke)
 registerMembersCommand(program);
@@ -395,6 +395,21 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.stderr.write(`hq: ${err.message}\n`);
         deps.setExitCode(1);
     }
+    else if (browserLoginAbandonedMessage(err)) {
+        // HQ-CLI-V: the caller triggered the implicit browser sign-in fallback
+        // (an expiring/absent HQ session) and then never completed it —
+        // @indigoai-us/hq-cloud's browserLogin rejected either at its 15-minute
+        // deadline or because the user declined at the IdP (access_denied). A
+        // human walking away from an OAuth prompt is expected auth state the user
+        // fixes with `hq login`, not an hq-cli defect. Print the fixed actionable
+        // remedy and skip Sentry so one abandoned login doesn't file a permanent
+        // high-priority "crash". Placed with the auth carve-out (both mean "your
+        // HQ session isn't usable; run hq login"); every genuine browser-login or
+        // token-exchange fault stays outside the closed allowlist and still
+        // captures below.
+        deps.stderr.write(`hq: ${browserLoginAbandonedMessage(err)}\n`);
+        deps.setExitCode(1);
+    }
     else if (isPlanGateError(err)) {
         // hq-pro's plan denials are expected product limits, never a CLI crash.
         // The shared vault client has already decoded and typed the small safe

package/dist/utils/browser-login-abandoned.d.ts

@@ -0,0 +1,12 @@
+/**
+ * If `err` is an abandoned implicit browser sign-in, return a short, fixed
+ * user-facing remedy; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — a user who walked away from an OAuth prompt is not an hq-cli defect.
+ * A null result means "handle as usual (capture to Sentry)". CognitoRefreshError
+ * is a refresh fault, never an abandonment, so it is excluded structurally even
+ * though it extends CognitoAuthError.
+ */
+export declare function browserLoginAbandonedMessage(err: unknown): string | null;
+//# sourceMappingURL=browser-login-abandoned.d.ts.map

package/dist/utils/browser-login-abandoned.js

@@ -0,0 +1,70 @@
+// src/utils/browser-login-abandoned.ts
+//
+// Classify an ABANDONED implicit browser sign-in — the caller triggered the
+// fallback OAuth flow (an expiring/absent HQ session on any of the ~100
+// ensureCognitoToken/ensureCognitoIdToken call sites) and then never completed
+// it. @indigoai-us/hq-cloud's browserLogin arms a 15-minute deadline and also
+// rejects when the identity provider reports the user declined; both mint a
+// bare CognitoAuthError. A human walking away from an OAuth prompt is expected
+// auth state the user fixes with `hq login`, NOT an hq-cli defect — so the
+// top-level handler prints an actionable line and exits non-zero but SKIPS
+// Sentry capture, mirroring the auth (HQ-CLI-8), company-selection (HQ-CLI-7),
+// expected-user-error (HQ-CLI-6), and environmental-FS (HQ-CLI-2) carve-outs.
+//
+// HQ-CLI-V (Sentry indigo-d0/hq-cli 7685055900): `hq integrations list
+// --company <slug> --json` tried to refresh an expiring session, the refresh
+// 400'd (invalid_grant), and it fell back to browserLogin(). Nobody finished
+// the sign-in, so exactly 15 minutes later browserLogin rejected with
+// `CognitoAuthError("Login timed out after 15 minutes")`. That error carries no
+// `code`, no `expected` flag, and is not an AuthError/CompanySelectionError/…,
+// so every predicate in handleTopLevelError returned false and the abandoned
+// login was captured as a high-priority, unfixable "crash".
+//
+// The allowlist is CLOSED at the two upstream-minted human-abandonment
+// signatures and defaults to null (capture). Every other CognitoAuthError — a
+// state-parameter mismatch (possible CSRF), a missing callback code, a
+// non-access_denied IdP error, a token-exchange failure — and every
+// CognitoRefreshError (a refresh fault, not an abandonment) still reaches
+// Sentry.
+import { CognitoAuthError, CognitoRefreshError } from "@indigoai-us/hq-cloud";
+/**
+ * Fixed, actionable remedy. Deliberately interpolates NO upstream error text,
+ * so this carve-out can never widen disclosure and needs no redaction pass.
+ */
+const BROWSER_LOGIN_ABANDONED_MESSAGE = "Browser sign-in was not completed. Run `hq login`, finish the sign-in in " +
+    "your browser, then re-run your command.";
+/**
+ * The 15-minute login-deadline signature (@indigoai-us/hq-cloud cognito-auth
+ * `waitForAuthCode`). The minute count is tolerated (`\d+`) so an upstream
+ * retune of the deadline turns the contract test red rather than silently
+ * restoring the Sentry noise.
+ */
+const LOGIN_TIMED_OUT = /^Login timed out after \d+ minutes?$/;
+/**
+ * The user declined at the identity provider. Matched EXACTLY — other
+ * `Cognito returned error: <x>` values (server_error, …) are not abandonment
+ * and stay reportable.
+ */
+const ACCESS_DENIED = "Cognito returned error: access_denied";
+/**
+ * If `err` is an abandoned implicit browser sign-in, return a short, fixed
+ * user-facing remedy; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — a user who walked away from an OAuth prompt is not an hq-cli defect.
+ * A null result means "handle as usual (capture to Sentry)". CognitoRefreshError
+ * is a refresh fault, never an abandonment, so it is excluded structurally even
+ * though it extends CognitoAuthError.
+ */
+export function browserLoginAbandonedMessage(err) {
+    if (!(err instanceof CognitoAuthError))
+        return null;
+    if (err instanceof CognitoRefreshError)
+        return null;
+    const { message } = err;
+    if (LOGIN_TIMED_OUT.test(message) || message === ACCESS_DENIED) {
+        return BROWSER_LOGIN_ABANDONED_MESSAGE;
+    }
+    return null;
+}
+//# sourceMappingURL=browser-login-abandoned.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.103.22",
+  "version": "5.103.24",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.15.37",
+    "@indigoai-us/hq-cloud": "~6.15.71",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",