Separate LLVM package documentation from the live docs

.gitignore

@@ -9,8 +9,6 @@
 # Releases authenticate with short-lived OIDC credentials.
 .npmrc
 
-# Generated TSDoc API pages
-apps/docs/content/*-api/
 /apps/docs/.next/
 /apps/docs/next-env.d.ts
 /apps/docs/tsconfig.tsbuildinfo

apps/docs/README.md

@@ -1,39 +1,26 @@
 # `@silk-lang/docs`
 
-The documentation site for every package in this monorepo. Next.js + Fumadocs + Tailwind.
+The live documentation site for the Silk language and compiler. Next.js + Fumadocs + Tailwind.
 
 ```sh
 pnpm dev
 ```
 
 Run this from the repository root so Turbo also watches the local packages consumed by the app.
 
-## How content gets here
+## Content
 
-Package documentation is **read in place** — nothing is copied into this app, so
-`packages/<pkg>/docs` stays the single source of truth and keeps shipping to npm and rendering on
-GitHub.
+The language and compiler documentation is read in place from `packages/language/docs`; nothing is
+copied into this app. The `content/language` symlink keeps the package directory as the single
+source of truth while exposing it to Fumadocs at `/docs/language/**`.
 
-| URL                | Source                                                     |
-| ------------------ | ---------------------------------------------------------- |
-| `/docs/llvm/**`    | `content/llvm` → symlink to `packages/llvm/docs`            |
-| `/docs/llvm-api/**`| `content/llvm-api` → TSDoc generated by `pnpm api` (ignored) |
+The standalone `@silk-lang/llvm` package has its own Markdown documentation, indexed from
+[`packages/llvm/README.md`](../../packages/llvm/README.md). It is deliberately not published on
+this site because it documents using the LLVM library independently of the Silk language.
 
-Package docs are plain Markdown with no frontmatter. [`lib/source.ts`](lib/source.ts) derives each
-page title from its leading `# H1` (falling back to the file name), so no package has to carry
-site-specific frontmatter.
+These docs are plain Markdown with no frontmatter. [`lib/source.ts`](lib/source.ts) derives each
+page title from its leading `# H1` (falling back to the file name), so the source stays useful both
+on the site and on GitHub.
 
-## Adding a package
-
-1. `ln -s ../../../packages/<pkg>/docs content/<pkg>`
-2. Add `../../packages/<pkg>/src/*.ts` to `entryPoints` in [`typedoc.json`](typedoc.json), pointing
-   `out` at `content/<pkg>-api`.
-3. Add a sidebar label in `folderTitles` in [`lib/source.ts`](lib/source.ts) and list the folders in
-   [`content/meta.json`](content/meta.json).
-
-## TypeScript note
-
-The repo builds on TypeScript 7, which TypeDoc does not support yet — TS 7 no longer exposes the
-`SyntaxKind` enum object TypeDoc reads. This app therefore pins `typescript@5.9.3` as a dev
-dependency, used **only** by TypeDoc to parse package sources. Next.js and the repo build are
-unaffected.
+The app pins TypeScript 5.9 because Next.js does not yet support the compiler API exposed by the
+repository's TypeScript 7 toolchain.

apps/docs/content/meta.json

@@ -1,3 +1,3 @@
 {
-  "pages": ["language", "llvm", "llvm-api"]
+  "pages": ["language"]
 }

apps/docs/lib/source.ts

@@ -5,8 +5,8 @@ import { TextMate } from '@silk-lang/language';
 import { remarkH1Title } from './remark-h1-title.mjs';
 
 /**
- * Package docs and generated TSDoc are plain Markdown with no frontmatter — they ship to npm and
- * are read on GitHub, where a frontmatter block would render as noise.
+ * The language and compiler docs are plain Markdown with no frontmatter — they also ship with
+ * `@silk-lang/language` and render on GitHub, where a frontmatter block would be noise.
  *
  * Frontmatter is validated before remark runs, so the title falls back to the file name here and
  * `remarkH1Title` upgrades it to the document's `# H1`. An author-written title always wins.
@@ -25,14 +25,11 @@ function fallbackTitle(path: string): string {
   return words.charAt(0).toUpperCase() + words.slice(1);
 }
 
-// ponytail: one collection over `content/`, which is entirely symlinks + generated output.
-// Loader record keys are type discriminators, not slug prefixes, so namespacing per package has
-// to come from the directory layout:
+// ponytail: one collection over `content/`, whose language directory is a symlink to the package
+// documentation. Loader record keys are type discriminators, not slug prefixes, so namespacing
+// comes from the directory layout:
 //
-//   content/<pkg>      -> symlink to packages/<pkg>/docs  (read in place, never copied)
-//   content/<pkg>-api  -> typedoc markdown from `pnpm api` (gitignored)
-//
-// Adding a package is one symlink plus one entryPoints line in typedoc.json — no code change.
+//   content/language -> symlink to packages/language/docs (read in place, never copied)
 const docs = defineDocs({
   dir: './content',
   docs: {
@@ -57,7 +54,6 @@ const docs = defineDocs({
 /** Sidebar label for each top-level content folder, keyed by directory name. */
 const folderTitles: Record<string, string> = {
   language: '@silk-lang/language',
-  llvm: '@silk-lang/llvm',
 };
 
 export const source = loader({
@@ -74,7 +70,7 @@ export const source = loader({
     ],
   },
   // Package docs use `README.md` as their entry (that's what GitHub and npm render), where
-  // Fumadocs expects `index.md`. Treat them the same so `/docs/llvm` resolves.
+  // Fumadocs expects `index.md`. Treat them the same so `/docs/language` resolves.
   slugs(file) {
     const slugs = getSlugs(file.path);
     return slugs.at(-1) === 'README' ? slugs.slice(0, -1) : undefined;

apps/docs/package.json

@@ -4,13 +4,12 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "api": "typedoc && node scripts/label-api-folders.mjs",
-    "build": "pnpm api && next build",
+    "build": "next build",
     "clean": "node -e \"require('node:fs').rmSync('.next', { recursive: true, force: true })\"",
-    "dev": "pnpm api && next dev",
+    "dev": "next dev",
     "start": "next start",
     "test": "vitest run",
-    "typecheck": "pnpm api && next typegen && tsc --noEmit"
+    "typecheck": "next typegen && tsc --noEmit"
   },
   "dependencies": {
     "@codemirror/commands": "^6.10.4",
@@ -42,7 +41,6 @@
   "devDependencies": {
     "@effect/vitest": "catalog:",
     "@silk-lang/formatter": "workspace:*",
-    "@silk-lang/llvm": "workspace:*",
     "@silk-lang/wasm": "workspace:*",
     "@tailwindcss/postcss": "^4.3.3",
     "@types/mdast": "^4.0.4",
@@ -52,8 +50,6 @@
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.24",
     "tailwindcss": "^4.3.3",
-    "typedoc": "^0.28.20",
-    "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "5.9.3"
   }
 }

apps/docs/turbo.json

@@ -6,10 +6,10 @@
       "dependsOn": ["^build"],
       "inputs": [
         "$TURBO_DEFAULT$",
-        "$TURBO_ROOT$/packages/*/docs/**",
+        "$TURBO_ROOT$/packages/language/docs/**",
         "$TURBO_ROOT$/packages/*/src/**"
       ],
-      "outputs": [".next/**", "!.next/cache/**", "content/*-api/**"]
+      "outputs": [".next/**", "!.next/cache/**"]
     },
     "dev": {
       "dependsOn": ["^build"]

packages/llvm/README.md

@@ -90,12 +90,36 @@ const recovered = Type.integer(builder, 0).pipe(
 
 ## Documentation
 
-- [Build Tiny, a compiled language](./docs/tutorials/tiny-language/01-meet-tiny.md)
-- [Build a tiny expression compiler](./docs/tutorials/tiny-expression-compiler.md)
-- [How-to guides](./docs/README.md#solve-a-task)
+The package documentation is ordinary Markdown kept alongside the code and shipped in the npm
+package. Start from the track that matches what you need:
+
+### Learn by building
+
+- [Build Tiny, a compiled language](./docs/tutorials/tiny-language/01-meet-tiny.md) — a 13-lesson
+  path from source text to a native executable.
+- [Build a tiny expression compiler](./docs/tutorials/tiny-expression-compiler.md) — a shorter
+  path for readers already familiar with compiler frontends.
+
+### Solve a task
+
+- [Declare globals, aliases, and functions](./docs/how-to/declarations.md)
+- [Build branching control flow](./docs/how-to/control-flow.md)
+- [Emit memory, atomic, and intrinsic operations](./docs/how-to/memory-atomics-intrinsics.md)
+- [Add debug metadata](./docs/how-to/debug-metadata.md)
+- [Emit and validate LLVM output](./docs/how-to/output.md)
+
+### Look up behavior
+
 - [Actor reference](./docs/reference/actors.md)
 - [Behavior and guarantees](./docs/reference/behavior.md)
-- [Design explanations](./docs/README.md#understand-the-design)
+
+### Understand the design
+
+- [Why the builder is Effect-native](./docs/explanation/effect-native-builder.md)
+- [Why text and bitcode share one model](./docs/explanation/text-and-bitcode.md)
+
+The [documentation index](./docs/README.md) provides the same paths from within the `docs`
+directory.
 
 The package is organized as actor modules with explicit subpath exports. Prefer imports such as
 `@silk-lang/llvm/Builder` and `@silk-lang/llvm/FunctionBody` over a growing import from the root