@indigoai-us/hq-cli 5.47.14 → 5.47.16

package/dist/utils/people.js

@@ -0,0 +1,168 @@
+/**
+ * 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.
+ */
+
+!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]="aac5adc3-c336-5d9a-8a1a-edaf16ef4c11")}catch(e){}}();
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+/**
+ * Company slugs map directly onto a filesystem path segment, so we validate
+ * them before joining to keep a malicious or fat-fingered `--company` value
+ * from escaping the `companies/` tree. Mirrors the slug rules used by
+ * cloud-provision.
+ */
+const COMPANY_SLUG_REGEX = /^[A-Za-z0-9._-]+$/;
+const FORBIDDEN_COMPANY_SLUGS = new Set(["personal", ".", ".."]);
+export function assertSafeCompanySlug(slug) {
+    if (!slug || !COMPANY_SLUG_REGEX.test(slug)) {
+        throw new Error(`Invalid company slug "${slug}" — must match ${COMPANY_SLUG_REGEX.source}`);
+    }
+    if (FORBIDDEN_COMPANY_SLUGS.has(slug)) {
+        throw new Error(`Company slug "${slug}" is reserved and cannot be used here`);
+    }
+}
+/** Absolute path to a company's `people/` directory. */
+export function companyPeopleDir(hqRoot, companySlug) {
+    assertSafeCompanySlug(companySlug);
+    return path.join(hqRoot, "companies", companySlug, "people");
+}
+/**
+ * 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 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)}`);
+    }
+    if (!doc || typeof doc !== "object")
+        return null;
+    const d = doc;
+    const name = typeof d.name === "string" ? d.name.trim() : "";
+    if (!name)
+        return null;
+    const str = (v) => typeof v === "string" && v.trim() ? v.trim() : undefined;
+    const tags = Array.isArray(d.tags)
+        ? d.tags.filter((t) => typeof t === "string")
+        : undefined;
+    return {
+        slug,
+        name,
+        email: str(d.email),
+        type: str(d.type),
+        role: str(d.role),
+        organization: str(d.organization),
+        ...(tags && tags.length > 0 ? { tags } : {}),
+        source,
+    };
+}
+/**
+ * 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 function listCompanyPeople(hqRoot, companySlug) {
+    const dir = companyPeopleDir(hqRoot, companySlug);
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const people = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith("_"))
+            continue; // _example and other scaffolding
+        const metaPath = path.join(dir, entry.name, "meta.yaml");
+        if (!fs.existsSync(metaPath))
+            continue;
+        const raw = fs.readFileSync(metaPath, "utf-8");
+        const record = parsePersonMeta(raw, entry.name, metaPath);
+        if (record)
+            people.push(record);
+    }
+    people.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+    return people;
+}
+/**
+ * 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 function searchPeople(people, keyword) {
+    const needle = keyword.trim().toLowerCase();
+    if (!needle)
+        return [];
+    return people.filter((p) => {
+        const haystacks = [p.name, p.email, p.slug].filter((v) => typeof v === "string");
+        return haystacks.some((h) => h.toLowerCase().includes(needle));
+    });
+}
+/**
+ * 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 function resolveNameToEmail(people, name) {
+    const query = name.trim();
+    if (!query)
+        return { status: "not_found" };
+    const lowered = query.toLowerCase();
+    const exactName = people.filter((p) => p.name.toLowerCase() === lowered);
+    const exactSlug = people.filter((p) => p.slug.toLowerCase() === lowered);
+    const substring = searchPeople(people, query);
+    const matches = exactName.length > 0
+        ? exactName
+        : exactSlug.length > 0
+            ? exactSlug
+            : substring;
+    if (matches.length === 0)
+        return { status: "not_found" };
+    if (matches.length > 1)
+        return { status: "ambiguous", matches };
+    const person = matches[0];
+    if (!person.email)
+        return { status: "no_email", person };
+    return { status: "found", email: person.email, person };
+}
+//# sourceMappingURL=people.js.map
+//# debugId=aac5adc3-c336-5d9a-8a1a-edaf16ef4c11

package/package.json

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

package/src/commands/pack-install.test.ts

@@ -26,6 +26,7 @@ import {
   runScanPackages,
   stampInstallSource,
   validateManifest,
+  getStartedLine,
   toMarketplaceListing,
   fetchMarketplace,
   computeArtifactHash,
@@ -356,6 +357,218 @@ describe('pack-install: install path layout', () => {
     });
   });
 
+  // ---- 8. initialization.entrypoint validation (US-004) -------------------
+  // A pack may declare an `initialization` block whose `entrypoint` MUST resolve
+  // to a declared contributes skill/command. The block is OPTIONAL and
+  // backwards-compatible: legacy packs without it still validate. Slash
+  // normalization lets `/foo` match a contributes entry named `foo` (and v.v.).
+  describe('initialization.entrypoint (US-004)', () => {
+    // A valid pack that contributes one skill (`email-assistant`) and one
+    // command (`triage`), so an entrypoint can resolve to either. The only
+    // variable across these tests is the `initialization` block (extraYaml).
+    function writePackWithInit(extraYaml: string): string {
+      const dir = mkFakePackPayload({
+        'skills/email-assistant/SKILL.md': '# email assistant skill',
+        'commands/triage.md': '# triage command',
+      });
+      fs.writeFileSync(
+        path.join(dir, 'package.yaml'),
+        [
+          'name: hq-pack-test',
+          'version: 1.0.0',
+          "publisher: '@indigoai-us'",
+          'access: public',
+          'requires:',
+          "  hqCore: '>=12.0.0'",
+          'contributes:',
+          '  skills:',
+          '    - email-assistant',
+          '  commands:',
+          '    - triage',
+          extraYaml,
+          '',
+        ].join('\n'),
+      );
+      return dir;
+    }
+
+    it('accepts an entrypoint matching a contributes.skills entry', () => {
+      const dir = writePackWithInit(
+        ['initialization:', '  entrypoint: email-assistant'].join('\n'),
+      );
+      const m = validateManifest(dir, '12.0.0');
+      expect(m.name).toBe('hq-pack-test');
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('accepts a leading-slash entrypoint matching a no-slash contributes entry', () => {
+      const dir = writePackWithInit(
+        ['initialization:', '  entrypoint: /email-assistant'].join('\n'),
+      );
+      const m = validateManifest(dir, '12.0.0');
+      expect(m.name).toBe('hq-pack-test');
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('accepts a no-slash entrypoint matching a slashed contributes entry (vice-versa)', () => {
+      // Contributes declares `/onboard` (slashed); the entrypoint is `onboard`
+      // (no slash). The payload-file check computes `commands/${i}.md` which
+      // path.join normalizes (`commands//onboard.md` → `commands/onboard.md`),
+      // so a single `commands/onboard.md` file satisfies it.
+      const dir = mkFakePackPayload({
+        'commands/onboard.md': '# onboard command',
+      });
+      fs.writeFileSync(
+        path.join(dir, 'package.yaml'),
+        [
+          'name: hq-pack-test',
+          'version: 1.0.0',
+          "publisher: '@indigoai-us'",
+          'access: public',
+          'requires:',
+          "  hqCore: '>=12.0.0'",
+          'contributes:',
+          '  commands:',
+          '    - /onboard',
+          'initialization:',
+          '  entrypoint: onboard',
+          '',
+        ].join('\n'),
+      );
+      const m = validateManifest(dir, '12.0.0');
+      expect(m.name).toBe('hq-pack-test');
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('accepts an entrypoint matching a contributes.commands entry', () => {
+      const dir = writePackWithInit(
+        ['initialization:', '  entrypoint: triage'].join('\n'),
+      );
+      const m = validateManifest(dir, '12.0.0');
+      expect(m.name).toBe('hq-pack-test');
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('rejects an entrypoint that matches no contributes skill/command', () => {
+      const dir = writePackWithInit(
+        ['initialization:', '  entrypoint: does-not-exist'].join('\n'),
+      );
+      expect(() => validateManifest(dir, '12.0.0')).toThrow(
+        /initialization\.entrypoint.*does not resolve/,
+      );
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('rejects an initialization block with a missing entrypoint', () => {
+      const dir = writePackWithInit(
+        ['initialization:', '  prompt: hello'].join('\n'),
+      );
+      expect(() => validateManifest(dir, '12.0.0')).toThrow(
+        /initialization\.entrypoint is required/,
+      );
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('rejects an initialization block with an empty entrypoint', () => {
+      const dir = writePackWithInit(
+        ['initialization:', "  entrypoint: ''"].join('\n'),
+      );
+      expect(() => validateManifest(dir, '12.0.0')).toThrow(
+        /initialization\.entrypoint is required/,
+      );
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('accepts an initialization.prompt at the 2000-char limit', () => {
+      const dir = writePackWithInit(
+        [
+          'initialization:',
+          '  entrypoint: email-assistant',
+          `  prompt: '${'a'.repeat(2000)}'`,
+        ].join('\n'),
+      );
+      const m = validateManifest(dir, '12.0.0');
+      expect(m.name).toBe('hq-pack-test');
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('rejects an initialization.prompt longer than 2000 chars', () => {
+      const dir = writePackWithInit(
+        [
+          'initialization:',
+          '  entrypoint: email-assistant',
+          `  prompt: '${'a'.repeat(2001)}'`,
+        ].join('\n'),
+      );
+      expect(() => validateManifest(dir, '12.0.0')).toThrow(
+        /initialization\.prompt must be ≤ 2000 characters/,
+      );
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('rejects a non-string initialization.prompt', () => {
+      const dir = writePackWithInit(
+        ['initialization:', '  entrypoint: email-assistant', '  prompt: 42'].join('\n'),
+      );
+      expect(() => validateManifest(dir, '12.0.0')).toThrow(
+        /initialization\.prompt must be a string/,
+      );
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('a manifest WITHOUT an initialization block still validates (backwards-compatible)', () => {
+      const dir = writePackWithInit('');
+      const m = validateManifest(dir, '12.0.0');
+      expect(m.name).toBe('hq-pack-test');
+      expect((m as unknown as Record<string, unknown>).initialization).toBeUndefined();
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+  });
+
+  // ---- 8b. get-started line derivation (US-005) ---------------------------
+  // After a successful install, `installPack` prints a safe, auto-generated
+  // "get started" line derived from `initialization.entrypoint` ONLY (never the
+  // free-text prompt). The line matches the HQ Sync desktop wording and the
+  // command is normalized to exactly one leading slash. No initialization block
+  // → no extra line (backwards-compatible).
+  describe('getStartedLine (US-005)', () => {
+    it('renders a get-started line referencing the entrypoint', () => {
+      expect(getStartedLine({ entrypoint: 'email-assistant' })).toBe(
+        'Run `/email-assistant` to get started',
+      );
+    });
+
+    it('slash-normalizes an entrypoint already stored with a leading slash', () => {
+      expect(getStartedLine({ entrypoint: '/email-assistant' })).toBe(
+        'Run `/email-assistant` to get started',
+      );
+    });
+
+    it('collapses multiple leading slashes to exactly one', () => {
+      expect(getStartedLine({ entrypoint: '///triage' })).toBe(
+        'Run `/triage` to get started',
+      );
+    });
+
+    it('ignores the free-text prompt prose (PHASE 1 — entrypoint only)', () => {
+      const line = getStartedLine({
+        entrypoint: 'email-assistant',
+        prompt: 'do not surface this untrusted prose',
+      });
+      expect(line).toBe('Run `/email-assistant` to get started');
+      expect(line).not.toContain('untrusted');
+    });
+
+    it('returns null when there is no initialization block (prints nothing extra)', () => {
+      expect(getStartedLine(undefined)).toBeNull();
+    });
+
+    it('returns null for an empty/blank entrypoint', () => {
+      expect(getStartedLine({ entrypoint: '' })).toBeNull();
+      expect(getStartedLine({ entrypoint: '   ' })).toBeNull();
+    });
+  });
+
   it('stampInstallSource preserves a leading `---` document marker — no multi-doc YAML stream', () => {
     // Regression: prepending `source:` before a `---` would split the file
     // into two YAML documents, and single-doc `yaml.load` callers downstream

package/src/commands/pack-install.ts

@@ -1084,9 +1084,84 @@ export function validateManifest(
       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 as unknown;
+    if (!init || typeof init !== 'object' || Array.isArray(init)) {
+      throw new Error('initialization must be a mapping with an entrypoint');
+    }
+    const initObj = init as Record<string, unknown>;
+    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: string): string => (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 as PackManifest;
 }
 
+// ---------------------------------------------------------------------------
+// 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?: PackManifest['initialization'],
+): string | null {
+  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
 // ---------------------------------------------------------------------------
@@ -1452,6 +1527,13 @@ export async function installPack(
           `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 });
   }

package/src/commands/packs.test.ts

@@ -0,0 +1,88 @@
+/**
+ * packs list view tests — guards the machine-facing `hq packs list --json`
+ * shape consumed by the HQ Sync menubar app.
+ *
+ * US-005: `buildInstalledView` must surface a pack's `initialization` block so
+ * the desktop "Installed" panel can render its get-started affordance. The
+ * field is OPTIONAL — absent on legacy packs, in which case it is omitted from
+ * the view entirely (no null noise in the JSON).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildInstalledView } from './packs.js';
+import type {
+  InstalledPack,
+  InstalledPackManifest,
+} from '../utils/pack-contributions.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function fakeInstalledPack(
+  manifestOverrides: Partial<InstalledPackManifest>,
+): InstalledPack {
+  const manifest: InstalledPackManifest = {
+    name: 'hq-pack-test',
+    version: '1.0.0',
+    publisher: '@indigoai-us',
+    access: 'public',
+    requires: { hqCore: '>=12.0.0' },
+    contributes: { skills: ['email-assistant'] },
+    ...manifestOverrides,
+  } as InstalledPackManifest;
+  return {
+    name: 'hq-pack-test',
+    // A non-existent dir is fine — contributionLinks classifies missing links
+    // without throwing, and we never check updates (no network).
+    dir: '/tmp/does-not-exist/hq-pack-test',
+    manifest,
+  };
+}
+
+// `checkUpdates: false` keeps the call offline (no resolveLatest network hop).
+function build(pack: InstalledPack) {
+  return buildInstalledView('/tmp/does-not-exist', '12.0.0', pack, new Set(), false);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('buildInstalledView: initialization surfacing (US-005)', () => {
+  it('surfaces the initialization block when the pack declares one', () => {
+    const view = build(
+      fakeInstalledPack({
+        initialization: { entrypoint: 'email-assistant', prompt: 'hi there' },
+      }),
+    );
+    expect(view.initialization).toEqual({
+      entrypoint: 'email-assistant',
+      prompt: 'hi there',
+    });
+  });
+
+  it('surfaces initialization with no prompt (entrypoint only)', () => {
+    const view = build(
+      fakeInstalledPack({ initialization: { entrypoint: '/email-assistant' } }),
+    );
+    expect(view.initialization).toEqual({ entrypoint: '/email-assistant' });
+    expect(view.initialization).not.toHaveProperty('prompt');
+  });
+
+  it('omits the initialization field entirely when the pack declares none', () => {
+    const view = build(fakeInstalledPack({}));
+    expect(view.initialization).toBeUndefined();
+    expect(Object.prototype.hasOwnProperty.call(view, 'initialization')).toBe(false);
+  });
+
+  it('tolerates a malformed initialization block by omitting the field', () => {
+    const view = build(
+      fakeInstalledPack({
+        // An empty entrypoint is not a usable get-started target.
+        initialization: { entrypoint: '   ' },
+      }),
+    );
+    expect(view.initialization).toBeUndefined();
+  });
+});

package/src/commands/packs.ts

@@ -111,6 +111,12 @@ interface InstalledPackView {
   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;
 }
 
@@ -130,7 +136,7 @@ interface PacksListView {
   warnings: string[];
 }
 
-function buildInstalledView(
+export function buildInstalledView(
   hqRoot: string,
   hqVersion: string | null,
   pack: InstalledPack,
@@ -173,6 +179,22 @@ function buildInstalledView(
     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: InstalledPackView['initialization'];
+  const rawInit = m.initialization as unknown;
+  if (rawInit && typeof rawInit === 'object' && !Array.isArray(rawInit)) {
+    const initObj = rawInit as Record<string, unknown>;
+    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,
@@ -186,6 +208,7 @@ function buildInstalledView(
     brokenLinks,
     inCatalog: m.source ? installedSources.has(m.source) : false,
     updateAvailable,
+    ...(initialization ? { initialization } : {}),
   };
 }