## Everruns

Agentic runtime and control plane: Rust workspace in `crates/` (edition 2024), Next.js UI in
`apps/ui/`, docs site in `apps/docs/` (content in `docs/`), embeddable examples in `examples/`.
`just --list` shows every dev command.

### Where guidance lives

Keep each fact in exactly one layer, and read the layer that owns it.

| Layer | Owns |
|---|---|
| `AGENTS.md` (this file, plus per-subtree ones) | repo gotchas that are not discoverable from the code |
| `knowledge/` | why and what: OKF v0.2 design intent, contracts, success bars, start at `knowledge/index.md` |
| `.agents/skills/` | how: workflows loaded on demand (`/ship`, `/maintenance`, `/process-issues`, `/manual-ui-testing`) |
| source, `justfile`, `.github/workflows/` | exact commands, fields, shapes, and checks |

Extend the owning layer instead of restating it here. When working in a subtree, check for a
closer `AGENTS.md` (`apps/ui/`, `crates/server/migrations/`, `plugins/`, `.deepsec/`).

### Norms

- Telegraph. Drop filler. Keep updates short and factual.
- Start from latest `origin/main` unless the task says otherwise.
- Keep changes small, PR-sized, testable, and runnable locally.
- For bug fixes, write or update a failing test before the fix when practical.
- Record important decisions as concise comments near the relevant code, not in scratch docs.
- Internal code needs no backward compatibility unless a spec says otherwise.
- Examples (`examples/`, `crates/*/examples/`) run against a real LLM. Never script one with
  `llmsim` or another simulated model: that belongs in tests, and an example must show real
  agent behavior. Use `gpt-6.1-sol` (or `gpt-6-luna` for a lighter model), never a `gpt-5`
  model.
- Changelog is part of done. A PR that meets the public changelog's impact criteria adds its
  entry (`docs/changelog/<date>-<slug>/`) in the same PR and fills the PR template's
  `Changelog:` line; a PR that changes behavior an older entry
  describes updates that entry. Rules: `knowledge/docs/changelog.md`; how: the ship skill's
  `references/changelog-entry.md`.

### Gotchas

- Dreaming has an explicit user publication hold. Do not create or reinstate its public
  changelog entry or announcement assets until the user explicitly approves them. CI, merge
  and release are not publication approval. Continue implementation without an entry and
  record the hold in the PR's `Changelog:` line.
- Engine-owned durable execution for DO/Cloudflare/celld has an explicit user publication hold.
  Do not create or reinstate its public changelog entry or announcement assets until the
  Framework Engine, serve and celld implementation and qualification are complete, and the user
  explicitly approves the entry afterward. CI, merge and release are not publication approval.
  Continue implementation without an entry; record the hold in the PR's `Changelog:` line.

- Working-tree changes you did not make are probably another agent's or the user's. Work with
  them, and stage files by name rather than `git add -A`.
- Create server migrations with `just new-migration <name>` (UTC timestamp version). A new
  `NNN_` file fails CI; the baseline replaced 001..222, kept frozen in `legacy/`.
- A secret a workflow fetches at runtime (`doppler secrets get`) is invisible to the Actions log
  masker, which only knows values that came through `secrets.*`. Put one in `$GITHUB_ENV` or
  `$GITHUB_OUTPUT` and the runner prints it in the `env:` block of every later step. Scope it to the
  one command that needs it (`doppler run -- <cmd>`) instead;
  `scripts/test-workflow-secret-handling.sh` enforces this.
- Run `just pre-push` before pushing. It scopes expensive checks to changed surfaces and shares a
  dedicated pre-push Rust target across worktrees; use `just pre-push-full` to force every check.
