@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/usage-budget.d.ts

@@ -0,0 +1,28 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { AgentUsage } from './types.js';
+export declare function isAccountLimit(reason: string | undefined): boolean;
+export declare const budgetContext: AsyncLocalStorage<UsageBudget>;
+export declare class UsageBudget {
+    readonly file: string;
+    readonly maxTokens: number;
+    readonly maxUsd: number;
+    private sessions;
+    private stops;
+    private saving;
+    private lastSave;
+    stoppedReason: string | undefined;
+    constructor(file: string, maxTokens: number, maxUsd: number);
+    static open(root: string, planId: string, maxUsd?: number): Promise<UsageBudget>;
+    get totals(): {
+        tokens: number;
+        cost: number;
+    };
+    get remainingUsd(): number | undefined;
+    assertAvailable(): void;
+    register(stop: () => void): string;
+    update(id: string, usage: AgentUsage | undefined, reason?: string): void;
+    stop(reason: string): void;
+    finish(id: string, usage: AgentUsage | undefined, reason?: string): Promise<void>;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=usage-budget.d.ts.map

package/dist/usage-budget.js

@@ -0,0 +1,90 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export function isAccountLimit(reason) {
+    return /hit your (?:session|usage|weekly|daily) limit|usage limit|quota.{0,30}(?:exceeded|exhausted)|insufficient_quota|credit balance|rate.limit|budget exhausted/i.test(reason ?? '');
+}
+export const budgetContext = new AsyncLocalStorage();
+export class UsageBudget {
+    file;
+    maxTokens;
+    maxUsd;
+    sessions = {};
+    stops = new Map();
+    saving = Promise.resolve();
+    lastSave = 0;
+    stoppedReason;
+    constructor(file, maxTokens, maxUsd) {
+        this.file = file;
+        this.maxTokens = maxTokens;
+        this.maxUsd = maxUsd;
+    }
+    static async open(root, planId, maxUsd) {
+        // No limit unless one is set explicitly: a run should never stop on its own because of a built-in cap.
+        const positive = (raw, fallback) => Number.isFinite(Number(raw)) && Number(raw) > 0 ? Number(raw) : fallback;
+        if (!/^[\w-]+$/.test(planId))
+            throw new Error('Invalid budget plan ID');
+        const budget = new UsageBudget(join(root, '.doxloop', 'plans', planId, 'usage-budget.json'), positive(process.env.DOXLOOP_MAX_TOKENS, Number.POSITIVE_INFINITY), positive(process.env.DOXLOOP_MAX_USD, maxUsd ?? Number.POSITIVE_INFINITY));
+        try {
+            const saved = JSON.parse(await readFile(budget.file, 'utf8'));
+            if (!saved.sessions || typeof saved.sessions !== 'object' || Array.isArray(saved.sessions) || Object.values(saved.sessions).some((value) => !value || !Number.isFinite(value.tokens) || value.tokens < 0 || !Number.isFinite(value.cost) || value.cost < 0))
+                throw new Error('Invalid saved usage ledger');
+            budget.sessions = saved.sessions;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new Error(`Cannot read the saved usage budget: ${String(error)}. Preserve the ledger and repair it before resuming.`);
+        }
+        return budget;
+    }
+    get totals() {
+        return Object.values(this.sessions).reduce((a, b) => ({ tokens: a.tokens + b.tokens, cost: a.cost + b.cost }), { tokens: 0, cost: 0 });
+    }
+    get remainingUsd() { return Number.isFinite(this.maxUsd) ? Math.max(0, this.maxUsd - this.totals.cost) : undefined; }
+    assertAvailable() {
+        const totals = this.totals;
+        if (!this.stoppedReason && (totals.tokens >= this.maxTokens || totals.cost >= this.maxUsd))
+            this.stop(`Documentation budget exhausted (${totals.tokens} tokens, $${totals.cost.toFixed(2)}). Completed work is saved. Raise or clear DOXLOOP_MAX_TOKENS / DOXLOOP_MAX_USD or the project spend cap to continue this plan.`);
+        if (this.stoppedReason)
+            throw new Error(this.stoppedReason);
+    }
+    register(stop) { this.assertAvailable(); const id = randomUUID(); this.stops.set(id, stop); return id; }
+    update(id, usage, reason) {
+        if (usage)
+            this.sessions[id] = { tokens: usage.totalTokens, cost: usage.costUsd ?? 0 };
+        if (isAccountLimit(reason))
+            this.stop(`Agent account limit reached: ${reason}. Completed work is saved; resume after the allowance resets.`);
+        try {
+            this.assertAvailable();
+        }
+        catch { /* Stop callbacks checkpoint active sessions. */ }
+        if (Date.now() - this.lastSave > 2000) {
+            this.lastSave = Date.now();
+            void this.flush().catch(() => { });
+        }
+    }
+    stop(reason) {
+        if (this.stoppedReason)
+            return;
+        this.stoppedReason = reason;
+        for (const stop of this.stops.values())
+            stop();
+    }
+    async finish(id, usage, reason) {
+        this.stops.delete(id);
+        this.update(id, usage, reason);
+        await this.flush();
+    }
+    async flush() {
+        const value = JSON.stringify({ schemaVersion: 1, sessions: this.sessions, totals: this.totals });
+        this.saving = this.saving.catch(() => { }).then(async () => {
+            await mkdir(dirname(this.file), { recursive: true });
+            const temp = `${this.file}.${randomUUID()}.tmp`;
+            await writeFile(temp, value, { mode: 0o600 });
+            await rename(temp, this.file);
+        });
+        return this.saving;
+    }
+}
+//# sourceMappingURL=usage-budget.js.map

package/dist/validation.d.ts

@@ -1,4 +1,28 @@
-import type { ValidationResult } from './types.js';
+import type { DoxbrixNavNode, ValidationIssue, ValidationResult } from './types.js';
 export declare function validateProject(root: string): Promise<ValidationResult>;
+export interface DoxbrixNavigationEntry {
+    path: string;
+    section?: string;
+}
+/** Flatten Doxbrix navigation in reader order for validation and page discovery. */
+export declare function readDoxbrixNavigation(spaces: Array<{
+    name: string;
+    version?: string;
+    nav: DoxbrixNavNode[];
+}>): DoxbrixNavigationEntry[];
+/** Theme checks shared by validation and the branding panel's pre-write check. */
+export declare function validateDoxbrixTheme(value: unknown, contentRoot: string, configFile: string, issues: ValidationIssue[]): Promise<void>;
+/**
+ * Whether the section around an <ApiEndpoint> (from the heading before it to
+ * the next heading or endpoint) carries a fenced request for it: a cURL
+ * command, an HTTPie call, or a raw HTTP request line naming its path.
+ */
+export declare function hasRequestSample(masked: string, raw: string, start: number, end: number, path: string): boolean;
+/** A Mermaid diagram in any of the syntaxes the supported generators render. */
+export declare function hasDiagram(raw: string): boolean;
+export declare function validateShellExamples(raw: string, file: string): ValidationIssue[];
+export declare function validatePageDepth(body: string, file: string, planType?: string): ValidationIssue[];
+/** Generated scaffolding the authoring agent is told to replace: a starter marker or its placeholder language. */
+export declare function isStarterContent(content: string): boolean;
 export declare function formatValidation(result: ValidationResult): string;
 //# sourceMappingURL=validation.d.ts.map

package/dist/validation.js

@@ -1,22 +1,29 @@
+import { documentationCollections, collectionForPath } from './documentation-collections.js';
+import { contentLinks } from './content-links.js';
 import { access, readFile } from 'node:fs/promises';
 import { dirname, extname, join, relative, resolve } from 'node:path';
+import { EVIDENCE_MAP_FILE, readEvidenceMap } from './evidence.js';
+import { readSyncState } from './sync.js';
 import { pathExists, resolveContainedDirectory } from './fs.js';
 import { loadGeneratorAdapter } from './generators.js';
 import { loadPages, loadProject, loadSiteConfig, pageId, readPage, relativePath, siteConfigPath, } from './project.js';
 export async function validateProject(root) {
     const issues = [];
     const project = await loadProject(root);
-    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Validation content directory');
+    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Validation content directory', { allowRoot: project.generator === 'doxbrix' });
+    const collections = await documentationCollections(root, project);
     const files = await loadPages(root, project);
     const pages = files.map((path) => pageId(contentRoot, path));
     const pageSet = new Set(pages);
     const adapter = project.generator === 'doxbrix'
         ? undefined
         : await loadGeneratorAdapter(root, project);
+    const planTypes = await plannedPageTypes(root, project);
     if (project.generator === 'doxbrix') {
         const site = await loadSiteConfig(root, project);
         const configFile = relativePath(root, await siteConfigPath(root, project));
-        validateDoxbrixNavigation(site.spaces, pageSet, pages, configFile, issues);
+        const defaultVersion = (site.versions?.find((entry) => entry.default || entry.isDefault) ?? site.versions?.[0])?.version;
+        validateDoxbrixNavigation(site.spaces.map((space) => ({ ...space, ...(defaultVersion && !space.version ? { version: defaultVersion } : {}) })), pageSet, pages, configFile, issues);
         await validateDoxbrixTheme(site.theme, contentRoot, configFile, issues);
     }
     else {
@@ -24,8 +31,8 @@ export async function validateProject(root) {
             root,
             contentRoot,
             project,
-            pages: files,
-            pageIds: pages,
+            pages: files.filter((file) => file.startsWith(`${contentRoot}/`)),
+            pageIds: files.filter((file) => file.startsWith(`${contentRoot}/`)).map((file) => pageId(contentRoot, file)),
         })));
     }
     for (const path of files) {
@@ -51,16 +58,106 @@ export async function validateProject(root) {
             issues.push(...validateDoxbrixComponents(raw, file));
         }
         issues.push(...validateProfessionalContent(page.body, raw, file));
-        if ((adapter?.project.contentFormat ?? 'markdown') === 'markdown') {
-            issues.push(...(await validateLinks(path, contentRoot, raw, root, adapter)));
+        issues.push(...validateShellExamples(raw, file));
+        const planned = planTypes.get(file.replace(/\.[^./]+$/, ''));
+        issues.push(...validatePageDepth(page.body, file, planned?.type));
+        if (planned?.diagram === 'required' && !hasDiagram(raw)) {
+            issues.push(warning('missing-diagram', 'The approved plan requires a diagram on this page. Add a Mermaid block that shows the model or lifecycle it explains.', file));
         }
+        issues.push(...(await validateLinks(path, resolve(root, collectionForPath(collections, file)?.directory ?? project.contentDir), raw, root, adapter)));
     }
+    issues.push(...(await validateEvidenceMap(root, files.map((path) => relativePath(root, path)), project)));
     const errors = issues.filter((issue) => issue.severity === 'error').length;
     const warnings = issues.length - errors;
     return { issues, pages, errors, warnings };
 }
