New documentation structure: consolidate tutorial content, add command and environment references, and remove outdated files

Author: 8bitAlex

docs/commands.md

@@ -0,0 +1,89 @@
+---
+sidebar_position: 5
+---
+
+# Command Reference
+
+## raid install
+
+Clone all repositories in the active profile and run install tasks.
+
+```bash
+raid install [repo] [-t <threads>]
+```
+
+**Behaviour:**
+1. Clone all repositories concurrently (throttled by `-t` if set)
+2. Run profile-level install tasks
+3. Run each repository's install tasks in profile order
+
+If a repository already exists at its configured path, cloning is skipped.
+
+| Flag | Description |
+|---|---|
+| `[repo]` | Install only the named repository (profile-level tasks are not run) |
+| `-t, --threads` | Max concurrent clone threads (default: unlimited) |
+
+---
+
+## raid env
+
+Manage and apply environments.
+
+```bash
+raid env              # show the active environment
+raid env <name>       # apply a named environment to all repos
+raid env list         # list available environments
+```
+
+Applying an environment writes each repository's configured `.env` file and runs its environment tasks.
+
+---
+
+## raid profile
+
+Manage profiles.
+
+```bash
+raid profile create           # interactive wizard to create a new profile
+raid profile add <file>       # register a YAML or JSON profile file
+raid profile list             # list all registered profiles
+raid profile <name>           # switch the active profile
+raid profile remove <name>    # remove a profile
+```
+
+---
+
+## raid doctor
+
+Check the active configuration for issues.
+
+```bash
+raid doctor
+```
+
+Doctor inspects the current profile and reports findings at three severity levels:
+
+| Level | Meaning |
+|---|---|
+| `OK` | No issues |
+| `WARN` | Something looks off but raid can still function |
+| `ERROR` | A problem that will prevent raid from working correctly |
+
+Run `raid doctor` after initial setup or whenever something isn't working as expected.
+
+---
+
+## raid \<command\>
+
+Run a custom command defined in the active profile or any of its repositories.
+
+```bash
+raid deploy
+raid migrate
+raid test-all
+```
+
+Custom commands are defined in `commands` sections of the profile or in individual repository `raid.yaml` files. Run `raid --help` to see all available commands.
+
+Custom command names cannot shadow built-in names (`profile`, `install`, `env`, `doctor`).

docs/environments.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 4
+---
+
+# Environments
+
+Environments let you define named configurations — sets of `.env` files and tasks — that can be applied across all repositories at once. Switching from local to staging to production is a single command.
+
+## Define environments
+
+Environments are defined in the profile under each repository.
+
+```yaml
+repositories:
+  - name: api
+    url: git@github.com:my-org/api.git
+    path: ~/dev/api
+    environments:
+      local:
+        envFile: ./envs/local.env
+        tasks:
+          - type: shell
+            cmd: docker-compose up -d
+      staging:
+        envFile: ./envs/staging.env
+        tasks:
+          - type: shell
+            cmd: echo "Pointed at staging"
+      production:
+        envFile: ./envs/production.env
+        tasks:
+          - type: confirm
+            message: "You are switching to production. Continue?"
+```
+
+| Field | Description |
+|---|---|
+| `envFile` | Path to a `.env` file to write into the repository root |
+| `tasks` | Tasks to run when this environment is applied |
+
+## Apply an environment
+
+```bash
+raid env staging
+```
+
+This iterates over every repository in the active profile and for each one:
+1. Writes the `envFile` contents to `.env` in the repository root
+2. Runs the environment's `tasks`
+
+## Check the active environment
+
+```bash
+raid env
+```
+
+## List available environments
+
+```bash
+raid env list
+```
+
+## Tips
+
+**Keep `envFile` paths relative to the profile file.** This makes the profile portable across machines.
+
+**Use `confirm` tasks for production.** A confirmation gate before switching to a production environment prevents accidents.
+
+```yaml
+production:
+  envFile: ./envs/production.env
+  tasks:
+    - type: confirm
+      message: "Switch ALL repos to production?"
+    - type: shell
+      cmd: ./scripts/rotate-creds.sh
+```
+
+**Use `set` and `template` tasks for dynamic values.** If environment values differ per developer (e.g. local ports), generate them from a template rather than committing the final `.env`.
+
+```yaml
+local:
+  tasks:
+    - type: prompt
+      message: "Local API port"
+      var: API_PORT
+      default: "3000"
+    - type: template
+      src: ./envs/local.env.tmpl
+      dest: ~/dev/api/.env
+```

docs/intro.md

@@ -1,47 +1,71 @@
 ---
 sidebar_position: 1
+slug: /intro
 ---
 
-# Tutorial Intro
+# Getting Started
 
-Let's discover **Docusaurus in less than 5 minutes**.
+Raid is a CLI tool that lets you define your entire development environment — repositories, install steps, environment configs, and team commands — in a single YAML profile. Check it in, share it with the team, and anyone can go from a blank machine to a fully running environment with one command.
 
-## Getting Started
+## Install
 
-Get started by **creating a new site**.
+**Homebrew**
+```bash
+brew install 8bitalex/tap/raid
+```
 
-Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
+**Script**
+```bash
+curl -fsSL https://raw.githubusercontent.com/8bitalex/raid/main/install.sh | bash
+```
 
-### What you'll need
+## Create a profile
 
-- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
-  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+Run the interactive wizard to create your first profile:
 
-## Generate a new site
+```bash
+raid profile create
+```
 
-Generate a new Docusaurus site using the **classic template**.
+The wizard asks for a profile name and walks you through adding repositories. Each repository needs a name, a Git URL, and a local path.
 
-The classic template will automatically be added to your project after you run the command:
+You can also write the profile file manually and register it:
 
 ```bash
-npm init docusaurus@latest my-website classic
+raid profile add ./my-profile.yaml
 ```
 
-You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+See [Profile Configuration](./profile) for the full file format.
+
+## Install your environment
+
+Once a profile is active, clone all repositories and run their install tasks:
 
-The command also installs all necessary dependencies you need to run Docusaurus.
+```bash
+raid install
+```
+
+Raid clones all repositories concurrently, then runs profile-level install tasks followed by each repository's install tasks in profile order.
+
+To install a single repository:
+
+```bash
+raid install <repo-name>
+```
 
-## Start your site
+## Run a command
 
-Run the development server:
+If your profile or any of its repositories define custom commands, they are available immediately:
 
 ```bash
-cd my-website
-npm run start
+raid <command>
 ```
 
-The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
+Run `raid --help` to see all available commands, including any defined in the active profile.
 
-The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+## Next steps
 
-Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
+- [Profile Configuration](./profile) — repositories, environments, and commands
+- [Task Types](./tasks) — everything a task can do
+- [Environments](./environments) — switch between dev, staging, and production
+- [Command Reference](./commands) — built-in commands