From fb3cd6c31ac970ea2369a6db4a96ae11ef247018 Mon Sep 17 00:00:00 2001
From: Fernando Paladini <fnpaladini@gmail.com>
Date: Sun, 28 Jun 2026 11:38:41 -0300
Subject: [PATCH] docs: polish Pages site and SEO metadata

---
 docs/favicon.svg |   5 +
 docs/index.html  | 241 ++++++++++++++++++++++++++++++++-----
 docs/llms.txt    |  26 ++++
 docs/robots.txt  |   4 +
 docs/sitemap.xml |   9 ++
 docs/styles.css  | 304 +++++++++++++++++++++++++++++++----------------
 6 files changed, 457 insertions(+), 132 deletions(-)
 create mode 100644 docs/favicon.svg
 create mode 100644 docs/llms.txt
 create mode 100644 docs/robots.txt
 create mode 100644 docs/sitemap.xml

diff --git a/docs/favicon.svg b/docs/favicon.svg
new file mode 100644
index 0000000..ed37b45
--- /dev/null
+++ b/docs/favicon.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="SpecGov">
+  <rect width="64" height="64" rx="12" fill="#082016" />
+  <rect x="10" y="10" width="44" height="44" rx="6" fill="#58a86b" />
+  <path d="M20 24c0-5.1 4.1-9 10.4-9 4 0 7.2 1.2 9.8 3.5l-3.4 4.2a10 10 0 0 0-6.4-2.3c-3 0-4.8 1.5-4.8 3.5 0 2.5 2.3 3.1 6.2 4.1 5.8 1.5 9.2 3.8 9.2 9.2 0 5.6-4.3 9.1-10.8 9.1-5 0-9.1-1.6-12.2-4.7l3.7-4.1a12.2 12.2 0 0 0 8.5 3.4c3.2 0 5.2-1.3 5.2-3.4 0-2.3-1.9-3-6.1-4.1C23.8 32 20 29.6 20 24Z" fill="#f7fbf4" />
+</svg>
diff --git a/docs/index.html b/docs/index.html
index bef1457..db50cb7 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -8,18 +8,139 @@
     />
     <meta
       name="description"
-      content="SpecGov is a deterministic governance layer for keeping specs, ADRs, requirements, and code changes aligned in Git repositories."
+      content="SpecGov is a deterministic spec governance CLI and GitHub Action for keeping requirements, ADRs, product docs, and code changes aligned in Git."
     />
+    <meta name="author" content="Fernando Paladini" />
+    <meta
+      name="robots"
+      content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1"
+    />
+    <link rel="canonical" href="https://paladini.github.io/specgov/" />
     <meta name="theme-color" content="#f7fbf4" />
-    <meta property="og:title" content="SpecGov" />
+    <meta property="og:site_name" content="SpecGov" />
+    <meta
+      property="og:title"
+      content="SpecGov - Deterministic Spec Governance for Git"
+    />
     <meta
       property="og:description"
-      content="Govern the specs your code is supposed to honor."
+      content="Keep requirements, ADRs, product docs, and code changes aligned in pull requests without API keys or model calls."
     />
     <meta property="og:type" content="website" />
     <meta property="og:url" content="https://paladini.github.io/specgov/" />
-    <title>SpecGov | Spec governance for Git repositories</title>
+    <meta
+      property="og:image"
+      content="https://paladini.github.io/specgov/assets/specgov-report.svg"
+    />
+    <meta
+      property="og:image:alt"
+      content="SpecGov pull request report showing deterministic spec governance findings."
+    />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta
+      name="twitter:title"
+      content="SpecGov - Deterministic Spec Governance for Git"
+    />
+    <meta
+      name="twitter:description"
+      content="A local-first CLI and GitHub Action for requirements traceability, ADR governance, and pull request spec checks."
+    />
+    <meta
+      name="twitter:image"
+      content="https://paladini.github.io/specgov/assets/specgov-report.svg"
+    />
+    <meta name="application-name" content="SpecGov" />
+    <title>SpecGov - Spec Governance for Git Pull Requests</title>
+    <link rel="icon" href="favicon.svg" type="image/svg+xml" />
+    <link
+      rel="preload"
+      href="assets/specgov-report.svg"
+      as="image"
+      type="image/svg+xml"
+    />
     <link rel="stylesheet" href="styles.css" />
