0xray 3.4.1 → 3.4.3

package/dist/README.md

@@ -1,126 +1,203 @@
 # xray — MCP-Centric AI Governance OS
 
-9 agents · 44 skills · 16 MCPs governance servers · 60 codex terms
+**v3.4.2** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
-xray is the pure v2 three-subsystem AI orchestration framework, now **MCP-centric** with dedicated skill servers for governance deliberation:
-
-- **Inference** — reasoning, execution, and agent intelligence
-- **External Governance** — Dynamo Solar SSOT for proposal evaluation, resonance/isotopic signals, coherence, and Codex enforcement before any action
-- **Autonomous Engine** — thinDispatch 7-flow in the MCP orchestrator for automatic delegation, routing, and end-to-end coordination
-
-3 dedicated MCP servers (`code-review`, `security-audit`, `researcher`) deliberate governance proposals. Agents are declared in `.opencode/agents/*.yml` — the YML SSOT. Zero manual setup. Automatic discovery and activation.
+xray is the pure v2 three-subsystem AI orchestration framework — **MCP-centric**, governed by Dynamo, and autonomous via thinDispatch. Consumer `npm install 0xray` auto-wires all four platform bridges and seven MCP servers with zero manual config.
 
 ## Quick Start
 
 ```bash
-npm install 0xray
+npm install 0xray          # postinstall: 4 bridges + 7 MCPs + AGENTS.md + SKILLS.md + .mcp.json
+npx 0xray status          # verify install
+npx 0xray setup            # optional: symlinks, hook extras
+```
 
-# CLI
-npx 0xray --help
-npx 0xray grok install          # Install Grok CLI plugin
-npx 0xray hermes bridge         # Hermes Agent bridge
+Manual per-platform install (idempotent, same result as postinstall):
+
+```bash
+npx 0xray opencode install
+npx 0xray grok install     # 7 MCPs servers + dual skill sync (~/.grok/plugins + ~/.grok/skills)
+npx 0xray hermes install
+npx 0xray openclaw install
+npx 0xray skill:install    # starter skills
 ```
 
-The installation seeds YML surfaces and MCP servers. Place agent definitions in `.opencode/agents/` — they are live immediately.
+## Autonomy command (default operating model)
+
+When the suit is worn, **`autonomy-command`** is ON by default: lead dev takes helm, phased todos, best subagent per task, per-suite test triage, loop until green. No keywords required. Slash: `/autonomy-command`
+
+Docs: [guides/autonomy-command](docs-site/docs/guides/autonomy-command.md) · Skill: `src/skills/autonomy-command/SKILL.md`
+
+## What's New Since 3.1
+
+| Version | Highlights |
+|---------|------------|
+| **3.4.1** | Unified `install-bridges.cjs` on postinstall — OpenCode, Grok, Hermes, OpenClaw in one pass. All 7 MCPs servers via `npx -y 0xray mcp <cmd>` (no `dist/` paths). Canonical `release.mjs` pipeline. |
+| **3.3.1** | Orchestrator confidence gate wired into execution planning. |
+| **3.3.0** | Pluggable **Memory Routing** (`features.json` → `memory_routing`). Repertoire is the default provider in the framework repo. |
+| **3.2.0** | Typecheck hardening (58 errors fixed), orphan cleanup (5 deleted / ~39 integrated), full pre-tool-use hook, SelfProposalEngine + AsideContext restored, Hermes E2E 44/0/0, Grok CLI E2E green. |
+| **3.1.1** | StringRay → **0xRay** rename. Marketplace files (`.mcp.json`, `.grok-plugin/plugin.json`). Postinstall ships `AGENTS.md`, `SKILLS.md`, `.gitignore.default`. ConfigLoader `mcpServers` format. |
+| **3.1.0** | Pre-publish guard tolerates missing `features.json`. |
+
+### Consolidations
+
+- **One consumer install path** — `postinstall.cjs` → `installAllBridges()` replaces scattered per-platform setup.
+- **7-server MCP surface** — `.mcp.json` SSOT; Grok plugin and all bridges share `XRAY_MCP_SERVERS`.
+- **Dev vs consumer AGENTS** — `AGENTS.md` (framework) vs `AGENTS-consumer.md` (copied to consumer projects on install).
+- **Release pipeline** — `npm run release:patch|minor|major` → reconcile → gate → artifacts → tag → publish.
+
+### Removals / Deprecations
+
+- **StringRay / strray-ai** branding retired (3.1.1).
+- **`hermes bridge`** CLI removed — use `npx 0xray hermes install`.
+- **`.opencode/xray/` fallback** removed from auto-reflection-generator (3.1.1).
+- **~180 stale `@version` JSDoc tags** and **"xray 2.0" command doc strings** cleaned (3.2.0).
+- **`advanced-features/`** decoupled from core boot — not on the consumer install path.
+- **PostProcessor** soft-deprecated since 3.0 (`enablePostProcessor: false` default).
 
 ## Three-Subsystem Architecture
 
 ```
 ┌─────────────────────────────────────────────────┐
 │                  Inference                       │
-│  Proposals · Reflection · Execution             │
+│  Proposals · Reflection · Memory routing        │
 ├─────────────────────────────────────────────────┤
 │           External Governance (Dynamo)           │
-│  Codex enforcement · Resonance/Isotopic · SSOT  │
-│  16 MCPs skill servers deliberate proposals       │
+│  Codex enforcement · Resonance/Isotopic · SSOT    │
+│  3 deliberation MCPs: code-review, security,     │
+│  researcher (within 7-server consumer surface)  │
 ├─────────────────────────────────────────────────┤
 │          Autonomous Engine (thinDispatch)        │
-│  7-flow MCP · Delegation · Governance gate      │
+│  7-flow · AsideContext · Confidence gate        │
 └─────────────────────────────────────────────────┘
 ```
 
