@indigoai-us/hq-cli 5.77.3 → 5.77.5

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [5.77.5]
+
+### Added
+
+- **Cross-platform meeting-bot invites.** Run
+  `hq meetings invite <meeting-url>` to schedule the meeting bot from any
+  terminal. Add `--company <slug-or-uid>` to route the transcript to a company
+  vault; omitting it keeps the invite in your personal vault. (#252)
+
+### Fixed
+
+- High-security secret refusals now clearly direct callers to `hq secrets
+  sandbox` or the HQ secret proxy, including sandbox-only denials and
+  `--script` attempts. (#253)
+
+## [5.77.4]
+
+### Fixed
+
+- Malformed user-managed YAML now reports the affected file and line/column as
+  an expected, actionable CLI error instead of creating a Sentry exception.
+
 ## [5.77.2]
 
 ### Fixed

package/dist/commands/cloud-demote.js

@@ -30,6 +30,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import chalk from "chalk";
 import { ProvisionError, companyConfigPath, companyDirPath, createDefaultVaultClient, manifestPath, validateManifestAndDir, validateSlug, } from "./cloud-provision.js";
 import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, } from "../utils/cognito-session.js";
@@ -49,7 +50,7 @@ export function flipCompanyYamlCloudOff(hqRoot, slug) {
     if (!fs.existsSync(yPath))
         return false;
     const raw = fs.readFileSync(yPath, "utf-8");
-    const parsed = yaml.load(raw) ?? {};
+    const parsed = parseUserYaml(raw, yPath) ?? {};
     if (parsed.cloud === false)
         return false;
     parsed.cloud = false;
@@ -72,7 +73,7 @@ export function stripManifestCloudForSlug(hqRoot, slug) {
     if (!fs.existsSync(mPath))
         return false;
     const raw = fs.readFileSync(mPath, "utf-8");
-    const parsed = yaml.load(raw) ?? {};
+    const parsed = parseUserYaml(raw, mPath) ?? {};
     const companies = parsed.companies;
     if (!companies || !(slug in companies))
         return false;

package/dist/commands/cloud-provision.js

@@ -31,6 +31,7 @@ import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { share } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 /** Custom error class so the CLI runner can map to exit codes. */
@@ -105,7 +106,7 @@ export function validateManifestAndDir(hqRoot, slug) {
         throw new ProvisionError(2, `companies/manifest.yaml not found at ${mPath}`);
     }
     const raw = fs.readFileSync(mPath, "utf-8");
-    const parsed = yaml.load(raw);
+    const parsed = parseUserYaml(raw, mPath);
     if (!parsed ||
         typeof parsed !== "object" ||
         !("companies" in parsed) ||
@@ -225,7 +226,7 @@ export function ensureManifestEntryForProvision(hqRoot, slug) {
 export function patchManifest(hqRoot, slug, cloudUid, bucketName) {
     const mPath = manifestPath(hqRoot);
     const raw = fs.readFileSync(mPath, "utf-8");
-    const parsed = yaml.load(raw) ?? { companies: {} };
+    const parsed = parseUserYaml(raw, mPath) ?? { companies: {} };
     if (!parsed.companies)
         parsed.companies = {};
     const existing = parsed.companies[slug];

package/dist/commands/meetings.js

@@ -208,6 +208,43 @@ export function registerMeetingsCommand(program) {
             process.exit(1);
         }
     });
+    // ── hq meetings invite <meeting-url> ──────────────────────────────
+    meetings
+        .command("invite <meetingUrl>")
+        .description("Invite the meeting bot to a Google Meet, Zoom, or Teams URL")
+        .action(async (meetingUrl) => {
+        try {
+            const token = await ensureCognitoToken();
+            const companySlug = meetings.opts().company;
+            const query = {};
+            if (companySlug)
+                query.companyId = await getCompanyUid(token, companySlug);
+            const res = await vaultApiFetch({
+                token,
+                method: "POST",
+                path: "/v1/bot/invite",
+                query,
+                body: { meetingUrl },
+            });
+            if (!res.ok)
+                await handleApiError(res);
+            const data = (await res.json());
+            if (meetings.opts().json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            console.log(chalk.green(`\n✓ Meeting bot invited to ${chalk.cyan(data.meetingUrl ?? meetingUrl)}.`));
+            if (data.botId)
+                console.log(chalk.dim(`  Bot: ${data.botId}`));
+            if (data.status)
+                console.log(chalk.dim(`  Status: ${data.status}`));
+            console.log();
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
     // ── hq meetings get <id> ──────────────────────────────────────────
     meetings
         .command("get <meetingId>")

package/dist/commands/pack-install.js

@@ -37,7 +37,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as readline from 'readline';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { createHash, createPublicKey, verify as cryptoVerify, } from 'node:crypto';
 import { execFileSync, spawnSync } from 'child_process';
 import chalk from 'chalk';
@@ -940,9 +940,12 @@ export function validateManifest(payloadDir, hqVersion) {
     }
     let parsed;
     try {
-        parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+        parsed = parseUserYaml(fs.readFileSync(manifestPath, 'utf-8'), manifestPath);
     }
     catch (e) {
+        if (e instanceof Error && e.expected === true) {
+            throw e;
+        }
         throw new Error(`package.yaml invalid YAML: ${e.message}`);
     }
     const m = parsed;

package/dist/commands/people.js

@@ -14,7 +14,7 @@
 import * as fs from "fs";
 import { Option } from "commander";
 import chalk from "chalk";
-import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath } from "./cloud-provision.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -96,13 +96,7 @@ export function resolveCompanySlug(hqRoot, explicit) {
         throw new Error("Could not determine the active company — companies/manifest.yaml not found. " +
             "Re-run with --company <slug>.");
     }
-    let manifest;
-    try {
-        manifest = yaml.load(fs.readFileSync(mPath, "utf-8"));
-    }
-    catch (err) {
-        throw new Error(`companies/manifest.yaml is malformed: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const manifest = parseUserYaml(fs.readFileSync(mPath, "utf-8"), mPath);
     const slugs = activeCompanySlugs(manifest ?? {});
     if (slugs.length === 1)
         return slugs[0];

package/dist/commands/pkg-install.js

@@ -15,7 +15,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
@@ -117,7 +117,7 @@ async function installPackage(slug, company) {
         const packageYamlPath = path.resolve(installDir, 'package.yaml');
         if (fs.existsSync(packageYamlPath)) {
             const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-            const pkgMeta = yaml.load(pkgContent);
+            const pkgMeta = parseUserYaml(pkgContent, packageYamlPath);
             if (pkgMeta?.slug && pkgMeta.slug !== slug) {
                 // Mismatch — clean up and abort
                 fs.rmSync(installDir, { recursive: true, force: true });
@@ -137,7 +137,7 @@ async function installPackage(slug, company) {
             const packageYaml = path.resolve(installDir, 'package.yaml');
             if (fs.existsSync(packageYaml)) {
                 const content = fs.readFileSync(packageYaml, 'utf-8');
-                const meta = yaml.load(content);
+                const meta = parseUserYaml(content, packageYaml);
                 if (meta?.version)
                     version = meta.version;
                 if (meta?.name)

package/dist/commands/pkg-update.js

@@ -7,7 +7,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
@@ -92,7 +92,7 @@ async function updatePackages(slug) {
                 const packageYamlPath = path.resolve(installDir, 'package.yaml');
                 if (fs.existsSync(packageYamlPath)) {
                     const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-                    const pkgMeta = yaml.load(pkgContent);
+                    const pkgMeta = parseUserYaml(pkgContent, packageYamlPath);
                     if (pkgMeta?.slug && pkgMeta.slug !== entry.slug) {
                         fs.rmSync(installDir, { recursive: true, force: true });
                         throw new Error(`Package slug mismatch: expected "${entry.slug}", got "${pkgMeta.slug}"`);

package/dist/commands/publish.js

@@ -31,6 +31,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
@@ -91,7 +92,7 @@ export function stampAuthorYaml(manifest, author) {
 /** Read package.yaml, stamp author, write it back. Returns the stamped author. */
 export function stampAuthorIntoPackage(payloadDir, author) {
     const manifestPath = path.join(payloadDir, 'package.yaml');
-    const parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+    const parsed = parseUserYaml(fs.readFileSync(manifestPath, 'utf-8'), manifestPath);
     fs.writeFileSync(manifestPath, stampAuthorYaml(parsed, author));
 }
 // ---------------------------------------------------------------------------

package/dist/commands/secrets.js

@@ -131,6 +131,12 @@ function promptSecretInteractively() {
 // server (the legacy per-key GET path had no such cap).
 const MAX_BATCH_NAMES = 100;
 const SECRET_LOAD_TIMEOUT_MS = 30_000;
+function highSecuritySandboxOnlyMessage(secretName) {
+    const sandboxExample = secretName
+        ? `hq secrets sandbox --only ${secretName} -- <command>`
+        : "hq secrets sandbox --only <secret> -- <command>";
+    return `High-security secrets can run only in the sandbox (use \`${sandboxExample}\`) or through the HQ secret proxy. Local injection and script locks (\`--script\`) are not supported.`;
+}
 function parseSecretAclPrincipal(principal) {
     const p = principal.trim();
     if (p === "@all") {
@@ -435,10 +441,13 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
             if (!res.ok) {
                 const body = (await res.json().catch(() => ({})));
                 const message = extractApiMessage(body, res.statusText);
-                // High-security ("nuclear") refusal surfaced at the batch level (rather
-                // than per-name): point the caller at the proxy and never leak plaintext.
-                if (body.code === "high_security_denied" || body.highSecurity === true) {
-                    throw new Error("A requested secret is high-security and cannot be injected locally — it can only be used through the HQ secret proxy, which keeps the plaintext server-side.");
+                // High-security refusal surfaced at the batch level (rather than
+                // per-name): point the caller at the sandbox/proxy and never leak
+                // plaintext. A local script attestation is not an override.
+                if (body.code === "high_security_denied" ||
+                    body.code === "high_security_sandbox_only" ||
+                    body.highSecurity === true) {
+                    throw new Error(highSecuritySandboxOnlyMessage());
                 }
                 if (res.status >= 400 &&
                     res.status < 500 &&
@@ -508,14 +517,13 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     continue;
                 removeCacheEntry(companyUid, key);
                 const err = errorsByName.get(key);
-                // High-security ("nuclear") secret: the server refuses to vend it on the
-                // local-injection (batch-load) path — per-name code `high_security_denied`,
-                // no plaintext returned. Every caller of loadRevealedSecrets injects or
-                // prints the plaintext locally (`secrets get --reveal`, `secrets exec`,
-                // `secrets env`), so a high-security secret can NEVER be used here. Surface
-                // a clear, actionable error pointing at the proxy instead of a raw failure.
-                if (err?.code === "high_security_denied") {
-                    firstFailure ??= new Error(`Secret '${key}' is high-security and cannot be injected locally — it can only be used through the HQ secret proxy, which keeps the plaintext server-side.`);
+                // Every caller of loadRevealedSecrets injects or prints the plaintext
+                // locally (`secrets get --reveal`, `secrets exec`, `secrets env`). Both
+                // high-security denial shapes therefore receive the same explicit
+                // sandbox/proxy guidance, even if the caller supplied `--script`.
+                if (err?.code === "high_security_denied" ||
+                    err?.code === "high_security_sandbox_only") {
+                    firstFailure ??= new Error(highSecuritySandboxOnlyMessage(key));
                     continue;
                 }
                 const reason = err?.code === "not_found"
@@ -655,7 +663,7 @@ export function registerSecretsCommand(program) {
             removeCacheEntry(companyUid, name);
             console.log(chalk.green(formatSecretSaved(name, scopeLabel)));
             if (opts.highSecurity) {
-                console.log(chalk.dim(`  High-security: destination pinned to ${destinations?.[0]}. This value can never be revealed or injected locally — only used through the HQ secret proxy.`));
+                console.log(chalk.dim(`  High-security: destination pinned to ${destinations?.[0]}. This value can run only in the sandbox (hq secrets sandbox) or through the HQ secret proxy; local injection and script locks are unsupported.`));
             }
         }
         catch (err) {
@@ -677,13 +685,11 @@ export function registerSecretsCommand(program) {
             });
             if (!res.ok) {
                 const body = (await res.json().catch(() => ({})));
-                // High-security ("nuclear") secret: the server refuses to reveal it on
-                // the local-injection path (403, no plaintext). Surface a clear,
-                // actionable error pointing the user at the proxy rather than a raw
-                // 4xx — the value can ONLY be used through the server-side proxy.
+                // High-security secrets cannot be revealed locally. Surface the
+                // hosted execution path rather than a raw 4xx; `--script` never
+                // overrides this boundary.
                 if (res.status === 403 && body.highSecurity === true) {
-                    console.error(chalk.red(`Secret '${name}' is high-security and cannot be revealed locally.`));
-                    console.error(chalk.dim("  It can only be used through the HQ secret proxy, which keeps the plaintext server-side."));
+                    console.error(chalk.red(highSecuritySandboxOnlyMessage(name)));
                     process.exit(1);
                 }
                 console.error(chalk.red(`Failed to get secret: ${extractApiMessage(body, res.statusText)}`));

package/dist/commands/workers.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
@@ -11,7 +12,7 @@ export function readWorkerRegistry(hqRoot) {
     const p = path.join(hqRoot, "core/workers/registry.yaml");
     if (!fs.existsSync(p))
         return [];
-    const doc = yaml.load(fs.readFileSync(p, "utf8"));
+    const doc = parseUserYaml(fs.readFileSync(p, "utf8"), p);
     return doc?.workers ?? [];
 }
 /**
@@ -87,7 +88,7 @@ export function writeGrantSidecar(hqRoot, workerPath, principalLabel) {
     const sidecar = path.join(dir, ".grants.yaml");
     let grants = [];
     if (fs.existsSync(sidecar)) {
-        const doc = yaml.load(fs.readFileSync(sidecar, "utf8"));
+        const doc = parseUserYaml(fs.readFileSync(sidecar, "utf8"), sidecar);
         if (Array.isArray(doc?.grants))
             grants = doc.grants.filter((g) => typeof g === "string");
     }

package/dist/utils/manifest.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from './user-yaml-error.js';
 const MANIFEST_FILE = 'modules.yaml';
 const LOCK_FILE = 'modules.lock';
 const STATE_FILE = '.hq-sync-state.json';
@@ -51,7 +52,7 @@ export function readManifest(hqRoot) {
         return null;
     }
     const content = fs.readFileSync(manifestPath, 'utf-8');
-    return yaml.load(content);
+    return parseUserYaml(content, manifestPath);
 }
 export function writeManifest(hqRoot, manifest) {
     const manifestPath = getManifestPath(hqRoot);
@@ -68,7 +69,7 @@ export function readLock(hqRoot) {
         return null;
     }
     const content = fs.readFileSync(lockPath, 'utf-8');
-    return yaml.load(content);
+    return parseUserYaml(content, lockPath);
 }
 export function writeLock(hqRoot, lock) {
     const lockPath = getLockPath(hqRoot);

package/dist/utils/people.js

@@ -16,7 +16,7 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import * as yaml from "js-yaml";
+import { parseUserYaml } from "./user-yaml-error.js";
 /**
  * Company slugs map directly onto a filesystem path segment, so we validate
  * them before joining to keep a malicious or fat-fingered `--company` value
@@ -45,13 +45,7 @@ export function companyPeopleDir(hqRoot, companySlug) {
  * surfaced as a half-row. Exported for unit testing.
  */
 export function parsePersonMeta(raw, slug, source) {
-    let doc;
-    try {
-        doc = yaml.load(raw);
-    }
-    catch (err) {
-        throw new Error(`Failed to parse ${source}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const doc = parseUserYaml(raw, source);
     if (!doc || typeof doc !== "object")
         return null;
     const d = doc;

package/dist/utils/registry-client.js

@@ -6,8 +6,8 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
 import { resolveDefaultHqRoot } from './cognito-session.js';
+import { parseUserYaml } from './user-yaml-error.js';
 // ---------------------------------------------------------------------------
 // URL helper (unchanged from US-004)
 // ---------------------------------------------------------------------------
@@ -23,7 +23,7 @@ export function getRegistryUrl() {
         throw new Error(`No packages/sources.yaml found at ${sourcesPath}. Is your HQ packages directory set up?`);
     }
     const content = fs.readFileSync(sourcesPath, 'utf-8');
-    const parsed = yaml.load(content);
+    const parsed = parseUserYaml(content, sourcesPath);
     if (!parsed?.sources?.length) {
         throw new Error('No sources defined in packages/sources.yaml');
     }

package/dist/utils/registry.js

@@ -4,6 +4,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from './user-yaml-error.js';
 function registryPath(hqRoot) {
     return path.resolve(hqRoot, 'packages', 'registry.yaml');
 }
@@ -17,7 +18,7 @@ export function readRegistry(hqRoot) {
         return [];
     }
     const content = fs.readFileSync(filePath, 'utf-8');
-    const parsed = yaml.load(content);
+    const parsed = parseUserYaml(content, filePath);
     return parsed?.packages ?? [];
 }
 /**

package/dist/utils/user-yaml-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse YAML supplied from an on-disk HQ file.
+ *
+ * YAML syntax is user-correctable content, not an hq-cli defect. js-yaml's
+ * default error includes a source excerpt, which can inadvertently echo
+ * secrets, so replace it with a concise, actionable location instead.
+ */
+export declare function parseUserYaml<T>(content: string, filePath: string): T;
+//# sourceMappingURL=user-yaml-error.d.ts.map

package/dist/utils/user-yaml-error.js

@@ -0,0 +1,25 @@
+import * as yaml from "js-yaml";
+/**
+ * Parse YAML supplied from an on-disk HQ file.
+ *
+ * YAML syntax is user-correctable content, not an hq-cli defect. js-yaml's
+ * default error includes a source excerpt, which can inadvertently echo
+ * secrets, so replace it with a concise, actionable location instead.
+ */
+export function parseUserYaml(content, filePath) {
+    try {
+        return yaml.load(content, { filename: filePath });
+    }
+    catch (err) {
+        if (!(err instanceof yaml.YAMLException))
+            throw err;
+        const line = err.mark ? err.mark.line + 1 : undefined;
+        const column = err.mark ? err.mark.column + 1 : undefined;
+        const location = line !== undefined && column !== undefined
+            ? `:${line}:${column}`
+            : "";
+        throw Object.assign(new Error(`Invalid YAML in ${filePath}${location}: ${err.reason}. ` +
+            "Fix the indentation or syntax and try again."), { expected: true });
+    }
+}
+//# sourceMappingURL=user-yaml-error.js.map

package/package.json

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

package/src/commands/cloud-demote.ts

@@ -31,6 +31,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { Command } from "commander";
 import chalk from "chalk";
 
@@ -98,7 +99,7 @@ export function flipCompanyYamlCloudOff(hqRoot: string, slug: string): boolean {
   const yPath = path.join(companyDirPath(hqRoot, slug), "company.yaml");
   if (!fs.existsSync(yPath)) return false;
   const raw = fs.readFileSync(yPath, "utf-8");
-  const parsed = (yaml.load(raw) as Record<string, unknown> | null) ?? {};
+  const parsed = parseUserYaml<Record<string, unknown> | null>(raw, yPath) ?? {};
   if (parsed.cloud === false) return false;
   parsed.cloud = false;
   const dump = yaml.dump(parsed, { lineWidth: -1, noRefs: true });
@@ -120,7 +121,7 @@ export function stripManifestCloudForSlug(hqRoot: string, slug: string): boolean
   const mPath = manifestPath(hqRoot);
   if (!fs.existsSync(mPath)) return false;
   const raw = fs.readFileSync(mPath, "utf-8");
-  const parsed = (yaml.load(raw) as { companies?: Record<string, unknown> } | null) ?? {};
+  const parsed = parseUserYaml<{ companies?: Record<string, unknown> } | null>(raw, mPath) ?? {};
   const companies = parsed.companies;
   if (!companies || !(slug in companies)) return false;
   const entry = companies[slug];

package/src/commands/cloud-provision.ts

@@ -33,6 +33,7 @@ import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 
 import { share } from "@indigoai-us/hq-cloud";
 
@@ -255,7 +256,7 @@ export function validateManifestAndDir(
     );
   }
   const raw = fs.readFileSync(mPath, "utf-8");
-  const parsed = yaml.load(raw) as unknown;
+  const parsed = parseUserYaml<unknown>(raw, mPath);
   if (
     !parsed ||
     typeof parsed !== "object" ||
@@ -411,7 +412,7 @@ export function patchManifest(
 ): boolean {
   const mPath = manifestPath(hqRoot);
   const raw = fs.readFileSync(mPath, "utf-8");
-  const parsed = (yaml.load(raw) as ManifestDoc) ?? { companies: {} };
+  const parsed = parseUserYaml<ManifestDoc | null>(raw, mPath) ?? { companies: {} };
   if (!parsed.companies) parsed.companies = {};
   const existing = parsed.companies[slug];
   // Preserve null / object / unknown — promote null → {} so we can write keys.

package/src/commands/meetings.test.ts

@@ -32,6 +32,7 @@ vi.mock("../utils/vault-api.js", async (importOriginal) => {
 });
 
 import { registerMeetingsCommand } from "./meetings.js";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 
 let logSpy: MockInstance<typeof console.log>;
@@ -145,6 +146,61 @@ describe("meetings get — short id resolution", () => {
   });
 });
 
+describe("meetings invite", () => {
+  it("authenticates and posts the meeting URL with the optional company routing", async () => {
+    const meetingUrl = "https://meet.google.com/abc-defg-hij";
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonRes({
+        botId: "bot_123",
+        meetingUrl,
+        platform: "google_meet",
+        status: "scheduled",
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync([
+      "node",
+      "hq",
+      "meetings",
+      "--company",
+      "indigo",
+      "invite",
+      meetingUrl,
+    ]);
+
+    expect(ensureCognitoToken).toHaveBeenCalledOnce();
+    expect(getCompanyUid).toHaveBeenCalledWith("test-token", "indigo");
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      method: "POST",
+      path: "/v1/bot/invite",
+      query: { companyId: "cmp_indigo" },
+      body: { meetingUrl },
+    });
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("Meeting bot invited"));
+  });
+
+  it("omits company routing so the backend uses the caller's personal vault", async () => {
+    const meetingUrl = "https://zoom.us/j/123456789";
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonRes({ botId: "bot_123", meetingUrl, status: "scheduled" }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(["node", "hq", "meetings", "invite", meetingUrl]);
+
+    expect(getCompanyUid).not.toHaveBeenCalled();
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      method: "POST",
+      path: "/v1/bot/invite",
+      query: {},
+      body: { meetingUrl },
+    });
+  });
+});
+
 describe("meetings set-company", () => {
   it("POSTs the resolved company id and applies to the recurring series by default", async () => {
     vi.mocked(vaultApiFetch).mockResolvedValueOnce(

package/src/commands/meetings.ts

@@ -101,6 +101,13 @@ interface MeetingDocument {
   notes: MeetingNotes | null;
 }
 
+interface MeetingBotInviteResponse {
+  botId?: string;
+  meetingUrl?: string;
+  platform?: string;
+  status?: string;
+}
+
 function formatDuration(seconds: number): string {
   const h = Math.floor(seconds / 3600);
   const m = Math.floor((seconds % 3600) / 60);
@@ -344,6 +351,43 @@ export function registerMeetingsCommand(program: Command): void {
       }
     });
 
+  // ── hq meetings invite <meeting-url> ──────────────────────────────
+
+  meetings
+    .command("invite <meetingUrl>")
+    .description("Invite the meeting bot to a Google Meet, Zoom, or Teams URL")
+    .action(async (meetingUrl: string) => {
+      try {
+        const token = await ensureCognitoToken();
+        const companySlug = meetings.opts().company as string | undefined;
+        const query: Record<string, string> = {};
+        if (companySlug) query.companyId = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          method: "POST",
+          path: "/v1/bot/invite",
+          query,
+          body: { meetingUrl },
+        });
+        if (!res.ok) await handleApiError(res);
+        const data = (await res.json()) as MeetingBotInviteResponse;
+
+        if (meetings.opts().json) {
+          console.log(JSON.stringify(data, null, 2));
+          return;
+        }
+
+        console.log(chalk.green(`\n✓ Meeting bot invited to ${chalk.cyan(data.meetingUrl ?? meetingUrl)}.`));
+        if (data.botId) console.log(chalk.dim(`  Bot: ${data.botId}`));
+        if (data.status) console.log(chalk.dim(`  Status: ${data.status}`));
+        console.log();
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
   // ── hq meetings get <id> ──────────────────────────────────────────
 
   meetings

package/src/commands/pack-install.ts

@@ -38,7 +38,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as readline from 'readline';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import {
   createHash,
   createPublicKey,
@@ -1261,8 +1261,11 @@ export function validateManifest(
   }
   let parsed: unknown;
   try {
-    parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+    parsed = parseUserYaml(fs.readFileSync(manifestPath, 'utf-8'), manifestPath);
   } catch (e) {
+    if (e instanceof Error && (e as { expected?: unknown }).expected === true) {
+      throw e;
+    }
     throw new Error(`package.yaml invalid YAML: ${(e as Error).message}`);
   }
   const m = parsed as Partial<PackManifest> & Record<string, unknown>;

package/src/commands/people.test.ts

@@ -19,6 +19,7 @@ import {
   resolveNameToEmail,
   type PersonRecord,
 } from "../utils/people.js";
+import { isExpectedUserError } from "../utils/expected-cli-error.js";
 import {
   activeMemberToPersonRecord,
   mergePeople,
@@ -138,9 +139,17 @@ describe("parsePersonMeta", () => {
   });
 
   it("throws on unparseable yaml", () => {
-    expect(() => parsePersonMeta("name: [unterminated\n", "x", "/x")).toThrow(
-      /Failed to parse/,
-    );
+    const error = (() => {
+      try {
+        parsePersonMeta("name: [unterminated\n", "x", "/x");
+      } catch (err) {
+        return err;
+      }
+      throw new Error("expected malformed YAML to throw");
+    })();
+
+    expect(isExpectedUserError(error)).toBe(true);
+    expect((error as Error).message).toContain("Invalid YAML in /x:2:1");
   });
 });
 

package/src/commands/people.ts

@@ -15,7 +15,7 @@
 import * as fs from "fs";
 import { Command, Option } from "commander";
 import chalk from "chalk";
-import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath, type ManifestDoc } from "./cloud-provision.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -146,14 +146,10 @@ export function resolveCompanySlug(
         "Re-run with --company <slug>.",
     );
   }
-  let manifest: ManifestDoc;
-  try {
-    manifest = yaml.load(fs.readFileSync(mPath, "utf-8")) as ManifestDoc;
-  } catch (err) {
-    throw new Error(
-      `companies/manifest.yaml is malformed: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
+  const manifest = parseUserYaml<ManifestDoc>(
+    fs.readFileSync(mPath, "utf-8"),
+    mPath,
+  );
   const slugs = activeCompanySlugs(manifest ?? {});
   if (slugs.length === 1) return slugs[0];
   if (slugs.length === 0) {

package/src/commands/pkg-install.ts

@@ -16,7 +16,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -157,7 +157,7 @@ async function installPackage(
     const packageYamlPath = path.resolve(installDir, 'package.yaml');
     if (fs.existsSync(packageYamlPath)) {
       const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-      const pkgMeta = yaml.load(pkgContent) as { slug?: string } | null;
+      const pkgMeta = parseUserYaml<{ slug?: string } | null>(pkgContent, packageYamlPath);
       if (pkgMeta?.slug && pkgMeta.slug !== slug) {
         // Mismatch — clean up and abort
         fs.rmSync(installDir, { recursive: true, force: true });
@@ -179,10 +179,10 @@ async function installPackage(
       const packageYaml = path.resolve(installDir, 'package.yaml');
       if (fs.existsSync(packageYaml)) {
         const content = fs.readFileSync(packageYaml, 'utf-8');
-        const meta = yaml.load(content) as {
+        const meta = parseUserYaml<{
           version?: string;
           name?: string;
-        } | null;
+        } | null>(content, packageYaml);
         if (meta?.version) version = meta.version;
         if (meta?.name) name = meta.name;
       }

package/src/commands/pkg-update.ts

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -146,9 +146,9 @@ async function updatePackages(slug?: string): Promise<void> {
         const packageYamlPath = path.resolve(installDir, 'package.yaml');
         if (fs.existsSync(packageYamlPath)) {
           const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-          const pkgMeta = yaml.load(pkgContent) as {
+          const pkgMeta = parseUserYaml<{
             slug?: string;
-          } | null;
+          } | null>(pkgContent, packageYamlPath);
           if (pkgMeta?.slug && pkgMeta.slug !== entry.slug) {
             fs.rmSync(installDir, { recursive: true, force: true });
             throw new Error(

package/src/commands/publish.ts

@@ -32,6 +32,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execFileSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -124,7 +125,10 @@ export function stampAuthorIntoPackage(
   author: ResolvedAuthor,
 ): void {
   const manifestPath = path.join(payloadDir, 'package.yaml');
-  const parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8')) as Record<string, unknown>;
+  const parsed = parseUserYaml<Record<string, unknown>>(
+    fs.readFileSync(manifestPath, 'utf-8'),
+    manifestPath,
+  );
   fs.writeFileSync(manifestPath, stampAuthorYaml(parsed, author));
 }
 

package/src/commands/secrets.test.ts

@@ -138,6 +138,29 @@ describe("secrets sandbox", () => {
     expect(channel).toBe("sandbox");
   });
 
+  it("runs a high-security secret in the sandbox without a local script attestation", async () => {
+    const program = buildProgram();
+    await program.parseAsync([
+      "node",
+      "hq",
+      "secrets",
+      "sandbox",
+      "--only",
+      "HIGH_SECURITY_KEY",
+      "--",
+      "env",
+    ]);
+
+    expect(startJobSpy).toHaveBeenCalledWith("test-token", {
+      companyUid: "prs_alice",
+      secretNames: ["HIGH_SECURITY_KEY"],
+      command: "env",
+    });
+    expect(vaultApiFetch).not.toHaveBeenCalledWith(
+      expect.objectContaining({ path: expect.stringContaining("/load") }),
+    );
+  });
+
   it("parses --company, --only, and joins args after -- into a command", async () => {
     const program = buildProgram();
     await program.parseAsync([
@@ -534,9 +557,9 @@ describe("secrets exists (HQ-4H HEAD probe)", () => {
 
 // US-003 (secrets-server-proxy): the CLI surfaces the SERVER's refusal of a
 // high-security ("nuclear") secret on the local-injection path as a clear,
-// actionable error pointing at the proxy — and never prints the value. The
-// server-side deny is the real control (it returns 403 + highSecurity:true and
-// NO plaintext); these tests assert the CLI's surfacing behavior.
+// actionable sandbox/proxy error — and never prints the value. The server-side
+// deny is the real control (it returns 403 + highSecurity:true and NO
+// plaintext); these tests assert the CLI's surfacing behavior.
 describe("US-003 — CLI refuses high-security secrets on local injection", () => {
   // The server's 403 refusal shape for a high-security secret.
   function highSecurityDenied(): Response {
@@ -550,6 +573,20 @@ describe("US-003 — CLI refuses high-security secrets on local injection", () =
     );
   }
 
+  function highSecuritySandboxOnly(): Response {
+    return jsonRes({
+      secrets: [],
+      errors: [
+        {
+          name: "ANTHROPIC_API_KEY",
+          code: "high_security_sandbox_only",
+          message:
+            "High-security-tier secrets can run only in the sandbox (`hq secrets sandbox`) or through the secret proxy. Local injection and script locks (`--script`) are not supported.",
+        },
+      ],
+    });
+  }
+
   let exitSpy: MockInstance<typeof process.exit>;
   beforeEach(() => {
     exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
@@ -576,17 +613,22 @@ describe("US-003 — CLI refuses high-security secrets on local injection", () =
     const exitCode = exitSpy.mock.calls[0]?.[0] as number | undefined;
 
     expect(exitCode).toBe(1);
-    // A clear, actionable error mentioning high-security + the proxy.
+    // A clear, actionable error names the sandbox/proxy boundary and rules
+    // out script-lock bypasses.
     const errText = errSpy.mock.calls.flat().join(" ");
     expect(errText).toMatch(/high-security/i);
+    expect(errText).toMatch(/hq secrets sandbox/i);
     expect(errText).toMatch(/proxy/i);
+    expect(errText).toMatch(/--script/);
     // The value is NEVER printed — no "Value:" line carrying plaintext.
     const logText = logSpy.mock.calls.flat().join(" ");
     expect(logText).not.toMatch(/sk-ant/i);
   });
 
-  it("E2E: `secrets exec --only <name> -- env` is denied — proxy-pointing error, command not run", async () => {
-    vi.mocked(vaultApiFetch).mockResolvedValueOnce(highSecurityDenied());
+  it("E2E: `secrets exec --script <path>` is denied — sandbox guidance, command not run", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(highSecuritySandboxOnly());
+    const scriptPath = join(tempDir, "deploy.sh");
+    writeFileSync(scriptPath, "#!/usr/bin/env bash\necho deploy\n");
 
     const program = buildProgram();
     try {
@@ -597,6 +639,10 @@ describe("US-003 — CLI refuses high-security secrets on local injection", () =
         "exec",
         "--only",
         "ANTHROPIC_API_KEY",
+        "--script",
+        scriptPath,
+        "--script-id",
+        "script.deploy",
         "--",
         "env",
       ]);
@@ -608,7 +654,10 @@ describe("US-003 — CLI refuses high-security secrets on local injection", () =
     expect(exitCode).toBe(1);
     const errText = errSpy.mock.calls.flat().join(" ");
     expect(errText).toMatch(/high-security/i);
+    expect(errText).toMatch(/hq secrets sandbox/i);
     expect(errText).toMatch(/proxy/i);
+    expect(errText).toMatch(/--script/);
+    expect(spawn).not.toHaveBeenCalled();
   });
 });
 

package/src/commands/secrets.ts

@@ -212,6 +212,13 @@ export interface SecretLoadResponse {
   errors: Array<{ name: string; code: string; message?: string }>;
 }
 
+function highSecuritySandboxOnlyMessage(secretName?: string): string {
+  const sandboxExample = secretName
+    ? `hq secrets sandbox --only ${secretName} -- <command>`
+    : "hq secrets sandbox --only <secret> -- <command>";
+  return `High-security secrets can run only in the sandbox (use \`${sandboxExample}\`) or through the HQ secret proxy. Local injection and script locks (\`--script\`) are not supported.`;
+}
+
 interface SecretGetResponse {
   secret: {
     name: string;
@@ -669,12 +676,15 @@ export async function loadRevealedSecrets(
       if (!res.ok) {
         const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
         const message = extractApiMessage(body, res.statusText);
-        // High-security ("nuclear") refusal surfaced at the batch level (rather
-        // than per-name): point the caller at the proxy and never leak plaintext.
-        if (body.code === "high_security_denied" || body.highSecurity === true) {
-          throw new Error(
-            "A requested secret is high-security and cannot be injected locally — it can only be used through the HQ secret proxy, which keeps the plaintext server-side.",
-          );
+        // High-security refusal surfaced at the batch level (rather than
+        // per-name): point the caller at the sandbox/proxy and never leak
+        // plaintext. A local script attestation is not an override.
+        if (
+          body.code === "high_security_denied" ||
+          body.code === "high_security_sandbox_only" ||
+          body.highSecurity === true
+        ) {
+          throw new Error(highSecuritySandboxOnlyMessage());
         }
         if (
           res.status >= 400 &&
@@ -752,16 +762,15 @@ export async function loadRevealedSecrets(
         if (resolved.has(key)) continue;
         removeCacheEntry(companyUid, key);
         const err = errorsByName.get(key);
-        // High-security ("nuclear") secret: the server refuses to vend it on the
-        // local-injection (batch-load) path — per-name code `high_security_denied`,
-        // no plaintext returned. Every caller of loadRevealedSecrets injects or
-        // prints the plaintext locally (`secrets get --reveal`, `secrets exec`,
-        // `secrets env`), so a high-security secret can NEVER be used here. Surface
-        // a clear, actionable error pointing at the proxy instead of a raw failure.
-        if (err?.code === "high_security_denied") {
-          firstFailure ??= new Error(
-            `Secret '${key}' is high-security and cannot be injected locally — it can only be used through the HQ secret proxy, which keeps the plaintext server-side.`,
-          );
+        // Every caller of loadRevealedSecrets injects or prints the plaintext
+        // locally (`secrets get --reveal`, `secrets exec`, `secrets env`). Both
+        // high-security denial shapes therefore receive the same explicit
+        // sandbox/proxy guidance, even if the caller supplied `--script`.
+        if (
+          err?.code === "high_security_denied" ||
+          err?.code === "high_security_sandbox_only"
+        ) {
+          firstFailure ??= new Error(highSecuritySandboxOnlyMessage(key));
           continue;
         }
         const reason =
@@ -947,7 +956,7 @@ export function registerSecretsCommand(program: Command): void {
         if (opts.highSecurity) {
           console.log(
             chalk.dim(
-              `  High-security: destination pinned to ${destinations?.[0]}. This value can never be revealed or injected locally — only used through the HQ secret proxy.`,
+              `  High-security: destination pinned to ${destinations?.[0]}. This value can run only in the sandbox (hq secrets sandbox) or through the HQ secret proxy; local injection and script locks are unsupported.`,
             ),
           );
         }
@@ -979,21 +988,11 @@ export function registerSecretsCommand(program: Command): void {
 
         if (!res.ok) {
           const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-          // High-security ("nuclear") secret: the server refuses to reveal it on
-          // the local-injection path (403, no plaintext). Surface a clear,
-          // actionable error pointing the user at the proxy rather than a raw
-          // 4xx — the value can ONLY be used through the server-side proxy.
+          // High-security secrets cannot be revealed locally. Surface the
+          // hosted execution path rather than a raw 4xx; `--script` never
+          // overrides this boundary.
           if (res.status === 403 && body.highSecurity === true) {
-            console.error(
-              chalk.red(
-                `Secret '${name}' is high-security and cannot be revealed locally.`,
-              ),
-            );
-            console.error(
-              chalk.dim(
-                "  It can only be used through the HQ secret proxy, which keeps the plaintext server-side.",
-              ),
-            );
+            console.error(chalk.red(highSecuritySandboxOnlyMessage(name)));
             process.exit(1);
           }
           console.error(

package/src/commands/workers.ts

@@ -3,6 +3,7 @@ import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
@@ -26,9 +27,10 @@ export interface RegistryWorker {
 export function readWorkerRegistry(hqRoot: string): RegistryWorker[] {
   const p = path.join(hqRoot, "core/workers/registry.yaml");
   if (!fs.existsSync(p)) return [];
-  const doc = yaml.load(fs.readFileSync(p, "utf8")) as
-    | { workers?: RegistryWorker[] }
-    | null;
+  const doc = parseUserYaml<{ workers?: RegistryWorker[] } | null>(
+    fs.readFileSync(p, "utf8"),
+    p,
+  );
   return doc?.workers ?? [];
 }
 
@@ -120,9 +122,10 @@ export function writeGrantSidecar(
   const sidecar = path.join(dir, ".grants.yaml");
   let grants: string[] = [];
   if (fs.existsSync(sidecar)) {
-    const doc = yaml.load(fs.readFileSync(sidecar, "utf8")) as
-      | { grants?: string[] }
-      | null;
+    const doc = parseUserYaml<{ grants?: string[] } | null>(
+      fs.readFileSync(sidecar, "utf8"),
+      sidecar,
+    );
     if (Array.isArray(doc?.grants)) grants = doc!.grants.filter((g) => typeof g === "string");
   }
   if (!grants.includes(principalLabel)) grants.push(principalLabel);

package/src/utils/manifest.test.ts

@@ -28,6 +28,7 @@ import {
   writeManifest,
 } from './manifest.js';
 import type { ModulesManifest } from '../types.js';
+import { isExpectedUserError } from './expected-cli-error.js';
 
 let tmpRoot: string;
 
@@ -83,6 +84,24 @@ describe('getManifestPath', () => {
 });
 
 describe('readManifest / writeManifest round-trip', () => {
+  it('surfaces malformed user YAML with the manifest file and location', () => {
+    const nested = path.join(tmpRoot, 'modules', 'modules.yaml');
+    fs.mkdirSync(path.dirname(nested), { recursive: true });
+    fs.writeFileSync(nested, 'modules:\n  - name: hq\n bad: indentation\n');
+
+    const error = (() => {
+      try {
+        readManifest(tmpRoot);
+      } catch (err) {
+        return err;
+      }
+      throw new Error('expected malformed YAML to throw');
+    })();
+
+    expect(isExpectedUserError(error)).toBe(true);
+    expect((error as Error).message).toContain(`${nested}:3:2`);
+  });
+
   it('round-trips against the nested layout', () => {
     writeManifest(tmpRoot, sampleManifest);
 

package/src/utils/manifest.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import type { ModulesManifest, ModuleDefinition, ModuleLock, SyncState } from '../types.js';
+import { parseUserYaml } from './user-yaml-error.js';
 
 const MANIFEST_FILE = 'modules.yaml';
 const LOCK_FILE = 'modules.lock';
@@ -57,7 +58,7 @@ export function readManifest(hqRoot: string): ModulesManifest | null {
     return null;
   }
   const content = fs.readFileSync(manifestPath, 'utf-8');
-  return yaml.load(content) as ModulesManifest;
+  return parseUserYaml<ModulesManifest>(content, manifestPath);
 }
 
 export function writeManifest(hqRoot: string, manifest: ModulesManifest): void {
@@ -76,7 +77,7 @@ export function readLock(hqRoot: string): ModuleLock | null {
     return null;
   }
   const content = fs.readFileSync(lockPath, 'utf-8');
-  return yaml.load(content) as ModuleLock;
+  return parseUserYaml<ModuleLock>(content, lockPath);
 }
 
 export function writeLock(hqRoot: string, lock: ModuleLock): void {

package/src/utils/people.ts

@@ -17,7 +17,7 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import * as yaml from "js-yaml";
+import { parseUserYaml } from "./user-yaml-error.js";
 
 /** A single person/member record parsed from a `people/<slug>/meta.yaml`. */
 export interface PersonRecord {
@@ -76,14 +76,7 @@ export function parsePersonMeta(
   slug: string,
   source: string,
 ): PersonRecord | null {
-  let doc: unknown;
-  try {
-    doc = yaml.load(raw);
-  } catch (err) {
-    throw new Error(
-      `Failed to parse ${source}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
+  const doc = parseUserYaml<unknown>(raw, source);
   if (!doc || typeof doc !== "object") return null;
   const d = doc as Record<string, unknown>;
 

package/src/utils/registry-client.ts

@@ -7,8 +7,8 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
 import { resolveDefaultHqRoot } from './cognito-session.js';
+import { parseUserYaml } from './user-yaml-error.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -86,7 +86,7 @@ export function getRegistryUrl(): string {
   }
 
   const content = fs.readFileSync(sourcesPath, 'utf-8');
-  const parsed = yaml.load(content) as SourcesFile;
+  const parsed = parseUserYaml<SourcesFile>(content, sourcesPath);
 
   if (!parsed?.sources?.length) {
     throw new Error('No sources defined in packages/sources.yaml');

package/src/utils/registry.ts

@@ -5,6 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from './user-yaml-error.js';
 
 export interface RegistryEntry {
   name: string;
@@ -35,7 +36,7 @@ export function readRegistry(hqRoot: string): RegistryEntry[] {
     return [];
   }
   const content = fs.readFileSync(filePath, 'utf-8');
-  const parsed = yaml.load(content) as RegistryFile | null;
+  const parsed = parseUserYaml<RegistryFile | null>(content, filePath);
   return parsed?.packages ?? [];
 }
 

package/src/utils/user-yaml-error.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { isExpectedUserError } from "./expected-cli-error.js";
+import { parseUserYaml } from "./user-yaml-error.js";
+
+describe("parseUserYaml", () => {
+  it("marks malformed user YAML as expected and names its file and location", () => {
+    const filePath = "/tmp/HQ/modules/modules.yaml";
+    const error = (() => {
+      try {
+        parseUserYaml('apiKey: "secret-do-not-echo"\nmodule:\n  name: hq\n bad: indentation\n', filePath);
+      } catch (err) {
+        return err;
+      }
+      throw new Error("expected malformed YAML to throw");
+    })();
+
+    expect(isExpectedUserError(error)).toBe(true);
+    expect((error as Error).message).toContain(
+      `Invalid YAML in ${filePath}:4:2: bad indentation of a mapping entry.`,
+    );
+    expect((error as Error).message).toContain("Fix the indentation or syntax and try again.");
+    expect((error as Error).message).not.toContain("secret-do-not-echo");
+  });
+});

package/src/utils/user-yaml-error.ts

@@ -0,0 +1,30 @@
+import * as yaml from "js-yaml";
+
+/**
+ * Parse YAML supplied from an on-disk HQ file.
+ *
+ * YAML syntax is user-correctable content, not an hq-cli defect. js-yaml's
+ * default error includes a source excerpt, which can inadvertently echo
+ * secrets, so replace it with a concise, actionable location instead.
+ */
+export function parseUserYaml<T>(content: string, filePath: string): T {
+  try {
+    return yaml.load(content, { filename: filePath }) as T;
+  } catch (err) {
+    if (!(err instanceof yaml.YAMLException)) throw err;
+
+    const line = err.mark ? err.mark.line + 1 : undefined;
+    const column = err.mark ? err.mark.column + 1 : undefined;
+    const location = line !== undefined && column !== undefined
+      ? `:${line}:${column}`
+      : "";
+
+    throw Object.assign(
+      new Error(
+        `Invalid YAML in ${filePath}${location}: ${err.reason}. ` +
+          "Fix the indentation or syntax and try again.",
+      ),
+      { expected: true as const },
+    );
+  }
+}