iosm-cli 0.1.2 → 0.1.3

package/docs/cli-reference.md

@@ -98,6 +98,22 @@ View and manage configuration.
 iosm config
 ```
 
+### `iosm semantic`
+
+Semantic index management for meaning-based retrieval.
+
+```bash
+iosm semantic help
+iosm semantic status
+iosm semantic index
+iosm semantic rebuild
+iosm semantic query "<text>" [--top-k N]
+```
+
+Notes:
+- If semantic config is missing, the command prints actionable paths and suggests `/semantic setup`.
+- `query` auto-refreshes stale indexes incrementally; provider/chunk/filter changes require `rebuild`.
+
 ---
 
 ## Core Options
@@ -209,12 +225,13 @@ iosm --api-key sk-test-123           # Override for this run
 
 ### Available Tools
 
-`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`
+`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`, `semantic_search`
 
 Tool notes:
 - `rg`, `fd` are managed by iosm-cli and auto-resolved when missing.
 - `ast_grep`, `comby`, `jq`, `yq`, `semgrep` are optional external CLIs and should be available in `PATH` to use their tools.
 - `sed` tool is preview/extraction-oriented; in-place edits are intentionally blocked.
+- `semantic_search` uses configured embeddings provider/index (`/semantic setup`).
 
 **Examples:**
 

package/docs/configuration.md

@@ -12,6 +12,7 @@ Complete reference for `iosm-cli` settings, environment variables, profiles, and
 ~/.iosm/agent/
 ├── settings.json          # Global settings
 ├── mcp.json               # User MCP servers
+├── semantic.json          # User semantic search config
 ├── models.json            # Model configuration and preferences
 ├── auth.json              # Provider credentials (OAuth + API keys via /login)
 ├── keybindings.json       # Custom keyboard shortcuts
@@ -28,6 +29,7 @@ Complete reference for `iosm-cli` settings, environment variables, profiles, and
 ```
 .iosm/
 ├── settings.json          # Project-specific settings
+├── semantic.json          # Project semantic search overrides
 ├── extensions/            # Project extensions
 ├── skills/                # Project skills
 ├── prompts/               # Project prompt templates
@@ -105,6 +107,76 @@ MCP configs are loaded with project override precedence:
 
 ---
 
+## Semantic Search Configuration
+
+Semantic search is configured separately from settings and supports user/project override merge:
+
+1. `~/.iosm/agent/semantic.json`
+2. `.iosm/semantic.json` (project root, overrides user)
+
+Interactive setup:
+
+```bash
+/semantic setup
+```
+
+CLI actions:
+
+```bash
+iosm semantic status
+iosm semantic index
+iosm semantic query "where auth token is validated" --top-k 8
+iosm semantic rebuild
+```
+
+Schema (`semanticSearch` object):
+
+```json
+{
+  "semanticSearch": {
+    "enabled": true,
+    "provider": {
+      "type": "openrouter",
+      "model": "openai/text-embedding-3-small",
+      "baseUrl": "optional",
+      "apiKeyEnv": "optional",
+      "headers": {
+        "KEY": "VALUE"
+      },
+      "batchSize": 32,
+      "timeoutMs": 30000
+    },
+    "index": {
+      "includeGlobs": [
+        "**/*.{ts,tsx,js,jsx,py,go,rs,java,md,json,yaml,yml}"
+      ],
+      "excludeGlobs": [
+        "**/.git/**",
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/.iosm/**"
+      ],
+      "chunkMaxChars": 1200,
+      "chunkOverlapChars": 200,
+      "maxFileBytes": 262144,
+      "maxFiles": 20000
+    }
+  }
+}
+```
+
+Index storage (global cache):
+
+```
+~/.iosm/agent/semantic/indexes/<project-hash>/
+├── meta.json
+├── chunks.jsonl
+└── vectors.jsonl
+```
+
+---
+
 ## Environment Variables
 
 ### Provider API Keys
@@ -118,7 +190,7 @@ MCP configs are loaded with project override precedence:
 | `GROQ_API_KEY` | Groq | |
 | `CEREBRAS_API_KEY` | Cerebras | |
 | `XAI_API_KEY` | xAI (Grok) | |
-| `OPENROUTER_API_KEY` | OpenRouter | Multi-provider gateway |
+| `OPENROUTER_API_KEY` | OpenRouter | Multi-provider gateway + default semantic embeddings key |
 | `MISTRAL_API_KEY` | Mistral | |
 | `MINIMAX_API_KEY` | MiniMax | |
 | `KIMI_API_KEY` | Kimi | |
@@ -165,7 +237,7 @@ Profiles control the agent's behavior, available tools, and system prompt.
 
 | Profile | Tools | Behavior |
 |---------|-------|----------|
-| `full` | All built-ins (read, bash, edit, write, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed) | Default full development capabilities |
+| `full` | All built-ins (read, bash, edit, write, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search) | Default full development capabilities |
 | `plan` | Read-only (read, grep, find, ls) | Architecture planning and code review |
 | `iosm` | All + IOSM context | IOSM cycle execution with artifact synchronization |
 

package/docs/getting-started.md

@@ -92,6 +92,7 @@ You'll see a prompt where you can type messages. The agent has access to your fi
 |---------|-------------|
 | `/model` | Pick or change the active model |
 | `/login` | Authenticate with OAuth providers (including Qwen) or add OpenRouter API key |
+| `/semantic` | Configure semantic provider and index/query meaning-based code search |
 | `/init` | Bootstrap IOSM artifacts for the current project |
 | `/agents` | View available custom/system agents |
 | `/settings` | View and modify settings |

package/docs/interactive-mode.md

@@ -53,6 +53,7 @@ iosm --continue
 | `/model` | Open provider-first model selector (`provider -> model`) | `/model` |
 | `/scoped-models` | Manage model rotation | `/scoped-models` |
 | `/mcp` | Open MCP manager UI and run MCP subcommands | `/mcp` |
+| `/semantic` | Open semantic search manager (`setup/status/index/rebuild/query`) | `/semantic` |
 | `/memory` | Interactive memory manager (`add/edit/remove/scope/path`) | `/memory` |
 | `/settings` | View/modify settings | `/settings` |
 | `/hotkeys` | View keyboard shortcuts | `/hotkeys` |
@@ -97,6 +98,9 @@ iosm --continue
 | `/logout` | Clear saved provider credentials | `/logout` |
 
 `/mcp add` without flags starts a guided wizard in the terminal UI.
+`/semantic` opens an interactive setup/status/index/query manager for embeddings search.
+`/semantic setup` now auto-loads model catalogs for OpenRouter (`/api/v1/embeddings/models`) and Ollama (`/api/tags`) with manual fallback.
+In `/semantic setup`, the headers step is optional: press `Enter` on empty input to skip.
 `/memory` opens an interactive manager. `/memory <text>` saves a note to `memory.md` and reloads session context. Use `/memory edit <index> <text>` for direct updates.
 
 ---
@@ -161,7 +165,7 @@ Profiles change the agent's behavior, available tools, and system prompt:
 
 | Profile | Tools | Use Case |
 |---------|-------|----------|
-| `full` | All built-ins (read, bash, edit, write, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed) | Default development work |
+| `full` | All built-ins (read, bash, edit, write, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search) | Default development work |
 | `plan` | Read-only (read, grep, find, ls) | Architecture planning, code review |
 | `iosm` | All + IOSM context | IOSM cycle execution with artifact sync |
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "iosm-cli",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"description": "Standalone IOSM CLI with agent tooling, session management, and IOSM artifact orchestration",
 	"type": "module",
 	"iosmConfig": {