diff --git a/docs/js-asset-proxy-prd.md b/docs/js-asset-proxy-prd.md
new file mode 100644
index 00000000..c5a01d54
--- /dev/null
+++ b/docs/js-asset-proxy-prd.md
@@ -0,0 +1,356 @@
+# Product Requirements: First-Party JS Asset Proxy
+
+**Status:** Draft
+**Author:** Trusted Server Product
+**Last updated:** 2026-03-26
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Problem Statement](#2-problem-statement)
+3. [Goals and Non-Goals](#3-goals-and-non-goals)
+4. [Target Customers](#4-target-customers)
+5. [Opaque URL Routing](#5-opaque-url-routing)
+6. [KV Asset Cache](#6-kv-asset-cache)
+7. [HTML Script Tag Injection](#7-html-script-tag-injection)
+8. [Cache Lifecycle](#8-cache-lifecycle)
+9. [Configuration](#9-configuration)
+10. [Routes](#10-routes)
+11. [Security](#11-security)
+12. [Open Questions](#12-open-questions)
+13. [Success Metrics](#13-success-metrics)
+
+---
+
+## 1. Overview
+
+The JS Asset Proxy allows Trusted Server to fetch third-party JavaScript files from configured origin URLs, cache them in Fastly or similar KV Store under opaque first-party paths, and serve them from the publisher's own domain. When running in full HTML proxy mode, TS also injects the corresponding `<script>` tag into the page `<head>` automatically.
+
+The primary use case is publisher-controlled delivery of ad tech scripts (header bidding wrappers, Prebid loaders, measurement SDKs) that today load from vendor-controlled infrastructure outside the publisher's trust boundary. By serving these assets from `assets2.publisher.com`, TS brings third-party script delivery inside the publisher's operational control without requiring any ongoing changes from the publisher.
+
+TS Lite acts as a publisher-controlled JS execution gateway. Before any third-party script reaches a user's browser, it passes through the publisher's own edge service — where TS can enforce consent, inspect cache state, apply rate limits, or disable delivery entirely. This is the same trust model publishers use for their own first-party assets, extended to vendor dependencies.
+
+---
+
+## 2. Problem Statement
+
+Publishers using third-party ad tech wrappers have every component of the ad stack served from vendor-controlled domains outside the publisher's infrastructure:
+
+| Asset | Third-party origin | Publisher control |
+|---|---|---|
+| Prebid bootstrapper | `web.prebidwrapper.com` | None — vendor infrastructure |
+| Vendor loader | `raven-edge.vendor.io` | None — vendor infrastructure |
+| Vendor bundle | `raven-static.vendor.io` | None — vendor infrastructure |
+| PBS auction XHR | `vendor-pbs.com` | None — vendor infrastructure |
+| PBS cookie sync | `vendor-pbs.com/cookie_sync` | None — vendor infrastructure |
+| Google Tag Manager | `googletagmanager.com` | None — vendor infrastructure |
+
+Publishers have no ability to inspect, version-lock, throttle, or disable any of these assets without contacting the vendor. A misbehaving or slow script on `raven-static.vendor.io` is outside the publisher's operational control entirely. DNS resolution and TLS handshakes to 4+ distinct origins also add measurable latency on every uncached pageview.
+
+### 2.1 The fix is publisher-owned infrastructure
+
+Serving JS from the publisher's own domain (`assets2.publisher.com`) puts the asset delivery path inside the publisher's operational boundary. The publisher can audit what runs, when it was last fetched, and disable any asset centrally without a vendor call. The publisher sets a single CNAME to Fastly or similar and hardcodes one `<script>` tag in their HTML template. TS handles all fetching, caching, and refreshing transparently.
+
+### 2.2 Stable opaque paths provide namespace isolation
+
+Even on a first-party domain, a predictable path like `/prebid-load.js` is fragile — it couples the publisher's asset namespace to vendor naming conventions and breaks if the vendor renames their file. Serving under an opaque path (`/sdk/gWnLmpLy.js`, derived from a publisher-specific token) keeps the publisher's asset namespace decoupled from vendor naming conventions and protects against vendor URL changes breaking the publisher's page. The path never changes after initial setup regardless of what the vendor does upstream.
+
+---
+
+## 3. Goals and Non-Goals
+
+### Goals
+
+- Fetch third-party JS from configured origin URLs and cache in `js_asset_store` KV
+- Serve cached JS under opaque, first-party paths at `assets2.publisher.com`
+- Give publishers operational control over which third-party scripts execute on their pages — inspectable, version-lockable, and disableable without vendor involvement
+- Initial TTL of **1 hour**, matching the most common origin `Cache-Control: max-age=3600`
+- Use ETag-based conditional refresh: only re-fetch body on `200`; on `304` extend TTL only
+- Store content brotli-compressed in KV; serve with matching `Content-Encoding` header
+- In full HTML proxy mode: inject the `<script>` tag into `<head>` automatically using the existing `html_processor.rs` head injection pipeline
+- In TS Lite mode: publisher hardcodes the opaque `<script>` tag once; TS serves it
+- Support versioned wildcard paths for assets with dynamic version segments (e.g., `/raven-static/*/raven.js`)
+
+### Non-Goals
+
+- URL rewriting within served JS content (origin providers are expected to make CDN URLs configurable rather than hardcoded)
+- Serving non-JS assets (images, CSS, fonts) through this pipeline — ad tech JS only
+- Real-time cache invalidation webhooks (TTL-based expiry is sufficient for v1)
+- Per-request personalization of JS content (JS is the same for all users of a given publisher)
+- Rotating opaque filenames over time — paths are stable per publisher
+
+---
+
+## 4. Target Customers
+
+| Customer | Deployment mode | How they use this feature |
+|---|---|---|
+| Publisher (TS Lite) | `assets2.publisher.com` → Fastly or similar | Hardcodes one opaque `<script>` tag; all vendor JS delivered through publisher-controlled infrastructure |
+| Publisher (full TS) | Full HTML proxy | TS injects `<script>` tag automatically; no HTML change needed |
+| Ad tech partner | Ships TS Lite config to their pub customers | Configures asset mappings; publishers flip a DNS record |
+
+---
+
+## 5. Opaque URL Routing
+
+### 5.1 Path generation
+
+The opaque path token is derived deterministically from the publisher token using the first 8 characters of a base62 encoding of the publisher ID. The token is stable — it does not rotate and the publisher sets it once.
+
+**Example mapping for publisher `golf-WnLmpLyEjL`:**
+
+| Opaque path | Asset type | Origin URL |
+|---|---|---|
+| `/sdk/gWnLmpLy.js` | Prebid bootstrapper | `https://web.prebidwrapper.com/golf-WnLmpLyEjL/default-v2/prebid-load.js` |
+| `/raven/golfmain.js` | Vendor loader | `https://raven-edge.vendor.io/raven/golf-main-L1Zrx/library.js` |
+| `/raven-static/*/raven.js` | Vendor bundle (versioned) | `https://raven-static.vendor.io/prod/*/raven.js` |
+
+### 5.2 Route matching
+
+TS matches inbound paths against the asset registry in `trusted-server.toml`. Wildcard segments (`*`) in the path are forwarded verbatim to the origin URL. Paths not matching any registered asset return `404`.
+
+### 5.3 Why opaque and not content-hash
+
+Content-hash URLs (e.g., `tsjs-core.abc123.js`) are appropriate for assets TS generates itself, where the hash is computed at build time. Third-party JS has content that changes independently — using a publisher-token-derived slug decouples the URL from the content version. The ETag mechanism handles freshness.
+
+---
+
+## 6. KV Asset Cache
+
+### 6.1 KV store
+
+**Store name:** `js_asset_store` (configured in `trusted-server.toml` alongside `ec_store` and `partner_store`)
+
+### 6.2 Key format
+
+```
+js-asset:{asset_slug}:{path_suffix}
+```
+
+| Key | Origin |
+|---|---|
+| `js-asset:golf-WnLmpLyEjL:prebid-load` | `https://web.prebidwrapper.com/golf-WnLmpLyEjL/default-v2/prebid-load.js` |
+| `js-asset:golf-main-L1Zrx:vendor-library` | `https://raven-edge.vendor.io/raven/golf-main-L1Zrx/library.js` |
+| `js-asset:vendor-static:prod/1.19.8-hcskhn` | `https://raven-static.vendor.io/prod/1.19.8-hcskhn/raven.js` |
+
+For versioned wildcard paths, the wildcard segment is included in the key suffix so each version is cached independently.
+
+### 6.3 KV entry structure
+
+Fastly or similar KV has two layers: metadata (≤2048 bytes, fast non-streaming read) and body (≤8MB, streamed). This feature uses both.
+
+**Metadata** (read first on every request, no streaming cost):
+
+```json
+{
+  "v": 1,
+  "origin_url": "https://web.prebidwrapper.com/golf-WnLmpLyEjL/default-v2/prebid-load.js",
+  "content_type": "application/javascript",
+  "etag": "W/\"72a5efa508944ba68ea00764ce5ebe3d\"",
+  "fetched_at": 1742910400,
+  "expires_at": 1742914000,
+  "asset_slug": "golf-WnLmpLyEjL:prebid-load"
+}
+```
+
+**Body:** Brotli-compressed JS content, matching the origin's `Content-Encoding`. Stored compressed to minimize KV read/write cost and to serve directly without re-compression.
+
+**KV TTL:** `3600` seconds on initial write. Extended (without body re-write) on `304 Not Modified` from origin.
+
+### 6.4 Cache read flow
+
+```
+Inbound request: GET assets2.golf.com/sdk/gWnLmpLy.js
+        │
+        ▼
+Read KV metadata only  (~1ms, no stream, no WASM heap cost)
+        │
+        ├── expires_at > now  (cache hit)
+        │       └── stream KV body → response
+        │           Content-Type: application/javascript
+        │           Content-Encoding: br
+        │           Cache-Control: max-age=3600
+        │           ETag: {stored etag}
+        │
+        └── expires_at ≤ now  (cache miss or expired)
+                │
+                ▼
+        Conditional GET to origin
+        If-None-Match: {stored etag}
+                │
+                ├── 304 Not Modified
+                │       → write updated metadata (new expires_at only, no body write)
+                │       → stream existing KV body → response
+                │
+                └── 200 OK
+                        → write new metadata
+                        → write new body (brotli-compressed)
+                        → stream body → response
+```
+
+Reading metadata before deciding whether to stream the body is the key optimization: on a cache hit, JS content is never loaded into WASM memory. It streams directly from KV to the response buffer.
+
+### 6.5 KV degraded behavior
+
+| Condition | Behavior |
+|---|---|
+| KV read fails | Fall back to direct origin fetch. Log at `warn`. Serve origin response. Do not cache (avoid writing to a degraded store). |
+| KV write fails after successful origin fetch | Serve the fetched content. Log at `warn`. Next request will retry the write. |
+| Origin fetch fails | Return `502` with `X-ts-error: asset-origin-unreachable`. Do not clear cached entry — stale content is preferable to a broken page. |
+| Origin returns non-200/304 | Return `502`. Log response status at `warn`. |
+
+Stale-on-error: if the KV entry is expired but the origin returns a non-200/304, the stale cached body is served with an additional response header `X-ts-cache: stale` rather than breaking the page.
+
+---
+
+## 7. HTML Script Tag Injection
+
+### 7.1 Full TS proxy mode
+
+When TS is operating as a full HTML proxy (HTML proxy enabled in `trusted-server.toml`), it injects the asset's `<script>` tag automatically using the existing `html_processor.rs` head injection pipeline.
+
+The injection point is the start of `<head>`, before the TS core bundle, consistent with how integration head injectors work today (`head_inserts()` in `integration_registry.rs`). This ensures the vendor JS is available as early as possible in page parse order.
+
+**Injected tag (example):**
+```html
+<head>
+  <script src="https://assets2.golf.com/sdk/gWnLmpLy.js"></script>
+  <!-- existing TS bundle injection follows -->
+  <script src="/static/tsjs=tsjs-unified.min.js"></script>
+```
+
+### 7.2 TS Lite mode (HTML proxy disabled)
+
+TS does not modify HTML responses. The publisher hardcodes the opaque `<script>` tag in their HTML template once at onboarding. TS only responds to requests for the opaque asset URLs.
+
+```html
+<!-- Publisher adds once to HTML <head> template, never changes -->
+<script src="https://assets2.golf.com/sdk/gWnLmpLy.js"></script>
+```
+
+### 7.3 Tag attributes
+
+The injected or hardcoded tag has no `async` or `defer` attributes by default. Ad tech bootstrapper scripts (Prebid loaders, vendor loaders) are render-blocking by design — they must execute before GPT slot definitions and auction calls. The ad tech partner controls whether their subsequently loaded scripts are async/defer.
+
+---
+
+## 8. Cache Lifecycle
+
+### 8.1 Initial TTL
+
+**1 hour (3600 seconds)** for v1. This matches the most common `Cache-Control: max-age=3600` from ad tech CDN origins. The TTL is configurable per asset entry in `trusted-server.toml` to accommodate partners with different cache policies.
+
+### 8.2 ETag-based conditional refresh
+
+On TTL expiry, TS issues a conditional `GET` with `If-None-Match: {stored_etag}` to the origin. A `304 Not Modified` response costs only a TCP roundtrip — no body is transferred. The KV body is reused as-is, and only the metadata `expires_at` is updated. This is the expected common case: vendor files are typically updated daily, not hourly.
+
+### 8.3 Cache warming
+
+On first request after deployment (cold KV), the origin fetch adds latency to that one request. This is acceptable for v1. A pre-warm step (fetching and populating KV at service deploy time) is a follow-on improvement.
+
+### 8.4 Manual invalidation
+
+TS operators can force a cache bust by deleting the KV entry via the KV management API. The next request will treat it as a cold miss and fetch from origin. No binary redeploy required.
+
+---
+
+## 9. Configuration
+
+New section in `trusted-server.toml`:
+
+```toml
+[kv_stores]
+js_asset_store = "golf-js-asset-store"   # new, alongside ec_store and partner_store
+
+# One [[js_assets]] entry per proxied asset
+[[js_assets]]
+slug = "golf-WnLmpLyEjL:prebid-load"
+path = "/sdk/gWnLmpLy.js"
+origin_url = "https://web.prebidwrapper.com/golf-WnLmpLyEjL/default-v2/prebid-load.js"
+ttl_sec = 3600
+inject_in_head = true          # inject <script> tag in full HTML proxy mode
+
+[[js_assets]]
+slug = "golf-main-L1Zrx:vendor-library"
+path = "/raven/golfmain.js"
+origin_url = "https://raven-edge.vendor.io/raven/golf-main-L1Zrx/library.js"
+ttl_sec = 3600
+inject_in_head = false         # loaded by prebid-load.js, not injected directly
+
+[[js_assets]]
+slug = "vendor-static"
+path = "/raven-static/*"       # wildcard — version segment forwarded to origin
+origin_url = "https://raven-static.vendor.io/prod/*"
+ttl_sec = 3600
+inject_in_head = false
+```
+
+### 9.1 Backend configuration
+
+Each distinct origin hostname requires a declared backend in `trusted-server.toml` (Fastly or similar Compute requires backends to be declared at deploy time):
+
+```toml
+[backends.vendor_prebid]
+url = "https://web.prebidwrapper.com"
+
+[backends.vendor_raven_edge]
+url = "https://raven-edge.vendor.io"
+
+[backends.vendor_raven_static]
+url = "https://raven-static.vendor.io"
+```
+
+---
+
+## 10. Routes
+
+| Method | Path | Handler | Notes |
+|---|---|---|---|
+| `GET` | `/{asset_path}` matching a configured `[[js_assets]]` entry | `handle_js_asset` | KV cache read → conditional origin fetch |
+| Any | `/{asset_path}` not matching any entry | `404` with `X-ts-error: asset-not-found` | |
+
+The asset path matching runs before publisher origin proxying in the request dispatch order. If a path matches a configured `[[js_assets]]` entry, it is handled entirely by `handle_js_asset` and never forwarded to the publisher's origin.
+
+---
+
+## 11. Security
+
+### 11.1 Origin allowlist
+
+Only URLs declared in `[[js_assets]]` are ever fetched. TS does not accept arbitrary origin URLs at request time. The wildcard `*` in path patterns is forwarded verbatim to the declared origin only — it cannot be used to construct requests to other hosts.
+
+### 11.2 Content validation
+
+TS does not execute or parse the JS content. It fetches, stores, and serves it as an opaque byte stream. No XSS sanitization is applied — the expectation is that the configured origins are trusted ad tech partners explicitly allowlisted by the publisher.
+
+### 11.3 Path traversal
+
+Wildcard path segments are validated to contain only URL-safe characters (`[A-Za-z0-9._-/]`) before being appended to the origin URL. Segments containing `..`, `%2e`, or other traversal patterns return `400`.
+
+### 11.4 Response size limit
+
+Origin responses larger than 8MB are rejected with `502` and not written to KV. This matches Fastly or similar KV per-entry body limits. Ad tech JS files are typically 100–500KB compressed; 8MB provides substantial headroom.
+
+---
+
+## 12. Open Questions
+
+1. **Pre-warming:** Should TS populate KV entries at service deploy time rather than on first user request? Eliminates cold-miss latency for the first user after a deployment.
+2. **Stale TTL extension:** Should the stale-on-error window be configurable per asset, or is a fixed 24-hour stale window sufficient for v1?
+3. **Multiple publishers sharing a service:** The current design assumes one publisher per TS service instance. If multiple publishers share a service, the `[[js_assets]]` table needs a `publisher_id` field for disambiguation.
+4. **Versioned wildcard paths and KV growth:** Each unique vendor bundle version is a separate KV entry. If the vendor deploys frequently, old entries accumulate. Should entries with wildcard paths have a shorter TTL or an explicit eviction policy?
+5. **Vendor CDN URL configurability:** This PRD assumes the vendor makes their CDN URL configurable per publisher rather than hardcoded in their loader script. If that change is not made, TS will need to rewrite the string in the served loader body before caching. Confirm with the vendor before finalizing the implementation.
+
+---
+
+## 13. Success Metrics
+
+| Metric | Target | Measurement |
+|---|---|---|
+| KV cache hit rate | >95% of asset requests served from KV (not origin) | KV read vs. origin fetch log counters |
+| Third-party delivery consistency | Measurable increase in asset load success rate; reduction in failed or partially loaded ad stack across user segments | Publisher-reported asset load rates before/after |
+| Origin fetch latency (cache miss) | p99 < 300ms (origin RTT + KV write) | Edge log `bereq_elapsed` |
+| KV read latency (cache hit) | p99 < 5ms | Edge log timing |
+| Stale responses | < 0.1% of total | `X-ts-cache: stale` header count in logs |
diff --git a/docs/superpowers/specs/2026-04-01-js-asset-auditor-design.md b/docs/superpowers/specs/2026-04-01-js-asset-auditor-design.md
new file mode 100644
index 00000000..d6168592
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-01-js-asset-auditor-design.md
@@ -0,0 +1,216 @@
+# JS Asset Auditor — Engineering Spec
+
+**Date:** 2026-04-01  
+**Status:** Approved for engineering breakdown  
+**Related:** [JS Asset Proxy spec](2026-04-01-js-asset-proxy-design.md)
+
+---
+
+## Context
+
+The JS Asset Proxy requires a `js-assets.toml` file declaring which third-party JS assets to proxy. Without tooling, populating this file requires manually inspecting network requests in browser DevTools, extracting URLs, generating opaque slugs, and writing TOML — a tedious error-prone process that is a barrier to publisher onboarding.
+
+The Auditor eliminates this friction. It sweeps a publisher's page using the Chrome DevTools MCP, detects third-party JS assets, auto-generates `js-assets.toml` entries, and auto-detects `inject_in_head` from the page DOM. The operator's only remaining decision is reviewing the output before committing.
+
+It also runs as a monitoring tool — `--diff` mode compares a new sweep against the existing config and surfaces new or removed assets, giving publishers ongoing visibility into their third-party JS footprint.
+
+**Implementation:** Pure Claude Code skill — no Rust, no compiled code, no additional dependencies. Uses the Chrome DevTools MCP already configured in `.claude/settings.json`.
+
+---
+
+## Command Interface
+
+```bash
+/audit-js-assets https://www.publisher.com          # init — generate js-assets.toml
+/audit-js-assets https://www.publisher.com --diff   # diff — compare against existing file
+```
+
+---
+
+## Sweep Protocol
+
+1. Read `trusted-server.toml` → extract `publisher.domain` (defines first-party boundary)
+2. Open Chrome via `mcp__chrome-devtools__new_page`, navigate to target URL via `mcp__chrome-devtools__navigate_page`
+3. Wait for full page load + ~6s settle window for async script loads (`mcp__chrome-devtools__wait_for`)
+4. In parallel:
+   - `mcp__chrome-devtools__list_network_requests` → filter for requests where URL ends in `.js` or `Content-Type: application/javascript`, and origin ≠ `publisher.domain`
+   - `mcp__chrome-devtools__evaluate_script` → `Array.from(document.head.querySelectorAll('script[src]')).map(s => s.src)` → collect head-loaded script URLs
+5. Apply heuristic filter (see below)
+6. For each surviving asset, generate a `[[js_assets]]` entry (see below)
+7. Write output (init or diff mode)
+8. Print terminal summary
+9. Close page via `mcp__chrome-devtools__close_page`
+
+---
+
+## Heuristic Filter
+
+The following origin categories are excluded silently. The terminal summary reports what was filtered and why so operators can manually add entries if needed.
+
+| Category | Excluded origins |
+|---|---|
+| Framework CDNs | `cdnjs.cloudflare.com`, `ajax.googleapis.com`, `cdn.jsdelivr.net`, `unpkg.com` |
+| Error tracking | `sentry.io`, `bugsnag.com`, `rollbar.com` |
+| Font services | `fonts.googleapis.com`, `fonts.gstatic.com` |
+| Social embeds | `platform.twitter.com`, `connect.facebook.net` |
+
+**`googletagmanager.com` is not filtered** — GTM is ad tech and should be proxied.
+
+Everything else surfaces for operator review.
+
+---
+
+## Asset Entry Generation
+
+| Field | Derivation |
+|---|---|
+| `slug` | `{publisher_prefix}:{asset_stem}` — see slug algorithm below |
+| `path` | `/{publisher_prefix}/{asset_stem}.js`, or wildcard variant if versioned path detected |
+| `origin_url` | Full captured URL, with wildcard substitution applied if versioned |
+| `ttl_sec` | Omitted — proxy defaults to 1800 (wildcard) or 3600 (fixed) |
+| `inject_in_head` | `true` if URL appeared in head script list from DOM evaluation, else `false` |
+
+### Slug algorithm
+
+```
+publisher_prefix = first_8_chars(base62(sha256(publisher.domain + origin_url)))
+asset_stem       = filename_without_extension(origin_url)
+slug             = "{publisher_prefix}:{asset_stem}"
+```
+
+**Rationale:** Fully opaque and hash-derived — no human naming required, no ambiguity for cryptic vendor filenames. The KV metadata (`origin_url`, `content_type`, `asset_slug`) serves as the lookup table. Operators can query `js-asset:{slug}` in the KV store to retrieve full provenance. The terminal summary also prints slug → origin_url at generation time.
+
+**Important:** This algorithm must produce identical output to the Proxy's KV key derivation. Engineering should implement this as a shared utility (e.g., a small JS/TS helper in the skill, or a standalone `scripts/` utility) rather than duplicating the logic.
+
+### Wildcard detection
+
+Path segments matching either pattern are replaced with `*`:
+- Semver: `\d+\.\d+[\.\d-]*` (e.g., `1.19.8-hcskhn`)
+- Hash-like: `[a-f0-9]{6,}` or `[A-Za-z0-9]{8,}` between path separators
+
+The original URL is preserved as a comment above the generated entry so operators can verify the wildcard substitution is correct.
+
+---
+
+## Init Mode Output
+
+### `js-assets.toml` (written to repo root)
+
+```toml
+# Generated by /audit-js-assets on 2026-04-01
+# Publisher: publisher.com
+# Source URL: https://www.publisher.com
+
+[[js_assets]]
+# https://web.prebidwrapper.com/golf-WnLmpLyEjL/default-v2/prebid-load.js
+slug = "aB3kR7mN:prebid-load"
+path = "/sdk/aB3kR7mN.js"
+origin_url = "https://web.prebidwrapper.com/golf-WnLmpLyEjL/default-v2/prebid-load.js"
+inject_in_head = true
+
+[[js_assets]]
+# https://raven-static.vendor.io/prod/1.19.8-hcskhn/raven.js (wildcard detected)
+slug = "xQ9pL2wY:raven"
+path = "/raven-static/*"
+origin_url = "https://raven-static.vendor.io/prod/*/raven.js"
+inject_in_head = false
+```
+
+### Terminal summary
+
+```
+JS Asset Audit — publisher.com
+────────────────────────────────
+Detected:  8 third-party JS requests
+Filtered:  3 (cdnjs.cloudflare.com ×2, sentry.io ×1)
+Surfaced:  5 assets → js-assets.toml
+
+  aB3kR7mN  inject_in_head=true   web.prebidwrapper.com/.../prebid-load.js
+  xQ9pL2wY  inject_in_head=false  raven-static.vendor.io/prod/*/raven.js  [wildcard]
+  zM4nK8vP  inject_in_head=true   googletagmanager.com/gtm.js
+  ...
+
+Review inject_in_head values and commit js-assets.toml when ready.
+Diff mode: /audit-js-assets <url> --diff
+```
+
+---
+
+## Diff Mode Output
+
+Compares sweep results against the existing `js-assets.toml`.
+
+| Condition | Behavior |
+|---|---|
+| Asset in sweep, not in file | **New** — appended to `js-assets.toml` as a commented-out block |
+| Asset in file, not in sweep | **Missing** — flagged in terminal summary with `⚠`. Never auto-removed. |
+| Asset in both | **Confirmed** — listed as present |
+
+New entries are appended as TOML comments so the file stays valid and nothing is activated without the operator explicitly uncommenting.
+
+### `js-assets.toml` (new entry appended as comment)
+
+```toml
+# --- NEW (detected by /audit-js-assets --diff on 2026-04-01, uncomment to activate) ---
+# [[js_assets]]
+# # https://googletagmanager.com/gtm.js
+# slug = "zM4nK8vP:gtm"
+# path = "/sdk/zM4nK8vP.js"
+# origin_url = "https://googletagmanager.com/gtm.js"
+# inject_in_head = true
+```
+
+### Terminal summary (diff mode)
+
+```
+JS Asset Audit (diff) — publisher.com
+────────────────────────────────
+Confirmed:  4 assets still present on page
+New:        1 asset detected (appended as comment to js-assets.toml)
+Missing:    1 asset no longer seen on page ⚠
+
+  NEW      zM4nK8vP  googletagmanager.com/gtm.js  → review in js-assets.toml
+  MISSING  xQ9pL2wY  raven-static.vendor.io/...   → may have been removed or renamed
+```
+
+---
+
+## Implementation
+
+The Auditor is a Claude Code skill file. No compiled code.
+
+**Skill location:** `.claude/skills/audit-js-assets.md`
+
+**MCP tools used:**
+- `mcp__chrome-devtools__new_page` — open browser tab
+- `mcp__chrome-devtools__navigate_page` — load publisher URL
+- `mcp__chrome-devtools__wait_for` — settle after page load
+- `mcp__chrome-devtools__list_network_requests` — capture JS requests
+- `mcp__chrome-devtools__evaluate_script` — detect head-loaded scripts via DOM query
+- `mcp__chrome-devtools__close_page` — clean up tab
+
+**File tools used:**
+- `Read` — read `trusted-server.toml` (publisher domain) and existing `js-assets.toml` (diff mode)
+- `Write` — write generated/updated `js-assets.toml`
+
+---
+
+## Delivery Order
+
+The Auditor should be delivered **after Proxy Phase 1** (so `js-assets.toml` schema is defined) and **before Proxy Phase 2** (so engineering has real populated entries to test the cache pipeline against actual vendor origins).
+
+See [delivery order in the Proxy spec](2026-04-01-js-asset-proxy-design.md).
+
+---
+
+## Verification
+
+- Run `/audit-js-assets https://www.publisher.com` against a known test publisher page with identified third-party JS
+- Verify generated entries match actual third-party JS observed on the page (cross-check in browser DevTools)
+- Verify `inject_in_head = true` only for scripts that appear in `<head>` (not `<body>`)
+- Verify wildcard detection fires for versioned path segments and not for stable paths
+- Verify GTM (`googletagmanager.com`) is captured and not filtered
+- Verify framework CDNs (`cdnjs.cloudflare.com` etc.) are filtered with reason in summary
+- Run `--diff` against an unchanged page → all entries confirmed, no new/missing
+- Run `--diff` after adding a new vendor script to the page → appears as `NEW` in summary
+- Run `--diff` after removing a script → appears as `MISSING ⚠` in summary, file unchanged
diff --git a/docs/superpowers/specs/2026-04-01-js-asset-proxy-design.md b/docs/superpowers/specs/2026-04-01-js-asset-proxy-design.md
new file mode 100644
index 00000000..afef2896
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-01-js-asset-proxy-design.md
@@ -0,0 +1,302 @@
+# JS Asset Proxy — Engineering Spec
+
+**Date:** 2026-04-01  
+**Status:** Approved for engineering breakdown  
+**Related:** [JS Asset Auditor spec](2026-04-01-js-asset-auditor-design.md), [PRD](../../js-asset-proxy-prd.md)
+
+---
+
+## Context
+
+Publishers using third-party ad tech (Prebid loaders, header bidding wrappers, vendor bundles) have every JS asset served from vendor-controlled infrastructure. They cannot inspect, version-lock, throttle, or disable any of these without contacting the vendor. A misbehaving or slow script on a vendor CDN is completely outside the publisher's operational control.
+
+This feature brings third-party JS delivery inside the publisher's operational boundary. TS fetches vendor JS, caches it in a KV store under opaque first-party paths, and serves it from the publisher's own domain. The publisher sets one CNAME to Fastly. TS handles all fetching, caching, and refreshing transparently.
+
+---
+
+## PRD Open Question Resolutions
+
+| Question | Resolution |
+|---|---|
+| Pre-warming | Deferred to v2. Cold-miss on first request is acceptable. Document as known gap. |
+| Stale TTL | Default 86400s (24h). Optional `stale_ttl_sec` per asset entry to override. |
+| Multiple publishers per service | Closed — one publisher per service. Non-issue. |
+| Versioned wildcard KV growth | Wildcard entries default `ttl_sec = 1800` (30 min) if not set. Eviction job v2. |
+| Vendor CDN URL configurability | Vendors must make CDN URLs configurable (Option 2). Per-vendor launch dependency. String rewriting deferred. |
+| Backend declarations (PRD §9.1) | **Removed.** `BackendConfig::from_url()` in `crates/trusted-server-core/src/backend.rs` creates dynamic backends at runtime. No `[backends.*]` toml entries needed. |
+
+---
+
+## Config Contract: `js-assets.toml` (new file)
+
+Separate from `trusted-server.toml` to avoid bloat. Loaded via the same `include_bytes!` / `build.rs` pattern as the main config.
+
+```toml
+# js-assets.toml
+[kv_stores]
+js_asset_store = "golf-js-asset-store"
+
+[[js_assets]]
+# https://web.prebidwrapper.com/golf-WnLmpLyEjL/default-v2/prebid-load.js
+slug = "aB3kR7mN:prebid-load"
+path = "/sdk/aB3kR7mN.js"
+origin_url = "https://web.prebidwrapper.com/golf-WnLmpLyEjL/default-v2/prebid-load.js"
+inject_in_head = true
+# ttl_sec = 3600           # optional, defaults to 3600 (fixed) or 1800 (wildcard)
+# stale_ttl_sec = 86400    # optional, defaults to 86400
+
+[[js_assets]]
+# https://raven-static.vendor.io/prod/1.19.8-hcskhn/raven.js (wildcard detected)
+slug = "xQ9pL2wY:raven"
+path = "/raven-static/*"
+origin_url = "https://raven-static.vendor.io/prod/*/raven.js"
+inject_in_head = false
+```
+
+### Rust config structs
+
+Add to `crates/trusted-server-core/src/settings.rs`:
+
+```rust
+#[derive(Debug, Default, Clone, Deserialize, Serialize)]
+pub struct KvStores {
+    #[serde(default)]
+    pub js_asset_store: String,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, Validate)]
+pub struct JsAsset {
+    pub slug: String,
+    pub path: String,
+    pub origin_url: String,
+    pub ttl_sec: Option<u32>,        // None = use default
+    pub stale_ttl_sec: Option<u32>,  // None = 86400
+    #[serde(default)]
+    pub inject_in_head: bool,
+}
+
+impl JsAsset {
+    pub fn is_wildcard(&self) -> bool { self.path.contains('*') }
+
+    pub fn resolved_ttl_sec(&self) -> u32 {
+        self.ttl_sec.unwrap_or(if self.is_wildcard() { 1800 } else { 3600 })
+    }
+
+    pub fn resolved_stale_ttl_sec(&self) -> u32 {
+        self.stale_ttl_sec.unwrap_or(86400)
+    }
+}
+```
+
+Extend `Settings`:
+```rust
+#[serde(default)]
+pub kv_stores: KvStores,
+#[serde(default)]
+pub js_assets: Vec<JsAsset>,
+```
+
+**Note on `ttl_sec: Option<u32>`:** Using `Option` (not a default) is intentional — it distinguishes "not set" from "explicitly set to the default value", which is required for the wildcard TTL defaulting logic.
+
+---
+
+## KV Data Model
+
+**Store name:** `js_asset_store`  
+**Key format:** `js-asset:{slug}:{path_suffix}`
+
+For wildcard paths, the wildcard segment is included in the key suffix so each version is cached independently (e.g., `js-asset:xQ9pL2wY:raven:prod/1.19.8-hcskhn`).
+
+**Metadata** (≤2048 bytes, fast non-streaming read — no WASM heap cost on cache hit):
+```json
+{
+  "v": 1,
+  "origin_url": "https://web.prebidwrapper.com/...",
+  "content_type": "application/javascript",
+  "etag": "W/\"72a5efa508944ba68ea00764ce5ebe3d\"",
+  "fetched_at": 1742910400,
+  "expires_at": 1742914000,
+  "asset_slug": "aB3kR7mN:prebid-load"
+}
+```
+
+**Body:** JS content compressed to brotli on the cold path and stored in that form. On every subsequent request the compressed bytes stream directly from KV to the browser — TS never decompresses or re-compresses them. The browser receives the brotli bytes, sees `Content-Encoding: br`, and decompresses natively.
+
+**Slug derivation** (shared algorithm — must be identical between Proxy config and Auditor tool):  
+`slug = "{publisher_prefix}:{asset_stem}"` where `publisher_prefix` = first 8 chars of base62(sha256(`publisher.domain` + `origin_url`)).  
+Engineering should define this as a shared utility to guarantee consistency.
+
+---
+
+## Cache Read Flow
+
+```
+Inbound: GET assets2.publisher.com/sdk/aB3kR7mN.js
+        │
+        ▼
+Read KV metadata only  (~1ms, no stream)
+        │
+        ├── expires_at > now  → stream stored compressed bytes → browser
+        │       Content-Type: application/javascript
+        │       Content-Encoding: br   (browser decompresses natively)
+        │       Cache-Control: max-age=3600
+        │       ETag: {stored_etag}
+        │
+        └── expires_at ≤ now
+                │
+                ▼
+        Conditional GET: If-None-Match: {stored_etag}
+                │
+                ├── 304 Not Modified
+                │       → update expires_at in metadata only (no body write)
+                │       → stream existing KV body → response
+                │
+                └── 200 OK
+                        → write new metadata + new brotli body
+                        → stream body → response
+```
+
+---
+
+## Degraded Behavior
+
+| Condition | Behavior |
+|---|---|
+| KV read fails | Fall through to direct origin fetch. Log `warn`. Do not cache (avoid writing to degraded store). |
+| KV write fails after successful fetch | Serve fetched content. Log `warn`. Next request retries write. |
+| Origin fetch fails | Return `502` with `X-ts-error: asset-origin-unreachable`. If stale KV entry exists, serve it with `X-ts-cache: stale`. |
+| Origin returns non-200/304 | Return `502`. Log status at `warn`. |
+| Response body > 8MB | Return `502`. Do not write to KV. |
+
+---
+
+## Implementation Phases
+
+### Phase 1: Config schema + routing + KV data model
+
+No user-visible behavior. Establishes the foundation.
+
+**Scope:**
+- Provision `js_asset_store` KV store in Fastly and link to the Compute service (see Fastly provisioning below)
+- Add local dev KV store entry to `fastly.toml`
+- Load `js-assets.toml` via `build.rs` alongside existing `trusted-server.toml` pipeline
+- Add `KvStores` and `JsAsset` structs to `settings.rs`; extend `Settings`
+- Route matcher: inbound path → `[[js_assets]]` entry lookup before publisher origin fallback in `main.rs`
+  - Wildcard segment extraction from path
+  - Unmatched paths → `404` with `X-ts-error: asset-not-found`
+- Open `js_asset_store` KV store by name at runtime
+- Define KV metadata struct and key format (`js-asset:{slug}:{suffix}`)
+
+**Fastly KV store provisioning (one-time, per publisher service):**
+
+```bash
+# 1. Create the KV store in Fastly
+fastly kv-store create --name "golf-js-asset-store"
+# Note the store ID from the output
+
+# 2. Link the store to the Compute service
+fastly resource-link create \
+  --service-id <service-id> \
+  --resource-id <kv-store-id> \
+  --version <service-version>
+
+# 3. Activate the new service version
+fastly service-version activate --version <service-version>
+```
+
+**`fastly.toml` — add local dev entry** (matches existing pattern for `counter_store`, `consent_store` etc.):
+```toml
+[[local_server.kv_stores.js_asset_store]]
+    key = "placeholder"
+    data = "placeholder"
+```
+
+The `key`/`data` values are literal dummy strings — Viceroy requires at least one seed entry to declare the store at startup. The real `js-asset:` entries are written at runtime by the handler.
+
+For local testing of the cache hit (hot) path without a live vendor origin, engineering should add a pre-populated test entry alongside the placeholder:
+```toml
+[[local_server.kv_stores.js_asset_store]]
+    key = "js-asset:test-slug:test-asset"
+    data = "{\"v\":1,\"origin_url\":\"https://example.com/test.js\",\"content_type\":\"application/javascript\",\"etag\":\"\\\"test\\\"\",\"fetched_at\":0,\"expires_at\":9999999999,\"asset_slug\":\"test-slug:test-asset\"}"
+```
+
+**Files:**
+- `js-assets.toml` — new, checked in with placeholder entries
+- `fastly.toml` — add `[[local_server.kv_stores.js_asset_store]]` entry
+- `crates/trusted-server-core/src/settings.rs` — add `KvStores`, `JsAsset`, extend `Settings`
+- `crates/trusted-server-adapter-fastly/src/main.rs` — add asset path routing before publisher fallback
+- `crates/trusted-server-adapter-fastly/build.rs` — include `js-assets.toml`
+- `crates/trusted-server-core/src/js_assets/mod.rs` (new module) — route matcher, KV key format, metadata types
+
+### Phase 2: Fetch + cache pipeline
+
+Core value. Requires populated `js-assets.toml` from the Auditor (see delivery order).
+
+**Scope:**
+- `handle_js_asset()` handler wired into route dispatch
+- Cold path: `BackendConfig::from_url()` → origin fetch → compress body to brotli → write compressed bytes + metadata to KV
+- Hot path: KV metadata read → `expires_at > now` check → stream stored compressed bytes directly to browser (no decompression or re-compression)
+- Conditional refresh: `If-None-Match` → handle 304 (metadata-only update) and 200 (full write)
+- All degraded behavior from the table above
+
+**Response headers on serve:**
+```
+Content-Type: application/javascript
+Content-Encoding: br
+Cache-Control: public, max-age=3600
+ETag: {stored_etag}
+```
+
+**Caching layers — all aligned at 1h:**
+- **KV store TTL (1h):** how long TS keeps its cached copy before issuing a conditional GET to the vendor origin
+- **Fastly CDN edge cache (s-maxage=3600 via `public, max-age=3600`):** Fastly serves the asset from edge POP without hitting the TS WASM at all
+- **Browser cache (max-age=3600):** browser does not request the asset again until the hour expires
+
+All three are intentionally aligned. Do not differentiate them without revisiting the full caching strategy.
+
+**Files:**
+- `crates/trusted-server-core/src/js_assets/` — `handle_js_asset()`, fetch logic, KV read/write, conditional refresh
+- `crates/trusted-server-adapter-fastly/src/main.rs` — wire handler into dispatch
+
+**Reuse:**
+- `BackendConfig::from_url()` in `crates/trusted-server-core/src/backend.rs` — dynamic backend creation, no toml changes needed
+- Brotli compression patterns from existing streaming pipeline in `crates/trusted-server-core/src/streaming_processor.rs`
+
+### Phase 3: HTML injection + security hardening
+
+Completes full proxy mode.
+
+**Scope:**
+- For each `[[js_assets]]` entry with `inject_in_head = true`: inject `<script src="...">` at start of `<head>` using existing `html_processor.rs` pipeline. Injection point: before TS core bundle, consistent with existing `head_inserts()` pattern in `integrations/registry.rs`.
+- Path traversal validation: wildcard segments must match `[A-Za-z0-9._\-/]` only. Segments containing `..`, `%2e`, or traversal patterns → `400`.
+- Origin allowlist enforcement: fetch only for URLs declared in `[[js_assets]]`. Wildcard `*` forwarded verbatim to declared origin only.
+
+**Files:**
+- `crates/trusted-server-core/src/html_processor.rs` — js asset head injection
+- `crates/trusted-server-core/src/js_assets/` — path traversal validation
+- `crates/trusted-server-core/src/integrations/registry.rs` — integrate asset injectors alongside existing `head_inserts()`
+
+---
+
+## Known Gaps (v2)
+
+- Pre-warming: populate KV at deploy time (eliminates cold-miss for first user after deploy)
+- KV eviction job for orphaned wildcard entries
+- String rewriting within served JS content (vendor CDN URL rewriting)
+- Tag Auditor for ongoing JS firewall visibility (separate future spec)
+
+---
+
+## Verification
+
+- `cargo test --workspace` — unit + integration tests covering:
+  - Route matching for fixed and wildcard paths
+  - Wildcard segment extraction and forwarding
+  - Path traversal rejection (`..`, `%2e`)
+  - KV hit path (metadata read → stream body)
+  - KV miss path (origin fetch → KV write → stream body)
+  - Conditional refresh: 304 (metadata-only update) and 200 (full write)
+  - Stale-on-error serve with `X-ts-cache: stale`
+  - Degraded behavior fallbacks (KV read fail, KV write fail, origin fail, oversized body)
+- Manual: `fastly compute serve` with a test `[[js_assets]]` entry → verify cache hit/miss response headers and KV population
+- Manual: verify `inject_in_head = true` entry appears as `<script>` before TS bundle in `<head>`
