temps: Instructions file for Codex

AGENTS.md

The rules for working on Temps, for people and for every coding agent. Claude Code loads this file through CLAUDE.md; Codex, Cursor and others read it directly. Core philosophy: code that works safely, and when it fails, explains why comprehensively.

Read REVIEW.md before opening a PR: the recurring review findings (authorization scope, secrets in logs, stale writes, cancellation and cleanup, resource limits, migrations) and a pre-PR checklist.

Critical Rules

NEVER

• Put a real user's, customer's or third party's identity into anything that leaves this machine. The repository is public. Company, product and account names, internal hostnames, contract/method names, real trace/span/request IDs, or any other detail that identifies whose system produced a payload never appear in code, comments, test fixtures, commit messages, branch or file names, PR titles, descriptions or comments, or issue text.
  • Reproducing a reported bug: keep the shape that makes the payload valuable (timings, ordering, precision, nesting, sizes, edge cases); rename services, operations and hosts to generic ones and regenerate every identifier. A fixture that identifies nobody is strictly better.
  • Describing it: say "a reported cross-project trace", never who reported it.
  • A live task target is scratch input, not evidence: a real URL, repo or account a user hands you ("deploy github.com/someone/their-repo") must not end up in tests, fixtures, commits or PRs as an example, even though the user supplied it. Write against a generic case ("a repo with no build manifest, just an index.html").
  • Allowed: public provider names and logos that identify supported integrations, and upstream URLs and copyright/license notices that attribute third-party assets; keep required attribution. This never covers customer accounts, private hostnames, credentials or captured payload identifiers.
  • Before pushing, grep the diff and any PR body for the reporter's names and identifiers. Once on GitHub it is effectively permanent: force-pushing does not remove a PR's recorded commits or diff, PRs cannot be deleted, forks keep the objects.
• Put the local build or verification environment into public text (PRs, commits, code comments): machine paths, cache helpers or servers, Docker socket paths, local toolchain workarounds. Report verification as the generic commands and their results.
• Commit .env files, credentials or secrets, including local dev-instance artifacts (encryption keys, auth secrets, generated tokens, temps_data-style directories). Run git status before staging and scrutinize every path you did not intentionally edit; a broad git add after running a local instance is the usual cause. A committed secret is compromised: stop tracking it and tell the user whether history needs rewriting; never force-push without asking.
• Sweep unrelated dirty files into a commit. If the tree was dirty when you arrived, ask before staging those files.
• Access the database from an HTTP handler. Handlers call services.
• Return untyped JSON (serde_json::Value). Use typed structs.
• Use anyhow's .context()/.with_context(). Use .map_err() into a typed error. Enforced as disallowed-methods in clippy.toml (the temps-cli bootstrap binary is exempt).
• Use .unwrap()/.expect() in production code. Use ? or explicit handling. unwrap_used, expect_used, dbg_macro and todo are denied workspace-wide (tests are exempt via clippy.toml). For a truly infallible call prefer restructuring; otherwise #[allow(clippy::unwrap_used, reason = "why it cannot fail")] on the narrowest item. Every lint allow needs a reason.
• Use anyhow::Result in the service layer. Use typed thiserror enums.
• Expose stored sensitive data (API keys, tokens, passwords) in responses; mask them. The one exception is a credential minted by the request itself (a new API key, an admin-reset temporary password): returned exactly once in plaintext with Cache-Control: no-store, never persisted in retrievable form, never logged or audited.
• Write N+1 queries. Use JOINs for related data.
• Leave the project in a non-compilable state.
• Use #[tokio::main] when integrating with pingora.
• Log in plain text. Use structured logging (JSONL for deployment logs).
• Overwrite apps/temps-cli/openapi.json with the raw server response. Use bun run spec:update (OpenAPI clients).
• Create markdown documentation files unless explicitly asked.
• Mark Docker tests #[ignore]. They skip at runtime when Docker is missing. #[ignore = "reason"] is allowed only on a test a dedicated CI job runs with --ignored, or a known-broken/manual test whose reason starts with known broken: / manual: and says what is wrong. A bare #[ignore] fails CI (scripts/rule_drift.py).
• Write error types with generic messages. Include IDs, names and the operation.
• Expose internal dependencies through public accessors (service.db()). Pass them via the constructor or AppState.
• Use Option<T> for a required dependency. Use Arc<T> and fail at startup if it is missing.
• Use get_service for a required plugin dependency. Use require_service, which fails fast with a clear error.
• Add runtime configuration as an environment variable (next section).
• Hand-edit CHANGELOG.md. git-cliff generates it from commit subjects at release time (concurrent edits used to conflict constantly); preview with scripts/changelog.sh --unreleased.
• Pass --no-verify unless the user explicitly asks. If a hook is broken, fix the hook.
• Mutate Docker resources you did not create. A host may already run a live Temps instance or operator-owned resources: never stop, remove, prune, rebuild or retag existing containers, images, volumes or networks. Tests create uniquely named resources and clean up only their own.