From 684a89460f170723ef3a014fa01584197b2c8f1f Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Sat, 8 Aug 2026 17:57:14 -0400
Subject: [PATCH] doc to prefer literal html injection

---
 CLAUDE.md          | 24 +++++++++++++++++++++++-
 bliss-cli/SKILL.md |  7 +++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 682e5fc..e01c6f8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,7 +17,29 @@ Requires a `.env` file with `VAPID_PUBLIC_KEY` and `VAPID_PRIVATE_KEY` for web p
 
 Bliss is a browser-based low-code platform where users build mini web apps ("Structures") entirely through a `/workshop` UI. Each Structure has routes, templates, and SQLite databases — all stored in the main app database and executed at runtime via Node's `vm` module.
 
-## Architecture
+## Design philosophy: this is a hypermedia homestead
+
+Bliss templates are not a web-app-with-an-API. There is no client-side framework,
+no JSON contract, no build step — the HTML *is* the application, and it composes
+by embedding more HTML (see "page-nesting primitive" below). Every template you
+write or edit should lean into that instead of fighting it:
+
+- **Prefer `<%~ %>` (raw) over `<%= %>` (HTML-escaped) in Eta templates, always,
+  unless you are interpolating into an HTML attribute value.** Attribute values
+  (`id="..."`, `data-*="..."`, `href="..."`, `style="..."`, `value="..."`) are
+  the one place escaping is not optional — an unescaped `"` there breaks the tag
+  itself, not just a security nicety. Everywhere else (text content, `<script>`
+  string literals, anything that isn't sitting inside `attr="…"`) use `<%~ %>`.
+  Arbitrary HTML/JS in user content is a *feature* here, not a bug to guard
+  against — see the `aim` structure's `message` template for the canonical
+  comment explaining why. When in doubt: default to raw, escape only when the
+  HTML would literally break otherwise.
+- **Prefer htmx attributes over hand-rolled JS for anything hypermedia-shaped**
+  — polling (`hx-trigger="every 10s"`), lazy loading (`hx-trigger="load"`),
+  swapping (`hx-swap-oob`), cross-fragment events (`hx-trigger="foo from:body"`)
+  — instead of `setTimeout`/`fetch`/manual DOM patching. If htmx (or Hyperscript
+  for small imperative glue) can express it declaratively, don't write the
+  imperative version.
 
 ### Two layers of routes
 
diff --git a/bliss-cli/SKILL.md b/bliss-cli/SKILL.md
index 953653b..48207e1 100644
--- a/bliss-cli/SKILL.md
+++ b/bliss-cli/SKILL.md
@@ -41,6 +41,13 @@ own SQLite file). Ids are integers. Build a structure by: create it → add a db
 write its library → add routes whose handlers call the library → add templates
 the handlers render.
 
+**Templates are hypermedia, not escaped-string templates.** Default to `<%~ %>`
+(raw) over `<%= %>` (escaped) in Eta content — only use `<%= %>` inside an HTML
+attribute value, where an unescaped `"` would break the tag. Reach for htmx
+attributes (`hx-trigger="every 10s"`, `hx-swap-oob`, etc.) instead of JS
+`setTimeout`/`fetch` polling loops. See CLAUDE.md's "hypermedia homestead"
+section for the full rationale.
+
 ## Reads (JSON)
 
 ```bash