Release Notes

# Changelog

Stay up to date with all the latest features, improvements, and bug fixes in Knowns CLI.

[npmv0.20.5](https://www.npmjs.com/package/knowns) [GitHub30 releases](https://github.com/knowns-dev/knowns/releases)

v0.20.5Latest

April 30, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.20.5)

# v0.20.5

## Highlights

Major code ingest performance boost — batch embedding with length-sorted content and parser pooling cuts ingest time from ~1m27s to ~17s (5× speedup). Adds Java, Rust, and C# language support to the AST indexer. Expands `knowns mcp setup` to support 10 platforms via a unified registry pattern, including new Cline, Continue, Claude Desktop, and Gemini CLI targets.

* * *

### Added

- **Java, Rust, C# language support** — AST indexer now parses `.java`, `.rs`, and `.cs` files via tree-sitter CGO bindings, extracting symbols (classes, structs, enums, traits, impl blocks, constructors) and edges (imports, method ownership)
- **Cline platform support** — `knowns mcp setup cline` generates `.cline/mcp_settings.json` with Knowns MCP server config
- **Continue platform support** — `knowns mcp setup continue` generates Continue MCP config
- **Claude Desktop platform support** — `knowns mcp setup claude-desktop` generates global Claude Desktop MCP config
- **Gemini CLI platform support** — `knowns mcp setup gemini` generates global Gemini CLI MCP config
- **Unified MCP platform registry** — all 10 platforms (Claude Code, Kiro, OpenCode, Cursor, Codex, Cline, Continue, Claude Desktop, Antigravity, Gemini CLI) managed through a single `mcpPlatform` registry with consistent setup interface

### Improved

- **5× code ingest speedup** — batch embedding with length-sorted content minimizes padding waste in ONNX inference; adaptive batch sizes (64 for short content, 32 for long) balance throughput and memory
- **Parser instance pooling** — tree-sitter parsers are reused via per-extension pools, eliminating alloc/dealloc overhead per file
- **Compact embedding content** — classes embed as signature + member signature list instead of full source code; functions embed as signature + edge summary. Content truncated to ~2000 chars (model's effective window) to save tokenizer CPU
- **Audit page expandable events** — audit event rows now expand to show argument summaries and project root details
- **Code graph page improvements** — layout and interaction refinements
- **Memory page resilience** — removed dependency on `/api/working-memories` route that caused silent page failure; page now loads reliably with persistent memories only

### Fixed

- **Memory page silent failure** — `MemoryPage` crashed silently when `Promise.all` included a call to the non-existent `/api/working-memories` endpoint; removed the broken call
- **Watch command stale ingest reference** — corrected `knowns ingest` → `knowns code ingest` in the semantic search warning message
- **E2E test flaky port allocation** — `findPort()` generated random port numbers without checking availability, causing server startup timeouts on CI. Now uses OS-assigned port via `net.createServer()` bound to port 0
- **E2E server startup diagnostics** — increased `waitForServer` timeout from 15s to 30s and added stderr capture for better failure messages

### Dependencies

- Added `tree-sitter-java`, `tree-sitter-rust`, `tree-sitter-c-sharp` Go bindings

* * *

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.20.4...v0.20.5](https://github.com/knowns-dev/knowns/compare/v0.20.4...v0.20.5)

v0.20.4

April 28, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.20.4)

# v0.20.4

## Highlights

Fixes a critical MCP server crash caused by the ONNX Runtime native library accessing freed memory. The crash occurred when `Embedder.Close()` destroyed the process-global ONNX environment while background indexing goroutines were still active or about to reinitialize it.

* * *

### Fixed

- **MCP server crash — ONNX Runtime use-after-free** — `ORTRuntime.Close()` called `ort.DestroyEnvironment()` on every `Embedder.Close()`, tearing down the process-global ONNX C++ environment while other goroutines could still be using it. The fault address (`0x614d3a3a786e6e6f` → `onnx::Ma`) confirmed the crash was inside native ONNX code accessing freed memory. `Close()` now only releases the model session; the environment lives for the process lifetime.
- **ONNX environment initialization race condition** — `ensureORTEnvironment()` used a simple `IsInitialized()` check with no synchronization, allowing two goroutines to race into `InitializeEnvironment()` simultaneously. Now guarded by `sync.Once`.

* * *

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.20.3...v0.20.4](https://github.com/knowns-dev/knowns/compare/v0.20.3...v0.20.4)

v0.20.3

April 24, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.20.3)

# v0.20.3

## Highlights

Expands platform support to Cursor, Antigravity, and Codex with full MCP config and skill sync. Restructures the public documentation into English-first (`docs/en/`) and Vietnamese (`docs/vi/`) mirrors. Fixes MCP text field escaping so multiline content (plans, notes, descriptions) is stored correctly.

* * *

### Added

- **Cursor platform support** — `knowns init` and `knowns sync` now generate `.cursor/mcp.json` with the Knowns MCP server config; `knowns update` keeps it in sync after upgrades
- **Antigravity platform support** — generates `.agent/rules/knowns.md` guidance file and `~/.gemini/antigravity/mcp_config.json` MCP config during init and sync
- **Codex platform support** — generates `.codex/config.toml` with `[mcp_servers.knowns]` section during init and sync
- **`.agents/skills/` directory** — new repo-level skills directory used by OpenCode, Antigravity, and Codex (13 skills: kn-init, kn-plan, kn-implement, kn-commit, kn-research, kn-review, kn-spec, kn-go, kn-verify, kn-doc, kn-extract, kn-template, kn-debug)
- **Vietnamese README** — full `README.vi.md` translation alongside the English README
- **Bilingual documentation** — complete `docs/en/` and `docs/vi/` doc trees covering getting-started, guides, reference, integrations, and contributing

### Improved

- **MCP text field escaping** — new `textArg()` / `unescapeText()` helpers unescape literal `\n` and `\t` in MCP arguments, fixing multiline content for task descriptions, plans, notes, doc content, and memory entries
- **Semantic search type-aware availability** — search engine now checks embedder availability per search type (memory-only searches work even when the main ONNX embedder is not loaded), with nil-guard on `semanticSearch` and `semanticSearchSingleStore`
- **Init wizard narrow-terminal fallback** — automatically falls back to non-interactive defaults when terminal width < 90 columns, with a clear warning message
- **Init wizard alt-screen** — the interactive setup form now uses bubbletea's alt-screen mode for a cleaner experience
- **Skill sync for new platforms** — `SyncSkillsForPlatforms` distinguishes `.agents/skills/` (OpenCode, Antigravity, Codex) from legacy `.agent/skills/` (agents) with backwards-compatible detection
- **`knowns sync` platform config sync** — sync command now regenerates Cursor, Codex, and Antigravity configs alongside existing Claude/Kiro/OpenCode sync
- **`knowns update` MCP config sync** — update command syncs Cursor, Codex, and Antigravity MCP configs after binary upgrade
- **Windows shell command quoting** — `hookCommandPath` now properly quotes arguments and converts backslashes to forward slashes on Windows for Claude's bash-based command hooks

### Documentation

- **Restructured docs/** — migrated 14 flat docs into organized `docs/en/` and `docs/vi/` trees with categories: getting-started, guides, reference, integrations, contributing
- **New docs** — added compatibility matrix, guidance files reference, model management, sync reference, validate reference, AI agent guide, AI workflow guide, memory system guide, and platform integration mapping
- **Updated README** — expanded with Before & After comparison, Claude Code Skills workflow section, all skills table, and updated quick reference

### Testing

- **`init_test.go`** — comprehensive tests for init command including platform config generation, wizard fallback, and narrow-terminal detection
- **`skill_sync_test.go`** — tests for `.agents/skills/` vs `.agent/skills/` directory selection and legacy detection
- **`runtimeinstall_test.go`** — tests for shell command quoting and Windows path normalization
- **`search_test.go`** — tests for type-aware semantic availability checks

### Removed

- **`internal/cli/guidelines.go`** — removed standalone guidelines command (functionality merged into sync)
- **Root `.mcp.json`** — removed in favor of platform-specific MCP configs

* * *

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.20.2...v0.20.3](https://github.com/knowns-dev/knowns/compare/v0.20.2...v0.20.3)

v0.20.2

April 24, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.20.2)

# v0.20.2

## Highlights

Fixes ONNX Runtime architecture mismatch on Linux, improves `knowns update` with interactive install method detection, and adds ORT library to CI test environments.

* * *

### Fixed

- **ONNX Runtime architecture validation** — `ResolveORTLibraryPath()` now reads the ELF header to verify the shared library matches the host CPU architecture (x86\_64 vs aarch64), skipping wrong-arch files instead of letting `dlopen` fail with a cryptic error
- **CI: wrong-arch ORT bundled in Linux x64 package** — The build pipeline previously tried Go module `test_data` first, which only contains arm64 libs, potentially shipping an arm64 `.so` inside the x64 tarball. Now always downloads from official ONNX Runtime GitHub releases for all platforms
- **CI: ELF architecture verification** — Tarball verification step now checks `e_machine` in ELF headers to catch architecture mismatches before publishing
- **Self-update missing ORT library** — `knowns update` (script-managed) now copies `libonnxruntime.*` / `onnxruntime.dll` from the release tarball alongside the binary, preventing stale or missing native libs after upgrade

### Improved

- **Interactive install method detection** — `knowns update` now shows a bubbletea confirm prompt with the detected install method, with option to choose a different one from a selectable list (↑/↓ navigation, number keys, Esc/Ctrl+C to cancel)
- **Runtime-first detection** — Install method detection prioritizes binary path analysis over persisted `install.json` metadata, correctly handling cases where users switch install methods (e.g. script → Homebrew)
- **Cross-platform path detection** — Path matching normalizes separators for Windows compatibility, detecting npm/bun/pnpm/yarn/script installs on all platforms
- **CI test coverage for semantic search** — Both `ci.yml` and `publish.yml` now download ONNX Runtime v1.25.0 for unit tests and E2E semantic search tests

* * *

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.20.1...v0.20.2](https://github.com/knowns-dev/knowns/compare/v0.20.1...v0.20.2)

v0.20.1

April 23, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.20.1)

# v0.20.1

## Highlights

Patch release fixing ONNX Runtime library resolution for Homebrew installations and CI bundling improvements.

* * *

### Fixed

- **Homebrew ONNX Runtime resolution** — `ResolveORTLibraryPath()` now checks sibling directories (`../libexec`, `../lib`) relative to the binary, fixing semantic search on Homebrew where the dylib is installed in `libexec/` rather than next to the binary
- **CI ONNX Runtime bundling** — Download ONNX Runtime x64 libs from official GitHub releases as fallback when Go module `test_data` lacks them

### Removed

- **macOS Intel (darwin/amd64)** — Dropped from build matrix, npm packages, tarballs, verification, Homebrew formula, and install script. ONNX Runtime 1.25.0 no longer ships macOS x64 binaries.

* * *

### Breaking Changes

- **macOS Intel (x86\_64) no longer supported** — Only macOS Apple Silicon (arm64) is supported going forward. The install script now exits early on macOS Intel with a clear message.

* * *

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.20.0...v0.20.1](https://github.com/knowns-dev/knowns/compare/v0.20.0...v0.20.1)

v0.20.0

April 23, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.20.0)

# v0.20.0

## Highlights

This release replaces the external sidecar embedding process with a native ONNX runtime, introduces an AI permission guard system, adds MCP audit trail capabilities, and consolidates MCP tools for a cleaner API surface. The CI pipeline is also simplified by removing the now-unnecessary sidecar smoke tests.

* * *

### Added

- **AI Permission Guard** — New permission system (`internal/permissions`) with guard, policy, and registry modules for controlling AI tool access
- **MCP Audit Trail** — Track all MCP tool invocations with audit middleware, storage layer, CLI commands (`knowns audit`), API routes, and a new Audit UI page
- **Structural Knowledge Retrieval** — Code graph edge storage and traversal (`internal/storage/structural_*`) for querying code relationships
- **Project Activation Readiness** — New `internal/readiness` module to check project setup completeness
- **Status CLI command** — `knowns status` for quick project health overview

### Changed

- **MCP Tool Consolidation** — Refactored all MCP handlers; removed standalone `board` and `working_memory` handlers in favor of unified interfaces; added shared handler helpers
- **Native ONNX Embedding** — Replaced the external `knowns-embed` sidecar process with native ONNX runtime integration (`internal/search/onnx_runtime.go`, `embedding_native.go`), eliminating the need for a separate binary
- **Skills Update** — Synced skill definitions across all platforms (`.agent/`, `.claude/`, `.kiro/`, `internal/instructions/`)
- **Working Memory Merged** — Consolidated `internal/workingmemory` into the unified memory store
- **CI Simplified** — Removed `sidecar-smoke` job (5-platform matrix) and sidecar build steps from CI pipeline
- **Install Scripts** — Updated for new binary structure
- **Publish Workflow** — Refactored CI publish pipeline

### Removed

- `internal/mcp/handlers/board.go` — Merged into consolidated handler
- `internal/mcp/handlers/working_memory.go` — Merged into memory handler
- `internal/workingmemory/store.go` — Replaced by unified memory store
- `internal/search/embedding_sidecar*.go` — Replaced by native ONNX embedding
- `internal/cli/skill.go` — Skill CLI command removed
- `cmd/knowns-embed/main_nonwindows.go` — No longer needed
- `sidecar-smoke` CI job — No longer needed with native embedding

### Documentation

- Added research docs and specs for: AI permission model, audit trail, structural retrieval, project readiness, MCP tool consolidation
- Updated AI, MCP, skills, and architecture documentation
- Updated README, user guide, commands reference, and templates docs
- Synced agent instruction files (AGENTS, CLAUDE, GEMINI, KNOWNS, OPENCODE)

* * *

### Breaking Changes

- **MCP tool names may have changed** due to handler consolidation. Clients using `board` or `working_memory` tools directly will need to update to the new unified endpoints.
- **Sidecar binary no longer required** — The `knowns-embed` binary is no longer needed. Embedding is handled natively via ONNX runtime. Existing `KNOWNS_EMBED_BIN` environment variable references can be removed.

* * *

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.19.2...v0.20.0](https://github.com/knowns-dev/knowns/compare/v0.19.2...v0.20.0)

v0.19.2

April 22, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.19.2)

## **v0.19.2**

`0.19.2` is a patch release focused on semantic search stability, especially on Windows, while also improving CI and release reliability.

### **Highlights**

- Improved semantic search setup in non-interactive environments such as CI or terminals without TTY support.
- Added multi-platform smoke tests for `knowns-embed`, with a strong focus on Windows runtime validation.
- Expanded test coverage for `sync`, `semantic search`, and related MCP workflows.

### **Changed**

- Semantic search setup now behaves more reliably when running in non-interactive environments.
- The CI pipeline now builds and validates the sidecar across macOS, Linux, Windows x64, and Windows ARM.
- The build and release flow now includes real runtime checks for the Windows sidecar before publishing artifacts.

### **Fixed**

- Reduced the risk of shipping semantic search artifacts that fail at runtime on Windows.
- Improved early failure detection for semantic search and sync workflows through E2E and smoke tests.
- Increased release stability by validating that the sidecar not only exists in published packages, but also runs successfully.

### **Testing**

- Added CI smoke tests for `knowns-embed` across multiple platforms.
- Added test coverage for:
- `knowns sync --instructions`
- `knowns sync --skills`
- semantic CLI subset
- semantic MCP subset

### **Notes**

- There are no breaking changes in this release.
- This release prioritizes stability and reliability over new feature work.

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.19.1...v0.19.2](https://github.com/knowns-dev/knowns/compare/v0.19.1...v0.19.2)

v0.19.1

April 20, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.19.1)

## v0.19.1 - CI and Semantic Search Stabilization

### ✨ Added

- Added cross-platform sidecar smoke checks in PR CI for all Bun targets: darwin x64/arm64, linux x64/arm64, and windows x64/arm64
- Added end-to-end CLI coverage for `knowns sync --instructions --platform claude` and `knowns sync --skills`
- Added semantic search subsets to PR CI so semantic CLI and MCP search flows are exercised in pull requests

### 🔄 Changed

- Updated CI runner selection for Darwin x64 sidecar smoke to use the Intel macOS runner label already used by publish workflow
- Adjusted Unix sidecar smoke execution to export bundle-local dynamic library paths before launching the compiled sidecar
- Refined PR CI coverage so sidecar packaging/runtime validation and semantic search validation run as separate targeted checks

### 🐛 Fixed

- Fixed semantic model download in non-interactive environments by avoiding Bubble Tea setup UI when running without a TTY
- Fixed CI failures where semantic CLI tests fell back to keyword-only mode because model setup could not complete in GitHub Actions
- Fixed sidecar smoke regressions on Unix runners caused by missing runtime loader paths when executing packaged sidecar binaries directly

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.19.0...v0.19.1](https://github.com/knowns-dev/knowns/compare/v0.19.0...v0.19.1)

v0.19.0

April 20, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.19.0)

## v0.19.0 - Tree-sitter Sidecar Runtime for Search

### ✨ Added

- New Bun-based sidecar runtime for symbol extraction, parsing, and embedding support across supported platforms
- Tree-sitter-driven symbol extraction pipeline, candidate discovery helpers, and sidecar server/build assets under `sidecar/`
- Sidecar runtime plumbing in the CLI, including setup/download flow updates and tunnel/cloudflared helpers for runtime-managed services
- Spec doc for the tree-sitter sidecar design and rollout

### 🔄 Changed

- Search and indexing flows now use the new sidecar-based embedding/runtime path instead of the previous ONNX implementation
- Runtime queue, MCP server integration, install scripts, and update/browser/runtime commands were updated to support sidecar packaging and execution
- Publish workflow, Makefile, and release packaging now build and ship sidecar bundles alongside the main CLI artifacts

### 🐛 Fixed

- Improved cross-platform search/runtime consistency by removing the older ONNX/stub split and standardizing parsing and embedding behavior behind the sidecar runtime
- Tightened AST indexing coverage and runtime-related tests around parser candidates, browser/search flows, and sidecar-backed indexing behavior

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.18.4...v0.19.0](https://github.com/knowns-dev/knowns/compare/v0.18.4...v0.19.0)

v0.18.4

April 17, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.18.4)

## v0.18.4 - Semantic References & Working Memory

### ✨ Added

- Semantic reference model and resolution flow for knowledge links such as `references`, `implements`, `blocked-by`, `related`, `depends`, and `follows`
- New reference resolution and rewrite helpers in storage and reference packages, with dedicated tests
- `knowns resolve` CLI support for resolving semantic references directly
- Working memory store and MCP/server support for session-scoped memory operations
- New semantic reference badge rendering in the editor and richer release/spec docs for the feature set

### 🔄 Changed

- Search, graph, docs, and MCP flows now surface semantic references more consistently across backend and web UI
- Memory APIs and the Memory page were reworked to separate persistent memory from working memory, with improved create/view/edit flows
- Graph filtering and legends now support semantic relation edge types and clearer impact exploration
- Installer and publish workflow assets were updated to include the new runtime/reference-related behavior
- User and developer docs were refreshed for semantic references, mention playground usage, and related workflows

### 🐛 Fixed

- Improved document reference resolution and validation behavior so semantic links are interpreted more reliably across storage, routes, and search
- Tightened tests around MCP search, doc storage, graph routes, runtime memory, and reference resolution to reduce regressions in the new reference pipeline

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.18.3...v0.18.4](https://github.com/knowns-dev/knowns/compare/v0.18.3...v0.18.4)

v0.18.3

April 12, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.18.3)

## v0.18.3 - Runtime Adapter Install, MCP-First Retrieval & Search Improvements

### ✨ Added

- Unified runtime adapter install package for global hook/plugin setup across claude-code, codex, kiro, and opencode
- `runtime-memory` CLI command for direct runtime memory hook invocation
- Kiro native runtime-memory hook (`.kiro/hooks/knowns-runtime-memory.kiro.hook`)
- Specs: multi-store semantic memory retrieval and unified runtime adapter install
- Design system reference doc for SVG diagrams, Web UI, and knowns.sh visual consistency
- README SVG diagrams: architecture, capabilities, cover, knowledge-graph, mcp-integration, multi-platform, template-pipeline, workflow

### 🔄 Changed

- All agent skills and compatibility shims now prefer MCP `retrieve` tool over CLI, with CLI as fallback
- Search engine improvements: chunker source-type awareness, vecstore type filtering, sqlite store optimizations, and sync refinements
- Init flow updated with runtime discovery, adapter install integration, and MCP-first guidance generation
- Docs refreshed: commands, configuration, semantic-search, mcp-integration, user-guide, developer-guide, web-ui

### 🐛 Fixed

- Search type filtering now applies at the vector store level so `--type memory` queries are not crowded out by unrelated doc/task chunks

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.18.2...v0.18.3](https://github.com/knowns-dev/knowns/compare/v0.18.2...v0.18.3)

v0.18.2

April 11, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.18.2)

## v0.18.2 - Shared Runtime Queue, Script Updates & Stability Fixes

### ✨ Added

- Shared global runtime queue for background semantic/code indexing work, with project-scoped queues, lease tracking, idle shutdown, and runtime status reporting
- Installer metadata persisted under `~/.knowns/install.json` for official shell and PowerShell installs
- Script-managed self-update flow for `knowns update`, including runtime version awareness and safer runtime restart behavior after upgrades
- MCP and runtime process logs under `~/.knowns/logs`, including per-process MCP logs and bounded log rotation

### 🔄 Changed

- MCP write paths now keep source-of-truth writes synchronous while enqueueing follow-up indexing, watch-triggered work, and reindex tasks to the shared runtime
- `knowns watch` and related background indexing flows now reuse shared runtime infrastructure instead of spawning redundant heavyweight work
- Shell installer now defaults to `~/.knowns/bin`, reducing the need for `sudo` and avoiding password prompts for script-managed installs on macOS and Linux
- Background indexing now uses queue pacing, debounce windows, duplicate coalescing, and lower ONNX thread defaults to reduce CPU spikes

### 🐛 Fixed

- Fixed runtime memory injection scoring so prompt hooks only inject memories with actual prompt relevance instead of matching only on runtime/context tokens
- Fixed Windows and race-sensitive test behavior by forcing test commands and MCP e2e flows to run with inline runtime mode instead of leaving shared runtime processes behind
- Fixed MCP/background work stability issues caused by inline indexing pressure, stale runtime reuse, and oversized shared log growth

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.18.1...v0.18.2](https://github.com/knowns-dev/knowns/compare/v0.18.1...v0.18.2)

v0.18.1

April 11, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.18.1)

## v0.18.1 - Release Docs, MCP Schema & Update Guidance

### ✨ Added

- Public docs for the `v0.18.0` feature set, including workspace-aware browser mode, code intelligence commands, code graph usage, and chat/runtime UX updates
- Installer README examples for pinning a specific version with `KNOWNS_VERSION` on both shell and PowerShell installers

### 🔄 Changed

- README and command guides now describe the shipped `knowns code ingest`, `knowns code watch`, `knowns code search`, `knowns code deps`, and `knowns code symbols` workflows
- Browser and web UI docs now cover workspace switching, project scanning, code watcher mode, and richer graph/chat capabilities

### 🐛 Fixed

- Fixed MCP tool schema for `knowns_retrieve` so `sourceTypes` declares array item types and no longer triggers `array schema missing items`
- Fixed Homebrew upgrade guidance to use `brew upgrade knowns-dev/tap/knowns` consistently in the CLI notifier and release/install messaging

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.18.0...v0.18.1](https://github.com/knowns-dev/knowns/compare/v0.18.0...v0.18.1)

v0.18.0

April 10, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.18.0)

## v0.18.0 - Workspace Switching, Code Intelligence & Chat UX

### ✨ Added

- AST-based code intelligence with symbol indexing, relationship edges, neighbor discovery, and dedicated tests
- New code-focused CLI and MCP capabilities for code search, code graph exploration, ingest, and file watching/sync flows
- Dedicated Code Graph experience in the web UI with new graph toolbar, legend, styling, and detail panel improvements
- Welcome page and chat timeline dialog to improve session onboarding and chat history navigation
- Workspace picker and server-side workspace switching improvements, including broader browser/server test coverage
- Search benchmarking utilities and new research/spec docs for retrieval, graph UX, and chat runtime upgrades

### 🔄 Changed

- Upgraded chat runtime and message rendering to better support tool calls, shell output, sub-agents, and richer thread interactions
- Expanded search engine and server routes to support code-aware retrieval alongside existing knowledge/doc search flows
- Updated browser/server integration, route wiring, and configuration plumbing to support workspace-aware behavior end to end
- Refined agent skill instructions and internal guidance for planning, implementation, review, research, and debugging workflows

### 🐛 Fixed

- OpenCode client/runtime handling is more robust, with added tests around client behavior and browser command flows
- Graph, search, validation, storage, and API route handling received targeted fixes alongside the new workspace/code features
- Publish workflow and package metadata were adjusted to keep release/build behavior aligned with the new runtime changes

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.17.1...v0.18.0](https://github.com/knowns-dev/knowns/compare/v0.17.1...v0.18.0)

v0.17.1

April 2, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.17.1)

## v0.17.1 - MCP Fixes & Working Memory Persistence

### 🐛 Fixed

- `create_task` MCP handler now properly saves `plan` and `notes` fields (were being silently ignored)
- `update_doc` MCP handler no longer clears content when sending empty string `content: ""`
- Working memory now persists to `.knowns/.working-memory/` directory instead of RAM-only, surviving restarts and compacts
- `clear_working_memory` properly removes working memory files from disk

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.17.0...v0.17.1](https://github.com/knowns-dev/knowns/compare/v0.17.0...v0.17.1)

v0.17.0

April 2, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.17.0)

## v0.17.0 - Memory System & Knowledge Graph

### ✨ Highlights

- **🧠 3-Layer Memory System** — Working, project, and global memory layers for agents. Store patterns, decisions, and conventions that persist across sessions via CLI (`knowns memory`) and full MCP tool coverage (`add_memory`, `list_memories`, `search_memories`, `promote_memory`, `add_working_memory`).
- **🕸️ Knowledge Graph UI** — New Graph page visualizes relationships between tasks, docs, and memories as an interactive network. Click any node to open a detail panel with full context.
- **📈 Semantic Search Quality** — Model-specific embedding prefixes (EmbedQuery/EmbedDocument) for bge, nomic, and e5; H1 content loss fixed; tokenizer-based chunk splitting; `ChunkVersion` auto-reindex on version mismatch.
- **🔄 `knowns update` Command** — New CLI command to check for and install the latest version of Knowns.
- **🔌 Custom Provider UI** — Add custom OpenCode-compatible providers (base URL, models, headers, API key) directly from the provider connect dialog.

* * *

### 🚀 Added

- `knowns memory` CLI command — list, view, add, update, delete, and search memory entries across layers
- `add_memory` / `get_memory` / `update_memory` / `delete_memory` / `list_memories` / `search_memories` MCP tools (project + global layers)
- `promote_memory` / `demote_memory` MCP tools for cross-layer promotion (`project → global`)
- `add_working_memory` / `get_working_memory` / `list_working_memories` / `delete_working_memory` / `clear_working_memory` MCP tools (session-scoped, in-memory)
- `MemoryEntry` model with `id`, `title`, `layer`, `category`, `tags`, `content`, `metadata`, `createdAt`, `updatedAt`
- `MemoryStore` file-backed storage under `.knowns/memory/` with semantic search indexing
- `GET /api/memories`, `POST /api/memories`, `PATCH /api/memories/:id`, `DELETE /api/memories/:id` REST endpoints
- `GET /api/graph` endpoint — returns nodes and edges for tasks, docs, and memories with relationship inference
- Graph page (`/graph`) with force-directed network visualization and node type filtering
- Graph detail panel — click any node to see title, type, tags, excerpt, and outbound links
- Memory page (`/memory`) — list and browse all memory entries by layer and category
- `knowns update` CLI command — checks GitHub releases and installs the latest binary
- OpenCode auto-detection during `knowns init` wizard — skips download if already installed
- Custom provider step in `ProviderConnectDialog` — provider ID, display name, base URL, models, optional headers and API key
- Sidebar navigation entries for Graph and Memory pages
- `kn-extract` skill: new Step 5 saves memory entry alongside extracted doc
- `kn-init` skill: Step 3.6 loads project memory at session start
- `kn-research` skill: Step 2 searches project memory before completed tasks

* * *

### 📝 Changed

- `knowns search` — improved result ranking with model-aware embedding prefixes
- Chunker now uses tokenizer-based token counting with configurable overlap; splits oversized task chunks
- `ChunkVersion` bumped — mismatched indexes are automatically wiped and reindexed on next sync
- `KNOWNS.md` / compatibility shims — added Memory Usage section with usage guidelines for agents
- Skills (`kn-extract`, `kn-init`, `kn-research`) updated to include memory steps in their workflows
- `knowns sync` — content-based out-of-sync detection replaces `.version` file mechanism
- MDRender components (`CopyablePre`, `CopyableTable`, `StableHeading`) moved to module scope to fix React reconciliation key warnings
- `.air.toml` dev server switched from pre-built binary to `go run ./cmd/knowns/main.go`

* * *

### 🐛 Fixed

- H1 heading content captured correctly in chunker (was being dropped before the first H2)
- Code block language detection in chunker prevented false heading matches inside fenced blocks
- `execLookPath` in `mcpCommand()` now injectable — CI test failures caused by `knowns` not being in PATH resolved
- Chat scroll uses `useLayoutEffect` for instant initial positioning (no flash of bottom-scrolled content)
- Mention badge re-rendering stabilized with stable `useMemo` refs
- `sync.go` import sync no longer races on concurrent file writes

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.16.3...v0.17.0](https://github.com/knowns-dev/knowns/compare/v0.16.3...v0.17.0)

v0.16.3

March 28, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.16.3)

## v0.16.3 - Mermaid Viewer & Import Sync

### ✨ Highlights

- **🔍 Interactive Mermaid Diagrams** — Drag to pan, Ctrl+scroll to zoom, auto-fit to container, and theme-aware colors for light/dark mode.
- **📦 Git Import Auto-Sync** — Git imports now clone and sync immediately on add, with a spinner UI and private repo token support.
- **🎨 Brand Progress Bars** — All CLI progress bars use the Knowns navy blue (`#1e3a5f`) instead of the default gradient.
- **⏱️ Time Tracking Fix** — Stopping a timer now correctly updates the task's `timeSpent` field.

* * *

### 🚀 Added

- Mermaid drag-to-pan with grab/grabbing cursor feedback
- Mermaid Ctrl+Scroll zoom centered on cursor position with smooth animation
- Mermaid auto-fit on render — large diagrams scale down, small ones cap at 150%
- Mermaid dynamic container aspect ratio (4:3 to 21:9) based on SVG shape
- Mermaid zoom percentage indicator in bottom-right controls
- `KnownsBrand` constant (`#1e3a5f`) in `styles.go` for centralized brand color
- Git import auto-sync on `knowns import add` with bubbletea spinner UI
- Git token injection for private HTTPS clone URLs
- `importedAt` and `ref` fields in import metadata
- Dry-run preview → "Import Now" flow in ConfigPage add import modal

* * *

### 📝 Changed

- Mermaid controls simplified — removed D-pad buttons, kept zoom +/- and reset (fit-to-view)
- Mermaid hardcoded dark colors replaced with theme tokens (`bg-muted`, `text-muted-foreground`, `border-border`)
- All 4 CLI progress bars (`model.go`, `download_setup.go`, `search.go`) switched from `WithDefaultBlend()` to `WithColors(lipgloss.Color(KnownsBrand))`
- `CopyablePre` now skips wrapping mermaid code blocks to avoid duplicate copy button
- Import metadata format aligned between CLI and server (`_import.json`)
- `ImportEntry` struct extended with `Ref` and `ImportedAt` fields

* * *

### 🐛 Fixed

- Duplicate copy button on mermaid diagrams — `CopyablePre` wrapper now detects `language-mermaid` and yields
- Mermaid Ctrl+scroll zoom not working in fullscreen — wheel listener now re-attaches on `isFullscreen` toggle
- Task `timeSpent` not updating when stopping timer via API — `time.go` now writes accumulated duration back to task

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.16.2...v0.16.3](https://github.com/knowns-dev/knowns/compare/v0.16.2...v0.16.3)

v0.16.2

March 28, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.16.2)

## v0.16.2 - Custom Providers & Render Stability

### ✨ Highlights

- **🔌 Custom Provider UI** — Add any OpenAI-compatible endpoint directly from the Provider Connect dialog.
- **⚡ Stable Markdown Rendering** — Fixed React error #310 and eliminated mention badge flickering on re-render.
- **📜 Chat Scroll Fix** — Messages now appear at the correct position instantly instead of jumping.
- **🧹 No More .version Files** — Replaced auto-sync mechanism with content-based `knowns sync` warning.

* * *

### 🚀 Added

- Custom provider UI in ProviderConnectDialog — add any OpenAI-compatible endpoint with provider ID, display name, base URL, models, optional headers, and optional API key
- `patchConfig()` API method to call PATCH /config on OpenCode server
- `addCustomProvider()` action in OpenCodeContext (patchConfig → setAuth → globalDispose → refreshAll)
- `SkillsOutOfSync()` content-based check — compares embedded skills vs on-disk copies without version files
- CLI warning `⚠ Skills are out of sync. Run 'knowns sync' to update.` when skills are stale after upgrade

* * *

### 📝 Changed

- Extracted `CopyablePre`, `CopyableTable`, `StableHeading`, `MermaidLoading` into `mdComponents.tsx` for cleaner separation
- MDRender `useMemo` deps reduced to `[]` — all callbacks accessed via stable refs, components object created once
- Chat scroll switched from `useEffect` \+ smooth scroll to `useLayoutEffect` \+ instant scroll for new messages
- Removed `AutoSyncOnUpdate` config field and init wizard step
- Removed `.version` file generation from skill sync
- Added `**/.version` to `.gitignore`

* * *

### 🐛 Fixed

- React error #310 — hooks inside `useMemo` (pre/table components) lost identity on dep change, causing "Rendered more hooks than during the previous render"
- Mention badges (task/doc) flickering and re-fetching on every render due to unstable `components` object identity in MDRender
- Chat messages appearing above the last message then jumping down — scroll now fires before paint via `useLayoutEffect`

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.16.1...v0.16.2](https://github.com/knowns-dev/knowns/compare/v0.16.1...v0.16.2)

v0.16.1

March 27, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.16.1)

## v0.16.1 - Enhanced Skills & Developer Experience

### ✨ Highlights

- **🤖 3 New Skills** — `kn-go` (full pipeline), `kn-review` (code review), `kn-debug` (structured debugging) for a more complete AI workflow.
- **🔍 Socratic Exploring** — `kn-spec` now asks one question at a time to lock decisions before writing specs.
- **📊 Context Usage Indicator** — Arc indicator in Chat UI showing real-time context window usage with heatmap breakdown.
- **🔄 Smart Sync** — `knowns sync` reads config.json and sets up everything locally (skills, instructions, model, search index).
- **🧠 MCP Auto-Detect** — MCP server automatically finds the project from cwd, `--project` flag, or `KNOWNS_PROJECT` env.

* * *

### 🚀 Added

- `kn-go` skill — full pipeline execution from approved spec (generate tasks → plan → implement → verify → commit) with no review gates between steps
- `kn-review` skill — multi-perspective code review (quality, architecture, security, completeness) with P1/P2/P3 severity triage
- `kn-debug` skill — structured debugging: triage → check known patterns → reproduce → root cause → fix → capture learning
- `kn-spec` Phase 0 Socratic exploring — scope assessment, domain classification, gray area identification, one-question-at-a-time dialog, decision locking with stable IDs
- `kn-extract` compounding — captures decisions and failures alongside patterns, promotes critical learnings, `--consolidate` mode for reviewing all learnings
- `kn-plan` pre-execution validation — AC coverage check, scope sizing, dependency check, risk assessment before approval
- `kn-init` critical learnings — loads `learnings/critical-patterns` at session start for institutional knowledge
- Context usage indicator in Chat UI — arc indicator with percentage, hover popover with heatmap grid and token breakdown
- `knowns sync` command — applies config.json after cloning (skills + instructions + git integration + model download + reindex)
- `knowns sync --model` flag to download embedding model only
- MCP server auto-detects project from `--project` flag, `KNOWNS_PROJECT` env var, or cwd walk-up
- MCP `--project` flag for explicit project path
- Auto-setup warning when embedding model is missing (suggests `knowns sync`)
- `knowns init --force` pre-populates all wizard fields from existing config.json (name, git mode, platforms, semantic model)

* * *

### 📝 Changed

- Init wizard splits prompts into sequential groups (one at a time instead of combined)
- Git-ignored mode now whitelists `config.json` for clone+sync workflow
- Git tracking mode select pre-populates from existing config on re-init
- Semantic search and model selection pre-populate from existing config on re-init
- `set_project` MCP tool description updated (only needed for runtime switching)
- All MCP error and success messages centralized in `handlers/messages.go`
- Skills table updated from 10 to 13 in docs

* * *

### 🐛 Fixed

- MCP `create_task` and `update_task` now call `SaveVersion` for version tracking
- SSE multiplexing — OpenCode SSE events merged into Knowns SSE stream (1 connection per tab)
- Auto-inject directory param in session list proxy
- Auto-reload on stale chunk imports (lazy retry for code-split bundles)
- Vietnamese text in skills replaced with English
- Removed unused `splitView` prop from VersionDiffViewer

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.16.0...v0.16.1](https://github.com/knowns-dev/knowns/compare/v0.16.0...v0.16.1)

v0.16.0

March 24, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.16.0)

## v0.16.0 - Hub Mode & Multi-Project Support

### ✨ Highlights

- **🏠 Hub Mode** — Run `knowns browser` from anywhere, no repo needed. The server becomes a multi-project hub.
- **📂 Workspace Picker** — Browse, switch, add, and scan projects from the UI without restarting.
- **🗂️ Project Registry** — Global registry tracks all your Knowns projects with auto-discovery.
- **🔄 Runtime Switching** — Switch projects on the fly. No restart needed.
- **🤖 Shared OpenCode Daemon** — Single shared process with auto health checks and crash recovery.

* * *

### 🚀 Added

- Launch `knowns browser` outside any repo — opens workspace picker to choose a project
- `--project <path>` flag to open a specific project directly
- `--scan <dirs>` flag to discover projects from directories
- Workspace Picker dialog — list, switch, add, scan, and remove projects from the UI
- Sidebar switcher button for quick workspace switching
- Global project registry with auto-discovery and last-used tracking
- Auto-registers current project on startup
- Workspace REST API — list, switch, scan, remove projects
- Live data reload via SSE when switching workspaces
- Shared OpenCode daemon with PID management, health checks, and auto-restart
- Graceful remote shutdown via API

* * *

### 📝 Changed

- Server binds port before writing port file (eliminates race condition)
- Server can start without a project (picker mode)
- OpenCode now runs as a single shared daemon instead of per-server process
- Server restart command now works reliably

* * *

### 🐛 Fixed

- Port file written before port was actually available
- Server errors silently swallowed on startup
- Stale port file left behind after shutdown
- Server restart command was broken (wrong HTTP method)

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.15.3...v0.16.0](https://github.com/knowns-dev/knowns/compare/v0.15.3...v0.16.0)

v0.15.3

March 20, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.15.3)

## v0.15.3 - Compact Sessions & Hosted Installers

### ✨ Highlights

- **📦 `/compact` Slash Command** \- Summarize the current chat session into a compact context directly from the Chat UI
- **🌐 Hosted Installers** \- New install and uninstall entrypoints via `knowns.sh`
- **📦 Smarter npm Binary Install** \- `knowns` now auto-recovers platform binaries during install with npm and GitHub release fallbacks

* * *

### 🚀 Added

**Chat UI**

- Added local `/compact` slash command to the Chat input command menu
- Added OpenCode session summarize API support via `POST /session/{id}/summarize`
- Added model-aware summarize requests using the active session model or effective default model

**Install & Uninstall**

- Added `install/uninstall.sh` for macOS/Linux uninstall flow
- Added `install/uninstall.ps1` for Windows uninstall flow
- Added hosted installer/uninstaller docs using:
  - `https://knowns.sh/script/install`
  - `https://knowns.sh/script/install.ps1`
  - `https://knowns.sh/script/uninstall`
  - `https://knowns.sh/script/uninstall.ps1`