- Editing `ci.yml`'s Rust jobs has two non-obvious traps: jobs sharing a `rust-cache` `shared-key`
  must set the same `RUSTFLAGS` (it is part of cargo's fingerprint), and each extra `cargo test`
  invocation costs a codegen+link pass. See `knowledge/project/ci-build-time.md` before re-cutting
  the shards. Locally, `export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS="-C
  link-arg=-fuse-ld=lld"` with `lld` installed buys the same speedup CI gets.
- Knowledge captures why/what; link to source instead of copying fields, enum variants, SQL DDL,
  or API shapes. `docs/` holds public product documentation only, durable decisions and
  investigations belong in `knowledge/`. Run `just check-okf` after knowledge
  changes.
- Linear: OSS project, EVE team.

### Local dev

```bash
# Canonical coding-agent stack; choose a distinct prefix per worktree.
PORT_PREFIX=271 AUTH_MODE=none ./scripts/start-agent-dev.sh
```

This is the single agent startup contract. The script preserves the caller's `PORT_PREFIX` and
`AUTH_MODE` through Doppler, then runs `just start-all --no-watch`. It starts PostgreSQL, Valkey,
and NATS as local processes (no Docker), plus the API, worker, UI, and Caddy. The proxy is
`http://localhost/<PORT_PREFIX>00` (prefix `271` → `http://localhost:27100`). Pick an unused prefix
from `1` through `654`; never reuse one across concurrent worktrees.

Prerequisites: Rust and Node.js, a configured Doppler CLI, and the repository dependencies. On a
first checkout run `./scripts/init-cloud-env.sh` and then `just init`. The first Rust and Next.js
build can take several minutes.

`AUTH_MODE=none` is local-development-only and gives the anonymous user admin access. For
authenticated testing, explicitly select `admin`, `full`, or `external` and configure that mode's
variables per `docs/sre/runbooks/authentication.md`.

`start-all` maps Doppler's `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` to
`DEFAULT_OPENAI_API_KEY` and `DEFAULT_ANTHROPIC_API_KEY`. Analyze/Health additionally requires
`UTILITY_OPENAI_API_KEY` (or `UTILITY_OPENROUTER_API_KEY`); no extra setup is needed when Doppler
already supplies it. If Doppler does
not supply `SECRETS_ENCRYPTION_KEY`, startup creates a private per-prefix local-development key.

PostgreSQL and NATS data persist under `.local/data/`, isolated by the derived ports. Encrypted
database records depend on the encryption key remaining stable: the generated key is stored with
mode 0600 under `.local/agent-dev/`. Do not delete that key
without migrating or explicitly resetting affected local data. Valkey is started without
snapshots. Stop the foreground stack with Ctrl+C, or from another shell with
`PORT_PREFIX=271 just stop-all`; that command also stops the prefix's infrastructure processes.
Delete persistent data only with the explicit, prefix-scoped `PORT_PREFIX=271 just reset` command.

Verify the selected stack and auth contract with the actual `/health` endpoint:

```bash
curl -fsS http://localhost:27100/health
curl -fsS -o /dev/null -w '%{http_code}\n' http://localhost:27100/
```

### Cloud agents and secrets

`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GITHUB_TOKEN`, and `LINEAR_API_KEY` come from Doppler:

```bash
./scripts/init-cloud-env.sh
export CARGO_INCREMENTAL=0
# Then use the canonical command in "Local dev" above.
```

Failing auth usually means the token was not passed through, not that it expired:

```bash
doppler run -- bash -lc 'TOKEN="$SOME_TOKEN" <command>'
```

### Commits

- Conventional Commits (`type(scope): description`); use `chore` for `knowledge/` and `AGENTS.md`.
- Commit as the real human user. The only automated exception is the exact allowlisted author
  metadata tuple with name `warp-factories[bot]` and email
  `243557089+warp-factories[bot]@users.noreply.github.com`; all other agent-like identities remain
  prohibited. This local check is a policy heuristic, not cryptographic or server-side provenance.
  If `git config user.name`/`user.email` are missing or prohibited, set them from
  `GIT_USER_NAME`/`GIT_USER_EMAIL`; if those are absent, ask instead of committing.
- No AI attribution anywhere, commits, PRs, docs, code comments. The sole exception is yolop's
  standard `Co-Authored-By` trailer and `Generated with yolop` PR footer for work yolop performed.
