export type PagePlannerInput = {
  schemaVersion: "page-planner-input/v1";
  objective: PlanningObjective;
  project: ProjectPromptContext;
  docsInventory: DocsInventorySummary;
  navigation: NavigationSummary;
  coverage: DocumentationCoverageSummary;
  semanticArtifacts: SemanticArtifactSummary[];
  existingPages: ExistingPageSummary[];
  evidence: EvidenceItem[];
  constraints: PagePlanningConstraints;
};

export type PlanningObjective =
  | { type: "initialDocs"; scope: "full" | "minimal" | "api" | "cli" }
  | { type: "fillCoverageGaps"; artifactTypes: string[] }
  | { type: "updateForDiff"; changedArtifacts: string[] }
  | { type: "planSinglePage"; topic: string }
  | { type: "reorganizeNavigation"; scope: string };

export type DocsInventorySummary = {
  pagesTotal: number;
  pagesByKind: Record<PageKind, number>;
  generatedPages: number;
  manualPages: number;
  orphanPages: ExistingPageSummary[];
  duplicateTopics: DuplicateTopicSummary[];
  stalePages: StalePageSummary[];
};

export type ExistingPageSummary = {
  pageId: PageId;
  route: RoutePath;
  title: string;
  description?: string;
  kind: PageKind;
  sourcePath: string;
  generated: boolean;
  hidden: boolean;
  draft: boolean;
  documentedTargets: GraphNodeRef[];
  headings: string[];
  tags: string[];
};

export type SemanticArtifactSummary = {
  id: string;
  type:
    | "apiEndpoint"
    | "cliCommand"
    | "configField"
    | "packageExport"
    | "event"
    | "job"
    | "example"
    | "test";
  key: string;
  title: string;
  visibility: "public" | "internal" | "admin" | "unknown";
  confidence: Confidence;
  documentedBy: PageId[];
  sourceEvidenceIds: string[];
  tags: string[];
  changed?: boolean;
};

{
  "id": "cli:docforge-build",
  "type": "cliCommand",
  "key": "docforge build",
  "title": "Build static documentation site",
  "visibility": "public",
  "confidence": "high",
  "documentedBy": [],
  "sourceEvidenceIds": ["ev_cli_build"],
  "tags": ["cli", "build"]
}

export type DocumentationCoverageSummary = {
  groups: CoverageGroupSummary[];
};

export type CoverageGroupSummary = {
  artifactType: string;
  total: number;
  documented: number;
  undocumented: SemanticArtifactSummary[];
  stale: SemanticArtifactSummary[];
};

{
  "artifactType": "cliCommand",
  "total": 8,
  "documented": 5,
  "undocumented": [
    { "id": "cli:docforge-index", "key": "docforge index" }
  ]
}

export type PagePlanningConstraints = {
  maxNewPages: number;
  maxUpdatedPages: number;
  allowedPageKinds: PageKind[];
  routePrefix?: string;
  preserveManualPages: boolean;
  allowGeneratedPages: boolean;
  includeInternal: boolean;
  preferredStrategy: "minimal" | "comprehensive" | "referenceFirst" | "guideFirst";
  navigationPolicy: "doNotChange" | "proposeOnly" | "allowGeneratedSections";
};

{
  "maxNewPages": 10,
  "maxUpdatedPages": 5,
  "preserveManualPages": true,
  "allowGeneratedPages": true,
  "includeInternal": false,
  "preferredStrategy": "referenceFirst",
  "navigationPolicy": "proposeOnly"
}

export type PagePlanOutput = {
  schemaVersion: "page-plan/v1";
  summary: string;
  actions: PlannedPageAction[];
  navigationSuggestions: NavigationSuggestion[];
  coverageImpact: CoverageImpactSummary;
  missingEvidence: MissingEvidence[];
  diagnostics: DraftDiagnostic[];
};

export type PlannedPageAction =
  | CreatePageAction
  | UpdatePageAction
  | SkipPageAction
  | SplitPageAction
  | MergePageAction;

export type CreatePageAction = {
  action: "create";
  id: string;
  title: string;
  route: RoutePath;
  sourcePath?: string;
  kind: PageKind;
  priority: "must" | "should" | "could";
  purpose: string;
  audience: "beginner" | "intermediate" | "advanced";
  targetArtifacts: GraphNodeRef[];
  evidenceIds: string[];
  requiredSections: PlannedSection[];
  generationMode: "deterministic" | "aiDraft" | "hybrid";
  rationale: string;
};

export type UpdatePageAction = {
  action: "update";
  pageId: PageId;
  reason: "stale" | "coverageGap" | "structure" | "quality" | "diff";
  priority: "must" | "should" | "could";
  targetArtifacts: GraphNodeRef[];
  evidenceIds: string[];
  requiredChanges: PlannedChange[];
  rationale: string;
};

export type SkipPageAction = {
  action: "skip";
  targetArtifacts: GraphNodeRef[];
  reason: "alreadyDocumented" | "internal" | "lowConfidence" | "outOfScope" | "missingEvidence";
  rationale: string;
};

export type PlannedSection = {
  id: string;
  title: string;
  purpose: string;
  requiredEvidenceIds: string[];
  expectedBlocks: Array<
    | "paragraph"
    | "steps"
    | "code"
    | "table"
    | "callout"
    | "apiOperation"
    | "cardGroup"
  >;
  acceptanceCriteria: string[];
};

{
  "id": "build-options",
  "title": "Build options",
  "purpose": "Explain the key flags for the build command.",
  "requiredEvidenceIds": ["ev_cli_build"],
  "expectedBlocks": ["table", "paragraph"],
  "acceptanceCriteria": [
    "Includes --out, --strict, and --no-search.",
    "Does not mention flags not present in CLI evidence."
  ]
}

export type GenerationMode =
  | "deterministic"
  | "aiDraft"
  | "hybrid";

Configuration and Deployment and API Auth and Troubleshooting

Configuration Reference
Deploy Documentation Site
Authentication Concepts
Troubleshooting Build Failures

export function validatePlannedRoutes(
  plan: PagePlanOutput,
  existingRoutes: Set<RoutePath>
): Diagnostic[] {
  const diagnostics: Diagnostic[] = [];
  const planned = new Map<RoutePath, PlannedPageAction[]>();

  for (const action of plan.actions) {
    if (action.action !== "create") continue;

    const group = planned.get(action.route) ?? [];
    group.push(action);
    planned.set(action.route, group);

    if (existingRoutes.has(action.route)) {
      diagnostics.push({
        code: "planner.route.exists",
        severity: "error",
        category: "ai",
        message: `Planned route already exists: ${action.route}.`,
      });
    }
  }

  for (const [route, actions] of planned) {
    if (actions.length > 1) {
      diagnostics.push({
        code: "planner.route.duplicate",
        severity: "error",
        category: "ai",
        message: `Multiple planned pages use route: ${route}.`,
      });
    }
  }

  return diagnostics;
}

{
  "summary": "Plan creates a minimal docs set with overview, quickstart, CLI reference, config reference, and API reference generated from the OpenAPI spec."
}

{
  "type": "fillCoverageGaps",
  "artifactTypes": ["cliCommand", "configField"]
}

{
  "action": "update",
  "pageId": "reference-configuration",
  "reason": "coverageGap",
  "targetArtifacts": [
    { "type": "semanticArtifact", "id": "config:search.enabled" }
  ]
}

export type ChangedArtifactSummary = {
  artifactId: ArtifactId;
  path: string;
  changedSymbols: GraphNodeRef[];
  changedSemanticArtifacts: GraphNodeRef[];
  affectedPages: PageId[];
};

Generate guide for setting up API reference from OpenAPI.

export type NavigationSuggestion = {
  type: "addPage" | "addGroup" | "addGeneratedSection" | "movePage";
  title: string;
  targetRoute?: RoutePath;
  parentGroup?: string;
  reason: string;
  confidence: Confidence;
};

{
  "type": "addPage",
  "title": "Configuration",
  "targetRoute": "/reference/configuration",
  "parentGroup": "Reference",
  "reason": "New configuration reference page should be discoverable under Reference.",
  "confidence": "high"
}

export type CoverageImpactSummary = {
  before: Record<string, { total: number; documented: number }>;
  afterEstimate: Record<string, { total: number; documented: number }>;
  newlyDocumentedArtifactIds: string[];
  remainingGaps: string[];
};

