Docs discoverability: nav link, intro landing page, llms.txt

.github/workflows/deploy-landing.yml

@@ -66,6 +66,24 @@ jobs:
           mkdir -p apps/landing/dist/docs
           cp -R apps/docs/.vitepress/dist/. apps/landing/dist/docs/
 
+      # Generate llms-full.txt: the whole user docs concatenated into one file
+      # for LLM agents (companion to the hand-authored public/llms.txt index).
+      - name: Generate llms-full.txt
+        run: |
+          cd apps/docs
+          {
+            echo "# mx — full documentation"
+            echo
+            echo "> Concatenated source of the mx user documentation (https://mx.rousanali.com/docs)."
+            for f in index.md why-mx.md getting-started.md concepts.md tutorial.md \
+                     guides/repos.md guides/works-and-worktrees.md guides/ports.md \
+                     guides/hooks.md guides/context.md guides/mission-control.md \
+                     guides/lifecycle.md guides/coding-agents.md \
+                     reference/cli.md reference/configuration.md faq.md; do
+              echo; echo "---"; echo; cat "$f"; echo
+            done
+          } > ../landing/dist/llms-full.txt
+
       # Package dist/ as the Pages artifact for the deploy job to consume.
       - uses: actions/upload-pages-artifact@v3
         with:

apps/docs/.vitepress/config.mts

