knowns-dev · howznguyen · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -127,6 +127,12 @@ jobs:
         with:
           node-version: '20'
 
+      - name: Cache semantic models
+        uses: actions/cache@v4
+        with:
+          path: ~/.knowns/models
+          key: semantic-models-${{ runner.os }}-all-MiniLM-L6-v2-v1
+
       - name: Install llvm-mingw toolchain
         if: runner.os == 'Windows'
         shell: bash

diff --git a/.knowns/config.json b/.knowns/config.json
@@ -46,12 +46,6 @@
     },
     "serverPort": 6420,
     "platforms": [
-      "claude-code",
-      "opencode",
-      "codex",
-      "kiro",
-      "gemini",
-      "copilot",
       "agents"
     ],
     "enableChatUI": false,

diff --git a/.knowns/docs/features/model-command.md b/.knowns/docs/features/model-command.md
@@ -1,17 +1,16 @@
 ---
 title: Model Command
+description: CLI command for managing embedding models - list, download, set, add custom models
 createdAt: '2026-02-24T07:29:13.547Z'
-updatedAt: '2026-03-08T18:22:07.249Z'
-description: >-
-  CLI command for managing embedding models - list, download, set, add custom
-  models
+updatedAt: '2026-06-04T04:50:30.572Z'
 tags:
   - feature
   - cli
   - model
   - embedding
   - search
 ---
+
 # Model Command
 
 Manage embedding models for semantic search.
@@ -241,3 +240,8 @@ knowns search --reindex
 
 - @doc/specs/semantic-search - Semantic search specification
 - @doc/guides/cli-guide - CLI usage guide
+
+
+### `knowns settings` Local ONNX picker
+
+`knowns settings` also manages semantic search. When the provider is Local ONNX, the settings flow shows all supported ONNX models with dimensions, max tokens, approximate size, and downloaded/not downloaded status. Selecting a missing model asks for confirmation and can download it with the existing semantic model download flow before saving the full local semantic config.
diff --git a/.knowns/docs/guides/cli-guide.md b/.knowns/docs/guides/cli-guide.md
@@ -1,13 +1,14 @@
 ---
 title: Knowns CLI Guide
-createdAt: '2025-12-26T19:43:25.470Z'
-updatedAt: '2026-03-08T18:22:39.448Z'
 description: Complete guide for using Knowns CLI
+createdAt: '2025-12-26T19:43:25.470Z'
+updatedAt: '2026-06-04T09:57:29.075Z'
 tags:
   - guide
   - cli
   - tutorial
 ---
+
 # Knowns CLI Guide
 
 Knowns is a CLI tool for managing tasks, documentation, and time tracking for development teams.
@@ -33,73 +34,69 @@ knowns init [project-name]
 
 ### Interactive Wizard
 
-When running without a name, the wizard prompts for:
+When running without a name, the wizard prompts for project basics and project instruction files:
 
-```
-Knowns Project Setup Wizard
-   Configure your project settings
+```text
+Knowns Project Setup
+   Quick configuration
 
 ? Project name > my-project
-? Git tracking mode > Git Tracked (recommended for teams)
-? AI Guidelines type > CLI / MCP
-? Select AI agent files > CLAUDE.md, AGENTS.md
+? Git tracking mode > Git Tracked  · tasks, docs, templates
+? Project instruction files > CLAUDE.md, AGENTS.md
 ```
 
+`KNOWNS.md` is always created as the canonical project guidance file when instruction shims are created. Compatibility shims such as `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `OPENCODE.md`, and `.github/copilot-instructions.md` defer behavior rules back to `KNOWNS.md`.
+
 **Example session:**
-```
+```text
 $ knowns init
 
-Knowns Project Setup Wizard
-   Configure your project settings
+Knowns Project Setup
+   Quick configuration
 
 ? Project name > my-app
