@oooooooooo/ch0de 0.0.0-stage → 1.9.55

package/API-TESTING.md

@@ -0,0 +1,76 @@
+# API testing in Chode
+
+Three optional engines provide complementary evidence:
+
+| Engine | Purpose | Pinned managed release |
+| --- | --- | --- |
+| [Hurl](https://hurl.dev/docs/installation.html) | Plain-text HTTP journeys, captured IDs/tokens, JSON assertions | 8.1.0 |
+| [Schemathesis](https://schemathesis.readthedocs.io/en/stable/) | Generated OpenAPI/GraphQL contract tests, including edge cases | 4.32.7 |
+| [k6](https://grafana.com/docs/k6/latest/) | Explicit HTTP load tests, checks and performance thresholds | 2.3.0 |
+
+Chode does not install these with its normal package. `list` and `doctor` work without them. Setup installs Hurl through its official npm package, Schemathesis into a Python virtual environment, and k6 from a release with a pinned SHA-256. Managed installations stay under the workspace's `.chode/api-tools`; global installations are also detected. `CHODE_API_TOOLS_HOME` optionally selects a shared directory. Setup requires network access; Schemathesis also requires a compatible Python installation. k6 managed setup supports Windows x64, Linux x64/arm64 and macOS x64/arm64; use a PATH installation on other platforms.
+
+```text
+chode api-test list
+chode api-test doctor
+chode api-test setup hurl
+chode api-test setup schemathesis
+chode api-test setup k6
+
+chode api-test run hurl "tests/api journey.hurl" --base-url http://127.0.0.1:3000
+chode api-test run schemathesis openapi.json --base-url http://127.0.0.1:3000 --examples 20
+chode api-test run k6 tests/smoke.js --base-url http://127.0.0.1:3000 --iterations 5 --vus 1
+```
+
+The TUI uses the same interface: `/api-test list`, `/api-test setup hurl`, `/api-test run hurl "tests/api journey.hurl" --base-url http://127.0.0.1:3000`. It runs in a worker, stays responsive and can be stopped with Ctrl+C. Setup and execution are blocked in plan mode; discovery remains available. These commands make zero model calls. An API-test failure shows its evidence directly instead of queuing an unrelated provider retry. Builds can run these commands through the existing guarded `exec` tool, inspect the failed assertions, repair the application and rerun the unchanged test.
+
+## Minimal tests
+
+Hurl uses the `base_url` variable:
+
+```hurl
+GET {{base_url}}/health
+HTTP 200
+[Asserts]
+jsonpath "$.ok" == true
+```
+
+Schemathesis takes the application's actual OpenAPI/GraphQL schema. Generated examples default to 10 per operation, one worker and seed 1. Schema coverage and negative testing remain enabled. Reported JUnit test counts refer to engine test cases/operations, not a coding benchmark score or exhaustive API coverage.
+
+k6 uses `__ENV.BASE_URL`:
+
+```js
+import http from 'k6/http';
+import {check} from 'k6';
+export const options = {thresholds: {http_req_duration: ['p(95)<500']}};
+export default function () {
+  const response = http.get(__ENV.BASE_URL + '/health');
+  check(response, {'healthy': r => r.status === 200});
+}
+```
+
+k6 defaults to one virtual user and five iterations. Chode checks the summary for failed assertions and HTTP requests even when k6 itself exits zero. Native threshold failures also fail the run; an HTTP test that sends no requests cannot pass. A script's own scenarios can specify additional workload. Load testing is explicit, never an automatic probe of a public service.
+
+## Evidence and limits
+
+CLI output is JSON and failures exit nonzero. Reports under `.chode/api-tests/results` retain the actual native exit code, timeout/signal, timestamps, test SHA-256, bounded redacted diagnostics and available metrics. Human TUI output shows a concise result and report path. Raw native summaries/JUnit files are removed after extraction. A failed launch, missing tool, absent required report, zero schema tests, changed test file or timeout cannot count as a pass. Default execution timeout is 60 seconds; `--timeout 1..300` bounds a test process tree. This does not impose a time limit on the build workflow.
+
+Only regular workspace test inputs with expected extensions are accepted; credential/internal-state paths, links and hardlinks are rejected. Test files are executable project input with the same authority as project test commands, not a sandbox. Keep credentials in environment variables rather than test files or base URLs. Known saved/environment credentials are redacted from retained diagnostics; arbitrary application-specific secrets are not automatically known.
+
+Overlapping frameworks from the proposed list are not installed. Existing project suites can continue through `exec`; the three adapters above add distinct coverage without making every Chode user install Java, Python and multiple duplicate workflow runners.
+
+## On-demand runn know-how
+
+Chode recognizes [runn](https://github.com/k1LoW/runn) as an available-to-get capability for SSH, browser/CDP screenshots and DOM access, HTTP/gRPC and database workflows. Relevant tasks receive concise guidance to check availability and use `toolbox inspect {repo:"k1LoW/runn"}` to clone the official repository only when needed. Reuse the checkout, read relevant documentation, follow official setup and verify actual results. Nothing is installed or cloned merely by starting Chode. Unrelated tasks receive no runn-specific context; existing permissions still apply.
+
+## Further integration direction
+
+Keyless website-backed code generation remains an experimental candidate, not a working browser integration in this release. It needs per-site access/automation support, completion detection, code extraction and local verification. Prefer a documented public interface when one is available: [AI Horde](https://aihorde.net/) publishes a community text/image API, and [Gradio](https://www.gradio.app/guides/querying-gradio-apps-with-curl) documents API access to compatible public apps. Their coding quality and practical availability have not been qualified here. Never infer anonymous access from a model catalogue or treat a web session as an unlimited API.
+
+A future component library should inspect layout/DOM/styles/interactions and collect reusable code with source/license, dependencies, comments, examples and tests. Public client-side assets do not supply a site's backend. Chode already has web fetching/research and browser verification; a searchable, provenance-aware reusable component store is not implemented by these API-test adapters.
+
+## Tool use and implementation quality
+
+Tools are chosen automatically from the user's task. `/tools` explains this; `/tools forex` shows capability guidance and an example message without pretending it executed the tool. Ask Chode to use a named tool in normal language. Actual tool activity/results show when it is used. Live forex, geocoding and weather calls passed on29October2026.
+
+Requests for multiple core mechanisms (such as learning, reasoning, grammar, reinforcement and pruning) get an explicit behavior contract and use the test-capable workspace instead of the static HTML artifact shortcut. Certification needs observed successful runtime or protected acceptance tests; labels, sample data, screenshots, syntax checks and empty tests do not qualify. Independent review must distinguish the underlying system from its visualization and assess every original requirement. Tests still need to cover the requested behavior; this gate is a minimum evidence bar, not proof that an arbitrary implementation is flawless. The display-only brain supplied by the user is retained as a rejection regression.

package/DEBTAUR-INTEGRATION.md

@@ -0,0 +1,71 @@
+# Debtaur orchestration integration
+
+Status: implementation in progress; default activation requires an installed, pinned private runtime. No Cone dependency, remote service, model call or permission-policy replacement.
+
+## What runs where
+
+- `debtaur-engine.js`: public Node bridge, strict native protocol encoder/decoder, pinned runtime hashes, worker lifecycle/deadlines and explicit local setup/status.
+- `debtaur-worker.cjs`: isolated worker thread loading the private standalone WASM. Calls are serialized. It uses the native `_judge_run(input,output,capacity)` ABI; high-water native state resets per batch. Never substitutes a JS judge, HTTP demo or model answer.
+- `debtaur-orchestration.js`: host-owned scoped leases, artifact snapshots, policy facts and decision receipts. Recorded history is audit data; it is never loaded as authority for a new build.
+- `orchestrator.js`: obtains leases before dispatch, validates file checks against stable hashes before accepting handoffs, and releases failed/retried workers.
+- `chode.js`: binds local acceptance/browser checks to artifact generations and rechecks that binding after independent review before final certification.
+
+Private engine C/WASM is not redistributed in Chode. Its backup/source histories remain in the private `fogennnnn/debtaur` repository. Review source revision: phase3-harness `7f0b84b` (full revision recorded in the private recovery index). The saved WASM has been functionally probed; exact source-to-binary reproducibility is not yet claimed. Pinned byte hashes are in debtaur-engine.js. Changing a pin requires explicit review and rerunning native/bridge parity and negative controls.
+
+## Setup and control
+
+```sh
+# From your separately authorized private Debtaur checkout:
+chode debtaur setup /absolute/path/to/debtaur/backups/2026-11-02/worker/wasm
+chode debtaur status
+```
+
+Setup copies only the known glue and WASM into `~/.chode/runtimes/debtaur`, using private file permissions. It preserves differing existing files for review. No credentials or network access are needed. CHODE_PROVIDER_HOME, when configured, replaces the user home for this location. Override the runtime directory with `CHODE_DEBTAUR_RUNTIME`; hashes still must match. Explicitly opt out with `CHODE_DEBTAUR=off`. YOLO and existing permissions are unchanged.
+
+Without an installed runtime Chode continues its established local verification. Metadata reports unavailable, never a Debtaur approval. If an available judge explicitly denies, or host checks detect stale/conflicting evidence, that checkpoint cannot be accepted. A timeout, malformed response or runtime-integrity failure is unavailable, not approval; useful baseline work can continue without claiming native certification.
+
+## Evidence and decisions
+
+The host creates facts only from actual scoped ownership, completed checks and current artifact hashes. Prompts, expert-panel advice and worker completion prose never become trusted facts. The original user goal remains authoritative.
+
+| Boundary | Required facts | Meaning of allow |
+| --- | --- | --- |
+| Dispatch | valid source scope; no conflicting active owner | Worker may start its scoped work |
+| Handoff | current lease; stable checked artifact generation; successful worker/file checks | Parent may accept these files for integration |
+| Verification | stable artifacts across actual checks; checks passed; workers settled | Current check evidence may be consumed |
+| Final confirmation | same checked artifacts after independent review; workers settled | Check binding is still current |
+
+An allowance establishes these policy conditions, not arbitrary code correctness or satisfaction of every user requirement. Existing protected tests, quality checks, browser checks and independent review remain necessary. Native failures do not spend or enlarge provider budgets.
+
+Each batch is rebuilt from current host facts. Withdrawal/changed hashes remove the premise supporting the allowance; no stale conclusion is reasserted. Leases are reserved synchronously before awaiting native decisions, so concurrent workers cannot race into the same scope. Retries acquire new leases; failed leases cannot submit later handoffs.
+
+The pinned native parser supports the tested two-premise conjunction form. Three required facts are expressed as two chained two-premise rules, not a guessed flat three-way conjunction. Every truth-table combination is checked against the real binary.
+
+## Native protocol contract
+
+This is the judge-WASM/judge_cli tab protocol, not the plugin JSON shim or raw gate_cli prefix protocol:
+
+```text
+stated<TAB>if the artifact is current and the check is passed then the evidence is usable
+stated<TAB>the artifact is current
+stated<TAB>the check is passed
+!<TAB>the evidence is usable
+```
+
+Only stated, dreamt, ! and - operations are accepted by the public encoder. No control characters or unbounded clauses. Unsupported native prefixes can become facts, so the host rejects them before the worker. One output row per operation is required. Gate rows must have op:gate, the exact input clause, a recognized verdict, an explicit consistent boolean allow, nonempty reason and typed evidence. Unknown/malformed outputs cannot authorise.
+
+Limits:48 operations,180 UTF-8 bytes per clause,24KB batch,512KB output,4 in-flight requests,5-second worker deadline (bounded configuration up to10 seconds). Native calls in one module never interleave. Timeout/cancellation terminates the worker and resolves outstanding requests as unavailable. Idle workers are unreferenced; build-finally cleanup closes owned workers.
+
+## Storage, replay and privacy
+
+Local `.chode/orchestration/<run-uuid>.json` contains the task digest, scoped file hashes, controlled policy facts/proofs, runtime/input/output hashes and a hash-linked bounded decision journal. It contains no source contents, prompts, API keys or shell-command output. No service receives it. Storage failures do not convert checks into approvals. `--no-memory` disables this journal while retaining current in-process correctness checks; no historical memory is recalled by this integration.
+
+The journal is inspectable audit evidence, not an authenticated store against a user able to rewrite the workspace. New builds never use it to grant ownership or mark tests passed. File hashes are recomputed from current bytes. Preserve reports when diagnosing; do not label replayed history as a newly executed test.
+
+Snapshot scope is observed write/edit paths, existing planned paths, the protected acceptance test and package.json when present. It is not a snapshot of every dependency or the whole filesystem. Bounds:256 files,16MB per file,64MB total. Linked/hardlinked/credential/internal-state paths are excluded. An unobservable set cannot claim native certification; existing host checks remain in force.
+
+## Verification and maintenance checklist
+
+Before default release: native C make test; direct native/WASM protocol probes; bridge malformed/empty/timeout/cancellation/concurrency controls; ownership conflict/crash/retry/stale-handoff controls; artifact mutation during and after checks; actual multi-worker build and protected acceptance; deterministic repeated input/output; deliberately broken variants that must fail; full Chode regression suite and release-integrity checks.
+
+When changing the integration, document the exact stage, fact sources, invalidation rules, protocol version/hash, positive/negative controls and any unsupported cases. Never accept a model's self-reported pass as a host fact, silently truncate a world, treat no verdict as native approval, or add Cone as a hidden dependency.

package/EDITING.md

@@ -0,0 +1,80 @@
+# Grouped edits and undo
+
+Chode supports one undoable batch across up to 20 text edits. Every operation is prepared before any user file changes. An invalid match, protected path or missing permission rejects the batch. Several edits to one file compose in order.
+
+Save a workspace-relative manifest:
+
+```json
+{
+  "edits": [
+    {"file":"src/a.js","oldString":"oldName","newString":"newName"},
+    {"file":"src/b.js","oldString":"oldName","newString":"newName"},
+    {"op":"write","file":"src/new.js","content":"export const answer = 42;\n"}
+  ]
+}
+```
+
+```sh
+chode edits preview changes.json
+chode edits apply changes.json
+chode edits history
+chode undo
+```
+
+Preview returns a unified diff without modifying the target files or recording an edit. Apply prepares against current contents and rechecks the original bytes before committing. Manual single-file `write`/`edit` and agent edits share the same persistent history. `/changes` lists it in the TUI; `/undo` restores the latest applied edit group. Undo removes files that a group created and rejects any content conflicts before restoring other files. Stop an active build before using `/undo`.
+
+The agent tool is `multiedit {edits:[...], preview?:true}`. Existing workspace, secret, fixture and whole-file overwrite permissions still apply. Protected acceptance tests are excluded. Plan mode disables batch mutation. An applied batch is recorded as implementation work for verification.
+
+History retains 50 records under `.chode/changes`; journal contents contain the edited files' before/after text and must not be committed. Each file is UTF-8 text, <=200 KB; combined before/after contents are <=1 MB. Binary files, symbolic links, hard-linked files and harness/Git metadata are excluded. File modes are retained where supported by the host filesystem.
+
+Each individual replacement uses a temporary file and rename. An ordinary batch failure rolls back committed files; an interrupted apply/undo is recovered at the next edit operation if contents still match the journal. A concurrent external modification produces a conflict rather than overwriting it. Multi-file visibility is not an operating-system atomic primitive: other processes may briefly observe intermediate files. A dead process's lock can be recovered; an unreadable or live-owner lock is left intact for inspection.
+
+Content is rechecked immediately before each replacement. External programs do not share Chode's lock, so concurrent-edit detection cannot eliminate the interval between that check and rename; stop external writers when applying a batch.
+
+The older `chode rewind` snapshot interface remains available. Undoing changes through an external editor or `rewind` may cause a history conflict; inspect the current files and history instead of forcing restoration.
+
+## Isolated Git worktrees
+
+```sh
+chode worktree create fix-map --ref HEAD
+chode worktree list
+chode worktree remove fix-map
+```
+
+Creation makes a new `codex/fix-map` branch and checkout under the repository's `.chode/worktrees/`. The JSON result includes `directory`: change into that directory and start Chode there to work in isolation. From a repository subdirectory, the matching subdirectory is selected when it exists in the new checkout. `/worktree` exposes the same management commands in the TUI; it does not change an active process's workspace.
+
+Creation starts from a committed ref, preserves all uncommitted work in the original checkout and never copies credentials or ignored local state. Existing destinations/branches are not overwritten. Removal uses Git's normal checks, refuses dirty/untracked changes and never deletes the branch. No force-removal option is provided. Git must be installed, the repository must have a commit, and Git's own safe-directory rules apply. If checkout is interrupted, inspect `git worktree list` and the retained branch before cleanup.
+
+## Plan and execute
+
+Use `chode plan "goal"` or `chode ai --mode plan "goal"` to inspect and produce a plan without model-driven project mutations or command execution. `chode execute "goal"` and `chode ai --mode execute "goal"` use the normal tool and verification loop. Explicit `--mode` overrides the default; invalid values fail before model access. JSON planning output is supported with `--json`.
+
+In the TUI, `/mode plan` makes subsequent prompts read-only; `/mode execute` restores normal builds. `/plan <goal>` explicitly plans, and `/execute <goal>` explicitly builds regardless of the current default. The current mode is visible in the header. A queued retry retains its original mode. Task delegation is refused in plan mode; manual management commands such as undo/worktree remain explicit user actions. Planning can save local plan/session/todo metadata, but cannot execute model-supplied file edits, commands, installation or nested tasks. Enforcement happens in the shared dispatcher, including the grouped-edit tool.
+
+## Project guidance and observed memory
+
+Chode reads workspace-root `AGENTS.md`, `CLAUDE.md` and `CHODE.md` as project guidance, subordinate to the current user request and permissions. It does not scan arbitrary ancestor folders or rewrite these human-maintained files. Guidance is bounded to 6 KB; historical observations to 4 KB. Use `--no-memory` on a build or plan to disable both inputs for that run.
+
+After a verified build, `.chode/project-memory.json` records changed-file names/hashes and successful, completed checks. It stores no source snapshots, model summaries, prompt transcripts or raw command output. Simple test commands are retained; other successful commands are represented by a hash. Failed/unverified runs are not promoted into verified memory. Credentials and harness state are excluded. Recall is explicitly historical: current files must be rechecked, and independent verification does not inherit this author context.
+
+`chode memory show` inspects the local record; `chode memory clear` clears only that generated record. Records are bounded to 20 runs and 60 KB, use atomic replacement and a writer lock, and preserve corrupt data for inspection. Each workspace is separate, so worktree memory is local to that checkout. No extra model call is used for automatic updates. Never commit `.chode` state.
+
+## Subagent spawn and join
+
+The existing `task {prompt,label?}` tool still runs one isolated helper and waits for it. For parallel investigation, use `task {action:"spawn",prompt,label?}`; it returns an ID immediately. Use `task {action:"status",id}` and `task {action:"join",id}` to collect the result. Join before finishing: an unjoined group prevents a complete parent result. At most three spawned helpers are active, with six total per parent run. The parent and helpers share its bounded model-call budget and free-only policy. Nested tasks are disabled.
+
+Spawned helpers are read-only to avoid simultaneous writes in a shared checkout. The synchronous task path retains its existing workspace mutation guards; implementation should use an isolated worktree when independent branches are needed. Context isolation is not an OS sandbox. Parent prompts/transcripts are not copied into child sessions. Legacy child mutations/actions and writer identities are included in parent verification evidence.
+
+Results are saved under `.chode/tasks` and can be retrieved later with `chode task status <id>` or `chode task join <id>`. A running record from another/interrupted process is unresolved, not successful. A new process cannot restart an in-flight Promise; rerun the task if its owner was interrupted. Child failures are collected and results are bounded/redacted. Parent cleanup awaits its bounded helper runs so a normal worker exit does not abandon them.
+
+## Verification and repair
+
+Run `chode verify acceptance.cjs` for a standalone immutable acceptance check, or `/verify acceptance.cjs` when the TUI is idle. `/check acceptance.cjs` selects a check for subsequent builds. To implement and iterate against it:
+
+```sh
+chode ai --check acceptance.cjs "Complete the implementation; preserve acceptance.cjs unchanged."
+```
+
+The existing bounded repair loop receives the failed checks and observed diagnostics, then reruns acceptance and independent verification. It shares the parent model-call budget; unavailable verification and exhausted windows remain incomplete, never successful.
+
+Checks run in the project via Node with a 30-second process limit and 1 MB output buffer. Both stdout and stderr are captured separately, redacted, and retained up to 16 KB each in `.chode/verification` reports. Reports include exit status, signal, duration and original/observed test digests. A zero exit with a changed test fails. The most recent 50 reports are retained; report persistence failure also prevents a verification pass. These are local code executions, not sandboxed untrusted programs. Test coverage still determines what a passing check proves.

package/EXPERT-PANEL.md

@@ -0,0 +1,16 @@
+# Sequential expert panel
+
+Coding builds in CLI and TUI now run two sequential read-only expert passes by default, then use the existing implementation/repair/verification pipeline. Lightweight direct tool, math and settings routes stay direct. Use `--no-council` for a one-shot build or `CHODE_COUNCIL=off` to disable the panel. Explicit budgets below five calls reserve their capacity for the build instead. Incomplete expert analysis is reported and does not block native build recovery.
+
+Standalone command, installed alongside `chode`:
+
+```sh
+chode-council "Build the requested application" --check acceptance.cjs
+chode-council "Implement the parser" --experts 4 --providers kilo,llm7,kilo,llm7 --max-calls 30 --check acceptance.py
+```
+
+Three experts means two sequential analysis passes followed by the staff synthesizer; four adds a security/correctness reviewer. Each analysis receives the original goal and bounded prior contributions. Analysts make actual separate calls and cannot execute tools. Only the synthesizer uses the existing build/repair/verification engine. Default automatic routing may choose the same provider; recorded provider IDs show what actually happened. Forced IDs must be registered. Strict free mode is default; paid routes require explicit `--allow-paid`.
+
+The model-call budget is shared across all passes, including synthesis and verification; default30. Native tool execution also has one shared cap. Intermediate advice is bounded, redacted and saved privately in `.chode/panels/`; it is not promoted into verified project memory. Actual source files and native test results remain authoritative. Panel failure returns PARTIAL with its saved report, not a fabricated synthesis. Existing command approvals remain enforced. The ongoing frozen Python benchmark remains on its original installed runtime. The standalone command also supports an explicit four-expert panel.
+
+Run `node expert-panel.cjs ...` from a source checkout if the new executable is not installed yet. Provider and MCP availability still depend on configured access. The panel does not add provider quotas or bypass cooldowns.

package/INTEGRATIONS.md

@@ -0,0 +1,75 @@
+# Native integrations
+
+Chode reads installed Agent Skills and connects to compatible Streamable HTTP or stdio MCP servers. These are Chode-owned integrations; setup does not modify another coding agent's configuration.
+
+## Quick start
+
+```sh
+chode integrations list
+chode integrations setup cloudflare --global
+chode mcp auth cloudflare
+chode mcp test cloudflare
+chode mcp tools cloudflare
+chode skills list
+chode skills read cloudflare
+```
+
+The Cloudflare skills already installed under `~/.agents/skills` are discovered automatically. OAuth opens the account provider's login page only when you run `mcp auth` in an interactive terminal. Complete browser consent yourself. A saved configuration is **configured**, a 401 is **needs_auth**, and **ready** requires an actual MCP handshake and tool listing. No agent restart is required: configuration is loaded for each operation. A live test describes that moment, not a perpetual availability guarantee.
+
+Other presets:
+
+```sh
+chode integrations setup openai-docs --global
+chode integrations setup context7 --global
+chode integrations setup github --global
+```
+
+OpenAI docs is public documentation, not free ChatGPT inference. Context7 currently supports unauthenticated discovery; service limits apply. To use its own bearer key, add `--token-env CONTEXT7_API_KEY` on initial setup. GitHub uses the `GITHUB_MCP_TOKEN` environment variable; use a token scoped to the repositories and actions you intend. Existing configurations are preserved; inspect and explicitly remove/re-add a server to change authentication settings. Never paste tokens into prompts or server URLs.
+
+## Other compatible servers
+
+```sh
+chode mcp add docs --url https://example.org/mcp --global
+chode mcp add local -- node /absolute/path/server.cjs
+chode mcp list
+chode mcp trust local
+chode mcp test local
+chode mcp tools local
+chode mcp schema local TOOL_NAME
+chode mcp call local TOOL_NAME '{"query":"example"}'
+chode mcp logout local
+chode mcp remove local
+```
+
+PowerShell and other shells have different JSON quoting rules. `mcp call` executes the requested tool and may change remote resources. Model-driven `mcp_call` requests require approval; headless runs deny them without an approval callback. Plan and read-only subagent modes disable this tool. Discovery starts only explicitly trusted configurations. Local servers execute code: inspect the executable and arguments before trusting them. Configurations found in repositories are not automatically trusted.
+
+Project configuration is `.chode/mcp.json`; user configuration is `~/.chode/mcp.json`. Project names override user names. An explicitly added configuration is trusted; manual changes invalidate that trust. OAuth tokens and client secrets stay in `~/.chode/mcp-auth` (including project connections), separate from the repository, bound to project and endpoint. Local credential files are created with private POSIX permissions; Windows inherits its directory ACLs. Logout clears local credentials; revoke remote grants at the account provider if necessary. Keep `.chode` state out of source control.
+
+Tools are discovered on demand rather than injecting every server schema into every model turn. Each operation opens and closes its own client. Stateful browser sessions spanning several calls are **not supported by this lifecycle yet**; Playwright's CLI plus skills is a better initial browser route. Legacy SSE-only servers, non-dynamic/pre-registered OAuth clients, cross-process session persistence, an interactive TUI integration picker, MCP resources/prompts, and exposing Chode as a server for other apps remain follow-up work. HTTP redirects are rejected; configure the canonical endpoint.
+
+## Agent Skills
+
+Chode discovers project `skills`, `.agents/skills`, `.chode/skills`, `.claude/skills`, then user `.chode/skills`, `.agents/skills`, `.claude/skills` and `.codex/skills`. Project slugs take precedence. Valid `SKILL.md` frontmatter needs a name and description. Relevant metadata is added to build context; the model reads instructions and relative text references through the paged `skill` tool. `--no-memory` suppresses automatic metadata selection. Loading skills never runs their scripts or grants account access. Secret references and paths escaping a skill's real directory are denied.
+
+## Research and next candidates (28 October 2026)
+
+- [Cloudflare agent setup](https://developers.cloudflare.com/agent-setup/prompt.md): shared skills and the OAuth account MCP endpoint. Chode uses its own configuration instead of copying OpenCode examples.
+- [OpenAI documentation MCP](https://learn.chatgpt.com/learn/docs-mcp): usable now through the preset. [Codex SDK](https://learn.chatgpt.com/docs/codex-sdk) is a separate optional agent integration candidate with its own authentication and costs. It is not enabled as a free fallback.
+- [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview): API-key based optional agent candidate. Anthropic says third parties need prior approval to offer claude.ai login or subscription rate limits. Chode does not reuse another app's sessions or promise subscription access.
+- [Context7](https://github.com/upstash/context7): current library documentation, available through the preset.
+- [GitHub MCP](https://github.com/github/github-mcp-server): repository, review and CI context, available through the preset with your token.
+- [Playwright MCP](https://github.com/microsoft/playwright-mcp) and [CLI](https://github.com/microsoft/playwright-cli): browser verification candidate. The official MCP README recommends considering CLI plus skills for coding workflows. Add persistent, cancellable sessions before enabling a browser MCP preset.
+
+Connecting ChatGPT or Claude **to Chode** requires a separately designed server with explicit exported tools and account permissions. This release makes Chode a client; it does not claim those products are connected. No paid service is an automatic fallback for free mode.
+
+## Wolfram Cloud
+
+Run `chode integrations setup wolfram --global` to connect the documented public endpoint `https://agenttools.wolfram.com/mcp`. [Wolfram's current documentation](https://www.wolfram.com/ai/mcp/cloud/wolfram-mcp-cloud/) identifies this service; the [support page](https://support.wolfram.com/75237) says no authentication is required. The older paid `services.wolfram.com` MCP service is separate and is not an automatic fallback. Hosted limits still apply.
+
+Standalone calculations go directly to WolframAlpha over MCP before any model call. For example, `chode ai "What is 7*8?"` returned 56 through the real endpoint with zero model calls on 29 October 2026. Use `/math <query>` in the TUI or `chode math <query>` to explicitly select this route. JSON usage records `modelCalls: 0`. It needs no account key or setup command; it uses the fixed public endpoint, with known credentials redacted before sending. `--no-tools` blocks computation. A Wolfram failure returns an incomplete result without spending a model call on a fallback. Automatic detection handles common standalone calculations, units and symbolic queries; explicit `/math` handles queries outside that classifier. Code/build requests still use the coding workflow; mathematical tool use inside a build retains its MCP permission checks.
+
+Chode discovers WolframContext, WolframLanguageEvaluator and WolframAlpha through its native MCP client. Live discovery, WolframAlpha and symbolic integration were verified on 29 October 2026. WolframContext returned an upstream HTTP504 during one live check; this service failure is reported as retryable unavailability, not a verified context result. Symbolic test: `Integrate[x^2, {x, 0, 3}]` returned `Out[1]= 9`. External outputs remain untrusted evidence. Resetting provider settings keeps MCP connections.
+
+## Coding engine direction
+
+Chode already calls model providers through their APIs. OpenCode is **not a dependency** and was not added as a builder. The chosen direction is direct API-backed generation: Chode owns the task, scoped requests, context, file operations, verification, repair and final delivery. Its current delegated workers use the same provider API layer and shared budget, with file ownership and free-only routing preserved. Adding another coding CLI is not needed for that workflow. Dedicated hosted builders can be evaluated later through documented APIs or MCP tools, but are not enabled or claimed here; an MCP transport alone does not improve model quality or remove provider limits.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MODELS-DEV-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 models.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROVIDER-CONNECTIONS.md

@@ -0,0 +1,48 @@
+# Provider connections and verification
+
+Chode includes 17 built-in routes and a searchable catalog of **184 connection profiles**: 181 cloud profiles from the MIT-licensed Models.dev snapshot and three local server presets (LM Studio, llama.cpp, vLLM). Some catalog names overlap built-ins or represent gateways/regions. This is broader connection coverage, not 184 independently verified companies or a claim of 10x free capacity.
+
+```sh
+chode providers
+chode providers huggingface
+chode connect agnes
+# In the TUI:
+/providers lmstudio
+/connect lmstudio
+/connect sambanova
+```
+
+`/connect` supports provider IDs, display names, numbered pages, `next`, `previous` and `search <text>`. Catalog connections show their endpoint and documentation before asking for a key. They are activated only after you explicitly save them. Live model discovery takes precedence; catalog models remain labelled as metadata when discovery is unavailable. A local preset requires your running server and installed model; choose custom if its address or authentication differs. The llama.cpp preset uses the documented native port 9931, not Docker's example port 8080.
+
+## Credentials and errors
+
+Provider setup saves credentials for your user account in `~/.chode/providers.json` and keeps key-free references in project configuration. New workspaces can use those settings. Older keys saved in `~/.chode/config.json` are read for compatibility without copying them into projects. Project-specific settings take precedence. Shared credentials are bound to user-saved endpoint definitions. A different project URL or authentication mode cannot inherit them; reconnect to confirm it. Unconfirmed project definitions cannot map arbitrary environment keys or activate a remote guest route. Existing project-only setup remains available to callers through `scope: 'project'`. Global defaults do not automatically disable strict free mode in a new project. Set `CHODE_PROVIDER_HOME` to an existing private directory for an isolated credential root (useful for tests or portable setups); this avoids changing operating-system profile variables used by browsers.
+
+Files use private POSIX permissions where supported and inherit the user's Windows directory ACLs. Keys remain unencrypted on disk. Secret paths and known credentials are excluded/redacted from tools and retained history; this is not an operating-system sandbox against arbitrary executable code. Do not commit `.chode` credentials.
+
+Agnes supports the documented `AGNES_API_KEY`, the legacy `CHODE_KEY`, and saved credentials. Explicitly saved keys override stale environment values. A copied `Bearer KEY` prefix is normalized. Reconnecting clears stale authentication suppression without resetting provider rate-limit cooldowns.
+
+Live diagnostic on 29 October 2026: the user's existing Agnes key successfully listed models (HTTP 200), but selected `agnes-2.5-pro-beta` returned HTTP 403 / `insufficient_user_quota`. This is an account/model quota condition, not proof of a malformed key. Setup now distinguishes authentication, quota, model access and missing-model errors. On access/quota failures you can choose another model, explicitly save an unverified connection, or cancel. Saving after a failed test is never labelled ready. No account quotas are bypassed.
+
+## Free access: verified distinctions
+
+- Strict free mode still uses keyless/local routes only. Catalog prices never automatically enable an account-key provider or paid fallback.
+- 55 cloud profiles list at least one zero-token-price model in the snapshot. That is metadata, not verified free account access, independent free vendors, unlimited usage or a quality ranking.
+- [OpenRouter's current free-model documentation](https://openrouter.ai/collections/free-models) provides free variants and a free-model router. Account/API-key requirements and rate limits still apply; its gateway is not dozens of separate Chode integrations.
+- [Hugging Face](https://huggingface.co/docs/inference-providers/pricing) documents small monthly credits for free accounts, with paid usage beyond those credits. This is a useful low-budget gateway, not unlimited free inference.
+- [SambaNova's plans page](https://cloud.sambanova.ai/plans) currently says to add a payment method and purchase credits for initial requests. Do not label it free based on older third-party lists.
+- [LM Studio](https://lmstudio.ai/docs/developer/openai-compat), [llama.cpp](https://github.com/ggml-org/llama.cpp/tree/master/tools/server) and [vLLM](https://docs.vllm.ai/en/latest/serving/online_serving/openai_compatible_server/) provide local API routes that avoid cloud request quotas. Model licenses and your hardware/resource costs still apply. No models are downloaded automatically.
+
+## Evidence and limits
+
+The snapshot records its source URL, retrieval time and SHA-256, with its MIT license preserved in `MODELS-DEV-LICENSE`. Unsupported cloud authentication protocols, providers without compatible endpoints, and Copilot session-token routes are excluded. The public installer hashes the catalog as part of the release.
+
+`tests/provider-directory.test.js` exercises every profile's setup and HTTP request format against a real local HTTP fixture, plus authentication precedence, shared credentials, corrupt-state preservation and free-mode isolation. These are protocol tests; they do not verify live credentials, billing or availability at every vendor.
+
+`tests/tui-command-matrix.test.js` drives all 37 registered commands through the real TUI input handler and actual worker subprocesses. It checks direct Wolfram math, builds, plan/task, retry/resume, checkpoints, undo, verification, quota-aware Agnes setup, hidden credentials, exports and terminal restoration. Model/account responses are controlled fixtures. `tests/native-workflow.py` adds actual Linux pseudo-terminal journeys for an installed package, including a local HTTP quota response. Existing native-startup, provider, browser, RE and other regression suites remain in place.
+
+No benchmark shows that all new providers are better than existing routes. Select and compare models under the same task/evaluator/budget before making a quality claim. Live authenticated vendor coverage remains limited to accounts that can be tested with authorized credentials.
+
+## Recover or reset
+
+Use `/free on` (or `chode free on`) to clear a forced account provider and save automatic keyless/local routing. Existing paid retries cannot override that explicit choice. Stop an active run with Ctrl+C first. `/reset` opens a menu for free-mode recovery, workspace settings reset, or workspace plus saved provider-key reset. CLI equivalents are `chode reset --confirm` and `chode reset --providers --confirm`. Project files, history, checkpoints and MCP connections are kept. Reset creates private backups, which can contain previous credentials; environment variables remain unchanged.

package/PROVIDERS.md

@@ -0,0 +1,17 @@
+# Provider and model setup
+
+Run `chode connect` or `/connect` to choose a built-in provider, or add a custom OpenAI-compatible endpoint. Credentials are shared across your workspaces in user configuration, with key-free project references and masked input is excluded from chat/history/export. Account providers still need their own authorized key; OpenRouter's existing browser authorization flow remains available.
+
+The model picker supports `next`, `previous`, `search <text>`, an on-page number or an exact model ID. Enter `current` to retain the saved model. Only the chosen ID is saved: display labels never become request model names. Discovery failure still permits manual entry. An optional connection test validates access before saving.
+
+Models with explicitly zero prompt/completion prices and no other listed charge sort first, followed by advertised tool support. Missing, malformed, negative or partial price metadata never establishes a zero price. Labels describe the provider's catalog response, not measured coding ability. Quotas, eligibility, availability and prices can change. Unknown models remain selectable; verify provider terms before use.
+
+Tool/structured-output support and context size appear only when reported in recognized metadata fields. They are informative; selecting a model does not enable an unsupported protocol or change the harness's established tool handling. Discovery is bounded to 500 distinct valid IDs and 5,000 input entries, with 20 models per page.
+
+Changing models does not reset provider cooldowns, shared account/IP quotas or circuit breakers. Strict free mode continues to allow only keyless/local providers without credentials; a zero-price listing on an account provider does not make that provider eligible. No paid fallback or automatic account provisioning is introduced.
+
+For local inference, see LOCAL-MODELS.md. No model downloads happen automatically.
+
+Provider setup requests (discovery, connection tests and OAuth exchange) have a ten-second total deadline, including response body consumption, and a 4 MB response limit. Oversized or invalid JSON fails safely; a failed connection test never automatically saves settings; quota/access failures offer an explicit unverified-save option. Discovery failure still allows deliberate manual model entry. Cancellation and even a misbehaving response reader cannot block the setup flow indefinitely.
+
+For the expanded catalog, shared credential storage, Agnes quota diagnostics and current test coverage, see [PROVIDER-CONNECTIONS.md](PROVIDER-CONNECTIONS.md).