@indigoai-us/hq-cli 5.47.14 → 5.47.16

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

@@ -238,6 +238,20 @@ export declare function computeArtifactHash(tarballBytes: Uint8Array): string;
  */
 export declare function verifyArtifact(input: VerifyArtifactInput): void;
 export declare function validateManifest(payloadDir: string, hqVersion: string | null): PackManifest;
+/**
+ * Derive the safe, auto-generated "get started" line for a freshly installed
+ * pack from its `initialization.entrypoint` ONLY. PHASE 1 deliberately ignores
+ * the free-text `initialization.prompt` prose (rendering/moderation is a later
+ * story) so untrusted prose can't reach the operator's terminal.
+ *
+ * The command is slash-normalized to exactly one leading slash regardless of
+ * whether `entrypoint` was stored with or without one, matching the HQ Sync
+ * desktop render: ``Run `/email-assistant` to get started``.
+ *
+ * Returns `null` when there is no initialization block (backwards-compatible —
+ * the caller prints nothing extra).
+ */
+export declare function getStartedLine(initialization?: PackManifest['initialization']): string | null;
 /**
  * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
  * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships

package/dist/commands/pack-install.js

@@ -34,7 +34,7 @@
  * 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]="cbb11285-034d-50c4-917d-797ab226db66")}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]="cb8b5583-b60f-52a5-802d-befc33f2a07b")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -807,9 +807,75 @@ export function validateManifest(payloadDir, hqVersion) {
             throw new Error('capabilities must be a list of strings');
         }
     }
+    // initialization (US-004) — OPTIONAL and backwards-compatible. Absent → fine
+    // (legacy packs). Present → the `entrypoint` is REQUIRED and MUST resolve to a
+    // declared `contributes.skills` or `contributes.commands` entry (this is the
+    // content-pack system, so entries are named under `contributes.*` — NOT the
+    // registry `exposes.*` system). The post-install initialization prompt is
+    // rendered/moderated in a later story; here we only validate shape so a
+    // malformed block can't slip through to install.
+    if (m.initialization !== undefined) {
+        const init = m.initialization;
+        if (!init || typeof init !== 'object' || Array.isArray(init)) {
+            throw new Error('initialization must be a mapping with an entrypoint');
+        }
+        const initObj = init;
+        const entrypoint = initObj.entrypoint;
+        if (typeof entrypoint !== 'string' || entrypoint.trim() === '') {
+            throw new Error('initialization.entrypoint is required and must be a non-empty string');
+        }
+        // Resolve the entrypoint against declared skills/commands. Normalize a
+        // leading slash on BOTH sides so `/email-assistant` matches a contributes
+        // entry named `email-assistant` and vice-versa.
+        const stripSlash = (s) => (s.startsWith('/') ? s.slice(1) : s);
+        const target = stripSlash(entrypoint.trim());
+        const declared = [
+            ...(contributes.skills ?? []),
+            ...(contributes.commands ?? []),
+        ];
+        const resolves = declared.some((d) => stripSlash(d) === target);
+        if (!resolves) {
+            throw new Error(`initialization.entrypoint "${entrypoint}" does not resolve to a declared ` +
+                `contributes.skills or contributes.commands entry. ` +
+                `Valid entries: ${declared.length ? declared.join(', ') : '(none declared)'}`);
+        }
+        // initialization.prompt — OPTIONAL. When present it must be a string ≤ 2000
+        // chars. (Rendering/moderation is a later story; we only validate type/length.)
+        if (initObj.prompt !== undefined) {
+            if (typeof initObj.prompt !== 'string') {
+                throw new Error('initialization.prompt must be a string');
+            }
+            if (initObj.prompt.length > 2000) {
+                throw new Error(`initialization.prompt must be ≤ 2000 characters (got ${initObj.prompt.length})`);
+            }
+        }
+    }
     return m;
 }
 // ---------------------------------------------------------------------------
+// Post-install get-started line (US-005)
+// ---------------------------------------------------------------------------
+/**
+ * Derive the safe, auto-generated "get started" line for a freshly installed
+ * pack from its `initialization.entrypoint` ONLY. PHASE 1 deliberately ignores
+ * the free-text `initialization.prompt` prose (rendering/moderation is a later
+ * story) so untrusted prose can't reach the operator's terminal.
+ *
+ * The command is slash-normalized to exactly one leading slash regardless of
+ * whether `entrypoint` was stored with or without one, matching the HQ Sync
+ * desktop render: ``Run `/email-assistant` to get started``.
+ *
+ * Returns `null` when there is no initialization block (backwards-compatible —
+ * the caller prints nothing extra).
+ */
+export function getStartedLine(initialization) {
+    const entrypoint = initialization?.entrypoint;
+    if (typeof entrypoint !== 'string' || entrypoint.trim() === '')
+        return null;
+    const command = '/' + entrypoint.trim().replace(/^\/+/, '');
+    return `Run \`${command}\` to get started`;
+}
+// ---------------------------------------------------------------------------
 // Hooks confirmation
 // ---------------------------------------------------------------------------
 async function confirmHooks(pkg, allowHooks) {
@@ -1070,10 +1136,18 @@ export async function installPack(source, opts = {}) {
         say(chalk.green(`\nOK Installed ${pkg.name}@${pkg.version} -> ${path.relative(hqRoot, destDir)}/`));
         say(chalk.dim(`  Wired ${Object.values(pkg.contributes).flat().filter(Boolean).length} ` +
             `contribution(s) into host-side paths.`));
+        // US-005 — when the pack declares an `initialization` block, print a safe,
+        // auto-generated "get started" line right after the success output. PHASE 1
+        // derives the line from `initialization.entrypoint` ONLY (never the
+        // free-text `initialization.prompt` prose), and matches the HQ Sync desktop
+        // wording for consistency. Absent block → nothing extra (backwards-compat).
+        const getStarted = getStartedLine(pkg.initialization);
+        if (getStarted)
+            say(chalk.cyan(getStarted));
     }
     finally {
         fs.rmSync(tmpDir, { recursive: true, force: true });
     }
 }
 //# sourceMappingURL=pack-install.js.map
