@indigoai-us/hq-cli 5.115.1 → 5.115.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.115.2] — 2026-09-15
+
+### Fixed
+
+- Search indexing no longer starts a second embedding rebuild when one is
+  already running. Two rebuilds could use much of a machine while writing to
+  the same local index, so hq now skips the duplicate and lets a later pass
+  finish any remaining work.
+- Creating a company from the command line (`hq onboard create-company`), and from a bot's conversation, works again; it had been refused with "ownerUid must match the authenticated caller". A company you already created but never finished setting up is now picked up and completed instead of being refused as "already taken".
+
 ## [5.115.1] — 2026-09-15
 
 ### Fixed

package/assets/scaffold/core/scripts/qmd-reindex-after-sync.sh

@@ -1,93 +1,16 @@
 #!/usr/bin/env bash
-# qmd-reindex-after-sync.sh — incremental qmd reindex after an HQ sync.
+# FORWARDER — the implementation of this script lives in the hq CLI.
 #
-# Why this exists: the qmd index is a per-machine local SQLite store derived
-# from local folder paths. Nothing re-indexed it after `hq-sync` pulled new
-# files in, so search results diverged between teammates depending on who ran
-# `qmd update` most recently. This script makes post-sync indexing automatic
-# and deterministic, so every machine's personal index converges to the same
-# content. The index itself stays personal (it is large, binary, and embeds
-# absolute local paths); only the *freshness* is made automatic.
-#
-# Behavior:
-#   1. Auto-registers any company knowledge dir that isn't yet a qmd
-#      collection (fixes the "newly-synced knowledge isn't searchable until I
-#      manually map it" gap).
-#   2. Runs an incremental lexical reindex (`qmd update` — fast, skips
-#      unchanged files by mtime).
-#   3. Rebuilds embeddings only when called with --embed (slow on a
-#      multi-GB index; meant for an idle/interval pass, not every sync).
-#
-# Idempotent and safe: no-op (exit 0) when qmd is absent or the path isn't an
-# HQ root. Never blocks or fails a sync.
-#
-# Usage: qmd-reindex-after-sync.sh [hq_root] [--embed]
-#   hq_root  Local HQ directory (default: $PWD). Must contain core/core.yaml.
-#   --embed  Also rebuild embeddings (deferred-cost; omit for fast lexical-only).
-
-set -uo pipefail
-
-hq_root=""
-embed=0
-for arg in "$@"; do
-  case "$arg" in
-    --embed) embed=1 ;;
-    --*)     : ;;                       # ignore unknown flags
-    *)       [ -z "$hq_root" ] && hq_root="$arg" ;;
-  esac
-done
-[ -z "$hq_root" ] && hq_root="$PWD"
-
-command -v qmd >/dev/null 2>&1 || exit 0
-[ -f "$hq_root/core/core.yaml" ] || exit 0
-
-cd "$hq_root" || exit 0
-
-# 1. Auto-register company knowledge collections that don't exist yet.
-#    Convention matches /newcompany: --name <slug> --mask "**/*.md".
-existing="$(qmd collection list 2>/dev/null || true)"
-for kdir in companies/*/knowledge; do
-  [ -d "$kdir" ] || continue
-  [ -n "$(find "$kdir" -name '*.md' -not -name 'INDEX.md' -print -quit 2>/dev/null)" ] || continue
-  slug="$(basename "$(dirname "$kdir")")"
-  printf '%s\n' "$existing" | grep -Fq "qmd://$slug/" && continue
-  qmd collection add "$hq_root/$kdir" --name "$slug" --mask "**/*.md" >/dev/null 2>&1 || true
-  qmd context add "qmd://$slug" "Knowledge base for $slug." >/dev/null 2>&1 || true
-done
-
-# 1b. Auto-register company *projects* collections that don't exist yet.
-#    Convention matches the HQ-level `hq-projects` collection: --name <slug>-projects
-#    --mask "**/*.{md,json}" (so prd.json + project docs are searchable). Without
-#    this, company projects/ dirs are indexed by nothing and /startwork's global
-#    `qmd search "prd.json"` and /brainstorm's project discovery silently miss them.
-for pdir in companies/*/projects; do
-  [ -d "$pdir" ] || continue
-  [ -n "$(find "$pdir" -type f \( -name '*.md' -o -name '*.json' \) -print -quit 2>/dev/null)" ] || continue
-  slug="$(basename "$(dirname "$pdir")")"
-  name="${slug}-projects"
-  printf '%s\n' "$existing" | grep -Fq "qmd://$name/" && continue
-  qmd collection add "$hq_root/$pdir" --name "$name" --mask "**/*.{md,json}" >/dev/null 2>&1 || true
-  qmd context add "qmd://$name" "Project PRDs and documentation for $slug." >/dev/null 2>&1 || true
-done
-
-# 1c. Auto-register the personal knowledge collection if it isn't one yet.
-#     personal/knowledge is now read DIRECTLY (the reindex symlink mirror into
-#     core/knowledge is retired), so it needs its own qmd collection to stay
-#     searchable rather than riding in under a core collection.
-if [ -d "personal/knowledge" ] && \
-   [ -n "$(find "personal/knowledge" -name '*.md' -not -name 'INDEX.md' -print -quit 2>/dev/null)" ]; then
-  printf '%s\n' "$existing" | grep -Fq "qmd://personal-knowledge/" || {
-    qmd collection add "$hq_root/personal/knowledge" --name "personal-knowledge" --mask "**/*.md" >/dev/null 2>&1 || true
-    qmd context add "qmd://personal-knowledge" "Personal knowledge base (owner overlay)." >/dev/null 2>&1 || true
-  }
-fi
+# This shipped compatibility path must delegate rather than invoke qmd itself:
+# `hq core qmd-reindex-after-sync` participates in hq-cli's shared embed lock.
+# Arguments, stdio, exit status, and signal disposition are preserved.
 
