diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 0000000..282c3f6
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,85 @@
+---
+title: The lectio CLI
+description: One command — collect your docs and get a searchable site
+---
+
+# The `lectio` CLI
+
+The `lectio-docs` package ships a `lectio` command that turns a repo's markdown
+into a static, searchable docs site — with no app code to write.
+
+```sh
+npx lectio-docs dev     # collect + serve locally, with live reload on the UI
+npx lectio-docs build   # collect + build a static site into ./dist
+```
+
+> The npm package is `lectio-docs`; the command it installs is `lectio`. Once
+> it's a dependency of your repo you can run `lectio dev` / `lectio build`
+> directly.
+
+## Try it in seconds
+
+Run `dev` in any repo that has markdown in it:
+
+```sh
+npx lectio-docs dev
+```
+
+With no `docs.config` present, it writes a starter one (matching `**/*.md`) and
+opens a local server, so you see your docs as a site immediately. Edit the
+generated `docs.config.ts` and re-run.
+
+## Configure your sources
+
+A `docs.config.ts` (or `.js` / `.mjs`) at the repo root describes what to gather
+and how to brand it:
+
+```ts
+export default {
+  output: '.lectio',
+  sources: [
+    { glob: 'docs/**/*.md', target: '/' },
+    {
+      glob: 'libs/*/README.md',
+      target: '/libraries',
+      titleFromPackageJson: true,
+      sectionTitle: 'Libraries',
+    },
+  ],
+  editUrl: 'https://github.com/your-org/your-repo/edit/main/{path}',
+  site: {
+    title: 'Developer Docs',
+    githubUrl: 'https://github.com/your-org/your-repo',
+  },
+};
+```
+
+- **`sources`** — each is a glob plus the `target` path it mounts under. Globs
+  are relative to where you run the command; `node_modules`, `dist`, `.next` and
+  dotfiles are skipped automatically.
+- **`editUrl`** — an "edit this page" link template; `{path}` is filled per page.
+- **`site`** — the title and GitHub link shown in the header.
+
+See [Configuration](/guides/configuration) for how targets become slugs.
+
+## Build and deploy
+
+```sh
+npx lectio-docs build
+```
+
+This prerenders every page to static HTML in `./dist`, with a search index at
+`/search-index.json`. Deploy `dist/` to any static host — Cloudflare Pages,
+Netlify, GitHub Pages, an object store:
+
+```sh
+# Cloudflare Pages, for example
+npx wrangler pages deploy dist --project-name my-docs
+```
+
+## `dev` vs `build` when there's no config
+
+- **`dev`** scaffolds a starter `docs.config.ts` and runs — it's the on-ramp for
+  trying things out.
+- **`build`** never writes files on its own: it asks first when interactive, and
+  errors in CI. A build stays deterministic.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index f66b2e6..15be412 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,14 +1,31 @@
 ---
 title: Getting started
-description: Collect scattered docs into a single content tree
+description: Two ways to turn scattered docs into a site
 ---
 
 # Getting started
 
-Point the collector at the places your documentation already lives, then read it
-back through the content source.
+There are two ways to use Lectio, depending on how much control you want.
 
-## 1. Describe your sources
+## The fast path — the CLI
+
+If you just want a docs site, the `lectio` CLI collects your markdown and builds
+it for you. No app code:
+
+```sh
+npx lectio-docs dev
+```
+
+It scaffolds a starter `docs.config.ts` and opens a local server, so a fresh
+repo shows a site right away. See [The lectio CLI](/cli) for configuring
+sources, branding and deploy.
+
+## The library path — embed it in your app
+
+If you want to own routing, rendering and theme, use the toolkit directly: point
+the collector at your sources, then read them back through the content source.
+
+### 1. Describe your sources
 
 A source is a glob plus the target path it should land under:
 
@@ -22,12 +39,15 @@ A source is a glob plus the target path it should land under:
 }
 ```
 
-## 2. Collect
+### 2. Collect
 
 `collect()` copies each match into the output directory, enriches its
 frontmatter, and writes `manifest.json` alongside it.
 
-## 3. Read it back
+### 3. Read it back
 
 `createContentSource({ manifest, loadBody })` gives you the navigation tree and
 individual pages. Rendering stays entirely yours.
+
+Under the hood, the CLI is exactly this library wired into a React Router app —
+so both paths share the same collector and content source.