docs(adr): document the src layout and the build pipeline

[Chemaclass]

🤔 Background

ADR-010 decided that large files become module directories, and was later amended on where the aggregator lives. What no document stated was the whole picture: what the modules are, in what order they load, how the single-file binary is assembled from them, and which tests keep all of that honest.

That was spread across ADR-010, build.sh comments, .claude/rules/architecture-map.md and eight issues. Someone arriving at the project — contributor or agent — had no single place to read it.

💡 Changes

ADR-011 is descriptive, not a new decision. It records:

• The rule — src/ holds module directories and nothing else; each has an index.sh entry point holding onlysource lines.
• The 17 modules, in entrypoint source order, with what each owns.
• The three load-order facts that are load-bearing, not stylistic — api/globals.sh runs set -euo pipefail at file scope; config/env.sh executes at source time and must precede console/, whose palette is built at file scope; main/ is sourced last.
• The six build steps, and why "aggregators hold only source lines" follows from step 2 emitting a file's body before recursing into its sources.
• The eight contracts that enforce all of it — with the warning that a path-grepping contract passes vacuously the moment its target moves, as happened in refactor(state): split src/state.sh into a src/state/ module #946.
• How to change things — add a function, a file, a module, a subcommand; and how to prove a split is a relocation.

docs/project-overview.md gains the module table and a pointer to the ADR. It previously described src/ in a single line, written before any of this work.

✅ Verification

Every figure was checked against the tree rather than written from memory — module count, file counts, line counts, the aggregator rule, the embed markers, the src/dev/ exclusion, and that all five named contract tests exist.

That caught a wrong claim in my own draft: I'd written that the largest file is main/test.sh at 485 lines; it's actually assert/core.sh at 970. Corrected, and the passage now explains why all three of the deliberately-large files stayed whole.

make sa · make lint · full suite (1604 passed, 0 failed) green.

[Chemaclass]

🤔 Background

ADR-010 decided that large files become module directories, and was later amended on where the aggregator lives. What no document stated was the whole picture: what the modules are, in what order they load, how the single-file binary is assembled from them, and which tests keep all of that honest.

That was spread across ADR-010, build.sh comments, .claude/rules/architecture-map.md and eight issues. Someone arriving at the project — contributor or agent — had no single place to read it.

💡 Changes

ADR-011 is descriptive, not a new decision. It records:

• The rule — src/ holds module directories and nothing else; each has an index.sh entry point holding onlysource lines.
• The 17 modules, in entrypoint source order, with what each owns.
• The three load-order facts that are load-bearing, not stylistic — api/globals.sh runs set -euo pipefail at file scope; config/env.sh executes at source time and must precede console/, whose palette is built at file scope; main/ is sourced last.
• The six build steps, and why "aggregators hold only source lines" follows from step 2 emitting a file's body before recursing into its sources.
• The eight contracts that enforce all of it — with the warning that a path-grepping contract passes vacuously the moment its target moves, as happened in refactor(state): split src/state.sh into a src/state/ module #946.
• How to change things — add a function, a file, a module, a subcommand; and how to prove a split is a relocation.

docs/project-overview.md gains the module table and a pointer to the ADR. It previously described src/ in a single line, written before any of this work.

✅ Verification

Every figure was checked against the tree rather than written from memory — module count, file counts, line counts, the aggregator rule, the embed markers, the src/dev/ exclusion, and that all five named contract tests exist.

That caught a wrong claim in my own draft: I'd written that the largest file is main/test.sh at 485 lines; it's actually assert/core.sh at 970. Corrected, and the passage now explains why all three of the deliberately-large files stayed whole.

make sa · make lint · full suite (1604 passed, 0 failed) green.

[Chemaclass]

🤔 Background

ADR-010 decided that large files become module directories, and was later amended on where the aggregator lives. What no document stated was the whole picture: what the modules are, in what order they load, how the single-file binary is assembled from them, and which tests keep all of that honest.

That was spread across ADR-010, build.sh comments, .claude/rules/architecture-map.md and eight issues. Someone arriving at the project — contributor or agent — had no single place to read it.

💡 Changes

ADR-011 is descriptive, not a new decision. It records:

• The rule — src/ holds module directories and nothing else; each has an index.sh entry point holding onlysource lines.
• The 17 modules, in entrypoint source order, with what each owns.
• The three load-order facts that are load-bearing, not stylistic — api/globals.sh runs set -euo pipefail at file scope; config/env.sh executes at source time and must precede console/, whose palette is built at file scope; main/ is sourced last.
• The six build steps, and why "aggregators hold only source lines" follows from step 2 emitting a file's body before recursing into its sources.
• The eight contracts that enforce all of it — with the warning that a path-grepping contract passes vacuously the moment its target moves, as happened in refactor(state): split src/state.sh into a src/state/ module #946.
• How to change things — add a function, a file, a module, a subcommand; and how to prove a split is a relocation.

