AGENTS.md

• This is Ork, derived from Rakazo. Follow README.md for local setup; README.reference.md contains the adapted reference. Use Ork for display names, orkbot for technical identifiers and @orkbot/* packages, and ork.run for the public domain. Preserve original copyright attribution, historical migration SQL, and compatibility identifiers for persisted data and cryptography.
• Follow LICENSE.md for license scope. Preserve LICENSE byte-for-byte, the Apache baseline, and all upstream and third-party notices. New original Ork files require an SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0 header and copyright attribution. Use an adjacent .license sidecar for JSON and binary files. Never relabel imported code as Ork-owned. Mark changes to inherited files and identify the inherited Apache material separately from new PolyForm-covered changes. Update package license metadata when its contents become mixed, and run pnpm licenses:check and pnpm test:licenses. Describe the combined product as source-available. Do not promise a blanket free-business exemption, revoke earlier Apache grants, claim legal approval, activate the draft CLA, or publish the transition before the rollout requirements in docs/licensing-rollout.md are met.
• All workflows live in .github/workflows/; workflow-definition tests read the active files. Standard CI, reports, and diagnostic native artifacts use GitHub infrastructure. Store submissions, signed releases, OTA, hosted report galleries, production deployment, and AI dependency updates require the Ork-owned configuration documented in docs/github-actions.md.
• This is a public repository: assume all tracked content and diffs are public. Never commit secrets, .env files, private URLs, personal/customer data, or real production data; use fake placeholders. Review git status and the staged diff before committing, and never force-add ignored files. If private data appears, stop and alert the maintainer.
• Ork runs in Tauri desktop and Expo mobile apps. Tauri hosts the shared web renderer; it is not a standalone browser product. Browser pages only hand off a server connection to a native app or finish an existing protocol callback, without product login or app screens. Put shared behavior, contracts, API logic, and reusable UI in packages. Keep only genuinely native navigation, storage, permissions, and interactions platform-specific. Core workflows must cover both native surfaces or degrade safely for an explicit reason.
• No hosted vendor is required to run the core product. Keep LLMs, sandboxes, memory, voice, integrations, and future external services optional and behind provider-neutral interfaces. Vendor SDKs, configuration, and translation belong only in adapters and composition roots. Vendor names never appear outside them either: not in shared contracts, settings, database columns, routes, UI, or copy, even when only one provider supports a feature today. New providers must reuse shared contracts and deterministic offline conformance tests. Packages most users won't need must load via dynamic import() only when configured, and must be a reputable package or the vendor's direct API from a trusted, established brand (not, say, a brand-new startup's sandbox).
• Keep UI and copy minimal. Show advanced capability progressively and only when it becomes relevant; do not add explainer text that repeats the interface. Frontends express intent and render state; the backend owns orchestration, authorization, validation, retries, recovery, and provider translation. Give controls concise accessible names when needed.
• Treat every visible word as UI. Start UX work by asking what can be removed, and prefer progressive disclosure over persistent explanation or status chrome. If a PR adds user-facing copy, its description must quote the copy, explain why it is necessary, and say why removing it or revealing it only when relevant would not work.
• Configure compatible providers and models through shared connection settings and standard protocol capabilities; never add provider- or model-specific environment variables when the generic connection can express the behavior.
• Use top-level import type, never inline type imports. Reserve dynamic import() for necessary deferred loading.
• For API placement, module boundaries, import aliases, and test commands, follow apps/api/AGENTS.md.
• Keep code simple: reuse existing primitives and one source of truth, remove duplication and unused flexibility, and avoid speculative abstractions. Add an interface when it protects a real external or platform boundary, not for its own sake. A provider-neutral interface always counts as a real boundary.
• Production deploys keep the previous release running after migrations apply (the old API for a few seconds, the old worker until its running jobs finish), so every migration must keep working with the previous release's code. Adding tables and columns is safe. To drop one, remove it from the Prisma schema and code and, in the same PR, add a migration whose first line is -- deferred: the migrate command holds it back for one run, so it applies on the next deploy, once nothing running reads it. A dropped column must be nullable or have a default while it waits; relax it in an ordinary migration in the same PR if needed. Rename by adding and backfilling the new column, switching the code, and dropping the old one deferred.
• Build for many concurrent users across several instances. Work that waits on the network (agent runs, jobs, deliveries) starts as soon as it arrives: never put it behind a global slot count, a single-flight loop, or a queue hop on the hot path. Limit only the specific resource that needs it (one bot, one computer, one provider's rate limit) so unrelated work never waits, and coordinate across processes through Postgres claims and leases.
• Treat auth, secret handling, sandbox boundaries, host commands, and integrations as security-sensitive. Keep tests deterministic and offline by default.
• Judge natural-language meaning and factual claims with an LLM and an explicit, versioned rubric calibrated against reviewed examples; do not grade free-form prose with keyword lists, regexes, or exact wording. Keep deterministic assertions for observable effects and structured output contracts. Keep judge calls opt-in and provider-neutral, report their cost separately, and treat judge errors as unqualified results rather than passes.
• Desktop development and native screenshot checks open real windows and can steal focus on macOS. Do not launch them on a maintainer's machine as routine verification. Run the desktop TypeScript and Rust tests locally, and use the manual native screenshot workflow when an interactive check is needed.
• Marketing pages (the Astro site in apps/www) don't need new tests or CI screenshots beyond the existing homepage screenshot suite, and may name third-party vendors and providers; the product's rules on vendor names and UI tests don't apply there. Check those changes visually and with a build.
• Do not edit CHANGELOG.md in feature pull requests; the release skill (.agents/skills/release/SKILL.md) writes it from merged pull requests when a version is cut, so write the PR's ## What and ## Risk for that reader.
• After creating a pull request, stay with it until CI and automated review bots have finished; passing checks alone do not mean the review is complete. Follow .agents/skills/pr-watch/SKILL.md: run its pr-digest --watch helper as a single backgrounded call that blocks until a new review comment or check failure arrives or the checks on the current head commit are terminal, then act on the verdict it prints and watch again. Do not poll in the foreground on a timer, which mostly buys repeated snapshots of an unchanged PR and dies at the tool timeout. Address every actionable issue, push the fixes, and repeat until no actionable feedback remains. Do not merge while review bots are still pending or review issues remain unresolved.
• Ignore the Vercel "Authorization required to deploy" failure on fork PRs; it is expected and not required.
• PR descriptions start with ## What: a short plain-language paragraph explaining what the PR does, simple enough for someone who has never seen the code. Then ## Why: the product reason in the same plain words, what was wrong or missing and who it hurt. Then ## Changes: behavior and decisions a reviewer needs, not a tour of files, libraries, or internals the diff already shows; at most about 8 bullets. Add ## Risk only when there is one (security, migrations, limits, irreversible effects). End with ## Tested: a short paragraph naming the kinds of tests run and what was not tested, not a list of every case. Keep it under about 350 words unless the change is security- or migration-heavy. Write as the author, never as a third-person briefing about the maintainer.
• Commit messages, PR descriptions, issues, and review replies are public too. Describe test results in words instead of pasting tool output. Never include business metrics such as analytics, traffic, click-through, conversion, signup, revenue, or star-growth numbers; give the product reason in words, even when data motivated the change. Never include anything that identifies a person, machine, or account: local paths, usernames, hostnames, signing identities, legal entity names, Apple Team IDs, API key IDs, issuer or tenant IDs, account emails, or the accounts, machines, and files that secret values came from. Naming the secrets a workflow reads is fine; use placeholders when a value must be shown.
• For UI changes, embed the CI E2E screenshot that shows the change in the PR description (pr-watch covers how, once CI publishes it); add the web test that opens that screen if it is missing. For native-only mobile UI that CI cannot capture, never link an unrelated web screenshot; for a large native change, add a flow to the existing iOS screenshot catalog. Whenever you captured screens while verifying a change (simulator, emulator, or browser), attach the ones that show it (pr-watch covers how) unless they show private data; say so only when you have none. Never add feature-specific flags, runners, or fake services to shared test or screenshot tooling to capture one screen; if the existing fixtures cannot show it, say so instead.
• Review bots ask how to make the code work as written, never whether it should exist. Before fixing a finding, decide whether the flagged code belongs in the PR; remove speculative, unrun, or out-of-scope code instead of building more to support it, and refute wrong findings with evidence.
• Keep each PR to one feature or fix. A large PR is fine; bundling unrelated features is not, so open a separate PR for each.
• When reviewing a PR, judge it against this file. Recommend removing code that cannot work or does not belong rather than suggesting more code to support it, and flag changes the PR description does not mention, such as new vendor or provider presets, dependencies, test runners, environment variables, or edits to shared tooling.
• UI system. Colors live in @orkbot/ui-tokens as semantic tokens (background, card, muted, border, primary, destructive, ...) with one TypeScript source that generates tokens.css; never hardcode a product hex or use [var(--…)] arbitrary values. Web and Tauri use shadcn/ui on Base UI, vendored into packages/ui-web via pnpm exec shadcn add from the official registry only (third-party registries are a supply-chain risk); reuse those components before writing chrome by hand (section headings use SectionHeading), and reuse apps/web/src/components/ai/ for AI moments (loading, shimmer, success). The app is monochrome: primary is ink, status colors are destructive/success/warning, bots carry the only identity color. Mobile is native-first: Expo Router, Expo UI, native sheets, menus, alerts and pickers wherever one exists; custom surfaces (thread, composer, avatars, cards) use plain StyleSheet with the shared tokens through apps/mobile/lib/appearance, and system chrome stays PlatformColor via lib/native. Mobile may diverge from web when the native pattern is better.
• On mobile, use built-in native iOS controls (@expo/ui SwiftUI and Liquid Glass, native header items, context menus, alerts, pickers, and switches) wherever possible instead of custom React Native pills or buttons.