{
  "before": { "cliCommand": { "total": 8, "documented": 5 } },
  "afterEstimate": { "cliCommand": { "total": 8, "documented": 8 } },
  "newlyDocumentedArtifactIds": ["cli:docforge-index", "cli:docforge-graph"],
  "remainingGaps": []
}

You are a documentation page planning agent.
You create a plan, not final documentation prose.
Use only supplied evidence, docs inventory, semantic artifact summaries, and constraints.
Do not invent pages for internal or low-confidence artifacts unless explicitly requested.
Prefer updating existing pages over creating duplicates.
Preserve manual pages.
Return only JSON matching PagePlanOutput schema.

If an existing page already covers an artifact or topic, plan an update or skip, not a duplicate page.

{
  "evidenceIds": ["ev_cli_build", "ev_config_build_output_dir"]
}

{
  "requiredEvidenceIds": ["ev_cli_build"]
}

export function validateNoInternalTargets(
  plan: PagePlanOutput,
  artifacts: Map<string, SemanticArtifactSummary>,
  includeInternal: boolean
): Diagnostic[] {
  if (includeInternal) return [];

  const diagnostics: Diagnostic[] = [];

  for (const action of plan.actions) {
    const targets = "targetArtifacts" in action ? action.targetArtifacts : [];

    for (const target of targets) {
      const artifact = artifacts.get(target.id);
      if (artifact?.visibility === "internal") {
        diagnostics.push({
          code: "planner.target.internalNotAllowed",
          severity: "error",
          category: "ai",
          message: `Plan targets internal artifact ${target.id}, but internal docs are disabled.`,
        });
      }
    }
  }

  return diagnostics;
}

if (action.action === "update" && page.generated === false) {
  // allowed only as suggestion, not auto-apply
}

applyPolicy: "auto" | "reviewRequired";

export type SplitPageAction = {
  action: "split";
  pageId: PageId;
  reason: string;
  proposedPages: Array<{
    title: string;
    route: RoutePath;
    kind: PageKind;
    targetSections: string[];
  }>;
  priority: "should" | "could";
  applyPolicy: "reviewRequired";
};

export type MergePageAction = {
  action: "merge";
  pageIds: PageId[];
  proposedTargetPage: {
    title: string;
    route: RoutePath;
    kind: PageKind;
  };
  reason: string;
  priority: "should" | "could";
  applyPolicy: "reviewRequired";
};

"generationMode": "deterministic"

export type PlannedSection = {
  generationMode?: "deterministic" | "aiDraft" | "hybrid";
};

{
  "title": "Generate API reference from OpenAPI",
  "requiredSections": [
    {
      "title": "Prerequisites",
      "purpose": "List required OpenAPI spec and config."
    },
    {
      "title": "Configure OpenAPI ingestion",
      "purpose": "Show docforge.config.json openapi.specs."
    },
    {
      "title": "Build and verify",
      "purpose": "Run build/check and explain expected output."
    }
  ]
}

Build fails with unknown MDX component
OpenAPI operation missing operationId
Search index too large
Dev server reload loop

{
  "includeInternal": false
}

{
  "includeInternal": true,
  "allowedPageKinds": ["architecture", "adr", "concept"]
}

Start here
Guides
Reference
API Reference
Troubleshooting

export function defaultPrefixForPageKind(kind: PageKind): string {
  switch (kind) {
    case "howTo": return "/guides";
    case "reference": return "/reference";
    case "apiReference": return "/api-reference";
    case "troubleshooting": return "/troubleshooting";
    case "concept": return "/concepts";
    default: return "";
  }
}

export type PlannedRoute = {
  proposed: RoutePath;
  stabilityKey: string;
};

page:cli:docforge-build -> /reference/cli/build

{
  "question": "Need example command output for docforge init.",
  "severity": "nonBlocking",
  "suggestedSources": ["README", "tests", "CLI snapshots"]
}

export type PlannedActionRisk = {
  level: "low" | "medium" | "high";
  reasons: string[];
};

