docs(claude): add architecture, commands, and pre-flight pitfalls

Adds a 30-second architecture overview, a concrete commands block
(build / test / lint / xtask audits / nix dev shell), a pitfall about
GPU/NPU crates being excluded from default-members, and corrects the
stale Steelbore-era project-memory path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

CLAUDE.md

@@ -14,6 +14,62 @@ turns.
 
 ---
 
+## Architecture in 30 Seconds
+
+14-crate workspace. The binary `caliper` depends only on `caliper-trace`
+(public API re-exports) and `caliper-tui`. `caliper-trace` re-exports from
+`caliper-crucible` (pipeline orchestrator). `caliper-crucible` drives the
+seven-stage DAG across the stage crates:
+
+```
+Assayer → Smelt → Etch → Burin → Temper → Weld → Cast
+(route)   (quant) (edge) (trace) (fit)    (stitch) (write)
+```
+
+`caliper-anvil` is the SIMD primitives layer — the only crate allowed
+`unsafe`. `caliper-bellows` (wgpu GPU) and `caliper-touchstone`
+(ONNX Runtime NPU) are feature-gated optional backends and excluded from
+`default-members` in the workspace `Cargo.toml`. `caliper-tui` is the
+`--format explore` ratatui interface, never depended on by library crates.
+
+Status: pre-v0.1.0. Most crates are scaffolds with module-level docs;
+[`TODO.md §1`](TODO.md) drives the current sprint.
+
+---
+
+## Commands
+
+### Build / test / lint
+- `cargo build --workspace` — builds default-members (CPU-only surface).
+- `cargo build -p caliper-bellows` / `-p caliper-touchstone` — GPU / NPU
+  crates are excluded from `default-members` (heavy native deps: wgpu,
+  ort/ONNX Runtime), so build them by name.
+- `cargo test --workspace` — full test suite.
+- `cargo test -p <crate> <name>` — run a single test (e.g.
+  `cargo test -p caliper-smelt kmeans::tests::converges`).
+- `cargo test --test schema_roundtrip` — JSON-schema round-trip;
+  a failure is P0 per pitfall #4 below.
+- `cargo +nightly miri test -p caliper-anvil` — Miri-validates the only
+  crate where `unsafe` is allowed.
+- `cargo insta test` — TUI snapshot tests (`caliper-tui`).
+- `cargo clippy --workspace --all-targets -- -D warnings` — CI lint gate.
+- `cargo fmt --all --check` — CI format gate.
+
+### Workspace audits (via `cargo xtask`, aliased in `.cargo/config.toml`)
+- `cargo xtask spdx-audit` — every source file has a GPL-3.0-or-later header.
+- `cargo xtask utf8-audit` — UTF-8 without BOM on every text file.
+- `cargo xtask network-audit` — no network I/O outside `caliper models pull`.
+- `cargo xtask cross-shell-test` — CLI round-trip under POSIX sh / Bash /
+  Brush / Nushell / PowerShell / Ion.
+- `cargo deny check` (alias: `cargo deny`) — license + advisory + sources
+  audits.
+
+### Dev shell
+- `nix develop` — reproducible toolchain pinned in `flake.nix` +
+  `rust-toolchain.toml` (Rust 1.88.0, Edition 2024).
+
+---
+
 ## Before You Edit Any `.rs` File
 
 Invoke the `rust-guidelines` skill. It is mandatory for every Rust touch, no
@@ -26,13 +82,13 @@ For non-Rust work, the relevant skills are:
 | You are about to …                          | Skill to invoke           |
 |---------------------------------------------|---------------------------|
 | Touch any `.rs` file                        | `rust-guidelines`         |
