knowns 0.1.4 → 0.1.6

package/dist/index.js

@@ -10489,10 +10489,10 @@ function serializeTaskMarkdown(task) {
     title: task.title,
     status: task.status,
     priority: task.priority,
-    labels: task.labels,
+    labels: task.labels || [],
     createdAt: task.createdAt.toISOString(),
     updatedAt: task.updatedAt.toISOString(),
-    timeSpent: task.timeSpent
+    timeSpent: task.timeSpent ?? 0
   };
   if (task.assignee)
     frontmatter.assignee = task.assignee;
@@ -10743,6 +10743,11 @@ class FileStore {
     const task = {
       ...taskData,
       id,
+      labels: taskData.labels || [],
+      subtasks: taskData.subtasks || [],
+      acceptanceCriteria: taskData.acceptanceCriteria || [],
+      timeSpent: taskData.timeSpent ?? 0,
+      timeEntries: taskData.timeEntries || [],
       createdAt: now,
       updatedAt: now
     };
@@ -11447,12 +11452,165 @@ var import_prompts = __toESM(require_prompts3(), 1);
 var KNOWNS_GUIDELINES = `<!-- KNOWNS GUIDELINES START -->
 # Knowns CLI Guidelines
 
-## Core Principle
+## Core Principles
 
+### 1. CLI-Only Operations
 **NEVER edit .md files directly. ALL operations MUST use CLI commands.**
 
 This ensures data integrity, maintains proper change history, and prevents file corruption.
 
+### 2. Documentation-First (For AI Agents)
+**ALWAYS read project documentation BEFORE planning or coding.**
+
+AI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.
+
+---
+
+## AI Agent Guidelines
+
+> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.
+
+### First-Time Initialization
+
+When starting a new session or working on an unfamiliar project:
+
+\`\`\`bash
+# 1. List all available documentation
+knowns doc list --plain
+
+# 2. Read essential project docs (prioritize these)
+knowns doc view "README" --plain           # Project overview
+knowns doc view "ARCHITECTURE" --plain     # System design
+knowns doc view "CONVENTIONS" --plain      # Coding standards
+knowns doc view "API" --plain              # API specifications
+
+# 3. Review current task backlog
+knowns task list --plain
+knowns task list --status in-progress --plain
+\`\`\`
+
+### Before Taking Any Task
+
+\`\`\`bash
+# 1. View the task details
+knowns task view <id> --plain
+
+# 2. Follow ALL refs in the task (see Reference System section)
+# @.knowns/tasks/task-44 - ... \u2192 knowns task view 44 --plain
+# @.knowns/docs/patterns/module.md \u2192 knowns doc view "patterns/module" --plain
+
+# 3. Search for additional related documentation
+knowns search "<keywords from task>" --type doc --plain
+
+# 4. Read ALL related docs before planning
+knowns doc view "<related-doc>" --plain
+
+# 5. Check for similar completed tasks (learn from history)
+knowns search "<keywords>" --type task --status done --plain
+\`\`\`
+
+### Why Documentation First?
+
+| Without Reading Docs | With Reading Docs |
+|---------------------|-------------------|
+| Reinvent existing patterns | Reuse established patterns |
+| Break conventions | Follow project standards |
+| Duplicate code | Use existing utilities |
+| Wrong architecture decisions | Align with system design |
+| Inconsistent naming | Match naming conventions |
+
+### Context Checklist for Agents
+
+Before writing ANY code, ensure you can answer:
+
+- [ ] Have I followed ALL refs (\`@.knowns/...\`) in the task?
+- [ ] Have I followed nested refs recursively?
+- [ ] What is the project's overall architecture?
+- [ ] What coding conventions does this project follow?
+- [ ] Are there existing patterns/utilities I should reuse?
+- [ ] What are the testing requirements?
+- [ ] How should I structure my implementation?
+
+> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.
+
+---
+
+## Reference System (Refs)
+
+Tasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.
+
+### Reference Formats
+
+| Type | User Input | System Output | CLI Command |
+|------|------------|---------------|-------------|
+| **Task ref** | \`@task-<id>\` | \`@.knowns/tasks/task-<id> - <title>.md\` | \`knowns task view <id> --plain\` |
+| **Doc ref** | \`@doc/<path>\` | \`@.knowns/docs/<path>.md\` | \`knowns doc view "<path>" --plain\` |
+
+### How to Follow Refs
+
+When you read a task and see refs in system output format, follow them:
+
+\`\`\`bash
+# Example: Task 42 output contains:
+# @.knowns/tasks/task-44 - CLI Task Create Command.md
+# @.knowns/docs/patterns/module.md
+
+# Follow task ref (extract ID from task-<id>)
+knowns task view 44 --plain
+
+# Follow doc ref (extract path, remove .md)
+knowns doc view "patterns/module" --plain
+\`\`\`
+
+### Parsing Rules
+
+1. **Task refs**: \`@.knowns/tasks/task-<id> - ...\` \u2192 extract \`<id>\` \u2192 \`knowns task view <id> --plain\`
+2. **Doc refs**: \`@.knowns/docs/<path>.md\` \u2192 extract \`<path>\` \u2192 \`knowns doc view "<path>" --plain\`
+
+### Recursive Following
+
+Refs can be nested. Follow until complete context is gathered:
+
+\`\`\`
+Task 42
+  \u2192 @.knowns/docs/README.md
+    \u2192 @.knowns/docs/patterns/module.md (found in README)
+      \u2192 (read for full pattern details)
+\`\`\`
+
+### When to Follow Refs
+
+| Situation | Action |
+|-----------|--------|
+| Refs in Description | ALWAYS follow - critical context |
+| Refs in Implementation Plan | Follow if implementing related work |
+| Refs in Notes | Optional - for historical context |
+| Dependency mentions | Follow if marked as blocker |
+
+### Example: Complete Ref Resolution
+
+\`\`\`bash
+# 1. Read the task
+$ knowns task view 42 --plain
+
+# Output contains:
+# @.knowns/tasks/task-44 - CLI Task Create Command.md
+# @.knowns/docs/README.md
+
+# 2. Follow task ref
+$ knowns task view 44 --plain
+
+# 3. Follow doc ref
+$ knowns doc view "README" --plain
+
+# 4. If README contains more refs, follow them too
+# @.knowns/docs/patterns/module.md \u2192 knowns doc view "patterns/module" --plain
+
+# Now you have complete context
+\`\`\`
+
+> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.
+
 ---
 
 ## Quick Start
@@ -11476,63 +11634,195 @@ knowns search "query" --plain
 
 ---
 
-## Task Workflow (CRITICAL - Follow Every Step!)
+## End-to-End Example
+
+Here's a complete workflow for an AI agent implementing a feature:
+
+\`\`\`bash
+# === AGENT SESSION START (Do this once per session) ===
+
+# 0a. List all available documentation
+$ knowns doc list --plain
+
+# Output:
+# DOC: README.md
+# DOC: ARCHITECTURE.md
+# DOC: CONVENTIONS.md
+# DOC: security-patterns.md
+# DOC: api-guidelines.md
+# DOC: email-templates.md
+
+# 0b. Read essential project docs
+$ knowns doc view "README" --plain
+$ knowns doc view "ARCHITECTURE" --plain
+$ knowns doc view "CONVENTIONS" --plain
+
+# Now the agent understands project context and conventions
+
+# === TASK WORKFLOW ===
+
+# 1. Create the task
+$ knowns task create "Add password reset flow" \\
+    -d "Users need ability to reset forgotten passwords via email" \\
+    --ac "User can request password reset via email" \\
+    --ac "Reset link expires after 1 hour" \\
+    --ac "User can set new password via reset link" \\
+    --ac "Unit tests cover all scenarios" \\
+    --priority high \\
+    -l "auth,feature"
+
+# Output: Created task AUTH-042
+
+# 2. Take the task and start timer
+$ knowns task edit AUTH-042 -s in-progress -a @me
+$ knowns time start AUTH-042
+
+# Output: Timer started for AUTH-042
+
+# 3. Search for related documentation
+$ knowns search "password security" --type doc --plain
+
+# Output:
+# DOC: security-patterns.md (score: 0.92)
+# DOC: email-templates.md (score: 0.78)
+
+# 4. Read the documentation
+$ knowns doc view "security-patterns" --plain
+
+# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)
+$ knowns task edit AUTH-042 --plan $'1. Review security patterns (see [security-patterns.md](./docs/security-patterns.md))
+2. Design token generation with 1-hour expiry
+3. Create email template (see [email-templates.md](./docs/email-templates.md))
+4. Implement /forgot-password endpoint
+5. Implement /reset-password endpoint
+6. Add unit tests
+7. Update API documentation'
+
+# 6. After approval, implement and check criteria as you go
+$ knowns task edit AUTH-042 --check-ac 1
+$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /forgot-password endpoint"
+
+$ knowns task edit AUTH-042 --check-ac 2
+$ knowns task edit AUTH-042 --append-notes "\u2713 Token expiry set to 1 hour"
+
+$ knowns task edit AUTH-042 --check-ac 3
+$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /reset-password endpoint"
+
+$ knowns task edit AUTH-042 --check-ac 4
+$ knowns task edit AUTH-042 --append-notes "\u2713 Added 12 unit tests, 100% coverage"
+
+# 7. Add final implementation notes
+$ knowns task edit AUTH-042 --notes $'## Summary
+Implemented complete password reset flow with secure token generation.
+
+## Changes
+- Added POST /forgot-password endpoint
+- Added POST /reset-password endpoint
+- Created password_reset_tokens table
+- Added email template for reset link
+
+## Security
+- Tokens use crypto.randomBytes(32)
+- 1-hour expiry enforced at DB level
+- Rate limiting: 3 requests per hour per email
+
+## Tests
+- 12 unit tests added
+- Coverage: 100% for new code
+
+## Documentation
+- Updated API.md with new endpoints'
+
+# 8. Stop timer and complete
+$ knowns time stop
+$ knowns task edit AUTH-042 -s done
+
+# Output: Task AUTH-042 marked as done
+\`\`\`
+
+---
+
+## Task Workflow
 
 ### Step 1: Take Task
+
 \`\`\`bash
-knowns task edit <id> -s in-progress -a @yourself
+knowns task edit <id> -s in-progress -a @me
 \`\`\`
 
+> **Note**: \`@me\` is a special keyword that assigns the task to yourself. You can also use specific usernames like \`@harry\` or \`@john\`.
+
 ### Step 2: Start Time Tracking
+
 \`\`\`bash
 knowns time start <id>
 \`\`\`
 
 ### Step 3: Read Related Documentation
+
+> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.
+
 \`\`\`bash
 # Search for related docs
 knowns search "authentication" --type doc --plain
 
 # View relevant documents
 knowns doc view "API Guidelines" --plain
+knowns doc view "Security Patterns" --plain
+
+# Also check for similar completed tasks
+knowns search "auth" --type task --status done --plain
 \`\`\`
 
-**CRITICAL**: ALWAYS read related documentation BEFORE planning!
+> **CRITICAL**: ALWAYS read related documentation BEFORE planning! Understanding existing patterns and conventions prevents rework and ensures consistency.
 
 ### Step 4: Create Implementation Plan
+
 \`\`\`bash
-# Add plan with documentation references
-knowns task edit <id> --plan $'1. Research patterns (see [security-patterns.md](./security-patterns.md))\\n2. Design middleware\\n3. Implement\\n4. Add tests\\n5. Update docs'
+knowns task edit <id> --plan $'1. Research patterns (see [security-patterns.md](./security-patterns.md))
+2. Design middleware
+3. Implement
+4. Add tests
+5. Update docs'
 \`\`\`
 
-**CRITICAL**:
-- Share plan with user and **WAIT for approval** before coding
-- Include doc references using \`[file.md](./path/file.md)\` format
+> **CRITICAL**:
+> - Share plan with user and **WAIT for approval** before coding
+> - Include doc references using \`[file.md](./path/file.md)\` format
 
 ### Step 5: Implement
+
 \`\`\`bash
 # Check acceptance criteria as you complete them
 knowns task edit <id> --check-ac 1 --check-ac 2 --check-ac 3
 \`\`\`
 
 ### Step 6: Add Implementation Notes
+
 \`\`\`bash
 # Add comprehensive notes (suitable for PR description)
-knowns task edit <id> --notes $'## Summary\\n\\nImplemented JWT auth.\\n\\n## Changes\\n- Added middleware\\n- Added tests'
+knowns task edit <id> --notes $'## Summary
 
-# OR append progressively
+Implemented JWT auth.
+
+## Changes
+- Added middleware
+- Added tests'
+
+# OR append progressively (recommended)
 knowns task edit <id> --append-notes "\u2713 Implemented middleware"
 knowns task edit <id> --append-notes "\u2713 Added tests"
 \`\`\`
 
 ### Step 7: Stop Time Tracking
+
 \`\`\`bash
 knowns time stop
 \`\`\`
 
 ### Step 8: Complete Task
+
 \`\`\`bash
-# Mark as done (only after ALL criteria are met)
 knowns task edit <id> -s done
 \`\`\`
 
@@ -11551,11 +11841,11 @@ knowns task edit <id> -t "New title"
 knowns task edit <id> -d "New description"
 knowns task edit <id> -s in-progress
 knowns task edit <id> --priority high
-knowns task edit <id> -a @yourself
+knowns task edit <id> -a @me
 
 # Acceptance Criteria
 knowns task edit <id> --ac "New criterion"           # Add
-knowns task edit <id> --check-ac 1 --check-ac 2      # Check
+knowns task edit <id> --check-ac 1 --check-ac 2      # Check (1-indexed)
 knowns task edit <id> --uncheck-ac 2                 # Uncheck
 knowns task edit <id> --remove-ac 3                  # Remove
 
@@ -11568,7 +11858,7 @@ knowns task edit <id> --append-notes "Progress update"
 knowns task view <id> --plain                        # ALWAYS use --plain
 knowns task list --plain
 knowns task list --status in-progress --plain
-knowns task list --assignee @yourself --plain
+knowns task list --assignee @me --plain
 knowns task list --tree --plain                      # Tree hierarchy
 \`\`\`
 
@@ -11598,11 +11888,16 @@ knowns doc list --plain
 knowns doc list --tag architecture --plain
 knowns doc view "Doc Name" --plain
 
-# Create
+# Create (with optional folder)
 knowns doc create "Title" -d "Description" -t "tags"
+knowns doc create "Title" -d "Description" -t "tags" -f "folder/path"
 
 # Edit metadata
 knowns doc edit "Doc Name" -t "New Title" --tags "new,tags"
+
+# Edit content
+knowns doc edit "Doc Name" -c "New content"        # Replace content
+knowns doc edit "Doc Name" -a "Appended content"   # Append to content
 \`\`\`
 
 ### Search
@@ -11624,51 +11919,100 @@ knowns search "bug" --status in-progress --priority high --plain
 ## Task Structure
 
 ### Title
+
 Clear summary (WHAT needs to be done).
-- Good: "Add JWT authentication"
-- Bad: "Do auth stuff"
+
+| Bad | Good |
+|-----|------|
+| Do auth stuff | Add JWT authentication |
+| Fix bug | Fix login timeout on slow networks |
+| Update docs | Document rate limiting in API.md |
 
 ### Description
+
 Explains WHY and WHAT (not HOW). **Link related docs using \`[file.md](./path/file.md)\`**
 
-\`\`\`
-We need JWT authentication because sessions don't scale.
+\`\`\`markdown
+We need JWT authentication because sessions don't scale for our microservices architecture.
 
 Related docs:
-- [security-patterns.md](./security-patterns.md)
-- [api-guidelines.md](./api-guidelines.md)
+- [security-patterns.md](./docs/security-patterns.md)
+- [api-guidelines.md](./docs/api-guidelines.md)
 \`\`\`
 
 ### Acceptance Criteria
-**Outcome-oriented**, testable criteria. NOT implementation details.
 
-- Good: "User can login and receive JWT token"
-- Good: "Token expires after 15 minutes"
-- Bad: "Add function handleLogin() in auth.ts"
+**Outcome-oriented**, testable criteria. NOT implementation steps.
+
+| Bad (Implementation details) | Good (Outcomes) |
+|------------------------------|-----------------|
+| Add function handleLogin() in auth.ts | User can login and receive JWT token |
+| Use bcrypt for hashing | Passwords are securely hashed |
+| Add try-catch blocks | Errors return appropriate HTTP status codes |
 
 ### Implementation Plan
+
 HOW to solve. Added AFTER taking task, BEFORE coding.
 
-\`\`\`
-1. Research JWT libraries (see [security-patterns.md](./security-patterns.md))
-2. Design token structure
-3. Implement middleware
-4. Add tests
+\`\`\`markdown
+1. Research JWT libraries (see [security-patterns.md](./docs/security-patterns.md))
+2. Design token structure (access + refresh tokens)
+3. Implement auth middleware
+4. Add unit tests (aim for 90%+ coverage)
+5. Update API.md with new endpoints
 \`\`\`
 
 ### Implementation Notes
-Summary for PR. Added AFTER completion.
 
-\`\`\`
+Summary for PR description. Added AFTER completion.
+
+\`\`\`markdown
 ## Summary
-Implemented JWT auth using jsonwebtoken.
+Implemented JWT auth using jsonwebtoken library.
 
 ## Changes
-- Added middleware in src/auth.ts
-- Added tests with 100% coverage
+- Added auth middleware in src/middleware/auth.ts
+- Added /login and /refresh endpoints
+- Created JWT utility functions
+
+## Tests
+- Added 15 unit tests
+- Coverage: 94%
 
 ## Documentation
-- Updated API.md
+- Updated API.md with authentication section
+\`\`\`
+
+---
+
+## Error Handling
+
+### Common Errors and Solutions
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| \`Error: Task not found\` | Invalid task ID | Run \`knowns task list --plain\` to find correct ID |
+| \`Error: No active timer\` | Calling \`time stop\` without active timer | Start timer first: \`knowns time start <id>\` |
+| \`Error: Timer already running\` | Starting timer when one is active | Stop current: \`knowns time stop\` |
+| \`Error: Invalid status\` | Wrong status format | Use lowercase with hyphens: \`in-progress\`, not \`In Progress\` |
+| \`Error: AC index out of range\` | Checking non-existent criterion | View task first: \`knowns task view <id> --plain\` |
+| \`Error: Document not found\` | Wrong document name | Run \`knowns doc list --plain\` to find correct name |
+| \`Error: Not initialized\` | Running commands without init | Run \`knowns init\` first |
+
+### Debugging Commands
+
+\`\`\`bash
+# Check CLI version
+knowns --version
+
+# Verify project is initialized
+knowns status
+
+# View raw task data (for debugging)
+knowns task view <id> --json
+
+# Check timer status
+knowns time status
 \`\`\`
 
 ---
@@ -11678,109 +12022,193 @@ Implemented JWT auth using jsonwebtoken.
 A task is **Done** ONLY when **ALL** criteria are met:
 
 ### Via CLI (Required)
-1. All acceptance criteria checked: \`--check-ac <index>\`
-2. Implementation notes added: \`--notes "..."\`
-3. Status set to done: \`-s done\`
+
+- [ ] All acceptance criteria checked: \`--check-ac <index>\`
+- [ ] Implementation notes added: \`--notes "..."\`
+- [ ] Timer stopped: \`knowns time stop\`
+- [ ] Status set to done: \`-s done\`
 
 ### Via Code (Required)
-4. Tests pass
-5. Documentation updated
-6. Code reviewed (linting, formatting)
-7. No regressions
+
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] Code reviewed (linting, formatting)
+- [ ] No regressions introduced
+
+---
+
+## Status & Priority Reference
+
+### Status Values
+
+Use **lowercase with hyphens**:
+
+| Status | Description | When to Use |
+|--------|-------------|-------------|
+| \`todo\` | Not started | Default for new tasks |
+| \`in-progress\` | Currently working | After taking task |
+| \`in-review\` | In code review | PR submitted |
+| \`blocked\` | Waiting on dependency | External blocker |
+| \`done\` | Completed | All criteria met |
+
+### Priority Values
+
+| Priority | Description |
+|----------|-------------|
+| \`low\` | Can wait, nice-to-have |
+| \`medium\` | Normal priority (default) |
+| \`high\` | Urgent, time-sensitive |
 
 ---
 
 ## Common Mistakes
 
 | Wrong | Right |
-|---------|---------|
+|-------|-------|
 | Edit .md files directly | Use \`knowns task edit\` |
 | Change \`- [ ]\` to \`- [x]\` in file | Use \`--check-ac <index>\` |
-| Start coding without reading docs | Read docs FIRST, then plan |
-| Plan without checking docs | Search and read docs before planning |
-| Missing doc links in description/plan | Link docs using \`[file.md](./path/file.md)\` |
-| Forget to use \`--plain\` flag | Always use \`--plain\` for AI |
-| Forget to share plan before coding | Share plan, WAIT for approval |
-| Mark done without all criteria checked | Check ALL criteria first |
-| Write implementation details in AC | Write outcome-oriented criteria |
+| Start coding without reading docs | Read ALL related docs FIRST |
+| Skip \`knowns doc list\` on new project | Always list docs when starting |
+| Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |
+| Plan without checking docs | Read docs before planning |
+| Ignore similar completed tasks | Search done tasks for patterns |
+| Missing doc links in description/plan | Link docs using \`[file.md](./path)\` |
+| Forget \`--plain\` flag | Always use \`--plain\` for AI |
+| Code before plan approval | Share plan, WAIT for approval |
+| Mark done without all criteria | Check ALL criteria first |
+| Write implementation steps in AC | Write outcome-oriented criteria |
 | Use \`"In Progress"\` or \`"Done"\` | Use \`in-progress\`, \`done\` |
+| Use \`@yourself\` | Use \`@me\` or specific username |
+| Ignore refs in task description | Follow ALL refs (\`@.knowns/...\`) before planning |
+| See \`@.knowns/docs/...\` but don't read | Use \`knowns doc view "<path>" --plain\` |
+| See \`@.knowns/tasks/task-X\` but don't check | Use \`knowns task view X --plain\` for context |
+| Follow only first-level refs | Recursively follow nested refs until complete |
 
 ---
 
-## Best Practices
-
-### Critical Rules
-- **ALWAYS use \`--plain\` flag** for AI-readable output
-- **Read documentation BEFORE planning**: \`knowns search "keyword" --type doc --plain\`
-- **Link docs in tasks**: Use \`[file.md](./path/file.md)\` or \`[mapper.md](./patterns/mapper.md)\`
-- **Share plan before coding**: Get approval first
-- **Start time tracking**: \`knowns time start <id>\` before work
-- **Stop time tracking**: \`knowns time stop\` after work
-- **Check criteria as you go**: Don't wait until end
-- **Add notes progressively**: Use \`--append-notes\`
+## Platform-Specific Notes
 
 ### Multi-line Input
-- **Bash/Zsh**: \`$'Line1\\nLine2\\nLine3'\`
-- **PowerShell**: \`"Line1\\\`nLine2\\\`nLine3"\`
-- **Portable**: \`"$(printf 'Line1\\nLine2\\nLine3')"\`
 
-### Documentation Workflow
-1. Search: \`knowns search "keyword" --type doc --plain\`
-2. Read: \`knowns doc view "Doc Name" --plain\`
-3. Link in description: \`[file.md](./path/file.md)\`
-4. Link in plan: Reference specific sections
-5. Update after implementation
+Different shells handle multi-line strings differently:
+
+**Bash / Zsh (Recommended)**
+\`\`\`bash
+knowns task edit <id> --plan $'1. First step\\n2. Second step\\n3. Third step'
+\`\`\`
+
+**PowerShell**
+\`\`\`powershell
+knowns task edit <id> --plan "1. First step\`n2. Second step\`n3. Third step"
+\`\`\`
+
+**Cross-platform (Using printf)**
+\`\`\`bash
+knowns task edit <id> --plan "$(printf '1. First step\\n2. Second step\\n3. Third step')"
+\`\`\`
+
+**Using heredoc (for long content)**
+\`\`\`bash
+knowns task edit <id> --plan "$(cat <<EOF
+1. First step
+2. Second step
+3. Third step
+EOF
+)"
+\`\`\`
+
+### Path Separators
+
+- **Unix/macOS**: Use forward slashes: \`./docs/api.md\`
+- **Windows**: Both work, but prefer forward slashes for consistency
 
 ---
 
-## Status & Priority Values
+## Best Practices Checklist
+
+### For AI Agents: Session Start
 
-**Status** (lowercase with hyphens):
-- \`todo\` - Not started
-- \`in-progress\` - Currently working
-- \`in-review\` - In code review
-- \`done\` - Completed
-- \`blocked\` - Waiting on dependency
+- [ ] List all docs: \`knowns doc list --plain\`
+- [ ] Read README/ARCHITECTURE docs
+- [ ] Understand coding conventions
+- [ ] Review current task backlog
 
-**Priority**:
-- \`low\` - Can wait
-- \`medium\` - Normal (default)
-- \`high\` - Urgent, important
+### Before Starting Work
+
+- [ ] Task has clear acceptance criteria
+- [ ] ALL refs in task followed (\`@.knowns/...\`)
+- [ ] Nested refs recursively followed until complete context gathered
+- [ ] Related docs searched: \`knowns search "keyword" --type doc --plain\`
+- [ ] ALL relevant docs read: \`knowns doc view "Doc Name" --plain\`
+- [ ] Similar done tasks reviewed for patterns
+- [ ] Task assigned to self: \`-a @me\`
+- [ ] Status set to in-progress: \`-s in-progress\`
+- [ ] Timer started: \`knowns time start <id>\`
+
+### During Work
+
+- [ ] Implementation plan created and approved
+- [ ] Doc links included in plan: \`[file.md](./path/file.md)\`
+- [ ] Criteria checked as completed: \`--check-ac <index>\`
+- [ ] Progress notes appended: \`--append-notes "\u2713 ..."\`
+
+### After Work
+
+- [ ] All acceptance criteria checked
+- [ ] Implementation notes added: \`--notes "..."\`
+- [ ] Timer stopped: \`knowns time stop\`
+- [ ] Tests passing
+- [ ] Documentation updated
+- [ ] Status set to done: \`-s done\`
 
 ---
 
-## Quick Reference
+## Quick Reference Card
 
 \`\`\`bash
-# Full workflow
+# === AGENT INITIALIZATION (Once per session) ===
+knowns doc list --plain
+knowns doc view "README" --plain
+knowns doc view "ARCHITECTURE" --plain
+knowns doc view "CONVENTIONS" --plain
+
+# === FULL WORKFLOW ===
 knowns task create "Title" -d "Description" --ac "Criterion"
-knowns task edit <id> -s in-progress -a @yourself
+knowns task edit <id> -s in-progress -a @me
 knowns time start <id>
 knowns search "keyword" --type doc --plain
 knowns doc view "Doc Name" --plain
+knowns search "keyword" --type task --status done --plain  # Learn from history
 knowns task edit <id> --plan $'1. Step (see [file.md](./file.md))\\n2. Step'
-# ... implement code ...
+# ... wait for approval, then implement ...
 knowns task edit <id> --check-ac 1 --check-ac 2
-knowns task edit <id> --append-notes "\u2713 Completed"
+knowns task edit <id> --append-notes "\u2713 Completed feature"
 knowns time stop
 knowns task edit <id> -s done
 
-# View task
+# === VIEW & SEARCH ===
 knowns task view <id> --plain
-
-# List tasks
 knowns task list --plain
-knowns task list --status in-progress --assignee @yourself --plain
-
-# Search
+knowns task list --status in-progress --assignee @me --plain
 knowns search "query" --plain
 knowns search "bug" --type task --status in-progress --plain
+
+# === TIME TRACKING ===
+knowns time start <id>
+knowns time stop
+knowns time status
+knowns time report --from "2025-12-01" --to "2025-12-31"
+
+# === DOCUMENTATION ===
+knowns doc list --plain
+knowns doc view "path/doc-name" --plain
+knowns doc create "Title" -d "Description" -t "tags" -f "folder"
+knowns doc edit "doc-name" -c "New content"
+knowns doc edit "doc-name" -a "Appended content"
 \`\`\`
 
 ---
 
-**Last Updated**: 2025-12-26
-**Version**: 2.1.0
 **Maintained By**: Knowns CLI Team
 
 <!-- KNOWNS GUIDELINES END -->
@@ -12029,7 +12457,7 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
 });
 // src/commands/task.ts
 import { mkdir as mkdir4, readdir as readdir2, unlink } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 
 // src/utils/doc-links.ts
 import { existsSync as existsSync3 } from "fs";
@@ -12114,6 +12542,86 @@ function findProjectRoot(startPath = process.cwd()) {
   return null;
 }
 
+// src/utils/mention-refs.ts
+var TASK_MENTION_REGEX = /@task-(\d+)/g;
+var DOC_MENTION_REGEX = /@docs?\/([^\s|)]+)/g;
+function sanitizeTitle(title) {
+  return title.replace(/[<>:"/\\|?*]/g, "").replace(/\s+/g, " ").trim().slice(0, 50);
+}
+function transformTaskMention(taskId, tasks) {
+  const task = tasks.get(taskId);
+  if (task) {
+    const sanitizedTitle = sanitizeTitle(task.title);
+    return `@.knowns/tasks/task-${taskId} - ${sanitizedTitle}.md`;
+  }
+  return `@.knowns/tasks/task-${taskId}.md`;
+}
+function transformDocMention(docPath) {
+  const normalizedPath = docPath.endsWith(".md") ? docPath : `${docPath}.md`;
+  return `@.knowns/docs/${normalizedPath}`;
+}
+function transformMentionsToRefs(text, tasks) {
+  let result = text;
+  result = result.replace(TASK_MENTION_REGEX, (match, taskId) => {
+    return transformTaskMention(taskId, tasks);
+  });
+  result = result.replace(DOC_MENTION_REGEX, (match, docPath) => {
+    return transformDocMention(docPath);
+  });
+  return result;
+}
+function buildTaskMap(tasks) {
+  const map = new Map;
+  for (const task of tasks) {
+    map.set(task.id, task);
+  }
+  return map;
+}
+
+// src/utils/notify-server.ts
+import { existsSync as existsSync5, readFileSync } from "fs";
+import { join as join7 } from "path";
+var DEFAULT_PORT = 6420;
+function getServerPort() {
+  try {
+    const projectRoot = findProjectRoot();
+    if (!projectRoot)
+      return DEFAULT_PORT;
+    const configPath = join7(projectRoot, ".knowns/config.json");
+    if (!existsSync5(configPath))
+      return DEFAULT_PORT;
+    const content = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content);
+    const port = config.settings?.serverPort;
+    return typeof port === "number" ? port : DEFAULT_PORT;
+  } catch {
+    return DEFAULT_PORT;
+  }
+}
+async function notifyTaskUpdate(taskId) {
+  try {
+    const port = getServerPort();
+    const response = await fetch(`http://localhost:${port}/api/notify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ taskId }),
+      signal: AbortSignal.timeout(1000)
+    });
+    if (response.ok) {}
+  } catch {}
+}
+async function notifyDocUpdate(docPath) {
+  try {
+    const port = getServerPort();
+    await fetch(`http://localhost:${port}/api/notify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "docs:updated", docPath }),
+      signal: AbortSignal.timeout(1000)
+    });
+  } catch {}
+}
+
 // src/commands/task.ts
 function getFileStore() {
   const projectRoot = findProjectRoot();
@@ -12153,6 +12661,9 @@ async function formatTask(task, fileStore, plain = false) {
     const border = "-".repeat(50);
     const titleBorder = "=".repeat(50);
     const output2 = [];
+    const allTasks = await fileStore.getAllTasks();
+    const taskMap = buildTaskMap(allTasks);
+    const transformText = (text) => transformMentionsToRefs(text, taskMap);
     const projectRoot2 = findProjectRoot();
     if (projectRoot2) {
       const filename = `task-${task.id} - ${task.title.replace(/[^a-z0-9]+/gi, "-")}`;
@@ -12204,7 +12715,7 @@ async function formatTask(task, fileStore, plain = false) {
     if (task.description) {
       output2.push("Description:");
       output2.push(border);
-      output2.push(task.description);
+      output2.push(transformText(task.description));
       output2.push("");
     }
     if (task.acceptanceCriteria.length > 0) {
@@ -12212,20 +12723,20 @@ async function formatTask(task, fileStore, plain = false) {
       output2.push(border);
       for (const [i, ac] of task.acceptanceCriteria.entries()) {
         const checkbox = ac.completed ? "[x]" : "[ ]";
-        output2.push(`- ${checkbox} #${i + 1} ${ac.text}`);
+        output2.push(`- ${checkbox} #${i + 1} ${transformText(ac.text)}`);
       }
       output2.push("");
     }
     if (task.implementationPlan) {
       output2.push("Implementation Plan:");
       output2.push(border);
-      output2.push(task.implementationPlan);
+      output2.push(transformText(task.implementationPlan));
       output2.push("");
     }
     if (task.implementationNotes) {
       output2.push("Implementation Notes:");
       output2.push(border);
-      output2.push(task.implementationNotes);
+      output2.push(transformText(task.implementationNotes));
       output2.push("");
     }
     if (projectRoot2) {
@@ -12504,6 +13015,7 @@ var createCommand2 = new Command("create").description("Create a new task").argu
       timeSpent: 0,
       timeEntries: []
     });
