# AGENTS.md

These rules apply to the entire Lumbridge repository.

## Product boundary

Lumbridge is a terminal/workspace runtime and ACP client. It may host, supervise,
and observe coding harnesses, but must not silently impersonate them, harvest their
private credentials, or claim provider quota data that cannot be verified.

**Credential use is narrow and named.** A harness's stored credential may be read
only to ask that same provider a documented question about the user's own account,
and only where the answer cannot be obtained another way. Under that allowance a
credential must never be persisted, logged, copied into application state, written
to a crash report, or passed as a command-line argument; it must be released as
soon as the request it authorises has been made; and any request it authorises must
identify Lumbridge as the caller. A refresh token is never used — renewing a
credential is the harness's job, not Lumbridge's. Every such use is named in a
decision record, and each is switchable off by the user. Reading a credential for
anything other than a use recorded that way is out of bounds. See decision 0016.

## Research boundary

Upstream repositories are cloned outside this Git repository under the desktop
workspace's `Research/` directory. They are references, not vendored code.

- Do not copy upstream implementation code without an explicit license review.
- Record the source repository and relevant license for any adapted design.
- AGPL/GPL and unlicensed repositories may be studied for behavior and UX only
  unless the project deliberately changes its licensing strategy.

## Engineering rules

- Keep provider, harness, protocol, terminal, persistence, and UI boundaries
  separate. A provider is not a harness and ACP is not a provider API.
- Preserve a PTY fallback. ACP adds structure but must not be required to open a
  normal shell or run an arbitrary CLI.
- Keep secrets out of SQLite, logs, crash reports, command-line arguments, and
  repository files. Store only opaque secret references in application state.
- Usage values must include a provenance and confidence classification.
- Avoid platform behavior hidden behind scattered `cfg` blocks; isolate it in
  platform adapters with shared contract tests.
- No telemetry is enabled by default. Any future telemetry must be documented,
  opt-in, redacted, and independently disableable.

## Dependencies that are not an agent's decision

The native UI framework is settled and its dependency is pinned by a decision
record. Do not change the `gpui` (or `gpui_platform`) source, revision, or
version; do not edit `rust-toolchain.toml` or the workspace `rust-version`; do
not run `cargo update` or relax `deny.toml` to make a build succeed. A headless
test asserts the pinned source and revision on every push, so a silent bump
fails CI rather than landing.

Changing any of them is a new decision record with a probe run at the new
revision, not a commit. If a UI build fails, the failure is the finding: report
it rather than routing around it.

## Every crate is a workspace member

A crate directory in neither `workspace.members` nor `workspace.exclude`
inherits no lints, is never built, and its tests never run -- silently. This has
happened twice here, and both times the code looked finished and did not
compile. Add a crate to `members` in the same change that creates it, and never
move code into an excluded directory to make a build pass. CI fails on a crate
that is in neither list.

## Verification

Before committing Rust changes, run:

```bash
export PATH="$HOME/.cargo/bin:$PATH"   # a non-interactive shell has no cargo
./scripts/ci.sh
```

`cargo` is on `PATH` only via an interactive shell profile, so an agent, an
`ssh` command, or a hook gets `cargo: command not found` without that export.
Never conclude a gate passed from an exit code obtained through a pipe -- a
pipeline reports its last command's status, which has hidden a failing gate
here already. `--headless` deliberately excludes `apps/lumbridge`, so a headless
pass is not a product pass.

Keep `bacon` running during development. Tests must use synthetic fixtures; real
agent transcripts, subscription state, private source, and credentials are never
test data.