knowns 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to Knowns will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-01-06
+
+### Added
+
+- **Git Tracking Mode**: Select tracking mode during `knowns init`
+  - `git-tracked` (default): All `.knowns/` files tracked in git (recommended for teams)
+  - `git-ignored`: Only docs tracked, tasks/config ignored (personal use)
+  - Automatically updates `.gitignore` for git-ignored mode
+- **SSE Auto-Reconnection**: Web UI automatically refreshes data on reconnect
+  - Detects when connection is restored after sleep/wake
+  - Triggers `tasks:refresh`, `time:refresh`, `docs:refresh` events
+- **New Docs**: Added feature documentation
+  - `features/git-tracking-modes.md` - Git tracking modes explained
+  - `features/real-time-sync.md` - SSE sync and reconnection behavior
+
+### Changed
+
+- **WebSocket → SSE**: Migrated real-time updates from WebSocket to Server-Sent Events
+  - Simpler protocol with built-in auto-reconnect
+  - Better firewall compatibility (standard HTTP)
+- **Init requires Git**: `knowns init` now checks for `.git` directory and exits with helpful message if not found
+- **Documentation Updates**:
+  - All docs translated to English
+  - Updated architecture diagrams (WebSocket → SSE)
+  - Added `--plain` flag clarification (only for view/list/search commands)
+  - Added doc organization guide (core docs at root, categorized in folders)
+
+### Fixed
+
+- **Guidelines clarity**: Updated CLI/MCP templates to clarify `--plain` flag usage
+  - `--plain` only works with view/list/search commands
+  - Create/edit commands do NOT support `--plain`
+
 ## [0.5.0] - 2025-01-04
 
 ### Added

package/CLAUDE.md

@@ -1,5 +1,3 @@
-/Users/howznguyen/Workspaces/Knowns/knowns/src/templates/knowns-guidelines-cli.md
-
 <!-- KNOWNS GUIDELINES START -->
 # Knowns CLI Guidelines
 
@@ -561,6 +559,26 @@ knowns doc edit "Doc Name" -c "New content"        # Replace content
 knowns doc edit "Doc Name" -a "Appended content"   # Append to content
 ```
 
+#### Doc Organization
+
+| Doc Type | Location | Example |
+|----------|----------|---------|
+| **Important/Core docs** | Root `.knowns/docs/` | `README.md`, `ARCHITECTURE.md`, `CONVENTIONS.md` |
+| **Guides** | `.knowns/docs/guides/` | `guides/getting-started.md` |
+| **Patterns** | `.knowns/docs/patterns/` | `patterns/controller.md` |
+| **API docs** | `.knowns/docs/api/` | `api/endpoints.md` |
+| **Other categorized docs** | `.knowns/docs/<category>/` | `security/auth-patterns.md` |
+
+```bash
+# Important docs - at root (no -f flag)
+knowns doc create "README" -d "Project overview" -t "core"
+knowns doc create "ARCHITECTURE" -d "System design" -t "core"
+
+# Categorized docs - use -f for folder
+knowns doc create "Getting Started" -d "Setup guide" -t "guide" -f "guides"
+knowns doc create "Controller Pattern" -d "MVC pattern" -t "pattern" -f "patterns"
+```
+
 ### Search
 
 ```bash
@@ -746,6 +764,83 @@ Use **lowercase with hyphens**:
 | See `@.knowns/docs/...` but don't read | Use `knowns doc "<path>" --plain` |
 | See `@.knowns/tasks/task-X` but don't check | Use `knowns task X --plain` for context |
 | Follow only first-level refs | Recursively follow nested refs until complete |
+| Use `--plain` with `task create` | `--plain` is only for view/list commands |
+| Use `--plain` with `task edit` | `--plain` is only for view/list commands |
+| Use `--plain` with `doc create` | `--plain` is only for view/list commands |
+| Use `--plain` with `doc edit` | `--plain` is only for view/list commands |
+
+---
+
+## The `--plain` Flag (AI Agents)
+
+> **⚠️ CRITICAL FOR AI AGENTS**: The `--plain` flag is ONLY supported by **view/list/search** commands. Using it with create/edit commands will cause errors!
+
+### ✅ Commands that support `--plain`
+
+These are **read-only** commands - use `--plain` to get clean output:
+
+```bash
+# Task viewing/listing
+knowns task <id> --plain
+knowns task view <id> --plain
+knowns task list --plain
+knowns task list --status in-progress --plain
+
+# Doc viewing/listing
+knowns doc <path> --plain
+knowns doc view "<path>" --plain
+knowns doc list --plain
+knowns doc list --tag <tag> --plain
+
+# Search
+knowns search "<query>" --plain
+knowns search "<query>" --type task --plain
+knowns search "<query>" --type doc --plain
+
+# Config
+knowns config get <key> --plain
+```
+
+### ❌ Commands that do NOT support `--plain`
+
+These are **write** commands - NEVER use `--plain`:
+
+```bash
+# Task create/edit - NO --plain!
+knowns task create "Title" -d "Description"          # ✅ Correct
+knowns task create "Title" --plain                   # ❌ ERROR!
+knowns task edit <id> -s done                        # ✅ Correct
+knowns task edit <id> -s done --plain                # ❌ ERROR!
+
+# Doc create/edit - NO --plain!
+knowns doc create "Title" -d "Description"           # ✅ Correct
+knowns doc create "Title" --plain                    # ❌ ERROR!
+knowns doc edit "name" -c "content"                  # ✅ Correct
+knowns doc edit "name" -c "content" --plain          # ❌ ERROR!
+
+# Time tracking - NO --plain!
+knowns time start <id>                               # ✅ Correct
+knowns time stop                                     # ✅ Correct
+knowns time add <id> 2h                              # ✅ Correct
+```
+
+### Quick Reference Table
+
+| Command Type | Example | `--plain` Support |
+|-------------|---------|-------------------|
+| `task <id>` | `knowns task 42 --plain` | ✅ Yes |
+| `task list` | `knowns task list --plain` | ✅ Yes |
+| `task create` | `knowns task create "Title"` | ❌ No |
+| `task edit` | `knowns task edit 42 -s done` | ❌ No |
+| `doc <path>` | `knowns doc "README" --plain` | ✅ Yes |
+| `doc list` | `knowns doc list --plain` | ✅ Yes |
+| `doc create` | `knowns doc create "Title"` | ❌ No |
+| `doc edit` | `knowns doc edit "name" -c "..."` | ❌ No |
+| `search` | `knowns search "query" --plain` | ✅ Yes |
+| `time start/stop` | `knowns time start 42` | ❌ No |
+| `time add` | `knowns time add 42 2h` | ❌ No |
+| `config get` | `knowns config get key --plain` | ✅ Yes |
+| `config set` | `knowns config set key value` | ❌ No |
 
 ---
 
@@ -902,11 +997,3 @@ knowns doc edit "doc-name" -a "Appended content"
 <!-- KNOWNS GUIDELINES END -->
 
 
-
-
-
-
-
-
-
-