iosm-cli 0.1.2 → 0.2.0

package/docs/cli-reference.md

@@ -98,6 +98,40 @@ 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 only when `semanticSearch.autoIndex=true` (default is `true`).
+- When auto-index is off, run `iosm semantic index` (or `rebuild` for provider/chunk/filter changes).
+
+### Interactive feasibility/contract commands
+
+These commands run inside interactive mode (`iosm`), not as top-level CLI subcommands:
+
+- `/contract` — interactive engineering contract manager:
+  - edit fields one-by-one
+  - autosave on `Enter`
+  - auto-build `.iosm/contract.json` for project scope
+- `/singular <feature request>` — command-first feasibility analyzer:
+  - baseline repository scan + standard agent pass
+  - outputs exactly 3 implementation options with recommendation
+  - lets user choose option `1/2/3` before implementation
+
+Migration notes:
+- `/blast` removed in favor of `/singular`
+- `/shadow` removed
+
 ---
 
 ## Core Options
@@ -209,12 +243,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,81 @@ 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,
+    "autoIndex": 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
+    }
+  }
+}
+```
+
+`autoIndex` controls query-time automatic refresh:
+- `true` (default): `query` automatically refreshes stale index (and rebuilds when required)
+- `false`: stale/missing index must be updated manually via `iosm semantic index` / `rebuild`
+
+Index storage (global cache):
+
+```
+~/.iosm/agent/semantic/indexes/<project-hash>/
+├── meta.json
+├── chunks.jsonl
+└── vectors.jsonl
+```
+
+---
+
 ## Environment Variables
 
 ### Provider API Keys
@@ -118,7 +195,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 +242,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,9 @@ 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/auto-index/status/index/rebuild/query`) | `/semantic` |
+| `/contract` | Interactive engineering contract editor (field-by-field, auto JSON build) | `/contract` |
+| `/singular` | Feature feasibility analyzer with implementation options and recommendation | `/singular add account dashboard` |
 | `/memory` | Interactive memory manager (`add/edit/remove/scope/path`) | `/memory` |
 | `/settings` | View/modify settings | `/settings` |
 | `/hotkeys` | View keyboard shortcuts | `/hotkeys` |
@@ -97,7 +100,138 @@ 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.
+Manager includes `Automatic indexing` toggle (default `on`) to control query-time auto-refresh.
+`/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.
+`/contract` edits contract fields interactively (`goal`, scope, constraints, quality gates, DoD, risks, etc.), then writes JSON automatically.
+`/singular <request>` runs a two-pass feasibility analysis (baseline scan + standard agent pass), builds concrete implementation options, and asks user to choose one.
+`/blast` and `/shadow` are removed from active interactive workflow.
+
+### `/contract` Detailed Guide
+
+`/contract` is a layered contract editor with two sources and one merged output:
+
+| Layer | Scope | Persistence | Storage |
+|------|-------|-------------|---------|
+| `project` | Project-wide baseline | Persistent | `.iosm/contract.json` |
+| `session` | Current session override | Temporary | In-memory session overlay |
+| `effective` | `project + session` merged result | Derived | Computed at runtime |
+
+Important merge rule:
+- `session` overrides `project` for the same keys.
+- `effective` is what the runtime actually uses.
+
+#### Quick Difference: Effective vs Session vs Project
+
+- `Open effective contract` is read-only and shows what runtime is enforcing right now.
+- `Edit session contract` changes only this session (temporary overlay, not persisted to disk).
+- `Edit project contract` changes `.iosm/contract.json` (persistent baseline for future sessions).
+
+#### Manager Actions
+
+| Action | What it does | When to use |
+|------|---------------|-------------|
+| `Open effective contract` | Shows the merged JSON currently enforced by runtime | Verify final active constraints |
+| `Edit session contract` | Edits temporary overrides for current session | Experiments, one-off constraints |
+| `Edit project contract` | Edits persistent project contract file | Team-wide stable defaults |
+| `Copy effective -> session` | Saves merged state into session layer | Freeze current merged state for this run |
+| `Copy effective -> project` | Saves merged state into project file | Promote temporary decisions to baseline |
+| `Delete session contract` | Clears temporary overlay | Reset session overrides |
+| `Delete project contract` | Removes `.iosm/contract.json` | Full baseline reset |
+
+#### Field Editor Behavior
+
+- Select a field and press `Enter`.
+- Input text (single-line or multi-line list depending on field type).
+- Press `Enter` to submit.
+- Change is saved immediately to selected scope (`session` or `project`).
+- Empty input clears that field.
+
+There is no separate "Save" step in field editor mode.
+
+#### Common Workflows
+
+1. Temporary tightening for one run:
+   - Open `/contract`
+   - `Edit session contract`
+   - Set `constraints` and `quality_gates`
+   - Confirm via `Open effective contract`
+
+2. Promote temporary policy to project baseline:
+   - Open `/contract`
+   - `Copy effective -> project`
+   - Review `.iosm/contract.json` in VCS
+
+3. Recover from aggressive temporary overrides:
+   - Open `/contract`
+   - `Delete session contract`
+   - Re-open `effective` and verify fallback to `project`
+
+### `/singular` Detailed Guide
+
+`/singular` is a command-first feasibility mode (no pre-menu).  
+Pattern: `/singular <feature request>`
+
+Examples:
+- `/singular add account dashboard`
+- `/singular introduce RBAC for API`
+- `/singular redesign billing reconciliation flow`
+
+#### What Happens Internally
+
+1. Baseline repository pass:
+   - Scans project files and estimates baseline complexity/blast radius.
+   - Collects likely impacted files and contract signals.
+
+2. Standard agent feasibility pass:
+   - Launches an isolated standard agent run (`plan` profile) with repository tools.
+   - Agent inspects real files and returns structured feasibility JSON.
+   - Produces recommendation, impact analysis, and implementation variants.
+
+3. Merge + persistence:
+   - Agent insights are merged with baseline data.
+   - Analysis is saved to `.iosm/singular/<run-id>/analysis.json` (+ `meta.json`).
+
+#### Output Shape
+
+Each run includes:
+- `recommendation`: `implement_now | implement_incrementally | defer`
+- `reason`: why this recommendation is best for current stage
+- `complexity` and `blast_radius`
+- `stage_fit`: `needed_now | optional_now | later`
+- `impact_analysis`: codebase, delivery, risks, operations
+- `implementation_options` (exactly 3 variants):
+  - Option 1: practical/recommended path
+  - Option 2: alternative approach
+  - Option 3: defer / do not implement now
+
+Each option includes:
+- summary and trade-offs (`pros`/`cons`)
+- concrete file targets (`suggested_files`)
+- step-by-step plan (`plan`)
+- `when_to_choose` guidance
+
+#### Decision Flow
+
+After analysis, selector opens with variants:
+- choose Option 1 / Option 2 / Option 3
+- or close without decision
+
+If Option 1 or 2 is selected, execution draft is inserted into editor (ready to run).  
+If Option 3 is selected, run is explicitly marked as postponed.
+
+#### Fallback Behavior
+
+If no model is selected (or agent pass fails), `/singular` still returns a heuristic baseline analysis.  
+Use `/model` to enable full agent feasibility pass.
+
+#### Command Migration
+
+- `/singular` is the feasibility command to use.
+- `/blast` is deprecated/removed.
+- `/shadow` is removed.
 
 ---
 
@@ -161,7 +295,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.2.0",
 	"description": "Standalone IOSM CLI with agent tooling, session management, and IOSM artifact orchestration",
 	"type": "module",
 	"iosmConfig": {