+    await notifyTaskUpdate(task.id);
     console.log(source_default.green(`\u2713 Created task-${task.id}: ${task.title}`));
     if (options2.parent) {
       console.log(source_default.gray(`  Subtask of: ${options2.parent}`));
@@ -12668,6 +13180,7 @@ var editCommand = new Command("edit").description("Edit task properties").argume
       updates.implementationNotes = existingNotes + separator + options2.appendNotes;
     }
     await fileStore.updateTask(id, updates);
+    await notifyTaskUpdate(id);
     console.log(source_default.green(`\u2713 Updated task-${id}`));
     const changes = [];
     if (options2.title)
@@ -12724,17 +13237,17 @@ var archiveCommand = new Command("archive").description("Archive a task").argume
       console.error(source_default.red(`\u2717 Task ${id} not found`));
       process.exit(1);
     }
-    const archiveDir = join7(projectRoot, ".knowns", "archive");
+    const archiveDir = join8(projectRoot, ".knowns", "archive");
     await mkdir4(archiveDir, { recursive: true });
-    const tasksPath = join7(projectRoot, ".knowns", "tasks");
+    const tasksPath = join8(projectRoot, ".knowns", "tasks");
     const files = await readdir2(tasksPath);
     const taskFile = files.find((f) => f.startsWith(`task-${id} -`));
     if (!taskFile) {
       console.error(source_default.red(`\u2717 Task file for ${id} not found`));
       process.exit(1);
     }