docs/project-overview.md gains the module table and a pointer to the ADR. It previously described src/ in a single line, written before any of this work.

✅ Verification

Every figure was checked against the tree rather than written from memory — module count, file counts, line counts, the aggregator rule, the embed markers, the src/dev/ exclusion, and that all five named contract tests exist.

That caught a wrong claim in my own draft: I'd written that the largest file is main/test.sh at 485 lines; it's actually assert/core.sh at 970. Corrected, and the passage now explains why all three of the deliberately-large files stayed whole.

make sa · make lint · full suite (1604 passed, 0 failed) green.

[Chemaclass]

🤔 Background

ADR-010 decided that large files become module directories, and was later amended on where the aggregator lives. What no document stated was the whole picture: what the modules are, in what order they load, how the single-file binary is assembled from them, and which tests keep all of that honest.

That was spread across ADR-010, build.sh comments, .claude/rules/architecture-map.md and eight issues. Someone arriving at the project — contributor or agent — had no single place to read it.

💡 Changes

ADR-011 is descriptive, not a new decision. It records:

• The rule — src/ holds module directories and nothing else; each has an index.sh entry point holding onlysource lines.
• The 17 modules, in entrypoint source order, with what each owns.
• The three load-order facts that are load-bearing, not stylistic — api/globals.sh runs set -euo pipefail at file scope; config/env.sh executes at source time and must precede console/, whose palette is built at file scope; main/ is sourced last.
• The six build steps, and why "aggregators hold only source lines" follows from step 2 emitting a file's body before recursing into its sources.
• The eight contracts that enforce all of it — with the warning that a path-grepping contract passes vacuously the moment its target moves, as happened in refactor(state): split src/state.sh into a src/state/ module #946.
• How to change things — add a function, a file, a module, a subcommand; and how to prove a split is a relocation.

docs/project-overview.md gains the module table and a pointer to the ADR. It previously described src/ in a single line, written before any of this work.

✅ Verification

Every figure was checked against the tree rather than written from memory — module count, file counts, line counts, the aggregator rule, the embed markers, the src/dev/ exclusion, and that all five named contract tests exist.

That caught a wrong claim in my own draft: I'd written that the largest file is main/test.sh at 485 lines; it's actually assert/core.sh at 970. Corrected, and the passage now explains why all three of the deliberately-large files stayed whole.

make sa · make lint · full suite (1604 passed, 0 failed) green.

[Chemaclass]

🤔 Background

ADR-010 decided that large files become module directories, and was later amended on where the aggregator lives. What no document stated was the whole picture: what the modules are, in what order they load, how the single-file binary is assembled from them, and which tests keep all of that honest.

That was spread across ADR-010, build.sh comments, .claude/rules/architecture-map.md and eight issues. Someone arriving at the project — contributor or agent — had no single place to read it.

💡 Changes

ADR-011 is descriptive, not a new decision. It records:

• The rule — src/ holds module directories and nothing else; each has an index.sh entry point holding onlysource lines.
• The 17 modules, in entrypoint source order, with what each owns.
• The three load-order facts that are load-bearing, not stylistic — api/globals.sh runs set -euo pipefail at file scope; config/env.sh executes at source time and must precede console/, whose palette is built at file scope; main/ is sourced last.
• The six build steps, and why "aggregators hold only source lines" follows from step 2 emitting a file's body before recursing into its sources.
• The eight contracts that enforce all of it — with the warning that a path-grepping contract passes vacuously the moment its target moves, as happened in refactor(state): split src/state.sh into a src/state/ module #946.
• How to change things — add a function, a file, a module, a subcommand; and how to prove a split is a relocation.

docs/project-overview.md gains the module table and a pointer to the ADR. It previously described src/ in a single line, written before any of this work.

✅ Verification

Every figure was checked against the tree rather than written from memory — module count, file counts, line counts, the aggregator rule, the embed markers, the src/dev/ exclusion, and that all five named contract tests exist.

That caught a wrong claim in my own draft: I'd written that the largest file is main/test.sh at 485 lines; it's actually assert/core.sh at 970. Corrected, and the passage now explains why all three of the deliberately-large files stayed whole.

make sa · make lint · full suite (1604 passed, 0 failed) green.

[Chemaclass]

🤔 Background

ADR-010 decided that large files become module directories, and was later amended on where the aggregator lives. What no document stated was the whole picture: what the modules are, in what order they load, how the single-file binary is assembled from them, and which tests keep all of that honest.

That was spread across ADR-010, build.sh comments, .claude/rules/architecture-map.md and eight issues. Someone arriving at the project — contributor or agent — had no single place to read it.

💡 Changes

ADR-011 is descriptive, not a new decision. It records:

