rsc-universal 0.1.1

package/skills/htmx/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: htmx
+description: "Use when adding interactivity to a server-rendered app (FastAPI/Jinja, Django, Rails, Laravel, Go templates, Express) without adopting a JS framework, wiring hx-get/post/put/delete plus hx-target plus hx-swap plus hx-trigger, returning HTML fragments instead of JSON, doing out-of-band swaps, or building active search, infinite scroll, inline edit, click-to-load, and polling. Triggers: 'swap a server partial into a div on click', 'return an HTML fragment not JSON', 'render a fragment on HX-Request else the full page', 'update the cart count and drawer from one response', 'live search box without React', 'afegir interactivitat a la meva app Django sense muntar un SPA', 'intercambiar un fragmento HTML del servidor', 'buscador en vivo sin SPA'. NOT a client-state SPA with routing/store (that is react / nextjs)."
+tags: [htmx, hypermedia, frontend, server-rendered, html]
+recommends: [fastapi, django, secure-coding, accessibility]
+origin: risco
+---
+
+# htmx: hypermedia-driven UIs
+
+The server owns all application state and renders HTML. The client is dumb: it swaps
+server-rendered fragments into the DOM. There is no JSON API for the UI, no client store,
+no virtual DOM, no client router. If you find yourself returning JSON and rendering it with
+JavaScript, you have stopped doing htmx and started building an SPA — use a different tool.
+
+**The unit of work is one request, described by four attributes on one element:**
+
+1. a verb — `hx-get` / `hx-post` / `hx-put` / `hx-patch` / `hx-delete` (the URL)
+2. `hx-target` — which DOM node receives the response (CSS selector or `this`)
+3. `hx-swap` — how the response is placed (default `innerHTML`)
+4. `hx-trigger` — on what event (default: natural — `click` for buttons, `submit` for forms,
+   `change` for inputs)
+
+**Versions (verify before pinning).** htmx 2.0.x is current stable (2.0.10 latest 2.x line);
+v1 (1.9.x) is legacy, kept only for IE/old-browser support. htmx v4 is in beta targeting
+Summer 2026 and changes some defaults (default swap behavior, config) — do **not** write to v4
+yet. Pin to 2.x:
+
+```html
+<script src="https://unpkg.com/htmx.org@2.0.10" crossorigin="anonymous"></script>
+```
+
+## When to use
+
+- Adding interactivity to a server-rendered app without a JS framework.
+- Wiring a verb + `hx-target` + `hx-swap` + `hx-trigger` to update a page region.
+- Returning **partials/fragments** — full page on direct navigation, fragment on htmx request
+  (branch on the `HX-Request` header).
+- Out-of-band updates (`hx-swap-oob`) when one response must refresh several regions.
+- Trigger-driven UX: active search, infinite scroll, inline edit, click-to-load, polling,
+  `revealed`, `intersect`, debounced input.
+- Server-driven control flow via response headers (`HX-Trigger`, `HX-Redirect`, …).
+
+## When NOT to use — route elsewhere
+
+- A client-state-heavy SPA (offline, optimistic UI everywhere, complex client routing) →
+  `react`, `vue-nuxt`, `svelte`, `solid-js`, `angular`, or ../nextjs/SKILL.md. htmx is the
+  anti-SPA; do not fight it.
+- How to structure the server framework itself (routers, ORM, controllers) → ../fastapi/SKILL.md,
+  `django`, `rails`, `laravel`. This skill owns the *htmx contract* (which fragment, which
+  header, which swap), not framework internals. Cross-link, do not duplicate.
+- Generic XSS/CSP/auth theory → ../secure-coding/SKILL.md. Keep only the htmx-specific notes here.
+- Focus management and ARIA live regions after a swap → `accessibility`.
+- Browser E2E of swaps → `testing-web` / `e2e-testing`.
+- Purely-client state (Alpine, vanilla sprinkles) → out of scope; htmx is for server round-trips.
+
+## Decision rules
+
+1. **Return HTML, never JSON, for the UI.** The response *is* the new DOM. JSON forces a client
+   renderer, which is the SPA you are trying to avoid.
+2. **Branch on `HX-Request`: fragment for htmx, full page otherwise.** A bookmarked URL or hard
+   refresh must still render a whole page; the htmx call gets just the partial.
+3. **The full page is the layout wrapping the *same* partial.** One template for the fragment,
+   reused inside the page layout — never two copies that drift.
+4. **Set `hx-target` and `hx-swap` explicitly when the default is wrong.** Default target is the
+   element itself; default swap is `innerHTML`. Be explicit the moment you need otherwise.
+5. **Use out-of-band swaps for multi-region updates, not multiple requests.** One action that
+   changes a list *and* a counter is one response with one OOB element.
+6. **Drive UX with `hx-trigger`, not JavaScript.** Debounce, polling, reveal, intersect are all
+   trigger modifiers — reaching for `addEventListener` usually means you missed a modifier.
+7. **Steer the client from the server with response headers.** Redirect, retarget, reswap, and
+   fire events via `HX-*` response headers instead of branching logic in the browser.
+8. **Escape everything; add CSRF yourself.** Your template engine auto-escapes — keep it on.
+   htmx does not add CSRF tokens; you propagate them via `hx-headers` or a hidden field.
+
+## Request anatomy: Bad to Good
+
+```html
+<!-- Bad: JSON endpoint + hand-written DOM patching = a tiny SPA -->
+<button id="like">Like</button>
+<script>
+  document.getElementById('like').addEventListener('click', async () => {
+    const r = await fetch('/posts/42/like', { method: 'POST' });
+    const data = await r.json();                       // JSON contract
+    document.getElementById('count').textContent = data.count;  // manual render
+  });
+</script>
+```
+
+```html
+<!-- Good: the server returns the new HTML; the element declares the swap -->
+<button hx-post="/posts/42/like"
+        hx-target="#likes"
+        hx-swap="outerHTML">Like</button>
+<span id="likes">42 likes</span>
+<!-- POST /posts/42/like responds with: <span id="likes">43 likes</span> -->
+```
+
+The Good version has no JS, no JSON, no client state. The server computed the count and rendered
+the truth; the client placed it.
+
+## Fragment rendering: branch on HX-Request
+
+Framework-agnostic rule: **if `HX-Request: true`, render the partial; otherwise render the page
+that embeds that same partial.** Concrete FastAPI + Jinja2:
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.templating import Jinja2Templates
+
+app = FastAPI()
+templates = Jinja2Templates(directory="templates")
+
+@app.get("/contacts")
+def contacts(request: Request, q: str = ""):
+    rows = search_contacts(q)
+    # htmx asked for just the table body; a browser nav gets the whole page.
+    template = "contacts/_rows.html" if request.headers.get("HX-Request") else "contacts/index.html"
+    return templates.TemplateResponse(template, {"request": request, "rows": rows, "q": q})
+```
+
+```jinja
+{# templates/contacts/index.html — the page wraps the SAME partial #}
+{% extends "base.html" %}
+{% block content %}
+  <input type="search" name="q" value="{{ q }}"
+         hx-get="/contacts" hx-target="#rows" hx-swap="innerHTML"
+         hx-trigger="keyup changed delay:500ms">
+  <table><tbody id="rows">{% include "contacts/_rows.html" %}</tbody></table>
+{% endblock %}
+```
+
+```jinja
+{# templates/contacts/_rows.html — auto-escaped; reused by page AND fragment #}
+{% for c in rows %}<tr><td>{{ c.name }}</td><td>{{ c.email }}</td></tr>{% endfor %}
+```
+
+Full per-framework wiring (Django `django-htmx` middleware, Express, CSRF per stack) is in
+[references/server-contract.md](references/server-contract.md).
+
+## Swap and target reference
+
+| `hx-swap` | Where the response goes |
+|---|---|
+| `innerHTML` | inside the target, replacing contents (default) |
+| `outerHTML` | replaces the target element itself |
+| `beforebegin` / `afterbegin` | before the target / as its first child |
+| `beforeend` / `afterend` | as its last child / after the target |
+| `delete` | deletes the target (response ignored) |
+| `none` | does not swap (use with OOB or `HX-Trigger`) |
+
+Swap modifiers: `transition:true`, `swap:<time>` (delay before swap), `settle:<time>`,
+`scroll:top|bottom`, `show:top|bottom`, `focus-scroll:false`.
+
+`hx-target` accepts a CSS selector, `this`, or an extended selector: `closest <sel>`,
+`find <sel>`, `next <sel>`, `previous <sel>`. Prefer a **stable `id`** over a fragile structural
+selector — a deep `div > div:nth-child(3)` breaks the first time markup shifts.
+
+## Out-of-band swaps
+
+When one action must refresh more than the target, mark extra elements in the response with
+`hx-swap-oob`. They are swapped into the matching live element **by `id`**, bypassing the target.
+
+```html
+<!-- Response to POST /cart/add: swap the row in normally... -->
+<tr id="row-42">2 × Widget</tr>
+<!-- ...and update the cart badge out of band (default OOB swap is outerHTML) -->
+<span id="cart-count" hx-swap-oob="true">3 items</span>
+```
+
+`hx-swap-oob="true"` defaults to `outerHTML`; you can specify a strategy
+(`hx-swap-oob="beforeend:#log"`). Use OOB instead of firing two requests for two regions.
+
+## Server-driven control flow (response headers)
+
+The server can steer htmx without any client code:
+
+| Response header | Effect |
+|---|---|
+| `HX-Trigger` | fire client event(s); JSON value `{"event": detail}` passes detail |
+| `HX-Retarget` | override `hx-target` with a CSS selector |
+| `HX-Reswap` | override `hx-swap` for this response |
+| `HX-Redirect` | full-page client redirect to the given URL |
+| `HX-Location` | client-side navigation *with* an htmx request (no full reload) |
+| `HX-Push-Url` | push a URL into history |
+| `HX-Refresh` | `true` forces a full page reload |
+
+Request headers htmx sends (read these server-side): `HX-Request`, `HX-Target`, `HX-Trigger`,
+`HX-Current-URL`, `HX-Boosted`. Full tables in
+[references/server-contract.md](references/server-contract.md).
+
+`hx-boost` is the cheapest "SPA feel": it upgrades normal `<a>`/`<form>` to AJAX that swaps
+`<body>` with `pushState` history — no SPA, no JSON.
+
+## Security (htmx-specific only)
+
+htmx makes HTML more expressive, so **injected HTML is an XSS surface**. The htmx-specific rules
+(generic theory lives in ../secure-coding/SKILL.md):
+
+- **Keep your template engine's auto-escaping on.** Never `| safe` / `|safe` user-controlled
+  content. Manually rendering raw user HTML re-introduces XSS that escaping had closed.
+- **When you must inject third-party HTML, scrub it with a whitelist** — strip `hx-*`/`data-hx-*`
+  attributes and inline scripts. An injected `hx-get` would issue requests you never intended.
+- **`hx-disable` halts htmx processing for a subtree** as defense-in-depth — but it is bypassable
+  by closing the tag, so it is *not* a primary control. Sanitize at the source.
+- **`htmx.config.selfRequestsOnly` defaults to `true` in 2.x** — keep it. It blocks htmx requests
+  to other origins.
+- **CSRF is your job.** htmx sends same-origin requests but adds no CSRF token. Propagate it:
+  `<body hx-headers='{"X-CSRF-Token": "…"}'>` or a hidden form field.
+- **Guard `HX-Redirect` / `HX-Location`** — never build them from attacker-controlled values;
+  a `javascript:` URL there is an injection.
+
+## UX recipes
+
+Worked, copy-ready recipes — server fragment + client markup for each — live in
+[references/patterns.md](references/patterns.md):
+
+- **Active search** — debounced `keyup changed delay:500ms` filtering a results table.
+- **Infinite scroll / click-to-load** — `hx-trigger="revealed"` or a "load more" button.
+- **Inline edit (click-to-edit)** — swap a row to a form and back.
+- **Delete row + OOB count** — remove a row and update a counter in one response.
+- **Modal dialog** — load a dialog fragment on demand.
+- **Progress bar** — `every 600ms` polling closed by an `HX-Trigger` event.
+- **Tabs / accordion** — swap the active panel.
+
+## Common triggers
+
+| `hx-trigger` value | Use |
+|---|---|
+| `keyup changed delay:500ms` | active search (debounced, only on real change) |
+| `every 2s` | polling a progress/status region |
+| `revealed` | infinite scroll — load when the sentinel scrolls into view |
+| `intersect once` | lazy-load a region once it enters the viewport |
+| `load delay:1s` | deferred load after the page paints |
+| `click[ctrlKey]` | event filter — only ctrl-click |
+| `submit` / `change` | natural defaults for forms / inputs |
+| `customEvent from:body` | react to an `HX-Trigger`-fired event from elsewhere |
+
+Modifiers worth knowing: `throttle:<time>`, `queue:first|last|all|none`, `from:<sel>`, `once`,
+`changed`, `delay:<time>`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it is wrong | Do instead |
+|---|---|---|
+| Endpoint returns JSON, JS renders it | that is an SPA; you lose htmx's whole point | return the HTML fragment; the server renders |
+| No `HX-Request` branch | the fragment leaks the full layout (nested `<html>`) on htmx calls, or a bookmark renders a bare partial | branch: partial vs page wrapping the same partial |
+| Two copies of the fragment (page + ajax) | they drift; bug fixed in one, not the other | one partial template, `{% include %}`d by the page |
+| Polling `every 1s` for a one-off event | wasteful traffic; hammers the server | poll only while pending, end it with `HX-Trigger`/`hx-swap-oob`; or use SSE |
+| `hx-target="div > div:nth-child(3)"` | structural selectors shatter when markup shifts | target a stable `id` |
+| `{{ user_html | safe }}` | unescaped user content → XSS | keep auto-escaping; whitelist-scrub if injecting 3rd-party HTML |
+| Rebuilding client state in `hx-on`/JS | re-creates the SPA state you came here to avoid | let the server hold state; re-render from it |
+| Multiple requests to update related regions | extra round-trips, races | one response + `hx-swap-oob` |
+
+## See also
+
+- ../fastapi/SKILL.md — FastAPI routes/templates that serve these fragments.
+- ../secure-coding/SKILL.md — the general XSS/CSP/auth theory this skill defers to.
+- ../nextjs/SKILL.md — when the requirement really is a React/SPA app, not hypermedia.
+- `django`, `rails`, `laravel` — other server frameworks (the htmx contract is identical).
+- `accessibility` — focus and ARIA after a DOM swap.

package/skills/htmx/evals/README.md

@@ -0,0 +1,3 @@
+# htmx evals
+
+Trigger and capability checks for htmx hypermedia UI work.

package/skills/htmx/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: htmx
+
+should_trigger:
+  - prompt: "Swap a server-rendered partial into a div on click with htmx."
+    why: "Verb/target/swap-driven htmx interaction is canonical."
+  - prompt: "Return an HTML fragment on HX-Request and a full page otherwise."
+    why: "Branching full page vs fragment is core htmx server contract."
+  - prompt: "Update the cart count and drawer from one htmx response."
+    why: "Out-of-band swaps for multi-region updates belong here."
+  - prompt: "Build a live search box without React using server-rendered HTML."
+    why: "Active search via hx-trigger and server fragments is htmx."
+  - prompt: "Intercambiar un fragmento HTML del servidor sin montar una SPA."
+    why: "Spanish hypermedia/no-SPA wording triggers htmx."
+
+should_not_trigger:
+  - prompt: "Build a client-side SPA with routes and global state."
+    route_to: "react"
+    why: "Client-state-heavy SPA work is not htmx."
+  - prompt: "Structure this FastAPI router and dependency injection."
+    route_to: "fastapi"
+    why: "Server framework internals are separate from htmx fragment contracts."
+  - prompt: "Audit generic XSS and CSP for this app."
+    route_to: "secure-coding"
+    why: "Generic security review belongs to secure-coding."
+  - prompt: "Write browser E2E tests for this flow."
+    route_to: "testing-web"
+    why: "Test mechanics belong to testing skills; htmx defines the interaction contract."
+
+capability:
+  - scenario: "A server-rendered app needs live search, inline edit, and cart counter updates without a SPA."
+    must_include:
+      - "Returns HTML fragments for UI requests, not JSON."
+      - "Uses hx-get/post/put/delete with explicit hx-target and hx-swap where defaults are wrong."
+      - "Branches on HX-Request so direct navigation still returns a full page."
+      - "Uses hx-trigger modifiers for debounce/reveal/polling instead of custom JavaScript."
+      - "Uses hx-swap-oob for multi-region updates from one response."
+      - "Keeps server as source of truth for application state."
+      - "Routes server framework, security and accessibility details to matching skills when needed."

package/skills/htmx/references/patterns.md

@@ -0,0 +1,113 @@
+# htmx UX recipes
+
+Copy-ready patterns. Each shows the client markup and the server fragment it expects. All
+assume htmx 2.0.x, template auto-escaping on, and that endpoints branch on `HX-Request` to
+serve the partial vs the full page (see [server-contract.md](server-contract.md)).
+
+## Active search (debounced)
+
+```html
+<input type="search" name="q" placeholder="Search contacts…"
+       hx-get="/contacts" hx-target="#results" hx-swap="innerHTML"
+       hx-trigger="keyup changed delay:500ms, search">
+<table><tbody id="results"><!-- _rows.html --></tbody></table>
+```
+
+`changed` fires only when the value actually changed; `delay:500ms` debounces. The server
+returns just the `<tr>` rows. The endpoint reuses the same `_rows.html` partial it includes in
+the full page, so there is one source of truth.
+
+## Click-to-load and infinite scroll
+
+Click-to-load: the button replaces itself (`outerHTML`) with the next rows plus a fresh button.
+
+```html
+<tbody id="rows">{# ...rows... #}</tbody>
+<button hx-get="/rows?page=2" hx-target="#rows" hx-swap="beforeend"
+        hx-on::after-request="this.remove()">Load more</button>
+```
+
+Infinite scroll: make the *last row* the trigger with `revealed` — when it scrolls into view it
+loads the next page and appends it.
+
+```html
+<tr hx-get="/rows?page=3" hx-trigger="revealed"
+    hx-target="#rows" hx-swap="beforeend">…last row…</tr>
+```
+
+Server returns the next page's rows; the new last row carries the next `revealed` trigger.
+
+## Inline edit (click-to-edit)
+
+```html
+<!-- view state -->
+<div hx-target="this" hx-swap="outerHTML">
+  <span>{{ contact.email }}</span>
+  <button hx-get="/contacts/{{ contact.id }}/edit">Edit</button>
+</div>
+```
+
+```html
+<!-- GET .../edit returns the form, which replaces the div (outerHTML inherited) -->
+<form hx-put="/contacts/{{ contact.id }}" hx-target="this" hx-swap="outerHTML">
+  <input name="email" value="{{ contact.email }}">
+  <button>Save</button>
+  <button type="button" hx-get="/contacts/{{ contact.id }}">Cancel</button>
+</form>
+```
+
+`PUT` returns the view state again; the form is replaced by the updated view.
+
+## Delete row + out-of-band count
+
+One response removes a row and updates a counter elsewhere.
+
+```html
+<tr id="row-{{ id }}">
+  <td>{{ name }}</td>
+  <td><button hx-delete="/items/{{ id }}"
+              hx-target="#row-{{ id }}" hx-swap="delete"
+              hx-confirm="Delete this item?">Delete</button></td>
+</tr>
+```
+
+```html
+<!-- DELETE response: empty body for the target (swap:delete) plus OOB badge update -->
+<span id="item-count" hx-swap-oob="true">{{ remaining }} items</span>
+```
+
+## Modal dialog (load on demand)
+
+```html
+<button hx-get="/items/{{ id }}/detail" hx-target="#modal" hx-swap="innerHTML">Details</button>
+<div id="modal"></div>
+```
+
+The endpoint returns the dialog markup; a close button swaps an empty fragment back in, or fire
+`HX-Trigger: closeModal` and listen with `hx-trigger="closeModal from:body"`.
+
+## Progress bar (polling, ended by HX-Trigger)
+
+```html
+<div id="progress" hx-get="/jobs/{{ id }}/progress"
+     hx-trigger="every 600ms" hx-swap="innerHTML">
+  <progress value="0" max="100"></progress>
+</div>
+```
+
+While the job runs, the endpoint returns an updated `<progress>`. When it finishes, the endpoint
+responds with markup that has **no** `every 600ms` trigger (polling stops because the element was
+replaced) and sets `HX-Trigger: jobDone` so other regions can react. This is the right way to end
+polling — do not poll forever.
+
+## Tabs
+
+```html
+<nav>
+  <button hx-get="/tab/overview" hx-target="#panel">Overview</button>
+  <button hx-get="/tab/activity" hx-target="#panel">Activity</button>
+</nav>
+<section id="panel" hx-swap="innerHTML"><!-- active panel --></section>
+```
+
+Each tab endpoint returns only its panel fragment.

package/skills/htmx/references/server-contract.md

@@ -0,0 +1,91 @@
+# htmx server contract
+
+The full request/response header tables and the fragment-vs-page wiring per framework. The
+contract is identical across stacks: **branch on `HX-Request`, return a partial or the page that
+embeds the same partial, steer the client with `HX-*` response headers.**
+
+## Request headers htmx sends
+
+| Header | Meaning |
+|---|---|
+| `HX-Request` | `true` on every htmx-issued request — the branch point for partial vs page |
+| `HX-Boosted` | `true` if the request came from an `hx-boost`ed element |
+| `HX-Target` | `id` of the target element (if it has one) |
+| `HX-Trigger` | `id` of the triggering element |
+| `HX-Trigger-Name` | `name` of the triggering element |
+| `HX-Current-URL` | the browser's current URL |
+| `HX-Prompt` | the user's response to an `hx-prompt` |
+
+## Response headers the server can set
+
+| Header | Effect |
+|---|---|
+| `HX-Trigger` | fire client event(s) after the swap; JSON `{"event": detail}` to pass detail |
+| `HX-Trigger-After-Settle` | fire after the settle step |
+| `HX-Trigger-After-Swap` | fire after the swap step |
+| `HX-Retarget` | CSS selector overriding `hx-target` |
+| `HX-Reswap` | a swap value overriding `hx-swap` |
+| `HX-Redirect` | full-page client redirect to a URL |
+| `HX-Location` | client-side navigation via an htmx request (no full reload) |
+| `HX-Push-Url` | push a URL into browser history (`false` to disable) |
+| `HX-Replace-Url` | replace the current history entry |
+| `HX-Refresh` | `true` triggers a full page reload |
+
+Guard `HX-Redirect`/`HX-Location` against attacker-controlled URLs — a `javascript:` value is an
+injection.
+
+## FastAPI + Jinja2
+
+```python
+@app.get("/contacts")
+def contacts(request: Request, q: str = ""):
+    rows = search_contacts(q)
+    name = "contacts/_rows.html" if request.headers.get("HX-Request") else "contacts/index.html"
+    return templates.TemplateResponse(name, {"request": request, "rows": rows, "q": q})
+```
+
+Fire a client event from the server:
+
+```python
+from fastapi.responses import HTMLResponse
+resp = HTMLResponse("<span id='cart-count'>3 items</span>")
+resp.headers["HX-Trigger"] = '{"cartUpdated": {"count": 3}}'
+return resp
+```
+
+## Django (django-htmx)
+
+Add the `django_htmx.middleware.HtmxMiddleware`, then `request.htmx` is truthy on htmx requests:
+
+```python
+def contacts(request):
+    rows = search_contacts(request.GET.get("q", ""))
+    template = "contacts/_rows.html" if request.htmx else "contacts/index.html"
+    return render(request, template, {"rows": rows})
+```
+
+CSRF: Django requires the token on unsafe methods. Send it from htmx with a global header so you
+do not add it to every element:
+
+```html
+<body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}'>
+```
+
+## Express
+
+```js
+app.get("/contacts", (req, res) => {
+  const rows = searchContacts(req.query.q || "");
+  const view = req.get("HX-Request") ? "contacts/_rows" : "contacts/index";
+  res.render(view, { rows });
+});
+```
+
+CSRF (e.g. `csurf` or a double-submit cookie): expose the token to htmx via `hx-headers`, the
+same pattern as Django — htmx never adds CSRF tokens itself.
+
+## Fragment-vs-page rule (all stacks)
+
+The full page **is** the layout that `include`s the fragment. Keep exactly one fragment template;
+the page embeds it, the htmx branch returns it directly. Two divergent copies is the most common
+htmx bug — fix it once and it stays fixed.

package/skills/htmx/scripts/verify.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# verify.sh — heuristic, advisory static lint for htmx templates.
+# Read-only. Scans *.html and common template files for the highest-signal mistakes
+# this skill prohibits. Echoes PASS / WARN / FAIL lines. Exits non-zero only on FAIL.
+# Empty or clean targets exit 0 (no false failure).
+#
+# Usage: scripts/verify.sh [DIR]   (default: current directory)
+# This is grep/awk-based, not a real HTML parser. Treat output as advisory.
+
+set -u
+
+TARGET="${1:-.}"
+FAIL=0
+WARN=0
+CHECKED=0
+
+# Valid hx-swap base strategies (modifiers after a space/colon are stripped before checking).
+VALID_SWAP="innerHTML outerHTML textContent beforebegin afterbegin beforeend afterend delete none"
+
+is_valid_swap() {
+  local v="$1"
+  for s in $VALID_SWAP; do [ "$v" = "$s" ] && return 0; done
+  return 1
+}
+
+# Collect candidate template files. Null-delimited to survive spaces.
+FILES=()
+while IFS= read -r -d '' f; do FILES+=("$f"); done < <(
+  find "$TARGET" -type f \( \
+      -name '*.html' -o -name '*.htm' -o -name '*.jinja' -o -name '*.jinja2' \
+      -o -name '*.j2' -o -name '*.twig' -o -name '*.erb' -o -name '*.blade.php' \
+      -o -name '*.ejs' -o -name '*.hbs' \
+    \) -not -path '*/node_modules/*' -not -path '*/.git/*' -print0 2>/dev/null
+)
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  echo "PASS: no HTML/template files found under '$TARGET' — nothing to check."
+  exit 0
+fi
+
+for f in "${FILES[@]}"; do
+  # Only inspect files that actually use htmx attributes.
+  grep -Eq 'hx-(get|post|put|patch|delete|target|swap|trigger|swap-oob|boost)' "$f" 2>/dev/null || continue
+  CHECKED=$((CHECKED + 1))
+
+  # 1. Invalid hx-swap base value (strip modifiers after whitespace).
+  while IFS= read -r raw; do
+    base="${raw%%[[:space:]]*}"
+    if [ -n "$base" ] && ! is_valid_swap "$base"; then
+      echo "FAIL: $f — invalid hx-swap value '$base' (allowed: $VALID_SWAP)"
+      FAIL=$((FAIL + 1))
+    fi
+  done < <(grep -Eo 'hx-swap[[:space:]]*=[[:space:]]*"[^"]*"' "$f" 2>/dev/null \
+            | sed -E 's/.*=[[:space:]]*"([^"]*)"/\1/')
+
+  # 2. hx-trigger modifier typos: catch 'dela:', 'delay' w/o colon, 'throtle', 'evry'.
+  if grep -Eq 'hx-trigger[[:space:]]*=[[:space:]]*"[^"]*(dela:|delay[^:"]|throtle|throttle[^:"]|evry|revaled)' "$f" 2>/dev/null; then
+    echo "WARN: $f — possible hx-trigger modifier typo (check delay:/throttle:/every/revealed spelling)"
+    WARN=$((WARN + 1))
+  fi
+
+  # 3. hx-target='#id' referencing an id not defined in the same file (best-effort, same-file).
+  while IFS= read -r tid; do
+    [ -z "$tid" ] && continue
+    if ! grep -Eq "id[[:space:]]*=[[:space:]]*[\"']${tid}[\"']" "$f" 2>/dev/null; then
+      echo "WARN: $f — hx-target='#${tid}' but no id='${tid}' in the same file (may live elsewhere/OOB)"
+      WARN=$((WARN + 1))
+    fi
+  done < <(grep -Eo 'hx-target[[:space:]]*=[[:space:]]*"#[A-Za-z0-9_-]+"' "$f" 2>/dev/null \
+            | sed -E 's/.*"#([A-Za-z0-9_-]+)"/\1/')
+
+  # 4. Uses hx-* attributes but no htmx script include detected (heuristic warn).
+  if ! grep -Eq 'htmx(\.org|\.min)?\.js|htmx@|unpkg\.com/htmx|cdn[^"]*htmx' "$f" 2>/dev/null; then
+    echo "WARN: $f — hx-* attributes present but no htmx <script> include detected (may be in a layout)"
+    WARN=$((WARN + 1))
+  fi
+
+  # 5. Raw/unescaped output near content (XSS warn): | safe, |safe, |raw, {!! !!} (Blade), == (ERB raw via raw()).
+  if grep -Eq '\|[[:space:]]*safe|\|[[:space:]]*raw|\{!![^}]*!!\}|<%==' "$f" 2>/dev/null; then
+    echo "WARN: $f — raw/unescaped template output (| safe / |raw / {!! !!} / <%==) — ensure it is not user content (XSS)"
+    WARN=$((WARN + 1))
+  fi
+done
+
+echo "----"
+echo "Checked $CHECKED htmx file(s) of ${#FILES[@]} template file(s). FAIL=$FAIL WARN=$WARN"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo "FAIL: $FAIL hard violation(s) found."
+  exit 1
+fi
+echo "PASS: no hard violations."
+exit 0