From 0941075baad3f0d7d9e64bb88c5bf63e171dc501 Mon Sep 17 00:00:00 2001
From: Cole Speelman <crspeelman@gmail.com>
Date: Tue, 11 Aug 2026 22:15:59 -0400
Subject: [PATCH] docs: align source preview with project voice

---
 PUBLIC-SNAPSHOT.json      |  2 +-
 PUBLIC-SNAPSHOT.sha256    |  4 +--
 README.md                 | 59 +++++++++++++++++++++++++++++++++------
 scripts/check-licenses.sh |  7 +++++
 4 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/PUBLIC-SNAPSHOT.json b/PUBLIC-SNAPSHOT.json
index aba1521..d3a8945 100644
--- a/PUBLIC-SNAPSHOT.json
+++ b/PUBLIC-SNAPSHOT.json
@@ -1 +1 @@
-{"schema_version":2,"project":"sandwich-hime","export_policy":"exact-allowlist-v1","export_mode":"release","file_count":98,"allowlist_sha256":"91213f72ddef67aaed7764f08f89fd13281bb79855f3680e1ec0d05cda0e133d","manifest_sha256":"474d6a21ee5ea38ae42d0a2aaa897b6fe95f2b1a8faa46e1884646c185ea9f6f"}
+{"schema_version":2,"project":"sandwich-hime","export_policy":"exact-allowlist-v1","export_mode":"release","file_count":98,"allowlist_sha256":"91213f72ddef67aaed7764f08f89fd13281bb79855f3680e1ec0d05cda0e133d","manifest_sha256":"e2eec9fed86828dff900a09f39a05021c48f295bf87a1a9b2896d673886c9a69"}
diff --git a/PUBLIC-SNAPSHOT.sha256 b/PUBLIC-SNAPSHOT.sha256
index 4efe1ef..0b2360b 100644
--- a/PUBLIC-SNAPSHOT.sha256
+++ b/PUBLIC-SNAPSHOT.sha256
@@ -13,7 +13,7 @@ f7ac75b443f4ca16b503241344b41aeff9503b0c30bedc2b119551d83cb0fa90  ./DCO.txt
 1b398f6e2679a4c1d6c5a03468f66b86be34e82ed40e3a029935c74742502e7a  ./LICENSES.md
 b6aa08e5ccaec3c5dccdc19d7cd7f54a70adae4d57966263c7aa353c7ba70e08  ./MAINTAINERS.md
 6638db2f1fba831c79de835ce95c847a5b36c5b5c693b99a28655b2d096cc440  ./OUTPUT_EXCEPTION.md
-793989c26290a8c0da15f7e4168942a15dad32e83ff5b826dcb5f6b6829b1065  ./README.md
+88150b7ae8759b62829f3a0ba2b03b1c44abc2f688349d5b3ad39ebf654a29d4  ./README.md
 6007b80cd80f8f238a1e77de6417aa0c69c159dce6f5a5bd085ef87b8865f5c9  ./RELEASE.md
 f5fe4d5bf5f8b72ad974060faf458ad26bb4b2c05c2bd9539533247b7462f76b  ./ROADMAP.md
 2c86f5b983dfeb97a02d46850fa42e18cab1ed23201822aa3c344b9d2e1b0c3f  ./SECURITY.md
@@ -86,7 +86,7 @@ ff76daee5b642ad84af31701833246d68b54d09580192312d750a7a2e893a692  ./sando/go.mod
 85621a44c730582f4410ac2c70418b739fb55e916f7e6b73a1a619982c459572  ./sando/write.go
 b188917e258890e6b6e4840a6fd946fc9a77cabc2068da3764f221e4a6a5df97  ./sando/write_test.go
 2d92e1578d8907ab434f1924f698b586f47d6c9bc6fab989639a5332fd235163  ./scripts/README.md
-c61456ce33eb6e6f7a1b44d436cf99c33e31f8a07b59fb4723096c6a41b7f215  ./scripts/check-licenses.sh
+032832440431a532771054bcbfb6c46944ead61bfdb38ca11a049aae14459bc3  ./scripts/check-licenses.sh
 e35895423494018d5e380c447a8fb9bd5410af82a4a12f9fbaae391c286dd32a  ./scripts/check-site.sh
 d53d93df7e355ec45e6540703c6098c3fb49a610cb35600c5d525afa0f0d48cb  ./scripts/release-check.sh
 be79b6bd1d18ce53a1b4cf301f7c4fa41342728d0a6333a766171cfc586a65d5  ./scripts/verify-public-install.sh
diff --git a/README.md b/README.md
index 7c2233f..c36a682 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,10 @@
 
 # Sandwich Hime
 
-Sandwich Hime (Hime-san) is an HTML-first component compiler for Go. It keeps the direct, mixed-markup feeling of classic PHP while producing typed, deterministic Go that an ordinary `go build` can audit and deploy.
+Sandwich Hime is an HTML-first, ahead-of-time template engine for Go. Hime-san
+keeps the direct, mixed-markup feeling of classic PHP while compiling trusted
+`.sando` templates into typed, deterministic Go components that an ordinary
+`go build` can audit and deploy.
 
 ```sando
 <?sando go
@@ -24,12 +27,22 @@ The generated API is ordinary Go:
 func Profile(page ProfileView) sando.Component
 ```
 
