knowns 0.8.3 → 0.8.5

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 join23 = path.join;
+    var join24 = 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 = join23(dir, file3);
+      var path2 = join24(dir, file3);
       var stat3 = tryStat(path2);
       if (stat3 && stat3.isFile()) {
         return path2;
       }
-      path2 = join23(dir, basename3(file3, ext), "index" + ext);
+      path2 = join24(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 join23 = path.join;
+    var join24 = 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(join23(root, path2));
+        path2 = normalize(join24(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 = join23(path2, self._index[i]);
+        var p = join24(path2, self._index[i]);
         debug('stat "%s"', p);
         fs.stat(p, function(err2, stat3) {
           if (err2) return next(err2);
@@ -43479,19 +43479,22 @@ var import_prompts = __toESM(require_prompts3(), 1);
 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';
 
 // src/templates/guidelines/commands-reference.md
-var commands_reference_default = '# CLI Commands Reference\n\nComplete reference for all Knowns CLI commands.\n\n---\n\n## Task Commands\n\n### task create\n\n```\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--description` | `-d` | Task description | `-d "Fix the login bug"` |\n| `--ac` | | Acceptance criterion (repeatable) | `--ac "User can login"` |\n| `--labels` | `-l` | Comma-separated labels | `-l "bug,urgent"` |\n| `--assignee` | `-a` | Assign to user | `-a @username` |\n| `--priority` | | low/medium/high | `--priority high` |\n| `--status` | `-s` | Initial status | `-s todo` |\n| `--parent` | | Parent task ID (raw ID only!) | `--parent 48` |\n\n**Example:**\n```bash\nknowns task create "Fix login timeout" \\\n  -d "Users experience timeout on slow networks" \\\n  --ac "Login works on 3G connection" \\\n  --ac "Timeout increased to 30s" \\\n  -l "bug,auth" \\\n  --priority high\n```\n\n---\n\n### task edit\n\n```\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--title` | `-t` | Change title | `-t "New title"` |\n| `--description` | `-d` | Change description | `-d "New desc"` |\n| `--status` | `-s` | Change status | `-s in-progress` |\n| `--priority` | | Change priority | `--priority high` |\n| `--labels` | `-l` | Set labels | `-l "bug,urgent"` |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F | `-a @username` |\n| `--parent` | | Move to parent | `--parent 48` |\n| `--ac` | | Add acceptance criterion | `--ac "New criterion"` |\n| `--check-ac` | | Mark AC done (1-indexed) | `--check-ac 1` |\n| `--uncheck-ac` | | Unmark AC (1-indexed) | `--uncheck-ac 1` |\n| `--remove-ac` | | Delete AC (1-indexed) | `--remove-ac 3` |\n| `--plan` | | Set implementation plan | `--plan "1. Step one"` |\n| `--notes` | | Replace notes | `--notes "Summary"` |\n| `--append-notes` | | Add to notes | `--append-notes "\u2713 Done"` |\n\n**\u26A0\uFE0F WARNING:** `-a` is assignee, NOT acceptance criteria! Use `--ac` for AC.\n\n**Examples:**\n```bash\n# Take task\nknowns task edit abc123 -s in-progress -a @me\n\n# Add acceptance criteria (use --ac, NOT -a!)\nknowns task edit abc123 --ac "Feature works offline"\n\n# Check criteria as done (1-indexed)\nknowns task edit abc123 --check-ac 1 --check-ac 2\n\n# Add implementation plan\nknowns task edit abc123 --plan $\'1. Research\\n2. Implement\\n3. Test\'\n\n# Add progress notes\nknowns task edit abc123 --append-notes "\u2713 Completed research phase"\n\n# Complete task\nknowns task edit abc123 -s done\n```\n\n---\n\n### task view/list\n\n```bash\n# View single task (ALWAYS use --plain for AI)\nknowns task <id> --plain\nknowns task view <id> --plain\n\n# List tasks\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain\n```\n\n---\n\n## Doc Commands\n\n### doc create\n\n```\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--description` | `-d` | Description | `-d "API reference"` |\n| `--tags` | `-t` | Comma-separated tags | `-t "api,reference"` |\n| `--folder` | `-f` | Folder path | `-f "guides"` |\n\n**Example:**\n```bash\nknowns doc create "API Reference" \\\n  -d "REST API documentation" \\\n  -t "api,docs" \\\n  -f "api"\n```\n\n---\n\n### doc edit\n\n```\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--title` | `-t` | Change title | `-t "New Title"` |\n| `--description` | `-d` | Change description | `-d "New desc"` |\n| `--tags` | | Set tags | `--tags "new,tags"` |\n| `--content` | `-c` | Replace content | `-c "New content"` |\n| `--append` | `-a` | Append content \u26A0\uFE0F | `-a "Added section"` |\n| `--content-file` | | Content from file | `--content-file ./content.md` |\n| `--append-file` | | Append from file | `--append-file ./more.md` |\n\n**\u26A0\uFE0F NOTE:** In doc edit, `-a` means append content, NOT assignee!\n\n**Examples:**\n```bash\n# Replace content\nknowns doc edit "readme" -c "# New Content"\n\n# Append content\nknowns doc edit "readme" -a "## New Section"\n```\n\n---\n\n### doc view/list\n\n```bash\n# View doc (ALWAYS use --plain for AI)\nknowns doc <path> --plain\nknowns doc view "<path>" --plain\n\n# List docs\nknowns doc list --plain\nknowns doc list --tag api --plain\nknowns doc list "guides/" --plain\n```\n\n---\n\n## Time Commands\n\n```bash\n# Start timer (REQUIRED when taking task)\nknowns time start <taskId>\n\n# Stop timer (REQUIRED when completing task)\nknowns time stop\n\n# Pause/resume\nknowns time pause\nknowns time resume\n\n# Check status\nknowns time status\n\n# Manual entry\nknowns time add <taskId> <duration> -n "Note" -d "2025-01-01"\n# duration: "2h", "30m", "1h30m"\n\n# Report\nknowns time report --from "2025-01-01" --to "2025-12-31"\n```\n\n---\n\n## Search Commands\n\n```bash\n# Search everything\nknowns search "query" --plain\n\n# Search by type\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\n\n# Filter by status/priority\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash/Zsh (ANSI-C quoting):**\n```bash\nknowns task edit <id> --plan $\'1. Step one\\n2. Step two\\n3. Step three\'\n```\n\n**PowerShell:**\n```powershell\nknowns task edit <id> --plan "1. Step one`n2. Step two`n3. Step three"\n```\n\n**Cross-platform (heredoc):**\n```bash\nknowns task edit <id> --plan "$(cat <<EOF\n1. Step one\n2. Step two\n3. Step three\nEOF\n)"\n```\n\n---\n\n## MCP Tools (Alternative to CLI)\n\n| Action | MCP Tool |\n|--------|----------|\n| List tasks | `list_tasks({})` |\n| Get task | `get_task({ taskId })` |\n| Create task | `create_task({ title, description, priority, labels })` |\n| Update task | `update_task({ taskId, status, assignee, plan, notes })` |\n| Search tasks | `search_tasks({ query })` |\n| List docs | `list_docs({})` |\n| Get doc | `get_doc({ path })` |\n| Create doc | `create_doc({ title, description, tags, folder })` |\n| Update doc | `update_doc({ path, content, appendContent })` |\n| Start timer | `start_time({ taskId })` |\n| Stop timer | `stop_time({ taskId })` |\n\n**Note:** MCP does NOT support acceptance criteria operations. Use CLI:\n```bash\nknowns task edit <id> --ac "criterion"\nknowns task edit <id> --check-ac 1\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---\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 |\n| `--append` | `-a` | Append content \u26A0\uFE0F |\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---\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---\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/workflow-completion.md
-var workflow_completion_default = '# Task Completion Workflow\n\nGuide for properly completing tasks.\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** of the following are complete:\n\n### \u2705 Via CLI Commands\n\n| Requirement | Command | Status |\n|-------------|---------|--------|\n| All AC checked | `knowns task edit <id> --check-ac N` | Required |\n| Implementation notes added | `knowns task edit <id> --notes "..."` | Required |\n| Timer stopped | `knowns time stop` | Required |\n| Status set to done | `knowns task edit <id> -s done` | Required |\n\n### \u2705 Via Code/Testing\n\n| Requirement | Action | Status |\n|-------------|--------|--------|\n| Tests pass | Run test suite | Required |\n| No regressions | Verify existing functionality | Required |\n| Docs updated | Update relevant documentation | If applicable |\n| Code reviewed | Self-review changes | Required |\n\n---\n\n## Completion Steps\n\n### Step 1: Verify All Acceptance Criteria\n\n```bash\n# View the task to check AC status\nknowns task <id> --plain\n\n# Ensure ALL criteria are checked\n# If any are unchecked, complete the work first!\n```\n\n### Step 2: Add Implementation Notes\n\nWrite notes suitable for a PR description:\n\n```bash\nknowns task edit <id> --notes $\'## Summary\nImplemented JWT authentication using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Notes\n- Chose HS256 algorithm for simplicity\n- Token expiry set to 1 hour as per requirements\'\n```\n\n**Good notes include:**\n- What was implemented\n- Key decisions and why\n- Files changed\n- Test coverage\n- Any follow-up needed\n\n### Step 3: Stop Timer\n\n```bash\nknowns time stop\n```\n\n**\u26A0\uFE0F CRITICAL:** Never forget to stop the timer!\n\nIf you forgot to stop earlier, add manual entry:\n```bash\nknowns time add <id> 2h -n "Forgot to stop timer"\n```\n\n### Step 4: Mark as Done\n\n```bash\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf the user requests changes **AFTER** the task is marked done:\n\n```bash\n# 1. Reopen task\nknowns task edit <id> -s in-progress\n\n# 2. Restart timer\nknowns time start <id>\n\n# 3. Add AC for the changes\nknowns task edit <id> --ac "Post-completion fix: description"\n\n# 4. Document why reopened\nknowns task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - reason"\n\n# 5. Complete the work, then follow completion steps again\n```\n\n---\n\n## Knowledge Extraction\n\nAfter completing a task, consider if any knowledge should be documented:\n\n```bash\n# Search if similar pattern already documented\nknowns search "pattern-name" --type doc --plain\n\n# If new reusable knowledge, create doc\nknowns doc create "Pattern: Name" \\\n  -d "Reusable pattern from task implementation" \\\n  -t "pattern" \\\n  -f "patterns"\n\n# Reference source task\nknowns doc edit "patterns/name" -a "Source: @task-<id>"\n```\n\n**Extract knowledge when:**\n- New patterns/conventions discovered\n- Common error solutions found\n- Reusable code approaches identified\n- Integration patterns documented\n\n**Don\'t extract:**\n- Task-specific details (those belong in implementation notes)\n- One-off solutions\n\n---\n\n## Common Mistakes\n\n### \u274C Marking done without all AC checked\n\n```bash\n# \u274C Wrong: AC not all checked\nknowns task edit <id> -s done\n\n# \u2705 Right: Check all AC first\nknowns task edit <id> --check-ac 1 --check-ac 2 --check-ac 3\nknowns task edit <id> -s done\n```\n\n### \u274C Forgetting to stop timer\n\nTimer keeps running! Always stop when done:\n```bash\nknowns time stop\n```\n\n### \u274C No implementation notes\n\nNotes are required for PR description:\n```bash\n# \u274C Wrong: No notes\nknowns task edit <id> -s done\n\n# \u2705 Right: Add notes first\nknowns task edit <id> --notes "Summary of what was done"\nknowns task edit <id> -s done\n```\n\n### \u274C Autonomously creating follow-up tasks\n\nAfter completing work, **present** follow-up ideas to the user. Don\'t automatically create new tasks without permission.\n\n---\n\n## Completion Checklist\n\nBefore marking done, verify:\n\n- [ ] All acceptance criteria are checked (`--check-ac`)\n- [ ] Implementation notes are added (`--notes`)\n- [ ] Implementation plan reflects final approach\n- [ ] Tests pass without regressions\n- [ ] Documentation updated if needed\n- [ ] Timer stopped (`knowns time stop`)\n- [ ] Status set to done (`-s done`)\n';
+var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| 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';
 
 // src/templates/guidelines/workflow-creation.md
-var workflow_creation_default = '# Task Creation Workflow\n\nGuide for creating well-structured tasks.\n\n---\n\n## Step 1: Search First\n\nBefore creating a new task, check if similar work already exists:\n\n```bash\n# Search for existing tasks\nknowns search "keyword" --type task --plain\n\n# List tasks by status\nknowns task list --status todo --plain\nknowns task list --status in-progress --plain\n```\n\n**Why?** Avoid duplicate work and understand existing context.\n\n---\n\n## Step 2: Assess Scope\n\nAsk yourself:\n- Does this work fit in one PR?\n- Does it span multiple systems?\n- Are there natural breaking points?\n\n**Single task:** Work is focused, affects one area\n**Multiple tasks:** Work spans different subsystems or has phases\n\n---\n\n## Step 3: Create with Proper Structure\n\n### Basic Task Creation\n\n```bash\nknowns task create "Clear title describing what needs to be done" \\\n  -d "Description explaining WHY this is needed" \\\n  --ac "First acceptance criterion" \\\n  --ac "Second acceptance criterion" \\\n  --priority medium \\\n  -l "label1,label2"\n```\n\n### Creating Subtasks\n\n```bash\n# Create parent task first\nknowns task create "Parent feature"\n\n# Create subtasks (use raw ID, not task-XX)\nknowns task create "Subtask 1" --parent 48\nknowns task create "Subtask 2" --parent 48\n```\n\n---\n\n## Task Quality Guidelines\n\n### Title (The "what")\n\nClear, brief summary of the task.\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description (The "why")\n\nExplains context and purpose. Include doc references.\n\n```markdown\nWe need JWT authentication because sessions don\'t scale\nfor our microservices architecture.\n\nRelated: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria (The "what" - outcomes)\n\n**Key Principles:**\n- **Outcome-oriented** - Focus on results, not implementation\n- **Testable** - Can be objectively verified\n- **User-focused** - Frame from end-user perspective\n\n| \u274C Bad (Implementation details) | \u2705 Good (Outcomes) |\n|--------------------------------|-------------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Anti-Patterns to Avoid\n\n### \u274C Don\'t create overly broad tasks\n\n```bash\n# \u274C Too broad - too many ACs\nknowns task create "Build entire auth system" \\\n  --ac "Login" --ac "Logout" --ac "Register" \\\n  --ac "Password reset" --ac "OAuth" --ac "2FA"\n\n# \u2705 Better - split into focused tasks\nknowns task create "Implement user login" --ac "User can login with email/password"\nknowns task create "Implement user registration" --ac "User can create account"\n```\n\n### \u274C Don\'t embed implementation steps in AC\n\n```bash\n# \u274C Implementation steps as AC\n--ac "Create auth.ts file"\n--ac "Add bcrypt dependency"\n--ac "Write handleLogin function"\n\n# \u2705 Outcome-focused AC\n--ac "User can login with valid credentials"\n--ac "Invalid credentials return 401 error"\n--ac "Successful login returns JWT token"\n```\n\n### \u274C Don\'t skip search\n\nAlways search for existing tasks first. You might find:\n- Duplicate task already exists\n- Related task with useful context\n- Completed task with reusable patterns\n\n---\n\n## Report Results\n\nAfter creating tasks, show the user:\n- Task ID\n- Title\n- Description summary\n- Acceptance criteria\n\nThis allows for feedback and corrections before work begins.\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/workflow-execution.md
-var workflow_execution_default = '# Task Execution Workflow\n\nGuide for implementing tasks effectively.\n\n---\n\n## Step 1: Take the Task\n\nThe **first things** you must do when taking a task:\n\n```bash\n# Set status to in-progress and assign to yourself\nknowns task edit <id> -s in-progress -a @me\n\n# Start time tracking (REQUIRED!)\nknowns time start <id>\n```\n\n---\n\n## Step 2: Research & Understand\n\nBefore planning, gather complete context:\n\n```bash\n# Read the task details\nknowns task <id> --plain\n\n# Follow ALL refs in the task\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search for related documentation\nknowns search "keyword" --type doc --plain\n\n# Check similar completed tasks for patterns\nknowns search "keyword" --type task --status done --plain\n```\n\n**Why?** Understanding existing patterns prevents reinventing the wheel.\n\n---\n\n## Step 3: Create Implementation Plan\n\nCapture your plan in the task **BEFORE writing any code**.\n\n```bash\nknowns task edit <id> --plan $\'1. Research existing patterns (see @doc/xxx)\n2. Design approach\n3. Implement core functionality\n4. Add tests\n5. Update documentation\'\n```\n\n### \u26A0\uFE0F CRITICAL: Wait for Approval\n\n**Share the plan with the user and WAIT for explicit approval before coding.**\n\nDo not begin implementation until:\n- User approves the plan, OR\n- User explicitly tells you to skip review\n\n---\n\n## Step 4: Implement\n\nWork through your plan step by step:\n\n### Document Progress\n\n```bash\n# After completing each significant piece of work\nknowns task edit <id> --append-notes "\u2713 Completed: research phase"\nknowns task edit <id> --append-notes "\u2713 Completed: core implementation"\n```\n\n### Check Acceptance Criteria\n\nOnly mark AC as done **AFTER** the work is actually complete:\n\n```bash\n# After completing work for AC #1\nknowns task edit <id> --check-ac 1\n\n# After completing work for AC #2\nknowns task edit <id> --check-ac 2\n```\n\n**\u26A0\uFE0F CRITICAL:** Never check AC before the work is done. ACs represent completed outcomes.\n\n---\n\n## Scope Management\n\n### When New Requirements Emerge\n\nIf you discover additional work needed during implementation:\n\n**Option 1: Add to current task (if small)**\n```bash\nknowns task edit <id> --ac "New requirement discovered"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X"\n```\n\n**Option 2: Create follow-up task (if significant)**\n```bash\nknowns task create "Follow-up: Additional feature" -d "Discovered during task <id>"\nknowns task edit <id> --append-notes "\u{1F4DD} Created follow-up task for X"\n```\n\n**\u26A0\uFE0F CRITICAL:** Stop and ask the user which option to use. Don\'t silently expand scope.\n\n---\n\n## Plan Updates\n\nIf your approach changes during implementation, update the plan:\n\n```bash\nknowns task edit <id> --plan $\'1. [DONE] Research\n2. [DONE] Original approach\n3. [CHANGED] New approach due to X\n4. Remaining work\'\n```\n\nThe plan should remain the **single source of truth** for how the task was solved.\n\n---\n\n## Handling Subtasks\n\n### When Assigned "Parent and All Subtasks"\n\nProceed sequentially without asking permission between each subtask:\n\n1. Complete subtask 1\n2. Complete subtask 2\n3. Continue until all done\n\n### When Assigned Single Subtask\n\nPresent progress and request guidance before advancing to the next subtask.\n\n---\n\n## Key Principles\n\n1. **Plan before code** - Always capture approach before implementation\n2. **Document decisions** - Record why you chose certain approaches\n3. **Update on changes** - Keep plan current if approach shifts\n4. **Ask on scope** - Don\'t silently expand work\n5. **Check AC after work** - Only mark done when truly complete\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# @.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';
 
 // src/templates/guidelines/common-mistakes.md
-var common_mistakes_default = '# Common Mistakes\n\nAnti-patterns and common errors to avoid.\n\n---\n\n## \u26A0\uFE0F CRITICAL: Flag Confusion\n\n### The -a Flag Means Different Things!\n\n| Command | `-a` Flag 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### \u274C WRONG: Using -a for Acceptance Criteria\n\n```bash\n# \u274C WRONG: -a is assignee, sets assignee to garbage text!\nknowns task edit 35 -a "- [ ] Criterion"\nknowns task edit 35 -a "User can login"\nknowns task create "Title" -a "Criterion text"\n```\n\n### \u2705 CORRECT: Using --ac for Acceptance Criteria\n\n```bash\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## Quick Reference: DO vs DON\'T\n\n### File Operations\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| Change `- [ ]` to `- [x]` in file | `--check-ac <index>` |\n| Add notes directly to file | `--notes` or `--append-notes` |\n| Edit frontmatter manually | Use CLI flags |\n\n### Task Operations\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| `-a "criterion"` (assignee!) | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| Skip time tracking | Always `time start`/`time stop` |\n| Check AC before work done | Check AC AFTER completing work |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read ALL related docs first |\n\n### Flag Usage\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| `--plain` with create | `--plain` only for view/list/search |\n| `--plain` with edit | `--plain` only for view/list/search |\n| `--criteria "text"` | `--ac "text"` |\n| `-ac "text"` | `--ac "text"` (two dashes!) |\n\n---\n\n## Detailed Mistakes\n\n### 1. Direct File Editing\n\n```markdown\n# \u274C DON\'T DO THIS:\n1. Open backlog/tasks/task-7.md in editor\n2. Change "- [ ]" to "- [x]" manually\n3. Add notes directly to the file\n4. Save the file\n\n# \u2705 DO THIS INSTEAD:\nknowns task edit 7 --check-ac 1\nknowns task edit 7 --notes "Implementation complete"\n```\n\n**Why?** Direct editing breaks:\n- Metadata synchronization\n- Git tracking\n- Task relationships\n\n### 2. Wrong Flag for Acceptance Criteria\n\n```bash\n# \u274C WRONG: All these set assignee, NOT acceptance criteria\nknowns task edit 35 -a "Criterion"\nknowns task create "Title" -a "AC text"\nknowns task edit 35 --assignee "Criterion"  # Still wrong!\n\n# \u2705 CORRECT: Use --ac\nknowns task edit 35 --ac "Criterion"\nknowns task create "Title" --ac "AC text"\n```\n\n### 3. Wrong Task ID Format for Parent\n\n```bash\n# \u274C WRONG: Don\'t prefix with "task-"\nknowns task create "Title" --parent task-48\nknowns task edit 35 --parent task-48\n\n# \u2705 CORRECT: Use raw ID only\nknowns task create "Title" --parent 48\nknowns task edit 35 --parent qkh5ne\n```\n\n### 4. Using --plain with Create/Edit\n\n```bash\n# \u274C WRONG: create/edit don\'t support --plain\nknowns task create "Title" --plain       # ERROR!\nknowns task edit 35 -s done --plain      # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n\n# \u2705 CORRECT: --plain only for view/list/search\nknowns task 35 --plain                   # OK\nknowns task list --plain                 # OK\nknowns doc "readme" --plain              # OK\nknowns search "query" --plain            # OK\n```\n\n### 5. Skipping Time Tracking\n\n```bash\n# \u274C WRONG: No timer\nknowns task edit 35 -s in-progress\n# ... work ...\nknowns task edit 35 -s done\n\n# \u2705 CORRECT: Always track time\nknowns task edit 35 -s in-progress -a @me\nknowns time start 35\n# ... work ...\nknowns time stop\nknowns task edit 35 -s done\n```\n\n### 6. Checking AC Before Work is Done\n\n```bash\n# \u274C WRONG: Checking AC as a TODO list\nknowns task edit 35 --check-ac 1  # Haven\'t done the work yet!\n# ... then do the work ...\n\n# \u2705 CORRECT: Check AC AFTER completing work\n# ... do the work first ...\nknowns task edit 35 --check-ac 1  # Now it\'s actually done\n```\n\n### 7. Coding Before Plan Approval\n\n```bash\n# \u274C WRONG: Start coding immediately\nknowns task edit 35 -s in-progress\nknowns task edit 35 --plan "1. Do X\\n2. Do Y"\n# Immediately starts coding...\n\n# \u2705 CORRECT: Wait for approval\nknowns task edit 35 -s in-progress\nknowns task edit 35 --plan "1. Do X\\n2. Do Y"\n# STOP! Present plan to user\n# Wait for explicit approval\n# Then start coding\n```\n\n### 8. Ignoring Task References\n\n```bash\n# \u274C WRONG: Don\'t read refs\nknowns task 35 --plain\n# See "@.knowns/docs/api.md" but don\'t read it\n# Start implementing without context...\n\n# \u2705 CORRECT: Follow ALL refs\nknowns task 35 --plain\n# See "@.knowns/docs/api.md"\nknowns doc "api" --plain  # Read it!\n# See "@.knowns/tasks/task-30"\nknowns task 30 --plain    # Read it!\n# Now have full context\n```\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text by mistake | `knowns task edit <id> -a @me` to fix |\n| Forgot to stop timer | `knowns time add <id> <duration> -n "Forgot to stop"` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac <index>` |\n| Task not found | `knowns task list --plain` to find correct ID |\n| AC index out of range | `knowns task <id> --plain` to see AC numbers |\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 `@.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';
+
+// src/templates/guidelines/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## 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. **Write concise** - Compact notes, not essays\n5. **Don\'t repeat** - Reference context already loaded\n6. **Summarize** - Key points, not full quotes\n';
 
 // src/templates/guidelines/index.ts
 var CORE_RULES = core_rules_default.trim();
@@ -43500,6 +43503,7 @@ var WORKFLOW_CREATION = workflow_creation_default.trim();
 var WORKFLOW_EXECUTION = workflow_execution_default.trim();
 var WORKFLOW_COMPLETION = workflow_completion_default.trim();
 var COMMON_MISTAKES = common_mistakes_default.trim();
+var CONTEXT_OPTIMIZATION = context_optimization_default.trim();
 var Guidelines = {
   // Core rules - always needed
   core: CORE_RULES,
@@ -43513,6 +43517,8 @@ var Guidelines = {
   },
   // Common mistakes
   mistakes: COMMON_MISTAKES,
+  // Context optimization
+  contextOptimization: CONTEXT_OPTIMIZATION,
   /**
    * Get full guidelines (all sections combined)
    */
@@ -43520,6 +43526,8 @@ var Guidelines = {
     const content = [
       CORE_RULES,
       "---",
+      CONTEXT_OPTIMIZATION,
+      "---",
       COMMANDS_REFERENCE,
       "---",
       WORKFLOW_CREATION,
@@ -43538,16 +43546,16 @@ ${content}
     return content;
   },
   /**
-   * Get compact guidelines (core + mistakes only)
+   * Get compact guidelines (core + context optimization + mistakes only)
    */
   getCompact() {
-    return [CORE_RULES, "---", COMMON_MISTAKES].join("\n\n");
+    return [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---", COMMON_MISTAKES].join("\n\n");
   },
   /**
    * Get guidelines for specific workflow stage
    */
   getForStage(stage) {
-    const sections = [CORE_RULES, "---"];
+    const sections = [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---"];
     switch (stage) {
       case "creation":
         sections.push(WORKFLOW_CREATION);
@@ -43592,11 +43600,11 @@ var INSTRUCTION_FILES = [
   { path: "GEMINI.md", name: "Gemini", selected: false },
   { path: ".github/copilot-instructions.md", name: "GitHub Copilot", selected: false }
 ];
-function getGuidelines(type, variant = "instruction") {
-  if (variant === "general") {
-    return Guidelines.getFull(true);
+function getGuidelines(type, variant = "general") {
+  if (variant === "instruction") {
+    return type === "mcp" ? MCP_INSTRUCTION : CLI_INSTRUCTION;
   }
-  return type === "mcp" ? MCP_INSTRUCTION : CLI_INSTRUCTION;
+  return Guidelines.getFull(true);
 }
 async function updateInstructionFile(filePath, guidelines) {
   const fullPath = join3(PROJECT_ROOT, filePath);
@@ -43676,14 +43684,14 @@ Updating agent instruction files (${label2})...
       message: "Select variant:",
       choices: [
         {
-          title: "Minimal (Recommended)",
-          value: "instruction",
-          description: "Just tells AI to call `knowns agents guideline` for rules"
-        },
-        {
-          title: "Full (Embedded)",
+          title: "Full (Recommended)",
           value: "general",
           description: "Complete guidelines embedded in file"
+        },
+        {
+          title: "Minimal",
+          value: "instruction",
+          description: "Just tells AI to call `knowns agents guideline` for rules"
         }
       ],
       initial: 0
@@ -43775,10 +43783,10 @@ 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("--full", "Use full embedded guidelines (default: minimal instruction)").option("--all", "Update all instruction files (including Gemini, Copilot)").action(async (options2) => {
+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.full ? "general" : "instruction";
+    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)";
@@ -43849,8 +43857,41 @@ function checkGitExists(projectRoot) {
     process.exit(1);
   }
 }
+async function createMcpJsonFile(projectRoot) {
+  const { writeFileSync: writeFileSync3, readFileSync: readFileSync4 } = await import("node:fs");
+  const mcpJsonPath = join4(projectRoot, ".mcp.json");
+  const mcpConfig = {
+    mcpServers: {
+      knowns: {
+        command: "npx",
+        args: ["-y", "knowns", "mcp"]
+      }
+    }
+  };
+  if (existsSync2(mcpJsonPath)) {
+    try {
+      const existing = JSON.parse(readFileSync4(mcpJsonPath, "utf-8"));
+      if (existing?.mcpServers?.knowns) {
+        console.log(source_default.gray("  .mcp.json already has knowns configuration"));
+        return;
+      }
+      existing.mcpServers = {
+        ...existing.mcpServers,
+        ...mcpConfig.mcpServers
+      };
+      writeFileSync3(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");
+      console.log(source_default.green("\u2713 Created .mcp.json (replaced invalid file)"));
+    }
+  } else {
+    writeFileSync3(mcpJsonPath, JSON.stringify(mcpConfig, null, "	"), "utf-8");
+    console.log(source_default.green("\u2713 Created .mcp.json for Claude Code MCP auto-discovery"));
+  }
+}
 async function updateGitignoreForIgnoredMode(projectRoot) {
-  const { appendFileSync, readFileSync: readFileSync3, writeFileSync: writeFileSync2 } = await import("node:fs");
+  const { appendFileSync, readFileSync: readFileSync4, writeFileSync: writeFileSync3 } = await import("node:fs");
   const gitignorePath = join4(projectRoot, ".gitignore");
   const knownsIgnorePattern = `
 # knowns (ignore all except docs)
@@ -43859,7 +43900,7 @@ async function updateGitignoreForIgnoredMode(projectRoot) {
 !.knowns/docs/**
 `;
   if (existsSync2(gitignorePath)) {
-    const content = readFileSync3(gitignorePath, "utf-8");
+    const content = readFileSync4(gitignorePath, "utf-8");
     if (content.includes(".knowns/*")) {
       console.log(source_default.gray("  .gitignore already has knowns pattern"));
       return;
@@ -43867,7 +43908,7 @@ async function updateGitignoreForIgnoredMode(projectRoot) {
     appendFileSync(gitignorePath, knownsIgnorePattern);
     console.log(source_default.green("\u2713 Updated .gitignore with knowns pattern"));
   } else {
-    writeFileSync2(gitignorePath, `${knownsIgnorePattern.trim()}
+    writeFileSync3(gitignorePath, `${knownsIgnorePattern.trim()}
 `, "utf-8");
     console.log(source_default.green("\u2713 Created .gitignore with knowns pattern"));
   }
@@ -43907,43 +43948,6 @@ async function runWizard() {
         initial: 0
         // git-tracked
       },
-      {
-        type: "text",
-        name: "defaultAssignee",
-        message: "Default assignee (optional)",
-        initial: "",
-        format: (value) => value.trim() ? value.trim() : void 0
-      },
-      {
-        type: "select",
-        name: "defaultPriority",
-        message: "Default priority for new tasks",
-        choices: [
-          { title: "Low", value: "low" },
-          { title: "Medium", value: "medium" },
-          { title: "High", value: "high" }
-        ],
-        initial: 1
-        // medium
-      },
-      {
-        type: "list",
-        name: "defaultLabels",
-        message: "Default labels (comma-separated, optional)",
-        initial: "",
-        separator: ","
-      },
-      {
-        type: "select",
-        name: "timeFormat",
-        message: "Time format",
-        choices: [
-          { title: "24-hour (14:30)", value: "24h" },
-          { title: "12-hour (2:30 PM)", value: "12h" }
-        ],
-        initial: 0
-        // 24h
-      },
       {
         type: "select",
         name: "guidelinesType",
@@ -43980,10 +43984,9 @@ async function runWizard() {
   }
   return {
     name: response.name,
-    defaultAssignee: response.defaultAssignee,
-    defaultPriority: response.defaultPriority,
-    defaultLabels: response.defaultLabels?.filter((l) => l.trim()) || [],
-    timeFormat: response.timeFormat,
+    defaultPriority: "medium",
+    defaultLabels: [],
+    timeFormat: "24h",
     gitTrackingMode: response.gitTrackingMode || "git-tracked",
     guidelinesType: response.guidelinesType || "cli",
     agentFiles: response.agentFiles || []
@@ -44026,57 +44029,35 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
     if (config2.gitTrackingMode === "git-ignored") {
       await updateGitignoreForIgnoredMode(projectRoot);
     }
+    if (config2.guidelinesType === "mcp") {
+      await createMcpJsonFile(projectRoot);
+    }
     const fileStore2 = new FileStore(projectRoot);
     const project = await fileStore2.initProject(config2.name, {
-      defaultAssignee: config2.defaultAssignee,
       defaultPriority: config2.defaultPriority,
       defaultLabels: config2.defaultLabels,
       timeFormat: config2.timeFormat,
       gitTrackingMode: config2.gitTrackingMode
     });
     console.log();
-    console.log(source_default.green("\u2713 Project initialized successfully!"));
-    console.log(source_default.gray(`  Name: ${project.name}`));
-    console.log(source_default.gray(`  Location: ${knownsPath}`));
-    console.log(
-      source_default.gray(`  Git Mode: ${config2.gitTrackingMode === "git-tracked" ? "Tracked (team)" : "Ignored (personal)"}`)
-    );
-    if (config2.defaultAssignee) {
-      console.log(source_default.gray(`  Default Assignee: ${config2.defaultAssignee}`));
-    }
-    console.log(source_default.gray(`  Default Priority: ${config2.defaultPriority}`));
-    if (config2.defaultLabels.length > 0) {
-      console.log(source_default.gray(`  Default Labels: ${config2.defaultLabels.join(", ")}`));
-    }
-    console.log(source_default.gray(`  Time Format: ${config2.timeFormat}`));
-    console.log();
+    console.log(source_default.green(`\u2713 Project initialized: ${project.name}`));
     if (config2.agentFiles.length > 0) {
       const guidelines = getGuidelines(config2.guidelinesType);
-      console.log(source_default.bold(`Updating AI instruction files (${config2.guidelinesType.toUpperCase()} version)...`));
-      console.log();
-      let syncedCount = 0;
       for (const file3 of config2.agentFiles) {
         try {
           const result = await updateInstructionFile(file3.path, guidelines);
           if (result.success) {
-            syncedCount++;
             const action = result.action === "created" ? "Created" : result.action === "appended" ? "Appended" : "Updated";
-            console.log(source_default.green(`\u2713 ${action} ${file3.name}: ${file3.path}`));
+            console.log(source_default.green(`\u2713 ${action}: ${file3.path}`));
           }
-        } catch (error48) {
-          console.log(source_default.yellow(`\u26A0\uFE0F  Skipped ${file3.name}: ${file3.path}`));
+        } catch {
+          console.log(source_default.yellow(`\u26A0\uFE0F  Skipped: ${file3.path}`));
         }
       }
-      console.log();
-      console.log(source_default.green(`\u2713 Synced guidelines to ${syncedCount} AI instruction file(s)`));
-    } else {
-      console.log(source_default.gray("Skipped AI instruction files (none selected)"));
     }
     console.log();
-    console.log(source_default.cyan("Next steps:"));
-    console.log(source_default.gray('  1. Create a task: knowns task create "My first task"'));
-    console.log(source_default.gray("  2. List tasks: knowns task list"));
-    console.log(source_default.gray("  3. Open web UI: knowns browser"));
+    console.log(source_default.cyan("Get started:"));
+    console.log(source_default.gray('  knowns task create "My first task"'));
   } catch (error48) {
     console.error(source_default.red("\u2717 Failed to initialize project"));
     if (error48 instanceof Error) {
@@ -62531,6 +62512,10 @@ 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/mcp.ts
+import { existsSync as existsSync18, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { join as join22 } from "node:path";
+
 // src/mcp/server.ts
 import { existsSync as existsSync17 } from "node:fs";
 import { readFile as readFile15 } from "node:fs/promises";
@@ -70761,6 +70746,89 @@ if (isStandaloneServer) {
 }
 
 // src/commands/mcp.ts
+function getMcpConfig() {
+  return {
+    command: "npx",
+    args: ["-y", "knowns", "mcp"]
+  };
+}
+async function setupClaudeCode() {
+  const { spawnSync } = await import("node:child_process");
+  const claudeCheck = spawnSync("claude", ["--version"], { stdio: "pipe" });
+  if (claudeCheck.status !== 0) {
+    console.log(source_default.yellow("\u26A0\uFE0F  Claude Code CLI not found"));
+    console.log(source_default.gray("  Install Claude Code first: https://claude.ai/code"));
+    console.log(source_default.gray("  After installing, run: knowns mcp setup"));
+    return false;
+  }
+  const config2 = getMcpConfig();
+  const configJson = JSON.stringify(config2);
+  const result = spawnSync("claude", ["mcp", "add-json", "knowns", configJson], {
+    stdio: "inherit"
+  });
+  if (result.status === 0) {
+    console.log(source_default.green("\u2713 Added knowns MCP server to Claude Code"));
+    console.log(source_default.gray("  Restart Claude Code to activate the server"));
+    return true;
+  }
+  const altResult = spawnSync("claude", ["mcp", "add", "knowns", "--", "npx", "-y", "knowns", "mcp"], {
+    stdio: "inherit"
+  });
+  if (altResult.status === 0) {
+    console.log(source_default.green("\u2713 Added knowns MCP server to Claude Code"));
+    console.log(source_default.gray("  Restart Claude Code to activate the server"));
+    return true;
+  }
+  console.log(source_default.red("\u2717 Failed to add MCP server to Claude Code"));
+  console.log(source_default.gray("  Try adding manually with:"));
+  console.log(source_default.cyan(`    claude mcp add-json knowns '${configJson}'`));
+  return false;
+}
+function createProjectMcpJson(projectRoot) {
+  const mcpJsonPath = join22(projectRoot, ".mcp.json");
+  const mcpConfig = {
+    mcpServers: {
+      knowns: getMcpConfig()
+    }
+  };
+  if (existsSync18(mcpJsonPath)) {
+    try {
+      const existing = JSON.parse(readFileSync2(mcpJsonPath, "utf-8"));
+      if (existing?.mcpServers?.knowns) {
+        console.log(source_default.gray("  .mcp.json already has knowns configuration"));
+        return true;
+      }
+      existing.mcpServers = {
+        ...existing.mcpServers,
+        ...mcpConfig.mcpServers
+      };
+      writeFileSync(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");
+      console.log(source_default.green("\u2713 Created .mcp.json (replaced invalid file)"));
+    }
+  } else {
+    writeFileSync(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;
+}
+var setupCommand = new Command("setup").description("Setup knowns MCP server in Claude Code").option("--project", "Only create .mcp.json in project (skip Claude Code setup)").option("--global", "Only setup in Claude Code globally (skip .mcp.json)").action(async (options2) => {
+  const projectRoot = findProjectRoot();
+  const doProject = options2.project || !options2.project && !options2.global;
+  const doGlobal = options2.global || !options2.project && !options2.global;
+  if (doProject) {
+    if (projectRoot) {
+      createProjectMcpJson(projectRoot);
+    } else {
+      console.log(source_default.yellow("\u26A0\uFE0F  Not in a Knowns project. Run 'knowns init' first."));
+    }
+  }
+  if (doGlobal) {
+    await setupClaudeCode();
+  }
+});
 var mcpCommand = new Command("mcp").description("Start MCP server for AI agent integration (Claude Desktop, etc.)").option("-v, --verbose", "Enable verbose logging").option("--info", "Show configuration instructions").action(async (options2) => {
   if (options2.info) {
     showConfigInfo();
@@ -70779,7 +70847,7 @@ var mcpCommand = new Command("mcp").description("Start MCP server for AI agent i
     console.error(source_default.red("Error:"), error48 instanceof Error ? error48.message : error48);
     process.exit(1);
   }
-});
+}).addCommand(setupCommand);
 function showConfigInfo() {
   const configExample = {
     mcpServers: {
@@ -70823,10 +70891,10 @@ function showConfigInfo() {
 }
 
 // src/utils/update-notifier.ts
-import { existsSync as existsSync18, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { existsSync as existsSync19, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { mkdir as mkdir10 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname as dirname4, join as join22 } from "node:path";
+import { dirname as dirname4, join as join23 } from "node:path";
 var DEFAULT_TTL_MS = 60 * 60 * 1e3;
 var DEFAULT_TIMEOUT_MS = 2e3;
 function detectPackageManager(cwd) {
@@ -70839,10 +70907,10 @@ function detectPackageManager(cwd) {
   if (ua.startsWith("yarn/")) return "yarn";
   if (ua.startsWith("bun/")) return "bun";
   if (ua.startsWith("npm/")) return "npm";
-  if (existsSync18(join22(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync18(join22(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync18(join22(cwd, "bun.lock"))) return "bun";
-  if (existsSync18(join22(cwd, "package-lock.json"))) 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";
   return "npm";
 }
 function compareVersions(a, b) {
@@ -70866,11 +70934,11 @@ function shouldSkip(args2, force) {
 }
 function getGlobalCachePath(explicit) {
   if (explicit) return explicit;
-  return join22(homedir(), ".knowns", "cli-cache.json");
+  return join23(homedir(), ".knowns", "cli-cache.json");
 }
 function readCache(cachePath) {
   try {
-    const raw = readFileSync2(cachePath, "utf-8");
+    const raw = readFileSync3(cachePath, "utf-8");
     const data = JSON.parse(raw);
     if (typeof data.lastChecked === "number" && typeof data.latestVersion === "string") {
       return data;
@@ -70882,10 +70950,10 @@ function readCache(cachePath) {
 }
 async function writeCache(cachePath, data) {
   const dir = dirname4(cachePath);
-  if (dir && !existsSync18(dir)) {
+  if (dir && !existsSync19(dir)) {
     await mkdir10(dir, { recursive: true });
   }
-  writeFileSync(cachePath, JSON.stringify(data, null, 2), "utf-8");
+  writeFileSync2(cachePath, JSON.stringify(data, null, 2), "utf-8");
 }
 async function fetchLatestVersion(packageName) {
   try {
@@ -70948,7 +71016,7 @@ async function notifyCliUpdate(options2) {
 // package.json
 var package_default = {
   name: "knowns",
-  version: "0.8.3",
+  version: "0.8.5",
   description: "AI-native task and documentation management for dev teams",
   module: "index.ts",
   type: "module",