anbaric-cloud-hosting 1.26.0 → 1.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-cloud-hosting",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "Anbaric Cloud hosting service: Postgres-backed job persistence and queuing exposed over an HTTP API",
   "license": "MIT",
   "author": "chris@anbaric.ai",
@@ -18,18 +18,18 @@
     "@aws-sdk/client-s3": "^3.1110.0",
     "@aws-sdk/client-secrets-manager": "^3.700.0",
     "@aws-sdk/client-servicediscovery": "^3.1110.0",
-    "anbaric-data-store": "^1.26.0",
-    "anbaric-plugins": "^1.26.0",
-    "anbaric-tsapi": "^1.26.0",
-    "anbaric-web": "^1.26.0",
+    "anbaric-data-store": "^1.28.0",
+    "anbaric-plugins": "^1.28.0",
+    "anbaric-tsapi": "^1.28.0",
+    "anbaric-web": "^1.28.0",
     "esbuild": "^0.28.2",
     "pg": "^8.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@types/pg": "^8.15.0",
-    "anbaric-impl-cloud": "^1.26.0",
-    "anbaric-state-machine": "^1.26.0",
+    "anbaric-impl-cloud": "^1.28.0",
+    "anbaric-state-machine": "^1.28.0",
     "tsx": "^4.20.0",
     "typescript": "^7.0.2"
   },

package/src/app-management/BaseBuildLayer.ts

@@ -2,6 +2,7 @@ import {ChildProcess, spawn} from "node:child_process";
 import {mkdir, readFile, rm, symlink, writeFile} from "node:fs/promises";
 import {join} from "node:path";
 import {adminPing} from "../app-admin/adminPing";