-Hime-san is a development tool, not an application framework. A consuming project keeps its `.sando` sources, commits the adjacent `.sando.go` output, and imports only the small Apache-2.0 `sando` runtime. Hime-san never owns the router, middleware, layout policy, request object, or production server.
+Templates are what authors write. Components are the typed output and
+composition unit. Hime-san is an intentionally opinionated development tool,
+not an application framework: a consuming project keeps its `.sando` sources,
+commits the adjacent `.sando.go` output, and imports only the small Apache-2.0
+`sando` runtime. Hime-san never owns the router, middleware, layout policy,
+request object, or production server.
 
 ## Status
 
 This repository is an unsupported public pre-1.0 source preview, not a supported v1 release. EQL Wiki remains the proof-of-production proving ground, and v1 is gated on security testing, cross-platform determinism, and a 14-day production soak with no renderer, security, or accessibility regression.
 
+[sandwichhime.com](https://sandwichhime.com/) is the running self-hosted proof:
+its pages begin as `.sando`, compile into ordinary Go, and ship in an ordinary
+Go service whose production binary links only the `sando` runtime—not this
+compiler.
+
 For repository development:
 
 ```sh
@@ -41,10 +54,13 @@ go test ./...
 (cd examples/eql-shaped && himesan dev --config himesan.json)
 ```
 
-The example's development server remains the application's own `net/http`
-program. Hime-san builds it in the user cache, health-checks a random loopback
-upstream, and serves the last healthy candidate through
-`http://127.0.0.1:7331` with local-only reload diagnostics.
+The portable path is `generate`, `check`, and the project's normal Go tools.
+For people who want the paved road, `himesan dev` deliberately does more: it
+builds the application's own `net/http` program in the user cache,
+health-checks a random loopback candidate, preserves the last healthy process,
+and serves it through `http://127.0.0.1:7331` with local-only reload
+diagnostics. That is a Cole-shaped convenience, not a production server or a
+requirement. Take the paved path—or don't.
 
 The eventual versioned installs are:
 
@@ -57,12 +73,12 @@ Those vanity paths must not be advertised as working until the corresponding sig
 
 ## The contract
 
-- One typed component per `.sando` file.
+- One typed template, compiled into one component constructor, per `.sando` file.
 - Go statements are trusted source code; rendered values are untrusted.
 - `<?= ... ?>` escapes for the statically known HTML context.
 - `<?~ ... ?>` composes another component and propagates errors.
 - Ambiguous or unsupported HTML contexts fail compilation.
-- Generation is deterministic, formatted, atomic, and never edits handwritten Go or `go.mod`.
+- Generation is deterministic and formatted; each owned output is replaced atomically, and handwritten Go and `go.mod` are never edited.
 - `check` is read-only and detects invalid or stale generated output.
 - Production builds need no compiler binary.
 
@@ -83,4 +99,29 @@ The project is never marketed as bare “Hime”; that name is already used by a
 
 ## Why
 
-This is a love letter to hand-built web development: the immediacy of a 2004 personal site, with typed interfaces, reproducible builds, modern contextual safety, and boring production operations. Performance claims will follow published measurements, never precede them.
+This is a love letter to hand-built web development: the immediacy of Cole's
+2004 Geocities page for a PSO Gameclub, with typed interfaces, reproducible
+builds, modern contextual safety, and boring production operations. The first
+prototype was a wonderfully cursed princess that could `bless` or `rebuke`
+templates, announced when Hime-san was resting, and concluded that creating a
+compiler was not hubris but destiny. The jokes stayed because developer joy is
+part of the point. The security boundary grew up because care is part of the
+point too.
+
+Cole builds with ADHD, neurodivergence, a disabled body, finite energy, and a
+family he wants to leave understandable work for. Clear files, calm defaults,
+accessible documentation, last-good development builds, and honest limitations
+are therefore operating requirements—not decorative empathy. The project aims
+to leave room for individuals, tiny teams, learners, disabled people, and
+anyone too small to win a complexity contest.
+
+Open source permits corporate use. Independence comes instead from the
+AGPL-3.0-only compiler, the Apache-2.0 runtime, application-owned generated
+output, contributor-held copyright, founder-led governance, release-key
+control, and careful trademark stewardship. Companies may use and contribute;
+participation does not confer ownership of the identity or project.
+
+The fuller origin, Japanese craft inspirations, family dedication, human-art
+commitment, and stewardship boundary live on the
+[project site](https://sandwichhime.com/docs/project/). Performance claims will
+follow published measurements, never precede them.
diff --git a/scripts/check-licenses.sh b/scripts/check-licenses.sh
index fa69ad9..6bf9d23 100755
--- a/scripts/check-licenses.sh
+++ b/scripts/check-licenses.sh
@@ -134,6 +134,13 @@ while IFS= read -r -d '' path; do
 			# Cryptographic dependency records are externally covered data.
 			continue
 			;;
+		private/*.png | private/**/*.png)
+			# A tracked private binary needs an exact entry in the private map.
+			# The map and material remain outside reviewed public snapshots.
+			grep -Fq "\`$path\`" private/LICENSES.md || \
+				fail "$path needs an exact private license-map entry"
+			continue
+			;;
 		PUBLIC-SNAPSHOT.json | PUBLIC-SNAPSHOT.sha256)
 			# Generated factual provenance; covered by LICENSES.md.
 			continue