**npm Distribution**

- Added `npm/knowns/install.js` postinstall binary bootstrapper
- Added fallback logic to install platform binaries from npm first, then GitHub Releases if needed
- Added package homepage metadata across npm packages

* * *

### 📝 Changed

**Release Workflow**

- Updated publish workflow to upload install and uninstall scripts as release assets
- Added release metadata tracing and built artifact checks in GitHub Actions
- Added verification that the expected release version is present in the built UI artifact

**Documentation**

- Updated `README.md` install instructions to use hosted `knowns.sh` endpoints
- Updated `docs/user-guide.md` install instructions to use hosted `knowns.sh` endpoints
- Added uninstall instructions to both main docs

**Chat Command Handling**

- `/compact` is now available even when it does not come from the remote OpenCode command registry
- Chat session summarize flow now uses streaming/watchdog handling like other async session actions
- Stop-session handling now uses the OpenCode abort endpoint and restores UI state more safely on failure

* * *

### 🐛 Fixed

**Chat Input**

- Fixed slash command selection so pressing `Enter` while the command menu is open autocompletes the selected command instead of submitting partial input like `/com`

**npm CLI**

- Improved missing-binary error output with reinstall hints for the expected platform package
- Improved packaged binary installation resilience for platform-specific npm installs

* * *

