Merge: polyglot docs composition (SP-1) — per-language apiSurfaces, model once (ADR-0027)

meta docs now declares api surfaces as a per-language list (docs.apiSurfaces:
[{lang,subDir,baseUrl?}]); the model page links every declared surface
(API reference: [TypeScript] · [Java]) via apiSurfaceHref (relative in one tree,
absolute when a surface sets baseUrl). meta docs emits the surfaces this port
owns (lang=ts) + links all declared; other ports' surfaces are produced by their
own docs command (SP-2 adds Java). Model docs stay a single shared engine — no
per-language duplication.

Also relocates the TS-only docs-gate fixtures (template-source-conformance{,-package})
out of the shared cross-port fixtures/conformance/ corpus into a TS-package-local
dir, so cross-port harnesses stop globbing input-only fixtures.

ADR-0027 records the composition contract (extends ADR-0025). TS built now; the
apiSurfaces schema + cross-link contract are the cross-port contract for SP-2.

Author: dmealing

docs/superpowers/plans/2026-06-06-polyglot-docs-composition.md

@@ -0,0 +1,121 @@
+# Polyglot docs composition (SP-1) — design
+
+**Date:** 2026-06-06
+**Status:** Design (pending review)
+**Relates to:** ADR-0025 (unified docs door — this implements its multi-language direction). This is **SP-1** of a two-part program; **SP-2** (the Java api surface + a real TS+Java end-to-end conformance) follows in its own spec.
+
+## Goal
+
+Let a **polyglot solution** (e.g. TypeScript + Java over the same meta models) produce ONE coherent doc tree: the **model docs generated once** (shared, language-independent) + **one api surface per language** (idiomatic SDK reference), all **cross-linked**. SP-1 builds the TS-side composition + the contract; it is TS-only today but lays the exact shape the Java api surface (SP-2) plugs into. No model-doc duplication across languages.
+
+## Research basis (why this shape)
+
+Tools that do precisely "one neutral model → many idiomatic language outputs" converge on **an explicit list of per-language targets, each with its own output dir, in one build config**:
+- **buf** `buf.gen.yaml` lists `plugins[]`, each with its own `out:` per language; "managed mode" keeps the schema neutral while per-consumer options live in config.
+- **Smithy** `smithy-build.json` declares multiple projections + plugins (`<language>-<type>-codegen`) from one model.
+- **Backstage TechDocs** aggregates many components via a manifest (`catalog-info.yaml`) — but that is a *portal/federation layer ABOVE* per-project generation.
+
+**Decision:** an **explicit per-language `apiSurfaces[]` list in the `docs:` config** (the buf/Smithy pattern, and consistent with our own `generators[]`/`targets{}`). The Backstage-style **manifest is deferred** (YAGNI); we keep the internal resolver consuming a *source-agnostic resolved surface list* so a multi-repo manifest can feed the same contract later without reworking the generators.
+
+## Scope
+
+- **Build now (TS):** the `apiSurfaces[]` config, the model-page→**set-of-api-surfaces** links, per-language api subdirs, relative-or-`baseUrl` cross-link bases, the emit/skip behavior of `meta docs`, and a conformance gate proving a one-tree, **N-api-surface** layout (using a simulated second surface). 
+- **Contract (designed, not built here):** the surface declaration + cross-link path contract that SP-2's Java api surface will emit into.
+- **Out of scope:** the Java api surface itself (SP-2); the federation manifest path (deferred); the non-TS model-engine reach (still deferred per ADR-0025 — *not needed* for a polyglot solution, since the model docs come from the TS toolchain once).
+- **Fixture hygiene (in scope):** SP-1 fixtures live **TS-package-local**, NOT in the shared `fixtures/conformance/` corpus; and SP-1 **relocates the existing `template-source-conformance` + `template-source-conformance-package` fixtures out of the shared corpus** (see "Fixture placement" below).
+
+## Design
+
+### 1. Config: `apiSurfaces[]` is the canonical api-target list
+
+> **No backwards compatibility required** — the docs door is unreleased / unused, so SP-1 replaces the single-api notion outright rather than carrying a dual path. Goldens update once to the new shape; there is no "byte-identical default" constraint.
+
+Extend `DocsConfig` (`packages/codegen-ts/src/metaobjects-config.ts`):
+```ts
+export interface ApiSurface {
+  lang: string;        // "ts" | "java" | … (free string; label derived)
+  subDir: string;      // e.g. "api/ts"; per-language output sub-root under outDir
+  baseUrl?: string;    // when set, cross-links to THIS surface are absolute (federated)
+}
+export interface DocsConfig {
+  outDir?: string; layout?: OutputLayout; baseUrl?: string;
+  surfaces?: DocsSurface[];          // model/api on-off selector (drives --model/--api)
+  apiSurfaces?: ApiSurface[];        // the api targets; default [{ lang:"ts", subDir:"api" }]
+}
+```
+- `apiSurfaces` is **the** api-target list. The model page links to every entry; each language's `docs` command emits the surface whose `lang` it owns into that entry's `subDir`. The TS api surface is just `{ lang:"ts", subDir:"api" }` in that list (no special single-surface path).
+- `resolveDocsConfig` resolves `apiSurfaces` (default the single TS entry) into one `ResolvedDocsConfig.apiSurfaces` list — the source-agnostic seam a future manifest can also feed.
+- `surfaces` stays only as the model/api on-off selector (CLI `--model`/`--api`); whether the api side emits = `"api" ∈ surfaces && apiSurfaces` non-empty.
+
+### 2. Model page links to the SET of api surfaces
+
+The model entity page's single `apiPageHref` is **replaced** by `apiRefs: { label: string; href: string }[]` (one rendering path, no special-case):
+- rendered as `**API reference:** [TypeScript](api/ts/Order.md) · [Java](api/java/Order.md)`; a single-entry list renders one labeled link.
+- `label` from a small `lang → label` map (`ts`→`TypeScript`, `java`→`Java`, `kotlin`→`Kotlin`, `csharp`→`C#`, `python`→`Python`; unknown → the `lang` verbatim, capitalized).
+
+### 3. Cross-link base: relative (one tree) or `baseUrl` (federated)
+
+A helper computes each cross-link from the emitting page to a target surface page:
+- if the **target surface has no `baseUrl`** → relative path via the shared `surfaceCrossHref(fromOutputPath, `${subDir}/${page}`)` (Option A, one tree).
+- if the **target surface has a `baseUrl`** → `${baseUrl}/${page}` (Option B, federated/multi-repo).
+- the api→model link mirrors this using the model surface's own base (relative by default, or `docs.baseUrl` if the model docs are published separately).
+
+This makes A and B the same code path, differing only by whether a `baseUrl` is set — exactly the "build A, get B by config" decision.
+
+### 4. Who emits what (and the honest note)
+
+`meta docs` (TS):
+- emits the **model** surface once (when `model` ∈ surfaces),
+- emits **only the api surface whose `lang` this port generates** (`ts`) into its `subDir`,
+- renders model→links for **all** declared `apiSurfaces` (so the model page is solution-complete),
+- if a declared surface (e.g. `java`) is NOT emitted by this command, prints a one-line note: `meta docs: declared api surface 'java' (api/java) is produced by that port's docs command — run it to populate those pages.`
+
+The other languages' api pages are produced by their own port commands into the same tree (SP-2). In a federated setup they're produced in their own repos and linked by `baseUrl`.
+
+### 5. Conformance gate (TS-local fixtures)
+
+Because one command cannot emit another language's pages, the gate emits **all declared surfaces together** to prove integrity:
+- a fixture declares ≥2 `apiSurfaces` (e.g. `ts` + a **simulated second** surface standing in for `java` — produced by running the api engine again under a second `subDir`/label);
+- emit model + both api surfaces; assert every model→api link (one per surface) and every api→model link resolves to a real emitted page, in **flat AND package** layouts (extends the existing `docs-cross-link-conformance` pattern);
+- include a `baseUrl` case asserting a surface with `baseUrl` produces absolute links (and is therefore NOT expected in the local tree);
+- a teeth unit proving the checker flags a missing target.
+
+### 6. No back-compat constraint
+
+The docs door is unreleased, so SP-1 need not preserve current output. The model/api page goldens update **once** to the new `apiRefs` shape (the default single TS surface now renders `**API reference:** [TypeScript](api/Order.md)`). One rendering path; no dual single-vs-list special case.
+
+## Fixture placement (fixes a cross-port landmine)
+
+The shared `fixtures/conformance/` corpus is globbed by **cross-port** harnesses (C# conformance tests, the metadata-conformance bin that writes `expected.json` per fixture, etc.) that expect each case to carry cross-port expectations. The docs gates' fixtures (`template-source-conformance`, `template-source-conformance-package`) are **TS-implementation-test inputs** (input-only, no cross-port expectations) and currently sit in that shared corpus — tripping those harnesses ("no expectation files"). SP-1:
+- places its OWN fixtures **TS-package-local** (e.g. `packages/codegen-ts/test/fixtures/docs/…`), not in the shared corpus; and
+- **relocates `template-source-conformance` + `template-source-conformance-package`** out of `fixtures/conformance/` into the same TS-local home, updating the `CORPUS`/`FIXTURE` constants in the TS gates that reference them.
+
+This removes the existing red and prevents SP-1 from adding more shared-corpus landmines. (Verify against the actually-failing port harness during implementation; the relocation must leave all TS docs gates green and stop the cross-port harnesses from globbing these input-only dirs.)
+
+## ADR
+
+A new ADR (next free number, ~ADR-0026) records the **polyglot docs composition contract**: model-once + per-language `apiSurfaces[]` (explicit-list, buf/Smithy-aligned), cross-link base relative-or-`baseUrl`, the deferred manifest/federation path, and the per-port-command/shared-model-engine principle inherited from ADR-0025. Add a pointer line from ADR-0025.
+
+## File structure (TS)
+
+- `packages/codegen-ts/src/metaobjects-config.ts` — `ApiSurface` type, `apiSurfaces` on `DocsConfig`/`ResolvedDocsConfig`, resolution in `resolveDocsConfig`.
+- `packages/codegen-ts/src/docs-paths.ts` — a cross-link-base helper (relative-or-baseUrl) over `surfaceCrossHref`.
+- `packages/codegen-ts/src/generators/docs-file.ts` + the entity doc-data builder + `templates/docs/entity-page.md.mustache` — `apiRefs[]` (generalize `apiPageHref`), the multi-link section (synced + byte-gated).
+- `packages/cli/src/commands/docs.ts` — resolve `apiSurfaces`; emit the owned api surface(s); render all declared links; the skip note.
+- `packages/codegen-ts/test/fixtures/docs/…` — relocated + new TS-local fixtures.
+- `packages/codegen-ts/test/golden/docs-cross-link-conformance.test.ts` (+ a new multi-surface gate) — N-surface integrity, flat+package+baseUrl+teeth; updated `CORPUS` paths.
+- `spec/decisions/ADR-0026-*.md` — the contract.
+
+## Testing / gates
+
+- `resolveDocsConfig` resolves `apiSurfaces` (config → resolved list); absent → single-surface default.
+- multi-surface cross-link integrity (flat + package), baseUrl federation case, teeth.
+- the default single-TS-surface case renders the `apiRefs` shape; goldens updated once to it.
+- all TS docs gates green after fixture relocation; the shared-corpus cross-port harnesses no longer glob the docs input-only fixtures.
+
+## YAGNI / non-goals
+
+- No Java (or other) api surface emit — that is SP-2.
+- No federation manifest path — deferred; only the source-agnostic seam.
+- No non-TS model-engine reach — not needed for polyglot (model comes from TS once).
+- No new model/api page CONTENT beyond the multi-link section.

docs/superpowers/specs/2026-06-06-polyglot-docs-composition-design.md

@@ -23,6 +23,7 @@ import {
   buildPkMap,
   buildRelationMap,
   resolveDocsConfig,
+  apiLabel,
 } from "@metaobjectsdev/codegen-ts";
 import type {
   GenContext,
@@ -265,24 +266,27 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   const emit: EmittedFile[] = [];
   let modelFiles: EmittedFile[] = [];
 
-  // Both surfaces emitted together → cross-link them. The api surface only
-  // materializes with a loadable gen config, so guard on that too: when both are
-  // requested AND the config loaded, the model pages cross-link to `api/` and the
-  // api pages cross-link back to the model root. Otherwise each surface emits its
-  // historical, byte-identical standalone output.
-  const bothSurfaces =
-    docsCfg.surfaces.includes("model") &&
-    docsCfg.surfaces.includes("api") &&
-    loadedConfig !== undefined;
+  // The declared api surfaces, each tagged with its human label (apiLabel maps
+  // the language key → label; never hardcode labels). The model page links one
+  // reference per declared surface — across ALL ports, not just the surfaces
+  // THIS command emits — so a polyglot model page points at every port's docs.
+  const labeled = docsCfg.apiSurfaces.map((s) => ({ ...s, label: apiLabel(s.lang) }));
+
+  // The api surface only materializes with a loadable gen config (there is
+  // nothing generated to document otherwise), so gate api emit + cross-linking
+  // on that. When false, the model surface emits its historical standalone form.
+  const apiSelected = docsCfg.surfaces.includes("api") && loadedConfig !== undefined;
 
   // MODEL surface — the neutral metadata pages (<Entity>.md / <Template>.md +
   // README.md). Keep the render-error handling tight around docsFile() only.
   if (docsCfg.surfaces.includes("model")) {
+    // When api is selected, link EVERY declared surface from the model page (so a
+    // polyglot model page references each port's api docs). `labeled` already
+    // carries {label, subDir, baseUrl?} (docsFile ignores the extra `lang`), so
+    // pass it straight through. Otherwise no api refs.
+    const modelOpts = apiSelected ? { apiSurfaces: labeled } : {};
     try {
-      modelFiles = await (bothSurfaces
-        ? docsFile({ apiSurface: { subDir: "api" } })
-        : docsFile()
-      ).generate(ctx);
+      modelFiles = await docsFile(modelOpts).generate(ctx);
     } catch (err) {
       const msg = (err as Error).message;
       // Duplicate output path (silent-overwrite backstop): the generator already
@@ -311,16 +315,24 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   }
 
   // API surface — the SDK reference for the GENERATED REST surface, side by side
-  // under api/. Only meaningful with a loadable gen config (there is nothing
-  // generated to document otherwise), so skip gracefully when absent.
+  // under each surface's subDir. THIS command only OWNS the surfaces it can
+  // generate — i.e. its own port (lang "ts"). Surfaces owned by other ports are
+  // linked (above) but produced by running that port's docs command; we just log
+  // a pointer. Only meaningful with a loadable gen config, so skip when absent.
   let apiFiles: EmittedFile[] = [];
   if (docsCfg.surfaces.includes("api")) {
     if (loadedConfig !== undefined) {
       try {
-        apiFiles = await apiDocsFile({
-          subDir: "api",
-          modelSurface: docsCfg.surfaces.includes("model"),
-        }).generate(ctx);
+        // Emit every surface THIS port owns (loop so it generalizes beyond the
+        // single ts surface owned today).
+        for (const s of labeled.filter((s) => s.lang === "ts")) {
+          apiFiles.push(
+            ...(await apiDocsFile({
+              subDir: s.subDir,
+              modelSurface: docsCfg.surfaces.includes("model"),
+            }).generate(ctx)),
+          );
+        }
       } catch (err) {
         const msg = (err as Error).message;
         if (msg.startsWith("docs: duplicate output path")) {
@@ -331,6 +343,13 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
         return 1;
       }
       emit.push(...apiFiles);
+      // Surfaces owned by other ports: link only, with a pointer to where they
+      // get produced.
+      for (const s of labeled.filter((s) => s.lang !== "ts")) {
+        log.info(
+          `meta docs: api surface '${s.lang}' (${s.subDir}) is produced by that port's docs command — run it to populate those pages.`,
+        );
+      }
     } else if (hasConfig) {
       // Config present but failed to load — already warned above; don't claim an
       // api surface we couldn't build.

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

@@ -1,6 +1,6 @@
 import { describe, test, expect, afterAll } from "bun:test";
 import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { docsCommand } from "../../src/commands/docs.js";
@@ -37,6 +37,25 @@ const CONFIG = [
   `});`,
 ].join("\n");
 
+// A config whose docs block declares TWO api surfaces: one this port owns
+// (lang "ts") and one another port owns (lang "java"). This command should emit
+// only the owned (ts) surface but link BOTH from the model page.
+const CONFIG_TWO_SURFACES = [
+  `import { defineConfig } from "@metaobjectsdev/codegen-ts";`,
+  `import { entityFile } from "@metaobjectsdev/codegen-ts/generators";`,
+  `export default defineConfig({`,
+  `  outDir: "out",`,
+  `  dialect: "sqlite",`,
+  `  generators: [entityFile()],`,
+  `  docs: {`,
+  `    apiSurfaces: [`,
+  `      { lang: "ts", subDir: "api/ts" },`,
+  `      { lang: "java", subDir: "api/java" },`,
+  `    ],`,
+  `  },`,
+  `});`,
+].join("\n");
+
 const dirs: string[] = [];
 
 /** Project root with metadata + a metaobjects.config.ts present. */
@@ -49,6 +68,16 @@ async function projectWithConfig(): Promise<string> {
   return root;
 }
 
+/** Project root whose docs config declares two api surfaces (ts + java). */
+async function projectTwoSurfaces(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "meta-docs-surf-2-"));
+  dirs.push(root);
+  await mkdir(join(root, "metaobjects"), { recursive: true });
+  await writeFile(join(root, "metaobjects", "meta.json"), JSON.stringify(META), "utf8");
+  await writeFile(join(root, "metaobjects.config.ts"), CONFIG_TWO_SURFACES, "utf8");
+  return root;
+}
+
 /** Project root with metadata but NO metaobjects.config.ts. */
 async function projectNoConfig(): Promise<string> {
   const root = await mkdtemp(join(tmpdir(), "meta-docs-surf-nocfg-"));
@@ -88,6 +117,23 @@ describe("meta docs — model + api surfaces from one docs: config", () => {
     expect(existsSync(join(out, "api"))).toBe(false);
   });
 
+  test("emits only the owned (ts) surface but links ALL declared surfaces", async () => {
+    const root = await projectTwoSurfaces();
+    const out = join(root, "out-two");
+
+    const code = await docsCommand([root, "--out", out], root);
+    expect(code).toBe(0);
+
+    // TS surface IS emitted (this port owns lang "ts"):
+    expect(existsSync(join(out, "api", "ts", "Widget.md"))).toBe(true);
+    // Java surface is NOT emitted by THIS command:
+    expect(existsSync(join(out, "api", "java"))).toBe(false);
+    // the model entity page links BOTH surfaces:
+    const page = readFileSync(join(out, "Widget.md"), "utf8");
+    expect(page).toContain("api/ts/");
+    expect(page).toContain("api/java/");
+  });
+
   test("no config → model surface only, exit 0 (api skipped)", async () => {
     const root = await projectNoConfig();
     const out = join(root, "out-nocfg");

server/typescript/packages/cli/test/unit/docs-command-surfaces.test.ts

@@ -87,6 +87,21 @@ export function surfaceCrossHref(fromOutputPath: string, toOutputPath: string):
   return rel.startsWith(".") ? rel : `./${rel}`;
 }
 
+/** Href FROM a page (at `fromOutputPath`, relative to the docs root) TO a page
+ *  (`page`, relative to the surface's own root) in an api surface. Relative via
+ *  `surfaceCrossHref` when the surface is in the same tree; absolute `baseUrl/page`
+ *  when the surface declares a baseUrl (federated / separate repo). */
+export function apiSurfaceHref(
+  fromOutputPath: string,
+  surface: { subDir: string; baseUrl?: string },
+  page: string,
+): string {
+  if (surface.baseUrl !== undefined && surface.baseUrl !== "") {
+    return `${surface.baseUrl.replace(/\/$/, "")}/${page}`;
+  }
+  return surfaceCrossHref(fromOutputPath, `${surface.subDir}/${page}`);
+}
+
 /** A page about to be emitted, paired with the FQN of the node that produced it
  *  (for a precise collision diagnostic). */
 export interface DocPagePlacement {

server/typescript/packages/codegen-ts/src/docs-paths.ts

@@ -0,0 +1,7 @@
+const LABELS: Record<string, string> = {
+  ts: "TypeScript", java: "Java", kotlin: "Kotlin", csharp: "C#", python: "Python",
+};
+/** Human label for an api-surface language key. Unknown → capitalized verbatim. */
+export function apiLabel(lang: string): string {
+  return LABELS[lang] ?? (lang.length ? lang[0]!.toUpperCase() + lang.slice(1) : lang);
+}