From c9c916a73abf3d67e4bbb1258cb13e28bbe92074 Mon Sep 17 00:00:00 2001
From: Justin Levine <20596508+jal-co@users.noreply.github.com>
Date: Tue, 2 Jun 2026 22:57:45 -0700
Subject: [PATCH] docs: promote distribution to its own section

Move github-registries out of CLI into a new Distribution section and add
a companion hosted page, so the two distribution models read as peer
concepts rather than CLI command reference.

- New www/content/docs/distribution/ with hosted.mdx + github-registries.mdx
- Update root + cli nav meta
- Repoint all inbound links (index, options, prompts, README) to
  /docs/distribution/github-registries
---
 README.md                                     |  2 +-
 www/content/docs/cli/meta.json                |  2 +-
 www/content/docs/cli/options.mdx              |  4 +-
 www/content/docs/cli/prompts.mdx              |  2 +-
 .../github-registries.mdx                     |  4 +-
 www/content/docs/distribution/hosted.mdx      | 65 +++++++++++++++++++
 www/content/docs/distribution/meta.json       |  4 ++
 www/content/docs/index.mdx                    |  2 +-
 www/content/docs/meta.json                    |  2 +
 9 files changed, 79 insertions(+), 8 deletions(-)
 rename www/content/docs/{cli => distribution}/github-registries.mdx (96%)
 create mode 100644 www/content/docs/distribution/hosted.mdx
 create mode 100644 www/content/docs/distribution/meta.json

diff --git a/README.md b/README.md
index 678ff3a..53527d7 100644
--- a/README.md
+++ b/README.md
@@ -59,7 +59,7 @@ Turn a public GitHub repo into a registry. Users install with `npx shadcn add <o
 npx create-scn-stack my-toolkit --github acme/toolkit
 ```
 
