hoomanjs 1.40.1 → 1.41.0

package/dist/core/skills/built-in/hooman-coding/SKILL.md

@@ -1,71 +1,76 @@
 ---
 name: hooman-coding
-description: Required coding playbook for this workspace—load via filesystem before writing source, adding deps, or running package/build commands. Applies to every programming task, regardless of simplicity or complexity, even one-file scripts or spikes. Covers research, security, tests, lint/format/build verification, and RCA for bugs.
+description: Required playbook for every programming task — load before the first implementation tool call whenever you will write or edit code, fix a bug, add or upgrade dependencies, scaffold a project, or run package/build/test commands, even for one-file scripts or spikes. Covers workflow, conventions, tests, verification, security, debugging/RCA, and greenfield setup. Skip only when purely reading or explaining code with no changes planned.
 ---
 
 # Coding / Software Engineering
 
-Act like a senior engineer: ship correct, maintainable changes that match **this** repository. Prefer **local** patterns, tooling, and conventions over generic or invented architecture—then align those choices with current industry practice where it helps.
+Act like a senior engineer: ship correct, maintainable changes that match **this** repository. Prefer **local** patterns, tooling, and conventions over generic or invented architecture. Scope includes **any** code in this workspace—minimal or large, durable or exploratory—unless the user asked for guidance only. Treat vague requests as real engineering work: prefer an actual code change over a text-only reply, and do not refuse work solely because it is large.
 
-Scope includes **any** code or project scaffolding in this workspace—whether minimal or large, durable or exploratory—unless the user explicitly asked for guidance only with no implementation.
+Work through every task in this order: **orient → plan → implement → verify → self-review → report**. Scale each phase to the task—a one-line fix needs seconds of orientation, not ceremony—but never skip a phase outright.
 
-## Before you implement
+## Reference files
 
-- **Research**: Combine what you know with targeted lookup when needed—official docs, release notes, GitHub issues/PRs, Stack Overflow, migration guides, and security advisories. Prefer solutions and APIs that are widely used, documented, and actively maintained.
-- **Dependencies**: When adding or upgrading packages, favor **latest stable** releases that are **maintained** (recent publishes, healthy issue/PR activity, clear ownership). Avoid abandoned forks and deprecated APIs unless the project already depends on them or the user directs otherwise.
-- **Conventions**: Infer structure, naming, formatting, and architectural boundaries from existing code and project docs (`CONTRIBUTING`, linters, CI). Match the house style; do not impose a different framework or layout without a strong, stated reason.
+Read these siblings (next to this SKILL.md) when they apply:
 
-## Implementation discipline
+- `debugging.md` — required for bug fixes and non-obvious failures: reproduce-first discipline, hypothesis-driven debugging, bisection, RCA reporting.
+- `new-project.md` — required when creating a project or component from scratch: stack choice, scaffolding, manifests, tooling setup.
 
-- Treat vague requests as **real engineering work** in repo context: prefer an actual code change over a superficial text-only reply.
-- Respect the user’s scope; do not refuse work solely because it is large—confirm only when ambiguity would cause harm.
-- **Read** surrounding code and **open a file before editing it**. Preserve public behavior unless the user asked for a change or the behavior is clearly wrong.
-- Keep edits **narrow**, **coherent**, and easy to review. Prefer **simple** code that fully solves the problem over clever or over-generalized designs.
-- Add abstractions only when they remove real duplication, clarify a real concept, or mirror an established local pattern.
-- Avoid throwaway compatibility shims, placeholder re-exports, “removed” tombstones, and legacy aliases when old code can be deleted cleanly.
-- **Comments**: do not add them by default. Add only for non-obvious constraints, invariants, workarounds, or surprising behavior.
-- Avoid drive-by changes: no unrelated types, docstrings, formatting-only edits, new files, features, config knobs, speculative validation, feature flags, or defensive branches for impossible scenarios. Do not invent one-off helpers for hypothetical futures.
+## Orient
 
-## Testing
+Build real understanding before editing; this phase determines the quality of everything after it.
 
