AGENTS.md git:20261023.b4ac944A

Immutable. This exact content never changes and is served at /api/v1/blob/9ebc4ca618fb87ca.

# Development conventions

MUST means a requirement. SHOULD means the default unless a concrete task-specific reason justifies an exception. MAY means an option.

- Use the MIT license. Maintain public source and desktop artifacts on GitHub. Do not publish a public npm package.
- Assess whether commits and pushes are necessary for the task. No separate authorization is required. Commit and push directly when needed to complete the task. Respect explicit restrictions against committing or pushing, or requests to wait for review. Release tags, uploads, and public Releases require user authorization.
- Support macOS and Windows desktops and headless Linux x86_64/aarch64. Business code MUST NOT depend on other projects or personal environments. Use Tauri and Rust for the native desktop. Node/npm are build tools only. The product owns local Tunnel Client installation, configuration, and lifecycle. Use official Tunnel identity registration and servers.
- Never use Git worktree. Purposeful one-time state migrations are allowed. Delete old files after migration. Do not retain obsolete aliases, shims, or compatibility layers.
- The control-source MCP tools are frozen as `guide`, `query`, and `act`. Do not rename, remove, or change their parameter structures, including optional additions. Sessions with cached schemas use the query guide op for current contracts. Expose capability changes through catalog ops and guide. Do not add MCP tools or old-tool aliases. Ops may be replaced or removed directly. Errors MUST guide clients to the current contract.
- The MCP event surface is frozen as the single `notification` event with subscription parameters `{op, args}`. Do not rename it or change the outer structure, including optional additions. Disclose event ops and args through guide. The server validates, authorizes, and filters by op. Ops may be replaced or removed. Errors MUST identify the current contract. Do not retain old event names or compatibility aliases.
- Read external data using current native login and upstream responses. Do not add account, credential-expiry, or content-sensitivity checks. Do not reject reads or rewrite results based on local inference. Retain checks required for ARC's own MCP OAuth, ingress authorization, task association, and resource boundaries.
- Allow only `Contract` tests for frozen surfaces (`guide`/`query`/`act`, `notification`, CLI JSON envelopes, error codes and wire formats), `Regression` tests naming a fixing commit or observed failure, and `Property` tests for pure-computation invariants. Every test case MUST carry exactly one `// Contract: ...`, `// Regression: <commit|symptom>` or `// Property: <invariant>` comment, including Rust cases.
- Tests MUST assert observable behavior through MCP ops, CLI, management ops, exported pure functions or accessible roles/names. Never assert class names, DOM shape, computed styles, pixel constants, exact user-facing copy, internal file layouts or mock call counts.
- When an intended product change breaks a test, rewrite it at the behavior level or delete it and report which. Never align expected values with new implementation details. Delete a test that blocks a reasonable refactor instead of working around it.
- The control source owns `tests/contract/` and `tooling/test-policy-allowlist.json`. Implementation turns MUST NOT modify either unless the dispatch prompt explicitly grants it. Exceptions require an exact file, test name, rule and reason in that allowlist.
- Run `npm run check:tests` before tests. Visual/layout correctness belongs to `npm run accept:ui` scenarios, not unit tests.
- After direct Cargo builds or tests, run `npm run cache:prune` to check the compilation-cache budget.
- Commit messages MUST use Conventional Commits with an English single-line subject: `type(scope): description`. Allowed types are feat, fix, docs, refactor, test, build, ci, chore, perf, and revert. Do not write a body or rewrite history. A required Git trailer may follow one blank line.
- Keep personal paths, project names, accounts, secrets, Tunnel identities, quota details, and real task content out of the repository. Personal dispatch criteria belong in local state configuration.
- Documentation describes current features, architecture, limits, and procedures. Do not store process records, acceptance results, decision logs, or personal environment details.

## Language and terminology

- Model-facing text and AI-maintainer text MUST be English only. Keep no Chinese copies. This includes every control-source guide and topic, catalog descriptions and signatures, schema descriptions, receipt hints, errors and correction examples, notification/event text, `docs/dev/**`, and this file.
- Product UI, promotional documentation, and end-user onboarding documentation remain localized. Preserve Chinese user input and original upstream evidence.
- Use the fixed vocabulary in [terminology](docs/dev/terminology.md). Define MUST, SHOULD, and MAY once at the top of each guide response. Use one rule per sentence.

## UI components

- Use `SingleChoice` for every single-choice control. Use pill tabs with at most five options when width permits. Otherwise use a dropdown. Do not add standalone Select, native `select`, or duplicate single-choice styling in business pages. Configure themes centrally. Preserve keyboard navigation, disabled states, and validation.
- Use React for rendering. Reuse `ui/components/ui/index.tsx` for shared controls and Radix for complex interactions. Do not reimplement equivalent controls in business pages.
- Define semantic tokens in `ui/tokens.css`. Manage light/dark state in `ui/theme.ts`, following the system by default. Use the shared `Icon` wrapper with Lucide at 16/20px and 1.75px strokes. Retain brand-specific assets.
- Reuse `Dialog` for editing. Use native `form` with shared `Field`/`Input`. Default to one column with labels above inputs. Only short, related fields may share a row. Associate validation errors with their fields. Focus the first error after failed submission. Restore trigger focus after closing an overlay.
- The homepage uses the ARC mark and earcup connections. Preserve topology, spatial transitions for expanded node panels, and simplified tactile toggles. Functional pages use quiet, compact, consistent layouts. Keep workspace-panel title bars at the top. Opening and closing use only fades and slight movement of at most 180ms. Nested views switch content without morphing the whole panel. Related tooltips remain visible while smoothly moving and resizing. Hover highlights use the shared spring-following layer. Preserve reduced motion, keyboard navigation, layered Escape, and focus restoration. Radix owns common interaction foundations. Layout components only arrange content and do not duplicate input/button styles. See [UI](docs/dev/ui.md).
- Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.

## Documentation layers

- Promotional: keep README.md and README.zh-CN.md short and centered on Claude + Codex Loop and ChatGPT Chat + Codex.
- Onboarding and guides: docs/getting-started.md, concepts.md, guides/, auto-setup.md, faq.md, installation.md, and story.md have English primary files and complete matching Chinese versions under docs/zh-CN/. Keep them synchronized.
- Reference: docs/reference/ is English only. It owns precise contracts for tools, Agents, CLI, OAuth, Linux, and subscriptions.
- Maintainer: docs/dev/ is English only. It describes development, releases, architecture, and UI. Internal lifecycle belongs in architecture.
- Organize user guides by task. Use short sentences and lead with actions. Collect real limitations at the end under Limits or the localized equivalent. Avoid repeated defensive explanations.
- Current source, cli help, and cli guide are authoritative. Path changes MUST update internal links, application/CLI URLs, and README Agent prompts. cli guide embeds docs/reference/cli.md.