@devinnn/docdrift 0.1.4 → 0.1.7

package/README.md

@@ -163,7 +163,7 @@ This repo has **intentional drift**: the API has been expanded (new fields `full
 
 Once published to npm, any repo can use the CLI locally or in GitHub Actions.
 
-1. **In the consuming repo** add a `docdrift.yaml` at the root (see this repo’s `docdrift.yaml` and `docdrift-yml.md`).
+1. **Setup** — `npx @devinnn/docdrift setup` (requires `DEVIN_API_KEY`). Devin generates `docdrift.yaml`, `.docdrift/DocDrift.md`, and `.github/workflows/docdrift.yml`. Prerequisite: add your repo in Devin's Machine first. Or add `docdrift.yaml` manually (see `docdrift-yml.md`).
 2. **CLI**
    ```bash
    npx @devinnn/docdrift validate

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/devin/schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PatchResultSchema = exports.PatchPlanSchema = void 0;
+exports.PatchResultSchema = exports.SetupOutputSchema = exports.PatchPlanSchema = void 0;
 exports.PatchPlanSchema = {
     type: "object",
     additionalProperties: false,
@@ -59,6 +59,27 @@ exports.PatchPlanSchema = {
         },
     },
 };
+/** Structured output for docdrift setup (Devin generates config files) */
+exports.SetupOutputSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["docdriftYaml", "summary"],
+    properties: {
+        docdriftYaml: { type: "string", description: "Full docdrift.yaml content, valid per schema" },
+        docDriftMd: {
+            type: "string",
+            description: "Content for .docdrift/DocDrift.md custom instructions (project-specific guidance for Devin)",
+        },
+        workflowYml: {
+            type: "string",
+            description: "Content for .github/workflows/docdrift.yml — must use npx @devinnn/docdrift for validate and run",
+        },
+        summary: {
+            type: "string",
+            description: "Brief summary of what you inferred (openapi paths, docsite, verification commands)",
+        },
+    },
+};
 exports.PatchResultSchema = {
     type: "object",
     additionalProperties: false,

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/devin-setup.js

@@ -0,0 +1,157 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSetupDevin = runSetupDevin;
+exports.runSetupDevinAndValidate = runSetupDevinAndValidate;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+require("dotenv/config");
+const v1_1 = require("../devin/v1");
+const schemas_1 = require("../devin/schemas");
+const setup_prompt_1 = require("./setup-prompt");
+const generate_yaml_1 = require("./generate-yaml");
+const index_1 = require("../index");
+const onboard_1 = require("./onboard");
+/** Resolve path to docdrift.schema.json in the package */
+function getSchemaPath() {
+    // dist/src/setup -> ../../../ ; src/setup (tsx) -> ../..
+    const candidates = [
+        node_path_1.default.join(__dirname, "../../../docdrift.schema.json"),
+        node_path_1.default.join(__dirname, "../../docdrift.schema.json"),
+    ];
+    const schemaPath = candidates.find((p) => node_fs_1.default.existsSync(p));
+    if (!schemaPath) {
+        throw new Error(`docdrift.schema.json not found. Tried: ${candidates.join(", ")}`);
+    }
+    return schemaPath;
+}
+function parseSetupOutput(session) {
+    const raw = session?.structured_output ?? session?.data?.structured_output;
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    const yaml = o.docdriftYaml;
+    const summary = o.summary;
+    if (typeof yaml !== "string" || typeof summary !== "string")
+        return null;
+    return {
+        docdriftYaml: yaml,
+        docDriftMd: typeof o.docDriftMd === "string" && o.docDriftMd ? o.docDriftMd : undefined,
+        workflowYml: typeof o.workflowYml === "string" && o.workflowYml ? o.workflowYml : undefined,
+        summary,
+        sessionUrl: "",
+    };
+}
+async function runSetupDevin(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
+    const apiKey = process.env.DEVIN_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error("DEVIN_API_KEY is required for setup. Set it in .env or export.");
+    }
+    const configExists = node_fs_1.default.existsSync(outputPath);
+    if (configExists && !options.force) {
+        const { confirm } = await Promise.resolve().then(() => __importStar(require("@inquirer/prompts")));
+        const overwrite = await confirm({
+            message: "docdrift.yaml already exists. Overwrite?",
+            default: false,
+        });
+        if (!overwrite) {
+            throw new Error("Setup cancelled.");
+        }
+    }
+    process.stdout.write("Uploading schema…\n");
+    const schemaPath = getSchemaPath();
+    const attachmentUrl = await (0, v1_1.devinUploadAttachment)(apiKey, schemaPath);
+    const prompt = (0, setup_prompt_1.buildSetupPrompt)([attachmentUrl]);
+    process.stdout.write("Creating Devin session…\n");
+    const session = await (0, v1_1.devinCreateSession)(apiKey, {
+        prompt,
+        unlisted: true,
+        max_acu_limit: 2,
+        tags: ["docdrift", "setup"],
+        attachments: [attachmentUrl],
+        structured_output: {
+            schema: schemas_1.SetupOutputSchema,
+        },
+        metadata: { purpose: "docdrift-setup" },
+    });
+    process.stdout.write("Devin is analyzing the repo and generating config…\n");
+    process.stdout.write(`Session: ${session.url}\n`);
+    const finalSession = await (0, v1_1.pollUntilTerminal)(apiKey, session.session_id, 15 * 60_000);
+    const result = parseSetupOutput(finalSession);
+    if (!result) {
+        throw new Error("Devin session did not return valid setup output. Check the session for details: " + session.url);
+    }
+    result.sessionUrl = session.url;
+    // Write files
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(outputPath), { recursive: true });
+    node_fs_1.default.writeFileSync(outputPath, result.docdriftYaml, "utf8");
+    if (result.docDriftMd) {
+        (0, onboard_1.ensureDocdriftDir)(cwd);
+        const docDriftPath = node_path_1.default.resolve(cwd, ".docdrift", "DocDrift.md");
+        node_fs_1.default.writeFileSync(docDriftPath, result.docDriftMd, "utf8");
+    }
+    if (result.workflowYml) {
+        const workflowsDir = node_path_1.default.resolve(cwd, ".github", "workflows");
+        node_fs_1.default.mkdirSync(workflowsDir, { recursive: true });
+        node_fs_1.default.writeFileSync(node_path_1.default.join(workflowsDir, "docdrift.yml"), result.workflowYml, "utf8");
+        (0, onboard_1.addSlaCheckWorkflow)(cwd);
+    }
+    (0, onboard_1.ensureGitignore)(cwd);
+    const validation = (0, generate_yaml_1.validateGeneratedConfig)(outputPath);
+    if (!validation.ok) {
+        throw new Error("Generated config failed validation:\n" + validation.errors.join("\n"));
+    }
+    return result;
+}
+async function runSetupDevinAndValidate(options) {
+    const result = await runSetupDevin(options);
+    const cwd = options.cwd ?? process.cwd();
+    const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
+    if (outputPath === node_path_1.default.resolve(cwd, "docdrift.yaml")) {
+        try {
+            await (0, index_1.runValidate)();
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }
+    return result;
+}

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/index.js

@@ -1,109 +1,35 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSetup = runSetup;
 const node_path_1 = __importDefault(require("node:path"));
-const repo_fingerprint_1 = require("./repo-fingerprint");
-const ai_infer_1 = require("./ai-infer");
-const interactive_form_1 = require("./interactive-form");
-const generate_yaml_1 = require("./generate-yaml");
-const onboard_1 = require("./onboard");
-const index_1 = require("../index");
+const devin_setup_1 = require("./devin-setup");
 async function runSetup(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
-    const configExists = await Promise.resolve().then(() => __importStar(require("node:fs"))).then((fs) => fs.existsSync(outputPath));
-    if (configExists && !options.force) {
-        const { confirm } = await Promise.resolve().then(() => __importStar(require("@inquirer/prompts")));
-        const overwrite = await confirm({
-            message: "Config already exists. Overwrite?",
-            default: false,
-        });
-        if (!overwrite) {
-            console.log("Setup cancelled.");
-            return;
-        }
-    }
-    process.stdout.write("Analyzing your repo…\n");
-    const fingerprint = (0, repo_fingerprint_1.buildRepoFingerprint)(cwd);
-    process.stdout.write("Generating suggestions…\n");
-    const inference = await (0, ai_infer_1.inferConfigFromFingerprint)(fingerprint, cwd);
-    const formResult = await (0, interactive_form_1.runInteractiveForm)(inference, cwd);
-    let config = (0, generate_yaml_1.buildConfigFromInference)(inference, formResult);
-    if (formResult.onboarding.addCustomInstructions) {
-        const devin = config.devin ?? {};
-        config.devin = {
-            ...devin,
-            customInstructions: [".docdrift/DocDrift.md"],
-        };
-    }
-    (0, generate_yaml_1.writeConfig)(config, outputPath);
-    const { created } = (0, onboard_1.runOnboarding)(cwd, formResult.onboarding);
-    const validation = (0, generate_yaml_1.validateGeneratedConfig)(outputPath);
-    if (!validation.ok) {
-        console.error("Config validation failed:\n" + validation.errors.join("\n"));
-        throw new Error("Generated config is invalid. Fix the errors above or edit docdrift.yaml manually.");
-    }
-    if (outputPath === node_path_1.default.resolve(cwd, "docdrift.yaml")) {
-        try {
-            await (0, index_1.runValidate)();
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            throw err;
-        }
-    }
+    const result = await (0, devin_setup_1.runSetupDevinAndValidate)({
+        cwd,
+        outputPath: options.outputPath ?? "docdrift.yaml",
+        force: options.force,
+        openPr: options.openPr,
+    });
     console.log("\ndocdrift setup complete\n");
     console.log("  docdrift.yaml     written and validated");
-    for (const item of created) {
-        if (item === ".docdrift/")
-            console.log("  .docdrift/        created");
-        else if (item === "DocDrift.md")
-            console.log("  DocDrift.md       created (edit for custom instructions)");
-        else if (item === ".gitignore")
-            console.log("  .gitignore        updated");
-        else if (item.endsWith("docdrift.yml"))
-            console.log("  " + item + "  added");
+    if (result.docDriftMd)
+        console.log("  .docdrift/DocDrift.md   created (edit for custom instructions)");
+    if (result.workflowYml) {
+        console.log("  .github/workflows/docdrift.yml         added");
+        console.log("  .github/workflows/docdrift-sla-check.yml  added");
     }
+    console.log("  .gitignore        updated");
+    console.log("\nSummary: " + result.summary);
+    console.log("\nSession: " + result.sessionUrl);
     console.log("\nNext steps:");
-    console.log("  1. Set DEVIN_API_KEY (local: .env or export; CI: repo secrets)");
-    console.log("  2. Set GITHUB_TOKEN in repo secrets for PR comments and issues");
-    console.log("  3. Run: docdrift validate   — verify config");
-    console.log("  4. Run: docdrift detect     — check for drift");
-    console.log("  5. Run: docdrift run        — create Devin session (requires DEVIN_API_KEY)");
+    console.log("  1. Add DEVIN_API_KEY to repo secrets (Settings > Secrets > Actions)");
+    console.log("  2. Ensure your repo is set up in Devin (Devin's Machine > Add repository)");
+    console.log("  3. Run: npx @devinnn/docdrift validate   — verify config");
+    console.log("  4. Run: npx @devinnn/docdrift detect     — check for drift");
+    console.log("  5. Run: npx @devinnn/docdrift run        — create Devin session (requires DEVIN_API_KEY)");
 }

package/dist/src/setup/onboard.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureDocdriftDir = ensureDocdriftDir;
 exports.createCustomInstructionsFile = createCustomInstructionsFile;
 exports.ensureGitignore = ensureGitignore;
+exports.addSlaCheckWorkflow = addSlaCheckWorkflow;
 exports.addGitHubWorkflow = addGitHubWorkflow;
 exports.runOnboarding = runOnboarding;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -19,7 +20,129 @@ const GITIGNORE_BLOCK = `
 .docdrift/state.json
 .docdrift/run-output.json
 `;
-const WORKFLOW_CONTENT = "name: docdrift\n\non:\n  push:\n    branches: [\"main\"]\n  pull_request:\n    branches: [\"main\"]\n  workflow_dispatch:\n\njobs:\n  docdrift:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n\n      - run: npm install\n\n      - name: Determine SHAs\n        id: shas\n        run: |\n          if [ \"${{ github.event_name }}\" = \"pull_request\" ]; then\n            HEAD_SHA=\"${{ github.event.pull_request.head.sha }}\"\n            BASE_SHA=\"${{ github.event.pull_request.base.sha }}\"\n          else\n            HEAD_SHA=\"${{ github.sha }}\"\n            BASE_SHA=\"${{ github.event.before }}\"\n            if [ -z \"$BASE_SHA\" ] || [ \"$BASE_SHA\" = \"0000000000000000000000000000000000000000\" ]; then\n              BASE_SHA=\"$(git rev-parse HEAD^)\"\n            fi\n          fi\n          echo \"head=${HEAD_SHA}\" >> $GITHUB_OUTPUT\n          echo \"base=${BASE_SHA}\" >> $GITHUB_OUTPUT\n          echo \"pr_number=${{ github.event.pull_request.number || '' }}\" >> $GITHUB_OUTPUT\n\n      - name: Validate config\n        run: npx docdrift validate\n\n      - name: Run Doc Drift\n        env:\n          DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          GITHUB_REPOSITORY: ${{ github.repository }}\n          GITHUB_SHA: ${{ github.sha }}\n          GITHUB_EVENT_NAME: ${{ github.event_name }}\n          GITHUB_PR_NUMBER: ${{ steps.shas.outputs.pr_number }}\n        run: |\n          PR_ARGS=\"\"\n          if [ -n \"$GITHUB_PR_NUMBER\" ]; then\n            PR_ARGS=\"--trigger pull_request --pr-number $GITHUB_PR_NUMBER\"\n          fi\n          npx docdrift run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }} $PR_ARGS\n\n      - name: Upload artifacts\n        if: always()\n        uses: actions/upload-artifact@v4\n        with:\n          name: docdrift-artifacts\n          path: |\n            .docdrift/drift_report.json\n            .docdrift/metrics.json\n            .docdrift/run-output.json\n            .docdrift/evidence/**\n            .docdrift/state.json\n";
+const WORKFLOW_CONTENT = `name: docdrift
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  docdrift:
+    if: github.event_name != 'pull_request' || !startsWith(github.event.pull_request.head.ref, 'docdrift/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm install
+
+      - name: Determine SHAs
+        id: shas
+        run: |
+          if [ "\$\{\{ github.event_name \}\}" = "pull_request" ]; then
+            HEAD_SHA="\$\{\{ github.event.pull_request.head.sha \}\}"
+            BASE_SHA="\$\{\{ github.event.pull_request.base.sha \}\}"
+          else
+            HEAD_SHA="\$\{\{ github.sha \}\}"
+            BASE_SHA="\$\{\{ github.event.before \}\}"
+            if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+              BASE_SHA="$(git rev-parse HEAD^)"
+            fi
+          fi
+          echo "head=\${HEAD_SHA}" >> $GITHUB_OUTPUT
+          echo "base=\${BASE_SHA}" >> $GITHUB_OUTPUT
+          echo "pr_number=\$\{\{ github.event.pull_request.number || '' \}\}" >> $GITHUB_OUTPUT
+
+      - name: Restore docdrift state
+        uses: actions/cache/restore@v4
+        id: docdrift-cache
+        with:
+          path: .docdrift
+          key: docdrift-state-\$\{\{ github.event_name \}\}-\$\{\{ github.event.pull_request.number || 'main' \}\}-\$\{\{ github.run_id \}\}
+          restore-keys: |
+            docdrift-state-\$\{\{ github.event_name \}\}-\$\{\{ github.event.pull_request.number || 'main' \}\}-
+
+      - name: Validate config
+        run: npx @devinnn/docdrift validate
+
+      - name: Run Doc Drift
+        env:
+          DEVIN_API_KEY: \$\{\{ secrets.DEVIN_API_KEY \}\}
+          GITHUB_TOKEN: \$\{\{ secrets.GITHUB_TOKEN \}\}
+          GITHUB_REPOSITORY: \$\{\{ github.repository \}\}
+          GITHUB_SHA: \$\{\{ github.sha \}\}
+          GITHUB_EVENT_NAME: \$\{\{ github.event_name \}\}
+          GITHUB_PR_NUMBER: \$\{\{ steps.shas.outputs.pr_number \}\}
+        run: |
+          PR_ARGS=""
+          if [ -n "$GITHUB_PR_NUMBER" ]; then
+            PR_ARGS="--trigger pull_request --pr-number $GITHUB_PR_NUMBER"
+          fi
+          npx @devinnn/docdrift run --base \$\{\{ steps.shas.outputs.base \}\} --head \$\{\{ steps.shas.outputs.head \}\} $PR_ARGS
+
+      - name: Save docdrift state
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: .docdrift
+          key: docdrift-state-\$\{\{ github.event_name \}\}-\$\{\{ github.event.pull_request.number || 'main' \}\}-\$\{\{ github.run_id \}\}
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docdrift-artifacts
+          path: |
+            .docdrift/drift_report.json
+            .docdrift/metrics.json
+            .docdrift/run-output.json
+            .docdrift/evidence/**
+            .docdrift/state.json
+`;
+const SLA_CHECK_WORKFLOW_CONTENT = `name: docdrift-sla-check
+
+on:
+  schedule:
+    # Run daily at 09:00 UTC (checks for doc-drift PRs open 7+ days)
+    - cron: "0 9 * * *"
+  workflow_dispatch:
+
+jobs:
+  sla-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm install
+
+      - name: Validate config
+        run: npx @devinnn/docdrift validate
+
+      - name: Run SLA check
+        env:
+          GITHUB_TOKEN: \$\{\{ secrets.GITHUB_TOKEN \}\}
+          GITHUB_REPOSITORY: \$\{\{ github.repository \}\}
+        run: npx @devinnn/docdrift sla-check
+`;
 function ensureDocdriftDir(cwd) {
     const dir = node_path_1.default.resolve(cwd, DOCDRIFT_DIR);
     node_fs_1.default.mkdirSync(dir, { recursive: true });
@@ -54,11 +177,16 @@ function ensureGitignore(cwd) {
     const toAppend = content.endsWith("\n") ? GITIGNORE_BLOCK.trimStart() : GITIGNORE_BLOCK;
     node_fs_1.default.writeFileSync(gitignorePath, content + toAppend, "utf8");
 }
+function addSlaCheckWorkflow(cwd) {
+    const workflowsDir = node_path_1.default.resolve(cwd, ".github", "workflows");
+    node_fs_1.default.mkdirSync(workflowsDir, { recursive: true });
+    node_fs_1.default.writeFileSync(node_path_1.default.join(workflowsDir, "docdrift-sla-check.yml"), SLA_CHECK_WORKFLOW_CONTENT, "utf8");
+}
 function addGitHubWorkflow(cwd) {
     const workflowsDir = node_path_1.default.resolve(cwd, ".github", "workflows");
     node_fs_1.default.mkdirSync(workflowsDir, { recursive: true });
-    const workflowPath = node_path_1.default.join(workflowsDir, "docdrift.yml");
-    node_fs_1.default.writeFileSync(workflowPath, WORKFLOW_CONTENT, "utf8");
+    node_fs_1.default.writeFileSync(node_path_1.default.join(workflowsDir, "docdrift.yml"), WORKFLOW_CONTENT, "utf8");
+    addSlaCheckWorkflow(cwd);
 }
 function runOnboarding(cwd, choices) {
     const created = [];
@@ -75,6 +203,7 @@ function runOnboarding(cwd, choices) {
     if (choices.addWorkflow) {
         addGitHubWorkflow(cwd);
         created.push(".github/workflows/docdrift.yml");
+        created.push(".github/workflows/docdrift-sla-check.yml");
     }
     return { created };
 }

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/dist/src/setup/setup-prompt.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Prompt for Devin setup session — Devin analyzes the repo and generates
+ * docdrift.yaml, DocDrift.md, and GitHub workflow. The repo is already in
+ * Devin's Machine, so Devin has full context.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSetupPrompt = buildSetupPrompt;
+function attachmentBlock(urls) {
+    return urls.map((url, i) => `- ATTACHMENT ${i + 1}: ${url}`).join("\n");
+}
+function buildSetupPrompt(attachmentUrls) {
+    return [
+        "You are Devin. Task: set up docdrift for this repository.",
+        "",
+        "This repo is already loaded in your environment. Analyze it and produce the docdrift configuration files.",
+        "",
+        "ATTACHMENTS (read these for spec and schema):",
+        attachmentBlock(attachmentUrls),
+        "",
+        "REQUIREMENTS:",
+        "",
+        "1) docdrift.yaml (REQUIRED)",
+        "   - Use version: 2",
+        "   - Use specProviders format with format: openapi3",
+        "   - Infer: current (type: export, command, outputPath), published path",
+        "   - Set docsite to your docs root (e.g. docs, apps/docs-site)",
+        "   - devin: apiVersion v1, unlisted true, maxAcuLimit 2, tags [docdrift]",
+        "   - If you find an OpenAPI/swagger file or export script, use it",
+        "   - policy: prCaps, confidence, allowlist (paths Devin may edit), verification.commands (e.g. npm run docs:build, npm run build)",
+        "   - Add schema comment at top: # yaml-language-server: $schema=https://unpkg.com/@devinnn/docdrift/docdrift.schema.json",
+        "",
+        "2) .docdrift/DocDrift.md (RECOMMENDED)",
+        "   - Starter custom instructions: PR title prefix [docdrift], tone, project-specific guidance",
+        "   - If you include this, set devin.customInstructions: [.docdrift/DocDrift.md] in docdrift.yaml",
+        "",
+        "3) .github/workflows/docdrift.yml (RECOMMENDED)",
+        "   - CRITICAL: Use npx @devinnn/docdrift (not npx docdrift)",
+        "   - Steps: checkout, setup-node 20, Determine SHAs (base/head for push or PR), Validate config, Run Doc Drift",
+        "   - Env: DEVIN_API_KEY, GITHUB_TOKEN, GITHUB_REPOSITORY, GITHUB_SHA",
+        "   - Skip when PR head ref starts with docdrift/ (avoid feedback loop)",
+        "   - Upload .docdrift artifacts (drift_report.json, metrics.json, evidence, state.json)",
+        "   - Note: docdrift-sla-check.yml (daily cron for PRs open 7+ days) is added automatically",
+        "",
+        "OUTPUT:",
+        "Emit your final output in the provided structured output schema.",
+        "- docdriftYaml: complete YAML string (no leading/trailing comments about the task)",
+        "- docDriftMd: content for .docdrift/DocDrift.md, or empty string to omit",
+        "- workflowYml: content for .github/workflows/docdrift.yml, or empty string to omit",
+        "- summary: what you inferred (openapi export, docsite path, verification commands)",
+        "",
+        "Do NOT create files in the repo. Only produce the structured output.",
+    ].join("\n");
+}

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.7",
   "private": false,
   "description": "Detect and remediate documentation drift with Devin sessions",
   "main": "dist/src/index.js",
@@ -61,4 +61,4 @@
     "vitest": "^3.0.5",
     "zod-to-json-schema": "^3.25.1"
   }
-}
+}