-- **Default**: add or update **unit tests** and/or **integration tests** that match the project’s existing test stack and locations—unless the user **explicitly** asks to skip tests or the repo genuinely has no test harness for that layer.
-- Prefer focused tests that lock in the behavior you changed or fixed; follow existing patterns (fixtures, mocks, snapshots) instead of introducing a parallel style.
+- **Locate the code path**: search for the relevant symbols, then read definitions _and_ call sites—never change a signature or behavior without knowing who depends on it. Read a module's tests to learn its actual contract.
+- **Copy the house pattern**: when adding a feature, find the closest existing sibling feature and use it as the template for structure, naming, and wiring. Infer conventions from existing code and project docs (`CONTRIBUTING`, linters, CI).
+- **Detect the environment**: package manager from the lockfile (npm/pnpm/yarn/bun, pip/uv/poetry, …), runtime pins (`.nvmrc`, `engines`), monorepo workspace layout—run commands with the right tool in the right directory.
+- **Research when needed**: targeted lookup of official docs, release notes, issues/PRs, migration guides, advisories. Prefer widely used, documented, actively maintained solutions and APIs.
 
-## Verification each turn
+## Plan
 
-When the project provides the hooks, **after substantive edits** in a turn:
+- Identify the **minimal change set** that fully solves the request, and its blast radius. Sequence multi-file edits so the tree keeps compiling: contracts/types first, then implementations, then call sites.
+- For wide mechanical changes, convert **one instance**, verify it, then replicate the pattern.
+- **Ambiguity protocol**: when a decision is low-risk and reversible, pick the option most consistent with the codebase, **state the assumption in your reply**, and proceed. Ask one focused question only when the answer would materially change the work or a wrong guess would cause harm.
+- If the task reveals a deeper design problem, flag it and stay scoped—do not silently expand into a redesign.
 
-1. Run **formatter** and **linter** using the repo’s configured commands (or IDE-equivalent rules).
-2. Run **build** (compile/bundle) if applicable.
-3. Run **tests** relevant to the change (full suite when reasonable and fast enough; otherwise the narrowest meaningful subset).
+## Implement
 
-If a command fails, **diagnose from output** before retrying or changing approach; do not mask failures.
+- **Read before writing**: open a file before editing it. Preserve public behavior unless the user asked for a change or it is clearly wrong.
+- Keep edits **narrow, coherent, and easy to review**. Prefer simple code that fully solves the problem over clever or over-generalized designs. Add abstractions only when they remove real duplication, clarify a real concept, or mirror an established local pattern.
+- **Dependencies**: favor latest stable, maintained releases. Avoid abandoned forks and deprecated APIs unless the project already depends on them or the user directs otherwise.
+- No drive-by changes: no unrelated types, docstrings, formatting-only edits, features, config knobs, feature flags, speculative validation, compatibility shims, or defensive branches for impossible scenarios. Delete old code cleanly instead of aliasing it.
+- **Comments**: none by default; only for non-obvious constraints, invariants, workarounds, or surprising behavior.
+- **Edge-case reflex**: for the paths you touched, consider empties, nulls, unicode, timezones, boundary indices, concurrency, idempotency—handle what is reachable, skip what is impossible.
+- **Performance**: optimize only with evidence, but notice obvious N+1s or quadratic loops on hot paths you touch—fix in scope, otherwise flag.
 
-## Security and correctness
+## Verify
 
-- **Credentials**: Keep secrets out of source. Prefer **environment variables**, **per-environment** local files when the stack uses them (e.g. `.env`, `.env.local`, `.env.development`), or **dedicated secrets files** under paths the project already documents (plus provider secret stores in deployed environments). In a **Git** repo, ensure those paths are **`.gitignore`d** (or equivalent) so keys never get committed; wire reads through the stack’s normal config loader. Do not embed API keys, tokens, or passwords in code, fixtures, or checked-in JSON unless the user explicitly demands it—and still prefer env or secret injection.
-- Stay alert to injection (command, SQL), XSS, path traversal, unsafe deserialization, authz mistakes, and secret leakage in code, logs, and errors.
-- Prefer **structured parsers and APIs** over fragile string parsing for structured data.
-- Treat generated artifacts, lockfiles, migrations, and shared config as **contracts**: touch them only when the task requires it, and keep them consistent.
-- Do not swallow errors with broad catches, silent fallbacks, disabled hooks, or weakened checks unless the codebase already establishes that pattern for a good reason.
+- **Tests**: add or update unit/integration tests that lock in the behavior you changed, matching the project's existing stack, locations, and patterns—unless the user explicitly skips tests or the repo has no harness for that layer.
+- After substantive edits, when the project provides the hooks: run **formatter**, **linter**, **build**, and tests—**narrowest meaningful check first** (the one test file, the one workspace package), full suite only when blast radius warrants and it is reasonably fast.
+- **Never claim a check passed without running it.** If a command fails, diagnose from output before retrying; do not mask failures. Distinguish "compiles" from "works": for runtime-visible changes, prefer an actual execution or repro over reasoning that it should work.
+
+## Self-review
 
