Docs Pack

A docs pack is the self-contained artifact by which a service publishes its end-user documentation and its API surface to the AI knowledge base. It is built at build time, served over a shielded route, and pulled by the AI microservice on lifecycle events — the KB always mirrors the set of currently-live services.

Code
dist/docs-pack/
  manifest.json    # { schema, repo, generated_at, files[{path,sha256,bytes}], has_openapi }
  docs/...         # docs/user-guide copied verbatim (incl. _order.json, generated/)
  openapi.json     # the service's runtime OpenAPI spec (optional but standard)

Building — buildDocsPack

Code
import { buildDocsPack } from "@primebrick/sdk";
import { MY_OPENAPI_SPEC } from "../src/openapi.js";

await buildDocsPack({
  repo: "emailsender",            // becomes the KB's repo key for these docs
  docsDir: "docs/user-guide",     // OPTIONAL — omit for openapi-only packs
  outDir: "dist/docs-pack",
  openapi: MY_OPENAPI_SPEC,       // runtime spec object — never a hand-kept file
});

• docsDir is copied verbatim — _order.json, generated/ pages, and nested folders all travel. Dev-only services omit it entirely: their pack is a manifest + openapi.json (their docs live in docs/dev-guide and never enter the KB).
• openapi accepts the spec object — services generate it at module load via buildOpenApiSpec/entityCrudSpec/rpcSpec, so the pack always carries exactly what the service serves. A file-based openapiPath alternative exists for exotic cases.
• generators?: GenerateDocsFn[] run after the raw copy — the repo's own metadata extractors emit derived pages into the same tree (the BE uses this slot via its own pre-step; see its generate:docs script).
• manifest.json records a sha256 per file — the AI's hash-diff ingestion re-embeds only what changed.

The standard wiring is one scripts/build-docs-pack.ts (~15 lines) per service, exposed as pnpm generate:docs and invoked in the build chain.

Serving — docsPackRouteHandler

Code
docsPackRouteHandler(join(process.cwd(), "dist", "docs-pack"))

Produces an RouteHandler for composeRouteHandlers serving GET /api/v1/system/docs/pack (payload: manifest + all docs + spec). The route is auth: "public" in route-table terms because the real wall is the client-identity gate — the request must carry the client-shield secret, which only services (and the BE proxy) possess.

Auto-capability — ServiceRegistrar

createMicroservice defaults docsPackDir to <cwd>/dist/docs-pack. When a manifest.json exists there, docs_pack is appended to the registered capabilities[] automatically — a service advertises its pack with zero manual configuration.

Pulling — fetchDocsPack

Code
const payload = await fetchDocsPack(baseUrl);

Wraps internalFetch (identity headers + client-shield secret) — the only caller today is the AI ingestion subscriber, which validates the payload with parseDocsPackPayload before ingesting.

The full loop

Code
service build → generate:docs → dist/docs-pack (docs + openapi.json)
     │ boot
     ├─ ServiceRegistrar detects manifest → capabilities += "docs_pack"
     ├─ GET /api/v1/system/docs/pack live (client-shield gated)
     └─ service.register broadcast
              │
              ▼
   AI subscriber → fetchDocsPack(base_url) → parse → ingest (repo-scoped)
   service.unregister → delete repo docs
   gateway_online   → re-pull BE pack (BE doesn't register via NATS)

Rules of thumb: docs reach the KB only via packs; the filesystem pipeline is a dev fallback (docs_fs_pipeline). FE/DAL/SDK ship no packs — they are dev-only repos.