konteks · zainphp · Jun 5, 2026 · Jun 5, 2026
diff --git a/README.md b/README.md
@@ -10,7 +10,6 @@ Memory artifacts are stored directly inside your repository, exposing compact, t
 
 ## 🚀 Key Features
 
-* **One-Off Setup**: Try or initialize Konteks with `npx` or `bunx`; use an installed CLI for MCP startup.
 * **Language-Aware**: Understands code structure across [various file types](src/assets/grammar-registry.ts).
 * **Local-First**: Your project memory stays in your repo—no cloud, no accounts.
 * **Token-Efficient**: High-fidelity context synthesis designed for LLM economy.

diff --git a/docs/api/cli.md b/docs/api/cli.md
@@ -1,6 +1,6 @@
 # CLI API
 
-The Konteks CLI manages local project memory. It can run through `npx`, `bunx`, `pnpm dlx`, or `yarn dlx` for one-off commands, but MCP server registration should use an installed `konteks-cli` executable for fast startup.
+The Konteks CLI manages local project memory. It can run through `npx`, `bunx`, `pnpm dlx`, or `yarn dlx` for one-off commands, but MCP server registration should use the installed command form that matches the user's runtime.
 
 For terms, see the [Glossary](../reference/glossary.md).
 
@@ -22,7 +22,7 @@ For terms, see the [Glossary](../reference/glossary.md).
 | `konteks install-skills` | Compatibility | Install Konteks skills for agents without MCP prompt support. |
 
 > [!IMPORTANT]
-> Configure MCP clients with an installed command such as `"command": "konteks-cli", "args": ["mcp"]`. Avoid one-off runners for MCP server startup because package resolution or downloads can exceed the client startup timeout.
+> Bun users should configure MCP clients with `"command": "bunx", "args": ["--bun", "konteks-cli", "mcp"]`. Node users can configure MCP with `"command": "konteks-cli", "args": ["mcp"]`; the direct `konteks-cli` command requires Node.js on `PATH` because the current package bin uses a Node shebang.
 
 ## Memory Portability
 

diff --git a/docs/for-agents/installation.md b/docs/for-agents/installation.md
@@ -21,12 +21,13 @@ Do not create a new application. Konteks is added to the project the user alread
 2. Check whether Konteks is already initialized by looking for `.konteks/config.json`.
 3. If it is already initialized, skip initialization and continue to MCP setup and workflow verification.
 4. Verify that either Node.js 22.13 or newer, or Bun 1.3 or newer, is available.
-5. Install `konteks-cli` globally with the available package manager.
-6. Run `konteks-cli init`.
-7. Configure the user's MCP-compatible agent to run `konteks-cli mcp`.
-8. Install compatibility skills only when the agent supports MCP tools but does not show MCP prompts.
-9. Run a quick verification command.
-10. Explain the exact next prompt the user should run at the start of future sessions.
+5. Select the command mode that matches the user's runtime preference.
+6. Install `konteks-cli` globally with the selected package manager.
+7. Run the selected initialization command.
+8. Configure the user's MCP-compatible agent with the selected MCP server definition.
+9. Install compatibility skills only when the agent supports MCP tools but does not show MCP prompts.
+10. Run a quick verification command.
+11. Explain the exact next prompt the user should run at the start of future sessions.
 
 ## Prerequisite Checks
 
@@ -40,17 +41,17 @@ npm -v
 bun --version
 ```
 
-Use whichever runtime is available:
+Select the package manager and command mode from the user's environment:
 
-* Prefer Bun when Bun 1.3 or newer is available.
-* Use npm when Node.js 22.13 or newer and npm are available but Bun is not available.
-* If both are available, prefer the package manager the user requested. If they did not express a preference, use Bun.
+* Use Bun mode when the user requested Bun, the project uses Bun, or Bun is the only supported runtime available.
+* Use npm mode when the user requested npm/Node, the project uses npm, or Node.js with npm is the only supported runtime available.
+* If both are available and there is no user or project signal, ask the user which package manager they prefer before installing globally.
 
 If neither supported runtime is available, stop and ask the user to install Node.js 22.13+ or Bun 1.3+ before continuing. Do not install system runtimes unless the user explicitly asks you to do that.
 
 ## Install Konteks Globally
 
-Install Konteks globally before running setup or configuring MCP. MCP clients expect the server process to start quickly; one-off package runners such as `npx`, `bunx`, `pnpm dlx`, and `yarn dlx` may spend time resolving or downloading packages before the server starts.
+Install Konteks globally before running setup or configuring MCP. MCP clients expect the server process to start quickly, so choose the command form that matches the user's runtime.
 
 With Bun:
 
@@ -71,6 +72,10 @@ If global package installation requires network access, package downloads, or el
 Run one initialization command from the project root:
 
 ```bash