+    <script type="application/ld+json">
+      {
+        "@context": "https://schema.org",
+        "@graph": [
+          {
+            "@type": "WebSite",
+            "@id": "https://paladini.github.io/specgov/#website",
+            "name": "SpecGov",
+            "url": "https://paladini.github.io/specgov/",
+            "description": "Deterministic spec governance for Git repositories.",
+            "inLanguage": "en",
+            "publisher": {
+              "@id": "https://paladini.github.io/specgov/#person"
+            }
+          },
+          {
+            "@type": "Person",
+            "@id": "https://paladini.github.io/specgov/#person",
+            "name": "Fernando Paladini",
+            "url": "https://github.com/paladini",
+            "sameAs": ["https://github.com/paladini"]
+          },
+          {
+            "@type": "SoftwareApplication",
+            "@id": "https://paladini.github.io/specgov/#software",
+            "name": "SpecGov",
+            "url": "https://paladini.github.io/specgov/",
+            "codeRepository": "https://github.com/paladini/specgov",
+            "description": "SpecGov is a deterministic CLI and GitHub Action that keeps requirements, ADRs, product docs, and code changes aligned in Git pull requests.",
+            "applicationCategory": "DeveloperApplication",
+            "operatingSystem": "Cross-platform",
+            "programmingLanguage": "TypeScript",
+            "runtimePlatform": "Node.js",
+            "softwareRequirements": "Node.js 20 or newer",
+            "license": "https://github.com/paladini/specgov/blob/main/LICENSE",
+            "isAccessibleForFree": true,
+            "offers": {
+              "@type": "Offer",
+              "price": "0",
+              "priceCurrency": "USD"
+            },
+            "featureList": [
+              "Spec-to-code path mappings",
+              "Pull request spec impact checks",
+              "Lifecycle and drift reporting",
+              "Markdown, JSON, and GitHub Action outputs",
+              "Advisory and strict enforcement modes"
+            ]
+          },
+          {
+            "@type": "FAQPage",
+            "@id": "https://paladini.github.io/specgov/#faq",
+            "mainEntity": [
+              {
+                "@type": "Question",
+                "name": "What does SpecGov check?",
+                "acceptedAnswer": {
+                  "@type": "Answer",
+                  "text": "SpecGov checks whether changed code paths map to requirements, ADRs, product docs, or spec folders and reports missing spec impact, stale artifacts, lifecycle gaps, and unmapped code."
+                }
+              },
+              {
+                "@type": "Question",
+                "name": "Does SpecGov need API keys or model calls?",
+                "acceptedAnswer": {
+                  "@type": "Answer",
+                  "text": "No. SpecGov runs locally and in CI with deterministic checks, so it does not require API keys, hosted services, or model calls."
+                }
+              },
+              {
+                "@type": "Question",
+                "name": "Can SpecGov work with existing spec formats?",
+                "acceptedAnswer": {
+                  "@type": "Answer",
+                  "text": "Yes. SpecGov maps existing docs, ADRs, .specs folders, Kiro specs, Spec Kit files, or custom paths through a small .specgov.yml manifest."
+                }
+              }
+            ]
+          }
+        ]
+      }
+    </script>
   </head>
   <body>
     <a class="skip-link" href="#main">Skip to content</a>
@@ -30,39 +151,65 @@
         <span>SpecGov</span>
       </a>
       <nav class="nav-links" aria-label="Primary navigation">
