connecta: Instructions file for Codex

Working on connecta

This is the canonical agent instruction file. CLAUDE.md is its symlink; keep it that way. Connecta aggregates remote MCP servers and HTTP APIs behind one MCP endpoint. Agents use JavaScript through execute_code, with direct calls for known operations and writes. One fetch-native core runs on Node and Cloudflare Workers, with Effect inside and Promises at the published edge. Read PRINCIPLES.md before changing a subsystem, then use the agent documentation index to select the task guide and contract sections. Architecture maps the implementation; subsystem source and tests establish current behavior. README.md owns the short human-facing product overview and setup handoff. guides/ owns human-facing explanations of the mental model, agent connections, and safety. Keep exact behavior, configuration references, contracts, and runnable deployment setup in agent docs. This file owns repository policy; scoped skills and provider guides own their task-specific detail. Update the owning contract when changing behavior, and keep the README and explanatory guides consistent without adding a configuration reference. The completed rework plan of record #703 records owner decisions that supersede older guidance wherever they conflict. decisions/ explains past choices without binding later PRs. spec/coverage.json records current MCP support, gaps, and test evidence. Describe planned work as planned, not shipped behavior. The roadmap lives in GitHub issues: file new work with motivation, behavior, and acceptance criteria, not a TODO.md.

Shipped documentation audience

Write documentation/, templates/, and examples/worker/ first for an agent operating a deployment from the installed package. Route operator tasks through node_modules/@zackbart/connecta/documentation/README.md. Write README.md and guides/ for people: short, explanatory, and visual. Guides may illustrate a concept with a small example, but own no contracts or complete setup procedures; link to documentation/ for those and keep the explanations consistent with it. guides/ ships in the npm package so README links also work for installed-package readers. The same neutral-name rule below applies to the README and guides. State every operator convention as self-contained rules with a neutral example; decision records and issues may explain why, never supply required steps. decisions/, spec/, and .claude/ do not ship. Separate contributor-only source maps, INV citations, and implementation/test evidence under clearly labeled contributor headings; operator tasks must not need them. Use neutral names (assistant, alice, bob, crm, tickets, notes_alice, [email protected]), never real deployments, clients, people, or organizations. Maintained provider product names remain valid.