@tyvm/knowhow 0.0.109 → 0.0.111

package/autodoc/config-reference.md

@@ -1,46 +1,71 @@
 # `knowhow.json` Configuration Reference
 
-This document describes how to configure Knowhow CLI using a `knowhow.json` file (local or global).
+`knowhow.json` is the main configuration file for the **Knowhow CLI**. In a project, it lives at:
 
-- **Local path:** `.knowhow/knowhow.json`
-- **Global path:** `~/.knowhow/knowhow.json`
+- `./.knowhow/knowhow.json`
 
-> **Format:** JSON object  
-> **Purpose:** Configure prompts, generation pipelines, embedding pipelines, plugins/modules, custom agents, MCP servers, model providers, chat UI, the worker sandbox, and language tooling (ycmd).
+During `knowhow init`, Knowhow also creates a global config at:
+
+- `~/.knowhow/knowhow.json`
+
+> This reference is derived from the `Config` type (`src/types.ts`) and the default config/template behavior (`src/config.ts`).
+
+---
+
+## Example (minimal)
+
+```json
+{
+  "promptsDir": ".knowhow/prompts",
+  "modules": [],
+  "plugins": { "enabled": [], "disabled": [] },
+  "sources": [],
+  "embedSources": [],
+  "embeddingModel": "openai:EmbeddingAda2",
+  "agents": [],
+  "mcps": [],
+  "modelProviders": []
+}
+```
 
 ---
 
 ## Top-level keys
 
-| Key | Type | Description | Example |
-|---|---|---|---|
-| `promptsDir` | `string` | Directory that contains prompt templates (`{promptName}.mdx`). | `.knowhow/prompts` |
-| `sources` | `SourceConfig[]` | Generation pipeline(s) that turn inputs into generated outputs. | see “sources” section |
-| `embedSources` | `EmbedSourceConfig[]` | Embedding pipeline(s) that turn inputs into embedding artifacts (often JSON). | see “embedSources” section |
-| `embeddingModel` | `string` | Embedding model identifier used by the embedding pipeline. | `openai:EmbeddingAda2` *(value format depends on your setup)* |
-| `plugins` | `PluginsConfig` | Enable/disable built-in plugins. | `{ "enabled": ["embeddings"], "disabled": [] }` |
-| `pluginPackages` | `string[]` | Extra/custom plugin npm packages to load. | `["@myorg/knowhow-plugin-acme"]` |
-| `modules` | `ModuleConfig[]` | Load custom npm modules that can add tools/agents/plugins/clients. | `[{"package":"@myorg/knowhow-module-x"}]` |
-| `agents` | `AgentConfig[]` | Custom agent definitions (for generation/chat). | see “agents/assistants” section |
-| `assistants` | `AgentConfig[]` | Additional/custom agent definitions (same shape as `agents`). | see “agents/assistants” section |
-| `mcps` | `McpServerConfig[]` | MCP server configurations Knowhow can connect to. | see “mcps” section |
-| `modelProviders` | `ModelProviderConfig[]` | Custom model provider endpoints. | see “modelProviders” section |
-| `lintCommands` | `Record<string,string>` | Lint command per file extension. | `{ "ts": "eslint $1" }` |
-| `chat` | `ChatConfig` | Chat runtime configuration (renderer + module wiring). | see “chat” section |
-| `worker` | `WorkerConfig` | Worker execution and networking configuration. | see “worker” section |
-| `skills` | `string[]` | Directories containing “skills” (domain/tool logic). | `[".knowhow/skills"]` |
-| `files` | `FileSyncConfig` | File sync configuration (tooling-specific; schema varies by build). | see “files” section |
-| `ycmd` | `YcmdConfig` | ycmd language-server configuration. | see “ycmd” section |
+| Key | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `openaiBaseUrl` | `string` | No | — | Base URL override for OpenAI-compatible APIs. |
+| `promptsDir` | `string` | **Yes** | `.knowhow/prompts` | Directory containing prompt templates (`*.mdx`). |
+| `lintCommands` | `{ [fileExtension: string]: string }` | No | see defaults | Lint commands run after successful patches (by extension). |
+| `orgId` | `string` | No | — | Organization ID (used by some providers / services). |
+| `syncRemote` | `boolean` | No | `false` | Whether remote operations should use sync behavior (tooling-dependent). |
+| `micCommand` | `string` | No | — | Mic command (for audio-related workflows; provider/tool-dependent). |
+| `defaultMic` | `string` | No | — | Default microphone identifier (if applicable). |
+| `sources` | `GenerationSource[]` | **Yes** | see defaults | File generation pipeline for `knowhow generate`. |
+| `embedSources` | `EmbedSource[]` | **Yes** | see defaults | Embedding pipeline for `knowhow embed`. |
+| `embeddingModel` | `string` | **Yes** | `EmbeddingModels.openai.EmbeddingAda2` | Embedding model ID/name. |
+| `skills` | `string[]` | No | — | Directories to load “skills” from (custom behavior; plugin/tooling dependent). |
+| `plugins` | `{ enabled: string[]; disabled: string[] }` | **Yes** | see defaults | Plugin enable/disable lists. |
+| `chat` | `{ rootModule?: string; renderer?: string; modules?: string[] }` | No | — | Chat UI/runtime configuration. |
+| `modules` | `string[]` | **Yes** | `[]` | Extra NPM modules to load (tools/agents/plugins/clients). |
+| `agents` | `Assistant[]` | **Yes** | see default | Custom chat agents available in Knowhow chat. |
+| `mcps` | `McpConfig[]` | **Yes** | see defaults | MCP servers to start/connect. |
+| `modelProviders` | `ModelProvider[]` | **Yes** | see defaults | Custom model provider endpoints/config. |
+| `ycmd` | `{ enabled?: boolean; installPath?: string; port?: number; logLevel?: ...; completionTimeout?: number }` | No | see defaults | ycmd language server configuration. |
+| `files` | `{ remotePath: string; localPath: string; direction?: "download" \| "upload" \| "sync" }[]` | No | — | Remote/local file sync configuration. |
+| `worker` | `worker` config object | No | partial defaults | Worker runtime sandbox/tunnel/tools. |
 
 ---
 
 ## `promptsDir`
 
 - **Type:** `string`
