changes

packages/cli/src/commands/init.ts

···
 import { spawn } from "child_process";
 import { createInterface } from "readline";
 import pc from "picocolors";
+import { generateExternalsFile } from "../utils/externals-generator.js";
 
 function gradientText(text: string): string {
   const colors = [
···
   return `import "@typelex/emitter";
 import "./externals.tsp";
 
-namespace ${namespace}.post {
-  @rec("tid")
+namespace ${namespace}.example.profile {
+  /** My profile. */
+  @rec("literal:self")
   model Main {
-    @required text: string;
-    @required createdAt: datetime;
+    /** Free-form profile description.*/
+    @maxGraphemes(256)
+    description?: string;
   }
 }
 `;
···
     console.log(`${pc.green("✓")} Created ${pc.cyan("typelex/main.tsp")}`);
   }
 
-  // Always create/overwrite externals.tsp
-  await writeFile(externalsTspPath, EXTERNALS_TSP_TEMPLATE, "utf-8");
+  // Generate externals.tsp with any existing external lexicons
+  const outDir = lexiconsDir || "./lexicons";
+  await generateExternalsFile(namespace, cwd, outDir);
   console.log(`${pc.green("✓")} Created ${pc.cyan("typelex/externals.tsp")}`);
 
   // Add build script to package.json

packages/cli/test/scenarios/basic/expected/lexicons/com/test/example/profile.json

···
+{
+  "lexicon": 1,
+  "id": "com.test.example.profile",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "literal:self",
+      "record": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "maxGraphemes": 256,
+            "description": "Free-form profile description."
+          }
+        }
+      },
+      "description": "My profile."
+    }
+  }
+}

packages/cli/test/scenarios/basic/expected/lexicons/com/test/post.json

···
-{
-  "lexicon": 1,
-  "id": "com.test.post",
-  "defs": {
-    "main": {
-      "type": "record",
-      "key": "tid",
-      "record": {
-        "type": "object",
-        "properties": {
-          "text": {
-            "type": "string"
-          },
-          "createdAt": {
-            "type": "string",
-            "format": "datetime"
-          }
-        },
-        "required": [
-          "text",
-          "createdAt"
-        ]
-      }
-    }
-  }
-}

packages/cli/test/scenarios/basic/expected/typelex/main.tsp

···
 import "@typelex/emitter";
 import "./externals.tsp";
 
-namespace com.test.post {
-  @rec("tid")
+namespace com.test.example.profile {
+  /** My profile. */
+  @rec("literal:self")
   model Main {
-    @required text: string;
-    @required createdAt: datetime;
+    /** Free-form profile description.*/
+    @maxGraphemes(256)
+    description?: string;
   }
 }

packages/cli/test/scenarios/nested-init/expected/lexicons/com/myservice/example/profile.json

···
+{
+  "lexicon": 1,
+  "id": "com.myservice.example.profile",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "literal:self",
+      "record": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "maxGraphemes": 256,
+            "description": "Free-form profile description."
+          }
+        }
+      },
+      "description": "My profile."
+    }
+  }
+}

packages/cli/test/scenarios/nested-init/expected/lexicons/com/myservice/post.json

···
-{
-  "lexicon": 1,
-  "id": "com.myservice.post",
-  "defs": {
-    "main": {
-      "type": "record",
-      "key": "tid",
-      "record": {
-        "type": "object",
-        "properties": {
-          "text": {
-            "type": "string"
-          },
-          "createdAt": {
-            "type": "string",
-            "format": "datetime"
-          }
-        },
-        "required": [
-          "text",
-          "createdAt"
-        ]
-      }
-    }
-  }
-}

packages/cli/test/scenarios/nested-init/expected/typelex/main.tsp

···
 import "@typelex/emitter";
 import "./externals.tsp";
 
-namespace com.myservice.post {
-  @rec("tid")
+namespace com.myservice.example.profile {
+  /** My profile. */
+  @rec("literal:self")
   model Main {
-    @required text: string;
-    @required createdAt: datetime;
+    /** Free-form profile description.*/
+    @maxGraphemes(256)
+    description?: string;
   }
 }

packages/cli/test/scenarios/parent-lexicons/expected1/app/typelex/main.tsp

···
 import "@typelex/emitter";
 import "./externals.tsp";
 
-namespace com.myapp.post {
-  @rec("tid")
+namespace com.myapp.example.profile {
+  /** My profile. */
+  @rec("literal:self")
   model Main {
-    @required text: string;
-    @required createdAt: datetime;
+    /** Free-form profile description.*/
+    @maxGraphemes(256)
+    description?: string;
   }
 }

packages/cli/test/scenarios/parent-lexicons/expected1/lexicons/com/myapp/example/profile.json

···
+{
+  "lexicon": 1,
+  "id": "com.myapp.example.profile",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "literal:self",
+      "record": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "maxGraphemes": 256,
+            "description": "Free-form profile description."
+          }
+        }
+      },
+      "description": "My profile."
+    }
+  }
+}