-Commit and push is the publish step. See [GitHub Registries](https://scnstack.sh/docs/cli/github-registries).
+Commit and push is the publish step. See [GitHub Registries](https://scnstack.sh/docs/distribution/github-registries).
 
 ### Add to an existing project
 
diff --git a/www/content/docs/cli/meta.json b/www/content/docs/cli/meta.json
index 663f066..cd9bfa9 100644
--- a/www/content/docs/cli/meta.json
+++ b/www/content/docs/cli/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "CLI",
-  "pages": ["options", "init", "github-registries", "eject", "prompts"]
+  "pages": ["options", "init", "eject", "prompts"]
 }
diff --git a/www/content/docs/cli/options.mdx b/www/content/docs/cli/options.mdx
index aa21221..ba6c746 100644
--- a/www/content/docs/cli/options.mdx
+++ b/www/content/docs/cli/options.mdx
@@ -27,7 +27,7 @@ When you run `npx create-scn-stack`, you'll be guided through these options:
 |--------|-------------|---------|
 | **Registry name** | Identifier for your registry (e.g., `my-ui`) | `my-ui` |
 | **Project location** | Folder to create the registry in | `./<registry-name>` |
-| **Distribution** | Hosted (build + host) or [GitHub source registry](/docs/cli/github-registries) | `Hosted` |
+| **Distribution** | [Hosted](/docs/distribution/hosted) (build + host) or [GitHub source registry](/docs/distribution/github-registries) | `Hosted` |
 | **GitHub repo** | `owner/repo` slug (GitHub target only) | — |
 | **Style** | shadcn/ui style variant | `New York` |
 | **Homepage** | URL where the registry will be hosted | `https://<name>.com` |
@@ -55,7 +55,7 @@ npx create-scn-stack my-ui --yes --no-skills
 | `--style <style>` | `new-york` \| `default` |
 | `--homepage <url>` | Registry homepage URL |
 | `--target <target>` | `hosted` \| `github` (default: `hosted`) |
-| `--github [owner/repo]` | Shorthand for `--target github` — see [GitHub registries](/docs/cli/github-registries) |
+| `--github [owner/repo]` | Shorthand for `--target github` — see [GitHub registries](/docs/distribution/github-registries) |
 | `--github-slug <slug>` | `owner/repo` for GitHub source registries |
 | `--framework <fw>` | `nextjs` \| `vite` \| `react-router` \| `tanstack-start` |
 | `--docs <engine>` | `fumadocs` \| `mintlify` \| `starlight` \| `none` |
diff --git a/www/content/docs/cli/prompts.mdx b/www/content/docs/cli/prompts.mdx
index 31d7b14..3460500 100644
--- a/www/content/docs/cli/prompts.mdx
+++ b/www/content/docs/cli/prompts.mdx
@@ -42,7 +42,7 @@ build step, and a homepage URL. **GitHub** produces a minimal repo that *is*
 the registry — users install with `npx shadcn add <owner>/<repo>/<item>` and
 there's no build or server. Picking GitHub asks for an `owner/repo` slug and
 skips the framework, docs, namespace, and monorepo prompts. See
-[GitHub Registries](/docs/cli/github-registries).
+[GitHub Registries](/docs/distribution/github-registries).
 
 ### Style
 
diff --git a/www/content/docs/cli/github-registries.mdx b/www/content/docs/distribution/github-registries.mdx
similarity index 96%
rename from www/content/docs/cli/github-registries.mdx
rename to www/content/docs/distribution/github-registries.mdx
index 81b9474..24e2297 100644
--- a/www/content/docs/cli/github-registries.mdx
+++ b/www/content/docs/distribution/github-registries.mdx
@@ -118,5 +118,5 @@ npx create-scn-stack add-component input
 | Install form | `@ns/item` or URL | `owner/repo/item` |
 | Publish step | deploy | `git push` |
 
-Pick **hosted** when you want docs, previews, and a branded site. Pick
-**GitHub** when you just want to share items from a repo.
+Pick [**hosted**](/docs/distribution/hosted) when you want docs, previews, and
+a branded site. Pick **GitHub** when you just want to share items from a repo.
diff --git a/www/content/docs/distribution/hosted.mdx b/www/content/docs/distribution/hosted.mdx
new file mode 100644
index 0000000..c8873a8
--- /dev/null
+++ b/www/content/docs/distribution/hosted.mdx
@@ -0,0 +1,65 @@
+---
+title: Hosted Registry
+description: The classic shadcn build-and-host model — a framework app builds your registry JSON and serves it from a URL.
+---
+
+A **hosted registry** is the default distribution model. `create-scn-stack`
+scaffolds a framework app that builds your `registry.json` into static JSON
+files and serves them from a homepage URL. Users install via a namespace
+handle or the full registry URL.
+
+```bash
+# Default target — no extra flags needed
+npx create-scn-stack my-ui
+```
+
+Pick hosted when you want a branded docs site, live component previews, v0
+integration, and full control over where the registry lives. If you only want
+to share items from a public repo with no build step, use a
+[GitHub source registry](/docs/distribution/github-registries) instead.
+
+## How it works
+
+1. You author items in `registry/<style>/ui/` and declare them in
+   `registry.json` (via the `include` pattern).
+2. `shadcn build` (or the `registry:build` script) generates static JSON files
+   into `public/r/`.
+3. Your framework app serves those files from your homepage URL.
+4. Users install with the shadcn CLI.
+
+```bash
+# Build the registry output
+npm run registry:build
+
+# Users install via namespace…
+npx shadcn@latest add @my-ui/button
+
+# …or the full URL
+npx shadcn@latest add https://my-ui.com/r/button.json
+```
+
+## What you get
+
+A hosted scaffold wires up the pieces a GitHub source registry intentionally
+skips:
+
+- A **framework** app shell — see [Frameworks](/docs/frameworks)
+  (Next.js, Vite, React Router, TanStack Start).
+- A **docs engine** — see [Docs Engines](/docs/docs-engines)
+  (Fumadocs, Mintlify, Starlight).
+- A `registry:build` script and `public/r/` output.
+- A **namespace** (e.g. `@my-ui`) for short install handles.
+- Component previews, v0 integration, and `llms.txt`.
+
+See [Project Structure](/docs/project-structure) for the full layout, and the
+[options reference](/docs/cli/options) for every prompt and flag.
+
+## Publishing
+
+Deploy the app anywhere (Vercel, Netlify, Cloudflare, self-hosted). Each time
+you add or change an item, rebuild and redeploy so `public/r/` stays in sync.
+
+## Hosted vs GitHub
+
+For a side-by-side comparison of the two distribution models, see
+[Hosted vs GitHub](/docs/distribution/github-registries#hosted-vs-github).
diff --git a/www/content/docs/distribution/meta.json b/www/content/docs/distribution/meta.json
new file mode 100644
index 0000000..51902c8
--- /dev/null
+++ b/www/content/docs/distribution/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Distribution",
+  "pages": ["hosted", "github-registries"]
+}
diff --git a/www/content/docs/index.mdx b/www/content/docs/index.mdx
index 15fcbd4..4c93744 100644
--- a/www/content/docs/index.mdx
+++ b/www/content/docs/index.mdx
@@ -22,7 +22,7 @@ Follow the interactive prompts to configure your registry. Or skip prompts entir
 npx create-scn-stack my-ui --yes
 ```
 
-Want to share items straight from a public repo with **no build, no host, and no server**? Scaffold a [GitHub source registry](/docs/cli/github-registries) instead — users install with `npx shadcn add <owner>/<repo>/<item>`:
+Want to share items straight from a public repo with **no build, no host, and no server**? Scaffold a [GitHub source registry](/docs/distribution/github-registries) instead — users install with `npx shadcn add <owner>/<repo>/<item>`:
 
 ```bash
 npx create-scn-stack my-toolkit --github acme/toolkit
diff --git a/www/content/docs/meta.json b/www/content/docs/meta.json
index 379a53c..85ee207 100644
--- a/www/content/docs/meta.json
+++ b/www/content/docs/meta.json
@@ -2,6 +2,8 @@
   "title": "scn-stack",
   "pages": [
     "index",
+    "---Distribution---",
+    "...distribution",
     "---CLI---",
     "...cli",
     "---Output---",