docs: consolidate docs/ into mkdocs site (PER-190)

CHANGELOG.md

@@ -22,7 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Pending artifact alert on every `abc` subcommand.** When `.agentic-beacon/pending.yaml` is non-empty, every `abc` invocation prints a one-line stderr notice: `⚠ N pending artifacts. Run 'abc adopt' to wire them.` Exit code is unaffected.
 
 - **Removed `artifacts.knowledge` from `beacon.yaml`.** Knowledge is now auto-derived from markdown links inside adopted contexts and skills. On first sync after upgrade, any existing `artifacts.knowledge` list is silently dropped and a single INFO log is emitted. To keep a knowledge file available, ensure it is referenced by a markdown link from an adopted context or skill.
-- **Agent dependencies moved from frontmatter to `agents/agents.yaml`.** `requires:` blocks in agent frontmatter are no longer supported. Agent skill dependencies must be declared in `agents/agents.yaml` instead. `abc sync` and `abc warehouse status` will hard-error if agent files contain `requires:` frontmatter or if `agents/agents.yaml` is missing/malformed. See [Migration Guide: Artifact Dependencies via Frontmatter](./docs/migrations/artifact-dependencies-frontmatter.md) for upgrade instructions.
+- **Agent dependencies moved from frontmatter to `agents/agents.yaml`.** `requires:` blocks in agent frontmatter are no longer supported. Agent skill dependencies must be declared in `agents/agents.yaml` instead. `abc sync` and `abc warehouse status` will hard-error if agent files contain `requires:` frontmatter or if `agents/agents.yaml` is missing/malformed. See [Migration Guide: Artifact Dependencies via Frontmatter](./docs/archive/migrations/artifact-dependencies-frontmatter.md) for upgrade instructions.
 
 ### Added
 
@@ -31,7 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Migration
 
-- See [Migration Guide: Artifact Dependencies via Frontmatter](./docs/migrations/artifact-dependencies-frontmatter.md) for step-by-step instructions on adding `requires:` frontmatter to existing warehouses.
+- See [Migration Guide: Artifact Dependencies via Frontmatter](./docs/archive/migrations/artifact-dependencies-frontmatter.md) for step-by-step instructions on adding `requires:` frontmatter to existing warehouses.
 
 ### Breaking Changes (PER-113 — unify-agent-distribution)
 

CONTRIBUTING.md

@@ -1,25 +1,25 @@
 # Contributing to Agentic Beacon
 
-Welcome to Agentic Beacon — the package manager for AI coding agents. This guide covers everything you need to go from zero to a merged pull request: environment setup, the project's architecture and conventions, how to run tests, and the contribution workflow.
+Welcome — this file is the entry point for new contributors. It covers everything you need to go from a fresh clone to running tests locally. The deeper reference material (architecture, code style, testing strategy, design patterns, gotchas, etc.) is in `docs/contributing/` and is primarily there so AI coding agents working in the repo have something to grep. Human contributors generally won't need to read them end-to-end.
+
+---
 
 ## Project Overview
 
 **Agentic Beacon** is a Python CLI tool (published as `agentic-beacon` on PyPI, invoked as `abc`) that solves "context drift" — the problem that arises when multiple projects each maintain their own `AGENTS.md` or `CLAUDE.md` files independently, causing agent instructions to diverge over time. Agentic Beacon introduces a **warehouse** model: a single git repository that is the source of truth for shared agent artifacts (contexts, knowledge, skills, agents). Projects connect to the warehouse and receive artifacts as per-file symlinks rather than copies. Edits flow back through those symlinks into the warehouse working tree; `abc warehouse contribute` pushes them upstream to the team.
 
 The primary consumers of this project are software engineering teams that use AI coding assistants (Claude Code, OpenCode, or compatible tools) across multiple repositories. The CLI is the sole public interface; there is no HTTP API, no library API surface, and no frontend.
 
