RFD 0071 — Agent-tooling distribution: the agents/ tree, the ~/.argon/.agents/ home, and oxup registration
- State: committed (ratified 2026-07-09)
- Provenance: transcribes owner-ratified decisions plus a precedent-traced survey of agent-ecosystem install conventions (per-host registration surfaces inspected empirically on live installs; installer precedents from shipped tools). A record of decided design, not a new decision.
Summary
Argon ships an MCP server (ox mcp) and a four-valued epistemic discipline for coding agents. This RFD records how that tooling is organized in-repo and installed onto a developer machine so that any supported agent host picks it up with no manual file copying and no repo access — oxup does it end to end.
Motivation
The initial per-host packages required a user to copy config + rules files by hand out of the repo. That is the wrong end state: users should not touch the repo, and installation must be idempotent, uninstallable, and upgrade-proof. The agent ecosystem has converged on conventions (a vendor-neutral skills home, per-host MCP config, the AGENTS.md rules standard) that a first-class installer should follow rather than reinvent.
Decisions
1. In-repo layout — top-level agents/
Agent tooling is host-neutral and lives at the top level in agents/, not under editors/ (which is for editor LSP clients). One package per host as peers — agents/{claude,codex,cursor,opencode,vscode}/ — plus the single source agents/argon-discipline.md. Claude Code is one host among peers, not special-cased outside the tree. Each host’s rules file is generated from the single source and drift-gated (cargo xtask gen / check-drift); no consumer is hand-mirrored.
2. Central artifact home — ~/.argon/.agents/
oxup owns ~/.argon/.agents/ as the canonical on-machine artifact home (skill body, rules texts, MCP fragments), regenerated wholesale on oxup update (the embedded-assets pattern already used for the Claude plugin). All host registrations point INTO this home, so an upgrade refreshes one place with zero re-registration.
3. Skills — one symlink covers three hosts
The ecosystem’s vendor-neutral skills home is ~/.agents/skills/ (read natively by codex, cursor, opencode, and ~70 agents; symlink-by-default is the established install convention). oxup creates a single symlink ~/.agents/skills/argon -> ~/.argon/.agents/skills/argon. Claude Code does not yet read ~/.agents/skills and keeps its existing plugin path; it is not double-installed.
4. MCP registration — per host, host-native mechanism, PATH shim
The MCP command is always the PATH shim ox (ox mcp), never a versioned absolute path, so upgrades need no re-registration. Per host: use the host’s own registration CLI where it exists (codex codex mcp add; VS Code code --add-mcp when a genuine VS Code — not a fork — is detected); otherwise a parse-preserving merge of only Argon’s own key into the host’s config, preserving all foreign bytes (cursor ~/.cursor/mcp.json mcpServers.argon, which has no add CLI; opencode via its CLI or a parse-preserving JSONC merge, refusing loudly rather than corrupting a JSONC/symlinked config). Claude keeps the plugin’s own .mcp.json.
5. Rules — project vs global
Project mode appends a sentinel-delimited block to AGENTS.md (the de-facto cross-host standard: codex/cursor/opencode/Copilot all read it) plus the CLAUDE.md @AGENTS.md bridge for Claude (which reads only CLAUDE.md). Global mode is the default for a toolchain and prefers NO user-file writes — the discipline floor already rides the MCP tool descriptions + server instructions + the skill; if a global rules file is written at all, it is a sentinel block only, never a whole-file write (a whole-file write clobbers user content).
6. LSP per host — full parity, host limitations owned by the host
Feature parity per host is the requirement; no host is favored. Claude via its plugin .lsp.json; opencode via its config lsp.argon key (command:["ox","lsp"], extensions:[".ar"]) merged alongside MCP; Cursor and VS Code via the editor extension oxup already installs. codex has no LSP surface today — that is the host’s limitation, documented as such, with the MCP argon_check tool wired as the equivalent diagnostics channel; the cell is revisited as the host evolves.
7. Idempotency, receipts, uninstall
Plan→apply with merge-only-own-keys and foreign bytes preserved. A receipts file under ~/.argon/.agents/ records every touched host file so oxup agents unregister removes exactly those. Sentinel blocks for prose files; key-scoped merge for structured configs (never a sentinel inside JSON/TOML/JSONC). Pre-existing same-name user entries are respected. A non-interactive -y mode is provided.
Verification posture
Each cell is marked EMPIRICAL or DOCS-ONLY. Unverified lanes take the conservative verified path rather than blocking: VS Code --add-mcp fork semantics (DOCS — skip-with-message unless a genuine install is detected), opencode CLI write behavior (prefer parse-preserving merge / refuse loudly), and whether any Cursor surface reads ~/.cursor/rules/ (drop that target; rely on .cursor/rules/*.mdc project rules and AGENTS.md). These are tracked as open questions to close as installs become available, not gates on shipping.
Alternatives considered
A GUI one-click bundle (MCPB/.mcpb) and the remote MCP registry (server.json) are discovery/marketplace mechanisms, not local-install for a toolchain-owned stdio server; they do not replace per-host config writes. A single “write every host’s config” rewrite is rejected — it would clobber foreign content; merge-only-own-keys with receipts is the accepted practice across shipped installers (host-config mergers, the vendor-neutral skills installer, and the in-house Claude-plugin installer).