### 🔧 Technical

**UI / OpenCode**

- New `OpenCodeSummarizeSessionRequest` request type in `ui/src/api/client.ts`
- New `opencodeApi.summarizeSession()` client method
- Updated `ui/src/pages/chat/useChatPage.ts` to route `/compact` through summarize flow
- Updated `ui/src/data/skills.ts` to merge local slash items with remote command items

**Packaging**

- `npm/knowns/package.json` now runs a `postinstall` script
- All platform packages now include `homepage: https://knowns.sh`
- Release assets now include install and uninstall scripts alongside archives and checksums

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.15.2...v0.15.3](https://github.com/knowns-dev/knowns/compare/v0.15.2...v0.15.3)

v0.15.2

March 19, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.15.2)

## Changes

- fix(npm): restore executable packaged binaries

## Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.15.1...v0.15.2](https://github.com/knowns-dev/knowns/compare/v0.15.1...v0.15.2)

v0.15.1

March 19, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.15.1)

Known issue: v0.15.1 is broken and may not run after npm/bun install. Please use v0.15.2 or later.

v0.15.0

March 19, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.15.0)

## v0.15.0 - Go Rewrite & Cross-Platform CI

### ✨ Highlights

- **⚙️ Go Rewrite** \- Rebuilt Knowns from TypeScript to a Go-native CLI, server, MCP, and packaging flow
- **🧪 Stronger CI** \- Native test coverage on Ubuntu and Windows, plus Playwright UI E2E in CI
- **📦 Better Packaging** \- Cross-platform build and npm packaging flow updated for the Go release model

