---
title: "AGENTS.md — Tedix Operating Manual"
description: "Operating manual for coding agents working inside a Tedix installation export."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.tedix.dev/llms.txt
> Use this file to discover all available pages before exploring further.



# 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

| Change           | Read first                                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| UI               | `apps/os/README.md`, `apps/os/AGENTS.md`, then `apps/os/src/routes/`                                            |
| API              | `apps/api/AGENTS.md`, contract in `packages/api-contract/src/contracts/`, router in `apps/api/src/rpc/routers/` |
| Persistence      | `packages/db/AGENTS.md`, owning `src/schema/` and `src/queries/` modules                                        |
| Worker execution | `apps/tedi-runtime/AGENTS.md`, `src/do.ts` and the relevant adjacent module                                     |
| MCP tools        | `apps/mcp/AGENTS.md`, `src/mcp/handler.ts` and `packages/db/src/schema/tools.ts`                                |
| CLI              | `packages/cli/README.md` and the command's implementation                                                       |

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.

Source: https://docs.tedix.dev/agents/index.mdx