docs: add configuration section with hooks, sandbox, and settings docs

astro.config.mjs

@@ -79,6 +79,10 @@ export default defineConfig({
       status: 301,
       destination: "/rover/reference/cli-reference/",
     },
+    "/rover/intro/configuration": {
+      status: 301,
+      destination: "/rover/config/project-config",
+    },
   },
   integrations: [
     // @see https://github.com/joesaby/astro-mermaid?tab=readme-ov-file#integration-order-important
@@ -105,6 +109,10 @@ export default defineConfig({
                 label: "Key Concepts",
                 autogenerate: { directory: "rover/concepts" },
               },
+              {
+                label: "Configuration",
+                autogenerate: { directory: "rover/config" },
+              },
               {
                 label: "Guides",
                 autogenerate: { directory: "rover/guides" },

src/content/docs/rover/advanced/global-store.mdx

@@ -106,7 +106,7 @@ This directory is created on first Rover CLI use, along with a default `rover.js
 
 The `rover.json` file is the central configuration file for Rover. It stores user preferences, AI agent settings, and the registry of all projects you've used with Rover. This file is auto-generated and managed by the Rover CLI, so you don't need to edit it.
 
-If you want to customize a specific project, create a [Project Configuration](/rover/intro/configuration) file.
+If you want to customize a specific project, create a [Project Configuration](/rover/config/project-config) file.
 
 ### Project Registry
 

src/content/docs/rover/concepts/project.mdx

@@ -127,5 +127,5 @@ When you run Rover commands outside a git repository, Rover operates in **global
 <CardGrid>
   <LinkCard title="Task" href="/rover/concepts/task" description="Learn how Rover manages tasks as units of work for AI agents" />
   <LinkCard title="Global Store" href="/rover/advanced/global-store" description="Explore the central storage location for all Rover data" />
-  <LinkCard title="Configuration" href="/rover/intro/configuration" description="Customize Rover settings for your projects" />
+  <LinkCard title="Configuration" href="/rover/config/project-config" description="Customize Rover settings for your projects" />
 </CardGrid>

src/content/docs/rover/concepts/sandbox.mdx

@@ -22,7 +22,7 @@ Currently, sandboxes are implemented using containers. This ensures that each ta
 When you create a new task with `rover task`, Rover sets up a sandbox for it. This involves:
 
 1. **Creating a [workspace](/rover/concepts/workspace)**, which has copy of your project files
-2. **Load the user configuration to set up the sandbox environment**. This includes MCP servers, environment variables, and any [other settings defined in the configuration](/rover/intro/configuration)
+2. **Load the user configuration to set up the sandbox environment**. This includes MCP servers, environment variables, and any [other settings defined in the configuration](/rover/config/project-config)
 2. **Defines an entrypoint file to initialize the sandbox environment**. This file includes setup steps like installing dependencies and starting MCP servers
 3. **Spinning up a containerized environment** using Docker or Podman container runtimes
 4. **Running the coding agent inside the sandbox**, allowing it to execute commands and make changes in isolation

src/content/docs/rover/config/hooks.mdx

@@ -0,0 +1,159 @@
+---
+title: Hooks
+description: Run custom commands when tasks are merged, pushed, or completed
+sidebar:
+  order: 3
+---
+
+import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+Hooks let you run custom shell commands at specific points in the task lifecycle. Use them to trigger notifications, update dashboards, run CI pipelines, or integrate with other tools.
+
+## Available Hooks
+
+| Hook | Trigger |
+|------|---------|
+| `onMerge` | Runs after a task is successfully merged via `rover merge` |
+| `onPush` | Runs after a task branch is pushed via `rover push` |
+| `onComplete` | Runs when a task finishes (success or failure), detected via `rover list` |
+
+## Configuration
+
+Add hooks to your `rover.json` file:
+
+```jsonc
+{
+  "version": "1.2",
+  "languages": ["typescript"],
+  "packageManagers": ["npm"],
+  "hooks": {
+    "onComplete": ["./scripts/on-complete.sh"],
+    "onMerge": ["./scripts/on-merge.sh"],
+    "onPush": ["echo 'Task $ROVER_TASK_ID pushed'"]
+  }
+}
+```
+
+Each hook accepts an array of shell commands. Commands are executed sequentially in the order specified.
+
+## Environment Variables
+
+Rover passes task information to hooks via environment variables:
+
+| Variable | Description | Available In |
+|----------|-------------|--------------|
+| `ROVER_TASK_ID` | The task ID | All hooks |
+| `ROVER_TASK_BRANCH` | The task branch name | All hooks |
+| `ROVER_TASK_TITLE` | The task title | All hooks |
+| `ROVER_TASK_STATUS` | Task status: `completed` or `failed` | `onComplete` only |
+
+## Example Hook Script
+
+Create a script that notifies your team when a task completes:
+
+```bash
+#!/bin/bash
+# scripts/on-complete.sh
+
+echo "Task $ROVER_TASK_ID ($ROVER_TASK_TITLE) finished with status: $ROVER_TASK_STATUS"
+
+# Send a Slack notification
+if [ "$ROVER_TASK_STATUS" = "completed" ]; then
+  curl -X POST -H 'Content-type: application/json' \
+    --data "{\"text\":\"Task #$ROVER_TASK_ID completed: $ROVER_TASK_TITLE\"}" \
+    "$SLACK_WEBHOOK_URL"
+fi
+```
+
+Make sure to set execute permissions:
+
+```sh
+chmod +x scripts/on-complete.sh
+```
+
+## Hook Behavior
+
+### Execution Context
+
+- Hooks run in the **project directory** (where `rover.json` is located)
+- Commands execute via the shell (`sh -c`), supporting pipes and complex commands
+- Hooks inherit the current environment plus `ROVER_*` variables
+
+### Error Handling
+
+- Hook failures are logged as **warnings** but don't interrupt the main operation
+- If a hook fails, subsequent hooks in the array still execute
+- The primary command (`merge`, `push`, `list`) completes regardless of hook failures
+
+<Aside type="tip">Hooks are designed to be non-blocking. A failing notification script won't prevent your merge from completing.</Aside>
+
+### Deduplication
+
+The `onComplete` hook only triggers on **new** status transitions. If a task was already completed and you run `rover list` again, the hook won't re-execute.
+
+## Use Cases
+
+### Notify on Completion
+
+Send notifications when tasks finish:
+
+```jsonc
+{
+  "hooks": {
+    "onComplete": [
+      "curl -X POST https://api.example.com/webhook -d '{\"task\": \"$ROVER_TASK_ID\", \"status\": \"$ROVER_TASK_STATUS\"}'"
+    ]
+  }
+}
+```
+
+### Trigger CI on Push
+
+Start a CI pipeline when a task branch is pushed:
+
+```jsonc
+{
+  "hooks": {
+    "onPush": [
+      "gh workflow run ci.yml --ref $ROVER_TASK_BRANCH"
+    ]
+  }
+}
+```
+
+### Update Issue Tracker on Merge
+
+Close related issues when tasks are merged:
+
+```jsonc
+{
+  "hooks": {
+    "onMerge": [
+      "./scripts/close-issue.sh"
+    ]
+  }
+}
+```
+
+### Multiple Commands
+
+Chain multiple commands for a single hook:
+
+```jsonc
+{
+  "hooks": {
+    "onComplete": [
+      "echo 'Task $ROVER_TASK_ID completed'",
+      "./scripts/notify-slack.sh",
+      "./scripts/update-dashboard.sh"
+    ]
+  }
+}
+```
+
+## Next Steps
+
+<CardGrid>
+  <LinkCard title="Project Configuration" href="/rover/config/project-config" description="Configure project-wide settings" />
+  <LinkCard title="User Settings" href="/rover/config/user-settings" description="Configure user-specific preferences" />
+</CardGrid>