-# 2. Incremental lexical reindex (cheap; mtime-incremental inside qmd).
-qmd update >/dev/null 2>&1 || true
+set -euo pipefail
 
-# 3. Embeddings only on explicit request.
-if [ "$embed" -eq 1 ]; then
-  qmd embed >/dev/null 2>&1 || true
+if ! command -v hq >/dev/null 2>&1; then
+  echo "qmd-reindex-after-sync.sh: requires the hq CLI — this script's implementation now ships with it." >&2
+  echo "Install it with: npm install -g @indigoai-us/hq-cli" >&2
+  exit 127
 fi
 
-exit 0
+exec hq core qmd-reindex-after-sync "$@"

package/dist/commands/bot.js

@@ -800,7 +800,7 @@ async function runBotIntro(nameArg) {
     if (hasPromotionHold(dir))
         throw new Error("This bot is held for cloud promotion. Continue its promotion before changing local settings or lifecycle.");
     const api = new BotApi({ token: botTokenSupplier(dir) });
-    await api.sendDm({ toPersonUid: config.ownerUid, body: introDmText(name, config.runtime, config.intro) });
+    await api.sendDm({ toPersonUid: config.ownerUid, body: introDmText(name, config.runtime, config.intro, { kind: effectiveBotKind(config), companies: effectiveBotCompanies(config) }) });
     patchBotConfig(dir, { introSentAt: new Date().toISOString() });
     console.log(chalk.green(`${name} introduced itself to you.`));
 }

package/dist/commands/index-cmd.d.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { type RunQmdOptions, type SearchCollection, type QmdProcessResult } from '../lib/search-index/index.js';
 import { type BackgroundDependencies, type BackgroundResult, type BackgroundStatus } from '../lib/search-index/background.js';
