feat(docs): polish introduction page

docs-site/app/docs/[[...slug]]/page.tsx

@@ -17,6 +17,10 @@ function isDocsIndex(slug: string[] | undefined) {
   return slug === undefined || slug.length === 0 || slug.join("/") === "";
 }
 
+function isHeroPage(slug: string[] | undefined) {
+  return slug?.join("/") === "getting-started/introduction";
+}
+
 export default async function Page(props: {
   params: Promise<{ slug?: string[] }>;
 }) {
@@ -30,14 +34,22 @@ export default async function Page(props: {
 
   const MDX = page.data.body;
 
+  const hero = isHeroPage(params.slug);
+
   return (
     <DocsPage toc={page.data.toc}>
-      <DocsTitle>{page.data.title}</DocsTitle>
-      <DocsDescription>{page.data.description}</DocsDescription>
-      <DocsPageActions
-        markdownUrl={`${page.url}.md`}
-        mdxSource={page.data.content}
-      />
+      {!hero && (
+        <>
+          <div className="flex items-start justify-between gap-4">
+            <DocsTitle>{page.data.title}</DocsTitle>
+            <DocsPageActions
+              markdownUrl={`${page.url}.md`}
+              mdxSource={page.data.content}
+            />
+          </div>
+          <DocsDescription>{page.data.description}</DocsDescription>
+        </>
+      )}
       <DocsBody>
         <MDX components={{ ...defaultMdxComponents, pre: CodeBlock }} />
       </DocsBody>

docs-site/app/global.css

@@ -262,6 +262,74 @@ figure[data-rehype-pretty-code-figure]:has(.ktx-code) {
   color: #c8c3bc !important;
 }
 
+/* ── Mode D: Output preview (wizard prompts, status output) ── */
+.ktx-code-output {
+  background: var(--color-fd-muted);
+  border: 1px solid var(--color-fd-border);
+  border-left: 3px solid color-mix(in oklch, var(--color-fd-primary) 50%, var(--color-fd-border));
+  position: relative;
+  box-shadow: 0 1px 2px rgba(27, 27, 24, 0.02);
+}
+
+.dark .ktx-code-output {
+  background: #111a1e;
+  border-color: rgba(255, 255, 255, 0.05);
+  border-left-color: rgba(34, 211, 238, 0.25);
+}
+
+.ktx-code-output:hover {
+  border-color: color-mix(in oklch, var(--color-fd-primary) 25%, var(--color-fd-border));
+  border-left-color: var(--color-fd-primary);
+}
+
+.dark .ktx-code-output:hover {
+  border-color: rgba(255, 255, 255, 0.08);
+  border-left-color: rgba(34, 211, 238, 0.45);
+}
+
+.ktx-code-output-label {
+  position: absolute;
+  top: 8px;
+  right: 14px;
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-fd-muted-foreground);
+  font-family: var(--font-display), var(--font-sans), sans-serif;
+  opacity: 0.4;
+  pointer-events: none;
+  z-index: 1;
+}
+
+.ktx-code-output-copy {
+  position: absolute !important;
+  top: 6px !important;
+  right: 6px !important;
+  opacity: 0;
+  transform: translateY(-4px);
+  transition: opacity 0.2s var(--ktx-ease), transform 0.2s var(--ktx-ease);
+  z-index: 2;
+}
+
+.ktx-code-output:hover .ktx-code-output-copy {
+  opacity: 0.5;
+  transform: translateY(0);
+}
+
+.ktx-code-output:hover .ktx-code-output-label {
+  opacity: 0;
+}
+
+.ktx-code-body-output {
+  background: transparent !important;
+  color: var(--ktx-ink-soft) !important;
+}
+
+.dark .ktx-code-body-output {
+  color: #8a9da6 !important;
+}
+
 /* ── Mode B: VS Code tab (filename) ───────── */
 .ktx-code-tab {
   background: var(--color-fd-card);
@@ -495,14 +563,20 @@ th {
   opacity: 0.7;
 }
 
+/* Hide the vertical indicator lines in sidebar sections */
+#nd-sidebar div[data-state]::before,
+#nd-sidebar a[data-active]::before {
+  content: none !important;
+  display: none !important;
+}
+
 /* Page link items */
 #nd-sidebar a[data-active] {
   font-size: 14px;
   padding: 6px 12px;
   border-radius: 6px;
   margin-left: 0;
-  border-left: 2px solid transparent;
-  transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+  transition: background 0.15s ease, color 0.15s ease;
 }
 
 #nd-sidebar a[data-active="false"]:hover {
@@ -512,7 +586,6 @@ th {
 
 #nd-sidebar a[data-active="true"] {
   background: color-mix(in oklch, var(--color-fd-primary) 8%, transparent) !important;
-  border-left-color: var(--color-fd-primary) !important;
   color: var(--color-fd-primary) !important;
   font-weight: 500;
 }

docs-site/components/code-block.tsx

@@ -52,12 +52,11 @@ export function CodeBlock(props: Props) {
   const language = detectLanguage(props, children);
   const codeText = extractText(children);
 
-  const isTerminal =
-    (language !== null && TERMINAL_LANGS.has(language)) ||
-    WIZARD_GLYPHS.test(codeText);
+  const isTerminal = language !== null && TERMINAL_LANGS.has(language);
+  const isOutput = !isTerminal && WIZARD_GLYPHS.test(codeText);
   const hasTitle = typeof title === "string" && title.length > 0;
 
-  // Mode A — Terminal
+  // Mode A — Terminal (commands the user types)
   if (isTerminal) {
     return (
       <div className="not-prose ktx-code ktx-code-terminal group">
@@ -80,6 +79,19 @@ export function CodeBlock(props: Props) {
     );
   }
 
+  // Mode D — Output preview (wizard prompts, terminal output)
+  if (isOutput) {
+    return (
+      <div className="not-prose ktx-code ktx-code-output group relative">
+        <span className="ktx-code-output-label">output</span>
+        <CopyButton text={codeText} className="ktx-code-output-copy" />
+        <pre {...rest} className="ktx-code-body ktx-code-body-output">
+          {children}
+        </pre>
+      </div>
+    );
+  }
+
   // Mode B — VS Code tab (filename present)
   if (hasTitle) {
     return (

docs-site/components/docs-page-actions.tsx

@@ -11,7 +11,7 @@ type Props = {
 
 export function DocsPageActions({ markdownUrl, mdxSource }: Props) {
   return (
-    <div className="not-prose mt-4 mb-8 flex flex-wrap items-center gap-2 border-b border-fd-border pb-6 text-xs">
+    <div className="not-prose flex flex-wrap items-center gap-2 text-xs">
       <CopyMarkdownButton markdownUrl={markdownUrl} />
       <a
         href={markdownUrl}

docs-site/content/docs/getting-started/introduction.mdx

@@ -1,71 +1,86 @@
 ---
 title: Introduction
-description: What KTX is and who it's for.
+description: How KTX gives analytics agents trusted context for warehouse work.
 ---
 
-Data agents can write SQL. The hard part is making sure they write the SQL your analytics team would have written.
-
-KTX is the agent-native context layer for analytics engineering. At its core is a semantic layer: YAML sources that define tables, columns, measures, joins, grain, filters, segments, and computed fields. Around that core, KTX adds the context analytics agents need to work safely: warehouse scans, knowledge pages, ingestion from existing tools, provenance, validation, and MCP access.
-
-KTX projects are plain files — YAML, Markdown, and SQLite — that you commit to git and review in PRs, just like dbt models. Agents can read them, edit them, validate them, query through them, and leave behind a diff your team can review.
+<div className="not-prose mb-14">
+  <div className="mb-8">
+    <h1
+      className="text-4xl font-extrabold tracking-tight lg:text-5xl"
+      style={{
+        fontFamily: 'var(--font-display)',
+        background: 'linear-gradient(180deg, var(--color-fd-foreground) 0%, color-mix(in oklch, var(--color-fd-foreground) 75%, var(--color-fd-primary)) 100%)',
+        WebkitBackgroundClip: 'text',
+        backgroundClip: 'text',
+        color: 'transparent',
+        WebkitTextFillColor: 'transparent',
+        lineHeight: '1.1',
+        letterSpacing: '0',
+      }}
+    >
+      Make analytics context{'\n'}usable by agents
+    </h1>
+    <p className="mt-4 text-lg text-fd-muted-foreground max-w-2xl" style={{ lineHeight: '1.7' }}>
+      KTX turns warehouse metadata, semantic definitions, and business knowledge
+      into reviewable project files that agents can use while planning, querying,
+      and updating analytics work.
+    </p>
+  </div>
+  <div className="flex flex-wrap gap-3">
+    <a
+      href="/docs/getting-started/quickstart"
+      className="inline-flex h-10 items-center rounded-lg bg-fd-primary px-5 text-sm font-medium text-fd-primary-foreground transition-colors hover:opacity-90"
+    >
+      Get Started
+    </a>
+    <a
+      href="/docs/concepts/the-context-layer"
+      className="inline-flex h-10 items-center rounded-lg border border-fd-border bg-fd-background px-5 text-sm font-medium text-fd-foreground transition-colors hover:bg-fd-muted"
+    >
+      The Context Layer
+    </a>
+    <a
+      href="/docs/guides/building-context"
+      className="inline-flex h-10 items-center rounded-lg border border-fd-border bg-fd-background px-5 text-sm font-medium text-fd-foreground transition-colors hover:bg-fd-muted"
+    >
+      Building Context
+    </a>
+  </div>
+</div>
 
 ## Who KTX is for
 
-KTX is built for analytics engineers and data teams who want data agents to work on real analytics systems, not just generate one-off SQL.
+KTX is built for analytics engineers and data teams who want data agents to
+work on real analytics systems — not just generate one-off SQL.
 
 Use KTX when you want agents to:
 
-- Generate SQL from approved measures, dimensions, and joins
-- Repair or extend semantic definitions through reviewable git diffs
-- Explain where a metric definition came from and what business rules shape it
-- Use warehouse scans and relationship evidence instead of guessing join paths
-- Work alongside **dbt**, **LookML**, **MetricFlow**, **Looker**, **Metabase**, **Notion**, and BI platforms
-- Work with warehouses like **PostgreSQL**, **Snowflake**, **BigQuery**, **ClickHouse**, **MySQL**, or **SQL Server**
+- **Generate SQL** from approved measures and joins
+- **Repair semantic definitions** through reviewable diffs
+- **Explain metric provenance** with warehouse evidence
+- **Work alongside** dbt, LookML, MetricFlow, Looker, Metabase, and modern BI platforms
 
-If you've ever watched an agent confidently generate a query that joins on the wrong key or invents a metric that doesn't exist, KTX is the fix.
+Works with PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, and SQL Server.
 
-## What KTX gives agents
-
-- **A semantic layer they can edit** — plain YAML sources with measures, dimensions, joins, grain, segments, filters, and computed columns
-- **Safe query planning** — grain-aware SQL generation, fan-out detection, chasm-trap handling, and dialect transpilation
-- **Business context** — Markdown knowledge pages for definitions, rules, exceptions, and data quality notes
-- **Schema evidence** — warehouse scans with table metadata, column stats, constraints, and inferred relationships
-- **Provenance** — ingest transcripts and replay metadata that explain where context came from and why it changed
-- **An agent-facing API** — MCP and CLI tools for reading, writing, validating, searching, and querying context
-
-## How these docs are organized
+## Explore the docs
 
 <Cards>
   <Card title="Quickstart" href="/docs/getting-started/quickstart">
     Set up KTX and build your first context in under 10 minutes.
   </Card>
-  <Card title="AI Resources" href="/docs/ai-resources">
-    Machine-readable docs and prompt recipes for coding assistants.
-  </Card>
   <Card title="Concepts" href="/docs/concepts/the-context-layer">
-    Understand what a context layer is, why agents need one, and how KTX compares to other semantic layers.
+    Understand what a context layer is and why agents need one.
   </Card>
   <Card title="Guides" href="/docs/guides/building-context">
-    Hands-on workflows for scanning, ingesting, writing semantic sources, and serving agents.
-  </Card>
-  <Card title="Integrations" href="/docs/integrations/primary-sources">
-    Setup details for every supported database, context source, and agent client.
+    Hands-on workflows for scanning, ingesting, writing, and serving.
   </Card>
   <Card title="CLI Reference" href="/docs/cli-reference/ktx-setup">
-    Exhaustive flag and subcommand reference for every KTX command.
+    Complete flag and subcommand reference for every KTX command.
   </Card>
 </Cards>
 
-## Next steps
-
-- **Get hands-on** — follow the [Quickstart](/docs/getting-started/quickstart) to set up KTX with your own database in under 10 minutes.
-- **Help a coding agent use the docs** — start with [AI Resources](/docs/ai-resources) or fetch [`/llms.txt`](/llms.txt).
-- **Understand the theory** — read [The Context Layer](/docs/concepts/the-context-layer) to learn why schema access alone breaks on real analytics and how KTX addresses it.
-
 ## Agent usage notes
 
-Use this page as the high-level routing document for KTX docs.
-
 | Agent task | Read next |
 |------------|-----------|
 | Discover machine-readable docs | [AI Resources](/docs/ai-resources) |