* * *

### 🚀 Added

#### Go Runtime

- New Go-native `knowns` CLI entrypoint
- Go-based server implementation for browser/UI workflows
- Go-based MCP implementation and supporting handlers
- New Go-first project structure replacing the previous TypeScript runtime layout

#### CI & Verification

- Native `go test` coverage on both `ubuntu-latest` and `windows-latest`
- UI Playwright E2E execution in CI
- Automatic browser installation for Playwright in CI
- Cross-platform build verification for Linux and Windows targets

#### npm Packaging

- Main npm launcher script for the `knowns` package
- Updated npm wrapper flow to resolve and execute platform-specific binaries

* * *

### 📝 Changed

#### Architecture

- Migrated the repository from TypeScript to Go as the primary implementation language
- Reorganized runtime, build, packaging, and workflow structure around the Go codebase
- Updated embedded UI handling to work with the new Go binary layout

#### Build & CI

- CI now builds the UI before Go validation so embedded assets exist during vet/test
- CI now builds the binary before E2E suites that expect `bin/knowns`
- Windows CI build steps now use platform-appropriate shell commands
- Non-interactive init flow now avoids TTY-dependent semantic setup in CI/E2E contexts

#### UI Tooling

- Standardized UI workflow on Bun in CI jobs
- Updated Playwright E2E helpers to use non-interactive init and stable binary resolution

