knowns 0.10.6 → 0.11.0

package/dist/index.js

@@ -3316,10 +3316,10 @@ var require_stringify = __commonJS({
       data = Object.assign({}, file3.data, data);
       const open = opts.delimiters[0];
       const close = opts.delimiters[1];
-      const matter12 = engine.stringify(data, options2).trim();
+      const matter16 = engine.stringify(data, options2).trim();
       let buf = "";
-      if (matter12 !== "{}") {
-        buf = newline(open) + newline(matter12) + newline(close);
+      if (matter16 !== "{}") {
+        buf = newline(open) + newline(matter16) + newline(close);
       }
       if (typeof file3.excerpt === "string" && file3.excerpt !== "") {
         if (str2.indexOf(file3.excerpt.trim()) === -1) {
@@ -3425,19 +3425,19 @@ var require_gray_matter = __commonJS({
     var toFile = require_to_file();
     var parse4 = require_parse();
     var utils = require_utils();
-    function matter12(input, options2) {
+    function matter16(input, options2) {
       if (input === "") {
         return { data: {}, content: input, excerpt: "", orig: input };
       }
       let file3 = toFile(input);
-      const cached2 = matter12.cache[file3.content];
+      const cached2 = matter16.cache[file3.content];
       if (!options2) {
         if (cached2) {
           file3 = Object.assign({}, cached2);
           file3.orig = cached2.orig;
           return file3;
         }
-        matter12.cache[file3.content] = file3;
+        matter16.cache[file3.content] = file3;
       }
       return parseMatter(file3, options2);
     }
@@ -3459,7 +3459,7 @@ var require_gray_matter = __commonJS({
       }
       str2 = str2.slice(openLen);
       const len = str2.length;
-      const language = matter12.language(str2, opts);
+      const language = matter16.language(str2, opts);
       if (language.name) {
         file3.language = language.name;
         str2 = str2.slice(language.raw.length);
@@ -3494,24 +3494,24 @@ var require_gray_matter = __commonJS({
       }
       return file3;
     }
-    matter12.engines = engines2;
-    matter12.stringify = function(file3, data, options2) {
-      if (typeof file3 === "string") file3 = matter12(file3, options2);
+    matter16.engines = engines2;
+    matter16.stringify = function(file3, data, options2) {
+      if (typeof file3 === "string") file3 = matter16(file3, options2);
       return stringify(file3, data, options2);
     };
-    matter12.read = function(filepath, options2) {
+    matter16.read = function(filepath, options2) {
       const str2 = fs.readFileSync(filepath, "utf8");
-      const file3 = matter12(str2, options2);
+      const file3 = matter16(str2, options2);
       file3.path = filepath;
       return file3;
     };
-    matter12.test = function(str2, options2) {
+    matter16.test = function(str2, options2) {
       return utils.startsWith(str2, defaults2(options2).delimiters[0]);
     };
-    matter12.language = function(str2, options2) {
+    matter16.language = function(str2, options2) {
       const opts = defaults2(options2);
       const open = opts.delimiters[0];
-      if (matter12.test(str2)) {
+      if (matter16.test(str2)) {
         str2 = str2.slice(open.length);
       }
       const language = str2.slice(0, str2.search(/\r?\n/));
@@ -3520,11 +3520,11 @@ var require_gray_matter = __commonJS({
         name: language ? language.trim() : ""
       };
     };
-    matter12.cache = {};
-    matter12.clearCache = function() {
-      matter12.cache = {};
+    matter16.cache = {};
+    matter16.clearCache = function() {
+      matter16.cache = {};
     };
-    module2.exports = matter12;
+    module2.exports = matter16;
   }
 });
 
@@ -12444,7 +12444,7 @@ var require_no_conflict = __commonJS({
   "node_modules/handlebars/dist/cjs/handlebars/no-conflict.js"(exports2, module2) {
     "use strict";
     exports2.__esModule = true;
-    exports2["default"] = function(Handlebars2) {
+    exports2["default"] = function(Handlebars4) {
       (function() {
         if (typeof globalThis === "object") return;
         Object.prototype.__defineGetter__("__magic__", function() {
@@ -12454,11 +12454,11 @@ var require_no_conflict = __commonJS({
         delete Object.prototype.__magic__;
       })();
       var $Handlebars = globalThis.Handlebars;
-      Handlebars2.noConflict = function() {
-        if (globalThis.Handlebars === Handlebars2) {
+      Handlebars4.noConflict = function() {
+        if (globalThis.Handlebars === Handlebars4) {
           globalThis.Handlebars = $Handlebars;
         }
-        return Handlebars2;
+        return Handlebars4;
       };
     };
     module2.exports = exports2["default"];
@@ -14378,7 +14378,7 @@ var require_util3 = __commonJS({
       return path3;
     }
     exports2.normalize = normalize3;
-    function join43(aRoot, aPath) {
+    function join47(aRoot, aPath) {
       if (aRoot === "") {
         aRoot = ".";
       }
@@ -14410,7 +14410,7 @@ var require_util3 = __commonJS({
       }
       return joined;
     }
-    exports2.join = join43;
+    exports2.join = join47;
     exports2.isAbsolute = function(aPath) {
       return aPath.charAt(0) === "/" || urlRegexp.test(aPath);
     };
@@ -14583,7 +14583,7 @@ var require_util3 = __commonJS({
             parsed.path = parsed.path.substring(0, index + 1);
           }
         }
-        sourceURL = join43(urlGenerate(parsed), sourceURL);
+        sourceURL = join47(urlGenerate(parsed), sourceURL);
       }
       return normalize3(sourceURL);
     }
@@ -36817,7 +36817,7 @@ var require_view = __commonJS({
     var dirname9 = path3.dirname;
     var basename5 = path3.basename;
     var extname = path3.extname;
-    var join43 = path3.join;
+    var join47 = path3.join;
     var resolve3 = path3.resolve;
     module2.exports = View;
     function View(name, options2) {
@@ -36879,12 +36879,12 @@ var require_view = __commonJS({
     };
     View.prototype.resolve = function resolve4(dir, file3) {
       var ext2 = this.ext;
-      var path4 = join43(dir, file3);
+      var path4 = join47(dir, file3);
       var stat5 = tryStat(path4);
       if (stat5 && stat5.isFile()) {
         return path4;
       }
-      path4 = join43(dir, basename5(file3, ext2), "index" + ext2);
+      path4 = join47(dir, basename5(file3, ext2), "index" + ext2);
       stat5 = tryStat(path4);
       if (stat5 && stat5.isFile()) {
         return path4;
@@ -38622,11 +38622,11 @@ var require_router = __commonJS({
     var slice = Array.prototype.slice;
     var flatten = Array.prototype.flat;
     var methods = METHODS.map((method) => method.toLowerCase());
-    module2.exports = Router12;
+    module2.exports = Router13;
     module2.exports.Route = Route;
-    function Router12(options2) {
-      if (!(this instanceof Router12)) {
-        return new Router12(options2);
+    function Router13(options2) {
+      if (!(this instanceof Router13)) {
+        return new Router13(options2);
       }
       const opts = options2 || {};
       function router(req, res, next) {
@@ -38640,9 +38640,9 @@ var require_router = __commonJS({
       router.stack = [];
       return router;
     }
-    Router12.prototype = function() {
+    Router13.prototype = function() {
     };
-    Router12.prototype.param = function param(name, fn) {
+    Router13.prototype.param = function param(name, fn) {
       if (!name) {
         throw new TypeError("argument name is required");
       }
@@ -38662,7 +38662,7 @@ var require_router = __commonJS({
       params.push(fn);
       return this;
     };
-    Router12.prototype.handle = function handle(req, res, callback2) {
+    Router13.prototype.handle = function handle(req, res, callback2) {
       if (!callback2) {
         throw new TypeError("argument callback is required");
       }
@@ -38789,7 +38789,7 @@ var require_router = __commonJS({
         }
       }
     };
-    Router12.prototype.use = function use(handler) {
+    Router13.prototype.use = function use(handler) {
       let offset = 0;
       let path3 = "/";
       if (typeof handler !== "function") {
@@ -38822,7 +38822,7 @@ var require_router = __commonJS({
       }
       return this;
     };
-    Router12.prototype.route = function route(path3) {
+    Router13.prototype.route = function route(path3) {
       const route2 = new Route(path3);
       const layer = new Layer(path3, {
         sensitive: this.caseSensitive,
@@ -38837,7 +38837,7 @@ var require_router = __commonJS({
       return route2;
     };
     methods.concat("all").forEach(function(method) {
-      Router12.prototype[method] = function(path3) {
+      Router13.prototype[method] = function(path3) {
         const route = this.route(path3);
         route[method].apply(route, slice.call(arguments, 1));
         return this;
@@ -39020,7 +39020,7 @@ var require_application = __commonJS({
     var compileTrust = require_utils5().compileTrust;
     var resolve3 = __require("node:path").resolve;
     var once = require_once();
-    var Router12 = require_router();
+    var Router13 = require_router();
     var slice = Array.prototype.slice;
     var flatten = Array.prototype.flat;
     var app = exports2 = module2.exports = {};
@@ -39036,7 +39036,7 @@ var require_application = __commonJS({
         enumerable: true,
         get: function getrouter() {
           if (router === null) {
-            router = new Router12({
+            router = new Router13({
               caseSensitive: this.enabled("case sensitive routing"),
               strict: this.enabled("strict routing")
             });
@@ -40529,7 +40529,7 @@ var require_send = __commonJS({
     var Stream2 = __require("stream");
     var util2 = __require("util");
     var extname = path3.extname;
-    var join43 = path3.join;
+    var join47 = path3.join;
     var normalize3 = path3.normalize;
     var resolve3 = path3.resolve;
     var sep3 = path3.sep;
@@ -40701,7 +40701,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = path4.split(sep3);
-        path4 = normalize3(join43(root, path4));
+        path4 = normalize3(join47(root, path4));
       } else {
         if (UP_PATH_REGEXP.test(path4)) {
           debug('malicious path "%s"', path4);
@@ -40834,7 +40834,7 @@ var require_send = __commonJS({
           if (err) return self.onStatError(err);
           return self.error(404);
         }
-        var p = join43(path4, self._index[i]);
+        var p = join47(path4, self._index[i]);
         debug('stat "%s"', p);
         fs.stat(p, function(err2, stat5) {
           if (err2) return next(err2);
@@ -41574,7 +41574,7 @@ var require_express = __commonJS({
     var EventEmitter2 = __require("node:events").EventEmitter;
     var mixin = require_merge_descriptors();
     var proto2 = require_application();
-    var Router12 = require_router();
+    var Router13 = require_router();
     var req = require_request();
     var res = require_response();
     exports2 = module2.exports = createApplication;
@@ -41596,8 +41596,8 @@ var require_express = __commonJS({
     exports2.application = proto2;
     exports2.request = req;
     exports2.response = res;
-    exports2.Route = Router12.Route;
-    exports2.Router = Router12;
+    exports2.Route = Router13.Route;
+    exports2.Router = Router13;
     exports2.json = bodyParser.json;
     exports2.raw = bodyParser.raw;
     exports2.static = require_serve_static();
@@ -41741,9 +41741,9 @@ async function getImportsWithMetadata(projectRoot) {
   }
   const importsDir = getImportsDir(projectRoot);
   if (existsSync11(importsDir)) {
-    const { readdir: readdir16 } = await import("node:fs/promises");
+    const { readdir: readdir19 } = await import("node:fs/promises");
     try {
-      const entries = await readdir16(importsDir, { withFileTypes: true });
+      const entries = await readdir19(importsDir, { withFileTypes: true });
       for (const entry of entries) {
         if (!entry.isDirectory()) continue;
         if (entry.name.startsWith(".")) continue;
@@ -57595,6 +57595,7 @@ function parseTaskMarkdown(content) {
     assignee: frontmatter.assignee,
     labels: frontmatter.labels || [],
     parent: frontmatter.parent,
+    spec: frontmatter.spec,
     subtasks: [],
     // Will be populated by FileStore
     createdAt: new Date(frontmatter.createdAt),
@@ -57621,6 +57622,7 @@ function serializeTaskMarkdown(task) {
   };
   if (task.assignee) frontmatter.assignee = task.assignee;
   if (task.parent) frontmatter.parent = task.parent;
+  if (task.spec) frontmatter.spec = task.spec;
   let body = "";
   body += `# ${task.title}
 
@@ -58799,42 +58801,39 @@ var {
 var import_prompts = __toESM(require_prompts3(), 1);
 
 // src/codegen/skill-sync.ts
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync2, readdirSync, rmSync } from "node:fs";
 import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname, join as join4 } from "node:path";
 
-// src/instructions/skills/knowns.commit/SKILL.md
-var SKILL_default = '---\nname: knowns.commit\ndescription: Use when committing code changes with proper conventional commit format and verification\n---\n\n# Committing Changes\n\nCreate well-formatted commits following conventional commit standards.\n\n**Announce at start:** "I\'m using the knowns.commit skill to commit changes."\n\n**Core principle:** VERIFY BEFORE COMMITTING - check staged changes, ask for confirmation.\n\n## The Process\n\n### Step 1: Review Staged Changes\n\n```bash\ngit status\ngit diff --staged\n```\n\n### Step 2: Generate Commit Message\n\n**Format:**\n```\n<type>(<scope>): <message>\n\n- Bullet point summarizing change\n- Another point if needed\n```\n\n**Types:**\n\n| Type | Description |\n|------|-------------|\n| `feat` | New feature |\n| `fix` | Bug fix |\n| `docs` | Documentation only |\n| `style` | Formatting, no code change |\n| `refactor` | Code restructure |\n| `perf` | Performance improvement |\n| `test` | Adding tests |\n| `chore` | Maintenance |\n\n**Rules:**\n- Title lowercase, no period, max 50 chars\n- Scope optional but recommended\n- Body explains *why*, not just *what*\n\n### Step 3: Ask for Confirmation\n\nPresent message to user:\n\n```\nReady to commit:\n\nfeat(auth): add JWT token refresh\n\n- Added refresh token endpoint\n- Tokens expire after 1 hour\n\nProceed? (yes/no/edit)\n```\n\n**Wait for user approval.**\n\n### Step 4: Commit\n\n```bash\ngit commit -m "feat(auth): add JWT token refresh\n\n- Added refresh token endpoint\n- Tokens expire after 1 hour"\n```\n\n## Guidelines\n\n- Only commit staged files (don\'t `git add` unless asked)\n- NO "Co-Authored-By" lines\n- NO "Generated with Claude Code" ads\n- Ask before committing, never auto-commit\n\n## Examples\n\n**Good:**\n```\nfeat(api): add user profile endpoint\nfix(auth): handle expired token gracefully\ndocs(readme): update installation steps\n```\n\n**Bad:**\n```\nupdate code          (too vague)\nWIP                  (not ready)\nfix bug              (which bug?)\n```\n\n## Remember\n\n- Review staged changes first\n- Follow conventional format\n- Ask for confirmation\n- Keep messages concise\n';
+// src/instructions/skills/kn:commit/SKILL.md
+var SKILL_default = '---\nname: kn:commit\ndescription: Use when committing code changes with proper conventional commit format and verification\n---\n\n# Committing Changes\n\n**Announce:** "Using kn:commit to commit changes."\n\n**Core principle:** VERIFY BEFORE COMMITTING - check staged changes, ask for confirmation.\n\n## Step 1: Review Staged Changes\n\n```bash\ngit status\ngit diff --staged\n```\n\n## Step 2: Generate Commit Message\n\n**Format:**\n```\n<type>(<scope>): <message>\n\n- Bullet point summarizing change\n```\n\n**Types:** feat, fix, docs, style, refactor, perf, test, chore\n\n**Rules:**\n- Title lowercase, no period, max 50 chars\n- Body explains *why*, not just *what*\n\n## Step 3: Ask for Confirmation\n\n```\nReady to commit:\n\nfeat(auth): add JWT token refresh\n\n- Added refresh token endpoint\n\nProceed? (yes/no/edit)\n```\n\n**Wait for user approval.**\n\n## Step 4: Commit\n\n```bash\ngit commit -m "feat(auth): add JWT token refresh\n\n- Added refresh token endpoint"\n```\n\n## Guidelines\n\n- Only commit staged files\n- NO "Co-Authored-By" lines\n- NO "Generated with Claude Code" ads\n- Ask before committing\n\n## Checklist\n\n- [ ] Reviewed staged changes\n- [ ] Message follows convention\n- [ ] User approved\n';
 
-// src/instructions/skills/knowns.doc/SKILL.md
-var SKILL_default2 = '---\nname: knowns.doc\ndescription: Use when working with Knowns documentation - viewing, searching, creating, or updating docs\n---\n\n# Working with Documentation\n\nNavigate, create, and update Knowns project documentation.\n\n**Announce at start:** "I\'m using the knowns.doc skill to work with documentation."\n\n**Core principle:** SEARCH BEFORE CREATING - avoid duplicates.\n\n## Quick Reference\n\n{{#if mcp}}\n```json\n// List all docs\nmcp__knowns__list_docs({})\n\n// View doc (smart mode)\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\n\n// Search docs\nmcp__knowns__search_docs({ "query": "<query>" })\n\n// Create doc\nmcp__knowns__create_doc({\n  "title": "<title>",\n  "description": "<description>",\n  "tags": ["tag1", "tag2"],\n  "folder": "folder"\n})\n\n// Update doc\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "content": "content"\n})\n\n// Update section only\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "section": "2",\n  "content": "new section content"\n})\n```\n{{else}}\n```bash\n# List all docs\nknowns doc list --plain\n\n# View doc (auto-handles large docs)\nknowns doc "<path>" --plain\n\n# Search docs\nknowns search "<query>" --type doc --plain\n\n# Create doc\nknowns doc create "<title>" -d "<description>" -t "tags" -f "folder"\n\n# Update doc\nknowns doc edit "<path>" -c "content"      # Replace\nknowns doc edit "<path>" -a "content"      # Append\nknowns doc edit "<path>" --section "2" -c "content"  # Section only\n```\n{{/if}}\n\n## Reading Documents\n\n{{#if mcp}}\n**Use smart mode:**\n```json\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\n```\n\n- Small doc (\u22642000 tokens) \u2192 full content\n- Large doc \u2192 stats + TOC, then request specific section\n{{else}}\n**View doc:**\n```bash\nknowns doc "<path>" --plain\n```\n\nFor large docs, use sections:\n```bash\nknowns doc "<path>" --toc --plain\nknowns doc "<path>" --section "2" --plain\n```\n{{/if}}\n\n## Creating Documents\n\n### Step 1: Search First\n\n{{#if mcp}}\n```json\nmcp__knowns__search_docs({ "query": "<topic>" })\n```\n{{else}}\n```bash\nknowns search "<topic>" --type doc --plain\n```\n{{/if}}\n\n**Don\'t duplicate.** Update existing docs when possible.\n\n### Step 2: Choose Location\n\n| Doc Type | Location | Folder |\n|----------|----------|--------|\n| Core (README, ARCH) | Root | (none) |\n| Guide | `guides/` | `guides` |\n| Pattern | `patterns/` | `patterns` |\n| API doc | `api/` | `api` |\n\n### Step 3: Create\n\n{{#if mcp}}\n```json\nmcp__knowns__create_doc({\n  "title": "<title>",\n  "description": "<brief description>",\n  "tags": ["tag1", "tag2"],\n  "folder": "folder"\n})\n```\n{{else}}\n```bash\nknowns doc create "<title>" \\\n  -d "<brief description>" \\\n  -t "tag1,tag2" \\\n  -f "folder"  # optional\n```\n{{/if}}\n\n### Step 4: Add Content\n\n{{#if mcp}}\n```json\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "content": "# Title\\n\\n## 1. Overview\\nWhat this doc covers.\\n\\n## 2. Details\\nMain content."\n})\n```\n{{else}}\n```bash\nknowns doc edit "<path>" -c "$(cat <<\'EOF\'\n# Title\n\n## 1. Overview\nWhat this doc covers.\n\n## 2. Details\nMain content.\n\n## 3. Examples\nPractical examples.\nEOF\n)"\n```\n{{/if}}\n\n## Updating Documents\n\n### View First\n\n{{#if mcp}}\n```json\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\nmcp__knowns__get_doc({ "path": "<path>", "toc": true })\n```\n{{else}}\n```bash\nknowns doc "<path>" --plain\nknowns doc "<path>" --toc --plain  # For large docs\n```\n{{/if}}\n\n### Update Methods\n\n| Method | Use When |\n|--------|----------|\n| Replace all | Rewriting entire doc |\n| Append | Adding to end |\n| Section edit | Updating one section |\n\n**Section edit is most efficient** - less context, safer.\n\n{{#if mcp}}\n```json\n// Update just section 3\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "section": "3",\n  "content": "## 3. New Content\\n\\nUpdated section content..."\n})\n```\n{{else}}\n```bash\n# Update just section 3\nknowns doc edit "<path>" --section "3" -c "## 3. New Content\n\nUpdated section content..."\n```\n{{/if}}\n\n## Document Structure\n\nUse numbered headings for section editing to work:\n\n```markdown\n# Title (H1 - only one)\n\n## 1. Overview\n...\n\n## 2. Installation\n...\n\n## 3. Configuration\n...\n```\n\n## Remember\n\n- Search before creating (avoid duplicates)\n- Use smart mode when reading\n- Use section editing for targeted updates\n- Use numbered headings\n- Reference docs with `@doc/<path>`\n';
+// src/instructions/skills/kn:doc/SKILL.md
+var SKILL_default2 = '---\nname: kn:doc\ndescription: Use when working with Knowns documentation - viewing, searching, creating, or updating docs\n---\n\n# Working with Documentation\n\n**Announce:** "Using kn:doc to work with documentation."\n\n**Core principle:** SEARCH BEFORE CREATING - avoid duplicates.\n\n## Quick Reference\n\n```json\n// List docs\nmcp__knowns__list_docs({})\n\n// View doc (smart mode)\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\n\n// Search docs\nmcp__knowns__search_docs({ "query": "<query>" })\n\n// Create doc (MUST include description)\nmcp__knowns__create_doc({\n  "title": "<title>",\n  "description": "<brief description of what this doc covers>",\n  "tags": ["tag1", "tag2"],\n  "folder": "folder"\n})\n\n// Update content\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "content": "content"\n})\n\n// Update metadata (title, description, tags)\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "title": "New Title",\n  "description": "Updated description",\n  "tags": ["new", "tags"]\n})\n\n// Update section only\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "section": "2",\n  "content": "## 2. New Content\\n\\n..."\n})\n```\n\n## Creating Documents\n\n1. Search first (avoid duplicates)\n2. Choose location:\n\n| Type | Folder |\n|------|--------|\n| Core | (root) |\n| Guide | `guides` |\n| Pattern | `patterns` |\n| API | `api` |\n\n3. Create with **title + description + tags**\n4. Add content\n5. **Validate** after creating\n\n**CRITICAL:** Always include `description` - validate will fail without it!\n\n## Updating Documents\n\n**Section edit is most efficient:**\n```json\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "section": "3",\n  "content": "## 3. New Content\\n\\n..."\n})\n```\n\n## Validate After Changes\n\n**CRITICAL:** After creating/updating docs, validate:\n\n```json\nmcp__knowns__validate({ "scope": "docs" })\n```\n\nIf errors found, fix before continuing.\n\n## Mermaid Diagrams\n\nWebUI supports mermaid rendering. Use for:\n- Architecture diagrams\n- Flowcharts\n- Sequence diagrams\n- Entity relationships\n\n````markdown\n```mermaid\ngraph TD\n    A[Start] --> B{Decision}\n    B -->|Yes| C[Action]\n    B -->|No| D[End]\n```\n````\n\nDiagrams render automatically in WebUI preview.\n\n## Checklist\n\n- [ ] Searched for existing docs\n- [ ] Created with **description** (required!)\n- [ ] Used section editing for updates\n- [ ] Used mermaid for complex flows (optional)\n- [ ] Referenced with `@doc/<path>`\n- [ ] **Validated after changes**\n';
 
-// src/instructions/skills/knowns.extract/SKILL.md
-var SKILL_default3 = '---\nname: knowns.extract\ndescription: Use when extracting reusable patterns, solutions, or knowledge into documentation\n---\n\n# Extracting Knowledge\n\nConvert implementations, patterns, or solutions into reusable project documentation.\n\n**Announce at start:** "I\'m using the knowns.extract skill to extract knowledge."\n\n**Core principle:** ONLY EXTRACT GENERALIZABLE KNOWLEDGE.\n\n## The Process\n\n### Step 1: Identify Source\n\n**From task (if ID provided):**\n{{#if mcp}}\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\n```\n{{else}}\n```bash\nknowns task $ARGUMENTS --plain\n```\n{{/if}}\n\n**From current context (no arguments):**\n- Recent implementation work\n- Patterns discovered during research\n- Solutions found in conversation\n\nLook for:\n- Implementation patterns used\n- Problems solved\n- Decisions made\n- Lessons learned\n\n### Step 2: Identify Extractable Knowledge\n\n**Good candidates for extraction:**\n- Reusable code patterns\n- Error handling approaches\n- Integration patterns\n- Performance solutions\n- Security practices\n- API design decisions\n\n**NOT good for extraction:**\n- Task-specific details\n- One-time fixes\n- Context-dependent solutions\n\n### Step 3: Search for Existing Docs\n\n{{#if mcp}}\n```json\n// Check if pattern already documented\nmcp__knowns__search_docs({ "query": "<pattern/topic>" })\n\n// List related docs\nmcp__knowns__list_docs({ "tag": "pattern" })\n```\n{{else}}\n```bash\n# Check if pattern already documented\nknowns search "<pattern/topic>" --type doc --plain\n\n# List related docs\nknowns doc list --tag pattern --plain\n```\n{{/if}}\n\n**Don\'t duplicate.** Update existing docs when possible.\n\n### Step 4: Create or Update Documentation\n\n**If new pattern - create doc:**\n\n{{#if mcp}}\n```json\nmcp__knowns__create_doc({\n  "title": "Pattern: <Name>",\n  "description": "Reusable pattern for <purpose>",\n  "tags": ["pattern", "<domain>"],\n  "folder": "patterns"\n})\n```\n{{else}}\n```bash\nknowns doc create "Pattern: <Name>" \\\n  -d "Reusable pattern for <purpose>" \\\n  -t "pattern,<domain>" \\\n  -f "patterns"\n```\n{{/if}}\n\n**Add content:**\n\n{{#if mcp}}\n```json\nmcp__knowns__update_doc({\n  "path": "patterns/<name>",\n  "content": "# Pattern: <Name>\\n\\n## 1. Problem\\nWhat problem this pattern solves.\\n\\n## 2. Solution\\nHow to implement the pattern.\\n\\n## 3. Example\\n```typescript\\n// Code example\\n```\\n\\n## 4. When to Use\\n- Situation 1\\n\\n## 5. Source\\nDiscovered in @task-<id>"\n})\n```\n{{else}}\n```bash\nknowns doc edit "patterns/<name>" -c "$(cat <<\'EOF\'\n# Pattern: <Name>\n\n## 1. Problem\nWhat problem this pattern solves.\n\n## 2. Solution\nHow to implement the pattern.\n\n## 3. Example\n```typescript\n// Code example\n```\n\n## 4. When to Use\n- Situation 1\n- Situation 2\n\n## 5. Source\nDiscovered in @task-<id> (or describe context)\nEOF\n)"\n```\n{{/if}}\n\n**If updating existing doc:**\n\n{{#if mcp}}\n```json\nmcp__knowns__update_doc({\n  "path": "<path>",\n  "appendContent": "\\n\\n## Additional: <Topic>\\n\\n<new insight or example>"\n})\n```\n{{else}}\n```bash\nknowns doc edit "<path>" -a "\n\n## Additional: <Topic>\n\n<new insight or example>\n"\n```\n{{/if}}\n\n### Step 5: Create Template (if code-generatable)\n\nIf the pattern involves repeatable code structure, create a codegen template:\n\n```bash\n# Create template skeleton\nknowns template create <pattern-name>\n```\n\n**Update template config** (`.knowns/templates/<pattern-name>/_template.yaml`):\n\n```yaml\nname: <pattern-name>\ndescription: Generate <what it creates>\ndoc: patterns/<pattern-name>    # Link to the doc you just created\n\nprompts:\n  - name: name\n    message: Name?\n    validate: required\n\nfiles:\n  - template: "{{name}}.ts.hbs"\n    destination: "src/{{kebabCase name}}.ts"\n```\n\n**Create template files** (`.hbs` files with Handlebars):\n\n```handlebars\n// {{name}}.ts.hbs\nexport class {{pascalCase name}} {\n  // Pattern implementation\n}\n```\n\n**Link template in doc:**\n\n{{#if mcp}}\n```json\nmcp__knowns__update_doc({\n  "path": "patterns/<name>",\n  "appendContent": "\\n\\n## Generate\\n\\nUse @template/<pattern-name> to generate this pattern."\n})\n```\n{{else}}\n```bash\nknowns doc edit "patterns/<name>" -a "\n\n## Generate\n\nUse @template/<pattern-name> to generate this pattern.\n"\n```\n{{/if}}\n\n### Step 6: Link Back (if from task)\n\n```bash\nknowns task edit $ARGUMENTS --append-notes "\u{1F4DA} Extracted to @doc/patterns/<name>"\nknowns task edit $ARGUMENTS --append-notes "\u{1F527} Template: @template/<pattern-name>"\n```\n\n## What to Extract\n\n| Source | Extract As | Create Template? |\n|--------|------------|------------------|\n| Code pattern | Pattern doc | \u2705 Yes |\n| Component structure | Pattern doc | \u2705 Yes |\n| API endpoint pattern | Integration guide | \u2705 Yes |\n| Error solution | Troubleshooting guide | \u274C No |\n| Performance fix | Performance patterns | \u274C Usually no |\n| Security approach | Security guidelines | \u274C No |\n\n**Create template when:**\n- Pattern is repeatable (will be used multiple times)\n- Has consistent file structure\n- Can be parameterized (name, type, etc.)\n\n## Document Templates\n\n### Pattern Template\n```markdown\n# Pattern: <Name>\n\n## Problem\nWhat this solves.\n\n## Solution\nHow to implement.\n\n## Example\nWorking code.\n\n## When to Use\nWhen to apply this pattern.\n```\n\n### Guide Template\n```markdown\n# Guide: <Topic>\n\n## Overview\nWhat this covers.\n\n## Steps\n1. Step one\n2. Step two\n\n## Common Issues\n- Issue and solution\n```\n\n## Quality Checklist\n\n- [ ] Knowledge is generalizable (not task-specific)\n- [ ] Includes working example\n- [ ] Explains when to use\n- [ ] Links back to source (if applicable)\n- [ ] Tagged appropriately\n- [ ] Template created (if code-generatable)\n- [ ] Doc links to template (`@template/...`)\n- [ ] Template links to doc (`doc:` in config)\n\n## Remember\n\n- Only extract generalizable knowledge\n- Search before creating (avoid duplicates)\n- Include practical examples\n- Reference source when available\n- Tag docs for discoverability\n- **Create template for repeatable code patterns**\n- **Link doc \u2194 template bidirectionally**\n';
+// src/instructions/skills/kn:extract/SKILL.md
+var SKILL_default3 = '---\nname: kn:extract\ndescription: Use when extracting reusable patterns, solutions, or knowledge into documentation\n---\n\n# Extracting Knowledge\n\n**Announce:** "Using kn:extract to extract knowledge."\n\n**Core principle:** ONLY EXTRACT GENERALIZABLE KNOWLEDGE.\n\n## Step 1: Identify Source\n\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\n```\n\nLook for: patterns, problems solved, decisions made, lessons learned.\n\n## Step 2: Search for Existing Docs\n\n```json\nmcp__knowns__search_docs({ "query": "<pattern/topic>" })\n```\n\n**Don\'t duplicate.** Update existing docs when possible.\n\n## Step 3: Create Documentation\n\n```json\nmcp__knowns__create_doc({\n  "title": "Pattern: <Name>",\n  "description": "Reusable pattern for <purpose>",\n  "tags": ["pattern", "<domain>"],\n  "folder": "patterns"\n})\n\nmcp__knowns__update_doc({\n  "path": "patterns/<name>",\n  "content": "# Pattern: <Name>\\n\\n## Problem\\n...\\n\\n## Solution\\n...\\n\\n## Example\\n```typescript\\n// Code\\n```\\n\\n## Source\\n@task-<id>"\n})\n```\n\n## Step 4: Create Template (if code-generatable)\n\n```json\nmcp__knowns__create_template({\n  "name": "<pattern-name>",\n  "description": "Generate <what>",\n  "doc": "patterns/<pattern-name>"\n})\n```\n\nLink template in doc:\n```json\nmcp__knowns__update_doc({\n  "path": "patterns/<name>",\n  "appendContent": "\\n\\n## Generate\\n\\nUse @template/<pattern-name>"\n})\n```\n\n## Step 5: Validate\n\n**CRITICAL:** After creating doc/template, validate to catch broken refs:\n\n```json\nmcp__knowns__validate({})\n```\n\nIf errors found, fix before continuing.\n\n## Step 6: Link Back to Task\n\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "appendNotes": "\u{1F4DA} Extracted to @doc/patterns/<name>"\n})\n```\n\n## What to Extract\n\n| Source | Extract As | Template? |\n|--------|------------|-----------|\n| Code pattern | Pattern doc | \u2705 Yes |\n| API pattern | Integration guide | \u2705 Yes |\n| Error solution | Troubleshooting | \u274C No |\n| Security approach | Guidelines | \u274C No |\n\n## Checklist\n\n- [ ] Knowledge is generalizable\n- [ ] Includes working example\n- [ ] Links back to source\n- [ ] Template created (if applicable)\n- [ ] **Validated (no broken refs)**\n';
 
-// src/instructions/skills/knowns.init/SKILL.md
-var SKILL_default4 = '---\nname: knowns.init\ndescription: Use at the start of a new session to read project docs, understand context, and see current state\n---\n\n# Session Initialization\n\nInitialize a session by reading project documentation and understanding current state.\n\n**Announce at start:** "I\'m using the knowns.init skill to initialize this session."\n\n**Core principle:** READ DOCS BEFORE DOING ANYTHING ELSE.\n\n## The Process\n\n### Step 1: List Available Documentation\n\n{{#if mcp}}\n```json\nmcp__knowns__list_docs({})\n```\n{{else}}\n```bash\nknowns doc list --plain\n```\n{{/if}}\n\n### Step 2: Read Core Documents\n\n**Priority order:**\n\n{{#if mcp}}\n```json\n// 1. Project overview (always read)\nmcp__knowns__get_doc({ "path": "README", "smart": true })\n\n// 2. Architecture (if exists)\nmcp__knowns__get_doc({ "path": "ARCHITECTURE", "smart": true })\n\n// 3. Conventions (if exists)\nmcp__knowns__get_doc({ "path": "CONVENTIONS", "smart": true })\n```\n{{else}}\n```bash\n# 1. Project overview (always read)\nknowns doc "README" --plain\n\n# 2. Architecture (if exists)\nknowns doc "ARCHITECTURE" --plain\n\n# 3. Conventions (if exists)\nknowns doc "CONVENTIONS" --plain\n```\n{{/if}}\n\n### Step 3: Check Current State\n\n{{#if mcp}}\n```json\n// Active timer?\nmcp__knowns__get_time_report({})\n\n// Tasks in progress\nmcp__knowns__list_tasks({ "status": "in-progress" })\n\n// Board overview\nmcp__knowns__get_board({})\n```\n{{else}}\n```bash\n# Active timer?\nknowns time status\n\n# Tasks in progress\nknowns task list --status in-progress --plain\n\n# High priority todos\nknowns task list --status todo --plain | head -20\n```\n{{/if}}\n\n### Step 4: Summarize Context\n\nProvide a brief summary:\n\n```markdown\n## Session Context\n\n### Project\n- **Name**: [from config]\n- **Purpose**: [from README]\n\n### Key Docs Available\n- README: [brief note]\n- ARCHITECTURE: [if exists]\n- CONVENTIONS: [if exists]\n\n### Current State\n- Tasks in progress: [count]\n- Active timer: [yes/no]\n\n### Ready for\n- Working on tasks\n- Creating documentation\n- Answering questions about codebase\n```\n\n## Quick Commands After Init\n\n```\n# Work on a task\n/knowns.task <id>\n\n# Search for something\n{{#if mcp}}\nmcp__knowns__search_docs({ "query": "<query>" })\n{{else}}\nknowns search "<query>" --plain\n{{/if}}\n```\n\n## When to Re-Initialize\n\n**Run init again when:**\n- Starting a new session\n- Major project changes occurred\n- Switching to different area of project\n- Context feels stale\n\n## What to Learn from Docs\n\nFrom **README**:\n- Project purpose and scope\n- Key features\n- Getting started info\n\nFrom **ARCHITECTURE**:\n- System design\n- Component structure\n- Key decisions\n\nFrom **CONVENTIONS**:\n- Coding standards\n- Naming conventions\n- File organization\n\n## Remember\n\n- Always read docs first\n- Check for active work (in-progress tasks)\n- Summarize context for reference\n- Re-init when switching areas\n';
+// src/instructions/skills/kn:implement/SKILL.md
+var SKILL_default4 = '---\nname: kn:implement\ndescription: Use when implementing a task - follow the plan, check ACs, track progress\n---\n\n# Implementing a Task\n\nExecute the implementation plan, track progress, and complete the task.\n\n**Announce:** "Using kn:implement for task [ID]."\n\n**Core principle:** CHECK AC ONLY AFTER WORK IS DONE.\n\n## Step 1: Review Task\n\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\n```\n\n**If task status is "done"** (reopening):\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "status": "in-progress",\n  "appendNotes": "Reopened: <reason>"\n})\nmcp__knowns__start_time({ "taskId": "$ARGUMENTS" })\n```\n\nVerify: plan exists, timer running, which ACs pending.\n\n## Step 2: Check Templates\n\n```json\nmcp__knowns__list_templates({})\n```\n\nIf template exists \u2192 use it to generate boilerplate.\n\n## Step 3: Work Through Plan\n\nFor each step:\n1. Do the work\n2. Check AC (only after done!)\n3. Append note\n\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "checkAc": [1],\n  "appendNotes": "Done: brief description"\n})\n```\n\n## Step 4: Handle Scope Changes\n\n**Small:** Add AC + note\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "addAc": ["New requirement"],\n  "appendNotes": "Scope: added per user"\n})\n```\n\n**Large:** Stop and ask user.\n\n## Step 5: Validate & Complete\n\n1. Run tests/lint/build\n2. **Validate** to catch broken refs:\n\n```json\nmcp__knowns__validate({})\n```\n\n3. Add implementation notes (use `appendNotes`, NOT `notes`!)\n4. Stop timer + mark done\n\n```json\nmcp__knowns__stop_time({ "taskId": "$ARGUMENTS" })\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "status": "done"\n})\n```\n\n## Step 6: Extract Knowledge (optional)\n\nIf patterns discovered: `/kn:extract $ARGUMENTS`\n\n## Checklist\n\n- [ ] All ACs checked\n- [ ] Tests pass\n- [ ] **Validated (no broken refs)**\n- [ ] Notes added\n- [ ] Timer stopped\n- [ ] Status = done\n\n## Red Flags\n\n- Checking AC before work done\n- Skipping tests\n- Skipping validation\n- Using `notes` instead of `appendNotes`\n- Marking done without verification\n';
 
-// src/instructions/skills/knowns.research/SKILL.md
-var SKILL_default5 = '---\nname: knowns.research\ndescription: Use when you need to understand existing code, find patterns, or explore the codebase before implementation\n---\n\n# Researching the Codebase\n\nUnderstand existing patterns and implementation before making changes.\n\n**Announce at start:** "I\'m using the knowns.research skill to research [topic]."\n\n**Core principle:** UNDERSTAND WHAT EXISTS BEFORE ADDING NEW CODE.\n\n## The Process\n\n### Step 1: Search Documentation\n\n{{#if mcp}}\n```json\n// Search docs for topic\nmcp__knowns__search_docs({ "query": "<topic>" })\n\n// Read relevant docs\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\n```\n{{else}}\n```bash\n# Search docs for topic\nknowns search "<topic>" --type doc --plain\n\n# Read relevant docs\nknowns doc "<path>" --plain\n```\n{{/if}}\n\n### Step 2: Search Completed Tasks\n\n{{#if mcp}}\n```json\n// Find similar work that was done\nmcp__knowns__search_tasks({ "query": "<keywords>" })\n\n// View task for implementation details\nmcp__knowns__get_task({ "taskId": "<id>" })\n```\n{{else}}\n```bash\n# Find similar work that was done\nknowns search "<keywords>" --type task --status done --plain\n\n# View task for implementation details\nknowns task <id> --plain\n```\n{{/if}}\n\n**Learn from history** - completed tasks often contain valuable insights.\n\n### Step 3: Search Codebase\n\n```bash\n# Find files by name pattern\nfind . -name "*<pattern>*" -type f | grep -v node_modules | head -20\n\n# Search code content\ngrep -r "<pattern>" --include="*.ts" --include="*.tsx" -l | head -20\n```\n\n### Step 4: Analyze Patterns\n\nLook for:\n- How similar features are implemented\n- Common patterns used\n- File/folder structure conventions\n- Naming conventions\n- Error handling patterns\n\n### Step 5: Document Findings\n\n```markdown\n## Research: [Topic]\n\n### Existing Implementations\n- `src/path/file.ts`: Does X\n- `src/path/other.ts`: Handles Y\n\n### Patterns Found\n- Pattern 1: Used for...\n- Pattern 2: Applied when...\n\n### Related Docs\n- @doc/path1 - Covers X\n- @doc/path2 - Explains Y\n\n### Recommendations\nBased on research:\n1. Reuse X from Y\n2. Follow pattern Z\n3. Avoid approach W because...\n```\n\n## Research Checklist\n\n- [ ] Searched documentation\n- [ ] Reviewed similar completed tasks\n- [ ] Found existing code patterns\n- [ ] Identified reusable components\n- [ ] Noted conventions to follow\n\n## After Research\n\nUse findings in task:\n{{#if mcp}}\n```json\n// Create informed task\nmcp__knowns__create_task({\n  "title": "<title>",\n  "description": "Based on research: use pattern from X"\n})\n```\n{{else}}\n```bash\n# Create informed task\nknowns task create "<title>" \\\n  -d "Based on research: use pattern from X" \\\n  --ac "Follow pattern in src/..." \\\n  --ac "Reuse component Y"\n\n# Or update existing task plan\nknowns task edit <id> --plan $\'1. Based on research...\n2. Reuse pattern from...\'\n```\n{{/if}}\n\n## What to Look For\n\n| Looking For | Where to Check |\n|-------------|----------------|\n| Conventions | @doc/CONVENTIONS, existing code |\n| Patterns | @doc/patterns/*, similar features |\n| Utilities | src/utils/*, src/lib/* |\n| Examples | Completed tasks, tests |\n| API design | Existing endpoints, @doc/api/* |\n\n## When to Research\n\n**Always research before:**\n- Implementing new features\n- Adding new patterns\n- Making architectural decisions\n\n**Skip research for:**\n- Simple bug fixes with clear cause\n- Trivial changes following obvious patterns\n\n## Remember\n\n- Check docs and tasks first\n- Look at how similar things are done\n- Note file locations for reference\n- Look at tests for expected behavior\n- Document findings for future reference\n';
+// src/instructions/skills/kn:init/SKILL.md
+var SKILL_default5 = '---\nname: kn:init\ndescription: Use at the start of a new session to read project docs, understand context, and see current state\n---\n\n# Session Initialization\n\n**Announce:** "Using kn:init to initialize session."\n\n**Core principle:** READ DOCS BEFORE DOING ANYTHING ELSE.\n\n## Step 1: List Docs\n\n```json\nmcp__knowns__list_docs({})\n```\n\n## Step 2: Read Core Docs\n\n```json\nmcp__knowns__get_doc({ "path": "README", "smart": true })\nmcp__knowns__get_doc({ "path": "ARCHITECTURE", "smart": true })\nmcp__knowns__get_doc({ "path": "CONVENTIONS", "smart": true })\n```\n\n## Step 3: Check Current State\n\n```json\nmcp__knowns__list_tasks({ "status": "in-progress" })\nmcp__knowns__get_board({})\n```\n\n## Step 4: Summarize\n\n```markdown\n## Session Context\n- **Project**: [name]\n- **Key Docs**: README, ARCHITECTURE, CONVENTIONS\n- **In-progress tasks**: [count]\n- **Ready for**: tasks, docs, questions\n```\n\n## Next Steps\n\n```\n/kn:plan <task-id>     # Plan a task\n/kn:research <query>   # Research codebase\n```\n';
 
-// src/instructions/skills/knowns.task.brainstorm/SKILL.md
-var SKILL_default6 = '---\nname: knowns.task.brainstorm\ndescription: Use when requirements are unclear, multiple approaches exist, or you need to explore solutions before planning\n---\n\n# Brainstorming for Tasks\n\nConvert vague requirements into concrete design through structured questioning and exploration.\n\n**Announce at start:** "I\'m using the knowns.task.brainstorm skill to explore approaches."\n\n**Core principle:** UNDERSTAND THE PROBLEM BEFORE PROPOSING SOLUTIONS.\n\n## The Process\n\n### Phase 1: Discovery\n\n**One question at a time.** Don\'t overwhelm with multiple questions.\n\nPrefer multiple-choice when possible:\n```\nWhich approach do you prefer?\nA) Quick solution with trade-offs\nB) Comprehensive solution, more effort\nC) Something else (describe)\n```\n\nQuestions to clarify:\n- What problem are we solving?\n- Who are the users/stakeholders?\n- What are the constraints?\n- What does success look like?\n\n### Phase 2: Research Existing Patterns\n\n{{#if mcp}}\n```json\n// Search docs for related patterns\nmcp__knowns__search_docs({ "query": "<topic>" })\n\n// Check how similar things were done\nmcp__knowns__search_tasks({ "query": "<keywords>" })\n```\n{{else}}\n```bash\n# Search docs for related patterns\nknowns search "<topic>" --type doc --plain\n\n# Check how similar things were done\nknowns search "<keywords>" --type task --status done --plain\n```\n{{/if}}\n\n**Learn from history** - completed tasks often contain implementation insights.\n\n### Phase 3: Explore Approaches\n\nPresent 2-3 options with trade-offs:\n\n```markdown\n## Option A: [Name]\n- **Approach**: Brief description\n- **Pros**: What\'s good\n- **Cons**: What\'s challenging\n- **Effort**: Low/Medium/High\n\n## Option B: [Name]\n- **Approach**: Brief description\n- **Pros**: What\'s good\n- **Cons**: What\'s challenging\n- **Effort**: Low/Medium/High\n```\n\n**Lead with your recommendation** and explain why.\n\n### Phase 4: Validate and Document\n\nAfter agreement:\n- Summarize the chosen approach\n- Identify potential risks\n- Define acceptance criteria\n\nIf creating a new task:\n{{#if mcp}}\n```json\nmcp__knowns__create_task({\n  "title": "<title>",\n  "description": "Based on brainstorm: <key decisions>",\n  "acceptanceCriteria": ["Criterion 1", "Criterion 2"]\n})\n```\n{{else}}\n```bash\nknowns task create "<title>" \\\n  -d "Based on brainstorm: <key decisions>" \\\n  --ac "Criterion 1" \\\n  --ac "Criterion 2"\n```\n{{/if}}\n\nIf updating existing task:\n{{#if mcp}}\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "description": "Updated based on brainstorm..."\n})\n```\n{{else}}\n```bash\nknowns task edit $ARGUMENTS -d "Updated based on brainstorm..."\n```\n{{/if}}\n\n## When to Use This Skill\n\n**Good candidates:**\n- Vague requirements ("make it faster", "improve UX")\n- Multiple valid approaches exist\n- Significant effort involved\n- New territory for the project\n\n**Skip for:**\n- Clear, well-defined tasks\n- Bug fixes with obvious solutions\n- Simple additions following existing patterns\n\n## Red Flags\n\n**You\'re doing it wrong if:**\n- Proposing solutions before understanding the problem\n- Asking too many questions at once\n- Not researching existing patterns first\n- Skipping trade-off analysis\n\n## Remember\n\n- One question at a time\n- Research existing patterns first\n- Present options with trade-offs\n- Lead with your recommendation\n- Document the decision\n';
+// src/instructions/skills/kn:plan/SKILL.md
+var SKILL_default6 = '---\nname: kn:plan\ndescription: Use when creating an implementation plan for a task\n---\n\n# Planning a Task\n\n**Announce:** "Using kn:plan for task [ID]."\n\n**Core principle:** GATHER CONTEXT \u2192 PLAN \u2192 VALIDATE \u2192 WAIT FOR APPROVAL.\n\n## Mode Detection\n\nCheck if `$ARGUMENTS` contains `--from`:\n- **Yes** \u2192 Go to "Generate Tasks from Spec" section\n- **No** \u2192 Continue with normal planning flow\n\n---\n\n# Normal Planning Flow\n\n## Step 1: Take Ownership\n\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "status": "in-progress",\n  "assignee": "@me"\n})\nmcp__knowns__start_time({ "taskId": "$ARGUMENTS" })\n```\n\n## Step 2: Gather Context\n\nFollow refs in task:\n```json\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\nmcp__knowns__get_task({ "taskId": "<id>" })\n```\n\nSearch related:\n```json\nmcp__knowns__search_docs({ "query": "<keywords>" })\nmcp__knowns__list_templates({})\n```\n\n## Step 3: Draft Plan\n\n```markdown\n## Implementation Plan\n1. [Step] (see @doc/relevant-doc)\n2. [Step] (use @template/xxx)\n3. Add tests\n4. Update docs\n```\n\n**Tip:** Use mermaid for complex flows:\n````markdown\n```mermaid\ngraph LR\n    A[Input] --> B[Process] --> C[Output]\n```\n````\n\n## Step 4: Save Plan\n\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "plan": "1. Step one\\n2. Step two\\n3. Tests"\n})\n```\n\n## Step 5: Validate\n\n**CRITICAL:** After saving plan with refs, validate to catch broken refs:\n\n```bash\nknowns validate --plain\n```\n\nIf errors found (broken `@doc/...` or `@task-...`), fix before asking approval.\n\n## Step 6: Ask Approval\n\nPresent plan and **WAIT for explicit approval**.\n\n## Next Step\n\nAfter approval: `/kn:implement $ARGUMENTS`\n\n## Checklist\n\n- [ ] Ownership taken\n- [ ] Timer started\n- [ ] Refs followed\n- [ ] Templates checked\n- [ ] **Validated (no broken refs)**\n- [ ] User approved\n\n---\n\n# Generate Tasks from Spec\n\nWhen `$ARGUMENTS` contains `--from @doc/specs/<name>`:\n\n**Announce:** "Using kn:plan to generate tasks from spec [name]."\n\n## Step 1: Read Spec Document\n\nExtract spec path from arguments (e.g., `--from @doc/specs/user-auth` \u2192 `specs/user-auth`).\n\n```json\nmcp__knowns__get_doc({ "path": "specs/<name>", "smart": true })\n```\n\n## Step 2: Parse Requirements\n\nScan spec for:\n- **Functional Requirements** (FR-1, FR-2, etc.)\n- **Acceptance Criteria** (AC-1, AC-2, etc.)\n- **Scenarios** (for edge cases)\n\nGroup related items into logical tasks.\n\n## Step 3: Generate Task Preview\n\nFor each requirement/group, create task structure:\n\n```markdown\n## Generated Tasks from specs/<name>\n\n### Task 1: [Requirement Title]\n- **Description:** [From spec]\n- **ACs:**\n  - [ ] AC from spec\n  - [ ] AC from spec\n- **Spec:** specs/<name>\n- **Priority:** medium\n\n### Task 2: [Requirement Title]\n- **Description:** [From spec]\n- **ACs:**\n  - [ ] AC from spec\n- **Spec:** specs/<name>\n- **Priority:** medium\n\n---\nTotal: X tasks to create\n```\n\n## Step 4: Ask for Approval\n\n> I\'ve generated **X tasks** from the spec. Please review:\n> - **Approve** to create all tasks\n> - **Edit** to modify before creating\n> - **Cancel** to abort\n\n**WAIT for explicit approval.**\n\n## Step 5: Create Tasks\n\nWhen approved:\n\n```json\nmcp__knowns__create_task({\n  "title": "<requirement title>",\n  "description": "<from spec>",\n  "spec": "specs/<name>",\n  "priority": "medium",\n  "labels": ["from-spec"]\n})\n```\n\nThen add ACs:\n```json\nmcp__knowns__update_task({\n  "taskId": "<new-id>",\n  "addAc": ["AC 1", "AC 2", "AC 3"]\n})\n```\n\nRepeat for each task.\n\n## Step 6: Summary\n\n```markdown\n## Created Tasks\n\n| ID | Title | ACs |\n|----|-------|-----|\n| task-xxx | Requirement 1 | 3 |\n| task-yyy | Requirement 2 | 2 |\n\nAll tasks linked to spec: specs/<name>\n\nNext steps:\n- Start with: `/kn:plan <first-task-id>`\n- Or view all: `knowns task list --spec specs/<name> --plain`\n```\n\n## Checklist (--from mode)\n\n- [ ] Spec document read\n- [ ] Requirements parsed\n- [ ] Tasks previewed\n- [ ] User approved\n- [ ] Tasks created with spec link\n- [ ] Summary shown\n';
 
-// src/instructions/skills/knowns.task.implement/SKILL.md
-var SKILL_default7 = '---\nname: knowns.task.implement\ndescription: Use when implementing a task - follow the plan, check ACs, track progress\n---\n\n# Implementing a Task\n\nExecute the implementation plan, track progress, and complete the task.\n\n**Announce at start:** "I\'m using the knowns.task.implement skill to implement task [ID]."\n\n**Core principle:** CHECK AC ONLY AFTER WORK IS DONE.\n\n## The Process\n\n### Step 1: Review Current State\n\n{{#if mcp}}\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\n```\n{{else}}\n```bash\nknowns task $ARGUMENTS --plain\n```\n{{/if}}\n\nVerify:\n- Plan exists and is approved\n- Timer is running\n- Know which ACs are pending\n\n### Step 2: Check for Applicable Templates\n\nBefore writing code, check if there\'s a template that matches:\n\n```bash\nknowns template list\n```\n\n**If template exists:**\n1. Read linked doc for context\n2. Use template to generate boilerplate\n3. Customize generated code as needed\n\n{{#if mcp}}\n```json\n// Read template\'s linked doc\nmcp__knowns__get_doc({ "path": "<template-doc>", "smart": true })\n```\n```bash\n# Generate code from template (reduces context, ensures consistency)\nknowns template run <template-name> --name "MyComponent"\n```\n{{else}}\n```bash\n# Read template\'s linked doc\nknowns doc "<template-doc>" --plain\n\n# Generate code from template (reduces context, ensures consistency)\nknowns template run <template-name> --name "MyComponent"\n```\n{{/if}}\n\n**Why use templates:**\n- Reduces context (no need to generate boilerplate)\n- Ensures consistency with project patterns\n- Faster implementation\n\n### Step 3: Work Through Plan\n\nFor each step in the plan:\n\n1. **Check for template** (use if available)\n2. **Do the work** (generate or write code)\n3. **Check related AC** (only after work is done!)\n4. **Append progress note**\n\n{{#if mcp}}\n```json\n// After completing work for AC #1:\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "checkAc": [1],\n  "appendNotes": "\u2713 Done: brief description"\n})\n```\n{{else}}\n```bash\n# After completing work for AC #1:\nknowns task edit $ARGUMENTS --check-ac 1\nknowns task edit $ARGUMENTS --append-notes "\u2713 Done: brief description"\n```\n{{/if}}\n\n### Step 4: Handle Scope Changes\n\nIf new requirements emerge during implementation:\n\n**Small change:**\n{{#if mcp}}\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "addAc": ["New requirement"],\n  "appendNotes": "\u26A0\uFE0F Scope: added requirement per user"\n})\n```\n{{else}}\n```bash\nknowns task edit $ARGUMENTS --ac "New requirement"\nknowns task edit $ARGUMENTS --append-notes "\u26A0\uFE0F Scope: added requirement per user"\n```\n{{/if}}\n\n**Large change:**\n- Stop and ask user\n- Consider creating follow-up task\n- Update plan if needed\n\n### Step 5: Verify & Complete\n\nWhen all ACs are checked:\n\n**1. Verify code quality:**\n```bash\nnpm test        # or project\'s test command\nnpm run lint    # or project\'s lint command\nnpm run build   # if applicable\n```\n\n**Don\'t complete if verification fails.** Fix issues first.\n\n**2. Add implementation notes (REQUIRED for audit):**\n\nDocument all changes made for audit trail.\n\n> \u26A0\uFE0F **CRITICAL**: Use `appendNotes` (NOT `notes`). Using `notes` will DESTROY the audit trail!\n\n{{#if mcp}}\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "appendNotes": "## Implementation Complete\\n\\n### Files Changed\\n- `src/path/file.ts` - Added X\\n- `src/path/other.ts` - Modified Y\\n\\n### Key Changes\\n- Change 1: description\\n\\n### Testing\\n- Test coverage / manual testing done"\n})\n```\n{{else}}\n```bash\nknowns task edit $ARGUMENTS --append-notes $\'\n## Implementation Complete\n\n### Files Changed\n- `src/path/file.ts` - Added X\n- `src/path/other.ts` - Modified Y\n- `tests/file.test.ts` - Added tests\n\n### Key Changes\n- Change 1: description\n- Change 2: description\n\n### Testing\n- Test coverage / manual testing done\n\'\n```\n{{/if}}\n\n**IMPORTANT:** Always use `appendNotes` (not `notes`) to preserve audit trail.\n\n**3. Stop timer and mark done:**\n\n{{#if mcp}}\n```json\nmcp__knowns__stop_time({ "taskId": "$ARGUMENTS" })\n```\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "status": "done"\n})\n```\n{{else}}\n```bash\nknowns time stop\nknowns task edit $ARGUMENTS -s done\n```\n{{/if}}\n\n### Step 6: Consider Knowledge Extraction\n\nIf generalizable patterns were discovered:\n\n```\n/knowns.extract $ARGUMENTS\n```\n\n## Progress Tracking\n\nUse concise notes:\n\n{{#if mcp}}\n```json\n// Good\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "appendNotes": "\u2713 Auth middleware implemented"\n})\n\n// Bad (too verbose)\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "appendNotes": "I have successfully completed..."\n})\n```\n{{else}}\n```bash\n# Good\nknowns task edit $ARGUMENTS --append-notes "\u2713 Auth middleware implemented"\n\n# Bad (too verbose)\nknowns task edit $ARGUMENTS --append-notes "I have successfully completed..."\n```\n{{/if}}\n\n## Completion Checklist\n\n- [ ] All ACs checked\n- [ ] Tests pass\n- [ ] Lint clean\n- [ ] Implementation notes added (with file changes for audit)\n- [ ] Timer stopped\n- [ ] Status set to `done`\n- [ ] Knowledge extracted (if applicable)\n\n## Red Flags\n\n**You\'re doing it wrong if:**\n- Checking AC before work is actually complete\n- Making changes not in the approved plan (without asking)\n- Skipping tests\n- Not tracking progress with notes\n- Marking done without verification\n\n## When to Stop\n\n**STOP and ask when:**\n- Requirements unclear or contradictory\n- Approach isn\'t working after 2-3 attempts\n- Need changes outside approved scope\n- Hit unexpected blocker\n\n## If Verification Fails\n\n**Tests failing:**\n1. Keep task in-progress\n2. Fix the issue\n3. Re-run verification\n\n**Forgot to stop timer:**\n{{#if mcp}}\n```json\nmcp__knowns__add_time({\n  "taskId": "$ARGUMENTS",\n  "duration": "<duration>",\n  "note": "Timer correction"\n})\n```\n{{else}}\n```bash\nknowns time add $ARGUMENTS <duration> -n "Timer correction"\n```\n{{/if}}\n\n## Remember\n\n- Check AC only AFTER work is done\n- Use templates when available\n- Track progress with notes\n- Ask before scope changes\n- Follow the approved plan\n- Verify before marking done\n- Always stop the timer\n- Consider knowledge extraction\n';
+// src/instructions/skills/kn:research/SKILL.md
+var SKILL_default7 = '---\nname: kn:research\ndescription: Use when you need to understand existing code, find patterns, or explore the codebase before implementation\n---\n\n# Researching the Codebase\n\n**Announce:** "Using kn:research for [topic]."\n\n**Core principle:** UNDERSTAND WHAT EXISTS BEFORE ADDING NEW CODE.\n\n## Step 1: Search Documentation\n\n```json\nmcp__knowns__search_docs({ "query": "<topic>" })\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\n```\n\n## Step 2: Search Completed Tasks\n\n```json\nmcp__knowns__search_tasks({ "query": "<keywords>" })\nmcp__knowns__get_task({ "taskId": "<id>" })\n```\n\n## Step 3: Search Codebase\n\n```bash\nfind . -name "*<pattern>*" -type f | grep -v node_modules | head -20\ngrep -r "<pattern>" --include="*.ts" -l | head -20\n```\n\n## Step 4: Document Findings\n\n```markdown\n## Research: [Topic]\n\n### Existing Implementations\n- `src/path/file.ts`: Does X\n\n### Patterns Found\n- Pattern 1: Used for...\n\n### Related Docs\n- @doc/path1 - Covers X\n\n### Recommendations\n1. Reuse X from Y\n2. Follow pattern Z\n```\n\n## Checklist\n\n- [ ] Searched documentation\n- [ ] Reviewed similar completed tasks\n- [ ] Found existing code patterns\n- [ ] Identified reusable components\n\n## Next Step\n\nAfter research: `/kn:plan <task-id>`\n';
 
-// src/instructions/skills/knowns.task.plan/SKILL.md
-var SKILL_default8 = '---\nname: knowns.task.plan\ndescription: Use when creating an implementation plan for a task\n---\n\n# Planning a Task\n\nTake ownership, gather context, create implementation plan, and get user approval.\n\n**Announce at start:** "I\'m using the knowns.task.plan skill to plan task [ID]."\n\n**Core principle:** GATHER CONTEXT \u2192 PLAN \u2192 WAIT FOR APPROVAL.\n\n## The Process\n\n### Step 1: View Task & Take Ownership\n\n{{#if mcp}}\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\n```\n\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "status": "in-progress",\n  "assignee": "@me"\n})\n```\n\n```json\nmcp__knowns__start_time({ "taskId": "$ARGUMENTS" })\n```\n{{else}}\n```bash\nknowns task $ARGUMENTS --plain\nknowns task edit $ARGUMENTS -s in-progress -a @me\nknowns time start $ARGUMENTS\n```\n{{/if}}\n\n**Timer is mandatory.** Time data is used for estimation.\n\n### Step 2: Gather Context\n\n**Follow all refs in task:**\n\n{{#if mcp}}\n```json\n// @doc/<path> \u2192\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\n\n// @task-<id> \u2192\nmcp__knowns__get_task({ "taskId": "<id>" })\n```\n{{else}}\n```bash\n# @doc/<path> \u2192\nknowns doc "<path>" --plain\n\n# @task-<id> \u2192\nknowns task <id> --plain\n```\n{{/if}}\n\n**Search for related context:**\n\n{{#if mcp}}\n```json\nmcp__knowns__search_docs({ "query": "<keywords>" })\nmcp__knowns__search_tasks({ "query": "<keywords>" })\n```\n{{else}}\n```bash\nknowns search "<keywords>" --type doc --plain\nknowns search "<keywords>" --type task --status done --plain\n```\n{{/if}}\n\n**Check for templates:**\n\n```bash\nknowns template list\n```\n\n### Step 3: Draft Implementation Plan\n\nStructure your plan:\n\n```markdown\n## Implementation Plan\n\n1. [Step] (see @doc/relevant-doc)\n2. [Step] (use @template/xxx if available)\n3. Add tests\n4. Update documentation\n```\n\n**Plan guidelines:**\n- Reference relevant docs with `@doc/<path>`\n- Reference templates with `@template/<name>`\n- Include testing step\n- Include doc updates if needed\n- Keep steps actionable and specific\n\n### Step 4: Present to User\n\nShow the plan and **ASK for approval**:\n\n```markdown\nHere\'s my implementation plan for task [ID]:\n\n1. Step one (see @doc/xxx)\n2. Generate boilerplate with @template/xxx\n3. Customize implementation\n4. Add unit tests\n5. Update API docs\n\nShall I proceed with this plan?\n```\n\n**WAIT for explicit approval.**\n\n### Step 5: Save Plan (after approval)\n\n> \u26A0\uFE0F **Use `appendNotes` (NOT `notes`)** to preserve audit trail:\n\n{{#if mcp}}\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "plan": "1. Step one (see @doc/xxx)\\n2. Step two\\n3. Add unit tests\\n4. Update API docs",\n  "appendNotes": "\u{1F4CB} Plan approved, starting implementation"\n})\n```\n{{else}}\n```bash\nknowns task edit $ARGUMENTS --plan $\'1. Step one (see @doc/xxx)\n2. Step two\n3. Add unit tests\n4. Update API docs\'\nknowns task edit $ARGUMENTS --append-notes "\u{1F4CB} Plan approved, starting implementation"\n```\n{{/if}}\n\n## Plan Quality Checklist\n\n- [ ] Task ownership taken (status: in-progress)\n- [ ] Timer started\n- [ ] All refs followed\n- [ ] Related docs/tasks searched\n- [ ] Templates identified (if any)\n- [ ] Steps are specific and actionable\n- [ ] Includes relevant doc/template references\n- [ ] Includes testing\n- [ ] User has approved\n\n## Next Step\n\nAfter plan is approved:\n\n```\n/knowns.task.implement $ARGUMENTS\n```\n\n## When Plan Isn\'t Clear\n\nIf requirements are unclear or multiple approaches exist:\n\n```\n/knowns.task.brainstorm $ARGUMENTS\n```\n\n## Remember\n\n- Take ownership and start timer first\n- Gather context before planning\n- Check for templates to use\n- Never implement without approved plan\n- Reference docs and templates in the plan\n';
+// src/instructions/skills/kn:spec/SKILL.md
+var SKILL_default8 = '---\nname: kn:spec\ndescription: Use when creating a specification document for a feature (SDD workflow)\n---\n\n# Creating a Spec Document\n\nCreate a specification document for a feature using SDD (Spec-Driven Development).\n\n**Announce:** "Using kn:spec to create spec for [name]."\n\n**Core principle:** SPEC FIRST \u2192 REVIEW \u2192 APPROVE \u2192 THEN PLAN TASKS.\n\n## Step 1: Get Feature Name\n\nIf `$ARGUMENTS` provided, use it as spec name.\n\nIf no arguments, ask user:\n> What feature are you speccing? (e.g., "user-auth", "payment-flow")\n\n## Step 2: Gather Requirements\n\nAsk user to describe the feature:\n> Please describe the feature requirements. What should it do?\n\nListen for:\n- Core functionality\n- User stories / scenarios\n- Edge cases\n- Non-functional requirements\n\n## Step 3: Create Spec Document\n\n```json\nmcp__knowns__create_doc({\n  "title": "<Feature Name>",\n  "description": "Specification for <feature>",\n  "folder": "specs",\n  "tags": ["spec", "draft"],\n  "content": "<spec content>"\n})\n```\n\n**Spec Template:**\n\n```markdown\n## Overview\n\nBrief description of the feature and its purpose.\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [Requirement description]\n- FR-2: [Requirement description]\n\n### Non-Functional Requirements\n- NFR-1: [Performance, security, etc.]\n\n## Acceptance Criteria\n\n- [ ] AC-1: [Testable criterion]\n- [ ] AC-2: [Testable criterion]\n- [ ] AC-3: [Testable criterion]\n\n## Scenarios\n\n### Scenario 1: [Happy Path]\n**Given** [context]\n**When** [action]\n**Then** [expected result]\n\n### Scenario 2: [Edge Case]\n**Given** [context]\n**When** [action]\n**Then** [expected result]\n\n## Technical Notes\n\nOptional implementation hints or constraints.\n\n## Open Questions\n\n- [ ] Question 1?\n- [ ] Question 2?\n```\n\n## Step 4: Ask for Review\n\nPresent the spec and ask:\n> Please review this spec:\n> - **Approve** if requirements are complete\n> - **Edit** if you want to modify something\n> - **Add more** if requirements are missing\n\n## Step 5: Handle Response\n\n**If approved:**\n```json\nmcp__knowns__update_doc({\n  "path": "specs/<name>",\n  "tags": ["spec", "approved"]\n})\n```\n\nThen suggest:\n> Spec approved! Ready to create tasks?\n> Run: `/kn:plan --from @doc/specs/<name>`\n\n**If edit requested:**\nUpdate the spec based on feedback and return to Step 4.\n\n**If add more:**\nGather additional requirements and update spec.\n\n## Checklist\n\n- [ ] Feature name determined\n- [ ] Requirements gathered\n- [ ] Spec created in specs/ folder\n- [ ] Includes: Overview, Requirements, ACs, Scenarios\n- [ ] User reviewed\n- [ ] Status updated (draft \u2192 approved)\n- [ ] Next step suggested (/kn:plan --from)\n\n## Red Flags\n\n- Creating spec without user input\n- Skipping review step\n- Approving without explicit user confirmation\n- Not suggesting task creation after approval\n';
 
-// src/instructions/skills/knowns.task.reopen/SKILL.md
-var SKILL_default9 = '---\nname: knowns.task.reopen\ndescription: Use when reopening a completed task to add new requirements, fix issues, or extend functionality\n---\n\n# Reopening Tasks\n\nReopen completed tasks properly with time tracking and requirement documentation.\n\n**Announce at start:** "I\'m using the knowns.task.reopen skill to reopen task [ID]."\n\n**Core principle:** DOCUMENT WHY THE TASK IS REOPENED.\n\n## The Process\n\n### Step 1: View Current Task State\n\n{{#if mcp}}\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\n```\n{{else}}\n```bash\nknowns task $ARGUMENTS --plain\n```\n{{/if}}\n\nVerify:\n- Task is currently `done`\n- Understand what was implemented\n- Review implementation notes\n\n### Step 2: Reopen and Start Timer\n\n{{#if mcp}}\n```json\n// Set back to in-progress\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "status": "in-progress"\n})\n\n// Start timer (REQUIRED)\nmcp__knowns__start_time({ "taskId": "$ARGUMENTS" })\n```\n{{else}}\n```bash\n# Set back to in-progress\nknowns task edit $ARGUMENTS -s in-progress\n\n# Start timer (REQUIRED)\nknowns time start $ARGUMENTS\n```\n{{/if}}\n\n### Step 3: Document Reopen Reason\n\n> \u26A0\uFE0F **Use `appendNotes` (NOT `notes`)** to preserve existing audit trail:\n\n{{#if mcp}}\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "appendNotes": "\u{1F504} Reopened: <reason>"\n})\n```\n{{else}}\n```bash\nknowns task edit $ARGUMENTS --append-notes "\u{1F504} Reopened: <reason>"\n```\n{{/if}}\n\n**Common reasons:**\n- User requested changes\n- Bug found in implementation\n- New requirements added\n- Missed acceptance criteria\n\n### Step 4: Add New Requirements\n\n{{#if mcp}}\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "addAc": ["New requirement 1", "Fix: issue description"]\n})\n```\n{{else}}\n```bash\n# Add new acceptance criteria\nknowns task edit $ARGUMENTS --ac "New requirement 1"\nknowns task edit $ARGUMENTS --ac "Fix: issue description"\n```\n{{/if}}\n\n### Step 5: Update Plan (if needed)\n\n{{#if mcp}}\n```json\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "plan": "Previous plan + new steps:\\n1. Original step (done)\\n2. Original step (done)\\n3. NEW: Address new requirement\\n4. NEW: Fix reported issue"\n})\n```\n{{else}}\n```bash\nknowns task edit $ARGUMENTS --plan $\'Previous plan + new steps:\n1. Original step (done)\n2. Original step (done)\n3. NEW: Address new requirement\n4. NEW: Fix reported issue\'\n```\n{{/if}}\n\n**Present updated plan and WAIT for approval.**\n\n### Step 6: Implement and Complete\n\nFollow normal task completion flow:\n\n{{#if mcp}}\n```json\n// Check new ACs as completed\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "checkAc": [<new-index>],\n  "appendNotes": "\u2713 Done: new requirement"\n})\n\n// Stop timer\nmcp__knowns__stop_time({ "taskId": "$ARGUMENTS" })\n\n// Mark done again\nmcp__knowns__update_task({\n  "taskId": "$ARGUMENTS",\n  "status": "done"\n})\n```\n{{else}}\n```bash\n# Check new ACs as completed\nknowns task edit $ARGUMENTS --check-ac <new-index>\nknowns task edit $ARGUMENTS --append-notes "\u2713 Done: new requirement"\n\n# Stop timer\nknowns time stop\n\n# Mark done again\nknowns task edit $ARGUMENTS -s done\n```\n{{/if}}\n\n## When to Reopen vs Create New Task\n\n| Reopen Existing | Create New Task |\n|-----------------|-----------------|\n| Small fix/change | Major new feature |\n| Related to original work | Unrelated work |\n| Same context needed | Different context |\n| Quick addition | Significant scope |\n\n**Rule of thumb:** If it takes < 30 mins and relates to original task, reopen. Otherwise, create new task with reference.\n\n## Creating Follow-up Task Instead\n\n{{#if mcp}}\n```json\nmcp__knowns__create_task({\n  "title": "Follow-up: <description>",\n  "description": "Related to @task-$ARGUMENTS"\n})\n```\n{{else}}\n```bash\nknowns task create "Follow-up: <description>" \\\n  -d "Related to @task-$ARGUMENTS" \\\n  --ac "New requirement"\n```\n{{/if}}\n\n## Remember\n\n- Always document reopen reason\n- Start timer when reopening\n- Add new AC for traceability\n- Stop timer when done\n- Consider if new task is more appropriate\n';
+// src/instructions/skills/kn:template/SKILL.md
+var SKILL_default9 = '---\nname: kn:template\ndescription: Use when generating code from templates - list, run, or create templates\n---\n\n# Working with Templates\n\n**Announce:** "Using kn:template to work with templates."\n\n**Core principle:** USE TEMPLATES FOR CONSISTENT CODE GENERATION.\n\n## Step 1: List Templates\n\n```json\nmcp__knowns__list_templates({})\n```\n\n## Step 2: Get Template Details\n\n```json\nmcp__knowns__get_template({ "name": "<template-name>" })\n```\n\nCheck: prompts, `doc:` link, files to generate.\n\n## Step 3: Read Linked Documentation\n\n```json\nmcp__knowns__get_doc({ "path": "<doc-path>", "smart": true })\n```\n\n## Step 4: Run Template\n\n```json\n// Dry run first\nmcp__knowns__run_template({\n  "name": "<template-name>",\n  "variables": { "name": "MyComponent" },\n  "dryRun": true\n})\n\n// Then run for real\nmcp__knowns__run_template({\n  "name": "<template-name>",\n  "variables": { "name": "MyComponent" },\n  "dryRun": false\n})\n```\n\n## Step 5: Create New Template\n\n```json\nmcp__knowns__create_template({\n  "name": "<template-name>",\n  "description": "Description",\n  "doc": "patterns/<related-doc>"\n})\n```\n\n## Template Config\n\n```yaml\nname: react-component\ndescription: Create a React component\ndoc: patterns/react-component\n\nprompts:\n  - name: name\n    message: Component name?\n    validate: required\n\nfiles:\n  - template: ".tsx.hbs"\n    destination: "src/components//.tsx"\n```\n\n## CRITICAL: Syntax Pitfalls\n\n**NEVER write `$` + triple-brace:**\n```\n// \u274C WRONG\n$` + `{` + `{` + `{camelCase name}`\n\n// \u2705 CORRECT - add space, use ~\n${ {{~camelCase name~}}}\n```\n\n## Checklist\n\n- [ ] Listed available templates\n- [ ] Read linked documentation\n- [ ] Ran dry run first\n- [ ] Verified generated files\n';
 
-// src/instructions/skills/knowns.task/SKILL.md
-var SKILL_default10 = '---\nname: knowns.task\ndescription: Use when working on a Knowns task - view task details and decide next action\n---\n\n# Working on a Task\n\nView task details and determine the appropriate next action.\n\n**Announce at start:** "I\'m using the knowns.task skill to view task [ID]."\n\n**Core principle:** VIEW AND ROUTE - analyze state, suggest next skill.\n\n## The Process\n\n### Step 1: View Task\n\n{{#if mcp}}\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\n```\n{{else}}\n```bash\nknowns task $ARGUMENTS --plain\n```\n{{/if}}\n\n### Step 2: Analyze State\n\nCheck:\n- **Status**: todo, in-progress, done?\n- **Assignee**: Assigned to someone?\n- **AC**: Any checked? All checked?\n- **Plan**: Has implementation plan?\n- **Refs**: Any `@doc/` or `@task-` references?\n\n### Step 3: Suggest Next Action\n\nBased on task state, recommend the appropriate skill:\n\n| State | Next Skill |\n|-------|------------|\n| `todo`, not started | `knowns.task.plan` |\n| `in-progress`, no plan | `knowns.task.plan` |\n| `in-progress`, has plan | `knowns.task.implement` |\n| `done`, needs changes | `knowns.task.reopen` |\n| Requirements unclear | `knowns.task.brainstorm` |\n\n### Step 4: Follow Refs (if needed)\n\nIf task has references, follow them for context:\n\n{{#if mcp}}\n```json\n// Doc ref: @doc/path \u2192\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\n\n// Task ref: @task-<id> \u2192\nmcp__knowns__get_task({ "taskId": "<id>" })\n```\n{{else}}\n```bash\n# Doc ref: @doc/path \u2192\nknowns doc "<path>" --plain\n\n# Task ref: @task-<id> \u2192\nknowns task <id> --plain\n```\n{{/if}}\n\n## Quick Actions\n\n**Start planning (includes taking ownership):**\n```\n/knowns.task.plan $ARGUMENTS\n```\n\n**Continue implementing:**\n```\n/knowns.task.implement $ARGUMENTS\n```\n\n**Requirements unclear:**\n```\n/knowns.task.brainstorm $ARGUMENTS\n```\n\n**Reopen completed task:**\n```\n/knowns.task.reopen $ARGUMENTS\n```\n\n## Remember\n\n- This skill is for viewing and routing\n- Use `plan` to start a new task (takes ownership, starts timer)\n- Use `implement` to continue/complete in-progress tasks\n- Always follow refs for full context\n';
-
-// src/instructions/skills/knowns.template/SKILL.md
-var SKILL_default11 = '---\nname: knowns.template\ndescription: Use when generating code from templates - list, run, or create templates\n---\n\n# Working with Templates\n\nGenerate code from predefined templates stored in `.knowns/templates/`.\n\n**Announce at start:** "I\'m using the knowns.template skill to work with templates."\n\n**Core principle:** USE TEMPLATES FOR CONSISTENT CODE GENERATION.\n\n## The Process\n\n### Step 1: List Available Templates\n\n{{#if mcp}}\n```json\nmcp__knowns__list_templates({})\n```\n{{else}}\n```bash\nknowns template list\n```\n{{/if}}\n\n### Step 2: Get Template Details\n\n{{#if mcp}}\n```json\nmcp__knowns__get_template({ "name": "<template-name>" })\n```\n{{else}}\n```bash\nknowns template info <template-name>\n```\n{{/if}}\n\nCheck:\n- Required variables (prompts)\n- Linked documentation (`doc:`)\n- Files that will be generated\n\n### Step 3: Read Linked Documentation\n\nIf template has a `doc:` field, read it first:\n\n{{#if mcp}}\n```json\nmcp__knowns__get_doc({ "path": "<doc-path>", "smart": true })\n```\n{{else}}\n```bash\nknowns doc "<doc-path>" --plain\n```\n{{/if}}\n\n### Step 4: Run Template\n\n{{#if mcp}}\n```json\n// Dry run first (preview)\nmcp__knowns__run_template({\n  "name": "<template-name>",\n  "variables": { "name": "MyComponent", "type": "page" },\n  "dryRun": true\n})\n\n// Then run for real\nmcp__knowns__run_template({\n  "name": "<template-name>",\n  "variables": { "name": "MyComponent", "type": "page" },\n  "dryRun": false\n})\n```\n{{else}}\n```bash\n# Dry run (preview)\nknowns template run <template-name> --name "MyComponent" --dry-run\n\n# Run for real\nknowns template run <template-name> --name "MyComponent"\n```\n{{/if}}\n\n### Step 5: Create New Template\n\n{{#if mcp}}\n```json\nmcp__knowns__create_template({\n  "name": "<template-name>",\n  "description": "Template description",\n  "doc": "patterns/<related-doc>"  // Optional: link to documentation\n})\n```\n{{else}}\n```bash\nknowns template create <template-name>\n```\n{{/if}}\n\nThis creates:\n```\n.knowns/templates/<template-name>/\n  \u251C\u2500\u2500 _template.yaml    # Config\n  \u2514\u2500\u2500 example.ts.hbs    # Example file\n```\n\n## Template Config (`_template.yaml`)\n\n```yaml\nname: react-component\ndescription: Create a React component with tests\ndoc: patterns/react-component    # Link to documentation\n\nprompts:\n  - name: name\n    message: Component name?\n    validate: required\n\n  - name: type\n    message: Component type?\n    type: select\n    choices:\n      - page\n      - component\n      - layout\n\nfiles:\n  - template: "{{name}}.tsx.hbs"\n    destination: "src/components/{{pascalCase name}}/{{pascalCase name}}.tsx"\n\n  - template: "{{name}}.test.tsx.hbs"\n    destination: "src/components/{{pascalCase name}}/{{pascalCase name}}.test.tsx"\n    condition: "{{includeTests}}"\n```\n\n## Template-Doc Linking\n\nTemplates can reference docs and vice versa:\n\n**In `_template.yaml`:**\n```yaml\ndoc: patterns/react-component\n```\n\n**In doc (markdown):**\n```markdown\nUse @template/react-component to generate.\n```\n\n**AI workflow:**\n1. Get template config\n2. Follow `doc:` link to understand patterns\n3. Run template with appropriate variables\n\n## Handlebars Helpers\n\nTemplates use Handlebars with built-in helpers:\n\n| Helper | Example | Output |\n|--------|---------|--------|\n| `camelCase` | `{{camelCase "my name"}}` | `myName` |\n| `pascalCase` | `{{pascalCase "my name"}}` | `MyName` |\n| `kebabCase` | `{{kebabCase "MyName"}}` | `my-name` |\n| `snakeCase` | `{{snakeCase "MyName"}}` | `my_name` |\n| `upperCase` | `{{upperCase "name"}}` | `NAME` |\n| `lowerCase` | `{{lowerCase "NAME"}}` | `name` |\n\n## CRITICAL: Template Syntax Pitfalls\n\n### JavaScript Template Literals + Handlebars\n\n**NEVER write `$` followed by triple-brace** - Handlebars interprets triple-brace as unescaped output:\n\n```\n// \u274C WRONG - Parse error!\nthis.logger.log(`Created: $` + `\\{{\\{camelCase entity}.id}`);\n\n// \u2705 CORRECT - Add space, use ~ to trim whitespace\nthis.logger.log(`Created: ${ \\{{~camelCase entity~}}.id}`);\n// Output: this.logger.log(`Created: ${product.id}`);\n```\n\n**Rules when writing .hbs templates:**\n1. Never `$` + triple-brace - always add space: `${ \\{{`\n2. Use `~` (tilde) to trim whitespace: `\\{{~helper~}}`\n3. For literal braces, escape with backslash\n\n## When to Use Templates\n\n| Scenario | Action |\n|----------|--------|\n| Creating new component | Run `react-component` template |\n| Adding API endpoint | Run `api-endpoint` template |\n| Setting up new feature | Run `feature-module` template |\n| Consistent file structure | Use template instead of copy-paste |\n\n## Integrated Workflows\n\n### During Implementation (Use Template)\n\n```\nTask \u2192 Read Context \u2192 Find Template \u2192 Generate Code \u2192 Customize\n```\n\n1. Read task and understand requirements\n2. List templates to find applicable one\n3. Get template details and read linked doc\n4. Run template (dry run first, then real)\n5. Customize generated code as needed\n6. Continue with remaining implementation\n\n**Benefits:**\n- Reduces context (no need to generate boilerplate)\n- Ensures consistency with project patterns\n- Faster implementation\n\n### During Extract (Create Template)\n\n```\nContext \u2192 Identify Pattern \u2192 Create Doc \u2192 Create Template \u2192 Link Both\n```\n\n1. Identify repeatable code pattern\n2. Create doc with `/knowns.extract`\n3. Create template with `knowns template create <name>`\n4. Link template to doc: `doc: patterns/<name>`\n5. Link doc to template: `@template/<name>`\n\n**When to create template:**\n- Pattern will be used multiple times\n- Has consistent file structure\n- Can be parameterized\n\n## Checklist\n\n- [ ] Listed available templates\n- [ ] Got template details (prompts, files)\n- [ ] Read linked documentation (if any)\n- [ ] Understood required variables\n- [ ] Ran dry run first\n- [ ] Ran template with correct inputs\n- [ ] Verified generated files\n\n## Remember\n\n- Always dry run first before writing files\n- Check `doc:` link in template for context\n- Templates ensure consistent code structure\n- Create new templates for repeated patterns\n- **NEVER write `$` + triple-brace** - use `${ \\{{~helper~}}` instead (add space, use tilde)\n';
+// src/instructions/skills/kn:verify/SKILL.md
+var SKILL_default10 = '---\nname: kn:verify\ndescription: Use when running SDD verification and coverage reporting\n---\n\n# SDD Verification\n\nRun validation with SDD-awareness to check spec coverage and task status.\n\n**Announce:** "Using kn:verify to check SDD status."\n\n**Core principle:** VERIFY SPEC COVERAGE \u2192 REPORT WARNINGS \u2192 SUGGEST FIXES.\n\n## Step 1: Run SDD Validation\n\n### Via CLI\n```bash\nknowns validate --sdd --plain\n```\n\n### Via MCP (if available)\n```json\nmcp__knowns__validate({ "scope": "sdd" })\n```\n\n## Step 2: Present SDD Status Report\n\nDisplay the results in this format:\n\n```\nSDD Status Report\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\nSpecs:    X total | Y approved | Z draft\nTasks:    X total | Y done | Z in-progress | W todo\nCoverage: X/Y tasks linked to specs (Z%)\n\n\u26A0\uFE0F Warnings:\n  - task-XX has no spec reference\n  - specs/feature: X/Y ACs incomplete\n\n\u2705 Passed:\n  - All spec references resolve\n  - specs/auth: fully implemented\n```\n\n## Step 3: Analyze Results\n\n**Good coverage (>80%):**\n> SDD coverage is healthy. All tasks are properly linked to specs.\n\n**Medium coverage (50-80%):**\n> Some tasks are missing spec references. Consider:\n> - Link existing tasks to specs: `knowns task edit <id> --spec specs/<name>`\n> - Create specs for unlinked work: `/kn:spec <feature-name>`\n\n**Low coverage (<50%):**\n> Many tasks lack spec references. For better traceability:\n> 1. Create specs for major features: `/kn:spec <feature>`\n> 2. Link tasks to specs: `knowns task edit <id> --spec specs/<name>`\n> 3. Use `/kn:plan --from @doc/specs/<name>` for new tasks\n\n## Step 4: Suggest Actions\n\nBased on warnings, suggest specific fixes:\n\n**For tasks without spec:**\n> Link task to spec:\n> ```bash\n> knowns task edit <id> --spec specs/<name>\n> ```\n\n**For incomplete ACs:**\n> Check task progress:\n> ```bash\n> knowns task <id> --plain\n> ```\n\n**For approved specs without tasks:**\n> Create tasks from spec:\n> ```\n> /kn:plan --from @doc/specs/<name>\n> ```\n\n## Checklist\n\n- [ ] Ran validate --sdd\n- [ ] Presented status report\n- [ ] Analyzed coverage level\n- [ ] Suggested specific fixes for warnings\n\n## Red Flags\n\n- Ignoring warnings\n- Not suggesting actionable fixes\n- Skipping coverage analysis\n';
 
 // src/instructions/skills/index.ts
 function parseSkillFrontmatter(content) {
@@ -58861,35 +58860,27 @@ function createSkill(content, folderName) {
     content: content.trim()
   };
 }
-var SKILL_TASK = createSkill(SKILL_default10, "knowns.task");
-var SKILL_TASK_PLAN = createSkill(SKILL_default8, "knowns.task.plan");
-var SKILL_TASK_IMPLEMENT = createSkill(SKILL_default7, "knowns.task.implement");
-var SKILL_TASK_BRAINSTORM = createSkill(SKILL_default6, "knowns.task.brainstorm");
-var SKILL_TASK_REOPEN = createSkill(SKILL_default9, "knowns.task.reopen");
-var SKILL_EXTRACT = createSkill(SKILL_default3, "knowns.extract");
-var SKILL_DOC = createSkill(SKILL_default2, "knowns.doc");
-var SKILL_COMMIT = createSkill(SKILL_default, "knowns.commit");
-var SKILL_INIT = createSkill(SKILL_default4, "knowns.init");
-var SKILL_RESEARCH = createSkill(SKILL_default5, "knowns.research");
-var SKILL_TEMPLATE = createSkill(SKILL_default11, "knowns.template");
+var SKILL_INIT = createSkill(SKILL_default5, "kn:init");
+var SKILL_PLAN = createSkill(SKILL_default6, "kn:plan");
+var SKILL_IMPLEMENT = createSkill(SKILL_default4, "kn:implement");
+var SKILL_RESEARCH = createSkill(SKILL_default7, "kn:research");
+var SKILL_COMMIT = createSkill(SKILL_default, "kn:commit");
+var SKILL_EXTRACT = createSkill(SKILL_default3, "kn:extract");
+var SKILL_DOC = createSkill(SKILL_default2, "kn:doc");
+var SKILL_TEMPLATE = createSkill(SKILL_default9, "kn:template");
+var SKILL_SPEC = createSkill(SKILL_default8, "kn:spec");
+var SKILL_VERIFY = createSkill(SKILL_default10, "kn:verify");
 var SKILLS = [
-  // Task skills
-  SKILL_TASK,
-  SKILL_TASK_PLAN,
-  SKILL_TASK_IMPLEMENT,
-  SKILL_TASK_BRAINSTORM,
-  SKILL_TASK_REOPEN,
-  // Extract skill
-  SKILL_EXTRACT,
-  // Doc skills
-  SKILL_DOC,
-  // Git skills
-  SKILL_COMMIT,
-  // Session skills
   SKILL_INIT,
+  SKILL_PLAN,
+  SKILL_IMPLEMENT,
   SKILL_RESEARCH,
-  // Template skill
-  SKILL_TEMPLATE
+  SKILL_COMMIT,
+  SKILL_EXTRACT,
+  SKILL_DOC,
+  SKILL_TEMPLATE,
+  SKILL_SPEC,
+  SKILL_VERIFY
 ];
 
 // src/codegen/renderer.ts
@@ -59271,11 +59262,28 @@ async function syncToPlatform(skills, platform, options2) {
   }
   return result;
 }
+function cleanupDeprecatedSkills(targetDir, dryRun) {
+  let removed = 0;
+  if (existsSync2(targetDir)) {
+    const entries = readdirSync(targetDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith("knowns.")) {
+        if (!dryRun) {
+          const deprecatedPath = join4(targetDir, entry.name);
+          rmSync(deprecatedPath, { recursive: true, force: true });
+        }
+        removed++;
+      }
+    }
+  }
+  return removed;
+}
 async function syncToFolderPattern(skills, platform, options2, result) {
   const targetDir = join4(options2.projectRoot, platform.targetDir);
   if (!options2.dryRun && !existsSync2(targetDir)) {
     await mkdir3(targetDir, { recursive: true });
   }
+  cleanupDeprecatedSkills(targetDir, options2.dryRun);
   for (const skill of skills) {
     const skillFolder = join4(targetDir, skill.folderName);
     const skillFile = join4(skillFolder, platform.extension);
@@ -59410,16 +59418,16 @@ function detectPlatforms(projectRoot) {
 var commands_reference_default = '{{#if mcp}}\n# MCP Tools Reference\n\n## Project Tools (Session Init)\n\n**CRITICAL: Call these at session start to initialize the project.**\n\n### mcp__knowns__detect_projects\n\nScan for all Knowns projects on the system:\n\n```json\n{}\n```\n\nReturns: `{ projects: [{ path, name }], currentProject, note }`\n\n### mcp__knowns__set_project\n\nSet the active project for all operations:\n\n```json\n{ "projectRoot": "/absolute/path/to/project" }\n```\n\n### mcp__knowns__get_current_project\n\nCheck current project status:\n\n```json\n{}\n```\n\nReturns: `{ projectRoot, isExplicitlySet, isValid, source }`\n\n---\n\n## Task Tools\n\n### mcp__knowns__create_task\n\n```json\n{\n  "title": "Task title",\n  "description": "Task description",\n  "status": "todo",\n  "priority": "medium",\n  "labels": ["label1"],\n  "assignee": "@me",\n  "parent": "parent-id"\n}\n```\n\n### mcp__knowns__update_task\n\n```json\n{\n  "taskId": "<id>",\n  "status": "in-progress",\n  "assignee": "@me",\n  "addAc": ["Criterion 1", "Criterion 2"],\n  "checkAc": [1, 2],\n  "uncheckAc": [3],\n  "removeAc": [4],\n  "plan": "1. Step one\\n2. Step two",\n  "notes": "Implementation notes",\n  "appendNotes": "Additional notes"\n}\n```\n\n| Field | Purpose |\n|-------|---------|\n| `addAc` | Add new acceptance criteria |\n| `checkAc` | Mark AC done (1-based index) |\n| `uncheckAc` | Unmark AC (1-based index) |\n| `removeAc` | Remove AC (1-based index) |\n| `plan` | Set implementation plan |\n| `notes` | Replace implementation notes |\n| `appendNotes` | Append to notes |\n\n### mcp__knowns__get_task\n\n```json\n{ "taskId": "<id>" }\n```\n\n### mcp__knowns__list_tasks\n\n```json\n{ "status": "in-progress", "assignee": "@me" }\n```\n\n### mcp__knowns__search_tasks\n\n```json\n{ "query": "keyword" }\n```\n\n---\n\n## Doc Tools\n\n### mcp__knowns__get_doc\n\n**ALWAYS use `smart: true`** - auto-handles small/large docs:\n\n```json\n{ "path": "readme", "smart": true }\n```\n\nIf large, returns TOC. Then read section:\n```json\n{ "path": "readme", "section": "3" }\n```\n\n### mcp__knowns__list_docs\n\n```json\n{ "tag": "api" }\n```\n\n### mcp__knowns__create_doc\n\n```json\n{\n  "title": "Doc Title",\n  "description": "Description",\n  "tags": ["tag1"],\n  "folder": "guides",\n  "content": "Initial content"\n}\n```\n\n### mcp__knowns__update_doc\n\n```json\n{\n  "path": "readme",\n  "content": "Replace content",\n  "section": "2"\n}\n```\n\n### mcp__knowns__search_docs\n\n```json\n{ "query": "keyword", "tag": "api" }\n```\n\n### mcp__knowns__search (Unified)\n\n```json\n{\n  "query": "keyword",\n  "type": "all",\n  "status": "in-progress",\n  "priority": "high",\n  "assignee": "@me",\n  "label": "feature",\n  "tag": "api",\n  "limit": 20\n}\n```\n\n| Field | Purpose |\n|-------|---------|\n| `type` | "all", "task", or "doc" |\n| `status/priority/assignee/label` | Task filters |\n| `tag` | Doc filter |\n| `limit` | Max results (default: 20) |\n\n---\n\n## Time Tools\n\n### mcp__knowns__start_time\n\n```json\n{ "taskId": "<id>" }\n```\n\n### mcp__knowns__stop_time\n\n```json\n{ "taskId": "<id>" }\n```\n\n### mcp__knowns__add_time\n\n```json\n{\n  "taskId": "<id>",\n  "duration": "2h30m",\n  "note": "Note",\n  "date": "2025-01-15"\n}\n```\n\n### mcp__knowns__get_time_report\n\n```json\n{ "from": "2025-01-01", "to": "2025-01-31", "groupBy": "task" }\n```\n\n---\n\n## Template Tools\n\n### mcp__knowns__list_templates\n\n```json\n{}\n```\n\n### mcp__knowns__get_template\n\n```json\n{ "name": "template-name" }\n```\n\n### mcp__knowns__run_template\n\n```json\n{\n  "name": "template-name",\n  "variables": { "name": "MyComponent" },\n  "dryRun": true\n}\n```\n\n### mcp__knowns__create_template\n\n```json\n{\n  "name": "my-template",\n  "description": "Description",\n  "doc": "patterns/my-pattern"\n}\n```\n\n---\n\n## Other\n\n### mcp__knowns__get_board\n\n```json\n{}\n```\n\n{{/if}}\n{{#if cli}}\n# CLI Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Task description |\n| `--ac` | | Acceptance criterion (repeatable) |\n| `--labels` | `-l` | Comma-separated labels |\n| `--assignee` | `-a` | Assign to user |\n| `--priority` | | low/medium/high |\n| `--parent` | | Parent task ID (raw ID only!) |\n\n**`-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--status` | `-s` | Change status |\n| `--assignee` | `-a` | Assign user |\n| `--ac` | | Add acceptance criterion |\n| `--check-ac` | | Mark AC done (1-indexed) |\n| `--uncheck-ac` | | Unmark AC |\n| `--plan` | | Set implementation plan |\n| `--notes` | | Replace notes |\n| `--append-notes` | | Add to notes |\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --tree --plain\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Description |\n| `--tags` | `-t` | Comma-separated tags |\n| `--folder` | `-f` | Folder path |\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--content` | `-c` | Replace content |\n| `--append` | `-a` | Append content |\n| `--section` | | Target section (use with -c) |\n\n**In doc edit, `-a` = append content, NOT assignee!**\n\n---\n\n## doc view/list\n\n**ALWAYS use `--smart`** - auto-handles small/large docs:\n\n```bash\nknowns doc <path> --plain --smart\n```\n\nIf large, returns TOC. Then read section:\n```bash\nknowns doc <path> --plain --section 3\n```\n\n```bash\nknowns doc list --plain\nknowns doc list --tag api --plain\n```\n\n---\n\n## time\n\n```bash\nknowns time start <id>    # REQUIRED when taking task\nknowns time stop          # REQUIRED when completing\nknowns time status\nknowns time add <id> <duration> -n "Note"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\n```\n\n---\n\n## template\n\n```bash\nknowns template list\nknowns template info <name>\nknowns template run <name> --name "X" --dry-run\nknowns template create <name>\n```\n\n---\n\n## Multi-line Input\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n{{/if}}\n';
 
 // src/instructions/guidelines/unified/common-mistakes.md
-var common_mistakes_default = '# Common Mistakes\n\n{{#if cli}}\n## CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n{{/if}}\n\n## CRITICAL: Notes vs Append Notes\n\n**NEVER use `notes`/`--notes` for progress updates - it REPLACES all existing notes!**\n\n{{#if cli}}\n```bash\n# \u274C WRONG - Destroys audit trail!\nknowns task edit <id> --notes "Done: feature X"\n\n# \u2705 CORRECT - Preserves history\nknowns task edit <id> --append-notes "Done: feature X"\n```\n{{/if}}\n{{#if mcp}}\n```json\n// \u274C WRONG - Destroys audit trail!\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "notes": "Done: feature X"\n})\n\n// \u2705 CORRECT - Preserves history\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "appendNotes": "Done: feature X"\n})\n```\n{{/if}}\n\n| Field | Behavior |\n|-------|----------|\n{{#if cli}}\n| `--notes` | **REPLACES** all notes (use only for initial setup) |\n| `--append-notes` | **APPENDS** to existing notes (use for progress) |\n{{/if}}\n{{#if mcp}}\n| `notes` | **REPLACES** all notes (use only for initial setup) |\n| `appendNotes` | **APPENDS** to existing notes (use for progress) |\n{{/if}}\n\n---\n\n## Quick Reference\n\n| DON\'T | DO |\n|-------|-----|\n{{#if cli}}\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| `--notes` for progress | `--append-notes` for progress |\n{{/if}}\n{{#if mcp}}\n| Edit .md files directly | Use MCP tools |\n| `notes` for progress | `appendNotes` for progress |\n{{/if}}\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always start/stop timer |\n| Ignore refs | Follow ALL `@task-xxx`, `@doc/xxx`, `@template/xxx` refs |\n\n{{#if mcp}}\n---\n\n## MCP Task Operations\n\nAll task operations are available via MCP:\n\n| Operation | MCP Field |\n|-----------|-----------|\n| Add acceptance criteria | `addAc: ["criterion"]` |\n| Check AC | `checkAc: [1, 2]` (1-based) |\n| Uncheck AC | `uncheckAc: [1]` (1-based) |\n| Remove AC | `removeAc: [1]` (1-based) |\n| Set plan | `plan: "..."` |\n| Set notes | `notes: "..."` |\n| Append notes | `appendNotes: "..."` |\n| Change status | `status: "in-progress"` |\n| Assign | `assignee: "@me"` |\n{{/if}}\n\n---\n\n## Template Syntax Pitfalls\n\nWhen writing `.hbs` templates, **NEVER** create `$` followed by triple-brace - Handlebars interprets triple-brace as unescaped output:\n\n```\n// \u274C WRONG - Parse error!\nthis.logger.log(`Created: $` + `{` + `{` + `{camelCase entity}.id}`);\n\n// \u2705 CORRECT - Add space between ${ and double-brace, use ~ to trim whitespace\nthis.logger.log(`Created: ${ \\{{~camelCase entity~}}.id}`);\n```\n\n| DON\'T | DO |\n|-------|-----|\n| `$` + triple-brace | `${ \\{{~helper~}}}` (space + escaped) |\n\n**Rules:**\n- Add space between `${` and double-brace\n- Use `~` (tilde) to trim whitespace in output\n- Escape literal braces with backslash\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n{{#if cli}}\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n| Replaced notes by mistake | Cannot recover - notes are lost. Use `--append-notes` next time |\n{{/if}}\n{{#if mcp}}\n| Forgot to stop timer | `mcp__knowns__add_time` with duration |\n| Wrong status | `mcp__knowns__update_task` to fix |\n| Task not found | `mcp__knowns__list_tasks` to find ID |\n| Need to uncheck AC | `mcp__knowns__update_task` with `uncheckAc: [N]` |\n| Checked AC too early | `mcp__knowns__update_task` with `uncheckAc: [N]` |\n| Replaced notes by mistake | Cannot recover - notes are lost. Use `appendNotes` next time |\n{{/if}}\n';
+var common_mistakes_default = '# Common Mistakes\n\n{{#if cli}}\n## CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n{{/if}}\n\n## CRITICAL: Notes vs Append Notes\n\n**NEVER use `notes`/`--notes` for progress updates - it REPLACES all existing notes!**\n\n{{#if cli}}\n```bash\n# \u274C WRONG - Destroys audit trail!\nknowns task edit <id> --notes "Done: feature X"\n\n# \u2705 CORRECT - Preserves history\nknowns task edit <id> --append-notes "Done: feature X"\n```\n{{/if}}\n{{#if mcp}}\n```json\n// \u274C WRONG - Destroys audit trail!\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "notes": "Done: feature X"\n})\n\n// \u2705 CORRECT - Preserves history\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "appendNotes": "Done: feature X"\n})\n```\n{{/if}}\n\n| Field | Behavior |\n|-------|----------|\n{{#if cli}}\n| `--notes` | **REPLACES** all notes (use only for initial setup) |\n| `--append-notes` | **APPENDS** to existing notes (use for progress) |\n{{/if}}\n{{#if mcp}}\n| `notes` | **REPLACES** all notes (use only for initial setup) |\n| `appendNotes` | **APPENDS** to existing notes (use for progress) |\n{{/if}}\n\n---\n\n## Quick Reference\n\n| DON\'T | DO |\n|-------|-----|\n{{#if cli}}\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| `--notes` for progress | `--append-notes` for progress |\n{{/if}}\n{{#if mcp}}\n| Edit .md files directly | Use MCP tools |\n| `notes` for progress | `appendNotes` for progress |\n{{/if}}\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always start/stop timer |\n| Skip validation | Run validate before completing |\n| Ignore refs | Follow ALL `@task-xxx`, `@doc/xxx`, `@template/xxx` refs |\n\n{{#if mcp}}\n---\n\n## MCP Task Operations\n\nAll task operations are available via MCP:\n\n| Operation | MCP Field |\n|-----------|-----------|\n| Add acceptance criteria | `addAc: ["criterion"]` |\n| Check AC | `checkAc: [1, 2]` (1-based) |\n| Uncheck AC | `uncheckAc: [1]` (1-based) |\n| Remove AC | `removeAc: [1]` (1-based) |\n| Set plan | `plan: "..."` |\n| Set notes | `notes: "..."` |\n| Append notes | `appendNotes: "..."` |\n| Change status | `status: "in-progress"` |\n| Assign | `assignee: "@me"` |\n{{/if}}\n\n---\n\n## Template Syntax Pitfalls\n\nWhen writing `.hbs` templates, **NEVER** create `$` followed by triple-brace - Handlebars interprets triple-brace as unescaped output:\n\n```\n// \u274C WRONG - Parse error!\nthis.logger.log(`Created: $` + `{` + `{` + `{camelCase entity}.id}`);\n\n// \u2705 CORRECT - Add space between ${ and double-brace, use ~ to trim whitespace\nthis.logger.log(`Created: ${ \\{{~camelCase entity~}}.id}`);\n```\n\n| DON\'T | DO |\n|-------|-----|\n| `$` + triple-brace | `${ \\{{~helper~}}}` (space + escaped) |\n\n**Rules:**\n- Add space between `${` and double-brace\n- Use `~` (tilde) to trim whitespace in output\n- Escape literal braces with backslash\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n{{#if cli}}\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n| Replaced notes by mistake | Cannot recover - notes are lost. Use `--append-notes` next time |\n| Broken refs in task/doc | Run `knowns validate`, fix refs, validate again |\n{{/if}}\n{{#if mcp}}\n| Forgot to stop timer | `mcp__knowns__add_time` with duration |\n| Wrong status | `mcp__knowns__update_task` to fix |\n| Task not found | `mcp__knowns__list_tasks` to find ID |\n| Need to uncheck AC | `mcp__knowns__update_task` with `uncheckAc: [N]` |\n| Checked AC too early | `mcp__knowns__update_task` with `uncheckAc: [N]` |\n| Replaced notes by mistake | Cannot recover - notes are lost. Use `appendNotes` next time |\n| Broken refs in task/doc | Run `mcp__knowns__validate`, fix refs, validate again |\n{{/if}}\n';
 
 // src/instructions/guidelines/unified/context-optimization.md
 var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n{{#if cli}}\n## Output Format\n\n```bash\n# Verbose output\nknowns task 42 --json\n\n# Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n{{/if}}\n\n## Search Before Read\n\n{{#if cli}}\n### CLI\n```bash\n# DON\'T: Read all docs hoping to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\n\n# DO: Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\n// DON\'T: Read all docs hoping to find info\nmcp__knowns__get_doc({ "path": "doc1" })\nmcp__knowns__get_doc({ "path": "doc2" })\n\n// DO: Search first, then read only relevant docs\nmcp__knowns__search_docs({ "query": "authentication" })\nmcp__knowns__get_doc({ "path": "security-patterns" })\n```\n{{/if}}\n\n---\n\n{{#if mcp}}\n## Use Filters\n\n```json\n// DON\'T: List all then filter manually\nmcp__knowns__list_tasks({})\n\n// DO: Use filters in the query\nmcp__knowns__list_tasks({\n  "status": "in-progress",\n  "assignee": "@me"\n})\n```\n\n---\n{{/if}}\n\n## Reading Documents\n\n{{#if cli}}\n### CLI\n**ALWAYS use `--smart`** - auto-handles both small and large docs:\n\n```bash\n# DON\'T: Read without --smart\nknowns doc readme --plain\n\n# DO: Always use --smart\nknowns doc readme --plain --smart\n# Small doc \u2192 full content\n# Large doc \u2192 stats + TOC\n\n# If large, read specific section:\nknowns doc readme --plain --section 3\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n**ALWAYS use `smart: true`** - auto-handles both small and large docs:\n\n```json\n// DON\'T: Read without smart\nmcp__knowns__get_doc({ "path": "readme" })\n\n// DO: Always use smart\nmcp__knowns__get_doc({ "path": "readme", "smart": true })\n// Small doc \u2192 full content\n// Large doc \u2192 stats + TOC\n\n// If large, read specific section:\nmcp__knowns__get_doc({ "path": "readme", "section": "3" })\n```\n{{/if}}\n\n**Behavior:**\n- **\u22642000 tokens**: Returns full content automatically\n- **>2000 tokens**: Returns stats + TOC, then use section parameter\n\n---\n\n## Compact Notes\n\n```bash\n# DON\'T: Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation..."\n\n# DO: Compact notes\nknowns task edit 42 --append-notes "Done: Auth middleware + JWT validation"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t | Do Instead |\n|-------|------------|\n| Re-read files already in context | Reference from memory |\n| List tasks/docs multiple times | List once, remember results |\n| Quote entire file contents | Summarize key points |\n\n---\n\n## Efficient Workflow\n\n| Phase | Context-Efficient Approach |\n|-------|---------------------------|\n| **Research** | Search \u2192 Read only matches |\n| **Planning** | Brief plan, not detailed prose |\n| **Coding** | Read only files being modified |\n| **Notes** | Bullet points, not paragraphs |\n| **Completion** | Summary, not full log |\n\n---\n\n## Quick Rules\n\n{{#if cli}}\n1. **Always `--plain`** - Never use `--json` unless needed\n2. **Always `--smart`** - Auto-handles doc size\n{{/if}}\n{{#if mcp}}\n1. **Always `smart: true`** - Auto-handles doc size\n{{/if}}\n3. **Search first** - Don\'t read all docs hoping to find info\n4. **Read selectively** - Only fetch what you need\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n';
 
 // src/instructions/guidelines/unified/core-rules.md
-var core_rules_default = '# Core Rules\n\n> These rules are NON-NEGOTIABLE. Violating them leads to data corruption and lost work.\n\n---\n\n## The Golden Rule\n\n{{#if mcp}}\n{{#if cli}}\n**If you want to change ANYTHING in a task or doc, use MCP tools (preferred) or CLI commands (fallback). NEVER edit .md files directly.**\n{{else}}\n**If you want to change ANYTHING in a task or doc, use MCP tools. NEVER edit .md files directly.**\n{{/if}}\n{{else}}\n{{#if cli}}\n**If you want to change ANYTHING in a task or doc, use CLI commands. NEVER edit .md files directly.**\n{{/if}}\n{{/if}}\n\n{{#if mcp}}\n---\n\n## Session Initialization (MCP)\n\n**CRITICAL: At the START of every session, run these tools to initialize the project:**\n\n```json\n// Step 1: Detect available projects\nmcp__knowns__detect_projects({})\n\n// Step 2: Set the project you want to work with\nmcp__knowns__set_project({ "projectRoot": "/path/to/project" })\n\n// Step 3: Verify project is set correctly\nmcp__knowns__get_current_project({})\n```\n\n**Why?** The MCP server may not know which project you\'re working in. These tools:\n- `detect_projects` - Scans common workspace directories for Knowns projects\n- `set_project` - Sets the active project for all subsequent operations\n- `get_current_project` - Verifies the current project path\n\n**If you skip this step**, other tools like `list_tasks`, `get_doc`, etc. may fail or work on the wrong project.\n{{/if}}\n\n{{#if cli}}\n---\n\n## CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\n\n# CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n{{/if}}\n\n---\n\n## Quick Reference\n\n| Rule | Description |\n|------|-------------|\n{{#if mcp}}\n{{#if cli}}\n| **MCP Tools (preferred)** | Use MCP tools for ALL operations. Fallback to CLI if needed. NEVER edit .md files directly |\n{{else}}\n| **MCP Tools Only** | Use MCP tools for ALL operations. NEVER edit .md files directly |\n{{/if}}\n{{else}}\n{{#if cli}}\n| **CLI Only** | Use commands for ALL operations. NEVER edit .md files directly |\n{{/if}}\n{{/if}}\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After** | Only mark criteria done AFTER completing work |\n\n{{#if cli}}\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns search "query" --plain\n\n# WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\n```\n{{/if}}\n\n---\n\n## Reference System\n\nTasks, docs, and templates can reference each other:\n\n| Type | Writing (Input) | Reading (Output) |\n|------|-----------------|------------------|\n| Task | `@task-<id>` | `@.knowns/tasks/task-<id>` |\n| Doc | `@doc/<path>` | `@.knowns/docs/<path>.md` |\n| Template | `@template/<name>` | `@.knowns/templates/<name>` |\n\n**Always follow refs recursively** to gather complete context before planning.\n\n---\n\n## Subtasks\n\n{{#if cli}}\n### CLI\n```bash\nknowns task create "Subtask title" --parent 48\n```\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# CORRECT\nknowns task create "Title" --parent 48\n\n# WRONG\nknowns task create "Title" --parent task-48\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\nmcp__knowns__create_task({\n  "title": "Subtask title",\n  "parent": "parent-task-id"\n})\n```\n\n**CRITICAL:** Use raw ID (string) for all MCP tool calls.\n{{/if}}\n';
+var core_rules_default = '# Core Rules\n\n> These rules are NON-NEGOTIABLE. Violating them leads to data corruption and lost work.\n\n---\n\n## The Golden Rule\n\n{{#if mcp}}\n{{#if cli}}\n**If you want to change ANYTHING in a task or doc, use MCP tools (preferred) or CLI commands (fallback). NEVER edit .md files directly.**\n{{else}}\n**If you want to change ANYTHING in a task or doc, use MCP tools. NEVER edit .md files directly.**\n{{/if}}\n{{else}}\n{{#if cli}}\n**If you want to change ANYTHING in a task or doc, use CLI commands. NEVER edit .md files directly.**\n{{/if}}\n{{/if}}\n\n{{#if mcp}}\n---\n\n## Session Initialization (MCP)\n\n**CRITICAL: At the START of every session, run these tools to initialize the project:**\n\n```json\n// Step 1: Detect available projects\nmcp__knowns__detect_projects({})\n\n// Step 2: Set the project you want to work with\nmcp__knowns__set_project({ "projectRoot": "/path/to/project" })\n\n// Step 3: Verify project is set correctly\nmcp__knowns__get_current_project({})\n```\n\n**Why?** The MCP server may not know which project you\'re working in. These tools:\n- `detect_projects` - Scans common workspace directories for Knowns projects\n- `set_project` - Sets the active project for all subsequent operations\n- `get_current_project` - Verifies the current project path\n\n**If you skip this step**, other tools like `list_tasks`, `get_doc`, etc. may fail or work on the wrong project.\n{{/if}}\n\n{{#if cli}}\n---\n\n## CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\n\n# CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n{{/if}}\n\n---\n\n## Quick Reference\n\n| Rule | Description |\n|------|-------------|\n{{#if mcp}}\n{{#if cli}}\n| **MCP Tools (preferred)** | Use MCP tools for ALL operations. Fallback to CLI if needed. NEVER edit .md files directly |\n{{else}}\n| **MCP Tools Only** | Use MCP tools for ALL operations. NEVER edit .md files directly |\n{{/if}}\n{{else}}\n{{#if cli}}\n| **CLI Only** | Use commands for ALL operations. NEVER edit .md files directly |\n{{/if}}\n{{/if}}\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After** | Only mark criteria done AFTER completing work |\n| **Validate** | Run validate before completing task |\n\n{{#if cli}}\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns search "query" --plain\n\n# WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\n```\n{{/if}}\n\n---\n\n## Reference System\n\nTasks, docs, and templates can reference each other:\n\n| Type | Writing (Input) | Reading (Output) |\n|------|-----------------|------------------|\n| Task | `@task-<id>` | `@.knowns/tasks/task-<id>` |\n| Doc | `@doc/<path>` | `@.knowns/docs/<path>.md` |\n| Template | `@template/<name>` | `@.knowns/templates/<name>` |\n\n**Always follow refs recursively** to gather complete context before planning.\n\n---\n\n## Subtasks\n\n{{#if cli}}\n### CLI\n```bash\nknowns task create "Subtask title" --parent 48\n```\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# CORRECT\nknowns task create "Title" --parent 48\n\n# WRONG\nknowns task create "Title" --parent task-48\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\nmcp__knowns__create_task({\n  "title": "Subtask title",\n  "parent": "parent-task-id"\n})\n```\n\n**CRITICAL:** Use raw ID (string) for all MCP tool calls.\n{{/if}}\n';
 
 // src/instructions/guidelines/unified/workflow-completion.md
-var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n{{#if cli}}\n### CLI\n| Requirement | Command |\n|-------------|---------|\n| All AC checked | `knowns task edit <id> --check-ac N` |\n| Notes added | `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | `knowns time stop` |\n| Status = done | `knowns task edit <id> -s done` |\n| Tests pass | Run test suite |\n{{/if}}\n{{#if mcp}}\n### MCP\n| Requirement | How |\n|-------------|-----|\n| All AC checked | `mcp__knowns__update_task` with `checkAc` |\n| Notes added | `mcp__knowns__update_task` with `notes` |\n| Timer stopped | `mcp__knowns__stop_time` |\n| Status = done | `mcp__knowns__update_task` with `status: "done"` |\n| Tests pass | Run test suite |\n{{/if}}\n\n---\n\n## Completion Steps\n\n{{#if cli}}\n### CLI\n```bash\n# 1. Verify all AC are checked\nknowns task <id> --plain\n\n# 2. Add implementation notes\nknowns task edit <id> --notes $\'## Summary\nWhat was done and key decisions.\'\n\n# 3. Stop timer (REQUIRED!)\nknowns time stop\n\n# 4. Mark done\nknowns task edit <id> -s done\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\n// 1. Verify all AC are checked\nmcp__knowns__get_task({ "taskId": "<id>" })\n\n// 2. Add implementation notes\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "notes": "## Summary\\nWhat was done and key decisions."\n})\n\n// 3. Stop timer (REQUIRED!)\nmcp__knowns__stop_time({ "taskId": "<id>" })\n\n// 4. Mark done\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "status": "done"\n})\n```\n{{/if}}\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n{{#if cli}}\n### CLI\n```bash\nknowns task edit <id> -s in-progress    # Reopen\nknowns time start <id>                   # Restart timer\nknowns task edit <id> --ac "Fix: description"\nknowns task edit <id> --append-notes "Reopened: reason"\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\n// 1. Reopen task\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "status": "in-progress"\n})\n\n// 2. Restart timer\nmcp__knowns__start_time({ "taskId": "<id>" })\n\n// 3. Add AC for the fix\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "addAc": ["Fix: description"],\n  "appendNotes": "Reopened: reason"\n})\n```\n{{/if}}\n\nThen follow completion steps again.\n\n---\n\n## Checklist\n\n{{#if cli}}\n### CLI\n- [ ] All AC checked (`--check-ac`)\n- [ ] Notes added (`--notes`)\n- [ ] Timer stopped (`time stop`)\n- [ ] Tests pass\n- [ ] Status = done (`-s done`)\n{{/if}}\n{{#if mcp}}\n### MCP\n- [ ] All AC checked (`checkAc`)\n- [ ] Notes added (`notes`)\n- [ ] Timer stopped (`mcp__knowns__stop_time`)\n- [ ] Tests pass\n- [ ] Status = done (`mcp__knowns__update_task`)\n{{/if}}\n';
+var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n{{#if cli}}\n### CLI\n| Requirement | Command |\n|-------------|---------|\n| All AC checked | `knowns task edit <id> --check-ac N` |\n| Notes added | `knowns task edit <id> --notes "Summary"` |\n| Refs validated | `knowns validate` |\n| Timer stopped | `knowns time stop` |\n| Status = done | `knowns task edit <id> -s done` |\n| Tests pass | Run test suite |\n{{/if}}\n{{#if mcp}}\n### MCP\n| Requirement | How |\n|-------------|-----|\n| All AC checked | `mcp__knowns__update_task` with `checkAc` |\n| Notes added | `mcp__knowns__update_task` with `notes` |\n| Refs validated | `mcp__knowns__validate` |\n| Timer stopped | `mcp__knowns__stop_time` |\n| Status = done | `mcp__knowns__update_task` with `status: "done"` |\n| Tests pass | Run test suite |\n{{/if}}\n\n---\n\n## Completion Steps\n\n{{#if cli}}\n### CLI\n```bash\n# 1. Verify all AC are checked\nknowns task <id> --plain\n\n# 2. Add implementation notes\nknowns task edit <id> --notes $\'## Summary\nWhat was done and key decisions.\'\n\n# 3. Validate refs (catch broken @doc/ @task- refs)\nknowns validate\n\n# 4. Stop timer (REQUIRED!)\nknowns time stop\n\n# 5. Mark done\nknowns task edit <id> -s done\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\n// 1. Verify all AC are checked\nmcp__knowns__get_task({ "taskId": "<id>" })\n\n// 2. Add implementation notes\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "notes": "## Summary\\nWhat was done and key decisions."\n})\n\n// 3. Validate refs (catch broken @doc/ @task- refs)\nmcp__knowns__validate({})\n\n// 4. Stop timer (REQUIRED!)\nmcp__knowns__stop_time({ "taskId": "<id>" })\n\n// 5. Mark done\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "status": "done"\n})\n```\n{{/if}}\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n{{#if cli}}\n### CLI\n```bash\nknowns task edit <id> -s in-progress    # Reopen\nknowns time start <id>                   # Restart timer\nknowns task edit <id> --ac "Fix: description"\nknowns task edit <id> --append-notes "Reopened: reason"\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\n// 1. Reopen task\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "status": "in-progress"\n})\n\n// 2. Restart timer\nmcp__knowns__start_time({ "taskId": "<id>" })\n\n// 3. Add AC for the fix\nmcp__knowns__update_task({\n  "taskId": "<id>",\n  "addAc": ["Fix: description"],\n  "appendNotes": "Reopened: reason"\n})\n```\n{{/if}}\n\nThen follow completion steps again.\n\n---\n\n## Checklist\n\n{{#if cli}}\n### CLI\n- [ ] All AC checked (`--check-ac`)\n- [ ] Notes added (`--notes`)\n- [ ] Refs validated (`knowns validate`)\n- [ ] Timer stopped (`time stop`)\n- [ ] Tests pass\n- [ ] Status = done (`-s done`)\n{{/if}}\n{{#if mcp}}\n### MCP\n- [ ] All AC checked (`checkAc`)\n- [ ] Notes added (`notes`)\n- [ ] Refs validated (`mcp__knowns__validate`)\n- [ ] Timer stopped (`mcp__knowns__stop_time`)\n- [ ] Tests pass\n- [ ] Status = done (`mcp__knowns__update_task`)\n{{/if}}\n';
 
 // src/instructions/guidelines/unified/workflow-creation.md
 var workflow_creation_default = '# Task Creation\n\n## Before Creating\n\n{{#if cli}}\n### CLI\n```bash\n# Search for existing tasks first\nknowns search "keyword" --type task --plain\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\n// Search for existing tasks first\nmcp__knowns__search_tasks({ "query": "keyword" })\n```\n{{/if}}\n\n---\n\n## Create Task\n\n{{#if cli}}\n### CLI\n```bash\nknowns task create "Clear title (WHAT)" \\\n  -d "Description (WHY)" \\\n  --ac "Outcome 1" \\\n  --ac "Outcome 2" \\\n  --priority medium \\\n  -l "labels"\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\nmcp__knowns__create_task({\n  "title": "Clear title (WHAT)",\n  "description": "Description (WHY). Related: @doc/security-patterns",\n  "priority": "medium",\n  "labels": ["feature", "auth"]\n})\n```\n\n**Note:** Add acceptance criteria after creation:\n```bash\nknowns task edit <id> --ac "Outcome 1" --ac "Outcome 2"\n```\n{{/if}}\n\n---\n\n## Quality Guidelines\n\n### Title\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout |\n\n### Description\nExplain WHY. Include doc refs: `@doc/security-patterns`\n\n### Acceptance Criteria\n**Outcome-focused, NOT implementation steps:**\n\n| Bad | Good |\n|-----|------|\n| Add handleLogin() function | User can login |\n| Use bcrypt | Passwords are hashed |\n| Add try-catch | Errors return proper HTTP codes |\n\n---\n\n## Subtasks\n\n{{#if cli}}\n### CLI\n```bash\nknowns task create "Parent task"\nknowns task create "Subtask" --parent 48  # Raw ID only!\n```\n{{/if}}\n{{#if mcp}}\n### MCP\n```json\n// Create parent first\nmcp__knowns__create_task({ "title": "Parent task" })\n\n// Then create subtask with parent ID\nmcp__knowns__create_task({\n  "title": "Subtask",\n  "parent": "parent-task-id"\n})\n```\n{{/if}}\n\n---\n\n## Anti-Patterns\n\n- Too many AC in one task -> Split into multiple tasks\n- Implementation steps as AC -> Write outcomes instead\n- Skip search -> Always check existing tasks first\n';
@@ -60015,7 +60023,7 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
     console.log(source_default.cyan("Get started:"));
     console.log(source_default.gray('  knowns task create "My first task"'));
     if (hasSkillsPlatform) {
-      console.log(source_default.gray("  Use /knowns.init to start a session"));
+      console.log(source_default.gray("  Use /kn:init to start a session"));
     }
     if (hasNonSkillsPlatform) {
       console.log(source_default.gray("  See AGENTS.md for full AI guidelines"));
@@ -60681,6 +60689,9 @@ async function formatTask(task, fileStore, plain = false) {
     if (task.subtasks.length > 0) {
       output2.push(`Subtasks: ${task.subtasks.join(", ")}`);
     }
+    if (task.spec) {
+      output2.push(`Spec: @doc/${task.spec}`);
+    }
     if (task.timeSpent > 0) {
       const hours = Math.floor(task.timeSpent / 3600);
       const minutes = Math.floor(task.timeSpent % 3600 / 60);
@@ -60746,6 +60757,9 @@ async function formatTask(task, fileStore, plain = false) {
   if (task.parent) {
     output.push(`${source_default.gray("Parent:")} ${source_default.yellow(task.parent)}`);
   }
+  if (task.spec) {
+    output.push(`${source_default.gray("Spec:")} ${source_default.magenta(`@doc/${task.spec}`)}`);
+  }
   output.push("");
   if (task.description) {
     output.push(source_default.bold("Description:"));
@@ -61004,7 +61018,7 @@ function formatTaskList(tasks, plain = false) {
   }
   return output.join("\n");
 }
-var createCommand2 = new Command("create").description("Create a new task").argument("<title>", "Task title").option("-d, --description <text>", "Task description").option("--ac <criterion>", "Acceptance criterion (can be used multiple times)", collect, []).option("-l, --labels <labels>", "Comma-separated labels").option("-a, --assignee <name>", "Assignee (@username)").option("--priority <level>", "Priority: low, medium, high", "medium").option("-s, --status <status>", "Status", "todo").option("--parent <id>", "Parent task ID for subtasks").action(
+var createCommand2 = new Command("create").description("Create a new task").argument("<title>", "Task title").option("-d, --description <text>", "Task description").option("--ac <criterion>", "Acceptance criterion (can be used multiple times)", collect, []).option("-l, --labels <labels>", "Comma-separated labels").option("-a, --assignee <name>", "Assignee (@username)").option("--priority <level>", "Priority: low, medium, high", "medium").option("-s, --status <status>", "Status", "todo").option("--parent <id>", "Parent task ID for subtasks").option("--spec <path>", "Link to spec document (e.g., specs/user-auth)").action(
   async (title, options2) => {
     try {
       const fileStore = getFileStore();
@@ -61033,6 +61047,7 @@ var createCommand2 = new Command("create").description("Create a new task").argu
         assignee: options2.assignee,
         labels,
         parent: options2.parent,
+        spec: options2.spec,
         acceptanceCriteria,
         subtasks: [],
         timeSpent: 0,
@@ -61052,7 +61067,7 @@ var createCommand2 = new Command("create").description("Create a new task").argu
     }
   }
 );
-var listCommand = new Command("list").description("List all tasks").option("--status <status>", "Filter by status").option("--assignee <name>", "Filter by assignee").option("-l, --labels <labels>", "Filter by labels (comma-separated)").option("--priority <level>", "Filter by priority").option("--tree", "Display tasks as tree hierarchy").option("--plain", "Plain text output for AI").action(
+var listCommand = new Command("list").description("List all tasks").option("--status <status>", "Filter by status").option("--assignee <name>", "Filter by assignee").option("-l, --labels <labels>", "Filter by labels (comma-separated)").option("--priority <level>", "Filter by priority").option("--spec <path>", "Filter by spec document path").option("--tree", "Display tasks as tree hierarchy").option("--plain", "Plain text output for AI").action(
   async (options2) => {
     try {
       const fileStore = getFileStore();
@@ -61070,6 +61085,9 @@ var listCommand = new Command("list").description("List all tasks").option("--st
         const filterLabels = options2.labels.split(",").map((l) => l.trim());
         tasks = tasks.filter((t) => filterLabels.some((label) => t.labels.includes(label)));
       }
+      if (options2.spec) {
+        tasks = tasks.filter((t) => t.spec === options2.spec);
+      }
       if (options2.tree) {
         console.log(await formatTaskTree(tasks, fileStore, options2.plain));
       } else {
@@ -61121,7 +61139,7 @@ var editCommand = new Command("edit").description("Edit task properties").argume
   "Remove acceptance criterion by index (1-based, can be used multiple times)",
   collectNumbers,
   []
-).option("--plan <text>", "Implementation plan").option("--notes <text>", "Implementation notes (replaces existing)").option("--append-notes <text>", "Append to implementation notes").action(
+).option("--plan <text>", "Implementation plan").option("--notes <text>", "Implementation notes (replaces existing)").option("--append-notes <text>", "Append to implementation notes").option("--spec <path>", "Link to spec document (use 'none' to remove)").action(
   async (rawId, options2) => {
     try {
       const id = normalizeTaskId(rawId);
@@ -61179,6 +61197,13 @@ var editCommand = new Command("edit").description("Edit task properties").argume
           updates.parent = options2.parent;
         }
       }
+      if (options2.spec !== void 0) {
+        if (options2.spec.toLowerCase() === "none") {
+          updates.spec = void 0;
+        } else {
+          updates.spec = options2.spec;
+        }
+      }
       if (options2.ac.length > 0 || options2.checkAc.length > 0 || options2.uncheckAc.length > 0 || options2.removeAc.length > 0) {
         const criteria = [...task.acceptanceCriteria];
         for (const text of options2.ac) {
@@ -61247,6 +61272,13 @@ var editCommand = new Command("edit").description("Edit task properties").argume
       if (options2.plan) changes.push("updated implementation plan");
       if (options2.notes) changes.push("updated implementation notes");
       if (options2.appendNotes) changes.push("appended to implementation notes");
+      if (options2.spec !== void 0) {
+        if (options2.spec.toLowerCase() === "none") {
+          changes.push("spec removed");
+        } else {
+          changes.push(`spec \u2192 ${options2.spec}`);
+        }
+      }
       if (changes.length > 0) {
         console.log(source_default.gray(`  ${changes.join(", ")}`));
       }
@@ -64674,17 +64706,17 @@ timeCommand.addCommand(addCommand);
 timeCommand.addCommand(reportCommand);
 
 // src/commands/browser.ts
-import { existsSync as existsSync24 } from "node:fs";
-import { mkdir as mkdir14, readFile as readFile17, writeFile as writeFile12 } from "node:fs/promises";
-import { join as join28 } from "node:path";
+import { existsSync as existsSync26 } from "node:fs";
+import { mkdir as mkdir14, readFile as readFile19, writeFile as writeFile13 } from "node:fs/promises";
+import { join as join30 } from "node:path";
 
 // src/server/index.ts
 import { spawn } from "node:child_process";
-import { existsSync as existsSync23, realpathSync as realpathSync2 } from "node:fs";
-import { basename as basename3, dirname as dirname7, join as join27 } from "node:path";
+import { existsSync as existsSync25, realpathSync as realpathSync2 } from "node:fs";
+import { basename as basename3, dirname as dirname7, join as join29 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 var import_cors = __toESM(require_lib5(), 1);
-var import_express12 = __toESM(require_express2(), 1);
+var import_express13 = __toESM(require_express2(), 1);
 
 // src/server/middleware/error-handler.ts
 function errorHandler(err, _req, res, _next) {
@@ -64693,7 +64725,7 @@ function errorHandler(err, _req, res, _next) {
 }
 
 // src/server/routes/index.ts
-var import_express10 = __toESM(require_express2(), 1);
+var import_express11 = __toESM(require_express2(), 1);
 
 // src/server/routes/activities.ts
 var import_express = __toESM(require_express2(), 1);
@@ -65232,8 +65264,8 @@ var NpmProvider = class extends ImportProvider {
     try {
       const packageJsonPath = join16(tempDir, "package.json");
       if (existsSync13(packageJsonPath)) {
-        const { readFile: readFile25 } = await import("node:fs/promises");
-        const content = await readFile25(packageJsonPath, "utf-8");
+        const { readFile: readFile29 } = await import("node:fs/promises");
+        const content = await readFile29(packageJsonPath, "utf-8");
         const pkg = JSON.parse(content);
         if (pkg.version) {
           metadata.version = pkg.version;
@@ -67333,6 +67365,53 @@ function createSearchRoutes(ctx) {
 
 // src/server/routes/tasks.ts
 var import_express7 = __toESM(require_express2(), 1);
+var import_gray_matter7 = __toESM(require_gray_matter(), 1);
+import { existsSync as existsSync19 } from "node:fs";
+import { readFile as readFile14, writeFile as writeFile9 } from "node:fs/promises";
+import { join as join23 } from "node:path";
+function normalizeText(text) {
+  return text.toLowerCase().replace(/^(ac-?\d+:?\s*|#\d+\s*)/i, "").replace(/[^\w\s]/g, " ").replace(/\s+/g, " ").trim();
+}
+function textSimilarity(a, b) {
+  const wordsA = new Set(normalizeText(a).split(" ").filter(Boolean));
+  const wordsB = new Set(normalizeText(b).split(" ").filter(Boolean));
+  if (wordsA.size === 0 || wordsB.size === 0) return 0;
+  const intersection2 = [...wordsA].filter((w) => wordsB.has(w)).length;
+  const union2 = (/* @__PURE__ */ new Set([...wordsA, ...wordsB])).size;
+  return intersection2 / union2;
+}
+async function syncSpecACs(task, projectRoot, broadcast2) {
+  if (!projectRoot) return;
+  if (!task.spec) return;
+  const completedACs = task.acceptanceCriteria.filter((ac) => ac.completed);
+  if (completedACs.length === 0) return;
+  const specPath = join23(projectRoot, ".knowns", "docs", `${task.spec}.md`);
+  if (!existsSync19(specPath)) return;
+  try {
+    const content = await readFile14(specPath, "utf-8");
+    const { data: frontmatter, content: docContent } = (0, import_gray_matter7.default)(content);
+    let updatedContent = docContent;
+    let hasChanges = false;
+    const acPattern = /^([ \t]*)-\s*\[\s*\]\s*(.+)$/gm;
+    updatedContent = docContent.replace(acPattern, (match2, indent, acText) => {
+      for (const taskAC of completedACs) {
+        const similarity = textSimilarity(taskAC.text, acText);
+        if (similarity >= 0.5) {
+          hasChanges = true;
+          return `${indent}- [x] ${acText}`;
+        }
+      }
+      return match2;
+    });
+    if (hasChanges) {
+      const newFileContent = import_gray_matter7.default.stringify(updatedContent, frontmatter);
+      await writeFile9(specPath, newFileContent, "utf-8");
+      broadcast2({ type: "docs:updated", path: task.spec });
+    }
+  } catch (err) {
+    console.error("Error syncing spec ACs:", err);
+  }
+}
 function createTaskRoutes(ctx) {
   const router = (0, import_express7.Router)();
   const { store, broadcast: broadcast2 } = ctx;
@@ -67399,12 +67478,30 @@ function createTaskRoutes(ctx) {
       const updates = req.body;
       const task = await store.updateTask(req.params.id, updates);
       broadcast2({ type: "tasks:updated", task });
+      if (updates.acceptanceCriteria || updates.status === "done") {
+        await syncSpecACs(task, store.projectRoot, broadcast2);
+      }
       res.json(task);
     } catch (error48) {
       console.error("Error updating task:", error48);
       res.status(500).json({ error: String(error48) });
     }
   });
+  router.post("/sync-spec-acs", async (_req, res) => {
+    try {
+      const tasks = await store.getAllTasks();
+      const doneTasks = tasks.filter((t) => t.status === "done" && t.spec);
+      let syncedCount = 0;
+      for (const task of doneTasks) {
+        await syncSpecACs(task, store.projectRoot, broadcast2);
+        syncedCount++;
+      }
+      res.json({ success: true, synced: syncedCount });
+    } catch (error48) {
+      console.error("Error syncing spec ACs:", error48);
+      res.status(500).json({ error: String(error48) });
+    }
+  });
   router.post("/:id/archive", async (req, res) => {
     try {
       const task = await store.archiveTask(req.params.id);
@@ -67430,9 +67527,9 @@ function createTaskRoutes(ctx) {
 
 // src/server/routes/templates.ts
 var import_express8 = __toESM(require_express2(), 1);
-import { existsSync as existsSync21 } from "node:fs";
-import { mkdir as mkdir13, writeFile as writeFile10 } from "node:fs/promises";
-import { join as join25 } from "node:path";
+import { existsSync as existsSync22 } from "node:fs";
+import { mkdir as mkdir13, writeFile as writeFile11 } from "node:fs/promises";
+import { join as join26 } from "node:path";
 
 // node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -81280,9 +81377,9 @@ function safeValidateTemplateConfig(data) {
 
 // src/codegen/parser.ts
 var import_yaml = __toESM(require_dist3(), 1);
-import { existsSync as existsSync19 } from "node:fs";
-import { readFile as readFile14, readdir as readdir10 } from "node:fs/promises";
-import { join as join23 } from "node:path";
+import { existsSync as existsSync20 } from "node:fs";
+import { readFile as readFile15, readdir as readdir10 } from "node:fs/promises";
+import { join as join24 } from "node:path";
 var CONFIG_FILENAME = "_template.yaml";
 var TEMPLATE_EXTENSION = ".hbs";
 var TemplateParseError = class extends Error {
@@ -81294,16 +81391,16 @@ var TemplateParseError = class extends Error {
   }
 };
 async function loadTemplate(templateDir) {
-  if (!existsSync19(templateDir)) {
+  if (!existsSync20(templateDir)) {
     throw new TemplateParseError(`Template directory not found: ${templateDir}`);
   }
-  const configPath = join23(templateDir, CONFIG_FILENAME);
-  if (!existsSync19(configPath)) {
+  const configPath = join24(templateDir, CONFIG_FILENAME);
+  if (!existsSync20(configPath)) {
     throw new TemplateParseError(`Template config not found: ${CONFIG_FILENAME}`, void 0, [
       `Expected file at: ${configPath}`
     ]);
   }
-  const configContent = await readFile14(configPath, "utf-8");
+  const configContent = await readFile15(configPath, "utf-8");
   let rawConfig;
   try {
     rawConfig = (0, import_yaml.parse)(configContent);
@@ -81329,9 +81426,9 @@ async function findTemplateFiles(dir, base = "") {
   const files = [];
   const entries = await readdir10(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const relativePath = base ? join23(base, entry.name) : entry.name;
+    const relativePath = base ? join24(base, entry.name) : entry.name;
     if (entry.isDirectory()) {
-      const subFiles = await findTemplateFiles(join23(dir, entry.name), relativePath);
+      const subFiles = await findTemplateFiles(join24(dir, entry.name), relativePath);
       files.push(...subFiles);
     } else if (entry.name.endsWith(TEMPLATE_EXTENSION)) {
       files.push(relativePath);
@@ -81340,28 +81437,42 @@ async function findTemplateFiles(dir, base = "") {
   return files;
 }
 async function listTemplates(templatesDir) {
-  if (!existsSync19(templatesDir)) {
+  if (!existsSync20(templatesDir)) {
     return [];
   }
   const entries = await readdir10(templatesDir, { withFileTypes: true });
   const templates = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const configPath = join23(templatesDir, entry.name, CONFIG_FILENAME);
-    if (!existsSync19(configPath)) continue;
+    const configPath = join24(templatesDir, entry.name, CONFIG_FILENAME);
+    if (!existsSync20(configPath)) continue;
     try {
-      const loaded = await loadTemplate(join23(templatesDir, entry.name));
+      const loaded = await loadTemplate(join24(templatesDir, entry.name));
       templates.push(loaded.config);
     } catch {
     }
   }
   return templates;
 }
+async function getTemplateConfig(templateDir) {
+  const configPath = join24(templateDir, CONFIG_FILENAME);
+  if (!existsSync20(configPath)) {
+    return null;
+  }
+  try {
+    const content = await readFile15(configPath, "utf-8");
+    const raw = (0, import_yaml.parse)(content);
+    const result = safeValidateTemplateConfig(raw);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
 
 // src/codegen/runner.ts
-import { existsSync as existsSync20 } from "node:fs";
-import { appendFile, mkdir as mkdir12, readFile as readFile15, writeFile as writeFile9 } from "node:fs/promises";
-import { dirname as dirname6, join as join24 } from "node:path";
+import { existsSync as existsSync21 } from "node:fs";
+import { appendFile, mkdir as mkdir12, readFile as readFile16, writeFile as writeFile10 } from "node:fs/promises";
+import { dirname as dirname6, join as join25 } from "node:path";
 
 // node_modules/@isaacs/balanced-match/dist/esm/index.js
 var balanced = (a, b, str2) => {
@@ -84343,7 +84454,7 @@ var LRUCache = class _LRUCache {
 // node_modules/path-scurry/dist/esm/index.js
 import { posix as posix2, win32 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { lstatSync, readdir as readdirCB, readdirSync, readlinkSync, realpathSync as rps } from "fs";
+import { lstatSync, readdir as readdirCB, readdirSync as readdirSync2, readlinkSync, realpathSync as rps } from "fs";
 import * as actualFS from "node:fs";
 import { lstat, readdir as readdir11, readlink as readlink2, realpath } from "node:fs/promises";
 
@@ -85230,7 +85341,7 @@ var realpathSync = rps.native;
 var defaultFS = {
   lstatSync,
   readdir: readdirCB,
-  readdirSync,
+  readdirSync: readdirSync2,
   readlinkSync,
   realpathSync,
   promises: {
@@ -88134,10 +88245,10 @@ async function executeAction(action, template, context, options2, result) {
   }
 }
 async function executeAddAction(action, template, context, options2, result) {
-  const sourcePath = join24(template.templateDir, action.template);
+  const sourcePath = join25(template.templateDir, action.template);
   const destRelative = renderPath(action.path, context);
-  const destPath = join24(options2.projectRoot, template.config.destination || "", destRelative);
-  if (existsSync20(destPath)) {
+  const destPath = join25(options2.projectRoot, template.config.destination || "", destRelative);
+  if (existsSync21(destPath)) {
     if (action.skipIfExists && !options2.force) {
       result.skipped.push(destRelative);
       return;
@@ -88150,19 +88261,19 @@ async function executeAddAction(action, template, context, options2, result) {
   const content = await renderFile(sourcePath, context);
   if (!options2.dryRun) {
     await ensureDir(dirname6(destPath));
-    await writeFile9(destPath, content, "utf-8");
+    await writeFile10(destPath, content, "utf-8");
   }
   result.created.push(destRelative);
 }
 async function executeAddManyAction(action, template, context, options2, result) {
-  const sourceDir = join24(template.templateDir, action.source);
+  const sourceDir = join25(template.templateDir, action.source);
   const pattern = action.globPattern || "**/*.hbs";
   const files = await glob2(pattern, { cwd: sourceDir, nodir: true });
   for (const file3 of files) {
-    const sourcePath = join24(sourceDir, file3);
-    const destRelative = renderPath(join24(action.destination, file3), context);
-    const destPath = join24(options2.projectRoot, template.config.destination || "", destRelative);
-    if (existsSync20(destPath)) {
+    const sourcePath = join25(sourceDir, file3);
+    const destRelative = renderPath(join25(action.destination, file3), context);
+    const destPath = join25(options2.projectRoot, template.config.destination || "", destRelative);
+    if (existsSync21(destPath)) {
       if (action.skipIfExists && !options2.force) {
         result.skipped.push(destRelative);
         continue;
@@ -88175,17 +88286,17 @@ async function executeAddManyAction(action, template, context, options2, result)
     const content = await renderFile(sourcePath, context);
     if (!options2.dryRun) {
       await ensureDir(dirname6(destPath));
-      await writeFile9(destPath, content, "utf-8");
+      await writeFile10(destPath, content, "utf-8");
     }
     result.created.push(destRelative);
   }
 }
 async function executeModifyAction(action, context, options2, result) {
-  const filePath = join24(options2.projectRoot, renderPath(action.path, context));
-  if (!existsSync20(filePath)) {
+  const filePath = join25(options2.projectRoot, renderPath(action.path, context));
+  if (!existsSync21(filePath)) {
     throw new Error(`Cannot modify: file not found: ${action.path}`);
   }
-  const content = await readFile15(filePath, "utf-8");
+  const content = await readFile16(filePath, "utf-8");
   const replacement = renderString(action.template, context);
   const pattern = new RegExp(action.pattern, "g");
   const newContent = content.replace(pattern, replacement);
@@ -88194,15 +88305,15 @@ async function executeModifyAction(action, context, options2, result) {
     return;
   }
   if (!options2.dryRun) {
-    await writeFile9(filePath, newContent, "utf-8");
+    await writeFile10(filePath, newContent, "utf-8");
   }
   result.modified.push(action.path);
 }
 async function executeAppendAction(action, context, options2, result) {
-  const filePath = join24(options2.projectRoot, renderPath(action.path, context));
+  const filePath = join25(options2.projectRoot, renderPath(action.path, context));
   const contentToAppend = renderString(action.template, context);
-  if (action.unique && existsSync20(filePath)) {
-    const existingContent = await readFile15(filePath, "utf-8");
+  if (action.unique && existsSync21(filePath)) {
+    const existingContent = await readFile16(filePath, "utf-8");
     if (existingContent.includes(contentToAppend.trim())) {
       result.skipped.push(action.path);
       return;
@@ -88212,20 +88323,20 @@ async function executeAppendAction(action, context, options2, result) {
   const fullContent = separator + contentToAppend;
   if (!options2.dryRun) {
     await ensureDir(dirname6(filePath));
-    if (existsSync20(filePath)) {
+    if (existsSync21(filePath)) {
       await appendFile(filePath, fullContent, "utf-8");
     } else {
-      await writeFile9(filePath, contentToAppend, "utf-8");
+      await writeFile10(filePath, contentToAppend, "utf-8");
     }
   }
-  if (existsSync20(filePath)) {
+  if (existsSync21(filePath)) {
     result.modified.push(action.path);
   } else {
     result.created.push(action.path);
   }
 }
 async function ensureDir(dir) {
-  if (!existsSync20(dir)) {
+  if (!existsSync21(dir)) {
     await mkdir12(dir, { recursive: true });
   }
 }
@@ -88258,7 +88369,7 @@ function countFileActions(actions) {
 function createTemplateRoutes(ctx) {
   const router = (0, import_express8.Router)();
   const { store, broadcast: broadcast2 } = ctx;
-  const templatesDir = join25(store.projectRoot, ".knowns", "templates");
+  const templatesDir = join26(store.projectRoot, ".knowns", "templates");
   router.get("/", async (_req, res) => {
     try {
       const allTemplates = await listAllTemplates(store.projectRoot);
@@ -88379,8 +88490,8 @@ function createTemplateRoutes(ctx) {
           context[prompt.name] = prompt.initial;
         }
       }
-      const templatePath = join25(template.templateDir, templateFile);
-      if (!existsSync21(templatePath)) {
+      const templatePath = join26(template.templateDir, templateFile);
+      if (!existsSync22(templatePath)) {
         res.status(404).json({ error: `Template file not found: ${templateFile}` });
         return;
       }
@@ -88407,11 +88518,11 @@ function createTemplateRoutes(ctx) {
         res.status(400).json({ error: "Template name is required" });
         return;
       }
-      if (!existsSync21(templatesDir)) {
+      if (!existsSync22(templatesDir)) {
         await mkdir13(templatesDir, { recursive: true });
       }
-      const templateDir = join25(templatesDir, name);
-      if (existsSync21(templateDir)) {
+      const templateDir = join26(templatesDir, name);
+      if (existsSync22(templateDir)) {
         res.status(409).json({ error: `Template "${name}" already exists` });
         return;
       }
@@ -88441,7 +88552,7 @@ messages:
   success: |
     \u2713 Created {{name}}!
 `;
-      await writeFile10(join25(templateDir, "_template.yaml"), configContent, "utf-8");
+      await writeFile11(join26(templateDir, "_template.yaml"), configContent, "utf-8");
       const exampleTemplate = `/**
  * {{pascalCase name}}
  * Generated from ${name} template
@@ -88451,7 +88562,7 @@ export function {{camelCase name}}() {
   console.log("Hello from {{name}}!");
 }
 `;
-      await writeFile10(join25(templateDir, "example.ts.hbs"), exampleTemplate, "utf-8");
+      await writeFile11(join26(templateDir, "example.ts.hbs"), exampleTemplate, "utf-8");
       broadcast2({ type: "templates:created", template: name });
       res.status(201).json({
         success: true,
@@ -88512,18 +88623,18 @@ export function {{camelCase name}}() {
 
 // src/server/routes/time.ts
 var import_express9 = __toESM(require_express2(), 1);
-import { existsSync as existsSync22 } from "node:fs";
-import { readFile as readFile16, writeFile as writeFile11 } from "node:fs/promises";
-import { join as join26 } from "node:path";
+import { existsSync as existsSync23 } from "node:fs";
+import { readFile as readFile17, writeFile as writeFile12 } from "node:fs/promises";
+import { join as join27 } from "node:path";
 function createTimeRoutes(ctx) {
   const router = (0, import_express9.Router)();
   const { store, broadcast: broadcast2 } = ctx;
-  const timePath = join26(store.projectRoot, ".knowns", "time.json");
+  const timePath = join27(store.projectRoot, ".knowns", "time.json");
   async function loadTimeData3() {
-    if (!existsSync22(timePath)) {
+    if (!existsSync23(timePath)) {
       return { active: [] };
     }
-    const content = await readFile16(timePath, "utf-8");
+    const content = await readFile17(timePath, "utf-8");
     const data = JSON.parse(content);
     if (data.active && !Array.isArray(data.active)) {
       return { active: [data.active] };
@@ -88534,7 +88645,7 @@ function createTimeRoutes(ctx) {
     return data;
   }
   async function saveTimeData3(data) {
-    await writeFile11(timePath, JSON.stringify(data, null, 2), "utf-8");
+    await writeFile12(timePath, JSON.stringify(data, null, 2), "utf-8");
   }
   async function enrichTimers(timers) {
     return Promise.all(
@@ -88766,9 +88877,126 @@ function createTimeRoutes(ctx) {
   return router;
 }
 
+// src/server/routes/validate.ts
+var import_express10 = __toESM(require_express2(), 1);
+var import_gray_matter8 = __toESM(require_gray_matter(), 1);
+import { existsSync as existsSync24 } from "node:fs";
+import { readFile as readFile18, readdir as readdir12 } from "node:fs/promises";
+import { join as join28 } from "node:path";
+function createValidateRoutes(ctx) {
+  const router = (0, import_express10.Router)();
+  const { store } = ctx;
+  router.get("/sdd", async (_req, res) => {
+    try {
+      const tasks = await store.getAllTasks();
+      const docsDir = join28(store.projectRoot, ".knowns", "docs");
+      const stats = {
+        specs: { total: 0, approved: 0, draft: 0, implemented: 0 },
+        tasks: { total: tasks.length, done: 0, inProgress: 0, todo: 0, withSpec: 0, withoutSpec: 0 },
+        coverage: { linked: 0, total: tasks.length, percent: 0 },
+        acCompletion: {}
+      };
+      const warnings = [];
+      const passed = [];
+      for (const task of tasks) {
+        if (task.status === "done") stats.tasks.done++;
+        else if (task.status === "in-progress") stats.tasks.inProgress++;
+        else stats.tasks.todo++;
+        if (task.spec) {
+          stats.tasks.withSpec++;
+        } else {
+          stats.tasks.withoutSpec++;
+          if (task.status !== "done") {
+            warnings.push({
+              type: "task-no-spec",
+              entity: `task-${task.id}`,
+              message: `${task.title} has no spec reference`
+            });
+          }
+        }
+      }
+      stats.coverage.linked = stats.tasks.withSpec;
+      stats.coverage.percent = stats.tasks.total > 0 ? Math.round(stats.tasks.withSpec / stats.tasks.total * 100) : 0;
+      const specsDir = join28(docsDir, "specs");
+      if (existsSync24(specsDir)) {
+        async function scanSpecs(dir, relativePath) {
+          const entries = await readdir12(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.name.startsWith(".")) continue;
+            const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+              await scanSpecs(join28(dir, entry.name), entryRelPath);
+            } else if (entry.name.endsWith(".md")) {
+              stats.specs.total++;
+              const specPath = `specs/${entryRelPath.replace(/\.md$/, "")}`;
+              try {
+                const content = await readFile18(join28(dir, entry.name), "utf-8");
+                const { data } = (0, import_gray_matter8.default)(content);
+                if (data.status === "implemented") {
+                  stats.specs.implemented++;
+                } else if (data.status === "approved") {
+                  stats.specs.approved++;
+                } else {
+                  stats.specs.draft++;
+                }
+                const linkedTasks = tasks.filter((t) => t.spec === specPath);
+                if (linkedTasks.length > 0) {
+                  let totalAC = 0;
+                  let completedAC = 0;
+                  for (const task of linkedTasks) {
+                    totalAC += task.acceptanceCriteria.length;
+                    completedAC += task.acceptanceCriteria.filter((ac) => ac.completed).length;
+                  }
+                  const percent = totalAC > 0 ? Math.round(completedAC / totalAC * 100) : 100;
+                  stats.acCompletion[specPath] = { total: totalAC, completed: completedAC, percent };
+                  if (percent < 100 && totalAC > 0) {
+                    warnings.push({
+                      type: "spec-ac-incomplete",
+                      entity: specPath,
+                      message: `${completedAC}/${totalAC} ACs complete (${percent}%)`
+                    });
+                  }
+                }
+              } catch {
+              }
+            }
+          }
+        }
+        await scanSpecs(specsDir, "");
+      }
+      for (const task of tasks) {
+        if (task.spec) {
+          const specDocPath = join28(docsDir, `${task.spec}.md`);
+          if (!existsSync24(specDocPath)) {
+            warnings.push({
+              type: "spec-broken-link",
+              entity: `task-${task.id}`,
+              message: `Broken spec reference: @doc/${task.spec}`
+            });
+          }
+        }
+      }
+      if (warnings.filter((w) => w.type === "spec-broken-link").length === 0) {
+        passed.push("All spec references resolve");
+      }
+      for (const [specPath, completion] of Object.entries(stats.acCompletion)) {
+        if (completion.percent === 100) {
+          passed.push(`${specPath}: fully implemented`);
+        }
+      }
+      const result = { stats, warnings, passed };
+      res.json(result);
+    } catch (error48) {
+      console.error("Error getting SDD stats:", error48);
+      res.status(500).json({ error: String(error48) });
+    }
+  });
+  return router;
+}
+
 // src/server/routes/index.ts
 function createRoutes(ctx) {
-  const router = (0, import_express10.Router)();
+  const router = (0, import_express11.Router)();
   router.use("/tasks", createTaskRoutes(ctx));
   router.use("/docs", createDocRoutes(ctx));
   router.use("/templates", createTemplateRoutes(ctx));
@@ -88778,11 +89006,12 @@ function createRoutes(ctx) {
   router.use("/notify", createNotifyRoutes(ctx));
   router.use("/time", createTimeRoutes(ctx));
   router.use("/imports", createImportRoutes(ctx));
+  router.use("/validate", createValidateRoutes(ctx));
   return router;
 }
 
 // src/server/routes/events.ts
-var import_express11 = __toESM(require_express2(), 1);
+var import_express12 = __toESM(require_express2(), 1);
 var clients = /* @__PURE__ */ new Set();
 function broadcast(event, data) {
   const message = `event: ${event}
@@ -88798,7 +89027,7 @@ data: ${JSON.stringify(data)}
   }
 }
 function createEventsRoute() {
-  const router = (0, import_express11.Router)();
+  const router = (0, import_express12.Router)();
   router.get("/", (req, res) => {
     res.setHeader("Content-Type", "text/event-stream");
     res.setHeader("Cache-Control", "no-cache");
@@ -88846,26 +89075,26 @@ async function startServer(options2) {
   const normalizedDir = currentDir.replace(/[/\\]+$/, "");
   const dirName = basename3(normalizedDir);
   if (dirName === "dist") {
-    packageRoot = join27(currentDir, "..");
+    packageRoot = join29(currentDir, "..");
   } else if (normalizedDir.includes("/src/server") || normalizedDir.includes("\\src\\server")) {
-    packageRoot = join27(currentDir, "..", "..");
+    packageRoot = join29(currentDir, "..", "..");
   }
-  const uiDistPath = join27(packageRoot, "dist", "ui");
-  if (!existsSync23(join27(uiDistPath, "index.html"))) {
+  const uiDistPath = join29(packageRoot, "dist", "ui");
+  if (!existsSync25(join29(uiDistPath, "index.html"))) {
     throw new Error(`UI build not found at ${uiDistPath}. Run 'bun run build:ui' first.`);
   }
-  const app = (0, import_express12.default)();
+  const app = (0, import_express13.default)();
   app.use((0, import_cors.default)());
-  app.use(import_express12.default.json());
+  app.use(import_express13.default.json());
   app.use(
     "/assets",
-    import_express12.default.static(join27(uiDistPath, "assets"), {
+    import_express13.default.static(join29(uiDistPath, "assets"), {
       maxAge: "1y",
       immutable: true
     })
   );
   app.use(
-    import_express12.default.static(uiDistPath, {
+    import_express13.default.static(uiDistPath, {
       maxAge: "1d",
       index: false
       // Don't serve index.html automatically
@@ -88875,8 +89104,8 @@ async function startServer(options2) {
   app.use("/api", createRoutes({ store, broadcast: broadcastEvent }));
   app.use(errorHandler);
   app.get("/{*path}", (_req, res) => {
-    const indexPath = join27(uiDistPath, "index.html");
-    if (existsSync23(indexPath)) {
+    const indexPath = join29(uiDistPath, "index.html");
+    if (existsSync25(indexPath)) {
       res.sendFile("index.html", { root: uiDistPath });
     } else {
       res.status(404).send("Not Found");
@@ -88924,21 +89153,21 @@ async function startServer(options2) {
 var DEFAULT_PORT2 = 6420;
 var CONFIG_FILE2 = ".knowns/config.json";
 async function saveServerPort(projectRoot, port) {
-  const configPath = join28(projectRoot, CONFIG_FILE2);
-  const knownsDir = join28(projectRoot, ".knowns");
-  if (!existsSync24(knownsDir)) {
+  const configPath = join30(projectRoot, CONFIG_FILE2);
+  const knownsDir = join30(projectRoot, ".knowns");
+  if (!existsSync26(knownsDir)) {
     await mkdir14(knownsDir, { recursive: true });
   }
   try {
     let config2 = {};
-    if (existsSync24(configPath)) {
-      const content = await readFile17(configPath, "utf-8");
+    if (existsSync26(configPath)) {
+      const content = await readFile19(configPath, "utf-8");
       config2 = JSON.parse(content);
     }
     const settings = config2.settings || {};
     settings.serverPort = port;
     config2.settings = settings;
-    await writeFile12(configPath, JSON.stringify(config2, null, 2), "utf-8");
+    await writeFile13(configPath, JSON.stringify(config2, null, 2), "utf-8");
   } catch {
   }
 }
@@ -88968,9 +89197,9 @@ var browserCommand = new Command("browser").description("Open web UI for task ma
 });
 
 // src/commands/doc.ts
-import { existsSync as existsSync25 } from "node:fs";
-import { mkdir as mkdir15, readFile as readFile18, readdir as readdir12, writeFile as writeFile13 } from "node:fs/promises";
-import { join as join29 } from "node:path";
+import { existsSync as existsSync27 } from "node:fs";
+import { mkdir as mkdir15, readFile as readFile20, readdir as readdir13, writeFile as writeFile14 } from "node:fs/promises";
+import { join as join31 } from "node:path";
 
 // src/utils/markdown-toc.ts
 function extractToc(markdown) {
@@ -89159,14 +89388,14 @@ function matchesPartial(title, search) {
 }
 
 // src/commands/doc.ts
-var import_gray_matter7 = __toESM(require_gray_matter(), 1);
-var DOCS_DIR3 = join29(process.cwd(), ".knowns", "docs");
+var import_gray_matter9 = __toESM(require_gray_matter(), 1);
+var DOCS_DIR3 = join31(process.cwd(), ".knowns", "docs");
 async function getAllMdFiles(dir, basePath = "") {
   const files = [];
-  const entries = await readdir12(dir, { withFileTypes: true });
+  const entries = await readdir13(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join29(dir, entry.name);
-    const relativePath = normalizePath2(basePath ? join29(basePath, entry.name) : entry.name);
+    const fullPath = join31(dir, entry.name);
+    const relativePath = normalizePath2(basePath ? join31(basePath, entry.name) : entry.name);
     if (entry.isDirectory()) {
       const subFiles = await getAllMdFiles(fullPath, relativePath);
       files.push(...subFiles);
@@ -89177,7 +89406,7 @@ async function getAllMdFiles(dir, basePath = "") {
   return files;
 }
 async function ensureDocsDir() {
-  if (!existsSync25(DOCS_DIR3)) {
+  if (!existsSync27(DOCS_DIR3)) {
     await mkdir15(DOCS_DIR3, { recursive: true });
   }
 }
@@ -89197,12 +89426,12 @@ async function resolveDocPath(name, context) {
     };
   }
   let filename = name.endsWith(".md") ? name : `${name}.md`;
-  let filepath = join29(DOCS_DIR3, filename);
-  if (!existsSync25(filepath)) {
+  let filepath = join31(DOCS_DIR3, filename);
+  if (!existsSync27(filepath)) {
     filename = `${titleToFilename(name)}.md`;
-    filepath = join29(DOCS_DIR3, filename);
+    filepath = join31(DOCS_DIR3, filename);
   }
-  if (!existsSync25(filepath)) {
+  if (!existsSync27(filepath)) {
     const allFiles = await getAllMdFiles(DOCS_DIR3);
     const searchName = name.toLowerCase().replace(/\.md$/, "");
     const matchingFile = allFiles.find((file3) => {
@@ -89212,10 +89441,10 @@ async function resolveDocPath(name, context) {
     });
     if (matchingFile) {
       filename = matchingFile;
-      filepath = join29(DOCS_DIR3, matchingFile);
+      filepath = join31(DOCS_DIR3, matchingFile);
     }
   }
-  if (!existsSync25(filepath)) {
+  if (!existsSync27(filepath)) {
     return null;
   }
   return { filepath, filename };
@@ -89229,14 +89458,14 @@ var createCommand3 = new Command("create").description("Create a new documentati
       let relativePath = filename;
       if (options2.folder) {
         const folderPath = options2.folder.replace(/^\/|\/$/g, "");
-        targetDir = join29(DOCS_DIR3, folderPath);
-        relativePath = join29(folderPath, filename);
-        if (!existsSync25(targetDir)) {
+        targetDir = join31(DOCS_DIR3, folderPath);
+        relativePath = join31(folderPath, filename);
+        if (!existsSync27(targetDir)) {
           await mkdir15(targetDir, { recursive: true });
         }
       }
-      const filepath = join29(targetDir, filename);
-      if (existsSync25(filepath)) {
+      const filepath = join31(targetDir, filename);
+      if (existsSync27(filepath)) {
         console.error(source_default.red(`\u2717 Document already exists: ${relativePath}`));
         process.exit(1);
       }
@@ -89252,8 +89481,8 @@ var createCommand3 = new Command("create").description("Create a new documentati
       if (options2.tags) {
         metadata.tags = options2.tags.split(",").map((t) => t.trim());
       }
-      const content = import_gray_matter7.default.stringify("# Content\n\nWrite your documentation here.\n", metadata);
-      await writeFile13(filepath, content, "utf-8");
+      const content = import_gray_matter9.default.stringify("# Content\n\nWrite your documentation here.\n", metadata);
+      await writeFile14(filepath, content, "utf-8");
       await notifyDocUpdate(relativePath);
       if (options2.plain) {
         console.log(`Created: ${relativePath}`);
@@ -89288,8 +89517,8 @@ var listCommand2 = new Command("list").description("List all documentation files
       const docs = [];
       for (const doc of allDocs) {
         try {
-          const fileContent = await readFile18(doc.fullPath, "utf-8");
-          const { data, content } = (0, import_gray_matter7.default)(fileContent);
+          const fileContent = await readFile20(doc.fullPath, "utf-8");
+          const { data, content } = (0, import_gray_matter9.default)(fileContent);
           const stats = calculateDocStats(content);
           docs.push({
             ref: doc.ref,
@@ -89463,8 +89692,8 @@ var viewCommand2 = new Command("view").description("View a documentation file").
         process.exit(1);
       }
       const { filepath, filename, isImported, source } = resolved;
-      const fileContent = await readFile18(filepath, "utf-8");
-      const { data, content } = (0, import_gray_matter7.default)(fileContent);
+      const fileContent = await readFile20(filepath, "utf-8");
+      const { data, content } = (0, import_gray_matter9.default)(fileContent);
       const metadata = data;
       if (options2.smart) {
         const stats = calculateDocStats(content);
@@ -89639,7 +89868,7 @@ var viewCommand2 = new Command("view").description("View a documentation file").
         }
         console.log(enhancedContent);
         const projectRoot = findProjectRoot() || process.cwd();
-        const tasksDir = join29(projectRoot, ".knowns", "tasks");
+        const tasksDir = join31(projectRoot, ".knowns", "tasks");
         const refs = await validateRefs(projectRoot, enhancedContent, tasksDir);
         const brokenRefs = refs.filter((r) => !r.exists);
         if (brokenRefs.length > 0) {
@@ -89669,7 +89898,7 @@ var viewCommand2 = new Command("view").description("View a documentation file").
         }
         console.log(displayContent);
         const projectRoot = findProjectRoot() || process.cwd();
-        const tasksDir = join29(projectRoot, ".knowns", "tasks");
+        const tasksDir = join31(projectRoot, ".knowns", "tasks");
         const refs = await validateRefs(projectRoot, displayContent, tasksDir);
         const brokenRefs = refs.filter((r) => !r.exists);
         if (brokenRefs.length > 0) {
@@ -89694,13 +89923,13 @@ var editCommand2 = new Command("edit").description("Edit a documentation file (m
     try {
       await ensureDocsDir();
       let filename = name.endsWith(".md") ? name : `${name}.md`;
-      let filepath = join29(DOCS_DIR3, filename);
-      if (!existsSync25(filepath)) {
+      let filepath = join31(DOCS_DIR3, filename);
+      if (!existsSync27(filepath)) {
         const baseName = name.includes("/") ? name : titleToFilename(name);
         filename = baseName.endsWith(".md") ? baseName : `${baseName}.md`;
-        filepath = join29(DOCS_DIR3, filename);
+        filepath = join31(DOCS_DIR3, filename);
       }
-      if (!existsSync25(filepath)) {
+      if (!existsSync27(filepath)) {
         const allFiles = await getAllMdFiles(DOCS_DIR3);
         const searchName = name.toLowerCase().replace(/\.md$/, "");
         const matchingFile = allFiles.find((file3) => {
@@ -89710,15 +89939,15 @@ var editCommand2 = new Command("edit").description("Edit a documentation file (m
         });
         if (matchingFile) {
           filename = matchingFile;
-          filepath = join29(DOCS_DIR3, matchingFile);
+          filepath = join31(DOCS_DIR3, matchingFile);
         }
       }
-      if (!existsSync25(filepath)) {
+      if (!existsSync27(filepath)) {
         console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
         process.exit(1);
       }
-      const fileContent = await readFile18(filepath, "utf-8");
-      const { data, content } = (0, import_gray_matter7.default)(fileContent);
+      const fileContent = await readFile20(filepath, "utf-8");
+      const { data, content } = (0, import_gray_matter9.default)(fileContent);
       const metadata = data;
       if (options2.title) metadata.title = options2.title;
       if (options2.description) metadata.description = normalizeRefs(options2.description);
@@ -89727,19 +89956,19 @@ var editCommand2 = new Command("edit").description("Edit a documentation file (m
       let updatedContent = content;
       let sourceFile;
       if (options2.contentFile) {
-        if (!existsSync25(options2.contentFile)) {
+        if (!existsSync27(options2.contentFile)) {
           console.error(source_default.red(`\u2717 File not found: ${options2.contentFile}`));
           process.exit(1);
         }
-        const fileData = await readFile18(options2.contentFile, "utf-8");
+        const fileData = await readFile20(options2.contentFile, "utf-8");
         updatedContent = normalizeRefs(fileData);
         sourceFile = options2.contentFile;
       } else if (options2.appendFile) {
-        if (!existsSync25(options2.appendFile)) {
+        if (!existsSync27(options2.appendFile)) {
           console.error(source_default.red(`\u2717 File not found: ${options2.appendFile}`));
           process.exit(1);
         }
-        const fileData = await readFile18(options2.appendFile, "utf-8");
+        const fileData = await readFile20(options2.appendFile, "utf-8");
         updatedContent = `${content.trimEnd()}
 
 ${normalizeRefs(fileData)}`;
@@ -89764,8 +89993,8 @@ ${normalizeRefs(fileData)}`;
 
 ${normalizeRefs(options2.append)}`;
       }
-      const newFileContent = import_gray_matter7.default.stringify(updatedContent, metadata);
-      await writeFile13(filepath, newFileContent, "utf-8");
+      const newFileContent = import_gray_matter9.default.stringify(updatedContent, metadata);
+      await writeFile14(filepath, newFileContent, "utf-8");
       await notifyDocUpdate(filename);
       if (options2.plain) {
         console.log(`Updated: ${filename}`);
@@ -89800,7 +90029,7 @@ var validateCommand2 = new Command("validate").description("Validate a documenta
       console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
       process.exit(1);
     }
-    const content = await readFile18(resolved.filepath, "utf-8");
+    const content = await readFile20(resolved.filepath, "utf-8");
     const result = validateDoc(content);
     if (options2.plain) {
       console.log(`Validating: ${resolved.filename}`);
@@ -89927,8 +90156,8 @@ var searchInCommand = new Command("search-in").description("Search text within a
       console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
       process.exit(1);
     }
-    const fileContent = await readFile18(resolved.filepath, "utf-8");
-    const { content } = (0, import_gray_matter7.default)(fileContent);
+    const fileContent = await readFile20(resolved.filepath, "utf-8");
+    const { content } = (0, import_gray_matter9.default)(fileContent);
     const lines = content.split("\n");
     const matches = [];
     const searchQuery = options2.ignoreCase ? query.toLowerCase() : query;
@@ -89980,8 +90209,8 @@ var replaceCommand = new Command("replace").description("Replace text in a docum
       console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
       process.exit(1);
     }
-    const fileContent = await readFile18(resolved.filepath, "utf-8");
-    const { data, content } = (0, import_gray_matter7.default)(fileContent);
+    const fileContent = await readFile20(resolved.filepath, "utf-8");
+    const { data, content } = (0, import_gray_matter9.default)(fileContent);
     if (!content.includes(oldText)) {
       if (options2.plain) {
         console.log(`Text not found: "${oldText}"`);
@@ -90002,8 +90231,8 @@ var replaceCommand = new Command("replace").description("Replace text in a docum
     }
     const metadata = data;
     metadata.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    const updatedFileContent = import_gray_matter7.default.stringify(newContent, data);
-    await writeFile13(resolved.filepath, updatedFileContent, "utf-8");
+    const updatedFileContent = import_gray_matter9.default.stringify(newContent, data);
+    await writeFile14(resolved.filepath, updatedFileContent, "utf-8");
     await notifyDocUpdate(resolved.filename);
     if (options2.plain) {
       console.log(`Updated: ${resolved.filename}`);
@@ -90024,8 +90253,8 @@ var replaceSectionCommand = new Command("replace-section").description("Replace
       console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
       process.exit(1);
     }
-    const fileContent = await readFile18(resolved.filepath, "utf-8");
-    const { data, content } = (0, import_gray_matter7.default)(fileContent);
+    const fileContent = await readFile20(resolved.filepath, "utf-8");
+    const { data, content } = (0, import_gray_matter9.default)(fileContent);
     const headerLevel = (header.match(/^#+/) || ["##"])[0];
     const headerPattern = new RegExp(`^${header.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
     const headerMatch = content.match(headerPattern);
@@ -90056,8 +90285,8 @@ ${newSectionContent}
 ${afterSection.trimStart()}`;
     const metadata = data;
     metadata.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    const updatedFileContent = import_gray_matter7.default.stringify(newContent.trim(), data);
-    await writeFile13(resolved.filepath, updatedFileContent, "utf-8");
+    const updatedFileContent = import_gray_matter9.default.stringify(newContent.trim(), data);
+    await writeFile14(resolved.filepath, updatedFileContent, "utf-8");
     await notifyDocUpdate(resolved.filename);
     if (options2.plain) {
       console.log(`Updated: ${resolved.filename}`);
@@ -90084,8 +90313,8 @@ var docCommand = new Command("doc").description("Manage documentation").argument
         process.exit(1);
       }
       const { filepath, filename, isImported, source } = resolved;
-      const fileContent = await readFile18(filepath, "utf-8");
-      const { data, content } = (0, import_gray_matter7.default)(fileContent);
+      const fileContent = await readFile20(filepath, "utf-8");
+      const { data, content } = (0, import_gray_matter9.default)(fileContent);
       const metadata = data;
       if (options2.smart) {
         const stats = calculateDocStats(content);
@@ -90260,7 +90489,7 @@ var docCommand = new Command("doc").description("Manage documentation").argument
         }
         console.log(enhancedContent);
         const projectRoot = findProjectRoot() || process.cwd();
-        const tasksDir = join29(projectRoot, ".knowns", "tasks");
+        const tasksDir = join31(projectRoot, ".knowns", "tasks");
         const refs = await validateRefs(projectRoot, enhancedContent, tasksDir);
         const brokenRefs = refs.filter((r) => !r.exists);
         if (brokenRefs.length > 0) {
@@ -90290,7 +90519,7 @@ var docCommand = new Command("doc").description("Manage documentation").argument
         }
         console.log(displayContent);
         const projectRoot = findProjectRoot() || process.cwd();
-        const tasksDir = join29(projectRoot, ".knowns", "tasks");
+        const tasksDir = join31(projectRoot, ".knowns", "tasks");
         const refs = await validateRefs(projectRoot, displayContent, tasksDir);
         const brokenRefs = refs.filter((r) => !r.exists);
         if (brokenRefs.length > 0) {
@@ -90321,9 +90550,9 @@ docCommand.addCommand(replaceCommand);
 docCommand.addCommand(replaceSectionCommand);
 
 // src/commands/config.ts
-import { existsSync as existsSync26 } from "node:fs";
-import { mkdir as mkdir16, readFile as readFile19, writeFile as writeFile14 } from "node:fs/promises";
-import { join as join30 } from "node:path";
+import { existsSync as existsSync28 } from "node:fs";
+import { mkdir as mkdir16, readFile as readFile21, writeFile as writeFile15 } from "node:fs/promises";
+import { join as join32 } from "node:path";
 var CONFIG_FILE3 = ".knowns/config.json";
 var ConfigSchema = external_exports.object({
   defaultAssignee: external_exports.string().optional(),
@@ -90351,12 +90580,12 @@ function getProjectRoot2() {
   return projectRoot;
 }
 async function loadConfig(projectRoot) {
-  const configPath = join30(projectRoot, CONFIG_FILE3);
-  if (!existsSync26(configPath)) {
+  const configPath = join32(projectRoot, CONFIG_FILE3);
+  if (!existsSync28(configPath)) {
     return { ...DEFAULT_CONFIG };
   }
   try {
-    const content = await readFile19(configPath, "utf-8");
+    const content = await readFile21(configPath, "utf-8");
     const data = JSON.parse(content);
     const settings = data.settings || {};
     const validated = ConfigSchema.parse(settings);
@@ -90370,22 +90599,22 @@ async function loadConfig(projectRoot) {
   }
 }
 async function saveConfig(projectRoot, config2) {
-  const configPath = join30(projectRoot, CONFIG_FILE3);
-  const knownsDir = join30(projectRoot, ".knowns");
-  if (!existsSync26(knownsDir)) {
+  const configPath = join32(projectRoot, CONFIG_FILE3);
+  const knownsDir = join32(projectRoot, ".knowns");
+  if (!existsSync28(knownsDir)) {
     await mkdir16(knownsDir, { recursive: true });
   }
   try {
     let existingData = {};
-    if (existsSync26(configPath)) {
-      const content = await readFile19(configPath, "utf-8");
+    if (existsSync28(configPath)) {
+      const content = await readFile21(configPath, "utf-8");
       existingData = JSON.parse(content);
     }
     const merged = {
       ...existingData,
       settings: config2
     };
-    await writeFile14(configPath, JSON.stringify(merged, null, 2), "utf-8");
+    await writeFile15(configPath, JSON.stringify(merged, null, 2), "utf-8");
   } catch (error48) {
     console.error(source_default.red("\u2717 Failed to save config"));
     if (error48 instanceof Error) {
@@ -90527,8 +90756,8 @@ var resetCommand = new Command("reset").description("Reset configuration to defa
 var configCommand = new Command("config").description("Manage configuration settings").addCommand(listCommand3).addCommand(getCommand).addCommand(setCommand).addCommand(resetCommand);
 
 // src/commands/sync.ts
-import { existsSync as existsSync27, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
-import { join as join31 } from "node:path";
+import { existsSync as existsSync29, mkdirSync, readFileSync as readFileSync2, readdirSync as readdirSync3, rmSync as rmSync2, writeFileSync } from "node:fs";
+import { join as join33 } from "node:path";
 var PROJECT_ROOT2 = process.cwd();
 function renderSkillContent2(content, mode) {
   try {
@@ -90537,21 +90766,49 @@ function renderSkillContent2(content, mode) {
     return content;
   }
 }
+function cleanupDeprecatedSkills2(skillsDir) {
+  let removed = 0;
+  if (existsSync29(skillsDir)) {
+    const entries = readdirSync3(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith("knowns.")) {
+        const deprecatedPath = join33(skillsDir, entry.name);
+        rmSync2(deprecatedPath, { recursive: true, force: true });
+        console.log(source_default.yellow(`\u2713 Removed deprecated: ${entry.name}`));
+        removed++;
+      }
+    }
+  }
+  const agentSkillsDir = join33(PROJECT_ROOT2, ".agent", "skills");
+  if (existsSync29(agentSkillsDir)) {
+    const entries = readdirSync3(agentSkillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith("knowns.")) {
+        const deprecatedPath = join33(agentSkillsDir, entry.name);
+        rmSync2(deprecatedPath, { recursive: true, force: true });
+        console.log(source_default.yellow(`\u2713 Removed deprecated: .agent/skills/${entry.name}`));
+        removed++;
+      }
+    }
+  }
+  return removed;
+}
 async function syncSkills2(options2) {
-  const skillsDir = join31(PROJECT_ROOT2, ".claude", "skills");
+  const skillsDir = join33(PROJECT_ROOT2, ".claude", "skills");
   const mode = options2.mode ?? "mcp";
-  if (!existsSync27(skillsDir)) {
+  if (!existsSync29(skillsDir)) {
     mkdirSync(skillsDir, { recursive: true });
     console.log(source_default.green("\u2713 Created .claude/skills/"));
   }
+  const removed = cleanupDeprecatedSkills2(skillsDir);
   let created = 0;
   let updated = 0;
   let skipped = 0;
   for (const skill of SKILLS) {
-    const skillFolder = join31(skillsDir, skill.folderName);
-    const skillFile = join31(skillFolder, "SKILL.md");
+    const skillFolder = join33(skillsDir, skill.folderName);
+    const skillFile = join33(skillFolder, "SKILL.md");
     const renderedContent = renderSkillContent2(skill.content, mode);
-    if (existsSync27(skillFile)) {
+    if (existsSync29(skillFile)) {
       if (options2.force) {
         const existing = readFileSync2(skillFile, "utf-8");
         if (existing.trim() !== renderedContent.trim()) {
@@ -90567,7 +90824,7 @@ async function syncSkills2(options2) {
         skipped++;
       }
     } else {
-      if (!existsSync27(skillFolder)) {
+      if (!existsSync29(skillFolder)) {
         mkdirSync(skillFolder, { recursive: true });
       }
       writeFileSync(skillFile, renderedContent, "utf-8");
@@ -90575,7 +90832,7 @@ async function syncSkills2(options2) {
       created++;
     }
   }
-  return { created, updated, skipped };
+  return { created, updated, skipped, removed };
 }
 async function syncAgents(options2) {
   const type = options2.type === "mcp" ? "mcp" : "cli";
@@ -90612,13 +90869,13 @@ async function syncIDE(options2) {
   let skipped = 0;
   const configs = options2.ide ? [getIDEConfig(options2.ide)].filter(Boolean) : IDE_CONFIGS;
   for (const config2 of configs) {
-    const targetDir = join31(PROJECT_ROOT2, config2.targetDir);
+    const targetDir = join33(PROJECT_ROOT2, config2.targetDir);
     for (const file3 of config2.files) {
-      const filePath = join31(targetDir, file3.filename);
-      const fileDir = join31(targetDir, ...file3.filename.split("/").slice(0, -1));
+      const filePath = join33(targetDir, file3.filename);
+      const fileDir = join33(targetDir, ...file3.filename.split("/").slice(0, -1));
       const content = file3.isJson ? `${JSON.stringify(file3.content, null, 2)}
 ` : String(file3.content);
-      if (existsSync27(filePath)) {
+      if (existsSync29(filePath)) {
         if (options2.force) {
           const existing = readFileSync2(filePath, "utf-8");
           if (existing.trim() !== content.trim()) {
@@ -90634,7 +90891,7 @@ async function syncIDE(options2) {
           skipped++;
         }
       } else {
-        if (!existsSync27(fileDir)) {
+        if (!existsSync29(fileDir)) {
           mkdirSync(fileDir, { recursive: true });
         }
         writeFileSync(filePath, content, "utf-8");
@@ -90648,6 +90905,7 @@ async function syncIDE(options2) {
 function printSummary(label, stats) {
   console.log(source_default.bold(`
 ${label}:`));
+  if (stats.removed && stats.removed > 0) console.log(source_default.yellow(`  Removed: ${stats.removed}`));
   if (stats.created > 0) console.log(source_default.green(`  Created: ${stats.created}`));
   if (stats.updated > 0) console.log(source_default.green(`  Updated: ${stats.updated}`));
   if (stats.skipped > 0) console.log(source_default.gray(`  Skipped: ${stats.skipped}`));
@@ -90725,13 +90983,13 @@ syncCommand.addCommand(agentSubcommand);
 syncCommand.addCommand(ideSubcommand);
 
 // src/commands/mcp.ts
-import { existsSync as existsSync34, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join39 } from "node:path";
+import { existsSync as existsSync37, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join42 } from "node:path";
 
 // src/mcp/server.ts
-import { existsSync as existsSync33 } from "node:fs";
-import { readFile as readFile24 } from "node:fs/promises";
-import { join as join38 } from "node:path";
+import { existsSync as existsSync36 } from "node:fs";
+import { readFile as readFile27 } from "node:fs/promises";
+import { join as join41 } from "node:path";
 
 // node_modules/zod/v3/helpers/util.js
 var util;
@@ -97791,17 +98049,17 @@ var StdioServerTransport = class {
 };
 
 // src/mcp/server.ts
-var import_gray_matter11 = __toESM(require_gray_matter(), 1);
+var import_gray_matter14 = __toESM(require_gray_matter(), 1);
 
 // src/mcp/utils.ts
-import { readFile as readFile20 } from "node:fs/promises";
-import { join as join33 } from "node:path";
-var import_gray_matter8 = __toESM(require_gray_matter(), 1);
+import { readFile as readFile22 } from "node:fs/promises";
+import { join as join35 } from "node:path";
+var import_gray_matter10 = __toESM(require_gray_matter(), 1);
 
 // src/mcp/handlers/project.ts
-import { existsSync as existsSync28, readdirSync as readdirSync2, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync30, readdirSync as readdirSync4, statSync as statSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { basename as basename4, join as join32 } from "node:path";
+import { basename as basename4, join as join34 } from "node:path";
 var currentProjectRoot = null;
 function getProjectRoot3() {
   if (currentProjectRoot) {
@@ -97819,23 +98077,23 @@ function getWorkspaceDirectories() {
   const home = homedir2();
   const dirs = [];
   const commonPaths = [
-    join32(home, "Workspaces"),
-    join32(home, "workspace"),
-    join32(home, "projects"),
-    join32(home, "Projects"),
-    join32(home, "dev"),
-    join32(home, "Development"),
-    join32(home, "Code"),
-    join32(home, "code"),
-    join32(home, "repos"),
-    join32(home, "Repos"),
-    join32(home, "src"),
-    join32(home, "Documents", "Projects"),
-    join32(home, "Documents", "GitHub"),
-    join32(home, "GitHub")
+    join34(home, "Workspaces"),
+    join34(home, "workspace"),
+    join34(home, "projects"),
+    join34(home, "Projects"),
+    join34(home, "dev"),
+    join34(home, "Development"),
+    join34(home, "Code"),
+    join34(home, "code"),
+    join34(home, "repos"),
+    join34(home, "Repos"),
+    join34(home, "src"),
+    join34(home, "Documents", "Projects"),
+    join34(home, "Documents", "GitHub"),
+    join34(home, "GitHub")
   ];
   for (const path3 of commonPaths) {
-    if (existsSync28(path3)) {
+    if (existsSync30(path3)) {
       dirs.push(path3);
     }
   }
@@ -97846,10 +98104,10 @@ function scanForKnownsProjects(baseDir, maxDepth = 2) {
   function scan(dir, depth) {
     if (depth > maxDepth) return;
     try {
-      const entries = readdirSync2(dir);
+      const entries = readdirSync4(dir);
       if (entries.includes(".knowns")) {
-        const knownsPath = join32(dir, ".knowns");
-        if (existsSync28(knownsPath) && statSync2(knownsPath).isDirectory()) {
+        const knownsPath = join34(dir, ".knowns");
+        if (existsSync30(knownsPath) && statSync2(knownsPath).isDirectory()) {
           projects.push(dir);
           return;
         }
@@ -97858,7 +98116,7 @@ function scanForKnownsProjects(baseDir, maxDepth = 2) {
         if (entry.startsWith(".") || entry === "node_modules" || entry === "vendor") {
           continue;
         }
-        const entryPath = join32(dir, entry);
+        const entryPath = join34(dir, entry);
         try {
           if (statSync2(entryPath).isDirectory()) {
             scan(entryPath, depth + 1);
@@ -97876,7 +98134,7 @@ function detectKnownsProjects() {
   const workspaceDirs = getWorkspaceDirectories();
   const allProjects = [];
   const cwd = process.cwd();
-  if (existsSync28(join32(cwd, ".knowns"))) {
+  if (existsSync30(join34(cwd, ".knowns"))) {
     allProjects.push(cwd);
   }
   for (const dir of workspaceDirs) {
@@ -97934,7 +98192,7 @@ function handleDetectProjects(input) {
   let projects = detectKnownsProjects();
   if (input.additionalPaths) {
     for (const path3 of input.additionalPaths) {
-      if (existsSync28(path3)) {
+      if (existsSync30(path3)) {
         const additional = scanForKnownsProjects(path3);
         for (const project of additional) {
           if (!projects.find((p) => p.path === project)) {
@@ -97954,15 +98212,15 @@ function handleDetectProjects(input) {
 }
 function handleSetProject(input) {
   const { projectRoot } = input;
-  if (!existsSync28(projectRoot)) {
+  if (!existsSync30(projectRoot)) {
     return {
       success: false,
       projectRoot,
       message: `Path does not exist: ${projectRoot}`
     };
   }
-  const knownsPath = join32(projectRoot, ".knowns");
-  if (!existsSync28(knownsPath)) {
+  const knownsPath = join34(projectRoot, ".knowns");
+  if (!existsSync30(knownsPath)) {
     return {
       success: false,
       projectRoot,
@@ -97986,7 +98244,7 @@ function handleGetCurrentProject() {
     source = "env";
     projectRoot = process.env.KNOWNS_PROJECT_ROOT;
   }
-  const isValid2 = existsSync28(join32(projectRoot, ".knowns"));
+  const isValid2 = existsSync30(join34(projectRoot, ".knowns"));
   return {
     projectRoot,
     isExplicitlySet: source === "explicit",
@@ -98027,7 +98285,7 @@ function formatDuration2(seconds) {
 }
 async function fetchLinkedDocs(task) {
   const projectRoot = getProjectRoot3();
-  const docsDir = join33(projectRoot, ".knowns", "docs");
+  const docsDir = join35(projectRoot, ".knowns", "docs");
   const allContent = [task.description || "", task.implementationPlan || "", task.implementationNotes || ""].join("\n");
   const docRefs = resolveDocReferences(allContent, projectRoot);
   const linkedDocs = [];
@@ -98035,9 +98293,9 @@ async function fetchLinkedDocs(task) {
     if (!ref.exists) continue;
     try {
       const filename = ref.resolvedPath.replace("@.knowns/docs/", "");
-      const filepath = join33(docsDir, filename);
-      const fileContent = await readFile20(filepath, "utf-8");
-      const { data, content } = (0, import_gray_matter8.default)(fileContent);
+      const filepath = join35(docsDir, filename);
+      const fileContent = await readFile22(filepath, "utf-8");
+      const { data, content } = (0, import_gray_matter10.default)(fileContent);
       linkedDocs.push({
         path: ref.resolvedPath,
         title: data.title || ref.text,
@@ -98070,6 +98328,10 @@ function errorResponse(error48) {
 }
 
 // src/mcp/handlers/task.ts
+function normalizeNewlines(text) {
+  if (!text) return text;
+  return text.replace(/\\n/g, "\n");
+}
 var createTaskSchema = external_exports.object({
   title: external_exports.string(),
   description: external_exports.string().optional(),
@@ -98077,7 +98339,8 @@ var createTaskSchema = external_exports.object({
   priority: external_exports.enum(["low", "medium", "high"]).optional(),
   assignee: external_exports.string().optional(),
   labels: external_exports.array(external_exports.string()).optional(),
-  parent: external_exports.string().optional()
+  parent: external_exports.string().optional(),
+  spec: external_exports.string().optional()
 });
 var getTaskSchema = external_exports.object({
   taskId: external_exports.string()
@@ -98090,6 +98353,8 @@ var updateTaskSchema = external_exports.object({
   priority: external_exports.enum(["low", "medium", "high"]).optional(),
   assignee: external_exports.string().optional(),
   labels: external_exports.array(external_exports.string()).optional(),
+  spec: external_exports.string().nullable().optional(),
+  // Spec document path (null to remove)
   // AC operations
   addAc: external_exports.array(external_exports.string()).optional(),
   // Add new acceptance criteria
@@ -98111,7 +98376,8 @@ var listTasksSchema = external_exports.object({
   status: external_exports.string().optional(),
   priority: external_exports.string().optional(),
   assignee: external_exports.string().optional(),
-  label: external_exports.string().optional()
+  label: external_exports.string().optional(),
+  spec: external_exports.string().optional()
 });
 var searchTasksSchema = external_exports.object({
   query: external_exports.string()
@@ -98141,7 +98407,8 @@ var taskTools = [
           items: { type: "string" },
           description: "Task labels"
         },
-        parent: { type: "string", description: "Parent task ID for subtasks" }
+        parent: { type: "string", description: "Parent task ID for subtasks" },
+        spec: { type: "string", description: "Spec document path (e.g., 'specs/user-auth')" }
       },
       required: ["title"]
     }
@@ -98182,6 +98449,7 @@ var taskTools = [
           items: { type: "string" },
           description: "New labels"
         },
+        spec: { type: "string", description: "Spec document path (set to null to remove)" },
         addAc: {
           type: "array",
           items: { type: "string" },
@@ -98218,7 +98486,8 @@ var taskTools = [
         status: { type: "string", description: "Filter by status" },
         priority: { type: "string", description: "Filter by priority" },
         assignee: { type: "string", description: "Filter by assignee" },
-        label: { type: "string", description: "Filter by label" }
+        label: { type: "string", description: "Filter by label" },
+        spec: { type: "string", description: "Filter by spec document path" }
       }
     }
   },
@@ -98238,12 +98507,13 @@ async function handleCreateTask(args2, fileStore) {
   const input = createTaskSchema.parse(args2);
   const task = await fileStore.createTask({
     title: input.title,
-    description: input.description,
+    description: normalizeNewlines(input.description),
     status: input.status || "todo",
     priority: input.priority || "medium",
     assignee: input.assignee,
     labels: input.labels || [],
     parent: input.parent,
+    spec: input.spec,
     subtasks: [],
     acceptanceCriteria: [],
     timeSpent: 0,
@@ -98276,6 +98546,7 @@ async function handleGetTask(args2, fileStore) {
       priority: task.priority,
       assignee: task.assignee,
       labels: task.labels,
+      spec: task.spec,
       acceptanceCriteria: task.acceptanceCriteria,
       implementationPlan: task.implementationPlan,
       implementationNotes: task.implementationNotes,
@@ -98294,11 +98565,14 @@ async function handleUpdateTask(args2, fileStore) {
   }
   const updates = {};
   if (input.title) updates.title = input.title;
-  if (input.description) updates.description = input.description;
+  if (input.description) updates.description = normalizeNewlines(input.description);
   if (input.status) updates.status = input.status;
   if (input.priority) updates.priority = input.priority;
   if (input.assignee) updates.assignee = input.assignee;
   if (input.labels) updates.labels = input.labels;
+  if (input.spec !== void 0) {
+    updates.spec = input.spec === null ? void 0 : input.spec;
+  }
   const criteria = [...currentTask.acceptanceCriteria];
   let acModified = false;
   if (input.addAc && input.addAc.length > 0) {
@@ -98341,15 +98615,15 @@ async function handleUpdateTask(args2, fileStore) {
     updates.acceptanceCriteria = criteria;
   }
   if (input.plan !== void 0) {
-    updates.implementationPlan = input.plan;
+    updates.implementationPlan = normalizeNewlines(input.plan);
   }
   if (input.notes !== void 0) {
-    updates.implementationNotes = input.notes;
+    updates.implementationNotes = normalizeNewlines(input.notes);
   }
   if (input.appendNotes) {
     const existingNotes = currentTask.implementationNotes || "";
     const separator = existingNotes ? "\n\n" : "";
-    updates.implementationNotes = existingNotes + separator + input.appendNotes;
+    updates.implementationNotes = existingNotes + separator + normalizeNewlines(input.appendNotes);
   }
   const task = await fileStore.updateTask(taskId, updates);
   await notifyTaskUpdate(task.id);
@@ -98380,6 +98654,9 @@ async function handleListTasks(args2, fileStore) {
   if (input.label) {
     tasks = tasks.filter((t) => t.labels.includes(input.label));
   }
+  if (input.spec) {
+    tasks = tasks.filter((t) => t.spec === input.spec);
+  }
   return successResponse({
     count: tasks.length,
     tasks: tasks.map((t) => ({
@@ -98388,7 +98665,8 @@ async function handleListTasks(args2, fileStore) {
       status: t.status,
       priority: t.priority,
       assignee: t.assignee,
-      labels: t.labels
+      labels: t.labels,
+      spec: t.spec
     }))
   });
 }
@@ -98411,9 +98689,9 @@ async function handleSearchTasks(args2, fileStore) {
 }
 
 // src/mcp/handlers/time.ts
-import { existsSync as existsSync29 } from "node:fs";
-import { readFile as readFile21, writeFile as writeFile15 } from "node:fs/promises";
-import { join as join34 } from "node:path";
+import { existsSync as existsSync31 } from "node:fs";
+import { readFile as readFile23, writeFile as writeFile16 } from "node:fs/promises";
+import { join as join36 } from "node:path";
 var startTimeSchema = external_exports.object({
   taskId: external_exports.string()
 });
@@ -98496,11 +98774,11 @@ var timeTools = [
   }
 ];
 async function loadTimeData2(projectRoot) {
-  const timePath = join34(projectRoot, ".knowns", "time.json");
-  if (!existsSync29(timePath)) {
+  const timePath = join36(projectRoot, ".knowns", "time.json");
+  if (!existsSync31(timePath)) {
     return { active: [] };
   }
-  const content = await readFile21(timePath, "utf-8");
+  const content = await readFile23(timePath, "utf-8");
   const data = JSON.parse(content);
   if (data.active && !Array.isArray(data.active)) {
     return { active: [data.active] };
@@ -98511,8 +98789,8 @@ async function loadTimeData2(projectRoot) {
   return data;
 }
 async function saveTimeData2(projectRoot, data) {
-  const timePath = join34(projectRoot, ".knowns", "time.json");
-  await writeFile15(timePath, JSON.stringify(data, null, 2), "utf-8");
+  const timePath = join36(projectRoot, ".knowns", "time.json");
+  await writeFile16(timePath, JSON.stringify(data, null, 2), "utf-8");
 }
 async function handleStartTime(args2, fileStore) {
   const input = startTimeSchema.parse(args2);
@@ -98727,12 +99005,16 @@ async function handleGetBoard(fileStore) {
 }
 
 // src/mcp/handlers/doc.ts
-import { existsSync as existsSync30 } from "node:fs";
-import { mkdir as mkdir17, readFile as readFile22, readdir as readdir13, writeFile as writeFile16 } from "node:fs/promises";
-import { join as join35 } from "node:path";
-var import_gray_matter9 = __toESM(require_gray_matter(), 1);
+import { existsSync as existsSync32 } from "node:fs";
+import { mkdir as mkdir17, readFile as readFile24, readdir as readdir14, writeFile as writeFile17 } from "node:fs/promises";
+import { join as join37 } from "node:path";
+var import_gray_matter11 = __toESM(require_gray_matter(), 1);
 function getDocsDir() {
-  return join35(getProjectRoot3(), ".knowns", "docs");
+  return join37(getProjectRoot3(), ".knowns", "docs");
+}
+function normalizeNewlines2(text) {
+  if (!text) return text;
+  return text.replace(/\\n/g, "\n");
 }
 var listDocsSchema = external_exports.object({
   tag: external_exports.string().optional()
@@ -98883,7 +99165,7 @@ var docTools = [
   }
 ];
 async function ensureDocsDir2() {
-  if (!existsSync30(getDocsDir())) {
+  if (!existsSync32(getDocsDir())) {
     await mkdir17(getDocsDir(), { recursive: true });
   }
 }
@@ -98892,13 +99174,13 @@ function titleToFilename2(title) {
 }
 async function getAllMdFiles2(dir, basePath = "") {
   const files = [];
-  if (!existsSync30(dir)) {
+  if (!existsSync32(dir)) {
     return files;
   }
-  const entries = await readdir13(dir, { withFileTypes: true });
+  const entries = await readdir14(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join35(dir, entry.name);
-    const relativePath = normalizePath2(basePath ? join35(basePath, entry.name) : entry.name);
+    const fullPath = join37(dir, entry.name);
+    const relativePath = normalizePath2(basePath ? join37(basePath, entry.name) : entry.name);
     if (entry.isDirectory()) {
       const subFiles = await getAllMdFiles2(fullPath, relativePath);
       files.push(...subFiles);
@@ -98911,13 +99193,13 @@ async function getAllMdFiles2(dir, basePath = "") {
 async function resolveDocPath2(name) {
   await ensureDocsDir2();
   let filename = name.endsWith(".md") ? name : `${name}.md`;
-  let filepath = join35(getDocsDir(), filename);
-  if (existsSync30(filepath)) {
+  let filepath = join37(getDocsDir(), filename);
+  if (existsSync32(filepath)) {
     return { filepath, filename };
   }
   filename = `${titleToFilename2(name)}.md`;
-  filepath = join35(getDocsDir(), filename);
-  if (existsSync30(filepath)) {
+  filepath = join37(getDocsDir(), filename);
+  if (existsSync32(filepath)) {
     return { filepath, filename };
   }
   const allFiles = await getAllMdFiles2(getDocsDir());
@@ -98929,7 +99211,7 @@ async function resolveDocPath2(name) {
   });
   if (matchingFile) {
     return {
-      filepath: join35(getDocsDir(), matchingFile),
+      filepath: join37(getDocsDir(), matchingFile),
       filename: matchingFile
     };
   }
@@ -98950,8 +99232,8 @@ async function handleListDocs(args2) {
   const docs = [];
   for (const doc of allDocs) {
     try {
-      const fileContent = await readFile22(doc.fullPath, "utf-8");
-      const { data, content } = (0, import_gray_matter9.default)(fileContent);
+      const fileContent = await readFile24(doc.fullPath, "utf-8");
+      const { data, content } = (0, import_gray_matter11.default)(fileContent);
       const metadata = data;
       const stats = calculateDocStats(content);
       if (input.tag && !metadata.tags?.includes(input.tag)) {
@@ -98983,8 +99265,8 @@ async function handleGetDoc(args2) {
   if (!resolved) {
     return errorResponse(`Documentation not found: ${input.path}`);
   }
-  const fileContent = await readFile22(resolved.filepath, "utf-8");
-  const { data, content } = (0, import_gray_matter9.default)(fileContent);
+  const fileContent = await readFile24(resolved.filepath, "utf-8");
+  const { data, content } = (0, import_gray_matter11.default)(fileContent);
   const metadata = data;
   if (input.smart) {
     const stats = calculateDocStats(content);
@@ -99079,7 +99361,7 @@ async function handleGetDoc(args2) {
     });
   }
   const projectRoot = getProjectRoot3();
-  const tasksDir = join35(projectRoot, ".knowns", "tasks");
+  const tasksDir = join37(projectRoot, ".knowns", "tasks");
   const refs = await validateRefs(projectRoot, content, tasksDir);
   const brokenRefs = refs.filter((r) => !r.exists).map((r) => r.ref);
   return successResponse({
@@ -99103,14 +99385,14 @@ async function handleCreateDoc(args2) {
   let relativePath = filename;
   if (input.folder) {
     const folderPath = input.folder.replace(/^\/|\/$/g, "");
-    targetDir = join35(getDocsDir(), folderPath);
-    relativePath = join35(folderPath, filename);
-    if (!existsSync30(targetDir)) {
+    targetDir = join37(getDocsDir(), folderPath);
+    relativePath = join37(folderPath, filename);
+    if (!existsSync32(targetDir)) {
       await mkdir17(targetDir, { recursive: true });
     }
   }
-  const filepath = join35(targetDir, filename);
-  if (existsSync30(filepath)) {
+  const filepath = join37(targetDir, filename);
+  if (existsSync32(filepath)) {
     return errorResponse(`Document already exists: ${relativePath}`);
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -99125,9 +99407,9 @@ async function handleCreateDoc(args2) {
   if (input.tags) {
     metadata.tags = input.tags;
   }
-  const initialContent = input.content || "# Content\n\nWrite your documentation here.";
-  const fileContent = import_gray_matter9.default.stringify(initialContent, metadata);
-  await writeFile16(filepath, fileContent, "utf-8");
+  const initialContent = normalizeNewlines2(input.content) || "# Content\n\nWrite your documentation here.";
+  const fileContent = import_gray_matter11.default.stringify(initialContent, metadata);
+  await writeFile17(filepath, fileContent, "utf-8");
   await notifyDocUpdate(relativePath);
   return successResponse({
     message: `Created documentation: ${relativePath}`,
@@ -99145,8 +99427,8 @@ async function handleUpdateDoc(args2) {
   if (!resolved) {
     return errorResponse(`Documentation not found: ${input.path}`);
   }
-  const fileContent = await readFile22(resolved.filepath, "utf-8");
-  const { data, content } = (0, import_gray_matter9.default)(fileContent);
+  const fileContent = await readFile24(resolved.filepath, "utf-8");
+  const { data, content } = (0, import_gray_matter11.default)(fileContent);
   const metadata = data;
   if (input.title) metadata.title = input.title;
   if (input.description) metadata.description = input.description;
@@ -99154,9 +99436,11 @@ async function handleUpdateDoc(args2) {
   metadata.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   let updatedContent = content;
   let sectionUpdated;
-  if (input.section && input.content) {
+  const normalizedContent = normalizeNewlines2(input.content);
+  const normalizedAppend = normalizeNewlines2(input.appendContent);
+  if (input.section && normalizedContent) {
     const sectionIndex = /^\d+$/.test(input.section) ? Number.parseInt(input.section, 10) : null;
-    const result = sectionIndex !== null ? replaceSectionByIndex(content, sectionIndex, input.content) : replaceSection(content, input.section, input.content);
+    const result = sectionIndex !== null ? replaceSectionByIndex(content, sectionIndex, normalizedContent) : replaceSection(content, input.section, normalizedContent);
     if (!result) {
       return errorResponse(
         `Section not found: ${input.section}. Use 'toc: true' with get_doc to see available sections.`
@@ -99164,16 +99448,16 @@ async function handleUpdateDoc(args2) {
     }
     updatedContent = result;
     sectionUpdated = input.section;
-  } else if (input.content) {
-    updatedContent = input.content;
+  } else if (normalizedContent) {
+    updatedContent = normalizedContent;
   }
-  if (input.appendContent) {
+  if (normalizedAppend) {
     updatedContent = `${updatedContent.trimEnd()}
 
-${input.appendContent}`;
+${normalizedAppend}`;
   }
-  const newFileContent = import_gray_matter9.default.stringify(updatedContent, metadata);
-  await writeFile16(resolved.filepath, newFileContent, "utf-8");
+  const newFileContent = import_gray_matter11.default.stringify(updatedContent, metadata);
+  await writeFile17(resolved.filepath, newFileContent, "utf-8");
   await notifyDocUpdate(resolved.filename);
   return successResponse({
     message: sectionUpdated ? `Updated section "${sectionUpdated}" in ${resolved.filename}` : `Updated documentation: ${resolved.filename}`,
@@ -99194,8 +99478,8 @@ async function handleSearchDocs(args2) {
   const query = input.query.toLowerCase();
   const results = [];
   for (const file3 of mdFiles) {
-    const fileContent = await readFile22(join35(getDocsDir(), file3), "utf-8");
-    const { data, content } = (0, import_gray_matter9.default)(fileContent);
+    const fileContent = await readFile24(join37(getDocsDir(), file3), "utf-8");
+    const { data, content } = (0, import_gray_matter11.default)(fileContent);
     const metadata = data;
     if (input.tag && !metadata.tags?.includes(input.tag)) {
       continue;
@@ -99231,11 +99515,11 @@ async function handleSearchDocs(args2) {
 }
 
 // src/mcp/handlers/template.ts
-import { existsSync as existsSync31 } from "node:fs";
-import { mkdir as mkdir18, writeFile as writeFile17 } from "node:fs/promises";
-import { join as join36 } from "node:path";
+import { existsSync as existsSync33 } from "node:fs";
+import { mkdir as mkdir18, writeFile as writeFile18 } from "node:fs/promises";
+import { join as join38 } from "node:path";
 function getTemplatesDir() {
-  return join36(getProjectRoot3(), ".knowns", "templates");
+  return join38(getProjectRoot3(), ".knowns", "templates");
 }
 var listTemplatesSchema = external_exports.object({});
 var getTemplateSchema = external_exports.object({
@@ -99342,7 +99626,7 @@ async function handleListTemplates(_args) {
     const templateList = [];
     for (const t of allTemplates) {
       try {
-        const loaded = await listTemplates(join36(t.path, ".."));
+        const loaded = await listTemplates(join38(t.path, ".."));
         const match2 = loaded.find((l) => l.name === t.name);
         templateList.push({
           name: t.name,
@@ -99485,11 +99769,11 @@ async function handleRunTemplate(args2) {
 async function handleCreateTemplate(args2) {
   const input = createTemplateSchema.parse(args2);
   try {
-    if (!existsSync31(getTemplatesDir())) {
+    if (!existsSync33(getTemplatesDir())) {
       await mkdir18(getTemplatesDir(), { recursive: true });
     }
-    const templateDir = join36(getTemplatesDir(), input.name);
-    if (existsSync31(templateDir)) {
+    const templateDir = join38(getTemplatesDir(), input.name);
+    if (existsSync33(templateDir)) {
       return errorResponse(`Template "${input.name}" already exists`);
     }
     await mkdir18(templateDir, { recursive: true });
@@ -99518,7 +99802,7 @@ messages:
   success: |
     \u2713 Created {{name}}!
 `;
-    await writeFile17(join36(templateDir, "_template.yaml"), configContent, "utf-8");
+    await writeFile18(join38(templateDir, "_template.yaml"), configContent, "utf-8");
     const exampleTemplate = `/**
  * {{pascalCase name}}
  * Generated from ${input.name} template
@@ -99528,7 +99812,7 @@ export function {{camelCase name}}() {
   console.log("Hello from {{name}}!");
 }
 `;
-    await writeFile17(join36(templateDir, "example.ts.hbs"), exampleTemplate, "utf-8");
+    await writeFile18(join38(templateDir, "example.ts.hbs"), exampleTemplate, "utf-8");
     return successResponse({
       message: `Created template: ${input.name}`,
       template: {
@@ -99550,10 +99834,10 @@ export function {{camelCase name}}() {
 }
 
 // src/mcp/handlers/search.ts
-var import_gray_matter10 = __toESM(require_gray_matter(), 1);
-import { existsSync as existsSync32 } from "node:fs";
-import { readFile as readFile23, readdir as readdir14 } from "node:fs/promises";
-import { join as join37 } from "node:path";
+var import_gray_matter12 = __toESM(require_gray_matter(), 1);
+import { existsSync as existsSync34 } from "node:fs";
+import { readFile as readFile25, readdir as readdir15 } from "node:fs/promises";
+import { join as join39 } from "node:path";
 var searchSchema = external_exports.object({
   query: external_exports.string(),
   type: external_exports.enum(["all", "task", "doc"]).optional(),
@@ -99640,12 +99924,12 @@ function calculateDocScore2(title, description, content, tags, query) {
 }
 async function getAllMdFiles3(dir, basePath = "") {
   const files = [];
-  if (!existsSync32(dir)) {
+  if (!existsSync34(dir)) {
     return files;
   }
-  const entries = await readdir14(dir, { withFileTypes: true });
+  const entries = await readdir15(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join37(dir, entry.name);
+    const fullPath = join39(dir, entry.name);
     const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
     if (entry.isDirectory()) {
       const subFiles = await getAllMdFiles3(fullPath, relativePath);
@@ -99688,15 +99972,15 @@ async function searchTasks(fileStore, query, filters) {
   })).sort((a, b) => b.score - a.score);
 }
 async function searchDocs2(docsDir, query, tagFilter) {
-  if (!existsSync32(docsDir)) {
+  if (!existsSync34(docsDir)) {
     return [];
   }
   const mdFiles = await getAllMdFiles3(docsDir);
   const q = query.toLowerCase();
   const results = [];
   for (const file3 of mdFiles) {
-    const fileContent = await readFile23(join37(docsDir, file3), "utf-8");
-    const { data, content } = (0, import_gray_matter10.default)(fileContent);
+    const fileContent = await readFile25(join39(docsDir, file3), "utf-8");
+    const { data, content } = (0, import_gray_matter12.default)(fileContent);
     const metadata = data;
     if (tagFilter && !metadata.tags?.includes(tagFilter)) {
       continue;
@@ -99732,7 +100016,7 @@ async function handleSearch(args2, fileStore) {
   const input = searchSchema.parse(args2);
   const searchType = input.type || "all";
   const limit = input.limit || 20;
-  const docsDir = join37(getProjectRoot3(), ".knowns", "docs");
+  const docsDir = join39(getProjectRoot3(), ".knowns", "docs");
   let taskResults = [];
   let docResults = [];
   if (searchType === "all" || searchType === "task") {
@@ -99763,6 +100047,657 @@ async function handleSearch(args2, fileStore) {
   });
 }
 
+// src/mcp/handlers/validate.ts
+import { existsSync as existsSync35 } from "node:fs";
+import { readFile as readFile26, readdir as readdir16, writeFile as writeFile19 } from "node:fs/promises";
+import { join as join40 } from "node:path";
+var import_gray_matter13 = __toESM(require_gray_matter(), 1);
+var import_handlebars2 = __toESM(require_lib2(), 1);
+init_config();
+var validateTools = [
+  {
+    name: "validate",
+    description: "Validate tasks, docs, and templates for reference integrity and quality. Returns errors, warnings, and info about broken refs, missing AC, orphan docs, etc. Use scope='sdd' for SDD (Spec-Driven Development) validation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: {
+          type: "string",
+          enum: ["all", "tasks", "docs", "templates", "sdd"],
+          description: "Validation scope: 'all' (default), 'tasks', 'docs', 'templates', or 'sdd' for spec-driven checks"
+        },
+        strict: {
+          type: "boolean",
+          description: "Treat warnings as errors (default: false)"
+        },
+        fix: {
+          type: "boolean",
+          description: "Auto-fix supported issues like broken doc refs (default: false)"
+        }
+      }
+    }
+  }
+];
+function stripTrailingPunctuation(path3) {
+  return path3.replace(/[.,;:!?`'")\]]+$/, "");
+}
+function extractRefs(content) {
+  const docRefs = [];
+  const taskRefs = [];
+  const templateRefs = [];
+  const docRefPattern = /@docs?\/([^\s,;:!?"'()\]]+)/g;
+  for (const match2 of content.matchAll(docRefPattern)) {
+    let docPath = stripTrailingPunctuation(match2[1] || "");
+    docPath = docPath.replace(/\.md$/, "");
+    if (docPath && !docRefs.includes(docPath)) {
+      docRefs.push(docPath);
+    }
+  }
+  const taskRefPattern = /@task-([a-zA-Z0-9]+)/g;
+  for (const match2 of content.matchAll(taskRefPattern)) {
+    const taskId = match2[1] || "";
+    if (taskId && !taskRefs.includes(taskId)) {
+      taskRefs.push(taskId);
+    }
+  }
+  const templateRefPattern = /@template\/([^\s,;:!?"'()\]]+)/g;
+  for (const match2 of content.matchAll(templateRefPattern)) {
+    const templateName = stripTrailingPunctuation(match2[1] || "");
+    if (templateName && !templateRefs.includes(templateName)) {
+      templateRefs.push(templateName);
+    }
+  }
+  return { docRefs, taskRefs, templateRefs };
+}
+async function loadValidateConfig(projectRoot) {
+  const config2 = await readConfig(projectRoot);
+  return config2.validate || {};
+}
+function getRuleSeverity(rule, defaultSeverity, validateConfig) {
+  if (validateConfig.rules?.[rule]) {
+    return validateConfig.rules[rule];
+  }
+  return defaultSeverity;
+}
+function shouldIgnore(entity, validateConfig) {
+  if (!validateConfig.ignore) return false;
+  for (const pattern of validateConfig.ignore) {
+    const regex2 = new RegExp(`^${pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*")}$`);
+    if (regex2.test(entity)) return true;
+  }
+  return false;
+}
+async function findSimilarDocs(projectRoot, brokenRef) {
+  const docsDir = join40(projectRoot, ".knowns", "docs");
+  if (!existsSync35(docsDir)) return null;
+  const allDocs = [];
+  async function scanDir(dir, relativePath) {
+    const entries = await readdir16(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await scanDir(join40(dir, entry.name), entryRelPath);
+      } else if (entry.name.endsWith(".md")) {
+        allDocs.push(entryRelPath.replace(/\.md$/, ""));
+      }
+    }
+  }
+  await scanDir(docsDir, "");
+  const brokenLower = brokenRef.toLowerCase();
+  let bestMatch = null;
+  let bestScore = 0;
+  for (const doc of allDocs) {
+    const docLower = doc.toLowerCase();
+    const brokenParts = brokenLower.split(/[-_/]/);
+    const docParts = docLower.split(/[-_/]/);
+    let matchScore = 0;
+    for (const part of brokenParts) {
+      if (docLower.includes(part) && part.length > 2) {
+        matchScore += part.length;
+      }
+    }
+    for (const part of docParts) {
+      if (brokenLower.includes(part) && part.length > 2) {
+        matchScore += part.length;
+      }
+    }
+    if (matchScore > bestScore) {
+      bestScore = matchScore;
+      bestMatch = doc;
+    }
+  }
+  return bestScore >= 3 ? bestMatch : null;
+}
+async function validateTasks(projectRoot, fileStore, validateConfig) {
+  const issues = [];
+  const tasks = await fileStore.getAllTasks();
+  const taskIds = new Set(tasks.map((t) => t.id));
+  for (const task of tasks) {
+    const taskRef = `task-${task.id}`;
+    if (shouldIgnore(taskRef, validateConfig)) continue;
+    const content = `${task.description || ""} ${task.implementationPlan || ""} ${task.implementationNotes || ""}`;
+    const { docRefs, taskRefs, templateRefs } = extractRefs(content);
+    const noAcSeverity = getRuleSeverity("task-no-ac", "warning", validateConfig);
+    if (noAcSeverity !== "off" && (!task.acceptanceCriteria || task.acceptanceCriteria.length === 0)) {
+      issues.push({
+        entity: taskRef,
+        entityType: "task",
+        rule: "task-no-ac",
+        severity: noAcSeverity,
+        message: "Task has no acceptance criteria"
+      });
+    }
+    const noDescSeverity = getRuleSeverity("task-no-description", "warning", validateConfig);
+    if (noDescSeverity !== "off" && (!task.description || task.description.trim() === "")) {
+      issues.push({
+        entity: taskRef,
+        entityType: "task",
+        rule: "task-no-description",
+        severity: noDescSeverity,
+        message: "Task has no description"
+      });
+    }
+    const brokenDocSeverity = getRuleSeverity("task-broken-doc-ref", "error", validateConfig);
+    if (brokenDocSeverity !== "off") {
+      for (const docPath of docRefs) {
+        const resolved = await resolveDoc(projectRoot, docPath);
+        if (!resolved) {
+          const suggestion = await findSimilarDocs(projectRoot, docPath);
+          const issue2 = {
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-broken-doc-ref",
+            severity: brokenDocSeverity,
+            message: suggestion ? `Broken reference: @doc/${docPath} \u2192 did you mean @doc/${suggestion}?` : `Broken reference: @doc/${docPath}`,
+            fixable: !!suggestion
+          };
+          if (suggestion) {
+            issue2.fix = async () => {
+              const tasksDir = join40(projectRoot, ".knowns", "tasks");
+              const files = await readdir16(tasksDir);
+              const taskFile = files.find((f) => f.startsWith(`task-${task.id} `));
+              if (taskFile) {
+                const taskFilePath = join40(tasksDir, taskFile);
+                const taskContent = await readFile26(taskFilePath, "utf-8");
+                const updated = taskContent.replace(
+                  new RegExp(`@docs?/${docPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g"),
+                  `@doc/${suggestion}`
+                );
+                await writeFile19(taskFilePath, updated, "utf-8");
+              }
+            };
+          }
+          issues.push(issue2);
+        }
+      }
+    }
+    const brokenTaskSeverity = getRuleSeverity("task-broken-task-ref", "error", validateConfig);
+    if (brokenTaskSeverity !== "off") {
+      for (const refTaskId of taskRefs) {
+        if (!taskIds.has(refTaskId)) {
+          issues.push({
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-broken-task-ref",
+            severity: brokenTaskSeverity,
+            message: `Broken reference: @task-${refTaskId}`
+          });
+        }
+      }
+    }
+    const brokenTplSeverity = getRuleSeverity("task-broken-template-ref", "error", validateConfig);
+    if (brokenTplSeverity !== "off") {
+      for (const templateName of templateRefs) {
+        const resolved = await resolveTemplate(projectRoot, templateName);
+        if (!resolved) {
+          issues.push({
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-broken-template-ref",
+            severity: brokenTplSeverity,
+            message: `Broken reference: @template/${templateName}`
+          });
+        }
+      }
+    }
+    const selfRefSeverity = getRuleSeverity("task-self-ref", "warning", validateConfig);
+    if (selfRefSeverity !== "off" && taskRefs.includes(task.id)) {
+      issues.push({
+        entity: taskRef,
+        entityType: "task",
+        rule: "task-self-ref",
+        severity: selfRefSeverity,
+        message: "Task references itself"
+      });
+    }
+    const circularSeverity = getRuleSeverity("task-circular-parent", "error", validateConfig);
+    if (circularSeverity !== "off" && task.parent) {
+      const visited = /* @__PURE__ */ new Set();
+      let currentId = task.parent;
+      while (currentId) {
+        if (visited.has(currentId) || currentId === task.id) {
+          issues.push({
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-circular-parent",
+            severity: circularSeverity,
+            message: currentId === task.id ? "Task is its own ancestor" : "Circular parent-child relationship detected"
+          });
+          break;
+        }
+        visited.add(currentId);
+        const parentTask = tasks.find((t) => t.id === currentId);
+        currentId = parentTask?.parent;
+      }
+    }
+  }
+  return issues;
+}
+async function validateDocs(projectRoot, fileStore, validateConfig) {
+  const issues = [];
+  const docsDir = join40(projectRoot, ".knowns", "docs");
+  if (!existsSync35(docsDir)) return issues;
+  const tasks = await fileStore.getAllTasks();
+  const taskIds = new Set(tasks.map((t) => t.id));
+  const referencedDocs = /* @__PURE__ */ new Set();
+  for (const task of tasks) {
+    const content = `${task.description || ""} ${task.implementationPlan || ""} ${task.implementationNotes || ""}`;
+    const { docRefs } = extractRefs(content);
+    for (const ref of docRefs) {
+      referencedDocs.add(ref.toLowerCase());
+    }
+  }
+  async function scanDir(dir, relativePath) {
+    const entries = await readdir16(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const fullPath = join40(dir, entry.name);
+      const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await scanDir(fullPath, entryRelPath);
+      } else if (entry.name.endsWith(".md")) {
+        const docPath = entryRelPath.replace(/\.md$/, "");
+        const docRef = `docs/${docPath}`;
+        if (shouldIgnore(docRef, validateConfig) || shouldIgnore(docPath, validateConfig)) continue;
+        try {
+          const content = await readFile26(fullPath, "utf-8");
+          const { data, content: docContent } = (0, import_gray_matter13.default)(content);
+          const noDescSeverity = getRuleSeverity("doc-no-description", "warning", validateConfig);
+          if (noDescSeverity !== "off" && (!data.description || String(data.description).trim() === "")) {
+            issues.push({
+              entity: docRef,
+              entityType: "doc",
+              rule: "doc-no-description",
+              severity: noDescSeverity,
+              message: "Doc has no description"
+            });
+          }
+          const orphanSeverity = getRuleSeverity("doc-orphan", "info", validateConfig);
+          if (orphanSeverity !== "off" && !referencedDocs.has(docPath.toLowerCase())) {
+            issues.push({
+              entity: docRef,
+              entityType: "doc",
+              rule: "doc-orphan",
+              severity: orphanSeverity,
+              message: "Doc is not referenced by any task"
+            });
+          }
+          const { docRefs, taskRefs } = extractRefs(docContent);
+          const brokenDocSeverity = getRuleSeverity("doc-broken-doc-ref", "error", validateConfig);
+          if (brokenDocSeverity !== "off") {
+            for (const refDocPath of docRefs) {
+              const resolved = await resolveDoc(projectRoot, refDocPath);
+              if (!resolved) {
+                const suggestion = await findSimilarDocs(projectRoot, refDocPath);
+                const issue2 = {
+                  entity: docRef,
+                  entityType: "doc",
+                  rule: "doc-broken-doc-ref",
+                  severity: brokenDocSeverity,
+                  message: suggestion ? `Broken reference: @doc/${refDocPath} \u2192 did you mean @doc/${suggestion}?` : `Broken reference: @doc/${refDocPath}`,
+                  fixable: !!suggestion
+                };
+                if (suggestion) {
+                  issue2.fix = async () => {
+                    const docFileContent = await readFile26(fullPath, "utf-8");
+                    const updated = docFileContent.replace(
+                      new RegExp(`@docs?/${refDocPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g"),
+                      `@doc/${suggestion}`
+                    );
+                    await writeFile19(fullPath, updated, "utf-8");
+                  };
+                }
+                issues.push(issue2);
+              }
+            }
+          }
+          const brokenTaskSeverity = getRuleSeverity("doc-broken-task-ref", "error", validateConfig);
+          if (brokenTaskSeverity !== "off") {
+            for (const refTaskId of taskRefs) {
+              if (!taskIds.has(refTaskId)) {
+                const issue2 = {
+                  entity: docRef,
+                  entityType: "doc",
+                  rule: "doc-broken-task-ref",
+                  severity: brokenTaskSeverity,
+                  message: `Broken reference: @task-${refTaskId}`,
+                  fixable: true
+                };
+                issue2.fix = async () => {
+                  const docFileContent = await readFile26(fullPath, "utf-8");
+                  const updated = docFileContent.replace(
+                    new RegExp(`@task-${refTaskId}\\b`, "g"),
+                    `~task-${refTaskId}`
+                  );
+                  await writeFile19(fullPath, updated, "utf-8");
+                };
+                issues.push(issue2);
+              }
+            }
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  await scanDir(docsDir, "");
+  return issues;
+}
+async function validateTemplates(projectRoot, validateConfig) {
+  const issues = [];
+  const templates = await listAllTemplates(projectRoot);
+  for (const template of templates) {
+    const templateRef = `templates/${template.ref}`;
+    if (shouldIgnore(templateRef, validateConfig)) continue;
+    try {
+      const config2 = await getTemplateConfig(template.path);
+      const invalidSyntaxSeverity = getRuleSeverity("template-invalid-syntax", "error", validateConfig);
+      if (invalidSyntaxSeverity !== "off" && !config2) {
+        issues.push({
+          entity: templateRef,
+          entityType: "template",
+          rule: "template-invalid-syntax",
+          severity: invalidSyntaxSeverity,
+          message: "Failed to load template config (invalid or missing _template.yaml)"
+        });
+        continue;
+      }
+      if (!config2) continue;
+      const brokenDocSeverity = getRuleSeverity("template-broken-doc-ref", "error", validateConfig);
+      if (brokenDocSeverity !== "off" && config2.doc) {
+        const resolved = await resolveDoc(projectRoot, config2.doc);
+        if (!resolved) {
+          issues.push({
+            entity: templateRef,
+            entityType: "template",
+            rule: "template-broken-doc-ref",
+            severity: brokenDocSeverity,
+            message: `Broken doc reference: @doc/${config2.doc}`
+          });
+        }
+      }
+      if (invalidSyntaxSeverity !== "off") {
+        for (const action of config2.actions || []) {
+          if (action.type === "add" && action.template) {
+            const templateFilePath = join40(template.path, action.template);
+            if (existsSync35(templateFilePath)) {
+              try {
+                const templateContent = await readFile26(templateFilePath, "utf-8");
+                import_handlebars2.default.compile(templateContent);
+              } catch (err) {
+                issues.push({
+                  entity: templateRef,
+                  entityType: "template",
+                  rule: "template-invalid-syntax",
+                  severity: invalidSyntaxSeverity,
+                  message: `Invalid Handlebars syntax in ${action.template}: ${err instanceof Error ? err.message : "unknown error"}`
+                });
+              }
+            }
+          }
+        }
+      }
+      const missingPartialSeverity = getRuleSeverity("template-missing-partial", "error", validateConfig);
+      if (missingPartialSeverity !== "off" && existsSync35(template.path)) {
+        const files = await readdir16(template.path);
+        const hbsFiles = files.filter((f) => f.endsWith(".hbs"));
+        for (const hbsFile of hbsFiles) {
+          const content = await readFile26(join40(template.path, hbsFile), "utf-8");
+          const partialPattern = /\{\{>\s*([^\s}]+)\s*\}\}/g;
+          for (const match2 of content.matchAll(partialPattern)) {
+            const partialName = match2[1];
+            const partialPath = join40(template.path, `_${partialName}.hbs`);
+            if (!existsSync35(partialPath)) {
+              issues.push({
+                entity: templateRef,
+                entityType: "template",
+                rule: "template-missing-partial",
+                severity: missingPartialSeverity,
+                message: `Missing partial: ${partialName} (expected at _${partialName}.hbs)`
+              });
+            }
+          }
+        }
+      }
+    } catch (err) {
+      const invalidSyntaxSeverity = getRuleSeverity("template-invalid-syntax", "error", validateConfig);
+      if (invalidSyntaxSeverity !== "off") {
+        issues.push({
+          entity: templateRef,
+          entityType: "template",
+          rule: "template-invalid-syntax",
+          severity: invalidSyntaxSeverity,
+          message: `Failed to load template config: ${err instanceof Error ? err.message : "unknown error"}`
+        });
+      }
+    }
+  }
+  return issues;
+}
+async function applyFixes(issues) {
+  const results = [];
+  const fixableIssues = issues.filter((i) => i.fixable && i.fix);
+  for (const issue2 of fixableIssues) {
+    try {
+      await issue2.fix?.();
+      results.push({
+        entity: issue2.entity,
+        rule: issue2.rule,
+        action: issue2.message,
+        success: true
+      });
+    } catch (err) {
+      results.push({
+        entity: issue2.entity,
+        rule: issue2.rule,
+        action: `Failed: ${err instanceof Error ? err.message : "unknown error"}`,
+        success: false
+      });
+    }
+  }
+  return results;
+}
+async function runSDDValidation(projectRoot, fileStore) {
+  const tasks = await fileStore.getAllTasks();
+  const docsDir = join40(projectRoot, ".knowns", "docs");
+  const stats = {
+    specs: { total: 0, approved: 0, draft: 0 },
+    tasks: { total: tasks.length, done: 0, inProgress: 0, todo: 0, withSpec: 0, withoutSpec: 0 },
+    coverage: { linked: 0, total: tasks.length, percent: 0 },
+    acCompletion: {}
+  };
+  const warnings = [];
+  const passed = [];
+  for (const task of tasks) {
+    if (task.status === "done") stats.tasks.done++;
+    else if (task.status === "in-progress") stats.tasks.inProgress++;
+    else stats.tasks.todo++;
+    if (task.spec) {
+      stats.tasks.withSpec++;
+    } else {
+      stats.tasks.withoutSpec++;
+      warnings.push({
+        type: "task-no-spec",
+        entity: `task-${task.id}`,
+        message: `${task.title} has no spec reference`
+      });
+    }
+  }
+  stats.coverage.linked = stats.tasks.withSpec;
+  stats.coverage.percent = stats.tasks.total > 0 ? Math.round(stats.tasks.withSpec / stats.tasks.total * 100) : 0;
+  const specsDir = join40(docsDir, "specs");
+  if (existsSync35(specsDir)) {
+    async function scanSpecs(dir, relativePath) {
+      const entries = await readdir16(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+          await scanSpecs(join40(dir, entry.name), entryRelPath);
+        } else if (entry.name.endsWith(".md")) {
+          stats.specs.total++;
+          const specPath = `specs/${entryRelPath.replace(/\.md$/, "")}`;
+          try {
+            const content = await readFile26(join40(dir, entry.name), "utf-8");
+            const { data } = (0, import_gray_matter13.default)(content);
+            if (data.status === "approved" || data.status === "implemented") {
+              stats.specs.approved++;
+            } else {
+              stats.specs.draft++;
+            }
+            const linkedTasks = tasks.filter((t) => t.spec === specPath);
+            if (linkedTasks.length > 0) {
+              let totalAC = 0;
+              let completedAC = 0;
+              for (const task of linkedTasks) {
+                totalAC += task.acceptanceCriteria.length;
+                completedAC += task.acceptanceCriteria.filter((ac) => ac.completed).length;
+              }
+              const percent = totalAC > 0 ? Math.round(completedAC / totalAC * 100) : 100;
+              stats.acCompletion[specPath] = { total: totalAC, completed: completedAC, percent };
+              if (percent < 100 && totalAC > 0) {
+                warnings.push({
+                  type: "spec-ac-incomplete",
+                  entity: specPath,
+                  message: `${completedAC}/${totalAC} ACs complete (${percent}%)`
+                });
+              }
+            }
+          } catch {
+          }
+        }
+      }
+    }
+    await scanSpecs(specsDir, "");
+  }
+  for (const task of tasks) {
+    if (task.spec) {
+      const specDocPath = join40(docsDir, `${task.spec}.md`);
+      if (!existsSync35(specDocPath)) {
+        warnings.push({
+          type: "spec-broken-link",
+          entity: `task-${task.id}`,
+          message: `Broken spec reference: @doc/${task.spec}`
+        });
+      }
+    }
+  }
+  if (warnings.filter((w) => w.type === "spec-broken-link").length === 0) {
+    passed.push("All spec references resolve");
+  }
+  for (const [specPath, completion] of Object.entries(stats.acCompletion)) {
+    if (completion.percent === 100) {
+      passed.push(`${specPath}: fully implemented`);
+    }
+  }
+  return { stats, warnings, passed };
+}
+async function handleValidate(args2, fileStore) {
+  try {
+    const projectRoot = getProjectRoot3();
+    if (args2?.scope === "sdd") {
+      const sddResult = await runSDDValidation(projectRoot, fileStore);
+      return successResponse({
+        mode: "sdd",
+        stats: sddResult.stats,
+        warnings: sddResult.warnings,
+        passed: sddResult.passed
+      });
+    }
+    const validateConfig = await loadValidateConfig(projectRoot);
+    const allIssues = [];
+    const stats = { tasks: 0, docs: 0, templates: 0 };
+    if (!args2?.type || args2.type === "task") {
+      const tasks = await fileStore.getAllTasks();
+      stats.tasks = tasks.length;
+      const taskIssues = await validateTasks(projectRoot, fileStore, validateConfig);
+      allIssues.push(...taskIssues);
+    }
+    if (!args2?.type || args2.type === "doc") {
+      const docsDir = join40(projectRoot, ".knowns", "docs");
+      if (existsSync35(docsDir)) {
+        async function countDocs(dir) {
+          let count = 0;
+          const entries = await readdir16(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.name.startsWith(".")) continue;
+            if (entry.isDirectory()) {
+              count += await countDocs(join40(dir, entry.name));
+            } else if (entry.name.endsWith(".md")) {
+              count++;
+            }
+          }
+          return count;
+        }
+        stats.docs = await countDocs(docsDir);
+      }
+      const docIssues = await validateDocs(projectRoot, fileStore, validateConfig);
+      allIssues.push(...docIssues);
+    }
+    if (!args2?.type || args2.type === "template") {
+      const templates = await listAllTemplates(projectRoot);
+      stats.templates = templates.length;
+      const templateIssues = await validateTemplates(projectRoot, validateConfig);
+      allIssues.push(...templateIssues);
+    }
+    if (args2?.strict) {
+      for (const issue2 of allIssues) {
+        if (issue2.severity === "warning") {
+          issue2.severity = "error";
+        }
+      }
+    }
+    let fixes = [];
+    if (args2?.fix) {
+      fixes = await applyFixes(allIssues);
+    }
+    const errors = allIssues.filter((i) => i.severity === "error");
+    const warnings = allIssues.filter((i) => i.severity === "warning");
+    const infos = allIssues.filter((i) => i.severity === "info");
+    return successResponse({
+      valid: errors.length === 0,
+      stats,
+      summary: {
+        errors: errors.length,
+        warnings: warnings.length,
+        info: infos.length
+      },
+      issues: allIssues.map((i) => ({
+        entity: i.entity,
+        entityType: i.entityType,
+        rule: i.rule,
+        severity: i.severity,
+        message: i.message,
+        fixable: i.fixable || false
+      })),
+      ...args2?.fix && fixes.length > 0 ? { fixes } : {}
+    });
+  } catch (error48) {
+    return errorResponse(error48 instanceof Error ? error48.message : String(error48));
+  }
+}
+
 // src/mcp/server.ts
 var fileStoreCache = /* @__PURE__ */ new Map();
 function getFileStore5() {
@@ -99793,7 +100728,8 @@ var tools = [
   ...boardTools,
   ...docTools,
   ...templateTools,
-  ...searchTools
+  ...searchTools,
+  ...validateTools
 ];
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
@@ -99857,6 +100793,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // Unified search handler
       case "search":
         return await handleSearch(args2, getFileStore5());
+      // Validate handler
+      case "validate":
+        return await handleValidate(args2, getFileStore5());
       default:
         return errorResponse(`Unknown tool: ${name}`);
     }
@@ -99866,7 +100805,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
   const tasks = await getFileStore5().getAllTasks();
-  const docsDir = join38(getProjectRoot3(), ".knowns", "docs");
+  const docsDir = join41(getProjectRoot3(), ".knowns", "docs");
   const taskResources = tasks.map((task) => ({
     uri: `knowns://task/${task.id}`,
     name: task.title,
@@ -99874,14 +100813,14 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     description: `Task #${task.id}: ${task.title}`
   }));
   const docResources = [];
-  if (existsSync33(docsDir)) {
-    const { readdir: readdir16 } = await import("node:fs/promises");
+  if (existsSync36(docsDir)) {
+    const { readdir: readdir19 } = await import("node:fs/promises");
     async function getAllMdFiles4(dir, basePath = "") {
       const files = [];
-      const entries = await readdir16(dir, { withFileTypes: true });
+      const entries = await readdir19(dir, { withFileTypes: true });
       for (const entry of entries) {
-        const fullPath = join38(dir, entry.name);
-        const relativePath = normalizePath2(basePath ? join38(basePath, entry.name) : entry.name);
+        const fullPath = join41(dir, entry.name);
+        const relativePath = normalizePath2(basePath ? join41(basePath, entry.name) : entry.name);
         if (entry.isDirectory()) {
           const subFiles = await getAllMdFiles4(fullPath, relativePath);
           files.push(...subFiles);
@@ -99893,9 +100832,9 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     }
     const mdFiles = await getAllMdFiles4(docsDir);
     for (const file3 of mdFiles) {
-      const filepath = join38(docsDir, file3);
-      const content = await readFile24(filepath, "utf-8");
-      const { data } = (0, import_gray_matter11.default)(content);
+      const filepath = join41(docsDir, file3);
+      const content = await readFile27(filepath, "utf-8");
+      const { data } = (0, import_gray_matter14.default)(content);
       docResources.push({
         uri: `knowns://doc/${file3.replace(/\.md$/, "")}`,
         name: data.title || file3.replace(/\.md$/, ""),
@@ -99930,13 +100869,13 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
   const docMatch = uri.match(/^knowns:\/\/doc\/(.+)$/);
   if (docMatch) {
     const docPath = docMatch[1];
-    const docsDir = join38(getProjectRoot3(), ".knowns", "docs");
-    const filepath = join38(docsDir, `${docPath}.md`);
-    if (!existsSync33(filepath)) {
+    const docsDir = join41(getProjectRoot3(), ".knowns", "docs");
+    const filepath = join41(docsDir, `${docPath}.md`);
+    if (!existsSync36(filepath)) {
       throw new Error(`Documentation ${docPath} not found`);
     }
-    const content = await readFile24(filepath, "utf-8");
-    const { data, content: docContent } = (0, import_gray_matter11.default)(content);
+    const content = await readFile27(filepath, "utf-8");
+    const { data, content: docContent } = (0, import_gray_matter14.default)(content);
     return {
       contents: [
         {
@@ -100014,13 +100953,13 @@ async function setupClaudeCode() {
   return false;
 }
 function createProjectMcpJson(projectRoot) {
-  const mcpJsonPath = join39(projectRoot, ".mcp.json");
+  const mcpJsonPath = join42(projectRoot, ".mcp.json");
   const mcpConfig = {
     mcpServers: {
       knowns: getMcpConfig()
     }
   };
-  if (existsSync34(mcpJsonPath)) {
+  if (existsSync37(mcpJsonPath)) {
     try {
       const existing = JSON.parse(readFileSync3(mcpJsonPath, "utf-8"));
       if (existing?.mcpServers?.knowns) {
@@ -100117,9 +101056,9 @@ function showConfigInfo() {
 }
 
 // src/commands/template.ts
-import { existsSync as existsSync35 } from "node:fs";
-import { mkdir as mkdir19, writeFile as writeFile18 } from "node:fs/promises";
-import { join as join40 } from "node:path";
+import { existsSync as existsSync38 } from "node:fs";
+import { mkdir as mkdir19, writeFile as writeFile20 } from "node:fs/promises";
+import { join as join43 } from "node:path";
 var TEMPLATES_DIR3 = ".knowns/templates";
 function getProjectRoot4() {
   const projectRoot = findProjectRoot();
@@ -100131,11 +101070,11 @@ function getProjectRoot4() {
   return projectRoot;
 }
 function getTemplatesDir2(projectRoot) {
-  return join40(projectRoot, TEMPLATES_DIR3);
+  return join43(projectRoot, TEMPLATES_DIR3);
 }
 async function ensureTemplatesDir(projectRoot) {
   const templatesDir = getTemplatesDir2(projectRoot);
-  if (!existsSync35(templatesDir)) {
+  if (!existsSync38(templatesDir)) {
     await mkdir19(templatesDir, { recursive: true });
   }
   return templatesDir;
@@ -100163,7 +101102,7 @@ var listCommand4 = new Command("list").description("List available templates (lo
     const templatesWithDesc = [];
     for (const t of templates) {
       try {
-        const loaded = await listTemplates(join40(t.path, ".."));
+        const loaded = await listTemplates(join43(t.path, ".."));
         const match2 = loaded.find((l) => l.name === t.name);
         templatesWithDesc.push({
           ref: t.ref,
@@ -100338,8 +101277,8 @@ var createCommand4 = new Command("create").description("Create a new template sc
   try {
     const projectRoot = getProjectRoot4();
     const templatesDir = await ensureTemplatesDir(projectRoot);
-    const templateDir = join40(templatesDir, name);
-    if (existsSync35(templateDir)) {
+    const templateDir = join43(templatesDir, name);
+    if (existsSync38(templateDir)) {
       console.error(source_default.red(`\u2717 Template "${name}" already exists`));
       process.exit(1);
     }
@@ -100370,7 +101309,7 @@ messages:
   success: |
     \u2713 Created {{name}}!
 `;
-    await writeFile18(join40(templateDir, "_template.yaml"), configContent, "utf-8");
+    await writeFile20(join43(templateDir, "_template.yaml"), configContent, "utf-8");
     const exampleTemplate = `/**
  * {{pascalCase name}}
  * Generated from ${name} template
@@ -100380,7 +101319,7 @@ export function {{camelCase name}}() {
   console.log("Hello from {{name}}!");
 }
 `;
-    await writeFile18(join40(templateDir, "example.ts.hbs"), exampleTemplate, "utf-8");
+    await writeFile20(join43(templateDir, "example.ts.hbs"), exampleTemplate, "utf-8");
     console.log();
     console.log(source_default.green(`\u2713 Created template: ${name}`));
     console.log(source_default.gray(`  Location: ${TEMPLATES_DIR3}/${name}/`));
@@ -100531,9 +101470,9 @@ templateCommand.argument("[name]", "Template name (shorthand for view)").option(
 });
 
 // src/commands/skill.ts
-import { existsSync as existsSync36 } from "node:fs";
-import { mkdir as mkdir20, writeFile as writeFile19 } from "node:fs/promises";
-import { join as join41 } from "node:path";
+import { existsSync as existsSync39 } from "node:fs";
+import { mkdir as mkdir20, writeFile as writeFile21 } from "node:fs/promises";
+import { join as join44 } from "node:path";
 var SKILLS_DIR = ".knowns/skills";
 function getProjectRoot5() {
   const projectRoot = findProjectRoot();
@@ -100545,11 +101484,11 @@ function getProjectRoot5() {
   return projectRoot;
 }
 function getSkillsDir(projectRoot) {
-  return join41(projectRoot, SKILLS_DIR);
+  return join44(projectRoot, SKILLS_DIR);
 }
 async function ensureSkillsDir(projectRoot) {
   const skillsDir = getSkillsDir(projectRoot);
-  if (!existsSync36(skillsDir)) {
+  if (!existsSync39(skillsDir)) {
     await mkdir20(skillsDir, { recursive: true });
   }
   return skillsDir;
@@ -100559,7 +101498,7 @@ var listCommand5 = new Command("list").description("List available skills").opti
   try {
     const projectRoot = getProjectRoot5();
     const skillsDir = getSkillsDir(projectRoot);
-    if (!existsSync36(skillsDir)) {
+    if (!existsSync39(skillsDir)) {
       if (options2.plain) {
         console.log("No skills found");
       } else {
@@ -100603,8 +101542,8 @@ var createCommand5 = new Command("create").description("Create a new skill").arg
   try {
     const projectRoot = getProjectRoot5();
     const skillsDir = await ensureSkillsDir(projectRoot);
-    const skillDir = join41(skillsDir, name);
-    if (existsSync36(skillDir)) {
+    const skillDir = join44(skillsDir, name);
+    if (existsSync39(skillDir)) {
       console.error(source_default.red(`\u2717 Skill "${name}" already exists`));
       process.exit(1);
     }
@@ -100635,7 +101574,7 @@ Describe when this skill should be used.
 knowns task list
 \`\`\`
 `;
-    await writeFile19(join41(skillDir, "SKILL.md"), skillContent, "utf-8");
+    await writeFile21(join44(skillDir, "SKILL.md"), skillContent, "utf-8");
     console.log();
     console.log(source_default.green(`\u2713 Created skill: ${name}`));
     console.log(source_default.gray(`  Location: ${SKILLS_DIR}/${name}/SKILL.md`));
@@ -100687,7 +101626,7 @@ var syncCommand2 = new Command("sync").description("Sync skills to AI platforms"
   try {
     const projectRoot = getProjectRoot5();
     const skillsDir = getSkillsDir(projectRoot);
-    if (!existsSync36(skillsDir)) {
+    if (!existsSync39(skillsDir)) {
       console.error(source_default.red("\u2717 No skills directory found"));
       console.error(source_default.gray(`  Create skills in ${SKILLS_DIR}/`));
       process.exit(1);
@@ -100768,12 +101707,12 @@ var statusCommand2 = new Command("status").description("Check skill sync status"
   try {
     const projectRoot = getProjectRoot5();
     const skillsDir = getSkillsDir(projectRoot);
-    const skills = existsSync36(skillsDir) ? await listSkills(skillsDir) : [];
+    const skills = existsSync39(skillsDir) ? await listSkills(skillsDir) : [];
     if (options2.plain) {
       console.log(`Skills: ${skills.length}`);
       for (const platform of PLATFORMS) {
-        const targetPath = join41(projectRoot, platform.targetDir);
-        const exists = existsSync36(targetPath);
+        const targetPath = join44(projectRoot, platform.targetDir);
+        const exists = existsSync39(targetPath);
         console.log(`${platform.name}: ${exists ? "present" : "not found"}`);
       }
     } else {
@@ -100783,8 +101722,8 @@ var statusCommand2 = new Command("status").description("Check skill sync status"
       console.log(source_default.bold("Platforms:"));
       console.log(source_default.gray("\u2500".repeat(50)));
       for (const platform of PLATFORMS) {
-        const targetPath = join41(projectRoot, platform.targetDir);
-        const exists = existsSync36(targetPath);
+        const targetPath = join44(projectRoot, platform.targetDir);
+        const exists = existsSync39(targetPath);
         const status = exists ? source_default.green("\u2713 Present") : source_default.gray("\u25CB Not synced");
         console.log(`  ${platform.name.padEnd(15)} ${platform.targetDir.padEnd(20)} ${status}`);
       }
@@ -101086,11 +102025,880 @@ importCommand.argument("[source]", "Source to import (shorthand for 'import add'
   }
 });
 
+// src/commands/validate.ts
+import { existsSync as existsSync40 } from "node:fs";
+import { readFile as readFile28, readdir as readdir18, writeFile as writeFile22 } from "node:fs/promises";
+import { join as join45 } from "node:path";
+var import_gray_matter15 = __toESM(require_gray_matter(), 1);
+var import_handlebars3 = __toESM(require_lib2(), 1);
+init_config();
+function getFileStore6() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.error(source_default.red("\u2717 Not a knowns project"));
+    console.error(source_default.gray('  Run "knowns init" to initialize'));
+    process.exit(1);
+  }
+  return new FileStore(projectRoot);
+}
+function getProjectRoot7() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.error(source_default.red("\u2717 Not a knowns project"));
+    console.error(source_default.gray('  Run "knowns init" to initialize'));
+    process.exit(1);
+  }
+  return projectRoot;
+}
+async function loadValidateConfig2(projectRoot) {
+  const config2 = await readConfig(projectRoot);
+  return config2.validate || {};
+}
+function getRuleSeverity2(rule, defaultSeverity, validateConfig) {
+  if (validateConfig.rules?.[rule]) {
+    return validateConfig.rules[rule];
+  }
+  return defaultSeverity;
+}
+function shouldIgnore2(entity, validateConfig) {
+  if (!validateConfig.ignore) return false;
+  for (const pattern of validateConfig.ignore) {
+    const regex2 = new RegExp(`^${pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*")}$`);
+    if (regex2.test(entity)) return true;
+  }
+  return false;
+}
+async function findSimilarDocs2(projectRoot, brokenRef) {
+  const docsDir = join45(projectRoot, ".knowns", "docs");
+  if (!existsSync40(docsDir)) return null;
+  const allDocs = [];
+  async function scanDir(dir, relativePath) {
+    const entries = await readdir18(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await scanDir(join45(dir, entry.name), entryRelPath);
+      } else if (entry.name.endsWith(".md")) {
+        allDocs.push(entryRelPath.replace(/\.md$/, ""));
+      }
+    }
+  }
+  await scanDir(docsDir, "");
+  const brokenLower = brokenRef.toLowerCase();
+  let bestMatch = null;
+  let bestScore = 0;
+  for (const doc of allDocs) {
+    const docLower = doc.toLowerCase();
+    const brokenParts = brokenLower.split(/[-_/]/);
+    const docParts = docLower.split(/[-_/]/);
+    let matchScore = 0;
+    for (const part of brokenParts) {
+      if (docLower.includes(part) && part.length > 2) {
+        matchScore += part.length;
+      }
+    }
+    for (const part of docParts) {
+      if (brokenLower.includes(part) && part.length > 2) {
+        matchScore += part.length;
+      }
+    }
+    if (matchScore > bestScore) {
+      bestScore = matchScore;
+      bestMatch = doc;
+    }
+  }
+  return bestScore >= 3 ? bestMatch : null;
+}
+function stripTrailingPunctuation2(path3) {
+  return path3.replace(/[.,;:!?`'")\]]+$/, "");
+}
+function extractRefs2(content) {
+  const docRefs = [];
+  const taskRefs = [];
+  const templateRefs = [];
+  const docRefPattern = /@docs?\/([^\s,;:!?"'()\]]+)/g;
+  for (const match2 of content.matchAll(docRefPattern)) {
+    let docPath = stripTrailingPunctuation2(match2[1] || "");
+    docPath = docPath.replace(/\.md$/, "");
+    if (docPath && !docRefs.includes(docPath)) {
+      docRefs.push(docPath);
+    }
+  }
+  const taskRefPattern = /@task-([a-zA-Z0-9]+)/g;
+  for (const match2 of content.matchAll(taskRefPattern)) {
+    const taskId = match2[1] || "";
+    if (taskId && !taskRefs.includes(taskId)) {
+      taskRefs.push(taskId);
+    }
+  }
+  const templateRefPattern = /@template\/([^\s,;:!?"'()\]]+)/g;
+  for (const match2 of content.matchAll(templateRefPattern)) {
+    const templateName = stripTrailingPunctuation2(match2[1] || "");
+    if (templateName && !templateRefs.includes(templateName)) {
+      templateRefs.push(templateName);
+    }
+  }
+  return { docRefs, taskRefs, templateRefs };
+}
+async function validateTasks2(projectRoot, fileStore, validateConfig) {
+  const issues = [];
+  const tasks = await fileStore.getAllTasks();
+  const taskIds = new Set(tasks.map((t) => t.id));
+  for (const task of tasks) {
+    const taskRef = `task-${task.id}`;
+    if (shouldIgnore2(taskRef, validateConfig)) continue;
+    const content = `${task.description || ""} ${task.implementationPlan || ""} ${task.implementationNotes || ""}`;
+    const { docRefs, taskRefs, templateRefs } = extractRefs2(content);
+    const noAcSeverity = getRuleSeverity2("task-no-ac", "warning", validateConfig);
+    if (noAcSeverity !== "off" && (!task.acceptanceCriteria || task.acceptanceCriteria.length === 0)) {
+      issues.push({
+        entity: taskRef,
+        entityType: "task",
+        rule: "task-no-ac",
+        severity: noAcSeverity,
+        message: "Task has no acceptance criteria"
+      });
+    }
+    const noDescSeverity = getRuleSeverity2("task-no-description", "warning", validateConfig);
+    if (noDescSeverity !== "off" && (!task.description || task.description.trim() === "")) {
+      issues.push({
+        entity: taskRef,
+        entityType: "task",
+        rule: "task-no-description",
+        severity: noDescSeverity,
+        message: "Task has no description"
+      });
+    }
+    const brokenDocSeverity = getRuleSeverity2("task-broken-doc-ref", "error", validateConfig);
+    if (brokenDocSeverity !== "off") {
+      for (const docPath of docRefs) {
+        const resolved = await resolveDoc(projectRoot, docPath);
+        if (!resolved) {
+          const suggestion = await findSimilarDocs2(projectRoot, docPath);
+          const issue2 = {
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-broken-doc-ref",
+            severity: brokenDocSeverity,
+            message: suggestion ? `Broken reference: @doc/${docPath} \u2192 did you mean @doc/${suggestion}?` : `Broken reference: @doc/${docPath}`,
+            fixable: !!suggestion
+          };
+          if (suggestion) {
+            issue2.fix = async () => {
+              const tasksDir = join45(projectRoot, ".knowns", "tasks");
+              const files = await readdir18(tasksDir);
+              const taskFile = files.find((f) => f.startsWith(`task-${task.id} `));
+              if (taskFile) {
+                const taskFilePath = join45(tasksDir, taskFile);
+                const taskContent = await readFile28(taskFilePath, "utf-8");
+                const updated = taskContent.replace(
+                  new RegExp(`@docs?/${docPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g"),
+                  `@doc/${suggestion}`
+                );
+                await writeFile22(taskFilePath, updated, "utf-8");
+              }
+            };
+          }
+          issues.push(issue2);
+        }
+      }
+    }
+    const brokenTaskSeverity = getRuleSeverity2("task-broken-task-ref", "error", validateConfig);
+    if (brokenTaskSeverity !== "off") {
+      for (const refTaskId of taskRefs) {
+        if (!taskIds.has(refTaskId)) {
+          issues.push({
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-broken-task-ref",
+            severity: brokenTaskSeverity,
+            message: `Broken reference: @task-${refTaskId}`
+          });
+        }
+      }
+    }
+    const brokenTplSeverity = getRuleSeverity2("task-broken-template-ref", "error", validateConfig);
+    if (brokenTplSeverity !== "off") {
+      for (const templateName of templateRefs) {
+        const resolved = await resolveTemplate(projectRoot, templateName);
+        if (!resolved) {
+          issues.push({
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-broken-template-ref",
+            severity: brokenTplSeverity,
+            message: `Broken reference: @template/${templateName}`
+          });
+        }
+      }
+    }
+    const selfRefSeverity = getRuleSeverity2("task-self-ref", "warning", validateConfig);
+    if (selfRefSeverity !== "off" && taskRefs.includes(task.id)) {
+      issues.push({
+        entity: taskRef,
+        entityType: "task",
+        rule: "task-self-ref",
+        severity: selfRefSeverity,
+        message: "Task references itself"
+      });
+    }
+    const circularSeverity = getRuleSeverity2("task-circular-parent", "error", validateConfig);
+    if (circularSeverity !== "off" && task.parent) {
+      const visited = /* @__PURE__ */ new Set();
+      let currentId = task.parent;
+      while (currentId) {
+        if (visited.has(currentId)) {
+          issues.push({
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-circular-parent",
+            severity: circularSeverity,
+            message: "Circular parent-child relationship detected"
+          });
+          break;
+        }
+        if (currentId === task.id) {
+          issues.push({
+            entity: taskRef,
+            entityType: "task",
+            rule: "task-circular-parent",
+            severity: circularSeverity,
+            message: "Task is its own ancestor"
+          });
+          break;
+        }
+        visited.add(currentId);
+        const parentTask = tasks.find((t) => t.id === currentId);
+        currentId = parentTask?.parent;
+      }
+    }
+  }
+  return issues;
+}
+async function validateDocs2(projectRoot, fileStore, validateConfig) {
+  const issues = [];
+  const docsDir = join45(projectRoot, ".knowns", "docs");
+  if (!existsSync40(docsDir)) {
+    return issues;
+  }
+  const tasks = await fileStore.getAllTasks();
+  const taskIds = new Set(tasks.map((t) => t.id));
+  const referencedDocs = /* @__PURE__ */ new Set();
+  for (const task of tasks) {
+    const content = `${task.description || ""} ${task.implementationPlan || ""} ${task.implementationNotes || ""}`;
+    const { docRefs } = extractRefs2(content);
+    for (const ref of docRefs) {
+      referencedDocs.add(ref.toLowerCase());
+    }
+  }
+  async function scanDir(dir, relativePath) {
+    const entries = await readdir18(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const fullPath = join45(dir, entry.name);
+      const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await scanDir(fullPath, entryRelPath);
+      } else if (entry.name.endsWith(".md")) {
+        const docPath = entryRelPath.replace(/\.md$/, "");
+        const docRef = `docs/${docPath}`;
+        if (shouldIgnore2(docRef, validateConfig)) continue;
+        if (shouldIgnore2(docPath, validateConfig)) continue;
+        try {
+          const content = await readFile28(fullPath, "utf-8");
+          const { data, content: docContent } = (0, import_gray_matter15.default)(content);
+          const metadata = data;
+          const noDescSeverity = getRuleSeverity2("doc-no-description", "warning", validateConfig);
+          if (noDescSeverity !== "off" && (!metadata.description || metadata.description.trim() === "")) {
+            issues.push({
+              entity: docRef,
+              entityType: "doc",
+              rule: "doc-no-description",
+              severity: noDescSeverity,
+              message: "Doc has no description"
+            });
+          }
+          const orphanSeverity = getRuleSeverity2("doc-orphan", "info", validateConfig);
+          if (orphanSeverity !== "off" && !referencedDocs.has(docPath.toLowerCase())) {
+            issues.push({
+              entity: docRef,
+              entityType: "doc",
+              rule: "doc-orphan",
+              severity: orphanSeverity,
+              message: "Doc is not referenced by any task"
+            });
+          }
+          const { docRefs, taskRefs } = extractRefs2(docContent);
+          const brokenDocSeverity = getRuleSeverity2("doc-broken-doc-ref", "error", validateConfig);
+          if (brokenDocSeverity !== "off") {
+            for (const refDocPath of docRefs) {
+              const resolved = await resolveDoc(projectRoot, refDocPath);
+              if (!resolved) {
+                const suggestion = await findSimilarDocs2(projectRoot, refDocPath);
+                const issue2 = {
+                  entity: docRef,
+                  entityType: "doc",
+                  rule: "doc-broken-doc-ref",
+                  severity: brokenDocSeverity,
+                  message: suggestion ? `Broken reference: @doc/${refDocPath} \u2192 did you mean @doc/${suggestion}?` : `Broken reference: @doc/${refDocPath}`,
+                  fixable: !!suggestion
+                };
+                if (suggestion) {
+                  issue2.fix = async () => {
+                    const docFileContent = await readFile28(fullPath, "utf-8");
+                    const updated = docFileContent.replace(
+                      new RegExp(`@docs?/${refDocPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g"),
+                      `@doc/${suggestion}`
+                    );
+                    await writeFile22(fullPath, updated, "utf-8");
+                  };
+                }
+                issues.push(issue2);
+              }
+            }
+          }
+          const brokenTaskSeverity = getRuleSeverity2("doc-broken-task-ref", "error", validateConfig);
+          if (brokenTaskSeverity !== "off") {
+            for (const refTaskId of taskRefs) {
+              if (!taskIds.has(refTaskId)) {
+                const issue2 = {
+                  entity: docRef,
+                  entityType: "doc",
+                  rule: "doc-broken-task-ref",
+                  severity: brokenTaskSeverity,
+                  message: `Broken reference: @task-${refTaskId}`,
+                  fixable: true
+                };
+                issue2.fix = async () => {
+                  const docFileContent = await readFile28(fullPath, "utf-8");
+                  const updated = docFileContent.replace(
+                    new RegExp(`@task-${refTaskId}\\b`, "g"),
+                    `~task-${refTaskId}`
+                  );
+                  await writeFile22(fullPath, updated, "utf-8");
+                };
+                issues.push(issue2);
+              }
+            }
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  await scanDir(docsDir, "");
+  return issues;
+}
+async function validateTemplates2(projectRoot, validateConfig) {
+  const issues = [];
+  const templates = await listAllTemplates(projectRoot);
+  for (const template of templates) {
+    const templateRef = `templates/${template.ref}`;
+    if (shouldIgnore2(templateRef, validateConfig)) continue;
+    try {
+      const config2 = await getTemplateConfig(template.path);
+      const invalidSyntaxSeverity = getRuleSeverity2("template-invalid-syntax", "error", validateConfig);
+      if (invalidSyntaxSeverity !== "off" && !config2) {
+        issues.push({
+          entity: templateRef,
+          entityType: "template",
+          rule: "template-invalid-syntax",
+          severity: invalidSyntaxSeverity,
+          message: "Failed to load template config (invalid or missing _template.yaml)"
+        });
+        continue;
+      }
+      if (!config2) continue;
+      const brokenDocSeverity = getRuleSeverity2("template-broken-doc-ref", "error", validateConfig);
+      if (brokenDocSeverity !== "off" && config2.doc) {
+        const resolved = await resolveDoc(projectRoot, config2.doc);
+        if (!resolved) {
+          issues.push({
+            entity: templateRef,
+            entityType: "template",
+            rule: "template-broken-doc-ref",
+            severity: brokenDocSeverity,
+            message: `Broken doc reference: @doc/${config2.doc}`
+          });
+        }
+      }
+      if (invalidSyntaxSeverity !== "off") {
+        for (const action of config2.actions || []) {
+          if (action.type === "add" && action.template) {
+            const templateFilePath = join45(template.path, action.template);
+            if (existsSync40(templateFilePath)) {
+              try {
+                const templateContent = await readFile28(templateFilePath, "utf-8");
+                import_handlebars3.default.compile(templateContent);
+              } catch (err) {
+                issues.push({
+                  entity: templateRef,
+                  entityType: "template",
+                  rule: "template-invalid-syntax",
+                  severity: invalidSyntaxSeverity,
+                  message: `Invalid Handlebars syntax in ${action.template}: ${err instanceof Error ? err.message : "unknown error"}`
+                });
+              }
+            }
+          }
+        }
+      }
+      const missingPartialSeverity = getRuleSeverity2("template-missing-partial", "error", validateConfig);
+      if (missingPartialSeverity !== "off") {
+        const templatesDir = template.path;
+        if (existsSync40(templatesDir)) {
+          const files = await readdir18(templatesDir);
+          const hbsFiles = files.filter((f) => f.endsWith(".hbs"));
+          for (const hbsFile of hbsFiles) {
+            const content = await readFile28(join45(templatesDir, hbsFile), "utf-8");
+            const partialPattern = /\{\{>\s*([^\s}]+)\s*\}\}/g;
+            for (const match2 of content.matchAll(partialPattern)) {
+              const partialName = match2[1];
+              const partialPath = join45(templatesDir, `_${partialName}.hbs`);
+              if (!existsSync40(partialPath)) {
+                issues.push({
+                  entity: templateRef,
+                  entityType: "template",
+                  rule: "template-missing-partial",
+                  severity: missingPartialSeverity,
+                  message: `Missing partial: ${partialName} (expected at _${partialName}.hbs)`
+                });
+              }
+            }
+          }
+        }
+      }
+    } catch (err) {
+      const invalidSyntaxSeverity = getRuleSeverity2("template-invalid-syntax", "error", validateConfig);
+      if (invalidSyntaxSeverity !== "off") {
+        issues.push({
+          entity: templateRef,
+          entityType: "template",
+          rule: "template-invalid-syntax",
+          severity: invalidSyntaxSeverity,
+          message: `Failed to load template config: ${err instanceof Error ? err.message : "unknown error"}`
+        });
+      }
+    }
+  }
+  return issues;
+}
+async function runSDDValidation2(projectRoot, fileStore) {
+  const tasks = await fileStore.getAllTasks();
+  const docsDir = join45(projectRoot, ".knowns", "docs");
+  const stats = {
+    specs: { total: 0, approved: 0, draft: 0 },
+    tasks: { total: tasks.length, done: 0, inProgress: 0, todo: 0, withSpec: 0, withoutSpec: 0 },
+    coverage: { linked: 0, total: tasks.length, percent: 0 },
+    acCompletion: /* @__PURE__ */ new Map()
+  };
+  const warnings = [];
+  const passed = [];
+  for (const task of tasks) {
+    if (task.status === "done") stats.tasks.done++;
+    else if (task.status === "in-progress") stats.tasks.inProgress++;
+    else stats.tasks.todo++;
+    if (task.spec) {
+      stats.tasks.withSpec++;
+    } else {
+      stats.tasks.withoutSpec++;
+      warnings.push({
+        type: "task-no-spec",
+        entity: `task-${task.id}`,
+        message: `${task.title} has no spec reference`
+      });
+    }
+  }
+  stats.coverage.linked = stats.tasks.withSpec;
+  stats.coverage.percent = stats.tasks.total > 0 ? Math.round(stats.tasks.withSpec / stats.tasks.total * 100) : 0;
+  const specsDir = join45(docsDir, "specs");
+  if (existsSync40(specsDir)) {
+    async function scanSpecs(dir, relativePath) {
+      const entries = await readdir18(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+          await scanSpecs(join45(dir, entry.name), entryRelPath);
+        } else if (entry.name.endsWith(".md")) {
+          stats.specs.total++;
+          const specPath = `specs/${entryRelPath.replace(/\.md$/, "")}`;
+          try {
+            const content = await readFile28(join45(dir, entry.name), "utf-8");
+            const { data } = (0, import_gray_matter15.default)(content);
+            if (data.status === "approved" || data.status === "implemented") {
+              stats.specs.approved++;
+            } else {
+              stats.specs.draft++;
+            }
+            const linkedTasks = tasks.filter((t) => t.spec === specPath);
+            if (linkedTasks.length > 0) {
+              let totalAC = 0;
+              let completedAC = 0;
+              for (const task of linkedTasks) {
+                totalAC += task.acceptanceCriteria.length;
+                completedAC += task.acceptanceCriteria.filter((ac) => ac.completed).length;
+              }
+              const percent = totalAC > 0 ? Math.round(completedAC / totalAC * 100) : 100;
+              stats.acCompletion.set(specPath, { total: totalAC, completed: completedAC, percent });
+              if (percent < 100 && totalAC > 0) {
+                warnings.push({
+                  type: "spec-ac-incomplete",
+                  entity: specPath,
+                  message: `${completedAC}/${totalAC} ACs complete (${percent}%)`
+                });
+              }
+            }
+          } catch {
+          }
+        }
+      }
+    }
+    await scanSpecs(specsDir, "");
+  }
+  for (const task of tasks) {
+    if (task.spec) {
+      const specDocPath = join45(docsDir, `${task.spec}.md`);
+      if (!existsSync40(specDocPath)) {
+        warnings.push({
+          type: "spec-broken-link",
+          entity: `task-${task.id}`,
+          message: `Broken spec reference: @doc/${task.spec}`
+        });
+      }
+    }
+  }
+  if (warnings.filter((w) => w.type === "spec-broken-link").length === 0) {
+    passed.push("All spec references resolve");
+  }
+  for (const [specPath, completion] of stats.acCompletion) {
+    if (completion.percent === 100) {
+      passed.push(`${specPath}: fully implemented`);
+    }
+  }
+  return { stats, warnings, passed };
+}
+function formatSDDReport(result, plain) {
+  const { stats, warnings, passed } = result;
+  if (plain) {
+    console.log("\nSDD Status Report");
+    console.log("=".repeat(50));
+    console.log(`Specs:    ${stats.specs.total} total | ${stats.specs.approved} approved | ${stats.specs.draft} draft`);
+    console.log(
+      `Tasks:    ${stats.tasks.total} total | ${stats.tasks.done} done | ${stats.tasks.inProgress} in-progress | ${stats.tasks.todo} todo`
+    );
+    console.log(
+      `Coverage: ${stats.coverage.linked}/${stats.coverage.total} tasks linked to specs (${stats.coverage.percent}%)`
+    );
+    if (warnings.length > 0) {
+      console.log("\nWarnings:");
+      for (const w of warnings) {
+        console.log(`  - ${w.entity}: ${w.message}`);
+      }
+    }
+    if (passed.length > 0) {
+      console.log("\nPassed:");
+      for (const p of passed) {
+        console.log(`  - ${p}`);
+      }
+    }
+  } else {
+    console.log(source_default.bold("\n\u{1F4CB} SDD Status Report"));
+    console.log(source_default.gray("\u2550".repeat(50)));
+    console.log(
+      `${source_default.gray("Specs:")}    ${stats.specs.total} total | ${source_default.green(`${stats.specs.approved} approved`)} | ${source_default.yellow(`${stats.specs.draft} draft`)}`
+    );
+    console.log(
+      `${source_default.gray("Tasks:")}    ${stats.tasks.total} total | ${source_default.green(`${stats.tasks.done} done`)} | ${source_default.yellow(`${stats.tasks.inProgress} in-progress`)} | ${source_default.gray(`${stats.tasks.todo} todo`)}`
+    );
+    console.log(
+      `${source_default.gray("Coverage:")} ${stats.coverage.linked}/${stats.coverage.total} tasks linked to specs (${stats.coverage.percent >= 75 ? source_default.green(`${stats.coverage.percent}%`) : source_default.yellow(`${stats.coverage.percent}%`)})`
+    );
+    if (warnings.length > 0) {
+      console.log(source_default.bold.yellow("\n\u26A0\uFE0F Warnings:"));
+      for (const w of warnings) {
+        console.log(`  ${source_default.yellow("\u2022")} ${source_default.bold(w.entity)}: ${w.message}`);
+      }
+    }
+    if (passed.length > 0) {
+      console.log(source_default.bold.green("\n\u2705 Passed:"));
+      for (const p of passed) {
+        console.log(`  ${source_default.green("\u2022")} ${p}`);
+      }
+    }
+  }
+}
+async function runValidation(options2) {
+  const projectRoot = getProjectRoot7();
+  const fileStore = getFileStore6();
+  const validateConfig = await loadValidateConfig2(projectRoot);
+  const allIssues = [];
+  const stats = { tasks: 0, docs: 0, templates: 0 };
+  if (!options2.type || options2.type === "task") {
+    const tasks = await fileStore.getAllTasks();
+    stats.tasks = tasks.length;
+    const taskIssues = await validateTasks2(projectRoot, fileStore, validateConfig);
+    allIssues.push(...taskIssues);
+  }
+  if (!options2.type || options2.type === "doc") {
+    const docsDir = join45(projectRoot, ".knowns", "docs");
+    if (existsSync40(docsDir)) {
+      async function countDocs(dir) {
+        let count = 0;
+        const entries = await readdir18(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.name.startsWith(".")) continue;
+          if (entry.isDirectory()) {
+            count += await countDocs(join45(dir, entry.name));
+          } else if (entry.name.endsWith(".md")) {
+            count++;
+          }
+        }
+        return count;
+      }
+      stats.docs = await countDocs(docsDir);
+    }
+    const docIssues = await validateDocs2(projectRoot, fileStore, validateConfig);
+    allIssues.push(...docIssues);
+  }
+  if (!options2.type || options2.type === "template") {
+    const templates = await listAllTemplates(projectRoot);
+    stats.templates = templates.length;
+    const templateIssues = await validateTemplates2(projectRoot, validateConfig);
+    allIssues.push(...templateIssues);
+  }
+  if (options2.strict) {
+    for (const issue2 of allIssues) {
+      if (issue2.severity === "warning") {
+        issue2.severity = "error";
+      }
+    }
+  }
+  return { issues: allIssues, stats };
+}
+async function applyFixes2(issues) {
+  const results = [];
+  const fixableIssues = issues.filter((i) => i.fixable && i.fix);
+  for (const issue2 of fixableIssues) {
+    try {
+      await issue2.fix?.();
+      results.push({
+        entity: issue2.entity,
+        rule: issue2.rule,
+        action: issue2.message,
+        success: true
+      });
+    } catch (err) {
+      results.push({
+        entity: issue2.entity,
+        rule: issue2.rule,
+        action: `Failed: ${err instanceof Error ? err.message : "unknown error"}`,
+        success: false
+      });
+    }
+  }
+  return results;
+}
+function formatIssues(issues, plain) {
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  const infos = issues.filter((i) => i.severity === "info");
+  if (plain) {
+    if (errors.length > 0) {
+      console.log("\nErrors:");
+      for (const issue2 of errors) {
+        console.log(`  ${issue2.entity}: [${issue2.rule}] ${issue2.message}`);
+      }
+    }
+    if (warnings.length > 0) {
+      console.log("\nWarnings:");
+      for (const issue2 of warnings) {
+        console.log(`  ${issue2.entity}: [${issue2.rule}] ${issue2.message}`);
+      }
+    }
+    if (infos.length > 0) {
+      console.log("\nInfo:");
+      for (const issue2 of infos) {
+        console.log(`  ${issue2.entity}: [${issue2.rule}] ${issue2.message}`);
+      }
+    }
+  } else {
+    if (errors.length > 0) {
+      console.log(source_default.bold.red("\n\u2717 Errors:"));
+      for (const issue2 of errors) {
+        console.log(
+          `  ${source_default.red("\u2022")} ${source_default.bold(issue2.entity)}: ${source_default.gray(`[${issue2.rule}]`)} ${issue2.message}`
+        );
+      }
+    }
+    if (warnings.length > 0) {
+      console.log(source_default.bold.yellow("\n\u26A0 Warnings:"));
+      for (const issue2 of warnings) {
+        console.log(
+          `  ${source_default.yellow("\u2022")} ${source_default.bold(issue2.entity)}: ${source_default.gray(`[${issue2.rule}]`)} ${issue2.message}`
+        );
+      }
+    }
+    if (infos.length > 0) {
+      console.log(source_default.bold.blue("\n\u2139 Info:"));
+      for (const issue2 of infos) {
+        console.log(
+          `  ${source_default.blue("\u2022")} ${source_default.bold(issue2.entity)}: ${source_default.gray(`[${issue2.rule}]`)} ${issue2.message}`
+        );
+      }
+    }
+  }
+}
+var validateCommand3 = new Command("validate").description("Validate tasks, docs, and templates for quality and reference integrity").option("--type <type>", "Entity type to validate: task, doc, template").option("--strict", "Treat warnings as errors").option("--json", "Output results as JSON").option("--fix", "Auto-fix supported issues (doc renames, stale refs)").option("--sdd", "Run SDD (Spec-Driven Development) validation checks").option("--plain", "Plain text output for AI").action(
+  async (options2) => {
+    try {
+      if (options2.type && !["task", "doc", "template"].includes(options2.type)) {
+        console.error(source_default.red(`\u2717 Invalid type: ${options2.type}`));
+        console.error(source_default.gray("  Valid types: task, doc, template"));
+        process.exit(1);
+      }
+      const projectRoot = getProjectRoot7();
+      const fileStore = getFileStore6();
+      const startTime = Date.now();
+      if (options2.sdd) {
+        const sddResult = await runSDDValidation2(projectRoot, fileStore);
+        const elapsed2 = Date.now() - startTime;
+        if (options2.json) {
+          const jsonOutput = {
+            mode: "sdd",
+            stats: {
+              specs: sddResult.stats.specs,
+              tasks: sddResult.stats.tasks,
+              coverage: sddResult.stats.coverage,
+              acCompletion: Object.fromEntries(sddResult.stats.acCompletion)
+            },
+            warnings: sddResult.warnings,
+            passed: sddResult.passed,
+            elapsed: elapsed2
+          };
+          console.log(JSON.stringify(jsonOutput, null, 2));
+        } else {
+          formatSDDReport(sddResult, !!options2.plain);
+          console.log(options2.plain ? `
+Time: ${elapsed2}ms` : source_default.gray(`
+Time: ${elapsed2}ms`));
+        }
+        process.exit(0);
+      }
+      const result = await runValidation({
+        type: options2.type,
+        strict: options2.strict
+      });
+      const elapsed = Date.now() - startTime;
+      let fixResults = [];
+      if (options2.fix) {
+        fixResults = await applyFixes2(result.issues);
+      }
+      const errors = result.issues.filter((i) => i.severity === "error");
+      const warnings = result.issues.filter((i) => i.severity === "warning");
+      const fixableCount = result.issues.filter((i) => i.fixable).length;
+      if (options2.json) {
+        const jsonOutput = {
+          valid: errors.length === 0,
+          stats: result.stats,
+          summary: {
+            errors: errors.length,
+            warnings: warnings.length,
+            info: result.issues.filter((i) => i.severity === "info").length
+          },
+          issues: result.issues.map((i) => ({
+            entity: i.entity,
+            entityType: i.entityType,
+            rule: i.rule,
+            severity: i.severity,
+            message: i.message,
+            fixable: i.fixable || false
+          })),
+          elapsed,
+          ...options2.fix && fixResults.length > 0 ? { fixes: fixResults } : {}
+        };
+        console.log(JSON.stringify(jsonOutput, null, 2));
+        process.exit(errors.length > 0 ? 1 : 0);
+      }
+      const isPlain = options2.plain;
+      if (isPlain) {
+        console.log("Validating...");
+        console.log(`  Tasks: ${result.stats.tasks} checked`);
+        console.log(`  Docs: ${result.stats.docs} checked`);
+        console.log(`  Templates: ${result.stats.templates} checked`);
+        console.log(`  Time: ${elapsed}ms`);
+      } else {
+        console.log(source_default.bold("\n\u{1F50D} Validating..."));
+        console.log(`  ${source_default.gray("Tasks:")} ${result.stats.tasks} checked`);
+        console.log(`  ${source_default.gray("Docs:")} ${result.stats.docs} checked`);
+        console.log(`  ${source_default.gray("Templates:")} ${result.stats.templates} checked`);
+        console.log(`  ${source_default.gray("Time:")} ${elapsed}ms`);
+      }
+      if (options2.fix && fixResults.length > 0) {
+        if (isPlain) {
+          console.log(`
+Fixed ${fixResults.filter((r) => r.success).length} issue(s):`);
+          for (const fix of fixResults) {
+            console.log(`  ${fix.success ? "\u2713" : "\u2717"} ${fix.entity}: ${fix.action}`);
+          }
+        } else {
+          console.log(source_default.bold.green(`
+\u2713 Fixed ${fixResults.filter((r) => r.success).length} issue(s):`));
+          for (const fix of fixResults) {
+            if (fix.success) {
+              console.log(`  ${source_default.green("\u2713")} ${source_default.bold(fix.entity)}: ${fix.action}`);
+            } else {
+              console.log(`  ${source_default.red("\u2717")} ${source_default.bold(fix.entity)}: ${fix.action}`);
+            }
+          }
+        }
+      }
+      if (result.issues.length === 0) {
+        if (isPlain) {
+          console.log("\n\u2713 All validations passed");
+        } else {
+          console.log(source_default.green("\n\u2713 All validations passed"));
+        }
+        process.exit(0);
+      }
+      if (isPlain) {
+        console.log(`
+${errors.length} error(s), ${warnings.length} warning(s)`);
+        if (fixableCount > 0 && !options2.fix) {
+          console.log(`  ${fixableCount} issue(s) can be auto-fixed with --fix`);
+        }
+      } else {
+        const summaryParts = [];
+        if (errors.length > 0) {
+          summaryParts.push(source_default.red(`${errors.length} error(s)`));
+        }
+        if (warnings.length > 0) {
+          summaryParts.push(source_default.yellow(`${warnings.length} warning(s)`));
+        }
+        console.log(`
+${summaryParts.join(", ")}`);
+        if (fixableCount > 0 && !options2.fix) {
+          console.log(source_default.gray(`  ${fixableCount} issue(s) can be auto-fixed with --fix`));
+        }
+      }
+      formatIssues(result.issues, !!isPlain);
+      process.exit(errors.length > 0 ? 1 : 0);
+    } catch (error48) {
+      console.error(source_default.red("\u2717 Validation failed"));
+      if (error48 instanceof Error) {
+        console.error(source_default.red(`  ${error48.message}`));
+      }
+      process.exit(1);
+    }
+  }
+);
+
 // src/utils/update-notifier.ts
-import { existsSync as existsSync37, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync41, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
 import { mkdir as mkdir21 } from "node:fs/promises";
 import { homedir as homedir3 } from "node:os";
-import { dirname as dirname8, join as join42 } from "node:path";
+import { dirname as dirname8, join as join46 } from "node:path";
 var DEFAULT_TTL_MS = 60 * 60 * 1e3;
 var DEFAULT_TIMEOUT_MS = 2e3;
 var hasNotifiedThisProcess = false;
@@ -101104,10 +102912,10 @@ function detectPackageManager(cwd) {
   if (ua.startsWith("yarn/")) return "yarn";
   if (ua.startsWith("bun/")) return "bun";
   if (ua.startsWith("npm/")) return "npm";
-  if (existsSync37(join42(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync37(join42(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync37(join42(cwd, "bun.lock"))) return "bun";
-  if (existsSync37(join42(cwd, "package-lock.json"))) return "npm";
+  if (existsSync41(join46(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync41(join46(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync41(join46(cwd, "bun.lock"))) return "bun";
+  if (existsSync41(join46(cwd, "package-lock.json"))) return "npm";
   return "npm";
 }
 function compareVersions(a, b) {
@@ -101131,7 +102939,7 @@ function shouldSkip(args2, force) {
 }
 function getGlobalCachePath(explicit) {
   if (explicit) return explicit;
-  return join42(homedir3(), ".knowns", "cli-cache.json");
+  return join46(homedir3(), ".knowns", "cli-cache.json");
 }
 function readCache(cachePath) {
   try {
@@ -101147,7 +102955,7 @@ function readCache(cachePath) {
 }
 async function writeCache(cachePath, data) {
   const dir = dirname8(cachePath);
-  if (dir && !existsSync37(dir)) {
+  if (dir && !existsSync41(dir)) {
     await mkdir21(dir, { recursive: true });
   }
   writeFileSync3(cachePath, JSON.stringify(data, null, 2), "utf-8");
@@ -101216,7 +103024,7 @@ async function notifyCliUpdate(options2) {
 // package.json
 var package_default = {
   name: "knowns",
-  version: "0.10.6",
+  version: "0.11.0",
   description: "AI-native task and documentation management for dev teams",
   module: "index.ts",
   type: "module",
@@ -101266,9 +103074,6 @@ var package_default = {
     prepare: "husky"
   },
   dependencies: {
-    "@blocknote/core": "^0.45.0",
-    "@blocknote/react": "^0.45.0",
-    "@blocknote/shadcn": "^0.45.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -101307,6 +103112,7 @@ var package_default = {
     handlebars: "^4.7.8",
     "lucide-react": "^0.562.0",
     marked: "^17.0.1",
+    mermaid: "^11.12.2",
     pluralize: "^8.0.0",
     prompts: "^2.4.2",
     react: "^19.2.3",
@@ -101386,6 +103192,7 @@ program2.addCommand(mcpCommand);
 program2.addCommand(templateCommand);
 program2.addCommand(skillCommand);
 program2.addCommand(importCommand);
+program2.addCommand(validateCommand3);
 var args = process.argv.slice(2);
 if (args.length === 0) {
   showBanner();