Prompt: "Write docs for this repo"
LLM -> docs/quickstart.mdx

Evidence Pack -> AI -> Content IR -> Validator -> MDX emitter -> diff

packages/ai/
  src/
    provider.ts
    model.ts
    job.ts
    prompt.ts
    evidence.ts
    output-schema.ts
    structured-output.ts
    generation-runner.ts
    retries.ts
    cache.ts
    cost.ts
    grounding.ts
    safety.ts
    diagnostics.ts

packages/ai-tasks/
  src/
    page-planner.ts
    doc-writer.ts
    doc-reviewer.ts
    fact-checker.ts
    diff-updater.ts

export type AiProvider = {
  id: string;
  listModels(): Promise<AiModelInfo[]>;
  generate(input: AiGenerateInput): Promise<AiGenerateResult>;
};

export type AiModelInfo = {
  id: string;
  supportsJsonSchema: boolean;
  supportsToolCalls: boolean;
  supportsStreaming: boolean;
  maxInputTokens?: number;
  maxOutputTokens?: number;
  cost?: {
    inputPerMillion?: number;
    outputPerMillion?: number;
  };
};

export type AiGenerateInput = {
  model: string;
  system: string;
  messages: AiMessage[];
  output?: AiOutputContract;
  temperature: number;
  maxOutputTokens?: number;
  metadata?: Record<string, string>;
  abortSignal?: AbortSignal;
};

export type AiMessage =
  | { role: "user"; content: string }
  | { role: "assistant"; content: string };

export type AiGenerateResult = {
  text: string;
  structured?: unknown;
  usage?: AiUsage;
  providerMetadata?: Record<string, unknown>;
};

{
  "ai": {
    "enabled": true,
    "provider": "openai-compatible",
    "model": "docs-writer",
    "reviewModel": "docs-reviewer",
    "temperature": 0.2,
    "maxOutputTokens": 6000
  }
}

export type AiModelRole =
  | "planner"
  | "writer"
  | "reviewer"
  | "summarizer"
  | "factChecker"
  | "embedding";

export type AiModelConfig = {
  default: string;
  roles: Partial<Record<AiModelRole, string>>;
};

{
  "ai": {
    "enabled": false
  }
}

export type AiConfig = {
  enabled: boolean;
  provider: string;
  model: string;
  apiKeyEnv?: string;
  temperature: number;
  maxInputTokens: number;
  maxOutputTokens: number;
  allowSendingSource: boolean;
  allowSendingPrivateDocs: boolean;
  cache: {
    enabled: boolean;
    path: string;
  };
  budget: {
    maxRequestsPerRun?: number;
    maxInputTokensPerRun?: number;
    maxCostUsdPerRun?: number;
  };
};

export type GenerationJob = {
  id: string;
  type: GenerationJobType;
  status: GenerationJobStatus;
  request: GenerationRequest;
  createdAt: string;
  updatedAt: string;
  diagnostics: Diagnostic[];
};

export type GenerationJobType =
  | "planPage"
  | "writePage"
  | "reviewPage"
  | "updatePageFromDiff"
  | "summarizeEvidence"
  | "generateTroubleshooting"
  | "generateGuide";

export type GenerationJobStatus =
  | "queued"
  | "retrievingContext"
  | "prompting"
  | "validating"
  | "readyForReview"
  | "failed"
  | "cancelled"
  | "applied";

export type GenerationRequest = {
  objective: string;
  target?: GenerationTarget;
  constraints: GenerationConstraint[];
  contextPolicy: ContextPolicy;
  outputPolicy: OutputPolicy;
};

export type GenerationTarget =
  | { type: "newPage"; pageKind: PageKind; routeHint?: string }
  | { type: "existingPage"; path: string; updateMode: "replaceManagedRegions" | "suggestPatch" }
  | { type: "apiOperation"; operationKey: OperationKey }
  | { type: "cliCommand"; commandId: string }
  | { type: "configReference"; schemaId: string };