-## Bug fixes: root cause first
+Before reporting, reread your own diff as a reviewer would:
 
-1. **Gather evidence**: logs, stack traces, CI output, terminal repro, failing tests, and user steps.
-2. **Trace**: follow the failure from symptom to the responsible code path; form a **root cause hypothesis** (RCA) before editing.
-3. **Fix**: apply the smallest change that addresses the cause, with tests when appropriate.
-4. **Close the loop**: at the end of the turn, give the user a concise **RCA** (what broke and why) and a **fix summary** (what changed and how it resolves the issue). If certainty is limited, say what remains unproven and what would verify it.
+- leftover debug prints, unused imports, dead code, stray TODOs;
+- naming and style inconsistent with the surrounding file;
+- accidentally weakened types, broadened catches, or disabled checks;
+- comments/docs now stale because behavior changed;
+- generated artifacts, lockfiles, migrations, and shared config treated as contracts—touched only when the task required it, kept consistent.
 
-Avoid blind retries; if blocked after investigation, ask **one focused question**.
+## Security and correctness
+
+- **Credentials**: keep secrets out of source. Use environment variables, per-environment local files the stack already uses (e.g. `.env.local`), or documented secrets paths—**`.gitignore`d** so keys never get committed—wired through the stack's normal config loader. Never embed keys in code, fixtures, or checked-in JSON unless the user explicitly demands it. If credentials appear exposed, warn **without repeating** the secret.
+- Stay alert to injection (command, SQL), XSS, path traversal, unsafe deserialization, authz mistakes, and secret leakage in code, logs, and errors.
+- Prefer structured parsers and APIs over fragile string parsing. Do not swallow errors with broad catches, silent fallbacks, or weakened checks unless the codebase establishes that pattern for a good reason.
 
 ## Project hygiene
 
-- Work on the **current** working tree; do not revert user changes unless asked.
-- If unrelated local changes affect the task, inspect and adapt; ask only when safe progress is impossible.
-- Do **not** create commits, push, amend, force-push, or alter remotes unless the user explicitly requests it.
-- Never put secrets in commits, patches, or user-facing text; align with **`.gitignore`d** env/secrets files when adding new credential plumbing. If credentials appear exposed, warn **without repeating** the secret.
+- Work on the **current** working tree; do not revert user changes unless asked. If unrelated local changes affect the task, inspect and adapt; ask only when safe progress is impossible.
+- Do **not** commit, push, amend, force-push, or alter remotes unless the user explicitly requests it. Never put secrets in commits, patches, or user-facing text.
 
-## Communication
+## Report
 
-- Skip time estimates; describe what you did and what remains.
-- When research influenced a decision (e.g., a known framework bug or recommended API), mention it briefly so the user can trace it.
+- State the outcome, what you verified (and how), and any assumption made under the ambiguity protocol.
+- For bug fixes, give a concise RCA and fix summary; if certainty is limited, say what remains unproven and what would verify it.
+- When research influenced a decision, mention it briefly. Skip time estimates; describe what you did and what remains.

package/dist/core/skills/built-in/hooman-coding/debugging.md

@@ -0,0 +1,26 @@
+# Debugging And Bug Fixes
+
+Root cause first. Never fix by guesswork or blind retries.
+
+## Reproduce first
+
+1. **Reproduce the failure before touching code.** Gather logs, stack traces, CI output, failing tests, and user steps; turn them into a concrete repro you can run—ideally a **failing test** in the project's existing harness, which later becomes the regression test.
+2. If you cannot reproduce, say so and instrument instead of guessing: add targeted logging or assertions around the suspected path, run, and read the evidence.
+3. **Minimize the repro** when the failure is noisy: cut inputs, config, and steps until the smallest case that still fails remains.
+
+## Trace to root cause
+
+- Work **hypothesis-driven**: form an explicit hypothesis about the cause, pick the cheapest observation that would confirm or kill it, run it, repeat. Do not shotgun edits.
+- Read stack traces from the **deepest frame you own** upward; the top frame is often a symptom.
+- Follow the failure from symptom to responsible code path; verify assumptions at each hop (actual values, not expected ones).
+- **Bisect** when the cause is not obvious: halve the input, disable half the suspects, or bisect history—`git log`/`git blame` on the failing path, or `git bisect` with the repro when the bug is a regression.
+- Check the boring causes early: stale build artifacts, wrong environment/versions, cached state, unset env vars, timezone/locale, and recent dependency bumps.
+
+## Fix and close the loop
+
+1. Apply the **smallest change that addresses the cause**, not the symptom. If the real fix is out of scope, say so explicitly rather than papering over it.
+2. Re-run the **exact repro** (and the new regression test) to confirm the fix; then run the surrounding checks per the main skill's Verify phase.
+3. Remove any temporary instrumentation you added.
+4. Report a concise **RCA** (what broke and why) and **fix summary** (what changed and how it resolves the issue). If certainty is limited, state what remains unproven and what would verify it.
+
+If blocked after genuine investigation, ask **one focused question** with the evidence you gathered—not a list of open-ended possibilities.

