feat(cli): surface meta docs as a next-step command (not a meta gen generator)

Discoverability fix for the PM review's gap: neutral metadata docs were undiscoverable. The architecturally-correct fix per ADR-0021 D1 is NOT to add docsFile() to the metaobjects.config.ts generators array (docsFile() is @deprecated for meta gen — it is the internal engine of the `meta docs` command, the single door for neutral docs). Instead, surface `meta docs` in the init next-steps block + add a guard test that the scaffold does not route neutral docs through meta gen. apiDocsFile() (Tier-1 SDK reference) stays in the generators array; its comment now points at `meta docs` for neutral docs.

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

Author: dmealing

server/typescript/packages/cli/src/commands/init.ts

@@ -48,7 +48,7 @@ export default defineConfig({
     queriesFile(),
     routesFile(),
     barrel(),
-    apiDocsFile(),
+    apiDocsFile(),  // SDK/API reference -> <outDir>/docs/api/ (for neutral model docs, run: meta docs)
   ],
 });
 `;
@@ -60,6 +60,7 @@ Initialized metaobjects/ + .metaobjects/ + metaobjects.config.ts
 Next steps (when later sub-projects ship):
   meta ingest        # propose entities from your existing TS code
   meta gen           # codegen TS targets from entities
+  meta docs          # neutral model docs (entity + template pages, incl. linked template source)
   meta serve         # local viewer
   meta install-hooks # register MCP server + Claude Code hooks
 `;

server/typescript/packages/cli/test/unit/init-scaffold-config.test.ts

@@ -2,7 +2,7 @@ import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { init } from "../../src/commands/init.js";
+import { init, nextStepsBlock } from "../../src/commands/init.js";
 
 let tmp: string;
 beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), "forge-init-")); });
@@ -22,6 +22,18 @@ describe("meta init scaffolds metaobjects.config.ts", () => {
     expect(result.created).toContain("metaobjects.config.ts");
   });
 
+  test("does NOT route neutral docs through meta gen (ADR-0021 D1: meta docs is the single door)", async () => {
+    // docsFile() is the INTERNAL engine of the `meta docs` command, not a `meta gen`
+    // config generator. Scaffolding it into metaobjects.config.ts would resurrect the
+    // exact second-door the @deprecated note on docsFile() forbids. Discoverability of
+    // neutral docs is via the `meta docs` command (surfaced in the next-steps block),
+    // not the generators array.
+    await init({ cwd: tmp, quiet: true });
+    const body = readFileSync(join(tmp, "metaobjects.config.ts"), "utf-8");
+    expect(body).not.toContain("docsFile");
+    expect(nextStepsBlock()).toContain("meta docs");
+  });
+
   test("does not overwrite an existing metaobjects.config.ts on subsequent runs", async () => {
     await init({ cwd: tmp, quiet: true });
     const before = readFileSync(join(tmp, "metaobjects.config.ts"), "utf-8");