packages/cli/test/scenarios/parent-lexicons/expected1/lexicons/com/myapp/post.json

···
-{
-  "lexicon": 1,
-  "id": "com.myapp.post",
-  "defs": {
-    "main": {
-      "type": "record",
-      "key": "tid",
-      "record": {
-        "type": "object",
-        "properties": {
-          "text": {
-            "type": "string"
-          },
-          "createdAt": {
-            "type": "string",
-            "format": "datetime"
-          }
-        },
-        "required": [
-          "text",
-          "createdAt"
-        ]
-      }
-    }
-  }
-}

packages/cli/test/scenarios/parent-lexicons/expected2/app/typelex/main.tsp

···
 import "@typelex/emitter";
 import "./externals.tsp";
 
-namespace com.myapp.post {
-  @rec("tid")
+namespace com.myapp.example.profile {
+  /** My profile. */
+  @rec("literal:self")
   model Main {
-    @required text: string;
+    /** Free-form profile description.*/
+    @maxGraphemes(256)
+    description?: string;
     labels?: com.atproto.label.defs.SelfLabels;
   }
 }

packages/cli/test/scenarios/parent-lexicons/expected2/lexicons/com/myapp/example/profile.json

···
+{
+  "lexicon": 1,
+  "id": "com.myapp.example.profile",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "literal:self",
+      "record": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "maxGraphemes": 256,
+            "description": "Free-form profile description."
+          },
+          "labels": {
+            "type": "ref",
+            "ref": "com.atproto.label.defs#selfLabels"
+          }
+        }
+      },
+      "description": "My profile."
+    }
+  }
+}

packages/cli/test/scenarios/parent-lexicons/expected2/lexicons/com/myapp/post.json

···
-{
-  "lexicon": 1,
-  "id": "com.myapp.post",
-  "defs": {
-    "main": {
-      "type": "record",
-      "key": "tid",
-      "record": {
-        "type": "object",
-        "properties": {
-          "text": {
-            "type": "string"
-          },
-          "labels": {
-            "type": "ref",
-            "ref": "com.atproto.label.defs#selfLabels"
-          }
-        },
-        "required": [
-          "text"
-        ]
-      }
-    }
-  }
-}

packages/cli/test/scenarios/parent-lexicons/test.ts

···
 
   await project.init("com.myapp.*", { cwd: appDir });
 
+  // Verify init generated externals.tsp with existing external lexicons (before build)
+  const externals = await project.readFile("app/typelex/externals.tsp");
+  if (!externals.includes("com.atproto.label.defs")) {
+    throw new Error(
+      "externals.tsp should contain external lexicons after init",
+    );
+  }
+
   // Verify init created a working project with default main.tsp
   await project.runBuildScript({ cwd: appDir });
   await project.compareTo("expected1");
 
-  // Edit main.tsp to add a post schema with labels (simulates user editing the file)
-  await project.writeFile("app/typelex/main.tsp", `import "@typelex/emitter";
+  // Edit main.tsp to add labels (simulates user editing the file)
+  await project.writeFile(
+    "app/typelex/main.tsp",
+    `import "@typelex/emitter";
 import "./externals.tsp";
 
-namespace com.myapp.post {
-  @rec("tid")
+namespace com.myapp.example.profile {
+  /** My profile. */
+  @rec("literal:self")
   model Main {
-    @required text: string;
+    /** Free-form profile description.*/
+    @maxGraphemes(256)
+    description?: string;
     labels?: com.atproto.label.defs.SelfLabels;
   }
 }
-`);
+`,
+  );
 
   await project.runBuildScript({ cwd: appDir });
   await project.compareTo("expected2");

packages/cli/test/scenarios/with-external-lexicons/expected1/lexicons/com/myapp/example/profile.json

···
+{
+  "lexicon": 1,
+  "id": "com.myapp.example.profile",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "literal:self",
+      "record": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "maxGraphemes": 256,
+            "description": "Free-form profile description."
+          }
+        }
+      },
+      "description": "My profile."
+    }
+  }
+}

packages/cli/test/scenarios/with-external-lexicons/expected1/lexicons/com/myapp/post.json

···
-{
-  "lexicon": 1,
-  "id": "com.myapp.post",
-  "defs": {
-    "main": {
-      "type": "record",
-      "key": "tid",
-      "record": {
-        "type": "object",
-        "properties": {
-          "text": {
-            "type": "string"
-          },
-          "createdAt": {
-            "type": "string",
-            "format": "datetime"
-          }
-        },
-        "required": [
-          "text",
-          "createdAt"
-        ]
-      }
-    }
-  }
-}

packages/cli/test/scenarios/with-external-lexicons/expected1/typelex/main.tsp