export async function planDocumentation(
  input: PagePlannerInput,
  ctx: AiPlanningContext
): Promise<PagePlanResult> {
  const prompt = renderPagePlannerPrompt(input);
  const raw = await ctx.model.generateJson(prompt, ctx.modelConfig);
  const parsed = parseModelJsonOutput(raw);
  const schemaResult = PagePlanOutputSchema.safeParse(parsed);

  if (!schemaResult.success) {
    return repairPlannerOutput(input, parsed, schemaResult.error, ctx);
  }

  const plan = schemaResult.data;
  const diagnostics = [
    ...validatePlannerEvidence(plan, input.evidence),
    ...validatePlannedRoutes(plan, existingRouteSet(input)),
    ...validatePlannerConstraints(plan, input.constraints, input),
    ...validatePlannerTargets(plan, input.semanticArtifacts),
  ];

  if (hasErrors(diagnostics)) {
    return repairOrFailPlan(input, plan, diagnostics, ctx);
  }

  return { plan, diagnostics };
}

export type GenerationJob =
  | DeterministicPageGenerationJob
  | AiWriterGenerationJob
  | PageUpdateJob
  | NavigationUpdateSuggestionJob;

export function createWriterJob(action: CreatePageAction): AiWriterGenerationJob {
  return {
    type: "writePage",
    pageId: action.id,
    title: action.title,
    route: action.route,
    kind: action.kind,
    evidenceIds: action.evidenceIds,
    requiredSections: action.requiredSections,
  };
}

Documentation plan:

Create:
  [must] /quickstart
    Quickstart
    evidence: ev_cli_init, ev_cli_dev, ev_cli_build

  [must] /reference/configuration
    Configuration Reference
    deterministic/hybrid
    targets: 62 config fields

Update:
  [should] /reference/cli
    Add missing command: docforge index

Skip:
  internal endpoint GET /metrics
    reason: internal

docforge generate --plan
docforge generate --apply
docforge generate --apply --only must

applyPolicy: "auto" | "reviewRequired" | "manualOnly";

it("rejects create action without evidence", () => {
  const plan = pagePlan({
    actions: [
      createAction({ evidenceIds: [] }),
    ],
  });

  const diagnostics = validatePlannerEvidence(plan, evidence);

  expect(diagnostics).toContainEqual(
    expect.objectContaining({ code: "planner.evidence.missing" })
  );
});

it("rejects planned route that already exists", () => {
  const diagnostics = validatePlannedRoutes(planWithRoute("/quickstart"), new Set(["/quickstart"]));

  expect(diagnostics).toContainEqual(
    expect.objectContaining({ code: "planner.route.exists" })
  );
});

it("rejects internal target when internal docs disabled", () => {
  const diagnostics = validateNoInternalTargets(plan, artifactMap, false);

  expect(diagnostics).toContainEqual(
    expect.objectContaining({ code: "planner.target.internalNotAllowed" })
  );
});

export type PlannerEvalCase = {
  name: string;
  input: PagePlannerInput;
  expectedActions: Array<{
    action: "create" | "update" | "skip";
    targetId?: string;
    route?: string;
  }>;
  forbiddenActions?: Array<{
    action: "create" | "update";
    targetId?: string;
    route?: string;
  }>;
};

class FakePlannerModel implements ModelClient {
  constructor(private readonly output: unknown) {}

  async generateJson(): Promise<string> {
    return JSON.stringify(this.output);
  }
}

export type PlannerQualityMetrics = {
  plannedCreate: number;
  plannedUpdate: number;
  plannedSkip: number;
  duplicateRouteErrors: number;
  unknownEvidenceErrors: number;
  internalTargetErrors: number;
  coverageImprovementEstimate: number;
  reviewRequiredActions: number;
};

{
  "page": "# Quickstart\nInstall DocForge..."
}

/reference/build
/reference/cli-build
/reference/docforge-build

packages/doc-planner/
  src/
    input.ts
    output-schema.ts
    prompt.ts
    planner.ts
    validation/
      evidence.ts
      routes.ts
      targets.ts
      constraints.ts
      duplicates.ts
      apply-policy.ts
    jobs.ts
    coverage-impact.ts
    presentation.ts
    eval.ts
    __tests__/
      schema.test.ts
      route-validation.test.ts
      target-validation.test.ts
      job-conversion.test.ts
      eval-cases.test.ts