Agent documentation¶
This section holds the detailed reference for coding agents and maintainers. Human-facing instructions belong in the short user guides.
Instructions and status¶
Read the repository's AGENTS.md before changing code. It is the authoritative source for development rules, data-safety invariants, authorization boundaries and quality gates; this site does not replace it.
- Completion audit: implemented evidence, active work and remaining product gaps.
- Performance evidence: budgets, methodology and limits of the measured results.
- Search matching: selected abbreviation matching, examples and comparison evidence.
- Native E2E skill: isolated MCP scenarios and required automated equivalents.
Detailed reference¶
- Development and architecture: commands, release setup, worker boundaries and extension points.
- Immediate actions proposal: a common lifecycle for instant local feedback, durable background work, Undo and safe failure recovery; awaiting review.
- Installation: installer options, platform services and asset conventions.
- Flatpak and Linux stores: the prepared Flathub manifest, permissions, offline Cargo sources and other store options.
- Mail: navigation, drafts, delivery recovery, Sent copies and reading behavior.
- Calendar: discovery, access, write acknowledgments, conflicts and connection removal.
- Google and backups: authorization, destination identity, scheduling, resumable uploads and additive restore.
- Google sign-in client: Shep's compiled-in Desktop OAuth client, build variables, self-configured grants and the Google Cloud setup.
- Multiple backup destinations: several local, S3/SFTP/FTP and Google Drive destinations with independent schedules, retention and passphrases.
- Local cache encryption: SQLCipher device keys, staged migration and recovery boundaries (in progress).
- Database transfer and profiles: staged import, local profile selection, credential isolation and the desktop profile sync implementation.
- Profile Drive records: shared metadata transport, durable pagination and immutable upload recovery.
- Profile metadata format and current limits.
- Local profile history: causal merge, durable upload identities, native worker/bridge and remaining enrollment work.
- Google profile files: verified identity, bounded file pages and immutable upload recovery from the shared crates.
- Durable profile discovery: saved scans, change replay and isolated remote summaries.
- Desktop profile discovery: active Google grant, durable scans and read-only iced controls; the desktop implementation now arrives from
main. - Desktop reconciliation engine: bounded ongoing preference reconciliation and its Flutter/browser equivalents.
- Mobile Google connection: platform Google Sign-In packages, stored bindings and cleanup state.
- Flutter profile discovery: saved Google binding, native session ownership and real discovery controls; reviewed Flutter enrollment is connected.
- Flutter profile publication: frozen reviews, initialized setup, immutable upload receipts and pause/retry controls.
- Flutter profile enrollment: independent device history, reviewed account/preferences application and credential reconnect boundaries.
- Browser profiles and sync: server-mediated Google consent, worker-owned WASM history, per-identity storage, discovery, reviewed publication/enrollment and onboarding.
- Profile sync handover: next-priority OAuth, Rust/Flutter enrollment, portable records, conflicts and verification requirements; implementation remains open.
- Browser group actions: abandoned-review cleanup, the wider Undo lifecycle and the desktop-matching review keys.
- Mobile group actions: native selection controls over the SQLite capture and the durable Flutter group journal with receipts, Undo, History and recovery.
- Limits: protocol requirements, storage ceilings and unverified behavior.
Documentation maintenance¶
User pages should answer the next practical question in plain language. Preserve longer implementation details here, and keep the completion audit explicit about fixture coverage versus live-provider verification.
zensical.toml defines navigation. requirements-docs.txt pins the builder. docs/images/ contains approved WebP assets for both the README and site. Screenshots must use isolated fictional fixtures, never personal inboxes.
Recreate the screenshot scenarios with:
cargo build --profile test-ui --features test-support
python3 scripts/e2e.py NativeFlows.test_documentation_screenshots
Review docs-mail-light.webp and docs-calendar-dark.webp under the printed artifacts/e2e/<run>/ directory before copying them into docs/images/ as mail-light.webp and calendar-dark.webp. The saved flow moves the pointer away from controls so tooltips do not cover the app. These captures prove native layout only; they do not verify live services.
The Documentation workflow is the only enabled workflow. It builds on GitHub-hosted Linux and deploys main through GitHub Pages. Keep the quality and release .yml.disabled files dormant until explicitly authorized to enable them.
GitHub Pages must be created with build_type=workflow. Private repositories require a plan that supports Pages; GitHub rejects setup with HTTP 422 otherwise. Do not change repository visibility to bypass this restriction without the user's explicit authorization. Once the account supports Pages, an administrator can configure it and dispatch the workflow: