diff --git a/.husky/pre-commit b/.husky/pre-commit
old mode 100644
new mode 100755
diff --git a/BUILDING.md b/BUILDING.md
index 5e031fea..6e90c8a6 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -40,6 +40,22 @@ npm run build
 
 `scripts/build-vendor.sh` clones and builds static archives for libgc, cJSON, libuv, tree-sitter, and libwebsockets into `vendor/`. It's idempotent — re-running skips already-built libraries.
 
+## Run
+
+After building, the compiler is available as a Node.js script:
+
+```bash
+node dist/chad-node.js build hello.ts -o hello
+./hello
+```
+
+For a ~10x faster compiler, build the native binary once:
+
+```bash
+node dist/chad-node.js build src/chad-native.ts -o .build/chad
+# Now tests and scripts auto-use .build/chad instead of node dist/chad-node.js
+```
+
 ## Verify
 
 ```bash
@@ -95,11 +111,13 @@ bash scripts/build-target-sdk.sh
 
 ## Self-Hosting (Stage 0)
 
-ChadScript can compile its own compiler to a native binary:
+ChadScript can compile its own compiler to a native binary (this is what `scripts/self-hosting.sh` automates):
 
 ```bash
-chad build src/chad-native.ts -o /tmp/chad-stage0
+# Stage 0: Node.js compiler produces a native binary
+node dist/chad-node.js build src/chad-native.ts -o /tmp/chad-stage0
 
