docs(claude): expand CLAUDE.md with commands and architecture

Replaces the stub (State Hub integration only) with full dev commands,
module architecture overview, LLM config resolution chain, infospace
conventions, and active roadmap pointers. Removes CLAUDE.custodian.md
(superseded by the expanded CLAUDE.md).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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)