export type GenerationConstraint =
  | { type: "tone"; value: "concise" | "tutorial" | "reference" }
  | { type: "audience"; value: string }
  | { type: "maxSections"; value: number }
  | { type: "allowedComponents"; value: string[] }
  | { type: "mustCiteEvidence"; value: boolean };

export type ContextPolicy = {
  maxItems: number;
  maxTokens: number;
  includeSourceCode: boolean;
  includeTests: boolean;
  includeExamples: boolean;
  includeExistingDocs: boolean;
  includeOpenApi: boolean;
  sensitivity: {
    allowInternal: boolean;
    allowSecretLike: false;
  };
};

export type OutputPolicy = {
  format: "contentIr" | "pagePlan" | "patchPlan" | "reviewReport";
  requireStructuredOutput: boolean;
  allowMarkdown: boolean;
  allowedComponents: string[];
  maxBlocks: number;
  requireProvenanceRefs: boolean;
};

{
  format: "contentIr",
  requireStructuredOutput: true,
  allowMarkdown: false,
  allowedComponents: ["Callout", "Steps", "Tabs", "CardGroup"],
  requireProvenanceRefs: true
}

export type EvidencePack = {
  id: string;
  objective: string;
  items: EvidenceItem[];
  constraints: string[];
  missingEvidence: MissingEvidence[];
  tokenEstimate: number;
};

export type EvidenceItem = {
  id: string;
  kind:
    | "docPage"
    | "codeSymbol"
    | "semanticArtifact"
    | "openapiOperation"
    | "configField"
    | "cliCommand"
    | "example"
    | "test"
    | "provenance";
  title: string;
  content: string;
  provenance: ProvenanceRef[];
  confidence: Confidence;
  priority: number;
};

export type MissingEvidence = {
  topic: string;
  reason: string;
  impact: "low" | "medium" | "high";
};

[EVIDENCE cli:docforge-build]
Kind: cliCommand
Confidence: high
Source: src/commands/build.ts:12-48

Command: docforge build
Description: Build the static documentation site.
Options:
- --out <dir>: Override output directory.
- --strict: Treat selected warnings as errors.
- --no-search: Skip search artifact generation.

[EVIDENCE symbol:buildSite]
Kind: codeSymbol
Confidence: high
Source: src/build/build-site.ts:18-96

Signature:
buildSite(args: BuildArgs): Promise<BuildResult>

Doc comment:
Runs the production build pipeline and writes static output.

[EVIDENCE openapi:public:createUser]
Kind: openapiOperation
Confidence: high
Source: openapi/public.yaml#/paths/~1users/post

POST /users
operationId: createUser
summary: Create user

You are a documentation generation engine.

Task:
Generate a Content IR draft for the requested page.

Hard rules:
- Use only facts from EVIDENCE items.
- Do not invent commands, options, endpoints, fields, or behavior.
- If evidence is missing, add a MissingInfo block instead of guessing.
- Every factual block must cite evidence IDs.
- Output must match the provided JSON schema.
- Do not output MDX.
- Use only allowed component block types.

Allowed components:
...

Evidence:
...

Return JSON only.

export const AiContentIrOutputSchema = z.object({
  page: z.object({
    title: z.string(),
    description: z.string(),
    kind: z.string(),
    blocks: z.array(ContentBlockSchema),
  }),
  evidenceUsage: z.array(z.object({
    evidenceId: z.string(),
    usedFor: z.string(),
  })),
  missingEvidence: z.array(z.object({
    topic: z.string(),
    reason: z.string(),
  })),
});

export function parseAiStructuredOutput<T>(
  raw: unknown,
  schema: z.ZodSchema<T>
): Result<T, Diagnostic[]> {
  const parsed = schema.safeParse(raw);

  if (!parsed.success) {
    return err(zodErrorsToDiagnostics(parsed.error));
  }

  return ok(parsed.data);
}