-? Git tracking mode > Git Tracked (recommended for teams)
-? AI Guidelines type > MCP
-? Select AI agent files > CLAUDE.md, AGENTS.md
+? Git tracking mode > Git Tracked  · tasks, docs, templates
+? Project instruction files > CLAUDE.md, AGENTS.md
 
-Created .mcp.json for Claude Code MCP auto-discovery
 Project initialized: my-app
+Created: KNOWNS.md
 Created: CLAUDE.md
 Created: AGENTS.md
 
 Get started:
   knowns task create "My first task"
+  knowns setup all
 ```
 
 ### Wizard Options
 
 | Option | Description |
 |--------|-------------|
 | **Project name** | Name of your project |
-| **Git tracking mode** | `git-tracked` (team) or `git-ignored` (personal) |
-| **AI Guidelines type** | `CLI` (commands) or `MCP` (MCP tools) |
-| **AI agent files** | Files to update with guidelines |
+| **Git tracking mode** | `git-tracked`, `git-ignored`, or `none` |
+| **Project instruction files** | Compatibility shims to create; defaults to `CLAUDE.md` and `AGENTS.md` |
 
 ### Quick Init (Non-Interactive)
 
 ```bash
 knowns init my-project --no-wizard
 ```
 
-### MCP Auto-Setup
+Non-interactive init uses global project defaults when configured, otherwise it creates the default project guidance set: `KNOWNS.md`, `CLAUDE.md`, and `AGENTS.md`.
+
+### AI Integration Setup
 
-When selecting **MCP** in the wizard, a `.mcp.json` file is automatically created:
+`knowns init` does not create project-level AI integration config such as `.mcp.json`, `.codex/config.toml`, or runtime hooks. Use `knowns setup` for those artifacts:
 
-```json
-{
-  "mcpServers": {
-    "knowns": {
-      "command": "knowns",
-      "args": ["mcp"]
-    }
-  }
-}
+```bash
+knowns setup all            # configure all selected project integrations
+knowns setup agents         # create/sync KNOWNS.md + AGENTS.md only
+knowns setup codex --global # install Codex integration at user scope
 ```
 
-This enables Claude Code to auto-discover the MCP server.
+This keeps global runtime setup separate from repo-specific project guidance.
 
 ---
-
 ## MCP Setup
 
 ### Quick Setup

diff --git a/README.md b/README.md
@@ -31,7 +31,12 @@ Every time you start a new AI coding session, you re-explain your architecture,
 If you believe AI should truly understand software projects, consider giving **Knowns** a star.
 
 <p align="center">
-  <img src="./images/task-workflow.gif" alt="Knowns task workflow demo" width="100%">
+  <a href="https://player.cloudinary.com/embed/?cloud_name=dkxhoyenc&public_id=knowns-full-pipeline_uwhyk1">
+    <img src="./images/knowns-full-pipeline-20s.gif" alt="Knowns full pipeline demo preview" width="100%">
+  </a>
+</p>
+<p align="center">
+  <em>Click the preview to watch the full pipeline demo video.</em>
 </p>
 
 ## Table of Contents
@@ -150,6 +155,7 @@ knowns --version
 # Initialize in your project
 cd your-project
 knowns init
+# Creates .knowns/ plus KNOWNS.md, CLAUDE.md, and AGENTS.md by default
 
 # or run without a global install
 npx knowns init
@@ -450,8 +456,10 @@ knowns lsp list
 knowns lsp install <language>
 # Use the MCP code tool for symbols, definitions, references, diagnostics, and edits
 