+/**
+ * Coverage checks for `.doxloop/evidence-map.json`. These are warnings and run
+ * only once a project has a map, so projects that predate it are unaffected
+ * and a partially recorded map never blocks validation.
+ */
+async function validateEvidenceMap(root, pageFiles, project) {
+    const map = await readEvidenceMap(root);
+    if (!map)
+        return [];
+    const issues = [];
+    const pages = new Set(pageFiles);
+    const sourceNames = new Set(project.sources.map((source) => source.name));
+    const pathCoverage = new Map();
+    const syncState = project.sync.maxVerificationAgeDays ? await readSyncState(root) : undefined;
+    for (const [page, evidence] of Object.entries(map.pages)) {
+        if (!pages.has(page)) {
+            issues.push(warning('evidence-map-orphan', `The evidence map records "${page}", which is not a documentation page. Remove the entry when a page is deleted or renamed.`, EVIDENCE_MAP_FILE));
+            continue;
+        }
+        for (const entry of evidence.sources) {
+            if (!sourceNames.has(entry.source)) {
+                issues.push(warning('evidence-map-unknown-source', `The evidence map binds "${page}" to source "${entry.source}", which is not configured.`, EVIDENCE_MAP_FILE));
+            }
+            for (const path of entry.paths ?? []) {
+                const key = `${entry.source}:${path}`;
+                const covered = pathCoverage.get(key) ?? new Set();
+                covered.add(page);
+                pathCoverage.set(key, covered);
+            }
+            if (project.sync.maxVerificationAgeDays) {
+                const record = syncState?.sources[entry.source];
+                const revision = evidence.verifiedAt?.[entry.source];
+                const verifiedOn = evidence.verifiedOn?.[entry.source] ?? (record && revision && [record.commit, record.contentFingerprint].includes(revision) ? record.recordedAt : undefined);
+                const ageDays = verifiedOn ? Math.floor((Date.now() - Date.parse(verifiedOn)) / 86_400_000) : Number.POSITIVE_INFINITY;
+                if (ageDays > project.sync.maxVerificationAgeDays) {
+                    const severity = project.sync.maxVerificationAgeSeverity === 'fail' ? 'error' : 'warning';
+                    issues.push({
+                        severity,
+                        code: 'evidence-verification-expired',
+                        message: `Verification for source "${entry.source}" is ${Number.isFinite(ageDays) ? `${ageDays} days old` : 'not dated'}; the maximum is ${project.sync.maxVerificationAgeDays} days. Re-verify the page even when the source revision is unchanged.`,
+                        file: page,
+                    });
+                }
+            }
+        }
+        if (evidence.confidence === 'needs-human') {
+            issues.push(warning('evidence-unverified', 'A claim on this page could not be verified from configured evidence and needs human confirmation.', page));
+        }
+    }
+    if (pageFiles.length >= 4) {
+        for (const [key, covered] of pathCoverage) {
+            if (covered.size <= pageFiles.length / 2)
+                continue;
+            const separator = key.indexOf(':');
+            const source = key.slice(0, separator);
+            const path = key.slice(separator + 1);
+            issues.push(warning('evidence-map-broad-path', `Source path "${path}" from "${source}" is attached to ${covered.size} of ${pageFiles.length} pages. Verify that each page directly depends on it; broad evidence makes localized changes mark most documentation stale.`, EVIDENCE_MAP_FILE));
+        }
+    }
+    for (const page of pageFiles) {
+        if (!map.pages[page]) {
+            issues.push(warning('evidence-map-missing-page', 'This page has no evidence-map entry, so `doxloop check` cannot report when its sources change.', page));
+        }
+    }
+    return issues;
+}
+/** Flatten Doxbrix navigation in reader order for validation and page discovery. */
+export function readDoxbrixNavigation(spaces) {
+    const entries = [];
+    const visit = (nodes, section) => {
+        for (const node of nodes) {
+            if (node.type === 'page' && typeof node.file === 'string' && node.file.trim()) {
+                entries.push({ path: node.file, ...(section ? { section } : {}) });
+            }
+            else if (node.type === 'group' && Array.isArray(node.items)) {
+                visit(node.items, node.label || section);
+            }
+        }
+    };
+    for (const space of spaces)
+        visit(space.nav, space.name);
+    return entries;
+}
 function validateDoxbrixNavigation(spaces, pageSet, pages, configFile, issues) {
     const navigation = new Set();
+    const versions = new Map();
+    let versionNavigation = new Set();
     if (spaces.length === 0) {
         issues.push(error('navigation-spaces', 'Doxbrix docs.json needs at least one space.', configFile));
     }
@@ -76,10 +173,11 @@ function validateDoxbrixNavigation(spaces, pageSet, pages, configFile, issues) {
                     issues.push(error('navigation-page', `${nodeLocation} needs a page file.`, configFile));
                     continue;
                 }
-                if (navigation.has(node.file)) {
+                if (versionNavigation.has(node.file)) {
                     issues.push(error('duplicate-navigation', `"${node.file}" appears more than once.`, configFile));
                 }
                 navigation.add(node.file);
+                versionNavigation.add(node.file);
                 if (!pageSet.has(node.file)) {
                     issues.push(error('missing-page', `Navigation references missing page "${node.file}".`, configFile));
                 }
@@ -90,6 +188,11 @@ function validateDoxbrixNavigation(spaces, pageSet, pages, configFile, issues) {
                     continue;
                 }
                 visit(node.items, `group "${node.label}"`);
+                // A group that holds one page is a page with an extra click in front
+                // of it; the planner is told to give every group at least two.
+                if (nodes.filter((sibling) => sibling && typeof sibling === 'object' && sibling.type === 'group').length > 1 && node.items.filter((item) => item && typeof item === 'object' && item.type === 'page').length === 1 && node.items.length === 1) {
+                    issues.push(warning('single-page-group', `Navigation group "${node.label}" holds one page; merge it into a neighbouring group or give it the pages that belong with it.`, configFile));
+                }
             }
             else if (!['label', 'divider', 'link', 'api'].includes(node.type)) {
                 issues.push(error('navigation-node', `${nodeLocation} has unsupported type "${node.type}".`, configFile));
@@ -101,15 +204,47 @@ function validateDoxbrixNavigation(spaces, pageSet, pages, configFile, issues) {
             issues.push(error('navigation-space', `Space ${index + 1} must have a name and nav array.`, configFile));
             continue;
         }
+        const version = space.version ?? '';
+        versionNavigation = versions.get(version) ?? new Set();
+        versions.set(version, versionNavigation);
+        const before = versionNavigation.size;
         visit(space.nav, `space "${space.name}"`);
+        // A top-level space is a destination in the site header. One that holds
+        // a handful of pages splits a reader journey for no gain; the planner is
+        // asked for at least five pages before it promotes a surface to a space.
+        if (spaces.length > 1 && versionNavigation.size - before < 5) {
+            issues.push(warning('thin-space', `Space "${space.name}" holds ${versionNavigation.size - before} page${versionNavigation.size - before === 1 ? '' : 's'}; fold it into another space as a group, or give it the pages that make it a real reader surface.`, configFile));
+        }
+        if (/^(?:documentation|docs|reference)$/i.test(space.name.trim()) && spaces.length > 1) {
+            issues.push(warning('generic-space-name', `Space "${space.name}" is a generic label; name spaces after the product's reader surfaces (for example "Guides", "API", "Self-hosting").`, configFile));
+        }
     }
     for (const id of pages) {
         if (!navigation.has(id)) {
             issues.push(error('unnavigated-page', `Page "${id}" is not in Doxbrix navigation.`));
         }
     }
+    // Doxbrix serves a page at its file name, so "guides/troubleshooting" and
+    // "embed/troubleshooting" share one address and the published site shows
+    // only one of them. Within each version, file names must be unique.
+    for (const ids of versions.values()) {
+        const byName = new Map();
+        for (const id of ids) {
+            // Each edition (editions/<version>/<locale>/…) is its own set of routes.
+            const edition = id.startsWith('editions/') ? id.split('/').slice(0, 3).join('/') : '';
+            const name = `${edition}:${id.split('/').at(-1) === 'index' ? id : id.split('/').at(-1)}`;
+            byName.set(name, [...(byName.get(name) ?? []), id]);
+        }
+        for (const [name, same] of byName) {
+            if (same.length < 2)
+                continue;
+            const fileName = name.slice(name.indexOf(':') + 1);
+            issues.push(error('duplicate-page-name', `Pages ${same.map((id) => `"${id}"`).join(' and ')} share the file name "${fileName}". Doxbrix serves pages by file name, so only one would be published; rename the others (for example "${same[1].replace(/[^/]+$/, `${same[1].split('/').at(-2) ?? 'more'}-${fileName}`)}").`, configFile));
+        }
+    }
 }