* * *

### 🐛 Fixed

- Fixed `go vet` failures caused by missing embedded UI assets in CI
- Fixed Linux and Windows cross-build failures caused by CGO-only semantic embedding paths
- Fixed Windows-specific CI shell errors in binary build steps
- Fixed E2E failures caused by missing `bin/knowns` on fresh runners
- Fixed Playwright E2E setup failures caused by relative `TEST_BINARY` path resolution
- Fixed repository ignore rules that prevented `cmd/knowns` from being tracked
- Fixed npm publish packaging by tracking the main launcher script used by `npm/knowns`

* * *

### 📚 Documentation

- Updated specs and docs to reflect the Go-first repository layout
- Refreshed workflow and agent/skill assets to match the new architecture
- Synced repository guidance with the rewritten runtime and packaging flow

* * *

### 🔧 Technical

- Split semantic embedding into build-specific implementations:
  - CGO/ONNX-enabled runtime path
  - non-CGO stub path for portable cross-builds
- Split terminal-specific stdin draining into Unix and Windows implementations
- Added Windows-aware binary path handling in Go test helpers
- Added npm launcher resolution for:
  - npm/pnpm layouts
  - hoisted installs
  - platform package resolution

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.12.4...v0.15.0](https://github.com/knowns-dev/knowns/compare/v0.12.4...v0.15.0)

v0.12.4

March 3, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.12.4)