-- **Description:** Directory containing prompt templates as `{promptName}.mdx`.
-- **How it’s used:** When a prompt name is referenced (e.g., `sources[].prompt`), Knowhow loads:
-  - `path.join(promptsDir, `${promptName}.mdx`)`
-- **Example:**
+- **Required:** Yes
+- **Description:** Directory where prompt templates are stored. Prompt files are looked up as:
+  - `${promptsDir}/${promptName}.mdx`
+- **Default:** `.knowhow/prompts`
+
+**Example**
 ```json
 {
   "promptsDir": ".knowhow/prompts"
@@ -49,25 +74,118 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
 
 ---
 
+## `modules`
+
+- **Type:** `string[]`
+- **Required:** Yes
+- **Description:** List of extra NPM modules to load. These can provide custom tools, agents, plugins, or clients.
+- **Default:** `[]`
+
+**Example**
+```json
+{
+  "modules": ["@myorg/knowhow-tools", "@myorg/knowhow-agent-awesome"]
+}
+```
+
+> Note: `knowhow init` automatically ensures `@tyvm/knowhow-module-script` is present in the global config.
+
+---
+
+## `plugins`
+
+- **Type:**
+  ```ts
+  { enabled: string[]; disabled: string[] }
+  ```
+- **Required:** Yes
+- **Default:**
+  ```json
+  {
+    "enabled": [
+      "embeddings","language","git","vim","github","asana","jira","linear",
+      "download","figma","url","tmux","agents-md","exec"
+    ],
+    "disabled": []
+  }
+  ```
+- **Description:** Enables/disables plugin names. Plugins provide integrations/tools and (for embedding) implementations keyed by `embedSources[].kind`.
+
+### Default/commonly referenced plugins
+
+| Plugin name | What it does (based on shipped examples) |
+|---|---|
+| `embeddings` | Provides embedding support; used by `embedSources` via `kind`. |
+| `language` | Language terms/hotkeys that expand into larger content (configured in `.knowhow/language.json`). |
+| `git` | Git integration (resolve/operate on git-related data; exact behavior plugin-defined). |
+| `vim` | Vim integration for loading/editing files (chat tools and patching flows). |
+| `github` | Resolve GitHub resources (PRs/issues) and fetch content referenced by URLs. |
+| `asana` | Resolve Asana tasks/lists referenced in inputs. |
+| `jira` | Resolve Jira issues/projects referenced in inputs. |
+| `linear` | Resolve Linear issues referenced in inputs. |
+| `download` | Download remote content referenced by `embedSources` / other pipelines. |
+| `figma` | Resolve design files from Figma. |
+| `url` | Resolve/generalize URL references into usable content. |
+| `tmux` | Integrate with tmux sessions (tooling-dependent). |
+| `agents-md` | Markdown-backed agent definitions (tooling-dependent). |
+| `exec` | Execute commands (tooling-dependent). |
+| `notion` *(seen in examples)* | Notion integration (tooling-dependent). |
+
+**Example**
+```json
+{
+  "plugins": {
+    "enabled": ["embeddings", "language", "github", "asana"],
+    "disabled": ["exec"]
+  }
+}
+```
+
+---
+
+## `lintCommands`
+
+- **Type:** `{ [fileExtension: string]: string }`
+- **Required:** No
+- **Default (partial):**
+  ```json
+  { "js": "eslint", "ts": "tslint" }
+  ```
+- **Description:** Commands run after an agent successfully patches a file, when the patched file extension matches the key.  
+  - `$1` is replaced with the patched file path.
+
+**Example**
+```json
+{
+  "lintCommands": {
+    "js": "eslint $1",
+    "ts": "tsc -p tsconfig.json && eslint $1"
+  }
+}
+```
+
+---
+
 ## `sources` (generation pipeline)
 
-- **Type:** `SourceConfig[]`
-- **Description:** Defines how Knowhow generates outputs from inputs by selecting a prompt and (optionally) an agent and model.
+- **Type:** `GenerationSource[]`
+- **Required:** Yes
+- **Purpose:** Used by `knowhow generate` to process input files and write output artifacts.
 
-### `SourceConfig`
+Each `GenerationSource` has:
 
-| Key | Type | Required | Description | Example |
+| Field | Type | Required | Default | Description |
 |---|---|---:|---|---|
-| `input` | `string` | ✅ | Input path/glob/identifier for this stage. | `src/**/*.mdx` |
-| `output` | `string` | ✅ | Output path (file or directory target). | `.knowhow/docs/` |
-| `prompt` | `string` | ✅ | Prompt name (from `promptsDir`) or a prompt reference. | `BasicCodeDocumenter` |
-| `kind` | `string` | ❌ | Generation “kind” (mode/behavior); often tied to plugins. | `summarization` |
-| `agent` | `string` | ❌ | Name of a custom agent used for this source. | `Example agent` |
-| `model` | `string` | ❌ | Model override for this source. | `gpt-4o-2024-08-06` |
-| `outputExt` | `string` | ❌ | Output file extension override. | `.mdx` |
-| `outputName` | `string` | ❌ | Output file/base name override. | `README.mdx` |
-
-### Example
+| `input` | `string` | Yes | — | Glob/path(s) to read input files. |
+| `output` | `string` | Yes | — | Output directory or file target. |
+| `prompt` | `string` | Yes | — | Prompt name (looks up `${promptsDir}/${prompt}.mdx`) or a direct prompt string. |
+| `kind` | `string` | No | — | Optional kind for pipeline/tooling behavior. |
+| `agent` | `string` | No | — | Agent name to use for generating output. |
+| `model` | `string` | No | — | Model override. |
+| `outputExt` | `string` | No | — | Output file extension override. |
+| `outputName` | `string` | No | — | Output file name override. |
+
+**Example**
 ```json
 {
   "sources": [
@@ -79,8 +197,22 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
     {
       "input": ".knowhow/docs/**/*.mdx",
       "output": ".knowhow/docs/README.mdx",
-      "prompt": "BasicProjectDocumenter",
-      "kind": "project"
+      "prompt": "BasicProjectDocumenter"
+    }
+  ]
+}
+```
+
+**Example (agent + model)**
+```json
+{
+  "sources": [
+    {
+      "input": ".knowhow/downloads/**/*.webm",
+      "output": ".knowhow/organized/",
+      "prompt": "FSOrganizer",
+      "agent": "Developer",
+      "model": "gpt-5.4-nano"
     }
   ]
 }
