@gethmy/mcp 2.1.0 → 2.1.1

package/README.md

@@ -20,6 +20,11 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor, Windsurf) to intera
 - **Smart Setup** - one command configures everything
 - **API Key Authentication** - no database credentials required
 
+## Prerequisites
+
+- [Node.js](https://nodejs.org) >= 20 or [Bun](https://bun.sh) >= 1.0
+- A [Harmony](https://gethmy.com) account with an API key
+
 ## Quick Start
 
 ### 1. Get an API Key

package/dist/cli.js

@@ -26301,6 +26301,8 @@ class HarmonyApiClient {
       params.set("summary", "true");
     if (options?.includeArchived)
       params.set("include_archived", "true");
+    if (options?.labelName)
+      params.set("label_name", options.labelName);
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `/board/${projectId}${query}`);
   }
@@ -31520,13 +31522,8 @@ function detectAgents(cwd = process.cwd()) {
 }
 
 // src/tui/docs.ts
-import {
-  existsSync as existsSync4,
-  readFileSync as readFileSync3,
-  readdirSync as readdirSync2,
-  statSync
-} from "node:fs";
-import { join as join4 } from "node:path";
+import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync } from "node:fs";
+import { isAbsolute, join as join4, resolve, sep as sep2 } from "node:path";
 
 // src/tui/theme.ts
 var pc = __toESM(require_picocolors(), 1);
@@ -31932,16 +31929,52 @@ function generateArchitectureMd(info, _cwd) {
   return lines.join(`
 `);
 }
