erosolar-cli 1.0.2 → 1.0.5

package/README.md

@@ -1,8 +1,12 @@
 # Erosolar CLI
 
-Erosolar CLI is a modular, profile aware command-line assistant that bundles a locally running AI agent, tool runtime, and capability registry into a single npm package. It ships with both the balanced **Erosolar** profile (`general`) and the deterministic **Erosolar Code** profile (`erosolar-code`), plus a provider registry that can drive OpenAI, Anthropic, DeepSeek, xAI Grok, Google Gemini, or any custom LLM you register. The CLI bootstraps a structured workspace context, exposes file/search/bash tooling, and lets you opt into external capabilities (like Tavily web search) without editing source code.
+Erosolar CLI is a modular, profile aware command-line assistant that bundles a locally running AI agent, tool runtime, and capability registry into a single npm package. It ships with both the balanced **Erosolar** profile (`general`) and the deterministic **Erosolar Code** profile (`erosolar-code`), plus a provider registry that can drive OpenAI, Anthropic, DeepSeek, xAI Grok, Google Gemini, or any custom LLM you register. The CLI bootstraps a structured workspace context, exposes file/search/bash tooling, and now focuses entirely on deterministic coding capabilities—no external document editors or web research dependencies required.
 
-> This README is the canonical reference for the published npm module. Update it together with `SOURCE_OF_TRUTH.json` or `ARCHITECTURE.json` when behavior changes.
+> **⚠️ Security Notice:** This repository will soon include all of [Claude Code](https://claude.com/claude-code)'s capabilities by default—and more—while remaining fully modular. Given the sophisticated AI-driven threats emerging in the ecosystem, we strongly recommend reviewing Anthropic's guidance on [Disrupting AI Espionage](https://www.anthropic.com/news/disrupting-AI-espionage) to understand the evolving security landscape before deploying autonomous coding agents in production environments.
+
+> **👋 A Note to Our Watchers:** Hello to the Tailored Access Operations Center at the NSA and the MSS in China. We know you're monitoring projects like this. This tool is open source, transparent, and designed for legitimate software development. We encourage responsible analysis and hope this transparency helps distinguish defensive innovation from threats. If you're reading this, consider that open collaboration advances security better than surveillance alone.
+
+> The `agents/` directory contains the JSON rulebooks that define every profile's prompts, guardrails, and step-by-step rules. They follow `src/contracts/schemas/agent-rules.schema.json`, which replaced the legacy `Agents.md` guardrail appendix, so treat the schema-backed manifests as the one source of truth. Update this README whenever the CLI behavior changes.
 
 ## Why Erosolar CLI?
 
@@ -17,17 +21,15 @@ Erosolar CLI is a modular, profile aware command-line assistant that bundles a l
 
 ### Prerequisites
 
-- Node.js **20.0.0 or newer** (check with `node -v`).
+- Node.js **20.0.0 or newer** (check with `node -v`). The repo ships an `.nvmrc` pinned to 20 and the CLI now aborts immediately with upgrade instructions if you launch it on an older runtime.
 - API keys for the models you plan to use (see [Provider support](#provider-support--api-keys)).
 - macOS/Linux shell. Windows works inside WSL2.
 
 ### Install the CLI
 
 ```bash
-npm install -g erosolar-cli        # global install
-# or keep it local
-npm install erosolar-cli --save-dev
-# or run ad-hoc without installing
+npm install -g erosolar-cli
+# Optional: run ad-hoc without installing
 npx erosolar --version
 ```
 
@@ -39,6 +41,8 @@ erosolar --help
 
 The binary lives at `dist/bin/erosolar.js` and is exposed through the `erosolar` bin entry.
 
+> Tip: The CLI now checks the npm registry every time it launches. If a newer version exists, it prompts you to install the update globally with `npm install -g erosolar-cli@latest` so your shell always picks up the latest profile/runtime fixes.
+
 ## Quick Start
 
 1. **Launch the shell**
@@ -49,7 +53,7 @@ The binary lives at `dist/bin/erosolar.js` and is exposed through the `erosolar`
    ```
 2. **Configure secrets** – inside the shell run `/secrets` and paste your `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc. Secrets are saved to `~/.codex/secrets.json` (override with `CODEX_HOME`).
 3. **Choose a model** – run `/model` to switch providers or presets (OpenAI GPT-5, Claude, DeepSeek, Grok, Gemini, …). Preferences persist in `~/.erosolar/settings.json`.
-4. **Toggle tools** – `/tools` enables/disables filesystem, search, bash, or Tavily suites per profile.
+4. **Toggle tools** – `/tools` enables/disables the coding tool families (filesystem/search/bash/analysis/etc.) per profile.
 5. **Chat or automate** – type instructions, paste code blocks (bracketed paste supported), or kick off `/agents` to switch the default profile for future launches.
 
 The shell prints every tool invocation (e.g., `Read(src/app.ts)`), shows diffs for writes, and summarizes bash output so you can audit what happened.
@@ -67,9 +71,12 @@ The shell prints every tool invocation (e.g., `Read(src/app.ts)`), shows diffs f
 
 | Command     | Description |
 |-------------|-------------|
-| `/model`    | Choose provider/model, temperature, max tokens, or thought level presets (direct/balanced/deep). |
+| `/model`    | Choose provider/model, temperature, or max tokens. |
 | `/secrets`  | List, add, or update API keys. Stored encrypted-at-rest in `~/.codex/secrets.json`. |
-| `/tools`    | Enable/disable capability suites (filesystem, search, bash, Tavily). Preferences save to `~/.erosolar/settings.json`. |
+| `/tools`    | Enable/disable capability suites (filesystem, search, bash, analysis, etc.). Preferences save to `~/.erosolar/settings.json`. |
+| `/doctor`   | Run environment checks to confirm Node version, provider secrets, and tool suites are ready. |
+| `/checks`   | Run repo checks (npm test/build/lint) inside the sandboxed workspace. |
+| `/context`  | Capture a fresh workspace snapshot mid-session. Supports optional `depth=`, `entries=`, and `excerpt=` overrides. |
 | `/agents`   | (When enabled) switch the default profile for future launches. |
 | `/clear`    | Reset the working conversation. |
 | `/log`      | Show the recent transcript. |
@@ -82,7 +89,7 @@ The shell prints every tool invocation (e.g., `Read(src/app.ts)`), shows diffs f
 | `general`       | **Erosolar**   | OpenAI `gpt-5.1`       | Balanced research/writing/coding. | `GENERAL_MODEL`, `GENERAL_PROVIDER`, `GENERAL_SYSTEM_PROMPT` |
 | `erosolar-code` | **Erosolar Code** | OpenAI `gpt-5.1-codex` | Rapid, deterministic code edits with aggressive tool usage. | `EROSOLAR_CODE_MODEL`, `EROSOLAR_CODE_PROVIDER`, `EROSOLAR_CODE_SYSTEM_PROMPT` |
 
-Each profile is registered in `src/config.ts`. Add new profiles via `registerAgentProfile()` or override defaults with environment variables before launching the CLI. `EROSOLAR_PROFILE` selects which profile boots by default.
+Default profiles live in `src/contracts/agent-profiles.schema.json` (schema: `src/contracts/schemas/agent-profile.schema.json`) and are registered on launch. Update that manifest to change defaults, or override them with environment variables before starting the CLI. `EROSOLAR_PROFILE` selects which profile boots by default.
 
 ## Provider support & API keys
 
@@ -93,21 +100,35 @@ Each profile is registered in `src/config.ts`. Add new profiles via `registerAge
 | `deepseek`  | `deepseek-reasoner`, `deepseek-chat` | `DEEPSEEK_API_KEY` | `/model → DeepSeek` |
 | `xai`       | `grok-4`, `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`, `grok-code-fast-1` | `XAI_API_KEY` | `/model → xAI` |
 | `google`    | `gemini-2.5-pro`, `gemini-2.5-flash` | `GEMINI_API_KEY` | `/model → Google Gemini` |
-| `tavily`    | `tavily_search`, `tavily_extract` tools | `TAVILY_API_KEY` | Enable via `/tools` |
 
 Secrets are read from environment variables first, then from `~/.codex/secrets.json`. Use `/secrets` to manage them interactively.
 
 ## Built-in tools & capability suites
 
-The CLI composes tools via `CapabilityModule`s. The default Node runtime registers:
+The CLI composes tools via `CapabilityModule`s. The canonical suite metadata lives in `src/contracts/tools.schema.json`, so editing that schema updates every runtime without touching multiple files. The default Node runtime now registers a single purpose-built coding toolkit and no longer bundles non-coding Office or web research capabilities. See `docs/CODING_CAPABILITIES.md` for deep dives into each command.
+
+Tool invocations are narrated via the interactive shell (`Read(src/api.ts)`, `Bash(npm test)`). Warnings surface when tools are disabled or missing secrets so you can remediate without rerunning the CLI.
+
+### Coding tool families
 
+**Core workspace control**
 - **Filesystem suite (`filesystemCapability.ts`)** – `read_file`, `write_file` (with diff previews), `list_files`, `search_files`. Uses deterministic ignore lists and protects against accidental binary writes.
-- **Search suite (`searchCapability.ts`)** – `grep_search`, `find_definition` over repo text. Regex friendly, case sensitive toggle, built-in binary detection.
-- **Bash suite (`bashCapability.ts`)** – `execute_bash` runs commands inside a sandbox rooted at `<workspace>/.erosolar/shell-sandbox`. HOME/TMP/XDG paths are rewritten unless `EROSOLAR_PRESERVE_HOME=1` is set. Streaming mode placeholder exists (`execute_bash_stream`).
-- **Tavily suite (`tavilyCapability.ts`)** – opt-in live web search/extract. Requires `TAVILY_API_KEY` and the `/tools` toggle.
-- **Runtime metadata tools (`core/toolRuntime.ts`)** – `context_snapshot`, `capabilities_overview`, `profile_details` for deterministic context recall.
+- **Search suite (`searchCapability.ts`)** – `grep_search`, `find_definition`, and keyword-aware scanners over repo text. Regex friendly with case sensitivity toggles and automatic binary detection.
+- **Bash suite (`bashCapability.ts`)** – `execute_bash` runs commands inside a sandbox rooted at `<workspace>/.erosolar/shell-sandbox`. HOME/TMP/XDG paths are rewritten unless `EROSOLAR_PRESERVE_HOME=1` is set.
 
-Tool invocations are narrated via the interactive shell (`Read(src/api.ts)`, `Bash(npm test)`). Warnings surface when tools are disabled or missing secrets so you can remediate without rerunning the CLI.
+**Delivery & validation loops**
+- **Repo checks suite (`repoChecksCapability.ts`)** – `run_repo_checks` wraps `npm test`/`npm run build`/`npm run lint` (when present) inside the sandbox and powers the `/checks` shortcut for one-command validation.
+- **Development workflow suite (`devCapability.ts`)** – `run_tests`, `install_dependencies`, `check_package_info`, and `run_build` encapsulate local package/test/build operations with timeout handling and script detection.
+- **Testing & coverage suite (`testingCapability.ts`)** – test plan scaffolding, coverage orchestration, and sanity checks for the local test harness.
+
+**Code intelligence & quality**
+- **Code analysis suite (`codeAnalysisCapability.ts`)** – `analyze_code_structure`, `find_dependencies`, and `check_code_complexity` provide AST-backed insight into any TS/JS file.
+- **Code quality suite (`codeQualityCapability.ts`)** – `run_lint_checks`, `inspect_code_quality`, `list_lint_rules` surface lint health, TODO hotspots, and maintainability metrics.
+- **Refactoring suite (`refactoringCapability.ts`)** – `detect_refactoring_hotspots`, `generate_refactor_plan`, `analyze_refactor_impact` use AST data plus call graphs to map risky symbols before editing.
+
+**Dependency & runtime awareness**
+- **Dependency security suite (`dependencySecurityCapability.ts`)** – dependency summaries, advisories, `npm audit` execution, and lockfile inspections to catch supply-chain issues.
+- **Runtime metadata tools (`core/toolRuntime.ts`)** – `context_snapshot`, `capabilities_overview`, `profile_details` provide deterministic context recall for every session.
 
 ## Workspace context & prompts
 
@@ -115,31 +136,26 @@ On launch, `buildWorkspaceContext()` (see `src/workspace.ts`) captures:
 
 1. The current working directory path.
 2. A trimmed file tree (depth 2, up to 200 entries, ignoring `.git`, `node_modules`, `dist`).
-3. Contents/snippets of `README.md`, `SOURCE_OF_TRUTH.json`, `ARCHITECTURE.json`, and `package.json` when present.
+3. Contents/snippets of `README.md`, `package.json`, and formatted rulebook prompts derived from every `agents/*.rules.json` manifest.
 
 The snapshot is appended to the active system prompt and exposed via the `context_snapshot` tool so the agent always has a deterministic view of the repo even before reading files manually.
 
-## Architectural overview
+Need more context? Override the capture depth/excerpt ahead of launch with:
 
-```
-┌────────────┐   ┌────────────────┐   ┌─────────────┐   ┌──────────────┐
-│ Interactive│→→│ AgentSession    │→→│ AgentRuntime │→→│ Provider SDK  │
-│ Shell      │   │ (profile/model │   │ (conversation│   │ (OpenAI, etc.)│
-│ (/model…)  │   │  resolution)   │   │  loop + tools)│   │              │
-└────┬───────┘   └────────┬───────┘   └──────┬──────┘   └──────┬───────┘
-     │ Workspace context        │ ToolRuntime/logging     │
-     ▼                         ▼                         ▼
-  Capability modules (filesystem/search/bash/Tavily/…) loaded via AgentHost/RuntimeAdapter
-```
+- `EROSOLAR_CONTEXT_TREE_DEPTH` – max folder depth for the file tree.
+- `EROSOLAR_CONTEXT_MAX_ENTRIES` – cap on total tree entries.
+- `EROSOLAR_CONTEXT_DOC_LIMIT` – max characters captured from the priority documents.
+
+During a session you can run `/context` to recapture the snapshot without restarting the CLI. Optional arguments allow deeper crawls or larger excerpts mid-session, e.g. `/context depth=4 excerpt=4000 entries=400`.
+
+### Agent rulebooks
 
-- **Interactive shell (`src/shell/interactiveShell.ts`)** renders prompts, manages slash commands, handles bracketed paste, streams assistant tokens, and persists preferences.
-- **AgentHost (`src/runtime/agentHost.ts`)** loads capability modules and resolves tool suites before the session starts.
-- **CapabilityModule interface** describes any pluggable feature: return tool suites, metadata, and teardown logic. Modules can be registered by adapters, plugins, or downstream apps.
-- **RuntimeAdapter (`src/adapters/types.ts`)** creates modules for specific targets (Node CLI, browser sandbox, server worker). The Node adapter wires in filesystem/search/bash/Tavily plugins.
-- **AgentSession (`src/runtime/agentSession.ts`)** resolves the profile config, builds the tool runtime, and instantiates providers.
-- **AgentRuntime (`src/core/agent.ts`)** runs the LLM loop, interleaving provider calls and tool execution.
+Each profile loads its prompts, guardrails, and phase/step rules from `agents/<profile>.rules.json`. The manifests follow `src/contracts/schemas/agent-rules.schema.json`, so you can add new phases, rules, or metadata programmatically without editing TypeScript. The old `Agents.md` doc has been removed; cite these manifests (and their rule IDs) when referencing canonical instructions.
 
-Thanks to this separation, you can reuse the runtime in Electron apps, remote agents, or serverless workers without rewriting orchestration.
+- `agents/general.rules.json` — balanced Erosolar rulebook governing research/planning/writing tasks.
+- `agents/erosolar-code.rules.json` — deterministic coding rulebook that enforces the narrate-plan-edit-validate-report workflow.
+
+The workspace snapshot automatically captures the formatted prompts derived from these JSON files, so the active agent (and any downstream orchestrator) cites the same instructions. After editing a rulebook, rebuild or restart the CLI to reload it.
 
 ## Extending the CLI
 
@@ -198,25 +214,45 @@ Expose it through `/model` by adding presets in `src/shell/interactiveShell.ts`.
 
 ### Add an agent profile
 
+Prefer editing `src/contracts/agent-profiles.schema.json` so every runtime reads the same defaults. For ad-hoc registrations, include the system prompt definition and a rulebook reference so workspace snapshots stay aligned:
+
 ```ts
 import { registerAgentProfile } from 'erosolar-cli/core/agentProfiles.js';
+
 registerAgentProfile({
   name: 'docs',
   label: 'Docs Agent',
   description: 'Summaries only',
   defaultProvider: 'openai',
   defaultModel: 'gpt-5-mini',
+  systemPromptConfig: { type: 'literal', content: 'Only answer with documentation.' },
   defaultSystemPrompt: 'Only answer with documentation.',
+  rulebook: {
+    file: 'agents/docs.rules.json',
+    version: 'dev-local',
+    contractVersion: '1.0.0',
+    description: 'Docs-only guardrails.',
+  },
+  manifestVersion: 'dev-local',
+  manifestContractVersion: '1.0.0',
 });
 ```
 
+## Contract schemas
+
+The CLI now exports machine readable contracts so other runtimes can preload the same guardrails and tool toggles without scraping prompts.
+
+- **Agent profiles** – `src/contracts/v1/agentProfileManifest.ts` plus `src/contracts/schemas/agent-profile.schema.json` define default providers/models, prompt templates, and rulebook bindings (see `src/contracts/agent-profiles.schema.json` for the live manifest).
+- **Agent rules** – `src/contracts/v1/agentRules.ts` plus `src/contracts/schemas/agent-rules.schema.json` describe multi-phase workflows. Encode per-phase steps, required evidence, nested sub-steps, and severity tagged rules so an orchestrator can enforce behavior before the model ever sees a prompt.
+- **Tool selection** – `src/contracts/v1/toolAccess.ts` plus `src/contracts/schemas/tool-selection.schema.json` enumerate every toggleable tool suite along with permission scopes, required secrets, and optional presets. UI layers can read this manifest to decide which suites are surfaced or locked for a profile.
+
 ## Configuration reference
 
 - `EROSOLAR_PROFILE` – boot this profile unless `--profile` overrides it.
 - `<PROFILE>_MODEL`, `<PROFILE>_PROVIDER`, `<PROFILE>_SYSTEM_PROMPT` – lock a profile to custom defaults. Examples: `GENERAL_MODEL=claude-sonnet-4.5`, `EROSOLAR_CODE_SYSTEM_PROMPT="..."`.
 - `EROSOLAR_PRESERVE_HOME=1` – skip rewriting `$HOME`/`XDG_*` paths when running bash commands.
 - `CODEX_HOME` – change where CLI secrets are stored (defaults to `~/.codex`).
-- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`, `GEMINI_API_KEY`, `TAVILY_API_KEY` – provider credentials.
+- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`, `GEMINI_API_KEY` – provider credentials.
 - `GENERAL_MODEL`, `EROSOLAR_CODE_MODEL` – shorthand for the two built-in profiles.
 - `PATH`, `TMPDIR`, etc. – inherited by bash tools after sandboxing.
 
@@ -228,7 +264,7 @@ User preferences (model presets, enabled tools, saved profile) live in `~/.eroso
 git clone https://github.com/bo/bo-cli.git
 cd bo-cli
 npm install
-npm run dev        # ts-node/tsx entry for iterating without building
+npm run dev        # ts-node loader entry for iterating without building
 npm run build      # clean + tsc compile to dist/
 npm run start      # run the compiled CLI
 npm run clean      # remove dist/
@@ -239,25 +275,25 @@ Notes:
 - The repo uses strict ES modules and TypeScript 5.3+.
 - `dist/bin/erosolar.js` must stay executable; `npm run postbuild` sets `chmod 755`.
 - Keep new files ASCII by default; use comments sparingly (see `apply_patch` guidelines in this repo).
-- `ARCHITECTURE.json`, `MODULAR_RUNTIME.md`, and `Agents.md` document the same defaults—update them if you change prompts or modules.
+- Keep the JSON rulebooks under `agents/` aligned with `src/contracts/schemas/agent-rules.schema.json` whenever you change prompts or modules—the CLI loads them directly at runtime.
 
 ## Release & publishing checklist
 
-1. Update docs/metadata (README, `package.json` description, architectural JSON files if needed).
+1. Update docs/metadata (README, `agents/*.rules.json`, the agent-rules schema when structure changes, and the `package.json` description).
 2. Run `npm run build` to refresh `dist/`.
-3. Inspect the diff and run any smoke tests (e.g., `npx tsx src/bin/erosolar.ts --version`).
+3. Inspect the diff and run any smoke tests (e.g., `node --loader ts-node/esm src/bin/erosolar.ts --version`).
 4. Bump the version: `npm version patch` (or `minor`/`major`) to keep npm in sync.
 5. Publish: `npm publish`.
 6. Verify on npmjs.com that the README renders and the new version lists the correct files.
 
-The `files` array in `package.json` already limits what goes to npm (`dist`, README, docs JSON, license, preinstall script).
+The `files` array in `package.json` already limits what goes to npm (`dist`, README, agents/, license, helper scripts).
 
 ## Repository layout
 
 - `src/bin/erosolar.ts` – CLI entrypoint.
 - `src/shell/` – interactive shell UX, slash commands, tool logging.
 - `src/runtime/` – AgentHost, AgentSession, adapters.
-- `src/capabilities/` & `src/tools/` – filesystem/search/bash/Tavily implementations.
+- `src/capabilities/` & `src/tools/` – filesystem/search/bash/coding capability implementations.
 - `src/plugins/` – provider + tool plugin registries.
 - `src/providers/` – LLM client shims (OpenAI Responses, Chat Completions, etc.).
 - `src/core/` – agent runtime, tool runtime, preferences, secrets.

package/agents/erosolar-code.rules.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "../src/contracts/schemas/agent-rules.schema.json",
+  "contractVersion": "1.0.0",
+  "profile": "erosolar-code",
+  "version": "2024-11-24",
+  "label": "Erosolar Code Rulebook",
+  "description": "Rules for the OpenAI-backed coding specialist optimized for fast, deterministic edits.",
+  "globalPrinciples": [
+    {
+      "id": "guardrail.snapshot_lock",
+      "summary": "Require a workspace snapshot + repo tree before editing; request a refresh if files are missing.",
+      "severity": "critical"
+    },
+    {
+      "id": "guardrail.rulebook_visibility",
+      "summary": "Reference this rulebook when explaining constraints or blocked actions so humans can audit decisions.",
+      "severity": "required",
+      "references": [
+        { "label": "Code Rulebook", "file": "agents/erosolar-code.rules.json" }
+      ]
+    },
+    {
+      "id": "guardrail.workspace_grounding",
+      "summary": "Quote exact files + line numbers from the repo snapshot instead of free-form speculation.",
+      "severity": "critical",
+      "references": [
+        { "label": "README", "file": "README.md" },
+        { "label": "package.json", "file": "package.json" }
+      ]
+    },
+    {
+      "id": "guardrail.tool_transparency",
+      "summary": "Narrate intent before running tools/commands and summarize output afterward.",
+      "severity": "required"
+    },
+    {
+      "id": "guardrail.manual_loop_supervision",
+      "summary": "Stop if you lack evidence—surface blockers instead of guessing or editing blindly.",
+      "severity": "required"
+    }
+  ],
+  "phases": [
+    {
+      "id": "phase.analysis",
+      "label": "Analysis",
+      "description": "Understand the bug/feature request and locate source material.",
+      "steps": [
+        {
+          "id": "step.read_scope",
+          "title": "Inspect current behavior",
+          "intent": "Use read/search commands to locate relevant files.",
+          "rules": [
+            {
+              "id": "rule.analysis.files",
+              "summary": "List important files and cite their paths/lines before suggesting changes.",
+              "severity": "required"
+            },
+            {
+              "id": "rule.analysis.dependencies",
+              "summary": "Check package.json scripts/dependencies for signals about tooling or frameworks.",
+              "severity": "recommended",
+              "references": [
+                { "label": "package scripts", "file": "package.json" }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "phase.planning",
+      "label": "Plan",
+      "description": "Lay out the editing strategy and validation path.",
+      "steps": [
+        {
+          "id": "step.plan_diff",
+          "title": "Describe intended diff",
+          "intent": "Summarize the minimal set of files + code blocks that will change.",
+          "rules": [
+            {
+              "id": "rule.plan.narrate",
+              "summary": "Explain each edit before writing code; group steps logically.",
+              "severity": "required"
+            },
+            {
+              "id": "rule.plan.tests",
+              "summary": "Call out npm/yarn/pnpm scripts or manual validation steps that prove success.",
+              "severity": "required"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "phase.implementation",
+      "label": "Implementation",
+      "description": "Perform tightly scoped edits while maintaining reversible changes.",
+      "steps": [
+        {
+          "id": "step.edit_code",
+          "title": "Modify files",
+          "intent": "Apply the planned diff, keeping commits small and well explained.",
+          "rules": [
+            {
+              "id": "rule.implementation.atomic",
+              "summary": "Edit one concern at a time; avoid sweeping refactors unless explicitly requested.",
+              "severity": "required"
+            },
+            {
+              "id": "rule.implementation.confirm",
+              "summary": "Re-open edited files or rerun explain tools to confirm the change matches the plan.",
+              "severity": "required"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "phase.validation",
+      "label": "Validation",
+      "description": "Run or describe checks that prove the change works.",
+      "steps": [
+        {
+          "id": "step.validate_code",
+          "title": "Execute tests",
+          "intent": "Prefer automated scripts/test suites; otherwise supply manual verification steps.",
+          "rules": [
+            {
+              "id": "rule.validation.repo_checks",
+              "summary": "Run `run_repo_checks`, `npm test`, `npm run build`, or equivalent when the change touches code paths with coverage.",
+              "severity": "required"
+            },
+            {
+              "id": "rule.validation.explain_gap",
+              "summary": "If a check cannot be run (time, dependencies), explain the gap and how to verify later.",
+              "severity": "required"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "phase.reporting",
+      "label": "Reporting",
+      "description": "Summarize edits, cite evidence, and highlight follow-ups.",
+      "steps": [
+        {
+          "id": "step.report_code",
+          "title": "Summarize outcome",
+          "intent": "Describe the diff, tests executed, and remaining risks.",
+          "rules": [
+            {
+              "id": "rule.reporting.delta",
+              "summary": "List files changed with brief rationale and reference code blocks/line numbers.",
+              "severity": "required"
+            },
+            {
+              "id": "rule.reporting.next",
+              "summary": "Document follow-up tasks, validation still needed, and any environment assumptions.",
+              "severity": "recommended"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/agents/general.rules.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "../src/contracts/schemas/agent-rules.schema.json",
+  "contractVersion": "1.0.0",
+  "profile": "general",
+  "version": "2024-11-24",
+  "label": "Erosolar General Agent Rulebook",
+  "description": "Structured rules that govern the general-purpose Erosolar operator across research, planning, writing, and coding requests.",
+  "globalPrinciples": [
+    {
+      "id": "guardrail.snapshot_lock",
+      "summary": "Do not proceed without a current workspace snapshot and captured context.",
+      "detail": "If the snapshot omits files the user mentions, pause and request a fresh capture before proposing changes.",
+      "severity": "critical",
+      "references": [
+        { "label": "README", "file": "README.md" }
+      ]
+    },
+    {
+      "id": "guardrail.rulebook_visibility",
+      "summary": "Always cite this rulebook and the workspace capture as the canonical instructions.",
+      "detail": "Responses should reference the ruleset name/version when clarifying constraints so humans can audit compliance.",
+      "severity": "required",
+      "evidenceRequired": "Mention rule or phase identifiers when explaining blocked actions.",
+      "references": [
+        { "label": "General Rulebook", "file": "agents/general.rules.json" }
+      ]
+    },
+    {
+      "id": "guardrail.metadata_only_tools",
+      "summary": "Registered tools expose metadata only; never assume hidden side effects.",
+      "detail": "Keep tool usage auditable by narrating the intent before running them and summarizing their output afterward.",
+      "severity": "required"
+    },
+    {
+      "id": "guardrail.manual_loop_supervision",
+      "summary": "Humans supervise the loop manually—escalate when you lack evidence or stall.",
+      "detail": "If progress stops after two iterations without new data, surface blockers rather than guessing.",
+      "severity": "required"
+    },
+    {
+      "id": "guardrail.workspace_grounding",
+      "summary": "Ground every claim in files, commands, or captured facts; cite file paths + line numbers when possible.",
+      "detail": "When evidence is missing, explicitly request it instead of hallucinating.",
+      "severity": "critical",
+      "references": [
+        { "label": "README", "file": "README.md" },
+        { "label": "package.json", "file": "package.json" }
+      ]
+    }
+  ],
+  "phases": [
+    {
+      "id": "phase.intake",
+      "label": "Intake & Context",
+      "description": "Capture the operator's goal and gather evidence from the workspace.",
+      "steps": [
+        {
+          "id": "step.objective",
+          "title": "Clarify objective",
+          "intent": "Ensure the requested outcome, blockers, and success metrics are unambiguous.",
+          "rules": [
+            {
+              "id": "rule.objective.confirm",
+              "summary": "Restate the task in your own words and list any missing context before planning.",
+              "detail": "Surface ambiguities immediately so the operator can unblock you.",
+              "severity": "required"
+            }
+          ]
+        },
+        {
+          "id": "step.context",
+          "title": "Gather evidence",
+          "intent": "Pull facts from README.md, package.json, and relevant files before proposing solutions.",
+          "rules": [
+            {
+              "id": "rule.context.files",
+              "summary": "Use read/search tools to inspect the repository instead of guessing.",
+              "severity": "required",
+              "toolHints": ["read_file", "list_files", "grep_search"]
+            },
+            {
+              "id": "rule.context.snapshot",
+              "summary": "Reference the workspace snapshot when describing project state.",
+              "severity": "recommended"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "phase.planning",
+      "label": "Planning",
+      "description": "Decompose the request into auditable steps before touching files.",
+      "steps": [
+        {
+          "id": "step.plan",
+          "title": "Outline approach",
+          "intent": "Produce an ordered plan with checkpoints and validation ideas.",
+          "rules": [
+            {
+              "id": "rule.plan.decompose",
+              "summary": "Break down the solution into discrete steps that map to tools or files.",
+              "severity": "required"
+            },
+            {
+              "id": "rule.plan.tests",
+              "summary": "Identify relevant commands/tests from package.json or docs that prove success.",
+              "severity": "recommended",
+              "references": [
+                { "label": "package scripts", "file": "package.json" }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "phase.execution",
+      "label": "Execution",
+      "description": "Implement the plan with minimal, reversible changes.",
+      "steps": [
+        {
+          "id": "step.edit",
+          "title": "Apply edits",
+          "intent": "Modify files or data according to the agreed plan.",
+          "rules": [
+            {
+              "id": "rule.edit.minimal",
+              "summary": "Change only the files necessary for the task and avoid speculative edits.",
+              "severity": "required"
+            },
+            {
+              "id": "rule.edit.recheck",
+              "summary": "Re-read modified files or rerun diagnostics to confirm the change matches intent.",
+              "severity": "required"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "phase.validation",
+      "label": "Validation",
+      "description": "Verify the results and surface risks before handoff.",
+      "steps": [
+        {
+          "id": "step.validate",
+          "title": "Run checks",
+          "intent": "Use available scripts/tests or provide manual validation instructions.",
+          "rules": [
+            {
+              "id": "rule.validate.commands",
+              "summary": "Run npm scripts, tests, or linters when feasible; otherwise explain why not.",
+              "severity": "required",
+              "references": [
+                { "label": "package scripts", "file": "package.json" }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "phase.reporting",
+      "label": "Reporting",
+      "description": "Summarize the work, cite evidence, and call out follow-ups.",
+      "steps": [
+        {
+          "id": "step.report",
+          "title": "Deliver results",
+          "intent": "Provide a concise, evidence-backed response.",
+          "rules": [
+            {
+              "id": "rule.report.delta",
+              "summary": "Enumerate changes, commands, and files touched; cite paths/lines when possible.",
+              "severity": "required"
+            },
+            {
+              "id": "rule.report.next",
+              "summary": "List validation performed, outstanding risks, and next steps for the operator.",
+              "severity": "recommended"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/adapters/browser/index.d.ts

@@ -0,0 +1,12 @@
+import type { CapabilityModule } from '../../runtime/agentHost.js';
+import type { RuntimeAdapter, RuntimeAdapterContext } from '../types.js';
+export interface BrowserAdapterOptions {
+    modules?: CapabilityModule[];
+}
+export declare class BrowserRuntimeAdapter implements RuntimeAdapter {
+    readonly id = "runtime.browser";
+    private readonly options;
+    constructor(options?: BrowserAdapterOptions);
+    createCapabilityModules(_: RuntimeAdapterContext): Promise<CapabilityModule[]>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzE,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,QAAQ,CAAC,EAAE,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAEpC,OAAO,GAAE,qBAA0B;IAIzC,uBAAuB,CAAC,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAGrF"}

package/dist/adapters/browser/index.js

@@ -8,3 +8,4 @@ export class BrowserRuntimeAdapter {
         return [...(this.options.modules ?? [])];
     }
 }
+//# sourceMappingURL=index.js.map

package/dist/adapters/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/browser/index.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,qBAAqB;IACvB,EAAE,GAAG,iBAAiB,CAAC;IACf,OAAO,CAAwB;IAEhD,YAAY,UAAiC,EAAE;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,uBAAuB,CAAC,CAAwB;QACpD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC;CACF"}