no-mistakes(test): Name api-docs generator entry in Java/Kotlin Not-there line

Author: dmealing

agent-context/servers/csharp.meta.json

@@ -4,5 +4,6 @@
   "codegenCommand": "dotnet meta gen",
   "docsCommand": "dotnet meta docs",
   "docsCondition": "",
+  "docsMissing": "",
   "apiSubDir": "api/csharp"
 }

agent-context/servers/java.meta.json

@@ -4,5 +4,6 @@
   "codegenCommand": "mvn metaobjects:generate",
   "docsCommand": "mvn metaobjects:generate",
   "docsCondition": " (when the project's generator list declares the api-docs generator)",
+  "docsMissing": "Declare `com.metaobjects.generator.apidocs.JavaApiDocsGenerator` as a `<generator>` entry in the pom's `<generators>` if it is missing",
   "apiSubDir": "api/java"
 }

agent-context/servers/kotlin.meta.json

@@ -4,5 +4,6 @@
   "codegenCommand": "mvn metaobjects:generate",
   "docsCommand": "mvn metaobjects:generate",
   "docsCondition": " (when the project's generator list declares the api-docs generator)",
+  "docsMissing": "Declare `com.metaobjects.generator.kotlin.apidocs.KotlinApiDocsGenerator` as a `<generator>` entry in the pom's `<generators>` if it is missing",
   "apiSubDir": "api/kotlin"
 }

agent-context/servers/python.meta.json

@@ -4,5 +4,6 @@
   "codegenCommand": "metaobjects gen",
   "docsCommand": "metaobjects docs",
   "docsCondition": "",
+  "docsMissing": "",
   "apiSubDir": "api/python"
 }

agent-context/servers/typescript.meta.json

@@ -4,5 +4,6 @@
   "codegenCommand": "npx meta gen",
   "docsCommand": "npx meta docs",
   "docsCondition": "",
+  "docsMissing": "",
   "apiSubDir": "api"
 }

agent-context/templates/always-on.md.mustache

@@ -37,7 +37,7 @@ inferring the answer from generated code, which is the disposable half.
 - **`{{apiSubDir}}/AGENT-API.md`** — before calling generated code. The types, endpoints and
   filter operators the generators actually emitted.
 
-Not there? Run `{{docsCommand}}`{{docsCondition}}.
+Not there? {{docsMissingAction}} `{{docsCommand}}`.
 
 The other three pages of that reference — `agent/schema.md` (persistence), `agent/ui.md`
 (forms and grids) and `agent/requirements.md` (what is already claimed, and what was

server/typescript/packages/sdk/src/agent-context/assemble.ts

@@ -37,6 +37,12 @@ interface ServerMeta {
    *  goal writes them only when the pom's generator list declares the api-docs generator,
    *  and a pointer that omits that sends a reader to run a command that writes nothing. */
   docsCondition: string;
+  /** What to do before running `docsCommand` when the api pages are missing, with no
+   *  trailing punctuation, or `""` when running it is the whole remedy. A Maven pom writes
+   *  them only once it declares the api-docs generator, and a missing entry is the usual
+   *  reason the file is absent, so the Not-there line names that entry instead of only the
+   *  command. */
+  docsMissing: string;
   /** The docs-root-relative directory THIS port's docs command writes its api pages into.
    *  It is NOT `api` outside TypeScript — Python defaults to `api/python`, C# to
    *  `api/csharp`, the Maven plugin to `api/<lang>` — so a pointer naming `api/AGENT-API.md`
@@ -54,7 +60,14 @@ function readServerMeta(contentRoot: string, server: string): ServerMeta | undef
 function stackLine(
   contentRoot: string,
   stack: Stack,
-): { line: string; codegenCommand: string; docsCommand: string; docsCondition: string; apiSubDir: string } {
+): {
+  line: string;
+  codegenCommand: string;
+  docsCommand: string;
+  docsCondition: string;
+  docsMissing: string;
+  apiSubDir: string;
+} {
   const primary = stack.servers[0];
   const meta = primary ? readServerMeta(contentRoot, primary) : undefined;
   const serverPart = stack.servers.length ? stack.servers.join(", ") + " server" : "no server";
@@ -69,6 +82,7 @@ function stackLine(
     codegenCommand: meta ? meta.codegenCommand : "meta gen",
     docsCommand: meta ? meta.docsCommand : "meta docs",
     docsCondition: meta ? meta.docsCondition : "",
+    docsMissing: meta ? meta.docsMissing : "",
     apiSubDir: meta ? meta.apiSubDir : "api",
   };
 }
@@ -143,10 +157,14 @@ export function assemble(opts: { contentRoot: string; stack: Stack }): Assembled
 
   // 1. Always-on (AGENTS.md + CLAUDE.md, identical contents).
   const tpl = readFileSync(join(contentRoot, "templates", "always-on.md.mustache"), "utf8");
-  const { line, codegenCommand, docsCommand, docsCondition, apiSubDir } = stackLine(contentRoot, stack);
+  const { line, codegenCommand, docsCommand, docsCondition, docsMissing, apiSubDir } = stackLine(
+    contentRoot,
+    stack,
+  );
+  const docsMissingAction = docsMissing === "" ? "Run" : `${docsMissing}, then run`;
   const alwaysOn = applyTemplate(
     tpl,
-    { stackLine: line, codegenCommand, docsCommand, docsCondition, apiSubDir },
+    { stackLine: line, codegenCommand, docsCommand, docsCondition, docsMissingAction, apiSubDir },
     { nodeDocsSurface: hasNodeDocsSurface(stack) },
   );
   out.push({ path: ".metaobjects/AGENTS.md", contents: alwaysOn });

server/typescript/packages/sdk/test/agent-context/assemble.test.ts

@@ -56,9 +56,19 @@ describe("assemble", () => {
       "`mvn metaobjects:generate` writes ONE reference file under this project's docs output " +
         "directory (when the project's generator list declares the api-docs generator).",
     );
+    // A missing api-docs entry is the usual reason the page is absent, so the Not-there line
+    // names the entry to declare before the command, rather than repeating the condition.
     expect(java).toContain(
-      "Not there? Run `mvn metaobjects:generate` (when the project's generator list declares " +
-        "the api-docs generator).",
+      "Not there? Declare `com.metaobjects.generator.apidocs.JavaApiDocsGenerator` as a " +
+        "`<generator>` entry in the pom's `<generators>` if it is missing, then run " +
+        "`mvn metaobjects:generate`.",
+    );
+    const kotlin = assemble({ contentRoot: CONTENT_ROOT, stack: makeStack(["kotlin"], []) })
+      .find((f) => f.path === ".metaobjects/AGENTS.md")!.contents;
+    expect(kotlin).toContain(
+      "Not there? Declare `com.metaobjects.generator.kotlin.apidocs.KotlinApiDocsGenerator` as a " +
+        "`<generator>` entry in the pom's `<generators>` if it is missing, then run " +
+        "`mvn metaobjects:generate`.",
     );
 
     // A Java backend serving React DOES run `meta gen`, so it gets the full pointer.
@@ -67,7 +77,7 @@ describe("assemble", () => {
     expect(javaReact).toContain("`meta docs` writes four reference files");
 
     // No section tag survives substitution on any of them.
-    for (const c of [node, python, java, javaReact]) {
+    for (const c of [node, python, java, kotlin, javaReact]) {
       expect(c).not.toContain("{{#");
       expect(c).not.toContain("{{^");
       expect(c).not.toContain("{{/");