+var VAGUE_STANDARDS = [
+  "follow best practices",
+  "use best practices",
+  "keep it clean",
+  "write clean code",
+  "maintain code quality",
+  "ensure quality",
+  "use proper naming",
+  "follow conventions",
+  "be consistent"
+];
 function verifyDocs(cwd) {
   const issues = [];
   const claudeMd = readText(join4(cwd, "CLAUDE.md"));
+  const agentsMd = readText(join4(cwd, "AGENTS.md"));
+  const pkg = readJson(join4(cwd, "package.json"));
+  const pkgScripts = pkg && typeof pkg.scripts === "object" && pkg.scripts !== null ? pkg.scripts : {};
+  const projectRoot = resolve(cwd);
   if (claudeMd) {
+    const importedFiles = [];
     for (const line of claudeMd.split(`
 `)) {
       const match = line.match(/^@(.+)$/);
       if (match) {
         const refPath = match[1].trim();
-        if (!existsSync4(join4(cwd, refPath))) {
+        if (isAbsolute(refPath)) {
+          issues.push({
+            severity: "error",
+            file: "CLAUDE.md",
+            message: `@ reference uses an absolute path: ${refPath}`,
+            fix: "Use a project-relative path under the repository root"
+          });
+          continue;
+        }
+        const resolvedPath = resolve(projectRoot, refPath);
+        if (resolvedPath !== projectRoot && !resolvedPath.startsWith(projectRoot + sep2)) {
+          issues.push({
+            severity: "error",
+            file: "CLAUDE.md",
+            message: `@ reference escapes project root: ${refPath}`,
+            fix: "Remove traversal segments (../) and keep references inside the repo"
+          });
+          continue;
+        }
+        importedFiles.push({ ref: refPath, resolved: resolvedPath });
+        if (!existsSync4(resolvedPath)) {
           issues.push({
             severity: "error",
             file: "CLAUDE.md",
@@ -31951,11 +31984,72 @@ function verifyDocs(cwd) {
         }
       }
     }
+    const claudeLines = claudeMd.split(`
+`).length;
+    if (claudeLines > 100) {
+      issues.push({
+        severity: "warning",
+        file: "CLAUDE.md",
+        message: `CLAUDE.md is ${claudeLines} lines (recommended: under 100)`,
+        fix: "Move detailed content to AGENTS.md or docs/ files and use @imports"
+      });
+    }
+    if (importedFiles.length > 0) {
+      const claudeHeadings = extractHeadings(claudeMd);
+      for (const { ref: refPath, resolved: resolvedPath } of importedFiles) {
+        const refContent = readText(resolvedPath);
+        if (!refContent)
+          continue;
+        const refHeadings = extractHeadings(refContent);
+        for (const heading of claudeHeadings) {
+          if (refHeadings.has(heading)) {
+            issues.push({
+              severity: "warning",
+              file: "CLAUDE.md",
+              message: `Section "${heading}" duplicates content from @${refPath}`,
+              fix: `Remove the "${heading}" section — it's already included via @import`
+            });
+          }
+        }
+      }
+    }
   }
-  const agentsMd = readText(join4(cwd, "AGENTS.md"));
-  const pkg = readJson(join4(cwd, "package.json"));
-  const pkgScripts = pkg && typeof pkg.scripts === "object" && pkg.scripts !== null ? pkg.scripts : {};
   if (agentsMd) {
+    const agentsLines = agentsMd.split(`
+`);
+    const contextLines = [];
+    let pastFirstHeading = false;
+    let hitNextSection = false;
+    for (const line of agentsLines) {
+      if (!pastFirstHeading) {
+        if (line.startsWith("# ")) {
+          pastFirstHeading = true;
+        }
+        continue;
+      }
+      if (line.startsWith("## ")) {
+        hitNextSection = true;
+        break;
+      }
+      const trimmed = line.trim();
+      if (trimmed)
+        contextLines.push(trimmed);
+    }
+    if (pastFirstHeading && !hitNextSection && contextLines.length === 0) {
+      issues.push({
+        severity: "warning",
+        file: "AGENTS.md",
+        message: "Missing project context line after the title heading",
+        fix: "Add a single-line description: stack + what the project does"
+      });
+    } else if (contextLines.length > 1) {
+      issues.push({
+        severity: "warning",
+        file: "AGENTS.md",
+        message: `Project context should be exactly 1 line, found ${contextLines.length}`,
+        fix: "Condense to a single line: stack + what the project does"
+      });
+    }
     const codeBlockRe = /```[\s\S]*?```/g;
     let blockMatch;
     while ((blockMatch = codeBlockRe.exec(agentsMd)) !== null) {
@@ -31964,7 +32058,16 @@ function verifyDocs(cwd) {
       let cmdMatch;
       while ((cmdMatch = cmdRe.exec(block)) !== null) {
         const scriptName = cmdMatch[1];
-        const builtins = new Set(["install", "init", "create", "exec", "dlx", "x", "test", "start"]);
+        const builtins = new Set([
+          "install",
+          "init",
+          "create",
+          "exec",
+          "dlx",
+          "x",
+          "test",
+          "start"
+        ]);
         if (builtins.has(scriptName))
           continue;
         if (Object.keys(pkgScripts).length > 0 && !(scriptName in pkgScripts)) {
@@ -31977,6 +32080,34 @@ function verifyDocs(cwd) {
         }
       }
     }
+    const standardsSection = extractSection(agentsMd, "Code Standards");
+    if (standardsSection) {
+      const lower = standardsSection.toLowerCase();
+      for (const phrase of VAGUE_STANDARDS) {
+        if (lower.includes(phrase)) {
+          issues.push({
+            severity: "warning",
+            file: "AGENTS.md",
+            message: `Code Standards contains vague phrase: "${phrase}"`,
+            fix: "Replace with specific, verifiable conventions derived from config files"
+          });
+        }
+      }
+    }
+    if (Object.keys(pkgScripts).length > 0) {
+      const hasTestScript = Object.keys(pkgScripts).some((k3) => k3 === "test" || k3.startsWith("test:"));
+      if (!hasTestScript) {
+        const mentionsNoTest = agentsMd.toLowerCase().includes("no test");
+        if (!mentionsNoTest) {
+          issues.push({
+            severity: "warning",
+            file: "AGENTS.md",
+            message: "No test script in package.json and AGENTS.md doesn't mention it",
+            fix: 'Add a note like "No test framework. Verify changes with `bun run build`."'
+          });
+        }
+      }
+    }
     checkBacktickPaths(agentsMd, "AGENTS.md", cwd, issues);
   }
   const archMd = readText(join4(cwd, "docs", "architecture.md"));
@@ -31985,16 +32116,48 @@ function verifyDocs(cwd) {
   }
   return issues;
 }
+function extractHeadings(content) {
+  const headings = new Set;
+  for (const line of content.split(`
+`)) {
+    const match = line.match(/^#{2,3}\s+(.+)$/);
+    if (match) {
+      headings.add(match[1].trim());
+    }
+  }
+  return headings;
+}
+function extractSection(content, heading) {
+  const lines = content.split(`
+`);
+  let capturing = false;
+  const result = [];
+  for (const line of lines) {
+    if (capturing) {
+      if (line.match(/^#{1,2}\s/))
+        break;
+      result.push(line);
+    } else if (line.match(new RegExp(`^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "i"))) {
+      capturing = true;
+    }
+  }
+  return result.length > 0 ? result.join(`
+`) : null;
+}
 function checkBacktickPaths(content, file2, cwd, issues) {
   const pathRe = /`((?:src\/|packages\/|apps\/|supabase\/|docs\/)[^`]+)`/g;
   let match;
   const checked = new Set;
+  const root = resolve(cwd);
   while ((match = pathRe.exec(content)) !== null) {
     const refPath = match[1].replace(/\/$/, "");
     if (checked.has(refPath))
       continue;
     checked.add(refPath);
-    if (!existsSync4(join4(cwd, refPath))) {
+    const resolvedRef = resolve(root, refPath);
+    if (resolvedRef !== root && !resolvedRef.startsWith(root + sep2))
+      continue;
+    if (!existsSync4(resolvedRef)) {
       issues.push({
         severity: "warning",
         file: file2,
@@ -32194,7 +32357,7 @@ async function writeFilesWithProgress(files, options = {}) {
       result = writeFile(file2.path, file2.content, options);
     }
     results.push(result);
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await new Promise((resolve2) => setTimeout(resolve2, 50));
   }
   spinner.stop("Files written");
   for (const result of results) {

package/dist/index.js

@@ -24061,6 +24061,8 @@ class HarmonyApiClient {
       params.set("summary", "true");
     if (options?.includeArchived)
       params.set("include_archived", "true");
+    if (options?.labelName)
+      params.set("label_name", options.labelName);
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `/board/${projectId}${query}`);
   }

package/dist/lib/api-client.js

@@ -221,6 +221,8 @@ export class HarmonyApiClient {
             params.set("summary", "true");
         if (options?.includeArchived)
             params.set("include_archived", "true");
+        if (options?.labelName)
+            params.set("label_name", options.labelName);
         const query = params.toString() ? `?${params.toString()}` : "";
         return this.request("GET", `/board/${projectId}${query}`);
     }

package/dist/lib/tui/docs.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, readdirSync, statSync, } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
 import * as p from "@clack/prompts";
 import { colors, symbols } from "./theme.js";
 // ── Helpers ─────────────────────────────────────────────────────────────────
@@ -141,8 +141,12 @@ export function scanProject(cwd) {
     let framework = null;
     if (pkg) {
         const deps = {
-            ...(typeof pkg.dependencies === "object" ? pkg.dependencies : {}),
-            ...(typeof pkg.devDependencies === "object" ? pkg.devDependencies : {}),
+            ...(typeof pkg.dependencies === "object"
+                ? pkg.dependencies
+                : {}),
+            ...(typeof pkg.devDependencies === "object"
+                ? pkg.devDependencies
+                : {}),
         };
         if (deps.next) {
             framework = "next";
@@ -305,7 +309,11 @@ function describeScript(name) {
  * Generate a scaffold AGENTS.md from project metadata.
  */
 export function generateAgentsMd(info, _cwd) {
-    const lang = info.language === "typescript" ? "TypeScript" : info.language === "javascript" ? "JavaScript" : info.language;
+    const lang = info.language === "typescript"
+        ? "TypeScript"
+        : info.language === "javascript"
+            ? "JavaScript"
+            : info.language;
     const frameworkLabel = info.framework ? `${info.framework} ` : "";
     const monoLabel = info.monorepo ? " (monorepo)" : "";
     const lines = [];
@@ -404,19 +412,63 @@ export function generateArchitectureMd(info, _cwd) {
     return lines.join("\n");
 }
 // ── Verification ────────────────────────────────────────────────────────────
+/** Vague phrases that provide no actionable guidance to agents. */
+const VAGUE_STANDARDS = [
+    "follow best practices",
+    "use best practices",
+    "keep it clean",
+    "write clean code",
+    "maintain code quality",
+    "ensure quality",
+    "use proper naming",
+    "follow conventions",
+    "be consistent",
+];
 /**
- * Verify existing docs for broken references, stale commands, and dead paths.
+ * Verify existing docs for broken references, stale commands, dead paths,
+ * and structural quality issues from the setup-agent-docs quality checks.
  */
 export function verifyDocs(cwd) {
     const issues = [];
-    // 1. CLAUDE.md — check @-references
     const claudeMd = readText(join(cwd, "CLAUDE.md"));
+    const agentsMd = readText(join(cwd, "AGENTS.md"));
+    const pkg = readJson(join(cwd, "package.json"));
+    const pkgScripts = pkg && typeof pkg.scripts === "object" && pkg.scripts !== null
+        ? pkg.scripts
+        : {};
+    // ── CLAUDE.md checks ──────────────────────────────────────────────────
+    const projectRoot = resolve(cwd);
     if (claudeMd) {
+        // Check @-references exist on disk (with path traversal protection)
+        const importedFiles = [];
         for (const line of claudeMd.split("\n")) {
             const match = line.match(/^@(.+)$/);
             if (match) {
                 const refPath = match[1].trim();
-                if (!existsSync(join(cwd, refPath))) {
+                // Reject absolute paths
+                if (isAbsolute(refPath)) {
+                    issues.push({
+                        severity: "error",
+                        file: "CLAUDE.md",
+                        message: `@ reference uses an absolute path: ${refPath}`,
+                        fix: "Use a project-relative path under the repository root",
+                    });
+                    continue;
+                }
+                // Resolve and ensure the path stays inside the project root
+                const resolvedPath = resolve(projectRoot, refPath);
+                if (resolvedPath !== projectRoot &&
+                    !resolvedPath.startsWith(projectRoot + sep)) {
+                    issues.push({
+                        severity: "error",
+                        file: "CLAUDE.md",
+                        message: `@ reference escapes project root: ${refPath}`,
+                        fix: "Remove traversal segments (../) and keep references inside the repo",
+                    });
+                    continue;
+                }
+                importedFiles.push({ ref: refPath, resolved: resolvedPath });
+                if (!existsSync(resolvedPath)) {
                     issues.push({
                         severity: "error",
                         file: "CLAUDE.md",
@@ -426,26 +478,96 @@ export function verifyDocs(cwd) {
                 }
             }
         }
+        // Line count — CLAUDE.md should be under 100 lines (lean, @imports only)
+        const claudeLines = claudeMd.split("\n").length;
+        if (claudeLines > 100) {
+            issues.push({
+                severity: "warning",
+                file: "CLAUDE.md",
+                message: `CLAUDE.md is ${claudeLines} lines (recommended: under 100)`,
+                fix: "Move detailed content to AGENTS.md or docs/ files and use @imports",
+            });
+        }
+        // Duplication — check if CLAUDE.md duplicates content from imported files
+        if (importedFiles.length > 0) {
+            const claudeHeadings = extractHeadings(claudeMd);
+            for (const { ref: refPath, resolved: resolvedPath } of importedFiles) {
+                const refContent = readText(resolvedPath);
+                if (!refContent)
+                    continue;
+                const refHeadings = extractHeadings(refContent);
+                // Flag if CLAUDE.md repeats section headings from imported files
+                for (const heading of claudeHeadings) {
+                    if (refHeadings.has(heading)) {
+                        issues.push({
+                            severity: "warning",
+                            file: "CLAUDE.md",
+                            message: `Section "${heading}" duplicates content from @${refPath}`,
+                            fix: `Remove the "${heading}" section — it's already included via @import`,
+                        });
+                    }
+                }
+            }
+        }
     }
-    // 2. AGENTS.md — check commands against package.json scripts
-    const agentsMd = readText(join(cwd, "AGENTS.md"));
-    const pkg = readJson(join(cwd, "package.json"));
-    const pkgScripts = pkg && typeof pkg.scripts === "object" && pkg.scripts !== null
-        ? pkg.scripts
-        : {};
+    // ── AGENTS.md checks ──────────────────────────────────────────────────
     if (agentsMd) {
-        // Extract commands from code blocks
+        // Project Context — first non-heading, non-blank line should be exactly one line
+        const agentsLines = agentsMd.split("\n");
+        const contextLines = [];
+        let pastFirstHeading = false;
+        let hitNextSection = false;
+        for (const line of agentsLines) {
+            if (!pastFirstHeading) {
+                if (line.startsWith("# ")) {
+                    pastFirstHeading = true;
+                }
+                continue;
+            }
+            // Stop at next ## heading
+            if (line.startsWith("## ")) {
+                hitNextSection = true;
+                break;
+            }
+            const trimmed = line.trim();
+            if (trimmed)
+                contextLines.push(trimmed);
+        }
+        if (pastFirstHeading && !hitNextSection && contextLines.length === 0) {
+            issues.push({
+                severity: "warning",
+                file: "AGENTS.md",
+                message: "Missing project context line after the title heading",
+                fix: "Add a single-line description: stack + what the project does",
+            });
+        }
+        else if (contextLines.length > 1) {
+            issues.push({
+                severity: "warning",
+                file: "AGENTS.md",
+                message: `Project context should be exactly 1 line, found ${contextLines.length}`,
+                fix: "Condense to a single line: stack + what the project does",
+            });
+        }
+        // Commands — check against package.json scripts
         const codeBlockRe = /```[\s\S]*?```/g;
         let blockMatch;
         while ((blockMatch = codeBlockRe.exec(agentsMd)) !== null) {
             const block = blockMatch[0];
-            // Match lines that look like package manager commands
             const cmdRe = /(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?(\S+)/g;
             let cmdMatch;
             while ((cmdMatch = cmdRe.exec(block)) !== null) {
                 const scriptName = cmdMatch[1];
-                // Skip if the script name is a built-in (install, init, etc.)
-                const builtins = new Set(["install", "init", "create", "exec", "dlx", "x", "test", "start"]);
+                const builtins = new Set([
+                    "install",
+                    "init",
+                    "create",
+                    "exec",
+                    "dlx",
+                    "x",
+                    "test",
+                    "start",
+                ]);
                 if (builtins.has(scriptName))
                     continue;
                 if (Object.keys(pkgScripts).length > 0 && !(scriptName in pkgScripts)) {
@@ -458,27 +580,91 @@ export function verifyDocs(cwd) {
                 }
             }
         }
-        // 3. Check backtick-quoted paths in AGENTS.md
+        // Code Standards — flag vague, non-actionable phrases
+        const standardsSection = extractSection(agentsMd, "Code Standards");
+        if (standardsSection) {
+            const lower = standardsSection.toLowerCase();
+            for (const phrase of VAGUE_STANDARDS) {
+                if (lower.includes(phrase)) {
+                    issues.push({
+                        severity: "warning",
+                        file: "AGENTS.md",
+                        message: `Code Standards contains vague phrase: "${phrase}"`,
+                        fix: "Replace with specific, verifiable conventions derived from config files",
+                    });
+                }
+            }
+        }
+        // Missing test command — if no test script exists, AGENTS.md should say so
+        if (Object.keys(pkgScripts).length > 0) {
+            const hasTestScript = Object.keys(pkgScripts).some((k) => k === "test" || k.startsWith("test:"));
+            if (!hasTestScript) {
+                const mentionsNoTest = agentsMd.toLowerCase().includes("no test");
+                if (!mentionsNoTest) {
+                    issues.push({
+                        severity: "warning",
+                        file: "AGENTS.md",
+                        message: "No test script in package.json and AGENTS.md doesn't mention it",
+                        fix: 'Add a note like "No test framework. Verify changes with `bun run build`."',
+                    });
+                }
+            }
+        }
+        // Check backtick-quoted paths
         checkBacktickPaths(agentsMd, "AGENTS.md", cwd, issues);
     }
-    // 3b. Check backtick-quoted paths in docs/architecture.md
+    // ── docs/architecture.md checks ───────────────────────────────────────
     const archMd = readText(join(cwd, "docs", "architecture.md"));
     if (archMd) {
         checkBacktickPaths(archMd, "docs/architecture.md", cwd, issues);
     }
     return issues;
 }
+/** Extract ## headings from markdown content. */
+function extractHeadings(content) {
+    const headings = new Set();
+    for (const line of content.split("\n")) {
+        const match = line.match(/^#{2,3}\s+(.+)$/);
+        if (match) {
+            headings.add(match[1].trim());
+        }
+    }
+    return headings;
+}
+/** Extract content under a specific ## section heading. */
+function extractSection(content, heading) {
+    const lines = content.split("\n");
+    let capturing = false;
+    const result = [];
+    for (const line of lines) {
+        if (capturing) {
+            // Stop at next ## heading
+            if (line.match(/^#{1,2}\s/))
+                break;
+            result.push(line);
+        }
+        else if (line.match(new RegExp(`^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "i"))) {
+            capturing = true;
+        }
+    }
+    return result.length > 0 ? result.join("\n") : null;
+}
 /** Scan markdown for backtick-quoted paths and check they exist. */
 function checkBacktickPaths(content, file, cwd, issues) {
     const pathRe = /`((?:src\/|packages\/|apps\/|supabase\/|docs\/)[^`]+)`/g;
     let match;
     const checked = new Set();
+    const root = resolve(cwd);
     while ((match = pathRe.exec(content)) !== null) {
         const refPath = match[1].replace(/\/$/, ""); // strip trailing slash
         if (checked.has(refPath))
             continue;
         checked.add(refPath);
-        if (!existsSync(join(cwd, refPath))) {
+        // Skip paths that escape the project root (e.g. src/../../etc/hosts)
+        const resolvedRef = resolve(root, refPath);
+        if (resolvedRef !== root && !resolvedRef.startsWith(root + sep))
+            continue;
+        if (!existsSync(resolvedRef)) {
             issues.push({
                 severity: "warning",
                 file,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -46,7 +46,8 @@
     "coding-assistant"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0",
+    "bun": ">=1.0.0"
   },
   "scripts": {
     "build": "bun build src/index.ts src/cli.ts --outdir dist --target node && tsc --outDir dist/lib --declaration false --skipLibCheck --noCheck",
@@ -68,7 +69,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^25.2.0",
-    "typescript": "^5.9.3"
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.1"
   }
 }

package/src/api-client.ts

@@ -286,6 +286,7 @@ export class HarmonyApiClient {
       columnId?: string;
       summary?: boolean;
       includeArchived?: boolean;
+      labelName?: string;
     },
   ): Promise<{
     project: unknown;
@@ -309,6 +310,7 @@ export class HarmonyApiClient {
     if (options?.columnId) params.set("column_id", options.columnId);
     if (options?.summary) params.set("summary", "true");
     if (options?.includeArchived) params.set("include_archived", "true");
+    if (options?.labelName) params.set("label_name", options.labelName);
 
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `/board/${projectId}${query}`);
@@ -497,6 +499,10 @@ export class HarmonyApiClient {
       currentTask?: string;
       blockers?: string[];
       estimatedMinutesRemaining?: number;
+      phase?: string;
+      filesChanged?: number;
+      costCents?: number;
+      recentActions?: { action: string; ts: string }[];
     },
   ): Promise<{ session: unknown; created: boolean }> {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);

package/src/tui/docs.ts

@@ -1,10 +1,5 @@
-import {
-  existsSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-} from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
 import * as p from "@clack/prompts";
 import { colors, symbols } from "./theme.js";
 
@@ -182,8 +177,12 @@ export function scanProject(cwd: string): ProjectInfo {
   let framework: string | null = null;
   if (pkg) {
     const deps: Record<string, string> = {
-      ...(typeof pkg.dependencies === "object" ? (pkg.dependencies as Record<string, string>) : {}),
-      ...(typeof pkg.devDependencies === "object" ? (pkg.devDependencies as Record<string, string>) : {}),
+      ...(typeof pkg.dependencies === "object"
+        ? (pkg.dependencies as Record<string, string>)
+        : {}),
+      ...(typeof pkg.devDependencies === "object"
+        ? (pkg.devDependencies as Record<string, string>)
+        : {}),
     };
 
     if (deps.next) {
@@ -347,7 +346,12 @@ function describeScript(name: string): string {
  * Generate a scaffold AGENTS.md from project metadata.
  */
 export function generateAgentsMd(info: ProjectInfo, _cwd: string): string {
-  const lang = info.language === "typescript" ? "TypeScript" : info.language === "javascript" ? "JavaScript" : info.language;
+  const lang =
+    info.language === "typescript"
+      ? "TypeScript"
+      : info.language === "javascript"
+        ? "JavaScript"
+        : info.language;
   const frameworkLabel = info.framework ? `${info.framework} ` : "";
   const monoLabel = info.monorepo ? " (monorepo)" : "";
 
@@ -388,7 +392,8 @@ export function generateAgentsMd(info: ProjectInfo, _cwd: string): string {
   lines.push("## Code Standards");
   lines.push("");
 
-  const langLabel = info.language === "typescript" ? "TypeScript" : "JavaScript";
+  const langLabel =
+    info.language === "typescript" ? "TypeScript" : "JavaScript";
   if (info.language === "typescript" || info.language === "javascript") {
     lines.push(`- ${langLabel} with ES modules`);
   }
@@ -442,7 +447,10 @@ export function generateClaudeMd(info: ProjectInfo): string {
 /**
  * Generate an architecture.md scaffold.
  */
-export function generateArchitectureMd(info: ProjectInfo, _cwd: string): string {
+export function generateArchitectureMd(
+  info: ProjectInfo,
+  _cwd: string,
+): string {
   const lines: string[] = [];
   lines.push("# Architecture");
   lines.push("");
@@ -468,20 +476,74 @@ export function generateArchitectureMd(info: ProjectInfo, _cwd: string): string
 
 // ── Verification ────────────────────────────────────────────────────────────
 
+/** Vague phrases that provide no actionable guidance to agents. */
+const VAGUE_STANDARDS = [
+  "follow best practices",
+  "use best practices",
+  "keep it clean",
+  "write clean code",
+  "maintain code quality",
+  "ensure quality",
+  "use proper naming",
+  "follow conventions",
+  "be consistent",
+];
+
 /**
- * Verify existing docs for broken references, stale commands, and dead paths.
+ * Verify existing docs for broken references, stale commands, dead paths,
+ * and structural quality issues from the setup-agent-docs quality checks.
  */
 export function verifyDocs(cwd: string): DocsIssue[] {
   const issues: DocsIssue[] = [];
 
-  // 1. CLAUDE.md — check @-references
   const claudeMd = readText(join(cwd, "CLAUDE.md"));
+  const agentsMd = readText(join(cwd, "AGENTS.md"));
+  const pkg = readJson(join(cwd, "package.json"));
+  const pkgScripts =
+    pkg && typeof pkg.scripts === "object" && pkg.scripts !== null
+      ? (pkg.scripts as Record<string, string>)
+      : {};
+
+  // ── CLAUDE.md checks ──────────────────────────────────────────────────
+
+  const projectRoot = resolve(cwd);
+
   if (claudeMd) {
+    // Check @-references exist on disk (with path traversal protection)
+    const importedFiles: { ref: string; resolved: string }[] = [];
     for (const line of claudeMd.split("\n")) {
       const match = line.match(/^@(.+)$/);
       if (match) {
         const refPath = match[1].trim();
-        if (!existsSync(join(cwd, refPath))) {
+
+        // Reject absolute paths
+        if (isAbsolute(refPath)) {
+          issues.push({
+            severity: "error",
+            file: "CLAUDE.md",
+            message: `@ reference uses an absolute path: ${refPath}`,
+            fix: "Use a project-relative path under the repository root",
+          });
+          continue;
+        }
+
+        // Resolve and ensure the path stays inside the project root
+        const resolvedPath = resolve(projectRoot, refPath);
+        if (
+          resolvedPath !== projectRoot &&
+          !resolvedPath.startsWith(projectRoot + sep)
+        ) {
+          issues.push({
+            severity: "error",
+            file: "CLAUDE.md",
+            message: `@ reference escapes project root: ${refPath}`,
+            fix: "Remove traversal segments (../) and keep references inside the repo",
+          });
+          continue;
+        }
+
+        importedFiles.push({ ref: refPath, resolved: resolvedPath });
+        if (!existsSync(resolvedPath)) {
           issues.push({
             severity: "error",
             file: "CLAUDE.md",
@@ -491,28 +553,99 @@ export function verifyDocs(cwd: string): DocsIssue[] {
         }
       }
     }
+
+    // Line count — CLAUDE.md should be under 100 lines (lean, @imports only)
+    const claudeLines = claudeMd.split("\n").length;
+    if (claudeLines > 100) {
+      issues.push({
+        severity: "warning",
+        file: "CLAUDE.md",
+        message: `CLAUDE.md is ${claudeLines} lines (recommended: under 100)`,
+        fix: "Move detailed content to AGENTS.md or docs/ files and use @imports",
+      });
+    }
+
+    // Duplication — check if CLAUDE.md duplicates content from imported files
+    if (importedFiles.length > 0) {
+      const claudeHeadings = extractHeadings(claudeMd);
+      for (const { ref: refPath, resolved: resolvedPath } of importedFiles) {
+        const refContent = readText(resolvedPath);
+        if (!refContent) continue;
+        const refHeadings = extractHeadings(refContent);
+        // Flag if CLAUDE.md repeats section headings from imported files
+        for (const heading of claudeHeadings) {
+          if (refHeadings.has(heading)) {
+            issues.push({
+              severity: "warning",
+              file: "CLAUDE.md",
+              message: `Section "${heading}" duplicates content from @${refPath}`,
+              fix: `Remove the "${heading}" section — it's already included via @import`,
+            });
+          }
+        }
+      }
+    }
   }
 
-  // 2. AGENTS.md — check commands against package.json scripts
-  const agentsMd = readText(join(cwd, "AGENTS.md"));
-  const pkg = readJson(join(cwd, "package.json"));
-  const pkgScripts = pkg && typeof pkg.scripts === "object" && pkg.scripts !== null
-    ? (pkg.scripts as Record<string, string>)
-    : {};
+  // ── AGENTS.md checks ──────────────────────────────────────────────────
 
   if (agentsMd) {
-    // Extract commands from code blocks
+    // Project Context — first non-heading, non-blank line should be exactly one line
+    const agentsLines = agentsMd.split("\n");
+    const contextLines: string[] = [];
+    let pastFirstHeading = false;
+    let hitNextSection = false;
+    for (const line of agentsLines) {
+      if (!pastFirstHeading) {
+        if (line.startsWith("# ")) {
+          pastFirstHeading = true;
+        }
+        continue;
+      }
+      // Stop at next ## heading
+      if (line.startsWith("## ")) {
+        hitNextSection = true;
+        break;
+      }
+      const trimmed = line.trim();
+      if (trimmed) contextLines.push(trimmed);
+    }
+
+    if (pastFirstHeading && !hitNextSection && contextLines.length === 0) {
+      issues.push({
+        severity: "warning",
+        file: "AGENTS.md",
+        message: "Missing project context line after the title heading",
+        fix: "Add a single-line description: stack + what the project does",
+      });
+    } else if (contextLines.length > 1) {
+      issues.push({
+        severity: "warning",
+        file: "AGENTS.md",
+        message: `Project context should be exactly 1 line, found ${contextLines.length}`,
+        fix: "Condense to a single line: stack + what the project does",
+      });
+    }
+
+    // Commands — check against package.json scripts
     const codeBlockRe = /```[\s\S]*?```/g;
     let blockMatch: RegExpExecArray | null;
     while ((blockMatch = codeBlockRe.exec(agentsMd)) !== null) {
       const block = blockMatch[0];
-      // Match lines that look like package manager commands
       const cmdRe = /(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?(\S+)/g;
       let cmdMatch: RegExpExecArray | null;
       while ((cmdMatch = cmdRe.exec(block)) !== null) {
         const scriptName = cmdMatch[1];
-        // Skip if the script name is a built-in (install, init, etc.)
-        const builtins = new Set(["install", "init", "create", "exec", "dlx", "x", "test", "start"]);
+        const builtins = new Set([
+          "install",
+          "init",
+          "create",
+          "exec",
+          "dlx",
+          "x",
+          "test",
+          "start",
+        ]);
         if (builtins.has(scriptName)) continue;
         if (Object.keys(pkgScripts).length > 0 && !(scriptName in pkgScripts)) {
           issues.push({
@@ -525,11 +658,47 @@ export function verifyDocs(cwd: string): DocsIssue[] {
       }
     }
 
-    // 3. Check backtick-quoted paths in AGENTS.md
+    // Code Standards — flag vague, non-actionable phrases
+    const standardsSection = extractSection(agentsMd, "Code Standards");
+    if (standardsSection) {
+      const lower = standardsSection.toLowerCase();
+      for (const phrase of VAGUE_STANDARDS) {
+        if (lower.includes(phrase)) {
+          issues.push({
+            severity: "warning",
+            file: "AGENTS.md",
+            message: `Code Standards contains vague phrase: "${phrase}"`,
+            fix: "Replace with specific, verifiable conventions derived from config files",
+          });
+        }
+      }
+    }
+
+    // Missing test command — if no test script exists, AGENTS.md should say so
+    if (Object.keys(pkgScripts).length > 0) {
+      const hasTestScript = Object.keys(pkgScripts).some(
+        (k) => k === "test" || k.startsWith("test:"),
+      );
+      if (!hasTestScript) {
+        const mentionsNoTest = agentsMd.toLowerCase().includes("no test");
+        if (!mentionsNoTest) {
+          issues.push({
+            severity: "warning",
+            file: "AGENTS.md",
+            message:
+              "No test script in package.json and AGENTS.md doesn't mention it",
+            fix: 'Add a note like "No test framework. Verify changes with `bun run build`."',
+          });
+        }
+      }
+    }
+
+    // Check backtick-quoted paths
     checkBacktickPaths(agentsMd, "AGENTS.md", cwd, issues);
   }
 
-  // 3b. Check backtick-quoted paths in docs/architecture.md
+  // ── docs/architecture.md checks ───────────────────────────────────────
+
   const archMd = readText(join(cwd, "docs", "architecture.md"));
   if (archMd) {
     checkBacktickPaths(archMd, "docs/architecture.md", cwd, issues);
@@ -538,6 +707,44 @@ export function verifyDocs(cwd: string): DocsIssue[] {
   return issues;
 }
 
+/** Extract ## headings from markdown content. */
+function extractHeadings(content: string): Set<string> {
+  const headings = new Set<string>();
+  for (const line of content.split("\n")) {
+    const match = line.match(/^#{2,3}\s+(.+)$/);
+    if (match) {
+      headings.add(match[1].trim());
+    }
+  }
+  return headings;
+}
+
+/** Extract content under a specific ## section heading. */
+function extractSection(content: string, heading: string): string | null {
+  const lines = content.split("\n");
+  let capturing = false;
+  const result: string[] = [];
+
+  for (const line of lines) {
+    if (capturing) {
+      // Stop at next ## heading
+      if (line.match(/^#{1,2}\s/)) break;
+      result.push(line);
+    } else if (
+      line.match(
+        new RegExp(
+          `^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+          "i",
+        ),
+      )
+    ) {
+      capturing = true;
+    }
+  }
+
+  return result.length > 0 ? result.join("\n") : null;
+}
+
 /** Scan markdown for backtick-quoted paths and check they exist. */
 function checkBacktickPaths(
   content: string,
@@ -549,12 +756,18 @@ function checkBacktickPaths(
   let match: RegExpExecArray | null;
   const checked = new Set<string>();
 
+  const root = resolve(cwd);
+
   while ((match = pathRe.exec(content)) !== null) {
     const refPath = match[1].replace(/\/$/, ""); // strip trailing slash
     if (checked.has(refPath)) continue;
     checked.add(refPath);
 
-    if (!existsSync(join(cwd, refPath))) {
+    // Skip paths that escape the project root (e.g. src/../../etc/hosts)
+    const resolvedRef = resolve(root, refPath);
+    if (resolvedRef !== root && !resolvedRef.startsWith(root + sep)) continue;
+
+    if (!existsSync(resolvedRef)) {
       issues.push({
         severity: "warning",
         file,