refactor(cli): drop cli-manifest.json emit; cliEntries lives in skill-menu.json

The wizard now reads cliEntries from skill-menu.json at runtime — no
published consumer reads cli-manifest.json. The standalone file was
dead-on-arrival, so removing it now keeps the contract honest (one
file, one consumer).

generateCliManifest was producing a wrapped object solely for the
file write. Renamed to generateCliEntries, returns the entries array
directly. Caller embeds it under skill-menu.json's cliEntries.

CLAUDE.md and CONTRIBUTING.md updated to point contributors at the
new location.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarahxsanders

CLAUDE.md

@@ -18,7 +18,7 @@ User-facing intro: [README.md](README.md). Contributor handbook:
 | Build pipeline | `scripts/lib/` (skill generator, build phases, change router) |
 | Build entrypoints | `scripts/build.js` (full) and `scripts/dev-server.js` (partial / watch) |
 | Tests | `scripts/lib/tests/` and `scripts/plugins/tests/` (vitest) |
-| Manifest output | `dist/skills/manifest.json`, `dist/skills/cli-manifest.json`, `dist/skills/skill-menu.json` |
+| Manifest output | `dist/skills/manifest.json`, `dist/skills/skill-menu.json` (CLI entries live under `cliEntries`) |
 | Per-skill ZIPs | `dist/skills/<id>.zip` |
 
 ## The `cli:` block (read [CONTRIBUTING.md](CONTRIBUTING.md) before editing)
