@devinnn/docdrift 0.1.4 → 0.1.6

package/dist/src/cli.js

@@ -50,7 +50,14 @@ function getArg(args, flag) {
 async function main() {
     const [, , command, ...args] = process.argv;
     if (!command) {
-        throw new Error("Usage: docdrift <validate|detect|run|status|sla-check|setup|generate-yaml> [options]\n  detect|run: [--base SHA] [--head SHA] (defaults: merge-base with main..HEAD)\n  setup|generate-yaml: [--output path] [--force]");
+        throw new Error("Usage: docdrift <validate|detect|run|status|sla-check|setup|generate-yaml> [options]\n" +
+            "  validate          Validate docdrift.yaml (v2 config)\n" +
+            "  detect            Check for drift [--base SHA] [--head SHA]\n" +
+            "  run               Full run with Devin [--base SHA] [--head SHA]\n" +
+            "  status            Show run status [--since 24h]\n" +
+            "  sla-check         Check SLA for unmerged PRs\n" +
+            "  setup             Interactive setup (generates v2 docdrift.yaml)\n" +
+            "  generate-yaml     Generate config [--output path] [--force]");
     }
     if (command === "setup" || command === "generate-yaml") {
         require("dotenv").config();

package/dist/src/config/normalize.js

@@ -16,8 +16,7 @@ function normalizeConfig(config) {
     let exclude = config.exclude ?? [];
     let requireHumanReview = config.requireHumanReview ?? [];
     let docAreas = config.docAreas ?? [];
-    const allowConceptualOnlyRun = config.allowConceptualOnlyRun ?? false;
-    const inferMode = config.inferMode ?? true;
+    const mode = config.mode ?? "strict";
     if (config.specProviders && config.specProviders.length >= 1) {
         specProviders = config.specProviders;
         const firstOpenApi3 = specProviders.find((p) => p.format === "openapi3");
@@ -149,7 +148,6 @@ function normalizeConfig(config) {
         exclude,
         requireHumanReview,
         docAreas,
-        allowConceptualOnlyRun,
-        inferMode,
+        mode,
     };
 }

package/dist/src/config/schema.js

@@ -98,8 +98,8 @@ exports.docDriftConfigBaseSchema = zod_1.z.object({
     exclude: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
     requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
     pathMappings: zod_1.z.array(exports.pathRuleSchema).optional().default([]),
-    allowConceptualOnlyRun: zod_1.z.boolean().optional().default(false),
-    inferMode: zod_1.z.boolean().optional().default(true),
+    /** strict: only run on spec drift. auto: also run when pathMappings match (no spec drift). */
+    mode: zod_1.z.enum(["strict", "auto"]).optional().default("strict"),
     devin: zod_1.z.object({
         apiVersion: zod_1.z.literal("v1"),
         unlisted: zod_1.z.boolean().default(true),
@@ -119,8 +119,8 @@ const docDriftConfigObjectSchema = zod_1.z.object({
     exclude: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
     requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
     pathMappings: zod_1.z.array(exports.pathRuleSchema).optional().default([]),
-    allowConceptualOnlyRun: zod_1.z.boolean().optional().default(false),
-    inferMode: zod_1.z.boolean().optional().default(true),
+    /** strict: only run on spec drift. auto: also run when pathMappings match (no spec drift). */
+    mode: zod_1.z.enum(["strict", "auto"]).optional().default("strict"),
     devin: zod_1.z.object({
         apiVersion: zod_1.z.literal("v1"),
         unlisted: zod_1.z.boolean().default(true),

package/dist/src/detect/index.js

@@ -7,6 +7,7 @@ exports.buildDriftReport = buildDriftReport;
 const node_path_1 = __importDefault(require("node:path"));
 const fs_1 = require("../utils/fs");
 const git_1 = require("../utils/git");
+const glob_1 = require("../utils/glob");
 const heuristics_1 = require("./heuristics");
 const registry_1 = require("../spec-providers/registry");
 async function buildDriftReport(input) {
@@ -68,15 +69,21 @@ async function buildDriftReport(input) {
         }
     }
     const hasHeuristicMatch = signals.some((s) => s.kind === "heuristic_path_impact");
+    const pathMappings = config.pathMappings ?? [];
+    const hasPathMappingMatch = pathMappings.length > 0 &&
+        changedPaths.some((p) => pathMappings.some((m) => (0, glob_1.matchesGlob)(m.match, p)));
     // 3. Gate logic
+    const isAuto = config.mode === "auto";
     let runGate = "none";
     if (anySpecDrift) {
         runGate = "spec_drift";
     }
-    else if (config.allowConceptualOnlyRun && hasHeuristicMatch) {
+    else if (isAuto && hasHeuristicMatch) {
         runGate = "conceptual_only";
     }
-    else if (config.inferMode && (config.specProviders.length === 0 || allSpecFailedOrNoDrift)) {
+    else if (isAuto &&
+        hasPathMappingMatch &&
+        (config.specProviders.length === 0 || allSpecFailedOrNoDrift)) {
         runGate = "infer";
         if (config.specProviders.length > 0) {
             for (const r of providerResults) {

package/dist/src/devin/prompts.js

@@ -97,15 +97,29 @@ function buildWholeDocsitePrompt(input) {
             "",
         ].join("\n")
         : "";
-    const draftPrBlock = input.trigger === "pull_request" && input.prNumber
-        ? [
+    const draftPrBlock = (() => {
+        if (input.trigger !== "pull_request" || !input.prNumber)
+            return "";
+        if (input.existingDocdriftPr) {
+            return [
+                "",
+                "CRITICAL: An existing doc-drift PR already exists for this API PR.",
+                `You MUST UPDATE that PR — do NOT create a new one.`,
+                `- Existing PR: #${input.existingDocdriftPr.number} (${input.existingDocdriftPr.url})`,
+                `- Branch to update: ${input.existingDocdriftPr.headRef}`,
+                "Checkout that branch, pull latest main, apply your doc changes, push. The existing PR will update.",
+                "Do NOT open a new pull request.",
+                "",
+            ].join("\n");
+        }
+        return [
             "",
             "This run was triggered by an open API PR. Open a **draft** pull request.",
             `In the PR description, link to the API PR (#${input.prNumber}) and state: "Merge the API PR first, then review this doc PR."`,
-            "Use a branch name like docdrift/pr-" + input.prNumber + " or docdrift/preview-<short-sha>.",
+            "Use branch name docdrift/pr-" + input.prNumber + " (required for future runs to update this PR).",
             "",
-        ].join("\n")
-        : "";
+        ].join("\n");
+    })();
     const pathMappings = input.config.pathMappings ?? [];
     const pathMappingsBlock = pathMappings.length > 0
         ? [

package/dist/src/github/client.js

@@ -10,6 +10,7 @@ exports.renderRequireHumanReviewIssueBody = renderRequireHumanReviewIssueBody;
 exports.renderSlaIssueBody = renderSlaIssueBody;
 exports.isPrOpen = isPrOpen;
 exports.listOpenPrsWithLabel = listOpenPrsWithLabel;
+exports.findExistingDocdriftPrForSource = findExistingDocdriftPrForSource;
 const rest_1 = require("@octokit/rest");
 function parseRepo(full) {
     const [owner, repo] = full.split("/");
@@ -172,3 +173,26 @@ async function listOpenPrsWithLabel(token, repository, label) {
         created_at: pr.created_at ?? "",
     }));
 }
+/** Find an existing open docdrift PR for a given source PR number.
+ * Looks for PRs from branch docdrift/pr-{sourcePrNumber} (Devin's convention).
+ * Returns the first match so we can instruct Devin to update it instead of creating a new one.
+ */
+async function findExistingDocdriftPrForSource(token, repository, sourcePrNumber) {
+    const octokit = new rest_1.Octokit({ auth: token });
+    const { owner, repo } = parseRepo(repository);
+    const branchName = `docdrift/pr-${sourcePrNumber}`;
+    const { data } = await octokit.pulls.list({
+        owner,
+        repo,
+        state: "open",
+        head: branchName,
+    });
+    const pr = data[0];
+    if (!pr)
+        return null;
+    return {
+        number: pr.number,
+        url: pr.html_url ?? "",
+        headRef: pr.head?.ref ?? branchName,
+    };
+}

package/dist/src/index.js

@@ -97,6 +97,7 @@ async function executeSessionSingle(input) {
         runGate: input.runGate,
         trigger: input.trigger,
         prNumber: input.prNumber,
+        existingDocdriftPr: input.existingDocdriftPr,
     });
     const session = await (0, v1_1.devinCreateSession)(input.apiKey, {
         prompt,
@@ -256,6 +257,16 @@ async function runDocDrift(options) {
     }
     const bundle = await (0, bundle_1.buildEvidenceBundle)({ runInfo, item, evidenceRoot });
     const attachmentPaths = [...new Set([bundle.archivePath, ...bundle.attachmentPaths])];
+    let existingDocdriftPr;
+    if (githubToken && runInfo.trigger === "pull_request" && runInfo.prNumber) {
+        existingDocdriftPr = (await (0, client_1.findExistingDocdriftPrForSource)(githubToken, repo, runInfo.prNumber)) ?? undefined;
+        if (existingDocdriftPr) {
+            (0, log_1.logInfo)("Found existing docdrift PR for source PR; will instruct Devin to update it", {
+                existingPr: existingDocdriftPr.number,
+                headRef: existingDocdriftPr.headRef,
+            });
+        }
+    }
     let sessionOutcome = {
         outcome: "NO_CHANGE",
         summary: "Skipped Devin session",
@@ -276,6 +287,7 @@ async function runDocDrift(options) {
             runGate,
             trigger: runInfo.trigger,
             prNumber: runInfo.prNumber,
+            existingDocdriftPr,
         });
         metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
     }
@@ -296,7 +308,7 @@ async function runDocDrift(options) {
         metrics.prsOpened += 1;
         state.lastDocDriftPrUrl = sessionOutcome.prUrl;
         state.lastDocDriftPrOpenedAt = new Date().toISOString();
-        if (githubToken && runInfo.trigger === "pull_request" && runInfo.prNumber) {
+        if (githubToken && runInfo.trigger === "pull_request" && runInfo.prNumber && !existingDocdriftPr) {
             await (0, client_1.postPrComment)({
                 token: githubToken,
                 repository: repo,
@@ -322,19 +334,18 @@ async function runDocDrift(options) {
         }
     }
     else if (githubToken &&
-        (decision.action === "OPEN_ISSUE" ||
-            sessionOutcome.outcome === "BLOCKED" ||
-            sessionOutcome.outcome === "NO_CHANGE")) {
+        sessionOutcome.outcome === "BLOCKED" &&
+        sessionOutcome.summary.includes("DEVIN_API_KEY")) {
         issueUrl = await (0, client_1.createIssue)({
             token: githubToken,
             repository: repo,
             issue: {
-                title: "[docdrift] docsite: docs drift requires input",
+                title: "[docdrift] Configuration required — set DEVIN_API_KEY",
                 body: (0, client_1.renderBlockedIssueBody)({
                     docArea: item.docArea,
-                    evidenceSummary: item.summary,
+                    evidenceSummary: sessionOutcome.summary,
                     questions: sessionOutcome.questions ?? [
-                        "Please confirm intended behavior and doc wording.",
+                        "Set DEVIN_API_KEY in GitHub Actions secrets or environment.",
                     ],
                     sessionUrl: sessionOutcome.sessionUrl,
                 }),
@@ -342,10 +353,11 @@ async function runDocDrift(options) {
             },
         });
         metrics.issuesOpened += 1;
-        if (sessionOutcome.outcome !== "PR_OPENED") {
-            sessionOutcome.outcome = "ISSUE_OPENED";
-        }
     }
+    // Note: We do NOT create "docs drift requires input" issues for Devin-reported BLOCKED
+    // (evidence questions) or for OPEN_ISSUE/NO_CHANGE. Issues are only created for:
+    // (1) requireHumanReview when a PR touches those paths, (2) 7-day SLA reminders,
+    // and (3) DEVIN_API_KEY missing. See docdrift-yml.md.
     if (sessionOutcome.outcome === "BLOCKED") {
         metrics.blockedCount += 1;
     }

package/dist/src/setup/ai-infer.js

@@ -15,20 +15,24 @@ const pathRuleSchema = zod_1.z.object({
     match: zod_1.z.string().min(1),
     impacts: zod_1.z.array(zod_1.z.string().min(1)).min(1),
 });
+const specProviderSchema = zod_1.z.object({
+    format: zod_1.z.enum(["openapi3", "swagger2", "graphql", "fern", "postman"]),
+    current: zod_1.z.object({
+        type: zod_1.z.literal("export"),
+        command: zod_1.z.string().min(1),
+        outputPath: zod_1.z.string().min(1),
+    }),
+    published: zod_1.z.string().min(1),
+});
 const InferenceSchema = zod_1.z.object({
     suggestedConfig: zod_1.z.object({
-        version: zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]).optional(),
-        openapi: zod_1.z
-            .object({
-            export: zod_1.z.string().min(1),
-            generated: zod_1.z.string().min(1),
-            published: zod_1.z.string().min(1),
-        })
-            .optional(),
+        version: zod_1.z.literal(2).optional(),
+        specProviders: zod_1.z.array(specProviderSchema).optional(),
         docsite: zod_1.z.union([zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1))]).optional(),
         exclude: zod_1.z.array(zod_1.z.string().min(1)).optional(),
         requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional(),
         pathMappings: zod_1.z.array(pathRuleSchema).optional(),
+        mode: zod_1.z.enum(["strict", "auto"]).optional(),
         devin: zod_1.z
             .object({
             apiVersion: zod_1.z.literal("v1"),
@@ -96,15 +100,21 @@ function writeCache(cwd, fingerprintHash, inference) {
 }
 function heuristicInference(fingerprint) {
     const scripts = fingerprint.rootPackage.scripts || {};
-    const openapiExport = scripts["openapi:export"] ?? scripts["openapi:generate"] ?? "npm run openapi:export";
+    const scriptNames = Object.keys(scripts);
+    const openapiScriptName = scriptNames.find((s) => s === "openapi:export" || s === "openapi:generate");
+    const openapiExport = openapiScriptName ? `npm run ${openapiScriptName}` : "npm run openapi:export";
     const firstOpenapi = fingerprint.foundPaths.openapi[0];
     const firstDocsite = fingerprint.foundPaths.docusaurusConfig[0]
         ? node_path_1.default.dirname(fingerprint.foundPaths.docusaurusConfig[0]).replace(/\\/g, "/")
         : fingerprint.foundPaths.docsDirs[0]
             ? node_path_1.default.dirname(fingerprint.foundPaths.docsDirs[0]).replace(/\\/g, "/")
             : "apps/docs-site";
-    const published = firstOpenapi ?? `${firstDocsite}/openapi/openapi.json`;
-    const generated = firstOpenapi ?? "openapi/generated.json";
+    const published = firstOpenapi && firstOpenapi.includes(firstDocsite)
+        ? firstOpenapi
+        : `${firstDocsite}/openapi/openapi.json`;
+    const generated = firstOpenapi && !firstOpenapi.includes(firstDocsite)
+        ? firstOpenapi
+        : "openapi/generated.json";
     const verificationCommands = [];
     if (scripts["docs:gen"])
         verificationCommands.push("npm run docs:gen");
@@ -112,19 +122,35 @@ function heuristicInference(fingerprint) {
         verificationCommands.push("npm run docs:build");
     if (verificationCommands.length === 0)
         verificationCommands.push("npm run build");
+    const treeKeys = Object.keys(fingerprint.fileTree);
+    const hasAppsApi = treeKeys.some((k) => k === "apps/api" || k.startsWith("apps/api/"));
+    const matchGlob = hasAppsApi ? "apps/api/**" : "**/api/**";
+    const allowlist = treeKeys.some((k) => k === "apps" || k.startsWith("apps/"))
+        ? ["openapi/**", "apps/**"]
+        : ["openapi/**", `${firstDocsite}/**`];
+    const requireHumanReview = fingerprint.foundPaths.docsDirs.length > 0
+        ? [`${firstDocsite}/docs/guides/**`]
+        : [];
     return {
         suggestedConfig: {
-            version: 1,
-            openapi: { export: openapiExport, generated, published },
+            version: 2,
+            specProviders: [
+                {
+                    format: "openapi3",
+                    current: { type: "export", command: openapiExport, outputPath: generated },
+                    published,
+                },
+            ],
             docsite: firstDocsite,
             exclude: ["**/CHANGELOG*", "**/blog/**"],
-            requireHumanReview: [],
-            pathMappings: [{ match: "**/api/**", impacts: [`${firstDocsite}/docs/**`, `${firstDocsite}/openapi/**`] }],
+            requireHumanReview,
+            pathMappings: [{ match: matchGlob, impacts: [`${firstDocsite}/docs/**`, `${firstDocsite}/openapi/**`] }],
+            mode: "strict",
             devin: { apiVersion: "v1", unlisted: true, maxAcuLimit: 2, tags: ["docdrift"] },
             policy: {
                 prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 },
                 confidence: { autopatchThreshold: 0.8 },
-                allowlist: ["openapi/**", firstDocsite + "/**"],
+                allowlist,
                 verification: { commands: verificationCommands },
                 slaDays: 7,
                 slaLabel: "docdrift",
@@ -133,11 +159,11 @@ function heuristicInference(fingerprint) {
         },
         choices: [
             {
-                key: "openapi.export",
+                key: "specProviders.0.current.command",
                 question: "OpenAPI export command",
                 options: [{ value: openapiExport, label: openapiExport, recommended: true }],
                 defaultIndex: 0,
-                help: "Command that generates the OpenAPI spec.",
+                help: "Use the npm script that generates the spec (e.g. npm run openapi:export).",
                 confidence: "medium",
             },
             {

package/dist/src/setup/generate-yaml.js

@@ -32,22 +32,59 @@ function applyOverrides(base, overrides) {
 function setByKey(obj, key, value) {
     const parts = key.split(".");
     let cur = obj;
-    for (let i = 0; i < parts.length - 1; i++) {
+    let i = 0;
+    while (i < parts.length - 1) {
         const p = parts[i];
-        if (!(p in cur) || typeof cur[p] !== "object" || cur[p] === null || Array.isArray(cur[p])) {
-            cur[p] = {};
+        const nextPart = parts[i + 1];
+        const isArrayIndex = nextPart !== undefined && /^\d+$/.test(nextPart);
+        const existing = cur[p];
+        if (existing != null && typeof existing === "object") {
+            if (Array.isArray(existing) && isArrayIndex) {
+                const idx = parseInt(nextPart, 10);
+                let el = existing[idx];
+                if (el == null || typeof el !== "object") {
+                    el = {};
+                    existing[idx] = el;
+                }
+                cur = el;
+                i += 2;
+                continue;
+            }
+            if (!Array.isArray(existing)) {
+                cur = existing;
+            }
+            else {
+                cur[p] = isArrayIndex ? [] : {};
+                cur = cur[p];
+            }
         }
-        cur = cur[p];
+        else {
+            const next = isArrayIndex ? [] : {};
+            cur[p] = next;
+            cur = next;
+        }
+        i++;
     }
     cur[parts[parts.length - 1]] = value;
 }
 const DEFAULT_CONFIG = {
-    version: 1,
-    openapi: { export: "npm run openapi:export", generated: "openapi/generated.json", published: "apps/docs-site/openapi/openapi.json" },
+    version: 2,
+    specProviders: [
+        {
+            format: "openapi3",
+            current: {
+                type: "export",
+                command: "npm run openapi:export",
+                outputPath: "openapi/generated.json",
+            },
+            published: "apps/docs-site/openapi/openapi.json",
+        },
+    ],
     docsite: "apps/docs-site",
     exclude: [],
     requireHumanReview: [],
     pathMappings: [],
+    mode: "strict",
     devin: {
         apiVersion: "v1",
         unlisted: true,

package/dist/src/setup/prompts.js

@@ -3,23 +3,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SYSTEM_PROMPT = void 0;
 exports.SYSTEM_PROMPT = `You are a docdrift config expert. Given a repo fingerprint (file tree, package.json scripts, and detected paths), infer a partial docdrift.yaml configuration and a list of interactive choices for the user.
 
-## Docdrift config (simple mode)
+## Docdrift config (v2)
 
-Minimal valid config uses: version, openapi, docsite, pathMappings, devin, policy.
+Minimal valid config uses: version: 2, specProviders (or pathMappings only for path-only setups), docsite, devin, policy.
 
 Example:
 \`\`\`yaml
-version: 1
-openapi:
-  export: "npm run openapi:export"
-  generated: "openapi/generated.json"
-  published: "apps/docs-site/openapi/openapi.json"
+version: 2
+specProviders:
+  - format: openapi3
+    current:
+      type: export
+      command: "npm run openapi:export"
+      outputPath: "openapi/generated.json"
+    published: "apps/docs-site/openapi/openapi.json"
 docsite: "apps/docs-site"
 pathMappings:
   - match: "apps/api/**"
     impacts: ["apps/docs-site/docs/**", "apps/docs-site/openapi/**"]
 exclude: ["**/CHANGELOG*", "apps/docs-site/blog/**"]
 requireHumanReview: []
+mode: strict
 devin:
   apiVersion: v1
   unlisted: true
@@ -38,25 +42,88 @@ policy:
 
 ## Field rules
 
-- openapi.export: Command to generate OpenAPI spec (e.g. "npm run openapi:export"). Prefer an existing script from root or workspace package.json.
-- openapi.generated: Path where the export writes the spec (e.g. "openapi/generated.json").
-- openapi.published: Path where the docsite consumes the spec (often under docsite, e.g. "apps/docs-site/openapi/openapi.json").
+- version: Always use 2.
+- specProviders: Array of spec sources. For OpenAPI: format "openapi3", current.type "export", current.command = npm script (e.g. "npm run openapi:export"), current.outputPath = where export writes (e.g. "openapi/generated.json"), published = docsite path (e.g. "apps/docs-site/openapi/openapi.json"). Never use raw script body; use "npm run <scriptName>".
 - docsite: Path to the docs site root (Docusaurus, Next.js docs, VitePress, MkDocs). Single string or array of strings.
 - pathMappings: Array of { match, impacts }. match = glob for source/API code; impacts = globs for doc files that may need updates when match changes.
+- mode: "strict" (only run on spec drift) or "auto" (also run when pathMappings match without spec drift). Default: strict.
 - policy.verification.commands: Commands to run after patching (e.g. "npm run docs:gen", "npm run docs:build"). Must exist in repo.
 - exclude: Globs to never touch (e.g. blog, CHANGELOG).
 - requireHumanReview: Globs that require human review when touched (e.g. guides).
 
+## Path-only config (no OpenAPI)
+
+If no OpenAPI/spec found, use version: 2 with pathMappings only (no specProviders):
+\`\`\`yaml
+version: 2
+docsite: "apps/docs-site"
+pathMappings: [...]
+mode: auto
+\`\`\`
+
 ## Common patterns
 
-- Docusaurus: docsite often has docusaurus.config.*; docs:gen may be "docusaurus -- gen-api-docs api"; openapi published path often under docsite/openapi/.
+- Docusaurus: docsite often has docusaurus.config.*; docs:gen may be "docusaurus -- gen-api-docs api"; published path often under docsite/openapi/.
 - Next/VitePress/MkDocs: docsite is the app root; look for docs/ or similar.
 
 ## Output rules
 
-1. Infer suggestedConfig from the fingerprint. Only include fields you can confidently infer. Use existing paths and scripts from the fingerprint; do not invent paths that are not present.
-2. For each field where confidence is medium or low, OR where multiple valid options exist, add an entry to choices with: key (e.g. "openapi.export"), question, options (array of { value, label, recommended? }), defaultIndex, help?, warning?, confidence ("high"|"medium"|"low").
+1. Infer suggestedConfig from the fingerprint. Use version: 2. Only include fields you can confidently infer. Use existing paths and scripts from the fingerprint; do not invent paths that are not present.
+2. For each field where confidence is medium or low, OR where multiple valid options exist, add an entry to choices with: key (e.g. "specProviders.0.current.command"), question, options (array of { value, label, recommended? }), defaultIndex, help?, warning?, confidence ("high"|"medium"|"low").
 3. Add to skipQuestions the keys for which you are highly confident so the CLI will not ask the user.
 4. Prefer fewer, high-quality choices. If truly uncertain, set confidence to "low" and provide 2–3 options.
 5. Do not suggest paths that do not exist in the fingerprint. Prefer existing package.json scripts for export and verification commands.
-6. suggestedConfig must be a valid partial docdrift config; policy.allowlist and policy.verification.commands are required if you include policy. devin.apiVersion must be "v1" if you include devin.`;
+6. suggestedConfig must be a valid partial docdrift config; policy.allowlist and policy.verification.commands are required if you include policy. devin.apiVersion must be "v1" if you include devin.
+
+## Example docdrift.yaml
+# yaml-language-server: $schema=./docdrift.schema.json
+version: 2
+
+specProviders:
+  - format: openapi3
+    current:
+      type: export
+      command: "npm run openapi:export"
+      outputPath: "openapi/generated.json"
+    published: "apps/docs-site/openapi/openapi.json"
+
+docsite: "apps/docs-site"
+mode: strict
+
+pathMappings:
+  - match: "apps/api/**"
+    impacts: ["apps/docs-site/docs/**", "apps/docs-site/openapi/**"]
+
+exclude:
+  - "apps/docs-site/blog/**"
+  - "**/CHANGELOG*"
+
+requireHumanReview:
+  - "apps/docs-site/docs/guides/**"
+
+devin:
+  apiVersion: v1
+  unlisted: true
+  maxAcuLimit: 2
+  tags:
+    - docdrift
+  customInstructions:
+    - "DocDrift.md"
+
+policy:
+  prCaps:
+    maxPrsPerDay: 5
+    maxFilesTouched: 30
+  confidence:
+    autopatchThreshold: 0.8
+  allowlist:
+    - "openapi/**"
+    - "apps/**"
+  verification:
+    commands:
+      - "npm run docs:gen"
+      - "npm run docs:build"
+  slaDays: 7
+  slaLabel: docdrift
+  allowNewFiles: false
+`;

package/docdrift.schema.json

@@ -183,13 +183,13 @@
       },
       "default": []
     },
-    "allowConceptualOnlyRun": {
-      "type": "boolean",
-      "default": false
-    },
-    "inferMode": {
-      "type": "boolean",
-      "default": true
+    "mode": {
+      "type": "string",
+      "enum": [
+        "strict",
+        "auto"
+      ],
+      "default": "strict"
     },
     "devin": {
       "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinnn/docdrift",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "description": "Detect and remediate documentation drift with Devin sessions",
   "main": "dist/src/index.js",