warp-os 1.1.0

package/agents/warp-upgrade.md

@@ -0,0 +1,334 @@
+---
+name: warp-upgrade
+description: >-
+  One-command Warp upgrade from inside Claude Code. Pulls latest, rebuilds, reinstalls, shows changelog, detects migration requirements, and offers to re-run /warp-setup on the current project. No terminal switching needed.
+---
+
+<!-- ═══════════════════════════════════════════════════════════ -->
+<!-- TIER 1 — Engineering Foundation. Generated by build.sh    -->
+<!-- ═══════════════════════════════════════════════════════════ -->
+
+
+# Warp Engineering Foundation
+
+Universal principles for every agent in the Warp pipeline. Tier 1: highest authority.
+
+---
+
+## Core Principles
+
+**Clarity over cleverness.** Optimize for "I can understand this in six months."
+
+**Explicit contracts between layers.** Modules communicate through defined interfaces. Swap persistence without touching the service layer.
+
+**Every component earns its place.** No speculative code. If a feature isn't in the current or next phase, it doesn't exist in code.
+
+**Fail loud, recover gracefully.** Never swallow errors silently. User-facing experience degrades gracefully — stale-data indicator, not a crash.
+
+**Prefer reversible decisions.** When two approaches are equivalent, choose the one that can be undone.
+
+**Security is structural.** Designed for the most restrictive phase, enforced from the earliest.
+
+**AI is a tool, not an authority.** AI agents accelerate development but do not make architectural decisions autonomously. Every significant design decision is reviewed by the user before it ships.
+
+---
+
+## Bias Classification
+
+When the same AI system writes code, writes tests, and evaluates its own output, shared biases create blind spots.
+
+| Level | Definition | Trust |
+|-------|-----------|-------|
+| **L1** | Deterministic. Binary pass/fail. Zero AI judgment. | Highest |
+| **L2** | AI interpretation anchored to verifiable external source. | Medium |
+| **L3** | AI evaluating AI. Both sides share training biases. | Lowest |
+
+**L1 Imperative:** Every quality gate that CAN be L1 MUST be L1. L3 is the outer layer, never the only layer. When L1 is unavailable, use L2 (grounded in external docs). Fall back to L3 only when no external anchor exists.
+
+---
+
+## Completeness
+
+AI compresses implementation 10-100x. Always choose the complete option. Full coverage, hardened behavior, robust edge cases. The delta between "good enough" and "complete" is minutes, not days.
+
+Never recommend the less-complete option. Never skip edge cases. Never defer what can be done now.
+
+---
+
+## Quality Gates
+
+**Hard Gate** — blocks progression. Between major phases. Present output, ask the user: A) Approve, B) Revise, C) Restart. MUST get user input.
+
+**Soft Gate** — warns but allows. Between minor steps. Proceed if quality criteria met; warn and get input if not.
+
+**Completeness Gate** — final check before artifact write. Verify no empty sections, key decisions explicit. Fix before writing.
+
+---
+
+## Escalation
+
+Always OK to stop and escalate. Bad work is worse than no work.
+
+**STOP if:** 3 failed attempts at the same problem, uncertain about security-sensitive changes, scope exceeds what you can verify, or a decision requires domain knowledge you don't have.
+
+---
+
+## External Data Gate
+
+When a task requires real-world data or domain knowledge that cannot be derived from code, docs, or git history — PAUSE and ask the user. Never hallucinate fixtures or APIs. Check docs via Context7 or saved files before writing code that touches external services.
+
+---
+
+## Error Severity
+
+| Tier | Definition | Response |
+|------|-----------|----------|
+| T1 | Normal variance (cache miss, retry succeeded) | Log, no action |
+| T2 | Degraded capability (stale data served, fallback active) | Log, degrade visibly |
+| T3 | Operation failed (invalid input, auth rejected) | Log, return error, continue |
+| T4 | Subsystem non-functional (DB unreachable, corrupt state) | Log, halt subsystem, alert |
+
+---
+
+## Universal Engineering Principles
+
+- Assert outcomes, not implementation. Test "input produces output" — not "function X calls Y."
+- Each test is independent. No shared state or execution order dependencies.
+- Mock at the system boundary, not internal helpers.
+- Expected values are hardcoded from the spec, never recalculated using production logic.
+- Every bug fix ships with a regression test.
+- Every error has two audiences: the system (full diagnostics) and the consumer (only actionable info). Never the same message.
+- Errors change shape at every module boundary. No error propagates without translation.
+- Errors never reveal system internals to consumers. No stack traces, file paths, or queries in responses.
+- Graceful degradation: live data → cached → static fallback → feature unavailable.
+- Every input is hostile until validated.
+- Default deny. Any permission not explicitly granted is denied.
+- Secrets never logged, never in error messages, never in responses, never committed.
+- Dependencies flow downward only. Never import from a layer above.
+- Each external service has exactly one integration module that owns its boundary.
+- Data crosses boundaries as plain values. Never pass ORM instances or SDK types between layers.
+- ASCII diagrams for data flow, state machines, and architecture. Use box-drawing characters (─│┌┐└┘├┤┬┴┼) and arrows (→←↑↓).
+
+---
+
+## Shell Execution
+
+Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`) or backslash paths in Bash tool calls. On Windows, use forward slashes, `ls`, `grep`, `rm`, `cat`.
+
+---
+
+## AskUserQuestion
+
+**Contract:**
+1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
+2. **Simplify:** Plain English a smart 16-year-old could follow.
+3. **Recommend:** Name the recommended option and why.
+4. **Options:** Ordered by completeness descending.
+5. **One decision per question.**
+
+**When to ask (mandatory):**
+1. Design/UX choice not resolved in artifacts
+2. Trade-off with more than one viable option
+3. Before writing to files outside .warp/
+4. Deviating from architecture or design spec
+5. Skipping or deferring an acceptance criterion
+6. Before any destructive or irreversible action
+7. Ambiguous or underspecified requirement
+8. Choosing between competing library/tool options
+
+**Completeness scores in labels (mandatory):**
+Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
+Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
+
+**Formatting:**
+- *Italics* for emphasis, not **bold** (bold for headers only).
+- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- Previews under 8 lines. Full mockups go in conversation text before the question.
+
+---
+
+## Scale Detection
+
+- **Feature:** One capability/screen/endpoint. Lean phases, fewer questions.
+- **Module:** A package or subsystem. Full depth, multiple concerns.
+- **System:** Whole product or greenfield. Maximum depth, every edge case.
+
+Detection: Single behavior change → feature. 3+ files → module. Cross-package → system.
+
+---
+
+## Artifact I/O
+
+Header: `<!-- Pipeline: {skill-name} | {date} | Scale: {scale} | Inputs: {prerequisites} -->`
+
+Validation: all schema sections present, no empty sections, key decisions explicit.
+Preview: show first 8-10 lines + total line count before writing.
+HTML preview: use `_warp_html.sh` if available. Open in browser at hard gates only.
+
+---
+
+## Completion Banner
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WARP │ {skill-name} │ {STATUS}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Wrote:      {artifact path(s)}
+Decisions:  {N} recorded
+Next:       /{next-skill}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Status values: **DONE**, **DONE_WITH_CONCERNS** (list concerns), **BLOCKED** (state blocker + what was tried + next steps), **NEEDS_CONTEXT** (state exactly what's needed).
+
+<!-- ═══════════════════════════════════════════════════════════ -->
+<!-- Skill-Specific Content.                                   -->
+<!-- ═══════════════════════════════════════════════════════════ -->
+
+
+# Upgrade
+
+Meta skill. Upgrades WarpOS from inside Claude Code — no terminal switching.
+
+**The upgrade is ONE COMMAND.** Do not decompose into manual steps. The upgrade
+script handles pull, build, install, auto-patch, changelog, and migration detection.
+
+---
+
+## STEP 1: Locate the WarpOS Repo
+
+```bash
+WARP_REPO=""
+for candidate in \
+  "$(cat "$HOME/.warp/repo-path" 2>/dev/null)" \
+  "$(readlink -f ~/.claude/skills/warp-setup 2>/dev/null)/../../../.." \
+  "$(dirname "$(readlink -f ~/.warp/hooks/identity-briefing.sh 2>/dev/null)")/../.." \
+  "$HOME/Projects/warp" \
+  "$HOME/warp" \
+; do
+  [ -z "$candidate" ] && continue
+  if [ -d "$candidate/.git" ] && [ -f "$candidate/VERSION" ] && [ -f "$candidate/build.sh" ]; then
+    WARP_REPO="$(cd "$candidate" && pwd)"
+    break
+  fi
+done
+echo "Warp repo: ${WARP_REPO:-NOT FOUND}"
+```
+
+If not found, ask the user for the path.
+
+---
+
+## STEP 2: Run the Upgrade Script
+
+**Run `bin/warp-upgrade.sh` as a single command. Do NOT decompose into manual steps.**
+
+The script handles everything: fetch, version check, pull, build, install, auto-patch
+project hooks, changelog display, migration detection, and restart recommendation.
+
+```bash
+cd "$WARP_REPO" && bash bin/warp-upgrade.sh
+```
+
+**IMPORTANT — Timeout:** On Windows (Git Bash), build + install can take 2-4 minutes.
+Use a Bash timeout of at least 300000ms (5 minutes). If the default timeout is shorter,
+set it explicitly. A timed-out upgrade leaves a half-installed state.
+
+**If the script succeeds:** Read its output, summarize what changed, and remind the user
+to restart Claude Code.
+
+**If the script fails:** Read the error output. Common failures:
+- Network error on git pull → "Check your connection and try again"
+- Build error → "build.sh failed — check the error above"
+- Install error (Windows file locks) → "Close other Claude Code instances and retry"
+- Git conflicts → "Your local Warp repo has changes. Run `git stash` first."
+
+Only if the script itself is missing or broken should you fall back to manual steps.
+
+---
+
+## STEP 3: Verify Auto-Patch (if script completed)
+
+The upgrade script auto-patches `.claude/settings.local.json` in the current project
+directory with the latest hook config from `~/.warp/project-hooks.json`.
+
+Verify the patch applied:
+
+```bash
+# Check that settings.local.json references new hook names
+grep -c 'identity-foundation\|identity-briefing\|consistency-check' .claude/settings.local.json 2>/dev/null && echo "hooks patched" || echo "hooks NOT patched"
+```
+
+If NOT patched (script ran from a different directory, or no settings.local.json):
+- If `settings.local.json` exists but has old hook names → patch it manually using
+  `~/.warp/project-hooks.json` as the source. Preserve `permissions` and `enabledMcpjsonServers`.
+- If no `settings.local.json` → tell user to run `/warp-setup` (first-time setup, not upgrade).
+
+---
+
+## FALLBACK: Manual Steps (only if warp-upgrade.sh is missing/broken)
+
+If `bin/warp-upgrade.sh` does not exist or crashes on invocation, fall back to manual:
+
+```bash
+cd "$WARP_REPO"
+git fetch origin --quiet
+git pull --rebase origin master
+bash build.sh
+bash install.sh
+cat CHANGELOG.md | head -60
+```
+
+Then manually patch project hooks:
+```bash
+# Read template and patch settings.local.json
+python3 -c "
+import json
+t = json.load(open('$HOME/.warp/project-hooks.json'))
+s = json.load(open('.claude/settings.local.json'))
+s['agent'] = t['agent']
+s['hooks'] = t['hooks']
+json.dump(s, open('.claude/settings.local.json','w'), indent=2)
+print('Patched.')
+"
+```
+
+**This fallback exists for emergencies only.** The script is the primary path.
+
+---
+
+## OUTPUT FORMAT
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WARP │ UPGRADE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Repo:      {path}
+  Upgrade:   v{old} → v{new}
+
+  {changelog excerpt — Added/Changed/Removed}
+
+  Hooks:     auto-patched ✓
+  Restart:   required (new hooks + skills)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Always remind:** "Restart Claude Code to pick up the new skills and hooks."
+
+---
+
+## MUST / MUST NOT
+
+**MUST:**
+- Run `bin/warp-upgrade.sh` as a single command (not decomposed steps)
+- Use a 5-minute timeout for the upgrade script on Windows
+- Verify hooks auto-patched after script completes
+- Show changelog summary
+- Remind user to restart Claude Code
+
+**MUST NOT:**
+- Decompose the upgrade into individual git/build/install commands when the script works
+- Use default Bash timeout (2 minutes is too short on Windows)
+- Proceed to install if build fails
+- Require the user to re-run `/warp-setup` after a normal upgrade
+- Force-push, reset, or destructively modify the Warp repo without consent

package/bin/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// cli.js — Warp CLI entry point
+// Usage: npx warp-os install | upgrade | version | uninstall
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const command = process.argv[2];
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`
+warp-os — A development operating system for Claude Code
+
+Usage:
+  npx warp-os install     Install Warp (skills, agents, hooks, claude-mem)
+  npx warp-os upgrade     Upgrade to the latest version
+  npx warp-os uninstall   Remove Warp from this machine
+  npx warp-os version     Show installed version
+  npx warp-os doctor      Check installation health
+`);
+  process.exit(0);
+}
+
+if (command === 'version' || command === '--version' || command === '-v') {
+  const version = require('../package.json').version;
+  console.log(`warp-os v${version}`);
+  process.exit(0);
+}
+
+if (command === 'install' || command === 'upgrade') {
+  require('./install.js');
+} else if (command === 'uninstall') {
+  console.log('Uninstall not yet implemented. Remove manually:');
+  console.log('  rm -rf ~/.claude/skills/warp-*');
+  console.log('  rm -rf ~/.claude/agents/warp-*.md');
+  console.log('  rm -rf ~/.warp/');
+  process.exit(0);
+} else if (command === 'doctor') {
+  require('./install.js');
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "npx warp-os --help" for usage.');
+  process.exit(1);
+}

package/bin/hooks/_warp_html.sh

@@ -0,0 +1,291 @@
+#!/usr/bin/env bash
+# _warp_html.sh — Shared utility for markdown-to-HTML conversion
+# Source this file in skills/hooks that need HTML preview generation.
+# Provides:
+#   _warp_md_to_html "input.md" "artifact_name" "output.html"
+#   _warp_open_preview "file.html"
+#
+# Uses the warp streak CSS palette. Sanitizes HTML tags to prevent XSS (F-1).
+# No external dependencies — pure bash + sed.
+
+# Convert markdown to HTML with warp streak CSS
+# Usage: _warp_md_to_html "input.md" "Artifact Name" "output.html"
+_warp_md_to_html() {
+  local input="$1"
+  local artifact_name="$2"
+  local output="$3"
+
+  if [ ! -f "$input" ]; then
+    echo "[WARP WARNING] _warp_md_to_html: input file not found: $input" >&2
+    return 1
+  fi
+
+  # Ensure output directory exists
+  mkdir -p "$(dirname "$output")" 2>/dev/null || true
+
+  # Convert markdown to HTML with state tracking for code blocks and comments
+  local body=""
+  local in_code=false
+  local in_comment=false
+
+  while IFS= read -r line || [ -n "$line" ]; do
+    # --- HTML comment handling: skip entirely ---
+    if [[ "$line" == *"<!--"* ]]; then
+      if [[ "$line" == *"-->"* ]]; then
+        continue  # single-line comment — skip
+      fi
+      in_comment=true
+      continue
+    fi
+    if $in_comment; then
+      if [[ "$line" == *"-->"* ]]; then
+        in_comment=false
+      fi
+      continue
+    fi
+
+    # --- Fenced code blocks ---
+    if [[ "$line" =~ ^\`\`\` ]]; then
+      if $in_code; then
+        body+="</code></pre>"$'\n'
+        in_code=false
+      else
+        body+="<pre><code>"
+        in_code=true
+      fi
+      continue
+    fi
+
+    if $in_code; then
+      # Inside code block: escape HTML but preserve whitespace exactly
+      line="${line//&/&amp;}"
+      line="${line//</&lt;}"
+      line="${line//>/&gt;}"
+      body+="$line"$'\n'
+      continue
+    fi
+
+    # --- Normal markdown conversion (outside code blocks) ---
+    # Escape HTML entities
+    line="${line//&/&amp;}"
+    line="${line//</&lt;}"
+    line="${line//>/&gt;}"
+
+    # Headings
+    if [[ "$line" =~ ^###\  ]]; then
+      line="<h3>${line#\#\#\# }</h3>"
+    elif [[ "$line" =~ ^##\  ]]; then
+      line="<h2>${line#\#\# }</h2>"
+    elif [[ "$line" =~ ^#\  ]]; then
+      line="<h1>${line#\# }</h1>"
+    # Horizontal rule
+    elif [[ "$line" == "---" ]]; then
+      line="<hr>"
+    # List items
+    elif [[ "$line" =~ ^-\  ]]; then
+      line="<li>${line#- }</li>"
+    elif [[ "$line" =~ ^[0-9]+\.\  ]]; then
+      line="<li>${line#*. }</li>"
+    # Blank line
+    elif [[ -z "$line" ]]; then
+      line="<br>"
+    # Table rows (pipe-delimited)
+    elif [[ "$line" == *"|"* ]] && [[ "$line" =~ ^\|.*\|$ ]]; then
+      # Skip separator rows (|---|---|)
+      if [[ "$line" =~ ^[[:space:]]*\|[-[:space:]|]+\|[[:space:]]*$ ]]; then
+        continue
+      fi
+      local cells=""
+      local tag="td"
+      # Simple heuristic: if all cells are bold, use th
+      if [[ "$line" == *"**"* ]] && [[ $(echo "$line" | grep -o '\*\*' | wc -l) -ge 4 ]]; then
+        tag="th"
+      fi
+      IFS='|' read -ra PARTS <<< "$line"
+      for part in "${PARTS[@]}"; do
+        part=$(echo "$part" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        [ -z "$part" ] && continue
+        cells+="<$tag>$part</$tag>"
+      done
+      line="<tr>$cells</tr>"
+    fi
+
+    # Inline formatting (outside headings processing)
+    line=$(echo "$line" | sed 's/\*\*\([^*]*\)\*\*/<strong>\1<\/strong>/g')
+    line=$(echo "$line" | sed 's/\*\([^*]*\)\*/<em>\1<\/em>/g')
+    line=$(echo "$line" | sed 's/`\([^`]*\)`/<code>\1<\/code>/g')
+
+    body+="$line"$'\n'
+  done < "$input"
+
+  # Close unclosed code block
+  if $in_code; then
+    body+="</code></pre>"$'\n'
+  fi
+
+  # Wrap consecutive <tr> rows in <table> tags
+  body=$(echo "$body" | awk '
+    /<tr>/ && !intable { print "<table>"; intable=1 }
+    !/<tr>/ && intable { print "</table>"; intable=0 }
+    { print }
+    END { if (intable) print "</table>" }
+  ')
+
+  # Write the full HTML file
+  cat > "$output" << HTMLEOF
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Warp │ ${artifact_name}</title>
+  <style>
+    :root {
+      --space-deep:     #0d0d14;
+      --space-surface:  #1a1528;
+      --uv-border:      #2d2444;
+      --uv-glow:        #6b5ce7;
+      --streak-primary: #e8e6f0;
+      --streak-bright:  #f5f4f8;
+      --streak-dim:     #a9a5b8;
+      --flare-cyan:     #58e8ff;
+      --flare-magenta:  #ff58e4;
+      --flare-amber:    #ffc858;
+      --flare-red:      #ff5878;
+      --flare-green:    #58ff9e;
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font: 16px/1.8 -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: var(--space-deep); color: var(--streak-primary);
+      max-width: 860px; margin: 0 auto; padding: 0 1.5rem 4rem;
+      /* Subtle radial glow from top center */
+      background-image: radial-gradient(ellipse 80% 50% at 50% -5%, rgba(107, 92, 231, 0.12) 0%, transparent 70%);
+      background-attachment: fixed;
+    }
+    /* Hero header — full-width gradient bar with glow */
+    .warp-header {
+      font: 700 0.8rem/1 'JetBrains Mono', 'Fira Code', monospace;
+      letter-spacing: 0.2em; text-transform: uppercase;
+      padding: 1.5rem 0;
+      margin: 0 -1.5rem 3rem;
+      padding-left: 1.5rem;
+      border-bottom: 2px solid transparent;
+      border-image: linear-gradient(90deg, var(--flare-cyan), var(--flare-magenta), var(--flare-amber), var(--flare-green), var(--flare-cyan)) 1;
+      background: linear-gradient(180deg, rgba(107, 92, 231, 0.08) 0%, transparent 100%);
+      color: var(--streak-dim);
+    }
+    .warp-header span {
+      background: linear-gradient(90deg, var(--flare-cyan), var(--flare-magenta), var(--flare-amber), var(--flare-green));
+      -webkit-background-clip: text; -webkit-text-fill-color: transparent;
+      background-clip: text;
+    }
+    /* H1 — large with rainbow underline accent */
+    h1 {
+      color: var(--streak-bright); font-size: 1.6rem; font-weight: 700;
+      margin: 2.5rem 0 1.2rem; padding-bottom: 0.6rem;
+      border-bottom: 2px solid transparent;
+      border-image: linear-gradient(90deg, var(--flare-cyan), var(--flare-magenta), transparent 80%) 1;
+    }
+    /* H2 — section cards */
+    h2 {
+      color: var(--streak-bright); font-size: 1.15rem; font-weight: 600;
+      margin: 2.5rem -1rem 1rem; padding: 0.7rem 1rem;
+      background: linear-gradient(135deg, rgba(107, 92, 231, 0.1) 0%, rgba(26, 21, 40, 0.6) 100%);
+      border-left: 3px solid var(--uv-glow);
+      border-radius: 0 8px 8px 0;
+    }
+    h3 {
+      color: var(--streak-bright); font-size: 1rem; font-weight: 600;
+      margin: 1.8rem 0 0.5rem; padding-left: 0.8rem;
+      border-left: 2px solid var(--uv-glow);
+    }
+    p { margin: 0.7rem 0; }
+    a { color: var(--flare-cyan); text-decoration: none; border-bottom: 1px solid rgba(88, 232, 255, 0.3);
+        transition: border-color 0.2s; }
+    a:hover { border-bottom-color: var(--flare-cyan); }
+    strong { color: var(--streak-bright); }
+    em { color: var(--streak-dim); font-style: italic; }
+    /* Inline code — pill with glow */
+    code {
+      font-family: 'JetBrains Mono', 'Fira Code', monospace;
+      background: rgba(107, 92, 231, 0.1); padding: 2px 8px; border-radius: 4px;
+      font-size: 0.86em; border: 1px solid rgba(107, 92, 231, 0.25);
+      color: var(--streak-bright);
+    }
+    /* Code blocks — elevated card with UV border glow */
+    pre {
+      background: linear-gradient(180deg, var(--space-surface) 0%, rgba(13, 13, 20, 0.95) 100%);
+      padding: 1.4rem 1.6rem; border-radius: 10px;
+      border: 1px solid var(--uv-border); overflow-x: auto; margin: 1.4rem 0;
+      box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4), 0 0 1px rgba(107, 92, 231, 0.3);
+      position: relative;
+    }
+    pre::before {
+      content: ''; position: absolute; top: -1px; left: 20%; right: 20%; height: 1px;
+      background: linear-gradient(90deg, transparent, var(--uv-glow), transparent);
+    }
+    pre code { background: none; padding: 0; font-size: 0.84em; line-height: 1.6;
+               border: none; color: var(--streak-primary); }
+    /* Tables — frosted glass effect */
+    table {
+      border-collapse: separate; border-spacing: 0; width: 100%; margin: 1.4rem 0;
+      font-size: 0.92em; border-radius: 8px; overflow: hidden;
+      border: 1px solid var(--uv-border);
+      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
+    }
+    th, td { border-bottom: 1px solid var(--uv-border); padding: 0.6rem 0.85rem; text-align: left; }
+    td { border-right: 1px solid rgba(45, 36, 68, 0.5); }
+    td:last-child { border-right: none; }
+    th {
+      background: rgba(107, 92, 231, 0.12);
+      color: var(--streak-bright); font-weight: 600; font-size: 0.8em;
+      text-transform: uppercase; letter-spacing: 0.06em;
+      border-bottom: 2px solid var(--uv-border);
+    }
+    tr:last-child td { border-bottom: none; }
+    tr:hover td { background: rgba(107, 92, 231, 0.06); transition: background 0.15s; }
+    blockquote {
+      border-left: 3px solid var(--uv-glow); padding: 0.8rem 1.2rem;
+      color: var(--streak-dim); margin: 1.2rem 0;
+      background: rgba(107, 92, 231, 0.04); border-radius: 0 8px 8px 0;
+    }
+    li { margin: 0.35rem 0; margin-left: 1.5rem; }
+    li::marker { color: var(--uv-glow); }
+    /* HR — rainbow streak */
+    hr {
+      border: none; height: 1px; margin: 3rem 0;
+      background: linear-gradient(90deg, transparent 5%, var(--flare-cyan) 20%, var(--flare-magenta) 50%, var(--flare-amber) 80%, transparent 95%);
+      opacity: 0.4;
+    }
+    /* Scrollbar */
+    ::-webkit-scrollbar { width: 6px; height: 6px; }
+    ::-webkit-scrollbar-track { background: var(--space-deep); }
+    ::-webkit-scrollbar-thumb { background: var(--uv-border); border-radius: 3px; }
+    ::-webkit-scrollbar-thumb:hover { background: var(--uv-glow); }
+  </style>
+</head>
+<body>
+  <div class="warp-header"><span>Warp</span> │ ${artifact_name}</div>
+  ${body}
+</body>
+</html>
+HTMLEOF
+
+  # Set restrictive permissions (security.md recommendation)
+  chmod 600 "$output" 2>/dev/null || true
+}
+
+# Open a file in the user's default browser (cross-platform)
+# Usage: _warp_open_preview "file.html"
+_warp_open_preview() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    return 0
+  fi
+  case "$(uname -s)" in
+    MINGW*|MSYS*|CYGWIN*) start "" "$file" 2>/dev/null || true ;;
+    Darwin)               open "$file" 2>/dev/null || true ;;
+    *)                    xdg-open "$file" 2>/dev/null || true ;;
+  esac
+}