-        <a href="#how-it-works">How it works</a>
-        <a href="#quickstart">Quick start</a>
-        <a href="#action">GitHub Action</a>
-        <a href="https://github.com/paladini/specgov">GitHub</a>
+        <a class="nav-link" href="#how-it-works">How it works</a>
+        <a class="nav-link" href="#quickstart">Quick start</a>
+        <a class="nav-link" href="#action">GitHub Action</a>
+        <a class="nav-link" href="#faq">FAQ</a>
+        <a
+          class="github-link"
+          href="https://github.com/paladini/specgov"
+          aria-label="Open SpecGov on GitHub"
+          rel="noopener"
+        >
+          <svg
+            class="github-icon"
+            viewBox="0 0 16 16"
+            aria-hidden="true"
+            focusable="false"
+          >
+            <path
+              d="M8 0C3.58 0 0 3.67 0 8.2c0 3.62 2.29 6.69 5.47 7.78.4.08.55-.18.55-.4 0-.2-.01-.86-.01-1.56-2.01.38-2.53-.5-2.69-.96-.09-.24-.48-.96-.82-1.15-.28-.16-.68-.55-.01-.56.63-.01 1.08.59 1.23.84.72 1.24 1.87.89 2.33.68.07-.53.28-.89.51-1.09-1.78-.21-3.64-.91-3.64-4.04 0-.89.31-1.62.82-2.19-.08-.21-.36-1.04.08-2.16 0 0 .67-.22 2.2.84A7.43 7.43 0 0 1 8 3.96c.68 0 1.36.09 2 .27 1.53-1.06 2.2-.84 2.2-.84.44 1.12.16 1.95.08 2.16.51.57.82 1.3.82 2.19 0 3.14-1.87 3.83-3.65 4.04.29.26.54.76.54 1.53 0 1.1-.01 1.99-.01 2.27 0 .22.15.48.55.4A8.12 8.12 0 0 0 16 8.2C16 3.67 12.42 0 8 0Z"
+            />
+          </svg>
+          GitHub
+        </a>
       </nav>
     </header>
 
     <main id="main">
       <section class="hero" id="top" aria-labelledby="hero-title">
-        <img
-          class="hero-visual"
-          src="assets/specgov-report.svg"
-          alt="SpecGov pull request report showing an advisory warning for a code change without related spec impact."
-        />
-        <div class="hero-copy">
-          <p class="eyebrow">Deterministic spec governance for Git</p>
-          <h1 id="hero-title">
-            Govern the specs your code is supposed to honor.
-          </h1>
-          <p class="lede">
-            SpecGov keeps requirements, ADRs, product docs, and spec folders
-            aligned with pull requests without API keys, hosted services, or
-            model calls.
-          </p>
-          <div class="hero-actions" aria-label="Primary actions">
-            <a class="button primary" href="#quickstart">Start using SpecGov</a>
-            <a
-              class="button secondary"
-              href="https://github.com/paladini/specgov"
-            >
-              View source
-            </a>
+        <div class="hero-inner">
+          <div class="hero-copy">
+            <p class="eyebrow">Deterministic spec governance for Git</p>
+            <h1 id="hero-title">
+              Govern the specs your code is supposed to honor.
+            </h1>
+            <p class="lede">
+              SpecGov keeps requirements, ADRs, product docs, and spec folders
+              aligned with pull requests without API keys, hosted services, or
+              model calls.
+            </p>
+            <div class="hero-actions" aria-label="Primary actions">
+              <a class="button primary" href="#quickstart"
+                >Start using SpecGov</a
+              >
+              <a
+                class="button secondary"
+                href="https://github.com/paladini/specgov"
+              >
+                View source
+              </a>
+            </div>
           </div>
+          <figure class="hero-visual-frame">
+            <img
+              class="hero-visual"
+              src="assets/specgov-report.svg"
+              width="1120"
+              height="760"
+              alt="SpecGov pull request report showing an advisory warning for a code change without related spec impact."
+            />
+          </figure>
         </div>
       </section>
 
@@ -312,6 +459,38 @@ <h3>Framework folders</h3>
           </article>
         </div>
       </section>
+
+      <section class="section faq-section" id="faq" aria-labelledby="faq-title">
+        <div class="section-heading">
+          <p class="eyebrow">Searchable answers</p>
+          <h2 id="faq-title">Spec governance without a new process.</h2>
+        </div>
+        <div class="faq-list">
+          <details>
+            <summary>What does SpecGov check?</summary>
+            <p>
+              SpecGov checks whether changed code paths map to requirements,
+              ADRs, product docs, or spec folders. It reports missing spec
+              impact, stale artifacts, lifecycle gaps, and unmapped code.
+            </p>
+          </details>
+          <details>
+            <summary>Does SpecGov need API keys or model calls?</summary>
+            <p>
+              No. SpecGov runs locally and in CI with deterministic checks, so
+              it does not require API keys, hosted services, or model calls.
+            </p>
+          </details>
+          <details>
+            <summary>Can SpecGov work with existing spec formats?</summary>
+            <p>
+              Yes. SpecGov maps existing docs, ADRs, .specs folders, Kiro specs,
+              Spec Kit files, or custom paths through a small .specgov.yml
+              manifest.
+            </p>
+          </details>
+        </div>
+      </section>
     </main>
 
     <footer class="site-footer">