-//# debugId=cbb11285-034d-50c4-917d-797ab226db66
+//# debugId=cb8b5583-b60f-52a5-802d-befc33f2a07b

package/dist/commands/packs.d.ts

@@ -18,5 +18,37 @@
  * Spec: knowledge/public/hq-core/package-yaml-spec.md.
  */
 import { Command } from 'commander';
+import { type InstalledPack, type LinkStatus } from '../utils/pack-contributions.js';
+import type { PackContributeKey } from '../types.js';
+interface InstalledPackView {
+    name: string;
+    version?: string;
+    publisher?: string;
+    source?: string;
+    transport: string | null;
+    requiresHqCore?: string;
+    hqCoreSatisfied: boolean | null;
+    contributes: Partial<Record<PackContributeKey, number>>;
+    links: Record<LinkStatus, number>;
+    brokenLinks: Array<{
+        key: PackContributeKey;
+        item: string;
+        dst: string;
+    }>;
+    inCatalog: boolean;
+    updateAvailable: boolean | null;
+    /**
+     * Post-install initialization (US-005). Present only when the pack's
+     * package.yaml declares an `initialization` block — drives the HQ Sync
+     * "Installed" panel get-started affordance. Absent → omitted (no null noise).
+     */
+    initialization?: {
+        entrypoint: string;
+        prompt?: string;
+    };
+    error?: string;
+}
+export declare function buildInstalledView(hqRoot: string, hqVersion: string | null, pack: InstalledPack, installedSources: Set<string>, checkUpdates: boolean): InstalledPackView;
 export declare function registerPacksCommand(parent: Command): void;
+export {};
 //# sourceMappingURL=packs.d.ts.map

package/dist/commands/packs.js