-    const oldPath = join7(tasksPath, taskFile);
-    const newPath = join7(archiveDir, taskFile);
+    const oldPath = join8(tasksPath, taskFile);
+    const newPath = join8(archiveDir, taskFile);
     const content = await Bun.file(oldPath).text();
     await Bun.write(newPath, content);
     await unlink(oldPath);
@@ -12755,16 +13268,16 @@ var unarchiveCommand = new Command("unarchive").description("Restore archived ta
       console.error(source_default.gray('  Run "knowns init" to initialize'));
       process.exit(1);
     }
-    const archiveDir = join7(projectRoot, ".knowns", "archive");
-    const tasksPath = join7(projectRoot, ".knowns", "tasks");
+    const archiveDir = join8(projectRoot, ".knowns", "archive");
+    const tasksPath = join8(projectRoot, ".knowns", "tasks");
     const files = await readdir2(archiveDir);
     const taskFile = files.find((f) => f.startsWith(`task-${id} -`));
     if (!taskFile) {
       console.error(source_default.red(`\u2717 Archived task ${id} not found`));
       process.exit(1);
     }
-    const archivePath = join7(archiveDir, taskFile);
-    const tasksFilePath = join7(tasksPath, taskFile);
+    const archivePath = join8(archiveDir, taskFile);
+    const tasksFilePath = join8(tasksPath, taskFile);
     const content = await Bun.file(archivePath).text();
     await Bun.write(tasksFilePath, content);
     await unlink(archivePath);