export type GeneratedContentIr = {
  title: string;
  description: string;
  kind: PageKind;
  blocks: ContentBlock[];
  provenance: BlockProvenance[];
};

export type BlockProvenance = {
  blockId: string;
  evidenceIds: string[];
};

{
  "type": "paragraph",
  "text": "The build command compiles the documentation site into static output.",
  "evidenceIds": ["cli:docforge-build"]
}

{
  "type": "missingInfo",
  "topic": "Exact deployment command",
  "reason": "No deployment adapter or package script evidence was provided."
}

export type ExtractedClaimEntity =
  | { type: "cliCommand"; name: string }
  | { type: "cliOption"; name: string }
  | { type: "apiEndpoint"; method: string; path: string }
  | { type: "configField"; path: string }
  | { type: "codeSymbol"; name: string };

error ai.grounding.unknownCliCommand
Generated output mentions command "docforge deploy", but no evidence supports it.

Config field table must be generated from schema, not AI.

export type FormalContentPolicy = {
  apiOperations: "deterministicOnly";
  cliCommands: "deterministicOnly";
  configFields: "deterministicOnly";
  codeSamples: "deterministicOnly";
};

export type PatchPlan = {
  targetPath: string;
  changes: PatchChange[];
  summary: string;
  risk: "low" | "medium" | "high";
};

export type PatchChange =
  | { type: "insertManagedRegion"; afterHeading: string; content: ContentBlock[] }
  | { type: "replaceManagedRegion"; regionId: string; content: ContentBlock[] }
  | { type: "createPage"; page: GeneratedContentIr }
  | { type: "suggestManualEdit"; path: string; message: string };

{/* docforge:begin generated id="build-command-summary" source="cli:docforge-build" */}
...
{/* docforge:end generated */}

export async function runGenerationJob(
  job: GenerationJob,
  ctx: GenerationContext
): Promise<GenerationResult> {
  const evidence = await ctx.retriever.retrieve(job.request);

  const prompt = ctx.promptBuilder.build({
    request: job.request,
    evidence,
    outputPolicy: job.request.outputPolicy,
  });

  const aiResult = await ctx.provider.generate({
    model: ctx.modelSelector.select(job.type),
    system: prompt.system,
    messages: prompt.messages,
    output: prompt.outputContract,
    temperature: ctx.temperatureFor(job.type),
    maxOutputTokens: ctx.maxOutputTokens,
  });

  const parsed = parseAiOutput(aiResult, job.request.outputPolicy);

  const validation = await validateGeneratedOutput(parsed, {
    evidence,
    registry: ctx.componentRegistry,
    knowledgeStore: ctx.store,
  });

  if (!validation.ok) {
    return failedGeneration(job, validation.diagnostics);
  }

  const patch = await createPatchPlan(parsed.value, job.request, ctx);

  return {
    ok: true,
    jobId: job.id,
    evidence,
    output: parsed.value,
    patch,
    diagnostics: validation.diagnostics,
    usage: aiResult.usage,
  };
}

export type RetryPolicy = {
  maxAttempts: number;
  backoffMs: number;
  retryOn: RetryReason[];
};

Your previous output did not match the required JSON schema.

Validation errors:
- page.blocks[3].type must be one of paragraph, heading, callout
- evidenceUsage[2].evidenceId references unknown evidence item

Return corrected JSON only.

export type AiCacheKey = {
  provider: string;
  model: string;
  promptHash: string;
  outputSchemaHash: string;
  temperature: number;
};

.docforge/cache/ai/

{
  "key": "...",
  "createdAt": "...",
  "usage": { "inputTokens": 1234, "outputTokens": 567 },
  "response": { ... }
}

export type AiBudgetState = {
  requests: number;
  inputTokens: number;
  outputTokens: number;
  estimatedCostUsd: number;
};