+# Stage 1: that native binary recompiles itself
 /tmp/chad-stage0 build src/chad-native.ts -o /tmp/chad-stage1
 ```
 
diff --git a/c_bridges/yyjson-bridge.c b/c_bridges/yyjson-bridge.c
index ac230206..f7393046 100644
--- a/c_bridges/yyjson-bridge.c
+++ b/c_bridges/yyjson-bridge.c
@@ -104,6 +104,20 @@ void *csyyjson_create_obj(void) {
     return (void *)doc;
 }
 
+void *csyyjson_create_arr(void) {
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    if (!doc) return NULL;
+    yyjson_mut_val *root = yyjson_mut_arr(doc);
+    if (!root) { yyjson_mut_doc_free(doc); return NULL; }
+    yyjson_mut_doc_set_root(doc, root);
+    return (void *)doc;
+}
+
+void *csyyjson_mut_arr_add_obj(void *doc, void *arr) {
+    if (!doc || !arr) return NULL;
+    return (void *)yyjson_mut_arr_add_obj((yyjson_mut_doc *)doc, (yyjson_mut_val *)arr);
+}
+
 void *csyyjson_mut_get_root(void *doc) {
     if (!doc) return NULL;
     return (void *)yyjson_mut_doc_get_root((yyjson_mut_doc *)doc);
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 1a900d3b..797473e1 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -17,13 +17,6 @@ export default defineConfig({
     languages: [llvmGrammar],
   },
 
-  transformPageData(pageData) {
-    const mdPath = path.resolve(__dirname, '..', pageData.relativePath)
-    try {
-      pageData.frontmatter.__rawMarkdown = fs.readFileSync(mdPath, 'utf-8')
-    } catch {}
-  },
-
   themeConfig: {
     search: {
       provider: 'local'
@@ -40,11 +33,11 @@ export default defineConfig({
       {
         text: 'Getting Started',
         items: [
-          { text: 'Language Support', link: '/language/limitations' },
+          { text: 'About ChadScript', link: '/language/architecture' },
           { text: 'Installation', link: '/getting-started/installation' },
           { text: 'Examples', link: '/getting-started/quickstart' },
-          { text: 'How it Works', link: '/language/architecture' },
           { text: 'CLI Reference', link: '/getting-started/cli' },
+          { text: 'Supported Features', link: '/language/limitations' },
           { text: 'Debugging', link: '/getting-started/debugging' }
         ]
       },
@@ -84,12 +77,6 @@ export default defineConfig({
           { text: 'Benchmarks', link: '/benchmarks' }
         ]
       },
-      {
-        text: 'Resources',
-        items: [
-          { text: 'FAQ', link: '/faq' }
-        ]
-      }
     ],
 
     socialLinks: [
diff --git a/docs/.vitepress/theme/CopyMarkdown.vue b/docs/.vitepress/theme/CopyMarkdown.vue
index 291cdc84..a2d7087e 100644
--- a/docs/.vitepress/theme/CopyMarkdown.vue
+++ b/docs/.vitepress/theme/CopyMarkdown.vue
@@ -1,29 +1,49 @@
+<!-- Copy-as-markdown button: lazily loads the raw .md source on click. -->
 <script setup lang="ts">
 import { ref } from 'vue'
 import { useData } from 'vitepress'
 
-const { page, frontmatter } = useData()
+const { page } = useData()
 const copied = ref(false)
 
+// Vite lazy-loads each .md as a raw string on demand (not bundled upfront)
+const markdownModules = import.meta.glob('../../**/*.md', { query: '?raw', import: 'default' }) as Record<string, () => Promise<string>>
+
 async function copyMarkdown() {
-  const raw = (frontmatter.value as any).__rawMarkdown
+  // Map page's relativePath (e.g. "getting-started/cli.md") to glob key
+  const key = `../../${page.value.relativePath}`
+  const loader = markdownModules[key]
+  if (!loader) return
+
+  const raw = await loader()
   if (!raw) return
 
-  try {
-    await navigator.clipboard.writeText(raw)
-    copied.value = true
-    setTimeout(() => { copied.value = false }, 2000)
-  } catch {
-    const textarea = document.createElement('textarea')
-    textarea.value = raw
-    document.body.appendChild(textarea)
-    textarea.select()
-    document.execCommand('copy')
-    document.body.removeChild(textarea)
-    copied.value = true
-    setTimeout(() => { copied.value = false }, 2000)
+  if (navigator.clipboard?.writeText) {
+    navigator.clipboard.writeText(raw).then(() => flash(), () => fallbackCopy(raw))
+  } else {
+    fallbackCopy(raw)
   }
 }
+
+function fallbackCopy(text: string) {
+  const ta = document.createElement('textarea')
+  ta.value = text
+  ta.style.position = 'fixed'
+  ta.style.left = '-9999px'
+  ta.style.top = '-9999px'
+  ta.style.opacity = '0'
+  document.body.appendChild(ta)
+  ta.focus()
+  ta.select()
+  document.execCommand('copy')
+  document.body.removeChild(ta)
+  flash()
+}
+
+function flash() {
+  copied.value = true
+  setTimeout(() => { copied.value = false }, 2000)
+}
 </script>
 
 <template>
diff --git a/docs/.vitepress/theme/ExampleTabs.vue b/docs/.vitepress/theme/ExampleTabs.vue
index 5c9b27a3..1ef0381d 100644
--- a/docs/.vitepress/theme/ExampleTabs.vue
+++ b/docs/.vitepress/theme/ExampleTabs.vue
@@ -19,9 +19,18 @@ const examples = [
   {
     label: 'HTTP Server',
     file: 'server.ts',
-    code: `ChadScript.embedDir("./public");
+    code: `// Static files baked into the binary at compile time
+ChadScript.embedDir("./public");
+
+const posts = [{ id: 1, title: "Hello World", likes: 42 }];
 
 function handleRequest(req: HttpRequest): HttpResponse {
+  // JSON REST API
+  if (req.path === "/api/posts") {
+    return { status: 200, body: JSON.stringify(posts), headers: "" };
+  }
+  // Fallback: serve embedded static files (.html, .css, etc.)
+  // Content-Type is inferred from the file extension
   return ChadScript.serveEmbedded(req.path);
 }
 
@@ -57,18 +66,18 @@ sqlite.close(db);`,
 
 async function main() {
   const results = await Promise.all([
-    fetch("https://api.github.com/repos/cs01/ChadScript"),
+    fetch("https://api.github.com/repos/vuejs/vue"),
     fetch("https://api.github.com/repos/facebook/react"),
   ]);
-  const cs = JSON.parse<Repo>(results[0].text());
+  const vue = JSON.parse<Repo>(results[0].text());
   const react = JSON.parse<Repo>(results[1].text());
-  console.log("ChadScript: " + cs.stargazers_count + " stars");
+  console.log("Vue: " + vue.stargazers_count + " stars");
   console.log("React: " + react.stargazers_count + " stars");
 }
 
 main();`,
     run: '$ chad run stars.ts',
-    output: `ChadScript: mass stars\nReact: 235k stars`,
+    output: `Vue: 208k stars\nReact: 235k stars`,
   },
 ]
 
diff --git a/docs/.vitepress/theme/IRShowcase.vue b/docs/.vitepress/theme/IRShowcase.vue
index bfcbb4db..5c1056f4 100644
--- a/docs/.vitepress/theme/IRShowcase.vue
+++ b/docs/.vitepress/theme/IRShowcase.vue
@@ -1,77 +1,24 @@
+<!-- Single-terminal animation showing the full ChadScript build-and-run flow.
+     One terminal accumulates: echo > file, chad build, ./hello.
+     Linking indicator appears between build and run steps.
+     Hex button drives the two user interactions (Build, Run). -->
 <script setup lang="ts">
 import { ref, computed, onMounted, onUnmounted, nextTick } from 'vue'
 
 const containerRef = ref<HTMLElement | null>(null)
-const phase = ref<'idle' | 'typing-source' | 'typing-build' | 'ready-compile' | 'compiling' | 'typing-run' | 'ready-run' | 'running' | 'done'>('idle')
+const phase = ref<'idle' | 'typing-echo' | 'typing-build' | 'ready-compile' | 'compiling' | 'typing-run' | 'ready-run' | 'running' | 'done'>('idle')
 
-const sourceText = ref('')
+const echoCmd = ref('')
 const buildCmd = ref('')
 const runCmd = ref('')
-const irVisibleCount = ref(0)
 const linkingState = ref<'idle' | 'linking' | 'done'>('idle')
 const execOutput = ref('')
 const execTime = ref('')
 
-const fullSource = 'console.log("Hello from ChadScript!");'
+const fullEchoCmd = "echo 'console.log(\"Hello from ChadScript!\")' > hello.ts"
 const fullBuildCmd = 'chad build hello.ts'
 const fullRunCmd = './hello'
 
-const irLines = [
-  '@.str.0 = private constant [24 x i8] c"Hello from ChadScript!\\0A\\00"',
-  '',
-  'declare i32 @printf(i8*, ...)',
-  '',
-  'define i32 @main(i32 %argc, i8** %argv) {',
-  'entry:',
-  '  %0 = getelementptr [24 x i8], [24 x i8]* @.str.0, i64 0, i64 0',
-  '  call i32 @printf(i8* %0)',
-  '  ret i32 0',
-  '}',
-]
-
-const irKeywords = new Set([
-  'define', 'declare', 'global', 'constant', 'private', 'internal',
-  'external', 'unnamed_addr', 'align', 'to', 'nuw', 'nsw',
-])
-
-const irInstructions = new Set([
-  'ret', 'br', 'call', 'alloca', 'load', 'store', 'getelementptr',
-  'add', 'sub', 'mul', 'icmp', 'fcmp', 'phi', 'select',
-  'trunc', 'zext', 'sext', 'bitcast', 'ptrtoint', 'inttoptr',
-])
-
-const irTypes = new Set([
-  'i1', 'i8', 'i16', 'i32', 'i64', 'i128', 'float', 'double', 'void', 'ptr',
-])
-
-function highlightIR(line: string): string {
-  const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-
-  if (line === '') return ''
-
-  if (/^[a-zA-Z_]\w*:$/.test(line.trim())) {
-    return `<span class="ir-label">${esc(line)}</span>`
-  }
-
-  return line.replace(
-    /(;[^\n]*)|(c"[^"]*"|"[^"]*")|(@[a-zA-Z$._][\w$.]*)|(%[a-zA-Z$._][\w$.]*|%\d+)|(\b-?\d+\b)|(\b[a-zA-Z_]\w*\b)/g,
-    (match, comment, str, global, local, num, word) => {
-      if (comment) return `<span class="ir-comment">${esc(comment)}</span>`
-      if (str) return `<span class="ir-string">${esc(str)}</span>`
-      if (global) return `<span class="ir-global">${esc(global)}</span>`
-      if (local) return `<span class="ir-local">${esc(local)}</span>`
-      if (num !== undefined && num !== '') return `<span class="ir-number">${esc(num)}</span>`
-      if (word) {
-        if (irKeywords.has(word)) return `<span class="ir-keyword">${esc(word)}</span>`
-        if (irInstructions.has(word)) return `<span class="ir-instr">${esc(word)}</span>`
-        if (irTypes.has(word)) return `<span class="ir-type">${esc(word)}</span>`
-      }
-      return esc(match)
-    }
-  )
-}
-
-const highlightedIR = computed(() => irLines.map(highlightIR))
 
 const hexVisible = computed(() =>
   phase.value === 'ready-compile' || phase.value === 'compiling' ||
@@ -109,6 +56,16 @@ const hexHint = computed(() => {
   }
 })
 
+// Which command lines are visible (accumulated in one terminal)
+const showEcho = computed(() => phase.value !== 'idle')
+const showBuild = computed(() =>
+  phase.value !== 'idle' && phase.value !== 'typing-echo'
+)
+const showRun = computed(() =>
+  phase.value === 'typing-run' || phase.value === 'ready-run' ||
+  phase.value === 'running' || phase.value === 'done'
+)
+
 let observer: IntersectionObserver | null = null
 let timeouts: ReturnType<typeof setTimeout>[] = []
 let started = false
@@ -140,11 +97,14 @@ function typewriter(target: { value: string }, text: string, speed: number): Pro
 async function startTyping() {
   if (started) return
   started = true
-  phase.value = 'typing-source'
+
+  // Type the echo command first
+  phase.value = 'typing-echo'
   await delay(300)
-  await typewriter(sourceText, fullSource, 35)
+  await typewriter(echoCmd, fullEchoCmd, 25)
   await delay(400)
 
+  // Then the build command
   phase.value = 'typing-build'
   await delay(200)
   await typewriter(buildCmd, fullBuildCmd, 40)
@@ -161,17 +121,12 @@ async function compile() {
   phase.value = 'compiling'
 
   await delay(400)
-  for (let i = 0; i < irLines.length; i++) {
-    irVisibleCount.value = i + 1
-    await delay(irLines[i] === '' ? 20 : 80)
-  }
-  await delay(300)
-
   linkingState.value = 'linking'
   await delay(1200)
   linkingState.value = 'done'
   await delay(500)
 
+  // Type run command in the same terminal
   phase.value = 'typing-run'
   await delay(300)
   await typewriter(runCmd, fullRunCmd, 50)
@@ -217,46 +172,42 @@ onUnmounted(() => {
 
     <div class="pipeline-panel" :class="{ visible: phase !== 'idle' }">
 
-      <div class="stage-source" v-if="phase !== 'idle'">
-        <div class="panel-header">
-          <span class="window-dots"><span class="dot red"></span><span class="dot yellow"></span><span class="dot green"></span></span>
-          <span class="panel-label">hello.ts</span>
-        </div>
-        <pre class="panel-code"><code>console.log(<span class="hl-string">"Hello from ChadScript!"</span>)<span v-if="sourceText.length < fullSource.length && phase === 'typing-source'" class="cursor">|</span></code></pre>
-        <div
-          class="code-mask"
-          :style="{ width: (100 - (sourceText.length / fullSource.length) * 100) + '%' }"
-        ></div>
-      </div>
-
+      <!-- Single terminal for all commands -->
       <div
         class="terminal-section"
-        :class="{ visible: phase !== 'idle' && phase !== 'typing-source' }"
+        :class="{ visible: phase !== 'idle' }"
       >
         <div class="terminal-chrome"><span class="window-dots"><span class="dot red"></span><span class="dot yellow"></span><span class="dot green"></span></span><span class="terminal-label">Terminal</span></div>
         <div class="terminal-body">
-          <div class="terminal-line">
+          <!-- echo command -->
+          <div v-if="showEcho" class="terminal-line">
+            <span class="terminal-prompt">$</span>
+            <span class="terminal-text">{{ echoCmd }}</span>
+            <span v-if="phase === 'typing-echo'" class="cursor">|</span>
+          </div>
+          <!-- build command -->
+          <div v-if="showBuild" class="terminal-line">
             <span class="terminal-prompt">$</span>
             <span class="terminal-text">{{ buildCmd }}</span>
             <span v-if="(phase === 'typing-build' || phase === 'ready-compile') && buildCmd.length <= fullBuildCmd.length" class="cursor">|</span>
           </div>
+          <!-- run command -->
+          <div v-if="showRun" class="terminal-line">
+            <span class="terminal-prompt">$</span>
+            <span class="terminal-text">{{ runCmd }}</span>
+            <span v-if="(phase === 'typing-run' || phase === 'ready-run') && runCmd.length <= fullRunCmd.length" class="cursor">|</span>
+          </div>
+          <!-- execution output -->
+          <div v-if="execOutput" class="terminal-line terminal-output">
+            {{ execOutput }}
+          </div>
+          <div v-if="execTime" class="timing-text">
+            completed in {{ execTime }}
+          </div>
         </div>
       </div>
 
-      <div class="stage-ir" :class="{ visible: irVisibleCount > 0 }">
-        <div class="panel-header">
-          <span class="window-dots"><span class="dot red"></span><span class="dot yellow"></span><span class="dot green"></span></span>
-          <span class="panel-label">LLVM IR</span>
-          <span v-if="irVisibleCount >= irLines.length" class="ir-badge">generated</span>
-        </div>
-        <pre class="panel-code ir-code"><code><template v-for="(line, i) in irLines" :key="i"><span
-          v-if="i < irVisibleCount"
-          class="ir-line"
-          :class="{ 'ir-entering': i === irVisibleCount - 1 }"
-        ><template v-if="line === ''">
-</template><span v-else v-html="highlightedIR[i] + '\n'"></span></span></template></code></pre>
-      </div>
-
+      <!-- Linking indicator -->
       <div class="stage-link" :class="{ visible: linkingState !== 'idle' }">
         <div class="terminal-line">
           <span v-if="linkingState === 'linking'" class="link-row">
@@ -265,31 +216,12 @@ onUnmounted(() => {
           </span>
           <span v-else-if="linkingState === 'done'" class="link-row">
             <span class="checkmark">✓</span>
-            <span class="link-text">hello: ELF 64-bit LSB executable, x86-64 (42 KB)</span>
+            <span class="link-text">.build/hello: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, stripped</span>
           </span>
         </div>
       </div>
 
-      <div
-        class="terminal-section"
-        :class="{ visible: phase === 'typing-run' || phase === 'ready-run' || phase === 'running' || phase === 'done' }"
-      >
-        <div class="terminal-chrome"><span class="window-dots"><span class="dot red"></span><span class="dot yellow"></span><span class="dot green"></span></span><span class="terminal-label">Terminal</span></div>
-        <div class="terminal-body">
-          <div class="terminal-line">
-            <span class="terminal-prompt">$</span>
-            <span class="terminal-text">{{ runCmd }}</span>
-            <span v-if="(phase === 'typing-run' || phase === 'ready-run') && runCmd.length <= fullRunCmd.length" class="cursor">|</span>
-          </div>
-          <div v-if="execOutput" class="terminal-line terminal-output">
-            {{ execOutput }}
-          </div>
-          <div v-if="execTime" class="timing-text">
-            completed in {{ execTime }}
-          </div>
-        </div>
-      </div>
-
+      <!-- Hex button -->
       <div class="hex-section" :class="{ visible: hexVisible }">
         <div class="hex-prompt" :class="{ active: hexActive, spinning: phase === 'compiling' || phase === 'running' }" @click="hexClick">
           <div class="hex-container">
@@ -305,6 +237,7 @@ onUnmounted(() => {
         </div>
       </div>
 
+      <!-- CTA after completion -->
       <div class="cta-section" :class="{ visible: ctaVisible }">
         <p class="cta-tagline">Congratulations, you wrote your first ChadScript app!</p>
         <div class="cta-buttons">
@@ -357,15 +290,6 @@ onUnmounted(() => {
   transform: translateY(0);
 }
 
-.panel-header {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 7px 16px;
-  background: rgba(255, 255, 255, 0.03);
-  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
-}
-
 .window-dots {
   display: flex;
   gap: 6px;
@@ -382,48 +306,6 @@ onUnmounted(() => {
 .dot.yellow { background: #b89530; }
 .dot.green { background: #2a9a38; }
 
-.panel-label {
-  font-size: 0.8rem;
-  font-weight: 600;
-  color: var(--vp-c-text-2);
-  font-family: var(--vp-font-family-mono);
-}
-
-.panel-code {
-  margin: 0;
-  padding: 10px 16px;
-  font-size: 0.82rem;
-  line-height: 1.5;
-  overflow-x: auto;
-  background: transparent;
-}
-
-.panel-code code {
-  font-family: var(--vp-font-family-mono);
-  color: var(--vp-c-text-1);
-  background: none;
-}
-
-.stage-source {
-  position: relative;
-  border-radius: 10px;
-  border: 1px solid rgba(255, 255, 255, 0.08);
-  background: var(--vp-c-bg-soft);
-  overflow: hidden;
-}
-
-.code-mask {
-  position: absolute;
-  top: 36px;
-  right: 0;
-  bottom: 0;
-  background: var(--vp-c-bg-soft);
-  pointer-events: none;
-  transition: width 0.02s linear;
-}
-
-.hl-string { color: #a5d6a7; }
-
 .cursor {
   color: var(--vp-c-brand-1);
   animation: blink 0.6s step-end infinite;
@@ -439,15 +321,12 @@ onUnmounted(() => {
   border-radius: 10px;
   border: 1px solid rgba(255, 255, 255, 0.08);
   opacity: 0;
-  max-height: 0;
   overflow: hidden;
-  transition: opacity 0.3s ease, max-height 0.3s ease, margin 0.3s ease;
+  transition: opacity 0.3s ease;
 }
 
 .terminal-section.visible {
   opacity: 1;
-  max-height: 200px;
-  margin-top: 8px;
 }
 
 .terminal-chrome {
@@ -662,65 +541,6 @@ onUnmounted(() => {
   color: var(--vp-c-text-1);
 }
 
-.stage-ir {
-  border-radius: 10px;
-  border: 1px solid rgba(255, 255, 255, 0.08);
-  background: var(--vp-c-bg-soft);
-  opacity: 0;
-  max-height: 0;
-  overflow: hidden;
-  transition: opacity 0.3s ease, max-height 0.5s ease, margin 0.3s ease;
-}
-
-.stage-ir.visible {
-  opacity: 1;
-  max-height: 500px;
-  margin-top: 8px;
-}
-
-.ir-code {
-  font-size: 0.75rem;
-  line-height: 1.6;
-  color: var(--vp-c-text-2);
-}
-
-.ir-code :deep(.ir-keyword) { color: #c678dd; }
-.ir-code :deep(.ir-instr) { color: #61afef; }
-.ir-code :deep(.ir-type) { color: #e5c07b; }
-.ir-code :deep(.ir-global) { color: #98c379; }
-.ir-code :deep(.ir-local) { color: #d19a66; }
-.ir-code :deep(.ir-string) { color: #98c379; }
-.ir-code :deep(.ir-number) { color: #d19a66; }
-.ir-code :deep(.ir-comment) { color: #5c6370; font-style: italic; }
-.ir-code :deep(.ir-label) { color: #e5c07b; }
-
-.ir-line {
-  display: block;
-  opacity: 1;
-}
-
-.ir-line.ir-entering {
-  animation: ir-slide-in 0.15s ease-out;
-}
-
-@keyframes ir-slide-in {
-  from {
-    opacity: 0;
-    transform: translateY(6px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-.ir-badge {
-  margin-left: auto;
-  font-size: 0.7rem;
-  color: var(--vp-c-text-3);
-  font-family: var(--vp-font-family-mono);
-  animation: fade-in 0.3s ease;
-}
 
 .stage-link {
   padding: 8px 16px;
@@ -789,12 +609,8 @@ onUnmounted(() => {
     padding: 0 16px;
   }
 
-  .panel-code {
-    font-size: 0.75rem;
-  }
-
-  .ir-code {
-    font-size: 0.68rem;
+  .terminal-line {
+    font-size: 0.72rem;
   }
 }
 </style>
diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
index 643f6cd5..3b6b6afb 100644
--- a/docs/.vitepress/theme/style.css
+++ b/docs/.vitepress/theme/style.css
@@ -13,6 +13,8 @@
 
 .copy-markdown-btn {
   float: right;
+  position: relative;
+  z-index: 10;
   margin-top: 8px;
   padding: 6px 12px;
   font-size: 13px;
@@ -35,9 +37,12 @@
   border-color: #22c55e;
 }
 
-@media (max-width: 1280px) {
+@media (max-width: 768px) {
   .copy-markdown-btn {
-    display: none;
+    float: none;
+    display: block;
+    width: fit-content;
+    margin: 8px 0 0 auto;
   }
 }
 
diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md
index c3077a16..fed7215d 100644
--- a/docs/getting-started/cli.md
+++ b/docs/getting-started/cli.md
@@ -1,11 +1,11 @@
 # CLI Reference
 
-## Commands
-
 ```
 chad <command> [options] <file>
 ```
 
+## Commands
+
 ### `chad build <file>`
 
 Compile a TypeScript file to a native binary.
@@ -25,15 +25,20 @@ chad run hello.ts
 chad run hello.ts -- arg1 arg2   # Pass arguments to the program
 ```
 
