knowns 0.8.7 → 0.8.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js
CHANGED
|
@@ -43476,13 +43476,13 @@ import { dirname, join as join3 } from "node:path";
|
|
|
43476
43476
|
var import_prompts = __toESM(require_prompts3(), 1);
|
|
43477
43477
|
|
|
43478
43478
|
// src/templates/guidelines/cli/commands-reference.md
|
|
43479
|
-
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#
|
|
43479
|
+
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';
|
|
43480
43480
|
|
|
43481
43481
|
// src/templates/guidelines/cli/common-mistakes.md
|
|
43482
43482
|
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';
|
|
43483
43483
|
|
|
43484
43484
|
// src/templates/guidelines/cli/context-optimization.md
|
|
43485
|
-
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##
|
|
43485
|
+
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';
|
|
43486
43486
|
|
|
43487
43487
|
// src/templates/guidelines/cli/core-rules.md
|
|
43488
43488
|
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';
|
|
@@ -43574,13 +43574,13 @@ ${content}
|
|
|
43574
43574
|
};
|
|
43575
43575
|
|
|
43576
43576
|
// src/templates/guidelines/mcp/commands-reference.md
|
|
43577
|
-
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###
|
|
43577
|
+
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';
|
|
43578
43578
|
|
|
43579
43579
|
// src/templates/guidelines/mcp/common-mistakes.md
|
|
43580
43580
|
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";
|
|
43581
43581
|
|
|
43582
43582
|
// src/templates/guidelines/mcp/context-optimization.md
|
|
43583
|
-
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##
|
|
43583
|
+
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';
|
|
43584
43584
|
|
|
43585
43585
|
// src/templates/guidelines/mcp/core-rules.md
|
|
43586
43586
|
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";
|
|
@@ -47934,6 +47934,13 @@ function extractSection(markdown, sectionTitle) {
|
|
|
47934
47934
|
}
|
|
47935
47935
|
return lines.slice(startLine, endLine).join("\n").trim();
|
|
47936
47936
|
}
|
|
47937
|
+
function extractSectionByIndex(markdown, index) {
|
|
47938
|
+
const toc = extractToc(markdown);
|
|
47939
|
+
if (index < 1 || index > toc.length) {
|
|
47940
|
+
return null;
|
|
47941
|
+
}
|
|
47942
|
+
return extractSection(markdown, toc[index - 1].title);
|
|
47943
|
+
}
|
|
47937
47944
|
function replaceSection(markdown, sectionTitle, newContent) {
|
|
47938
47945
|
const lines = markdown.split("\n");
|
|
47939
47946
|
const normalizedTarget = normalizeTitle(sectionTitle);
|
|
@@ -48147,11 +48154,13 @@ var listCommand2 = new Command("list").description("List all documentation files
|
|
|
48147
48154
|
}
|
|
48148
48155
|
const docs = [];
|
|
48149
48156
|
for (const file3 of mdFiles) {
|
|
48150
|
-
const
|
|
48151
|
-
const { data } = (0, import_gray_matter6.default)(
|
|
48157
|
+
const fileContent = await readFile11(join17(DOCS_DIR, file3), "utf-8");
|
|
48158
|
+
const { data, content } = (0, import_gray_matter6.default)(fileContent);
|
|
48159
|
+
const stats = calculateDocStats(content);
|
|
48152
48160
|
docs.push({
|
|
48153
48161
|
filename: file3,
|
|
48154
|
-
metadata: data
|
|
48162
|
+
metadata: data,
|
|
48163
|
+
tokens: stats.estimatedTokens
|
|
48155
48164
|
});
|
|
48156
48165
|
}
|
|
48157
48166
|
let filteredDocs = docs;
|
|
@@ -48177,7 +48186,8 @@ var listCommand2 = new Command("list").description("List all documentation files
|
|
|
48177
48186
|
if (parts.length === 1) {
|
|
48178
48187
|
rootDocs.push({
|
|
48179
48188
|
name: parts[0].replace(/\.md$/, ""),
|
|
48180
|
-
title: doc.metadata.title
|
|
48189
|
+
title: doc.metadata.title,
|
|
48190
|
+
tokens: doc.tokens
|
|
48181
48191
|
});
|
|
48182
48192
|
} else {
|
|
48183
48193
|
const folder = parts.slice(0, -1).join("/");
|
|
@@ -48185,7 +48195,7 @@ var listCommand2 = new Command("list").description("List all documentation files
|
|
|
48185
48195
|
if (!folders.has(folder)) {
|
|
48186
48196
|
folders.set(folder, []);
|
|
48187
48197
|
}
|
|
48188
|
-
folders.get(folder)?.push({ name, title: doc.metadata.title });
|
|
48198
|
+
folders.get(folder)?.push({ name, title: doc.metadata.title, tokens: doc.tokens });
|
|
48189
48199
|
}
|
|
48190
48200
|
}
|
|
48191
48201
|
const sortedFolders = Array.from(folders.keys()).sort();
|
|
@@ -48193,13 +48203,13 @@ var listCommand2 = new Command("list").description("List all documentation files
|
|
|
48193
48203
|
console.log(`${folder}/`);
|
|
48194
48204
|
const docs2 = folders.get(folder)?.sort((a, b) => a.name.localeCompare(b.name));
|
|
48195
48205
|
for (const doc of docs2) {
|
|
48196
|
-
console.log(` ${doc.name} - ${doc.title}`);
|
|
48206
|
+
console.log(` ${doc.name} - ${doc.title} (~${doc.tokens} tokens)`);
|
|
48197
48207
|
}
|
|
48198
48208
|
}
|
|
48199
48209
|
if (rootDocs.length > 0) {
|
|
48200
48210
|
rootDocs.sort((a, b) => a.name.localeCompare(b.name));
|
|
48201
48211
|
for (const doc of rootDocs) {
|
|
48202
|
-
console.log(`${doc.name} - ${doc.title}`);
|
|
48212
|
+
console.log(`${doc.name} - ${doc.title} (~${doc.tokens} tokens)`);
|
|
48203
48213
|
}
|
|
48204
48214
|
}
|
|
48205
48215
|
} else {
|
|
@@ -48254,7 +48264,7 @@ Documentation (${filteredDocs.length})
|
|
|
48254
48264
|
process.exit(1);
|
|
48255
48265
|
}
|
|
48256
48266
|
});
|
|
48257
|
-
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(
|
|
48267
|
+
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(
|
|
48258
48268
|
async (name, options2) => {
|
|
48259
48269
|
try {
|
|
48260
48270
|
await ensureDocsDir();
|
|
@@ -48284,6 +48294,45 @@ var viewCommand2 = new Command("view").description("View a documentation file").
|
|
|
48284
48294
|
const fileContent = await readFile11(filepath, "utf-8");
|
|
48285
48295
|
const { data, content } = (0, import_gray_matter6.default)(fileContent);
|
|
48286
48296
|
const metadata = data;
|
|
48297
|
+
if (options2.smart) {
|
|
48298
|
+
const stats = calculateDocStats(content);
|
|
48299
|
+
const SMART_THRESHOLD = 2e3;
|
|
48300
|
+
if (stats.estimatedTokens <= SMART_THRESHOLD) {
|
|
48301
|
+
} else {
|
|
48302
|
+
const toc = extractToc(content);
|
|
48303
|
+
if (options2.plain) {
|
|
48304
|
+
console.log(`Document: ${metadata.title}`);
|
|
48305
|
+
console.log("=".repeat(50));
|
|
48306
|
+
console.log();
|
|
48307
|
+
console.log(
|
|
48308
|
+
`Size: ${stats.chars.toLocaleString()} chars (~${stats.estimatedTokens.toLocaleString()} tokens)`
|
|
48309
|
+
);
|
|
48310
|
+
console.log(`Headings: ${stats.headingCount}`);
|
|
48311
|
+
console.log();
|
|
48312
|
+
console.log("Table of Contents:");
|
|
48313
|
+
console.log("-".repeat(50));
|
|
48314
|
+
toc.forEach((entry, index) => {
|
|
48315
|
+
const indent = " ".repeat(entry.level - 1);
|
|
48316
|
+
console.log(`${indent}${index + 1}. ${entry.title}`);
|
|
48317
|
+
});
|
|
48318
|
+
console.log();
|
|
48319
|
+
console.log("Document is large. Use --section <number> to read a specific section.");
|
|
48320
|
+
} else {
|
|
48321
|
+
console.log(source_default.bold(`
|
|
48322
|
+
\u{1F4C4} ${metadata.title} (Smart Mode)
|
|
48323
|
+
`));
|
|
48324
|
+
console.log(
|
|
48325
|
+
`Size: ${source_default.cyan(stats.chars.toLocaleString())} chars (~${source_default.yellow(stats.estimatedTokens.toLocaleString())} tokens)`
|
|
48326
|
+
);
|
|
48327
|
+
console.log();
|
|
48328
|
+
console.log(source_default.bold("Table of Contents:"));
|
|
48329
|
+
console.log(formatToc(toc));
|
|
48330
|
+
console.log();
|
|
48331
|
+
console.log(source_default.yellow("\u26A0 Document is large. Use --section <number> to read a specific section."));
|
|
48332
|
+
}
|
|
48333
|
+
return;
|
|
48334
|
+
}
|
|
48335
|
+
}
|
|
48287
48336
|
if (options2.info) {
|
|
48288
48337
|
const stats = calculateDocStats(content);
|
|
48289
48338
|
if (options2.plain) {
|
|
@@ -48336,7 +48385,8 @@ var viewCommand2 = new Command("view").description("View a documentation file").
|
|
|
48336
48385
|
return;
|
|
48337
48386
|
}
|
|
48338
48387
|
if (options2.section) {
|
|
48339
|
-
const
|
|
48388
|
+
const sectionIndex = /^\d+$/.test(options2.section) ? Number.parseInt(options2.section, 10) : null;
|
|
48389
|
+
const sectionContent = sectionIndex !== null ? extractSectionByIndex(content, sectionIndex) : extractSection(content, options2.section);
|
|
48340
48390
|
if (!sectionContent) {
|
|
48341
48391
|
console.error(
|
|
48342
48392
|
options2.plain ? `Section not found: ${options2.section}` : source_default.red(`\u2717 Section not found: ${options2.section}`)
|
|
@@ -48825,7 +48875,7 @@ ${afterSection.trimStart()}`;
|
|
|
48825
48875
|
process.exit(1);
|
|
48826
48876
|
}
|
|
48827
48877
|
});
|
|
48828
|
-
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(
|
|
48878
|
+
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(
|
|
48829
48879
|
async (name, options2) => {
|
|
48830
48880
|
if (!name) {
|
|
48831
48881
|
docCommand.help();
|
|
@@ -48841,6 +48891,45 @@ var docCommand = new Command("doc").description("Manage documentation").argument
|
|
|
48841
48891
|
const fileContent = await readFile11(filepath, "utf-8");
|
|
48842
48892
|
const { data, content } = (0, import_gray_matter6.default)(fileContent);
|
|
48843
48893
|
const metadata = data;
|
|
48894
|
+
if (options2.smart) {
|
|
48895
|
+
const stats = calculateDocStats(content);
|
|
48896
|
+
const SMART_THRESHOLD = 2e3;
|
|
48897
|
+
if (stats.estimatedTokens <= SMART_THRESHOLD) {
|
|
48898
|
+
} else {
|
|
48899
|
+
const toc = extractToc(content);
|
|
48900
|
+
if (options2.plain) {
|
|
48901
|
+
console.log(`Document: ${metadata.title}`);
|
|
48902
|
+
console.log("=".repeat(50));
|
|
48903
|
+
console.log();
|
|
48904
|
+
console.log(
|
|
48905
|
+
`Size: ${stats.chars.toLocaleString()} chars (~${stats.estimatedTokens.toLocaleString()} tokens)`
|
|
48906
|
+
);
|
|
48907
|
+
console.log(`Headings: ${stats.headingCount}`);
|
|
48908
|
+
console.log();
|
|
48909
|
+
console.log("Table of Contents:");
|
|
48910
|
+
console.log("-".repeat(50));
|
|
48911
|
+
toc.forEach((entry, index) => {
|
|
48912
|
+
const indent = " ".repeat(entry.level - 1);
|
|
48913
|
+
console.log(`${indent}${index + 1}. ${entry.title}`);
|
|
48914
|
+
});
|
|
48915
|
+
console.log();
|
|
48916
|
+
console.log("Document is large. Use --section <number> to read a specific section.");
|
|
48917
|
+
} else {
|
|
48918
|
+
console.log(source_default.bold(`
|
|
48919
|
+
\u{1F4C4} ${metadata.title} (Smart Mode)
|
|
48920
|
+
`));
|
|
48921
|
+
console.log(
|
|
48922
|
+
`Size: ${source_default.cyan(stats.chars.toLocaleString())} chars (~${source_default.yellow(stats.estimatedTokens.toLocaleString())} tokens)`
|
|
48923
|
+
);
|
|
48924
|
+
console.log();
|
|
48925
|
+
console.log(source_default.bold("Table of Contents:"));
|
|
48926
|
+
console.log(formatToc(toc));
|
|
48927
|
+
console.log();
|
|
48928
|
+
console.log(source_default.yellow("\u26A0 Document is large. Use --section <number> to read a specific section."));
|
|
48929
|
+
}
|
|
48930
|
+
return;
|
|
48931
|
+
}
|
|
48932
|
+
}
|
|
48844
48933
|
if (options2.info) {
|
|
48845
48934
|
const stats = calculateDocStats(content);
|
|
48846
48935
|
if (options2.plain) {
|
|
@@ -48893,7 +48982,8 @@ var docCommand = new Command("doc").description("Manage documentation").argument
|
|
|
48893
48982
|
return;
|
|
48894
48983
|
}
|
|
48895
48984
|
if (options2.section) {
|
|
48896
|
-
const
|
|
48985
|
+
const sectionIndex = /^\d+$/.test(options2.section) ? Number.parseInt(options2.section, 10) : null;
|
|
48986
|
+
const sectionContent = sectionIndex !== null ? extractSectionByIndex(content, sectionIndex) : extractSection(content, options2.section);
|
|
48897
48987
|
if (!sectionContent) {
|
|
48898
48988
|
console.error(
|
|
48899
48989
|
options2.plain ? `Section not found: ${options2.section}` : source_default.red(`\u2717 Section not found: ${options2.section}`)
|
|
@@ -70677,8 +70767,10 @@ var getDocSchema = external_exports.object({
|
|
|
70677
70767
|
// Return document stats (size, tokens, headings) without content
|
|
70678
70768
|
toc: external_exports.boolean().optional(),
|
|
70679
70769
|
// Return table of contents only
|
|
70680
|
-
section: external_exports.string().optional()
|
|
70770
|
+
section: external_exports.string().optional(),
|
|
70681
70771
|
// Return specific section by heading title or number
|
|
70772
|
+
smart: external_exports.boolean().optional()
|
|
70773
|
+
// Smart mode: auto-return full content if small, or stats+TOC if large
|
|
70682
70774
|
});
|
|
70683
70775
|
var createDocSchema = external_exports.object({
|
|
70684
70776
|
title: external_exports.string(),
|
|
@@ -70717,7 +70809,7 @@ var docTools = [
|
|
|
70717
70809
|
},
|
|
70718
70810
|
{
|
|
70719
70811
|
name: "get_doc",
|
|
70720
|
-
description: "Get a documentation file by path. Use '
|
|
70812
|
+
description: "Get a documentation file by path. Use 'smart: true' for auto-optimized reading (recommended for AI), or 'info/toc/section' for manual control.",
|
|
70721
70813
|
inputSchema: {
|
|
70722
70814
|
type: "object",
|
|
70723
70815
|
properties: {
|
|
@@ -70725,6 +70817,10 @@ var docTools = [
|
|
|
70725
70817
|
type: "string",
|
|
70726
70818
|
description: "Document path (e.g., 'readme', 'guides/setup', 'conventions/naming.md')"
|
|
70727
70819
|
},
|
|
70820
|
+
smart: {
|
|
70821
|
+
type: "boolean",
|
|
70822
|
+
description: "Smart mode (recommended): auto-return full content if small (\u22642000 tokens), or stats+TOC if large. Use this by default."
|
|
70823
|
+
},
|
|
70728
70824
|
info: {
|
|
70729
70825
|
type: "boolean",
|
|
70730
70826
|
description: "Return document stats (size, tokens, headings) without content. Use this first to decide how to read."
|
|
@@ -70875,9 +70971,10 @@ async function handleListDocs(args2) {
|
|
|
70875
70971
|
}
|
|
70876
70972
|
const docs = [];
|
|
70877
70973
|
for (const file3 of mdFiles) {
|
|
70878
|
-
const
|
|
70879
|
-
const { data } = (0, import_gray_matter8.default)(
|
|
70974
|
+
const fileContent = await readFile14(join20(DOCS_DIR2, file3), "utf-8");
|
|
70975
|
+
const { data, content } = (0, import_gray_matter8.default)(fileContent);
|
|
70880
70976
|
const metadata = data;
|
|
70977
|
+
const stats = calculateDocStats(content);
|
|
70881
70978
|
if (input.tag && !metadata.tags?.includes(input.tag)) {
|
|
70882
70979
|
continue;
|
|
70883
70980
|
}
|
|
@@ -70886,6 +70983,7 @@ async function handleListDocs(args2) {
|
|
|
70886
70983
|
title: metadata.title || file3.replace(/\.md$/, ""),
|
|
70887
70984
|
description: metadata.description,
|
|
70888
70985
|
tags: metadata.tags,
|
|
70986
|
+
tokens: stats.estimatedTokens,
|
|
70889
70987
|
updatedAt: metadata.updatedAt
|
|
70890
70988
|
});
|
|
70891
70989
|
}
|
|
@@ -70903,6 +71001,33 @@ async function handleGetDoc(args2) {
|
|
|
70903
71001
|
const fileContent = await readFile14(resolved.filepath, "utf-8");
|
|
70904
71002
|
const { data, content } = (0, import_gray_matter8.default)(fileContent);
|
|
70905
71003
|
const metadata = data;
|
|
71004
|
+
if (input.smart) {
|
|
71005
|
+
const stats = calculateDocStats(content);
|
|
71006
|
+
const SMART_THRESHOLD = 2e3;
|
|
71007
|
+
if (stats.estimatedTokens <= SMART_THRESHOLD) {
|
|
71008
|
+
} else {
|
|
71009
|
+
const toc = extractToc(content);
|
|
71010
|
+
return successResponse({
|
|
71011
|
+
doc: {
|
|
71012
|
+
path: resolved.filename.replace(/\.md$/, ""),
|
|
71013
|
+
title: metadata.title,
|
|
71014
|
+
smart: true,
|
|
71015
|
+
isLarge: true,
|
|
71016
|
+
stats: {
|
|
71017
|
+
chars: stats.chars,
|
|
71018
|
+
estimatedTokens: stats.estimatedTokens,
|
|
71019
|
+
headingCount: stats.headingCount
|
|
71020
|
+
},
|
|
71021
|
+
toc: toc.map((entry, index) => ({
|
|
71022
|
+
index: index + 1,
|
|
71023
|
+
level: entry.level,
|
|
71024
|
+
title: entry.title
|
|
71025
|
+
})),
|
|
71026
|
+
hint: "Document is large. Use 'section' parameter with a number (e.g., section: '1') to read specific content."
|
|
71027
|
+
}
|
|
71028
|
+
});
|
|
71029
|
+
}
|
|
71030
|
+
}
|
|
70906
71031
|
if (input.info) {
|
|
70907
71032
|
const stats = calculateDocStats(content);
|
|
70908
71033
|
let recommendation;
|
|
@@ -70954,7 +71079,8 @@ async function handleGetDoc(args2) {
|
|
|
70954
71079
|
});
|
|
70955
71080
|
}
|
|
70956
71081
|
if (input.section) {
|
|
70957
|
-
const
|
|
71082
|
+
const sectionIndex = /^\d+$/.test(input.section) ? Number.parseInt(input.section, 10) : null;
|
|
71083
|
+
const sectionContent = sectionIndex !== null ? extractSectionByIndex(content, sectionIndex) : extractSection(content, input.section);
|
|
70958
71084
|
if (!sectionContent) {
|
|
70959
71085
|
return errorResponse(`Section not found: ${input.section}. Use 'toc: true' to see available sections.`);
|
|
70960
71086
|
}
|
|
@@ -71604,7 +71730,7 @@ async function notifyCliUpdate(options2) {
|
|
|
71604
71730
|
// package.json
|
|
71605
71731
|
var package_default = {
|
|
71606
71732
|
name: "knowns",
|
|
71607
|
-
version: "0.8.
|
|
71733
|
+
version: "0.8.9",
|
|
71608
71734
|
description: "AI-native task and documentation management for dev teams",
|
|
71609
71735
|
module: "index.ts",
|
|
71610
71736
|
type: "module",
|