diff --git a/CLAUDE.md b/CLAUDE.md
index 2bfb0e03..d7b8e732 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,34 +1,120 @@
-# Markitect — Claude Code Instructions
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## Custodian State Hub Integration
 
 This project is tracked as the **markitect** domain in the Custodian State Hub.
 Hub topic ID: `5571d954-0d30-4950-980d-7bcaaad8e3e2`
 
-### Session Protocol
+**Session start:** Call `get_domain_summary("markitect")` via the `state-hub` MCP tool.
+If the hub is not reachable: `cd ~/the-custodian/state-hub && make api`
 
-**At the start of every session:**
-Call `get_state_summary()` via the `state-hub` MCP tool to orient yourself.
-If the hub is not reachable, start it: `cd ~/the-custodian/state-hub && make api`
+**Session end:** Call `add_progress_event()` with `topic_id` above, a `summary`, and `event_type` (`note` / `milestone` / `blocker`).
 
-**At the end of every session:**
-Call `add_progress_event()` with at minimum:
-- `topic_id`: `5571d954-0d30-4950-980d-7bcaaad8e3e2`
-- `summary`: what was accomplished or left in-flight
-- `event_type`: `note` for routine updates, `milestone` for completions, `blocker` for blockers
+**Available state-hub MCP tools:** `get_state_summary`, `get_domain_summary`, `add_progress_event`, `create_workstream`, `create_task`, `update_task_status`, `record_decision`, `resolve_decision`.
 
-### Available State-Hub MCP Tools
+If the hub API is unavailable, use `curl` against `http://127.0.0.1:8000/docs`.
 
-- `get_state_summary()` — full cross-domain overview
-- `add_progress_event(summary, topic_id, event_type, detail)` — log progress
-- `create_workstream(topic_id, title, ...)` — create a new workstream
-- `create_task(workstream_id, title, ...)` — create a task under a workstream
-- `update_task_status(task_id, status)` — move task through lifecycle
-- `record_decision(title, decision_type, topic_id, ...)` — log decisions
-- `resolve_decision(decision_id, rationale, decided_by)` — close a decision
+---
 
-### If the MCP Server is Not Available
+## Development Commands
 
-The state-hub MCP server (`state-hub`) is registered at user scope in `~/.claude.json`.
-It requires the API to be running at `http://127.0.0.1:8000`.
-Fallback: use `curl` directly against the REST API — see `/docs` at the hub URL.
+All commands assume the `markitect-venv` virtual environment is active (`source ~/.venvs/markitect-venv/bin/activate` or equivalent). The package is installed in editable mode.
+
+```bash
+# Run the core test suite
+pytest
+
+# Run a single test file
+pytest tests/test_issue_17_batch_processing.py
+
+# Run tests by marker
+pytest -m unit
+pytest -m "not slow"
+
+# Run with coverage
+pytest --cov=markitect
+
+# Run only fast unit tests (TDD inner loop)
+pytest tests/unit/
+
+# CLI entry point
+markitect --help
+
+# Infospace subcommands (primary active development area)
+markitect infospace --help
+markitect infospace eval-summary --update-metrics
+
+# LLM helper commands
+markitect llm-helper "<question>"
+markitect llm-catalog
+markitect llm-check
+markitect llm-default
+markitect llm-preference
+
+# Install / reinstall in dev mode
+pip install -e ".[analysis]"
+```
+
+## Architecture
+
+MarkiTect is a CLI-driven markdown engine that treats documents as structured, queryable information spaces. Entry point: `markitect/cli.py` → `main()` (Click group). All subcommand groups are registered at the bottom of `cli.py`.
+
+### Core Modules (`markitect/`)
+
+| Module | Purpose |
+|--------|---------|
+| `spaces/` | InformationSpace model — composability, events, history, transclusion, rendering, sync |
+| `prompts/` | Prompt resolver, compiler, execution engine, quality gates, dependency graph, traceability |
+| `llm/` | LLM adapter layer — 4 text providers + embedding adapter; 7-layer config resolution |
+| `infospace/` | Infospace lifecycle — init, entity parsing, evaluation, composition, graph export |
+| `analysis/` | Graph analysis (networkx) and FCA (Formal Concept Analysis, pure Python) |
+| `schema*/` | Schema generation, validation, naming, refinement, metaschema |
+| `core/` | Foundational parser, AST, serializer, workspace |
+
+### LLM Configuration (`markitect/llm/`)
+
+Resolution order (highest → lowest priority):
+1. CLI flags (`--provider`, `--model`)
+2. `MARKITECT_HELPER_MODEL` env var (model only)
+3. User preference (`[llm.preference]` in `~/.config/markitect/config.toml`)
+4. Directory preference (`[llm.preference]` in `.markitect.toml`)
+5. Directory default (`[llm.default]` in `.markitect.toml`)
+6. User default (`[llm.default]` in `~/.config/markitect/config.toml`)
+7. Hardcoded fallback: `gemini/gemini-2.5-flash`
+
+Canonical models: `markitect/llm/models.py` (`RunConfig`, `LLMResponse`) and `markitect/llm/adapter.py` (`LLMAdapter`). These are mirrored in the standalone `/home/worsch/llm-connect/` package (`llm_connect`), which is installed as a local path dependency. `markitect/prompts/execution/{models,llm_adapter}.py` are re-export shims for backward compatibility.
+
+**Gotcha:** The `OPENROUTER_API_KEY` env var may hold a stale key — `unset OPENROUTER_API_KEY` before running LLM commands if you get auth errors. `claude-code` provider fails inside Claude Code sessions (nested session restriction).
+
+### Infospace (`markitect/infospace/`)
+
+An infospace is a directory-based collection of typed entities governed by an `infospace.yaml` config. Key files:
+- `config.py` — config loading, `find_infospace_config()`, `DisciplineBinding`
+- `entity_parser.py` — parse entity markdown files from `output/entities/<slug>.md`
+- `evaluation.py` / `evaluation_io.py` — per-entity LLM evaluation (5 dimensions)
+- `state.py` — `build_state()` aggregates entity + evaluation state
+- `history.py` / `checks/` — viability tracking and collection-level checks
+
+Slugs use **underscores** (e.g., `accumulation_of_stock`). Active example: `examples/infospace-with-history/` (988 entities).
+
+### Layered Architecture
+
+The project has a partially-implemented layered architecture separate from `markitect/`:
+- `domain/` — domain models (issues, projects)
+- `infrastructure/` — config, repositories, logging, connection management
+- `application/` — application layer (mostly empty)
+- `capabilities/` — pluggable capability packages (`issue-facade`, `release-management`, `testdrive-jsui`, `markitect-utils`, `markitect-content`, `kaizen-agentic`)
+
+### Tests
+
+Tests live in `tests/`. Many test files are named `test_issue_NNN_*.py` (TDD by issue). Layered tests follow `test_l{N}_*.py` naming. The `tests/unit/` subtree has the cleanest structure and covers `prompts/`, `spaces/`, `llm/`, `infospace/`, `analysis/`.
+
+Pytest config is in `pytest.ini`. Relevant markers: `unit`, `integration`, `e2e`, `slow`, `performance`.
+
+### Active Roadmap Files
+
+- `roadmap/infospace-tooling/PLAN.md` — main infospace roadmap (S1 ✅ S2 ✅ S3 nearly done)
+- `roadmap/infospace-s3-closeout/PLAN.md` — S3 close-out tasks (C.1–C.8)
+- `roadmap/llm-shared-library/PLAN.md` — llm-connect extraction (S1+S2 done, S3 pending)