-| Touch any CLI surface, `--json`, schema     | `steelbore-cli-standard`  |
-| Touch agentic UX, AGENTS.md, MCP            | `steelbore-agentic-cli`   |
-| Touch TUI, palette, typography              | `steelbore-standard` + `steelbore-theme-factory` |
-| Touch documents (PRD/PLAN/TODO/README/docs) | `steelbore-document-format` |
-| Run a shell command                         | `steelbore-cli-preference` + `steelbore-cli-shell` |
-| Install missing software                    | `steelbore-missing-pkg`   |
-| Generic Steelbore compliance question       | `steelbore-standard`      |
+| Touch any CLI surface, `--json`, schema     | `spacecraft-cli-standard`  |
+| Touch agentic UX, AGENTS.md, MCP            | `spacecraft-agentic-cli`   |
+| Touch TUI, palette, typography              | `spacecraft-standard` + `spacecraft-theme-factory` |
+| Touch documents (PRD/PLAN/TODO/README/docs) | `spacecraft-document-format` |
+| Run a shell command                         | `spacecraft-cli-preference` + `spacecraft-cli-shell` |
+| Install missing software                    | `spacecraft-missing-pkg`   |
+| Generic Spacecraft Software compliance question | `spacecraft-standard`  |
 
 ---
 
@@ -41,7 +97,7 @@ For non-Rust work, the relevant skills are:
 - **File reads** → `Read`. Never `cat`.
 - **File edits** → `Edit` for diffs, `Write` for new files / full rewrites.
 - **Search** → `rg` (ripgrep), `fd` for filenames. Never bare `grep` or `find`.
-  See `steelbore-cli-preference` for the full mapping.
+  See `spacecraft-cli-preference` for the full mapping.
 - **JSON inspection** → `jaq`, not `jq`.
 - **Tests** → `cargo test --workspace`. For TUI snapshots: `cargo insta test`.
 - **Lints** → `cargo clippy --workspace --all-targets -- -D warnings`.
@@ -51,10 +107,10 @@ For non-Rust work, the relevant skills are:
 
 ## Output Style
 
-- Match the [Steelbore Standard §12](https://Steelbore.com/standard) date/time
+- Match the [Spacecraft Software Standard §12](https://SpacecraftSoftware.org/standard) date/time
   rules in every commit message, log line, and PR description: ISO 8601 UTC
   with `Z` suffix. 24-hour time. Metric units.
-- Steelbore palette in any colored output. Void Navy `#000027` is the canonical
+- Spacecraft Software palette in any colored output. Void Navy `#000027` is the canonical
   background.
 
 ---
@@ -74,12 +130,16 @@ For non-Rust work, the relevant skills are:
    `cargo test --test schema_roundtrip` and a failing round-trip is a P0.
 5. **"Cache the model auto-download in `~/.cache`."** No. PFA §6 — no network
    I/O outside `caliper models pull`. The cache is read-only at runtime.
+6. **"`cargo build --workspace` is green, so my GPU change is fine."** No.
+   `caliper-bellows` and `caliper-touchstone` are excluded from
+   `default-members`. Build them by name (`cargo build -p caliper-bellows`)
+   before claiming a GPU/NPU change works.
 
 ---
 
 ## Where to Stash Notes Between Sessions
 
-Use the conversation memory (`/home/mj/.claude/projects/-steelbore-caliper/memory/`).
+Use the conversation memory (`/home/mj/.claude/projects/-spacecraft-software-caliper/memory/`).
 Anything you learn about the user's workflow preferences, project context, or
 non-obvious decisions belongs there — not in PR descriptions or comments.
 
@@ -90,6 +150,6 @@ Memory files are *agent's* memory and are session-local.
 
 ## Maintainer
 
-**Mohamed Hammad** &lt;[Mohamed.Hammad@Steelbore.com](mailto:Mohamed.Hammad@Steelbore.com)&gt;
+**Mohamed Hammad** &lt;[Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)&gt;
 Copyright (c) 2026 Mohamed Hammad &nbsp;|&nbsp; License: GPL-3.0-or-later
-[https://Caliper.Steelbore.com/](https://Caliper.Steelbore.com/)
+[https://Caliper.SpacecraftSoftware.org/](https://Caliper.SpacecraftSoftware.org/)