@indigoai-us/hq-cli 5.14.0 → 5.14.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [5.14.1] — 2026-05-14
+
+### Fixed
+
+- **`hq install <pack>` now writes to `core/packages/<name>/`** under the
+  v12 HQ layout, not top-level `packages/<name>/`. Pre-v12 behavior left
+  an orphan tree alongside the canonical `core/packages/` shipped by the
+  template (`hq-core` / `hq-core-staging`).
+- **Post-install `scan-packages.sh` is now resolved at
+  `core/scripts/scan-packages.sh`** instead of top-level `scripts/`.
+- **Stopped writing pack entries to `modules/modules.yaml`.** Packs are
+  tracked by filesystem presence under v12 (no separate registry file).
+  `hq update <pack>` will re-resolve source from each pack's
+  `package.yaml` or prompt; this is intentional. The legacy
+  knowledge-modules feature (`strategy: 'git-clone'`) is untouched.
+
+(Surfaced during end-to-end testing of the hq-installer staging-channel
+toggle — see indigoai-us/hq-installer#61.)
+
 ## [5.14.0] — 2026-05-14
 
 ### Changed

package/dist/commands/cloud-provision.d.ts

@@ -20,7 +20,10 @@
  * Exit codes:
  *   0 — success (and `initial_sync.ok=true`)
  *   1 — vault auth/network/API error (no entity provisioned)
- *   2 — invalid slug, company missing from manifest, or company dir missing
+ *   2 — invalid slug, company dir missing, or company is status=archived.
+ *       Folder-only states (companies/<slug>/ exists on disk but no manifest
+ *       entry) self-heal via ensureManifestEntryForProvision before
+ *       validation runs, so a missing manifest entry alone is NOT an exit-2.
  *   3 — sync failure after entity provisioned (cloud_uid in JSON;
  *       `initial_sync.ok=false`). Manifest + config may have been written.
  */
@@ -99,6 +102,15 @@ interface InitialSyncArgs {
 }
 /** Vault HTTP client interface — minimal surface for entity ops. */
 export interface VaultClient {
+    /**
+     * List every person entity visible to the caller (scoped server-side by the
+     * caller's Cognito identity). Used by `provisionCompany` as a pre-flight
+     * to verify the caller has been onboarded before mutating any cloud-side
+     * resources — the initial-sync step at the end of provision needs to vend
+     * STS credentials, which the server only does for callers with a person
+     * entity.
+     */
+    listMyPersonEntities(): Promise<VaultEntity[]>;
     findCompanyBySlug(slug: string): Promise<VaultEntity | null>;
     createCompanyEntity(input: {
         slug: string;
@@ -114,8 +126,10 @@ export declare class ProvisionError extends Error {
 }
 /**
  * Validate a company slug per the contract: alphanumeric / dot / dash / underscore,
- * non-empty, and never `"personal"` (which is auto-provisioned per-user, not
- * promoted via this subcommand).
+ * non-empty, never `"."` or `".."` (path-traversal — would resolve to
+ * `companies/` itself or `<hqRoot>` and write outside the intended company
+ * directory), and never `"personal"` (auto-provisioned per-user, not promoted
+ * via this subcommand).
  *
  * Throws ProvisionError with code=2 on failure.
  */
@@ -136,11 +150,34 @@ export declare function companyConfigPath(hqRoot: string, slug: string): string;
  *   - company is `status: archived`
  *   - `companies/<slug>/` does not exist
  *
+ * Strict on purpose — callers that want the "auto-insert a missing entry when
+ * the local folder exists" affordance (cloud-provision's fault-tolerant flow)
+ * MUST call `ensureManifestEntryForProvision` first. cloud-demote and other
+ * sensitive callers depend on this strict failure for typo-catching.
+ *
  * Returns the parsed manifest (so the caller can re-use it for the patch step).
  */
 export declare function validateManifestAndDir(hqRoot: string, slug: string): {
     manifest: ManifestDoc;
 };
+/**
+ * Provision-only pre-step. If `companies/<slug>/` exists on disk but the slug
+ * is absent from `manifest.yaml`, atomically insert an empty entry
+ * (`<slug>: {}`) so the downstream `validateManifestAndDir` + `patchManifest`
+ * flow has something to operate on. Heals the common folder-only state
+ * (manual mkdir, or older tools that didn't patch manifest.yaml) that hq-sync's
+ * Connect button used to dead-end on with exit 2.
+ *
+ * No-op in every other case:
+ *   - manifest file missing / malformed (validation will surface)
+ *   - slug already present (any value, including null — preserved as-is)
+ *   - `companies/<slug>/` does not exist (validation will surface as a typo)
+ *
+ * This affordance is provision-specific. `cloud-demote` and other strict
+ * callers MUST NOT call this — their typo-catching contract depends on
+ * `validateManifestAndDir` throwing on missing-slug.
+ */
+export declare function ensureManifestEntryForProvision(hqRoot: string, slug: string): void;
 /**
  * Top-level manifest shape we touch. We preserve all unknown fields — only
  * `cloud_uid` and `bucket_name` under the target slug are mutated.

package/dist/commands/cloud-provision.js

@@ -20,12 +20,15 @@
  * Exit codes:
  *   0 — success (and `initial_sync.ok=true`)
  *   1 — vault auth/network/API error (no entity provisioned)
- *   2 — invalid slug, company missing from manifest, or company dir missing
+ *   2 — invalid slug, company dir missing, or company is status=archived.
+ *       Folder-only states (companies/<slug>/ exists on disk but no manifest
+ *       entry) self-heal via ensureManifestEntryForProvision before
+ *       validation runs, so a missing manifest entry alone is NOT an exit-2.
  *   3 — sync failure after entity provisioned (cloud_uid in JSON;
  *       `initial_sync.ok=false`). Manifest + config may have been written.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aacb5bf2-8362-5336-b864-43296c30a1d6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5573abae-ee71-5106-94e7-3485e3e0fbb2")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -45,11 +48,13 @@ export class ProvisionError extends Error {
 }
 // ── Validation ───────────────────────────────────────────────────────────────
 const SLUG_REGEX = /^[A-Za-z0-9._-]+$/;
-const FORBIDDEN_SLUGS = new Set(["personal"]);
+const FORBIDDEN_SLUGS = new Set(["personal", ".", ".."]);
 /**
  * Validate a company slug per the contract: alphanumeric / dot / dash / underscore,
- * non-empty, and never `"personal"` (which is auto-provisioned per-user, not
- * promoted via this subcommand).
+ * non-empty, never `"."` or `".."` (path-traversal — would resolve to
+ * `companies/` itself or `<hqRoot>` and write outside the intended company
+ * directory), and never `"personal"` (auto-provisioned per-user, not promoted
+ * via this subcommand).
  *
  * Throws ProvisionError with code=2 on failure.
  */
@@ -61,7 +66,10 @@ export function validateSlug(slug) {
         throw new ProvisionError(2, `Invalid slug "${slug}" — must match ${SLUG_REGEX.source}`);
     }
     if (FORBIDDEN_SLUGS.has(slug)) {
-        throw new ProvisionError(2, `Slug "${slug}" is reserved (auto-provisioned per-user, not eligible for cloud promotion)`);
+        const reason = slug === "personal"
+            ? "auto-provisioned per-user, not eligible for cloud promotion"
+            : "path-traversal slug (would resolve to a directory outside the intended company folder)";
+        throw new ProvisionError(2, `Slug "${slug}" is reserved (${reason})`);
     }
 }
 /** Path to the top-level companies manifest file. */
@@ -86,6 +94,11 @@ export function companyConfigPath(hqRoot, slug) {
  *   - company is `status: archived`
  *   - `companies/<slug>/` does not exist
  *
+ * Strict on purpose — callers that want the "auto-insert a missing entry when
+ * the local folder exists" affordance (cloud-provision's fault-tolerant flow)
+ * MUST call `ensureManifestEntryForProvision` first. cloud-demote and other
+ * sensitive callers depend on this strict failure for typo-catching.
+ *
  * Returns the parsed manifest (so the caller can re-use it for the patch step).
  */
 export function validateManifestAndDir(hqRoot, slug) {
@@ -115,6 +128,69 @@ export function validateManifestAndDir(hqRoot, slug) {
     }
     return { manifest };
 }
+/**
+ * Provision-only pre-step. If `companies/<slug>/` exists on disk but the slug
+ * is absent from `manifest.yaml`, atomically insert an empty entry
+ * (`<slug>: {}`) so the downstream `validateManifestAndDir` + `patchManifest`
+ * flow has something to operate on. Heals the common folder-only state
+ * (manual mkdir, or older tools that didn't patch manifest.yaml) that hq-sync's
+ * Connect button used to dead-end on with exit 2.
+ *
+ * No-op in every other case:
+ *   - manifest file missing / malformed (validation will surface)
+ *   - slug already present (any value, including null — preserved as-is)
+ *   - `companies/<slug>/` does not exist (validation will surface as a typo)
+ *
+ * This affordance is provision-specific. `cloud-demote` and other strict
+ * callers MUST NOT call this — their typo-catching contract depends on
+ * `validateManifestAndDir` throwing on missing-slug.
+ */
+export function ensureManifestEntryForProvision(hqRoot, slug) {
+    const mPath = manifestPath(hqRoot);
+    if (!fs.existsSync(mPath))
+        return;
+    // Defense-in-depth against path-traversal slugs (`.`, `..`, anything that
+    // resolves outside companies/). validateSlug rejects these upstream, but
+    // this helper is exported and might be called directly by future code —
+    // never auto-insert based on a path that isn't a literal direct child of
+    // `companies/`. fs.realpathSync would also catch symlink-escapes, but the
+    // directory may legitimately not exist yet on disk; path.resolve gives us
+    // the canonical lexical form without a stat call.
+    const companiesDir = path.resolve(hqRoot, "companies");
+    const expected = path.resolve(companiesDir, slug);
+    const expectedParent = path.dirname(expected);
+    if (expectedParent !== companiesDir)
+        return;
+    if (path.basename(expected) !== slug)
+        return;
+    const dir = companyDirPath(hqRoot, slug);
+    if (!fs.existsSync(dir))
+        return;
+    const raw = fs.readFileSync(mPath, "utf-8");
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch {
+        return;
+    }
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        !("companies" in parsed) ||
+        typeof parsed.companies !== "object") {
+        return;
+    }
+    const doc = parsed;
+    if (!doc.companies)
+        doc.companies = {};
+    if (doc.companies[slug] !== undefined)
+        return;
+    doc.companies[slug] = {};
+    const dump = yaml.dump(doc, { lineWidth: -1, noRefs: true });
+    const tmp = `${mPath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, dump);
+    fs.renameSync(tmp, mPath);
+}
 /**
  * Atomically patch `companies/manifest.yaml` to set `cloud_uid` + `bucket_name`
  * under the target slug. Read → mutate → temp-write → rename so concurrent
@@ -179,6 +255,18 @@ export function createDefaultVaultClient(apiUrl, accessToken) {
         Authorization: `Bearer ${accessToken}`,
     };
     return {
+        async listMyPersonEntities() {
+            const url = `${apiUrl.replace(/\/$/, "")}/entity/by-type/person`;
+            const res = await fetch(url, { method: "GET", headers });
+            if (res.status === 404)
+                return [];
+            if (!res.ok) {
+                const body = await safeBody(res);
+                throw new ProvisionError(1, `Vault GET /entity/by-type/person failed: ${res.status} ${res.statusText} — ${body}`);
+            }
+            const data = (await res.json());
+            return data.entities ?? [];
+        },
         async findCompanyBySlug(slug) {
             const url = `${apiUrl.replace(/\/$/, "")}/entity/by-slug/company/${encodeURIComponent(slug)}`;
             const res = await fetch(url, { method: "GET", headers });
@@ -258,8 +346,13 @@ async function defaultRunInitialSync(args) {
  */
 export async function provisionCompany(options) {
     const log = options.log ?? ((msg) => process.stderr.write(`[hq cloud provision] ${msg}\n`));
-    // Step 1+2+3: validate slug, manifest, dir
+    // Step 1+2+3: validate slug, auto-heal a folder-only manifest, then validate
+    // the resulting manifest + dir. The auto-heal is provision-specific: it
+    // inserts an empty entry when companies/<slug>/ exists on disk but the slug
+    // is missing from manifest.yaml. validateManifestAndDir stays strict so
+    // other callers (cloud-demote) keep their typo-catching guard.
     validateSlug(options.slug);
+    ensureManifestEntryForProvision(options.hqRoot, options.slug);
     validateManifestAndDir(options.hqRoot, options.slug);
     log(`validated slug=${options.slug}`);
     // Step 4: auth — defer to injected resolver (default: ensureCognitoToken)
@@ -270,6 +363,23 @@ export async function provisionCompany(options) {
     // Step 5: GET-then-POST for idempotency
     const vaultClient = options.vaultClient ??
         createDefaultVaultClient(options.vaultApiUrl, accessToken);
+    // Pre-flight: caller MUST have a registered person entity. Without one,
+    // the initial-sync step at the end of this flow (STS /sts/vend) returns
+    // 403 "no person entity" and leaves the operator with a half-built cloud
+    // company — vault entity created, S3 bucket provisioned, manifest patched,
+    // .hq/config.json written, but nothing actually syncing. This was the
+    // primary failure mode in the 2026-05-14 setup-session deep dive
+    // (Joey Muller / sum-digital).
+    //
+    // Failing here, BEFORE any cloud-side resource creation, leaves the operator
+    // with no cleanup work — they fix the underlying onboarding gap (run
+    // `hq onboard` / sign in with the correct federated identity) and re-run
+    // `hq cloud provision company <slug>` cleanly.
+    const persons = await vaultClient.listMyPersonEntities();
+    if (persons.length === 0) {
+        throw new ProvisionError(2, 'No person entity found for this Cognito identity. Run `hq onboard` first to create your HQ identity, then re-run `hq cloud provision company`. (Provision was halted before any cloud-side resources were created.)');
+    }
+    log(`pre-flight ok — caller has ${persons.length} person entity(ies)`);
     let entity = await vaultClient.findCompanyBySlug(options.slug);
     let createdEntity = false;
     if (entity) {
@@ -426,4 +536,4 @@ export function registerCloudProvisionCommands(program) {
     });
 }
 //# sourceMappingURL=cloud-provision.js.map
-//# debugId=aacb5bf2-8362-5336-b864-43296c30a1d6
+//# debugId=5573abae-ee71-5106-94e7-3485e3e0fbb2

package/dist/commands/pack-install.d.ts

@@ -26,16 +26,44 @@
  *   3. Parse + validate package.yaml (10 checks from spec)
  *   4. Evaluate `conditional` predicate — skip if exits non-zero
  *   5. Confirm hooks if `contributes.hooks` non-empty (unless --allow-hooks)
- *   6. Move into packages/{name}/
- *   7. Append entry to modules.yaml with strategy: package
- *   8. Run scan-packages.sh to wire contributions into host paths
+ *   6. Move into core/packages/{name}/
+ *   7. Run core/scripts/scan-packages.sh to wire contributions into host paths
+ *
+ * Installed packs are tracked by filesystem presence — there's no separate
+ * registry file under the v12 layout. (`hq update <pack>` re-resolves source
+ * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
+import type { PackManifest } from '../types.js';
 /**
  * sourceMatchesPackPattern — exported for the dispatcher in pkg-install.ts
  * so it can decide whether to route to the new content-pack handler or fall
  * back to the legacy registry flow.
  */
 export declare function sourceMatchesPackPattern(source: string): boolean;
+/**
+ * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
+ * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships
+ * `core/packages/` as the canonical pack root; writing to top-level
+ * `packages/` would leave an orphan tree alongside the real one.
+ *
+ * Re-installs replace the existing destination so stale contributions don't
+ * linger (the post-install `scan-packages.sh` would otherwise wire them
+ * back into host paths).
+ *
+ * Exported for tests in pack-install.test.ts — see that file for the
+ * contract this function pins.
+ */
+export declare function installToPackages(payloadDir: string, pkg: PackManifest, hqRoot: string): string;
+/**
+ * Run `<hqRoot>/core/scripts/scan-packages.sh` to wire the newly installed
+ * pack's contributions into the host paths (skills, hooks, policies, etc.).
+ * Skipping with a dim warning if the script is missing keeps fresh HQs (or
+ * older templates) usable — the next session start picks them up via its
+ * own scan.
+ *
+ * Exported for tests.
+ */
+export declare function runScanPackages(hqRoot: string): void;
 export interface InstallPackOptions {
     allowHooks?: boolean;
     followBranch?: boolean;

package/dist/commands/pack-install.js

@@ -26,12 +26,15 @@
  *   3. Parse + validate package.yaml (10 checks from spec)
  *   4. Evaluate `conditional` predicate — skip if exits non-zero
  *   5. Confirm hooks if `contributes.hooks` non-empty (unless --allow-hooks)
- *   6. Move into packages/{name}/
- *   7. Append entry to modules.yaml with strategy: package
- *   8. Run scan-packages.sh to wire contributions into host paths
+ *   6. Move into core/packages/{name}/
+ *   7. Run core/scripts/scan-packages.sh to wire contributions into host paths
+ *
+ * Installed packs are tracked by filesystem presence — there's no separate
+ * registry file under the v12 layout. (`hq update <pack>` re-resolves source
+ * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9c0fc9f1-9a26-5a3f-a795-7254534316d5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5dea7752-f10c-553c-a419-cf05441b3c13")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -42,7 +45,7 @@ import chalk from 'chalk';
 import semverSatisfies from 'semver/functions/satisfies.js';
 import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
-import { findHqRoot, readManifest, writeManifest, } from '../utils/manifest.js';
+import { findHqRoot } from '../utils/manifest.js';
 function classify(source) {
     if (source.startsWith('@'))
         return 'npm';
@@ -415,10 +418,23 @@ function evalConditional(expr) {
     return r.status === 0;
 }
 // ---------------------------------------------------------------------------
-// Move into packages/ + update modules.yaml + scan
+// Move into core/packages/ + run core/scripts/scan-packages.sh
 // ---------------------------------------------------------------------------
-function installToPackages(payloadDir, pkg, hqRoot) {
-    const packagesDir = path.join(hqRoot, 'packages');
+/**
+ * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
+ * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships
+ * `core/packages/` as the canonical pack root; writing to top-level
+ * `packages/` would leave an orphan tree alongside the real one.
+ *
+ * Re-installs replace the existing destination so stale contributions don't
+ * linger (the post-install `scan-packages.sh` would otherwise wire them
+ * back into host paths).
+ *
+ * Exported for tests in pack-install.test.ts — see that file for the
+ * contract this function pins.
+ */
+export function installToPackages(payloadDir, pkg, hqRoot) {
+    const packagesDir = path.join(hqRoot, 'core', 'packages');
     fs.mkdirSync(packagesDir, { recursive: true });
     const destDir = path.join(packagesDir, pkg.name);
     if (fs.existsSync(destDir)) {
@@ -430,28 +446,19 @@ function installToPackages(payloadDir, pkg, hqRoot) {
     execFileSync('rsync', ['-a', srcSlashed, destSlashed], { stdio: 'inherit' });
     return destDir;
 }
-function updateModulesYaml(hqRoot, pkg, fetched) {
-    const manifest = readManifest(hqRoot) ?? { version: '1', modules: [] };
-    // Drop any existing entry for this pack (idempotent re-install)
-    manifest.modules = manifest.modules.filter((m) => m.name !== pkg.name);
-    const entry = {
-        name: pkg.name,
-        strategy: 'package',
-        source: fetched.resolvedSource,
-        version: pkg.version,
-        installed_at: path.posix.join('packages', pkg.name),
-        installed_at_iso: new Date().toISOString(),
-        access: pkg.access === 'public' ? 'public' : undefined,
-    };
-    if (fetched.resolvedSha)
-        entry.resolved_sha = fetched.resolvedSha;
-    manifest.modules.push(entry);
-    writeManifest(hqRoot, manifest);
-}
-function runScanPackages(hqRoot) {
-    const script = path.join(hqRoot, 'scripts', 'scan-packages.sh');
+/**
+ * Run `<hqRoot>/core/scripts/scan-packages.sh` to wire the newly installed
+ * pack's contributions into the host paths (skills, hooks, policies, etc.).
+ * Skipping with a dim warning if the script is missing keeps fresh HQs (or
+ * older templates) usable — the next session start picks them up via its
+ * own scan.
+ *
+ * Exported for tests.
+ */
+export function runScanPackages(hqRoot) {
+    const script = path.join(hqRoot, 'core', 'scripts', 'scan-packages.sh');
     if (!fs.existsSync(script)) {
-        console.log(chalk.dim(`  (scripts/scan-packages.sh not present — skipping auto-wire; ` +
+        console.log(chalk.dim(`  (core/scripts/scan-packages.sh not present — skipping auto-wire; ` +
             `will run on next session start)`));
         return;
     }
@@ -502,7 +509,12 @@ export async function installPack(source, opts = {}) {
             return;
         }
         const destDir = installToPackages(fetched.payloadDir, pkg, hqRoot);
-        updateModulesYaml(hqRoot, pkg, fetched);
+        // Under the v12 HQ layout, packs live at `core/packages/<name>/` and are
+        // tracked by filesystem presence alone — no `modules.yaml` write. That
+        // removes the side effect that created a top-level `modules/` directory
+        // alongside the canonical `core/`. `hq update <pack>` will re-resolve a
+        // pack's source from its on-disk package.yaml or prompt for it, but that
+        // tradeoff is intentional — see the layout-fix PR for rationale.
         runScanPackages(hqRoot);
         console.log(chalk.green(`\n✓ Installed ${pkg.name}@${pkg.version} → ${path.relative(hqRoot, destDir)}/`));
         console.log(chalk.dim(`  Wired ${Object.values(pkg.contributes).flat().filter(Boolean).length} ` +
@@ -513,4 +525,4 @@ export async function installPack(source, opts = {}) {
     }
 }
 //# sourceMappingURL=pack-install.js.map
-//# debugId=9c0fc9f1-9a26-5a3f-a795-7254534316d5
+//# debugId=5dea7752-f10c-553c-a419-cf05441b3c13

package/dist/utils/cognito-session.d.ts

@@ -21,6 +21,31 @@
 import { type CognitoAuthConfig, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
 export declare const DEFAULT_COGNITO: CognitoAuthConfig;
 export declare const DEFAULT_VAULT_API_URL: string;
+/**
+ * Resolve the default HQ tree root for cloud-aware subcommands.
+ *
+ * Priority order:
+ *   1. `$HQ_ROOT` env var (explicit user override)
+ *   2. Walk up from `process.cwd()` to the nearest dir containing BOTH a
+ *      `core.yaml` file AND a `companies/` directory (root-unique marker
+ *      pair — see note below).
+ *   3. Fall back to `~/hq` (the historical default)
+ *
+ * Why both markers?
+ *   The HQ root has `core.yaml` AND a sibling `companies/` directory. The
+ *   synced `core/` subtree (which is itself part of the root's personal-vault
+ *   scope) ALSO contains a `core.yaml` (the template's version-source-of-
+ *   truth), but does NOT contain `companies/`. Single-marker `core.yaml`
+ *   detection would stop at `<hqRoot>/core/` when the CLI is launched from
+ *   somewhere inside that subtree, and downstream `companies/` lookups would
+ *   silently miss the real content. Requiring `companies/` as well guarantees
+ *   we resolve to the actual HQ root (Codex P2 on hq#146).
+ *
+ * Evaluated once at module load — commander.js `.option()` callers pin the
+ * value at registration time, which matches the user's actual cwd at process
+ * start. Re-importable as a function for tests and command-time resolution.
+ */
+export declare function resolveDefaultHqRoot(): string;
 export declare const DEFAULT_HQ_ROOT: string;
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in

package/dist/utils/cognito-session.js

@@ -19,7 +19,8 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="71d8f748-f249-50df-aa1f-eae381ea608d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6a8ac157-0903-513d-b4c5-45fb532b8026")}catch(e){}}();
+import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import chalk from "chalk";
@@ -41,7 +42,53 @@ export const DEFAULT_COGNITO = {
         : "Google",
 };
 export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hqapi.getindigo.ai";
-export const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
+/**
+ * Resolve the default HQ tree root for cloud-aware subcommands.
+ *
+ * Priority order:
+ *   1. `$HQ_ROOT` env var (explicit user override)
+ *   2. Walk up from `process.cwd()` to the nearest dir containing BOTH a
+ *      `core.yaml` file AND a `companies/` directory (root-unique marker
+ *      pair — see note below).
+ *   3. Fall back to `~/hq` (the historical default)
+ *
+ * Why both markers?
+ *   The HQ root has `core.yaml` AND a sibling `companies/` directory. The
+ *   synced `core/` subtree (which is itself part of the root's personal-vault
+ *   scope) ALSO contains a `core.yaml` (the template's version-source-of-
+ *   truth), but does NOT contain `companies/`. Single-marker `core.yaml`
+ *   detection would stop at `<hqRoot>/core/` when the CLI is launched from
+ *   somewhere inside that subtree, and downstream `companies/` lookups would
+ *   silently miss the real content. Requiring `companies/` as well guarantees
+ *   we resolve to the actual HQ root (Codex P2 on hq#146).
+ *
+ * Evaluated once at module load — commander.js `.option()` callers pin the
+ * value at registration time, which matches the user's actual cwd at process
+ * start. Re-importable as a function for tests and command-time resolution.
+ */
+export function resolveDefaultHqRoot() {
+    if (process.env.HQ_ROOT)
+        return path.resolve(process.env.HQ_ROOT);
+    let cur = path.resolve(process.cwd());
+    while (cur !== path.dirname(cur)) {
+        if (isHqRoot(cur))
+            return cur;
+        cur = path.dirname(cur);
+    }
+    return path.join(os.homedir(), "hq");
+}
+/** True iff `dir` looks like an HQ root (has core.yaml + companies/ dir). */
+function isHqRoot(dir) {
+    if (!fs.existsSync(path.join(dir, "core.yaml")))
+        return false;
+    try {
+        return fs.statSync(path.join(dir, "companies")).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export const DEFAULT_HQ_ROOT = resolveDefaultHqRoot();
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
  * as needed. Cache lives at ~/.hq/cognito-tokens.json.
@@ -108,4 +155,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=71d8f748-f249-50df-aa1f-eae381ea608d
+//# debugId=6a8ac157-0903-513d-b4c5-45fb532b8026

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.14.0",
+  "version": "5.14.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {