claude-skill: Instructions file for Codex

Agent notes — this repo is the canonical shared knowledge source

All agent-facing knowledge about the Axiom MCP tools and APIs has ONE canonical home: plugins/axiom/skills/axiom/references/ in this repo — tool manuals under tools/, the @axiom_ai/api surface + method allowlists, the action vocabulary, and the shared browser-automation rules. Two audiences consume it:

• Desktop Claude users — via the axiom skill itself.
• The OpenHands configure agent — via GENERATED copies: the backend's embedded agent tools (in every agent conversation's system prompt) and the agent sandbox image's tools-*.md + AXIOM_AGENT_SKILL.md (built from a template that pulls shared prose with <!-- INCLUDE <references-path> --> markers).

Rules when editing knowledge here:

• Never edit a synced or generated copy in the consumer repos (each carries a do-not-edit banner). Edit the canon here — or the sandbox template, for OpenHands-runtime-specific prose. The consumers are regenerated by the maintainers' sync step, which writes into the backend and infrastructure repositories: that is a deliberate OpenHands deploy step on those repos' own branches, NOT something to run as part of an edit here (this skill also ships to the desktop app on its own). --check reporting drift until that deploy is the expected state.
• Content true for BOTH audiences belongs in references/; only runtime-specific prose stays in an actor file or template. The desktop skill's account-setup/key-minting content must NEVER flow to the OpenHands agent (its credential is an injected job-scoped secret).
• A canon edit has deploy costs: lar deploy (new conversations embed it; parked warm slots self-invalidate via prompt_hash) and a sandbox image rebake for on-disk copies. Batch edits; bump the version in package.json and add a CHANGELOG entry — consumers pin to it.
• references/action-vocabulary.json is GENERATED, never hand-edited: npm run build:vocabulary derives it from the widget catalogue axiom_mcp ships (its nested axiom_builder_ir submodule, not the sibling checkout of the same repo). Run it whenever that pin moves — otherwise agents author widgets compile_ir rejects as unknown, and never learn about new ones. npm run build:vocabulary:check is the drift detector and runs in the test suite, so CI catches a stale file on its own. Fields this repo adds on top of the source (WidgetBotCreate's isLooping/afterLoopUpdate) are carried forward by the generator. Its schema is also an API: axiom_mcp's list_actions reads the same catalogue.
• Verify headlessly before shipping: npm run verify — the single gate (generated-copy drift check + lint + the full jest suite; no network, no key). A change here isn't done until it's green.
• Agent precedence, by design: job brief > actor skill > tool manuals. Brief-level policy (never-invent user values, ask-on-ambiguity) lives in the backend's agent job brief, not here.