@@ -90,25 +222,30 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
 
 ## `embedSources` (embedding pipeline)
 
-- **Type:** `EmbedSourceConfig[]`
-- **Description:** Defines how Knowhow creates embeddings from inputs, with optional chunking and optional remote/upload settings.
+- **Type:** `EmbedSource[]`
+- **Required:** Yes
+- **Purpose:** Used by `knowhow embed` to generate embedding JSON and optionally upload/download remote embeddings.
 
-### `EmbedSourceConfig`
+Each `EmbedSource` has:
 
-| Key | Type | Required | Description | Example |
+| Field | Type | Required | Default | Description |
 |---|---|---:|---|---|
-| `input` | `string` | ✅ | Input path/glob/URL to embed. | `.knowhow/docs/**/*.mdx` |
-| `output` | `string` | ✅ | Embedding artifact location (often JSON file). | `.knowhow/embeddings/docs.json` |
-| `prompt` | `string` | ❌ | Optional preprocessing prompt name. | `BasicEmbeddingExplainer` |
-| `kind` | `string` | ❌ | Embedding strategy/type (often plugin-driven). | `download` |
-| `chunkSize` | `number` | ❌ | Chunk size for splitting content before embedding. | `2000` |
-| `minLength` | `number` | ❌ | Minimum chunk length threshold. | `200` |
-| `remote` | `string` | ❌ | Remote destination name/id (backend-specific). | `micahriggan/knowhow` |
-| `remoteType` | `string` | ❌ | Remote backend type (e.g., `s3`, `github`). | `github` |
-| `remoteId` | `string` | ❌ | Remote identity/index/collection id (backend-specific). | `docs-index-1` |
-| `uploadMode` | `string` | ❌ | Upload/write mode (implementation-specific). | `overwrite` |
-
-### Example
+| `input` | `string` | Yes | — | Glob/path(s) or remote input. |
+| `output` | `string` | Yes | — | Where the embeddings JSON is written locally. |
+| `prompt` | `string` | No | — | Optional prompt name for preprocessing before embedding (`${promptsDir}/${prompt}.mdx`). |
+| `kind` | `string` | No | — | Plugin “kind” that implements embedding for this source (any plugin that implements embedding for that `kind`). |
+| `chunkSize` | `number` | No | — | Embedding chunk size (e.g., `2000`). |
+| `minLength` | `number` | No | — | Minimum text length threshold before embedding. |
+| `remote` | `string` | No | — | Remote target name used by upload tooling (plugin/tooling-dependent). |
+| `remoteType` | `string` | No | — | Remote type; examples include `s3` and `github*`. |
+| `remoteId` | `string` | No | — | Remote identifier (e.g., bucket/object or known embedding set id). |
+| `uploadMode` | `boolean` | No | — | Controls uploading behavior (tooling-dependent). |
+
+### Upload/download remote options (from examples)
+- **S3:** `remoteType: "s3"` (upload via `knowhow upload`)
+- **GitHub (`github*`):** download/upload via git LFS workflows (tooling-dependent)
+
+**Example (local docs + prompt preprocessing)**
 ```json
 {
   "embedSources": [
@@ -117,7 +254,15 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
       "output": ".knowhow/embeddings/docs.json",
       "prompt": "BasicEmbeddingExplainer",
       "chunkSize": 2000
-    },
+    }
+  ]
+}
+```
+
+**Example (code embedding)**
+```json
+{
+  "embedSources": [
     {
       "input": "src/**/*.ts",
       "output": ".knowhow/embeddings/code.json",
@@ -127,15 +272,17 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
 }
 ```
 
