Imported from Huzaifa-Shahid-6ll/orbit (apps/desktop/AGENTS.md). Install upstream with npx skills add Huzaifa-Shahid-6ll/orbit --skill desktop. Copyright stays with the author.

apps/desktop DOX

Purpose

• Owns: L1-lite Tauri 2.0 desktop shell, desktop TypeScript, Rust commands, capabilities, fixtures, and audits.
• Nearest binding work contract for this subtree.
• Read with every parent AGENTS.md before editing.
• Keep work understandable from durable files.
• Preserve root stack constraints.
• Current scope is LAYER 1 or L1-lite.
• Stop before scaffolding L2 or L3 work.
• Prefer named durable artifacts.
• Update this file when local behavior changes.

Ownership

• Scope path: $dir/.
• Contract file: $n.
• Owns local source materials.
• Owns local tests.
• Owns local durable docs.
• Owns local config.
• Does not own vendor directories.
• Does not own build output.
• Does not own temporary runtime files.
• This file adds local operational context.
• Child AGENTS.md files own registered subtrees.
• Update indexes when child contracts move.

Local Contracts

• Do not weaken root security rules.
• Do not bypass spec gates.
• Do not cross app ownership boundaries.
• Do not call provider APIs directly.
• Route LLM traffic through LiteLLM.
• Do not use raw LLM text in control flow.
• Use Zod schemas for generated control data.
• Do not log API keys.
• Do not log bearer tokens.
• Do not log decrypted credentials.
• Do not add libraries when locked stack suffices.
• Do not scaffold L2 or L3 work.
• Keep edits scoped to this owner.
• Update docs when purpose changes.
• Update docs when side effects change.
• Remove stale guidance immediately.

Work Guidance

• Read the DOX chain first.
• Use rg for search.
• Follow local patterns before abstractions.
• Prefer typed inputs.
• Prefer typed outputs.
• Validate external input at boundaries.
• Keep comments sparse and useful.
• Preserve unrelated user changes.
• Never revert dirty files you did not create.
• Put reusable business logic in packages.
• Keep app code focused on routing and transport.
• Keep tests near changed behavior.
• Cover risky branches first.
• Document breaking API changes.
• Root pnpm dev includes desktop and the local Inngest Dev Server.
• Tauri owns starting the desktop web surface through beforeDevCommand.
• Keep desktop web development on port 3001 so it can run beside the normal web dev server on port 3000.
• Desktop dev URL is http://localhost:3001/dashboard?source_surface=desktop.
• Hosted beta builds load an HTTPS web URL with source_surface=desktop; hosted URLs are configuration, not secrets.
• Keep desktop CSP narrow: allow the local desktop dev origin and approved hosted HTTPS web origin only; do not broaden CSP to reach DB, Redis, LiteLLM, provider, shell, filesystem, or worker/API internals directly.
• Tauri commands may only expose thin-shell behavior: show, hide, focus, quit, safe notification display, and safe-route focus from notification clicks.
• Desktop must preserve the same Better Auth/API path as web and must not add a desktop-specific auth or data path.
• Create child AGENTS.md for independent rules.
• Refresh child indexes after structure changes.

Project Context

• Runtime is Bun.
• Package manager is pnpm.
• Monorepo orchestration is Turborepo.
• Language is TypeScript 5 strict.
• Web framework is Next.js 16 App Router.
• API runtime uses Hono.
• Worker runtime uses Inngest serve/connect.
• PostgreSQL service is Supabase with pgvector.
• Local infra is Docker Compose.
• Web deploy target is Vercel.
• API and worker deploy to Railway.
• apps/web must not directly touch DB.
• apps/api must not import apps/worker.
• apps/worker must not import apps/api.
• packages/scheduler owns Inngest definitions.
• packages/db owns schema and migrations.

Inputs And Outputs

• Inputs include source files.
• Inputs include specs.
• Inputs include plans.
• Inputs include tests.
• Inputs include durable docs.
• Outputs include changed source.
• Outputs include changed docs.
• Outputs include changed tests.
• Outputs include verification results.
• Do not treat caches as durable outputs.
• Redact secrets from examples.
• Use environment variable names instead of secret values.
• Connect behavior changes to specs.

Safety And Boundaries

• Never commit .env secrets.
• Never print full environment dumps.
• Never store decrypted credentials in docs.
• Never store decrypted credentials in tests.
• Never weaken auth to make tests pass.
• Never weaken webhook verification to make tests pass.
• Never weaken budget caps to make tests pass.
• Never weaken auditability to make tests pass.
• Never import generated build output as source.
• Never add broad utilities where a domain owner exists.
• Never delete unrelated user work.
• Never hide failed verification.
• Never leave contradictory guidance.
• Never assume unlisted child contracts exist.

Verification

• For docs-only changes, run Prettier on changed Markdown.
• For code changes, run nearest package or app checks.
• For shared impact, run root pnpm check when feasible.
• Report every verification command run.
• Report every verification failure.
• Report commands intentionally skipped.
• Use E2E tests when browser workflows change.
• Use db checks when schema changes.
• Use Docker validation when containers change.

DOX Closeout Checklist

• Re-read this file after edits.
• Re-read every parent AGENTS.md after edits.
• Confirm purpose still matches contents.
• Confirm ownership still matches contents.
• Confirm local contracts still match behavior.
• Refresh this Child DOX Index when children change.
• Refresh parent indexes when this file moves.
• Refresh parent indexes when this file is added.
• Update child docs when parent rules affect them.
• Remove stale text.
• Remove contradictory text.
• Run relevant verification.
• Document skipped verification.
• Leave unrelated dirty files untouched.
• Keep final reporting specific.
• Keep context dense and operational.
• Package/app typecheck: pnpm --filter @orbit/desktop typecheck.
• Package/app test: pnpm --filter @orbit/desktop test.
• Package/app build: pnpm --filter @orbit/desktop build when output changes.
• Desktop audit: pnpm --filter @orbit/desktop audit.
• Tauri check: pnpm --filter @orbit/desktop tauri:check.

Child DOX Index

• No child AGENTS.md files are currently registered below this scope.

Generated And Ignored Local State

• node_modules is not a durable DOX boundary.
• .git is not a durable DOX boundary.
• .next is not a durable DOX boundary.
• dist is not a durable DOX boundary.
• target is not a durable DOX boundary.
• Do not add child contracts under generated folders.
• Document generators before relying on generated artifacts.

Line Budget

• This non-root DOX file must stay above 100 lines and below 200 lines.
• Keep context dense, specific, and operational.