Merge pull request #454 from control-toolbox/refactor/docs-structure

Refactor documentation structure: consolidate internals page

Author: ocots

.gitignore

@@ -45,6 +45,7 @@ reports/
 .vscode/
 .extras/
 .tmp/
+.claude/
 
 # Temporary test artifacts (created during test runs)
 test/_test_*/

AGENTS.md

@@ -4,72 +4,38 @@ Quick-reference for any agent working on this repository.
 
 ---
 
-## Project Overview
+## Repository Layout
 
-**CTBase.jl** is the foundational Julia package in the [control-toolbox](https://github.com/control-toolbox) ecosystem.
-It provides the **base layer**: shared types, exceptions, extensions infrastructure, and development tools.
-
----
-
-## Source Architecture
-
-Submodule layout (all public symbols accessed via qualified paths — no top-level exports):
+Standard control-toolbox package structure. Each directory may contain a `README.md`
+with package-specific details — read it before working in that directory.
 
 ```text
-src/
-├── CTBase.jl           # Top-level manifest — exports nothing
-├── Core/               # Core types and utilities
-├── Descriptions/       # Type descriptions and metadata
-├── Exceptions/         # Structured exception types
-├── Extensions/         # Extension infrastructure
-└── Unicode/            # Unicode utilities
-
-ext/
-├── CoveragePostprocessing.jl  # Coverage report postprocessing
-├── DocumenterReference.jl     # Documenter.jl reference generation
-└── TestRunner.jl             # Test runner with progress bar
-
-test/suite/             # Tests organised by functionality (not by src layout)
-docs/                   # Documenter.jl site (auto-generated API)
-dev/                    # Code philosophy, operational rules, plan template (versioned)
+src/        # Source code: one submodule per responsibility, no top-level exports
+ext/        # Weak-dependency extensions (loaded on demand by Julia)
+test/suite/ # Test suite: organised by functionality, not by src/ layout
+docs/       # Documentation site (DocumenterVitepress)
 ```
 
 ---
 
-## Developer resources
-
-| File | Purpose |
-|---|---|
-| [`dev/philosophy/PHILOSOPHY.md`](dev/philosophy/PHILOSOPHY.md) | Code philosophy — modules, types/traits, exceptions, docstrings, testing, docs |
-| [`dev/RULES.md`](dev/RULES.md) | Operational rules — running tests (MCP), building docs, git, output capture |
-| [`dev/planning.md`](dev/planning.md) | Plan template — phases, steps, human checkpoints |
-
----
-
-## Devin Workflows
+## Developer Resources
 
-| Workflow | Trigger | Purpose |
-|---|---|---|
-| `architecture.md` | — | Introducing new types, restructuring modules, reviewing SOLID/patterns |
-| `docstrings.md` | — | Writing or reviewing Julia docstrings |
-| `documentation.md` | `glob: docs/**/*` | Documenter.jl layout, `make.jl` template, `api_reference.jl`, `InterLinks` setup |
-| `exceptions.md` | — | Adding error paths, contract stubs, argument validation |
-| `modules.md` | `glob: src/**/*.jl, ext/**/*.jl` | Submodule conventions: qualified imports, manifest pattern, export policy, DAG ordering |
-| `performance.md` | — | Hot paths, inner loops, profiling, benchmarking |
-| `plan.md` | — | Writing an implementation plan before coding |
-| `testing-creation.md` | — | Writing or reviewing test files under `test/suite/` |
-| `testing-execution.md` | `model_decision` | How to run tests (commands, `tee` capture) |
-| `type-stability.md` | — | New structs, parametric types, `@inferred` test design |
+Design philosophy, operational rules, and plan templates live in the
+[control-toolbox Handbook](https://github.com/control-toolbox/Handbook):
 
-Workflows live in `.devin/workflows/`.
+| Topic | Link |
+| --- | --- |
+| Code philosophy (modules, types/traits, exceptions, docstrings, testing, docs) | [`PHILOSOPHY.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/PHILOSOPHY.md) |
+| Operational rules (tests, coverage, docs, git) | [`RULES.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/RULES.md) |
+| Plan template | [`PLAN.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/PLAN.md) |
 
 ---
 
 ## Key Conventions
 
-- **No top-level exports** — use `CTBase.Submodule.symbol` everywhere.
-- **Qualified imports** — `using PackageName: PackageName`, never bare `using`.
+- **No top-level exports** — use `Package.Submodule.symbol` everywhere.
+- **Qualified imports** — `import Pkg: Pkg`, never bare `using`.
 - **Fake types at module top-level** — never inside test functions.
-- **Plans before code** — write a plan and confirm with the user before touching files. Template: [`dev/planning.md`](dev/planning.md).
+- **Plans before code** — write a plan and confirm with the user before touching files.
 - **Docstrings last** — written only after all implementation steps are stable.
 - **Never commit or push without explicit user approval.**

CHANGELOGS.md

@@ -85,7 +85,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `testing.md`: Categories, fakes/stubs, module + callable function template
   - `documentation.md`: API generation, guides, draft workflow
 - **Added agent guides**: Added `AGENTS.md` (agent navigation guide) and `CLAUDE.md` (Claude project context)
-- **Added planning template**: Added `dev/planning.md` for implementation plans
+- **Added planning template**: Added `dev/PLAN.md` for implementation plans
 - **Added operational rules**: Added `dev/RULES.md` for MCP, doc build, git, and output capture procedures
 
 #### **Documentation Build Improvements**

CLAUDE.md

@@ -1,34 +1,41 @@
-# CTBase.jl — Claude project context
+# CTBase.jl — Agent Navigation Guide
 
-## Essential rules
+Quick-reference for any agent working on this repository.
 
-1. **Never commit or push without explicit approval.** Ask first, every time.
-2. **Run tests via the `ct-dev-mcp` MCP** — `get_test_command` → run with `tee` →
-   `generate_report`. Never invent the test command.
-3. **Build docs draft-first** — `draft = true` globally to validate links, then per file
-   with `Draft = false`, then full build. See `dev/RULES.md`.
-4. **Qualify everything** — `Module.symbol` at every call site; `import Pkg: Pkg` not
-   `using Pkg`; no top-level package exports.
-5. **Write a plan before coding** — any task touching more than one file or a public
-   interface needs a plan confirmed by the user first. Template in `dev/planning.md`.
-6. **Docstrings last** — written only after the API is stable.
-7. **Fake types at module top-level** — never inside test functions (world-age issues).
+---
 
-## Where to find more
+## Repository Layout
 
-| Topic | File |
-| --- | --- |
-| Code philosophy (modules, types/traits, exceptions, docstrings, testing, docs) | [`dev/philosophy/`](dev/philosophy/PHILOSOPHY.md) |
-| Operational rules (MCP, doc build, git, output capture) | [`dev/RULES.md`](dev/RULES.md) |
-| Plan template | [`dev/planning.md`](dev/planning.md) |
-
-## Project structure (quick reference)
+Standard control-toolbox package structure. Each directory may contain a `README.md`
+with package-specific details — read it before working in that directory.
 
 ```text
-src/CTBase.jl           # top-level manifest — exports nothing
-src/<Module>/<Module>.jl  # submodule manifests
-ext/                    # weak-dependency extensions (CoveragePostprocessing, DocumenterReference, TestRunner)
-test/suite/             # tests by functionality, not by src layout
-docs/                   # Documenter.jl site
-dev/                    # philosophy, rules, planning template (versioned)
+src/        # Source code: one submodule per responsibility, no top-level exports
+ext/        # Weak-dependency extensions (loaded on demand by Julia)
+test/suite/ # Test suite: organised by functionality, not by src/ layout
+docs/       # Documentation site (DocumenterVitepress)
 ```
+
+---
+
+## Developer Resources
+
+Design philosophy, operational rules, and plan templates live in the
+[control-toolbox Handbook](https://github.com/control-toolbox/Handbook):
+
+| Topic | Link |
+| --- | --- |
+| Code philosophy (modules, types/traits, exceptions, docstrings, testing, docs) | [`PHILOSOPHY.md`](https://github.com/control-toolbox/Handbook/blob/main/PHILOSOPHY.md) |
+| Operational rules (tests, coverage, docs, git) | [`RULES.md`](https://github.com/control-toolbox/Handbook/blob/main/RULES.md) |
+| Plan template | [`PLAN.md`](https://github.com/control-toolbox/Handbook/blob/main/PLAN.md) |
+
+---
+
+## Key Conventions
+
+- **No top-level exports** — use `Package.Submodule.symbol` everywhere.
+- **Qualified imports** — `import Pkg: Pkg`, never bare `using`.
+- **Fake types at module top-level** — never inside test functions.
+- **Plans before code** — write a plan and confirm with the user before touching files.
+- **Docstrings last** — written only after all implementation steps are stable.
+- **Never commit or push without explicit user approval.**

README.template.md

@@ -5,7 +5,7 @@ For instructions on how to customize this README.template.md and use the central
 please see the user guide: https://github.com/orgs/control-toolbox/discussions/67
 -->
 
-The CTBase.jl package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
+CTBase.jl is the **foundational layer** of the [control-toolbox ecosystem](https://github.com/control-toolbox): it provides the shared types, exception infrastructure, extensions scaffolding, and development utilities that all other packages in the ecosystem build on.
 
 <!-- INCLUDE_BADGES: Documentation, CI, Coverage, PackageEvaluation, Release, License, CodeStyle -->