codrsquad · zsimic · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026
diff --git a/.claude/settings.json b/.claude/settings.json
@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/portable-python:*)",
+      "Bash(.venv/bin/pytest:*)",
+      "Bash(.venv/bin/python scripts/check_okf.py:*)",
+      "Bash(tox:*)"
+    ]
+  }
+}
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,76 +1,24 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for Claude Code working in this repository.
 
-## What This Project Does
+`portable-python` is a CLI and Python library that compiles portable (statically-linked, relocatable) CPython binaries from source — see [`docs/overview.md`](docs/overview.md) for the full picture.
 
-portable-python is a CLI tool and Python library for compiling portable CPython binaries from source. Binaries are statically linked so they can be extracted to any folder and used without installation. Supports Linux and macOS (not Windows).
+## Documentation lives in `docs/`
 
-## Common Commands
+The authoritative, self-contained documentation is the OKF knowledge bundle under **`docs/`** — start at [`docs/index.md`](docs/index.md). **Don't duplicate it in this file — link to it.** When you change behavior, update the matching `docs/` entry and add a line to [`docs/log.md`](docs/log.md).
 
-```bash
-# Run all tests (tox manages envs for py310-314, coverage, docs, style)
-tox
+| Looking for… | Go to |
+|--------------|-------|
+| What it does, guiding principles, end-to-end build flow | [`docs/overview.md`](docs/overview.md) |
+| Core classes & how they collaborate | [`docs/architecture/`](docs/architecture/index.md) |
+| Concepts: portability, static linking, telltale detection, folder masking, ppp-marker, build layout | [`docs/concepts/`](docs/concepts/index.md) |
+| CLI commands & options | [`docs/cli/`](docs/cli/index.md) |
+| External modules (the statically-linked C libraries) | [`docs/modules/`](docs/modules/index.md) |
+| Configuration (`portable-python.yml`) | [`docs/configuration/`](docs/configuration/index.md) |
+| Dev setup, tests, code style, debugging, Docker, CI/CD, and common tasks | [`docs/guides/`](docs/guides/index.md) |
 
-# Run tests for a single Python version
-tox -e py313
+## Working in this repo
 
-# Run a single test
-pytest tests/test_build.py::test_build_rc -vv
-
-# Lint check / auto-fix
-tox -e style
-tox -e reformat
-
-# Run tests directly (from venv)
-pytest tests/
-
-# CI uses: uvx --with tox-uv tox -e py
-```
-
-## Architecture
-
-**Key classes:**
-
-- `PPG` (versions.py) — Global singleton holding config, target platform, and version families. All modules access shared state through this.
-- `BuildSetup` (__init__.py) — Coordinates overall compilation: downloads sources, builds external modules, then CPython.
-- `ModuleBuilder` (__init__.py) — Abstract base for anything that gets compiled. Both external C modules and Python itself extend this.
-- `PythonBuilder` (__init__.py) — Extends ModuleBuilder for Python implementations.
-- `Cpython` (cpython.py) — Concrete PythonBuilder that handles CPython's configure/make/install, optimization, and finalization.
-- `Config` (config.py) — Loads and merges YAML configuration (portable-python.yml) with platform-specific overrides.
-- `PythonInspector` (inspector.py) — Validates portability of a built Python by checking shared library dependencies and paths.
-
-**External modules** (external/xcpython.py): `Bdb`, `Bzip2`, `Gdbm`, `LibFFI`, `Mpdec`, `Openssl`, `Readline`, `Sqlite`, `Uuid`, `Xz`, `Zlib`, `Zstd` — each is a ModuleBuilder subclass that compiles a C library statically before CPython is built.
-
-**Key patterns:**
-
-- Platform-specific compile logic uses `_do_linux_compile()` / `_do_macos_compile()` method dispatch.
-- Environment injection: `xenv_*` methods provide CPATH, LDFLAGS, PATH etc. for compilation.
-- On macOS, `/usr/local` is masked with a RAM disk (`FolderMask`) to prevent accidental dynamic linking.
-- External modules compile to a shared `build/deps/` prefix; CPython finds them via CPATH/LDFLAGS.
-- Telltale detection: modules check for marker files (`m_telltale`) to determine if system already has the library.
-- No patches to upstream CPython source — relies solely on configure flags.
-
-**runez** is the foundational utility library (file ops, system info, CLI decorators, logging, Version/PythonSpec types). Check runez before reimplementing anything.
-
-**Additional pointers:**
-
-- `ModuleCollection.selected` contains only the modules chosen for a build — not all candidates.
-- Build logs go to `build/logs/NN-modulename.log` (e.g. `01-openssl.log`, `02-cpython.log`).
-- YAML config supports platform-specific overrides and path templates — see CONFIGURATION.md.
-- See ARCHITECTURE.md for class hierarchy and design patterns, DEVELOP.md for common tasks and dependencies.
-
-## Testing
-
-- pytest with 100% code coverage target
-- Tests mock `runez.run()` to avoid actual compilation — uses `--dryrun` mode
-- `conftest.py` provides a `cli` fixture (from runez) and forbids HTTP calls (`GlobalHttpCalls.forbid()`)
-- Sample YAML configs in `tests/sample-config*.yml` for testing configuration parsing
-
-## Linting
-
-Ruff handles all linting and formatting. Key settings in pyproject.toml:
-- Line length: 140
-- McCabe complexity: max 18
-- Security checks (S rules) disabled in tests
-- Numpy-style docstrings
+- Check **runez** before reimplementing file / system / CLI / logging / version helpers — see [`docs/guides/local-development.md`](docs/guides/local-development.md).
+- The docs use the OKF format; keep the bundle conformant (`scripts/check_okf.py docs`) when you edit it.
diff --git a/CONFIGURATION.md b/CONFIGURATION.md
diff --git a/DEVELOP.md b/DEVELOP.md
diff --git a/docs/architecture/build-setup.md b/docs/architecture/build-setup.md
@@ -0,0 +1,29 @@
+---
+type: Class
+title: BuildSetup
+description: Orchestrates a build end to end — resolves the spec, builds external modules then CPython, validates, and compresses the result.
+tags: [class, build, coordinator]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# BuildSetup
+
+The build orchestrator (`__init__.py`). The [`build`](/cli/build.md) command — and library users — construct one from a python spec and call `compile()`:
+
+```python
+from portable_python import BuildSetup
+
+BuildSetup("cpython:3.13.2").compile()
+```
+
+## Mental model
+
+A conductor: it compiles nothing itself, it sequences the pieces. `compile()` is the spine — it cleans the [build folders](/concepts/build-layout.md), enters a [`BuildContext`](/concepts/folder-masking.md) (macOS isolation), builds the [external modules](/modules/index.md) into `build/deps/`, then builds CPython through its [`PythonBuilder`](/architecture/python-builder.md) (a [`Cpython`](/architecture/cpython.md)), and finally compresses the install into `dist/`. **External libraries first, CPython last.**
+
+It owns the [`Folders`](/architecture/config.md) (resolved paths) and the python builder; shared config, target platform, and version family come from [`PPG`](/architecture/ppg.md).
+
+## Worth knowing
+
+- **Start reading at `compile()`** — it calls everything else in order.
+- A `--prefix` makes the build **non-portable**; without it the result is relocatable (see [ppp-marker](/concepts/ppp-marker.md) and [portability](/concepts/portability.md)).
+- It requires a full `X.Y.Z` spec — a bare `3.13` is rejected; `"latest"` (or empty) resolves to the newest known version.