-### `chad ir <file>`
+### `chad watch <file>`
 
-Emit LLVM IR without compiling to a binary. Useful for debugging codegen.
+Watch a source file for changes and automatically recompile + re-run. Uses `inotify` on Linux and `kqueue` on macOS for event-based change detection.
 
 ```bash
-chad ir hello.ts                 # Prints LLVM IR to stdout
-chad ir hello.ts > hello.ll      # Save to file
+chad watch server.ts            # Recompiles and re-runs on every save
 ```
 
+- On file change: kills the running process, recompiles, re-runs
+- Compile errors don't crash the loop — keeps watching
+- Ctrl+C exits cleanly (kills child process)
+
+## Project
+
 ### `chad init`
 
 Generate type definitions and a starter project in the current directory.
@@ -44,24 +49,23 @@ chad init
 
 Creates `chadscript.d.ts` (type declarations for editor support), `tsconfig.json`, and `hello.ts`. Run this once per project so your editor knows about ChadScript's built-in APIs.
 
-### `chad watch <file>`
+### `chad clean`
 
-Watch a source file for changes and automatically recompile + re-run. Uses `inotify` on Linux and `kqueue` on macOS for event-based change detection.
+Remove the `.build` directory.
 
 ```bash
-chad watch server.ts            # Recompiles and re-runs on every save
+chad clean
 ```
 
-- On file change: kills the running process, recompiles, re-runs
-- Compile errors don't crash the loop — keeps watching
-- Ctrl+C exits cleanly (kills child process)
+## Advanced
 
-### `chad clean`
+### `chad ir <file>`
 
-Remove the `.build` directory.
+Emit LLVM IR without compiling to a binary. Useful for debugging codegen.
 
 ```bash
-chad clean
+chad ir hello.ts                 # Prints LLVM IR to stdout
+chad ir hello.ts > hello.ll      # Save to file
 ```
 
 ### `chad target`
@@ -83,7 +87,7 @@ SDKs are installed to `~/.chadscript/targets/<name>/`.
 | `-o <output>` | Specify output file path (default: `.build/<input>`) |
 | `--target <target>` | Cross-compile for a different platform (see below) |
 | `-v`, `--verbose` | Show compilation steps |
-| `-g` | Emit DWARF debug info for source-level debugging with gdb/lldb |
+| `-g` | Emit DWARF debug info for source-level debugging with gdb/lldb (also skips stripping) |
 | `--emit-llvm`, `-S` | Output LLVM IR only (no binary) |
 | `--keep-temps` | Keep intermediate files (`.ll`, `.o`) |
 | `-fsanitize=address` | Build with AddressSanitizer (ASAN) |
@@ -126,6 +130,23 @@ When you pass `--target`, the compiler:
 |--------|--------|-------|
 | `linux-x64` | `x86_64-unknown-linux-gnu` | Static glibc binary |
 
+### Adding extra libraries
+
+The target SDK includes libgc, libuv, and yyjson, but not system libs like libsqlite3, libz, or libzstd. If your app links against these, you need to provide linux-x64 static builds and drop them into the SDK vendor directory at `~/.chadscript/targets/linux-x64/vendor/`.
+
+A convenient way to get them is to pull them from a throwaway Linux container:
+
+```bash
+podman run --rm -v ~/.chadscript/targets/linux-x64/vendor:/output:z ubuntu:22.04 bash -c "
+  apt-get update -qq &&
+  apt-get install -y -qq zlib1g-dev libzstd-dev libsqlite3-dev &&
+  cp /usr/lib/x86_64-linux-gnu/libz.a /output/ &&
+  cp /usr/lib/x86_64-linux-gnu/libzstd.a /output/ &&
+  cp /usr/lib/x86_64-linux-gnu/libsqlite3.a /output/"
+```
+
+Docker works the same way — just swap `podman` for `docker` and drop the `:z` volume flag.
+
 ### Limitations
 
 - **macOS to Linux** is the primary cross-compilation path (e.g., develop on Mac, deploy to Linux)
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 3bbb9cbc..cd682616 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -10,19 +10,20 @@ This downloads a pre-built binary for your platform and installs it to `~/.chads
 
 ## Prerequisites
 
-ChadScript compiles your TypeScript to native code via LLVM. **LLVM is the only required dependency** — everything else is bundled in the release:
+ChadScript compiles your TypeScript to native code via LLVM. The release bundles all vendor libraries (libgc, libuv, etc.) and pre-compiled C bridge objects, so **LLVM is the only required base dependency**:
 
 - **macOS**: `brew install llvm`
 - **Ubuntu/Debian**: `sudo apt install llvm clang`
 - **Fedora**: `sudo dnf install llvm clang`
 
-If your program uses certain features, you'll also need the corresponding system library installed on the machine where you compile:
+Programs that use certain features also need the corresponding system library present at compile time:
 
 | Feature | Package |
 |---------|---------|
 | `fetch()` / HTTP client | libcurl |
 | `crypto` | openssl |
 | `sqlite` | sqlite3 |
+| `httpServe()` | zlib, libzstd |
 
 **macOS Gatekeeper**: If you get a quarantine warning on the downloaded binary:
 
@@ -39,4 +40,10 @@ bash scripts/build-vendor.sh
 npm run build
 ```
 