+import { type EmbedLockDependencies } from '../lib/search-index/embed-lock.js';
 export type SearchIndexDependencies = {
     reconcileCollections: (hqRoot: string) => unknown;
     /** Apply the per-document size cap to qmd's config before the update reads anything. */
@@ -13,9 +14,15 @@ export type SearchIndexDependencies = {
     runBackgroundLauncher?: (dependencies: BackgroundDependencies) => BackgroundResult;
     runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult | Promise<BackgroundResult>;
     backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
+    /** Test seams for the lock shared by every hq-cli embed entry point. */
+    embedLockDependencies?: EmbedLockDependencies;
+    writeStderr?: (text: string) => void;
+};
+export type SyncSearchIndexResult = {
+    embedded: boolean;
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
-export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): void;
+export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): SyncSearchIndexResult;
 export declare function collectionStatusLines(expected: SearchCollection[], registered: ReadonlySet<string>): string[];
 export declare function collectionSummary(expected: SearchCollection[], registered: ReadonlySet<string>): string;
 export declare function registerIndexCommand(program: Command, dependencies?: SearchIndexDependencies): void;

package/dist/commands/index-cmd.js

@@ -1,6 +1,7 @@
 import { Option } from 'commander';
-import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
+import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdHome, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
 import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher, runBackgroundWorker, } from '../lib/search-index/background.js';
+import { defaultEmbedLockDependencies, runWithEmbedLock, } from '../lib/search-index/embed-lock.js';
 import { applyIndexSizeLimit } from '../lib/search-index/max-doc-bytes.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { QMD_NATIVE_BINDING_REMEDY, isQmdNativeBindingError, } from '../utils/qmd-native-binding-error.js';
@@ -35,8 +36,17 @@ export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
         /* capping is an optimisation; indexing is the job */
     }
     dependencies.runQmd(['update'], { cwd: hqRoot });
