@devinnn/docdrift 0.1.0 → 0.1.1

package/README.md

@@ -3,7 +3,8 @@
 Docs that never lie: detect drift between merged code and docs, then open low-noise, evidence-grounded remediation via Devin sessions.
 
 ## Deliverables
-- TypeScript CLI package (`docdrift`)
+
+- **npm package**: [@devinnn/docdrift](https://www.npmjs.com/package/@devinnn/docdrift) — TypeScript CLI (`docdrift`)
   - `validate`
   - `detect --base <sha> --head <sha>`
   - `run --base <sha> --head <sha>`
@@ -14,6 +15,7 @@ Docs that never lie: detect drift between merged code and docs, then open low-no
 - PR template + Loom script
 
 ## Why this is low-noise
+
 - One PR per doc area per day (bundling rule).
 - Global PR/day cap.
 - Confidence gating and allowlist enforcement.
@@ -21,17 +23,20 @@ Docs that never lie: detect drift between merged code and docs, then open low-no
 - Idempotency key prevents duplicate actions for same repo/SHAs/action.
 
 ## Detection tiers
-- Tier 0: docs checks (`npm run docs:check`)
-- Tier 1: OpenAPI drift (`openapi/generated.json` vs `docs/reference/openapi.json`)
-- Tier 2: heuristic path impacts (e.g. `apps/api/src/auth/**` -> `docs/guides/auth.md`)
+
+- Tier 0: docsite verification (`npm run docs:gen` then `npm run docs:build`)
+- Tier 1: OpenAPI drift (`openapi/generated.json` vs `apps/docs-site/openapi/openapi.json`)
+- Tier 2: heuristic path impacts (e.g. `apps/api/src/auth/**` -> `apps/docs-site/docs/guides/auth.md`)
 
 Output artifacts (under `.docdrift/`):
+
 - `drift_report.json`
 - `metrics.json` (after `run`)
 
 When you run docdrift as a package (e.g. `npx docdrift` or from another repo), all of this is written to **that repo’s** `.docdrift/` — i.e. the current working directory where the CLI is invoked, not inside the package. Add `.docdrift/` to the consuming repo’s `.gitignore` if you don’t want to commit run artifacts.
 
 ## Core flow (`docdrift run`)
+
 1. Validate config and command availability.
 2. Build drift report.
 3. Policy decision (`OPEN_PR | UPDATE_EXISTING_PR | OPEN_ISSUE | NOOP`).
@@ -41,7 +46,26 @@ When you run docdrift as a package (e.g. `npx docdrift` or from another repo), a
 7. Surface result via GitHub commit comment; open issue on blocked/low-confidence paths.
 8. Persist state in `.docdrift/state.json` and write `.docdrift/metrics.json`.
 
+## Where the docs are (this repo)
+
+| Path                                       | Purpose                                                                 |
+| ------------------------------------------ | ----------------------------------------------------------------------- |
+| `apps/docs-site/openapi/openapi.json`      | Published OpenAPI spec (docdrift updates this when drift is detected).  |
+| `apps/docs-site/docs/api/`                 | API reference MDX generated from the spec (`npm run docs:gen`).        |
+| `apps/docs-site/docs/guides/auth.md`       | Conceptual auth guide (updated only for conceptual drift).              |
+
+The docsite is a Docusaurus app with `docusaurus-plugin-openapi-docs`. The **generated** spec from code lives at `openapi/generated.json` (from `npm run openapi:export`). Drift = generated vs published differ. Verification runs `docs:gen` and `docs:build` so the docsite actually builds.
+
+## How Devin updates them
+
+1. **Evidence bundle** — Docdrift builds a tarball with the drift report, OpenAPI diff, and impacted doc snippets, and uploads it to the Devin API as session attachments.
+2. **Devin session** — Devin is prompted (see `src/devin/prompts.ts`) to update only files under the allowlist (`openapi/**`, `apps/docs-site/**`), make minimal correct edits, run verification (`npm run docs:gen`, `npm run docs:build`), and open **one PR** per doc area with a clear description.
+3. **PR** — Devin updates `apps/docs-site/openapi/openapi.json` to match the current API, runs `docs:gen` to regenerate API reference MDX, and opens a pull request. You review and merge; the docsite builds and the docs are updated.
+
+So the “fix” is a **PR opened by Devin** that you merge; the repo’s docs don’t change until that PR is merged.
+
 ## Local usage
+
 ```bash
 npm install
 npx tsx src/cli.ts validate
@@ -54,25 +78,29 @@ DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha>
 
 You can run a full end-to-end demo locally with no remote repo. Ensure `.env` has `DEVIN_API_KEY` (and optionally `GITHUB_TOKEN` only when you have a real repo).
 
-1. **One-time setup (already done if you have two commits with drift)**  
-   - Git is inited; baseline commit has docs in sync with API.  
+1. **One-time setup (already done if you have two commits with drift)**
+   - Git is inited; baseline commit has docs in sync with API.
    - A later commit changes `apps/api/src/model.ts` (e.g. `name` → `fullName`) and runs `npm run openapi:export`, so `openapi/generated.json` drifts from `docs/reference/openapi.json`.
 
 2. **Run the pipeline**
+
    ```bash
    npm install
    npx tsx src/cli.ts validate
    npx tsx src/cli.ts detect --base b0f624f --head 6030902
    ```
+
    - Use your own `git log --oneline -3` to get `base` (older) and `head` (newer) SHAs if you recreated the demo.
 
 3. **Run with Devin (no GitHub calls)**  
    Omit `GITHUB_TOKEN` so the CLI does not post comments or create issues. Devin session still runs; results are printed to stdout and written to `.docdrift/state.json` and `metrics.json`.
+
    ```bash
    export $(grep -v '^#' .env | xargs)
    unset GITHUB_TOKEN GITHUB_REPOSITORY GITHUB_SHA
    npx tsx src/cli.ts run --base b0f624f --head 6030902
    ```
+
    - `run` can take 1–3 minutes while the Devin session runs.
 
 4. **What you’ll see**
@@ -93,14 +121,15 @@ You can run a full end-to-end demo locally with no remote repo. Ensure `.env` ha
 ## Run on GitHub
 
 1. **Create a repo** on GitHub (e.g. `your-org/docdrift`), then add the remote and push:
+
    ```bash
    git remote add origin https://github.com/your-org/docdrift.git
    git push -u origin main
    ```
 
 2. **Add secret**  
-   Repo → **Settings** → **Secrets and variables** → **Actions** → **New repository secret**  
-   - Name: `DEVIN_API_KEY`  
+   Repo → **Settings** → **Secrets and variables** → **Actions** → **New repository secret**
+   - Name: `DEVIN_API_KEY`
    - Value: your Devin API key (same as in `.env` locally)
 
    `GITHUB_TOKEN` is provided automatically; the workflow uses it for commit comments and issues.
@@ -109,6 +138,25 @@ You can run a full end-to-end demo locally with no remote repo. Ensure `.env` ha
    - **Push to `main`** — runs on every push (compares previous commit vs current).
    - **Manual run** — **Actions** tab → **devin-doc-drift** → **Run workflow** (uses `HEAD` and `HEAD^` as head/base).
 
+## See it work (demo on GitHub)
+
+This repo has **intentional drift**: the API has been expanded (new fields `fullName`, `avatarUrl`, `createdAt`, `role` and new endpoint `GET /v1/users` with pagination), but **docs are unchanged** (`docs/reference/openapi.json` and `docs/reference/api.md` still describe the old single-endpoint, `id`/`name`/`email` only). Running docdrift will detect that and hand a large diff to Devin to fix via a PR. To see it:
+
+1. **Create a new GitHub repo** (e.g. `docdrift-demo`) so you have a clean place to run the workflow.
+2. **Push this project with full history** (so both commits are on `main`):
+   ```bash
+   git remote add origin https://github.com/YOUR_ORG/docdrift-demo.git
+   git push -u origin main
+   ```
+3. **Add secret** in that repo: **Settings** → **Secrets and variables** → **Actions** → `DEVIN_API_KEY` = your Devin API key.
+4. **Trigger the workflow**
+   - Either push another small commit (e.g. README tweak), or
+   - **Actions** → **devin-doc-drift** → **Run workflow**.
+5. **Where to look**
+   - **Actions** → open the run → **Run Doc Drift** step: the step logs print JSON with `sessionUrl`, `prUrl`, and `outcome` per doc area. Open any `sessionUrl` in your browser to see the Devin session.
+   - **Artifacts**: download **docdrift-artifacts** for `.docdrift/drift_report.json`, `.docdrift/metrics.json`, and evidence.
+   - **Devin dashboard**: sessions are tagged `docdrift`; you’ll see the run there once the step completes (often 1–3 minutes).
+
 ## Using in another repo (published package)
 
 Once published to npm, any repo can use the CLI locally or in GitHub Actions.
@@ -116,14 +164,14 @@ 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`).
 2. **CLI**
    ```bash
-   npx docdrift@latest validate
-   npx docdrift@latest detect --base <base-sha> --head <head-sha>
+   npx @devinnn/docdrift validate
+   npx @devinnn/docdrift detect --base <base-sha> --head <head-sha>
    # With env for run:
-   DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha> npx docdrift@latest run --base <base-sha> --head <head-sha>
+   DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha> npx @devinnn/docdrift run --base <base-sha> --head <head-sha>
    ```
 3. **GitHub Actions** — add a step that runs the CLI (e.g. after checkout and setting base/head):
    ```yaml
-   - run: npx docdrift@latest run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }}
+   - run: npx @devinnn/docdrift run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }}
      env:
        DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -140,8 +188,10 @@ Once published to npm, any repo can use the CLI locally or in GitHub Actions.
 - Only the `dist/` directory is included (`files` in `package.json`). Consumers get the built CLI; they provide their own `docdrift.yaml` in their repo.
 
 ## Demo scenario
+
 - Autogen drift: rename a field in `apps/api/src/model.ts`, merge to `main`, observe docs PR path.
 - Conceptual drift: change auth behavior under `apps/api/src/auth/**`, merge to `main`, observe single escalation issue.
 
 ## Loom
+
 See `/Users/cameronking/Desktop/sideproject/docdrift/loom.md` for the minute-by-minute recording script.

package/dist/src/cli.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("./index");
 function getArg(args, flag) {
     const index = args.indexOf(flag);
@@ -32,6 +37,9 @@ async function main() {
             const headSha = (0, index_1.requireSha)(getArg(args, "--head"), "--head");
             const trigger = (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
             const results = await (0, index_1.runDocDrift)({ baseSha, headSha, trigger });
+            const outPath = node_path_1.default.resolve(".docdrift", "run-output.json");
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(outPath), { recursive: true });
+            node_fs_1.default.writeFileSync(outPath, JSON.stringify(results, null, 2), "utf-8");
             console.log(JSON.stringify(results, null, 2));
             return;
         }

package/dist/src/config/load.js

@@ -21,5 +21,18 @@ function loadConfig(configPath = "docdrift.yaml") {
             .join("\n");
         throw new Error(`Invalid config:\n${message}`);
     }
-    return result.data;
+    const data = result.data;
+    if (data.devin.customInstructions?.length) {
+        const configDir = node_path_1.default.dirname(resolved);
+        const contents = [];
+        for (const p of data.devin.customInstructions) {
+            const fullPath = node_path_1.default.resolve(configDir, p);
+            if (!node_fs_1.default.existsSync(fullPath)) {
+                throw new Error(`Custom instructions file not found: ${fullPath}`);
+            }
+            contents.push(node_fs_1.default.readFileSync(fullPath, "utf8"));
+        }
+        data.devin.customInstructionContent = contents.join("\n\n");
+    }
+    return data;
 }

package/dist/src/config/schema.js

@@ -4,31 +4,31 @@ exports.docDriftConfigSchema = void 0;
 const zod_1 = require("zod");
 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)
+    impacts: zod_1.z.array(zod_1.z.string().min(1)).min(1),
 });
 const openApiDetectSchema = zod_1.z.object({
     exportCmd: zod_1.z.string().min(1),
     generatedPath: zod_1.z.string().min(1),
-    publishedPath: zod_1.z.string().min(1)
+    publishedPath: zod_1.z.string().min(1),
 });
 const docAreaSchema = zod_1.z.object({
     name: zod_1.z.string().min(1),
     mode: zod_1.z.enum(["autogen", "conceptual"]),
     owners: zod_1.z.object({
-        reviewers: zod_1.z.array(zod_1.z.string().min(1)).min(1)
+        reviewers: zod_1.z.array(zod_1.z.string().min(1)).min(1),
     }),
     detect: zod_1.z
         .object({
         openapi: openApiDetectSchema.optional(),
-        paths: zod_1.z.array(pathRuleSchema).optional()
+        paths: zod_1.z.array(pathRuleSchema).optional(),
     })
         .refine((v) => Boolean(v.openapi) || Boolean(v.paths?.length), {
-        message: "docArea.detect must include openapi or paths"
+        message: "docArea.detect must include openapi or paths",
     }),
     patch: zod_1.z.object({
         targets: zod_1.z.array(zod_1.z.string().min(1)).optional(),
-        requireHumanConfirmation: zod_1.z.boolean().optional().default(false)
-    })
+        requireHumanConfirmation: zod_1.z.boolean().optional().default(false),
+    }),
 });
 exports.docDriftConfigSchema = zod_1.z.object({
     version: zod_1.z.literal(1),
@@ -36,20 +36,22 @@ exports.docDriftConfigSchema = zod_1.z.object({
         apiVersion: zod_1.z.literal("v1"),
         unlisted: zod_1.z.boolean().default(true),
         maxAcuLimit: zod_1.z.number().int().positive().default(2),
-        tags: zod_1.z.array(zod_1.z.string().min(1)).default(["docdrift"])
+        tags: zod_1.z.array(zod_1.z.string().min(1)).default(["docdrift"]),
+        customInstructions: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        customInstructionContent: zod_1.z.string().optional(),
     }),
     policy: zod_1.z.object({
         prCaps: zod_1.z.object({
             maxPrsPerDay: zod_1.z.number().int().positive().default(1),
-            maxFilesTouched: zod_1.z.number().int().positive().default(12)
+            maxFilesTouched: zod_1.z.number().int().positive().default(12),
         }),
         confidence: zod_1.z.object({
-            autopatchThreshold: zod_1.z.number().min(0).max(1).default(0.8)
+            autopatchThreshold: zod_1.z.number().min(0).max(1).default(0.8),
         }),
         allowlist: zod_1.z.array(zod_1.z.string().min(1)).min(1),
         verification: zod_1.z.object({
-            commands: zod_1.z.array(zod_1.z.string().min(1)).min(1)
-        })
+            commands: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+        }),
     }),
-    docAreas: zod_1.z.array(docAreaSchema).min(1)
+    docAreas: zod_1.z.array(docAreaSchema).min(1),
 });

package/dist/src/config/validate.js

@@ -15,7 +15,7 @@ async function validateRuntimeConfig(config) {
         ...config.policy.verification.commands,
         ...config.docAreas
             .map((area) => area.detect.openapi?.exportCmd)
-            .filter((value) => Boolean(value))
+            .filter((value) => Boolean(value)),
     ]);
     for (const command of commandSet) {
         const binary = commandBinary(command);

package/dist/src/detect/docsCheck.js

@@ -21,7 +21,7 @@ async function runDocsChecks(commands, evidenceDir) {
             "\n--- stdout ---",
             result.stdout,
             "\n--- stderr ---",
-            result.stderr
+            result.stderr,
         ].join("\n"), "utf8");
         logs.push(logPath);
         commandResults.push({ command, exitCode: result.exitCode, logPath });
@@ -31,7 +31,7 @@ async function runDocsChecks(commands, evidenceDir) {
         return {
             logs,
             commandResults,
-            summary: "Docs checks passed"
+            summary: "Docs checks passed",
         };
     }
     return {
@@ -42,7 +42,7 @@ async function runDocsChecks(commands, evidenceDir) {
             kind: "docs_check_failed",
             tier: 0,
             confidence: 0.99,
-            evidence: failed.map((result) => result.logPath)
-        }
+            evidence: failed.map((result) => result.logPath),
+        },
     };
 }

package/dist/src/detect/heuristics.js

@@ -38,7 +38,7 @@ function detectHeuristicImpacts(docArea, changedPaths, evidenceDir) {
             kind: "heuristic_path_impact",
             tier: 2,
             confidence: 0.67,
-            evidence: [evidencePath]
-        }
+            evidence: [evidencePath],
+        },
     };
 }

package/dist/src/detect/index.js

@@ -26,7 +26,7 @@ async function buildDriftReport(input) {
         baseSha: input.baseSha,
         headSha: input.headSha,
         trigger: input.trigger,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
     };
     const evidenceRoot = node_path_1.default.resolve(".docdrift", "evidence", runInfo.runId);
     (0, fs_1.ensureDir)(evidenceRoot);
@@ -69,7 +69,7 @@ async function buildDriftReport(input) {
             signals,
             impactedDocs: [...impactedDocs],
             recommendedAction: defaultRecommendation(docArea.mode, signals),
-            summary: summaries.filter(Boolean).join(" | ")
+            summary: summaries.filter(Boolean).join(" | "),
         });
     }
     const report = {
@@ -78,15 +78,15 @@ async function buildDriftReport(input) {
             baseSha: input.baseSha,
             headSha: input.headSha,
             trigger: input.trigger,
-            timestamp: runInfo.timestamp
+            timestamp: runInfo.timestamp,
         },
-        items
+        items,
     };
     (0, fs_1.writeJsonFile)(node_path_1.default.resolve(".docdrift", "drift_report.json"), report);
     (0, fs_1.writeJsonFile)(node_path_1.default.join(evidenceRoot, "changeset.json"), {
         changedPaths,
         diffSummary,
-        commits
+        commits,
     });
     return { report, changedPaths, evidenceRoot, runInfo, checkSummaries };
 }

package/dist/src/detect/openapi.js

@@ -56,7 +56,7 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
         "\n--- stdout ---",
         exportResult.stdout,
         "\n--- stderr ---",
-        exportResult.stderr
+        exportResult.stderr,
     ].join("\n"), "utf8");
     if (exportResult.exitCode !== 0) {
         return {
@@ -67,8 +67,8 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
                 kind: "weak_evidence",
                 tier: 2,
                 confidence: 0.35,
-                evidence: [exportLogPath]
-            }
+                evidence: [exportLogPath],
+            },
         };
     }
     if (!node_fs_1.default.existsSync(openapi.generatedPath) || !node_fs_1.default.existsSync(openapi.publishedPath)) {
@@ -80,8 +80,8 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
                 kind: "weak_evidence",
                 tier: 2,
                 confidence: 0.35,
-                evidence: [exportLogPath]
-            }
+                evidence: [exportLogPath],
+            },
         };
     }
     const generatedRaw = node_fs_1.default.readFileSync(openapi.generatedPath, "utf8");
@@ -94,7 +94,7 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
         return {
             impactedDocs: [openapi.publishedPath],
             evidenceFiles: [exportLogPath],
-            summary: "No OpenAPI drift detected"
+            summary: "No OpenAPI drift detected",
         };
     }
     const summary = summarizeSpecDelta(publishedJson, generatedJson);
@@ -107,7 +107,7 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
         normalizedPublished,
         "",
         "# Generated (normalized)",
-        normalizedGenerated
+        normalizedGenerated,
     ].join("\n"), "utf8");
     return {
         impactedDocs: [...new Set([openapi.publishedPath, ...(docArea.patch.targets ?? [])])],
@@ -117,7 +117,7 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
             kind: "openapi_diff",
             tier: 1,
             confidence: 0.95,
-            evidence: [diffPath]
-        }
+            evidence: [diffPath],
+        },
     };
 }

package/dist/src/devin/prompts.js

@@ -6,7 +6,7 @@ function attachmentBlock(attachmentUrls) {
     return attachmentUrls.map((url, index) => `- ATTACHMENT ${index + 1}: ${url}`).join("\n");
 }
 function buildAutogenPrompt(input) {
-    return [
+    const base = [
         "You are Devin. Task: update API reference docs to match actual code/spec changes.",
         "",
         "EVIDENCE (attachments):",
@@ -30,12 +30,16 @@ function buildAutogenPrompt(input) {
         "  e) get blocked (status=BLOCKED + questions),",
         "  f) complete (status=DONE).",
         "",
-        `Goal: Produce a PR for doc area ${input.item.docArea} using only the evidence.`
+        `Goal: Produce a PR for doc area ${input.item.docArea} using only the evidence.`,
     ].join("\n");
+    if (input.customAppend) {
+        return base + "\n\n---\n\nCustom instructions:\n\n" + input.customAppend;
+    }
+    return base;
 }
 function buildConceptualPrompt(input) {
-    return [
-        "You are Devin. Task: propose minimal edits to conceptual docs potentially impacted by code changes.",
+    const base = [
+        "You are Devin. Task: propose minimal edits to conceptual docs potentially impacted by code changes. i..e GUIDES",
         "",
         "EVIDENCE (attachments):",
         attachmentBlock(input.attachmentUrls),
@@ -50,6 +54,10 @@ function buildConceptualPrompt(input) {
         "- Update at planning, editing, verifying, open-pr, blocked, done milestones.",
         "- If blocked, fill blocked.questions with concrete, reviewer-actionable questions.",
         "",
-        "Goal: either open a very small PR with confidence or open an issue/comment with crisp questions and suggested patch text."
+        "Goal: either open a very small PR with confidence or open an issue/comment with crisp questions and suggested patch text.",
     ].join("\n");
+    if (input.customAppend) {
+        return base + "\n\n---\n\nCustom instructions:\n\n" + input.customAppend;
+    }
+    return base;
 }

package/dist/src/devin/schemas.js

@@ -13,7 +13,7 @@ exports.PatchPlanSchema = {
         "evidence",
         "filesToEdit",
         "verification",
-        "nextAction"
+        "nextAction",
     ],
     properties: {
         status: { enum: ["PLANNING", "EDITING", "VERIFYING", "OPENED_PR", "BLOCKED", "DONE"] },
@@ -27,8 +27,8 @@ exports.PatchPlanSchema = {
             required: ["attachments", "diffSummary"],
             properties: {
                 attachments: { type: "array", items: { type: "string" } },
-                diffSummary: { type: "string" }
-            }
+                diffSummary: { type: "string" },
+            },
         },
         filesToEdit: { type: "array", items: { type: "string" } },
         verification: {
@@ -37,8 +37,8 @@ exports.PatchPlanSchema = {
             required: ["commands"],
             properties: {
                 commands: { type: "array", items: { type: "string" } },
-                results: { type: "array", items: { type: "string" } }
-            }
+                results: { type: "array", items: { type: "string" } },
+            },
         },
         nextAction: { enum: ["OPEN_PR", "OPEN_ISSUE", "NOOP"] },
         pr: {
@@ -46,18 +46,18 @@ exports.PatchPlanSchema = {
             additionalProperties: false,
             properties: {
                 title: { type: "string" },
-                url: { type: "string" }
-            }
+                url: { type: "string" },
+            },
         },
         blocked: {
             type: "object",
             additionalProperties: false,
             properties: {
                 reason: { type: "string" },
-                questions: { type: "array", items: { type: "string" } }
-            }
-        }
-    }
+                questions: { type: "array", items: { type: "string" } },
+            },
+        },
+    },
 };
 exports.PatchResultSchema = {
     type: "object",
@@ -74,8 +74,8 @@ exports.PatchResultSchema = {
             required: ["commands", "results"],
             properties: {
                 commands: { type: "array", items: { type: "string" } },
-                results: { type: "array", items: { type: "string" } }
-            }
+                results: { type: "array", items: { type: "string" } },
+            },
         },
         links: {
             type: "object",
@@ -84,16 +84,16 @@ exports.PatchResultSchema = {
             properties: {
                 sessionUrl: { type: "string" },
                 prUrl: { type: "string" },
-                issueUrl: { type: "string" }
-            }
+                issueUrl: { type: "string" },
+            },
         },
         blocked: {
             type: "object",
             additionalProperties: false,
             properties: {
                 reason: { type: "string" },
-                questions: { type: "array", items: { type: "string" } }
-            }
-        }
-    }
+                questions: { type: "array", items: { type: "string" } },
+            },
+        },
+    },
 };

package/dist/src/devin/v1.js

@@ -24,9 +24,9 @@ async function devinUploadAttachment(apiKey, filePath) {
     const response = await fetch("https://api.devin.ai/v1/attachments", {
         method: "POST",
         headers: {
-            Authorization: `Bearer ${apiKey}`
+            Authorization: `Bearer ${apiKey}`,
         },
-        body: form
+        body: form,
     });
     const text = await response.text();
     ensureOk(response, text, "Upload attachment");
@@ -49,9 +49,9 @@ async function devinCreateSession(apiKey, body) {
         method: "POST",
         headers: {
             Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json"
+            "Content-Type": "application/json",
         },
-        body: JSON.stringify(body)
+        body: JSON.stringify(body),
     });
     const text = await response.text();
     ensureOk(response, text, "Create session");
@@ -60,8 +60,8 @@ async function devinCreateSession(apiKey, body) {
 async function devinGetSession(apiKey, sessionId) {
     const response = await fetch(`https://api.devin.ai/v1/sessions/${sessionId}`, {
         headers: {
-            Authorization: `Bearer ${apiKey}`
-        }
+            Authorization: `Bearer ${apiKey}`,
+        },
     });
     const text = await response.text();
     ensureOk(response, text, "Get session");
@@ -77,8 +77,8 @@ async function devinListSessions(apiKey, params = {}) {
     }
     const response = await fetch(url, {
         headers: {
-            Authorization: `Bearer ${apiKey}`
-        }
+            Authorization: `Bearer ${apiKey}`,
+        },
     });
     const text = await response.text();
     ensureOk(response, text, "List sessions");

package/dist/src/evidence/bundle.js

@@ -52,7 +52,7 @@ async function buildEvidenceBundle(input) {
             baseSha: input.runInfo.baseSha,
             headSha: input.runInfo.headSha,
             trigger: input.runInfo.trigger,
-            timestamp: input.runInfo.timestamp
+            timestamp: input.runInfo.timestamp,
         },
         docArea: input.item.docArea,
         mode: input.item.mode,
@@ -60,7 +60,7 @@ async function buildEvidenceBundle(input) {
         signals: input.item.signals,
         impactedDocs: input.item.impactedDocs,
         copiedEvidence,
-        copiedDocs
+        copiedDocs,
     });
     const archivePath = `${bundleDir}.tar.gz`;
     const parent = node_path_1.default.dirname(bundleDir);
@@ -73,7 +73,7 @@ async function buildEvidenceBundle(input) {
         bundleDir,
         archivePath,
         manifestPath,
-        attachmentPaths: [archivePath, manifestPath]
+        attachmentPaths: [archivePath, manifestPath],
     };
 }
 function writeMetrics(metrics) {

package/dist/src/github/client.js

@@ -19,7 +19,7 @@ async function postCommitComment(input) {
         owner,
         repo,
         commit_sha: input.commitSha,
-        body: input.body
+        body: input.body,
     });
     return response.data.html_url;
 }
@@ -31,7 +31,7 @@ async function createIssue(input) {
         repo,
         title: input.issue.title,
         body: input.issue.body,
-        labels: input.issue.labels
+        labels: input.issue.labels,
     });
     return response.data.html_url;
 }

package/dist/src/index.js

@@ -45,7 +45,7 @@ function inferQuestions(structured) {
     }
     return [
         "Which conceptual docs should be updated for this behavior change?",
-        "What are the exact user-visible semantics after this merge?"
+        "What are the exact user-visible semantics after this merge?",
     ];
 }
 async function executeSession(input) {
@@ -60,14 +60,16 @@ async function executeSession(input) {
             attachmentUrls,
             verificationCommands: input.config.policy.verification.commands,
             allowlist: input.config.policy.allowlist,
-            confidenceThreshold: input.config.policy.confidence.autopatchThreshold
+            confidenceThreshold: input.config.policy.confidence.autopatchThreshold,
+            customAppend: input.config.devin.customInstructionContent ?? undefined,
         })
         : (0, prompts_1.buildConceptualPrompt)({
             item: input.item,
             attachmentUrls,
             verificationCommands: input.config.policy.verification.commands,
             allowlist: input.config.policy.allowlist,
-            confidenceThreshold: input.config.policy.confidence.autopatchThreshold
+            confidenceThreshold: input.config.policy.confidence.autopatchThreshold,
+            customAppend: input.config.devin.customInstructionContent ?? undefined,
         });
     const session = await (0, v1_1.devinCreateSession)(input.apiKey, {
         prompt,
@@ -76,13 +78,13 @@ async function executeSession(input) {
         tags: [...new Set([...(input.config.devin.tags ?? []), "docdrift", input.item.docArea])],
         attachments: attachmentUrls,
         structured_output: {
-            schema: schemas_1.PatchPlanSchema
+            schema: schemas_1.PatchPlanSchema,
         },
         metadata: {
             repository: input.repository,
             docArea: input.item.docArea,
-            mode: input.item.mode
-        }
+            mode: input.item.mode,
+        },
     });
     const finalSession = await (0, v1_1.pollUntilTerminal)(input.apiKey, session.session_id);
     const structured = parseStructured(finalSession);
@@ -96,7 +98,7 @@ async function executeSession(input) {
         : verificationCommands.map(() => "not reported");
     const verification = verificationCommands.map((command, idx) => ({
         command,
-        result: verificationResults[idx] ?? "not reported"
+        result: verificationResults[idx] ?? "not reported",
     }));
     if (prUrl) {
         return {
@@ -104,7 +106,7 @@ async function executeSession(input) {
             summary: String(structured?.summary ?? "PR opened by Devin"),
             sessionUrl: session.url,
             prUrl,
-            verification
+            verification,
         };
     }
     if (status === "blocked" || structured?.status === "BLOCKED") {
@@ -113,14 +115,14 @@ async function executeSession(input) {
             summary: String(structured?.blocked?.reason ?? structured?.summary ?? "Session blocked"),
             sessionUrl: session.url,
             questions: inferQuestions(structured),
-            verification
+            verification,
         };
     }
     return {
         outcome: "NO_CHANGE",
         summary: String(structured?.summary ?? "Session completed without PR"),
         sessionUrl: session.url,
-        verification
+        verification,
     };
 }
 async function runDetect(options) {
@@ -135,7 +137,7 @@ async function runDetect(options) {
         repo,
         baseSha: options.baseSha,
         headSha: options.headSha,
-        trigger: options.trigger ?? "manual"
+        trigger: options.trigger ?? "manual",
     });
     (0, log_1.logInfo)(`Drift items detected: ${report.items.length}`);
     return { hasDrift: report.items.length > 0 };
@@ -155,7 +157,7 @@ async function runDocDrift(options) {
         repo,
         baseSha: options.baseSha,
         headSha: options.headSha,
-        trigger: options.trigger ?? "manual"
+        trigger: options.trigger ?? "manual",
     });
     const docAreaByName = new Map(config.docAreas.map((area) => [area.name, area]));
     let state = (0, state_1.loadState)();
@@ -168,7 +170,7 @@ async function runDocDrift(options) {
         blockedCount: 0,
         timeToSessionTerminalMs: [],
         docAreaCounts: {},
-        noiseRateProxy: 0
+        noiseRateProxy: 0,
     };
     for (const item of report.items) {
         metrics.docAreaCounts[item.docArea] = (metrics.docAreaCounts[item.docArea] ?? 0) + 1;
@@ -183,14 +185,14 @@ async function runDocDrift(options) {
             state,
             repo,
             baseSha: options.baseSha,
-            headSha: options.headSha
+            headSha: options.headSha,
         });
         if (decision.action === "NOOP") {
             results.push({
                 docArea: item.docArea,
                 decision,
                 outcome: "NO_CHANGE",
-                summary: decision.reason
+                summary: decision.reason,
             });
             continue;
         }
@@ -205,14 +207,14 @@ async function runDocDrift(options) {
                 decision,
                 outcome,
                 summary,
-                prUrl: existingPr
+                prUrl: existingPr,
             });
             state = (0, engine_1.applyDecisionToState)({
                 state,
                 decision,
                 docArea: item.docArea,
                 outcome,
-                link: existingPr
+                link: existingPr,
             });
             continue;
         }
@@ -221,7 +223,10 @@ async function runDocDrift(options) {
         let sessionOutcome = {
             outcome: "NO_CHANGE",
             summary: "Skipped Devin session",
-            verification: config.policy.verification.commands.map((command) => ({ command, result: "not run" }))
+            verification: config.policy.verification.commands.map((command) => ({
+                command,
+                result: "not run",
+            })),
         };
         if (devinApiKey) {
             const sessionStart = Date.now();
@@ -230,7 +235,7 @@ async function runDocDrift(options) {
                 repository: repo,
                 item,
                 attachmentPaths,
-                config
+                config,
             });
             metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
         }
@@ -240,12 +245,17 @@ async function runDocDrift(options) {
                 outcome: "BLOCKED",
                 summary: "DEVIN_API_KEY missing; cannot start Devin session",
                 questions: ["Set DEVIN_API_KEY in environment or GitHub Actions secrets"],
-                verification: config.policy.verification.commands.map((command) => ({ command, result: "not run" }))
+                verification: config.policy.verification.commands.map((command) => ({
+                    command,
+                    result: "not run",
+                })),
             };
         }
         let issueUrl;
         if (githubToken &&
-            (decision.action === "OPEN_ISSUE" || sessionOutcome.outcome === "BLOCKED" || sessionOutcome.outcome === "NO_CHANGE")) {
+            (decision.action === "OPEN_ISSUE" ||
+                sessionOutcome.outcome === "BLOCKED" ||
+                sessionOutcome.outcome === "NO_CHANGE")) {
             issueUrl = await (0, client_1.createIssue)({
                 token: githubToken,
                 repository: repo,
@@ -254,11 +264,13 @@ async function runDocDrift(options) {
                     body: (0, client_1.renderBlockedIssueBody)({
                         docArea: item.docArea,
                         evidenceSummary: item.summary,
-                        questions: sessionOutcome.questions ?? ["Please confirm intended behavior and doc wording."],
-                        sessionUrl: sessionOutcome.sessionUrl
+                        questions: sessionOutcome.questions ?? [
+                            "Please confirm intended behavior and doc wording.",
+                        ],
+                        sessionUrl: sessionOutcome.sessionUrl,
                     }),
-                    labels: ["docdrift"]
-                }
+                    labels: ["docdrift"],
+                },
             });
             metrics.issuesOpened += 1;
             sessionOutcome.outcome = "ISSUE_OPENED";
@@ -276,7 +288,7 @@ async function runDocDrift(options) {
             summary: sessionOutcome.summary,
             sessionUrl: sessionOutcome.sessionUrl,
             prUrl: sessionOutcome.prUrl,
-            issueUrl
+            issueUrl,
         };
         results.push(result);
         if (githubToken) {
@@ -288,13 +300,13 @@ async function runDocDrift(options) {
                 sessionUrl: sessionOutcome.sessionUrl,
                 prUrl: sessionOutcome.prUrl,
                 issueUrl,
-                validation: sessionOutcome.verification
+                validation: sessionOutcome.verification,
             });
             await (0, client_1.postCommitComment)({
                 token: githubToken,
                 repository: repo,
                 commitSha,
-                body
+                body,
             });
         }
         state = (0, engine_1.applyDecisionToState)({
@@ -302,16 +314,18 @@ async function runDocDrift(options) {
             decision,
             docArea: item.docArea,
             outcome: sessionOutcome.outcome,
-            link: sessionOutcome.prUrl ?? issueUrl
+            link: sessionOutcome.prUrl ?? issueUrl,
         });
     }
     (0, state_1.saveState)(state);
     metrics.noiseRateProxy =
-        metrics.driftItemsDetected === 0 ? 0 : Number((metrics.prsOpened / metrics.driftItemsDetected).toFixed(4));
+        metrics.driftItemsDetected === 0
+            ? 0
+            : Number((metrics.prsOpened / metrics.driftItemsDetected).toFixed(4));
     (0, bundle_1.writeMetrics)(metrics);
     (0, log_1.logInfo)("Run complete", {
         items: report.items.length,
-        elapsedMs: Date.now() - startedAt
+        elapsedMs: Date.now() - startedAt,
     });
     return results;
 }

package/dist/src/model/state.js

@@ -5,6 +5,6 @@ const emptyState = () => ({
     idempotency: {},
     dailyPrCount: {},
     areaDailyPrOpened: {},
-    areaLatestPr: {}
+    areaLatestPr: {},
 });
 exports.emptyState = emptyState;

package/dist/src/policy/confidence.js

@@ -6,7 +6,7 @@ const tierWeight = {
     0: 1,
     1: 0.9,
     2: 0.6,
-    3: 0.35
+    3: 0.35,
 };
 function clamp01(value) {
     return Math.max(0, Math.min(1, value));

package/dist/src/policy/engine.js

@@ -70,21 +70,21 @@ function decidePolicy(input) {
         docArea: item.docArea,
         baseSha: input.baseSha,
         headSha: input.headSha,
-        action
+        action,
     });
     if (state.idempotency[idempotencyKey]) {
         return {
             action: "NOOP",
             confidence,
             reason: "Idempotency key already processed",
-            idempotencyKey
+            idempotencyKey,
         };
     }
     return {
         action,
         confidence,
         reason,
-        idempotencyKey
+        idempotencyKey,
     };
 }
 function applyDecisionToState(input) {
@@ -94,7 +94,7 @@ function applyDecisionToState(input) {
         createdAt: new Date().toISOString(),
         action: input.decision.action,
         outcome: input.outcome,
-        link: input.link
+        link: input.link,
     };
     next.idempotency[input.decision.idempotencyKey] = record;
     if (input.outcome === "PR_OPENED") {

package/dist/src/utils/exec.js

@@ -8,7 +8,7 @@ async function execCommand(command, cwd = process.cwd()) {
     try {
         const { stdout, stderr } = await exec(command, {
             cwd,
-            maxBuffer: 10 * 1024 * 1024
+            maxBuffer: 10 * 1024 * 1024,
         });
         return { command, stdout, stderr, exitCode: 0 };
     }
@@ -18,7 +18,7 @@ async function execCommand(command, cwd = process.cwd()) {
             command,
             stdout: e.stdout ?? "",
             stderr: e.stderr ?? String(error),
-            exitCode: typeof e.code === "number" ? e.code : 1
+            exitCode: typeof e.code === "number" ? e.code : 1,
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinnn/docdrift",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Detect and remediate documentation drift with Devin sessions",
   "main": "dist/src/index.js",
@@ -11,9 +11,20 @@
   "engines": {
     "node": ">=20"
   },
-  "files": ["dist/src"],
-  "repository": { "type": "git", "url": "" },
-  "keywords": ["docs", "drift", "openapi", "devin", "github-actions"],
+  "files": [
+    "dist/src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "keywords": [
+    "docs",
+    "drift",
+    "openapi",
+    "devin",
+    "github-actions"
+  ],
   "license": "MIT",
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -21,7 +32,9 @@
     "lint": "eslint .",
     "format": "prettier -w .",
     "openapi:export": "tsx apps/api/scripts/export-openapi.ts",
-    "docs:check": "node scripts/docs-check.js",
+    "docs:gen": "npm run --prefix apps/docs-site docusaurus -- gen-api-docs api",
+    "docs:build": "npm run --prefix apps/docs-site build",
+    "docs:serve": "npm run --prefix apps/docs-site start",
     "docdrift": "tsx src/cli.ts"
   },
   "dependencies": {