---
name: lumbridge-development
description: Build, test, review, benchmark, or document Lumbridge, the native Rust local-first IDE, terminal multiplexer, and agent workspace.
---

# Lumbridge Development

Work from the Lumbridge repository root. Read `AGENTS.md`, then only the product
documents relevant to the task:

- architecture or persistence: `docs/ARCHITECTURE.md` and `docs/decisions/`;
- product behavior: `docs/PRODUCT_SPEC.md`;
- tests: `docs/TESTING.md`;
- native UI work: `docs/UI_OPTIONS.md` and `docs/UI_SPIKE_SCORECARD.md`;
- Buzz work: `docs/BUZZ_INTEGRATION.md`.

Preserve these product boundaries:

- The application shell, terminal, editor, runtime, and state model are native
  Rust. Do not introduce Electron, React, TypeScript, or a webview shell.
- Data is local-first. SQLite contains metadata and history, never API keys,
  subscription tokens, SSH private keys, Buzz private keys, or Tailscale keys.
- Remote PTYs live in a per-user runtime on the user's remote machine. OpenSSH
  and Tailscale are transports over access the user already configured; do not
  change tailnet ACLs, copy credentials, or open public listeners.
- macOS, Ubuntu, and Omarchy/Arch are release targets. A Linux-only success is
  not cross-platform proof.
- Usage and quota values always retain provenance and uncertainty.

## The UI framework is decided

GPUI graduated out of `spikes/` into `apps/lumbridge` and is part of the product
workspace, its lints, and its licence closure. `spikes/floem-shell` is frozen
evidence at the revision the comparison was made; it is not maintained in parity
and is not a candidate. Do not reopen the comparison, do not add Floem to the
workspace, and do not read `UI_SPIKE_SCORECARD.md`'s provisional wording as a
live question. See `docs/decisions/0017-*` and any record superseding it.

## The dependencies that are not an agent's decision

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 UI build succeed. Each of these
is fixed by a decision record and checked mechanically in the fast headless CI
job; a change to any of them requires a new decision record, not a commit.

If a UI build fails, the failure is the finding. Report it.

## Every crate is a workspace member

A crate directory that appears in neither `workspace.members` nor
`workspace.exclude` inherits no lints, is not built, and its tests never run --
silently. This has happened twice in this repository, and both times the code
looked finished and was not. When you add a crate, add it to `members` in the
same change, and never move code into an excluded directory to make a build
pass.

## Development loop

Before editing, inspect Git status and preserve unrelated work.

`cargo` is installed at `~/.cargo/bin` and is put on `PATH` by an interactive
shell profile. A non-interactive shell -- which is what an agent, an `ssh`
command, and a hook all get -- does not source that profile and will fail with
`cargo: command not found`. Export it explicitly:

```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

Then:

```bash
bacon               # continuous check; t tests, c lints, v the full gate
cargo xtest         # fast isolated tests with nextest
./scripts/ci.sh     # format + strict Clippy + tests + doctests + cargo deny
```

`scripts/ci.sh --headless` skips the GPUI crates and finishes in seconds;
`--ui` runs only them. A headless pass is not a product pass: it deliberately
excludes `apps/lumbridge`. Never report the gate as green from `--headless`
alone, and never conclude a gate passed from an exit code you obtained through
a pipe -- a pipeline reports the exit status of its last command, which has
already hidden a failing gate here once.

For Buzz integration, use its Apache-2.0 Rust SDK and signed protocol semantics
rather than inventing a webhook dialect. Test against a local relay and fixture
identity. Pane screenshots or transcripts require a visible preview, redaction,
explicit destination, and user confirmation before upload.

Add tests at the lowest deterministic layer first, then platform or rendered
tests where behavior crosses a real boundary. Before handoff, run
`./scripts/ci.sh`, `git diff --check`, and report anything not validated on all
target systems.