feature(dev): new system

README.md

@@ -14,6 +14,10 @@ Visit the [Introduction](https://native.buridan.dev/docs/getting-started/introdu
 
 Visit the [CLI](https://native.buridan.dev/docs/getting-started/cli) page for information on how to use the CLI tool.
 
+## Dev (CLI)
+
+Visit the [dev](https://native.buridan.dev/docs/getting-started/dev) page for information on how to use the local dev environment when working with this repo.
+
 ## Components
 
 Visit [Components](https://native.buridan.dev/components) section to see all available components.

assets/docs/getting-started/dev.md

@@ -1,73 +1,119 @@
 ---
-title: "dev.py"
-description: "Interactive development CLI for selecting and running Buridan documentation pages locally."
+title: "dev"
+description: "Interactive and command-line tool for selecting and running Buridan documentation pages locally."
 order: 4
 ---
 
-# dev.py
+# dev
 
-The `dev.py` script is an interactive CLI tool used to control which documentation pages are loaded during local development.
-
-It replaces manual environment variable setup and makes it easier to selectively run parts of the documentation site while developing.
+The `dev` command is a CLI tool used to control which documentation pages are loaded during local development.
 
+It replaces manual environment variable setup and makes it easier to selectively run parts of the documentation site while developing. Pages can be picked interactively through a fuzzy search prompt, or loaded directly by name.
 
 # Requirements
 
-This script uses [questionary](https://github.com/tmbo/questionary) for interactive prompts.
-
-Install it using your project setup:
+This tool uses [questionary](https://github.com/tmbo/questionary) for the environment/confirm prompts, and [InquirerPy](https://github.com/kazhala/InquirerPy) for fuzzy-searchable page selection. Both are declared in the `dev` dependency group, so they're installed automatically.
 
-```uv
-uv add questionary
+```bash
+uv sync
 ```
 
-You can also add it manually to your `pyproject.toml`:
+This also registers the `dev` command itself, via the `[project.scripts]` entry in `pyproject.toml`:
 
 ```pyproject.toml
-dependencies = ["questionary"]
+[project.scripts]
+dev = "cli.dev:main"
 ```
 
-# Overview
+# Usage
 
-Instead of running the full documentation build every time, `dev.py` lets you:
+Run the command from your project root:
 
-- Select specific pages
-- Select entire sections
-- Select pages within specific sections
-- Run the app in dev or prod mode
+```bash
+uv run dev
+```
 
-It then automatically configures the correct environment variables and starts the Reflex server.
+With no arguments, this starts the interactive flow: choose an environment, then fuzzy-search and multi-select pages.
 
-# Usage
+To skip the prompts entirely, pass pages, sections, or a mode directly as arguments — see below.
 
-Run the script from your project root to start the interactive flow:
+# Command Reference
 
-```uv
-uv run dev.py
+```text
+uv run dev [pages...] [--section SECTION [SECTION ...]] [--prod]
 ```
 
-# Flow
+| Argument          | Description                                                                                   |
+| ----------------- | --------------------------------------------------------------------------------------------- |
+| `pages`           | Page names (e.g. `button`) or full paths (e.g. `components/button`) to load, space-separated. |
+| `--section`, `-s` | Load every page in the given section(s). Accepts one or more section names.                   |
+| `--prod`          | Run in prod mode, loading the full site. Same as passing `prod` as the only argument.         |
 
-The CLI follows this flow:
+If any pages or sections are passed on the command line, `dev` runs immediately in dev mode with those pages — no prompts, no confirmation step.
 
-1. Select environment (dev / prod)
-2. Select mode (pages / sections / section-pages)
-3. Select pages or sections depending on mode
-4. Confirm execution
-5. Launch Reflex
+If nothing is passed, `dev` falls back to the interactive flow (environment select → fuzzy page search).
 
+## Examples
 
-# Environment
+Interactive picker (no arguments):
 
-Before selecting what to run, you must choose the environment.
+```bash
+uv run dev
+```
 
-This determines whether the CLI runs the full documentation site or a filtered development subset.
+Load specific pages by name:
 
-## Dev
+```bash
+uv run dev button input
+```
+
+Load a page by its full `section/page` path — useful if a page name exists in more than one section:
+
+```bash
+uv run dev components/button
+```
+
+Load an entire section:
+
+```bash
+uv run dev --section components
+```
+
+Load multiple sections at once:
+
+```bash
+uv run dev --section components auth
+```
+
+Mix individual pages and whole sections in one command:
+
+```bash
+uv run dev button --section auth
+```
+
+Run the full site in prod mode, skipping all prompts:
+
+```bash
+uv run dev prod
+```
+
+```bash
+uv run dev --prod
+```
 
-Development mode allows you to work on specific parts of the documentation without loading the entire site.
+# Page Name Resolution
 
-It enables selective loading of pages through the `dev.py` CLI.
+When you pass a bare page name (e.g. `button`), `dev` looks it up across every section:
+
+- **Unique match** — resolves automatically to its full path (e.g. `components/button`).
+- **Ambiguous match** — if the same page name exists in more than one section, `dev` prints an error listing every match and asks you to use the full `section/page` path instead of guessing.
+- **No match** — prints an error naming the page that couldn't be found. Nothing is launched if any requested page or section fails to resolve.
+
+# Environment
+
+## Dev
+
+Development mode allows you to work on specific parts of the documentation without loading the entire site. It's the default mode whenever pages or sections are provided, or when you're using the interactive picker.
 
 Use this mode when:
 
@@ -77,18 +123,16 @@ Use this mode when:
 
 ## Prod
 
-Production mode runs the full documentation site without any filtering.
-
-# Modes
-
-## Pages
+Production mode runs the full documentation site without any filtering. Trigger it with `uv run dev prod`, `uv run dev --prod`, or by selecting **prod** in the interactive picker.
 
-Select individual pages from all available documentation. Useful when working on specific content or debugging a single page.
+# Interactive Page Selection
 
-## Sections
+When no arguments are passed, page selection happens through a single fuzzy-searchable, multi-select prompt:
 
-Select one or more sections. All pages inside those sections will be loaded automatically. Useful when working on a feature area.
+- Type to filter the list by page name or section name
+- Press `Tab` to select multiple entries
+- Press `Enter` to confirm your selection
 
-## Section Pages
+Each section also has a virtual **"(entire section)"** entry at the top of its group, letting you pull in every page in that section with one selection instead of picking them individually. You can mix and match — for example, select an entire section plus a couple of individual pages from other sections in the same pass.
 
-Select one or more sections first, then choose specific pages inside them. Useful when you want focused work inside a feature area without loading everything.
+If no pages are selected, the CLI exits without launching Reflex. When pages are selected interactively, you'll be asked to confirm before Reflex starts; this confirmation step is skipped when pages are passed directly as command-line arguments.

assets/llms.txt

@@ -7,7 +7,7 @@
 - [Installation](https://native.buridan.dev/docs/getting-started/installation): Installation page.
 - [Skills](https://native.buridan.dev/docs/getting-started/skills): Skills page.
 - [CLI](https://native.buridan.dev/docs/getting-started/cli): CLI page.
-- [dev.py](https://native.buridan.dev/docs/getting-started/dev): dev.py page.
+- [dev](https://native.buridan.dev/docs/getting-started/dev): dev page.
 - [JavaScript](https://native.buridan.dev/docs/getting-started/javascript): JavaScript page.
 - [Changelog](https://native.buridan.dev/docs/getting-started/changelog): Changelog page.