+# Bun mode:
+bunx --bun konteks-cli init
+
+# npm mode:
 konteks-cli init
 ```
 
@@ -89,6 +94,21 @@ Add Konteks to the user's MCP-compatible coding agent configuration. Prefer a gl
 
 Use this MCP server definition:
 
+```json
+{
+  "mcpServers": {
+    "konteks": {
+      "command": "bunx",
+      "args": ["--bun", "konteks-cli", "mcp"]
+    }
+  }
+}
+```
+
+Use that MCP server definition in Bun mode. `--bun` forces Bun to run the CLI.
+
+In npm mode, use this MCP server definition:
+
 ```json
 {
   "mcpServers": {
@@ -115,20 +135,28 @@ Konteks exposes its lifecycle workflows as MCP prompts:
 If the current agent does not show MCP prompts in its prompt or command UI, install the same lifecycle workflows as native skills:
 
 ```bash
+# Bun mode:
+bunx --bun konteks-cli install-skills --global
+
+# npm mode:
 konteks-cli install-skills --global
 ```
 
-Use `--global` for agent compatibility skills, because these prompts are useful across projects and this playbook keeps Konteks installed globally.
+Use `--global` for agent compatibility skills, because these prompts are useful across projects.
 
 ## Verify Setup
 
 Run:
 
 ```bash
+# Bun mode:
+bunx --bun konteks-cli status
+
+# npm mode:
 konteks-cli status
 ```
 
-Successful setup means the status command can find the project root, memory directory, and indexed project memory. If status says memory is not initialized, return to the project root and run `konteks-cli init` again.
+Successful setup means the status command can find the project root, memory directory, and indexed project memory. If status says memory is not initialized, return to the project root and run the selected initialization command again.
 
 ## First Session Workflow
 
@@ -164,7 +192,7 @@ The save prompt should persist compact durable memories first, then one session
 * Do not commit `.konteks/`; initialization should add it to `.gitignore`.
 * Do not add Konteks as an application dependency unless the user explicitly asks for that.
 * Do not invent custom memory directories; Konteks uses `.konteks/` in the project root.
-* Do not configure MCP to launch Konteks through `npx`, `bunx`, `pnpm dlx`, or `yarn dlx`; use the globally installed `konteks-cli` command.
+* Do not configure MCP to launch Konteks through `npx`, plain `bunx`, `pnpm dlx`, or `yarn dlx`. Use `bunx --bun konteks-cli mcp` for Bun users and direct `konteks-cli mcp` for Node users.
 * Keep installation output brief. Report what was initialized, how MCP was configured, whether compatibility skills were installed, and the first prompt to run.
 * If network access, package downloads, or global config writes require approval, ask for approval with the exact command you need to run.
 
@@ -173,7 +201,7 @@ The save prompt should persist compact durable memories first, then one session
 When everything is ready, leave the user with a short message like:
 
 ```text
-Konteks is initialized for this project. I configured the MCP server with the globally installed `konteks-cli` command, installed global compatibility skills because this agent does not expose MCP prompts, and verified setup with `konteks-cli status`.
+Konteks is initialized for this project. I configured the MCP server with the selected global command mode, installed global compatibility skills because this agent does not expose MCP prompts, and verified setup with the status command.
 
 For future fresh sessions, start with `/konteks-warm-up`. Use `/konteks-recall <focus>` when you need focused project memory, and run `/konteks-save` before ending a meaningful session.
 ```
diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md
@@ -31,7 +31,7 @@ Konteks stores memory artifacts inside your repository, typically in a `.konteks
 We believe that setup should not be a barrier. Konteks can be tried and initialized through the JavaScript package ecosystem without a global install.
 
 * Use one-off runners such as `npx` or `bunx` for setup and trial commands.
-* Use an installed `konteks-cli` command for MCP server startup so agents do not wait on package resolution.
+* For MCP server startup, use the command form that matches your runtime: Bun users can use `bunx --bun konteks-cli mcp`, while Node users can use the installed `konteks-cli mcp` command.
 * No separate database service or external account required.
 * Works anywhere Node.js or Bun is available.
 

diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
@@ -35,20 +35,35 @@ Do not commit `.konteks/`; initialization adds it to `.gitignore` so project mem
 
 ### 2. Set Up MCP
 
-Install Konteks before configuring MCP. MCP clients expect the server process to start quickly, while one-off runners such as `npx`, `bunx`, `pnpm dlx`, and `yarn dlx` may spend time resolving or downloading packages before the server starts.
+Install Konteks before configuring MCP. Use the global install command that matches your runtime.
 
 ```bash
-npm install -g konteks-cli
-
-# or, with Bun:
 bun add -g konteks-cli
+npm install -g konteks-cli
+pnpm add -g konteks-cli
+yarn global add konteks-cli
 ```
 
-Add Konteks to your MCP-compatible coding agent configuration before opening the agent.
+Add one MCP server definition before opening the agent.
 
 > [!TIP]
 > **Global Registration**: Register Konteks globally in your agent's config so you don't have to repeat this setup for every project.
 
+For Bun users:
+
+```json
+{
+  "mcpServers": {
+    "konteks": {
+      "command": "bunx",
+      "args": ["--bun", "konteks-cli", "mcp"]
+    }
+  }
+}
+```
+
+For Node (npm/yarn/pnpm) users:
+
 ```json
 {
   "mcpServers": {
@@ -63,7 +78,7 @@ Add Konteks to your MCP-compatible coding agent configuration before opening the
 MCP configuration locations are agent-specific. Prefer a global registration when your agent supports it, and restart or reload the agent after changing its MCP configuration.
 
 > [!IMPORTANT]
-> Konteks exposes its lifecycle workflows as [MCP Prompts](https://modelcontextprotocol.io/docs/concepts/prompts). If your agent does not show MCP Prompts in its autocomplete UI, run `konteks-cli install-skills --global` once after installation to use the lifecycle prompts as native skills. See [Compatibility](../api/cli.md#compatibility-skills).
+> Konteks exposes its lifecycle workflows as [MCP Prompts](https://modelcontextprotocol.io/docs/concepts/prompts). If your agent does not show MCP Prompts in its autocomplete UI, run `bunx --bun konteks-cli install-skills --global` for Bun installs or `konteks-cli install-skills --global` for npm installs. See [Compatibility](../api/cli.md#compatibility-skills).
 
 ## From This Point On
 

diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md
@@ -33,13 +33,13 @@ This guide helps you resolve common issues encountered while setting up or using
 ### 4. "MCP Tool timeout or connection error"
 
 **Symptoms**: Your AI agent reports that it cannot connect to the Konteks server or the tool timed out.
-**Cause**: The MCP server process may have crashed, is taking too long to process a large project, or is being launched through a one-off package runner that must resolve or download packages before the server starts.
+**Cause**: The MCP server process may have crashed, is taking too long to process a large project, is being launched through a slow package runner, or the direct `konteks-cli` command cannot find Node.js on `PATH`.
 **Solution**:
 
-1. Install Konteks globally with `npm install -g konteks-cli` or `bun add -g konteks-cli`.
-2. Configure your MCP client with `"command": "konteks-cli"` and `"args": ["mcp"]`, not `npx`, `bunx`, `pnpm dlx`, or `yarn dlx`.
-3. Run `konteks-cli status` to check project memory freshness.
-4. Ensure you are using a supported runtime (Bun 1.3+ or Node 22.13+).
+1. Install Konteks globally with the runtime you use: `bun add -g konteks-cli` for Bun users, or `npm install -g konteks-cli` for Node users.
+2. With Bun, configure your MCP client with `"command": "bunx"` and `"args": ["--bun", "konteks-cli", "mcp"]`. With Node, configure it with `"command": "konteks-cli"` and `"args": ["mcp"]`.
+3. Run `bunx --bun konteks-cli status` for Bun installs or `konteks-cli status` for npm installs to check project memory freshness.
+4. Ensure you are using a supported runtime (Bun 1.3+ or Node 22.13+). If you configure MCP with direct `konteks-cli`, Node must be on `PATH`.
 5. Check `.konteks/errors.log` for recent internal Konteks errors.
 6. Check the logs of your AI agent/host for connection-level errors.