feat(workspace): add multi-project workspace switching and hub mode

.agent/skills/.version

@@ -1,4 +1,4 @@
 {
   "cliVersion": "dev",
-  "syncedAt": "2026-03-19T09:17:14Z"
+  "syncedAt": "2026-03-24T09:06:19Z"
 }

.air.toml

@@ -2,8 +2,8 @@ root = "."
 tmp_dir = "tmp"
 
 [build]
-cmd = "go build -o ./tmp/knowns ./cmd/knowns"
-entrypoint = ["./tmp/knowns", "browser", "--dev", "--port", "6420", "--no-open"]
+cmd = "go build -o ./tmp/knowns ./cmd/knowns && lsof -ti:6420 | xargs kill -9 2>/dev/null || true"
+entrypoint = ["./tmp/knowns", "browser", "--restart", "--dev", "--port", "6420", "--no-open"]
 include_ext = ["go"]
 exclude_dir = ["tmp", "bin", "ui", "node_modules", ".git", ".knowns"]
 delay = 200

.claude/skills/.version

@@ -1,4 +1,4 @@
 {
   "cliVersion": "dev",
-  "syncedAt": "2026-03-19T09:17:14Z"
+  "syncedAt": "2026-03-24T09:06:19Z"
 }

.github/copilot-instructions.md

@@ -1,9 +1,11 @@
-# knowns - GitHub Copilot Instructions
+# knowns-go - GitHub Copilot Instructions
 
 Compatibility entrypoint for runtimes that auto-detect `.github/copilot-instructions.md`.
 
 <!-- KNOWNS GUIDELINES START -->
 
+**CRITICAL: You MUST read and follow `KNOWNS.md` in the repository root before doing any work. It is the canonical source of truth for all agent behavior in this project.**
+
 ## Canonical Guidance
 
 - Knowns is the repository memory layer for humans and the AI-friendly working layer for agents.

.github/workflows/publish.yml

@@ -413,6 +413,28 @@ jobs:
             rm "$base"
           done
 
+      - name: Verify tarball contents
+        run: |
+          for archive in \
+            knowns-darwin-arm64.tar.gz \
+            knowns-darwin-x64.tar.gz \
+            knowns-linux-arm64.tar.gz \
+            knowns-linux-x64.tar.gz; do
+            tar -tzf "$archive" | grep -Fx "knowns" >/dev/null || {
+              echo "Expected $archive to contain 'knowns'"
+              exit 1
+            }
+          done
+
+          for archive in \
+            knowns-win-arm64.tar.gz \
+            knowns-win-x64.tar.gz; do
+            tar -tzf "$archive" | grep -Fx "knowns.exe" >/dev/null || {
+              echo "Expected $archive to contain 'knowns.exe'"
+              exit 1
+            }
+          done
+
       - name: Ensure GitHub release exists
         if: github.event_name == 'release'
         env:
@@ -477,11 +499,11 @@ jobs:
 
             def install
               if OS.mac? && Hardware::CPU.arm?
-                bin.install "knowns-darwin-arm64" => "knowns"
+                bin.install "knowns" => "knowns"
               elsif OS.mac? && Hardware::CPU.intel?
-                bin.install "knowns-darwin-x64" => "knowns"
+                bin.install "knowns" => "knowns"
               elsif OS.linux? && Hardware::CPU.intel?
-                bin.install "knowns-linux-x64" => "knowns"
+                bin.install "knowns" => "knowns"
               end
               bin.install_symlink "knowns" => "kn"
             end

.kiro/skills/.version

@@ -0,0 +1,4 @@
+{
+  "cliVersion": "dev",
+  "syncedAt": "2026-03-24T09:06:19Z"
+}

.kiro/skills/kn-commit/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: kn-commit
+description: Use when committing code changes with proper conventional commit format and verification
+---
+
+# Committing Changes
+
+**Announce:** "Using kn-commit to commit changes."
+
+**Core principle:** VERIFY BEFORE COMMITTING - check staged changes, ask for confirmation.
+
+## Inputs
+
+- Current staged changes
+- Relevant task IDs, scope, and reason for the change
+
+## Preflight
+
+- Confirm the correct files are staged
+- Check whether the commit should reference a task or feature area
+- Refuse to commit if the staged diff looks unrelated or mixed across multiple concerns
+
+## Step 1: Review Staged Changes
+
+```bash
+git status
+git diff --staged
+```
+
+## Step 2: Generate Commit Message
+
+**Format:**
+```
+<type>(<scope>): <message>
+
+- Bullet point summarizing change
+```
+
+**Types:** feat, fix, docs, style, refactor, perf, test, chore
+
+**Rules:**
+- Title lowercase, no period, max 50 chars
+- Body explains *why*, not just *what*
+
+## Step 3: Ask for Confirmation
+
+```
+Ready to commit:
+
+feat(auth): add JWT token refresh
+
+- Added refresh token endpoint
+
+Proceed? (yes/no/edit)
+```
+
+**Wait for user approval.**
+
+## Step 4: Commit
+
+```bash
+git commit -m "feat(auth): add JWT token refresh
+
+- Added refresh token endpoint"
+```
+
+## Final Response Contract
+
+All built-in skills in scope must end with the same user-facing information order: `kn-init`, `kn-spec`, `kn-plan`, `kn-research`, `kn-implement`, `kn-verify`, `kn-doc`, `kn-template`, `kn-extract`, and `kn-commit`.
+
+Required order for the final user-facing response:
+
+1. Goal/result - state whether a commit was proposed, blocked, or created.
+2. Key details - include the proposed or final commit message, relevant diff concerns, and approval status.
+3. Next action - recommend a concrete follow-up command only when a natural handoff exists.
+
+Keep this concise for CLI use. Skill-specific content may extend the key-details section, but must not replace or reorder the shared structure.
+
+Out of scope: explaining, syncing, or generating `.claude/skills/*`. Runtime auto-sync already handles platform copies, so this skill source only defines the built-in output contract.
+
+For `kn-commit`, the key details should cover:
+
+- the proposed commit title
+- 1 short body explaining why
+- any concerns about the staged diff
+- a clear approval prompt
+
+## Guidelines
+
+- Only commit staged files
+- NO "Co-Authored-By" lines
+- NO "Generated with Claude Code" ads
+- Ask before committing
+
+## Next Step Suggestion
+
+When a follow-up is natural, recommend exactly one next command:
+
+- after proposing a commit: no command, wait for approval
+- after a successful commit tied to active work: `/kn-verify`
+- after a successful standalone commit: `/kn-extract` or the next task-specific workflow command if one is obvious
+
+## Checklist
+
+- [ ] Reviewed staged changes
+- [ ] Message follows convention
+- [ ] User approved
+- [ ] Next action suggested when applicable
+
+## Abort Conditions
+
+- Nothing staged
+- Staged diff includes unrelated work that should be split
+- User has not explicitly approved the final message