-### Inference
-Proposal generation, reflection cycles, and execution planning. Produces structured proposals that enter the governance gate.
-
-### External Governance (Dynamo Solar SSOT)
-Mandatory governance filter powered by Dynamo — a neural net based on solar physics and temporal first principles. Evaluates proposals for Codex compliance, resonance alignment, and isotopic coherence before any action is taken.
-
-- 3 real MCP skill servers deliberate: `code-review`, `security-audit`, `researcher`
-- Weighted voting via PHI (1.666) / TAU (0.865) matrix
-- External Dynamo integration required (not optional)
-- CodexPolicyService — single source of truth for Codex loading
-- Active codex snapshot available via `get_active_codex` MCP tool
-
-### Autonomous Engine (thinDispatch 7-flow)
-MCP orchestrator with 7-flow dispatch for automatic delegation, routing, and coordination. Handles complex multi-step tasks with automatic complexity-based routing.
-
-## CLI
-
-```bash
-0xray <command>
-
-Commands:
-  install         Install xray framework
-  grok            Grok CLI plugin management
-  hermes          Hermes Agent bridge
-  integration     Integration management
-  validate        Validate installation
-  version         Show version
+- **Inference** — proposals, reflection, execution planning. Optional memory-routing enrichment (v3.3).
+- **External Governance** — Dynamo Solar SSOT; CodexPolicyService; weighted PHI/TAU deliberation.
+- **Autonomous Engine** — thinDispatch 7-flow routing; orchestrator confidence gate (v3.3.1).
+
+## Consumer Install (postinstall)
+
+On `npm install 0xray` in a consumer project, postinstall automatically:
+
+1. Copies **`AGENTS-consumer.md` → `AGENTS.md`** and ships root **`SKILLS.md`**
+2. Seeds **`.gitignore`** from `.gitignore.default` (if absent)
+3. Deploys **`.xray/`** config (`codex.json`, `features.json`, `config.json`)
+4. Writes project **`.mcp.json`** with 7 MCPs servers (`npx -y 0xray mcp …`)
+5. Installs **4 bridges**: OpenCode (agents + `opencode.json`), Grok (plugin + global skills), Hermes (`~/.hermes/plugins/xray-hermes`), OpenClaw (config + skills)
+6. Syncs **45 framework skills** to platform skill dirs
+7. Installs git pre-commit hook (non-blocking if not a git repo)
+
+## Seven MCP Servers (consumer)
+
+All registered via `npx -y 0xray mcp <cmd>` — no brittle `dist/` paths:
+
+| Server | Command | Role |
+|--------|---------|------|
+| `xray-governance` | `mcp governance` | Proposal governance, codex snapshot, quality gates |
+| `xray-skills` | `mcp skills` | 45 knowledge skills + skill invocation |
+| `xray-orchestrator` | `mcp orchestrator` | Complexity analysis, lead-dev plan, task delegation |
+| `xray-enforcer` | `mcp enforcer` | Codex compliance, rule validation |
+| `xray-researcher` | `mcp researcher` | Codebase exploration, implementation lookup |
+| `xray-code-review` | `mcp code-review` | Proposal quality, best practices |
+| `xray-architect-tools` | `mcp architect-tools` | System design, architecture decisions |
+
+The framework repo also ships additional internal `.server.ts` implementations for orchestration pipelines — these are not part of the 7-server consumer `.mcp.json` surface.
+
+## Agents
+
+**42 YML agent surfaces** in `src/opencode/agents/*.yml` — zero manual registration. Invoke via `@agent-name` in OpenCode.
+
+Core governance agents:
+
+| Agent | Purpose |
+|-------|---------|
+| `@enforcer` | Codex compliance & error prevention |
+| `@orchestrator` | Multi-step task coordination |
+| `@architect` | System design & technical decisions |
+| `@security-auditor` | Vulnerability detection |
+| `@code-reviewer` | Quality assessment |
+| `@refactorer` | Technical debt elimination |
+| `@testing-lead` | Testing strategy |
+| `@bug-triage-specialist` | Error investigation |
+| `@researcher` | Codebase exploration |
+
+See [AGENTS.md](AGENTS.md) and [SKILLS.md](SKILLS.md) for the full agent and skill catalog.
+
+## Memory Routing + Repertoire (v3.3+)
+
+Pluggable `memory_routing` block in `features.json` (validated by `features.schema.json`):
+
+```json
+"memory_routing": {
+  "enabled": true,
+  "provider": "repertoire",
+  "module_path": "../repertoire/dist/provider/memory-routing-provider.js",
+  "config": {
+    "dataDir": "../repertoire/data",
+    "signalsPath": "../repertoire/data/curated_signals.json",
+    "logDir": "../repertoire/logs/groover-inference"
+  }
+}
 ```
 
-## Integrations
-
-| Platform | Status | Description |
-|----------|--------|-------------|
-| **OpenClaw** | ✅ | API server, client, config, hooks — full integration |
-| **Hermes Agent** | ✅ | Python bridge, plugin YAML, tools, schemas |
-| **Grok CLI** | ✅ | Plugin install via `0xray grok install --force`, user-level plugin hooks |
-| **OpenCode** | ✅ | Native YML agent surfaces, E2E 42/42 solo, 34/34 orchestrator |
+| Integration | What it does |
+|-------------|--------------|
+| **ExecutionPlanner** (v3.3.1) | `getTaskConfidence()` → complexity boost, trap hints, signal-aware `selectAgent()` |
+| **thinDispatch** | Nucleus `scoreAndRoute()` (`0xray/nucleus`); memory provider `resolveThinDispatch()` when routing enabled |
+| **Researcher** | `researcher-confidence.ts` appends `MEMORY_ROUTING:` block to governance output |
+| **AsideContext** (v3.2) | `buildInheritedContext` → `inheritedContext.memoryRouting` on orchestrator `spawnAside` |
+| **Feedback** | Per-task `ingestFeedback()` closes the learning loop |
 
-## MCP Server Ecosystem
+**External hosts** (Hermes/Grok): add `repertoire-mcp` to `.mcp.json` — see Repertoire docs.
 
-xray ships MCP servers for all governance deliberation and framework capabilities:
+Consumers without Repertoire: `"memory_routing": { "enabled": false, "provider": "null" }`.
 
-**Governance Deliberation:** code-review, security-audit, researcher, enforcer-tools, governance
+Docs: [memory routing](docs-site/docs/guides/memory-routing.md) · [Repertoire](docs-site/docs/guides/repertoire.md) · [features.json](docs-site/docs/guides/features-json.md) · [all features since 3.1](docs-site/docs/guides/features-since-3.1.md)
 
-**Core Framework:** architect-tools, boot-orchestrator, estimation, framework-compliance-audit, framework-help, lint, model-health-check, orchestrator, performance-analysis, processor-pipeline, state-manager, auto-format
+## Integrations
 
-**Knowledge Skills:** api-design, architecture-patterns, bug-triage-specialist, code-analyzer, content-creator, database-design, devops-deployment, git-workflow, growth-strategist, log-monitor, mobile-development, multimodal-looker, performance-optimization, project-analysis, refactoring-strategies, seo-consultant, session-management, skill-invocation, strategist, tech-writer, testing-best-practices, testing-strategy, ui-ux-design
+| Platform | Install | Postinstall behavior |
+|----------|---------|----------------------|
+| **OpenCode** | `npx 0xray opencode install` | Merges `opencode.json`, copies agent YML surfaces |
+| **Grok CLI / Build** | `npx 0xray grok install` | Plugin + `~/.grok/skills/` sync, 7 MCPs servers |
+| **Hermes Agent** | `npx 0xray hermes install` | `~/.hermes/plugins/xray-hermes`, consumer root marker |
+| **OpenClaw** | `npx 0xray openclaw install` | `.xray/config/openclaw.json`, skill sync |
 
 ## Governance & Codex
 
-Codex enforcement is integrated at every level:
+- **68 terms** in `.xray/codex.json` — core, architecture, testing, performance, security, operations, governance
+- CodexPolicyService — Governance-owned SSOT for codex loading
+- Pre-governance gate blocks non-compliant proposals
+- Active codex snapshot via `get_active_codex` MCP tool
+- frameworkLogger structured logging (never `console.*`)
 
-- **60 terms** across categories: core, architecture, testing, performance, security, operations, governance
-- CodexPolicyService — canonical Governance-owned SSOT for Codex loading
-- Pre-governance gate blocks non-compliant proposals before execution
-- 16 MCPs skill servers deliberate each proposal
-- frameworkLogger structured logging throughout (never console.*)
-- Active codex snapshot available via `get_active_codex` MCP tool
+## Testing
 
-## Testing (2,2500 tests)
+| Suite | Status (v3.4.1) |
+|-------|-----------------|
+| Unit / Integration | 185 files, **3,226 passed** |
+| OpenCode E2E | 42/42 solo, 34/34 orchestrator |
+| Grok CLI E2E | 62/0 failures (v3.2.0 verified) |
+| OpenClaw E2E | 9/9 (v3.2.0 verified) |
+| Hermes E2E | 44/0/0 (v3.2.0 verified) |
+| Consumer smoke | `npm run release:gate` — pack → clean install → 7 MCPs + 4 bridges |
 
-| Suite | Status |
-|-------|--------|
-| Unit / Integration | 158 files, all pass |
-| Performance | 2500 tests, all pass |
-| Infrastructure | 2500 tests, all pass |
-| Consumer E2E | 4 platforms, all pass |
-| OpenCode E2E | 42/42 solo, 34/34 orchestrator, all pass |
-| OpenClaw E2E | 2500 tests, all pass |
-| Hermes E2E | 2500 tests, all pass |
-| Grok CLI E2E | 60/60 solo, 59/59 orchestrator, all pass |
+```bash
+npm test
+npm run release:gate    # full release gate
+```
 
 ## Release
 
 ```bash
-npm run release              # patch bump
-npm run release minor        # minor bump
-npm run release major        # major bump
-npm run release -- --dry-run # preview
+npm run release:patch   # canonical pipeline
+npm run release:minor
+npm run release:major
+npm run release:patch -- --dry-run
 ```
 
-The release pipeline: test → version:sync → build → commit → publish → push.
+Pipeline: reconcile-version → release-gate (build + test + consumer smoke) → CHANGELOG/README/AGENTS artifacts → commit → tag → npm publish.
 
 ## License
 
@@ -128,4 +205,4 @@ MIT — see [LICENSE](LICENSE)
 
 ---
 
-*xray — MCP-centric, governed, autonomous. Pure v2 three-subsystem.*
+*xray — MCP-centric, governed, autonomous. Pure v2 three-subsystem.*

package/dist/SKILLS.md

@@ -1,6 +1,10 @@
 # 0xray Skills
 
-xray ships **46 skills** that provide domain expertise across the full software lifecycle. Skills are loaded on demand and invoked via MCP servers, agents, or direct API.
+**v3.4.2** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+
+xray ships 45 knowledge skills (`src/skills/<name>/SKILL.md`) across the full software lifecycle. Lead-dev operating model lives in **`orchestrator`** skill + `multi_agent_orchestration.lead_dev_mode` in features.json. Skills load on demand via the **xray-skills** MCP server (`npx -y 0xray mcp skills`), agent `@mentions`, or platform skill directories after postinstall.
+
+Consumer `npm install 0xray` syncs all 45 skills to Grok, Hermes, and OpenClaw skill dirs. Framework repo also ships this file to consumers (3.1.1+).
 
 ---
 
@@ -10,7 +14,7 @@ xray ships **46 skills** that provide domain expertise across the full software
 |-------|-------|-------------|
 | `code-review` | @code-reviewer | Proposal quality, code analysis, best practices |
 | `security-audit` | @security-auditor | Vulnerability detection, threat modeling |
-| `security-scan` | — | Security vulnerability scanning and assessment |
+| `security-scan` | @security-auditor | Security vulnerability scanning and assessment |
 | `enforcer` | @enforcer | Codex compliance validation and error prevention |
 | `framework-compliance-audit` | — | Framework compliance auditing and validation |
 
@@ -18,123 +22,145 @@ xray ships **46 skills** that provide domain expertise across the full software
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `architect-tools` | — | System design and technical architecture tools |
+| `architect-tools` | @architect | System design and technical architecture tools |
 | `architecture-patterns` | — | Software architecture patterns and best practices |
 | `api-design` | — | RESTful API design and validation |
-| `database-engineer` | — | SQL/NoSQL schema design, query optimization, migrations |
+| `database-engineer` | @database-engineer | SQL/NoSQL schema design, query optimization, migrations |
 | `state-manager` | — | Application state management and persistence |
-| `session-management` | — | Manage user sessions and persistent state |
+| `session-management` | — | User sessions and persistent state |
 
 ## Engineering
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `backend-engineer` | — | REST/GraphQL APIs, microservices, auth, server architecture |
-| `frontend-engineer` | — | React/Vue/Angular/Svelte, responsive design, accessibility |
-| `frontend-ui-ux-engineer` | — | Visual design, CSS systems, accessibility, UX |
-| `mobile-developer` | — | iOS (Swift/SwiftUI), Android (Kotlin/Compose), RN, Flutter |
-| `devops-engineer` | — | CI/CD, IaaC, containers, cloud deployment, reliability |
+| `backend-engineer` | @backend-engineer | REST/GraphQL APIs, microservices, auth, server architecture |
+| `frontend-engineer` | @frontend-engineer | React/Vue/Angular/Svelte, responsive design, accessibility |
+| `frontend-ui-ux-engineer` | @frontend-ui-ux-engineer | Visual design, CSS systems, accessibility, UX |
+| `mobile-developer` | @mobile-developer | iOS, Android, React Native, Flutter |
+| `devops-engineer` | @devops-engineer | CI/CD, IaC, containers, cloud deployment |
 
 ## Code Quality & Analysis
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `code-analyzer` | — | Deep code analysis, metrics extraction, pattern detection |
-| `project-analysis` | — | Analyze project structure, complexity, and health metrics |
+| `code-analyzer` | @code-analyzer | Deep code analysis, metrics, pattern detection |
+| `project-analysis` | — | Project structure, complexity, health metrics |
 | `lint` | — | Code linting and static analysis |
-| `auto-format` | — | Automated code formatting and style consistency |
-| `refactoring-strategies` | @refactorer | Code refactoring techniques and strategies |
+| `auto-format` | — | Automated formatting and style consistency |
+| `refactoring-strategies` | @refactorer | Refactoring techniques and strategies |
 
 ## Testing
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
 | `testing-strategy` | @testing-lead | Comprehensive testing strategies and coverage |
-| `testing-best-practices` | — | Testing best practices and patterns |
+| `testing-best-practices` | — | Testing best practices and QA patterns |
 
 ## Performance
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `performance-analysis` | — | System performance analysis and optimization |
-| `performance-engineer` | — | Profiling, benchmarking, load testing, optimization |
-| `performance-optimization` | — | Application performance optimization and tuning |
+| `performance-analysis` | — | System performance analysis |
+| `performance-engineer` | @performance-engineer | Profiling, benchmarking, load testing |
+| `performance-optimization` | — | Application performance tuning |
 
 ## Debugging & Monitoring
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `bug-triage` | @bug-triage-specialist | Bug triage, debugging analysis, issue prioritization |
-| `log-monitor` | — | Log analysis, pattern detection, alerting |
+| `bug-triage` | @bug-triage-specialist | Bug triage, debugging, issue prioritization |
+| `log-monitor` | @log-monitor | Log analysis, pattern detection, alerting |
 | `model-health-check` | — | AI model health monitoring and diagnostics |
 
 ## Orchestration & Workflow
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `orchestrator` | @orchestrator | Multi-agent workflow coordination and task delegation |
-| `xray-orchestrator` | — | Main orchestration skill for xray agents |
+| `orchestrator` | @orchestrator | Multi-agent coordination + **lead-dev mode** (codex 67–68) |
+| `xray-orchestrator` | — | xray orchestration skill (MCP orchestrator surface) |
 | `processor-pipeline` | — | Data processing pipeline management |
-| `boot-orchestrator` | — | Framework initialization and boot orchestration |
+| `boot-orchestrator` | — | Framework boot orchestration |
 
 ## Research & Content
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
 | `researcher` | @researcher | Codebase exploration, implementation lookup |
-| `content-creator` | — | Marketing copy, technical docs, blog posts, social media |
-| `tech-writer` | — | API docs, READMEs, ADRs, changelogs, DX |
-| `storyteller` | — | Deep narrative reflections, sagas, technical stories |
-| `seo-consultant` | — | Technical SEO, schema markup, Core Web Vitals |
-| `growth-strategist` | — | Campaign strategy, market analysis, brand positioning |
+| `content-creator` | @content-creator | Marketing copy, technical docs, SEO content |
+| `tech-writer` | @tech-writer | API docs, READMEs, ADRs, changelogs |
+| `storyteller` | @storyteller | Narrative reflections, sagas, technical stories |
+| `seo-consultant` | @seo-consultant | Technical SEO, schema markup, Core Web Vitals |
+| `growth-strategist` | @growth-strategist | Campaign strategy, market analysis, conversion |
 
 ## UX & Design
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `ui-ux-design` | — | Mobile-first, cognitive simplicity, accessibility-first |
-| `multimodal-looker` | — | Visual content analysis for diagrams, screenshots, UI mockups |
-
-## Strategy
-
-| Skill | Agent | Description |
-|-------|-------|-------------|
-| `strategist` | @strategist | Strategic guidance, architectural decisions, risk analysis |
-| `inference-improve` | — | Autonomous inference improvement through collaborative analysis |
+| `ui-ux-design` | — | Mobile-first, cognitive simplicity, accessibility |
+| `multimodal-looker` | @multimodal-looker | Diagrams, screenshots, UI mockup analysis |
 
-## Git & Workflow
+## Strategy & Inference
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `git-workflow` | — | Git workflow management and collaboration tools |
+| `strategist` | @strategist | Architecture decisions, risk analysis |
+| `inference-improve` | — | Autonomous inference improvement |
 
-## Integration
+## Git, Workflow & Integration
 
 | Skill | Agent | Description |
 |-------|-------|-------------|
-| `hermes-agent` | — | Manage xray from Hermes Agent via native plugin |
+| `git-workflow` | — | Git workflow and collaboration |
+| `hermes-agent` | @hermes-agent | Hermes Agent bridge operations |
 
 ---
 
 ## Invoking Skills
 
-Skills are invoked automatically by agents or via MCP:
+### Via agent (OpenCode / chat)
 
-```bash
-# Via agent mention (in any chat)
+```
 @code-reviewer review this PR
+@researcher find where auth is implemented
+```
+
+### Via xray-skills MCP (13 tools)
 
-# Via MCP tool call
-npx xray mcp call code-review analyze_code_quality --args '{"path": "src/"}' 
+Configured in project `.mcp.json` on postinstall:
 
-# Via direct agent
-npx xray agent run @refactorer "optimize src/core/"
+```bash
+npx -y 0xray mcp skills    # stdio server
+```
+
+MCP tools include: `invoke-skill`, `list-skills`, `skill-code-review`, `skill-security-audit`, `skill-api-design`, `skill-testing-strategy`, and more.
+
+### Install additional skill packs
+
+```bash
+npx 0xray skill:install
+npx 0xray skill:install <source>
 ```
 
-## Skill Locations
+## Skill locations
+
+| Context | Path |
+|---------|------|
+| Source (framework) | `src/skills/<name>/SKILL.md` |
+| Published package | `node_modules/0xray/dist/skills/<name>/SKILL.md` |
+| OpenCode (after setup) | `.opencode/skills/<name>/SKILL.md` |
+| Grok | `~/.grok/skills/<name>/SKILL.md` + plugin dir |
+| Hermes / OpenClaw | Platform skill dirs (postinstall sync) |
+
+## Related features (since 3.1)
+
+| Feature | Skill connection |
+|---------|------------------|
+| **Memory routing** (v3.3) | Researcher uses Repertoire signals; optional `@0xray/repertoire` MCP |
+| **AsideContext** (v3.2) | Orchestrator subcontexts during skill dispatch |
+| **7 MCP servers** (v3.4.1) | `xray-skills` is the primary skill invocation surface |
+
+Docs: [AGENTS.md](AGENTS.md) · [README.md](README.md) · [Docusaurus guides](docs-site/docs/guides/)
 
-Each skill has a `SKILL.md` with full reference:
+## Complete catalog (45)
 
-- **Source**: `src/skills/<name>/SKILL.md`
-- **Consumer**: `node_modules/0xray/dist/skills/<name>/SKILL.md`
-- **Opend**: `.opencode/skills/<name>/SKILL.md` (copied on `npx xray setup`)
+`api-design` · `architect-tools` · `architecture-patterns` · `auto-format` · `backend-engineer` · `boot-orchestrator` · `bug-triage` · `code-analyzer` · `code-review` · `content-creator` · `database-engineer` · `devops-engineer` · `enforcer` · `framework-compliance-audit` · `frontend-engineer` · `frontend-ui-ux-engineer` · `git-workflow` · `growth-strategist` · `hermes-agent` · `inference-improve` · `lint` · `log-monitor` · `mobile-developer` · `model-health-check` · `multimodal-looker` · `orchestrator` · `performance-analysis` · `performance-engineer` · `performance-optimization` · `processor-pipeline` · `project-analysis` · `refactoring-strategies` · `researcher` · `security-audit` · `security-scan` · `seo-consultant` · `session-management` · `state-manager` · `storyteller` · `strategist` · `tech-writer` · `testing-best-practices` · `testing-strategy` · `ui-ux-design` · `xray-orchestrator`

package/dist/agents/architect.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "./types.js";
+export declare const architect: AgentConfig;

package/dist/agents/backend-engineer.d.ts

@@ -0,0 +1,8 @@
+import type { AgentConfig } from "./types.js";
+/**
+ * Backend Engineer Agent
+ *
+ * Specialist in API design, server architecture, microservice patterns,
+ * authentication, and backend performance optimization.
+ */
+export declare const backendEngineer: AgentConfig;