package/dist/core/skills/built-in/hooman-coding/new-project.md

@@ -0,0 +1,23 @@
+# Greenfield Projects And Components
+
+For creating a project, package, or substantial component from scratch (no existing house pattern to copy).
+
+## Stack and structure
+
+- Choose a **boring, standard stack**: widely used, documented, actively maintained tools that match the user's stated constraints and ecosystem. Do not invent architecture or pick niche frameworks without a stated reason.
+- Match the ecosystem's conventional layout (e.g. `src/` + entrypoint, standard config file locations) so future tools and contributors find things where they expect them.
+- Start with the **smallest scaffold that builds and runs**, verify it, then add features incrementally—never a big-bang tree of untested files.
+
+## Manifests and tooling
+
+- Create a real dependency manifest (`package.json`, `requirements.txt`/`pyproject.toml`, `go.mod`, …) with **actual current versions**—add dependencies via the package manager rather than guessing version numbers.
+- Pin the runtime where the ecosystem supports it (`.nvmrc`/`engines`, `requires-python`, …).
+- Set up the basics the ecosystem expects: formatter, linter, test runner, and the corresponding scripts/commands—configured minimally, using defaults over bespoke rule sets.
+- Add a `.gitignore` appropriate to the stack before generating build artifacts, and keep env/secrets files ignored from the start.
+
+## Deliverables
+
+- A **README** with what the project is, prerequisites, install, run, and test commands—short and accurate beats long and aspirational.
+- A working entrypoint the user can run immediately; verify the documented commands actually work before reporting.
+- For web apps: a clean, modern UI with sensible defaults (layout, spacing, typography, responsive behavior)—polish the default experience rather than shipping unstyled scaffolding.
+- Example configuration (`.env.example` or equivalent) when the project needs credentials, with placeholders instead of real values.

package/dist/core/skills/built-in/hooman-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hooman-config
-description: Read and update Hooman's own config.json and instructions.md safely. Use when the user asks about Hooman config, custom instructions, model providers, LLM options, tool toggles, prompts, search, agents, compaction, or ~/.hooman config settings.
+description: Read and update Hooman's own ~/.hooman/config.json and instructions.md. Use when the user asks about Hooman's config, custom instructions, agent name, model providers, LLMs/models, API keys, reasoning options, web search settings, tool or prompt toggles, or compaction. Not for MCP servers (use hooman-mcp), channel integrations (hooman-channels), or installed skills (hooman-skills).
 ---
 
 # Hooman Config
@@ -14,6 +14,13 @@ Use this skill when the user asks you to inspect, explain, or change Hooman's ow
 - User instructions: `~/.hooman/instructions.md`.
 - This skill does not cover `mcp.json`, installed skill directories, or bundled skill files.
 
+## Reference Files
+
+Read these files (next to this SKILL.md) only when the task needs the details they cover:
+
+- `providers.md` — full `providers`/`llms` shapes, all supported provider ids, per-provider option and `reasoning` details, and worked examples. Read it before adding or changing any provider or LLM entry.
+- `search.md` — the `search` section shape, supported search providers, and per-provider notes. Read it before enabling or changing web search.
+
 ## Effective Runtime View
 
 Use `hooman config` to inspect the merged runtime `config.json` for
@@ -25,10 +32,11 @@ overlays walked from git root to the current directory). The command prints full
 
 1. Read the existing JSON first. Preserve user values, comments are not supported, and secrets such as API keys may be present.
 2. Make the smallest JSON edit that satisfies the request. Do not rewrite unrelated sections or normalize formatting beyond valid pretty JSON.