-### Example: embedding with `download` kind (URL input)
+**Example (remote embeddings via S3 + kind)**
 ```json
 {
   "embedSources": [
     {
-      "input": "https://www.youtube.com/shorts/BYuMBK5Ll-s",
-      "output": ".knowhow/embeddings/video.json",
-      "chunkSize": 2000,
-      "kind": "download"
+      "input": "https://app.asana.com/0/111111111111111/list",
+      "output": ".knowhow/embeddings/asana.json",
+      "remote": "mybucket",
+      "remoteType": "s3",
+      "kind": "asana",
+      "chunkSize": 2000
     }
   ]
 }
@@ -146,101 +293,42 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
 ## `embeddingModel`
 
 - **Type:** `string`
-- **Description:** Embedding model identifier used by embedding tasks.
-- **Example:**
-```json
-{
-  "embeddingModel": "openai:EmbeddingAda2"
-}
-```
-
-> Use the exact identifier format your Knowhow build expects (commonly defined by an `EmbeddingModels` enum/constant).
+- **Required:** Yes
+- **Default:** `EmbeddingModels.openai.EmbeddingAda2`
+- **Description:** The embedding model identifier to use for embedding generation.
 
----
-
-## `plugins`
-
-- **Type:**
-```ts
-{
-  enabled: string[];
-  disabled: string[];
-}
-```
-- **Description:** Enables/disables built-in plugins by name.
-
-| Key | Type | Description | Example |
-|---|---|---|---|
-| `enabled` | `string[]` | List of enabled plugin identifiers. | `["embeddings","git"]` |
-| `disabled` | `string[]` | List of disabled plugin identifiers. | `["github"]` |
-
-### Example
+**Example**
 ```json
 {
-  "plugins": {
-    "enabled": ["embeddings", "language", "git", "exec"],
-    "disabled": []
-  }
+  "embeddingModel": "openai:EmbeddingAda2"
 }
 ```
 
 ---
 
-## `pluginPackages`
-
-- **Type:** `string[]`
-- **Description:** NPM package names to load additional/custom plugins from.
-
-### Example
-```json
-{
-  "pluginPackages": ["@myorg/knowhow-plugin-acme"]
-}
-```
+## `agents` (custom chat agents)
 
----
+- **Type:** `Assistant[]`
+- **Required:** Yes
+- **Default:** includes an “Example agent”
+- **Description:** Defines named agents that can be selected in chat sessions. Agents are provided with:
+  - tool access (as determined by enabled plugins and loaded modules)
+  - prompt instructions
+  - an optional model/provider
 
-## `modules`
+**Important:** Your prompt/examples mention `assistants`, but the current `Config` type only defines **`agents`**.
 
-- **Type:** `ModuleConfig[]` *(commonly represented as `{ package: string }` objects)*
-- **Description:** Load custom npm modules that can provide tools/agents/plugins/clients.
+### `Assistant` fields
 
-### `ModuleConfig` (representative)
-| Key | Type | Required | Description | Example |
+| Field | Type | Required | Default | Description |
 |---|---|---:|---|---|
-| `package` | `string` | ✅ | NPM package name (or module identifier) to load. | `@myorg/knowhow-module-mycopilot` |
-
-### Example
-```json
-{
-  "modules": [
-    { "package": "@myorg/knowhow-module-custom-tools" },
-    { "package": "@myorg/knowhow-module-chat-ui" }
-  ]
-}
-```
-
----
-
-## `agents` / `assistants`
+| `name` | `string` | No | — | Agent name (used in chat selection). |
+| `description` | `string` | No | — | Short agent description. |
+| `instructions` | `string` | **Yes** | — | Agent behavior/instructions. |
+| `model` | `string` | No | — | Model override. |
+| `provider` | `keyof Providers` | No | — | Provider key (e.g., `openai`, `anthropic`, `google`, `xai`, etc.). |
 
-- **Type:** `AgentConfig[]`
-- **Description:** Custom agent definitions usable by generation/chat.
-- **Note:** Both keys typically share the same schema; `assistants` may be treated as an alias/parallel list.
-
-### `AgentConfig`
-
-| Key | Type | Required | Description | Example |
-|---|---|---:|---|---|
-| `name` | `string` | ✅ | Agent identifier referenced by `sources[].agent`. | `Example agent` |
-| `description` | `string` | ❌ | Short human-readable description. | `Docs writer` |
-| `instructions` | `string` | ✅ | Agent system/developer instructions. | `Reply with ...` |
-| `model` | `string` | ❌ | Model override used by this agent. | `gpt-4o-2024-08-06` |
-| `provider` | `string` | ❌/✅ | Model provider key used by this agent. | `openai` |
-| `tools` | `string[]` | ❌ | Tool names the agent is allowed to use. | `["git","exec"]` |
-| `files` | `string[]` | ❌ | Files/dirs/globs provided as context for this agent. | `[".knowhow/docs/"]` |
-
-### Example
+**Example**
 ```json
 {
   "agents": [
@@ -248,48 +336,37 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
       "name": "Example agent",
       "description": "You can define agents in the config. They will have access to all tools.",
       "instructions": "Reply to the user saying 'Hello, world!'",
-      "model": "gpt-4o-2024-08-06",
+      "model": "gpt-5.4-nano",
       "provider": "openai"
     }
   ]
 }
 ```
 
-### Example: agent with `tools` and `files`
-```json
-{
-  "agents": [
-    {
-      "name": "Docs agent",
-      "description": "Writes and updates project documentation.",
-      "instructions": "Summarize changes and update docs with a clear changelog.",
-      "model": "gpt-4o-2024-08-06",
-      "provider": "openai",
-      "tools": ["git", "exec"],
-      "files": [".knowhow/docs/"]
-    }
-  ]
-}
-```
-
 ---
 
 ## `mcps` (MCP servers)
 
-- **Type:** `McpServerConfig[]`
-- **Description:** Configure MCP servers Knowhow can spawn or connect to.
+- **Type:** `McpConfig[]`
+- **Required:** Yes
+- **Default:** includes a `browser` MCP example
+- **Description:** Configure MCP servers Knowhow can launch/connect to.
 
-### `McpServerConfig`
+### `McpConfig` fields
 
-| Key | Type | Required | Description | Example |
+| Field | Type | Required | Default | Description |
 |---|---|---:|---|---|
-| `name` | `string` | ✅ | MCP server name. | `browser` |
-| `command` | `string` | ❌ | Command used to start the MCP server. | `npx` |
-| `args` | `string[]` | ❌ | Arguments for `command`. | `["-y","@playwright/mcp@latest", "..."]` |
-| `url` | `string` | ❌ | Remote MCP URL (if applicable). | `http://localhost:3000` |
-| `autoConnect` | `boolean` | ❌ | Whether Knowhow connects automatically. | `true` |
-
-### Example
+| `name` | `string` | **Yes** | — | MCP server name. |
+| `autoConnect` | `boolean` | No | — | Whether to auto-connect. |
+| `command` | `string` | No | — | Command to run (e.g., `npx`). |
+| `args` | `string[]` | No | — | Command arguments. |
+| `url` | `string` | No | — | If provided, connect via URL instead of launching a process. |
+| `env` | `{ [key: string]: string }` | No | — | Environment variables for the process. |
+| `params` | `Partial<{ socket: WebSocket }>` | No | — | Advanced socket parameters (implementation-dependent). |
+| `authorization_token` | `string` | No | — | Authorization token for the MCP endpoint. |
+| `authorization_token_file` | `string` | No | — | Path to a file containing the token. |
+
+**Example**
 ```json
 {
   "mcps": [
@@ -305,110 +382,146 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
 
 ---
 
-## `modelProviders`
+## `modelProviders` (custom model providers)
 
-- **Type:** `ModelProviderConfig[]`
-- **Description:** Register custom model providers/endpoints.
+- **Type:** `ModelProvider[]`
+- **Required:** Yes
+- **Default (examples):** includes `openai`, `anthropic`, `google`, `xai`, `knowhow`, and `lms`.
 
-### `ModelProviderConfig`
+### `ModelProvider` fields
 
-| Key | Type | Required | Description | Example |
+| Field | Type | Required | Default | Description |
 |---|---|---:|---|---|
-| `url` | `string` | ✅ | Base URL of the provider endpoint. | `http://localhost:1234` |
-| `provider` | `string` | ✅ | Provider key/name used by `agents.provider`. | `lms` |
-| `jwtFile` | `string` | ❌ | Path to a JWT file for auth. | `~/.knowhow/.jwt/myprovider.jwt` |
-
-### Example
+| `provider` | `string` | **Yes** | — | Provider key (must match Knowhow’s provider selection). |
+| `url` | `string` | No | — | Base URL for the provider endpoint. |
+| `envKey` | `string` | No | — | Environment variable name holding provider auth (e.g., `OPENAI_API_KEY`). |
+| `headers` | `{ [key: string]: string }` | No | — | Additional HTTP headers. |
+| `jwtFile` | `string` | No | — | Path to a JWT file. |
+| `timeout` | `number` | No | — | Request timeout. |
+| `extra_body` | `Record<string, any>` | No | — | Extra fields injected into provider requests. |
+| `pricing` | `Record<string, { input?: number; output?: number; cached_input?: number; cache_hit?: number }>` | No | — | Optional model pricing map. |
+| *(Note)* `pricing` is passed to `HttpClient.setPrices()` per code comments. | | | | |
+
+**Example (LMS Studio / custom endpoint)**
 ```json
 {
   "modelProviders": [
-    { "url": "http://localhost:1234", "provider": "lms" }
+    {
+      "url": "http://localhost:1234",
+      "provider": "lms"
+    }
   ]
 }
 ```
 
 ---
 
