diff --git a/.github/workflows/deploy-landing.yml b/.github/workflows/deploy-landing.yml index f9e3244..ae65965 100644 --- a/.github/workflows/deploy-landing.yml +++ b/.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: diff --git a/apps/docs/.vitepress/config.mts b/apps/docs/.vitepress/config.mts index 2183796..2787b2a 100644 --- a/apps/docs/.vitepress/config.mts +++ b/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' }, diff --git a/apps/docs/index.md b/apps/docs/index.md index 8d1421c..e9e1eef 100644 --- a/apps/docs/index.md +++ b/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)**. diff --git a/apps/landing/public/llms.txt b/apps/landing/public/llms.txt new file mode 100644 index 0000000..cfcc860 --- /dev/null +++ b/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. diff --git a/apps/landing/src/content.ts b/apps/landing/src/content.ts index 82e0678..ca72eb4 100644 --- a/apps/landing/src/content.ts +++ b/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/' }, ];