package/dist/agents/bug-triage-specialist.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "./types.js";
+export declare const bugTriageSpecialist: AgentConfig;

package/dist/agents/code-analyzer.d.ts

@@ -0,0 +1,7 @@
+import { AgentConfig } from "./types.js";
+/**
+ * Code Analyzer Agent
+ *
+ * Universal analysis specialist for code, systems, and technical artifacts.
+ */
+export declare const codeAnalyzer: AgentConfig;

package/dist/agents/code-reviewer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "./types.js";
+export declare const codeReviewer: AgentConfig;

package/dist/agents/content-creator.d.ts

@@ -0,0 +1,9 @@
+import { AgentConfig } from "./types.js";
+/**
+ * Content Creator Agent
+ *
+ * Content specialist focused on SEO-optimized copywriting for both
+ * human readers and AI search engines. Expert in brand voice adaptation
+ * and conversion-focused content.
+ */
+export declare const contentCreator: AgentConfig;

package/dist/agents/database-engineer.d.ts

@@ -0,0 +1,8 @@
+import type { AgentConfig } from "./types.js";
+/**
+ * Database Engineer Agent
+ *
+ * Specialist in database architecture, schema design, query optimization,
+ * migrations, and data modeling for SQL and NoSQL databases.
+ */
+export declare const databaseEngineer: AgentConfig;