@@ -13355,9 +13868,9 @@ var boardCommand = new Command("board").description("Display Kanban board").opti
   }
 });
 // src/commands/search.ts
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { readFile as readFile2, readdir as readdir3 } from "fs/promises";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 var import_gray_matter2 = __toESM(require_gray_matter(), 1);
 function getFileStore3() {
   const projectRoot = findProjectRoot();
@@ -13409,8 +13922,8 @@ function calculateDocScore(doc, query) {
   return score;
 }
 async function searchDocs(query, projectRoot) {
-  const docsDir = join8(projectRoot, ".knowns", "docs");
-  if (!existsSync5(docsDir)) {
+  const docsDir = join9(projectRoot, ".knowns", "docs");
+  if (!existsSync6(docsDir)) {
     return [];
   }
   try {
@@ -13418,7 +13931,7 @@ async function searchDocs(query, projectRoot) {
     const mdFiles = files.filter((f) => f.endsWith(".md"));
     const results = [];
     for (const file of mdFiles) {
-      const content = await readFile2(join8(docsDir, file), "utf-8");
+      const content = await readFile2(join9(docsDir, file), "utf-8");
       const { data, content: docContent } = import_gray_matter2.default(content);
       const metadata = data;
       const doc = {
@@ -13676,6 +14189,7 @@ var stopCommand = new Command("stop").description("Stop current timer and save t
         timeEntries: task.timeEntries,
         timeSpent: task.timeSpent
       });
+      await notifyTaskUpdate(taskId);
     }
     data.active = null;
     await saveTimeData(projectRoot, data);
@@ -13847,6 +14361,7 @@ var addCommand = new Command("add").description("Manually add time entry to a ta
       timeEntries: task.timeEntries,
       timeSpent: task.timeSpent
     });
+    await notifyTaskUpdate(taskId);
     console.log(source_default.green(`\u2713 Added ${formatDuration(seconds)} to #${taskId}: ${task.title}`));
     if (options2.note) {
       console.log(source_default.gray(`  Note: ${options2.note}`));
@@ -13999,13 +14514,16 @@ timeCommand.addCommand(statusCommand);
 timeCommand.addCommand(logCommand);
 timeCommand.addCommand(addCommand);
 timeCommand.addCommand(reportCommand);
+// src/commands/browser.ts
+import { existsSync as existsSync8 } from "fs";
+import { mkdir as mkdir6, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+import { join as join11 } from "path";
+
 // src/server/index.ts
-import { watch } from "fs";
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 import { mkdir as mkdir5, readFile as readFile3, readdir as readdir4, writeFile as writeFile2 } from "fs/promises";
-import { join as join9, relative } from "path";
+import { join as join10, relative } from "path";
 var import_gray_matter3 = __toESM(require_gray_matter(), 1);
-var buildVersion = Date.now();
 async function startServer(options2) {
   const { port, projectRoot, open } = options2;
   const store = new FileStore(projectRoot);
@@ -14019,89 +14537,13 @@ async function startServer(options2) {
   const currentDir = import.meta.dir;
   let packageRoot = currentDir;
   if (currentDir.endsWith("/dist")) {
-    packageRoot = join9(currentDir, "..");
+    packageRoot = join10(currentDir, "..");
   } else if (currentDir.includes("/src/server")) {
-    packageRoot = join9(currentDir, "..", "..");
-  }
-  const uiSourcePath = join9(packageRoot, "src", "ui");
-  const uiDistPath = join9(packageRoot, "dist", "ui");
-  let shouldBuild = false;
-  if (existsSync6(join9(uiDistPath, "main.js"))) {
-    shouldBuild = false;
-  } else if (existsSync6(join9(uiSourcePath, "index.html"))) {
-    shouldBuild = true;
-  } else {
-    throw new Error(`UI files not found. Tried:
-  - ${uiDistPath} (${existsSync6(uiDistPath) ? "exists but no main.js" : "not found"})
-  - ${uiSourcePath} (${existsSync6(uiSourcePath) ? "exists but no index.html" : "not found"})
-Package root: ${packageRoot}
-Current dir: ${currentDir}`);
-  }
-  const buildUI = async () => {
-    if (!shouldBuild) {
-      return true;
-    }
-    console.log("Building UI...");
-    const startTime = Date.now();
-    if (!existsSync6(uiDistPath)) {
-      await mkdir5(uiDistPath, { recursive: true });
-    }
-    const buildResult = await Bun.build({
-      entrypoints: [join9(uiSourcePath, "main.tsx")],
-      outdir: uiDistPath,
-      target: "browser",
-      minify: false,
-      sourcemap: "inline",
-      define: {
-        "process.env.NODE_ENV": JSON.stringify("development")
-      }
-    });
-    if (!buildResult.success) {
-      console.error("Build errors:", buildResult.logs);
-      return false;
-    }
-    const cssResult = await Bun.build({
-      entrypoints: [join9(uiSourcePath, "index.css")],
-      outdir: uiDistPath,
-      target: "browser",
-      minify: false
-    });
-    if (!cssResult.success) {
-      console.error("CSS build errors:", cssResult.logs);
-    }
-    buildVersion = Date.now();
-    console.log(`UI built in ${Date.now() - startTime}ms`);
-    return true;
-  };
-  if (shouldBuild) {
-    if (!await buildUI()) {
-      throw new Error("Failed to build UI");
-    }
+    packageRoot = join10(currentDir, "..", "..");
   }
-  let watcher = null;
-  if (shouldBuild) {
-    let rebuildTimeout = null;
-    watcher = watch(uiSourcePath, { recursive: true }, async (_event, filename) => {
-      if (!filename)
-        return;
-      if (!filename.endsWith(".tsx") && !filename.endsWith(".ts") && !filename.endsWith(".css")) {
-        return;
-      }
-      if (rebuildTimeout) {
-        clearTimeout(rebuildTimeout);
-      }
-      rebuildTimeout = setTimeout(async () => {
-        console.log(`File changed: ${filename}`);
-        const success = await buildUI();
-        if (success) {
-          broadcast({ type: "reload" });
-        }
-      }, 100);
-    });
-    process.on("SIGINT", () => {
-      watcher?.close();
-      process.exit(0);
-    });
+  const uiDistPath = join10(packageRoot, "dist", "ui");
+  if (!existsSync7(join10(uiDistPath, "index.html"))) {
+    throw new Error(`UI build not found at ${uiDistPath}. Run 'bun run build:ui' first.`);
   }
   const server = Bun.serve({
     port,
@@ -14119,89 +14561,31 @@ Current dir: ${currentDir}`);
       if (url.pathname.startsWith("/api/")) {
         return handleAPI(req, url, store, broadcast);
       }
-      if (url.pathname === "/main.js" || url.pathname.startsWith("/main.js?")) {
-        const file = Bun.file(join9(uiDistPath, "main.js"));
+      if (url.pathname.startsWith("/assets/")) {
+        const filePath = join10(uiDistPath, url.pathname);
+        const file = Bun.file(filePath);
         if (await file.exists()) {
+          const ext = url.pathname.split(".").pop();
+          const contentType = ext === "js" ? "application/javascript" : ext === "css" ? "text/css" : ext === "svg" ? "image/svg+xml" : ext === "png" ? "image/png" : ext === "jpg" || ext === "jpeg" ? "image/jpeg" : ext === "woff2" ? "font/woff2" : ext === "woff" ? "font/woff" : "application/octet-stream";
           return new Response(file, {
             headers: {
-              "Content-Type": "application/javascript",
-              "Cache-Control": "no-cache, no-store, must-revalidate"
+              "Content-Type": contentType,
+              "Cache-Control": "public, max-age=31536000, immutable"
             }
           });
         }
       }
-      if (url.pathname === "/index.css" || url.pathname.startsWith("/index.css?")) {
-        const file = Bun.file(join9(uiDistPath, "index.css"));
-        if (await file.exists()) {
-          return new Response(file, {
+      if (url.pathname === "/" || url.pathname === "/index.html" || !url.pathname.includes(".")) {
+        const indexFile = Bun.file(join10(uiDistPath, "index.html"));
+        if (await indexFile.exists()) {
+          return new Response(indexFile, {
             headers: {
-              "Content-Type": "text/css",
+              "Content-Type": "text/html",
               "Cache-Control": "no-cache, no-store, must-revalidate"
             }
           });
         }
       }
-      if (url.pathname === "/" || url.pathname === "/index.html") {
-        const html = `<!DOCTYPE html>
-<html lang="en">
-	<head>
-		<meta charset="UTF-8" />
-		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
-		<title>Knowns - Task Management</title>
-		<link rel="stylesheet" href="/index.css?v=${buildVersion}" />
-	</head>
-	<body>
-		<div id="root"></div>
-		<script type="module" src="/main.js?v=${buildVersion}"></script>
-		<script>
-			// Live reload via WebSocket
-			(function() {
-				let ws;
-				let reconnectInterval;
-
-				function connect() {
-					ws = new WebSocket('ws://' + location.host + '/ws');
-
-					ws.onopen = function() {
-						console.log('[LiveReload] Connected');
-						if (reconnectInterval) {
-							clearInterval(reconnectInterval);
-							reconnectInterval = null;
-						}
-					};
-
-					ws.onmessage = function(event) {
-						const data = JSON.parse(event.data);
-						if (data.type === 'reload') {
-							console.log('[LiveReload] Reloading...');
-							location.reload();
-						}
-					};
-
-					ws.onclose = function() {
-						console.log('[LiveReload] Disconnected, reconnecting...');
-						if (!reconnectInterval) {
-							reconnectInterval = setInterval(connect, 1000);
-						}
-					};
-
-					ws.onerror = function() {
-						ws.close();
-					};
-				}
-
-				connect();
-			})();
-		</script>
-	</body>
-</html>`;
-        return new Response(html, {
-          headers: {
-            "Content-Type": "text/html",
-            "Cache-Control": "no-cache, no-store, must-revalidate"
-          }
-        });
-      }
       return new Response("Not Found", { status: 404 });
     },
     websocket: {
@@ -14214,13 +14598,7 @@ Current dir: ${currentDir}`);
       message(_ws, _message) {}
     }
   });
-  console.log(`Server running at http://localhost:${port}`);
-  console.log(`Open in browser: http://localhost:${port}`);
-  if (shouldBuild) {
-    console.log(`Live reload enabled - watching ${uiSourcePath}`);
-  } else {
-    console.log(`Serving pre-built UI from ${uiDistPath}`);
-  }
+  console.log(`\u2713 Server running at http://localhost:${port}`);
   if (open) {
     const openCommand = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
     try {
@@ -14235,7 +14613,7 @@ async function findMarkdownFiles(dir, baseDir) {
   const files = [];
   const entries = await readdir4(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join9(dir, entry.name);
+    const fullPath = join10(dir, entry.name);
     if (entry.isDirectory()) {
       const subFiles = await findMarkdownFiles(fullPath, baseDir);
       files.push(...subFiles);
@@ -14261,7 +14639,13 @@ async function handleAPI(req, url, store, broadcast) {
       const tasks = await store.getAllTasks();
       return new Response(JSON.stringify(tasks), { headers });
     }
-    const taskMatch = url.pathname.match(/^\/api\/tasks\/(.+)$/);
+    const historyMatch = url.pathname.match(/^\/api\/tasks\/(.+)\/history$/);
+    if (historyMatch && req.method === "GET") {
+      const taskId = historyMatch[1];
+      const history = await store.getTaskVersionHistory(taskId);
+      return new Response(JSON.stringify({ versions: history }), { headers });
+    }
+    const taskMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)$/);
     if (taskMatch && req.method === "GET") {
       const task = await store.getTask(taskMatch[1]);
       if (!task) {
@@ -14273,10 +14657,18 @@ async function handleAPI(req, url, store, broadcast) {
       return new Response(JSON.stringify(task), { headers });
     }
     if (taskMatch && req.method === "PUT") {
-      const updates = await req.json();
-      const task = await store.updateTask(taskMatch[1], updates);
-      broadcast({ type: "tasks:updated", task });
-      return new Response(JSON.stringify(task), { headers });
+      try {
+        const updates = await req.json();
+        const task = await store.updateTask(taskMatch[1], updates);
+        broadcast({ type: "tasks:updated", task });
+        return new Response(JSON.stringify(task), { headers });
+      } catch (error) {
+        console.error("Error updating task:", error);
+        return new Response(JSON.stringify({ error: String(error) }), {
+          status: 500,
+          headers
+        });
+      }
     }
     if (url.pathname === "/api/tasks" && req.method === "POST") {
       const data = await req.json();
@@ -14287,14 +14679,45 @@ async function handleAPI(req, url, store, broadcast) {
         status: 201
       });
     }
+    if (url.pathname === "/api/notify" && req.method === "POST") {
+      try {
+        const { taskId, type, docPath } = await req.json();
+        if (taskId) {
+          const task = await store.getTask(taskId);
+          if (task) {
+            broadcast({ type: "tasks:updated", task });
+            return new Response(JSON.stringify({ success: true }), { headers });
+          }
+        } else if (type === "tasks:refresh") {
+          broadcast({ type: "tasks:refresh" });
+          return new Response(JSON.stringify({ success: true }), { headers });
+        } else if (type === "docs:updated" && docPath) {
+          broadcast({ type: "docs:updated", docPath });
+          return new Response(JSON.stringify({ success: true }), { headers });
+        } else if (type === "docs:refresh") {
+          broadcast({ type: "docs:refresh" });
+          return new Response(JSON.stringify({ success: true }), { headers });
+        }
+        return new Response(JSON.stringify({ success: false, error: "Invalid notify request" }), {
+          status: 400,
+          headers
+        });
+      } catch (error) {
+        console.error("[Server] Notify error:", error);
+        return new Response(JSON.stringify({ error: String(error) }), {
+          status: 500,
+          headers
+        });
+      }
+    }
     if (url.pathname === "/api/docs" && req.method === "GET") {
-      const docsDir = join9(store.projectRoot, ".knowns", "docs");
-      if (!existsSync6(docsDir)) {
+      const docsDir = join10(store.projectRoot, ".knowns", "docs");
+      if (!existsSync7(docsDir)) {
         return new Response(JSON.stringify({ docs: [] }), { headers });
       }
       const mdFiles = await findMarkdownFiles(docsDir, docsDir);
       const docs = await Promise.all(mdFiles.map(async (relativePath) => {
-        const fullPath = join9(docsDir, relativePath);
+        const fullPath = join10(docsDir, relativePath);
         const content = await readFile3(fullPath, "utf-8");
         const { data, content: docContent } = import_gray_matter3.default(content);
         const pathParts = relativePath.split("/");
@@ -14310,9 +14733,88 @@ async function handleAPI(req, url, store, broadcast) {
       }));
       return new Response(JSON.stringify({ docs }), { headers });
     }
+    if (url.pathname.startsWith("/api/docs/") && req.method === "GET") {
+      const docPath = decodeURIComponent(url.pathname.replace("/api/docs/", ""));
+      const docsDir = join10(store.projectRoot, ".knowns", "docs");
+      const fullPath = join10(docsDir, docPath);
+      if (!fullPath.startsWith(docsDir)) {
+        return new Response(JSON.stringify({ error: "Invalid path" }), {
+          status: 400,
+          headers
+        });
+      }
+      if (!existsSync7(fullPath)) {
+        return new Response(JSON.stringify({ error: "Document not found" }), {
+          status: 404,
+          headers
+        });
+      }
+      const content = await readFile3(fullPath, "utf-8");
+      const { data, content: docContent } = import_gray_matter3.default(content);
+      const pathParts = docPath.split("/");
+      const filename = pathParts[pathParts.length - 1];
+      const folder = pathParts.length > 1 ? pathParts.slice(0, -1).join("/") : "";
+      const doc = {
+        filename,
+        path: docPath,
+        folder,
+        title: data.title || filename.replace(/\.md$/, ""),
+        description: data.description || "",
+        tags: data.tags || [],
+        metadata: data,
+        content: docContent
+      };
+      return new Response(JSON.stringify(doc), { headers });
+    }
+    if (url.pathname.startsWith("/api/docs/") && req.method === "PUT") {
+      const docPath = decodeURIComponent(url.pathname.replace("/api/docs/", ""));
+      const docsDir = join10(store.projectRoot, ".knowns", "docs");
+      const fullPath = join10(docsDir, docPath);
+      if (!fullPath.startsWith(docsDir)) {
+        return new Response(JSON.stringify({ error: "Invalid path" }), {
+          status: 400,
+          headers
+        });
+      }
+      if (!existsSync7(fullPath)) {
+        return new Response(JSON.stringify({ error: "Document not found" }), {
+          status: 404,
+          headers
+        });
+      }
+      const data = await req.json();
+      const { content, title, description, tags } = data;
+      const existingContent = await readFile3(fullPath, "utf-8");
+      const { data: existingData } = import_gray_matter3.default(existingContent);
+      const now = new Date().toISOString();
+      const updatedFrontmatter = {
+        ...existingData,
+        title: title ?? existingData.title,
+        description: description ?? existingData.description,
+        tags: tags ?? existingData.tags,
+        updatedAt: now
+      };
+      const newFileContent = import_gray_matter3.default.stringify(content ?? "", updatedFrontmatter);
+      await writeFile2(fullPath, newFileContent, "utf-8");
+      const pathParts = docPath.split("/");
+      const filename = pathParts[pathParts.length - 1];
+      const folder = pathParts.length > 1 ? pathParts.slice(0, -1).join("/") : "";
+      const updatedDoc = {
+        filename,
+        path: docPath,
+        folder,
+        title: updatedFrontmatter.title || filename.replace(/\.md$/, ""),
+        description: updatedFrontmatter.description || "",
+        tags: updatedFrontmatter.tags || [],
+        metadata: updatedFrontmatter,
+        content: content ?? ""
+      };
+      broadcast({ type: "docs:updated", doc: updatedDoc });
+      return new Response(JSON.stringify(updatedDoc), { headers });
+    }
     if (url.pathname === "/api/docs" && req.method === "POST") {
-      const docsDir = join9(store.projectRoot, ".knowns", "docs");
-      if (!existsSync6(docsDir)) {
+      const docsDir = join10(store.projectRoot, ".knowns", "docs");
+      if (!existsSync7(docsDir)) {
         await mkdir5(docsDir, { recursive: true });
       }
       const data = await req.json();
@@ -14328,16 +14830,16 @@ async function handleAPI(req, url, store, broadcast) {
       let targetDir;
       if (folder?.trim()) {
         const cleanFolder = folder.trim().replace(/^\/+|\/+$/g, "");
-        targetDir = join9(docsDir, cleanFolder);
-        filepath = join9(targetDir, filename);
+        targetDir = join10(docsDir, cleanFolder);
+        filepath = join10(targetDir, filename);
       } else {
         targetDir = docsDir;
-        filepath = join9(docsDir, filename);
+        filepath = join10(docsDir, filename);
       }
-      if (!existsSync6(targetDir)) {
+      if (!existsSync7(targetDir)) {
         await mkdir5(targetDir, { recursive: true });
       }
-      if (existsSync6(filepath)) {
+      if (existsSync7(filepath)) {
         return new Response(JSON.stringify({ error: "Document with this title already exists in this folder" }), {
           status: 409,
           headers
@@ -14362,8 +14864,8 @@ async function handleAPI(req, url, store, broadcast) {
       }), { status: 201, headers });
     }
     if (url.pathname === "/api/config" && req.method === "GET") {
-      const configPath = join9(store.projectRoot, ".knowns", "config.json");
-      if (!existsSync6(configPath)) {
+      const configPath = join10(store.projectRoot, ".knowns", "config.json");
+      if (!existsSync7(configPath)) {
         return new Response(JSON.stringify({
           config: {
             name: "Knowns",
@@ -14390,9 +14892,9 @@ async function handleAPI(req, url, store, broadcast) {
     }
     if (url.pathname === "/api/config" && req.method === "POST") {
       const config = await req.json();
-      const configPath = join9(store.projectRoot, ".knowns", "config.json");
+      const configPath = join10(store.projectRoot, ".knowns", "config.json");
       let existingData = {};
-      if (existsSync6(configPath)) {
+      if (existsSync7(configPath)) {
         const content = await readFile3(configPath, "utf-8");
         existingData = JSON.parse(content);
       }
@@ -14405,6 +14907,33 @@ async function handleAPI(req, url, store, broadcast) {
       await writeFile2(configPath, JSON.stringify(merged, null, 2), "utf-8");
       return new Response(JSON.stringify({ success: true }), { headers });
     }
+    if (url.pathname === "/api/activities" && req.method === "GET") {
+      const limit = Number.parseInt(url.searchParams.get("limit") || "50", 10);
+      const type = url.searchParams.get("type");
+      const tasks = await store.getAllTasks();
+      const allActivities = [];
+      for (const task of tasks) {
+        const versions = await store.getTaskVersionHistory(task.id);
+        for (const version of versions) {
+          if (type) {
+            const hasMatchingChange = version.changes.some((c) => c.field === type);
+            if (!hasMatchingChange)
+              continue;
+          }
+          allActivities.push({
+            taskId: task.id,
+            taskTitle: task.title,
+            version: version.version,
+            timestamp: version.timestamp,
+            author: version.author,
+            changes: version.changes
+          });
+        }
+      }
+      allActivities.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+      const limited = allActivities.slice(0, limit);
+      return new Response(JSON.stringify({ activities: limited }), { headers });
+    }
     if (url.pathname === "/api/search" && req.method === "GET") {
       const query = url.searchParams.get("q");
       if (!query) {
@@ -14424,12 +14953,12 @@ async function handleAPI(req, url, store, broadcast) {
         ].join(" ").toLowerCase();
         return searchText.includes(q);
       });
-      const docsDir = join9(store.projectRoot, ".knowns", "docs");
+      const docsDir = join10(store.projectRoot, ".knowns", "docs");
       const docResults = [];
-      if (existsSync6(docsDir)) {
+      if (existsSync7(docsDir)) {
         const mdFiles = await findMarkdownFiles(docsDir, docsDir);
         for (const relativePath of mdFiles) {
-          const fullPath = join9(docsDir, relativePath);
+          const fullPath = join10(docsDir, relativePath);
           const content = await readFile3(fullPath, "utf-8");
           const { data, content: docContent } = import_gray_matter3.default(content);
           const searchText = `${data.title || ""} ${data.description || ""} ${data.tags?.join(" ") || ""} ${docContent}`.toLowerCase();
@@ -14464,18 +14993,42 @@ async function handleAPI(req, url, store, broadcast) {
 }
 
 // src/commands/browser.ts
-var browserCommand = new Command("browser").description("Open web UI for task management").option("-p, --port <port>", "Port number", "6420").option("--no-open", "Don't open browser automatically").action(async (options2) => {
+var DEFAULT_PORT2 = 6420;
+var CONFIG_FILE = ".knowns/config.json";
+async function saveServerPort(projectRoot, port) {
+  const configPath = join11(projectRoot, CONFIG_FILE);
+  const knownsDir = join11(projectRoot, ".knowns");
+  if (!existsSync8(knownsDir)) {
+    await mkdir6(knownsDir, { recursive: true });
+  }
+  try {
+    let config = {};
+    if (existsSync8(configPath)) {
+      const content = await readFile4(configPath, "utf-8");
+      config = JSON.parse(content);
+    }
+    const settings = config.settings || {};
+    settings.serverPort = port;
+    config.settings = settings;
+    await writeFile3(configPath, JSON.stringify(config, null, 2), "utf-8");
+  } catch {}
+}
+var browserCommand = new Command("browser").description("Open web UI for task management").option("-p, --port <port>", "Port number", String(DEFAULT_PORT2)).option("--no-open", "Don't open browser automatically").action(async (options2) => {
   const projectRoot = findProjectRoot();
   if (!projectRoot) {
     console.error(source_default.red("\u2717 Not in a Knowns project"));
     console.log(source_default.gray("Run 'knowns init' to initialize a project"));
     process.exit(1);
   }
+  const port = Number.parseInt(options2.port);
+  if (options2.port !== String(DEFAULT_PORT2)) {
+    await saveServerPort(projectRoot, port);
+  }
   console.log(source_default.cyan("\u25C6 Starting Knowns.dev Web UI..."));
   console.log("");
   try {
     await startServer({
-      port: Number.parseInt(options2.port),
+      port,
       projectRoot,
       open: options2.open
     });
@@ -14487,17 +15040,17 @@ var browserCommand = new Command("browser").description("Open web UI for task ma
   }
 });
 // src/commands/doc.ts
-import { existsSync as existsSync7 } from "fs";
-import { mkdir as mkdir6, readFile as readFile4, readdir as readdir5, writeFile as writeFile3 } from "fs/promises";
-import { join as join10 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { mkdir as mkdir7, readFile as readFile5, readdir as readdir5, writeFile as writeFile4 } from "fs/promises";
+import { join as join12 } from "path";
 var import_gray_matter4 = __toESM(require_gray_matter(), 1);
-var DOCS_DIR = join10(process.cwd(), ".knowns", "docs");
+var DOCS_DIR = join12(process.cwd(), ".knowns", "docs");
 async function getAllMdFiles(dir, basePath = "") {
   const files = [];
   const entries = await readdir5(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join10(dir, entry.name);
-    const relativePath = basePath ? join10(basePath, entry.name) : entry.name;
+    const fullPath = join12(dir, entry.name);
+    const relativePath = basePath ? join12(basePath, entry.name) : entry.name;
     if (entry.isDirectory()) {
       const subFiles = await getAllMdFiles(fullPath, relativePath);
       files.push(...subFiles);
@@ -14508,20 +15061,30 @@ async function getAllMdFiles(dir, basePath = "") {
   return files;
 }
 async function ensureDocsDir() {
-  if (!existsSync7(DOCS_DIR)) {
-    await mkdir6(DOCS_DIR, { recursive: true });
+  if (!existsSync9(DOCS_DIR)) {
+    await mkdir7(DOCS_DIR, { recursive: true });
   }
 }
 function titleToFilename(title) {
   return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
-var createCommand3 = new Command("create").description("Create a new documentation file").argument("<title>", "Document title").option("-d, --description <text>", "Document description").option("-t, --tags <tags>", "Comma-separated tags").option("--plain", "Plain text output for AI").action(async (title, options2) => {
+var createCommand3 = new Command("create").description("Create a new documentation file").argument("<title>", "Document title").option("-d, --description <text>", "Document description").option("-t, --tags <tags>", "Comma-separated tags").option("-f, --folder <path>", "Folder path (e.g., guides, patterns/auth)").option("--plain", "Plain text output for AI").action(async (title, options2) => {
   try {
     await ensureDocsDir();
     const filename = `${titleToFilename(title)}.md`;
-    const filepath = join10(DOCS_DIR, filename);
-    if (existsSync7(filepath)) {
-      console.error(source_default.red(`\u2717 Document already exists: ${filename}`));
+    let targetDir = DOCS_DIR;
+    let relativePath = filename;
+    if (options2.folder) {
+      const folderPath = options2.folder.replace(/^\/|\/$/g, "");
+      targetDir = join12(DOCS_DIR, folderPath);
+      relativePath = join12(folderPath, filename);
+      if (!existsSync9(targetDir)) {
+        await mkdir7(targetDir, { recursive: true });
+      }
+    }
+    const filepath = join12(targetDir, filename);
+    if (existsSync9(filepath)) {
+      console.error(source_default.red(`\u2717 Document already exists: ${relativePath}`));
       process.exit(1);
     }
     const now = new Date().toISOString();
@@ -14540,11 +15103,12 @@ var createCommand3 = new Command("create").description("Create a new documentati
 
 Write your documentation here.
 `, metadata);
-    await writeFile3(filepath, content, "utf-8");
+    await writeFile4(filepath, content, "utf-8");
+    await notifyDocUpdate(relativePath);
     if (options2.plain) {
-      console.log(`Created: ${filename}`);
+      console.log(`Created: ${relativePath}`);
     } else {
-      console.log(source_default.green(`\u2713 Created documentation: ${source_default.bold(filename)}`));
+      console.log(source_default.green(`\u2713 Created documentation: ${source_default.bold(relativePath)}`));
       console.log(source_default.gray(`  Location: ${filepath}`));
     }
   } catch (error) {
@@ -14567,7 +15131,7 @@ var listCommand2 = new Command("list").description("List all documentation files
     }
     const docs = [];
     for (const file of mdFiles) {
-      const content = await readFile4(join10(DOCS_DIR, file), "utf-8");
+      const content = await readFile5(join12(DOCS_DIR, file), "utf-8");
       const { data } = import_gray_matter4.default(content);
       docs.push({
         filename: file,
@@ -14626,12 +15190,12 @@ var viewCommand2 = new Command("view").description("View a documentation file").
   try {
     await ensureDocsDir();
     let filename = name.endsWith(".md") ? name : `${name}.md`;
-    let filepath = join10(DOCS_DIR, filename);
-    if (!existsSync7(filepath)) {
+    let filepath = join12(DOCS_DIR, filename);
+    if (!existsSync9(filepath)) {
       filename = `${titleToFilename(name)}.md`;
-      filepath = join10(DOCS_DIR, filename);
+      filepath = join12(DOCS_DIR, filename);
     }
-    if (!existsSync7(filepath)) {
+    if (!existsSync9(filepath)) {
       const allFiles = await getAllMdFiles(DOCS_DIR);
       const searchName = name.toLowerCase().replace(/\.md$/, "");
       const matchingFile = allFiles.find((file) => {
@@ -14641,14 +15205,14 @@ var viewCommand2 = new Command("view").description("View a documentation file").
       });
       if (matchingFile) {
         filename = matchingFile;
-        filepath = join10(DOCS_DIR, matchingFile);
+        filepath = join12(DOCS_DIR, matchingFile);
       }
     }
-    if (!existsSync7(filepath)) {
+    if (!existsSync9(filepath)) {
       console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
       process.exit(1);
     }
-    const fileContent = await readFile4(filepath, "utf-8");
+    const fileContent = await readFile5(filepath, "utf-8");
     const { data, content } = import_gray_matter4.default(fileContent);
     const metadata = data;
     if (options2.plain) {
@@ -14701,6 +15265,13 @@ var viewCommand2 = new Command("view").description("View a documentation file").
       for (const { original, resolved } of linksToAdd) {
         enhancedContent = enhancedContent.replace(original, resolved);
       }
+      const knownProjectRoot = findProjectRoot();
+      if (knownProjectRoot) {
+        const fileStore = new FileStore(knownProjectRoot);
+        const allTasks = await fileStore.getAllTasks();
+        const taskMap = buildTaskMap(allTasks);
+        enhancedContent = transformMentionsToRefs(enhancedContent, taskMap);
+      }
       console.log(enhancedContent);
     } else {
       console.log(source_default.bold(`
@@ -14723,20 +15294,34 @@ var viewCommand2 = new Command("view").description("View a documentation file").
     process.exit(1);
   }
 });
-var editCommand2 = new Command("edit").description("Edit a documentation file metadata").argument("<name>", "Document name").option("-t, --title <text>", "New title").option("-d, --description <text>", "New description").option("--tags <tags>", "Comma-separated tags").action(async (name, options2) => {
+var editCommand2 = new Command("edit").description("Edit a documentation file (metadata and content)").argument("<name>", "Document name or path (e.g., guides/my-doc)").option("-t, --title <text>", "New title").option("-d, --description <text>", "New description").option("--tags <tags>", "Comma-separated tags").option("-c, --content <text>", "Replace content").option("-a, --append <text>", "Append to content").option("--plain", "Plain text output for AI").action(async (name, options2) => {
   try {
     await ensureDocsDir();
     let filename = name.endsWith(".md") ? name : `${name}.md`;
-    let filepath = join10(DOCS_DIR, filename);
-    if (!existsSync7(filepath)) {
-      filename = `${titleToFilename(name)}.md`;
-      filepath = join10(DOCS_DIR, filename);
+    let filepath = join12(DOCS_DIR, filename);
+    if (!existsSync9(filepath)) {
+      const baseName = name.includes("/") ? name : titleToFilename(name);
+      filename = baseName.endsWith(".md") ? baseName : `${baseName}.md`;
+      filepath = join12(DOCS_DIR, filename);
     }
-    if (!existsSync7(filepath)) {
+    if (!existsSync9(filepath)) {
+      const allFiles = await getAllMdFiles(DOCS_DIR);
+      const searchName = name.toLowerCase().replace(/\.md$/, "");
+      const matchingFile = allFiles.find((file) => {
+        const fileNameOnly = file.toLowerCase().replace(/\.md$/, "");
+        const fileBaseName = file.split("/").pop()?.toLowerCase().replace(/\.md$/, "");
+        return fileNameOnly === searchName || fileBaseName === searchName || file === name;
+      });
+      if (matchingFile) {
+        filename = matchingFile;
+        filepath = join12(DOCS_DIR, matchingFile);
+      }
+    }
+    if (!existsSync9(filepath)) {
       console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
       process.exit(1);
     }
-    const fileContent = await readFile4(filepath, "utf-8");
+    const fileContent = await readFile5(filepath, "utf-8");
     const { data, content } = import_gray_matter4.default(fileContent);
     const metadata = data;
     if (options2.title)
@@ -14746,9 +15331,23 @@ var editCommand2 = new Command("edit").description("Edit a documentation file me
     if (options2.tags)
       metadata.tags = options2.tags.split(",").map((t) => t.trim());
     metadata.updatedAt = new Date().toISOString();
-    const newContent = import_gray_matter4.default.stringify(content, metadata);
-    await writeFile3(filepath, newContent, "utf-8");
-    console.log(source_default.green(`\u2713 Updated documentation: ${source_default.bold(filename)}`));
+    let updatedContent = content;
+    if (options2.content) {
+      updatedContent = options2.content;
+    }
+    if (options2.append) {
+      updatedContent = `${content.trimEnd()}
+
+${options2.append}`;
+    }
+    const newFileContent = import_gray_matter4.default.stringify(updatedContent, metadata);
+    await writeFile4(filepath, newFileContent, "utf-8");
+    await notifyDocUpdate(filename);
+    if (options2.plain) {
+      console.log(`Updated: ${filename}`);
+    } else {
+      console.log(source_default.green(`\u2713 Updated documentation: ${source_default.bold(filename)}`));
+    }
   } catch (error) {
     console.error(source_default.red("Error editing documentation:"), error instanceof Error ? error.message : String(error));
     process.exit(1);
@@ -14756,9 +15355,9 @@ var editCommand2 = new Command("edit").description("Edit a documentation file me
 });
 var docCommand = new Command("doc").description("Manage documentation").addCommand(createCommand3).addCommand(listCommand2).addCommand(viewCommand2).addCommand(editCommand2);
 // src/commands/config.ts
-import { existsSync as existsSync8 } from "fs";
-import { mkdir as mkdir7, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
-import { join as join11 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { mkdir as mkdir8, readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
+import { join as join13 } from "path";
 
 // node_modules/zod/v4/classic/external.js
 var exports_external = {};
@@ -28173,20 +28772,22 @@ function date4(params) {
 // node_modules/zod/v4/classic/external.js
 config(en_default());
 // src/commands/config.ts
-var CONFIG_FILE = ".knowns/config.json";
+var CONFIG_FILE2 = ".knowns/config.json";
 var ConfigSchema = exports_external.object({
   defaultAssignee: exports_external.string().optional(),
   defaultPriority: exports_external.enum(["low", "medium", "high"]).optional(),
   defaultLabels: exports_external.array(exports_external.string()).optional(),
   timeFormat: exports_external.enum(["12h", "24h"]).optional(),
   editor: exports_external.string().optional(),
-  visibleColumns: exports_external.array(exports_external.enum(["todo", "in-progress", "in-review", "done", "blocked"])).optional()
+  visibleColumns: exports_external.array(exports_external.enum(["todo", "in-progress", "in-review", "done", "blocked"])).optional(),
+  serverPort: exports_external.number().optional()
 });
 var DEFAULT_CONFIG = {
   defaultPriority: "medium",
   defaultLabels: [],
   timeFormat: "24h",
-  visibleColumns: ["todo", "in-progress", "done"]
+  visibleColumns: ["todo", "in-progress", "done"],
+  serverPort: 6420
 };
 function getProjectRoot2() {
   const projectRoot = findProjectRoot();
@@ -28198,12 +28799,12 @@ function getProjectRoot2() {
   return projectRoot;
 }
 async function loadConfig(projectRoot) {
-  const configPath = join11(projectRoot, CONFIG_FILE);
-  if (!existsSync8(configPath)) {
+  const configPath = join13(projectRoot, CONFIG_FILE2);
+  if (!existsSync10(configPath)) {
     return { ...DEFAULT_CONFIG };
   }
   try {
-    const content = await readFile5(configPath, "utf-8");
+    const content = await readFile6(configPath, "utf-8");
     const data = JSON.parse(content);
     const settings = data.settings || {};
     const validated = ConfigSchema.parse(settings);
@@ -28217,22 +28818,22 @@ async function loadConfig(projectRoot) {
   }
 }
 async function saveConfig(projectRoot, config2) {
-  const configPath = join11(projectRoot, CONFIG_FILE);
-  const knownsDir = join11(projectRoot, ".knowns");
-  if (!existsSync8(knownsDir)) {
-    await mkdir7(knownsDir, { recursive: true });
+  const configPath = join13(projectRoot, CONFIG_FILE2);
+  const knownsDir = join13(projectRoot, ".knowns");
+  if (!existsSync10(knownsDir)) {
+    await mkdir8(knownsDir, { recursive: true });
   }
   try {
     let existingData = {};
-    if (existsSync8(configPath)) {
-      const content = await readFile5(configPath, "utf-8");
+    if (existsSync10(configPath)) {
+      const content = await readFile6(configPath, "utf-8");
       existingData = JSON.parse(content);
     }
     const merged = {
       ...existingData,
       settings: config2
     };
-    await writeFile4(configPath, JSON.stringify(merged, null, 2), "utf-8");
+    await writeFile5(configPath, JSON.stringify(merged, null, 2), "utf-8");
   } catch (error46) {
     console.error(source_default.red("\u2717 Failed to save config"));
     if (error46 instanceof Error) {
@@ -28374,9 +28975,94 @@ 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);
+// package.json
+var package_default = {
+  name: "knowns",
+  version: "0.1.6",
+  description: "CLI tool for dev teams to manage tasks and documentation",
+  module: "index.ts",
+  type: "module",
+  bin: {
+    knowns: "./dist/index.js",
+    kn: "./dist/index.js"
+  },
+  main: "./dist/index.js",
+  files: ["dist", "CLAUDE.md", "README.md", "CHANGELOG.md", "LICENSE"],
+  keywords: ["cli", "task-management", "documentation", "knowledge-base", "team-tools", "developer-tools"],
+  author: "howznguyen <howznguyen@knowns.dev>",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/knowns-dev/knowns.git"
+  },
+  homepage: "https://knowns.dev",
+  bugs: {
+    url: "https://github.com/knowns-dev/knowns/issues"
+  },
+  scripts: {
+    dev: "bun run --watch src/index.ts browser --no-open",
+    watch: "nodemon",
+    build: "bun run build:cli && bun run build:ui",
+    "build:cli": "bun build src/index.ts --outdir dist --target bun && bun build src/mcp/server.ts --outdir dist/mcp --target bun",
+    "build:ui": "vite build",
+    start: "bun run src/index.ts",
+    mcp: "bun run src/mcp/server.ts",
+    test: "bun test",
+    lint: "biome check .",
+    "lint:fix": "biome check --write .",
+    format: "biome format --write .",
+    prepare: "husky"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-navigation-menu": "^1.2.14",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@uiw/react-md-editor": "^4.0.11",
+    chalk: "^5.3.0",
+    "class-variance-authority": "^0.7.1",
+    clsx: "^2.1.1",
+    cmdk: "^1.1.1",
+    commander: "^12.1.0",
+    "gray-matter": "^4.0.3",
+    "lucide-react": "^0.562.0",
+    marked: "^17.0.1",
+    prompts: "^2.4.2",
+    react: "^19.2.3",
+    "react-diff-viewer": "^3.1.1",
+    "react-dom": "^19.2.3",
+    "tailwind-merge": "^3.4.0",
+    turndown: "^7.2.2",
+    "unist-util-visit": "^5.0.0",
+    zod: "^4.2.1"
+  },
+  devDependencies: {
+    "@biomejs/biome": "^1.9.4",
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/bun": "latest",
+    "@types/prompts": "^2.4.9",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    autoprefixer: "^10.4.23",
+    concurrently: "^9.2.1",
+    husky: "^9.1.7",
+    "lint-staged": "^15.2.10",
+    nodemon: "^3.1.11",
+    tailwindcss: "^4.1.18",
+    typescript: "^5.7.2",
+    vite: "^7.3.0"
+  }
+};
+
 // src/index.ts
 var program2 = new Command;
-program2.name("knowns").description("CLI tool for dev teams to manage tasks, track time, and sync").version("0.1.2");
+program2.name("knowns").description("CLI tool for dev teams to manage tasks, track time, and sync").version(package_default.version);
 program2.addCommand(initCommand);
 program2.addCommand(taskCommand);
 program2.addCommand(boardCommand);