-async function validateDoxbrixTheme(value, contentRoot, configFile, issues) {
+/** Theme checks shared by validation and the branding panel's pre-write check. */
+export async function validateDoxbrixTheme(value, contentRoot, configFile, issues) {
     if (value === undefined)
         return;
     if (value === 'light' || value === 'dark' || value === 'system')
@@ -255,7 +390,7 @@ function validateDoxbrixComponents(content, file) {
         issues.push(error('component-tag', `Line ${opening.line}: <${opening.name}> does not have a matching closing tag.`, file));
     }
     if (issues.length === 0) {
-        issues.push(...validateDoxbrixApiEndpoints(masked, file));
+        issues.push(...validateDoxbrixApiEndpoints(masked, file, content));
     }
     return issues;
 }
@@ -384,7 +519,13 @@ function maskDoxbrixCode(content) {
     });
     return masked.join('\n');
 }
-function validateDoxbrixApiEndpoints(content, file) {
+/**
+ * `content` has its code spans and fences masked to spaces (same length, same
+ * offsets) so component tags inside examples are not parsed; `raw` is the
+ * unmasked page, consulted only where the example itself is the payload — a
+ * fenced SVG or RSS body inside <Response> is a body, not an empty one.
+ */
+function validateDoxbrixApiEndpoints(content, file, raw = content) {
     const issues = [];
     for (const [index, match] of [
         ...content.matchAll(/<ApiEndpoint\b([^>]*)>([\s\S]*?)<\/ApiEndpoint>/g),
@@ -392,6 +533,7 @@ function validateDoxbrixApiEndpoints(content, file) {
         const label = `API endpoint ${index + 1}`;
         const attributes = componentAttributes(match[1] ?? '');
         const body = match[2] ?? '';
+        const bodyOffset = (match.index ?? 0) + match[0].length - body.length - '</ApiEndpoint>'.length;
         const method = stringAttribute(attributes.method).toUpperCase();
         const path = stringAttribute(attributes.path);
         const baseUrl = stringAttribute(attributes.baseUrl);
@@ -404,11 +546,17 @@ function validateDoxbrixApiEndpoints(content, file) {
         if (!/^https?:\/\/[^/\s]+/i.test(baseUrl)) {
             issues.push(error('api-endpoint-base-url', `${label} needs an absolute HTTP or HTTPS baseUrl so Doxbrix can generate the request example.`, file));
         }
-        if (stringAttribute(attributes.summary) === '' ||
+        // Doxbrix titles the endpoint card with `summary` and shows `description`
+        // under it only when present (its own OpenAPI importer omits an empty
+        // one), so one of the two is the contract. Demanding both produced 98
+        // warnings on a real run whose endpoints all had a summary and whose
+        // prose already described each operation.
+        if (stringAttribute(attributes.summary) === '' &&
             stringAttribute(attributes.description) === '') {
-            issues.push(warning('api-endpoint-description', `${label} should include both summary and description attributes.`, file));
+            issues.push(warning('api-endpoint-description', `${label} should include a summary attribute.`, file));
         }
         const pathParameters = new Set();
+        const withoutExample = [];
         const paramPattern = /<Param\b([^>]*)>([\s\S]*?)<\/Param>/g;
         for (const [paramIndex, paramMatch] of [
             ...body.matchAll(paramPattern),
@@ -426,12 +574,20 @@ function validateDoxbrixApiEndpoints(content, file) {
                     issues.push(error('api-endpoint-path-param', `${label} path parameter "${name}" must set required.`, file));
                 }
             }
-            if (stringAttribute(param.example) === '') {
-                issues.push(warning('api-endpoint-param-example', `${label} parameter "${name || paramIndex + 1}" should include a verified example for the generated request.`, file));
-            }
+            if (stringAttribute(param.example) === '')
+                withoutExample.push(name || String(paramIndex + 1));
+        }
+        // One suggestion per endpoint, not per parameter, and none when the page
+        // already shows a request for this endpoint in a code sample: a real run
+        // spent two fix sessions on 204 per-parameter warnings for endpoints
+        // whose cURL examples were already complete.
+        if (withoutExample.length > 0 && !hasRequestSample(content, raw, match.index ?? 0, (match.index ?? 0) + match[0].length, path)) {
+            issues.push(warning('api-endpoint-param-example', `${label} parameter${withoutExample.length === 1 ? '' : 's'} ${withoutExample.map((name) => `"${name}"`).join(', ')} should include a verified example for the generated request.`, file));
         }
         for (const placeholder of path.matchAll(/\{([^}]+)}/g)) {
-            const name = placeholder[1] ?? '';
+            // A gRPC-gateway template names its variable before an "=" pattern:
+            // "/api/v1/{name=memos/*}" is the path parameter "name".
+            const name = (placeholder[1] ?? '').split('=')[0].trim();
             if (!pathParameters.has(name)) {
                 issues.push(error('api-endpoint-path-param', `${label} path placeholder "{${name}}" needs a matching required <Param in="path">.`, file));
             }
@@ -450,13 +606,40 @@ function validateDoxbrixApiEndpoints(content, file) {
                 stringAttribute(response.description) === '') {
                 issues.push(warning('api-endpoint-response-metadata', `${label} response ${status || responseIndex + 1} should include contentType and description.`, file));
             }
-            if ((responseMatch[2] ?? '').trim() === '') {
+            const responseBody = responseMatch[2] ?? '';
+            const responseOffset = bodyOffset + (responseMatch.index ?? 0) + responseMatch[0].length - responseBody.length - '</Response>'.length;
+            const rawResponseBody = raw.slice(responseOffset, responseOffset + responseBody.length);
+            if (responseBody.trim() === '' && rawResponseBody.trim() === '') {
                 issues.push(error('api-endpoint-response', `${label} response ${status || responseIndex + 1} needs an example body.`, file));
             }
         }
     }
     return issues;
 }
+/**
+ * Whether the section around an <ApiEndpoint> (from the heading before it to
+ * the next heading or endpoint) carries a fenced request for it: a cURL
+ * command, an HTTPie call, or a raw HTTP request line naming its path.
+ */
+export function hasRequestSample(masked, raw, start, end, path) {
+    // Section boundaries come from the masked page, where a `# comment` inside
+    // a shell fence is blank, not a heading; the fences come from the raw page.
+    const before = masked.slice(0, start);
+    const headings = [...before.matchAll(/^#{1,6}\s/gm)];
+    const sectionStart = headings.at(-1)?.index ?? 0;
+    const after = masked.slice(end);
+    const next = after.search(/^#{1,6}\s|<ApiEndpoint\b/m);
+    const sectionEnd = next === -1 ? raw.length : end + next;
+    const section = `${raw.slice(sectionStart, start)}\n${raw.slice(end, sectionEnd)}`;
+    const staticPath = path.split(/[{:]/)[0].replace(/\/+$/, '');
+    for (const fence of section.matchAll(/^\s*(`{3,}|~{3,})[^\n]*\n([\s\S]*?)^\s*\1\s*$/gm)) {
+        const code = fence[2] ?? '';
+        const request = /\bcurl\b|\bhttp(?:ie)?\s+(?:GET|POST|PUT|PATCH|DELETE)\b|\bfetch\(|^\s*(?:GET|POST|PUT|PATCH|DELETE)\s+\S/im.test(code);
+        if (request && (staticPath === '' || code.includes(staticPath)))
+            return true;
+    }
+    return false;
+}
 function componentAttributes(source) {
     const attributes = {};
     const pattern = /([A-Za-z_][\w-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|\{([^}]*)\}))?/g;
@@ -475,11 +658,116 @@ function stringAttribute(value) {
 function trueAttribute(value) {
     return value === true || value === 'true';
 }
+/**
+ * Page types from the plan staged in the workspace, keyed by extension-less
+ * page path. Direct authoring without a plan infers the type from the page.
+ */
+async function plannedPageTypes(root, project) {
+    const types = new Map();
+    try {
+        const plan = JSON.parse(await readFile(join(root, '.doxloop', 'documentation-plan.json'), 'utf8'));
+        for (const page of plan.pages ?? []) {
+            if (typeof page.path !== 'string' || typeof page.type !== 'string')
+                continue;
+            const key = join(project.contentDir, page.path).replaceAll('\\', '/').replace(/^\.\//, '');
+            types.set(key, { type: page.type, ...(typeof page.diagram === 'string' ? { diagram: page.diagram } : {}) });
+        }
+    }
+    catch {
+        // No staged plan: infer page types from content instead.
+    }
+    return types;
+}
+/** A Mermaid diagram in any of the syntaxes the supported generators render. */
+export function hasDiagram(raw) {
+    return /<Mermaid[\s>]|```mermaid\b|\.\. mermaid::|\{%\s*mermaid|<pre class="mermaid"|\{\{<\s*mermaid/i.test(raw);
+}
+const PROCEDURAL_TYPES = new Set(['how-to', 'tutorial', 'getting-started']);
+/** Minimum prose words before a page reads as a stub rather than documentation. */
+// A five-step UI guide with prerequisites, verification, and troubleshooting
+// runs past 350 words; the earlier 250 let 300-word skeletons through.
+const MINIMUM_WORDS = { reference: 200, concept: 300, procedure: 350, other: 200 };
+const MINIMUM_STEPS = 3;
+/**
+ * Depth gate. A page with a title, a sentence, and one screenshot passes every
+ * structural check yet reads as a placeholder; the agent's own quality pass
+ * cannot notice that from inside the page, so Doxloop measures it. Warnings,
+ * never errors: a genuinely small surface may legitimately produce a short
+ * page, and the authoring contract tells the agent to resolve each one.
+ */
+/**
+ * Shell variables a script cannot assign. A generated quickstart opened with
+ * `UID="$(date +%s)"` to make a unique username; bash stops with "UID:
+ * readonly variable" and zsh tries to change the user ID, so the very first
+ * command a reader copies failed.
+ */
+const READONLY_SHELL_VARIABLES = ['UID', 'EUID', 'PPID', 'GID', 'EGID', 'BASHPID', 'BASH_VERSINFO', 'SHELLOPTS', 'BASHOPTS'];
+const SHELL_FENCE = /^(```|~~~)\s*(?:bash|sh|shell|zsh|console)\b[^\n]*\n([\s\S]*?)^\1\s*$/gm;
+export function validateShellExamples(raw, file) {
+    const issues = [];
+    const assignment = new RegExp(`(?:^|[;&|]\\s*|\\b(?:export|local|declare|readonly)\\s+)(${READONLY_SHELL_VARIABLES.join('|')})=`, 'm');
+    for (const match of raw.matchAll(SHELL_FENCE)) {
+        const fenceLine = raw.slice(0, match.index).split('\n').length;
+        for (const [offset, line] of match[2].split('\n').entries()) {
+            const found = assignment.exec(line.replace(/^\s*\$\s+/, '').trimStart());
+            if (!found)
+                continue;
+            issues.push(error('shell-readonly-variable', `Line ${fenceLine + offset + 1}: the shell example assigns ${found[1]}, a read-only shell variable; the command fails when a reader runs it. Use another name, such as RUN_ID or SUFFIX.`, file));
+            break;
+        }
+    }
+    return issues;
+}
+export function validatePageDepth(body, file, planType) {
+    const issues = [];
+    // A generated glossary is a list of short definitions by design; the
+    // depth gate is for workflow and concept pages, not term lists.
+    if (body.includes('doxloop:glossary'))
+        return issues;
+    const withoutCode = stripCodeFences(body);
+    const prose = withoutCode
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/^\s*\|?\s*-{3,}.*$/gm, ' ');
+    const words = prose.split(/\s+/).filter((token) => /[A-Za-z0-9]/.test(token)).length;
+    const stepCount = (withoutCode.match(/<Step\b/g) ?? []).length;
+    const orderedItems = (withoutCode.match(/^\s*\d+\.\s+\S/gm) ?? []).length;
+    const type = planType ?? inferPageType(file, withoutCode, stepCount, orderedItems);
+    const procedural = PROCEDURAL_TYPES.has(type) || stepCount > 0;
+    const minimum = type === 'reference' ? MINIMUM_WORDS.reference : procedural ? MINIMUM_WORDS.procedure : type === 'concept' ? MINIMUM_WORDS.concept : MINIMUM_WORDS.other;
+    if (words < minimum) {
+        issues.push(warning('thin-page', `The page has about ${words} words of prose; ${procedural ? 'a procedural page' : type === 'other' ? 'a page like this' : `a ${type} page`} normally needs at least ${minimum} to be complete. Add the reader outcome, prerequisites, every step with its observable result, verification, evidence-backed troubleshooting, and a next step — or merge this page into one that can be complete.`, file));
+    }
+    if (procedural && Math.max(stepCount, orderedItems) < MINIMUM_STEPS && words < 600) {
+        issues.push(warning('thin-procedure', `The procedure has ${Math.max(stepCount, orderedItems)} step${Math.max(stepCount, orderedItems) === 1 ? '' : 's'}; a guide normally needs at least ${MINIMUM_STEPS} ordered steps that each name the reader action, the exact control or value, and the visible result. Split combined actions into their own steps and finish the workflow through verification.`, file));
+    }
+    return issues;
+}
+function inferPageType(file, body, stepCount, orderedItems) {
+    const normalized = file.toLowerCase();
+    if (/(^|\/)(?:reference|api|cli|commands?|configuration)(\/|\.)/.test(normalized))
+        return 'reference';
+    if (/(^|\/)(?:concepts?|explanations?|architecture)(\/|\.)/.test(normalized))
+        return 'concept';
+    if (/(^|\/)(?:guides?|how-?to|tutorials?|getting-started|quickstart)(\/|\.)/.test(normalized))
+        return 'how-to';
+    if (stepCount > 0 || orderedItems >= 2)
+        return 'how-to';
+    if (/^index\.[a-z]+$/.test(normalized) || /(^|\/)index\.[a-z]+$/.test(normalized))
+        return 'other';
+    return body.includes('<Steps') ? 'how-to' : 'other';
+}
+/** Generated scaffolding the authoring agent is told to replace: a starter marker or its placeholder language. */
+export function isStarterContent(content) {
+    const prose = stripCodeFences(content);
+    return (/(?:<!--|\{\/\*)\s*doxloop:starter-page\s*(?:-->|\*\/\})/i.test(prose) ||
+        /^\.\.\s+doxloop:starter-page\s*$/im.test(prose) ||
+        /\b(?:replace this starter|the authoring agent will replace this starter)\b/i.test(prose));
+}
 function validateProfessionalContent(body, raw, file) {
     const issues = [];
     const prose = stripCodeFences(body);
-    if (/(?:<!--|\{\/\*)\s*doxloop:starter-page\s*(?:-->|\*\/\})/i.test(prose) ||
-        /\b(?:replace this starter|the authoring agent will replace this starter)\b/i.test(prose)) {
+    if (isStarterContent(prose)) {
         issues.push(error('starter-content', 'Replace generated starter content before validation or publishing.', file));
     }
     if (/^\s*(?:TODO|TBD|FIXME)(?:\s*:|\b)/im.test(prose)) {
@@ -545,17 +833,15 @@ function stripCodeFences(content) {
 }
 async function validateLinks(pagePath, contentRoot, content, projectRoot, adapter) {
     const issues = [];
-    const pattern = /!?\[[^\]]*]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
-    for (const match of content.matchAll(pattern)) {
-        const href = match[1];
+    for (const href of contentLinks(content)) {
         if (href === undefined ||
-            href.startsWith('#') ||
+            href.startsWith('#') || href.startsWith('//') ||
             /^[a-z][a-z0-9+.-]*:/i.test(href)) {
             continue;
         }
         let decoded;
         try {
-            decoded = decodeURIComponent(href.split('#')[0] ?? '');
+            decoded = decodeURIComponent(href.split(/[?#]/)[0] ?? '');
         }
         catch {
             issues.push(error('invalid-link', `Local link is not valid URL syntax: ${href}`, relativePath(projectRoot, pagePath)));
@@ -567,8 +853,8 @@ async function validateLinks(pagePath, contentRoot, content, projectRoot, adapte
             ? resolve(contentRoot, `.${decoded}`)
             : resolve(dirname(pagePath), decoded);
         const candidates = extname(base) === ''
-            ? [base, `${base}.md`, `${base}.mdx`, join(base, 'index.md'), join(base, 'index.mdx')]
-            : [base];
+            ? [base, ...['md', 'mdx', 'rst', 'html', 'htm'].flatMap((extension) => [`${base}.${extension}`, join(base, `index.${extension}`)])]
+            : /\.html?$/.test(base) ? [base, base.replace(/\.html?$/, '.rst'), base.replace(/\.html?$/, '.md'), base.replace(/\.html?$/, '.mdx')] : [base];
         const generatorAsset = adapter?.resolveLocalAsset?.({
             root: projectRoot,
             contentRoot,