farming-labs · Kinfe123 · Aug 20, 2026 · Aug 20, 2026
diff --git a/packages/docs/src/cli/agent.test.ts b/packages/docs/src/cli/agent.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createServer } from "node:http";
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { AddressInfo } from "node:net";
@@ -1231,6 +1231,64 @@ Updated body.
     );
   });
 
+  it("keeps generated content fresh when only the page file mtime changes", async () => {
+    writeFileSync(
+      path.join(tmpDir, "docs.config.ts"),
+      `export default { entry: "docs" };`,
+      "utf-8",
+    );
+    mkdirSync(path.join(tmpDir, "app", "docs", "installation"), { recursive: true });
+    const pagePath = path.join(tmpDir, "app", "docs", "installation", "page.mdx");
+    writeFileSync(
+      pagePath,
+      `---
+title: "Installation"
+description: "Install the framework"
+agent:
+  tokenBudget: 500
+---
+
+# Installation
+
+Body.
+`,
+      "utf-8",
+    );
+
+    const server = createServer(async (_req, res) => {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          output: "Initial compacted",
+          original_input_tokens: 100,
+          output_tokens: 25,
+        }),
+      );
+    });
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+    const { port } = server.address() as AddressInfo;
+
+    try {
+      process.chdir(tmpDir);
+      await compactAgentDocs({
+        apiKey: "test-key",
+        baseUrl: `http://127.0.0.1:${port}`,
+        pages: ["installation"],
+      });
+    } finally {
+      await new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+    }
+
+    // A fresh checkout resets every file's mtime; that alone must not flag drift.
+    const shifted = new Date(Date.now() + 400 * 24 * 60 * 60 * 1000);
+    utimesSync(pagePath, shifted, shifted);
+
+    delete process.env.DOCS_CLOUD_API_KEY;
+    await expect(compactAgentDocs({ check: true })).resolves.toBeUndefined();
+  });
+
   it("records reviewed agent.md hashes and fails when reviewed content or source drifts", async () => {
     writeFileSync(
       path.join(tmpDir, "docs.config.ts"),

diff --git a/packages/docs/src/cli/agent.ts b/packages/docs/src/cli/agent.ts
@@ -686,11 +686,15 @@ function buildPageOptions(
 }
 
 function buildResolvedPageSourceDocument(page: DocsMcpPage): string {
+  // Filesystem mtimes differ across checkouts, so the mtime-derived lastModified
+  // fallback must not leak into compaction source hashes; only explicit
+  // frontmatter lastmod may contribute a last_updated line.
   return stripGeneratedPageAgentContractMarkdown(
     renderDocsMarkdownDocument({
       ...page,
       agentContent: undefined,
       agentRawContent: undefined,
+      lastModified: undefined,
     }),
   );
 }

diff --git a/website/.farming-labs/agent-compaction-reviews.json b/website/.farming-labs/agent-compaction-reviews.json
@@ -1,41 +1,68 @@
 {
   "version": 1,
   "reviews": [
+    {
+      "route": "/docs/cli",
+      "sourceHash": "fnv1a64:ff98ba0ac661af3e",
+      "settingsHash": "fnv1a64:e50e89e221226fc3",
+      "outputHash": "fnv1a64:c95a0dd048e26147",
+      "reviewedAt": "2026-08-20T10:21:22.767Z",
+      "reviewedBy": "Kinfe123",
+      "reason": "Preserve the curated compacted output that passes the golden-task quality gates: #485/#487 added agent-compact review-workflow coverage to these source pages, and a cloud re-compaction regressed golden tasks from 22/22 to 9/22, so the curated agent.md is kept until the new coverage is folded in by a reviewed curation pass."
+    },
     {
       "route": "/docs/configuration",
-      "sourceHash": "fnv1a64:67d7e2763afbf5a4",
+      "sourceHash": "fnv1a64:036bc04f1a1943f6",
       "settingsHash": "fnv1a64:aa433a28ef4afd1f",
       "outputHash": "fnv1a64:d404f870b0ddaafa",
-      "reviewedAt": "2026-08-14T15:49:25.027Z",
-      "reviewedBy": "farming-labs/docs maintainers",
-      "reason": "Preserve the detailed machine-oriented configuration contract."
+      "reviewedAt": "2026-08-20T10:21:05.808Z",
+      "reviewedBy": "Kinfe123",
+      "reason": "Re-reviewed after #485 documented agent.compact.reviewManifestPath in the source page: the preserved machine-oriented configuration contract covers agent.compact at the defaults level, so its guidance remains correct without enumerating the new option. Hash also shifted because compaction source hashing no longer embeds mtime-derived last_updated dates."
     },
     {
       "route": "/docs/customization/agent-primitive",
-      "sourceHash": "fnv1a64:c8aa1b291752bf79",
+      "sourceHash": "fnv1a64:28b9ad19a979f2f4",
       "settingsHash": "fnv1a64:3fa80ff29bd1598e",
       "outputHash": "fnv1a64:d733ee51a757a5ec",
-      "reviewedAt": "2026-08-14T15:49:27.379Z",
-      "reviewedBy": "farming-labs/docs maintainers",
-      "reason": "Preserve the canonical audience projection, discovery, feedback, and Agent Skills operating guide."
+      "reviewedAt": "2026-08-20T10:21:13.546Z",
+      "reviewedBy": "Kinfe123",
+      "reason": "Re-recorded after compaction source hashing stopped embedding mtime-derived last_updated dates; page sources are unchanged since the 2026-08-14 review, and the intentionally preserved agent.md content (audience projection and Agent Skills guide, operator-only authoring MCP safety guidance, scoped sidebar answer guide) still matches its source."
     },
     {
       "route": "/docs/customization/mcp",
-      "sourceHash": "fnv1a64:120a971d05404387",
+      "sourceHash": "fnv1a64:724e794e76a6d24e",
       "settingsHash": "fnv1a64:4d5874ba9e62babc",
       "outputHash": "fnv1a64:0b4119aece602f67",
-      "reviewedAt": "2026-08-14T15:49:22.702Z",
-      "reviewedBy": "farming-labs/docs maintainers",
-      "reason": "Preserve reviewed operator-only authoring MCP and publishing safety guidance."
+      "reviewedAt": "2026-08-20T10:21:13.548Z",
+      "reviewedBy": "Kinfe123",
+      "reason": "Re-recorded after compaction source hashing stopped embedding mtime-derived last_updated dates; page sources are unchanged since the 2026-08-14 review, and the intentionally preserved agent.md content (audience projection and Agent Skills guide, operator-only authoring MCP safety guidance, scoped sidebar answer guide) still matches its source."
     },
     {
       "route": "/docs/customization/sidebar",
-      "sourceHash": "fnv1a64:4cfd6a1ea869d828",
+      "sourceHash": "fnv1a64:34bc2c22bac145f1",
       "settingsHash": "fnv1a64:063b4c9a14696a17",
       "outputHash": "fnv1a64:b6bb2f7c8d8f3184",
-      "reviewedAt": "2026-08-14T15:49:29.748Z",
-      "reviewedBy": "farming-labs/docs maintainers",
-      "reason": "Preserve the intentionally scoped sidebar answer guide."
+      "reviewedAt": "2026-08-20T10:21:13.549Z",
+      "reviewedBy": "Kinfe123",
+      "reason": "Re-recorded after compaction source hashing stopped embedding mtime-derived last_updated dates; page sources are unchanged since the 2026-08-14 review, and the intentionally preserved agent.md content (audience projection and Agent Skills guide, operator-only authoring MCP safety guidance, scoped sidebar answer guide) still matches its source."
+    },
+    {
+      "route": "/docs/reference",
+      "sourceHash": "fnv1a64:083bdfc462e36413",
+      "settingsHash": "fnv1a64:aa433a28ef4afd1f",
+      "outputHash": "fnv1a64:173fd105503fea58",
+      "reviewedAt": "2026-08-20T10:21:22.777Z",
+      "reviewedBy": "Kinfe123",
+      "reason": "Preserve the curated compacted output that passes the golden-task quality gates: #485/#487 added agent-compact review-workflow coverage to these source pages, and a cloud re-compaction regressed golden tasks from 22/22 to 9/22, so the curated agent.md is kept until the new coverage is folded in by a reviewed curation pass."
+    },
+    {
+      "route": "/docs/token-efficiency",
+      "sourceHash": "fnv1a64:723305a70b3f23f3",
+      "settingsHash": "fnv1a64:72be2461542d7a95",
+      "outputHash": "fnv1a64:d63cfdc9326dd1b7",
+      "reviewedAt": "2026-08-20T10:21:22.778Z",
+      "reviewedBy": "Kinfe123",
+      "reason": "Preserve the curated compacted output that passes the golden-task quality gates: #485/#487 added agent-compact review-workflow coverage to these source pages, and a cloud re-compaction regressed golden tasks from 22/22 to 9/22, so the curated agent.md is kept until the new coverage is folded in by a reviewed curation pass."
     }
   ]
 }
diff --git a/website/app/docs/agent.md b/website/app/docs/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:59c67ee6d2cf86cb
+sourceHash=fnv1a64:f31c3c54e92a6a1e
 settingsHash=fnv1a64:0a67cd1f3384201a
 outputHash=fnv1a64:5a773c15e735f864
-generatedAt=2026-08-14T12:45:38.380Z
+generatedAt=2026-08-20T10:20:45.454Z
 -->
 # Introduction
 

diff --git a/website/app/docs/cli/agent.md b/website/app/docs/cli/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:8474cf95b5a961dd
+sourceHash=fnv1a64:ff98ba0ac661af3e
 settingsHash=fnv1a64:e50e89e221226fc3
 outputHash=fnv1a64:c95a0dd048e26147
-generatedAt=2026-08-14T12:45:38.405Z
+generatedAt=2026-08-20T10:20:45.204Z
 -->
 URL: /docs/cli
 LLM index: /llms.txt

diff --git a/website/app/docs/cloud/agent.md b/website/app/docs/cloud/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:18c7a33ffe5d8ac7
+sourceHash=fnv1a64:ea4599fe0d071f98
 settingsHash=fnv1a64:54aabfe997b31e1c
 outputHash=fnv1a64:3bbb07e4687e854e
-generatedAt=2026-08-14T12:45:38.425Z
+generatedAt=2026-08-20T10:20:45.233Z
 -->
 # Docs Cloud
 

diff --git a/website/app/docs/cloud/analytics/agent.md b/website/app/docs/cloud/analytics/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:6f70f7ff5dd7cacb
+sourceHash=fnv1a64:7034d577d38a7462
 settingsHash=fnv1a64:72be2461542d7a95
 outputHash=fnv1a64:71082a9b0c66a490
-generatedAt=2026-08-14T12:45:38.442Z
+generatedAt=2026-08-20T10:20:45.215Z
 -->
 # Analytics
 

diff --git a/website/app/docs/cloud/deploy/agent.md b/website/app/docs/cloud/deploy/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:71b392aaea120dba
+sourceHash=fnv1a64:21f42c17384037d9
 settingsHash=fnv1a64:063b4c9a14696a17
 outputHash=fnv1a64:c156b3ca29676945
-generatedAt=2026-08-14T12:45:38.462Z
+generatedAt=2026-08-20T10:20:45.224Z
 -->
 # Deploy
 

diff --git a/website/app/docs/contributing/agent.md b/website/app/docs/contributing/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:9d52eda6dbea2d4d
+sourceHash=fnv1a64:b5dc93bd0362d4de
 settingsHash=fnv1a64:b2106dff2d4f1f98
 outputHash=fnv1a64:0ba4aa7e16e15e72
-generatedAt=2026-08-14T12:45:38.478Z
+generatedAt=2026-08-20T10:20:45.259Z
 -->
 # Contributing
 

diff --git a/website/app/docs/customization/agent.md b/website/app/docs/customization/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:96996c56771b9d6e
+sourceHash=fnv1a64:e24affa1d337935b
 settingsHash=fnv1a64:b2106dff2d4f1f98
 outputHash=fnv1a64:14aaecb13600c381
-generatedAt=2026-08-14T12:45:38.496Z
+generatedAt=2026-08-20T10:20:45.362Z
 -->
 # Customization
 

diff --git a/website/app/docs/customization/ai-chat/agent.md b/website/app/docs/customization/ai-chat/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:2f11c9729fea733b
+sourceHash=fnv1a64:90a70f0c0a38a3ce
 settingsHash=fnv1a64:7a85fb928fd52635
 outputHash=fnv1a64:ded084b41bf41852
-generatedAt=2026-08-14T12:45:38.514Z
+generatedAt=2026-08-20T10:20:45.282Z
 -->
 # Ask AI
 

diff --git a/website/app/docs/customization/analytics/agent.md b/website/app/docs/customization/analytics/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:7bbdd54dbf142528
+sourceHash=fnv1a64:1d7dae95f1156a3b
 settingsHash=fnv1a64:72be2461542d7a95
 outputHash=fnv1a64:8dfc9629f7835ae0
-generatedAt=2026-08-14T12:45:38.531Z
+generatedAt=2026-08-20T10:20:45.290Z
 -->
 # Analytics
 

diff --git a/website/app/docs/customization/colors/agent.md b/website/app/docs/customization/colors/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:c961ad4ca8c68060
+sourceHash=fnv1a64:868072b335139257
 settingsHash=fnv1a64:b2106dff2d4f1f98
 outputHash=fnv1a64:3ef315ed2e252ae5
-generatedAt=2026-08-14T12:45:38.549Z
+generatedAt=2026-08-20T10:20:45.296Z
 -->
 # Colors
 

diff --git a/website/app/docs/customization/components/agent.md b/website/app/docs/customization/components/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:a6c99c7c5dd5505d
+sourceHash=fnv1a64:5c3143c5a326a02e
 settingsHash=fnv1a64:063b4c9a14696a17
 outputHash=fnv1a64:359366d4cee9d620
-generatedAt=2026-08-14T12:45:38.567Z
+generatedAt=2026-08-20T10:20:45.310Z
 -->
 # Components
 

diff --git a/website/app/docs/customization/llms-txt/agent.md b/website/app/docs/customization/llms-txt/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:16f85bc74cf45618
+sourceHash=fnv1a64:575801915b4e04d5
 settingsHash=fnv1a64:3fa80ff29bd1598e
 outputHash=fnv1a64:34ab5873e4b3807d
-generatedAt=2026-08-14T12:45:38.585Z
+generatedAt=2026-08-20T10:20:45.323Z
 -->
 # llms.txt
 

diff --git a/website/app/docs/customization/observability/agent.md b/website/app/docs/customization/observability/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:69c2b01877d26ee6
+sourceHash=fnv1a64:9d3948c775786cbd
 settingsHash=fnv1a64:72be2461542d7a95
 outputHash=fnv1a64:5a926dd8952106a9
-generatedAt=2026-08-14T12:45:38.600Z
+generatedAt=2026-08-20T10:20:45.332Z
 -->
 # Observability
 

diff --git a/website/app/docs/customization/og-images/agent.md b/website/app/docs/customization/og-images/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:a1b9c8598c9c6647
+sourceHash=fnv1a64:6fa5aff3470aecd8
 settingsHash=fnv1a64:1b5212557ba75927
 outputHash=fnv1a64:7df800a8c45ebe93
-generatedAt=2026-08-14T12:45:38.615Z
+generatedAt=2026-08-20T10:20:45.344Z
 -->
 # OG Images
 

diff --git a/website/app/docs/customization/page-actions/agent.md b/website/app/docs/customization/page-actions/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:f232a73ce7fd95a0
+sourceHash=fnv1a64:f58201f70663f345
 settingsHash=fnv1a64:72be2461542d7a95
 outputHash=fnv1a64:64fef2cb27439f75
-generatedAt=2026-08-14T12:45:38.632Z
+generatedAt=2026-08-20T10:20:45.354Z
 -->
 # Page Actions
 

diff --git a/website/app/docs/customization/sitemaps/agent.md b/website/app/docs/customization/sitemaps/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:3cd93ebac6b64e23
+sourceHash=fnv1a64:c75827353d89371c
 settingsHash=fnv1a64:0a67cd1f3384201a
 outputHash=fnv1a64:3255515be7b4e3ee
-generatedAt=2026-08-14T12:45:38.649Z
+generatedAt=2026-08-20T10:20:45.376Z
 -->
 # Sitemaps
 

diff --git a/website/app/docs/customization/telemetry/agent.md b/website/app/docs/customization/telemetry/agent.md
@@ -1,10 +1,10 @@
 <!-- @farming-labs/docs:generated
 version=1
 sourceKind=resolved-page
-sourceHash=fnv1a64:b3153c6a1e416385
+sourceHash=fnv1a64:27054689be801ecc
 settingsHash=fnv1a64:b2106dff2d4f1f98
 outputHash=fnv1a64:aad652137c192ee9
-generatedAt=2026-08-14T12:45:38.665Z
+generatedAt=2026-08-20T10:20:45.382Z
 -->
 # Telemetry