@@ -59,6 +59,7 @@ export default defineConfig({
       {
         text: 'Introduction',
         items: [
+          { text: 'What is mx?', link: '/' },
           { text: 'Why mx', link: '/why-mx' },
           { text: 'Getting started', link: '/getting-started' },
           { text: 'Core concepts', link: '/concepts' },

apps/docs/index.md

@@ -1,43 +1,36 @@
 ---
-layout: home
-
-hero:
-  name: mx
-  text: Parallel features, one runtime
-  tagline: Run several features at once — each in its own git worktree, branch, ports, and coding-agent session. Switch instantly; nothing collides.
-  actions:
-    - theme: brand
-      text: Get started
-      link: /getting-started
-    - theme: alt
-      text: Why mx
-      link: /why-mx
-    - theme: alt
-      text: ← Back to mx.rousanali.com
-      link: https://mx.rousanali.com
-
-features:
-  - title: One runtime, many repos
-    details: Clone each repo once into a single runtime; fork lightweight worktrees per feature that share the pristine clone's git object store — no duplicated repos on disk.
-  - title: A work per feature
-    details: Each feature is a "work" with its own worktrees, branches, and per-service ports. Switching between features is a swipe, not a 20-minute stash-and-reinstall reset.
-  - title: Ports that never clash
-    details: mx allocates each feature its own ports, unique across the whole runtime — so you can run the same app many times, side by side, one per feature.
-  - title: Ready-to-run worktrees
-    details: Lifecycle hooks hydrate a fresh worktree the moment it's created — copy the .env, install deps, seed the database — in any language you like.
-  - title: Shared context registry
-    details: A runtime-wide memory of findings, conventions, and runbooks that every feature's coding agent reads from, so a hard-won discovery isn't re-learned next time.
-  - title: Built for coding agents
-    details: One agent per worktree means a whole fleet of Claude Code / Cursor sessions working in parallel — each isolated, none stepping on another.
+title: What is mx?
 ---
 
-## New here?
+# What is mx?
 
-Start with **[Why mx](/why-mx)** for the problem it solves, then **[Getting started](/getting-started)** to install it and create your first parallel feature in a couple of minutes. **[Core concepts](/concepts)** explains the four words — runtime, repo, work, worktree — that the whole tool is built on.
+**mx** ("multiplexer") runs several software features **in parallel** across shared repos, using git worktrees and coding agents. Each feature lives in its own isolated world — its own worktrees, branches, ports, and coding-agent session — so you switch between them instantly, and run a whole fleet of agents at once without anything colliding.
 
-Prefer a visual tour? Watch the **[demo deck](https://mx.rousanali.com/deck)**.
+It's a single, open-source CLI:
 
 ```bash
 npm i -g @rousan/mx
 mx init
 ```
+
+## At a glance
+
+- **One runtime, many repos.** You clone each repo once into a single runtime folder. Those clones stay pristine and read-only.
+- **A work per feature.** Each feature is a *work*: it groups a lightweight **worktree** per repo it touches, each on its own branch, sharing the pristine clone's git objects — no duplicated repos on disk.
+- **Ports that never clash.** mx allocates each feature its own ports, unique across the whole runtime, so the same app runs many times side by side.
+- **Ready-to-run worktrees.** Lifecycle hooks hydrate a fresh worktree the moment it's created — copy the `.env`, install deps, seed the database.
+- **Shared context.** A runtime-wide registry of findings, conventions, and runbooks that every feature's agent reads from.
+- **A recoverable lifecycle.** Archive a finished feature to free its ports and worktrees while keeping its branches and notes; unarchive to pick it right back up.
+
+## Who it's for
+
+Anyone juggling **more than one thing at a time** — a feature, an urgent bug, a review — especially when you want **coding agents** (Claude Code, Cursor, and friends) making progress on several of them in parallel. A coding agent works one checkout at a time, so a fleet of agents needs a fleet of isolated checkouts. That's exactly what mx manages for you.
+
+## Start here
+
+- **[Why mx](/why-mx)** — the problem this design solves, in depth.
+- **[Getting started](/getting-started)** — install mx and create your first parallel feature in a couple of minutes.
+- **[Core concepts](/concepts)** — the four words (runtime, repo, work, worktree) the whole tool is built on.
+- **[Tutorial](/tutorial)** — a full end-to-end walkthrough: two features in parallel across two repos.
+
+Prefer a visual tour first? Watch the **[demo deck](https://mx.rousanali.com/deck)**.

apps/landing/public/llms.txt

@@ -0,0 +1,36 @@
+# mx
+
+> mx ("multiplexer") runs several software features in parallel across shared repos using git worktrees and coding agents. Each feature is a "work" with its own worktrees, branches, ports, and coding-agent session — fully isolated, so you switch between features instantly and run a fleet of agents at once without anything colliding.
+
+mx is an open-source CLI: install with `npm i -g @rousan/mx`, then `mx init`. It is built for developers juggling more than one feature at a time, especially those running coding agents (Claude Code, Cursor, and friends) on several features in parallel. This file indexes the user documentation; every link points to a self-contained page.
+
+## Introduction
+
+- [What is mx?](https://mx.rousanali.com/docs/): Overview of mx and how it works at a glance.
+- [Why mx](https://mx.rousanali.com/docs/why-mx): The problem mx solves and why a tab-per-feature or hand-rolled worktree setup breaks down.
+- [Getting started](https://mx.rousanali.com/docs/getting-started): Install mx, create a runtime, add a repo, and create your first parallel feature.
+- [Core concepts](https://mx.rousanali.com/docs/concepts): The four words the tool is built on — runtime, repo, work, worktree — and the rule that mx owns all runtime state.
+- [Tutorial](https://mx.rousanali.com/docs/tutorial): End-to-end walkthrough running two features in parallel across two repos, with ports, mission control, and archive/resume.
+
+## Guides
+
+- [Repos](https://mx.rousanali.com/docs/guides/repos): Add, list, fetch, and remove repositories; the pristine read-only clone model.
+- [Works & worktrees](https://mx.rousanali.com/docs/guides/works-and-worktrees): Create works, add worktrees (one per repo, or several of one repo), switch branches, and tear down.
+- [Ports](https://mx.rousanali.com/docs/guides/ports): Allocate per-feature ports unique across the runtime and run the same app many times side by side.
+- [Hooks & hydration](https://mx.rousanali.com/docs/guides/hooks): Make a fresh worktree ready to run automatically; the full set of lifecycle hooks and their environment variables.
+- [Context registry](https://mx.rousanali.com/docs/guides/context): The runtime-wide shared memory (INDEX.json + body files) that every feature's agent reads from.
+- [Mission control](https://mx.rousanali.com/docs/guides/mission-control): The live read-only dashboard, health commands, and terminal dividers for organizing macOS Spaces.
+- [Archive & resume](https://mx.rousanali.com/docs/guides/lifecycle): The active → archived → resumed lifecycle, session summaries, and archive vs destroy.
+- [Coding agents](https://mx.rousanali.com/docs/guides/coding-agents): Run one agent per feature, seed sessions with the session-prompt hook, and a workflow that fits the tool.
+
+## Reference
+
+- [CLI reference](https://mx.rousanali.com/docs/reference/cli): Every command by area — global, repos, works, bin — with common flags.
+- [Configuration](https://mx.rousanali.com/docs/reference/configuration): Runtime discovery ($MX_RUNTIME), versioning, sync vs update vs migrate, and the files store.
+- [FAQ](https://mx.rousanali.com/docs/faq): Common questions about worktrees, agents, multi-repo features, ports, upgrades, and safety.
+
+## Optional
+
+- [Demo deck](https://mx.rousanali.com/deck): A visual, slide-by-slide tour of mx.
+- [GitHub repository](https://github.com/rousan/mx): Source code and issues (MIT licensed).
+- [npm package](https://www.npmjs.com/package/@rousan/mx): The published `@rousan/mx` CLI.

apps/landing/src/content.ts

@@ -363,4 +363,5 @@ export const NAV_LINKS: { label: string; href: string }[] = [
   { label: 'Agents', href: '#agents' },
   { label: 'Concepts', href: '#concepts' },
   { label: 'Commands', href: '#commands' },
+  { label: 'Docs', href: '/docs/' },
 ];