diff --git a/docs/llms.txt b/docs/llms.txt
new file mode 100644
index 0000000..9d856ad
--- /dev/null
+++ b/docs/llms.txt
@@ -0,0 +1,26 @@
+# SpecGov
+
+SpecGov is a deterministic spec governance CLI and GitHub Action for Git repositories.
+
+Official site: https://paladini.github.io/specgov/
+Source repository: https://github.com/paladini/specgov
+License: MIT
+Runtime: Node.js 20 or newer
+
+## What SpecGov Does
+
+SpecGov keeps requirements, ADRs, product docs, and spec folders aligned with pull requests. It uses a small `.specgov.yml` manifest to map code paths to governed artifacts and reports missing spec impact, unmapped code, lifecycle gaps, and stale artifacts.
+
+## Key Capabilities
+
+- Deterministic local and CI checks with no API keys, hosted services, or model calls.
+- Advisory mode for non-blocking rollout and strict mode for enforced governance.
+- Markdown reports, JSON trace output, and a GitHub Action wrapper.
+- Compatibility with existing docs, ADRs, `.specs`, Kiro specs, Spec Kit files, and custom folders.
+
+## Useful Entrypoints
+
+- Quick start: https://paladini.github.io/specgov/#quickstart
+- Manifest example: https://paladini.github.io/specgov/#manifest
+- GitHub Action setup: https://paladini.github.io/specgov/#action
+- FAQ: https://paladini.github.io/specgov/#faq
diff --git a/docs/robots.txt b/docs/robots.txt
new file mode 100644
index 0000000..dae7943
--- /dev/null
+++ b/docs/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://paladini.github.io/specgov/sitemap.xml
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
new file mode 100644
index 0000000..3631e8d
--- /dev/null
+++ b/docs/sitemap.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://paladini.github.io/specgov/</loc>
+    <lastmod>2026-06-28</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>1.0</priority>
+  </url>
+</urlset>
diff --git a/docs/styles.css b/docs/styles.css
index c51d9a2..5341c52 100644
--- a/docs/styles.css
+++ b/docs/styles.css
@@ -1,15 +1,18 @@
 :root {
   color-scheme: light;
-  --page: oklch(98% 0.012 125);
-  --paper: oklch(99.2% 0.006 125);
-  --ink: oklch(19% 0.028 150);
+  --page: oklch(98.5% 0.012 125);
+  --paper: oklch(99.4% 0.006 125);
+  --paper-strong: oklch(96.5% 0.018 122);
+  --ink: oklch(18% 0.03 150);
   --muted: oklch(42% 0.032 155);
-  --line: oklch(84% 0.036 145);
-  --green: oklch(55% 0.15 150);
-  --green-dark: oklch(31% 0.1 150);
+  --line: oklch(84% 0.035 145);
+  --green: oklch(54% 0.15 150);
+  --green-dark: oklch(30% 0.1 150);
   --blue: oklch(45% 0.13 245);
   --coral: oklch(59% 0.17 30);
-  --shadow: 0 24px 60px color-mix(in oklch, var(--ink) 12%, transparent);
+  --gold: oklch(72% 0.14 86);
+  --shadow: 0 24px 70px color-mix(in oklch, var(--ink) 14%, transparent);
+  --soft-shadow: 0 14px 36px color-mix(in oklch, var(--ink) 7%, transparent);
   --radius: 8px;
   --space-xs: clamp(0.5rem, 0.45rem + 0.2vw, 0.75rem);
   --space-sm: clamp(0.75rem, 0.65rem + 0.4vw, 1rem);
@@ -34,19 +37,24 @@ body {
   background:
     linear-gradient(
         90deg,
-        color-mix(in oklch, var(--line) 28%, transparent) 1px,
+        color-mix(in oklch, var(--line) 20%, transparent) 1px,
         transparent 1px
       )
       0 0 / 72px 72px,
     linear-gradient(
-        color-mix(in oklch, var(--line) 26%, transparent) 1px,
+        color-mix(in oklch, var(--line) 18%, transparent) 1px,
         transparent 1px
       )
       0 0 / 72px 72px,
-    var(--page);
+    linear-gradient(
+      180deg,
+      color-mix(in oklch, var(--gold) 10%, var(--page)) 0,
+      var(--page) 28rem
+    );
   color: var(--ink);
   font-size: 1rem;
   line-height: 1.6;
+  text-rendering: optimizeLegibility;
 }
 
 a {
@@ -83,9 +91,9 @@ pre {
   align-items: center;
   justify-content: space-between;
   gap: 1rem;
-  padding: 0.85rem max(1rem, env(safe-area-inset-left));
-  border-bottom: 1px solid color-mix(in oklch, var(--line) 72%, transparent);
-  background: color-mix(in oklch, var(--paper) 88%, transparent);
+  padding: 0.75rem max(1rem, calc((100vw - var(--max)) / 2));
+  border-bottom: 1px solid color-mix(in oklch, var(--line) 68%, transparent);
+  background: color-mix(in oklch, var(--paper) 91%, transparent);
   backdrop-filter: blur(16px);
 }
 
@@ -94,7 +102,7 @@ pre {
   align-items: center;
   gap: 0.7rem;
   color: var(--ink);
-  font-weight: 800;
+  font-weight: 850;
   text-decoration: none;
 }
 
@@ -111,62 +119,70 @@ pre {
 }
 
 .nav-links {
-  display: none;
+  display: flex;
   align-items: center;
-  gap: 1.2rem;
+  gap: 0.65rem;
   color: var(--muted);
   font-size: 0.92rem;
-  font-weight: 650;
+  font-weight: 700;
 }
 
-.nav-links a {
+.nav-link {
+  display: none;
   text-decoration: none;
 }
 
-.nav-links a:hover,
-.nav-links a:focus-visible {
+.nav-link:hover,
+.nav-link:focus-visible {
   color: var(--green-dark);
 }
 
-.hero {
-  position: relative;
-  min-height: calc(100svh - 4rem);
-  display: grid;
+.github-link {
+  display: inline-flex;
+  min-height: 42px;
   align-items: center;
-  overflow: hidden;
-  padding: clamp(2.4rem, 5vw, 5rem) 1rem clamp(2.5rem, 5vw, 5rem);
-  border-bottom: 1px solid var(--line);
+  justify-content: center;
+  gap: 0.5rem;
+  padding: 0.64rem 0.86rem;
+  border: 1px solid var(--ink);
+  border-radius: var(--radius);
+  background: var(--ink);
+  color: var(--paper);
+  text-decoration: none;
+  box-shadow: 0 8px 20px color-mix(in oklch, var(--ink) 14%, transparent);
+  transition:
+    transform 160ms ease,
+    box-shadow 160ms ease;
 }
 
-.hero::after {
-  content: "";
-  position: absolute;
-  inset: auto 0 0;
-  height: 32%;
-  background: linear-gradient(
-    to top,
-    color-mix(in oklch, var(--page) 94%, transparent),
-    transparent
-  );
-  pointer-events: none;
+.github-link:hover,
+.github-link:focus-visible {
+  color: var(--paper);
+  transform: translateY(-1px);
+  box-shadow: 0 12px 28px color-mix(in oklch, var(--ink) 18%, transparent);
 }
 
-.hero-visual {
-  position: absolute;
-  right: max(-30rem, -42vw);
-  top: clamp(5rem, 12vh, 9rem);
-  width: min(980px, 118vw);
-  max-width: none;
-  filter: drop-shadow(var(--shadow));
-  opacity: 0.88;
+.github-icon {
+  width: 1rem;
+  height: 1rem;
+  fill: currentColor;
+  flex: 0 0 auto;
+}
+
+.hero {
+  border-bottom: 1px solid var(--line);
+  padding: clamp(2.75rem, 5vw, 5.5rem) max(1rem, calc((100vw - var(--max)) / 2))
+    clamp(2.5rem, 5vw, 5rem);
+}
+
+.hero-inner {
+  display: grid;
+  gap: clamp(1.75rem, 4vw, 4rem);
+  align-items: center;
 }
 
 .hero-copy {
-  position: relative;
-  z-index: 1;
-  width: min(720px, 100%);
-  margin-inline: auto;
-  padding-right: clamp(0rem, 22vw, 18rem);
+  max-width: 660px;
 }
 
 .eyebrow {
@@ -186,19 +202,20 @@ p {
 }
 
 h1 {
-  max-width: 15ch;
   margin-bottom: 1.25rem;
-  font-size: clamp(2.8rem, 5.6vw, 5.2rem);
-  line-height: 0.98;
+  font-size: clamp(2.65rem, 5.2vw, 4.35rem);
+  line-height: 1.03;
   letter-spacing: 0;
+  text-wrap: balance;
 }
 
 h2 {
-  max-width: 14ch;
+  max-width: 12em;
   margin-bottom: 1rem;
-  font-size: clamp(2.1rem, 5vw, 4.8rem);
-  line-height: 1;
+  font-size: clamp(2.1rem, 4vw, 3.9rem);
+  line-height: 1.05;
   letter-spacing: 0;
+  text-wrap: balance;
 }
 
 h3 {
@@ -211,8 +228,8 @@ h3 {
   max-width: 58ch;
   margin-bottom: 1.5rem;
   color: color-mix(in oklch, var(--ink) 84%, var(--green-dark));
-  font-size: clamp(1.12rem, 1.5vw, 1.35rem);
-  line-height: 1.55;
+  font-size: clamp(1.08rem, 1.35vw, 1.28rem);
+  line-height: 1.58;
 }
 
 .hero-actions {
@@ -223,17 +240,18 @@ h3 {
 
 .button {
   display: inline-flex;
-  min-height: 44px;
+  min-height: 46px;
   align-items: center;
   justify-content: center;
-  padding: 0.75rem 1rem;
+  padding: 0.78rem 1rem;
   border: 1px solid var(--ink);
   border-radius: var(--radius);
-  font-weight: 800;
+  font-weight: 850;
   text-decoration: none;
   transition:
     transform 160ms ease,
-    background-color 160ms ease;
+    background-color 160ms ease,
+    box-shadow 160ms ease;
 }
 
 .button:hover,
@@ -244,32 +262,54 @@ h3 {
 .button.primary {
   background: var(--ink);
   color: var(--paper);
+  box-shadow: 0 12px 26px color-mix(in oklch, var(--ink) 14%, transparent);
 }
 
 .button.secondary {
-  background: color-mix(in oklch, var(--paper) 86%, transparent);
+  background: color-mix(in oklch, var(--paper) 88%, transparent);
   color: var(--ink);
 }
 
+.hero-visual-frame {
+  margin: 0;
+  border: 1px solid color-mix(in oklch, var(--ink) 72%, var(--green));
+  border-radius: var(--radius);
+  background: oklch(17% 0.026 155);
+  box-shadow: var(--shadow);
+  overflow: hidden;
+}
+
+.hero-visual {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
 .signal-band {
+  position: relative;
+  z-index: 1;
   display: grid;
-  gap: 1px;
+  gap: 0.8rem;
   max-width: var(--max);
-  margin: -3rem auto var(--space-xl);
+  margin: clamp(1.25rem, 3vw, 2.25rem) auto var(--space-xl);
   padding-inline: 1rem;
 }
 
 .signal-band div {
   display: grid;
-  gap: 0.3rem;
-  padding: 1.1rem;
+  gap: 0.35rem;
+  min-height: 7.75rem;
+  padding: 1.15rem;
   border: 1px solid var(--line);
-  background: var(--paper);
-  box-shadow: 0 10px 30px color-mix(in oklch, var(--ink) 7%, transparent);
+  border-radius: var(--radius);
+  background: color-mix(in oklch, var(--paper) 96%, var(--green) 4%);
+  box-shadow: var(--soft-shadow);
 }
 
 .signal-band strong {
-  font-size: 0.95rem;
+  color: var(--ink);
+  font-size: 1rem;
+  line-height: 1.25;
 }
 
 .signal-band span {
@@ -298,6 +338,12 @@ h3 {
   margin-bottom: 0;
 }
 
+.section-heading.compact h2 {
+  max-width: 15em;
+  font-size: clamp(2rem, 3.2vw, 3rem);
+  line-height: 1.06;
+}
+
 .two-column {
   display: grid;
   gap: var(--space-md);
@@ -317,6 +363,7 @@ h3 {
   border-radius: var(--radius);
   background: var(--paper);
   padding: clamp(1rem, 2.4vw, 1.7rem);
+  box-shadow: 0 8px 22px color-mix(in oklch, var(--ink) 4%, transparent);
 }
 
 .step-number {
@@ -349,7 +396,7 @@ h3 {
 }
 
 .panel-title {
-  padding: 0.78rem 1rem 0;
+  padding: 0.82rem 1rem 0;
   color: oklch(74% 0.13 150);
   font-size: 0.76rem;
   font-weight: 850;
@@ -357,18 +404,30 @@ h3 {
   text-transform: uppercase;
 }
 
+.copy-shell + .panel-title {
+  border-top: 1px solid color-mix(in oklch, var(--paper) 12%, transparent);
+}
+
 pre {
   margin: 0;
   overflow-x: auto;
   padding: 1rem;
-  font-size: 0.9rem;
+  font-size: 0.88rem;
   line-height: 1.55;
 }
 
+pre code {
+  white-space: pre;
+}
+
 .copy-shell {
   position: relative;
 }
 
+.copy-shell .copy-block {
+  padding-right: 5.1rem;
+}
+
 .copy-button {
   position: absolute;
   top: 0.65rem;
@@ -389,6 +448,7 @@ pre {
   border: 1px solid var(--line);
   border-radius: var(--radius);
   background: var(--paper);
+  box-shadow: var(--soft-shadow);
 }
 
 .command-row {
@@ -421,6 +481,31 @@ pre {
   font-weight: 850;
 }
 
+.faq-list {
+  display: grid;
+  gap: 0.75rem;
+}
+
+.faq-list details {
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--paper);
+  box-shadow: 0 8px 22px color-mix(in oklch, var(--ink) 4%, transparent);
+}
+
+.faq-list summary {
+  cursor: pointer;
+  padding: 1rem 1.15rem;
+  color: var(--ink);
+  font-weight: 850;
+}
+
+.faq-list p {
+  margin: 0;
+  padding: 0 1.15rem 1.15rem;
+  color: var(--muted);
+}
+
 .site-footer {
   display: flex;
   flex-direction: column;
@@ -446,27 +531,13 @@ pre {
   font-weight: 850;
 }
 
-@media (min-width: 720px) {
-  .site-header {
-    padding-inline: 1.5rem;
-  }
-
+@media (min-width: 760px) {
   .nav-links {
-    display: flex;
-  }
-
-  .hero {
-    padding-inline: 1.5rem;
+    gap: 1rem;
   }
 
-  .hero-copy {
-    margin-left: max(1rem, calc((100vw - var(--max)) / 2));
-    margin-right: 0;
-  }
-
-  .hero-visual {
-    right: max(-36rem, calc((100vw - var(--max)) / 2 - 21rem));
-    width: min(900px, 70vw);
+  .nav-link {
+    display: inline-flex;
   }
 
   .signal-band {
@@ -475,7 +546,7 @@ pre {
 
   .two-column,
   .split-section {
-    grid-template-columns: minmax(0, 0.9fr) minmax(340px, 1.1fr);
+    grid-template-columns: minmax(0, 0.85fr) minmax(360px, 1.15fr);
   }
 
   .flow-grid,
@@ -495,20 +566,51 @@ pre {
   }
 }
 
-@media (max-width: 719px) {
-  .hero-visual {
-    right: -34rem;
-    opacity: 0.14;
+@media (min-width: 960px) {
+  .hero-inner {
+    grid-template-columns: minmax(0, 1fr) minmax(420px, 0.9fr);
   }
+}
 
-  .hero-copy {
-    padding-right: 0;
+@media (max-width: 759px) {
+  .site-header {
+    padding-block: 0.65rem;
+  }
+
+  .brand {
+    gap: 0.55rem;
+  }
+
+  .brand-mark {
+    width: 1.95rem;
+    height: 1.95rem;
+  }
+
+  .hero {
+    padding-top: 2.35rem;
   }
 
   h1 {
-    max-width: 10.5ch;
-    font-size: clamp(2.75rem, 13vw, 3.6rem);
-    line-height: 0.98;
+    font-size: clamp(2.45rem, 10vw, 3.2rem);
+    line-height: 1.04;
+  }
+
+  h2 {
+    font-size: clamp(1.9rem, 8vw, 2.75rem);
+  }
+
+  .hero-visual-frame {
+    margin-top: 0.35rem;
+  }
+
+  .signal-band div {
+    min-height: 0;
+  }
+}
+
+@media (max-width: 420px) {
+  .brand span:last-child {
+    display: none;
   }
 }