Agent guide for the source repository

Tedix runs persistent, organization-owned AI workers on Cloudflare. Start with README.md and docs/public/index.md. Source publication is in preparation; Cloud access is by invitation and self-hosting is experimental.

Start locally

Run bun run-local from the repository root with Bun, Node.js 22+, and Git. It installs locked dependencies and starts isolated API, OS and D1 state. No login is needed. The default has no model turns; --demo adds sample state, --smoke checks onboarding/persistence, and --inference requires your own paid Cloudflare access. See docs/public/getting-started.md.

For UI-only work, use bun run --cwd apps/os dev (fixture data). Never treat local tests as proof of Cloud behavior or production deployment.

Choose a source path

Read the nearest scoped AGENTS.md, exact callers, and tests before changing behavior. Keep unrelated work intact. Contracts and current code take priority over prose; fix stale instructions when you encounter them.

Validate the change

• bun run --cwd <workspace> type-check: TypeScript source.
• bun run --cwd <workspace> test:run: that workspace’s tests; follow scoped guidance for narrower tests. Never use bare bun test on Worker apps.
• bun run types:check: generated Worker bindings; regenerate with bun run types:generate, never by hand.
• bun run lint:repo: architecture boundaries.
• bun run docs:public:check: public documentation and agent references.
• bun run scan:secrets: public source safety.

The pre-push hook selects relevant checks. Do not weaken a failing check or invent evidence. Report what ran and distinguish tests, settled outcomes, independent verification, and deployment.

Hard Invariants

Breaking these is expensive and usually invisible locally. Do not:

• Use db.transaction(). D1 rejects BEGIN (error 7500). db.batch() is the transaction primitive.
• Select two columns with the same output name in one query. D1 batch results are object rows and silently collapse duplicates before Drizzle maps them. Every query must stay safe when composed into a batch; tests use a D1 facade that rejects both idioms.
• Define oRPC contracts inline in routers. Contracts live in packages/api-contract/src/contracts/, schemas in packages/api-contract/src/schemas/; apps import direct @tedix/api-contract/... paths.
• Add barrel files or re-export facades. Direct imports everywhere. DB access goes through @tedix/db/queries/<domain> modules — never inline Drizzle queries in routers, jobs, services, or workflows (scripts/lint-db-access.ts enforces this).
• Hardcode per-tenant behavior in TypeScript. Config-driven behavior (tools, widgets, scopes, policies, schedules) belongs in D1 rows and versioned assets; TypeScript provides the engines, validators, renderers, and adapters.
• Name MCP tools anything but verb-first snake_case. list_skills, get_skill, run_skill_workflow. A noun prefix is allowed only for multi-product disambiguation (gmail_send). Internal oRPC contract keys keep their TypeScript {noun}.{verb} shape and are exempt.
• Edit worker-configuration.d.ts by hand — regenerate with bun run types:generate. Worker config is wrangler.jsonc, never .toml.

Local work and live authority

Reading and modifying a local checkout does not grant access to any live organization. For authorized live work, read docs/public/agent-guide.md, check tedix auth status, and discover the exact callable and schema. Human-required consent, MFA and user presence remain human actions; other approvals go to the designated independent principal.

Trusted maintainers use their existing Work coordination and direct-to-main flow. External contributions require an agreed scope; the maintainer owns internal tracking. See CONTRIBUTING.md. Never fabricate Work or agent identity.

Own-account installation is optional, experimental operator work. Follow docs/public/installation-manifests.md and docs/public/self-hosted-boundary.md only when deployment is the task. A source checkout is not authorization to operate Tedix Cloud.