## v0.12.4 - Error Handling & Stability Improvements

### ✨ Highlights

- **🛡️ Error Boundary** \- Catch rendering errors to prevent full app crashes
- **🔄 Retry UI** \- Graceful error recovery with retry button in DocsPage
- **📝 Defensive Parsing** \- Skip corrupted docs instead of crashing

* * *

### 🚀 Added

**Error Handling**

- New `ErrorBoundary` component to catch React rendering errors
- Error state and retry UI in DocsPage when docs fail to load
- Fallback UI with "Try Again" button and error message display

* * *

### 🐛 Fixed

**Stability**

- **App crashes from rendering errors** \- ErrorBoundary prevents full app crash
- **Corrupted doc files crash** \- Now skips invalid .md files with try-catch
- **Missing doc metadata** \- Ensures all docs have required defaults (title, createdAt, updatedAt)
- **DocsPage load failures** \- Shows error state with retry instead of silent failure

* * *

### 🔧 Technical

**Error Boundary Component**

- React class component with `getDerivedStateFromError` and `componentDidCatch`
- Supports custom fallback UI via props
- Logs errors to console for debugging
- Reset error state with retry button

**Doc Parsing Safety**

- Wrapped doc parsing in try-catch blocks
- Filters out null results from failed parsing
- Prevents server route crashes on invalid markdown files
- Default metadata injection for missing fields

**App Integration**

- ErrorBoundary wraps all page content in `App.tsx`
- Page errors are isolated and don't affect sidebar/header
- Users can continue using the app even if one page fails

* * *

### Files Changed

```
src/ui/components/atoms/ErrorBoundary.tsx - New component (61 lines)
src/ui/components/atoms/index.ts          - Export ErrorBoundary
src/ui/App.tsx                            - Wrap pages in ErrorBoundary
src/ui/pages/DocsPage.tsx                 - Error state + retry UI
src/server/routes/docs.ts                 - Defensive parsing with try-catch
```

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.12.3...v0.12.4](https://github.com/knowns-dev/knowns/compare/v0.12.3...v0.12.4)

v0.12.3

February 26, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.12.3)

## v0.12.3 - Mobile Responsive UI & UX Enhancements

### ✨ Highlights

- **📱 Mobile Responsive** \- Optimized padding, spacing, and layouts for mobile devices
- **🚀 Performance** \- Lazy load Mermaid and page components (bundle reduced ~680KB)
- **🎨 UX Improvements** \- Breadcrumb navigation, scroll memory, copy table as markdown

* * *

### 🚀 Added

#### Mobile Support

- Mobile drawer for DocsPage, TemplatesPage, ImportsPage
- Mobile warning banner for Kanban (drag & drop not optimal on touch)
- Responsive padding throughout: `p-3 sm:p-6`
- Task modals use sheet-only mode on mobile (no center dialog)
- Hide maximize button on mobile (not applicable)

#### UX Features

- Copy table as markdown button (hover on tables)
- Breadcrumb navigation for DocsPage
- Scroll position memory when navigating between docs
- Keyboard shortcut Ctrl+B to toggle sidebar

#### Performance

- Lazy load MermaidBlock with React.lazy/Suspense
- Lazy load all page components in App.tsx
- Bundle size reduced from ~2,682KB to ~2,003KB

* * *

### 📝 Changed

#### Mermaid Diagrams

- GitHub-style zoom/pan controls
- Fullscreen mode support
- Improved rendering with better styling

#### Table Styling

- GitHub-like appearance with zebra striping
- Hover effects on rows
- Better border styling for headers vs cells

#### Typography

- Improved heading sizes and spacing
- Better list styling
- Custom checkbox styling for task lists

* * *

### 🐛 Fixed

- **Task links in DocsPage** \- Now opens global modal instead of navigating to Kanban
- **SSE reconnection** \- Improved handling for connection drops
- **Safari markdown editor** \- Fixed issues with react-markdown-editor-lite

* * *

### 🔧 Technical

#### Responsive Patterns

- Consistent mobile padding: `p-3` (mobile) / `p-6` (desktop)
- Responsive gaps: `gap-2 sm:gap-4`, `gap-3 sm:gap-6`
- Responsive text: `text-xl sm:text-2xl`
- Truncate with `min-w-0` for flex overflow handling

#### Components Updated

- TaskDetailSheet - mobile sheet mode, reduced padding
- TaskCreateForm - mobile sheet mode, compact layout
- TaskDataTable - responsive toolbar, stacked on mobile
- TaskGroupedView - responsive filters
- Board - responsive column controls

* * *

### Files Changed

```
src/ui/App.tsx                    - Lazy load pages
src/ui/components/editor/MDRender.tsx - Table copy, lazy Mermaid
src/ui/components/editor/MermaidBlock.tsx - Zoom/pan/fullscreen
src/ui/components/organisms/TaskDetailSheet.tsx - Mobile sheet
src/ui/components/organisms/TaskCreateForm.tsx - Mobile sheet
src/ui/pages/DocsPage.tsx         - Breadcrumb, scroll memory, drawer
src/ui/pages/KanbanPage.tsx       - Mobile warning banner
src/ui/pages/TasksPage.tsx        - Responsive layout
src/ui/pages/TemplatesPage.tsx    - Mobile drawer
src/ui/pages/ImportsPage.tsx      - Mobile drawer
src/ui/index.css                  - Table styling, typography
```

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.12.2...v0.12.3](https://github.com/knowns-dev/knowns/compare/v0.12.2...v0.12.3)

v0.12.2

February 25, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.12.2)

## v0.12.2 - Browser Improvements & Validate E2E Tests

### ✨ Highlights

- **🌐 Smart Browser Detection** \- Prevents duplicate server instances when running `knowns browser`
- **✅ Validate E2E Tests** \- Comprehensive validation tests with scope filtering
- **🎨 Dynamic Status Options** \- UI now uses custom statuses from project config

* * *

### 🚀 Added

#### Validation Tests

- Added 29 vitest integration tests in `validate.test.ts`
- Expanded MCP e2e tests with 6 validation workflow tests
- Expanded CLI e2e tests with 6 validation workflow tests
- Tests cover: scope filtering, SDD mode, strict mode

#### Browser Command Improvements

