Skip to content

docs: add a from-zero overview with architecture diagrams - #34

Merged
ttncode merged 2 commits into
mainfrom
docs/overview-and-diagrams
Sep 17, 2026
Merged

ttncode merged 2 commits into
mainfrom
docs/overview-and-diagrams

Conversation

@ttncode

@ttncode ttncode commented Sep 17, 2026

Copy link
Copy Markdown
Owner

What this changes

  • Adds docs/README.md, the from-zero entry page: what scaffold is, repository map, how scaffold new works, what a generated project contains, commands table, glossary, reading path.
  • Adds six diagrams under docs/diagrams/ (HTML source + exported SVG): system context, code layers, scaffold new, generated project, release flow, scaffold update. Each node was derived from the code, not from existing prose.
  • README.md: links the new page first under Documentation.

How it was verified

  • Every command, flag, path and function in docs/README.md and the diagrams checked against scaffold, lib/*.sh, common/ and the reusable workflows; an independent review re-checked them.
  • SVGs: parsed as XML, rendered in headless Chrome at 830px (GitHub column width); smallest text ≥ 8px, no clipping.
  • bats tests/documentation.bats 5/5 (a deliberately broken path and image in the new page made the path and link tests fail). mise run test-unit 199/199. mise run lint clean.

Checklist

  • mise run lint passes
  • mise run test-runner passes — docs only; CI runs it
  • New behaviour has a test that fails without the change
  • Docs that describe changed behaviour were updated in the same commit
  • No unrelated changes

@ttncode
ttncode merged commit 43e5be6 into main Sep 17, 2026
21 checks passed
@ttncode
ttncode deleted the docs/overview-and-diagrams branch September 17, 2026 07:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant