feat: WP-0001 foundation + WP-0002 core extensions

WP-0001 — Foundation & GAAF Baseline
- SCOPE.md, ARCHITECTURE-LAYERS.md, contracts/ tree
- .claude/rules/ stubs filled (architecture, stack, boundary)
- 57 tests (pytest), pyproject.toml with ruff+mypy, CI workflow

WP-0002 — Core Extensions (FR-4 + FR-3)
- FR-4: BudgetTracker (thread-safe) + LLMBudgetExceededError +
  optional RunConfig.budget_tracker + enforcement in all adapters
- FR-3: async_execute_prompt on LLMAdapter ABC (asyncio.to_thread
  fallback) + native asyncio.create_subprocess_exec in ClaudeCodeAdapter

81 tests passing.

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

.claude/rules/architecture.md

@@ -1,8 +1,58 @@
 ## Architecture
 
-<!-- TODO: Describe the key design decisions and component structure.
-     Key modules, data flows, external integrations, state machines, etc. -->
+llm-connect is structured as a **GAAF-2026 layered library**. See
+`ARCHITECTURE-LAYERS.md` for the full layer map and scorecard.
 
-## Quick Reference
+### Layer summary
 
-`~/the-custodian/state-hub/mcp_server/TOOLS.md` — MCP tool reference
+```
+Core (frozen after v1)
+  LLMAdapter ABC          adapter.py
+  RunConfig / LLMResponse models.py
+  LLMError hierarchy      exceptions.py
+  MockLLMAdapter          adapter.py   ← test primitive, belongs with Core
+
+Functional (evolvable, independently shippable)
+  OpenAIAdapter           openai.py
+  GeminiAdapter           gemini.py
+  OpenRouterAdapter       openrouter.py
+  ClaudeCodeAdapter       claude_code.py
+  EmbeddingAdapter ABC    embedding_adapter.py
+  OpenAICompatibleEmbeddingAdapter  embedding_openai.py
+  EmbeddingCache          embedding_cache.py
+  create_adapter()        factory.py
+  create_embedding_adapter()  embedding_factory.py
+  _token_estimator        _token_estimator.py
+  similarity utilities    similarity.py
+
+Configuration (user-controlled declarative state)
+  resolve_llm() chain     toml_config.py   ← 7-level TOML priority chain
+  LLMConfig / load_config config.py
+  _http shared utility    _http.py         ← also used by Functional adapters
+```
+
+### Dependency rule
+
+Core ← Functional ← Configuration  
+No upward dependencies. `_http.py` is consumed by Functional only.
+
+### Key design decisions
+
+**API key resolution** (`config.resolve_api_key`): three-step chain —
+explicit argument → environment variable → plaintext key file in project root.
+Adapters raise `LLMConfigurationError` at construction time if no key is found
+(except `ClaudeCodeAdapter` which needs no key).
+
+**TOML config chain** (`toml_config.resolve_llm`): 7 priority levels allow
+per-project and per-user LLM preferences. Currently defaults to `markitect`
+app_name for backward compatibility — consumers pass their own `app_name`.
+
+**Factory pattern** (`factory.create_adapter`): lazy imports prevent pulling
+all provider SDKs at module load. Add a new provider by registering its FQN
+in `_PROVIDERS`.
+
+**ClaudeCodeAdapter subprocess model**: prompt is piped via stdin (not CLI
+arg) to avoid shell argument length limits on large prompts (>30 KB).
+
+**Retry logic**: `OpenAIAdapter` and `OpenRouterAdapter` retry on 429 and 5xx
+with exponential backoff. `GeminiAdapter` does not (rate-limit handling deferred).

.claude/rules/repo-boundary.md

@@ -1,8 +1,17 @@
 ## Repo boundary
 
-This repo owns **{PROJECT_NAME}** only. It does not own:
+This repo owns **llm-connect** — the multi-provider LLM client library — only.
 
-<!-- TODO: List what belongs in adjacent repos, e.g.:
-- SSH key management → railiance-infra/
-- State hub code     → the-custodian/state-hub/
--->
+It does NOT own:
+
+- **API key storage / secret management** → caller's environment (env vars,
+  key files, vault). llm-connect resolves keys but does not store them.
+- **Consumer routing logic** → `inter-hub/AgentBridge.hs`, `markitect` etc.
+  `RoutingPolicy` (WP-0003) provides primitives; policy data belongs in the consumer.
+- **The Claude Code CLI binary** → installed separately; `ClaudeCodeAdapter`
+  shells out to it.
+- **markitect application code** → `markitect.llm` is a shim that re-exports
+  from here; all implementation lives in this repo.
+- **State hub / custodian infrastructure** → `the-custodian/state-hub/`
+- **IHF bridge scripts** → `inter-hub/scripts/llm_bridge.py` lives in inter-hub,
+  not here. llm-connect is a dependency of that script.

.claude/rules/stack-and-commands.md

@@ -1,19 +1,59 @@
 ## Stack
 
-<!-- TODO: Fill in language, frameworks, and key dependencies -->
-- **Language:**
-- **Key deps:**
+- **Language:** Python 3.10+
+- **Key deps (runtime):** `toml` (TOML config parsing)
+- **Key deps (dev):** `pytest`, `ruff`, `mypy`
+- **HTTP:** stdlib `urllib` via `_http.py` (no requests/httpx runtime dep)
+- **Build:** setuptools / uv
 
 ## Dev Commands
 
 ```bash
-# TODO: Fill in the standard commands for this repo
-
-# Install dependencies
+# Install (editable, with dev extras)
+uv pip install -e ".[dev]"
+# or
+pip install -e ".[dev]"
 
 # Run tests
+uv run pytest
+# or
+pytest
 
-# Lint / type check
+# Lint
+uv run ruff check .
 
-# Build / package (if applicable)
+# Type check
+uv run mypy llm_connect
+
+# Run a single test file
+uv run pytest tests/test_models.py -v
+
+# Build package (dry run)
+uv build --no-sources
+```
+
+## Project layout
+
+```
+llm_connect/         source package
+  adapter.py         LLMAdapter ABC + Mock/ErrorLLMAdapter
+  models.py          RunConfig, LLMResponse
+  exceptions.py      LLMError hierarchy
+  factory.py         create_adapter()
+  openai.py          OpenAIAdapter
+  gemini.py          GeminiAdapter
+  openrouter.py      OpenRouterAdapter
+  claude_code.py     ClaudeCodeAdapter
+  embedding_adapter.py  EmbeddingAdapter ABC
+  embedding_openai.py   OpenAICompatibleEmbeddingAdapter
+  embedding_cache.py    EmbeddingCache
+  embedding_factory.py  create_embedding_adapter()
+  toml_config.py     7-level TOML config resolution
+  config.py          LLMConfig, resolve_api_key, find_project_root
+  _http.py           shared HTTP POST utility
+  _token_estimator.py  rough token count estimate
+  similarity.py      cosine similarity utilities
+tests/               pytest test suite
+contracts/           GAAF-2026 contract docs
+workplans/           workplan files (LLM-WP-NNNN)
 ```