radicle-explorer/AGENTS.md

# radicle-gui

Monorepo for Radicle's graphical interfaces. It holds two projects, each with
its own Cargo workspace, toolchain files, checks and conventions, and the UI
code they share. One npm workspace at the root holds all three packages:

- **Explorer** (`explorer/`): the Svelte web app for browsing Radicle
  repositories, its TypeScript HTTP client, and the `radicle-httpd` and
  `radicle-search` backends it talks to. See `explorer/AGENTS.md`.
- **Desktop** (`desktop/`): the Tauri desktop app. See `desktop/AGENTS.md`.
- **Shared UI** (`shared/ui/`): the `@radicle-gui/ui` package with Svelte
  components, helpers, design tokens and fonts used by both apps. See
  `shared/ui/AGENTS.md`.

This file covers what applies to both. Each project's `AGENTS.md` is the
source of truth for anything inside it.

## Layout

| Path | What it is |
|---|---|
| `explorer/` | Web app, HTTP client, `radicle-httpd` and `radicle-search` |
| `desktop/` | Tauri app: Svelte frontend in `src/`, Rust in `crates/` |
| `shared/ui/` | UI code shared by both apps |
| `package.json`, `package-lock.json`, `.npmrc`, `.nvmrc` | The npm workspace, its lockfile and npm and Node settings |
| `docs/adr/` | Decisions that affect the whole repository |
| `.github/workflows/` | GitHub CI: `explorer-*.yml` for explorer, `desktop-*.yml` for desktop, `shared-ui.yml` for the shared UI |
| `.buildkite/` | Radicle CI pipelines (explorer only) |
| `.ryph/` | Dev machine image and setup for agents, see `.ryph/environment.md` |

## Working in this repo

- Install npm dependencies at the root: `npm ci` for everything, or
  `npm ci -w explorer` or `npm ci -w desktop` for one app. Run every other
  command from the project's directory; there are no root `cargo` commands.
- Work out which project a change belongs to first. Changes to `shared/ui`
  affect both apps: check `shared/ui` and both apps.
- A change that touches both projects is two changes: check each project
  with its own commands.
- Explorer's components use legacy Svelte syntax (`$:`, stores,
  `export let`), desktop's and the shared ones use Svelte 5 runes.
- Code in `shared/ui` must not import `@tauri-apps/*`, `@bindings`,
  `@http-client` or anything else from one app. It takes plain props, and
  each app adapts its own data to them.
- Record a bigger architectural change as a new ADR, numbered after the last
  one and in the same format: in `docs/adr/` if it affects the whole
  repository, in the project's own `docs/adr/` otherwise.
- Before opening a patch or tagging a release, read `CONTRIBUTING.md` for
  patch labels and release tags. Never create or match the old
  `releases/<version>` tags; they predate the monorepo.

## Shared conventions

- Prefer `undefined` over `null`
- Do not add comments unless explicitly asked. When writing comments,
  use proper English sentences
- Ask before adding new dependencies: each one is a supply-chain risk, and
  installs are gated by `min-release-age` and `strict-allow-scripts`
- Use npm, never `yarn` or `pnpm`: the lockfile and `.npmrc` settings are
  npm's
- Updates and audit fixes must respect each project's 7-day cooldown, see
  "Updating dependencies" below
- Run tests through the `npm run` scripts, not `npm test` (neither project
  has one), `npx vitest` or `npx playwright test`: the scripts set `TZ=UTC`
  and, in explorer, `NODE_CONFIG_ENV`, which the tests rely on
- Use ES private fields (`#field`), not the TypeScript `private` keyword

### Svelte components

- CSS: scoped styles with design tokens (`var(--color-text-primary)`,
  `var(--txt-body-m-regular)`, `var(--border-radius-sm)`); use `:global()`
  for styling slotted or `{@html}` content
- Loading states: `{#await promise}` blocks for inline async;
  local `loading` boolean with `try/catch` for imperative fetches

## Updating dependencies

Both projects only install releases that are at least 7 days old: npm through
`min-release-age` in the root `.npmrc`, Cargo through `cooldown.toml` and
`cargo-cooldown`. npm commands cover the whole workspace and change the root
lockfile; run Cargo commands from the project's directory:

```sh
npm audit                         # list advisories
npm audit fix                     # apply fixes that are past the cooldown
cargo audit                       # list advisories
cargo cooldown update -p <crate>  # update a crate within the cooldown
```

- Never run plain `cargo update`: it ignores `cooldown.toml`
- `katex` is pinned for the whole workspace by an override in the root
  `package.json`, so mermaid and both apps use one version. Bump it there as
  well as in the apps, or the apps' bump has no effect
- Never run `npm audit fix --force`: it takes major-version bumps. Ask first
- If a fix is still cooling down, report when it clears and ask before
  taking it early. Taking it early means reviewing the release's diff
  against the previous version, then:
  - npm: `npm install <pkg>@<version> -w <project> --min-release-age=0` at
    the root
  - Cargo: add an `[[allow.exact]]` entry to `cooldown.toml` with a comment
    naming the advisory and the date it can be removed

## Commit messages

- Imperative mood: "Add feature" not "Added feature"
- Capitalize subject, no trailing period, about 50 chars
- Prefix commits that touch a single component with it: `explorer:`,
  `httpd:` or `desktop:`, e.g. "desktop: Add release view". Commits that span
  most of the repository have no prefix
- Each commit should be understandable, testable and revertable on its own

## Radicle ecosystem (sibling repos)

Both projects build on crates from sibling repositories, which may be
checked out next to this one. If present, read their source when a type
comes from outside this repo or you need protocol context:

- `../heartwood`: the protocol. Crates `radicle`, `radicle-cob`,
  `radicle-crypto` and `radicle-core`. Start with `HACKING.md` and
  `ARCHITECTURE.md`
- `../radicle-git`: `radicle-surf`, the code browsing (files, diffs, commits)
  that httpd and desktop serve
- `../radicle-job`: CI job COBs
- `../rips`: protocol specs: `0001-heartwood.md`, `0002-identity.md`,
  `0003-storage-layout.md`
- `../radicle.dev`: user docs. `_guides/user.md` covers workflows,
  `_guides/protocol.md` covers gossip, replication and the COB model, and
  `_guides/seeder.md` covers seed nodes and httpd setup

## Domain glossary

- **RID** — Repository ID (`rad:z3gqc...`)
- **DID** — Decentralized Identifier, user identity (`did:key:z6Mk...`)
- **NID** — Node ID, the public key in a DID
- **COB** — Collaborative Object (issue, patch, or identity as a Git DAG)
- **Delegate** — authorized repo maintainer; signatures determine canonical state
- **Patch** — pull-request equivalent with immutable revisions and reviews
- **Seed** — hosting/replicating a repo; seed nodes are always-on servers
- **Canonical refs** — branches/tags resolved by delegate quorum