docs(readme): improve quick start guide and restructure documentation

README.md

@@ -96,10 +96,9 @@ atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
 ## Table of Contents
 
 - [What Engineers Use Atomic For](#what-engineers-use-atomic-for)
-- [Set up Atomic](#set-up-atomic)
+- [Quick Start Guide](#quick-start-guide)
 - [The Flywheel](#the-flywheel)
 - [How It Works](#how-it-works)
-- [The Workflow](#the-workflow)
 - [Commands, Agents, and Skills](#commands-agents-and-skills)
 - [TUI Features](#tui-features)
 - [Supported Coding Agents](#supported-coding-agents)
@@ -116,31 +115,19 @@ atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
 
 ---
 
-## Set up Atomic
+## Quick Start Guide
 
-> Install Atomic and start using it with your preferred AI coding agent.
-
-### System requirements
+### Prerequisites
 
 - **Operating Systems**: macOS, Linux, or Windows (with PowerShell)
-- **Hardware**: Minimal requirements
-- **Network**: Internet connection required for installation
-- **Coding agent installed** (at least one):
+- **At least one coding agent installed**:
     - [Claude Code](https://code.claude.com/docs/en/quickstart)
     - [OpenCode](https://opencode.ai)
     - [GitHub Copilot CLI](https://github.com/features/copilot/cli)
 
-#### Additional dependencies
-
-- **Bun**: Only required for [bun installation](#bun-installation)
-
-### Installation
-
-To install Atomic, use one of the following methods:
+### Step 1: Install Atomic
 
-#### Native install (Recommended)
-
-**macOS, Linux:**
+**macOS / Linux:**
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
@@ -152,186 +139,148 @@ curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | b
 irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
 ```
 
-#### bun installation
-
-```bash
-# Using bun
-bun add -g @bastani/atomic
-```
-
-**Without installation (one-time use):**
-
-```bash
-bunx @bastani/atomic
-```
-
-### Install a specific version
-
-**macOS, Linux:**
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash -s -- v1.0.0
-```
-
-**Windows PowerShell:**
-
-```powershell
-iex "& { $(irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1) } -Version v1.0.0"
-```
-
-### Getting started
-
-After installation, navigate to your project and set up Atomic:
+### Step 2: Initialize Your Project
 
 ```bash
 cd your-awesome-project
 atomic init
 ```
 
-Select your agent. The CLI configures your project automatically.
+Select your coding agent when prompted. The CLI configures your project automatically.
 
-`atomic init` configures source-control-specific skills in your project (GitHub/Git or Sapling), while Atomic's baseline agents/skills are installed globally under `~/.atomic/.claude`, `~/.atomic/.opencode`, and `~/.atomic/.copilot` during install/update (including `bun install` for editable/package installs).
+### Step 3: Generate Context Files
 
-Then start a chat session and run `/init` to generate `CLAUDE.md` and `AGENTS.md`:
+Start a chat session and run `/init` to generate `CLAUDE.md` and `AGENTS.md`:
 
 ```bash
-atomic chat -a claude
+atomic chat -a <claude|opencode|copilot>
 ```
 
 ```
 /init
 ```
 
-The `/init` command explores your codebase using sub-agents and generates populated `CLAUDE.md` and `AGENTS.md` files tailored to your project. These files give coding agents the context they need to work effectively in your repository.
+The `/init` command explores your codebase using sub-agents and generates documentation tailored to your project. These files give coding agents the context they need to work effectively.
 
-### Source Control Selection
+### Step 4: Ship Features
 
-During `atomic init`, you'll be prompted to select your source control system:
+```
+Research → Spec → Implement → (Debug) → PR
+```
 
-| SCM Type              | CLI Tool | Code Review       | Use Case                     |
-| --------------------- | -------- | ----------------- | ---------------------------- |
-| GitHub / Git          | `git`    | Pull Requests     | Most open-source projects    |
-| Sapling + Phabricator | `sl`     | Phabricator Diffs | Meta-style stacked workflows |
+**Research the codebase:**
 
-The selection is saved to `.atomic/settings.json` in your project and configures the appropriate commit and code review commands for your workflow.
+```
+/research-codebase [Describe your feature or question]
+/clear
+```
 
-#### Sapling + Phabricator Setup
+Review: Confirm the agent understood your codebase and requirements.
 
-If you select Sapling + Phabricator:
+**Create a specification:**
 
-1. Ensure `.arcconfig` exists in your repository root (required for Phabricator)
-2. Use `/sl-commit` for creating commits with `sl commit`
-3. Use `/sl-submit-diff` for submitting to Phabricator for code review
+```
+/create-spec [research-path]
+/clear
+```
 
-**Note for Windows users:** Sapling templates use the full path `& 'C:\Program Files\Sapling\sl.exe'` to avoid conflicts with PowerShell's built-in `sl` alias for `Set-Location`.
+Review (**critical**): This is your main decision point. The spec becomes the contract.
 
-### Custom install directory
+**Implement features:**
 
-**macOS, Linux:**
-
-```bash
-ATOMIC_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
+```
+/ralph "<prompt-or-spec-path>"
 ```
 
-**Windows PowerShell:**
+**Commit and ship:**
 
-```powershell
-$env:ATOMIC_INSTALL_DIR = "C:\tools"; irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
+```
+/gh-commit
+/gh-create-pr
 ```
 
----
-
-## The Flywheel
+**Debugging:** If something breaks during implementation, use the debugging agent:
 
 ```
-Research → Specs → Execution → Outcomes → Specs (persistent memory)
-                ↑                                    ↓
-                └────────────────────────────────────┘
+Use the debugging agent to create a debugging report for [insert error message here].
 ```
 
-Every feature follows this cycle. Specs and research become memory for future sessions.
+Then follow the debugging report to resolve the issue.
 
----
+### Advanced Installation
 
-## How It Works
+<details>
+<summary>Install a specific version</summary>
 
-[![Architecture](assets/architecture.svg)](assets/architecture.svg)
+**macOS / Linux:**
 
----
+```bash
+curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash -s -- v1.0.0
+```
 
-## The Workflow
+**Windows PowerShell:**
 
+```powershell
+iex "& { $(irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1) } -Version v1.0.0"
 ```
-Research → Plan (Spec) → Implement (Ralph) → (Debug) → PR
-```
 
-### 1. Research the Codebase
+</details>
+
+<details>
+<summary>Custom install directory</summary>
 
-Start a chat session and use the `/research-codebase` command:
+**macOS / Linux:**
 
 ```bash
-atomic chat -a <claude|opencode|copilot>
+ATOMIC_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
 ```
 
-Then type in the chat:
-
-```
-/research-codebase [Describe your feature or question]
-```
+**Windows PowerShell:**
 
+```powershell
+$env:ATOMIC_INSTALL_DIR = "C:\tools"; irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
 ```
-/clear
-```
-
-**You review:** Confirm the agent understood your codebase and requirements.
 
-### 2. Create a Specification
+</details>
 
-```
-/create-spec [research-path]
-```
+<details>
+<summary>Source control selection</summary>
 
-```
-/clear
-```
-
-**You review (CRITICAL):** This is your main decision point. The spec becomes the contract.
+During `atomic init`, you'll be prompted to select your source control system:
 
-### 3. Implement Features
+| SCM Type              | CLI Tool | Code Review       | Use Case                     |
+| --------------------- | -------- | ----------------- | ---------------------------- |
+| GitHub / Git          | `git`    | Pull Requests     | Most open-source projects    |
+| Sapling + Phabricator | `sl`     | Phabricator Diffs | Meta-style stacked workflows |
 
-Use the Ralph workflow to autonomously implement features from the task list. More in [Ralph Section](#autonomous-execution-ralph):
+The selection is saved to `.atomic/settings.json` and configures the appropriate commit and code review commands.
 
-```
-/ralph "<prompt-or-spec-path>"
-```
+**Sapling + Phabricator:**
 
-### 4. Commit Changes
+1. Ensure `.arcconfig` exists in your repository root
+2. Use `/sl-commit` for commits and `/sl-submit-diff` for code review
 
-```
-/gh-commit
-```
+**Note for Windows users:** Sapling templates use the full path `& 'C:\Program Files\Sapling\sl.exe'` to avoid conflicts with PowerShell's built-in `sl` alias.
 
-### 5. Debugging
+</details>
 
-Software engineering is highly non-linear. You are bound to need to debug along the way.
+---
 
-If something breaks during implementation that the agent did not catch, you can manually debug. Type in the chat:
+## The Flywheel
 
 ```
-Use the debugging agent to create a debugging report for [insert error message here].
+Research → Specs → Execution → Outcomes → Specs (persistent memory)
+                ↑                                    ↓
+                └────────────────────────────────────┘
 ```
 
-Then, use the debugging report to guide your agent:
+Every feature follows this cycle. Specs and research become memory for future sessions.
 
-```
-Follow the debugging report above to resolve the issue.
-```
+---
 
-### 6. Create Pull Request
+## How It Works
 
-```
-/gh-create-pr
-```
+[![Architecture](assets/architecture.svg)](assets/architecture.svg)
 
 ---