@indigoai-us/hq-cli 5.47.14 → 5.47.15

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.47.14",
+  "version": "5.47.15",
   "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 } : {}),
   };
 }
 

package/src/schemas/hq-package.schema.json

@@ -132,6 +132,24 @@
           "minLength": 1
         }
       }
+    },
+    "initialization": {
+      "type": "object",
+      "description": "Optional post-install onboarding. `entrypoint` is the pack's primary get-started action (a skill or command that must resolve to one of this package's exposes.skills / exposes.commands entries); HQ surfaces a safe auto-generated 'get started' line from it after install. `prompt` is optional free-text the user can copy/paste into their agent to begin setup — treated as UNTRUSTED instruction text, surfaced only after marketplace injection-scan/moderation (suppressed for non-marketplace installs).",
+      "additionalProperties": false,
+      "properties": {
+        "entrypoint": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Primary get-started action — a skill or command name (with or without a leading slash) that must resolve to a declared exposes.skills / exposes.commands entry."
+        },
+        "prompt": {
+          "type": "string",
+          "maxLength": 2000,
+          "description": "Optional copy/paste setup prompt. Untrusted; surfaced only after moderation for marketplace packs, suppressed for local/git installs."
+        }
+      },
+      "required": ["entrypoint"]
     }
   }
 }

package/src/types.ts

@@ -117,4 +117,11 @@ 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 };
 }