-# AI Guidelines
-knowns setup
+# AI setup
+knowns setup agents        # KNOWNS.md + AGENTS.md only
+knowns setup codex --global # user-level Codex MCP/skills/hooks
+knowns setup               # full interactive project integration setup
 knowns sync
 ```
 

diff --git a/README.vi.md b/README.vi.md
@@ -31,7 +31,12 @@ Mỗi lần mở session mới với AI, bạn lại phải giải thích lại
 Nếu bạn nghĩ AI nên thực sự hiểu software project, cho **Knowns** một star nhé.
 
 <p align="center">
-  <img src="./images/task-workflow.gif" alt="Knowns task workflow demo" width="100%">
+  <a href="https://player.cloudinary.com/embed/?cloud_name=dkxhoyenc&public_id=knowns-full-pipeline_uwhyk1">
+    <img src="./images/knowns-full-pipeline-20s.gif" alt="Knowns full pipeline demo preview" width="100%">
+  </a>
+</p>
+<p align="center">
+  <em>Click preview để xem video full pipeline.</em>
 </p>
 
 ## Mục lục
@@ -150,6 +155,7 @@ knowns --version
 # Init trong project
 cd your-project
 knowns init
+# Mặc định tạo .knowns/ cùng KNOWNS.md, CLAUDE.md, AGENTS.md
 
 # Hoặc chạy không cần cài global
 npx knowns init
@@ -450,8 +456,10 @@ knowns lsp list
 knowns lsp install <language>
 knowns lsp cleanup
 
-# AI Guidelines
-knowns setup
+# AI setup
+knowns setup agents        # chỉ KNOWNS.md + AGENTS.md
+knowns setup codex --global # Codex MCP/skills/hooks ở user scope
+knowns setup               # interactive project integration setup đầy đủ
 knowns sync
 ```
 

diff --git a/docs/en/getting-started/quick-start.md b/docs/en/getting-started/quick-start.md
@@ -14,10 +14,11 @@ The init flow configures:
 
 - project name
 - git tracking mode (with per-section toggles)
+- project instruction files (`KNOWNS.md`, default `CLAUDE.md` + `AGENTS.md`)
 - semantic search
 - embedding model
 
-> **Note:** AI platform integrations (instructions, MCP configs, skills) are configured separately via `knowns setup`.
+> **Note:** `knowns init` creates project guidance files. AI platform integrations such as MCP configs, skills, and runtime hooks are configured separately via `knowns setup`.
 
 ## 2. Create a task
 

diff --git a/docs/en/guides/user-guide.md b/docs/en/guides/user-guide.md
@@ -21,9 +21,10 @@ The CLI, MCP server, and browser UI all operate on the same project state.
   - project structure creation
   - settings application
   - git integration configuration
+  - project instruction file creation (`KNOWNS.md`, default `CLAUDE.md` + `AGENTS.md`)
   - semantic index building (if enabled)
 
-After init, run `knowns setup` to configure AI platform integrations (skills, MCP configs, instruction files).
+After init, run `knowns setup <target>` to configure AI platform integrations such as skills, MCP configs, and runtime hooks. Use `knowns setup agents` if you only need `KNOWNS.md` + `AGENTS.md`.
 
 ## Terminal behavior
 

diff --git a/docs/en/integrations/compatibility.md b/docs/en/integrations/compatibility.md
@@ -43,11 +43,11 @@ For Antigravity, the MCP config is global:
 
 ### `knowns init`
 
-Creates the project structure, git tracking, and semantic search setup.
+Creates the project structure, git tracking, semantic search setup, and selected project instruction shims (`KNOWNS.md`, default `CLAUDE.md` + `AGENTS.md`).
 
 ### `knowns setup`
 
-Generates AI platform artifacts (skills, instructions, MCP configs, runtime hooks).
+Generates AI platform artifacts such as skills, MCP configs, platform-specific configs, runtime hooks, and any additional instruction files for the selected target. Use `knowns setup agents` when you only need `KNOWNS.md` + `AGENTS.md`.
 
 ### `knowns sync`
 

diff --git a/docs/en/integrations/guidance-files.md b/docs/en/integrations/guidance-files.md
@@ -17,9 +17,11 @@ Knowns uses one canonical file plus several compatibility files for AI runtimes.
 ## Refresh generated content
 
 ```bash
+knowns init
+knowns setup agents
 knowns setup
 knowns sync
 knowns sync --instructions
 ```
 