- Server detection before starting new instance
- Auto-switch to next available port if occupied
- Only opens browser on successful port (not fallback)

* * *

### 📝 Changed

#### UI Enhancements

- TaskDataTable now uses dynamic status options from `config.statuses`
- StatusBadge supports custom statuses (e.g., "urgent")
- DocsPage and TaskGroupedView UI improvements

#### Skills System

- Updated `/kn-spec` with validation step
- Updated `/kn-template` with validation step
- Updated `/kn-verify` with improved coverage reporting

#### Publish Workflow

- Changed install instructions from Homebrew to npm/bun

* * *

### 🐛 Fixed

- **Browser duplicate ports** \- Fixed `knowns browser` opening both 6420 and 6421
- **Server port detection** \- Now properly checks if Knowns server is already running
- **E2E test order** \- Fixed `git init` must run before `knowns init`

* * *

### 🔧 Technical

#### Validate Command

- Enhanced MCP handler with better scope filtering
- Improved stats reporting (tasks, docs, templates count)
- SDD validation with coverage percentage

#### Server

- Added `isKnownsServerRunning()` health check function
- Browser only opens on originally requested port
- Port fallback message shown when switching ports

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.12.1...v0.12.2](https://github.com/knowns-dev/knowns/compare/v0.12.1...v0.12.2)

v0.12.1

February 24, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.12.1)

## v0.12.1 - E2E Tests & Node 20+ Requirement

### ✨ Highlights

- **🧪 E2E Test Suite** \- Comprehensive CLI and MCP workflow tests
- **📦 pnpm Support** \- Added pnpm as package manager option
- **⚡ Node 20+** \- Dropped Node 18, now requires Node 20+

* * *

### 🚀 Added

#### E2E Tests

- `scripts/test-cli.mjs` \- CLI basic tests
- `scripts/test-cli-e2e.mjs` \- CLI workflow tests
- `scripts/test-mcp.mjs` \- MCP basic tests
- `scripts/test-mcp-e2e.mjs` \- MCP workflow tests with semantic search
- New npm scripts: `test:cli`, `test:cli:e2e`, `test:mcp`, `test:mcp:e2e`

#### Documentation

- Added `auth-patterns.md` pattern documentation

* * *

### 📝 Changed

#### Node.js Requirements

- **Breaking**: Minimum Node.js version raised from 18 to 20
- Vite 7 and @vitest](https://github.com/vitest)/coverage-v8 require Node 20+

#### Package Manager

- Added `pnpm-lock.yaml` for pnpm support
- CI now uses pnpm for faster installs

#### Skills System

- Removed `.agent/skills/` synced files
- Skills now sourced directly from `src/instructions/skills/`

* * *

### 🐛 Fixed

- Fixed semantic search not working in MCP e2e tests
- Fixed CI coverage failing on Node 18 (now skipped)

* * *

### 🔧 Technical

- Updated CI matrix: Node 20, 22, 24 (removed 18)
- MCP e2e tests now use CLI to setup semantic search properly
- Removed obsolete `engine.test.ts` and `store.test.ts`

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.12.0...v0.12.1](https://github.com/knowns-dev/knowns/compare/v0.12.0...v0.12.1)

v0.12.0

February 24, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.12.0)

## v0.12.0 - Semantic Search & SDD Enhancements

### ✨ Highlights

- **🔍 Semantic Search** \- AI-powered search using vector embeddings for better relevance
- **🔗 Fulfills Field** \- Link tasks to spec acceptance criteria for SDD workflow
- **📊 Similarity Scores** \- See match confidence (%) in search results

* * *

### 🚀 Added

#### Semantic Search

- New `knowns search` with hybrid mode (semantic + keyword + fuzzy matching)
- `knowns model`command for embedding model management
  - `model list` \- List available models (6 curated models)
  - `model download <id>` \- Download embedding model
  - `model set <id>` \- Set model for project
  - `model status` \- Show current model status
- `--reindex` flag to rebuild search index
- `--status-check` flag to check semantic search status
- `--keyword` flag for keyword-only search fallback
- Similarity scores shown in results: `(97%)` for high relevance
- `Matched by: semantic, fuzzy, keyword` to explain why results matched

#### SDD (Spec-Driven Development)

- `fulfills` field on tasks to link to spec ACs
- Auto-check spec ACs when task AC is completed
- Pattern documentation for fulfills mapping

#### New Commands

- `knowns guidelines`\- Display Knowns usage guidelines for AI agents
  - `--plain` for AI-readable output
  - `--mode cli|mcp|unified` for different guideline modes
  - `--search <query>` to search within guidelines
  - `--compact` for condensed rules (what goes in CLAUDE.md)

#### Auto-Sync & Version Tracking

- `.version` file in skill directories for tracking sync state
- Auto-sync skills when CLI version changes
- Progress bar utility for visual feedback during operations

* * *

### 📝 Changed

#### Search Output

- Plain output now shows structured format for AI:

```
#taskId [status] [priority] (97%)
    Content snippet...
    Matched by: semantic, fuzzy, keyword
```

- Doc results show section and match reason

#### Documentation

- Converted ASCII diagrams to Mermaid in all docs
- Translated all Vietnamese text to English
- Removed non-existent CLI commands from docs
- Added 9 guide docs in `.knowns/docs/guides/`
- Updated README.md structure

#### MCP

- Search MCP tool now includes `score` field in results
- Added `mode` parameter: `hybrid`, `semantic`, `keyword`

* * *

### 🐛 Fixed

- Fixed config test using invalid key `testKey`
- Removed fake CLI commands: `knowns ai detect`, `knowns mcp status`, `knowns skill export`

* * *

### 📚 New Documentation

- `docs/semantic-search.md` \- Semantic search guide
- `docs/skills.md` \- Skills system guide
- `docs/auto-sync.md` \- Auto-sync version tracking
- `docs/guidelines.md` \- AI guidelines command
- `docs/multi-platform.md` \- Multi-platform support
- `.knowns/docs/guides/` \- 9 new guide docs

* * *

### 🔧 Technical

- New `src/search/` module:
  - `chunker.ts` \- Document chunking for embeddings
  - `embedding.ts` \- Embedding service (transformers.js)
  - `engine.ts` \- Hybrid search engine
  - `store.ts` \- Search index storage
  - `index-service.ts` \- Incremental indexing
- New `src/utils/progress-bar.ts` \- Progress bar utility
- New `src/utils/auto-sync.ts` \- Version tracking
- New `src/utils/sync-spec-acs.ts` \- Spec AC sync utility

* * *

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.11.4...v0.12.0](https://github.com/knowns-dev/knowns/compare/v0.11.4...v0.12.0)

v0.11.4

February 7, 2026 [View on GitHub](https://github.com/knowns-dev/knowns/releases/tag/v0.11.4)

### Changea

- Add setNotifyProjectRoot() to cache project root in notify-server
- Call setNotifyProjectRoot() when MCP sets project via set\_project tool
- Sync project root in getFileStore() for all MCP tool calls
- Fixes issue where MCP couldn't notify web UI due to process.cwd() mismatch

### Contributors

@howznguyen](https://github.com/howznguyen)

**Full Changelog**: [https://github.com/knowns-dev/knowns/compare/v0.11.3...v0.11.4](https://github.com/knowns-dev/knowns/compare/v0.11.3...v0.11.4)

Showing all 30 releases. [View on GitHub](https://github.com/knowns-dev/knowns/releases)

Knowns v0.20.5

A new version is available

[View changelog](https://knowns.sh/changelog)

Ask AI `I`

[v0.20.5 available](https://knowns.sh/changelog "v0.20.5 available")