Refine CLAUDE.md

.claude/skills/radicle-ecosystem/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: radicle-ecosystem
+description: Map of the sibling Radicle repositories that radicle-httpd depends on (heartwood, radicle-git, radicle-job, rips, radicle.dev), with the key crates and files to read in each. Use when working on Rust code in radicle-httpd, when you need protocol or domain context, or when a type comes from a crate outside this repo.
+---
+
+# Radicle ecosystem (sibling repos)
+
+`radicle-httpd` depends on crates from sibling repositories. Read
+source from these paths when working on Rust code.
+
+## heartwood (`../heartwood`)
+
+Core Radicle protocol implementation. Key crates used by httpd:
+- `radicle` — standard library (storage, identity, COBs, git, node)
+- `radicle-cob` — collaborative objects (issues, patches as CRDTs)
+- `radicle-crypto` — Ed25519 signing, SSH key handling
+- `radicle-core` — fundamental types (`RepoId`, etc.)
+
+Key files:
+- `../heartwood/HACKING.md` — development guide, environment variables
+- `../heartwood/ARCHITECTURE.md` — high-level architecture
+- `../heartwood/crates/radicle/src/lib.rs` — main library entry point
+
+## radicle-git (`../radicle-git`)
+
+Git library wrappers. Key crate:
+- `radicle-surf` — code browsing (files, diffs, commits, branches,
+  tags). This is what httpd uses to serve repository content.
+
+Key file: `../radicle-git/radicle-surf/src/lib.rs`
+
+## radicle-job (`../radicle-job`)
+
+Decentralized job execution (CI/CD) on the Radicle network.
+Key file: `../radicle-job/README.md`
+
+## RIPs — protocol specs (`../rips`)
+
+- `../rips/0001-heartwood.md` — protocol overview
+- `../rips/0002-identity.md` — identity system (DIDs, Ed25519)
+- `../rips/0003-storage-layout.md` — git storage layout
+
+## Radicle documentation (`../radicle.dev`)
+
+Read these when you need domain context for UI work:
+- `../radicle.dev/_guides/user.md` — end-to-end user workflows
+  (init, clone, seed, issues, patches, code review, private repos)
+- `../radicle.dev/_guides/protocol.md` — protocol internals
+  (gossip, replication, identity documents, COB data model, trust)
+- `../radicle.dev/_guides/seeder.md` — seed node operation
+  (seeding policies, httpd setup, DNS-SD)
+- `../radicle.dev/_posts/2025-07-23-using-radicle-ci-for-development.md` — CI integration
+- `../radicle.dev/_posts/2025-08-12-canonical-references.md` — canonical refs design

CLAUDE.md

@@ -13,9 +13,6 @@ client (`http-client/`) and a Rust backend (`radicle-httpd/`).
 ## Tech stack
 
 - Svelte 5 with legacy syntax (`$:`, stores, `export let`)
-- TypeScript, Vite, Vitest, Playwright
-- Rust backend: `radicle-httpd/`
-- Path aliases: `@app` (src), `@http-client`, `@public`, `@tests`
 
 ## Commands
 
@@ -89,52 +86,9 @@ and fall back when they're absent.
 
 ## Radicle ecosystem (sibling repos)
 
-`radicle-httpd` depends on crates from sibling repositories. Read
+See the `radicle-ecosystem` skill for the map of sibling repositories
-source from these paths when working on Rust code.
+(heartwood, radicle-git, radicle-job, rips, radicle.dev) and the key
-
+crates and files in each.
-### heartwood (`../heartwood`)
-
-Core Radicle protocol implementation. Key crates used by httpd:
-- `radicle` — standard library (storage, identity, COBs, git, node)
-- `radicle-cob` — collaborative objects (issues, patches as CRDTs)
-- `radicle-crypto` — Ed25519 signing, SSH key handling
-- `radicle-core` — fundamental types (`RepoId`, etc.)
-
-Key files:
-- `../heartwood/HACKING.md` — development guide, environment variables
-- `../heartwood/ARCHITECTURE.md` — high-level architecture
-- `../heartwood/crates/radicle/src/lib.rs` — main library entry point
-
-### radicle-git (`../radicle-git`)
-
-Git library wrappers. Key crate:
-- `radicle-surf` — code browsing (files, diffs, commits, branches,
-  tags). This is what httpd uses to serve repository content.
-
-Key file: `../radicle-git/radicle-surf/src/lib.rs`
-
-### radicle-job (`../radicle-job`)
-
-Decentralized job execution (CI/CD) on the Radicle network.
-Key file: `../radicle-job/README.md`
-
-### RIPs — protocol specs (`../rips`)
-
-- `../rips/0001-heartwood.md` — protocol overview
-- `../rips/0002-identity.md` — identity system (DIDs, Ed25519)
-- `../rips/0003-storage-layout.md` — git storage layout
-
-### Radicle documentation (`../radicle.dev`)
-
-Read these when you need domain context for UI work:
-- `../radicle.dev/_guides/user.md` — end-to-end user workflows
-  (init, clone, seed, issues, patches, code review, private repos)
-- `../radicle.dev/_guides/protocol.md` — protocol internals
-  (gossip, replication, identity documents, COB data model, trust)
-- `../radicle.dev/_guides/seeder.md` — seed node operation
-  (seeding policies, httpd setup, DNS-SD)
-- `../radicle.dev/_posts/2025-07-23-using-radicle-ci-for-development.md` — CI integration
-- `../radicle.dev/_posts/2025-08-12-canonical-references.md` — canonical refs design
 
 ## Domain glossary
 
@@ -174,20 +128,6 @@ Read these when you need domain context for UI work:
 - API timestamps are in seconds; multiply by 1000 for JS `Date`
 - Relative imports inside `http-client/` use `.js` extension (ESM)
 
-### Rust backend (radicle-httpd)
-
-- Each route module exposes `pub fn router(ctx: Context) -> Router`;
-  handlers are private `async fn`s
-- Handler signature:
-  `async fn handler(State(ctx): State<Context>, Path(rid): Path<RepoId>) -> impl IntoResponse`
-- Annotate the error type on Ok: `Ok::<_, Error>(Json(data))`
-- All response structs: `#[serde(rename_all = "camelCase")]`
-- Optional fields: `#[serde(skip_serializing_if = "Option::is_none")]`
-- Use `json!()` macro for inline JSON; `immutable_response()` /
-  `cached_response()` helpers for Cache-Control headers
-- Module structure: `api/v1/` handlers, `api/json/` serialization helpers,
-  `api/query.rs` query param types, `api/error.rs` error types
-
 ## Commit messages
 
 - Imperative mood: "Add feature" not "Added feature"

crates/radicle-httpd/CLAUDE.md

@@ -0,0 +1,17 @@
+# radicle-httpd
+
+Rust backend for radicle-explorer.
+
+## Code conventions
+
+- Each route module exposes `pub fn router(ctx: Context) -> Router`;
+  handlers are private `async fn`s
+- Handler signature:
+  `async fn handler(State(ctx): State<Context>, Path(rid): Path<RepoId>) -> impl IntoResponse`
+- Annotate the error type on Ok: `Ok::<_, Error>(Json(data))`
+- All response structs: `#[serde(rename_all = "camelCase")]`
+- Optional fields: `#[serde(skip_serializing_if = "Option::is_none")]`
+- Use `json!()` macro for inline JSON; `immutable_response()` /
+  `cached_response()` helpers for Cache-Control headers
+- Module structure: `api/v1/` handlers, `api/json/` serialization helpers,
+  `api/query.rs` query param types, `api/error.rs` error types