• The rule — src/ holds module directories and nothing else; each has an index.sh entry point holding onlysource lines.
• The 17 modules, in entrypoint source order, with what each owns.
• The three load-order facts that are load-bearing, not stylistic — api/globals.sh runs set -euo pipefail at file scope; config/env.sh executes at source time and must precede console/, whose palette is built at file scope; main/ is sourced last.
• The six build steps, and why "aggregators hold only source lines" follows from step 2 emitting a file's body before recursing into its sources.
• The eight contracts that enforce all of it — with the warning that a path-grepping contract passes vacuously the moment its target moves, as happened in refactor(state): split src/state.sh into a src/state/ module #946.
• How to change things — add a function, a file, a module, a subcommand; and how to prove a split is a relocation.

docs/project-overview.md gains the module table and a pointer to the ADR. It previously described src/ in a single line, written before any of this work.

✅ Verification

Every figure was checked against the tree rather than written from memory — module count, file counts, line counts, the aggregator rule, the embed markers, the src/dev/ exclusion, and that all five named contract tests exist.

That caught a wrong claim in my own draft: I'd written that the largest file is main/test.sh at 485 lines; it's actually assert/core.sh at 970. Corrected, and the passage now explains why all three of the deliberately-large files stayed whole.

make sa · make lint · full suite (1604 passed, 0 failed) green.

[Chemaclass]

🤔 Background

ADR-010 decided that large files become module directories, and was later amended on where the aggregator lives. What no document stated was the whole picture: what the modules are, in what order they load, how the single-file binary is assembled from them, and which tests keep all of that honest.

That was spread across ADR-010, build.sh comments, .claude/rules/architecture-map.md and eight issues. Someone arriving at the project — contributor or agent — had no single place to read it.

💡 Changes

ADR-011 is descriptive, not a new decision. It records:

• The rule — src/ holds module directories and nothing else; each has an index.sh entry point holding onlysource lines.
• The 17 modules, in entrypoint source order, with what each owns.
• The three load-order facts that are load-bearing, not stylistic — api/globals.sh runs set -euo pipefail at file scope; config/env.sh executes at source time and must precede console/, whose palette is built at file scope; main/ is sourced last.
• The six build steps, and why "aggregators hold only source lines" follows from step 2 emitting a file's body before recursing into its sources.
• The eight contracts that enforce all of it — with the warning that a path-grepping contract passes vacuously the moment its target moves, as happened in refactor(state): split src/state.sh into a src/state/ module #946.
• How to change things — add a function, a file, a module, a subcommand; and how to prove a split is a relocation.

docs/project-overview.md gains the module table and a pointer to the ADR. It previously described src/ in a single line, written before any of this work.

✅ Verification

Every figure was checked against the tree rather than written from memory — module count, file counts, line counts, the aggregator rule, the embed markers, the src/dev/ exclusion, and that all five named contract tests exist.

That caught a wrong claim in my own draft: I'd written that the largest file is main/test.sh at 485 lines; it's actually assert/core.sh at 970. Corrected, and the passage now explains why all three of the deliberately-large files stayed whole.

make sa · make lint · full suite (1604 passed, 0 failed) green.

[Chemaclass]

🤔 Background

ADR-010 decided that large files become module directories, and was later amended on where the aggregator lives. What no document stated was the whole picture: what the modules are, in what order they load, how the single-file binary is assembled from them, and which tests keep all of that honest.

That was spread across ADR-010, build.sh comments, .claude/rules/architecture-map.md and eight issues. Someone arriving at the project — contributor or agent — had no single place to read it.

💡 Changes

ADR-011 is descriptive, not a new decision. It records:

• The rule — src/ holds module directories and nothing else; each has an index.sh entry point holding onlysource lines.
• The 17 modules, in entrypoint source order, with what each owns.
• The three load-order facts that are load-bearing, not stylistic — api/globals.sh runs set -euo pipefail at file scope; config/env.sh executes at source time and must precede console/, whose palette is built at file scope; main/ is sourced last.
• The six build steps, and why "aggregators hold only source lines" follows from step 2 emitting a file's body before recursing into its sources.
• The eight contracts that enforce all of it — with the warning that a path-grepping contract passes vacuously the moment its target moves, as happened in refactor(state): split src/state.sh into a src/state/ module #946.
• How to change things — add a function, a file, a module, a subcommand; and how to prove a split is a relocation.

docs/project-overview.md gains the module table and a pointer to the ADR. It previously described src/ in a single line, written before any of this work.

✅ Verification

Every figure was checked against the tree rather than written from memory — module count, file counts, line counts, the aggregator rule, the embed markers, the src/dev/ exclusion, and that all five named contract tests exist.

That caught a wrong claim in my own draft: I'd written that the largest file is main/test.sh at 485 lines; it's actually assert/core.sh at 970. Corrected, and the passage now explains why all three of the deliberately-large files stayed whole.

make sa · make lint · full suite (1604 passed, 0 failed) green.