export function checkBudget(state: AiBudgetState, config: AiConfig): Diagnostic[] {
  const diagnostics: Diagnostic[] = [];

  if (config.budget.maxRequestsPerRun && state.requests >= config.budget.maxRequestsPerRun) {
    diagnostics.push({
      code: "ai.budget.maxRequestsExceeded",
      severity: "error",
      category: "ai",
      message: "AI request budget exceeded for this run.",
    });
  }

  return diagnostics;
}

AI usage:
  requests: 3
  input tokens: 18,420
  output tokens: 4,208
  estimated cost: $0.12

export type AiGenerationEvent =
  | { type: "started"; jobId: string }
  | { type: "retrievedEvidence"; items: number }
  | { type: "token"; text: string }
  | { type: "validationStarted" }
  | { type: "diagnostic"; diagnostic: Diagnostic }
  | { type: "completed"; result: GenerationResult };

export function validateEvidenceForAi(
  evidence: EvidencePack,
  config: AiConfig
): Diagnostic[] {
  const diagnostics: Diagnostic[] = [];

  for (const item of evidence.items) {
    if (item.kind === "codeSymbol" && !config.allowSendingSource) {
      diagnostics.push({
        code: "ai.privacy.sourceNotAllowed",
        severity: "error",
        category: "ai",
        message: "AI evidence includes source code, but sending source is disabled.",
      });
    }

    if (containsSecretLikePattern(item.content)) {
      diagnostics.push({
        code: "ai.privacy.secretLikeEvidence",
        severity: "error",
        category: "ai",
        message: "AI evidence appears to contain secret-like content.",
      });
    }
  }

  return diagnostics;
}

export function redactEvidenceItem(item: EvidenceItem): EvidenceItem {
  return {
    ...item,
    content: redactSecrets(item.content),
  };
}

docforge generate guide --topic "build pipeline" --dry-run

Generated draft ready for review.

Target:
  docs/guides/build-pipeline.mdx

Evidence:
  8 items

Diagnostics:
  0 errors, 2 warnings

Diff:
  + ...

docforge generate guide --topic "build pipeline" --apply

docforge generate page --kind guide --topic "build pipeline"
docforge generate api-guides
docforge generate config-reference
docforge generate cli-reference
docforge update docs --from-diff
docforge review docs

--dry-run
--apply
--target docs/guides/build.mdx
--format json
--max-context 12000
--model ...
--no-ai-cache

export type AiGenerationReport = {
  jobId: string;
  objective: string;
  model: string;
  evidenceItems: number;
  diagnostics: Diagnostic[];
  usage?: AiUsage;
  outputFiles: Array<{
    path: string;
    action: "create" | "update" | "suggest";
  }>;
  provenance: Array<{
    outputBlockId: string;
    evidenceIds: string[];
  }>;
};

.docforge/reports/generation/<job-id>.json

{
  "ai": {
    "tracing": {
      "enabled": true,
      "includePrompts": false,
      "includeResponses": false
    }
  }
}

.docforge/traces/ai/<job-id>/
  evidence.json
  prompt.redacted.txt
  response.redacted.json
  validation.json

export class FakeAiProvider implements AiProvider {
  constructor(private readonly responses: unknown[]) {}

  async generate(input: AiGenerateInput): Promise<AiGenerateResult> {
    const response = this.responses.shift();

    return {
      text: typeof response === "string" ? response : JSON.stringify(response),
      structured: typeof response === "object" ? response : undefined,
      usage: { inputTokens: 100, outputTokens: 50 },
    };
  }
}

it("builds page writer prompt", () => {
  const prompt = buildDocWriterPrompt(fixtureRequest, fixtureEvidence);

  expect(prompt.system).toMatchSnapshot();
  expect(prompt.messages[0].content).toMatchSnapshot();
});

export type AiGenerationEvalCase = {
  id: string;
  objective: string;
  evidenceFixture: string;
  expectedEntities: string[];
  forbiddenEntities: string[];
  requiredSections: string[];
};