···
 import "@typelex/emitter";
 import "./externals.tsp";
 
-namespace com.myapp.post {
-  @rec("tid")
+namespace com.myapp.example.profile {
+  /** My profile. */
+  @rec("literal:self")
   model Main {
-    @required text: string;
-    @required createdAt: datetime;
+    /** Free-form profile description.*/
+    @maxGraphemes(256)
+    description?: string;
   }
 }

packages/cli/test/scenarios/with-external-lexicons/test.ts

···
 export async function run(project) {
   await project.init("com.myapp.*");
 
+  // Verify init generated externals.tsp with existing external lexicons (before build)
+  const externals = await project.readFile("typelex/externals.tsp");
+  if (!externals.includes("com.atproto.label.defs")) {
+    throw new Error("externals.tsp should contain external lexicons after init");
+  }
+
   // Verify init created a working project with default main.tsp
   await project.runBuildScript();
   await project.compareTo("expected1");

packages/website/src/components/CodeBlock.astro

···
+---
+import { highlightCode } from '../utils/shiki';
+
+interface Props {
+  lang: 'typespec' | 'json' | 'bash';
+  code?: string;
+}
+
+const { lang, code } = Astro.props;
+const codeContent = code || await Astro.slots.render('default');
+const highlighted = await highlightCode(codeContent.trim(), lang);
+---
+
+<pre set:html={highlighted} />

packages/website/src/components/ComparisonBlock.astro

···
+---
+import { highlightCode } from '../utils/shiki';
+import { compileToJson } from '../utils/compile';
+import { createPlaygroundUrl } from '../utils/playground-url';
+import stringify from 'json-stringify-pretty-compact';
+import { mkdtempSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+interface Props {
+  code: string;
+}
+
+const { code } = Astro.props;
+
+// Create temporary file for compilation
+const tmpDir = mkdtempSync(join(tmpdir(), 'typelex-'));
+const tmpFile = join(tmpDir, 'example.tsp');
+writeFileSync(tmpFile, code);
+
+let lexiconJson: string;
+let lexicon: string;
+
+try {
+  lexiconJson = await compileToJson(tmpFile);
+  lexicon = stringify(JSON.parse(lexiconJson), { maxLength: 80 });
+} finally {
+  rmSync(tmpDir, { recursive: true, force: true });
+}
+
+const typelexHtml = await highlightCode(code, 'typespec');
+const lexiconHtml = await highlightCode(lexicon, 'json');
+const playgroundUrl = createPlaygroundUrl(code);
+---
+
+<div class="comparison">
+  <div class="comparison-content">
+    <div class="code-panel">
+      <p class="code-header">
+        Typelex
+        <a href={playgroundUrl} target="_blank" rel="noopener noreferrer" class="code-playground-link" aria-label="Open in playground">
+          <svg width="14" height="14" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+            <path d="M6.5 3.5C6.5 3.22386 6.72386 3 7 3H13C13.2761 3 13.5 3.22386 13.5 3.5V9.5C13.5 9.77614 13.2761 10 13 10C12.7239 10 12.5 9.77614 12.5 9.5V4.70711L6.85355 10.3536C6.65829 10.5488 6.34171 10.5488 6.14645 10.3536C5.95118 10.1583 5.95118 9.84171 6.14645 9.64645L11.7929 4H7C6.72386 4 6.5 3.77614 6.5 3.5Z" fill="currentColor"/>
+            <path d="M3 5.5C3 4.67157 3.67157 4 4.5 4H5C5.27614 4 5.5 4.22386 5.5 4.5C5.5 4.77614 5.27614 5 5 5H4.5C4.22386 5 4 5.22386 4 5.5V11.5C4 11.7761 4.22386 12 4.5 12H10.5C10.7761 12 11 11.7761 11 11.5V11C11 10.7239 11.2239 10.5 11.5 10.5C11.7761 10.5 12 10.7239 12 11V11.5C12 12.3284 11.3284 13 10.5 13H4.5C3.67157 13 3 12.3284 3 11.5V5.5Z" fill="currentColor"/>
+          </svg>
+        </a>
+      </p>
+      <div class="code-block" set:html={typelexHtml} />
+    </div>
+    <div class="code-panel">
+      <p class="code-header">
+        Lexicon
+      </p>
+      <div class="code-block" set:html={lexiconHtml} />
+    </div>
+  </div>
+</div>

packages/website/src/layouts/BaseLayout.astro

···
+---
+interface Props {
+  title: string;
+  description?: string;
+  transparentNav?: boolean;
+}
+
+const {
+  title,
+  description = "An experimental TypeSpec syntax for AT Protocol Lexicons. Write Lexicons in a more readable syntax using TypeSpec.",
+  transparentNav = false
+} = Astro.props;
+---
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="generator" content={Astro.generator} />
+    <title>{title}</title>
+    <meta name="description" content={description} />
+
+    <!-- Open Graph / Facebook -->
+    <meta property="og:type" content="website" />
+    <meta property="og:url" content="https://typelex.org/" />
+    <meta property="og:title" content={title} />
+    <meta property="og:description" content={description} />
+    <meta property="og:image" content="https://typelex.org/og.png" />
+
+    <!-- Twitter -->
+    <meta property="twitter:card" content="summary_large_image" />
+    <meta property="twitter:url" content="https://typelex.org/" />
+    <meta property="twitter:title" content={title} />
+    <meta property="twitter:description" content={description} />
+    <meta property="twitter:image" content="https://typelex.org/og.png" />
+  </head>
+  <body>
+    <nav class:list={["top-nav", { transparent: transparentNav }]}>
+      <div class="nav-container">
+        <a href="/" class="logo">typelex</a>
+        <div class="nav-links">
+          <a href="#install">Install</a>
+          <a href="https://tangled.org/@danabra.mov/typelex/blob/main/DOCS.md" target="_blank" rel="noopener noreferrer">Docs</a>
+          <a href="https://playground.typelex.org" target="_blank" rel="noopener noreferrer">Playground</a>
+        </div>
+      </div>
+    </nav>
+
+    <slot />
+
+    {transparentNav && (
+      <script>
+        const nav = document.querySelector('.top-nav');
+        const heroTitle = document.querySelector('header h1');
+
+        if (heroTitle && nav) {
+          const handleScroll = () => {
+            const titleRect = heroTitle.getBoundingClientRect();
+
+            if (titleRect.bottom < 0) {
+              nav.classList.remove('transparent');
+            } else {
+              nav.classList.add('transparent');
+            }
+          };
+
+          window.addEventListener('scroll', handleScroll, { passive: true });
+          handleScroll();
+        }
+      </script>
+    )}
+  </body>
+</html>
+
+<style is:global>
+  * {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+  }
+
+  html {
+    scroll-behavior: smooth;
+  }
+
+  body {
+    font-family: system-ui, -apple-system, sans-serif;
+    line-height: 1.6;
+    color: #1e293b;
+    background: #f8fafc;
+    font-size: 16px;
+  }
+
+  @media (min-width: 768px) {
+    body {
+      font-size: 17px;
+    }
+  }
+
+  .top-nav {
+    position: sticky;
+    top: 0;
+    z-index: 100;
+    background: rgba(255, 255, 255, 0.8);
+    backdrop-filter: blur(10px);
+    border-bottom: 1px solid #e2e8f0;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
+    transition: all 0.3s ease;
+  }
+
+  .top-nav.transparent {
+    background: rgba(255, 255, 255, 0);
+    backdrop-filter: none;
+    border-bottom-color: transparent;
+    box-shadow: none;
+  }
+
+  .top-nav.transparent .logo {
+    opacity: 0;
+    transform: translateY(-100%);
+  }
+
+  .top-nav.transparent .nav-links a {
+    opacity: 0.7;
+  }
+
+  .nav-container {
+    max-width: 1104px;
+    margin: 0 auto;
+    padding: 1rem 2rem;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+
+  @media (min-width: 768px) {
+    .nav-container {
+      padding: 1rem 2rem;
+    }
+  }
+
+  .logo {
+    font-size: 1.25rem;
+    font-weight: 800;
+    background: linear-gradient(90deg, #4a9eff 0%, #7a8ef7 40%, #ff85c1 70%, #9b7ef7 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+    text-decoration: none;
+    transition: all 0.3s ease;
+  }
+
+  .nav-links {
+    display: flex;
+    gap: 1.5rem;
+    align-items: center;
+  }
+
+  .nav-links a {
+    color: #64748b;
+    text-decoration: none;
+    font-weight: 500;
+    transition: all 0.3s ease;
+    font-size: 0.9375rem;
+  }
+
+  .nav-links a:hover {
+    color: #7a8ef7;
+  }
+</style>

packages/website/src/layouts/DocsLayout.astro

···
+---
+import BaseLayout from './BaseLayout.astro';
+
+interface Props {
+  title: string;
+}
+
+const { title } = Astro.props;
+---
+
+<BaseLayout title={`${title} – typelex`}>
+  <div class="docs-container">
+      <aside class="sidebar">
+        <div class="sidebar-content">
+          <h3>Documentation</h3>
+          <nav class="sidebar-nav">
+            <a href="/docs" class:list={[{ active: Astro.url.pathname === '/docs' || Astro.url.pathname === '/docs/' }]}>Introduction</a>
+          </nav>
+        </div>
+      </aside>
+
+      <main class="docs-main">
+        <article class="docs-content">
+          <h1>{title}</h1>
+          <slot />
+        </article>
+      </main>
+    </div>
+
+  <script>
+    document.addEventListener('DOMContentLoaded', () => {
+      const scrollables = document.querySelectorAll('.code-panel:last-child .code-block');
+
+      // Update gradient mask based on scroll position
+      scrollables.forEach(block => {
+        const updateMask = () => {
+          const isAtBottom = block.scrollHeight - block.scrollTop <= block.clientHeight + 5;
+          if (isAtBottom) {
+            block.style.maskImage = 'none';
+            block.style.webkitMaskImage = 'none';
+          } else {
+            block.style.maskImage = 'linear-gradient(to bottom, black calc(100% - 150px), transparent 100%)';
+            block.style.webkitMaskImage = 'linear-gradient(to bottom, black calc(100% - 150px), transparent 100%)';
+          }
+        };
+
+        block.addEventListener('scroll', updateMask);
+        updateMask(); // Initial check
+      });
+
+      // Freeze inner scrollable blocks while scrolling the page
+      let scrollTimeout;
+      const freezeInnerScroll = () => {
+        document.body.classList.add('outer-scrolling');
+
+        clearTimeout(scrollTimeout);
+        scrollTimeout = setTimeout(() => {
+          document.body.classList.remove('outer-scrolling');
+        }, 150);
+      };
+
+      // Listen for both scroll and wheel events to catch scrolling early
+      window.addEventListener('scroll', freezeInnerScroll, { passive: true });
+      window.addEventListener('wheel', (e) => {
+        // Only freeze if the wheel event is not inside a scrollable block
+        const target = e.target;
+        const isInsideScrollable = target.closest('.code-panel:last-child .code-block');
+        if (!isInsideScrollable) {
+          freezeInnerScroll();
+        }
+      }, { passive: true });
+    });
+  </script>
+</BaseLayout>
+
+<style is:global>
+  .docs-container {
+    max-width: 1400px;
+    margin: 0 auto;
+    display: grid;
+    grid-template-columns: 250px 1fr;
+    gap: 3rem;
+    padding: 2rem 1.5rem;
+  }
+
+  @media (max-width: 968px) {
+    .docs-container {
+      grid-template-columns: 1fr;
+      gap: 2rem;
+    }
+
+    .sidebar {
+      position: static;
+      border-right: none;
+      border-bottom: 1px solid #e2e8f0;
+      padding-bottom: 2rem;
+    }
+  }
+
+  .sidebar {
+    position: sticky;
+    top: 5rem;
+    height: fit-content;
+  }
+
+  .sidebar-content h3 {
+    font-size: 0.875rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: #94a3b8;
+    margin-bottom: 1rem;
+    font-weight: 600;
+  }
+
+  .sidebar-nav {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+  }
+
+  .sidebar-nav a {
+    color: #64748b;
+    text-decoration: none;
+    padding: 0.5rem 0.75rem;
+    border-radius: 6px;
+    transition: all 0.2s ease;
+    font-weight: 500;
+  }
+
+  .sidebar-nav a:hover {
+    background: #f1f5f9;
+    color: #1e293b;
+  }
+
+  .sidebar-nav a.active {
+    background: linear-gradient(135deg, #7a8ef7 0%, #9483f7 70%, #b87ed8 100%);
+    color: white;
+    font-weight: 600;
+  }
+
+  .docs-main {
+    min-width: 0;
+    max-width: 800px;
+  }
+
+  .docs-content {
+    padding-bottom: 4rem;
+  }
+
+  .docs-content h1 {
+    font-size: 2.5rem;
+    font-weight: 800;
+    margin: 0 0 2rem 0;
+    background: linear-gradient(90deg, #4a9eff 0%, #7a8ef7 40%, #ff85c1 70%, #9b7ef7 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+  }
+
+  .docs-content h2 {
+    font-size: 1.875rem;
+    font-weight: 700;
+    margin-top: 3rem;
+    margin-bottom: 1.5rem;
+    color: #1e293b;
+  }
+
+  .docs-content h3 {
+    font-size: 1.5rem;
+    font-weight: 600;
+    margin-top: 2rem;
+    margin-bottom: 1rem;
+    color: #334155;
+  }
+
+  .docs-content h4 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin-top: 1.5rem;
+    margin-bottom: 0.75rem;
+    color: #475569;
+  }
+
+  .docs-content p {
+    margin-bottom: 1.25rem;
+    line-height: 1.8;
+    color: #475569;
+  }
+
+  .docs-content a {
+    color: #6366f1;
+    text-decoration: none;
+    border-bottom: 1px solid #c7d2fe;
+    transition: all 0.2s ease;
+  }
+
+  .docs-content a:hover {
+    color: #4f46e5;
+    border-bottom-color: #6366f1;
+  }
+
+  .docs-content ul, .docs-content ol {
+    margin-bottom: 1.5rem;
+    padding-left: 2rem;
+  }
+
+  .docs-content li {
+    margin-bottom: 0.5rem;
+    line-height: 1.8;
+    color: #475569;
+  }
+
+  .docs-content code {
+    font-family: 'Monaco', 'Menlo', monospace;
+    font-size: 0.875em;
+    background: #f1f5f9;
+    padding: 0.2em 0.4em;
+    border-radius: 4px;
+    color: #e879b9;
+  }
+
+  .docs-content pre {
+    background: #1e1b29;
+    border-radius: 8px;
+    padding: 1rem;
+    overflow-x: auto;
+    margin-bottom: 1.5rem;
+  }
+
+  @media (min-width: 768px) {
+    .docs-content pre {
+      padding: 1.25rem;
+    }
+  }
+
+  .docs-content pre code {
+    background: transparent;
+    padding: 0;
+    color: inherit;
+    font-size: 0.75rem;
+    line-height: 1.6;
+  }
+
+  @media (min-width: 768px) {
+    .docs-content pre code {
+      font-size: 0.875rem;
+      line-height: 1.7;
+    }
+  }
+
+  .docs-content table {
+    width: 100%;
+    border-collapse: collapse;
+    margin-bottom: 1.5rem;
+    font-size: 0.9375rem;
+  }
+
+  .docs-content th,
+  .docs-content td {
+    text-align: left;
+    padding: 0.75rem 1rem;
+    border: 1px solid #e2e8f0;
+  }
+
+  .docs-content th {
+    background: #f8fafc;
+    font-weight: 600;
+    color: #1e293b;
+  }
+
+  .docs-content td {
+    color: #475569;
+  }
+
+  .docs-content blockquote {
+    border-left: 4px solid #7a8ef7;
+    padding-left: 1.5rem;
+    margin: 1.5rem 0;
+    color: #64748b;
+    font-style: italic;
+  }
+
+  .comparison {
+    background: #1e1b29;
+    border-radius: 12px;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+    overflow: hidden;
+    margin: 2rem 0;
+  }
+
+  .comparison-content {
+    position: relative;
+    padding: 0.75rem;
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 1.5rem;
+  }
+
+  @media (min-width: 768px) {
+    .comparison-content {
+      padding: 1rem;
+      grid-template-columns: 1fr 1fr;
+      gap: 2rem;
+    }
+  }
+
+  .code-panel {
+    position: relative;
+    min-width: 0;
+    overflow: hidden;
+    text-align: left;
+  }
+
+  .code-header {
+    padding: 0.5rem 1rem;
+    background: #252231;
+    border-radius: 8px 8px 0 0;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    margin: 0;
+    color: #94a3b8;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+
+  @media (min-width: 768px) {
+    .code-header {
+      font-size: 0.8125rem;
+      padding: 0.625rem 1rem;
+    }
+  }
+
+  .code-block {
+    position: relative;
+    text-align: left;
+  }
+
+  .code-panel:last-child .code-block {
+    overflow-y: auto;
+    max-height: 400px;
+    -webkit-mask-image: linear-gradient(to bottom, black calc(100% - 100px), transparent 100%);
+    mask-image: linear-gradient(to bottom, black calc(100% - 100px), transparent 100%);
+  }
+
+  /* Freeze inner scrollables when scrolling the page */
+  body.outer-scrolling .code-panel:last-child .code-block {
+    pointer-events: none;
+    overflow-y: hidden;
+  }
+
+  @media (min-width: 768px) {
+    .code-panel:first-child {
+      position: relative;
+      z-index: 1;
+    }
+
+    .code-panel:last-child {
+      position: absolute;
+      top: 1rem;
+      bottom: 1rem;
+      right: 1rem;
+      left: calc(50% + 1rem);
+    }
+
+    .code-panel:last-child .code-block {
+      max-height: none;
+      height: 100%;
+      padding-bottom: 1.5rem;
+      -webkit-mask-image: linear-gradient(to bottom, black calc(100% - 150px), transparent 100%);
+      mask-image: linear-gradient(to bottom, black calc(100% - 150px), transparent 100%);
+    }
+
+    body.outer-scrolling .code-panel:last-child .code-block {
+      pointer-events: none;
+      overflow-y: hidden;
+    }
+  }
+
+  .code-block pre {
+    margin: 0;
+    padding: 1rem;
+    background: transparent !important;
+    overflow-x: auto;
+    overflow-y: visible;
+    -webkit-overflow-scrolling: touch;
+    max-width: 100%;
+  }
+
+  @media (min-width: 768px) {
+    .code-block pre {
+      padding: 1.5rem;
+    }
+  }
+
+  .code-block code {
+    font-family: 'Monaco', 'Menlo', monospace;
+    font-size: 0.75rem !important;
+    line-height: 1.6;
+    white-space: pre;
+    text-align: left;
+  }
+
+  @media (min-width: 768px) {
+    .code-block code {
+      font-size: 0.875rem !important;
+    }
+  }
+
+  .code-block pre code,
+  .code-block pre code * {
+    font-size: inherit !important;
+  }
+
+  .code-playground-link {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: #94a3b8;
+    transition: all 0.2s ease;
+    text-decoration: none;
+    opacity: 0.4;
+    padding: 0.125rem;
+    border-bottom: none !important;
+  }
+
+  .code-playground-link:hover {
+    color: #c7d2fe;
+    opacity: 1;
+  }
+
+  .code-playground-link svg {
+    width: 1rem;
+    height: 1rem;
+  }
+
+  @media (min-width: 768px) {
+    .code-playground-link svg {
+      width: 1.125rem;
+      height: 1.125rem;
+    }
+  }
+</style>

packages/website/src/pages/index.astro

···
 ---
+import BaseLayout from '../layouts/BaseLayout.astro';
 import { highlightCode } from '../utils/shiki';
 import { compileToJson } from '../utils/compile';
 import { createPlaygroundUrl } from '../utils/playground-url';
···
 );
 ---
 
-<!DOCTYPE html>
-<html lang="en">
-	<head>
-		<meta charset="utf-8" />
-		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-		<meta name="viewport" content="width=device-width, initial-scale=1" />
-		<meta name="generator" content={Astro.generator} />
-		<title>typelex – An experimental TypeSpec syntax for Lexicon</title>
-		<meta name="description" content="An experimental TypeSpec syntax for AT Protocol Lexicons. Write Lexicons in a more readable syntax using TypeSpec." />
-
-		<!-- Open Graph / Facebook -->
-		<meta property="og:type" content="website" />
-		<meta property="og:url" content="https://typelex.org/" />
-		<meta property="og:title" content="typelex – An experimental TypeSpec syntax for Lexicon" />
-		<meta property="og:description" content="An experimental TypeSpec syntax for AT Protocol Lexicons. Write Lexicons in a more readable syntax using TypeSpec." />
-		<meta property="og:image" content="https://typelex.org/og.png" />
-
-		<!-- Twitter -->
-		<meta property="twitter:card" content="summary_large_image" />
-		<meta property="twitter:url" content="https://typelex.org/" />
-		<meta property="twitter:title" content="typelex – An experimental TypeSpec syntax for Lexicon" />
-		<meta property="twitter:description" content="An experimental TypeSpec syntax for AT Protocol Lexicons. Write Lexicons in a more readable syntax using TypeSpec." />
-		<meta property="twitter:image" content="https://typelex.org/og.png" />
-	</head>
-	<body>
-		<main class="container">
+<BaseLayout title="typelex – An experimental TypeSpec syntax for Lexicon" transparentNav={true}>
+	<main class="container">
 			<header>
 				<h1>typelex</h1>
 				<p class="tagline">An experimental <a href="https://typespec.io" target="_blank" rel="noopener noreferrer">TypeSpec</a> syntax for <a href="https://atproto.com/specs/lexicon" target="_blank" rel="noopener noreferrer">Lexicon</a></p>
···
 
 				<nav class="hero-actions">
 					<a href="#install" class="install-cta">Try It</a>
-					<a href="https://tangled.org/@danabra.mov/typelex/blob/main/DOCS.md" target="_blank" rel="noopener noreferrer" class="star-btn">
+					<a target="_blank" href="https://tangled.org/@danabra.mov/typelex/blob/main/DOCS.md" class="star-btn">
 						Read Docs
 					</a>
 				</nav>
···
 						<div class="step-number">0</div>
 						<div class="step-content">
 							<h3>Try the playground</h3>
-							<p class="step-description">Experiment with typelex in your browser before installing.</p>
 							<a href="https://playground.typelex.org" target="_blank" rel="noopener noreferrer" class="playground-button">
 								Open Playground
 							</a>
+							<p class="step-description">Experiment with typelex in your browser before installing.</p>
 						</div>
 					</div>
 
 					<div class="install-step">
 						<div class="step-number">1</div>
 						<div class="step-content">
-							<h3>Install packages</h3>
-							<figure class="install-box" set:html={await highlightCode('npm install -D @typespec/compiler @typelex/emitter', 'bash')} />
+							<h3>Add typelex to your app</h3>
+							<figure class="install-box" set:html={await highlightCode('npx @typelex/cli init', 'bash')} />
+							<p class="step-description">This will add a few things to your <code>package.json</code>, and create a <code>typelex/</code> folder.</p>
 						</div>
 					</div>
 
 					<div class="install-step">
 						<div class="step-number">2</div>
 						<div class="step-content">
-							<h3>Create <code>typelex/main.tsp</code></h3>
+							<h3>Write your lexicons in <code>typelex/main.tsp</code></h3>
 							<figure class="install-box install-box-with-link">
 								<a href={createPlaygroundUrl(`import "@typelex/emitter";
+import "./externals.tsp";
 
-namespace com.example.actor.profile {
+namespace com.myapp.example.profile {
   /** My profile. */
   @rec("literal:self")
   model Main {
···
 									</svg>
 								</a>
 								<div set:html={await highlightCode(`import "@typelex/emitter";
+import "./externals.tsp";
 
-namespace com.example.actor.profile {
+namespace com.myapp.example.profile {
   /** My profile. */
   @rec("literal:self")
   model Main {
···
 }`, 'typespec')} />
 							</figure>
 						</div>
-						<p class="step-description">Or grab any example Lexicon <a target=_blank href="https://playground.typelex.org/">from the Playground</a>.</p>
+						<p class="step-description">Your app's lexicons go here. They may reference any external ones from <code>lexicons/</code>.
 					</div>
 
 					<div class="install-step">
 						<div class="step-number">3</div>
 						<div class="step-content">
-							<h3>Create <code><a href="https://typespec.io/docs/handbook/configuration/configuration/" target="_blank" rel="noopener noreferrer">tspconfig.yaml</a></code></h3>
-							<figure class="install-box" set:html={await highlightCode(`emit:
-  - "@typelex/emitter"
-options:
-  "@typelex/emitter":
-    output-dir: "./lexicons"`, 'yaml')} />
+							<h3>Compile your lexicons</h3>
+							<figure class="install-box" set:html={await highlightCode(`npm run build:typelex`, 'bash')} />
+							<p class="step-description">Your app’s compiled lexicons will appear in <code>lexicons/</code> alongside any external ones.</p>
 						</div>
 					</div>
 
 					<div class="install-step">
 						<div class="step-number">4</div>
 						<div class="step-content">
-							<h3>Add a build script to <code>package.json</code></h3>
-							<figure class="install-box" set:html={await highlightCode(`{
-  "scripts": {
-    // ...
-    "build:lexicons": "tsp compile typelex/main.tsp"
-  }
-}`, 'json')} />
-						</div>
-					</div>
-
-					<div class="install-step">
-						<div class="step-number">5</div>
-						<div class="step-content">
-							<h3>Generate Lexicon files</h3>
-							<figure class="install-box" set:html={await highlightCode(`npm run build:lexicons`, 'bash')} />
-							<p class="step-description">Lexicon files will be generated in the <code>output-dir</code> from your <code>tspconfig.yaml</code> config.</p>
-						</div>
-					</div>
-
-					<div class="install-step">
-						<div class="step-number">6</div>
-						<div class="step-content">
 							<h3>Set up VS Code</h3>
 							<p class="step-description">Install the <a href="https://typespec.io/docs/introduction/editor/vscode/" target="_blank" rel="noopener noreferrer">TypeSpec for VS Code extension</a> for syntax highlighting and IntelliSense.</p>
 						</div>
 					</div>
 
 					<div class="install-step">
-						<div class="step-number">7</div>
+						<div class="step-number">5</div>
 						<div class="step-content">
-							<h3>Read the docs</h3>
+							<h3>Learn more</h3>
 							<p class="step-description">Check out the <a href="https://tangled.org/@danabra.mov/typelex/blob/main/DOCS.md" target="_blank" rel="noopener noreferrer">documentation</a> to learn more.</p>
 						</div>
 					</div>
···
 			    <p>This is my personal hobby project and is not affiliated with AT or endorsed by anyone.</p>
 			    <p>Who knows if this is a good idea?</p>
 			</footer>
-		</main>
+	</main>
 
-		<script>
+	<script>
 			document.addEventListener('DOMContentLoaded', () => {
 				const scrollables = document.querySelectorAll('.code-panel:last-child .code-block, .hero-panel:last-child .hero-code');
 
···
 					}
 				}, { passive: true });
 			});
-		</script>
-	</body>
-</html>
+	</script>
+</BaseLayout>
 
 <style is:global>
-	* {
-		margin: 0;
-		padding: 0;
-		box-sizing: border-box;
-	}
-
-	html {
-		scroll-behavior: smooth;
-	}
-
 	body {
-		font-family: system-ui, -apple-system, sans-serif;
-		line-height: 1.6;
-		color: #1e293b;
-		background: #f8fafc;
-		font-size: 16px;
 		position: relative;
 		overflow-x: hidden;
 	}
···
 		border-radius: 50%;
 		pointer-events: none;
 		z-index: 0;
-	}
-
-	@media (min-width: 768px) {
-		body {
-			font-size: 17px;
-		}
 	}
 
 	.container {
···
 
 	.playground-button {
 		display: inline-block;
-		margin-top: 1.25rem;
 		padding: 0.875rem 2rem;
 		background: linear-gradient(135deg, #7a8ef7 0%, #9483f7 70%, #b87ed8 100%);
 		color: white;