package/dist/agents/devops-engineer.d.ts

@@ -0,0 +1,8 @@
+import type { AgentConfig } from "./types.js";
+/**
+ * DevOps Engineer Agent
+ *
+ * Specialist in CI/CD pipelines, infrastructure as code, container orchestration,
+ * cloud deployment, and operational reliability.
+ */
+export declare const devopsEngineer: AgentConfig;

package/dist/agents/frontend-engineer.d.ts

@@ -0,0 +1,8 @@
+import type { AgentConfig } from "./types.js";
+/**
+ * Frontend Engineer Agent
+ *
+ * Specialist in React, Vue, Angular, responsive design, accessibility,
+ * performance optimization, and modern UI/UX implementation.
+ */
+export declare const frontendEngineer: AgentConfig;

package/dist/agents/frontend-ui-ux-engineer.d.ts

@@ -0,0 +1,8 @@
+import type { AgentConfig } from "./types.js";
+/**
+ * Frontend UI/UX Engineer Agent
+ *
+ * Specialist in UI/UX design, user experience, visual design,
+ * accessibility, and frontend implementation.
+ */
+export declare const frontendUiUxEngineer: AgentConfig;

package/dist/agents/growth-strategist.d.ts

@@ -0,0 +1,8 @@
+import { AgentConfig } from "./types.js";
+/**
+ * Growth Strategist Agent
+ *
+ * Strategic marketing specialist for product positioning, campaign strategy,
+ * market analysis, and integrated marketing communications.
+ */
+export declare const growthStrategist: AgentConfig;

