feat: publish Sandwich Hime tooling preview

Publish the exact sanitized Agent Skill and VS Code preview source tree with independent license boundaries, deterministic provenance manifests, and no private development history. Material design and implementation assistance was provided by OpenAI Codex. Signed-off-by: Cole Speelman <crspeelman@gmail.com>
2026-08-12 20:33:51 -04:00
commit 6df87bc958
51 changed files with 7424 additions and 0 deletions
@@ -0,0 +1,58 @@
+---
+name: sandwich-hime
+description: Author, compose, migrate, review, debug, or secure Sandwich Hime `.sando` templates and the Apache-licensed Sando runtime. Use for Hime-san CLI workflows, generated `.sando.go` provenance and freshness, typed component nesting, contextual output diagnostics, trust-capability review, or Windows/Linux project setup.
+---
+
+# Sandwich Hime
+
+Work from the repository root. Treat `.sando` as Sandwich Hime templates and
+`.san` exclusively as source for the separate San language.
+
+## Inspect before acting
+
+1. Read `go.mod`; record the exact `gamertan.com/sandwich-hime/sando` version.
+2. Inspect adjacent `.sando.go` headers for compiler version, runtime ABI, and
+   source digest. Never hand-edit generated files.
+3. Run `himesan version --json`. Require a compatible runtime ABI and preserve
+   every pinned version. Never substitute `@latest` or silently update a module.
+4. Read [references/authoring.md](references/authoring.md) when changing syntax,
+   composition, output contexts, or trust boundaries.
+5. Read [references/workflows.md](references/workflows.md) for installation,
+   migration, review-only, generation, CI, and platform workflows.
+
+## Choose the workflow
+
+- For review, diagnosis, or security work, run `himesan check --json` only.
+  Do not write unless the user authorizes changes.
+- For authorized template changes, edit `.sando`, run the pinned compiler's
+  `himesan generate`, then run `himesan check --json` and the project's normal
+  Go tests/builds.
+- Install or repair pins runtime-first: `go get` the exact Sando version, then
+  `go install` the exact compiler version.
+- Use typed component functions and `<?~ Component(...) ?>` composition. Do
+  not invent an inheritance, block, or implicit-layout framework.
+- Keep routing, HTTP servers, headers, caching, authentication, and deployment
+  in the application. Sandwich Hime compiles templates; it does not own them.
+
+## Enforce security boundaries
+
+- Treat static template markup and Go code as trusted project source.
+- Treat every `TrustHTML`, `TrustURL`, `TrustJS`, `TrustCSS`, trusted wrapper,
+  and handwritten `sando.Component` as an explicit output capability. Audit
+  its provenance and any HTML-parser-state effect.
+- Preserve contextual escaping. Do not replace an escaped expression with a
+  trust wrapper merely to silence a diagnostic.
+- Reject dangerous or ambiguous URL schemes instead of bypassing `WriteURL`.
+- Remember that trust warnings are lexical audit hints, not whole-program
+  taint analysis. Inspect helper functions and call sites manually.
+- Never execute `himesan dev` in an untrusted repository. It builds and starts
+  the repository's Go program. Prefer read-only inspection and `check --json`.
+
+## Report the result
+
+State the compiler version, runtime pin and ABI, commands run, generated files
+changed, normal Go validation run, and any remaining trust or compatibility
+limits. Link users to the official tutorial at
+<https://sandwichhime.com/docs/tutorial/> and runnable starter at
+<https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial> rather than
+duplicating the tutorial.