-Use `knowns setup` to generate platform files initially, or `knowns sync` to refresh them.
+Use `knowns init` to create initial project guidance files. Use `knowns setup agents` to create or refresh only `KNOWNS.md` + `AGENTS.md`, `knowns setup <target>` for full platform integrations, or `knowns sync` to refresh generated files from config.
diff --git a/docs/en/integrations/platforms.md b/docs/en/integrations/platforms.md
@@ -30,17 +30,21 @@ Knowns can generate and sync different artifacts for different AI platforms via
 
 ## Setup
 
-AI integration files are generated via `knowns setup`, not during `knowns init`:
+`knowns init` creates project guidance files so agents can read repo rules immediately. AI integration artifacts are generated via `knowns setup`:
 
 ```bash
 knowns setup claude    # CLAUDE.md, .mcp.json, skills, hooks
 knowns setup opencode  # OPENCODE.md, opencode.json, skills, hooks
+knowns setup codex     # AGENTS.md, .codex/config.toml, skills, hooks
 knowns setup kiro      # .kiro steering/settings, skills, hooks
 knowns setup copilot   # .github/copilot-instructions.md
+knowns setup agents    # KNOWNS.md + AGENTS.md only
 knowns setup all       # All supported platforms
 ```
 
 ## Notes
 
 - `.agents/skills` is the primary path for agent-compatible platforms
-- `knowns init` no longer generates AI integration files — use `knowns setup` after init
+- `knowns init` creates selected instruction shims by default (`KNOWNS.md`, `CLAUDE.md`, `AGENTS.md`)
+- use `knowns setup <target>` for project-level MCP/config files, skills, and runtime hooks
+- use `knowns setup codex --global` when Codex integration should live only at user scope
diff --git a/docs/en/reference/commands.md b/docs/en/reference/commands.md
@@ -24,9 +24,12 @@ What `init` configures:
 
 - project name
 - git tracking mode (with per-section toggles)
+- project instruction files (`KNOWNS.md`, default `CLAUDE.md` + `AGENTS.md`)
 - semantic search
 - embedding model
 
+`knowns init` creates project guidance files, but leaves MCP configs, skills, and runtime hooks to `knowns setup`.
+
 ### `knowns setup`
 
 Configures AI tool integrations for an initialized project.
@@ -35,8 +38,11 @@ Configures AI tool integrations for an initialized project.
 knowns setup              # Interactive platform selector
 knowns setup claude       # Claude Code: CLAUDE.md, .mcp.json, skills, hooks
 knowns setup opencode     # OpenCode: OPENCODE.md, opencode.json, skills, hooks
+knowns setup codex        # Codex: AGENTS.md, .codex/config.toml, skills, hooks
 knowns setup kiro         # Kiro: .kiro steering/settings, skills, hooks
 knowns setup copilot      # GitHub Copilot: .github/copilot-instructions.md
+knowns setup agents       # KNOWNS.md + AGENTS.md only
+knowns setup codex --global # Codex user-level MCP/skills/hooks
 knowns setup all          # All supported platforms
 ```
 
@@ -69,6 +75,17 @@ knowns update
 knowns update --check
 ```
 
+### `knowns settings`
+
+Opens the interactive project settings center.
+
+```bash
+knowns settings
+knowns settings --global
+```
+
+Use `knowns settings` for human-friendly project edits: project name, git tracking, AI platforms, search, code intelligence, Browser/Chat UI, and maintenance guidance. In Search settings, Local ONNX models are listed with downloaded/not downloaded status; selecting a missing model can download it before saving. Use `knowns settings --global` for defaults reused by future `knowns init` runs. Use `knowns config get/set/list/reset` when you need scriptable config access.
+
 ## Tasks
 
 ### Create