package/dist/agents/index.d.ts

@@ -0,0 +1,25 @@
+import type { AgentConfig } from "./types.js";
+import { architect } from "./architect.js";
+import { bugTriageSpecialist } from "./bug-triage-specialist.js";
+import { codeReviewer } from "./code-reviewer.js";
+import { securityAuditor } from "./security-auditor.js";
+import { refactorer } from "./refactorer.js";
+import { testingLead } from "./testing-lead.js";
+import { logMonitor } from "./log-monitor.js";
+import { researcher } from "./researcher.js";
+import { codeAnalyzer } from "./code-analyzer.js";
+import { backendEngineer } from "./backend-engineer.js";
+import { contentCreator } from "./content-creator.js";
+import { databaseEngineer } from "./database-engineer.js";
+import { devopsEngineer } from "./devops-engineer.js";
+import { frontendEngineer } from "./frontend-engineer.js";
+import { frontendUiUxEngineer } from "./frontend-ui-ux-engineer.js";
+import { growthStrategist } from "./growth-strategist.js";
+import { mobileDeveloper } from "./mobile-developer.js";
+import { performanceEngineer } from "./performance-engineer.js";
+import { seoConsultant } from "./seo-consultant.js";
+import { strategist } from "./strategist.js";
+import { techWriter } from "./tech-writer.js";
+import { multimodalLooker } from "./multimodal-looker.js";
+export declare const builtinAgents: Record<string, AgentConfig>;
+export { architect, bugTriageSpecialist, codeReviewer, securityAuditor, refactorer, testingLead, logMonitor, researcher, codeAnalyzer, backendEngineer, contentCreator, databaseEngineer, devopsEngineer, frontendEngineer, frontendUiUxEngineer, growthStrategist, mobileDeveloper, performanceEngineer, seoConsultant, strategist, techWriter, multimodalLooker, };