-    if (embed)
-        dependencies.runQmd(['embed'], { cwd: hqRoot });
+    if (!embed)
+        return { embedded: false };
+    const runEmbed = () => dependencies.runQmd(['embed'], { cwd: hqRoot });
+    const lockDependencies = dependencies.embedLockDependencies ?? defaultEmbedLockDependencies();
+    const outcome = runWithEmbedLock(resolveQmdHome(lockDependencies.env), lockDependencies, runEmbed);
+    const writeStderr = dependencies.writeStderr ?? ((text) => process.stderr.write(text));
+    if (outcome === 'busy')
+        writeStderr('hq: qmd embed is already running; skipping this pass.\n');
+    if (outcome === 'unavailable')
+        writeStderr('hq: cannot access the qmd embed lock; skipping this pass.\n');
+    return { embedded: outcome === 'ran' };
 }
 function resolveRoot(hqRoot) {
     return hqRoot ?? findHqRoot();
@@ -73,8 +83,8 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .option('--hq-root <path>', 'HQ root to index (defaults to auto-detected root)')
         .action((options) => {
         const hqRoot = resolveRoot(options.hqRoot);
-        syncSearchIndex(hqRoot, options.embed === true);
-        console.log(`Updated search index for ${hqRoot}${options.embed ? ' (including embeddings)' : ''}.`);
+        const result = syncSearchIndex(hqRoot, options.embed === true, dependencies);
+        console.log(`Updated search index for ${hqRoot}${result.embedded ? ' (including embeddings)' : ''}.`);
     });
     index
         .command('collections')

package/dist/commands/onboard-identity-guard.d.ts

@@ -24,7 +24,7 @@
  * the checkpoint adopted a person the caller no longer owns. The resume command
  * uses it to surface a recoverable, actionable error instead of looping.
  */
-import type { OnboardingCheckpoint } from "@indigoai-us/hq-onboarding";
+import type { OnboardingCheckpoint } from "../lib/onboarding/index.js";
 export type OnboardingIdentityCheck = {
     kind: "ok";
 } | {

package/dist/commands/onboard.js

@@ -19,7 +19,7 @@
  * browser-OAuth flow opens automatically.
  */
 import chalk from "chalk";
-import { runOnboardCli, readCheckpoint } from "@indigoai-us/hq-onboarding";
+import { runOnboardCli, readCheckpoint } from "../lib/onboarding/index.js";
 import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { createDefaultVaultClient } from "./cloud-provision.js";
 import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";

package/dist/lib/bot/prompt.d.ts

@@ -110,6 +110,13 @@ export declare function nonOwnerRefusalText(botName: string, kind?: BotKind): st
 /**
  * The one-time introduction the bot DMs its owner when it first comes online.
  * A bot created with `--intro` sends that text verbatim instead.
+ *
+ * The first sentence depends on the bot's kind: a personal bot runs under its
+ * owner's login and permissions; a company bot runs with its own identity as
+ * a member of its companies and can only work inside those.
  */
-export declare function introDmText(botName: string, runtime: string, intro?: string): string;
+export declare function introDmText(botName: string, runtime: string, intro?: string, identity?: {
+    kind?: BotKind;
+    companies?: string[];
+}): string;
 //# sourceMappingURL=prompt.d.ts.map

package/dist/lib/bot/prompt.js

@@ -342,12 +342,20 @@ export function nonOwnerRefusalText(botName, kind = "personal") {
 /**
  * The one-time introduction the bot DMs its owner when it first comes online.
  * A bot created with `--intro` sends that text verbatim instead.
+ *
+ * The first sentence depends on the bot's kind: a personal bot runs under its
+ * owner's login and permissions; a company bot runs with its own identity as
+ * a member of its companies and can only work inside those.
  */
-export function introDmText(botName, runtime, intro) {
+export function introDmText(botName, runtime, intro, identity = {}) {
     if (intro?.trim())
         return intro.trim();
     const runtimeLabel = runtime === "claude" ? "Claude Code" : runtime === "codex" ? "Codex" : runtime === "grok" ? "Grok" : runtime;
-    return (`Hi, I'm ${botName} — your HQ bot. I run locally on this computer using your ${runtimeLabel} login, so I can work inside your HQ with your permissions.\n\n` +
+    const companies = (identity.companies ?? []).filter((c) => c.trim());
+    const opening = (identity.kind ?? "personal") === "company"
+        ? `Hi, I'm ${botName} — your HQ company bot. I run locally on this computer with my own identity, as a member of ${companies.length > 0 ? companies.join(", ") : "my companies"}, so I can only work inside ${companies.length === 1 ? "that company" : "those companies"}.`
+        : `Hi, I'm ${botName} — your HQ bot. I run locally on this computer using your ${runtimeLabel} login, so I can work inside your HQ with your permissions.`;
+    return (`${opening}\n\n` +
         `You can message me here from the desktop app or your phone whenever this computer is on, and I'll reply in this thread. ` +
         `You can also open me in Claude Code or Codex from your HQ folder.\n\n` +
         `What would you like me to do first?`);

package/dist/lib/bot/run.js

@@ -298,7 +298,7 @@ export async function runBot(deps) {
     }
     else if (!config.introSentAt) {
         try {
-            const sent = await api.sendDm({ toPersonUid: config.ownerUid, body: introDmText(config.name, config.runtime, config.intro) });
+            const sent = await api.sendDm({ toPersonUid: config.ownerUid, body: introDmText(config.name, config.runtime, config.intro, { kind: effectiveBotKind(config), companies: effectiveBotCompanies(config) }) });
             patchBotConfig(dir, { introSentAt: now().toISOString() });
             log("info", "intro DM sent to owner");
             if (config.kickoff?.trim())

package/dist/lib/core-utils/qmd-reindex-after-sync.d.ts

@@ -1,4 +1,5 @@
-import type { UtilityIo } from "./common.js";
+import { type EmbedLockDependencies } from "../search-index/embed-lock.js";
+import { type UtilityIo } from "./common.js";
 export type QmdReindexOptions = UtilityIo & {
     cwd?: string;
     /** Test seams; default to the real search-index implementations. */
@@ -11,6 +12,8 @@ export type QmdReindexOptions = UtilityIo & {
         cwd: string;
     }) => unknown;
     sizeLimit?: (hqRoot: string) => unknown;
+    /** Test seams for the lock shared by every hq-cli embed entry point. */
+    embedLockDependencies?: EmbedLockDependencies;
 };
 export declare function qmdReindexAfterSync(args?: string[], options?: QmdReindexOptions): number;
 //# sourceMappingURL=qmd-reindex-after-sync.d.ts.map

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -11,8 +11,10 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { reconcileCollections, resolveQmdBin, runQmd } from "../search-index/index.js";
+import { reconcileCollections, resolveQmdBin, resolveQmdHome, runQmd } from "../search-index/index.js";
 import { applyIndexSizeLimit } from "../search-index/max-doc-bytes.js";
+import { defaultEmbedLockDependencies, runWithEmbedLock, } from "../search-index/embed-lock.js";
+import { ioFor, line } from "./common.js";
 export function qmdReindexAfterSync(args = [], options = {}) {
     let hqRoot = "";
     let embed = false;
@@ -38,6 +40,7 @@ export function qmdReindexAfterSync(args = [], options = {}) {
     const reconcile = options.reconcile ?? ((root, opts) => reconcileCollections(root, opts));
     const run = options.run ?? ((argv, opts) => runQmd(argv, opts));
     const sizeLimit = options.sizeLimit ?? ((root) => applyIndexSizeLimit(root));
+    const { stderr } = ioFor(options);
     // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
     try {
         reconcile(hqRoot, { bin });
@@ -62,8 +65,14 @@ export function qmdReindexAfterSync(args = [], options = {}) {
         /* never fail a sync on index freshness */
     }
     if (embed) {
+        const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
         try {
-            run(["embed"], { bin, cwd: hqRoot });
+            const outcome = runWithEmbedLock(resolveQmdHome(lockDependencies.env), lockDependencies, () => { run(["embed"], { bin, cwd: hqRoot }); });
+            if (outcome === "busy") {
+                line(stderr, "hq: qmd embed is already running; skipping this pass.");
+            }
+            if (outcome === "unavailable")
+                line(stderr, "hq: cannot access the qmd embed lock; skipping this pass.");
         }
         catch {
             /* embeddings are deferred-cost and optional */

package/dist/lib/onboarding/checkpoint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Onboarding checkpoint persistence (VLT-9 US-001; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Reads/writes .hq/onboarding-state.json for idempotent resume.
+ * If a flow fails partway, re-running picks up from the last checkpoint.
+ */
+import type { OnboardingCheckpoint, OnboardingStep } from "./types.js";
+export declare function getCheckpointPath(hqRoot: string): string;
+export declare function readCheckpoint(hqRoot: string): Promise<OnboardingCheckpoint | null>;
+export declare function writeCheckpoint(hqRoot: string, checkpoint: OnboardingCheckpoint): Promise<void>;
+export declare function isStepComplete(checkpoint: OnboardingCheckpoint | null, step: OnboardingStep): boolean;
+export declare function deleteCheckpoint(hqRoot: string): Promise<void>;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/lib/onboarding/checkpoint.js

@@ -0,0 +1,44 @@
+/**
+ * Onboarding checkpoint persistence (VLT-9 US-001; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Reads/writes .hq/onboarding-state.json for idempotent resume.
+ * If a flow fails partway, re-running picks up from the last checkpoint.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+const CHECKPOINT_FILE = "onboarding-state.json";
+export function getCheckpointPath(hqRoot) {
+    return join(hqRoot, ".hq", CHECKPOINT_FILE);
+}
+export async function readCheckpoint(hqRoot) {
+    const path = getCheckpointPath(hqRoot);
+    try {
+        const raw = await readFile(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeCheckpoint(hqRoot, checkpoint) {
+    const path = getCheckpointPath(hqRoot);
+    await mkdir(dirname(path), { recursive: true });
+    checkpoint.updatedAt = new Date().toISOString();
+    await writeFile(path, JSON.stringify(checkpoint, null, 2) + "\n", "utf-8");
+}
+export function isStepComplete(checkpoint, step) {
+    if (!checkpoint)
+        return false;
+    return checkpoint.completedSteps.includes(step);
+}
+export async function deleteCheckpoint(hqRoot) {
+    const { unlink } = await import("node:fs/promises");
+    const path = getCheckpointPath(hqRoot);
+    try {
+        await unlink(path);
+    }
+    catch {
+        // File may not exist — that's fine
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/lib/onboarding/cli/onboard.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CLI onboard entry point (VLT-9 US-002; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Programmatic API for the /onboard command. The slash command calls
+ * these functions; they can also be consumed by integration tests.
+ */
+import type { VaultServiceConfig } from "@indigoai-us/hq-cloud";
+import { VaultClient } from "@indigoai-us/hq-cloud";
+import type { OnboardingResult } from "../types.js";
+export interface OnboardCliOptions {
+    mode: "create-company" | "join-company" | "resume" | "dry-run";
+    personName?: string;
+    personEmail?: string;
+    companyName?: string;
+    companySlug?: string;
+    inviteToken?: string;
+    vaultConfig: VaultServiceConfig;
+    hqRoot: string;
+    log?: (msg: string) => void;
+}
+export interface OnboardCliResult {
+    success: boolean;
+    result?: OnboardingResult;
+    error?: string;
+}
+export type CompanySlugAvailability = {
+    kind: "available";
+}
+/** The caller already owns (or is a member of) a company with this slug. */
+ | {
+    kind: "mine";
+    uid: string;
+}
+/** Another account holds the slug. */
+ | {
+    kind: "taken";
+};
+/**
+ * Decide whether `create-company` may proceed for a slug.
+ *
+ * A company that already exists in the CALLER's namespace is not "taken": it
+ * is theirs — typically left behind by an earlier run that created the
+ * entity and then died before the bucket, membership, or config were done
+ * (there may be no local checkpoint or company folder at all). The flow
+ * resumes against it instead of refusing. Only a slug held by a different
+ * account is refused.
+ */
+export declare function checkCompanySlugAvailability(client: Pick<VaultClient, "entity">, slug: string): Promise<CompanySlugAvailability>;
+/**
+ * Run the /onboard CLI flow.
+ */
+export declare function runOnboardCli(options: OnboardCliOptions): Promise<OnboardCliResult>;
+//# sourceMappingURL=onboard.d.ts.map

package/dist/lib/onboarding/cli/onboard.js

@@ -0,0 +1,135 @@
+/**
+ * CLI onboard entry point (VLT-9 US-002; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Programmatic API for the /onboard command. The slash command calls
+ * these functions; they can also be consumed by integration tests.
+ */
+import { VaultClient, VaultConflictError, VaultNotFoundError } from "@indigoai-us/hq-cloud";
+import { createCompanyFlow, joinCompanyFlow, resumeOnboarding, } from "../orchestrator.js";
+import { readCheckpoint, getCheckpointPath } from "../checkpoint.js";
+import { formatProgress, formatSummary, formatError } from "./prompts.js";
+const CREATE_STEPS = 6;
+const JOIN_STEPS = 6;
+/**
+ * Decide whether `create-company` may proceed for a slug.
+ *
+ * A company that already exists in the CALLER's namespace is not "taken": it
+ * is theirs — typically left behind by an earlier run that created the
+ * entity and then died before the bucket, membership, or config were done
+ * (there may be no local checkpoint or company folder at all). The flow
+ * resumes against it instead of refusing. Only a slug held by a different
+ * account is refused.
+ */
+export async function checkCompanySlugAvailability(client, slug) {
+    const mine = await client.entity.findInMyNamespace("company", slug);
+    if (mine)
+        return { kind: "mine", uid: mine.uid };
+    try {
+        await client.entity.findBySlug("company", slug);
+        return { kind: "taken" };
+    }
+    catch (err) {
+        // VaultNotFoundError = slug available, continue
+        const isNotFound = err instanceof VaultNotFoundError ||
+            (err instanceof Error && err.name === "VaultNotFoundError");
+        if (isNotFound)
+            return { kind: "available" };
+        // Several other tenants hold the slug (server answers 409): not ours.
+        const isConflict = err instanceof VaultConflictError ||
+            (err instanceof Error && err.name === "VaultConflictError");
+        if (isConflict)
+            return { kind: "taken" };
+        throw err;
+    }
+}
+/**
+ * Run the /onboard CLI flow.
+ */
+export async function runOnboardCli(options) {
+    const { mode, vaultConfig, hqRoot, log = console.log } = options;
+    let stepCounter = 0;
+    const onProgress = (event) => {
+        if (event.status === "running")
+            stepCounter++;
+        const total = mode === "create-company" ? CREATE_STEPS : JOIN_STEPS;
+        log(formatProgress(event, stepCounter, total));
+    };
+    const config = { vaultConfig, hqRoot };
+    try {
+        if (mode === "resume") {
+            const checkpoint = await readCheckpoint(hqRoot);
+            if (!checkpoint) {
+                return { success: false, error: "No checkpoint found. Run /onboard to start." };
+            }
+            log(`Resuming ${checkpoint.mode} flow from step ${checkpoint.completedSteps.length + 1}...`);
+            const result = await resumeOnboarding(config, onProgress);
+            log("");
+            log(formatSummary(result));
+            return { success: true, result };
+        }
+        if (mode === "dry-run") {
+            log("DRY RUN — simulating create-company flow:");
+            log("  1. Create person entity");
+            log("  2. Create company entity");
+            log("  3. Provision S3 bucket + KMS key");
+            log("  4. Bootstrap owner membership");
+            log("  5. Verify STS credential vending");
+            log("  6. Write .hq/config.json");
+            log("");
+            log("No resources will be created. Run /onboard to execute.");
+            return { success: true };
+        }
+        if (mode === "create-company") {
+            // Validate slug availability
+            if (options.companySlug) {
+                const client = new VaultClient(vaultConfig);
+                const availability = await checkCompanySlugAvailability(client, options.companySlug);
+                if (availability.kind === "taken") {
+                    return {
+                        success: false,
+                        error: `Company slug "${options.companySlug}" is already taken. Choose another.`,
+                    };
+                }
+                if (availability.kind === "mine") {
+                    log(`Company "${options.companySlug}" already exists in your account (${availability.uid}) — finishing its setup.`);
+                }
+            }
+            const input = {
+                mode: "create-company",
+                personName: options.personName,
+                personEmail: options.personEmail,
+                companyName: options.companyName,
+                companySlug: options.companySlug,
+            };
+            log(`Creating company "${input.companyName}" (${input.companySlug})...`);
+            log("");
+            const result = await createCompanyFlow(input, config, onProgress);
+            log("");
+            log(formatSummary(result));
+            return { success: true, result };
+        }
+        if (mode === "join-company") {
+            const input = {
+                mode: "join-company",
+                personName: options.personName,
+                personEmail: options.personEmail,
+                inviteToken: options.inviteToken,
+            };
+            log("Joining company via invite...");
+            log("");
+            const result = await joinCompanyFlow(input, config, onProgress);
+            log("");
+            log(formatSummary(result));
+            return { success: true, result };
+        }
+        return { success: false, error: `Unknown mode: ${mode}` };
+    }
+    catch (err) {
+        const checkpointPath = getCheckpointPath(hqRoot);
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        log("");
+        log(formatError(err instanceof Error ? err : new Error(errorMsg), checkpointPath));
+        return { success: false, error: errorMsg };
+    }
+}
+//# sourceMappingURL=onboard.js.map

package/dist/lib/onboarding/cli/prompts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CLI prompt helpers for /onboard command (VLT-9 US-002; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Provides typed prompt interfaces the slash command can call.
+ * These are library functions — the actual UX is in onboard.md.
+ */
+import type { OnboardingResult, OnboardingProgress } from "../types.js";
+/**
+ * Format a progress event for CLI display.
+ */
+export declare function formatProgress(event: OnboardingProgress, stepNumber: number, totalSteps: number): string;
+/**
+ * Format the success summary box.
+ */
+export declare function formatSummary(result: OnboardingResult): string;
+/**
+ * Format an error for CLI display with recovery hints.
+ */
+export declare function formatError(error: Error, checkpointPath: string): string;
+/**
+ * Validate a company slug: lowercase, alphanumeric + hyphens, 3-40 chars.
+ */
+export declare function validateSlug(slug: string): string | null;
+/**
+ * Validate email format.
+ */
+export declare function validateEmail(email: string): string | null;
+//# sourceMappingURL=prompts.d.ts.map