[bestickley]

README reorder

Moves sections only; no content changes.

1. Features → Why → Design Principles (moved up from the middle, so the pitch is read first)
2. Prerequisites → Getting Started → Basic Example
3. Architecture (right after the example, so readers choose a construct before tuning it)
4. Configuration → Splitting a Large App Across Functions (advanced tuning, next to the other customization sections)
5. Bring Your Own Resources → Preview Environments → … (unchanged)

Anchors still work. Each "above"/"below" reference points within its own section.

Architecture diagrams with AWS icons

GitHub's Mermaid renderer can't load icon packs, so the architecture-beta diagrams were stuck with generic server/disk/database icons. npm and Construct Hub don't render Mermaid at all, so those pages showed raw code blocks.

• Sources are in docs/diagrams/*.mmd (same diagrams, now using logos:aws-* icons from @iconify-json/logos, a new devDependency).
• pnpm diagrams renders them to committed SVGs with a pinned @mermaid-js/mermaid-cli run via npx. It isn't a devDependency, so installs don't pull in Puppeteer and Chrome.
• pnpm diagrams:check runs as part of test. Each SVG is stamped with its source's SHA-256 and the check compares the hashes, so it needs no Chrome. It doesn't diff bytes because Chromium's font layout differs between macOS and Linux.
• The README links the SVGs at raw.githubusercontent.com/.../main so they render on npm and Construct Hub. docs/diagrams/ is excluded from the tarball.
• Workflow documented in docs/development-guide.md.

Review note: the README images point at main, so the README preview on this PR shows broken images until it merges. View the SVGs under docs/diagrams/ in the Files tab.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
npm/@iconify-json/logos	1.2.16	Unknown	Unknown
npm/@iconify/types	2.0.0	🟢 4.2	Details Check Score Reason Code-Review 🟢 5 Found 8/16 approved changesets -- score normalized to 5 Maintained 🟢 10 30 commit(s) and 6 issue activity found in the last 90 days -- score normalized to 10 Token-Permissions ⚠️ -1 No tokens found Packaging ⚠️ -1 packaging workflow not detected Dangerous-Workflow ⚠️ -1 no workflows found CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Pinned-Dependencies ⚠️ -1 no dependencies found Binary-Artifacts 🟢 10 no binaries found in the repo License 🟢 10 license file detected Signed-Releases ⚠️ -1 no releases found Fuzzing ⚠️ 0 project is not fuzzed Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches Security-Policy ⚠️ 0 security policy file not detected SAST ⚠️ 0 SAST tool is not run on all commits -- score normalized to 0

Scanned Files

• pnpm-lock.yaml

[bestickley]

pr-review summary

Converged in 1 round (FULL review of c026e1e..822dadb, bugs + spec axes). No high- or medium-severity findings; the spec reviewer found the branch matches the PR description.

Round	Range	Raw (bugs/spec)	Blocking	Fixed	Escalated
1	FULL	4 / 0 (+1 side note)	0	4	1

Fixes (16df895), all in scripts/render-diagrams.mjs

• The source stamp now covers the mmdc and @iconify-json/logos versions, not just the .mmd. The icon pack is exact-pinned, which takes it out of the automated upgrade-dev-deps filter, so a version bump is a hand edit that diagrams:check makes you re-render for.
• diagrams:check now also fails on an SVG whose .mmd was renamed or deleted.
• npx runs through a shell on Windows, where npx.cmd can't be spawned without one.
• The header comment describes the hash check (it said "older than its .mmd").

Escalations

• README images link raw.githubusercontent.com/.../main, so the READMEs of already-published versions on npm and Construct Hub will show the current diagrams. Accepted as is: the diagrams rarely change, and relative links can't work with docs/diagrams/ excluded from the package.

pnpm test: 46 suites, 1131 tests pass; diagrams:check passes.