Skip to main content

​
Before you start

  1. Read the root README.md and the relevant docs/ design and check notes.
  2. Search for existing facades, DTOs, reducers, and platform adapters before you decide you need a new abstraction.
  3. Preserve existing uncommitted changes in the working tree; do not overwrite other people’s files.

​
Implementation principles

  • Keep DesktopRuntime as the single authoritative state owner.
  • Expose new capabilities through BackendFacade so they work for both the embedded runtime and a paired remote runtime.
  • Have clients reach capabilities through the shared backend and Remote v2 contracts, without duplicating business state.
  • Use structured errors, capabilities, and sequence numbers; do not infer success from UI copy.
  • Check and audit permissions for file, Git, terminal, provider, and device operations.
  • Redact logs, test evidence, and diagnostics; never write keys, prompts, file contents, or terminal bytes into them.

​
Pre-submit checks

Add the matching script for the area you changed:
pnpm check:acp, pnpm check:code-workbench, pnpm check:terminal, and pnpm check:all do not exist — use the real scripts in the table above. See Build and test for the full list.
Cross-layer changes should cover disconnect, restart, insufficient permission, sequence gaps, and recovery paths.

​
Documentation and evidence

User-visible behavior must update the Simplified Chinese, Traditional Chinese, and English pages together. Mark implementation details you cannot confirm with TODO, and do not document a feature that exists only in a code path but is unreachable for users — if an entry point is not open yet, do not mention it in the documentation. Explain behavior with written steps, state tables, protocol fields, and redacted diagnostic records; do not require visual captures, and do not submit workspace contents as evidence.

​
Documentation site maintenance

  • The version number lives in snippets/release.mdx. Do not hard-code a version in a page. When you publish a release, change only that file.
  • Download and release links point to the GitHub Releases latest page, which resolves to the newest version automatically.
  • User interface copy is defined by apps/desktop/src/locale.rs; keep documentation wording consistent with it.

​
Pull requests

Describe the behavior change, ownership boundaries, test commands, and known limitations. If you change a protocol or a persistence format, explain the compatibility, migration, and rollback strategy. Open issues and pull requests on GitHub.