@@ -18,7 +18,7 @@
  * Spec: knowledge/public/hq-core/package-yaml-spec.md.
  */
 
-!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]="fa6cf3bf-90fa-5261-a15f-c8810e4b5615")}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]="527d0e7d-2101-5438-8251-2579a40453e6")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
@@ -61,7 +61,7 @@ async function confirm(question) {
     });
     return /^(y|yes)$/i.test(answer.trim());
 }
-function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpdates) {
+export function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpdates) {
     if (!pack.manifest) {
         return {
             name: pack.name,
@@ -97,6 +97,22 @@ function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpda
     if (checkUpdates && m.source) {
         updateAvailable = resolveLatest(m.source, m.version).updateAvailable;
     }
+    // US-005 — surface the pack's `initialization` block so the HQ Sync
+    // "Installed" panel can render its get-started affordance. `readPackManifest`
+    // already parses the full package.yaml, so `m.initialization` is available;
+    // we still shape it defensively (tolerate a malformed/absent block) and omit
+    // the field entirely when absent so the JSON carries no null noise.
+    let initialization;
+    const rawInit = m.initialization;
+    if (rawInit && typeof rawInit === 'object' && !Array.isArray(rawInit)) {
+        const initObj = rawInit;
+        const entrypoint = initObj.entrypoint;
+        if (typeof entrypoint === 'string' && entrypoint.trim() !== '') {
+            initialization = { entrypoint };
+            if (typeof initObj.prompt === 'string')
+                initialization.prompt = initObj.prompt;
+        }
+    }
     return {
         name: m.name ?? pack.name,
         version: m.version,
@@ -110,6 +126,7 @@ function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpda
         brokenLinks,
         inCatalog: m.source ? installedSources.has(m.source) : false,
         updateAvailable,
+        ...(initialization ? { initialization } : {}),
     };
 }
 function buildListView(hqRoot, checkUpdates, evalConditionals) {
@@ -408,4 +425,4 @@ export function registerPacksCommand(parent) {
     });
 }
 //# sourceMappingURL=packs.js.map
-//# debugId=fa6cf3bf-90fa-5261-a15f-c8810e4b5615
+//# debugId=527d0e7d-2101-5438-8251-2579a40453e6

package/dist/commands/people.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `hq people` — read a company's people (membership) records from the local HQ
+ * tree and search/resolve over them.
+ *
+ *   hq people list      [--company <slug>] [--json]
+ *   hq people search <keyword> [--company <slug>] [--json]
+ *   hq people resolve <name>   [--company <slug>] [--json]
+ *
+ * Source of truth is `companies/<company>/people/<person>/meta.yaml`. Every
+ * subcommand operates on exactly ONE company (the active company, or the one
+ * named by `--company`); nothing reads across company boundaries.
+ */
+import { Command } from "commander";
+/**
+ * Resolve the single company to operate on. Explicit `--company` always wins
+ * (after a path-safety check). Otherwise the active company is inferred from
+ * `companies/manifest.yaml`: if exactly one company exists it's used; if several
+ * do, the caller must disambiguate with `--company`.
+ */
+export declare function resolveCompanySlug(hqRoot: string, explicit: string | undefined): string;
+export declare function registerPeopleCommand(program: Command): void;
+//# sourceMappingURL=people.d.ts.map

package/dist/commands/people.js

@@ -0,0 +1,187 @@
+/**
+ * `hq people` — read a company's people (membership) records from the local HQ
+ * tree and search/resolve over them.
+ *
+ *   hq people list      [--company <slug>] [--json]
+ *   hq people search <keyword> [--company <slug>] [--json]
+ *   hq people resolve <name>   [--company <slug>] [--json]
+ *
+ * Source of truth is `companies/<company>/people/<person>/meta.yaml`. Every
+ * subcommand operates on exactly ONE company (the active company, or the one
+ * named by `--company`); nothing reads across company boundaries.
+ */
+
+!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]="076b7f64-6626-5733-8992-ab9361a3e31d")}catch(e){}}();
+import * as fs from "fs";
+import { Option } from "commander";
+import chalk from "chalk";
+import * as yaml from "js-yaml";
+import { findHqRoot } from "../utils/manifest.js";
+import { manifestPath } from "./cloud-provision.js";
+import { assertSafeCompanySlug, listCompanyPeople, searchPeople, resolveNameToEmail, companyPeopleDir, } from "../utils/people.js";
+/** Companies that still exist (anything not explicitly `status: archived`). */
+function activeCompanySlugs(manifest) {
+    const companies = manifest.companies ?? {};
+    return Object.entries(companies)
+        .filter(([, entry]) => (entry?.status ?? "active") !== "archived")
+        .map(([slug]) => slug)
+        .sort();
+}
+/**
+ * Resolve the single company to operate on. Explicit `--company` always wins
+ * (after a path-safety check). Otherwise the active company is inferred from
+ * `companies/manifest.yaml`: if exactly one company exists it's used; if several
+ * do, the caller must disambiguate with `--company`.
+ */
+export function resolveCompanySlug(hqRoot, explicit) {
+    if (explicit) {
+        assertSafeCompanySlug(explicit);
+        return explicit;
+    }
+    const mPath = manifestPath(hqRoot);
+    if (!fs.existsSync(mPath)) {
+        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 slugs = activeCompanySlugs(manifest ?? {});
+    if (slugs.length === 1)
+        return slugs[0];
+    if (slugs.length === 0) {
+        throw new Error("No companies found in companies/manifest.yaml — re-run with --company <slug>.");
+    }
+    throw new Error("Multiple companies found — re-run with --company <slug> to pick one:\n" +
+        slugs.map((s) => `  --company ${s}`).join("\n"));
+}
+/** Resolve the HQ root: explicit override (tests) → cwd walk-up. */
+function resolveHqRoot(opts) {
+    return opts.hqRoot ?? findHqRoot();
+}
+function printPeopleTable(people) {
+    const nameW = Math.max(4, ...people.map((p) => p.name.length));
+    const emailW = Math.max(5, ...people.map((p) => (p.email ?? "—").length));
+    const roleW = Math.max(4, ...people.map((p) => (p.role ?? "—").length));
+    console.log(chalk.bold([
+        "NAME".padEnd(nameW),
+        "EMAIL".padEnd(emailW),
+        "ROLE".padEnd(roleW),
+        "TYPE",
+    ].join("  ")));
+    for (const p of people) {
+        console.log([
+            p.name.padEnd(nameW),
+            (p.email ?? "—").padEnd(emailW),
+            (p.role ?? "—").padEnd(roleW),
+            p.type ?? "—",
+        ].join("  "));
+    }
+}
+function fail(message) {
+    console.error(chalk.red(message));
+    process.exit(1);
+}
+export function registerPeopleCommand(program) {
+    const people = program
+        .command("people")
+        .description("List, search, and resolve a company's people (from companies/<co>/people)")
+        .option("--company <slug>", "Company slug to scope to (defaults to the active company)")
+        // Hidden escape hatch for tests / non-standard layouts — point the reader at
+        // an explicit HQ tree root instead of walking up from cwd.
+        .addOption(new Option("--hq-root <path>", "Override the HQ tree root (advanced)").hideHelp());
+    people
+        .command("list")
+        .description("List all people recorded for the company")
+        .option("--json", "Output JSON instead of a table")
+        .action((opts) => {
+        try {
+            const scope = people.opts();
+            const hqRoot = resolveHqRoot(scope);
+            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const records = listCompanyPeople(hqRoot, slug);
+            if (opts.json) {
+                console.log(JSON.stringify(records, null, 2));
+                return;
+            }
+            if (records.length === 0) {
+                console.log(chalk.gray(`No people recorded for '${slug}' (looked in ${companyPeopleDir(hqRoot, slug)}).`));
+                return;
+            }
+            printPeopleTable(records);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+    people
+        .command("search <keyword>")
+        .description("Keyword search over people names and emails")
+        .option("--json", "Output JSON instead of a table")
+        .action((keyword, opts) => {
+        try {
+            const scope = people.opts();
+            const hqRoot = resolveHqRoot(scope);
+            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const matches = searchPeople(listCompanyPeople(hqRoot, slug), keyword);
+            if (opts.json) {
+                console.log(JSON.stringify(matches, null, 2));
+                return;
+            }
+            if (matches.length === 0) {
+                console.log(chalk.gray(`No people in '${slug}' match "${keyword}".`));
+                return;
+            }
+            printPeopleTable(matches);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+    people
+        .command("resolve <name>")
+        .description("Resolve a person name to their email address")
+        .option("--json", "Output JSON instead of plain text")
+        .action((name, opts) => {
+        try {
+            const scope = people.opts();
+            const hqRoot = resolveHqRoot(scope);
+            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const result = resolveNameToEmail(listCompanyPeople(hqRoot, slug), name);
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                if (result.status === "found")
+                    return;
+                process.exit(1);
+            }
+            switch (result.status) {
+                case "found":
+                    // Bare email on stdout so callers can capture it directly.
+                    console.log(result.email);
+                    return;
+                case "no_email":
+                    fail(`Found '${result.person.name}' in '${slug}' but no email is recorded for them.`);
+                    break;
+                case "ambiguous":
+                    console.error(chalk.yellow(`"${name}" matches ${result.matches.length} people in '${slug}' — be more specific:`));
+                    for (const m of result.matches) {
+                        console.error(`  ${m.name}${m.email ? ` <${m.email}>` : ""}`);
+                    }
+                    process.exit(1);
+                    break;
+                case "not_found":
+                    fail(`No person matching "${name}" found in '${slug}'.`);
+                    break;
+            }
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=people.js.map
+//# debugId=076b7f64-6626-5733-8992-ab9361a3e31d

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!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]="964b8c71-056c-51fb-893a-d51f8f6ad5d9")}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]="aeb143c7-7e19-5999-b6cb-790fc79034cc")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -36,6 +36,7 @@ import { registerGroupGrantsCommand } from "./commands/group-grants.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
+import { registerPeopleCommand } from "./commands/people.js";
 import { registerDmCommand } from "./commands/dm.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
@@ -134,6 +135,9 @@ const filesCmd = registerFilesCommand(program);
 registerFilesBrowseCommands(filesCmd);
 // Membership management (subcommand group — hq members invite|list|revoke)
 registerMembersCommand(program);
+// People directory (subcommand group — hq people list|search|resolve), reading
+// the local companies/<co>/people store scoped to one company.
+registerPeopleCommand(program);
 registerDmCommand(program);
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);
@@ -180,4 +184,4 @@ registerRescueCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=964b8c71-056c-51fb-893a-d51f8f6ad5d9
+//# debugId=aeb143c7-7e19-5999-b6cb-790fc79034cc

package/dist/types.d.ts

@@ -93,5 +93,15 @@ export interface PackManifest {
      * yet enforced.
      */
     capabilities?: string[];
+    /**
+     * Post-install initialization (US-004/US-005). Optional — absent on legacy
+     * packs. `entrypoint` names a declared `contributes.skills`/`commands` entry
+     * (slash-normalized); `prompt` is optional free-text prose (PHASE 1 does NOT
+     * render the prose — only an auto-generated get-started line from entrypoint).
+     */
+    initialization?: {
+        entrypoint: string;
+        prompt?: string;
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/utils/people.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Company people (membership) directory reader + search.
+ *
+ * The local source of truth for "who belongs to a company" is the per-company
+ * people store on disk:
+ *
+ *     companies/<company-slug>/people/<person-slug>/meta.yaml
+ *
+ * Each `meta.yaml` carries at least `name` and `type` ("internal" | "external")
+ * plus optional `email`, `role`, `organization`, `tags`, etc. (see
+ * `companies/_template/people/_example/meta.yaml` for the canonical schema).
+ *
+ * Everything here is scoped to ONE company directory. Callers resolve a single
+ * company slug up front; nothing in this module ever enumerates or reads across
+ * company boundaries — HQ tenancy rules forbid cross-company member lookups.
+ */
+/** A single person/member record parsed from a `people/<slug>/meta.yaml`. */
+export interface PersonRecord {
+    /** Folder slug under `companies/<company>/people/<slug>/`. */
+    slug: string;
+    /** Display name (required field in `meta.yaml`). */
+    name: string;
+    /** Contact email, when recorded. */
+    email?: string;
+    /** "internal" (team member) | "external" (client, vendor, …). */
+    type?: string;
+    /** Role/title inside (or relative to) the company. */
+    role?: string;
+    /** External-only: the person's own organization. */
+    organization?: string;
+    /** Freeform tags for filtering. */
+    tags?: string[];
+    /** Absolute path to the `meta.yaml` this record was parsed from. */
+    source: string;
+}
+export declare function assertSafeCompanySlug(slug: string): void;
+/** Absolute path to a company's `people/` directory. */
+export declare function companyPeopleDir(hqRoot: string, companySlug: string): string;
+/**
+ * Parse a single `meta.yaml` body into a `PersonRecord`. Returns `null` when the
+ * file is empty, unparseable, or has no usable `name` — a person record without
+ * a name can't be listed, searched, or resolved, so it's skipped rather than
+ * surfaced as a half-row. Exported for unit testing.
+ */
+export declare function parsePersonMeta(raw: string, slug: string, source: string): PersonRecord | null;
+/**
+ * List every person recorded for ONE company. Reads
+ * `companies/<companySlug>/people/<personSlug>/meta.yaml` for each person
+ * folder.
+ *
+ * - Folders whose name starts with `_` are skipped (e.g. the `_example`
+ *   template that ships in `companies/_template/people/`).
+ * - Folders without a `meta.yaml`, or whose `meta.yaml` has no `name`, are
+ *   skipped silently — they aren't members yet.
+ * - Returns `[]` when the company has no `people/` directory at all.
+ *
+ * Results are sorted by name (case-insensitive) for stable output.
+ */
+export declare function listCompanyPeople(hqRoot: string, companySlug: string): PersonRecord[];
+/**
+ * Case-insensitive keyword search over a person's NAME and EMAIL (plus the
+ * folder slug, which is a normalized alias of the name). Pure — operates on an
+ * already-loaded list so it's trivially testable and reusable.
+ *
+ * An empty/whitespace keyword matches nothing (callers should treat that as a
+ * usage error rather than "return everyone").
+ */
+export declare function searchPeople(people: PersonRecord[], keyword: string): PersonRecord[];
+/** Outcome of resolving a name to an email address. */
+export type ResolveResult = {
+    status: "found";
+    email: string;
+    person: PersonRecord;
+} | {
+    status: "no_email";
+    person: PersonRecord;
+} | {
+    status: "ambiguous";
+    matches: PersonRecord[];
+} | {
+    status: "not_found";
+};
+/**
+ * Resolve a person NAME to their email, built on top of {@link searchPeople}.
+ *
+ * Match precedence (narrowest first) so a precise query isn't drowned out by
+ * looser substring hits:
+ *   1. exact name match (case-insensitive, trimmed)
+ *   2. exact folder-slug match
+ *   3. substring search over name/email/slug
+ *
+ * The first tier that yields any match decides the result:
+ *   - exactly one match with an email  → `found`
+ *   - exactly one match, no email      → `no_email`
+ *   - more than one match              → `ambiguous` (caller disambiguates)
+ *   - no match in any tier             → `not_found`
+ */
+export declare function resolveNameToEmail(people: PersonRecord[], name: string): ResolveResult;
+//# sourceMappingURL=people.d.ts.map