-## `lintCommands`
-
-- **Type:** `Record<string,string>`
-- **Description:** Map file extensions to lint commands.
-  - Common behavior: keys are extensions like `"ts"`, and the command is run with `$1` replaced by the patched file path.
+## `chat` (chat config)
 
-### Example
-```json
-{
-  "lintCommands": {
-    "js": "eslint $1",
-    "ts": "eslint $1"
+- **Type:**
+  ```ts
+  {
+    rootModule?: string;
+    renderer?: string;
+    modules?: string[];
   }
-}
-```
-
----
-
-## `chat`
-
-- **Type:** `ChatConfig`
-- **Description:** Configure chat renderer and module wiring.
-
-### `ChatConfig`
-
-| Key | Type | Required | Description | Example |
-|---|---|---:|---|---|
-| `renderer` | `string` | ❌ | Renderer module name/path. | `default` |
-| `modules` | `string[]` | ❌ | Chat modules to load. | `["@myorg/knowhow-chat-ui"]` |
-| `rootModule` | `string` | ❌ | Root module entry. | `knowhow-chat` |
+  ```
+- **Required:** No
+- **Description:** Configures chat runtime: renderer and module loading for chat UI/tooling.
 
-### Example
+**Example**
 ```json
 {
   "chat": {
-    "renderer": "default",
-    "modules": ["@myorg/knowhow-chat-ui"],
-    "rootModule": "knowhow-chat"
+    "renderer": "@knowhow/chat-renderer-default",
+    "rootModule": "@knowhow/chat-root",
+    "modules": ["@myorg/knowhow-chat-mods"]
   }
 }
 ```
 
 ---
 
