knowns 0.8.8 → 0.9.0

package/dist/index.js

@@ -30454,7 +30454,7 @@ var require_view = __commonJS({
     var dirname5 = path.dirname;
     var basename3 = path.basename;
     var extname = path.extname;
-    var join24 = path.join;
+    var join25 = path.join;
     var resolve = path.resolve;
     module2.exports = View;
     function View(name, options2) {
@@ -30516,12 +30516,12 @@ var require_view = __commonJS({
     };
     View.prototype.resolve = function resolve2(dir, file3) {
       var ext = this.ext;
-      var path2 = join24(dir, file3);
+      var path2 = join25(dir, file3);
       var stat3 = tryStat(path2);
       if (stat3 && stat3.isFile()) {
         return path2;
       }
-      path2 = join24(dir, basename3(file3, ext), "index" + ext);
+      path2 = join25(dir, basename3(file3, ext), "index" + ext);
       stat3 = tryStat(path2);
       if (stat3 && stat3.isFile()) {
         return path2;
@@ -34166,7 +34166,7 @@ var require_send = __commonJS({
     var Stream = __require("stream");
     var util2 = __require("util");
     var extname = path.extname;
-    var join24 = path.join;
+    var join25 = path.join;
     var normalize = path.normalize;
     var resolve = path.resolve;
     var sep = path.sep;
@@ -34338,7 +34338,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = path2.split(sep);
-        path2 = normalize(join24(root, path2));
+        path2 = normalize(join25(root, path2));
       } else {
         if (UP_PATH_REGEXP.test(path2)) {
           debug('malicious path "%s"', path2);
@@ -34471,7 +34471,7 @@ var require_send = __commonJS({
           if (err) return self.onStatError(err);
           return self.error(404);
         }
-        var p = join24(path2, self._index[i]);
+        var p = join25(path2, self._index[i]);
         debug('stat "%s"', p);
         fs.stat(p, function(err2, stat3) {
           if (err2) return next(err2);
@@ -43469,6 +43469,78 @@ var {
 // src/commands/init.ts
 var import_prompts2 = __toESM(require_prompts3(), 1);
 
+// src/templates/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\nYour task is to help the user to generate a commit message and commit the changes using git.\n\n## Guidelines\n\n- DO NOT add any ads such as "Generated with [Claude Code](https://claude.ai/code)"\n- DO NOT add Co-Authored-By line\n- Only generate the message for staged files/changes\n- Don\'t add any files using `git add`. The user will decide what to add.\n- Follow the rules below for the commit message.\n\n## Format\n\n```\n<type>:<space><message title>\n\n<bullet points summarizing what was updated>\n```\n\n## Example Titles\n\n```\nfeat(auth): add JWT login flow\nfix(ui): handle null pointer in sidebar\nrefactor(api): split user controller logic\ndocs(readme): add usage section\n```\n\n## Example with Title and Body\n\n```\nfeat(auth): add JWT login flow\n\n- Implemented JWT token validation logic\n- Added documentation for the validation component\n```\n\n## Rules\n\n* Title is lowercase, no period at the end.\n* Title should be a clear summary, max 50 characters.\n* Use the body (optional) to explain *why*, not just *what*.\n* Bullet points should be concise and high-level.\n\n**Avoid:**\n* Vague titles like: "update", "fix stuff"\n* Overly long or unfocused titles\n* Excessive detail in bullet points\n\n## Allowed Types\n\n| Type     | Description                           |\n| -------- | ------------------------------------- |\n| feat     | New feature                           |\n| fix      | Bug fix                               |\n| chore    | Maintenance (e.g., tooling, deps)     |\n| docs     | Documentation changes                 |\n| refactor | Code restructure (no behavior change) |\n| test     | Adding or refactoring tests           |\n| style    | Code formatting (no logic change)     |\n| perf     | Performance improvements              |\n\n## Process\n\n1. Run `git status` and `git diff --staged` to see staged changes\n2. Generate commit message following the format above\n3. Show the message to user and ask for confirmation\n4. Commit with `git commit -m "message"`\n';
+
+// src/templates/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```bash\n# List all docs\nknowns doc list --plain\n\n# View doc (auto-handles large docs)\nknowns doc "<path>" --plain --smart\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\n## Reading Documents\n\n**Always use `--smart` flag:**\n\n```bash\nknowns doc "<path>" --plain --smart\n```\n\n- Small doc (\u22642000 tokens) \u2192 full content\n- Large doc \u2192 stats + TOC, then use `--section`\n\n## Creating Documents\n\n### Step 1: Search First\n\n```bash\nknowns search "<topic>" --type doc --plain\n```\n\n**Don\'t duplicate.** Update existing docs when possible.\n\n### Step 2: Choose Location\n\n| Doc Type | Location | Flag |\n|----------|----------|------|\n| Core (README, ARCH) | Root | No `-f` |\n| Guide | `guides/` | `-f "guides"` |\n| Pattern | `patterns/` | `-f "patterns"` |\n| API doc | `api/` | `-f "api"` |\n\n### Step 3: Create\n\n```bash\nknowns doc create "<title>" \\\n  -d "<brief description>" \\\n  -t "tag1,tag2" \\\n  -f "folder"  # optional\n```\n\n### Step 4: Add Content\n\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\n## Updating Documents\n\n### View First\n\n```bash\nknowns doc "<path>" --plain --smart\nknowns doc "<path>" --toc --plain  # For large docs\n```\n\n### Update Methods\n\n| Method | Command | Use When |\n|--------|---------|----------|\n| Replace all | `-c "content"` | Rewriting entire doc |\n| Append | `-a "content"` | Adding to end |\n| Section edit | `--section "2" -c "content"` | Updating one section |\n\n**Section edit is most efficient** - less context, safer.\n\n```bash\n# Update just section 3\nknowns doc edit "<path>" --section "3" -c "## 3. New Content\n\nUpdated section content..."\n```\n\n## Document Structure\n\nUse numbered headings for `--section` 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- Always use `--smart` when reading\n- Use `--section` for targeted edits\n- Use numbered headings\n- Reference docs with `@doc/<path>`\n';
+
+// src/templates/skills/knowns.init/SKILL.md
+var SKILL_default3 = '---\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```bash\nknowns doc list --plain\n```\n\n### Step 2: Read Core Documents\n\n**Priority order:**\n\n```bash\n# 1. Project overview (always read)\nknowns doc "README" --plain --smart\n\n# 2. Architecture (if exists)\nknowns doc "ARCHITECTURE" --plain --smart\n\n# 3. Conventions (if exists)\nknowns doc "CONVENTIONS" --plain --smart\n```\n\n### Step 3: Check Current State\n\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\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```bash\n# Work on a task\n/knowns.task <id>\n\n# Search for something\nknowns search "<query>" --plain\n\n# View a doc\nknowns doc "<path>" --plain --smart\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/templates/skills/knowns.research/SKILL.md
+var SKILL_default4 = '---\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```bash\n# Search docs for topic\nknowns search "<topic>" --type doc --plain\n\n# Read relevant docs\nknowns doc "<path>" --plain --smart\n```\n\n### Step 2: Search Completed Tasks\n\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\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```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\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/templates/skills/knowns.task.brainstorm/SKILL.md
+var SKILL_default5 = '---\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```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\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```bash\nknowns task create "<title>" \\\n  -d "Based on brainstorm: <key decisions>" \\\n  --ac "Criterion 1" \\\n  --ac "Criterion 2"\n```\n\nIf updating existing task:\n```bash\nknowns task edit $ARGUMENTS -d "Updated based on brainstorm..."\n```\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/templates/skills/knowns.task.extract/SKILL.md
+var SKILL_default6 = '---\nname: knowns.task.extract\ndescription: Use when extracting reusable patterns, solutions, or knowledge from completed tasks into documentation\n---\n\n# Extracting Knowledge from Tasks\n\nConvert task-specific implementations into reusable project documentation.\n\n**Announce at start:** "I\'m using the knowns.task.extract skill to extract knowledge from task [ID]."\n\n**Core principle:** ONLY EXTRACT GENERALIZABLE KNOWLEDGE.\n\n## The Process\n\n### Step 1: Review Completed Task\n\n```bash\nknowns task $ARGUMENTS --plain\n```\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```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\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```bash\nknowns doc create "Pattern: <Name>" \\\n  -d "Reusable pattern for <purpose>" \\\n  -t "pattern,<domain>" \\\n  -f "patterns"\n```\n\n**Add content:**\n\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 from the task\n```\n\n## 4. When to Use\n- Situation 1\n- Situation 2\n\n## 5. Source\nDiscovered in @task-<id>\nEOF\n)"\n```\n\n**If updating existing doc:**\n\n```bash\nknowns doc edit "<path>" -a "\n\n## Additional: <Topic>\n\nFrom @task-<id>: <new insight or example>\n"\n```\n\n### Step 5: Link Back to Task\n\n```bash\nknowns task edit $ARGUMENTS --append-notes "\u{1F4DA} Extracted to @doc/patterns/<name>"\n```\n\n## What to Extract\n\n| From Task | Extract As |\n|-----------|------------|\n| New code pattern | Pattern doc |\n| Error solution | Troubleshooting guide |\n| API integration | Integration guide |\n| Performance fix | Performance patterns |\n| Security approach | Security guidelines |\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 task\n- [ ] Tagged appropriately\n\n## Remember\n\n- Only extract generalizable knowledge\n- Search before creating (avoid duplicates)\n- Include practical examples\n- Reference source task\n- Tag docs for discoverability\n';
+
+// src/templates/skills/knowns.task.reopen/SKILL.md
+var SKILL_default7 = '---\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```bash\nknowns task $ARGUMENTS --plain\n```\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```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\n### Step 3: Document Reopen Reason\n\n```bash\nknowns task edit $ARGUMENTS --append-notes "\u{1F504} Reopened: <reason>"\n```\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```bash\n# Add new acceptance criteria\nknowns task edit $ARGUMENTS --ac "New requirement 1"\nknowns task edit $ARGUMENTS --ac "Fix: issue description"\n```\n\n### Step 5: Update Plan (if needed)\n\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\n**Present updated plan and WAIT for approval.**\n\n### Step 6: Implement and Complete\n\nFollow normal task completion flow:\n\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\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```bash\nknowns task create "Follow-up: <description>" \\\n  -d "Related to @task-$ARGUMENTS" \\\n  --ac "New requirement"\n```\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/templates/skills/knowns.task/SKILL.md
+var SKILL_default8 = '---\nname: knowns.task\ndescription: Use when working on a Knowns task - take ownership, research, plan, implement, complete with proper tracking\n---\n\n# Working on a Knowns Task\n\nExecute the complete task workflow with proper documentation reading, planning, and time tracking.\n\n**Announce at start:** "I\'m using the knowns.task skill to work on task [ID]."\n\n**Core principle:** NO IMPLEMENTATION WITHOUT RESEARCH AND APPROVED PLAN FIRST.\n\n## The Process\n\n### Phase 1: Take Ownership\n\n```bash\n# View task details\nknowns task $ARGUMENTS --plain\n\n# Take task and start timer\nknowns task edit $ARGUMENTS -s in-progress -a @me\nknowns time start $ARGUMENTS\n```\n\n**Timer is mandatory.** Time tracking data informs project estimation and identifies bottlenecks.\n\n### Phase 2: Research (MANDATORY)\n\n**Follow ALL refs in task output:**\n- `@task-<id>` \u2192 `knowns task <id> --plain`\n- `@doc/<path>` \u2192 `knowns doc "<path>" --plain --smart`\n\n```bash\n# Search related docs\nknowns search "<keywords>" --type doc --plain\n\n# Check similar completed tasks (learn from history)\nknowns search "<keywords>" --type task --status done --plain\n```\n\n**Why research matters:**\n- Prevents reinventing existing patterns\n- Ensures consistency with project conventions\n- Reveals reusable code/utilities\n- Identifies potential blockers early\n\n### Phase 3: Plan (WAIT FOR APPROVAL)\n\n```bash\nknowns task edit $ARGUMENTS --plan $\'1. Step one (see @doc/relevant-doc)\n2. Step two\n3. Add tests\n4. Update documentation\'\n```\n\n**Present plan to user and WAIT.** Do not proceed until explicit approval.\n\nIf using brainstorm first:\n- **RELATED SKILL:** Use knowns.task.brainstorm for complex requirements\n\n### Phase 4: Implement\n\nFor each piece of work completed:\n\n```bash\n# Check AC only AFTER work is done\nknowns task edit $ARGUMENTS --check-ac 1\nknowns task edit $ARGUMENTS --append-notes "\u2713 Done: brief description"\n```\n\n**Red flags - you\'re doing it wrong if:**\n- Checking AC before work is actually complete\n- Making changes not in the approved plan\n- Skipping tests\n\n**If scope changes during implementation:**\n1. Stop and ask user\n2. Add new AC: `knowns task edit $ARGUMENTS --ac "New requirement"`\n3. Update plan if needed\n\n### Phase 5: Complete\n\n```bash\n# Add implementation summary\nknowns task edit $ARGUMENTS --notes $\'## Summary\nWhat was done and key decisions.\n\n## Changes\n- Change 1\n- Change 2\'\n\n# Stop timer (REQUIRED!)\nknowns time stop\n\n# Mark done\nknowns task edit $ARGUMENTS -s done\n```\n\n## When to Stop and Ask\n\n**STOP immediately when:**\n- Requirements are unclear or contradictory\n- You hit a blocker not addressed in the plan\n- The approach isn\'t working after 2-3 attempts\n- You need to make changes outside approved scope\n\n**Ask for clarification rather than guessing.**\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Check AC before work done | Check AC only AFTER completing |\n| Skip research phase | Always read related docs first |\n| Start coding before plan approval | Wait for explicit approval |\n| Forget to stop timer | Always `knowns time stop` |\n| Use `-a` for acceptance criteria | Use `--ac` (not `-a`) |\n\n## Remember\n\n- Research before planning\n- Plan before implementing\n- Check AC after completing (not before)\n- Timer is mandatory\n- Ask when blocked, don\'t guess\n';
+
+// src/templates/skills/index.ts
+function parseSkillFrontmatter(content) {
+  const lines = content.trim().split("\n");
+  let name = "";
+  let description = "";
+  if (lines[0] === "---") {
+    for (let i = 1; i < lines.length; i++) {
+      if (lines[i] === "---") break;
+      const nameMatch = lines[i].match(/^name:\s*(.+)$/);
+      if (nameMatch) name = nameMatch[1].trim();
+      const descMatch = lines[i].match(/^description:\s*(.+)$/);
+      if (descMatch) description = descMatch[1].trim();
+    }
+  }
+  return { name, description };
+}
+function createSkill(content, folderName) {
+  const { name, description } = parseSkillFrontmatter(content);
+  return {
+    name: name || folderName,
+    folderName,
+    description,
+    content: content.trim()
+  };
+}
+var SKILL_TASK = createSkill(SKILL_default8, "knowns.task");
+var SKILL_TASK_BRAINSTORM = createSkill(SKILL_default5, "knowns.task.brainstorm");
+var SKILL_TASK_REOPEN = createSkill(SKILL_default7, "knowns.task.reopen");
+var SKILL_TASK_EXTRACT = createSkill(SKILL_default6, "knowns.task.extract");
+var SKILL_DOC = createSkill(SKILL_default2, "knowns.doc");
+var SKILL_COMMIT = createSkill(SKILL_default, "knowns.commit");
+var SKILL_INIT = createSkill(SKILL_default3, "knowns.init");
+var SKILL_RESEARCH = createSkill(SKILL_default4, "knowns.research");
+var SKILLS = [
+  // Task skills
+  SKILL_TASK,
+  SKILL_TASK_BRAINSTORM,
+  SKILL_TASK_REOPEN,
+  SKILL_TASK_EXTRACT,
+  // Doc skills
+  SKILL_DOC,
+  // Git skills
+  SKILL_COMMIT,
+  // Session skills
+  SKILL_INIT,
+  SKILL_RESEARCH
+];
+
 // src/commands/agents.ts
 import { existsSync } from "node:fs";
 import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -43476,16 +43548,16 @@ import { dirname, join as join3 } from "node:path";
 var import_prompts = __toESM(require_prompts3(), 1);
 
 // src/templates/guidelines/cli/commands-reference.md
-var commands_reference_default = '# 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 \u26A0\uFE0F                 |\n| `--priority`    |       | low/medium/high                   |\n| `--status`      | `-s`  | Initial status                    |\n| `--parent`      |       | Parent task ID (raw ID only!)     |\n\n**\u26A0\uFE0F `-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| `--title`        | `-t`  | Change title             |\n| `--description`  | `-d`  | Change description       |\n| `--status`       | `-s`  | Change status            |\n| `--priority`     |       | Change priority          |\n| `--labels`       | `-l`  | Set labels               |\n| `--assignee`     | `-a`  | Assign user \u26A0\uFE0F           |\n| `--parent`       |       | Move to parent           |\n| `--ac`           |       | Add acceptance criterion |\n| `--check-ac`     |       | Mark AC done (1-indexed) |\n| `--uncheck-ac`   |       | Unmark AC (1-indexed)    |\n| `--remove-ac`    |       | Delete AC (1-indexed)    |\n| `--plan`         |       | Set implementation plan  |\n| `--notes`        |       | Replace notes            |\n| `--append-notes` |       | Add to notes             |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain              # View single task\nknowns task list --plain              # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain       # Tree hierarchy\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### Document Structure Best Practice\n\nWhen creating/editing docs, use clear heading structure for `--toc` and `--section` to work properly:\n\n```markdown\n# Main Title (H1 - only one)\n\n## 1. Overview\n\nBrief introduction...\n\n## 2. Installation\n\nStep-by-step guide...\n\n## 3. Configuration\n\n### 3.1 Basic Config\n\n...\n\n### 3.2 Advanced Config\n\n...\n\n## 4. API Reference\n\n...\n```\n\n**Writing rules:**\n\n- Use numbered headings (`## 1. Overview`) for easy `--section "1"` access\n- Keep H1 for title only, use H2 for main sections\n- Use H3 for subsections within H2\n- Each section should be self-contained (readable without context)\n\n**Reading workflow:**\n\n```bash\n# Step 1: Check size first\nknowns doc <path> --info --plain\n# \u2192 If <2000 tokens: read directly with --plain\n# \u2192 If >2000 tokens: continue to step 2\n\n# Step 2: Get table of contents\nknowns doc <path> --toc --plain\n\n# Step 3: Read specific section\nknowns doc <path> --section "2" --plain\n```\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag             | Short | Purpose                                   |\n| ---------------- | ----- | ----------------------------------------- |\n| `--title`        | `-t`  | Change title                              |\n| `--description`  | `-d`  | Change description                        |\n| `--tags`         |       | Set tags                                  |\n| `--content`      | `-c`  | Replace content (or section if --section) |\n| `--append`       | `-a`  | Append content \u26A0\uFE0F                         |\n| `--section`      |       | Target section to replace (use with -c)   |\n| `--content-file` |       | Content from file                         |\n| `--append-file`  |       | Append from file                          |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n### Section Edit (Context-Efficient)\n\nReplace only a specific section instead of entire document:\n\n```bash\n# Step 1: View TOC to find section\nknowns doc readme --toc --plain\n\n# Step 2: Edit only that section\nknowns doc edit readme --section "2. Installation" -c "New content here..."\nknowns doc edit readme --section "2" -c "New content..."  # By number works too\n```\n\nThis reduces context usage significantly - no need to read/write entire document.\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain             # View single doc\nknowns doc list --plain               # List all\nknowns doc list --tag api --plain     # Filter by tag\n```\n\n### Large Documents (--info, --toc, --section)\n\nFor large documents, check size first with `--info`, then use `--toc` and `--section`:\n\n```bash\n# Step 1: Check document size and token count\nknowns doc readme --info --plain\n# Output: Size: 42,461 chars (~12,132 tokens) | Headings: 83\n# Recommendation: Document is large. Use --toc first, then --section.\n\n# Step 2: View table of contents\nknowns doc readme --toc --plain\n\n# Step 3: Read specific section by title or number\nknowns doc readme --section "5. Sync" --plain\nknowns doc readme --section "3" --plain\n```\n\n**Decision flow:**\n\n- `--info` \u2192 Check size (~tokens) \u2192 If >2000 tokens, use --toc/--section\n- `--toc` \u2192 Get heading list \u2192 Choose section to read\n- `--section` \u2192 Read only what you need\n\n---\n\n## time\n\n```bash\nknowns time start <id>    # REQUIRED when taking task\nknowns time stop          # REQUIRED when completing\nknowns time pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\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\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
+var commands_reference_default = '# 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 \u26A0\uFE0F                 |\n| `--priority`    |       | low/medium/high                   |\n| `--status`      | `-s`  | Initial status                    |\n| `--parent`      |       | Parent task ID (raw ID only!)     |\n\n**\u26A0\uFE0F `-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| `--title`        | `-t`  | Change title             |\n| `--description`  | `-d`  | Change description       |\n| `--status`       | `-s`  | Change status            |\n| `--priority`     |       | Change priority          |\n| `--labels`       | `-l`  | Set labels               |\n| `--assignee`     | `-a`  | Assign user \u26A0\uFE0F           |\n| `--parent`       |       | Move to parent           |\n| `--ac`           |       | Add acceptance criterion |\n| `--check-ac`     |       | Mark AC done (1-indexed) |\n| `--uncheck-ac`   |       | Unmark AC (1-indexed)    |\n| `--remove-ac`    |       | Delete AC (1-indexed)    |\n| `--plan`         |       | Set implementation plan  |\n| `--notes`        |       | Replace notes            |\n| `--append-notes` |       | Add to notes             |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain              # View single task\nknowns task list --plain              # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain       # Tree hierarchy\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### Document Structure Best Practice\n\nWhen creating/editing docs, use clear heading structure for `--toc` and `--section` to work properly:\n\n```markdown\n# Main Title (H1 - only one)\n\n## 1. Overview\n\nBrief introduction...\n\n## 2. Installation\n\nStep-by-step guide...\n\n## 3. Configuration\n\n### 3.1 Basic Config\n\n...\n\n### 3.2 Advanced Config\n\n...\n\n## 4. API Reference\n\n...\n```\n\n**Writing rules:**\n\n- Use numbered headings (`## 1. Overview`) for easy `--section "1"` access\n- Keep H1 for title only, use H2 for main sections\n- Use H3 for subsections within H2\n- Each section should be self-contained (readable without context)\n\n**Reading workflow:**\n\n```bash\n# Always use --smart (handles both small and large docs automatically)\nknowns doc <path> --plain --smart\n\n# If doc is large, --smart returns TOC, then read specific section:\nknowns doc <path> --plain --section "2"\n```\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag             | Short | Purpose                                   |\n| ---------------- | ----- | ----------------------------------------- |\n| `--title`        | `-t`  | Change title                              |\n| `--description`  | `-d`  | Change description                        |\n| `--tags`         |       | Set tags                                  |\n| `--content`      | `-c`  | Replace content (or section if --section) |\n| `--append`       | `-a`  | Append content \u26A0\uFE0F                         |\n| `--section`      |       | Target section to replace (use with -c)   |\n| `--content-file` |       | Content from file                         |\n| `--append-file`  |       | Append from file                          |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n### Section Edit (Context-Efficient)\n\nReplace only a specific section instead of entire document:\n\n```bash\n# Step 1: View TOC to find section\nknowns doc readme --toc --plain\n\n# Step 2: Edit only that section\nknowns doc edit readme --section "2. Installation" -c "New content here..."\nknowns doc edit readme --section "2" -c "New content..."  # By number works too\n```\n\nThis reduces context usage significantly - no need to read/write entire document.\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain             # View single doc\nknowns doc list --plain               # List all\nknowns doc list --tag api --plain     # Filter by tag\n```\n\n### Reading Documents (--smart)\n\n**ALWAYS use `--smart` when reading documents.** It automatically handles both small and large docs:\n\n```bash\n# Always use --smart (recommended)\nknowns doc <path> --plain --smart\n```\n\n**Behavior:**\n\n- **Small doc (\u22642000 tokens)**: Returns full content automatically\n- **Large doc (>2000 tokens)**: Returns stats + TOC, then use `--section` to read specific parts\n\n```bash\n# Example with large doc:\nknowns doc readme --plain --smart\n# Output: Size: ~12,132 tokens | TOC with numbered sections\n# Hint: Use --section <number> to read specific section\n\n# Then read specific section:\nknowns doc readme --plain --section 3\n```\n\n### Manual Control (--info, --toc, --section)\n\nIf you need manual control instead of `--smart`:\n\n```bash\nknowns doc <path> --info --plain     # Check size/tokens\nknowns doc <path> --toc --plain      # View table of contents\nknowns doc <path> --section "3" --plain  # Read specific section\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 pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\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\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
 
 // src/templates/guidelines/cli/common-mistakes.md
-var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F 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# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\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| 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 `time start`/`stop` |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\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';
+var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F 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# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\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| 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 `time start`/`stop` |\n| Ignore task refs | Follow ALL `@task-xxx` and `@doc/xxx` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\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';
 
 // src/templates/guidelines/cli/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## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain  # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Large Documents (--info, --toc, --section)\n\nFor large documents, check size first with `--info`:\n\n```bash\n# \u274C Reading entire large document (may be truncated)\nknowns doc readme --plain\n\n# \u2705 Step 1: Check document size first\nknowns doc readme --info --plain\n# Output: Size: 42,461 chars (~12,132 tokens) | Headings: 83\n\n# \u2705 Step 2: View table of contents (if >2000 tokens)\nknowns doc readme --toc --plain\n\n# \u2705 Step 3: Read only the section you need\nknowns doc readme --section "3. Config" --plain\n```\n\n**Decision flow:** `--info` \u2192 check tokens \u2192 if >2000, use `--toc` then `--section`\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\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| Repeat full error messages       | Reference error briefly     |\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\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Read selectively** - Use offset/limit for large files\n4. **Use --info first** - Check doc size before reading, then --toc/--section if needed\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n7. **Summarize** - Key points, not full quotes\n';
+var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain  # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Reading Documents (--smart)\n\n**ALWAYS use `--smart` when reading documents.** It automatically handles both small and large docs:\n\n```bash\n# \u274C Reading without --smart (may get truncated large doc)\nknowns doc readme --plain\n\n# \u2705 Always use --smart\nknowns doc readme --plain --smart\n# Small doc \u2192 returns full content\n# Large doc \u2192 returns stats + TOC\n\n# \u2705 If doc is large, read specific section:\nknowns doc readme --plain --section 3\n```\n\n**`--smart` behavior:**\n\n- **\u22642000 tokens**: Returns full content automatically\n- **>2000 tokens**: Returns stats + TOC, then use `--section <number>`\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\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| Repeat full error messages       | Reference error briefly     |\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\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Always `--smart`** - Use `--smart` when reading docs (auto-handles size)\n3. **Search first** - Don\'t read all docs hoping to find info\n4. **Read selectively** - Use offset/limit for large files\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n7. **Summarize** - Key points, not full quotes\n';
 
 // src/templates/guidelines/cli/core-rules.md
-var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F 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# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion"   # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
+var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F 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# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion"   # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n```\n\n---\n\n## Reference System\n\n| Type | Format | Example |\n|------|--------|---------|\n| **Task ref** | `@task-<id>` | `@task-pdyd2e` |\n| **Doc ref** | `@doc/<path>` | `@doc/patterns/auth` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
 
 // src/templates/guidelines/cli/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| 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\n---\n\n## Completion Steps\n\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\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\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 "\u{1F504} Reopened: reason"\n# Complete work, then follow completion steps again\n```\n\n---\n\n## Checklist\n\n- [ ] All AC checked (`--check-ac`)\n- [ ] Notes added (`--notes`)\n- [ ] Timer stopped (`time stop`)\n- [ ] Tests pass\n- [ ] Status = done (`-s done`)\n';
@@ -43494,7 +43566,7 @@ var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\
 var workflow_creation_default = '# Task Creation\n\n## Before Creating\n\n```bash\n# Search for existing tasks first\nknowns search "keyword" --type task --plain\n```\n\n---\n\n## Create Task\n\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\n---\n\n## Quality Guidelines\n\n### Title\n| \u274C Bad | \u2705 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| \u274C Bad | \u2705 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```bash\nknowns task create "Parent task"\nknowns task create "Subtask" --parent 48  # Raw ID only!\n```\n\n---\n\n## Anti-Patterns\n\n- \u274C Too many AC in one task \u2192 Split into multiple tasks\n- \u274C Implementation steps as AC \u2192 Write outcomes instead\n- \u274C Skip search \u2192 Always check existing tasks first\n';
 
 // src/templates/guidelines/cli/workflow-execution.md
-var workflow_execution_default = '# Task Execution\n\n## Step 1: Take Task\n\n```bash\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>    # REQUIRED!\n```\n\n---\n\n## Step 2: Research\n\n```bash\n# Read task and follow ALL refs\nknowns task <id> --plain\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search related docs\nknowns search "keyword" --type doc --plain\n\n# Check similar done tasks\nknowns search "keyword" --type task --status done --plain\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**\u26A0\uFE0F Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\nknowns task create "Follow-up: feature" -d "From task <id>"\n```\n\n**\u26A0\uFE0F Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
+var workflow_execution_default = '# Task Execution\n\n## Step 1: Take Task\n\n```bash\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>    # REQUIRED!\n```\n\n---\n\n## Step 2: Research\n\n```bash\n# Read task and follow ALL refs\nknowns task <id> --plain\n# @doc/xxx \u2192 knowns doc "xxx" --plain\n# @task-YY \u2192 knowns task YY --plain\n\n# Search related docs\nknowns search "keyword" --type doc --plain\n\n# Check similar done tasks\nknowns search "keyword" --type task --status done --plain\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**\u26A0\uFE0F Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\nknowns task create "Follow-up: feature" -d "From task <id>"\n```\n\n**\u26A0\uFE0F Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
 
 // src/templates/guidelines/cli/index.ts
 var CLI_CORE_RULES = core_rules_default.trim();
@@ -43574,16 +43646,16 @@ ${content}
 };
 
 // src/templates/guidelines/mcp/commands-reference.md
-var commands_reference_default2 = '# MCP Tools Reference\n\n## mcp**knowns**create_task\n\nCreate a new task.\n\n```json\n{\n  "title": "Task title",\n  "description": "Task description",\n  "status": "todo",\n  "priority": "medium",\n  "labels": ["label1", "label2"],\n  "assignee": "@me",\n  "parent": "parent-task-id"\n}\n```\n\n| Parameter     | Required | Description                             |\n| ------------- | -------- | --------------------------------------- |\n| `title`       | Yes      | Task title                              |\n| `description` | No       | Task description                        |\n| `status`      | No       | todo/in-progress/in-review/blocked/done |\n| `priority`    | No       | low/medium/high                         |\n| `labels`      | No       | Array of labels                         |\n| `assignee`    | No       | Assignee (use @me for self)             |\n| `parent`      | No       | Parent task ID for subtasks             |\n\n**Note:** Acceptance criteria must be added via `mcp__knowns__update_task` after creation.\n\n---\n\n## mcp**knowns**update_task\n\nUpdate task fields.\n\n```json\n{\n  "taskId": "abc123",\n  "title": "New title",\n  "description": "New description",\n  "status": "in-progress",\n  "priority": "high",\n  "labels": ["updated"],\n  "assignee": "@me"\n}\n```\n\n| Parameter     | Required | Description       |\n| ------------- | -------- | ----------------- |\n| `taskId`      | Yes      | Task ID to update |\n| `title`       | No       | New title         |\n| `description` | No       | New description   |\n| `status`      | No       | New status        |\n| `priority`    | No       | New priority      |\n| `labels`      | No       | New labels array  |\n| `assignee`    | No       | New assignee      |\n\n**Note:** For acceptance criteria, implementation plan, and notes - use CLI commands or edit task file directly through knowns CLI.\n\n---\n\n## mcp**knowns**get_task\n\nGet a task by ID.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**list_tasks\n\nList tasks with optional filters.\n\n```json\n{\n  "status": "in-progress",\n  "priority": "high",\n  "assignee": "@me",\n  "label": "bug"\n}\n```\n\nAll parameters are optional filters.\n\n---\n\n## mcp**knowns**search_tasks\n\nSearch tasks by query string.\n\n```json\n{\n  "query": "authentication"\n}\n```\n\n---\n\n## mcp**knowns**get_doc\n\nGet a documentation file by path.\n\n```json\n{\n  "path": "README"\n}\n```\n\nPath can be filename or folder/filename (without .md extension).\n\n### Large Documents (info, toc, section)\n\nFor large documents, check size first with `info`, then use `toc` and `section`:\n\n```json\n// Step 1: Check document size and token count\n{\n  "path": "readme",\n  "info": true\n}\n// Response: { stats: { chars: 42461, estimatedTokens: 12132, headingCount: 83 }, recommendation: "..." }\n\n// Step 2: Get table of contents\n{\n  "path": "readme",\n  "toc": true\n}\n\n// Step 3: Read specific section by title or number\n{\n  "path": "readme",\n  "section": "5. Sync"\n}\n```\n\n| Parameter | Description                                              |\n| --------- | -------------------------------------------------------- |\n| `info`    | Set `true` to get stats (size, tokens, headings) only    |\n| `toc`     | Set `true` to get table of contents only                 |\n| `section` | Section title or number to read (e.g., "5. Sync" or "3") |\n\n**Decision flow:**\n\n- `info: true` \u2192 Check estimatedTokens \u2192 If >2000, use toc/section\n- `toc: true` \u2192 Get heading list \u2192 Choose section to read\n- `section: "X"` \u2192 Read only what you need\n\n---\n\n## mcp**knowns**list_docs\n\nList all documentation files.\n\n```json\n{\n  "tag": "api"\n}\n```\n\nOptional `tag` parameter to filter by tag.\n\n---\n\n## mcp**knowns**create_doc\n\nCreate a new documentation file.\n\n```json\n{\n  "title": "Doc Title",\n  "description": "Doc description",\n  "tags": ["tag1", "tag2"],\n  "folder": "guides",\n  "content": "Initial content"\n}\n```\n\n### Document Structure Best Practice\n\nWhen creating/updating docs, use clear heading structure for `toc` and `section` to work properly:\n\n```markdown\n# Main Title (H1 - only one)\n\n## 1. Overview\n\nBrief introduction...\n\n## 2. Installation\n\nStep-by-step guide...\n\n## 3. Configuration\n\n### 3.1 Basic Config\n\n...\n\n### 3.2 Advanced Config\n\n...\n\n## 4. API Reference\n\n...\n```\n\n**Writing rules:**\n\n- Use numbered headings (`## 1. Overview`) for easy `section: "1"` access\n- Keep H1 for title only, use H2 for main sections\n- Use H3 for subsections within H2\n- Each section should be self-contained (readable without context)\n\n**Reading workflow:**\n\n```json\n// Step 1: Check size first\n{ "path": "<path>", "info": true }\n// \u2192 If estimatedTokens <2000: read directly (no options)\n// \u2192 If estimatedTokens >2000: continue to step 2\n\n// Step 2: Get table of contents\n{ "path": "<path>", "toc": true }\n\n// Step 3: Read specific section\n{ "path": "<path>", "section": "2" }\n```\n\n---\n\n## mcp**knowns**update_doc\n\nUpdate an existing documentation file.\n\n```json\n{\n  "path": "README",\n  "title": "New Title",\n  "description": "New description",\n  "tags": ["new", "tags"],\n  "content": "Replace content",\n  "appendContent": "Append to existing"\n}\n```\n\nUse either `content` (replace) or `appendContent` (append), not both.\n\n### Section Edit (Context-Efficient)\n\nReplace only a specific section instead of entire document:\n\n```json\n// Step 1: View TOC to find section\n{ "path": "readme", "toc": true }\n\n// Step 2: Edit only that section\n{\n  "path": "readme",\n  "section": "2. Installation",\n  "content": "New content here..."\n}\n```\n\nThis reduces context usage significantly - no need to read/write entire document.\n\n---\n\n## mcp**knowns**search_docs\n\nSearch documentation by query.\n\n```json\n{\n  "query": "authentication",\n  "tag": "api"\n}\n```\n\n---\n\n## mcp**knowns**start_time\n\nStart time tracking for a task.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**stop_time\n\nStop time tracking.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**add_time\n\nManually add a time entry.\n\n```json\n{\n  "taskId": "abc123",\n  "duration": "2h30m",\n  "note": "Optional note",\n  "date": "2025-01-15"\n}\n```\n\n---\n\n## mcp**knowns**get_time_report\n\nGet time tracking report.\n\n```json\n{\n  "from": "2025-01-01",\n  "to": "2025-01-31",\n  "groupBy": "task"\n}\n```\n\n`groupBy` can be: task, label, or status.\n\n---\n\n## mcp**knowns**get_board\n\nGet current board state with tasks grouped by status.\n\n```json\n{}\n```\n\nNo parameters required.\n';
+var commands_reference_default2 = '# MCP Tools Reference\n\n## mcp**knowns**create_task\n\nCreate a new task.\n\n```json\n{\n  "title": "Task title",\n  "description": "Task description",\n  "status": "todo",\n  "priority": "medium",\n  "labels": ["label1", "label2"],\n  "assignee": "@me",\n  "parent": "parent-task-id"\n}\n```\n\n| Parameter     | Required | Description                             |\n| ------------- | -------- | --------------------------------------- |\n| `title`       | Yes      | Task title                              |\n| `description` | No       | Task description                        |\n| `status`      | No       | todo/in-progress/in-review/blocked/done |\n| `priority`    | No       | low/medium/high                         |\n| `labels`      | No       | Array of labels                         |\n| `assignee`    | No       | Assignee (use @me for self)             |\n| `parent`      | No       | Parent task ID for subtasks             |\n\n**Note:** Acceptance criteria must be added via `mcp__knowns__update_task` after creation.\n\n---\n\n## mcp**knowns**update_task\n\nUpdate task fields.\n\n```json\n{\n  "taskId": "abc123",\n  "title": "New title",\n  "description": "New description",\n  "status": "in-progress",\n  "priority": "high",\n  "labels": ["updated"],\n  "assignee": "@me"\n}\n```\n\n| Parameter     | Required | Description       |\n| ------------- | -------- | ----------------- |\n| `taskId`      | Yes      | Task ID to update |\n| `title`       | No       | New title         |\n| `description` | No       | New description   |\n| `status`      | No       | New status        |\n| `priority`    | No       | New priority      |\n| `labels`      | No       | New labels array  |\n| `assignee`    | No       | New assignee      |\n\n**Note:** For acceptance criteria, implementation plan, and notes - use CLI commands or edit task file directly through knowns CLI.\n\n---\n\n## mcp**knowns**get_task\n\nGet a task by ID.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**list_tasks\n\nList tasks with optional filters.\n\n```json\n{\n  "status": "in-progress",\n  "priority": "high",\n  "assignee": "@me",\n  "label": "bug"\n}\n```\n\nAll parameters are optional filters.\n\n---\n\n## mcp**knowns**search_tasks\n\nSearch tasks by query string.\n\n```json\n{\n  "query": "authentication"\n}\n```\n\n---\n\n## mcp**knowns**get_doc\n\nGet a documentation file by path.\n\n```json\n{\n  "path": "README"\n}\n```\n\nPath can be filename or folder/filename (without .md extension).\n\n### Reading Documents (smart)\n\n**ALWAYS use `smart: true` when reading documents.** It automatically handles both small and large docs:\n\n```json\n// Always use smart (recommended)\n{\n  "path": "readme",\n  "smart": true\n}\n```\n\n**Behavior:**\n\n- **Small doc (\u22642000 tokens)**: Returns full content automatically\n- **Large doc (>2000 tokens)**: Returns stats + TOC with numbered sections\n\n```json\n// If doc is large, smart returns TOC, then read specific section:\n{\n  "path": "readme",\n  "section": "3"\n}\n```\n\n| Parameter | Description                                                    |\n| --------- | -------------------------------------------------------------- |\n| `smart`   | **Recommended.** Auto-return full content or TOC based on size |\n| `section` | Read specific section by number (e.g., "3") or title           |\n\n### Manual Control (info, toc, section)\n\nIf you need manual control instead of `smart`:\n\n```json\n{ "path": "readme", "info": true }     // Check size/tokens\n{ "path": "readme", "toc": true }      // View table of contents\n{ "path": "readme", "section": "3" }   // Read specific section\n```\n\n---\n\n## mcp**knowns**list_docs\n\nList all documentation files.\n\n```json\n{\n  "tag": "api"\n}\n```\n\nOptional `tag` parameter to filter by tag.\n\n---\n\n## mcp**knowns**create_doc\n\nCreate a new documentation file.\n\n```json\n{\n  "title": "Doc Title",\n  "description": "Doc description",\n  "tags": ["tag1", "tag2"],\n  "folder": "guides",\n  "content": "Initial content"\n}\n```\n\n### Document Structure Best Practice\n\nWhen creating/updating docs, use clear heading structure for `toc` and `section` to work properly:\n\n```markdown\n# Main Title (H1 - only one)\n\n## 1. Overview\n\nBrief introduction...\n\n## 2. Installation\n\nStep-by-step guide...\n\n## 3. Configuration\n\n### 3.1 Basic Config\n\n...\n\n### 3.2 Advanced Config\n\n...\n\n## 4. API Reference\n\n...\n```\n\n**Writing rules:**\n\n- Use numbered headings (`## 1. Overview`) for easy `section: "1"` access\n- Keep H1 for title only, use H2 for main sections\n- Use H3 for subsections within H2\n- Each section should be self-contained (readable without context)\n\n**Reading workflow:**\n\n```json\n// Always use smart (handles both small and large docs automatically)\n{ "path": "<path>", "smart": true }\n\n// If doc is large, smart returns TOC, then read specific section:\n{ "path": "<path>", "section": "2" }\n```\n\n---\n\n## mcp**knowns**update_doc\n\nUpdate an existing documentation file.\n\n```json\n{\n  "path": "README",\n  "title": "New Title",\n  "description": "New description",\n  "tags": ["new", "tags"],\n  "content": "Replace content",\n  "appendContent": "Append to existing"\n}\n```\n\nUse either `content` (replace) or `appendContent` (append), not both.\n\n### Section Edit (Context-Efficient)\n\nReplace only a specific section instead of entire document:\n\n```json\n// Step 1: View TOC to find section\n{ "path": "readme", "toc": true }\n\n// Step 2: Edit only that section\n{\n  "path": "readme",\n  "section": "2. Installation",\n  "content": "New content here..."\n}\n```\n\nThis reduces context usage significantly - no need to read/write entire document.\n\n---\n\n## mcp**knowns**search_docs\n\nSearch documentation by query.\n\n```json\n{\n  "query": "authentication",\n  "tag": "api"\n}\n```\n\n---\n\n## mcp**knowns**start_time\n\nStart time tracking for a task.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**stop_time\n\nStop time tracking.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**add_time\n\nManually add a time entry.\n\n```json\n{\n  "taskId": "abc123",\n  "duration": "2h30m",\n  "note": "Optional note",\n  "date": "2025-01-15"\n}\n```\n\n---\n\n## mcp**knowns**get_time_report\n\nGet time tracking report.\n\n```json\n{\n  "from": "2025-01-01",\n  "to": "2025-01-31",\n  "groupBy": "task"\n}\n```\n\n`groupBy` can be: task, label, or status.\n\n---\n\n## mcp**knowns**get_board\n\nGet current board state with tasks grouped by status.\n\n```json\n{}\n```\n\nNo parameters required.\n';
 
 // src/templates/guidelines/mcp/common-mistakes.md
-var common_mistakes_default2 = "# Common Mistakes (MCP)\n\n## Quick Reference\n\n| DON'T | DO |\n|-------|-----|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | Always `start_time`/`stop_time` |\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| Ignore task refs | Follow ALL `@.knowns/...` refs |\n| Use wrong task ID format | Use raw ID string |\n\n---\n\n## MCP vs CLI Usage\n\nSome operations require CLI (not available in MCP):\n\n| Operation | Tool |\n|-----------|------|\n| Add acceptance criteria | CLI: `--ac` |\n| Check/uncheck AC | CLI: `--check-ac`, `--uncheck-ac` |\n| Set implementation plan | CLI: `--plan` |\n| Add/append notes | CLI: `--notes`, `--append-notes` |\n| Create/update task basic fields | MCP tools |\n| Time tracking | MCP tools |\n| Read tasks/docs | MCP tools |\n| Search | MCP tools |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\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 | CLI: `knowns task edit <id> --uncheck-ac N` |\n";
+var common_mistakes_default2 = "# Common Mistakes (MCP)\n\n## Quick Reference\n\n| DON'T | DO |\n|-------|-----|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | Always `start_time`/`stop_time` |\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| Ignore task refs | Follow ALL `@task-xxx` and `@doc/xxx` refs |\n| Use wrong task ID format | Use raw ID string |\n\n---\n\n## MCP vs CLI Usage\n\nSome operations require CLI (not available in MCP):\n\n| Operation | Tool |\n|-----------|------|\n| Add acceptance criteria | CLI: `--ac` |\n| Check/uncheck AC | CLI: `--check-ac`, `--uncheck-ac` |\n| Set implementation plan | CLI: `--plan` |\n| Add/append notes | CLI: `--notes`, `--append-notes` |\n| Create/update task basic fields | MCP tools |\n| Time tracking | MCP tools |\n| Read tasks/docs | MCP tools |\n| Search | MCP tools |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\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 | CLI: `knowns task edit <id> --uncheck-ac N` |\n";
 
 // src/templates/guidelines/mcp/context-optimization.md
-var context_optimization_default2 = '# Context Optimization (MCP)\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Search Before Read\n\n```json\n// DON\'T: Read all docs hoping to find info\nmcp__knowns__get_doc({ "path": "doc1" })\nmcp__knowns__get_doc({ "path": "doc2" })\nmcp__knowns__get_doc({ "path": "doc3" })\n\n// DO: Search first, then read only relevant docs\nmcp__knowns__search_docs({ "query": "authentication" })\nmcp__knowns__get_doc({ "path": "security-patterns" })  // Only the relevant one\n```\n\n---\n\n## Use Filters\n\n```json\n// DON\'T: List all tasks 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\n## Large Documents (info, toc, section)\n\nFor large documents, check size first with `info`:\n\n```json\n// DON\'T: Read entire large document (may be truncated)\nmcp__knowns__get_doc({ "path": "readme" })\n\n// DO: Step 1 - Check document size first\nmcp__knowns__get_doc({ "path": "readme", "info": true })\n// Response: { stats: { estimatedTokens: 12132 }, recommendation: "..." }\n\n// DO: Step 2 - Get table of contents (if >2000 tokens)\nmcp__knowns__get_doc({ "path": "readme", "toc": true })\n\n// DO: Step 3 - Read only the section you need\nmcp__knowns__get_doc({ "path": "readme", "section": "3. Config" })\n```\n\n**Decision flow:** `info: true` \u2192 check tokens \u2192 if >2000, use `toc` then `section`\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 tasks/docs already in context | Reference from memory       |\n| List tasks/docs multiple times        | List once, remember results |\n| Fetch same task repeatedly            | Cache the result            |\n\n---\n\n## Efficient Workflow\n\n| Phase          | Context-Efficient Approach     |\n| -------------- | ------------------------------ |\n| **Research**   | Search -> 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\n1. **Search first** - Don\'t read all docs hoping to find info\n2. **Use filters** - Don\'t list everything then filter manually\n3. **Read selectively** - Only fetch what you need\n4. **Use info first** - Check doc size before reading, then toc/section if needed\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n7. **Summarize** - Key points, not full quotes\n';
+var context_optimization_default2 = '# Context Optimization (MCP)\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Search Before Read\n\n```json\n// DON\'T: Read all docs hoping to find info\nmcp__knowns__get_doc({ "path": "doc1" })\nmcp__knowns__get_doc({ "path": "doc2" })\nmcp__knowns__get_doc({ "path": "doc3" })\n\n// DO: Search first, then read only relevant docs\nmcp__knowns__search_docs({ "query": "authentication" })\nmcp__knowns__get_doc({ "path": "security-patterns" })  // Only the relevant one\n```\n\n---\n\n## Use Filters\n\n```json\n// DON\'T: List all tasks 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\n## Reading Documents (smart)\n\n**ALWAYS use `smart: true` when reading documents.** It automatically handles both small and large docs:\n\n```json\n// DON\'T: Read without smart (may get truncated large doc)\nmcp__knowns__get_doc({ "path": "readme" })\n\n// DO: Always use smart\nmcp__knowns__get_doc({ "path": "readme", "smart": true })\n// Small doc \u2192 returns full content\n// Large doc \u2192 returns stats + TOC\n\n// DO: If doc is large, read specific section\nmcp__knowns__get_doc({ "path": "readme", "section": "3" })\n```\n\n**`smart: true` behavior:**\n\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 tasks/docs already in context | Reference from memory       |\n| List tasks/docs multiple times        | List once, remember results |\n| Fetch same task repeatedly            | Cache the result            |\n\n---\n\n## Efficient Workflow\n\n| Phase          | Context-Efficient Approach     |\n| -------------- | ------------------------------ |\n| **Research**   | Search -> 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\n1. **Always `smart: true`** - Use smart when reading docs (auto-handles size)\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Use filters** - Don\'t list everything then filter manually\n4. **Read selectively** - Only fetch what you need\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n7. **Summarize** - Key points, not full quotes\n';
 
 // src/templates/guidelines/mcp/core-rules.md
-var core_rules_default2 = "# Core Rules (MCP)\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **MCP Tools Only** | Use MCP tools for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID (string) for all MCP tool calls.\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n";
+var core_rules_default2 = "# Core Rules (MCP)\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **MCP Tools Only** | Use MCP tools for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## Reference System\n\n| Type | Format | Example |\n|------|--------|---------|\n| **Task ref** | `@task-<id>` | `@task-pdyd2e` |\n| **Doc ref** | `@doc/<path>` | `@doc/patterns/auth` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID (string) for all MCP tool calls.\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n";
 
 // src/templates/guidelines/mcp/workflow-completion.md
 var workflow_completion_default2 = '# Task Completion (MCP)\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| Requirement | How |\n|-------------|-----|\n| All AC checked | CLI: `knowns task edit <id> --check-ac N` |\n| Notes added | CLI: `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | MCP: `mcp__knowns__stop_time` |\n| Status = done | MCP: `mcp__knowns__update_task` |\n| Tests pass | Run test suite |\n\n---\n\n## Completion Steps\n\n```json\n// 1. Verify all AC are checked\nmcp__knowns__get_task({ "taskId": "abc123" })\n```\n\n```bash\n# 2. Add implementation notes (use CLI)\nknowns task edit abc123 --notes $\'## Summary\nWhat was done and key decisions.\'\n```\n\n```json\n// 3. Stop timer (REQUIRED!)\nmcp__knowns__stop_time({ "taskId": "abc123" })\n\n// 4. Mark done\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "done"\n})\n```\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n```json\n// 1. Reopen task\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "in-progress"\n})\n\n// 2. Restart timer\nmcp__knowns__start_time({ "taskId": "abc123" })\n```\n\n```bash\n# 3. Add AC for the fix\nknowns task edit abc123 --ac "Fix: description"\nknowns task edit abc123 --append-notes "Reopened: reason"\n```\n\nThen follow completion steps again.\n\n---\n\n## Checklist\n\n- [ ] All AC checked (CLI `--check-ac`)\n- [ ] Notes added (CLI `--notes`)\n- [ ] Timer stopped (`mcp__knowns__stop_time`)\n- [ ] Tests pass\n- [ ] Status = done (`mcp__knowns__update_task`)\n';
@@ -43592,7 +43664,7 @@ var workflow_completion_default2 = '# Task Completion (MCP)\n\n## Definition of
 var workflow_creation_default2 = '# Task Creation (MCP)\n\n## Before Creating\n\n```json\n// Search for existing tasks first\nmcp__knowns__search_tasks({ "query": "keyword" })\n```\n\n---\n\n## Create Task\n\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 using CLI:\n```bash\nknowns task edit <id> --ac "Outcome 1" --ac "Outcome 2"\n```\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```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\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';
 
 // src/templates/guidelines/mcp/workflow-execution.md
-var workflow_execution_default2 = '# Task Execution (MCP)\n\n## Step 1: Take Task\n\n```json\n// Update status and assignee\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "in-progress",\n  "assignee": "@me"\n})\n\n// Start timer (REQUIRED!)\nmcp__knowns__start_time({ "taskId": "abc123" })\n```\n\n---\n\n## Step 2: Research\n\n```json\n// Read task and follow ALL refs\nmcp__knowns__get_task({ "taskId": "abc123" })\n\n// @.knowns/docs/xxx.md -> read the doc\nmcp__knowns__get_doc({ "path": "xxx" })\n\n// @.knowns/tasks/task-YY -> read the task\nmcp__knowns__get_task({ "taskId": "YY" })\n\n// Search related docs\nmcp__knowns__search_docs({ "query": "keyword" })\n\n// Check similar done tasks\nmcp__knowns__list_tasks({ "status": "done" })\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\nUse CLI for implementation plan:\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\nUse CLI for checking acceptance criteria:\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\n```\n\n```json\nmcp__knowns__create_task({\n  "title": "Follow-up: feature",\n  "description": "From task <id>"\n})\n```\n\n**Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
+var workflow_execution_default2 = '# Task Execution (MCP)\n\n## Step 1: Take Task\n\n```json\n// Update status and assignee\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "in-progress",\n  "assignee": "@me"\n})\n\n// Start timer (REQUIRED!)\nmcp__knowns__start_time({ "taskId": "abc123" })\n```\n\n---\n\n## Step 2: Research\n\n```json\n// Read task and follow ALL refs\nmcp__knowns__get_task({ "taskId": "abc123" })\n\n// @doc/xxx -> read the doc\nmcp__knowns__get_doc({ "path": "xxx" })\n\n// @task-YY -> read the task\nmcp__knowns__get_task({ "taskId": "YY" })\n\n// Search related docs\nmcp__knowns__search_docs({ "query": "keyword" })\n\n// Check similar done tasks\nmcp__knowns__list_tasks({ "status": "done" })\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\nUse CLI for implementation plan:\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\nUse CLI for checking acceptance criteria:\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\n```\n\n```json\nmcp__knowns__create_task({\n  "title": "Follow-up: feature",\n  "description": "From task <id>"\n})\n```\n\n**Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
 
 // src/templates/guidelines/mcp/index.ts
 var MCP_CORE_RULES = core_rules_default2.trim();
@@ -43687,6 +43759,9 @@ var cli_default = '# Knowns Project\n\nThis project uses **Knowns CLI** for task
 // src/templates/instruction/mcp.md
 var mcp_default = '# Knowns Project\n\nThis project uses **Knowns MCP** tools for task and documentation management.\n\n## Before Starting\n\nCall this MCP tool to get usage guidelines:\n\n```\nmcp__knowns__get_guideline({})\n```\n\nYou MUST call this at session start and follow every rule it returns.\n\n## Context-Specific Guidelines\n\nGet guidelines for specific contexts:\n\n```\n// Full guidelines\nmcp__knowns__get_guideline({ type: "unified" })\n\n// CLI-specific (fallback)\nmcp__knowns__get_guideline({ type: "cli" })\n\n// MCP-specific\nmcp__knowns__get_guideline({ type: "mcp" })\n```\n\n**CLI Fallback:** If MCP tools are unavailable, use CLI commands:\n\n```bash\nknowns agents guideline --full      # All guidelines\nknowns agents guideline --stage creation    # Task creation\nknowns agents guideline --stage execution   # Task execution\nknowns agents guideline --stage completion  # Task completion\n```\n\n## Quick Tools\n\n```\n// List tasks\nmcp__knowns__list_tasks({})\n\n// View task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n// List docs\nmcp__knowns__list_docs({})\n\n// View doc\nmcp__knowns__get_doc({ path: "<path>" })\n\n// Search\nmcp__knowns__search_tasks({ query: "keyword" })\nmcp__knowns__search_docs({ query: "keyword" })\n```\n\n**Important:** Always read the guidelines before working on tasks.\n';
 
+// src/templates/instruction/skills.md
+var skills_default = '# Knowns Project\n\nThis project uses **Knowns** for task and documentation management with built-in Claude Code skills.\n\n## Available Skills\n\nUse `/knowns.<skill>` to invoke workflows:\n\n| Skill | Description |\n|-------|-------------|\n| `/knowns.init` | Initialize session - read docs, understand context |\n| `/knowns.task <id>` | Full task workflow - research, plan, implement |\n| `/knowns.task.brainstorm` | Explore solutions before implementation |\n| `/knowns.task.reopen` | Reopen completed task, add requirements |\n| `/knowns.task.extract` | Extract patterns from task to docs |\n| `/knowns.doc` | Work with documentation - view, create, update |\n| `/knowns.commit` | Commit with proper format |\n| `/knowns.research` | Research codebase before coding |\n\n## Getting Started\n\n```bash\n# Start a new session\n/knowns.init\n\n# Work on a task\n/knowns.task <task-id>\n\n# Quick commands\nknowns task list --plain\nknowns doc list --plain\nknowns search "query" --plain\n```\n\n## Key Principles\n\n1. **Read docs first** - Understand before implementing\n2. **Plan before coding** - Wait for approval\n3. **Track time** - Always use timer\n4. **Ask when blocked** - Don\'t guess\n';
+
 // src/templates/instruction/index.ts
 var START_MARKER = "<!-- KNOWNS GUIDELINES START -->";
 var END_MARKER = "<!-- KNOWNS GUIDELINES END -->";
@@ -43697,8 +43772,10 @@ ${END_MARKER}`;
 }
 var CLI_TEMPLATE_RAW = cli_default.trim();
 var MCP_TEMPLATE_RAW = mcp_default.trim();
+var SKILLS_TEMPLATE_RAW = skills_default.trim();
 var CLI_INSTRUCTION = withMarkers(cli_default);
 var MCP_INSTRUCTION = withMarkers(mcp_default);
+var SKILLS_INSTRUCTION = withMarkers(skills_default);
 
 // src/commands/agents.ts
 var PROJECT_ROOT = process.cwd();
@@ -43713,6 +43790,9 @@ var INSTRUCTION_FILES = [
   }
 ];
 function getGuidelines(type, variant = "general") {
+  if (type === "skills") {
+    return SKILLS_INSTRUCTION;
+  }
   if (variant === "instruction") {
     return type === "mcp" ? MCP_INSTRUCTION : CLI_INSTRUCTION;
   }
@@ -43897,24 +43977,6 @@ async function updateFiles(files, guidelines) {
   }
   console.log();
 }
-var syncCommand = new Command("sync").description("Sync/update all agent instruction files with latest guidelines").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--minimal", "Use minimal instruction (default: full embedded guidelines)").option("--all", "Update all instruction files (including Gemini, Copilot)").action(async (options2) => {
-  try {
-    const type = options2.type === "mcp" ? "mcp" : "cli";
-    const variant = options2.minimal ? "instruction" : "general";
-    const guidelines = getGuidelines(type, variant);
-    const filesToUpdate = options2.all ? INSTRUCTION_FILES : INSTRUCTION_FILES.filter((f) => f.selected);
-    const variantLabel = variant === "instruction" ? " (minimal)" : " (full)";
-    const label = `${type.toUpperCase()}${variantLabel}`;
-    console.log(source_default.bold(`
-Syncing agent instructions (${label})...
-`));
-    await updateFiles(filesToUpdate, guidelines);
-  } catch (error48) {
-    console.error(source_default.red("Error:"), error48 instanceof Error ? error48.message : String(error48));
-    process.exit(1);
-  }
-});
-agentsCommand.addCommand(syncCommand);
 var guidelineCommand = new Command("guideline").description("Output guidelines for AI agents (use this at session start)").option("--cli", "Show CLI-specific guidelines (legacy)").option("--mcp", "Show MCP-specific guidelines (legacy)").option("--full", "Show full guidelines (all sections)").option("--compact", "Show compact guidelines (core + mistakes only)").option("--stage <stage>", "Show guidelines for specific stage: creation, execution, completion").option("--core", "Show core rules only").option("--commands", "Show commands reference only").option("--mistakes", "Show common mistakes only").action(
   async (options2) => {
     try {
@@ -43972,7 +44034,7 @@ function checkGitExists(projectRoot) {
   }
 }
 async function createMcpJsonFile(projectRoot) {
-  const { writeFileSync: writeFileSync3, readFileSync: readFileSync4 } = await import("node:fs");
+  const { writeFileSync: writeFileSync4, readFileSync: readFileSync5 } = await import("node:fs");
   const mcpJsonPath = join4(projectRoot, ".mcp.json");
   const mcpConfig = {
     mcpServers: {
@@ -43984,7 +44046,7 @@ async function createMcpJsonFile(projectRoot) {
   };
   if (existsSync2(mcpJsonPath)) {
     try {
-      const existing = JSON.parse(readFileSync4(mcpJsonPath, "utf-8"));
+      const existing = JSON.parse(readFileSync5(mcpJsonPath, "utf-8"));
       if (existing?.mcpServers?.knowns) {
         console.log(source_default.gray("  .mcp.json already has knowns configuration"));
         return;
@@ -43993,19 +44055,19 @@ async function createMcpJsonFile(projectRoot) {
         ...existing.mcpServers,
         ...mcpConfig.mcpServers
       };
-      writeFileSync3(mcpJsonPath, JSON.stringify(existing, null, "	"), "utf-8");
+      writeFileSync4(mcpJsonPath, JSON.stringify(existing, null, "	"), "utf-8");
       console.log(source_default.green("\u2713 Added knowns to existing .mcp.json"));
     } catch {
-      writeFileSync3(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
+      writeFileSync4(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
       console.log(source_default.green("\u2713 Created .mcp.json (replaced invalid file)"));
     }
   } else {
-    writeFileSync3(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
+    writeFileSync4(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
     console.log(source_default.green("\u2713 Created .mcp.json for Claude Code MCP auto-discovery"));
   }
 }
 async function updateGitignore(projectRoot, mode) {
-  const { appendFileSync, readFileSync: readFileSync4, writeFileSync: writeFileSync3 } = await import("node:fs");
+  const { appendFileSync, readFileSync: readFileSync5, writeFileSync: writeFileSync4 } = await import("node:fs");
   const gitignorePath = join4(projectRoot, ".gitignore");
   const patterns = {
     "git-ignored": `
@@ -44022,7 +44084,7 @@ async function updateGitignore(projectRoot, mode) {
   const knownsIgnorePattern = patterns[mode];
   const checkPattern = mode === "none" ? ".knowns/" : ".knowns/*";
   if (existsSync2(gitignorePath)) {
-    const content = readFileSync4(gitignorePath, "utf-8");
+    const content = readFileSync5(gitignorePath, "utf-8");
     if (content.includes(checkPattern)) {
       console.log(source_default.gray("  .gitignore already has knowns pattern"));
       return;
@@ -44030,11 +44092,39 @@ async function updateGitignore(projectRoot, mode) {
     appendFileSync(gitignorePath, knownsIgnorePattern);
     console.log(source_default.green("\u2713 Updated .gitignore with knowns pattern"));
   } else {
-    writeFileSync3(gitignorePath, `${knownsIgnorePattern.trim()}
+    writeFileSync4(gitignorePath, `${knownsIgnorePattern.trim()}
 `, "utf-8");
     console.log(source_default.green("\u2713 Created .gitignore with knowns pattern"));
   }
 }
+async function createClaudeSkills(projectRoot) {
+  const { mkdirSync: mkdirSync2, writeFileSync: writeFileSync4 } = await import("node:fs");
+  const skillsDir = join4(projectRoot, ".claude", "skills");
+  if (!existsSync2(skillsDir)) {
+    mkdirSync2(skillsDir, { recursive: true });
+  }
+  let createdCount = 0;
+  let skippedCount = 0;
+  for (const skill of SKILLS) {
+    const skillFolder = join4(skillsDir, skill.folderName);
+    const skillFile = join4(skillFolder, "SKILL.md");
+    if (existsSync2(skillFile)) {
+      skippedCount++;
+      continue;
+    }
+    if (!existsSync2(skillFolder)) {
+      mkdirSync2(skillFolder, { recursive: true });
+    }
+    writeFileSync4(skillFile, skill.content, "utf-8");
+    createdCount++;
+  }
+  if (createdCount > 0) {
+    console.log(source_default.green(`\u2713 Created ${createdCount} Claude Code skills in .claude/skills/`));
+  }
+  if (skippedCount > 0) {
+    console.log(source_default.gray(`  Skipped ${skippedCount} existing skills`));
+  }
+}
 async function runWizard() {
   const projectRoot = process.cwd();
   const defaultName = basename(projectRoot);
@@ -44081,9 +44171,14 @@ async function runWizard() {
         message: "AI Guidelines type",
         choices: [
           {
-            title: "CLI",
+            title: "Skills (recommended)",
+            value: "skills",
+            description: "Minimal CLAUDE.md + built-in /knowns:* skills"
+          },
+          {
+            title: "CLI (full guidelines)",
             value: "cli",
-            description: "Use CLI commands (knowns task edit, knowns doc view)"
+            description: "Full CLI guidelines embedded in CLAUDE.md"
           },
           {
             title: "MCP",
@@ -44092,7 +44187,7 @@ async function runWizard() {
           }
         ],
         initial: 0
-        // CLI
+        // Skills
       },
       {
         type: "multiselect",
@@ -44123,7 +44218,7 @@ async function runWizard() {
     defaultLabels: [],
     timeFormat: "24h",
     gitTrackingMode: response.gitTrackingMode || "git-tracked",
-    guidelinesType: response.guidelinesType || "cli",
+    guidelinesType: response.guidelinesType || "skills",
     agentFiles: response.agentFiles || []
   };
 }
@@ -44157,7 +44252,7 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
         defaultLabels: [],
         timeFormat: "24h",
         gitTrackingMode: "git-tracked",
-        guidelinesType: "cli",
+        guidelinesType: "skills",
         agentFiles: INSTRUCTION_FILES.filter((f) => f.selected)
       };
     }
@@ -44176,6 +44271,7 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
     });
     console.log();
     console.log(source_default.green(`\u2713 Project initialized: ${project.name}`));
+    await createClaudeSkills(projectRoot);
     if (config2.agentFiles.length > 0) {
       const guidelines = getGuidelines(config2.guidelinesType);
       for (const file3 of config2.agentFiles) {
@@ -44289,60 +44385,13 @@ function findProjectRoot(startPath = process.cwd()) {
 }
 
 // src/utils/mention-refs.ts
-var TASK_MENTION_REGEX = /@task-(\d+)/g;
-var DOC_MENTION_REGEX = /@docs?\/([^\s|)]+)/g;
-var OUTPUT_TASK_REGEX = /@\.knowns\/tasks\/task-(\d+)(?:\s*-\s*[^@\n]+?\.md|\.md)/g;
+var OUTPUT_TASK_REGEX = /@\.knowns\/tasks\/task-([a-zA-Z0-9]+)(?:\s*-\s*[^@\n]+?\.md|\.md)/g;
 var OUTPUT_DOC_REGEX = /@\.knowns\/docs\/([^\s@]+?)\.md(?:\s*-\s*[^@\n]+)?/g;
-function sanitizeTitle(title) {
-  return title.replace(/[<>:"/\\|?*]/g, "").replace(/\s+/g, " ").trim().slice(0, 50);
-}
-function transformTaskMention(taskId, tasks) {
-  const task = tasks.get(taskId);
-  if (task) {
-    const sanitizedTitle = sanitizeTitle(task.title);
-    return `@.knowns/tasks/task-${taskId} - ${sanitizedTitle}.md`;
-  }
-  return `@.knowns/tasks/task-${taskId}.md`;
-}
-function transformDocMention(docPath) {
-  const normalizedPath = docPath.endsWith(".md") ? docPath : `${docPath}.md`;
-  return `@.knowns/docs/${normalizedPath}`;
-}
-function transformMentionsToRefs(text, tasks) {
-  const codeBlocks = [];
-  const inlineCodes = [];
-  let result = text.replace(/```[\s\S]*?```/g, (match) => {
-    const index = codeBlocks.length;
-    codeBlocks.push(match);
-    return `__CODE_BLOCK_${index}__`;
-  });
-  result = result.replace(/`[^`]+`/g, (match) => {
-    const index = inlineCodes.length;
-    inlineCodes.push(match);
-    return `__INLINE_CODE_${index}__`;
-  });
-  result = result.replace(TASK_MENTION_REGEX, (match, taskId) => {
-    return transformTaskMention(taskId, tasks);
-  });
-  result = result.replace(DOC_MENTION_REGEX, (match, docPath) => {
-    return transformDocMention(docPath);
-  });
-  result = result.replace(/__INLINE_CODE_(\d+)__/g, (_, index) => inlineCodes[Number.parseInt(index)]);
-  result = result.replace(/__CODE_BLOCK_(\d+)__/g, (_, index) => codeBlocks[Number.parseInt(index)]);
-  return result;
-}
-function buildTaskMap(tasks) {
-  const map2 = /* @__PURE__ */ new Map();
-  for (const task of tasks) {
-    map2.set(task.id, task);
-  }
-  return map2;
-}
 function normalizeRefs(text) {
   let result = text;
   result = parseEscapeSequences(result);
-  result = result.replace(new RegExp(OUTPUT_TASK_REGEX.source, "g"), (match, taskId) => `@task-${taskId}`);
-  result = result.replace(new RegExp(OUTPUT_DOC_REGEX.source, "g"), (match, docPath) => `@doc/${docPath}`);
+  result = result.replace(new RegExp(OUTPUT_TASK_REGEX.source, "g"), (_match, taskId) => `@task-${taskId}`);
+  result = result.replace(new RegExp(OUTPUT_DOC_REGEX.source, "g"), (_match, docPath) => `@doc/${docPath}`);
   return result;
 }
 function parseEscapeSequences(text) {
@@ -44854,9 +44903,6 @@ async function formatTask(task, fileStore2, plain = false) {
     const border = "-".repeat(50);
     const titleBorder = "=".repeat(50);
     const output2 = [];
-    const allTasks = await fileStore2.getAllTasks();
-    const taskMap = buildTaskMap(allTasks);
-    const transformText = (text) => transformMentionsToRefs(text, taskMap);
     const projectRoot2 = findProjectRoot();
     if (projectRoot2) {
       const filename = `task-${task.id} - ${task.title.replace(/[^a-z0-9]+/gi, "-")}`;
@@ -44908,7 +44954,7 @@ async function formatTask(task, fileStore2, plain = false) {
     if (task.description) {
       output2.push("Description:");
       output2.push(border);
-      output2.push(transformText(task.description));
+      output2.push(task.description);
       output2.push("");
     }
     if (task.acceptanceCriteria.length > 0) {
@@ -44916,20 +44962,20 @@ async function formatTask(task, fileStore2, plain = false) {
       output2.push(border);
       for (const [i, ac] of task.acceptanceCriteria.entries()) {
         const checkbox = ac.completed ? "[x]" : "[ ]";
-        output2.push(`- ${checkbox} #${i + 1} ${transformText(ac.text)}`);
+        output2.push(`- ${checkbox} #${i + 1} ${ac.text}`);
       }
       output2.push("");
     }
     if (task.implementationPlan) {
       output2.push("Implementation Plan:");
       output2.push(border);
-      output2.push(transformText(task.implementationPlan));
+      output2.push(task.implementationPlan);
       output2.push("");
     }
     if (task.implementationNotes) {
       output2.push("Implementation Notes:");
       output2.push(border);
-      output2.push(transformText(task.implementationNotes));
+      output2.push(task.implementationNotes);
       output2.push("");
     }
     if (projectRoot2) {
@@ -47934,6 +47980,13 @@ function extractSection(markdown, sectionTitle) {
   }
   return lines.slice(startLine, endLine).join("\n").trim();
 }
+function extractSectionByIndex(markdown, index) {
+  const toc = extractToc(markdown);
+  if (index < 1 || index > toc.length) {
+    return null;
+  }
+  return extractSection(markdown, toc[index - 1].title);
+}
 function replaceSection(markdown, sectionTitle, newContent) {
   const lines = markdown.split("\n");
   const normalizedTarget = normalizeTitle(sectionTitle);
@@ -47966,9 +48019,37 @@ function replaceSection(markdown, sectionTitle, newContent) {
   }
   const beforeSection = lines.slice(0, startLine);
   const afterSection = lines.slice(endLine);
-  const newSection = `${originalHeading}
+  const trimmedContent = newContent.trim();
+  const contentStartsWithHeading = /^#{1,6}\s+/.test(trimmedContent);
+  const newSection = contentStartsWithHeading ? trimmedContent : `${originalHeading}
+
+${trimmedContent}`;
+  return [...beforeSection, newSection, ...afterSection].join("\n");
+}
+function replaceSectionByIndex(markdown, index, newContent) {
+  const toc = extractToc(markdown);
+  if (index < 1 || index > toc.length) {
+    return null;
+  }
+  const lines = markdown.split("\n");
+  const targetEntry = toc[index - 1];
+  const startLine = targetEntry.line - 1;
+  const startLevel = targetEntry.level;
+  const originalHeading = lines[startLine];
+  let endLine = lines.length;
+  for (let i = index; i < toc.length; i++) {
+    if (toc[i].level <= startLevel) {
+      endLine = toc[i].line - 1;
+      break;
+    }
+  }
+  const beforeSection = lines.slice(0, startLine);
+  const afterSection = lines.slice(endLine);
+  const trimmedContent = newContent.trim();
+  const contentStartsWithHeading = /^#{1,6}\s+/.test(trimmedContent);
+  const newSection = contentStartsWithHeading ? trimmedContent : `${originalHeading}
 
-${newContent.trim()}`;
+${trimmedContent}`;
   return [...beforeSection, newSection, ...afterSection].join("\n");
 }
 function slugify(title) {
@@ -48147,11 +48228,13 @@ var listCommand2 = new Command("list").description("List all documentation files
     }
     const docs = [];
     for (const file3 of mdFiles) {
-      const content = await readFile11(join17(DOCS_DIR, file3), "utf-8");
-      const { data } = (0, import_gray_matter6.default)(content);
+      const fileContent = await readFile11(join17(DOCS_DIR, file3), "utf-8");
+      const { data, content } = (0, import_gray_matter6.default)(fileContent);
+      const stats = calculateDocStats(content);
       docs.push({
         filename: file3,
-        metadata: data
+        metadata: data,
+        tokens: stats.estimatedTokens
       });
     }
     let filteredDocs = docs;
@@ -48177,7 +48260,8 @@ var listCommand2 = new Command("list").description("List all documentation files
         if (parts.length === 1) {
           rootDocs.push({
             name: parts[0].replace(/\.md$/, ""),
-            title: doc.metadata.title
+            title: doc.metadata.title,
+            tokens: doc.tokens
           });
         } else {
           const folder = parts.slice(0, -1).join("/");
@@ -48185,7 +48269,7 @@ var listCommand2 = new Command("list").description("List all documentation files
           if (!folders.has(folder)) {
             folders.set(folder, []);
           }
-          folders.get(folder)?.push({ name, title: doc.metadata.title });
+          folders.get(folder)?.push({ name, title: doc.metadata.title, tokens: doc.tokens });
         }
       }
       const sortedFolders = Array.from(folders.keys()).sort();
@@ -48193,13 +48277,13 @@ var listCommand2 = new Command("list").description("List all documentation files
         console.log(`${folder}/`);
         const docs2 = folders.get(folder)?.sort((a, b) => a.name.localeCompare(b.name));
         for (const doc of docs2) {
-          console.log(`  ${doc.name} - ${doc.title}`);
+          console.log(`  ${doc.name} - ${doc.title} (~${doc.tokens} tokens)`);
         }
       }
       if (rootDocs.length > 0) {
         rootDocs.sort((a, b) => a.name.localeCompare(b.name));
         for (const doc of rootDocs) {
-          console.log(`${doc.name} - ${doc.title}`);
+          console.log(`${doc.name} - ${doc.title} (~${doc.tokens} tokens)`);
         }
       }
     } else {
@@ -48254,7 +48338,7 @@ Documentation (${filteredDocs.length})
     process.exit(1);
   }
 });
-var viewCommand2 = new Command("view").description("View a documentation file").argument("<name>", "Document name (filename or title or path)").option("--plain", "Plain text output for AI").option("--info", "Show document stats (size, tokens, headings) without content").option("--toc", "Show table of contents only").option("--section <title>", "Show specific section by heading title or number (e.g., '2. Overview' or '2')").action(
+var viewCommand2 = new Command("view").description("View a documentation file").argument("<name>", "Document name (filename or title or path)").option("--plain", "Plain text output for AI").option("--info", "Show document stats (size, tokens, headings) without content").option("--toc", "Show table of contents only").option("--section <title>", "Show specific section by heading title or number (e.g., '2. Overview' or '2')").option("--smart", "Smart mode: auto-return full content if small, or stats+TOC if large (>2000 tokens)").action(
   async (name, options2) => {
     try {
       await ensureDocsDir();
@@ -48284,6 +48368,45 @@ var viewCommand2 = new Command("view").description("View a documentation file").
       const fileContent = await readFile11(filepath, "utf-8");
       const { data, content } = (0, import_gray_matter6.default)(fileContent);
       const metadata = data;
+      if (options2.smart) {
+        const stats = calculateDocStats(content);
+        const SMART_THRESHOLD = 2e3;
+        if (stats.estimatedTokens <= SMART_THRESHOLD) {
+        } else {
+          const toc = extractToc(content);
+          if (options2.plain) {
+            console.log(`Document: ${metadata.title}`);
+            console.log("=".repeat(50));
+            console.log();
+            console.log(
+              `Size: ${stats.chars.toLocaleString()} chars (~${stats.estimatedTokens.toLocaleString()} tokens)`
+            );
+            console.log(`Headings: ${stats.headingCount}`);
+            console.log();
+            console.log("Table of Contents:");
+            console.log("-".repeat(50));
+            toc.forEach((entry, index) => {
+              const indent = "  ".repeat(entry.level - 1);
+              console.log(`${indent}${index + 1}. ${entry.title}`);
+            });
+            console.log();
+            console.log("Document is large. Use --section <number> to read a specific section.");
+          } else {
+            console.log(source_default.bold(`
+\u{1F4C4} ${metadata.title} (Smart Mode)
+`));
+            console.log(
+              `Size: ${source_default.cyan(stats.chars.toLocaleString())} chars (~${source_default.yellow(stats.estimatedTokens.toLocaleString())} tokens)`
+            );
+            console.log();
+            console.log(source_default.bold("Table of Contents:"));
+            console.log(formatToc(toc));
+            console.log();
+            console.log(source_default.yellow("\u26A0 Document is large. Use --section <number> to read a specific section."));
+          }
+          return;
+        }
+      }
       if (options2.info) {
         const stats = calculateDocStats(content);
         if (options2.plain) {
@@ -48336,7 +48459,8 @@ var viewCommand2 = new Command("view").description("View a documentation file").
         return;
       }
       if (options2.section) {
-        const sectionContent = extractSection(content, options2.section);
+        const sectionIndex = /^\d+$/.test(options2.section) ? Number.parseInt(options2.section, 10) : null;
+        const sectionContent = sectionIndex !== null ? extractSectionByIndex(content, sectionIndex) : extractSection(content, options2.section);
         if (!sectionContent) {
           console.error(
             options2.plain ? `Section not found: ${options2.section}` : source_default.red(`\u2717 Section not found: ${options2.section}`)
@@ -48411,13 +48535,6 @@ var viewCommand2 = new Command("view").description("View a documentation file").
         for (const { original, resolved } of linksToAdd) {
           enhancedContent = enhancedContent.replace(original, resolved);
         }
-        const knownProjectRoot = findProjectRoot();
-        if (knownProjectRoot) {
-          const fileStore2 = new FileStore(knownProjectRoot);
-          const allTasks = await fileStore2.getAllTasks();
-          const taskMap = buildTaskMap(allTasks);
-          enhancedContent = transformMentionsToRefs(enhancedContent, taskMap);
-        }
         console.log(enhancedContent);
       } else {
         console.log(source_default.bold(`
@@ -48500,7 +48617,8 @@ var editCommand2 = new Command("edit").description("Edit a documentation file (m
 ${normalizeRefs(fileData)}`;
         sourceFile = options2.appendFile;
       } else if (options2.section && options2.content) {
-        const result = replaceSection(content, options2.section, normalizeRefs(options2.content));
+        const sectionIndex = /^\d+$/.test(options2.section) ? Number.parseInt(options2.section, 10) : null;
+        const result = sectionIndex !== null ? replaceSectionByIndex(content, sectionIndex, normalizeRefs(options2.content)) : replaceSection(content, options2.section, normalizeRefs(options2.content));
         if (!result) {
           console.error(
             options2.plain ? `Section not found: ${options2.section}` : source_default.red(`\u2717 Section not found: ${options2.section}`)
@@ -48825,7 +48943,7 @@ ${afterSection.trimStart()}`;
     process.exit(1);
   }
 });
-var docCommand = new Command("doc").description("Manage documentation").argument("[name]", "Document name (shorthand for 'doc view <name>')").option("--plain", "Plain text output for AI").option("--info", "Show document stats (size, tokens, headings) without content").option("--toc", "Show table of contents only").option("--section <title>", "Show specific section by heading title or number").enablePositionalOptions().action(
+var docCommand = new Command("doc").description("Manage documentation").argument("[name]", "Document name (shorthand for 'doc view <name>')").option("--plain", "Plain text output for AI").option("--info", "Show document stats (size, tokens, headings) without content").option("--toc", "Show table of contents only").option("--section <title>", "Show specific section by heading title or number").option("--smart", "Smart mode: auto-return full content if small, or stats+TOC if large (>2000 tokens)").enablePositionalOptions().action(
   async (name, options2) => {
     if (!name) {
       docCommand.help();
@@ -48841,6 +48959,45 @@ var docCommand = new Command("doc").description("Manage documentation").argument
       const fileContent = await readFile11(filepath, "utf-8");
       const { data, content } = (0, import_gray_matter6.default)(fileContent);
       const metadata = data;
+      if (options2.smart) {
+        const stats = calculateDocStats(content);
+        const SMART_THRESHOLD = 2e3;
+        if (stats.estimatedTokens <= SMART_THRESHOLD) {
+        } else {
+          const toc = extractToc(content);
+          if (options2.plain) {
+            console.log(`Document: ${metadata.title}`);
+            console.log("=".repeat(50));
+            console.log();
+            console.log(
+              `Size: ${stats.chars.toLocaleString()} chars (~${stats.estimatedTokens.toLocaleString()} tokens)`
+            );
+            console.log(`Headings: ${stats.headingCount}`);
+            console.log();
+            console.log("Table of Contents:");
+            console.log("-".repeat(50));
+            toc.forEach((entry, index) => {
+              const indent = "  ".repeat(entry.level - 1);
+              console.log(`${indent}${index + 1}. ${entry.title}`);
+            });
+            console.log();
+            console.log("Document is large. Use --section <number> to read a specific section.");
+          } else {
+            console.log(source_default.bold(`
+\u{1F4C4} ${metadata.title} (Smart Mode)
+`));
+            console.log(
+              `Size: ${source_default.cyan(stats.chars.toLocaleString())} chars (~${source_default.yellow(stats.estimatedTokens.toLocaleString())} tokens)`
+            );
+            console.log();
+            console.log(source_default.bold("Table of Contents:"));
+            console.log(formatToc(toc));
+            console.log();
+            console.log(source_default.yellow("\u26A0 Document is large. Use --section <number> to read a specific section."));
+          }
+          return;
+        }
+      }
       if (options2.info) {
         const stats = calculateDocStats(content);
         if (options2.plain) {
@@ -48893,7 +49050,8 @@ var docCommand = new Command("doc").description("Manage documentation").argument
         return;
       }
       if (options2.section) {
-        const sectionContent = extractSection(content, options2.section);
+        const sectionIndex = /^\d+$/.test(options2.section) ? Number.parseInt(options2.section, 10) : null;
+        const sectionContent = sectionIndex !== null ? extractSectionByIndex(content, sectionIndex) : extractSection(content, options2.section);
         if (!sectionContent) {
           console.error(
             options2.plain ? `Section not found: ${options2.section}` : source_default.red(`\u2717 Section not found: ${options2.section}`)
@@ -48968,13 +49126,6 @@ var docCommand = new Command("doc").description("Manage documentation").argument
         for (const { original, resolved: resolved2 } of linksToAdd) {
           enhancedContent = enhancedContent.replace(original, resolved2);
         }
-        const knownProjectRoot = findProjectRoot();
-        if (knownProjectRoot) {
-          const fileStore2 = new FileStore(knownProjectRoot);
-          const allTasks = await fileStore2.getAllTasks();
-          const taskMap = buildTaskMap(allTasks);
-          enhancedContent = transformMentionsToRefs(enhancedContent, taskMap);
-        }
         console.log(enhancedContent);
       } else {
         console.log(source_default.bold(`
@@ -62987,14 +63138,135 @@ 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 existsSync16, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { join as join19 } from "node:path";
+var PROJECT_ROOT2 = process.cwd();
+async function syncSkills(options2) {
+  const skillsDir = join19(PROJECT_ROOT2, ".claude", "skills");
+  if (!existsSync16(skillsDir)) {
+    mkdirSync(skillsDir, { recursive: true });
+    console.log(source_default.green("\u2713 Created .claude/skills/"));
+  }
+  let created = 0;
+  let updated = 0;
+  let skipped = 0;
+  for (const skill of SKILLS) {
+    const skillFolder = join19(skillsDir, skill.folderName);
+    const skillFile = join19(skillFolder, "SKILL.md");
+    if (existsSync16(skillFile)) {
+      if (options2.force) {
+        const existing = readFileSync2(skillFile, "utf-8");
+        if (existing.trim() !== skill.content.trim()) {
+          writeFileSync(skillFile, skill.content, "utf-8");
+          console.log(source_default.green(`\u2713 Updated: ${skill.name}`));
+          updated++;
+        } else {
+          console.log(source_default.gray(`  Unchanged: ${skill.name}`));
+          skipped++;
+        }
+      } else {
+        console.log(source_default.gray(`  Skipped: ${skill.name} (use --force to update)`));
+        skipped++;
+      }
+    } else {
+      if (!existsSync16(skillFolder)) {
+        mkdirSync(skillFolder, { recursive: true });
+      }
+      writeFileSync(skillFile, skill.content, "utf-8");
+      console.log(source_default.green(`\u2713 Created: ${skill.name}`));
+      created++;
+    }
+  }
+  return { created, updated, skipped };
+}
+async function syncAgents(options2) {
+  const type = options2.type === "mcp" ? "mcp" : "cli";
+  const guidelines = getGuidelines(type);
+  const filesToUpdate = options2.all ? INSTRUCTION_FILES : INSTRUCTION_FILES.filter((f) => f.selected);
+  let created = 0;
+  let updated = 0;
+  let skipped = 0;
+  for (const file3 of filesToUpdate) {
+    try {
+      const result = await updateInstructionFile(file3.path, guidelines);
+      if (result.success) {
+        if (result.action === "created") {
+          console.log(source_default.green(`\u2713 Created: ${file3.path}`));
+          created++;
+        } else if (result.action === "appended") {
+          console.log(source_default.cyan(`\u2713 Appended: ${file3.path}`));
+          updated++;
+        } else {
+          console.log(source_default.green(`\u2713 Updated: ${file3.path}`));
+          updated++;
+        }
+      }
+    } catch (error48) {
+      console.log(source_default.gray(`  Skipped: ${file3.path}`));
+      skipped++;
+    }
+  }
+  return { created, updated, skipped };
+}
+function printSummary(label, stats) {
+  console.log(source_default.bold(`
+${label}:`));
+  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}`));
+}
+var syncCommand = new Command("sync").description("Sync skills and agent instruction files").enablePositionalOptions().option("-f, --force", "Force overwrite existing files").option("--type <type>", "Guidelines type for agents: cli or mcp", "cli").option("--all", "Update all agent files (including Gemini, Copilot)").action(async (options2) => {
+  try {
+    console.log(source_default.bold("\nSyncing all...\n"));
+    console.log(source_default.cyan("Skills:"));
+    const skillStats = await syncSkills(options2);
+    console.log(source_default.cyan("\nAgent files:"));
+    const agentStats = await syncAgents(options2);
+    printSummary("Skills", skillStats);
+    printSummary("Agents", agentStats);
+    console.log();
+  } catch (error48) {
+    console.error(source_default.red("Error:"), error48 instanceof Error ? error48.message : String(error48));
+    process.exit(1);
+  }
+});
+var skillsSubcommand = new Command("skills").description("Sync Claude Code skills only").option("-f, --force", "Force overwrite existing skills").action(async (options2) => {
+  try {
+    console.log(source_default.bold("\nSyncing skills...\n"));
+    const stats = await syncSkills({ force: options2.force });
+    printSummary("Summary", stats);
+    console.log();
+  } catch (error48) {
+    console.error(source_default.red("Error:"), error48 instanceof Error ? error48.message : String(error48));
+    process.exit(1);
+  }
+});
+var agentSubcommand = new Command("agent").description("Sync agent instruction files only (CLAUDE.md, AGENTS.md, etc.)").option("--force", "Force overwrite existing files").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--all", "Update all agent files (including Gemini, Copilot)").action(async (options2) => {
+  try {
+    const type = options2.type === "mcp" ? "mcp" : "cli";
+    console.log(source_default.bold(`
+Syncing agent files (${type.toUpperCase()})...
+`));
+    const stats = await syncAgents(options2);
+    printSummary("Summary", stats);
+    console.log();
+  } catch (error48) {
+    console.error(source_default.red("Error:"), error48 instanceof Error ? error48.message : String(error48));
+    process.exit(1);
+  }
+});
+syncCommand.addCommand(skillsSubcommand);
+syncCommand.addCommand(agentSubcommand);
+
 // src/commands/mcp.ts
-import { existsSync as existsSync18, readFileSync as readFileSync2, writeFileSync } from "node:fs";
-import { join as join22 } from "node:path";
+import { existsSync as existsSync19, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join23 } from "node:path";
 
 // src/mcp/server.ts
-import { existsSync as existsSync17 } from "node:fs";
+import { existsSync as existsSync18 } from "node:fs";
 import { readFile as readFile15 } from "node:fs/promises";
-import { join as join21 } from "node:path";
+import { join as join22 } from "node:path";
 
 // node_modules/zod/v3/helpers/util.js
 var util;
@@ -70058,7 +70330,7 @@ var import_gray_matter9 = __toESM(require_gray_matter(), 1);
 
 // src/mcp/utils.ts
 import { readFile as readFile13 } from "node:fs/promises";
-import { join as join19 } from "node:path";
+import { join as join20 } from "node:path";
 var import_gray_matter7 = __toESM(require_gray_matter(), 1);
 function parseDuration2(durationStr) {
   let totalSeconds = 0;
@@ -70091,7 +70363,7 @@ function formatDuration2(seconds) {
 }
 async function fetchLinkedDocs(task) {
   const projectRoot = process.cwd();
-  const docsDir = join19(projectRoot, ".knowns", "docs");
+  const docsDir = join20(projectRoot, ".knowns", "docs");
   const allContent = [task.description || "", task.implementationPlan || "", task.implementationNotes || ""].join("\n");
   const docRefs = resolveDocReferences(allContent, projectRoot);
   const linkedDocs = [];
@@ -70099,7 +70371,7 @@ async function fetchLinkedDocs(task) {
     if (!ref.exists) continue;
     try {
       const filename = ref.resolvedPath.replace("@.knowns/docs/", "");
-      const filepath = join19(docsDir, filename);
+      const filepath = join20(docsDir, filename);
       const fileContent = await readFile13(filepath, "utf-8");
       const { data, content } = (0, import_gray_matter7.default)(fileContent);
       linkedDocs.push({
@@ -70662,11 +70934,11 @@ async function handleGetBoard(fileStore2) {
 }
 
 // src/mcp/handlers/doc.ts
-import { existsSync as existsSync16 } from "node:fs";
+import { existsSync as existsSync17 } from "node:fs";
 import { mkdir as mkdir9, readFile as readFile14, readdir as readdir6, writeFile as writeFile10 } from "node:fs/promises";
-import { join as join20 } from "node:path";
+import { join as join21 } from "node:path";
 var import_gray_matter8 = __toESM(require_gray_matter(), 1);
-var DOCS_DIR2 = join20(process.cwd(), ".knowns", "docs");
+var DOCS_DIR2 = join21(process.cwd(), ".knowns", "docs");
 var listDocsSchema = external_exports.object({
   tag: external_exports.string().optional()
 });
@@ -70677,8 +70949,10 @@ var getDocSchema = external_exports.object({
   // Return document stats (size, tokens, headings) without content
   toc: external_exports.boolean().optional(),
   // Return table of contents only
-  section: external_exports.string().optional()
+  section: external_exports.string().optional(),
   // Return specific section by heading title or number
+  smart: external_exports.boolean().optional()
+  // Smart mode: auto-return full content if small, or stats+TOC if large
 });
 var createDocSchema = external_exports.object({
   title: external_exports.string(),
@@ -70717,7 +70991,7 @@ var docTools = [
   },
   {
     name: "get_doc",
-    description: "Get a documentation file by path. Use 'info: true' first to check size, then 'toc: true' for table of contents, then 'section' to read specific parts.",
+    description: "Get a documentation file by path. Use 'smart: true' for auto-optimized reading (recommended for AI), or 'info/toc/section' for manual control.",
     inputSchema: {
       type: "object",
       properties: {
@@ -70725,6 +70999,10 @@ var docTools = [
           type: "string",
           description: "Document path (e.g., 'readme', 'guides/setup', 'conventions/naming.md')"
         },
+        smart: {
+          type: "boolean",
+          description: "Smart mode (recommended): auto-return full content if small (\u22642000 tokens), or stats+TOC if large. Use this by default."
+        },
         info: {
           type: "boolean",
           description: "Return document stats (size, tokens, headings) without content. Use this first to decide how to read."
@@ -70810,7 +71088,7 @@ var docTools = [
   }
 ];
 async function ensureDocsDir2() {
-  if (!existsSync16(DOCS_DIR2)) {
+  if (!existsSync17(DOCS_DIR2)) {
     await mkdir9(DOCS_DIR2, { recursive: true });
   }
 }
@@ -70819,13 +71097,13 @@ function titleToFilename2(title) {
 }
 async function getAllMdFiles2(dir, basePath = "") {
   const files = [];
-  if (!existsSync16(dir)) {
+  if (!existsSync17(dir)) {
     return files;
   }
   const entries = await readdir6(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join20(dir, entry.name);
-    const relativePath = normalizePath(basePath ? join20(basePath, entry.name) : entry.name);
+    const fullPath = join21(dir, entry.name);
+    const relativePath = normalizePath(basePath ? join21(basePath, entry.name) : entry.name);
     if (entry.isDirectory()) {
       const subFiles = await getAllMdFiles2(fullPath, relativePath);
       files.push(...subFiles);
@@ -70838,13 +71116,13 @@ async function getAllMdFiles2(dir, basePath = "") {
 async function resolveDocPath2(name) {
   await ensureDocsDir2();
   let filename = name.endsWith(".md") ? name : `${name}.md`;
-  let filepath = join20(DOCS_DIR2, filename);
-  if (existsSync16(filepath)) {
+  let filepath = join21(DOCS_DIR2, filename);
+  if (existsSync17(filepath)) {
     return { filepath, filename };
   }
   filename = `${titleToFilename2(name)}.md`;
-  filepath = join20(DOCS_DIR2, filename);
-  if (existsSync16(filepath)) {
+  filepath = join21(DOCS_DIR2, filename);
+  if (existsSync17(filepath)) {
     return { filepath, filename };
   }
   const allFiles = await getAllMdFiles2(DOCS_DIR2);
@@ -70856,7 +71134,7 @@ async function resolveDocPath2(name) {
   });
   if (matchingFile) {
     return {
-      filepath: join20(DOCS_DIR2, matchingFile),
+      filepath: join21(DOCS_DIR2, matchingFile),
       filename: matchingFile
     };
   }
@@ -70875,9 +71153,10 @@ async function handleListDocs(args2) {
   }
   const docs = [];
   for (const file3 of mdFiles) {
-    const content = await readFile14(join20(DOCS_DIR2, file3), "utf-8");
-    const { data } = (0, import_gray_matter8.default)(content);
+    const fileContent = await readFile14(join21(DOCS_DIR2, file3), "utf-8");
+    const { data, content } = (0, import_gray_matter8.default)(fileContent);
     const metadata = data;
+    const stats = calculateDocStats(content);
     if (input.tag && !metadata.tags?.includes(input.tag)) {
       continue;
     }
@@ -70886,6 +71165,7 @@ async function handleListDocs(args2) {
       title: metadata.title || file3.replace(/\.md$/, ""),
       description: metadata.description,
       tags: metadata.tags,
+      tokens: stats.estimatedTokens,
       updatedAt: metadata.updatedAt
     });
   }
@@ -70903,6 +71183,33 @@ async function handleGetDoc(args2) {
   const fileContent = await readFile14(resolved.filepath, "utf-8");
   const { data, content } = (0, import_gray_matter8.default)(fileContent);
   const metadata = data;
+  if (input.smart) {
+    const stats = calculateDocStats(content);
+    const SMART_THRESHOLD = 2e3;
+    if (stats.estimatedTokens <= SMART_THRESHOLD) {
+    } else {
+      const toc = extractToc(content);
+      return successResponse({
+        doc: {
+          path: resolved.filename.replace(/\.md$/, ""),
+          title: metadata.title,
+          smart: true,
+          isLarge: true,
+          stats: {
+            chars: stats.chars,
+            estimatedTokens: stats.estimatedTokens,
+            headingCount: stats.headingCount
+          },
+          toc: toc.map((entry, index) => ({
+            index: index + 1,
+            level: entry.level,
+            title: entry.title
+          })),
+          hint: "Document is large. Use 'section' parameter with a number (e.g., section: '1') to read specific content."
+        }
+      });
+    }
+  }
   if (input.info) {
     const stats = calculateDocStats(content);
     let recommendation;
@@ -70954,7 +71261,8 @@ async function handleGetDoc(args2) {
     });
   }
   if (input.section) {
-    const sectionContent = extractSection(content, input.section);
+    const sectionIndex = /^\d+$/.test(input.section) ? Number.parseInt(input.section, 10) : null;
+    const sectionContent = sectionIndex !== null ? extractSectionByIndex(content, sectionIndex) : extractSection(content, input.section);
     if (!sectionContent) {
       return errorResponse(`Section not found: ${input.section}. Use 'toc: true' to see available sections.`);
     }
@@ -70987,14 +71295,14 @@ async function handleCreateDoc(args2) {
   let relativePath = filename;
   if (input.folder) {
     const folderPath = input.folder.replace(/^\/|\/$/g, "");
-    targetDir = join20(DOCS_DIR2, folderPath);
-    relativePath = join20(folderPath, filename);
-    if (!existsSync16(targetDir)) {
+    targetDir = join21(DOCS_DIR2, folderPath);
+    relativePath = join21(folderPath, filename);
+    if (!existsSync17(targetDir)) {
       await mkdir9(targetDir, { recursive: true });
     }
   }
-  const filepath = join20(targetDir, filename);
-  if (existsSync16(filepath)) {
+  const filepath = join21(targetDir, filename);
+  if (existsSync17(filepath)) {
     return errorResponse(`Document already exists: ${relativePath}`);
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -71039,7 +71347,8 @@ async function handleUpdateDoc(args2) {
   let updatedContent = content;
   let sectionUpdated;
   if (input.section && input.content) {
-    const result = replaceSection(content, input.section, input.content);
+    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);
     if (!result) {
       return errorResponse(
         `Section not found: ${input.section}. Use 'toc: true' with get_doc to see available sections.`
@@ -71077,7 +71386,7 @@ async function handleSearchDocs(args2) {
   const query = input.query.toLowerCase();
   const results = [];
   for (const file3 of mdFiles) {
-    const fileContent = await readFile14(join20(DOCS_DIR2, file3), "utf-8");
+    const fileContent = await readFile14(join21(DOCS_DIR2, file3), "utf-8");
     const { data, content } = (0, import_gray_matter8.default)(fileContent);
     const metadata = data;
     if (input.tag && !metadata.tags?.includes(input.tag)) {
@@ -71225,7 +71534,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
   const tasks = await fileStore.getAllTasks();
-  const docsDir = join21(process.cwd(), ".knowns", "docs");
+  const docsDir = join22(process.cwd(), ".knowns", "docs");
   const taskResources = tasks.map((task) => ({
     uri: `knowns://task/${task.id}`,
     name: task.title,
@@ -71233,14 +71542,14 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     description: `Task #${task.id}: ${task.title}`
   }));
   const docResources = [];
-  if (existsSync17(docsDir)) {
+  if (existsSync18(docsDir)) {
     const { readdir: readdir7 } = await import("node:fs/promises");
     async function getAllMdFiles3(dir, basePath = "") {
       const files = [];
       const entries = await readdir7(dir, { withFileTypes: true });
       for (const entry of entries) {
-        const fullPath = join21(dir, entry.name);
-        const relativePath = normalizePath(basePath ? join21(basePath, entry.name) : entry.name);
+        const fullPath = join22(dir, entry.name);
+        const relativePath = normalizePath(basePath ? join22(basePath, entry.name) : entry.name);
         if (entry.isDirectory()) {
           const subFiles = await getAllMdFiles3(fullPath, relativePath);
           files.push(...subFiles);
@@ -71252,7 +71561,7 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     }
     const mdFiles = await getAllMdFiles3(docsDir);
     for (const file3 of mdFiles) {
-      const filepath = join21(docsDir, file3);
+      const filepath = join22(docsDir, file3);
       const content = await readFile15(filepath, "utf-8");
       const { data } = (0, import_gray_matter9.default)(content);
       docResources.push({
@@ -71289,9 +71598,9 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
   const docMatch = uri.match(/^knowns:\/\/doc\/(.+)$/);
   if (docMatch) {
     const docPath = docMatch[1];
-    const docsDir = join21(process.cwd(), ".knowns", "docs");
-    const filepath = join21(docsDir, `${docPath}.md`);
-    if (!existsSync17(filepath)) {
+    const docsDir = join22(process.cwd(), ".knowns", "docs");
+    const filepath = join22(docsDir, `${docPath}.md`);
+    if (!existsSync18(filepath)) {
       throw new Error(`Documentation ${docPath} not found`);
     }
     const content = await readFile15(filepath, "utf-8");
@@ -71373,15 +71682,15 @@ async function setupClaudeCode() {
   return false;
 }
 function createProjectMcpJson(projectRoot) {
-  const mcpJsonPath = join22(projectRoot, ".mcp.json");
+  const mcpJsonPath = join23(projectRoot, ".mcp.json");
   const mcpConfig = {
     mcpServers: {
       knowns: getMcpConfig()
     }
   };
-  if (existsSync18(mcpJsonPath)) {
+  if (existsSync19(mcpJsonPath)) {
     try {
-      const existing = JSON.parse(readFileSync2(mcpJsonPath, "utf-8"));
+      const existing = JSON.parse(readFileSync3(mcpJsonPath, "utf-8"));
       if (existing?.mcpServers?.knowns) {
         console.log(source_default.gray("  .mcp.json already has knowns configuration"));
         return true;
@@ -71390,14 +71699,14 @@ function createProjectMcpJson(projectRoot) {
         ...existing.mcpServers,
         ...mcpConfig.mcpServers
       };
-      writeFileSync(mcpJsonPath, JSON.stringify(existing, null, "	"), "utf-8");
+      writeFileSync2(mcpJsonPath, JSON.stringify(existing, null, "	"), "utf-8");
       console.log(source_default.green("\u2713 Added knowns to existing .mcp.json"));
     } catch {
-      writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
+      writeFileSync2(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
       console.log(source_default.green("\u2713 Created .mcp.json (replaced invalid file)"));
     }
   } else {
-    writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
+    writeFileSync2(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
     console.log(source_default.green("\u2713 Created .mcp.json for Claude Code project-level auto-discovery"));
   }
   return true;
@@ -71479,10 +71788,10 @@ function showConfigInfo() {
 }
 
 // src/utils/update-notifier.ts
-import { existsSync as existsSync19, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync20, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
 import { mkdir as mkdir10 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname as dirname4, join as join23 } from "node:path";
+import { dirname as dirname4, join as join24 } from "node:path";
 var DEFAULT_TTL_MS = 60 * 60 * 1e3;
 var DEFAULT_TIMEOUT_MS = 2e3;
 function detectPackageManager(cwd) {
@@ -71495,10 +71804,10 @@ function detectPackageManager(cwd) {
   if (ua.startsWith("yarn/")) return "yarn";
   if (ua.startsWith("bun/")) return "bun";
   if (ua.startsWith("npm/")) return "npm";
-  if (existsSync19(join23(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync19(join23(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync19(join23(cwd, "bun.lock"))) return "bun";
-  if (existsSync19(join23(cwd, "package-lock.json"))) return "npm";
+  if (existsSync20(join24(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync20(join24(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync20(join24(cwd, "bun.lock"))) return "bun";
+  if (existsSync20(join24(cwd, "package-lock.json"))) return "npm";
   return "npm";
 }
 function compareVersions(a, b) {
@@ -71522,11 +71831,11 @@ function shouldSkip(args2, force) {
 }
 function getGlobalCachePath(explicit) {
   if (explicit) return explicit;
-  return join23(homedir(), ".knowns", "cli-cache.json");
+  return join24(homedir(), ".knowns", "cli-cache.json");
 }
 function readCache(cachePath) {
   try {
-    const raw = readFileSync3(cachePath, "utf-8");
+    const raw = readFileSync4(cachePath, "utf-8");
     const data = JSON.parse(raw);
     if (typeof data.lastChecked === "number" && typeof data.latestVersion === "string") {
       return data;
@@ -71538,10 +71847,10 @@ function readCache(cachePath) {
 }
 async function writeCache(cachePath, data) {
   const dir = dirname4(cachePath);
-  if (dir && !existsSync19(dir)) {
+  if (dir && !existsSync20(dir)) {
     await mkdir10(dir, { recursive: true });
   }
-  writeFileSync2(cachePath, JSON.stringify(data, null, 2), "utf-8");
+  writeFileSync3(cachePath, JSON.stringify(data, null, 2), "utf-8");
 }
 async function fetchLatestVersion(packageName) {
   try {
@@ -71604,7 +71913,7 @@ async function notifyCliUpdate(options2) {
 // package.json
 var package_default = {
   name: "knowns",
-  version: "0.8.8",
+  version: "0.9.0",
   description: "AI-native task and documentation management for dev teams",
   module: "index.ts",
   type: "module",
@@ -71760,6 +72069,7 @@ program2.addCommand(searchCommand);
 program2.addCommand(timeCommand);
 program2.addCommand(docCommand);
 program2.addCommand(configCommand);
+program2.addCommand(syncCommand);
 program2.addCommand(agentsCommand);
 program2.addCommand(mcpCommand);
 var args = process.argv.slice(2);