.kiro/skills/kn-doc/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: kn-doc
+description: Use when working with Knowns documentation - viewing, searching, creating, or updating docs
+---
+
+# Working with Documentation
+
+**Announce:** "Using kn-doc to work with documentation."
+
+**Core principle:** SEARCH BEFORE CREATING - avoid duplicates.
+
+## Inputs
+
+- Doc path, topic, folder, or task/spec reference
+- Whether this is a create, update, or search request
+
+## Preflight
+
+- Search before creating
+- Prefer section edits for targeted changes
+- Preserve doc structure and metadata unless the user asked for a restructure
+- Validate refs after doc changes
+
+## Quick Reference
+
+```json
+// List docs
+mcp__knowns__list_docs({})
+
+// View doc (smart mode)
+mcp__knowns__get_doc({ "path": "<path>", "smart": true })
+
+// Search docs
+mcp__knowns__search({ "query": "<query>", "type": "doc" })
+
+// Create doc (MUST include description)
+mcp__knowns__create_doc({
+  "title": "<title>",
+  "description": "<brief description of what this doc covers>",
+  "tags": ["tag1", "tag2"],
+  "folder": "folder"
+})
+
+// Update content
+mcp__knowns__update_doc({
+  "path": "<path>",
+  "content": "content"
+})
+
+// Update metadata (title, description, tags)
+mcp__knowns__update_doc({
+  "path": "<path>",
+  "title": "New Title",
+  "description": "Updated description",
+  "tags": ["new", "tags"]
+})
+
+// Update section only
+mcp__knowns__update_doc({
+  "path": "<path>",
+  "section": "2",
+  "content": "## 2. New Content\n\n..."
+})
+```
+
+## Creating Documents
+
+1. Search first (avoid duplicates)
+2. Choose location:
+
+| Type | Folder |
+|------|--------|
+| Core | (root) |
+| Guide | `guides` |
+| Pattern | `patterns` |
+| API | `api` |
+
+3. Create with **title + description + tags**
+4. Add content
+5. **Validate** after creating
+
+**CRITICAL:** Always include `description` - validate will fail without it!
+
+## Updating Documents
+
+**Section edit is most efficient:**
+```json
+mcp__knowns__update_doc({
+  "path": "<path>",
+  "section": "3",
+  "content": "## 3. New Content\n\n..."
+})
+```
+
+## Validate After Changes
+
+**CRITICAL:** After creating/updating docs, validate:
+
+```json
+// Validate specific doc (saves tokens)
+mcp__knowns__validate({ "entity": "<doc-path>" })
+
+// Or validate all docs
+mcp__knowns__validate({ "scope": "docs" })
+```
+
+If errors found, fix before continuing.
+
+## Shared Output Contract
+
+All built-in skills in scope must end with the same user-facing information order: `kn-init`, `kn-spec`, `kn-plan`, `kn-research`, `kn-implement`, `kn-verify`, `kn-doc`, `kn-template`, `kn-extract`, and `kn-commit`.
+
+Required order for the final user-facing response:
+
+1. Goal/result - state what doc was created, updated, inspected, or ruled out.
+2. Key details - include the most important supporting context, refs, path, warnings, or validation.
+3. Next action - recommend a concrete follow-up command only when a natural handoff exists.
+
+Keep this concise for CLI use. Documentation-specific content may extend the key-details section, but must not replace or reorder the shared structure.
+
+Out of scope: explaining, syncing, or generating `.claude/skills/*`. Runtime auto-sync already handles platform copies, so this skill source only defines the built-in output contract.
+
+For `kn-doc`, the key details should cover:
+
+- whether the doc was created, updated, or only inspected
+- the canonical doc path
+- any important refs added or fixed
+- validation result
+
+When doc work naturally leads to another action, include the best next command. If the request ends with inspection or a fully validated update, do not force a handoff.
+
+## Mermaid Diagrams
+
+WebUI supports mermaid rendering. Use for:
+- Architecture diagrams
+- Flowcharts
+- Sequence diagrams
+- Entity relationships
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+````
+
+Diagrams render automatically in WebUI preview.
+
+## Checklist
+
+- [ ] Searched for existing docs
+- [ ] Created with **description** (required!)
+- [ ] Used section editing for updates
+- [ ] Used mermaid for complex flows (optional)
+- [ ] Referenced with `@doc/<path>`
+- [ ] **Validated after changes**
+
+## Red Flags
+
+- Creating near-duplicate docs instead of updating an existing one
+- Replacing a full doc when only one section needed a change
+- Leaving broken refs after an edit