-## `worker`
+## `worker` (worker runtime config)
 
-- **Type:** `WorkerConfig`
-- **Description:** Worker execution/sandbox/tunnel configuration for tools.
+- **Type:**
+  ```ts
+  {
+    allowedTools?: string[];
+    workerId?: string;
+    sandbox?: boolean;
+    volumes?: string[];
+    envFile?: string;
+    auth?: { ... };
+    commandAuth?: { [toolName: string]: "always" | "session" | "never" };
+    tunnel?: {
+      enabled?: boolean;
+      allowedPorts?: number[];
+      maxConcurrentStreams?: number;
+      portMapping?: { [containerPort: number]: number };
+      localHost?: string;
+      enableUrlRewriting?: boolean;
+    };
+  }
+  ```
+- **Required:** No
+- **Default (partial):**
+  ```json
+  {
+    "worker": {
+      "tunnel": { "enabled": false, "allowedPorts": [] }
+    }
+  }
+  ```
 
-### `worker` keys
+### Worker fields
 
-| Key | Type | Required | Description | Example |
+| Field | Type | Required | Default | Description |
 |---|---|---:|---|---|
-| `allowedTools` | `string[]` | ❌ | Tool names permitted to run in the worker. | `["exec","download"]` |
-| `sandbox` | `boolean` | ❌ | Enable/disable sandboxing for tool execution. | `true` |
-| `volumes` | `string[]` | ❌ | Volume mounts (implementation-dependent). | `[".:/workspace"]` |
-| `envFile` | `string` | ❌ | Path to an env file loaded by the worker. | `.env.worker` |
-| `tunnel` | `WorkerTunnelConfig` | ❌ | Network tunnel configuration. | see below |
-
-### `worker.tunnel`
-
-- **Type:**
-```ts
-{
-  enabled: boolean;
-  allowedPorts: number[];
-}
-```
-
-### Example
+| `allowedTools` | `string[]` | No | — | Tools the worker is allowed to expose. |
+| `workerId` | `string` | No | — | Identifier for the worker instance. |
+| `sandbox` | `boolean` | No | — | Whether to run tools in a sandbox. |
+| `volumes` | `string[]` | No | — | Volume mappings for containerized execution. |
+| `envFile` | `string` | No | — | Path to an env file used by the worker. |
+| `auth` | object | No | — | Authentication requirements for worker access. |
+| `commandAuth` | `{ [toolName: string]: "always" \| "session" \| "never" }` | No | — | Per-tool authorization policy. |
+| `tunnel` | object | No | — | Network tunneling configuration. |
+
+#### `worker.auth`
+
+| Field | Type | Description |
+|---|---|---|
+| `required` | `boolean` | Whether auth is required. |
+| `passkey.publicKey` | `string` | Passkey public key. |
+| `passkey.credentialId` | `string` | Passkey credential id. |
+| `passkey.algorithm` | `string` | Passkey algorithm. |
+| `sessionDurationHours` | `number` | Session TTL in hours. |
+
+#### `worker.tunnel`
+
+| Field | Type | Description |
+|---|---|---|
+| `enabled` | `boolean` | Enable tunneling. |
+| `allowedPorts` | `number[]` | Ports allowed for tunneling. |
+| `maxConcurrentStreams` | `number` | Max concurrent tunnel streams. |
+| `portMapping` | `{ [containerPort: number]: number }` | Container→local port mapping. |
+| `localHost` | `string` | Host used for local forwarding. |
+| `enableUrlRewriting` | `boolean` | Rewrite URLs for proxied access. |
+
+**Example (expose tools via tunnel disabled)**
 ```json
 {
   "worker": {
-    "allowedTools": ["exec", "download"],
-    "sandbox": true,
-    "volumes": [".:/workspace"],
-    "envFile": ".env.worker",
+    "allowedTools": [
+      "embeddingSearch",
+      "finalAnswer",
+      "readFile",
+      "writeFileChunk",
+      "mcp_0_puppeteer_screenshot"
+    ],
     "tunnel": {
-      "enabled": true,
-      "allowedPorts": [3000, 8080]
+      "enabled": false,
+      "allowedPorts": []
     }
   }
 }
@@ -419,123 +532,111 @@ This document describes how to configure Knowhow CLI using a `knowhow.json` file
 ## `skills`
 
 - **Type:** `string[]`
-- **Description:** Directories to scan for “skills” definitions.
+- **Required:** No
+- **Description:** List of directories to load skills from (implementation-specific; used by skill/tool orchestration).
 
-### Example
+**Example**
 ```json
 {
-  "skills": [".knowhow/skills", "skills"]
+  "skills": ["./skills/common", "./skills/my-special-skill"]
 }
 ```
 
 ---
 
-## `files` (file sync config)
-
-- **Type:** `FileSyncConfig` *(schema varies by Knowhow build/version)*
-- **Description:** Configure how files are synced between local filesystem and Knowhow’s filesystem/runtime.
+## `files` (file sync configuration)
 
-### Example (illustrative shape)
+- **Type:**
+  ```ts
+  {
+    remotePath: string;
+    localPath: string;
+    direction?: "download" | "upload" | "sync";
+  }[]
+  ```
+- **Required:** No
+- **Description:** Declare remote↔local file sync entries.
+
+**Example**
 ```json
 {
-  "files": {
-    "syncDir": ".knowhow/sync",
-    "include": ["src/**/*", ".knowhow/docs/**/*"],
-    "exclude": ["**/node_modules/**", "**/.git/**"]
-  }
+  "files": [
+    {
+      "remotePath": "s3://mybucket/embeddings/docs.json",
+      "localPath": ".knowhow/embeddings/docs.json",
+      "direction": "download"
+    }
+  ]
 }
 ```
 
-> If you paste your `Config`/`FileSyncConfig` type from `src/types.ts`, I can replace this “illustrative shape” with the exact keys/types.
-
 ---
 
-## `ycmd` (language server)
-
-- **Type:** `YcmdConfig`
-- **Description:** Configure the ycmd language server.
-
-### `YcmdConfig`
+## `ycmd` (language server config)
 
-| Key | Type | Required | Description | Example |
-|---|---|---:|---|---|
-| `enabled` | `boolean` | ❌ | Whether ycmd is enabled. | `true` |
-| `installPath` | `string` | ❌ | ycmd install path. | `~/.knowhow/ycmd` |
-| `port` | `number` | ❌ | Listening port (`0` may mean “auto”). | `0` |
-| `logLevel` | `string` | ❌ | Logging verbosity. | `info` |
-| `completionTimeout` | `number` | ❌ | Completion request timeout (ms). | `5000` |
+- **Type:**
+  ```ts
+  {
+    enabled?: boolean;
+    installPath?: string;
+    port?: number;            // 0 for auto-assign
+    logLevel?: "debug" | "info" | "warning" | "error";
+    completionTimeout?: number;
+  }
+  ```
+- **Required:** No
+- **Default (from `config.ts`):**
+  ```json
+  {
+    "enabled": false,
+    "installPath": undefined,
+    "port": 0,
+    "logLevel": "info",
+    "completionTimeout": 5000
+  }
+  ```
+- **Description:** Configures **ycmd** installation and server behavior.
 
-### Example
+**Example**
 ```json
 {
   "ycmd": {
     "enabled": true,
-    "installPath": "~/.knowhow/ycmd",
-    "port": 0,
+    "port": 8123,
     "logLevel": "debug",
-    "completionTimeout": 10000
+    "completionTimeout": 8000
   }
 }
 ```
 
 ---
 
-## Minimal `knowhow.json` example
+## Other configuration keys
 
+### `openaiBaseUrl`
+- **Type:** `string`
+- **Default:** —  
+- **Description:** Base URL override for OpenAI-compatible clients.
+
+**Example**
 ```json
 {
-  "promptsDir": ".knowhow/prompts",
-  "plugins": {
-    "enabled": ["embeddings", "language", "git", "exec"],
-    "disabled": []
-  },
-  "lintCommands": {
-    "ts": "eslint $1",
-    "js": "eslint $1"
-  },
-  "sources": [
-    {
-      "input": "src/**/*.mdx",
-      "output": ".knowhow/docs/",
-      "prompt": "BasicCodeDocumenter"
-    }
-  ],
-  "embedSources": [
-    {
-      "input": ".knowhow/docs/**/*.mdx",
-      "output": ".knowhow/embeddings/docs.json",
-      "prompt": "BasicEmbeddingExplainer",
-      "chunkSize": 2000
-    }
-  ],
-  "embeddingModel": "openai:EmbeddingAda2",
-  "agents": [
-    {
-      "name": "Example agent",
-      "instructions": "Reply to the user saying 'Hello, world!'",
-      "model": "gpt-4o-2024-08-06",
-      "provider": "openai"
-    }
-  ],
-  "mcps": [
-    {
-      "name": "browser",
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest", "--browser", "chrome"]
-    }
-  ],
-  "modelProviders": [{ "url": "http://localhost:1234", "provider": "lms" }],
-  "worker": {
-    "tunnel": { "enabled": false, "allowedPorts": [] }
-  }
+  "openaiBaseUrl": "http://localhost:11434/v1"
 }
 ```
 
+### `orgId`
+- **Type:** `string`
+- **Description:** Organization ID (provider/service dependent).
+
+### `syncRemote`
+- **Type:** `boolean`
+- **Description:** Enables sync behavior for remote operations (tooling-dependent).
+
+### `micCommand` / `defaultMic`
+- **Type:** `string`
+- **Description:** Audio/microphone configuration (implementation/tooling dependent).
+
 ---
 
-### Want this to be 100% exact to your codebase?
-If you paste `src/config.ts` and `src/types.ts` (the actual `Config`, `SourceConfig`, `EmbedSourceConfig`, `WorkerConfig`, `FileSyncConfig`, and `YcmdConfig` type definitions), I can regenerate this reference with:
-- exact field names (no illustrative placeholders),
-- exact optional/required fields,
-- exact union literal types (e.g., allowed `uploadMode` values, `logLevel` enum values),
-- and the real list of built-in plugin names + what each one does.
+If you want, paste your current `knowhow.json` and I’ll validate it against this schema-style reference and suggest fixes for missing/invalid fields.