@@ -62,10 +62,11 @@ abstraction. Restructure to a family when a second vendor lands. See
 1. Read [CONTRIBUTING.md § Promotion criterion for `role: command`](CONTRIBUTING.md#promotion-criterion-for-role-command).
 2. Run `npm test` — the parser's test suite (`scripts/lib/tests/cli-block.test.js`)
    covers every naming-convention case.
-3. Run `npm run build` — confirm the entry appears (or disappears) in
-   `dist/skills/cli-manifest.json` with the values you expect.
-4. The wizard's next release picks up the change automatically. No wizard
-   PR needed unless the change requires wizard-side hooks (custom outro,
+3. Run `npm run build` — confirm the entry appears (or disappears) under
+   `cliEntries` inside `dist/skills/skill-menu.json` with the values you
+   expect.
+4. The wizard resolves new entries at runtime, so no wizard release is
+   required unless the change needs wizard-side hooks (custom outro,
    content blocks, abort cases).
 5. **Flag the wizard maintainer:** the wizard ships a committed
    `docs/cli.md` auto-generated from the manifest. When the wizard

CONTRIBUTING.md

@@ -9,9 +9,10 @@ manifest, see the [README](README.md).
 Every skill ships with a `config.yaml`. An optional `cli:` block on that
 config tells the PostHog wizard whether and how this skill appears as a
 command. The block is parsed in `scripts/lib/skill-generator.js` and
-emitted into `dist/skills/cli-manifest.json` alongside the regular
-manifest. The wizard snapshots that file at build time and turns each
-entry into a registered command.
+emitted as `cliEntries` inside `dist/skills/skill-menu.json`. The wizard
+fetches `skill-menu.json` at runtime and registers each entry as a
+command, so adding a new skill-backed command is a context-mill release
+— no wizard release needed.
 
 ### The `cli:` block schema
 
@@ -199,9 +200,10 @@ When you've decided your skill meets the `role: command` criterion:
 1. Add the `cli:` block to the skill's `config.yaml` with `role:
    command`, the right `parentCommand` (if it nests under an existing
    family), and `command`.
-2. Confirm `npm run build` emits the entry in
-   `dist/skills/cli-manifest.json` with the right `parentCommand` /
-   `command` values. The wizard's next release picks it up automatically.
+2. Confirm `npm run build` emits the entry under `cliEntries` inside
+   `dist/skills/skill-menu.json` with the right `parentCommand` /
+   `command` values. The wizard picks it up on its next invocation
+   (no wizard release needed).
 3. No wizard PR is needed for skill-backed public commands. If you also
    need wizard-side hooks (custom outro, content blocks, abort cases),
    that's a wizard PR — but the CLI registration is handled by the
@@ -239,7 +241,7 @@ manifest is published before the wizard tries to consume it.
 
 - Skill schema details: `scripts/lib/skill-generator.js`
   (`parseCliBlock`, `expandSkillGroups`, JSDoc typedef for the `cli:` block)
-- CLI manifest emit: `scripts/lib/build-phases.js` (`generateCliManifest`)
+- CLI entries emit: `scripts/lib/build-phases.js` (`generateCliEntries`)
 - Tests for the cli block parser: `scripts/lib/tests/cli-block.test.js`
 - The wizard's side of the contract: [PostHog/wizard CONTRIBUTING.md](https://github.com/PostHog/wizard/blob/main/CONTRIBUTING.md)
 

scripts/lib/build-phases.js

@@ -195,27 +195,23 @@ function writeManifestAndMenu({ allSkills, docContents, distDir, configDir, vers
     // The CLI entries are the lookup table the wizard's runtime resolver uses
     // (parentCommand + command -> skillId). They live inside skill-menu.json
     // so the wizard can reach them through the existing fetchSkillMenu path.
-    // cli-manifest.json still ships with the same array under `entries` for
-    // back-compat with the still-baked older wizard; it's slated for removal
-    // once that wizard release ages out.
-    const cliManifest = generateCliManifest({ allSkills, manifest });
+    const cliEntries = generateCliEntries({ allSkills });
 
     const skillMenu = {
         version: manifest.version,
         buildVersion: manifest.buildVersion,
         categories: skillsByCategory,
-        cliEntries: cliManifest.entries,
+        cliEntries,
     };
     fs.writeFileSync(path.join(skillsDir, 'skill-menu.json'), JSON.stringify(skillMenu, null, 2));
 
-    fs.writeFileSync(path.join(skillsDir, 'cli-manifest.json'), JSON.stringify(cliManifest, null, 2));
-
     return manifest;
 }
 
 /**
- * Build the CLI manifest object from the expanded skill list. Used by
- * `writeManifestAndMenu` and exercised directly by tests. Throws on an
+ * Build the CLI entries array from the expanded skill list. Used by
+ * `writeManifestAndMenu` (which embeds the result in `skill-menu.json`
+ * under `cliEntries`) and exercised directly by tests. Throws on an
  * invalid `recommended:` arrangement (see `validateRecommended`) so the
  * build fails before bad data reaches the wizard.
  *
@@ -227,10 +223,10 @@ function writeManifestAndMenu({ allSkills, docContents, distDir, configDir, vers
  *   { skillId, role, command?, parentCommand?, recommended?, displayName, description }
  *
  * Entries are sorted by role (command first, then skill, then internal),
- * then by `parentCommand`/`command` so diffs in `cli-manifest.json` stay
+ * then by `parentCommand`/`command` so diffs in `skill-menu.json` stay
  * reviewable.
  */
-function generateCliManifest({ allSkills, manifest }) {
+function generateCliEntries({ allSkills }) {
     const roleOrder = { command: 0, skill: 1, internal: 2 };
     const entries = allSkills
         .filter(s => s.cli)
@@ -254,17 +250,7 @@ function generateCliManifest({ allSkills, manifest }) {
             return (a.command || '').localeCompare(b.command || '');
         });
     validateRecommended(entries);
-    return {
-        // `version` is shared with the main manifest (it's uri-schema.yaml's
-        // `manifest_version`). There's no CLI-manifest-only version knob —
-        // bumping it bumps both manifests' version. If the CLI manifest shape
-        // ever needs to change independently of the main manifest, give it its
-        // own version field rather than reusing this one.
-        version: manifest.version,
-        buildVersion: manifest.buildVersion,
-        buildTimestamp: manifest.buildTimestamp,
-        entries,
-    };
+    return entries;
 }
 
 /**
@@ -379,7 +365,7 @@ export {
     zipSkillToBuffer,
     createBundledArchive,
     generateManifest,
-    generateCliManifest,
+    generateCliEntries,
     writeManifestAndMenu,
     reconcileOrphans,
     partialRebuild,

scripts/lib/tests/cli-block.test.js

@@ -9,7 +9,7 @@ import {
     expandSkillGroups,
     serializeSkill,
 } from '../skill-generator.js';
-import { generateCliManifest } from '../build-phases.js';
+import { generateCliEntries } from '../build-phases.js';
 
 function createFixture(tree, baseDir) {
     for (const [name, content] of Object.entries(tree)) {
@@ -293,43 +293,31 @@ describe('expandSkillGroups with cli blocks', () => {
     });
 });
 
-describe('generateCliManifest', () => {
-    const baseManifest = {
-        version: '1.0',
-        buildVersion: 'test',
-        buildTimestamp: '2026-06-08T00:00:00.000Z',
-    };
-
+describe('generateCliEntries', () => {
     it('emits only skills with a cli block', () => {
         const skills = [
             { id: 'integration-django', displayName: 'Django', description: 'd' },
             { id: 'audit-events', displayName: 'Audit events', description: 'a',
               cli: { role: 'command', parentCommand: 'audit', command: 'events' } },
         ];
-        const manifest = generateCliManifest({ allSkills: skills, manifest: baseManifest });
-        expect(manifest.entries).toHaveLength(1);
-        expect(manifest.entries[0].skillId).toBe('audit-events');
+        const entries = generateCliEntries({ allSkills: skills });
+        expect(entries).toHaveLength(1);
+        expect(entries[0].skillId).toBe('audit-events');
     });
 
-    it('carries version + buildVersion + buildTimestamp through', () => {
-        const manifest = generateCliManifest({ allSkills: [], manifest: baseManifest });
-        expect(manifest).toMatchObject({
-            version: '1.0',
-            buildVersion: 'test',
-            buildTimestamp: '2026-06-08T00:00:00.000Z',
-            entries: [],
-        });
+    it('returns an empty array when no skills declare a cli block', () => {
+        const entries = generateCliEntries({ allSkills: [] });
+        expect(entries).toEqual([]);
     });
 
     it('omits command and parentCommand when not set on the cli block', () => {
-        const manifest = generateCliManifest({
+        const entries = generateCliEntries({
             allSkills: [
                 { id: 'doctor', displayName: 'Doctor', description: 'd',
                   cli: { role: 'skill' } },
             ],
-            manifest: baseManifest,
         });
-        expect(manifest.entries[0]).toEqual({
+        expect(entries[0]).toEqual({
             skillId: 'doctor',
             role: 'skill',
             displayName: 'Doctor',
@@ -338,7 +326,7 @@ describe('generateCliManifest', () => {
     });
 
     it('sorts entries by role, then parentCommand, then command', () => {
-        const manifest = generateCliManifest({
+        const entries = generateCliEntries({
             allSkills: [
                 { id: 'b-skill', displayName: 'B', description: 'd', cli: { role: 'skill' } },
                 { id: 'a-int', displayName: 'A', description: 'd', cli: { role: 'internal' } },
@@ -349,22 +337,20 @@ describe('generateCliManifest', () => {
                 { id: 'revenue', displayName: 'R', description: 'd',
                   cli: { role: 'command', command: 'revenue' } },
             ],
-            manifest: baseManifest,
         });
-        const order = manifest.entries.map(e => e.skillId);
+        const order = entries.map(e => e.skillId);
         // command flat (no parent) sorts before grouped 'audit', then skill, then internal
         expect(order).toEqual(['revenue', 'audit-all', 'audit-events', 'b-skill', 'a-int']);
     });
 
     it('carries recommended:true through into the entry', () => {
-        const manifest = generateCliManifest({
+        const entries = generateCliEntries({
             allSkills: [
                 { id: 'audit-all', displayName: 'Audit', description: 'd',
                   cli: { role: 'command', parentCommand: 'audit', command: 'all', recommended: true } },
             ],
-            manifest: baseManifest,
         });
-        expect(manifest.entries[0]).toMatchObject({
+        expect(entries[0]).toMatchObject({
             skillId: 'audit-all',
             parentCommand: 'audit',
             command: 'all',
@@ -374,26 +360,24 @@ describe('generateCliManifest', () => {
 
     it('throws when a family has more than one recommended leaf', () => {
         expect(() =>
-            generateCliManifest({
+            generateCliEntries({
                 allSkills: [
                     { id: 'audit-all', displayName: 'A', description: 'd',
                       cli: { role: 'command', parentCommand: 'audit', command: 'all', recommended: true } },
                     { id: 'audit-events', displayName: 'AE', description: 'd',
                       cli: { role: 'command', parentCommand: 'audit', command: 'events', recommended: true } },
                 ],
-                manifest: baseManifest,
             }),
         ).toThrow(/Family "audit" has more than one cli\.recommended leaf/);
     });
 
     it('throws when recommended is set on a flat command with no parentCommand', () => {
         expect(() =>
-            generateCliManifest({
+            generateCliEntries({
                 allSkills: [
                     { id: 'revenue', displayName: 'R', description: 'd',
                       cli: { role: 'command', command: 'revenue', recommended: true } },
                 ],
-                manifest: baseManifest,
             }),
         ).toThrow(/only valid on a leaf inside a family/);
     });