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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.3...v0.18.4

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.2...v0.18.3

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.1...v0.18.2

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.0...v0.18.1

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.17.1...v0.18.0

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.17.0...v0.17.1

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.16.3...v0.17.0

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.16.2...v0.16.3

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.16.1...v0.16.2

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.16.0...v0.16.1

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.15.3...v0.16.0

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.15.2...v0.15.3

Changes

• fix(npm): restore executable packaged binaries

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.15.1...v0.15.2

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 - 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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.4...v0.15.0

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.3...v0.12.4

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.2...v0.12.3

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.1...v0.12.2

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 VI@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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.0...v0.12.1

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.4...v0.12.0

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

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.3...v0.11.4

Changes

• Add standalone binary detection with helpful error message
• Auto-increment port when requested port is in use (max 10 retries)
• Write running port to .server-port file for CLI to read
• Fix dark mode flash by setting theme before React loads
• Add background-color to body for proper theme display

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.2...v0.11.3

Fixed

• fix(ci): restructure workflow - version first, then build, then publish HO@howznguyen (#54)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.1...v0.11.2

v0.11.1

Highlights

🍺 Homebrew Support

Knowns CLI is now available via Homebrew! No Node.js required.

brew install knowns-dev/tap/knowns

🪟 Windows Compatibility Fix

Renamed skill folders from kn:* to kn-* to fix Windows compatibility issues. Windows doesn't allow colons (:) in directory names.

Breaking Change: Skill invocation changed from /kn:init to /kn-init.

What's Changed

Features

• Homebrew tap: brew install knowns-dev/tap/knowns - standalone binary, no Node.js required
• Standalone binaries: macOS (arm64, x64) and Linux (x64) binaries included in releases
• Auto-update Homebrew: Formula automatically updates on new releases

Fixes

• Windows compatibility: Skill folders renamed from kn:* to kn-*
• Deprecated folder cleanup: Old kn:* and knowns.* folders are automatically removed on sync

Docs

• Added Homebrew install instructions to README, user-guide, and mcp-integration docs

Installation

# Homebrew (macOS/Linux) - no Node.js required
brew install knowns-dev/tap/knowns

# npm
npm install -g knowns

# bun
bun install -g knowns

Upgrading

# Homebrew
brew upgrade knowns

# npm
npm update -g knowns

# Re-sync skills to update folder names
knowns sync skills --force

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.0...v0.11.1

v0.11.0 - SDD (Spec-Driven Development) Support

What's New

CLI & Backend

• Add knowns validate --sdd command for SDD coverage reporting
• Add spec AC auto-sync - when task ACs are checked, matching spec ACs are automatically updated
• Add task-spec linking via spec: field in task frontmatter
• Add mermaid diagram rendering support in markdown

Skills

• Rename all skills to kn:* namespace (kn:init, kn:plan, kn:commit, kn:research, kn:implement, kn:extract, kn:template, kn:doc)
• Add kn:spec skill - create spec documents from requirements
• Add kn:verify skill - run SDD verification and coverage reporting

WebUI

• Add Dashboard page with 7 widgets:

  • Tasks overview with completion progress
  • Documentation stats
  • SDD Coverage widget
  • Time Tracking Summary (today/week/total)
  • Recent Activity feed
  • Recent Tasks list
  • Spec Progress Cards

• Add spec link on Kanban task cards - clickable link to spec document

• Add spec badges in Docs page (SPEC badge, status badge)

• Add AC Progress bar for spec documents

• Add expandable linked tasks list in spec view

• Add Specs filter in Docs page

• Add status badge (Draft/Approved/Implemented) to spec cards

• Fix kanban navigation bug when closing task detail

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.6...v0.11.0

Release v0.10.6

Highlights

This release adds MCP Project Detection for global MCP configurations (like Antigravity) and cleans up deprecated agent commands.

What's Changed

Added

• MCP Project Detection Tools - New tools for AI agents using global MCP configs:
  • detect_projects - Scan for Knowns projects in common workspace directories
  • set_project - Set the active project for all MCP operations
  • get_current_project - Verify current project status
• Auto Antigravity MCP Config - Automatically creates MCP config at ~/.gemini/antigravity/mcp_config.json during knowns init
• GEMINI.md sync by default - Now included in default sync targets

Removed

• knowns agents command - Use knowns sync instead
• mcp__knowns__get_guideline tool - Guidelines are now embedded in instruction files (CLAUDE.md, GEMINI.md, AGENTS.md)

Documentation

• Updated MCP integration docs with project detection workflow
• Added Antigravity configuration examples
• Updated all command references to use knowns sync

Migration Guide

For CLI Users

# Before (deprecated)
knowns agents guideline
knowns agents sync

# After
knowns sync
knowns sync --all

For MCP Users (Antigravity/Global Configs)

Add session initialization at the start of each session:

// 1. Detect available projects
mcp__knowns__detect_projects({})

// 2. Set active project
mcp__knowns__set_project({ "projectRoot": "/path/to/project" })

// 3. Verify
mcp__knowns__get_current_project({})

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.5...v0.10.6

Release v0.10.5

What's New

Multi-Timer Support ⏱️

You can now run multiple timers concurrently - one per task. No more stopping your current timer to track time on another task!

• Concurrent timers: Start timers on multiple tasks simultaneously
• Task ID normalization: Use either 42 or task-42 format - both work everywhere
• Interactive selection: When multiple timers are running, CLI prompts you to choose which one to stop/pause

# Start timers on multiple tasks
knowns time start 1
knowns time start 2
knowns time status  # Shows all active timers

# Stop specific timer
knowns time stop 1

Template Import Prefix 📦

Templates from imports are now fully accessible via CLI and MCP using the import prefix.

# View imported template
knowns template knowns/knowns-command

# Run imported template
knowns template run knowns/knowns-command --name myCommand

• CLI/MCP support import-name/template-name syntax
• URL encoding fixed for template names with slashes

TreeView UI 🌳

New hierarchical tree view for better organization:

• DocsPage: Docs organized in collapsible folders
• ImportsPage: Imported files shown in tree structure
• TemplatesPage: Local and imported templates grouped separately
• Orphaned imports: Shows imports on disk but not in config

Bug Fixes 🐛

• Fixed duplicate update notification in CLI
• Fixed URL encoding for imported templates in UI

Changelog

Added

• Multi-timer support with concurrent task tracking
• Task ID normalization (42 and task-42 both valid)
• TreeView component for hierarchical file display
• Import prefix support for templates in CLI/MCP
• resolveTemplate for local and imported template resolution

Changed

• DocsPage, ImportsPage, TemplatesPage now use TreeView
• Update notifier shows only once per session
• Guidelines and skill instructions updated

Fixed

• Duplicate update notification in CLI
• URL encoding for template names with slashes
• Orphaned imports now visible in ImportsPage

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.4...v0.10.5

v0.10.4

Added

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Changed

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Documentation

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.3...v0.10.4

Fixed

• fix(mcp): fix template handler bugs and add syntax pitfall docs HO@howznguyen (#40)

Documentation

• fix(mcp): fix template handler bugs and add syntax pitfall docs HO@howznguyen (#40)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.2...v0.10.3

Fix

• Fix syncImport to bypass "already exists" check with isSync option
• Fix syncAllImports to sync all imports (not just autoSync)
• Add toast notifications for sync success/error in web UI
• Add imports field to config API response
• Improve type safety for imports in config handlers
• Fix auto-expand for imported docs in sidebar
• Add sourceUrl display for imported docs/templates in list commands

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.1...v0.10.2