diff --git a/CLAUDE.md b/CLAUDE.md
index 8f7a4b7..d6291be 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,52 +1,78 @@
-# CLAUDE.md — go-scm Agent Instructions
+# CLAUDE.md
 
-You are a dedicated domain expert for `forge.lthn.ai/core/go-scm`. Virgil orchestrates tasks via Forgejo issues. Pick up tasks in issue order, mark complete, commit and push.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## What This Package Does
+## What This Is
 
-SCM integration and data collection for the Lethean ecosystem. Three packages: `forge/` (Forgejo API client), `gitea/` (Gitea API client), `collect/` (data collection).
+SCM integration and data collection library for the Lethean ecosystem (`forge.lthn.ai/core/go-scm`). Provides Forgejo/Gitea API clients, an AgentCI pipeline for automated PR lifecycle, pluggable data collectors, and workspace management (repos registry, manifests with ed25519 signing, marketplace, plugin system).
 
-**Extracted to other repos:** `agentci/` + `jobrunner/` → `core/go-agent`, `git/` → `core/go-git`.
-
-**Note:** `forge/` is still used by `core/go-agent` as a dependency. `core/go-forge` is a separate, full API client with a different interface.
+Virgil orchestrates tasks via Forgejo issues. Pick up tasks in issue order, mark complete, commit and push.
 
 ## Commands
 
 ```bash
-go test ./...                    # Run all tests
-go test -v -run TestName ./...   # Single test
-go test -race ./...              # Race detector
-go vet ./...                     # Static analysis
+go build ./...                     # Compile all packages
+go test ./...                      # Run all tests
+go test -v -run TestName ./forge/  # Single test in a package
+go test -race ./...                # Race detector (important for git/, jobrunner/, collect/)
+go vet ./...                       # Static analysis
+golangci-lint run ./...            # Lint (govet, errcheck, staticcheck, unused, gocritic, gofmt)
 ```
 
+If using the `core` CLI:
+
+```bash
+core go qa             # fmt + vet + lint + test
+core go qa full        # + race, vuln, security
+```
+
+## Architecture
+
+Five subsystems — see `docs/architecture.md` for full detail:
+
+1. **Forge Clients** (`forge/`, `gitea/`) — thin wrappers over Forgejo/Gitea SDKs. Auth resolves: config file → env vars (`FORGE_URL`/`FORGE_TOKEN`) → flags → default localhost. All list methods handle pagination; `*Iter` variants yield lazily via `iter.Seq2`. SDK limitation: Forgejo SDK v2 does not accept `context.Context`.
+2. **AgentCI Pipeline** (`agentci/`, `jobrunner/`, `jobrunner/forgejo/`, `jobrunner/handlers/`) — poll-dispatch-journal loop. `ForgejoSource` finds epic issues with checklists, emits `PipelineSignal` per unchecked child, handlers match and execute in registration order (first match wins). Includes Clotho Protocol dual-run verification.
+3. **Data Collection** (`collect/`) — `Collector` interface with built-in scrapers (GitHub via `gh` CLI, BitcoinTalk, CoinGecko, IACR/arXiv). `Excavator` orchestrates sequential runs with rate limiting and incremental state.
+4. **Workspace Management** (`repos/`, `manifest/`, `marketplace/`, `plugin/`) — `repos.yaml` multi-repo registry with topological sorting, `.core/manifest.yaml` with ed25519 signing, module marketplace with install/update/remove, CLI plugin system.
+5. **Git Operations** (`git/`) — parallel multi-repo status, push/pull. DI-integrated `Service` with query/task handlers.
+
+CLI commands live in `cmd/forge/`, `cmd/gitea/`, `cmd/collect/`.
+
+**Note:** `agentci/` + `jobrunner/` are being extracted to `core/go-agent`, `git/` to `core/go-git`. `forge/` is still used by `core/go-agent` as a dependency.
+
 ## Local Dependencies
 
-Resolved via `replace` in go.mod or preferably via `go.work`:
-
-| Module | Local Path |
-|--------|-----------|
-| `forge.lthn.ai/core/go` | `../go` |
-
-## Key Types
+Use a Go workspace file (preferred over `replace` directives):
 
 ```go
-// forge/client.go
-type Client struct { api *forgejo.Client; url, token string }
+// ~/Code/go.work — includes all forge.lthn.ai/core/* modules
 ```
 
+Key dependencies: `core/go` (DI framework), `core/go-io` (filesystem abstraction), `core/go-log`, `core/go-config`, `core/go-i18n`, `core/go-crypt`.
+
+## Test Patterns
+
+Each subsystem has different test infrastructure — see `docs/development.md` for examples:
+
+- **forge/, gitea/**: `httptest` mock server required (SDK does GET `/api/v1/version` on client construction). Always isolate config: `t.Setenv("HOME", t.TempDir())`.
+- **manifest/, marketplace/, plugin/, repos/**: Use `io.NewMockMedium()` to avoid filesystem interaction.
+- **git/**: Real temporary git repos via `t.TempDir()` + `exec.Command("git", ...)`.
+- **agentci/**: Pure unit tests, no mocks needed.
+- **jobrunner/**: Table-driven tests against `JobHandler` interface.
+- **collect/**: Mixed — pure functions test directly, HTTP-dependent use mock servers. `SetHTTPClient` for injection.
+
 ## Coding Standards
 
-- **UK English**: colour, organisation, centre
-- **Tests**: testify assert/require, table-driven preferred, `_Good`/`_Bad`/`_Ugly` naming
-- **Conventional commits**: `feat(forge):`, `fix(gitea):`, `test(collect):`
-- **Co-Author**: `Co-Authored-By: Virgil <virgil@lethean.io>`
+- **UK English**: colour, organisation, centre, licence (noun), authorise, behaviour
+- **Tests**: testify assert/require, table-driven preferred, `_Good`/`_Bad`/`_Ugly` suffix naming
+- **Imports**: stdlib → `forge.lthn.ai/...` → third-party, each group separated by blank line
+- **Errors**: `"package.Func: context: %w"` or `log.E("package.Func", "context", err)` — no bare `fmt.Errorf`
+- **Conventional commits**: `feat(forge):`, `fix(gitea):`, `test(collect):`, `docs(agentci):`, `refactor(collect):`, `chore:`
+- **Co-Author trailer**: `Co-Authored-By: Virgil <virgil@lethean.io>`
 - **Licence**: EUPL-1.2
-- **Imports**: stdlib → forge.lthn.ai → third-party, each group separated by blank line
-- **Error pattern**: `"package.Func: context: %w"` — no bare `fmt.Errorf`
-
-See `docs/development.md` for full standards and test patterns.
 
 ## Forge
 
 - **Repo**: `forge.lthn.ai/core/go-scm`
 - **Push via SSH**: `git push origin main` (remote: `ssh://git@forge.lthn.ai:2223/core/go-scm.git`)
+- **CI**: Forgejo Actions — runs tests with race detector and coverage on push to main/dev and PRs to main