+import {DocGenerator} from "../docs/DocGenerator";
 import {BuildLayer, DeploymentStatus, DeploymentSummary} from "./BuildLayer";
 
 type Deployment = {
@@ -30,6 +31,7 @@ const adminProbe : Probe = (host, port) => adminPing(host, port, LIVENESS_PROBE_
 abstract class BaseBuildLayer implements BuildLayer {
 
     protected deployments = new Map<string, Deployment>();
+    protected docGenerator? : DocGenerator;
     private nextAppIndex = 0;
     private hydration? : Promise<void>;
 
@@ -127,6 +129,12 @@ abstract class BaseBuildLayer implements BuildLayer {
         this.log(deployment, "extracting application bundle");
         await this.run(deployment, "tar", ["-xzf", tarballPath, "-C", appDir]);
 
+        // Documentation is generated off the critical path: fire-and-forget from
+        // the extracted source, before the build, so a slow model call can never
+        // delay or fail the deploy. Regenerated on every deploy, replaces=redeploy.
+        void this.docGenerator?.generate(deployment.appName, appDir, { redeploy: !!deployment.replaces })
+            .catch(error => this.log(deployment, `doc generation skipped: ${error instanceof Error ? error.message : error}`));
+
         this.log(deployment, "linking anbaric workspace packages");
         const manifest = JSON.parse(await readFile(join(appDir, "package.json"), "utf8"));
         await this.linkWorkspacePackages(appDir, manifest);

package/src/app-management/DockerBuildLayer.ts

@@ -2,6 +2,7 @@ import {spawn} from "node:child_process";
 import {writeFile} from "node:fs/promises";
 import {join} from "node:path";
 import {BaseBuildLayer, Deployment, Probe} from "./BaseBuildLayer";
+import {DocGenerator} from "../docs/DocGenerator";
 import {childLines} from "./childLines";
 
 type LogStreamer = (container : string, signal : AbortSignal) => AsyncIterable<string>;
@@ -15,6 +16,7 @@ type DockerBuildLayerOptions = {
     platformUrl : string,
     sqlDatabaseUrl? : string,
     sqlSchema? : string,
+    docGenerator? : DocGenerator,
 };
 
 type CommandRunner = (command : string, args : Array<string>, onOutput : (line : string) => void) => Promise<void>;
@@ -51,6 +53,7 @@ class DockerBuildLayer extends BaseBuildLayer {
                 private runCommand : CommandRunner = spawnRunner, probe? : Probe,
                 private logStreamer : LogStreamer = dockerLogStreamer) {
         super(appsDir, consumerPortBase, probe);
+        this.docGenerator = options.docGenerator;
     }
 
     protected async diagnostics(deployment : Deployment) : Promise<Array<string>> {

package/src/app-management/FargateBuildLayer.ts

@@ -9,6 +9,7 @@ import {ServiceDiscoveryClient, CreateServiceCommand as CreateDiscoveryServiceCo
     ListServicesCommand} from "@aws-sdk/client-servicediscovery";
 import {CloudWatchLogsClient, FilterLogEventsCommand, StartLiveTailCommand} from "@aws-sdk/client-cloudwatch-logs";
 import {BaseBuildLayer, Deployment, Probe} from "./BaseBuildLayer";
+import {DocGenerator} from "../docs/DocGenerator";
 import {dockerfileFor} from "./DockerBuildLayer";
 
 type FargateBuildLayerOptions = {
@@ -30,6 +31,7 @@ type FargateBuildLayerOptions = {
     servicesApiKey? : string,
     sqlDatabaseUrlSecretArn? : string,
     sqlSchema? : string,
+    docGenerator? : DocGenerator,
 };
 
 type AwsClients = {
@@ -61,6 +63,7 @@ class FargateBuildLayer extends BaseBuildLayer {
                 private buildPollIntervalMs : number = 5000) {
         super(appsDir, consumerPortBase, probe, FARGATE_LIVENESS_TIMEOUT_MS);
         this.aws = aws ?? defaultClients(options.awsRegion);
+        this.docGenerator = options.docGenerator;
     }
 
     protected async diagnostics(deployment : Deployment) : Promise<Array<string>> {

package/src/data-store/AppDocsStore.ts

@@ -0,0 +1,23 @@
+type AppDoc = {
+    slug : string,
+    title : string,
+    markdown : string,
+    parentSlug : string | null,
+    position : number,
+};
+
+/* Generated user documentation for an app, held as a shallow tree: root docs
+   (an "Introduction" and, verbatim, any README) have a null parent, and every
+   other doc names its parent's slug, ordered among its siblings by position.
+   Docs are regenerated wholesale on every deploy, so the store replaces an
+   app's whole set at once rather than upserting doc by doc - a doc that no
+   longer applies after a redeploy must not linger. */
+interface AppDocsStore {
+
+    replaceForApp(appId : string, docs : Array<AppDoc>) : Promise<void>;
+
+    listForApp(appId : string) : Promise<Array<AppDoc>>;
+
+}
+
+export type { AppDoc, AppDocsStore };

package/src/data-store/InMemoryAppDocsStore.ts

@@ -0,0 +1,17 @@
+import {AppDoc, AppDocsStore} from "./AppDocsStore";
+
+class InMemoryAppDocsStore implements AppDocsStore {
+
+    private byApp = new Map<string, Array<AppDoc>>();
+
+    async replaceForApp(appId : string, docs : Array<AppDoc>) : Promise<void> {
+        this.byApp.set(appId, docs.map(doc => ({ ...doc })));
+    }
+
+    async listForApp(appId : string) : Promise<Array<AppDoc>> {
+        return (this.byApp.get(appId) ?? []).map(doc => ({ ...doc }));
+    }
+
+}
+
+export { InMemoryAppDocsStore }

package/src/data-store/PostgresAppDocsStore.ts

@@ -0,0 +1,56 @@
+import {Pool} from "pg";
+import {AppDoc, AppDocsStore} from "./AppDocsStore";
+
+/* Replacing an app's docs is a delete-then-insert in one transaction, so a
+   redeploy swaps the whole set atomically - a reader never sees a mix of old
+   and new, and a crash mid-write leaves the previous docs intact. */
+class PostgresAppDocsStore implements AppDocsStore {
+
+    constructor(private pool : Pool) {}
+
+    async replaceForApp(appId : string, docs : Array<AppDoc>) : Promise<void> {
+        const client = await this.pool.connect();
+
+        try {
+            await client.query("BEGIN");
+            await client.query("DELETE FROM app_docs WHERE app_id = $1", [appId]);
+
+            if (docs.length > 0) {
+                await client.query(
+                    `INSERT INTO app_docs (app_id, slug, title, markdown, parent_slug, position)
+                     SELECT $1, * FROM unnest($2::text[], $3::text[], $4::text[], $5::text[], $6::int[])`,
+                    [appId,
+                     docs.map(doc => doc.slug),
+                     docs.map(doc => doc.title),
+                     docs.map(doc => doc.markdown),
+                     docs.map(doc => doc.parentSlug),
+                     docs.map(doc => doc.position)],
+                );
+            }
+
+            await client.query("COMMIT");
+        } catch (error) {
+            await client.query("ROLLBACK").catch(() => {});
+            throw error;
+        } finally {
+            client.release();
+        }
+    }
+
+    async listForApp(appId : string) : Promise<Array<AppDoc>> {
+        const result = await this.pool.query(
+            `SELECT slug, title, markdown, parent_slug, position
+             FROM app_docs WHERE app_id = $1
+             ORDER BY position, slug`, [appId]);
+        return result.rows.map(row => ({
+            slug: row.slug,
+            title: row.title,
+            markdown: row.markdown,
+            parentSlug: row.parent_slug,
+            position: row.position,
+        }));
+    }
+
+}
+
+export { PostgresAppDocsStore }

package/src/data-store/Schema.ts

@@ -94,6 +94,24 @@ const ensureSchema = async (pool : Pool) : Promise<void> => {
         ON job_run_schedule (app_id, workflow_id, run_at)`);
     await pool.query(`CREATE INDEX IF NOT EXISTS job_run_schedule_due
         ON job_run_schedule (run_at) WHERE claimed_at IS NULL`);
+    // User documentation the platform generates from an app's source on deploy,
+    // keyed by (app_id, slug) and held as a shallow tree: a root doc has a null
+    // parent_slug, a child names its parent's slug, and position orders
+    // siblings. A redeploy replaces the whole set for an app.
+    await pool.query(`
+        CREATE TABLE IF NOT EXISTS app_docs (
+            app_id       TEXT NOT NULL,
+            slug         TEXT NOT NULL,
+            title        TEXT NOT NULL DEFAULT '',
+            markdown     TEXT NOT NULL,
+            parent_slug  TEXT,
+            position     INTEGER NOT NULL DEFAULT 0,
+            generated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            PRIMARY KEY (app_id, slug)
+        )
+    `);
+    await pool.query("ALTER TABLE app_docs ADD COLUMN IF NOT EXISTS parent_slug TEXT");
+    await pool.query("ALTER TABLE app_docs ADD COLUMN IF NOT EXISTS position INTEGER NOT NULL DEFAULT 0");
     await pool.query("CREATE SCHEMA IF NOT EXISTS anbaric_system");
     await pool.query(`
         CREATE TABLE IF NOT EXISTS anbaric_system.cli_keys (

package/src/docs/DocGenerator.ts

@@ -0,0 +1,97 @@
+import {AppDoc, AppDocsStore} from "../data-store/AppDocsStore";
+import {DocModel, DraftDoc} from "./DocModel";
+import {gatherSources} from "./gatherSources";
+
+const README = /^readme(\.md|\.markdown)?$/i;
+
+/* Arranges the model's draft docs into the shallow tree the store holds: one
+   "introduction" root with every other page beneath it, plus the app's README
+   copied in verbatim as a second root beside the introduction. It is defensive
+   about what the model returned - a missing introduction, a dangling or looping
+   parent - so the stored set is always a well-formed single-rooted tree (two
+   roots once the README is added). */
+const buildDocTree = (drafts : Array<DraftDoc>, readme : string | undefined) : Array<AppDoc> => {
+    const cleaned = drafts
+        .filter(draft => draft && typeof draft.slug === "string" && draft.slug.trim() && typeof draft.markdown === "string")
+        .map(draft => ({
+            slug: draft.slug.trim(),
+            title: (typeof draft.title === "string" && draft.title.trim() ? draft.title : draft.slug).trim(),
+            markdown: draft.markdown,
+            parentSlug: typeof draft.parentSlug === "string" && draft.parentSlug.trim() ? draft.parentSlug.trim() : null,
+        }))
+        .filter(draft => draft.slug !== "readme");
+
+    if (cleaned.length === 0) return [];
+
+    const bySlug = new Map(cleaned.map(draft => [draft.slug, draft]));
+
+    const intro = bySlug.get("introduction") ?? cleaned.find(draft => draft.parentSlug === null) ?? cleaned[0];
+    intro.parentSlug = null;
+
+    const reachesIntro = (draft : typeof cleaned[number]) : boolean => {
+        const seen = new Set<string>();
+        let current : typeof cleaned[number] | undefined = draft;
+
+        while (current && current !== intro) {
+            if (seen.has(current.slug)) return false;
+            seen.add(current.slug);
+            current = current.parentSlug === null ? undefined : bySlug.get(current.parentSlug);
+        }
+
+        return current === intro;
+    };
+
+    for (const draft of cleaned) {
+        if (draft !== intro && ! reachesIntro(draft)) draft.parentSlug = intro.slug;
+    }
+
+    const nextPosition = new Map<string, number>();
+    const positioned = (parentSlug : string | null) : number => {
+        const key = parentSlug ?? "";
+        const position = nextPosition.get(key) ?? 0;
+        nextPosition.set(key, position + 1);
+        return position;
+    };
+
+    const docs : Array<AppDoc> = [{ ...intro, position: positioned(null) }];
+
+    for (const draft of cleaned) {
+        if (draft !== intro) docs.push({ ...draft, position: positioned(draft.parentSlug) });
+    }
+
+    if (readme !== undefined) {
+        docs.push({ slug: "readme", title: "README", markdown: readme, parentSlug: null, position: positioned(null) });
+    }
+
+    return docs;
+};
+
+/* Generates an app's user documentation from its source and stores it. It runs
+   off the deploy's critical path (the build layer calls it fire-and-forget), so
+   it is deliberately all-or-nothing and never throws: any failure - no model
+   configured, a slow or erroring model, unreadable source - is logged and the
+   existing docs are left as they are. */
+class DocGenerator {
+
+    constructor(private model : DocModel, private store : AppDocsStore) {}
+
+    async generate(appName : string, appDir : string, options : { redeploy : boolean }) : Promise<void> {
+        try {
+            const { files, truncated } = await gatherSources(appDir);
+            if (files.length === 0) return;
+
+            const drafts = await this.model.writeDocs({ appName, files, truncated });
+            const readme = files.find(file => README.test(file.path))?.content;
+            const docs = buildDocTree(drafts, readme);
+            if (docs.length === 0) return;
+
+            await this.store.replaceForApp(appName, docs);
+            console.log(`[docs] ${options.redeploy ? "regenerated" : "generated"} ${docs.length} doc(s) for "${appName}"`);
+        } catch (error) {
+            console.error(`[docs] could not generate documentation for "${appName}": ${error instanceof Error ? error.message : error}`);
+        }
+    }
+
+}
+
+export { DocGenerator, buildDocTree }

package/src/docs/DocModel.ts

@@ -0,0 +1,27 @@
+type DocContext = {
+    appName : string,
+    files : Array<{ path : string, content : string }>,
+    truncated : boolean,
+};
+
+/* One doc as the model proposes it, before the generator arranges the set into
+   a tree: a slug, a title, its markdown, and optionally the slug of the doc it
+   belongs under (the introduction, or another page). The generator fills in the
+   final parent and sibling position. */
+type DraftDoc = {
+    slug : string,
+    title : string,
+    markdown : string,
+    parentSlug? : string | null,
+};
+
+/* Turns an app's source into a set of user-facing docs. An implementation that
+   cannot reach a model (nothing configured) returns an empty set rather than
+   throwing, so doc generation quietly does nothing. */
+interface DocModel {
+
+    writeDocs(context : DocContext) : Promise<Array<DraftDoc>>;
+
+}
+
+export type { DocContext, DraftDoc, DocModel };

package/src/docs/GatewayDocModel.ts

@@ -0,0 +1,86 @@
+import {DocContext, DocModel, DraftDoc} from "./DocModel";
+
+type FetchFn = (url : string, init : RequestInit) => Promise<Response>;
+
+const SYSTEM_PROMPT = `You write user documentation for an application deployed on Anbaric.
+
+Anbaric apps model their domain as state machines: long-lived jobs move through named states, driven by actions and transitions, with data validated against a schema and every change attributed to an actor. Read the whole source you are given and write documentation for the people who will USE this app - what it does, the workflows it runs, how someone drives it, and anything they need to know.
+
+Organise the docs as a shallow tree. Write exactly one top-level page with the slug "introduction" and a null parentSlug: a concise overview of the app that orients a new user. Write every other page as a child, giving its parentSlug as "introduction" (or, to nest one level deeper, the slug of another page). Prefer several focused child pages over one long page. Do not write a page with the slug "readme" - the app's README is added separately.
+
+Write clear markdown. Give each page a short kebab-case slug and a human title. Do not invent features the source does not show. If the source was truncated, document only what you can see.`;
+
+const OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        docs: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    slug: { type: "string" },
+                    title: { type: "string" },
+                    markdown: { type: "string" },
+                    parentSlug: { type: ["string", "null"] },
+                },
+                required: ["slug", "title", "markdown", "parentSlug"],
+            },
+        },
+    },
+    required: ["docs"],
+};
+
+/* The platform's doc writer over an OpenAI-compatible chat endpoint - the same
+   gateway the agentic actions use (ANBARIC_AI_GATEWAY_*), so no new config.
+   With no token there is nothing to call, so it returns no docs and the
+   generator does nothing. */
+class GatewayDocModel implements DocModel {
+
+    constructor(private baseUrl : string = process.env.ANBARIC_AI_GATEWAY_URL ?? "https://api.openai.com/v1",
+                private apiKey : string = process.env.ANBARIC_AI_GATEWAY_TOKEN ?? "",
+                private model : string = process.env.ANBARIC_AGENTIC_MODEL ?? "gpt-5.4-mini",
+                private fetchFn : FetchFn = (url, init) => fetch(url, init)) {}
+
+    async writeDocs(context : DocContext) : Promise<Array<DraftDoc>> {
+        if (!this.apiKey) {
+            console.warn(`[docs] no ANBARIC_AI_GATEWAY_TOKEN - skipping documentation for "${context.appName}"`);
+            return [];
+        }
+
+        const response = await this.fetchFn(`${this.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "authorization": `Bearer ${this.apiKey}` },
+            body: JSON.stringify({
+                model: this.model,
+                messages: [
+                    { role: "system", content: SYSTEM_PROMPT },
+                    { role: "user", content: this.render(context) },
+                ],
+                response_format: {
+                    type: "json_schema",
+                    json_schema: { name: "docs", strict: true, schema: OUTPUT_SCHEMA },
+                },
+            }),
+        });
+
+        if (!response.ok) {
+            const problem = await response.json().catch(() => ({}));
+            throw new Error(`Doc model request failed with status ${response.status}${problem.error?.message ? `: ${problem.error.message}` : ""}`);
+        }
+
+        const message = (await response.json()).choices?.[0]?.message?.content;
+        const docs = message ? JSON.parse(message).docs : [];
+        return Array.isArray(docs) ? docs : [];
+    }
+
+    private render(context : DocContext) : string {
+        const header = `App "${context.appName}"${context.truncated ? " (source was truncated - some files are omitted)" : ""}. Source:`;
+        const files = context.files.map(file => `\n\n=== ${file.path} ===\n${file.content}`).join("");
+        return header + files;
+    }
+
+}
+
+export { GatewayDocModel }

package/src/docs/gatherSources.ts

@@ -0,0 +1,79 @@
+import {readFile, readdir} from "node:fs/promises";
+import {join, relative} from "node:path";
+
+const INCLUDE = /\.(ts|tsx|js|jsx|json|md|css|html)$/;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".next", "build", "coverage"]);
+const SKIP_FILES = new Set(["package-lock.json"]);
+
+// A file this big that isn't a manifest is almost always baked data or an
+// inlined asset - noise that would crowd out code and burn tokens.
+const MAX_FILE_BYTES = 30_000;
+// ~60K tokens of source, a generous ceiling; real apps are far under it.
+const MAX_TOTAL_BYTES = 240_000;
+
+type GatheredFile = { path : string, content : string };
+type Gathered = { files : Array<GatheredFile>, truncated : boolean };
+
+const isManifest = (path : string) : boolean =>
+    /(^|\/)package\.json$/.test(path) || /(^|\/)\.anbaric\/app-config\.json$/.test(path) || /(^|\/)readme\.md$/i.test(path);
+
+// Manifests and docs first, then source, then the rest - so a truncated
+// snapshot keeps the files that describe the app best.
+const priority = (path : string) : number => {
+    if (isManifest(path)) return 0;
+    if (path.toLowerCase().endsWith(".md")) return 1;
+    if (/\.(ts|tsx|js|jsx)$/.test(path)) return 2;
+    return 3;
+};
+
+const walk = async (dir : string, root : string, found : Array<string>) : Promise<void> => {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name)) await walk(full, root, found);
+        } else if (INCLUDE.test(entry.name) && !SKIP_FILES.has(entry.name)) {
+            found.push(relative(root, full));
+        }
+    }
+};
+
+/* The whole of an app's source, small enough to hand to a model in one go:
+   manifests, docs and code, skipping dependencies, build output and oversized
+   data files, and capped in total. `truncated` is true when the cap dropped
+   files, so the caller can tell the model not to assume it saw everything. */
+const gatherSources = async (appDir : string) : Promise<Gathered> => {
+    const paths : Array<string> = [];
+    await walk(appDir, appDir, paths);
+    paths.sort((left, right) => priority(left) - priority(right) || left.localeCompare(right));
+
+    const files : Array<GatheredFile> = [];
+    let total = 0;
+    let truncated = false;
+
+    for (const path of paths) {
+        let content : string;
+        try {
+            content = await readFile(join(appDir, path), "utf8");
+        } catch {
+            continue;
+        }
+
+        if (!isManifest(path) && content.length > MAX_FILE_BYTES) continue;
+        if (total + content.length > MAX_TOTAL_BYTES) { truncated = true; continue; }
+
+        files.push({ path, content });
+        total += content.length;
+    }
+
+    return { files, truncated };
+};
+
+export { gatherSources };
+export type { Gathered, GatheredFile };

package/src/index.ts

@@ -24,6 +24,12 @@ export * from "./app-admin/adminPing";
 export * from "./data-store/PostgresCliKeyStore";
 export * from "./data-store/PostgresJobPersistence";
 export * from "./data-store/PostgresJobRunSchedulePersistence";
+export * from "./data-store/AppDocsStore";
+export * from "./data-store/PostgresAppDocsStore";
+export * from "./data-store/InMemoryAppDocsStore";
+export * from "./docs/DocModel";
+export * from "./docs/GatewayDocModel";
+export * from "./docs/DocGenerator";
 export * from "./data-store/PostgresJsonStore";
 export * from "./data-store/Schema";
 export * from "./data-store/SecretsManagerSecretStore";

package/src/main.ts

@@ -17,6 +17,9 @@ import {PostgresJsonStore} from "./data-store/PostgresJsonStore";
 import {PostgresQueue} from "./queuing/PostgresQueue";
 import {DockerBuildLayer} from "./app-management/DockerBuildLayer";
 import {FargateBuildLayer} from "./app-management/FargateBuildLayer";
+import {DocGenerator} from "./docs/DocGenerator";
+import {GatewayDocModel} from "./docs/GatewayDocModel";
+import {PostgresAppDocsStore} from "./data-store/PostgresAppDocsStore";
 import {ConsumerRegistry} from "./queuing/ConsumerRegistry";
 import {Dispatcher} from "./queuing/Dispatcher";
 import {HostingServer} from "./hosting/HostingServer";
@@ -32,6 +35,10 @@ const hostingPort = Number(process.env.ANBARIC_HOSTING_PORT ?? 8787);
 const internalPort = Number(process.env.ANBARIC_INTERNAL_PORT ?? 8788);
 const appsDir = process.env.ANBARIC_APPS_DIR ?? "/tmp/anbaric-apps";
 
+// Generates user docs from an app's source on deploy; no-ops without an AI
+// gateway token. The build layer calls it fire-and-forget off the deploy path.
+const docGenerator = new DocGenerator(new GatewayDocModel(), new PostgresAppDocsStore(pool));
+
 const buildLayer = process.env.ANBARIC_BUILD_LAYER === "docker"
     ? new DockerBuildLayer(appsDir, {
         baseImage: process.env.ANBARIC_APP_BASE_IMAGE ?? "anbaric-v2-platform:local",
@@ -39,6 +46,7 @@ const buildLayer = process.env.ANBARIC_BUILD_LAYER === "docker"
         platformUrl: process.env.ANBARIC_PLATFORM_INTERNAL_URL ?? `http://localhost:${internalPort}`,
         sqlDatabaseUrl: process.env.ANBARIC_APP_SQL_DATABASE_URL,
         sqlSchema: process.env.ANBARIC_SQL_SCHEMA,
+        docGenerator,
     })
     : process.env.ANBARIC_BUILD_LAYER === "fargate"
     ? new FargateBuildLayer(appsDir, {
@@ -60,6 +68,7 @@ const buildLayer = process.env.ANBARIC_BUILD_LAYER === "docker"
         servicesApiKey: process.env.ANBARIC_SERVICES_API_KEY,
         sqlDatabaseUrlSecretArn: process.env.ANBARIC_AWS_APP_SQL_URL_SECRET,
         sqlSchema: process.env.ANBARIC_SQL_SCHEMA,
+        docGenerator,
     })
     : undefined;