omnius 1.0.591 → 1.0.592

package/docs/research/personality-verbosity-control.md

@@ -0,0 +1,293 @@
+# LLM Personality Guidance & Verbosity Control: Research Synthesis
+
+**Date**: 2026-03-13
+**Purpose**: Literature review and integration strategy for transient personality/verbosity steering in the Omnius framework
+
+---
+
+## 1. Executive Summary
+
+This document synthesizes research on controlling LLM output style — specifically verbosity vs. conciseness — through system prompt engineering, persona/personality steering, and length control mechanisms. The findings are organized for direct integration into the Omnius agentic framework, where the system prompt and context engineering pipeline can transiently influence agent behavior without fine-tuning.
+
+**Key insight**: Prompt-level personality steering (natural language instructions) categorically dominates activation-level interventions. Explicit system prompt instructions override all other behavioral signals, making prompt engineering the most practical lever for our framework.
+
+---
+
+## 2. Literature & Provenance
+
+### 2.1 Core Papers
+
+| # | Paper | Authors | Venue | Year | Key Finding |
+|---|-------|---------|-------|------|-------------|
+| 1 | [The Prompt Report: A Systematic Survey of Prompting Techniques](https://arxiv.org/abs/2406.06608) | Schulhoff et al. (32 authors) | arXiv | 2024 | Taxonomy of 58 prompting techniques; role/persona prompting in §2.2 |
+| 2 | [Same Task, More Tokens](https://arxiv.org/abs/2402.14848) | Levy, Jacoby & Goldberg | ACL 2024 | 2024 | LLM reasoning degrades ~3,000 tokens; sweet spot 150–300 words |
+| 3 | [Lost in the Middle](https://arxiv.org/abs/2307.03172) | Liu, Lin, Hewitt et al. | TACL 2024 | 2024 | U-shaped attention bias; >30% accuracy drop for mid-context info |
+| 4 | [Linear Personality Probing and Steering in LLMs](https://arxiv.org/html/2512.17639v1) | (Big Five study) | arXiv | 2025 | Linear directions can probe personality but explicit prompts override steering vectors entirely |
+| 5 | [SAC: Style Adjective Continuation](https://arxiv.org/abs/2506.20993) | (16PF framework) | arXiv | 2026 | Continuous 1–5 trait intensity via adjective anchoring; 5 behavioral dimensions |
+| 6 | [Precise Length Control in LLMs (LDPE)](https://arxiv.org/abs/2412.11937) | (LDPE method) | ICLR 2026 | 2024 | Countdown positional encoding achieves <3 token error for exact length control |
+| 7 | [Dynamic Feedback for Length Regulation](https://arxiv.org/html/2601.01768) | — | arXiv | 2025 | Training-free dynamic feedback loop for length adherence |
+| 8 | [Effective Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) | Anthropic Engineering | Blog | 2025 | Altitude calibration, finite attention budget, just-in-time context |
+| 9 | [Control Illusion: Failure of Instruction Hierarchies](https://arxiv.org/pdf/2502.15851) | — | arXiv | 2025 | Instruction hierarchies break under conflicting constraints |
+| 10 | [AgentIF: Instruction Following in Agentic Scenarios](https://arxiv.org/html/2505.16944v1) | — | arXiv | 2025 | Best models follow <30% of agentic instructions perfectly |
+| 11 | [Persona Prompting as a Lens on LLM Social Reasoning](https://arxiv.org/abs/2601.20757) | — | arXiv | 2026 | Persona prompting improves classification but degrades rationale quality |
+
+### 2.2 Key Practitioner Sources
+
+| Source | URL | Key Contribution |
+|--------|-----|-----------------|
+| Anthropic Context Engineering | [anthropic.com/engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) | "Right altitude" system prompt design |
+| Google Prompt Engineering Guide | [prompthub.us](https://www.prompthub.us/blog/googles-prompt-engineering-best-practices) | Positive framing over negation |
+| DAIR.AI Prompt Engineering Guide | [promptingguide.ai](https://www.promptingguide.ai/papers) | Curated paper index |
+
+---
+
+## 3. Research Findings
+
+### 3.1 Prompt-Level Verbosity Control (Most Practical)
+
+**Finding**: Natural language instructions in system prompts are the most effective and reliable mechanism for controlling response style. They categorically override activation-space interventions [Paper 4].
+
+**Best practices distilled from literature**:
+
+1. **Positive framing over negation** — "Be concise" outperforms "Don't be verbose." KAIST research shows larger models perform worse on negated prompts [Paper 1, §2.2].
+
+2. **Explicit format/length constraints** — Specifying desired format, structure, length, and style yields the highest compliance. Example: "Respond in 2-3 sentences" vs. "Keep it short" [Paper 1].
+
+3. **Altitude calibration** (Anthropic) — System prompts should provide specific behavioral direction while remaining flexible. Neither too abstract ("be helpful") nor too brittle ("always respond in exactly 47 words") [Paper 8].
+
+4. **Adjective-based semantic anchoring** (SAC) — Grade behavioral intensity 1–5 using adjective clusters. For conciseness: Level 1 = "occasionally brief, somewhat terse"; Level 5 = "extremely concise, surgically precise, minimalist" [Paper 5].
+
+5. **Role/persona as behavioral anchor** — "You are a senior engineer reviewing code" naturally produces different verbosity than "You are a patient teacher explaining to a beginner" [Papers 1, 11].
+
+### 3.2 Length-Sensitive Prompt Design
+
+**Finding**: LLM reasoning performance degrades at ~3,000 input tokens, with the practical sweet spot for most task prompts being 150–300 words [Paper 2].
+
+**Finding**: U-shaped attention distribution means critical instructions should appear at the **beginning** or **end** of the system prompt, never buried in the middle [Paper 3].
+
+**Implication for our system prompt**:
+- Our SYSTEM_PROMPT is ~2,500 words (~3,500 tokens) — already near the degradation threshold
+- Critical behavioral instructions (verbosity control, workflow) should be at the **top** and **bottom**
+- Tool definitions (low-variance reference material) belong in the **middle** where attention is lowest
+
+### 3.3 Continuous Personality Dimensions (SAC Framework)
+
+**Finding**: The SAC framework defines 5 behavioral intensity dimensions that can control any personality trait along a 1–5 scale [Paper 5]:
+
+| Dimension | Controls | Verbosity Application |
+|-----------|----------|----------------------|
+| **Frequency** | How often the behavior occurs | How often the agent explains vs. acts silently |
+| **Depth** | Emotional-cognitive engagement | How thoroughly the agent reasons in output |
+| **Threshold** | Activation sensitivity | When the agent decides to narrate vs. stay silent |
+| **Effort** | Energy invested in expression | How elaborate/polished the response is |
+| **Willingness** | Voluntary commitment | How readily the agent offers unsolicited detail |
+
+**Practical mapping for our agent**:
+
+```
+Concise Mode (Level 1-2):
+  Frequency: "Rarely explain reasoning; act silently when possible"
+  Depth: "Surface-level status updates only"
+  Threshold: "Only speak when results are surprising or failed"
+  Effort: "Minimal formatting, no markdown headers for short answers"
+  Willingness: "Never volunteer extra context unless asked"
+
+Verbose Mode (Level 4-5):
+  Frequency: "Explain each step and reasoning"
+  Depth: "Include technical details, alternatives considered"
+  Threshold: "Narrate even routine operations"
+  Effort: "Well-structured responses with headers and examples"
+  Willingness: "Proactively offer related context and suggestions"
+```
+
+### 3.4 Activation-Space Steering (Not Practical for Us)
+
+**Finding**: Linear personality directions in activation space can probe personality traits but fail to steer behavior when explicit prompt instructions are present — "steering effects disappear entirely" when the prompt contains personality-relevant context [Paper 4].
+
+**Implication**: This approach requires model weight access and fine-tuning. Not applicable to our inference-only framework (Ollama/vLLM). Prompt-level control is both more practical and more effective.
+
+### 3.5 Precise Length Control (LDPE)
+
+**Finding**: Length-Difference Positional Encoding achieves <3 token error for exact length targeting [Paper 6]. However, this requires fine-tuning.
+
+**Training-free alternative**: Dynamic feedback during generation can regulate length without fine-tuning [Paper 7]. This could be approximated at inference time through `max_tokens` parameter and system prompt length cues.
+
+### 3.6 Context Engineering for Multi-Turn Agents
+
+**Key principles from Anthropic** [Paper 8]:
+
+1. **Finite attention budget** — Every added token depletes the model's attention capacity. Ruthlessly prioritize high-signal information.
+
+2. **Just-in-time context** — Don't pre-load; maintain lightweight identifiers and fetch dynamically.
+
+3. **Progressive disclosure** — Let the agent discover context through exploration rather than front-loading.
+
+4. **Compaction with recall** — Summarize while preserving critical details. Our Memex archive pattern already implements this.
+
+5. **Sub-agent architecture** — Deep exploration in child contexts, condensed summaries returned to parent. Already implemented in our sub_agent tool.
+
+---
+
+## 4. Integration Strategy for Omnius
+
+### 4.1 Transient Personality Injection Points
+
+The agent framework has several natural injection points for transient style control:
+
+| Injection Point | File | Mechanism |
+|----------------|------|-----------|
+| System prompt preamble | `agenticRunner.ts:223` | Static SYSTEM_PROMPT constant |
+| Dynamic context injection | `agenticRunner.ts` `dynamicContext` option | Per-task context appended to system prompt |
+| Health check prompts | `agenticRunner.ts:779` | Self-eval messages injected mid-task |
+| Compaction summaries | `agenticRunner.ts:1728` | Style-control instructions preserved across compaction |
+| Tool result formatting | `agenticRunner.ts:1819` | Observation masking controls output volume |
+
+### 4.2 Proposed: `PersonalityProfile` Interface
+
+```typescript
+/**
+ * Transient personality profile for controlling agent response style.
+ * Based on SAC framework (arXiv:2506.20993) intensity dimensions.
+ *
+ * Each dimension is 1-5:
+ *   1 = minimal (concise, silent, terse)
+ *   3 = balanced (default)
+ *   5 = maximal (verbose, explanatory, thorough)
+ */
+export interface PersonalityProfile {
+  /** How often the agent narrates its actions (1=silent, 5=running commentary) */
+  frequency: 1 | 2 | 3 | 4 | 5;
+  /** Depth of reasoning exposed in output (1=results only, 5=full chain of thought) */
+  depth: 1 | 2 | 3 | 4 | 5;
+  /** When the agent decides to speak vs. act silently (1=only on failure, 5=narrate everything) */
+  threshold: 1 | 2 | 3 | 4 | 5;
+  /** Effort invested in response formatting (1=raw, 5=polished markdown) */
+  effort: 1 | 2 | 3 | 4 | 5;
+  /** Willingness to offer unsolicited context (1=never, 5=proactive suggestions) */
+  willingness: 1 | 2 | 3 | 4 | 5;
+}
+
+/** Preset personality profiles */
+export const PERSONALITY_PRESETS = {
+  /** Silent operator — acts, doesn't explain */
+  concise: { frequency: 1, depth: 1, threshold: 1, effort: 2, willingness: 1 },
+  /** Balanced default */
+  balanced: { frequency: 3, depth: 3, threshold: 3, effort: 3, willingness: 3 },
+  /** Thorough explainer — narrates reasoning */
+  verbose: { frequency: 5, depth: 4, threshold: 4, effort: 4, willingness: 4 },
+  /** Teacher mode — maximum explanation */
+  pedagogical: { frequency: 5, depth: 5, threshold: 5, effort: 5, willingness: 5 },
+} as const;
+```
+
+### 4.3 Proposed: Personality-to-Prompt Compiler
+
+The personality profile would compile to a system prompt suffix using adjective anchoring:
+
+```typescript
+function compilePersonalityPrompt(profile: PersonalityProfile): string {
+  const avgIntensity = (profile.frequency + profile.depth +
+    profile.threshold + profile.effort + profile.willingness) / 5;
+
+  if (avgIntensity <= 1.5) {
+    return `\n## Response Style\nBe extremely concise. Act silently — only speak when results are ` +
+      `surprising or errors occur. No preamble, no summaries. Raw results and tool calls only.`;
+  }
+  if (avgIntensity <= 2.5) {
+    return `\n## Response Style\nBe concise and direct. Brief status updates between tool calls. ` +
+      `Skip reasoning explanation unless the approach is non-obvious. No markdown headers for short answers.`;
+  }
+  if (avgIntensity <= 3.5) {
+    return ``; // Default — no override needed
+  }
+  if (avgIntensity <= 4.5) {
+    return `\n## Response Style\nExplain your reasoning as you work. Describe what you're looking for ` +
+      `and why. Summarize findings. Use structured formatting for complex output.`;
+  }
+  return `\n## Response Style\nProvide thorough explanations of your reasoning at each step. ` +
+    `Describe alternatives you considered. Offer suggestions beyond the immediate task. ` +
+    `Use well-structured markdown with headers and examples.`;
+}
+```
+
+### 4.4 System Prompt Restructuring (Position Optimization)
+
+Based on "Lost in the Middle" findings [Paper 3], restructure the system prompt:
+
+```
+[TOP — HIGH ATTENTION]
+  Identity + Core behavioral rules
+  Response style instructions (personality profile)
+  Critical workflow rules
+
+[MIDDLE — LOW ATTENTION]
+  Tool definitions (reference material — rarely needs full attention)
+  Desktop automation details
+  Skills system
+
+[BOTTOM — HIGH ATTENTION]
+  Critical Rules (validation, iteration, task_complete)
+  Project awareness
+  Dynamic context (memory, git state, project files)
+```
+
+### 4.5 Transient vs. Persistent Application
+
+| Scope | Mechanism | When |
+|-------|-----------|------|
+| **Per-session** | User sets personality with `/style concise` command | User preference |
+| **Per-task** | Task type detection adjusts profile (code review → verbose, quick fix → concise) | Automatic |
+| **Per-turn** | Health check prompts can inject "be more/less verbose" | Self-correction |
+| **Persistent** | Saved to `~/.omnius/config.json` as default preference | User configuration |
+
+### 4.6 Token Budget Implications
+
+Per Levy et al. [Paper 2], our system prompt (~3,500 tokens) is near the reasoning degradation threshold. The personality prompt suffix should be:
+
+- **Concise mode**: 0 extra tokens (suppress the suffix entirely)
+- **Default mode**: 0 extra tokens (no suffix needed)
+- **Verbose mode**: ~50 tokens max
+- **Pedagogical mode**: ~80 tokens max
+
+This keeps total system prompt overhead well within budget.
+
+---
+
+## 5. Implementation Roadmap
+
+### Phase 1: System Prompt Position Optimization
+- Restructure SYSTEM_PROMPT per §4.4 (critical rules at top/bottom, tools in middle)
+- Zero new features, pure prompt restructuring
+- Verification: eval suite pass rate maintained or improved
+
+### Phase 2: PersonalityProfile Interface + Compiler
+- Add PersonalityProfile type and preset profiles per §4.2
+- Implement compilePersonalityPrompt() per §4.3
+- Wire into AgenticRunner options
+- Add `/style` slash command
+
+### Phase 3: Task-Adaptive Personality
+- Detect task type (code review, bug fix, exploration, question answering)
+- Auto-select personality profile based on task characteristics
+- Allow user override
+
+### Phase 4: Self-Correcting Verbosity
+- Health check prompts assess response style adherence
+- Mid-task personality injection if agent drifts from target style
+- Feedback loop with user satisfaction signal
+
+---
+
+## 6. References
+
+1. Schulhoff, S., et al. (2024). "The Prompt Report: A Systematic Survey of Prompting Techniques." arXiv:2406.06608. https://arxiv.org/abs/2406.06608
+2. Levy, M., Jacoby, A., & Goldberg, Y. (2024). "Same Task, More Tokens: the Impact of Input Length on the Reasoning Performance of LLMs." ACL 2024. https://arxiv.org/abs/2402.14848
+3. Liu, N.F., et al. (2024). "Lost in the Middle: How Language Models Use Long Contexts." TACL 12:157–173. https://arxiv.org/abs/2307.03172
+4. (2025). "Linear Personality Probing and Steering in LLMs: A Big Five Study." arXiv:2512.17639. https://arxiv.org/html/2512.17639v1
+5. (2026). "SAC: A Framework for Measuring and Inducing Personality Traits in LLMs with Dynamic Intensity Control." arXiv:2506.20993. https://arxiv.org/abs/2506.20993
+6. (2024). "Precise Length Control in Large Language Models." arXiv:2412.11937. ICLR 2026. https://arxiv.org/abs/2412.11937
+7. (2025). "Can LLMs Track Their Output Length? A Dynamic Feedback Mechanism for Precise Length Regulation." arXiv:2601.01768. https://arxiv.org/html/2601.01768
+8. Anthropic Engineering. (2025). "Effective Context Engineering for AI Agents." https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+9. (2025). "Control Illusion: The Failure of Instruction Hierarchies." arXiv:2502.15851. https://arxiv.org/pdf/2502.15851
+10. (2025). "AgentIF: Benchmarking Instruction Following of LLMs in Agentic Scenarios." arXiv:2505.16944. https://arxiv.org/html/2505.16944v1
+11. (2026). "Persona Prompting as a Lens on LLM Social Reasoning." arXiv:2601.20757. https://arxiv.org/abs/2601.20757

package/docs/rest/INDEX.md

@@ -2,6 +2,11 @@
 
 This directory is the human-readable REST API reference for Omnius. It is meant to be explored incrementally by agents and humans.
 
+For intent-first lookup, start with
+[Discovery](./endpoints/discovery.md), `GET /v1/discovery`, or the bundled
+[`DISCOVERY.json`](../DISCOVERY.json). Use this index after the catalog points
+to an endpoint family.
+
 Canonical sources:
 
 - Runtime OpenAPI generator: `packages/cli/src/api/openapi.ts`
@@ -21,6 +26,7 @@ Use this index first, then open the smallest relevant family file:
 | Auth, scopes, rate limits, API keys | `docs/rest/auth-and-scopes.md` |
 | Errors, pagination, ETags, request IDs | `docs/rest/errors-pagination-etags.md` |
 | OpenAPI and docs renderers | `docs/rest/openapi-source.md` |
+| Capability and documentation discovery | `docs/rest/endpoints/discovery.md` |
 | Chat, realtime, OpenAI-compatible inference | `docs/rest/endpoints/chat.md` |
 | Agentic jobs and run lifecycle | `docs/rest/endpoints/run.md` |
 | Config, endpoints, keys, profiles, projects | `docs/rest/endpoints/config.md` |
@@ -88,6 +94,7 @@ Scopes:
 | Family | Representative endpoints |
 | --- | --- |
 | Health | `/health`, `/health/ready`, `/health/startup`, `/version`, `/metrics` |
+| Discovery | `/v1/discovery`, `/v1/discovery/{id}` |
 | Inference and chat | `/v1/models`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/chat`, `/v1/generate`, `/api/generate`, `/v1/chat/sessions`, `/v1/chat/check-in` |
 | AIWG | `/v1/aiwg`, `/v1/aiwg/frameworks`, `/v1/aiwg/skills`, `/v1/aiwg/use`, `/v1/aiwg/expand` |
 | Runs | `/v1/run`, `/v1/runs`, `/v1/runs/{id}`, `/v1/todos`, `/v1/todos/{session_id}` |

package/docs/rest/QUICKREF.md

@@ -41,6 +41,13 @@ curl -s http://127.0.0.1:11435/health/ready
 curl -s http://127.0.0.1:11435/version
 ```
 
+## Discovery
+
+```bash
+curl -s 'http://127.0.0.1:11435/v1/discovery?q=bring%20your%20own%20inference'
+curl -s http://127.0.0.1:11435/v1/discovery/tool.web-search
+```
+
 ## Models
 
 ```bash
@@ -104,12 +111,23 @@ curl -s http://127.0.0.1:11435/v1/skills/omnius-rest-docs
 
 ## Tool Call
 
+First inspect `direct_callable`:
+
+```bash
+curl -s http://127.0.0.1:11435/v1/tools/memory_search
+```
+
 ```bash
 curl -s -X POST http://127.0.0.1:11435/v1/tools/memory_search/call \
   -H 'content-type: application/json' \
   -d '{"args":{"query":"rest api docs"}}'
 ```
 
+`web_search` is agent-bound. Offer it to `/v1/run`, `/v1/chat`, or
+`/v1/chat/completions` with `agent_loop: true` and
+`include_daemon_tools: ["read"]`; do not infer direct-call support from the
+presence of its schema.
+
 Deterministic bookkeeping without an agent run:
 
 ```bash

package/docs/rest/REST-DOCS-MANIFEST.json

@@ -12,6 +12,7 @@
   "full_reference": "docs/reference/rest-api.md",
   "skill": ".aiwg/addons/omnius-rest-docs/skills/omnius-rest-docs/SKILL.md",
   "families": [
+    { "name": "discovery", "path": "docs/rest/endpoints/discovery.md", "triggers": ["discovery", "capabilities", "catalog", "/v1/discovery", "discover", "show"] },
     { "name": "chat", "path": "docs/rest/endpoints/chat.md", "triggers": ["chat", "generate", "realtime", "OpenAI-compatible", "/v1/chat", "/v1/generate"] },
     { "name": "run", "path": "docs/rest/endpoints/run.md", "triggers": ["run", "jobs", "todos", "scheduled"] },
     { "name": "config", "path": "docs/rest/endpoints/config.md", "triggers": ["config", "keys", "profiles", "projects", "endpoint"] },

package/docs/rest/auth-and-scopes.md

@@ -24,7 +24,13 @@ key:scope:owner:rpm:tpd:max_jobs
 
 Compatibility: `OMNIUS_API_KEY` and `OMNIUS_API_KEYS` are still accepted as legacy REST auth variables, but new deployments should use the `OMNIUS_REST_*` namespace.
 
-Provider keys are separate from REST keys. Prefer `OMNIUS_PROVIDER_API_KEY`, `OMNIUS_MODEL_API_KEY`, or provider-native variables such as `VLLM_API_KEY` for upstream model auth. `OMNIUS_API_KEY` remains a legacy fallback for provider auth and legacy REST auth, so avoid it in new remote deployments. Scoped REST keys (`OMNIUS_REST_*` and `OMNIUS_API_KEYS`) are stripped before spawning agent subprocesses and are not forwarded as model-provider credentials.
+Provider keys are separate from REST keys. The exact upstream precedence is
+`OMNIUS_PROVIDER_API_KEY` → `OMNIUS_MODEL_API_KEY` →
+`OMNIUS_UPSTREAM_API_KEY` → `OMNIUS_API_KEY` → `VLLM_API_KEY` → persisted
+endpoint configuration. `OMNIUS_API_KEY` remains a legacy fallback for both
+provider and legacy REST auth, so avoid it in new remote deployments. Scoped
+REST keys (`OMNIUS_REST_*` and `OMNIUS_API_KEYS`) are stripped before spawning
+agent subprocesses and are not forwarded as model-provider credentials.
 
 Fields:
 

package/docs/rest/endpoints/discovery.md

@@ -0,0 +1,44 @@
+# Discovery
+
+The discovery API exposes the same catalog shipped in `docs/DISCOVERY.json`
+and used by `omnius discover` / `omnius show`.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/discovery` | Search or list catalog entries |
+| `GET` | `/v1/discovery/{id}` | Expand one stable entry |
+
+## Search
+
+```bash
+curl -s "http://127.0.0.1:11435/v1/discovery?q=web%20search&kind=tool&limit=5"
+```
+
+Query fields:
+
+- `q`: free-text intent; omit to list entries.
+- `kind`: one supported catalog kind.
+- `limit`: page size.
+- `offset`: zero-based page offset.
+
+The response includes pagination metadata and an ETag. Use
+`If-None-Match` when polling a long-running daemon.
+
+## Expand
+
+```bash
+curl -s http://127.0.0.1:11435/v1/discovery/tool.web-search
+```
+
+An entry contains its stable ID, kind, title, summary, aliases/keywords,
+invocation interfaces, typed references, and related entries. Discovery is
+read-scoped and does not execute the selected capability.
+
+Important entrypoints:
+
+- `capability.bring-your-own-inference`
+- `provider.anthropic`
+- `provider.gemini`
+- `tool.web-search`
+- `api.tools`
+- `operation.version-compatibility`

package/docs/rest/endpoints/events.md

@@ -61,3 +61,8 @@ Usage endpoints support dashboards for requests, token counts, rate limits, and
 ## Ollama Pool
 
 The pool endpoints are admin-oriented process hygiene tools. They report managed `ollama serve` processes and cleanup decisions. Cleanup accounts for stale pool state and orphan runner risks.
+
+`GET /version` is also the compatibility bootstrap for an agent or service
+integration. Execution clients should send `X-Omnius-Min-Version` on work
+requests so an older daemon returns `412` before starting work. See
+[Service Version Compatibility](../../operations/version-compatibility.md).

package/docs/rest/endpoints/tools.md

@@ -61,6 +61,15 @@ Profiles can also be selected with `X-Tool-Profile`. Named profiles resolve in t
 
 Tool calls are gated by auth scope, tool policy, off-device policy, and profile restrictions.
 
+Catalog presence does not imply direct invocation. Inspect
+`direct_callable` in the live metadata. In particular, `web_search` is
+agent-bound: discover its schema with `GET /v1/tools/web_search`, then offer it
+through `/v1/run`, `/v1/chat`, or `/v1/chat/completions` using
+`agent_loop: true` and `include_daemon_tools: ["read"]`. Do not assume
+`POST /v1/tools/web_search/call` is available.
+
+See [Tools And Web Search](../../guides/tools-and-web-search.md).
+
 Bookkeeping tools are direct-callable and do not require a model run:
 
 ```bash

package/docs/reviews/adversary-system-review.md

@@ -0,0 +1,42 @@
+# Adversary System Review
+
+**Date:** 2026-06-28  
+**Scope:** Read-only pass  
+**Files reviewed:**
+- `packages/orchestrator/src/adversaryStream.ts` (407 lines)
+- `packages/orchestrator/tests/adversaryStream.test.ts` (242 lines)
+
+## Architecture
+
+The adversary is a **generative, inference-driven auditor** running as a separate memory stream (`AdversaryStream`) adjacent to the main agent loop. It replaces the prior pure-regex adversary that only fired `false_success` when there were ZERO recent successes (missing every mixed success/failure run).
+
+## Key Features
+
+1. **Own persistent memory** — claims ledger (assertions, evidence state, verdicts) separate from main agent context
+2. **Single inference per observation** — fires one backend call per high-signal claim, parses structured critique
+3. **Classification taxonomy** — `false_failure`, `redundant_action`, `loop_detected`, plus `ok` (no intervention)
+4. **Loop detection** — `loopSignal` tracks repeated tool calls with same target; fires when count ≥ threshold
+5. **Success-language regex** — `SUCCESS_LANGUAGE` matches optimistic claims like "done", "verified", "live", "hydrated"
+6. **Non-blocking** — adversary is advisory; never blocks tool calls. `adversaryRedundantSignal` is Priority 1 in critic but returns guidance, not a block.
+
+## Integration Points
+
+- **AgenticRunner**: manages `adversaryMode` ("backseat" | "skillcoach" | "both"), creates `AdversaryStream`, emits `debug_adversary` and `adversary_reaction` events
+- **Critic**: `adversaryRedundantSignal` triggers WO-FIX-C path with message "The adversary recognized this exact tool call as already observed earlier."
+- **TUI**: renders adversary buffer (last 50 entries), shows `adversary: N tracked` in status line
+
+## Test Coverage
+
+- `adversarySystemPrompt` encodes evidence-demanding posture (checks "started ≠ running", "exit code 0")
+- `parseAdversaryCritique` structured output parsing
+- `AdversaryStream` single-flight behavior, ledger persistence
+- Loop detection with `loopSignal`
+- `false_failure` and `redundant_action` classification
+
+## Assessment
+
+The system is well-structured. The generative approach (inference-driven vs regex) addresses the original blind spot. The non-blocking design is correct — adversary provides critique without preventing progress. The integration with critic's Priority 1 path gives it real influence on loop behavior.
+
+## No Issues Found
+
+This was a read-only review. No bugs, no improvements identified. The system is production-ready.