Merge: wire api-docs into the adopter surface (default-on scaffold + agent pointer)

The last-mile fixes from the staff review: api-docs is now in the default
meta init scaffold (every new TS project generates docs/api/), and the
metaobjects-codegen skill's TS reference points a coding agent at
docs/api/AGENT-API.md ('read it before calling generated code'). Pointer is
stack-scoped (TS-only, where api-docs runs) to stay accurate — extends when
api-docs fans out to other ports. Agent-context conformance fixtures regenerated;
all agent-context gates green.

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

Author: dmealing

agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -55,6 +55,12 @@ From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
 | `barrel()` | `index.ts` re-exporting each `<Entity>.ts` (one-shot, not per-entity) |
 | `promptRender()` | `render<Name>()` per `template.prompt` |
 | `outputParser()` | `<Name>.output.ts` (`parse*` / `safeParse*`) per `template.output` |
+| `apiDocsFile()` | `docs/api/<Entity>.md` + `docs/api/README.md` index + `docs/api/AGENT-API.md` (condensed agent-facing API reference) |
+
+When `apiDocsFile()` is enabled (it is in the default scaffold), **read
+`docs/api/AGENT-API.md` before calling any generated code** — it has the exact
+imports, function signatures, payload field shapes, and runnable examples for this
+project's generated API, so you don't have to guess them.
 
 From `@metaobjectsdev/codegen-ts-react`: `formFile()` → `<Entity>.form.tsx`.
 From `@metaobjectsdev/codegen-ts-tanstack`: `tanstackQuery()` → `<Entity>.hooks.ts`

fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-codegen/references/typescript.md

@@ -55,6 +55,12 @@ From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
 | `barrel()` | `index.ts` re-exporting each `<Entity>.ts` (one-shot, not per-entity) |
 | `promptRender()` | `render<Name>()` per `template.prompt` |
 | `outputParser()` | `<Name>.output.ts` (`parse*` / `safeParse*`) per `template.output` |
+| `apiDocsFile()` | `docs/api/<Entity>.md` + `docs/api/README.md` index + `docs/api/AGENT-API.md` (condensed agent-facing API reference) |
+
+When `apiDocsFile()` is enabled (it is in the default scaffold), **read
+`docs/api/AGENT-API.md` before calling any generated code** — it has the exact
+imports, function signatures, payload field shapes, and runnable examples for this
+project's generated API, so you don't have to guess them.
 
 From `@metaobjectsdev/codegen-ts-react`: `formFile()` → `<Entity>.form.tsx`.
 From `@metaobjectsdev/codegen-ts-tanstack`: `tanstackQuery()` → `<Entity>.hooks.ts`

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

@@ -34,6 +34,7 @@ import {
   routesFile,
   // formFile,        // opt-in: emit React form components
   barrel,
+  apiDocsFile,
 } from "@metaobjectsdev/codegen-ts/generators";
 
 export default defineConfig({
@@ -47,6 +48,7 @@ export default defineConfig({
     queriesFile(),
     routesFile(),
     barrel(),
+    apiDocsFile(),
   ],
 });
 `;

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

@@ -18,6 +18,7 @@ describe("meta init scaffolds metaobjects.config.ts", () => {
     expect(body).toContain(`queriesFile()`);
     expect(body).toContain(`routesFile()`);
     expect(body).toContain(`barrel()`);
+    expect(body).toContain(`apiDocsFile()`);
     expect(result.created).toContain("metaobjects.config.ts");
   });