-See [BUILDING.md](https://github.com/cs01/ChadScript/blob/main/BUILDING.md) for full instructions.
+This produces `dist/chad-node.js`. Use it directly:
+
+```bash
+node dist/chad-node.js build hello.ts -o hello
+```
+
+See [BUILDING.md](https://github.com/cs01/ChadScript/blob/main/BUILDING.md) for full instructions including native compiler setup and cross-compilation.
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 3d014ccc..eb02363e 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -8,77 +8,41 @@ console.log("Hello from ChadScript!");
 
 ```bash
 chad run hello.ts
+# or compile to a standalone binary:
+chad build hello.ts -o hello && ./hello
 ```
 
-Or compile to a standalone binary:
+## More Examples
 
-```bash
-chad build hello.ts -o hello
-./hello
-```
-
-## HTTP Server
+The [`examples/`](https://github.com/cs01/ChadScript/tree/main/examples) directory contains runnable programs covering common use cases. Clone the repo and run any of them with `chad run`:
 
-```typescript
-function handleRequest(req: HttpRequest): HttpResponse {
-  if (req.path == "/") {
-    return { status: 200, body: "<h1>Hello from ChadScript</h1>" };
-  }
-  return { status: 404, body: "Not Found" };
-}
-
-httpServe(3000, handleRequest);
-```
+| Example | Description |
+|---------|-------------|
+| [`hello.ts`](https://github.com/cs01/ChadScript/blob/main/examples/hello.ts) | Hello World — native execution, no runtime |
+| [`word-count.ts`](https://github.com/cs01/ChadScript/blob/main/examples/word-count.ts) | File line/word/char counter (like `wc`) |
+| [`parallel.ts`](https://github.com/cs01/ChadScript/blob/main/examples/parallel.ts) | Parallel HTTP fetches with `async/await` + `Promise.all` |
+| [`query.ts`](https://github.com/cs01/ChadScript/blob/main/examples/query.ts) | SQLite database operations |
+| [`http-server.ts`](https://github.com/cs01/ChadScript/blob/main/examples/http-server.ts) | HTTP server with Express-like routing |
+| [`string-search.ts`](https://github.com/cs01/ChadScript/blob/main/examples/string-search.ts) | grep-like search with colorized output |
+| [`timers.ts`](https://github.com/cs01/ChadScript/blob/main/examples/timers.ts) | `setTimeout`/`setInterval` with the libuv event loop |
+| [`cli-parser-demo.ts`](https://github.com/cs01/ChadScript/blob/main/examples/cli-parser-demo.ts) | CLI argument parsing |
+| [`websocket/app.ts`](https://github.com/cs01/ChadScript/blob/main/examples/websocket) | WebSocket chat with embedded HTML/CSS |
+| [`hackernews/app.ts`](https://github.com/cs01/ChadScript/blob/main/examples/hackernews) | Full Hacker News clone — SQLite + embedded assets + JSON API |
 
 ```bash
-chad build server.ts -o server
-./server &
-curl http://localhost:3000
-```
-
-## CLI Tool
-
-```typescript
-const content = fs.readFileSync("README.md");
-const words = content.split(" ");
-console.log("Words: ");
-console.log(words.length);
-```
+git clone https://github.com/cs01/ChadScript && cd ChadScript
 
-```bash
-$ chad run word-count.ts
-Words:
-142
+chad run examples/hello.ts
+chad run examples/word-count.ts -- README.md
+chad run examples/parallel.ts
+chad run examples/query.ts
+chad run examples/http-server.ts          # http://localhost:3000
+chad run examples/websocket/app.ts        # http://localhost:8080
+chad run examples/hackernews/app.ts       # http://localhost:3000
 ```
 
-## Single-Binary Webapp
-
-Embed HTML, CSS, and other static files directly into the binary at compile time. No external files needed at runtime — deploy a full webapp as a single executable.
-
-```typescript
-ChadScript.embedDir("./public");
-
-function handleRequest(req: HttpRequest): HttpResponse {
-  if (req.path == "/")
-    return { status: 200, body: ChadScript.getEmbeddedFile("index.html") };
-  if (req.path == "/style.css")
-    return { status: 200, body: ChadScript.getEmbeddedFile("style.css") };
-  return { status: 404, body: "Not Found" };
-}
-
-httpServe(3000, handleRequest);
-```
-
-```bash
-$ chad build app.ts -o webapp
-$ scp webapp server:~/  # deploy = copy one file
-$ ./webapp
-```
-
-See [ChadScript.embed](/stdlib/embed) for full API docs.
-
 ## Next Steps
 
 - Browse the [Standard Library](/stdlib/) for all available APIs
 - See [CLI Reference](/getting-started/cli) for all compiler options
-- Check [Type Mappings](/language/type-mappings) to understand how types compile
+- Check [Supported Features](/language/limitations) to understand the TypeScript subset
diff --git a/docs/index.md b/docs/index.md
index 8e8f626e..a0972da5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,7 +10,7 @@ hero:
       link: /getting-started/installation
     - theme: alt
       text: Learn More
-      link: /language/limitations
+      link: /language/architecture
 
 features:
   - title: No Runtime
@@ -31,6 +31,8 @@ features:
 
 <ExampleTabs />
 
+<div class="examples-link">See more <a href="/ChadScript/getting-started/quickstart">examples →</a></div>
+
 <div class="cta-section">
 
 ## Ready to try it?
@@ -47,6 +49,19 @@ curl -fsSL https://raw.githubusercontent.com/cs01/ChadScript/main/install.sh | s
 </div>
 
 <style>
+.examples-link {
+  text-align: center;
+  margin-top: 1rem;
+  font-size: 0.9rem;
+  color: var(--vp-c-text-3);
+}
+.examples-link a {
+  color: var(--vp-c-brand-1);
+  text-decoration: none;
+}
+.examples-link a:hover {
+  text-decoration: underline;
+}
 .cta-section {
   max-width: 688px;
   margin: 4rem auto 2rem;
diff --git a/docs/language/architecture.md b/docs/language/architecture.md
index c895be56..61728970 100644
--- a/docs/language/architecture.md
+++ b/docs/language/architecture.md
@@ -1,52 +1,71 @@
-# How ChadScript Works
+# About ChadScript
 
-ChadScript is an ahead-of-time compiler. It reads TypeScript source files, type-checks them, generates LLVM IR, and produces a standalone native binary. There's no interpreter, no JIT, and no runtime dependency on Node.js or V8.
+ChadScript is an ahead-of-time TypeScript compiler that produces standalone native binaries. Write standard TypeScript, run `chad build`, and get an ELF or Mach-O binary that starts in under 2ms — no Node.js, no JVM, no runtime VM. The compiler is self-hosting: it is written in TypeScript and compiles itself to a native binary.
 
-## Compilation Pipeline
+It targets a practical subset of TypeScript where all types are known at compile time. This has a nice side effect: the supported language is simpler and easier to reason about. Like C++ has a "safe subset" that avoids its footguns, ChadScript is a safe subset of TypeScript — you get the familiar syntax without the dynamic corners that make large codebases hard to follow. See [Supported Features](/language/limitations) for the full feature list.
 
+## How It Compiles Your Code
+
+When you run `chad build app.ts -o app`, the compiler parses your TypeScript into an AST, resolves every type, lowers the AST to LLVM IR, then hands off to `opt` (LLVM's optimizer), `llc` (LLVM's object code generator), and `clang` (linker) to produce the final binary. The output is a standard ELF binary (Linux) or Mach-O binary (macOS) — run it, deploy it, or ship it like any other native program.
+
+### LLVM IR
+
+The core of the compiler is a code generator that emits [LLVM Intermediate Representation](https://llvm.org/docs/LangRef.html). LLVM IR is the same intermediate format used by Clang (C/C++), Rust, Swift, and Kotlin Native. It's a typed, register-based assembly language that sits one level above machine code: it describes operations like loads, stores, arithmetic, and function calls without committing to a specific CPU instruction set.
+
+From LLVM IR, LLVM's optimizer and backend produce tight native machine code for x86-64, ARM64, or any other LLVM target. This means ChadScript gets decades of battle-tested optimization passes for free.
+
+Here's what `console.log("Hello, World!")` compiles to:
+
+```llvm
+@str.0 = private constant [14 x i8] c"Hello, World!\00"
+@fmt.1 = private constant [4 x i8]  c"%s\0A\00"         ; "%s\n"
+
+define i32 @main() {
+entry:
+  %0 = getelementptr [14 x i8], [14 x i8]* @str.0, i64 0, i64 0
+  %1 = getelementptr [4 x i8],  [4 x i8]*  @fmt.1, i64 0, i64 0
+  %2 = call i32 (i8*, ...) @printf(i8* %1, i8* %0)
+  %3 = call i32 @fflush(i8* null)
+  ret i32 0
+}
+
+declare i32 @printf(i8*, ...)
+declare i32 @fflush(i8*)
 ```
-TypeScript source → parse → type-check → LLVM IR → assemble → link → native binary
-```
 
-When you run `chad build app.ts -o app`, the compiler:
+The string literal is a global constant. `getelementptr` produces a pointer to its first byte. `call` invokes C's `printf` directly — no VM, no dispatch table, no boxing. The `declare` lines tell LLVM the type signatures of external C functions; the actual implementations come from libc at link time.
+
+## Types and Semantics
 
-1. **Parses** your TypeScript into an AST
-2. **Resolves types** — every variable, parameter, and return value gets a concrete type
-3. **Generates LLVM IR** — each function, class, and expression is lowered to LLVM intermediate representation
-4. **Assembles** — `llc` converts the IR to a native object file
-5. **Links** — `clang` links the object file against system libraries to produce the final binary
+TypeScript (and JavaScript) has a single `number` type — a 64-bit IEEE 754 float. ChadScript preserves this at the source level, but the compiler is smart about it: integer literals (`42`, `0xFF`) compile to native 64-bit integer registers; fractional values (`3.14`) use 64-bit doubles. Integer arithmetic (`+`, `-`, `*`, `%`) between integers stays in integer registers — no floating-point overhead. Division always returns a float. This is automatic and invisible.
 
-The output is a standard ELF binary (Linux) or Mach-O binary (macOS). You can run it, deploy it, or distribute it like any other compiled program.
+This matters because LLVM distinguishes the two: `add i64 %a, %b` is an integer add, `fadd double %a, %b` is a floating-point add. Getting the right instruction means you pay for the operation you actually need.
 
-## What's Inside the Binary
+**Null safety.** In C, `null` is just a zero-valued pointer. Dereferencing it is undefined behavior — the compiler trusts you, and if you're wrong you get a segfault or worse. In TypeScript (and ChadScript), `null` is a value that must be explicitly included in a type: `string | null`. If a variable is typed `string`, the type checker guarantees it is never null before it's used. The compiled output is still a pointer under the hood, but the type system prevents the class of bugs C can't catch. You get the safety of TypeScript's type model with the performance profile of C.
 
-ChadScript links against several C libraries so your program has access to networking, databases, crypto, and more without installing anything at runtime:
+**Why this works well for LLMs.** TypeScript is one of the most widely represented languages in public training data — models know it well and generate it fluently. A safe, statically-typed subset means LLM-generated code is more likely to be correct: the types act as inline documentation telling both the compiler and the model what each value is. Simpler semantics (no `eval`, no `Proxy`, no runtime type mutation) mean programs are shorter and more predictable — fewer edge cases to reason about, fewer tokens needed to express intent, better output.
 
-| Library | What it provides |
-|---------|-----------------|
-| libgc (Boehm GC) | Automatic memory management |
-| libuv | Event loop for async/await, timers |
-| libcurl | HTTP client (`fetch()`) |
-| libcrypto (OpenSSL) | Hashing, random bytes |
-| libsqlite3 | SQLite database |
-| mongoose | HTTP server (`httpServe()`) |
-| cJSON | JSON parsing |
+## The Runtime
 
-All of these are statically linked into your binary. The result is a single file with no external dependencies.
+ChadScript programs are statically linked against C libraries so the binary has access to networking, databases, file I/O, crypto, and more with no external runtime. The libraries ship with the compiler and are bundled into the output at link time — the result is a single self-contained file.
 
-## Self-Hosting
+LLVM IR calls into C libraries using their native ABI — no FFI wrapper, no marshalling overhead. The `declare` + `call` pattern you saw above works for any C function:
 
-ChadScript compiles itself. The compiler is ~45k lines of TypeScript that produces a native binary — which can then compile the compiler again without Node.js. This three-stage bootstrap (Node.js → Stage 0 → Stage 1 → Stage 2) is the ultimate correctness test: if the compiler's output can reproduce itself, it's working correctly.
+```llvm
+; Declare the C function signature so LLVM knows how to call it
+declare i32 @sqlite3_open(i8*, i8**)
+
+; Call it just like any other function
+%rc = call i32 @sqlite3_open(i8* %path, i8** %db_out)
+```
+
+The linker resolves the symbol at build time. At runtime there is nothing dynamic — the address is baked into the binary.
 
 ## Platform Support
 
-- **Linux x86-64** — primary target, musl (static) and glibc builds
+- **Linux x86-64** — primary target
 - **Linux ARM64** — supported
 - **macOS ARM64** — supported (Apple Silicon)
 - **macOS x64** — supported (Intel)
 
-### Cross-Compilation
-
-ChadScript supports cross-compiling from any supported host to any supported target. The `--target` flag controls IR generation (triple, data layout, platform symbols), and pre-built target SDKs provide the vendor libraries and C bridge objects needed for linking.
-
-For Linux targets, cross-compiled binaries use musl and are fully statically linked — they run on any Linux distribution without runtime dependencies. See the [CLI reference](../getting-started/cli.md#cross-compilation) for setup instructions.
+Cross-compilation is supported — see the [CLI reference](../getting-started/cli.md#cross-compilation) for details.
diff --git a/docs/language/limitations.md b/docs/language/limitations.md
index 8ec9fab7..d010ddf8 100644
--- a/docs/language/limitations.md
+++ b/docs/language/limitations.md
@@ -1,6 +1,4 @@
-# Language Support
-
-ChadScript supports a practical subset of TypeScript. All types must be known at compile time — there's no runtime type system, no interpreter, and no VM.
+# Supported Features
 
 ## Core Language
 
@@ -79,7 +77,7 @@ ChadScript supports a practical subset of TypeScript. All types must be known at
 | `implements` | Supported |
 | Interface inheritance (`extends`) | Supported |
 | Static methods and fields | Supported |
-| Abstract classes | Not yet supported |
+| Abstract classes | Not supported |
 | Private class fields (`#field`) | Not supported |
 | Decorators | Not supported |
 
diff --git a/docs/stdlib/embed.md b/docs/stdlib/embed.md
index 58a7c4ec..12aed4b8 100644
--- a/docs/stdlib/embed.md
+++ b/docs/stdlib/embed.md
@@ -57,6 +57,8 @@ Returns a zero-length `Uint8Array` if the key is not found.
 
 Return an `HttpResponse` for an embedded file. Strips the leading `/` from the path, looks up the file in the embedded table, and returns `{ status: 200, body: content, headers: "" }` if found or `{ status: 404, body: "Not Found", headers: "" }` if not.
 
+The HTTP server automatically sets `Content-Type` based on the file extension, so `.css`, `.js`, `.png`, `.wasm`, etc. all get the correct header with no extra work.
+
 This eliminates per-file route boilerplate for serving static assets:
 
 ```typescript
@@ -83,13 +85,18 @@ my-server/
 ```
 
 ```typescript
+// Compile time: walks ./public/ and bakes every file into the binary as a string constant.
+// The directory itself is not needed at runtime — files live in memory.
 ChadScript.embedDir("./public");
 
 function handleRequest(req: HttpRequest): HttpResponse {
-  // Serve all embedded files with a single line
+  // serveEmbedded strips the leading '/', looks up the file in the embedded
+  // table, and returns 200 + body if found, or 404 if not.
+  // Content-Type is inferred from the file extension (.css, .png, .js, etc.)
   return ChadScript.serveEmbedded(req.path);
 }
 
+// Starts listening on port 3000; blocks forever
 httpServe(3000, handleRequest);
 ```
 
diff --git a/docs/stdlib/http-server.md b/docs/stdlib/http-server.md
index e102bf21..6a6c0b59 100644
--- a/docs/stdlib/http-server.md
+++ b/docs/stdlib/http-server.md
@@ -66,7 +66,7 @@ wsBroadcast("hello everyone");
 | `body` | `string` | Response body |
 | `headers` | `string` | Extra response headers as `"\n"`-separated lines (e.g. `"Set-Cookie: session=abc\nX-Custom: value"`) |
 
-If `headers` contains a `Content-Type:` line, it overrides the auto-sniffed content type. Set `headers` to `""` when no extra headers are needed.
+If `headers` contains a `Content-Type:` line, it overrides the auto-detected content type. Set `headers` to `""` when no extra headers are needed.
 
 ## WsEvent Object
 
diff --git a/examples/hackernews/app.ts b/examples/hackernews/app.ts
index 40dc5b88..e6f2aad6 100644
--- a/examples/hackernews/app.ts
+++ b/examples/hackernews/app.ts
@@ -1,4 +1,4 @@
-// Hacker News Clone - full-stack app with SQLite, embedded files, and server-side rendering
+// Hacker News Clone - full-stack app with SQLite, embedded files, and a JSON API
 import { ArgumentParser } from "../../src/argparse.js";
 
 const parser = new ArgumentParser(
@@ -37,113 +37,131 @@ sqlite.exec(
   "CREATE TABLE posts (id INTEGER PRIMARY KEY, title TEXT, url TEXT, points INTEGER)",
 );
 
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Show HN: ChadScript - TypeScript to native compiler via LLVM', 'https://github.com/cs01/ChadScript', 342)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Why we moved from Node.js to native binaries', 'https://example.com/native', 287)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('LLVM IR is surprisingly readable', 'https://llvm.org/docs/LangRef.html', 256)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('SQLite is the only database you need', 'https://sqlite.org', 234)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Single-binary deployments changed everything', 'https://example.com/single-binary', 198)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('The Boehm GC: garbage collection for C programs', 'https://hboehm.info/gc/', 176)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Zero-cost TypeScript: no runtime overhead', 'https://example.com/zero-cost', 165)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('libwebsockets: lightweight C WebSocket library', 'https://libwebsockets.org', 154)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Self-hosting compilers: the ultimate test', 'https://example.com/self-hosting', 143)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Compile-time file embedding in native languages', 'https://example.com/embed', 132)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Why I stopped using Docker for simple services', 'https://example.com/no-docker', 121)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('libuv: the event loop behind Node.js', 'https://libuv.org', 110)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Tree-sitter for building parsers', 'https://tree-sitter.github.io', 98)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Ask HN: What is your deploy strategy for side projects?', 'https://news.ycombinator.com', 87)",
-);
-sqlite.exec(
-  db,
-  "INSERT INTO posts (title, url, points) VALUES ('Building a compiler is easier than you think', 'https://example.com/compiler-easy', 76)",
-);
+interface SeedPost {
+  title: string;
+  url: string;
+  points: number;
+}
 
-function renderPosts(): string {
-  const posts: Post[] = sqlite.query(
-    db,
-    "SELECT id, title, url, points FROM posts ORDER BY points DESC",
-  );
-  let html = "";
-  for (let i = 0; i < posts.length; i++) {
-    const post = posts[i];
-    const rank = i + 1;
-    html = html + '<div class="post"><span class="rank">' + rank + ".</span>";
-    html = html + '<form method="POST" action="/upvote/' + post.id + '" style="display:inline">';
-    html = html + '<button type="submit" class="upvote" title="upvote"></button></form>';
-    html =
-      html + '<span class="title"><a href="' + post.url + '">' + post.title + "</a></span></div>";
-    html = html + '<div class="meta">' + post.points + " points</div>";
-  }
-  return html;
+const url = "https://github.com/cs01/ChadScript";
+
+const seedPosts: SeedPost[] = [
+  {
+    title: "Show HN: ChadScript - a compiled TypeScript that outputs native binaries",
+    url: url,
+    points: 342,
+  },
+  {
+    title: "ChadScript compiles TypeScript to LLVM IR, then to standalone ELF executables",
+    url: url,
+    points: 287,
+  },
+  {
+    title:
+      "ChadScript supports a large subset of TypeScript: classes, interfaces, generics, async/await",
+    url: url,
+    points: 256,
+  },
+  {
+    title: "Native performance: ChadScript binaries start in under 2ms with zero runtime overhead",
+    url: url,
+    points: 234,
+  },
+  {
+    title: "ChadScript uses SQLite as a built-in database - no external dependencies needed",
+    url: url,
+    points: 198,
+  },
+  {
+    title: "Single-binary deploys: ChadScript embeds HTML, CSS, and assets at compile time",
+    url: url,
+    points: 176,
+  },
+  {
+    title: "ChadScript includes a built-in HTTP server, fetch, crypto, and JSON out of the box",
+    url: url,
+    points: 165,
+  },
+  {
+    title: "The ChadScript compiler is self-hosting - it compiles itself to a native binary",
+    url: url,
+    points: 154,
+  },
+  {
+    title: "ChadScript uses the Boehm GC for automatic memory management in compiled binaries",
+    url: url,
+    points: 143,
+  },
+  {
+    title: "No node_modules: everything you would npm install is built into ChadScript",
+    url: url,
+    points: 132,
+  },
+  {
+    title: "ChadScript cross-compiles from macOS to Linux with a single --target flag",
+    url: url,
+    points: 121,
+  },
+  {
+    title: "ChadScript uses libuv under the hood for async I/O and event loop support",
+    url: url,
+    points: 110,
+  },
+  {
+    title: "Write TypeScript, ship a 42KB static binary - the ChadScript workflow",
+    url: url,
+    points: 98,
+  },
+  {
+    title: "ChadScript parses TypeScript with a hand-written recursive descent parser",
+    url: url,
+    points: 87,
+  },
+  {
+    title: "Ask HN: Has anyone tried ChadScript for deploying side projects?",
+    url: url,
+    points: 76,
+  },
+];
+
+for (let i = 0; i < seedPosts.length; i++) {
+  const post = seedPosts[i];
+  sqlite.exec(db, "INSERT INTO posts (title, url, points) VALUES (?, ?, ?)", [
+    post.title,
+    post.url,
+    "" + post.points,
+  ]);
 }
 
 function handleRequest(req: HttpRequest): HttpResponse {
   console.log(req.method + " " + req.path);
 
-  if (req.method === "GET" && req.path === "/") {
-    const template = ChadScript.getEmbeddedFile("index.html");
-    const posts = renderPosts();
-    const body = template.replace("{{POSTS}}", posts);
-    return { status: 200, body: body };
+  if (req.path === "/api/posts") {
+    const posts: Post[] = sqlite.query(
+      db,
+      "SELECT id, title, url, points FROM posts ORDER BY points DESC",
+    );
+    return { status: 200, body: JSON.stringify(posts) };
   }
 
   if (req.method === "POST" && req.path.startsWith("/upvote/")) {
     const idStr = req.path.substring(8, req.path.length);
     sqlite.exec(db, "UPDATE posts SET points = points + 1 WHERE id = ?", [idStr]);
-    const redirectHtml =
-      '<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0;url=/"></head><body>Redirecting...</body></html>';
-    return { status: 200, body: redirectHtml };
+    return { status: 200, body: '{"ok":true}' };
+  }
+
+  if (req.path === "/") {
+    return ChadScript.serveEmbedded("index.html");
   }
 
-  // Serve all other embedded files (CSS, images, etc.) with a single line
   return ChadScript.serveEmbedded(req.path);
 }
 
 console.log("Hacker News Clone");
-console.log("  listening on http://localhost:" + port);
-console.log("  HTML/CSS embedded in the binary at compile time");
-console.log("  SQLite database running in-memory with 15 posts");
+console.log(`  listening on http://localhost:${port}`);
+console.log("  HTML/CSS/JS embedded in the binary at compile time");
+console.log(`  SQLite database running in-memory with ${seedPosts.length} posts`);
 console.log("");
-console.log("Open http://localhost:" + port + " in your browser");
+console.log(`Open http://localhost:${port} in your browser`);
 console.log("");
 httpServe(port, handleRequest);
diff --git a/examples/hackernews/public/hn.js b/examples/hackernews/public/hn.js
new file mode 100644
index 00000000..13ba0761
--- /dev/null
+++ b/examples/hackernews/public/hn.js
@@ -0,0 +1,70 @@
+// Client-side rendering for the Hacker News clone.
+// Fetches posts from /api/posts and builds the DOM.
+
+function renderPosts(posts) {
+  var content = document.getElementById("content");
+  content.innerHTML = "";
+
+  for (var i = 0; i < posts.length; i++) {
+    var post = posts[i];
+    var rank = i + 1;
+
+    var postDiv = document.createElement("div");
+    postDiv.className = "post";
+
+    var rankSpan = document.createElement("span");
+    rankSpan.className = "rank";
+    rankSpan.textContent = rank + ".";
+
+    var upvoteForm = document.createElement("form");
+    upvoteForm.method = "POST";
+    upvoteForm.setAttribute("data-id", post.id);
+    upvoteForm.style.display = "inline";
+
+    var upvoteBtn = document.createElement("button");
+    upvoteBtn.type = "submit";
+    upvoteBtn.className = "upvote";
+    upvoteBtn.title = "upvote";
+    upvoteForm.appendChild(upvoteBtn);
+
+    var titleSpan = document.createElement("span");
+    titleSpan.className = "title";
+    var titleLink = document.createElement("a");
+    titleLink.href = post.url;
+    titleLink.textContent = post.title;
+    titleSpan.appendChild(titleLink);
+
+    postDiv.appendChild(rankSpan);
+    postDiv.appendChild(upvoteForm);
+    postDiv.appendChild(titleSpan);
+
+    var metaDiv = document.createElement("div");
+    metaDiv.className = "meta";
+    metaDiv.textContent = post.points + " points";
+
+    content.appendChild(postDiv);
+    content.appendChild(metaDiv);
+  }
+}
+
+function upvote(id, metaDiv) {
+  fetch("/upvote/" + id, { method: "POST" });
+  var pts = parseInt(metaDiv.textContent, 10);
+  metaDiv.textContent = pts + 1 + " points";
+}
+
+document.addEventListener("submit", function (e) {
+  e.preventDefault();
+  var form = e.target;
+  var id = form.getAttribute("data-id");
+  if (id) {
+    var metaDiv = form.closest(".post").nextElementSibling;
+    upvote(id, metaDiv);
+  }
+});
+
+fetch("/api/posts")
+  .then(function (res) {
+    return res.json();
+  })
+  .then(renderPosts);
diff --git a/examples/hackernews/public/index.html b/examples/hackernews/public/index.html
index 1656aad3..372e52fd 100644
--- a/examples/hackernews/public/index.html
+++ b/examples/hackernews/public/index.html
@@ -4,7 +4,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Hacker News</title>
-    <link rel="stylesheet" href="/style.css" />
+    <link rel="stylesheet" href="style.css" />
   </head>
   <body>
     <div id="header">
@@ -14,25 +14,11 @@
       </a>
       <span class="tagline">Served by a ChadScript native binary</span>
     </div>
-    <div id="content">
-      <!-- posts injected server-side -->
-      {{POSTS}}
-    </div>
+    <div id="content"></div>
     <div id="footer">
       <p>Powered by ChadScript &mdash; compiled from TypeScript to a native ELF binary via LLVM.</p>
       <p>HTML, CSS, and data are all embedded in a single binary. Zero runtime dependencies.</p>
     </div>
-    <script>
-      document.addEventListener("submit", function (e) {
-        var form = e.target;
-        if (form.action && form.action.indexOf("/upvote/") !== -1) {
-          e.preventDefault();
-          fetch(form.action, { method: "POST" });
-          var meta = form.closest(".post").nextElementSibling;
-          var pts = parseInt(meta.textContent, 10);
-          meta.textContent = pts + 1 + " points";
-        }
-      });
-    </script>
+    <script src="hn.js"></script>
   </body>
 </html>
diff --git a/examples/http-server.ts b/examples/http-server.ts
index 53f8c83a..cfdf4ffe 100644
--- a/examples/http-server.ts
+++ b/examples/http-server.ts
@@ -22,10 +22,7 @@ interface HttpResponse {
 // --- Route Handlers ---
 
 function homeHandler(req: HttpRequest): HttpResponse {
-  return {
-    status: 200,
-    body: "<h1>Hello from ChadScript</h1><p>This page is served by a native binary compiled from TypeScript.</p>",
-  };
+  return { status: 200, body: '{"name":"ChadScript HTTP Server","status":"running"}' };
 }
 
 function jsonHandler(req: HttpRequest): HttpResponse {
@@ -91,7 +88,7 @@ console.log("ChadScript HTTP Server");
 console.log("  listening on http://localhost:" + port);
 console.log("");
 console.log("Available routes:");
-console.log("  GET  /              - Home page (HTML)");
+console.log("  GET  /              - Server info (JSON)");
 console.log("  GET  /json          - JSON response");
 console.log("  GET  /echo?msg=...  - Echo query parameter");
 console.log("  GET  /status/:code  - Status code demo");
diff --git a/examples/parallel.ts b/examples/parallel.ts
index 03b1bc00..a6adf179 100644
--- a/examples/parallel.ts
+++ b/examples/parallel.ts
@@ -6,14 +6,14 @@ interface Repo {
 
 async function main(): Promise<void> {
   const results = await Promise.all([
-    fetch("https://api.github.com/repos/cs01/ChadScript"),
+    fetch("https://api.github.com/repos/vuejs/vue"),
     fetch("https://api.github.com/repos/facebook/react"),
   ]);
 
-  const cs = JSON.parse<Repo>(results[0].text());
+  const vue = JSON.parse<Repo>(results[0].text());
   const react = JSON.parse<Repo>(results[1].text());
 
-  console.log("ChadScript: " + cs.stargazers_count + " stars");
+  console.log("Vue: " + vue.stargazers_count + " stars");
   console.log("React: " + react.stargazers_count + " stars");
 }
 
diff --git a/examples/websocket/public/chat.js b/examples/websocket/public/chat.js
new file mode 100644
index 00000000..478eed09
--- /dev/null
+++ b/examples/websocket/public/chat.js
@@ -0,0 +1,55 @@
+// Client-side WebSocket chat logic.
+// Connects to the server, sends/receives messages, auto-reconnects.
+
+var messages = document.getElementById("messages");
+var form = document.getElementById("form");
+var input = document.getElementById("input");
+var status = document.getElementById("status");
+var ws;
+
+function addMessage(text, type) {
+  var div = document.createElement("div");
+  div.className = "message " + type;
+  div.textContent = text;
+  messages.appendChild(div);
+  messages.scrollTop = messages.scrollHeight;
+}
+
+function connect() {
+  status.textContent = "connecting...";
+  status.className = "status";
+  ws = new WebSocket("ws://" + location.host + "/ws");
+
+  ws.onopen = function () {
+    status.textContent = "connected";
+    status.className = "status connected";
+    addMessage("Connected to chat server", "system");
+  };
+
+  ws.onmessage = function (e) {
+    addMessage(e.data, "received");
+  };
+
+  ws.onerror = function () {
+    addMessage("Connection error", "system");
+  };
+
+  ws.onclose = function () {
+    status.textContent = "disconnected";
+    status.className = "status disconnected";
+    addMessage("Disconnected — reconnecting...", "system");
+    setTimeout(connect, 2000);
+  };
+}
+
+form.onsubmit = function (e) {
+  e.preventDefault();
+  var msg = input.value.trim();
+  if (msg.length > 0 && ws && ws.readyState === 1) {
+    ws.send(msg);
+    addMessage(msg, "sent");
+    input.value = "";
+  }
+};
+
+connect();
diff --git a/examples/websocket/public/index.html b/examples/websocket/public/index.html
index a58044e3..0eb1d3aa 100644
--- a/examples/websocket/public/index.html
+++ b/examples/websocket/public/index.html
@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ChadScript Chat</title>
-    <link rel="stylesheet" href="/style.css" />
+    <link rel="stylesheet" href="style.css" />
   </head>
   <body>
     <div class="container">
@@ -24,59 +24,6 @@ <h1>ChadScript Chat</h1>
         <button type="submit">Send</button>
       </form>
     </div>
-    <script>
-      var messages = document.getElementById("messages");
-      var form = document.getElementById("form");
-      var input = document.getElementById("input");
-      var status = document.getElementById("status");
-      var ws;
-
-      function addMessage(text, type) {
-        var div = document.createElement("div");
-        div.className = "message " + type;
-        div.textContent = text;
-        messages.appendChild(div);
-        messages.scrollTop = messages.scrollHeight;
-      }
-
-      function connect() {
-        status.textContent = "connecting...";
-        status.className = "status";
-        ws = new WebSocket("ws://" + location.host + "/ws");
-
-        ws.onopen = function () {
-          status.textContent = "connected";
-          status.className = "status connected";
-          addMessage("Connected to chat server", "system");
-        };
-
-        ws.onmessage = function (e) {
-          addMessage(e.data, "received");
-        };
-
-        ws.onerror = function () {
-          addMessage("Connection error", "system");
-        };
-
-        ws.onclose = function () {
-          status.textContent = "disconnected";
-          status.className = "status disconnected";
-          addMessage("Disconnected — reconnecting...", "system");
-          setTimeout(connect, 2000);
-        };
-      }
-
-      form.onsubmit = function (e) {
-        e.preventDefault();
-        var msg = input.value.trim();
-        if (msg.length > 0 && ws && ws.readyState === 1) {
-          ws.send(msg);
-          addMessage(msg, "sent");
-          input.value = "";
-        }
-      };
-
-      connect();
-    </script>
+    <script src="chat.js"></script>
   </body>
 </html>
diff --git a/src/analysis/semantic-analyzer.ts b/src/analysis/semantic-analyzer.ts
index b1580118..aac087fb 100644
--- a/src/analysis/semantic-analyzer.ts
+++ b/src/analysis/semantic-analyzer.ts
@@ -87,7 +87,11 @@ export class SemanticAnalyzer {
     this.ast = ast;
     this.symbols = new Map();
     this.diagnosticEngine = new DiagnosticEngine();
-    this.diagnosticEngine.setColor(true);
+    // Color off by default; caller sets via setDiagnosticColor after construction
+  }
+
+  setDiagnosticColor(enabled: boolean): void {
+    this.diagnosticEngine.setColor(enabled);
   }
 
   setSuppressWarnings(value: boolean): void {
diff --git a/src/argparse.ts b/src/argparse.ts
index 00927fc6..377bb741 100644
--- a/src/argparse.ts
+++ b/src/argparse.ts
@@ -15,6 +15,7 @@ interface ArgDef {
 interface SubcommandDef {
   name: string;
   description: string;
+  group: string; // display group header, e.g. "" (default Commands), "Project", "Advanced"
 }
 
 interface ParsedFlag {
@@ -34,6 +35,7 @@ export class ArgumentParser {
   args: ArgDef[];
   subcommands: SubcommandDef[];
   parsedSubcommand: string;
+  colorEnabled: boolean;
 
   // Rest args (after --)
   restArgs: string[];
@@ -48,14 +50,25 @@ export class ArgumentParser {
     this.args = [];
     this.subcommands = [];
     this.parsedSubcommand = "";
+    this.colorEnabled = false;
     this.restArgs = [];
     this.parsedPositionals = [];
     this.parsedFlags = [];
     this.parsedOptions = [];
   }
 
+  setColorEnabled(enabled: boolean): void {
+    this.colorEnabled = enabled;
+  }
+
   addSubcommand(name: string, desc: string): void {
-    this.subcommands.push({ name: name, description: desc });
+    this.subcommands.push({ name: name, description: desc, group: "" });
+  }
+
+  // Like addSubcommand but assigns a display group (e.g. "Project", "Advanced").
+  // Empty group string is the default "Commands:" section.
+  addSubcommandInGroup(name: string, desc: string, group: string): void {
+    this.subcommands.push({ name: name, description: desc, group: group });
   }
 
   // Add a boolean flag (e.g., -v, --verbose)
@@ -560,24 +573,65 @@ export class ArgumentParser {
     console.log("");
     console.log("Usage: " + this.programName + " <command> [options]");
     console.log("");
-    console.log("Commands:");
+
+    // Collect unique groups in insertion order
+    const groups: string[] = [];
     let i = 0;
     while (i < this.subcommands.length) {
-      let line = "  " + this.subcommands[i].name;
-      let padLen = 16 - this.subcommands[i].name.length;
-      if (padLen < 2) {
-        padLen = 2;
-      }
-      let pad = 0;
-      while (pad < padLen) {
-        line = line + " ";
-        pad = pad + 1;
-      }
-      line = line + this.subcommands[i].description;
-      console.log(line);
+      const g = this.subcommands[i].group;
+      let found = false;
+      let j = 0;
+      while (j < groups.length) {
+        if (groups[j] === g) {
+          found = true;
+        }
+        j = j + 1;
+      }
+      if (!found) {
+        groups.push(g);
+      }
       i = i + 1;
     }
 
+    // Print each group section
+    let gi = 0;
+    while (gi < groups.length) {
+      const groupName = groups[gi];
+      if (groupName.length === 0) {
+        console.log("Commands:");
+      } else {
+        console.log(groupName + ":");
+      }
+      let si = 0;
+      while (si < this.subcommands.length) {
+        if (this.subcommands[si].group === groupName) {
+          // Use visible name length for padding so ANSI codes don't throw off alignment
+          const visibleName = this.subcommands[si].name;
+          let displayName = visibleName;
+          if (this.colorEnabled) {
+            displayName = "\x1b[1;36m" + visibleName + "\x1b[0m"; // bold cyan
+          }
+          let line = "  " + displayName;
+          let padLen = 16 - visibleName.length;
+          if (padLen < 2) {
+            padLen = 2;
+          }
+          let pad = 0;
+          while (pad < padLen) {
+            line = line + " ";
+            pad = pad + 1;
+          }
+          line = line + this.subcommands[si].description;
+          console.log(line);
+        }
+        si = si + 1;
+      }
+      gi = gi + 1;
+      if (gi < groups.length) {
+        console.log("");
+      }
+    }
+
     let hasGlobalArgs = false;
     i = 0;
     while (i < this.args.length) {
diff --git a/src/chad-native.ts b/src/chad-native.ts
index ef1430b7..fbaf6de9 100644
--- a/src/chad-native.ts
+++ b/src/chad-native.ts
@@ -5,9 +5,11 @@ import {
   setTargetCpu,
   setTargetTriple,
   setVerbose,
+  setDebugInfo,
   addLinkObj,
   addLinkLib,
   addLinkPath,
+  setDiagnosticColor,
 } from "./native-compiler-lib.js";
 // d.ts content is embedded at compile time via ChadScript.embedFile
 const dtsContent = ChadScript.embedFile("../chadscript.d.ts");
@@ -51,17 +53,23 @@ declare function cs_watch_loop(
 const VERSION = "0.1.0";
 
 const parser = new ArgumentParser("chad", "compile TypeScript to native binaries via LLVM");
-parser.addSubcommand("build", "Compile to a native binary");
-parser.addSubcommand("run", "Compile and run");
-parser.addSubcommand("ir", "Emit LLVM IR only");
-parser.addSubcommand("init", "Generate starter project");
-parser.addSubcommand("watch", "Watch for changes and recompile+run");
-parser.addSubcommand("clean", "Remove the .build directory");
-parser.addSubcommand("target", "Manage cross-compilation target SDKs");
+// Color enabled unless NO_COLOR is set (https://no-color.org/) or TERM=dumb
+const _noColor = process.env.NO_COLOR || process.env.TERM === "dumb";
+const _colorEnabled = !_noColor;
+parser.setColorEnabled(_colorEnabled);
+setDiagnosticColor(_colorEnabled);
+parser.addSubcommandInGroup("build", "Compile to a native binary", "");
+parser.addSubcommandInGroup("run", "Compile and run", "");
+parser.addSubcommandInGroup("watch", "Watch for changes and recompile+run", "");
+parser.addSubcommandInGroup("init", "Generate starter project", "Project");
+parser.addSubcommandInGroup("clean", "Remove the .build directory", "Project");
+parser.addSubcommandInGroup("ir", "Emit LLVM IR only", "Advanced");
+parser.addSubcommandInGroup("target", "Manage cross-compilation target SDKs", "Advanced");
 
 parser.addFlag("version", "", "Show version");
 parser.addScopedOption("output", "o", "Specify output file", "", "build,run,ir");
 parser.addScopedFlag("verbose", "v", "Show compilation steps", "build,run,ir");
+parser.addScopedFlag("debug-info", "g", "Emit DWARF debug info (skips stripping)", "build,run");
 parser.addScopedFlag("skip-semantic-analysis", "", "Skip semantic analysis", "build,run,ir");
 parser.addScopedOption(
   "target",
@@ -246,6 +254,10 @@ if (parser.getFlag("verbose")) {
   setVerbose(true);
 }
 
+if (parser.getFlag("debug-info")) {
+  setDebugInfo(true);
+}
+
 if (parser.getFlag("skip-semantic-analysis")) {
   setSkipSemanticAnalysis(true);
 }
diff --git a/src/chad-node.ts b/src/chad-node.ts
index df4d7909..c2e999bc 100644
--- a/src/chad-node.ts
+++ b/src/chad-node.ts
@@ -25,13 +25,18 @@ import { execSync, spawn as spawnProc, ChildProcess } from "child_process";
 import { installTargetSDK, listInstalledSDKs, getSDKBaseDir } from "./cross-compile.js";
 
 const parser = new ArgumentParser("chad", "compile TypeScript to native binaries via LLVM");
-parser.addSubcommand("build", "Compile to a native binary");
-parser.addSubcommand("run", "Compile and run");
-parser.addSubcommand("ir", "Emit LLVM IR only");
-parser.addSubcommand("init", "Generate starter project (chadscript.d.ts, tsconfig.json, hello.ts)");
-parser.addSubcommand("watch", "Watch for changes and recompile+run");
-parser.addSubcommand("clean", "Remove the .build directory");
-parser.addSubcommand("target", "Manage cross-compilation target SDKs");
+parser.setColorEnabled(process.stdout.isTTY === true);
+parser.addSubcommandInGroup("build", "Compile to a native binary", "");
+parser.addSubcommandInGroup("run", "Compile and run", "");
+parser.addSubcommandInGroup("watch", "Watch for changes and recompile+run", "");
+parser.addSubcommandInGroup(
+  "init",
+  "Generate starter project (chadscript.d.ts, tsconfig.json, hello.ts)",
+  "Project",
+);
+parser.addSubcommandInGroup("clean", "Remove the .build directory", "Project");
+parser.addSubcommandInGroup("ir", "Emit LLVM IR only", "Advanced");
+parser.addSubcommandInGroup("target", "Manage cross-compilation target SDKs", "Advanced");
 
 parser.addFlag("version", "", "Show version");
 parser.addScopedOption("output", "o", "Specify output file", "", "build,run,ir");
diff --git a/src/codegen/expressions/method-calls.ts b/src/codegen/expressions/method-calls.ts
index 5d559e0f..a2ce4093 100644
--- a/src/codegen/expressions/method-calls.ts
+++ b/src/codegen/expressions/method-calls.ts
@@ -506,6 +506,26 @@ export class MethodCallGenerator {
       return isArray ? "1.0" : "0.0";
     }
 
+    // String.fromCharCode(n) — convert a number to a 1-char string
+    if (this.isVariableWithName(expr.object, "String") && method === "fromCharCode") {
+      if (expr.args.length === 0) {
+        return this.ctx.emitError("String.fromCharCode() requires 1 argument", expr.loc);
+      }
+      const codeVal = this.ctx.generateExpression(expr.args[0], params);
+      const dblVal = this.ctx.ensureDouble(codeVal);
+      const intVal = this.ctx.nextTemp();
+      this.ctx.emit(`${intVal} = fptosi double ${dblVal} to i32`);
+      const byteVal = this.ctx.nextTemp();
+      this.ctx.emit(`${byteVal} = trunc i32 ${intVal} to i8`);
+      // Allocate 2 bytes: the char + null terminator
+      const buf = this.ctx.emitCall("i8*", "@GC_malloc_atomic", "i64 2");
+      this.ctx.emitStore("i8", byteVal, buf);
+      const nullPtr = this.ctx.emitGep("i8", buf, "i64 1");
+      this.ctx.emitStore("i8", "0", nullPtr);
+      this.ctx.setVariableType(buf, "i8*");
+      return buf;
+    }
+
     if (this.isVariableWithName(expr.object, "Object") && method === "keys") {
       return generateObjectKeys(this.ctx, expr, params);
     }
diff --git a/src/codegen/infrastructure/type-inference.ts b/src/codegen/infrastructure/type-inference.ts
index 12b836b5..c890e89d 100644
--- a/src/codegen/infrastructure/type-inference.ts
+++ b/src/codegen/infrastructure/type-inference.ts
@@ -389,6 +389,7 @@ export class TypeInference {
       }
 
       if (varName === "JSON" && method === "stringify") return this.ctx.typeContext.stringType;
+      if (varName === "String" && method === "fromCharCode") return this.ctx.typeContext.stringType;
 
       if (varName === "crypto") {
         if (
diff --git a/src/codegen/llvm-generator.ts b/src/codegen/llvm-generator.ts
index 1a35959e..b0cc8f6b 100644
--- a/src/codegen/llvm-generator.ts
+++ b/src/codegen/llvm-generator.ts
@@ -1471,7 +1471,7 @@ export class LLVMGenerator extends BaseGenerator implements IGeneratorContext {
     this.diagnostics = new DiagnosticEngine();
     this.diagnostics.setSourceCode(this.sourceCode);
     this.diagnostics.setFilename(this.filename);
-    this.diagnostics.setColor(true);
+    // Color off by default; compiler.ts sets it based on stderr TTY
 
     this.typeContext = new TypeContext();
     this.symbolTable = new SymbolTable(this.typeContext);
diff --git a/src/codegen/runtime/runtime.ts b/src/codegen/runtime/runtime.ts
index 42ade6c9..82b0c4a8 100644
--- a/src/codegen/runtime/runtime.ts
+++ b/src/codegen/runtime/runtime.ts
@@ -262,6 +262,8 @@ export class RuntimeGenerator {
     ir += "declare void @csyyjson_obj_add_num(i8*, i8*, i8*, double)\n";
     ir += "declare void @csyyjson_obj_add_bool(i8*, i8*, i8*, i32)\n";
     ir += "declare i8* @csyyjson_stringify(i8*)\n";
+    ir += "declare i8* @csyyjson_create_arr()\n";
+    ir += "declare i8* @csyyjson_mut_arr_add_obj(i8*, i8*)\n";
     ir += "\n";
 
     ir += "define i32 @csyyjson_get_num_as_int(i8* %item) {\n";
diff --git a/src/codegen/stdlib/json.ts b/src/codegen/stdlib/json.ts
index f23fda44..7ae96735 100644
--- a/src/codegen/stdlib/json.ts
+++ b/src/codegen/stdlib/json.ts
@@ -472,6 +472,17 @@ export class JsonGenerator {
       return this.stringifyString(arg, params);
     }
 
+    // Check for ObjectArray (e.g. Post[]) before resolveInterfaceType —
+    // getRawInterfaceType returns the element type for arrays, which would
+    // cause stringifyInterface to treat the array pointer as a single object.
+    if (arg.type === "variable") {
+      const varNode = arg as { type: string; name: string };
+      const elementType = this.ctx.symbolTable.getObjectArrayElementType(varNode.name);
+      if (elementType) {
+        return this.stringifyObjectArray(arg, params, elementType);
+      }
+    }
+
     const interfaceType = this.resolveInterfaceType(arg);
     if (interfaceType) {
       return this.stringifyInterface(arg, params, interfaceType);
@@ -516,20 +527,42 @@ export class JsonGenerator {
       return this.stringifyNumber(arg, params);
     }
 
-    const fieldTypes: string[] = [];
-    for (let i = 0; i < fieldCount; i++) {
-      fieldTypes.push(this.ctx.interfaceStructGenGetFieldLlvmType(interfaceType, i));
-    }
-    const structType = `{ ${fieldTypes.join(", ")} }`;
+    const structType = this.buildStructType(interfaceType, fieldCount);
 
     const objPtr = this.ctx.generateExpression(arg, params);
-
     const typedPtr = this.ctx.emitBitcast(objPtr, "i8*", `${structType}*`);
 
     this.ctx.setUsesJson(true);
     const jsonDoc = this.ctx.emitCall("i8*", "@csyyjson_create_obj", "");
     const jsonObj = this.ctx.emitCall("i8*", "@csyyjson_mut_get_root", `i8* ${jsonDoc}`);
 
+    this.emitAddFieldsToJsonObj(typedPtr, structType, interfaceType, jsonDoc, jsonObj);
+
+    const result = this.ctx.emitCall("i8*", "@csyyjson_stringify", `i8* ${jsonDoc}`);
+    this.ctx.setVariableType(result, "i8*");
+
+    return result;
+  }
+
+  /** Build the LLVM struct type string for an interface (e.g. "{ i8*, double }") */
+  private buildStructType(interfaceType: string, fieldCount: number): string {
+    const fieldTypes: string[] = [];
+    for (let i = 0; i < fieldCount; i++) {
+      fieldTypes.push(this.ctx.interfaceStructGenGetFieldLlvmType(interfaceType, i));
+    }
+    return `{ ${fieldTypes.join(", ")} }`;
+  }
+
+  /** Emit IR to add all fields of a typed struct to a yyjson object.
+   *  Shared by stringifyInterface (single object) and stringifyObjectArray (per-element). */
+  private emitAddFieldsToJsonObj(
+    typedPtr: string,
+    structType: string,
+    interfaceType: string,
+    jsonDoc: string,
+    jsonObj: string,
+  ): void {
+    const fieldCount = this.ctx.interfaceStructGenGetFieldCount(interfaceType);
     for (let i = 0; i < fieldCount; i++) {
       const fieldName = this.ctx.interfaceStructGenGetFieldName(interfaceType, i);
       const fieldTsType = this.ctx.interfaceStructGenGetFieldTsType(interfaceType, i);
@@ -563,6 +596,74 @@ export class JsonGenerator {
         );
       }
     }
+  }
+
+  /** Stringify an ObjectArray (e.g. Post[]) as a JSON array of objects */
+  private stringifyObjectArray(arg: Expression, params: string[], elementType: string): string {
+    if (!this.ctx.interfaceStructGenHasInterface(elementType)) {
+      return this.stringifyNumber(arg, params);
+    }
+    const fieldCount = this.ctx.interfaceStructGenGetFieldCount(elementType);
+    if (fieldCount === 0) {
+      return this.stringifyNumber(arg, params);
+    }
+
+    const structType = this.buildStructType(elementType, fieldCount);
+    const structSize = fieldCount * 8;
+
+    const arrPtr = this.ctx.generateExpression(arg, params);
+
+    this.ctx.setUsesJson(true);
+
+    // Load ObjectArray length (field 1) and data pointer (field 0)
+    const lenPtr = this.ctx.emitGep("%ObjectArray", arrPtr, "i32 0, i32 1");
+    const len = this.ctx.emitLoad("i32", lenPtr);
+    const dataRawPtr = this.ctx.emitGep("%ObjectArray", arrPtr, "i32 0, i32 0");
+    const dataI8 = this.ctx.emitLoad("i8*", dataRawPtr);
+    const dataPtr = this.ctx.emitBitcast(dataI8, "i8*", "i8**");
+
+    // Create yyjson array doc
+    const jsonDoc = this.ctx.emitCall("i8*", "@csyyjson_create_arr", "");
+    const jsonArr = this.ctx.emitCall("i8*", "@csyyjson_mut_get_root", `i8* ${jsonDoc}`);
+
+    // Loop over elements using alloca counter pattern
+    const counterAlloca = this.ctx.nextTemp();
+    this.ctx.emit(`${counterAlloca} = alloca i32`);
+    this.ctx.emitStore("i32", "0", counterAlloca);
+
+    const loopCond = this.ctx.nextLabel("json_arr_loop_cond");
+    const loopBody = this.ctx.nextLabel("json_arr_loop_body");
+    const loopEnd = this.ctx.nextLabel("json_arr_loop_end");
+
+    this.ctx.emitBr(loopCond);
+    this.ctx.emitLabel(loopCond);
+    const i = this.ctx.emitLoad("i32", counterAlloca);
+    const cond = this.ctx.emitIcmp("slt", "i32", i, len);
+    this.ctx.emitBrCond(cond, loopBody, loopEnd);
+
+    this.ctx.emitLabel(loopBody);
+    // Load element pointer: dataPtr[i] is an i8*
+    const elemSlot = this.ctx.emitGep("i8*", dataPtr, `i32 ${i}`);
+    const elemRaw = this.ctx.emitLoad("i8*", elemSlot);
+    const elemTyped = this.ctx.emitBitcast(elemRaw, "i8*", `${structType}*`);
+
+    // Create a sub-object in the JSON array
+    const subObj = this.ctx.emitCall(
+      "i8*",
+      "@csyyjson_mut_arr_add_obj",
+      `i8* ${jsonDoc}, i8* ${jsonArr}`,
+    );
+
+    // Add all fields from this element to the sub-object
+    this.emitAddFieldsToJsonObj(elemTyped, structType, elementType, jsonDoc, subObj);
+
+    // Increment counter
+    const iNext = this.ctx.nextTemp();
+    this.ctx.emit(`${iNext} = add i32 ${i}, 1`);
+    this.ctx.emitStore("i32", iNext, counterAlloca);
+    this.ctx.emitBr(loopCond);
+
+    this.ctx.emitLabel(loopEnd);
 
     const result = this.ctx.emitCall("i8*", "@csyyjson_stringify", `i8* ${jsonDoc}`);
     this.ctx.setVariableType(result, "i8*");
diff --git a/src/compiler.ts b/src/compiler.ts
index 661d1208..6b49f5c2 100644
--- a/src/compiler.ts
+++ b/src/compiler.ts
@@ -79,6 +79,12 @@ let targetOverride: TargetInfo | null = null;
 let extraLinkObjs: string[] = [];
 let extraLinkLibs: string[] = [];
 let extraLinkPaths: string[] = [];
+// Defaults to true when stderr is a real terminal; can be overridden
+let diagnosticColorEnabled: boolean = process.stderr.isTTY === true;
+
+export function setDiagnosticColor(enabled: boolean): void {
+  diagnosticColorEnabled = enabled;
+}
 
 export function setTargetCpu(value: string): void {
   targetCpu = value;
@@ -203,6 +209,7 @@ export function compile(
   if (!skipSemanticAnalysis) {
     logger.info("Running semantic analysis...");
     const analyzer = new SemanticAnalyzer(mergedAST);
+    analyzer.setDiagnosticColor(diagnosticColorEnabled);
     const analysisSuccess = analyzer.analyze();
 
     if (!analysisSuccess) {
@@ -280,6 +287,7 @@ export function compile(
     target,
   };
   const generator = new LLVMGenerator(mergedAST, typeChecker, generatorOptions);
+  generator.diagnostics.setColor(diagnosticColorEnabled);
   const llvmIR = generator.generate();
 
   // Write IR to file
@@ -299,12 +307,13 @@ export function compile(
   const cpuFlag = crossCompiling ? `-mcpu=${target.cpu}` : `-mcpu=${targetCpu}`;
   const tripleFlag = crossCompiling ? ` -mtriple=${target.triple}` : "";
   let compileCmd: string;
+  let optFile: string | null = null;
   if (sanitize) {
     compileCmd = `${linkerPath} -c${sanitizeFlags} ${irFile} -o ${objFile}`;
   } else if (debugInfo) {
     compileCmd = `${llcPath} -O0${tripleFlag} -filetype=obj ${irFile} -o ${objFile}`;
   } else {
-    const optFile = irFile.replace(".ll", ".opt.bc");
+    optFile = irFile.replace(".ll", ".opt.bc");
     const optCmd = `${optPath} -O2 ${cpuFlag}${tripleFlag} ${irFile} -o ${optFile}`;
     logger.info(` ${optCmd}`);
     execSync(optCmd, { stdio: llcStdio });
@@ -457,6 +466,9 @@ export function compile(
   // -no-pie: only for native Linux builds (not macOS, not cross-compiling from macOS)
   const noPie = !targetIsMac && !crossCompiling ? " -no-pie" : "";
   const debugFlag = debugInfo ? " -g" : "";
+  // Strip symbol table from release builds — keeps binaries small and clean.
+  // Skip when -g is set (stripped + debug info produces nothing useful).
+  const stripFlag = !debugInfo && !targetIsMac ? " -s" : "";
   // Cross-compiled Linux binaries always link statically — the SDK's sysroot
   // contains .a archives only (Ubuntu's .so files are linker scripts with
   // hardcoded absolute paths that can't be relocated to a different sysroot).
@@ -472,7 +484,7 @@ export function compile(
   const userObjs = extraLinkObjs.length > 0 ? " " + extraLinkObjs.join(" ") : "";
   const userPaths = extraLinkPaths.map((p) => ` -L${p}`).join("");
   const userLibs = extraLinkLibs.map((l) => ` -l${l}`).join("");
-  const linkCmd = `${linker} ${objFile} ${lwsBridgeObj} ${regexBridgeObj} ${cpBridgeObj} ${osBridgeObj} ${dotenvBridgeObj} ${watchBridgeObj} ${cpSpawnObj}${extraObjs}${userObjs} -o ${outputFile}${noPie}${debugFlag}${staticFlag}${crossTarget}${crossLinker}${sanitizeFlags} ${linkLibs}${userPaths}${userLibs}`;
+  const linkCmd = `${linker} ${objFile} ${lwsBridgeObj} ${regexBridgeObj} ${cpBridgeObj} ${osBridgeObj} ${dotenvBridgeObj} ${watchBridgeObj} ${cpSpawnObj}${extraObjs}${userObjs} -o ${outputFile}${noPie}${debugFlag}${stripFlag}${staticFlag}${crossTarget}${crossLinker}${sanitizeFlags} ${linkLibs}${userPaths}${userLibs}`;
   logger.info(` ${linkCmd}`);
   const linkStdio = logger.getLevel() >= LogLevel.Verbose ? "inherit" : "pipe";
   execSync(linkCmd, { stdio: linkStdio });
@@ -491,6 +503,13 @@ export function compile(
         // File may already be deleted, ignore
       }
     }
+    if (optFile) {
+      try {
+        fs.unlinkSync(optFile);
+      } catch (e) {
+        // File may already be deleted, ignore
+      }
+    }
   }
 
   // Silent on success (like clang)
diff --git a/src/native-compiler-lib.ts b/src/native-compiler-lib.ts
index 1cd7af16..edbbca42 100644
--- a/src/native-compiler-lib.ts
+++ b/src/native-compiler-lib.ts
@@ -76,13 +76,19 @@ function findLLD(): string {
 export let skipSemanticAnalysis = false;
 export let emitLLVMOnly = false;
 export let verbose = false;
+export let debugInfo = false;
 export let targetCpu = "native";
 export let targetTriple = "";
+export let diagnosticColorEnabled = false; // set via setDiagnosticColor() by caller
 // Extra linker flags from --link-obj, --link-lib, --link-path
 export let extraLinkObjs: string[] = [];
 export let extraLinkLibs: string[] = [];
 export let extraLinkPaths: string[] = [];
 
+export function setDiagnosticColor(value: boolean): void {
+  diagnosticColorEnabled = value;
+}
+
 export function setSkipSemanticAnalysis(value: boolean): void {
   skipSemanticAnalysis = value;
 }
@@ -95,6 +101,10 @@ export function setVerbose(value: boolean): void {
   verbose = value;
 }
 
+export function setDebugInfo(value: boolean): void {
+  debugInfo = value;
+}
+
 export function setTargetCpu(value: string): void {
   targetCpu = value;
 }
@@ -193,6 +203,7 @@ export function compileNative(inputFile: string, outputFile: string): void {
       console.log("Running semantic analysis...");
     }
     const analyzer = new SemanticAnalyzer(mergedAST);
+    analyzer.setDiagnosticColor(diagnosticColorEnabled);
     const analysisSuccess = analyzer.analyze();
 
     if (!analysisSuccess) {
@@ -276,6 +287,7 @@ export function compileNative(inputFile: string, outputFile: string): void {
     target: targetInfo,
   };
   const generator = new LLVMGenerator(mergedAST, null, generatorOptions);
+  generator.diagnostics.setColor(diagnosticColorEnabled);
   const irParts = generator.generateParts();
   if (verbose) {
     console.log("Generated IR parts: " + irParts.length);
@@ -459,6 +471,10 @@ export function compileNative(inputFile: string, outputFile: string): void {
   const shouldStatic = !targetIsDarwin && crossCompiling;
   const staticFlag = shouldStatic ? " -static" : "";
   const crossTargetFlag = crossCompiling ? " --target=" + targetTriple : "";
+  const debugFlag = debugInfo ? " -g" : "";
+  // Strip symbol table from release builds. Skipped on macOS (linker handles it
+  // differently) and when -g is set (stripping debug info defeats the purpose).
+  const stripFlag = !debugInfo && !isMac ? " -s" : "";
   // Cross-compiling requires lld — the host linker can't produce foreign binaries.
   // Use full path because Homebrew clang can't find lld by short name.
   // Try ld.lld first (ELF-specific), fall back to lld (multicall binary, auto-detects format).
@@ -501,6 +517,8 @@ export function compileNative(inputFile: string, outputFile: string): void {
     " -o " +
     outputFile +
     noPie +
+    debugFlag +
+    stripFlag +
     staticFlag +
     crossTargetFlag +
     crossLinker +
@@ -517,6 +535,7 @@ export function compileNative(inputFile: string, outputFile: string): void {
   }
 
   fs.unlinkSync(objFile);
+  fs.unlinkSync(optFile);
   if (verbose) {
     console.log("Compiled: " + outputFile);
   }
diff --git a/src/parser-native/transformer.ts b/src/parser-native/transformer.ts
index 19e872dc..cb5a8110 100644
--- a/src/parser-native/transformer.ts
+++ b/src/parser-native/transformer.ts
@@ -746,6 +746,31 @@ function transformStringNode(node: TreeSitterNode): StringNode {
       } else if (next === "'") {
         processed += "'";
         i += 2;
+      } else if (next === "x" && i + 3 < text.length) {
+        // \xHH hex escape — parse two hex digits into a single character
+        const hex = text.substring(i + 2, i + 4);
+        const code = parseInt(hex, 16);
+        if (!isNaN(code)) {
+          processed += String.fromCharCode(code);
+          i += 4;
+        } else {
+          processed += next;
+          i += 2;
+        }
+      } else if (next === "u" && i + 5 < text.length) {
+        // \uHHHH unicode escape — parse four hex digits
+        const hex = text.substring(i + 2, i + 6);
+        const code = parseInt(hex, 16);
+        if (!isNaN(code)) {
+          processed += String.fromCharCode(code);
+          i += 6;
+        } else {
+          processed += next;
+          i += 2;
+        }
+      } else if (next === "0") {
+        processed += "\0";
+        i += 2;
       } else {
         processed += next;
         i += 2;
@@ -1200,7 +1225,16 @@ function transformTemplateString(node: TreeSitterNode): Expression {
       else if (decoded === "\\\\") decoded = "\\";
       else if (decoded === "\\`") decoded = "`";
       else if (decoded === "\\$") decoded = "$";
-      else if (decoded.length === 2 && decoded.charAt(0) === "\\") decoded = decoded.charAt(1);
+      else if (decoded === "\\0") decoded = "\0";
+      else if (decoded.length === 4 && decoded.startsWith("\\x")) {
+        // \xHH hex escape
+        const code = parseInt(decoded.substring(2, 4), 16);
+        decoded = !isNaN(code) ? String.fromCharCode(code) : decoded.charAt(1);
+      } else if (decoded.length === 6 && decoded.startsWith("\\u")) {
+        // \uHHHH unicode escape
+        const code = parseInt(decoded.substring(2, 6), 16);
+        decoded = !isNaN(code) ? String.fromCharCode(code) : decoded.charAt(1);
+      } else if (decoded.length === 2 && decoded.charAt(0) === "\\") decoded = decoded.charAt(1);
       parts.push({ type: "string", value: decoded } as Expression);
     } else if (c.type === "template_substitution") {
       hasSubstitutions = true;
diff --git a/tests/fixtures/builtins/json-stringify-array-test.ts b/tests/fixtures/builtins/json-stringify-array-test.ts
new file mode 100644
index 00000000..e3919d77
--- /dev/null
+++ b/tests/fixtures/builtins/json-stringify-array-test.ts
@@ -0,0 +1,17 @@
+// Test JSON.stringify on an array of typed objects
+interface Item {
+  name: string;
+  value: number;
+}
+
+const items: Item[] = [
+  { name: "alpha", value: 1 },
+  { name: "beta", value: 2 },
+  { name: "gamma", value: 3 },
+];
+
+const json = JSON.stringify(items);
+
+if (json.includes("alpha") && json.includes("beta") && json.includes("gamma")) {
+  console.log("TEST_PASSED");
+}
diff --git a/tests/fixtures/strings/string-fromcharcode.ts b/tests/fixtures/strings/string-fromcharcode.ts
new file mode 100644
index 00000000..a9b35ee1
--- /dev/null
+++ b/tests/fixtures/strings/string-fromcharcode.ts
@@ -0,0 +1,7 @@
+// @test-description: String.fromCharCode produces correct characters
+const a = String.fromCharCode(65);
+const b = String.fromCharCode(66);
+const newline = String.fromCharCode(10);
+if (a === "A" && b === "B" && newline === "\n") {
+  console.log("TEST_PASSED");
+}