-The project is pure Python (requires Python 3.12+) and is distributed as a standard PyPI wheel. It uses [uv](https://github.com/astral-sh/uv) as its package and workspace manager. The package is structured as a [uv workspace](https://docs.astral.sh/uv/concepts/workspaces/) with the single workspace member at `libs/beacon/`. The entrypoint registered in `pyproject.toml` is `abc = "beacon.cli.main:main"`.
+The project is pure Python (requires Python 3.12+) and is distributed as a standard PyPI wheel. It uses [uv](https://github.com/astral-sh/uv) as its package and workspace manager — the package is structured as a [uv workspace](https://docs.astral.sh/uv/concepts/workspaces/) with a single workspace member at `libs/beacon/`. The entrypoint registered in `pyproject.toml` is `abc = "beacon.cli.main:main"`.
 
-Key runtime dependencies are [Click](https://click.palletsprojects.com/) (CLI framework), [Rich](https://rich.readthedocs.io/) (terminal formatting), [Textual](https://textual.textualize.io/) (TUI for `abc adopt`), [Pydantic](https://docs.pydantic.dev/) and [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) (data models and settings), [PyYAML](https://pyyaml.org/) (YAML I/O), and [Loguru](https://loguru.readthedocs.io/) (structured logging).
+**Platform support:** macOS and Linux only. Windows is explicitly rejected at startup because symlink-based artifact sync is not reliably supported there.
 
-**Platform support:** macOS and Linux only. Windows is explicitly rejected at startup via `utils/platform.py`. The rejection reason is symlink-based artifact sync, which is not reliably supported on Windows.
+---
 
 ## Environment Setup
 
 ### 1. Install Python 3.12+
 
-The project requires Python 3.12 or newer. If you do not have it, install via [pyenv](https://github.com/pyenv/pyenv) (recommended) or your system package manager:
-
 ```bash
 # macOS with Homebrew
 brew install python@3.12
@@ -31,8 +31,6 @@ pyenv global 3.12
 
 ### 2. Install uv
 
-[uv](https://docs.astral.sh/uv/) is the package manager for this project. It manages the virtual environment, resolves dependencies, and runs tools.
-
 ```bash
 # macOS / Linux
 curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -54,7 +52,7 @@ uv sync --group dev
 
 The `--group dev` flag installs test and linting dependencies (`pytest`, `pytest-cov`, `pytest-asyncio`, `pre-commit`, `ruff`). Run this once, and again any time `pyproject.toml` changes.
 
-**Important:** Never run `uv sync` inside `libs/beacon/` and never create a separate virtualenv there. The workspace is managed from the repo root; the single `.venv` at the root is shared across all workspace members.
+> **Important:** never run `uv sync` inside `libs/beacon/`, and never create a separate virtualenv there. The workspace is managed from the repo root; the single `.venv` at the root is shared across all workspace members.
 
 ### 4. Install pre-commit hooks
 
@@ -66,7 +64,7 @@ This wires the pre-commit hooks (ruff lint, ruff format, YAML/TOML/JSON syntax c
 
 ### 5. Configure git identity
 
-Some tests run real `git` subprocess commands and require a configured git identity. If you do not have a global git config, set one:
+Some tests run real `git` subprocess commands and require a configured git identity:
 
 ```bash
 git config --global user.email "you@example.com"
@@ -76,14 +74,11 @@ git config --global user.name "Your Name"
 ### 6. Verify the setup
 
 ```bash
-# Should print the installed version (e.g. 3.2.0)
 .venv/bin/abc --version
-
-# Run the unit test suite — all should pass
 uv run pytest -m "not integration" -q
 ```
 
-### Environment Variables
+### Environment variables
 
 The CLI reads a small set of optional environment variables via `pydantic-settings`. All are optional with sensible defaults:
 
@@ -92,20 +87,27 @@ The CLI reads a small set of optional environment variables via `pydantic-settin
 | `ABC_GLOBAL_AGENTS_DIR` | `Path` | `~/.abc/agents` | Override the global agents directory used for agent symlink installation |
 | `ABC_MAX_COMMITS_LOOKBACK` | `int` | `100` | Maximum number of git commits to scan when annotating warehouse artifacts with recency |
 | `ABC_DEBUG` | `bool` | `false` | Enable debug-level logging output |
-
-These are rarely needed in normal development. The most common override is `ABC_MAX_COMMITS_LOOKBACK` if you have a very deep git history in a test warehouse.
-
-## Documentation
-
-- [Commands](docs/contributing/commands.md) — build, run, test, and lint commands
-- [Project Layout](docs/contributing/project-layout.md) — annotated directory tree and organization
-- [Architecture](docs/contributing/architecture.md) — four-layer design, subsystem boundaries, data flows
-- [Configuration System](docs/contributing/configuration.md) — settings, workspace config, manifest models
-- [Local Development](docs/contributing/local-development.md) — dev loop, debugging, running subsets
-- [Code Style & Conventions](docs/contributing/code-style.md) — naming, imports, formatting rules
-- [Design Patterns & Techniques](docs/contributing/design-patterns.md) — recurring patterns and when to use them
-- [Testing Strategy](docs/contributing/testing.md) — test layout, runners, unit vs integration, fixtures
-- [Contribution Workflow](docs/contributing/contribution-workflow.md) — branches, PRs, CI gates, release process
-- [Documentation Maintenance](docs/contributing/documentation.md) — how docs are built and published
-- [Gotchas & Sharp Edges](docs/contributing/gotchas.md) — known traps, architecture debt, sharp corners
-- [Open Questions](docs/contributing/open-questions.md) — unresolved items for future documentation updates
+| `BEACON_OFFLINE` | `bool` | `false` | Skip integration tests that require the package index (planes, flaky networks) |
+
+These are rarely needed in normal development.
+
+---
+
+## Where to Go Next
+
+The deep reference lives in `docs/contributing/`. These files are primarily written for AI coding agents working in the repo — the most efficient way to use them is to point your agent at the directory ("read `docs/contributing/`") and let it pick what's relevant.
+
+| File | Covers |
+|---|---|
+| [`commands.md`](docs/contributing/commands.md) | Build, run, test, and lint commands |
+| [`project-layout.md`](docs/contributing/project-layout.md) | Annotated directory tree |
+| [`architecture.md`](docs/contributing/architecture.md) | Four-layer design, five domains, data flows |
+| [`configuration.md`](docs/contributing/configuration.md) | Settings, workspace config, manifest models |
+| [`local-development.md`](docs/contributing/local-development.md) | Dev loop, debugging, running subsets |
+| [`code-style.md`](docs/contributing/code-style.md) | Naming, imports, formatting rules |
+| [`design-patterns.md`](docs/contributing/design-patterns.md) | Recurring patterns and when to use them |
+| [`testing.md`](docs/contributing/testing.md) | Test layout, unit vs integration, fixtures |
+| [`contribution-workflow.md`](docs/contributing/contribution-workflow.md) | Branches, PRs, CI gates, release process |
+| [`documentation.md`](docs/contributing/documentation.md) | How docs are built and published |
+| [`gotchas.md`](docs/contributing/gotchas.md) | Known traps and sharp corners |
+| [`open-questions.md`](docs/contributing/open-questions.md) | Unresolved items |

README.md

@@ -126,8 +126,6 @@ Everything is a per-file **symlink** into the warehouse clone — one physical f
 
 **Frontmatter dependencies.** Skills declare `requires:` in YAML frontmatter; agents declare dependencies in `agents/agents.yaml`. `abc sync` validates all declared dependencies are adopted and errors early if any are missing.
 
-> **Read:** [Decision — Single Warehouse Write Entrypoint](docs/no-project-overrides.md) for the full design rationale.
-
 > **Platform support:** macOS and Linux only.
 
 ## Artifact Types
@@ -142,7 +140,7 @@ Everything is a per-file **symlink** into the warehouse clone — one physical f
 - **Skills** — reusable workflows wired as slash commands into each tool's live directories.
 - **Agents** — sub-agent definitions declared per-project in `beacon.yaml` and symlinked into project-local `.claude/agents/` and `.opencode/agents/`; edits flow back to the warehouse through the symlink.
 
-> See **[Artifact Type Matrix](./docs/artifact-type-matrix.md)** for the full design rationale.
+> See **[Artifact Types](https://shadowsong27.github.io/agentic-beacon/concepts/artifact-types/)** for the full design rationale.
 
 ## When to Use Agentic Beacon
 
@@ -158,21 +156,19 @@ Everything is a per-file **symlink** into the warehouse clone — one physical f
 
 📚 **Full documentation site:** [shadowsong27.github.io/agentic-beacon](https://shadowsong27.github.io/agentic-beacon/)
 
-### Conceptual Design (docs/)
-- **[Artifact Type Matrix](./docs/artifact-type-matrix.md)** — Scope and tool-specificity axes; how they drive command design
-- **[Agentic Warehouse Design](./docs/agentic-warehouse-design.md)** — High-level design and architecture
-- **[Boot Context Design](./docs/boot-context-design/)** — AGENTS.md architecture and patterns
-- **[Spec-Driven Development](./docs/spec-driven-development.md)** — Structured approach to feature planning
-- **[Migration: Artifact Dependencies via Frontmatter](./docs/migrations/artifact-dependencies-frontmatter.md)** — Migrate warehouses to auto-derived knowledge and `requires:` frontmatter
-
-### Practical Guides (guides/)
-- **[Getting Started](./guides/getting-started.md)** — Full onboarding walkthrough
-- **[Warehouse Creation](./guides/warehouse-creation.md)** — Creating and structuring a warehouse
-- **[Contributing Back](./guides/warehouse-contribution-guide.md)** — Commit agent improvements back to the warehouse
-- **[beacon.yaml Reference](./guides/beacon-yaml-reference.md)** — Full configuration schema
-- **[Team Collaboration](./guides/team-collaboration.md)** — Multi-team workflows
-- **[Advanced Patterns](./guides/advanced-patterns.md)** — Glob patterns, dry-run, warehouse commands, migration
-- **[CLI Reference](./docs/cli-reference.md)** — Full command reference
+### Concepts
+- **[How It Works](https://shadowsong27.github.io/agentic-beacon/concepts/how-it-works/)** — Warehouse + beacon mental model and sync flow
+- **[Philosophy](https://shadowsong27.github.io/agentic-beacon/design/philosophy/)** — Why this exists, why markdown not RAG, why lightweight (Design)
+- **[Artifact Types](https://shadowsong27.github.io/agentic-beacon/concepts/artifact-types/)** — Scope and tool-specificity axes; how they drive command design
+
+### Guides
+- **[Quick Start](https://shadowsong27.github.io/agentic-beacon/quickstart/)** — Onboarding walkthrough
+- **[Warehouse Creation](https://shadowsong27.github.io/agentic-beacon/guides/warehouse-creation/)** — Creating and structuring a warehouse
+- **[Contributing Back](https://shadowsong27.github.io/agentic-beacon/guides/contributing-back/)** — Commit agent improvements back to the warehouse
+
+### Reference
+- **[beacon.yaml](https://shadowsong27.github.io/agentic-beacon/reference/beacon-yaml/)** — Full configuration schema
+- **[CLI Reference](https://shadowsong27.github.io/agentic-beacon/reference/cli/)** — Full command reference
 
 ### Examples (examples/)
 - **[Beacon Configs](./examples/beacon-configs/)** — Example `beacon.yaml` configurations for common project setups