-3. `name`, `providers`, and `llms` are required. `providers` stores shared credentials/config, and `llms` must be a **non-empty array** of entries that reference provider names (see below). `search`, `prompts`, `tools`, and `compaction` are optional in input, but Hooman expands them with defaults when loading.
+3. `name`, `providers`, and `llms` are required. `providers` stores shared credentials/config, and `llms` must be a **non-empty array** of entries that reference provider names (see `providers.md`). `search`, `prompts`, `tools`, and `compaction` are optional in input, but Hooman expands them with defaults when loading.
 4. Unknown keys are unsupported and may be dropped when Hooman parses and persists the config.
 5. `tools` only manages built-in runtime toggles exposed in `config.json`.
 6. Any change to `config.json` or `instructions.md` requires restarting the running Hooman agent/session before it takes effect. In an interactive `chat` session, running the `/config` command applies this automatically: it reloads config and re-bootstraps the session on exit.
+7. When editing `providers` or `llms`, preserve unrelated entries and API keys unless the user asks to remove or replace them.
 
 ## Full Config Shape
 
@@ -85,228 +93,25 @@ This is the default shape Hooman writes when `~/.hooman/config.json` is missing:
 }
 ```
 
+Hooman fills all optional sections with defaults on load and persist, so a minimal valid config is just `name`, `providers`, and `llms`.
+
 ## Top-Level Options
 
 - `name`: non-empty display name for the agent.
-- `providers`: required reusable provider definitions. Each entry has `name`, runtime `provider`, and provider-specific `options`.
-- `llms`: required non-empty list of named LLM configs. Each entry has `name`, provider reference `provider`, model `options`, and `default`.
-- `search`: optional web search config; defaults to disabled Brave.
+- `providers`: required reusable provider definitions. Each entry has `name`, runtime `provider`, and provider-specific `options`. Supported runtime providers: `anthropic`, `azure`, `bedrock`, `google`, `groq`, `minimax`, `moonshot`, `ollama`, `openai`, `openrouter`, `xai` — details in `providers.md`.
+- `llms`: required non-empty list of named LLM configs. Each entry has `name`, provider reference `provider`, model `options` (`model`, optional `temperature`, optional `maxTokens`), and `default` (mark exactly one entry `true`). Details in `providers.md`.
+- `search`: optional web search config; defaults to disabled Brave. Details in `search.md`.
 - `prompts`: optional built-in static prompt toggles; omitted fields default to `true`. Custom user instructions live in `~/.hooman/instructions.md`.
 - `tools`: optional tool toggles and tool-specific settings.
 - `compaction`: optional context compaction settings. `ratio` must be `0..1`; `keep` must be a non-negative integer.
 
-## LLMs array
-
-Each element of `llms` has:
-
-- `name`: non-empty label for this entry.
-- `provider`: provider reference name. It must match one of the entries in top-level `providers`.
-- `options.model`: model id passed to the resolved runtime provider.
-- `options.temperature`: optional normalized temperature override.
-- `options.maxTokens`: optional normalized output token limit.
-- `default`: boolean; mark one entry `"default": true` for the active model.
-
-## Providers array
-
-Each element of `providers` has:
-
-- `name`: non-empty reference name used by `llms[].provider`.
-- `provider`: runtime provider id such as `"openai"`, `"bedrock"`, or `"ollama"`.
-- `options`: provider-specific shared settings such as API keys, base URL, headers, region, or AWS credentials.
-
-Supported `providers[].provider` values:
-
-```json
-[
-  "anthropic",
-  "azure",
-  "bedrock",
-  "google",
-  "groq",
-  "minimax",
-  "moonshot",
-  "ollama",
-  "openai",
-  "openrouter",
-  "xai"
-]
-```
-
-Common shape:
-
-```json
-{
-  "providers": [
-    {
-      "name": "Anthropic",
-      "provider": "anthropic",
-      "options": {
-        "apiKey": "..."
-      }
-    }
-  ],
-  "llms": [
-    {
-      "name": "Claude Sonnet",
-      "provider": "Anthropic",
-      "options": {
-        "model": "claude-sonnet-4-20250514",
-        "temperature": 0.2,
-        "maxTokens": 4096
-      },
-      "default": true
-    }
-  ]
-}
-```
-
-Provider notes:
-
-- `anthropic`: provider `options` support `apiKey`, optional `baseURL`, optional `headers`, and optional `reasoning` (an object with optional `effort` — `"minimal"`, `"low"`, `"medium"`, `"high"` — and optional `display` — `"summarized"` or `"omitted"`). Providing `reasoning` enables extended thinking (sent as `thinking: { type: "enabled", budget_tokens }`); `effort` defaults to `"medium"` and maps to an explicit budget (`minimal`→1024, `low`→2048, `medium`→4096, `high`→8192). When thinking is enabled Hooman drops any custom `temperature` (Anthropic requires it unset/`1`). `display` is for Bedrock Claude (via an Anthropic-compatible proxy) and MiniMax only: newer Bedrock Claude models (e.g. Opus 4.7+) hide reasoning by default and reject `type: "enabled"`, so set `display: "summarized"` to reveal reasoning — this switches the request to `thinking: { type: "adaptive", display }` with `output_config.effort` (`minimal`→`low`, else passthrough). Do NOT set `display` for the native Anthropic API (api.anthropic.com); it rejects `adaptive`/`display`/`output_config`. Omit `reasoning` to keep thinking off. LLM `options` support `model`, `temperature`, and `maxTokens`.
-- `azure`: provider `options` support optional `resourceName`, optional `baseURL`, optional `apiKey`, optional `headers`, optional `apiVersion`, optional `useDeploymentBasedUrls`, and optional `reasoning` (an object with optional `effort` — `"minimal"`, `"low"`, `"medium"`, `"high"` — and optional `summary` — `"auto"`, `"concise"`, `"detailed"`, `"none"`). `reasoning` uses the Azure OpenAI Responses API; only reasoning-capable deployments honor it. LLM `options` support `model`, `temperature`, and `maxTokens`. The `model` value should be your Azure deployment name.
-- `bedrock`: provider `options` support `region`, `accessKeyId`, `secretAccessKey`, `sessionToken`, optional `apiKey`, and optional `reasoning` (an object with optional `effort` and optional `display` — `"summarized"` or `"omitted"`). Providing `reasoning` enables extended thinking on supported models (e.g. Claude); because Bedrock's Converse API requires a budget, `effort` (default `"medium"`) maps to `budget_tokens` (`minimal`→1024, `low`→2048, `medium`→4096, `high`→8192). Ensure the LLM `maxTokens` exceeds the budget. Newer Bedrock Claude (e.g. Opus 4.7+) hide reasoning by default and reject `type: "enabled"`; set `display: "summarized"` to reveal it — this switches to `thinking: { type: "adaptive", display }` with `output_config.effort` (`minimal`→`low`, else passthrough) sent via `additionalRequestFields`. LLM `options` support `model`, `temperature`, and `maxTokens`.
-- `google`: provider `options` support `apiKey` and optional `reasoning` (an object with optional `effort`). Setting `reasoning.effort` enables Gemini thinking with a dynamic budget (`thinkingConfig: { includeThoughts: true, thinkingBudget: -1 }`). LLM `options` support `model`, `temperature`, and `maxTokens` (Hooman maps this to the Google SDK's `maxOutputTokens` internally).
-- `groq`: provider `options` support `apiKey`, optional `baseURL`, optional `headers`, and optional `reasoning` (an object with optional `effort`). `reasoning.effort` maps to Groq's `reasoning_effort` (`minimal`→`low`) and streams reasoning via `reasoning_format: "parsed"`. Only reasoning models honor it. LLM `options` support `model`, `temperature`, and `maxTokens`.
-- `minimax`: provider `options` support `apiKey`, optional `headers`, and optional `reasoning` (an object with optional `effort` — `"minimal"`, `"low"`, `"medium"`, `"high"` — and optional `display` — `"summarized"` or `"omitted"`). Providing `reasoning` enables thinking, normalized to MiniMax's `thinking: { type: "adaptive", budget_tokens }`; `effort` defaults to `"medium"` and maps to an explicit budget (`minimal`→1024, `low`→2048, `medium`→4096, `high`→8192). Setting `display` switches to `thinking: { type: "adaptive", display }` with `output_config.effort` instead of a budget. Omit `reasoning` to keep thinking off. Hooman routes this through the Anthropic-compatible MiniMax endpoint automatically.
-- `moonshot`: provider `options` support `apiKey`, optional `baseURL`, optional `headers`, and optional `reasoning` (an object with optional `effort`). Setting `reasoning.effort` enables Kimi thinking (`thinking: { type: "enabled" }`). Served through the reasoning-aware openai-compatible adapter, so Kimi's `reasoning_content` is surfaced as thinking. When `baseURL` is omitted, Hooman defaults it to `https://api.moonshot.ai/v1`. To reach Kimi through an OpenAI-compatible proxy (e.g. LiteLLM), use this provider with `baseURL` set to the proxy's `/v1` endpoint — the `openai` provider's Chat adapter would otherwise drop Kimi's reasoning.
-- `ollama`: provider `options` support optional `baseURL` and optional `reasoning` (an object with optional `effort`). Setting `reasoning.effort` enables thinking, mapped to Ollama's `think` level (`minimal`/`low`→`"low"`, `medium`→`"medium"`, `high`→`"high"`). LLM `options` support `model`, `temperature`, and `maxTokens`.
-- `openai`: provider `options` support `apiKey`, optional `baseURL`, optional `headers`, optional `api` (`"responses"` or `"chat"`, defaults to `"responses"`), and optional `reasoning` (an object with optional `effort` — `"minimal"`, `"low"`, `"medium"`, `"high"` — and optional `summary` — `"auto"` (default), `"concise"`, `"detailed"`, `"none"`). LLM `options` support `model`, `temperature`, and `maxTokens`. Use `"responses"` (the default) to surface model reasoning/thinking; set `"chat"` for OpenAI-compatible endpoints/proxies that do not implement the Responses API. Reasoning summaries stream only on the Responses API, and some models (e.g. GPT-5) require `reasoning.effort` of `"medium"` or higher to emit them; set `reasoning.summary` to `"none"` for non-reasoning models that reject the `reasoning` parameter. Note: `"chat"` mode does NOT surface reasoning (the Chat adapter drops `reasoning_content`); for a proxy that only exposes thinking via chat `reasoning_content` (e.g. Kimi/Moonshot), use the `moonshot` or `openrouter` provider instead. Also note the Responses API may return an empty reasoning item for non-OpenAI backends behind a proxy (they won't stream summary text).
-- `openrouter`: provider `options` support `apiKey`, optional `baseURL`, optional `headers`, and optional `reasoning` (an object with optional `effort`). Served through the reasoning-aware openai-compatible adapter, so `reasoning`/`reasoning_content` deltas are surfaced as thinking. `reasoning.effort` maps to `reasoning_effort`, which OpenRouter normalizes for reasoning models. LLM `options` support `model`, `temperature`, and `maxTokens`. The `model` value is usually a provider-qualified OpenRouter model id such as `anthropic/claude-3.5-sonnet`.
-- `xai`: provider `options` support `apiKey`, optional `baseURL`, optional `headers`, and optional `reasoning` (an object with optional `effort`). `reasoning.effort` maps to xAI's `reasoning_effort` (`low`/`high`; `minimal`/`low`→`low`, `medium`/`high`→`high`). Only reasoning models (e.g. grok-3-mini) honor it. LLM `options` support `model`, `temperature`, and `maxTokens`.
-
-Examples:
-
-```json
-{
-  "providers": [
-    {
-      "name": "MiniMax",
-      "provider": "minimax",
-      "options": {
-        "apiKey": "..."
-      }
-    },
-    {
-      "name": "Kimi",
-      "provider": "moonshot",
-      "options": {
-        "apiKey": "..."
-      }
-    }
-  ],
-  "llms": [
-    {
-      "name": "MiniMax M3",
-      "provider": "MiniMax",
-      "options": {
-        "model": "MiniMax-M3"
-      },
-      "default": true
-    },
-    {
-      "name": "Kimi K2.7 Code",
-      "provider": "Kimi",
-      "options": {
-        "model": "kimi-k2.7-code"
-      },
-      "default": false
-    }
-  ]
-}
-```
-
-```json
-{
-  "providers": [
-    {
-      "name": "Bedrock",
-      "provider": "bedrock",
-      "options": {
-        "region": "us-west-2",
-        "accessKeyId": "AKIA...",
-        "secretAccessKey": "...",
-        "sessionToken": "..."
-      }
-    }
-  ],
-  "llms": [
-    {
-      "name": "Claude Sonnet",
-      "provider": "Bedrock",
-      "options": {
-        "model": "anthropic.claude-sonnet-4-20250514-v1:0",
-        "temperature": 0.2,
-        "maxTokens": 4096
-      },
-      "default": true
-    }
-  ]
-}
-```
-
-When editing `providers` or `llms`, preserve unrelated entries and API keys unless the user asks to remove or replace them.
-
-## Search
-
-`search.provider` must be `"brave"`, `"exa"`, `"firecrawl"`, `"litellm"`, `"serper"`, or `"tavily"`.
-
-```json
-{
-  "search": {
-    "enabled": true,
-    "provider": "brave",
-    "brave": {
-      "apiKey": "..."
-    },
-    "exa": {
-      "apiKey": "..."
-    },
-    "firecrawl": {
-      "apiKey": "..."
-    },
-    "litellm": {
-      "baseURL": "https://your-litellm-host",
-      "apiKey": "sk-...",
-      "tool": "perplexity-search"
-    },
-    "serper": {
-      "apiKey": "..."
-    },
-    "tavily": {
-      "apiKey": "..."
-    }
-  }
-}
-```
-
-Hooman calls Exa through the official **`exa-js`** SDK ([Exa search API](https://exa.ai/docs/reference/search-api-guide-for-coding-agents)).
-
-Hooman calls Firecrawl through **`@mendable/firecrawl-js`** ([Firecrawl search API](https://docs.firecrawl.dev/api-reference/endpoint/search)).
-
-The `litellm` provider calls a [LiteLLM](https://docs.litellm.ai/docs/search/) proxy's Perplexity-compatible `POST {baseURL}/v1/search/{tool}` endpoint using the virtual key as `apiKey`. It requires `baseURL`, `apiKey`, and `tool` (the `search_tool_name` registered on the proxy). The actual upstream search provider (perplexity, tavily, exa, brave, etc.) is chosen by the proxy config, so no provider API key is stored in Hooman.
-
-Defaults: `enabled: false`, `provider: "brave"`, all provider API keys unset.
-
 ## Prompts
 
-Each prompt toggle is optional and defaults to `true`. Coding and software-engineering guidance is not a config toggle; it lives in the built-in **hooman-coding** skill and is loaded when relevant (see the system prompt skills section).
-
-```json
-{
-  "prompts": {
-    "behaviour": true,
-    "communication": true,
-    "execution": true,
-    "guardrails": true
-  }
-}
-```
-
-Set a prompt to `false` only when the user explicitly wants to omit that harness section.
+Each prompt toggle (`behaviour`, `communication`, `execution`, `guardrails`) is optional and defaults to `true`. Set one to `false` only when the user explicitly wants to omit that harness section. Coding and software-engineering guidance is not a config toggle; it lives in the built-in **hooman-coding** skill and is loaded when relevant (see the system prompt skills section).
 
 ## Tools
 
-Simple toggles:
+Simple toggles, all enabled by default:
 
 ```json
 {
@@ -321,27 +126,11 @@ Simple toggles:
 }
 ```
 
-Subagents:
-
-```json
-{
-  "tools": {
-    "subagents": {
-      "enabled": true
-    }
-  }
-}
-```
-
-Defaults: `todo`, `fetch`, `filesystem`, `shell`, `sleep`, and `subagents` enabled. MCP servers and installed skills are not controlled by these toggles; do not inspect or edit them for this skill.
-
-`subagents`: the default file Hooman writes when `config.json` is missing includes `tools.subagents.enabled: true`. If `tools` or `tools.subagents` is omitted, the merged config still defaults this toggle to enabled.
+MCP servers and installed skills are not controlled by these toggles; do not inspect or edit them for this skill.
 
 ## Instructions
 
-`~/.hooman/instructions.md` contains the user's custom instructions. Read or edit it only when the user asks about Hooman instructions, custom instructions, persistent guidance, or agent behavior that belongs outside `config.json`.
-
-Keep instruction edits focused and preserve existing wording unless the user asks for a rewrite.
+`~/.hooman/instructions.md` contains the user's custom instructions. Read or edit it only when the user asks about Hooman instructions, custom instructions, persistent guidance, or agent behavior that belongs outside `config.json`. Keep instruction edits focused and preserve existing wording unless the user asks for a rewrite.
 
 ## Compaction
 
@@ -356,30 +145,3 @@ Keep instruction edits focused and preserve existing wording unless the user ask
 
 - `ratio`: target fraction of context after compaction, from `0` to `1`.
 - `keep`: minimum number of recent turns/message groups to preserve verbatim.
-
-## Minimal Valid Config
-
-```json
-{
-  "name": "Hooman",
-  "providers": [
-    {
-      "name": "Ollama",
-      "provider": "ollama",
-      "options": {}
-    }
-  ],
-  "llms": [
-    {
-      "name": "Default",
-      "provider": "Ollama",
-      "options": {
-        "model": "gemma4:e4b"
-      },
-      "default": true
-    }
-  ]
-}
-```
-
-Hooman fills all optional sections with defaults on load and persist.