docs: improve tutorial quality, fix typos, and add missing sections

- Fix getting-started overview: add time estimates, remove emoji, fix links
- Fix monitor tutorial: fix dangling OPTIONS, double colons, generic alt text, wrap callout in Aside, add checkpoint
- Fix CLI tutorial: add install verification step, expected output, Windows support, troubleshooting section
- Fix Slack agent tutorial: add verification checkpoint, troubleshooting section, time estimate
- Rewrite private location tutorial: add proper structure, Docker commands, token setup, verification, troubleshooting
- Fix status page tutorial: flesh out Step 2 config, add checkpoint, expand custom domain/password sections
- Fix configure status page tutorial: fix numbered list, typos, clean up beta language

Author: thibaultleouay

apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx

@@ -4,10 +4,17 @@ description: "Step-by-step tutorial to install and use the openstatus CLI for mo
 ---
 
 import { Image } from 'astro:assets';
+import { Aside } from '@astrojs/starlight/components';
 import CLI from '../../../assets/tutorial/get-started-with-openstatus-cli/CLI.png';
 
 ## What you'll learn
 
+| | |
+|---|---|
+| **Time** | ~10 minutes |
+| **Level** | Intermediate |
+| **Prerequisites** | openstatus account, command line experience |
+
 In this tutorial, you'll learn how to use the openstatus CLI to manage your monitors as code. This enables you to version control your monitoring configuration, automate deployments, and implement GitOps workflows.
 
 ### Prerequisites
@@ -53,19 +60,39 @@ curl -fsSL https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/in
 
 ### Windows
 
-```bash
+```powershell
 iwr https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.ps1 | iex
 ```
 
+### Verify installation
+
+Run the following command to confirm the CLI is installed:
+
+```bash
+openstatus --version
+```
+
+You should see output like:
+
+```
+openstatus version x.x.x
+```
+
 ## Configure API authentication
 
 Create an API key in your workspace settings (Settings → API), then set it as an environment variable:
 
 ```bash
+# macOS / Linux
 export OPENSTATUS_API_TOKEN=<your-api-token>
 ```
 
-**Tip**: Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist across sessions.
+```powershell
+# Windows PowerShell
+$env:OPENSTATUS_API_TOKEN="<your-api-token>"
+```
+
+<Aside>Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist across sessions.</Aside>
 
 ## Import existing monitors
 
@@ -75,8 +102,16 @@ Start by importing your existing monitors from your workspace to a YAML file:
 openstatus monitors import
 ```
 
+You should see output confirming the import:
+
+```
+Successfully imported X monitors to openstatus.yaml
+```
+
 This creates an `openstatus.yaml` file containing all your current monitors. This file becomes your single source of truth for monitoring configuration.
 
+**Checkpoint:** Open the `openstatus.yaml` file and verify it contains your monitors. You should see entries with your monitor names and URLs.
+
 ## Manage monitors as code
 
 Now you can add, remove, or update monitors in the YAML file and apply your changes:
@@ -95,6 +130,37 @@ Excellent work! You've successfully:
 - ✅ Imported monitors to a YAML file
 - ✅ Learned the monitoring as code workflow
 
+## Troubleshooting
+
+### "command not found: openstatus"
+
+**Cause:** The CLI binary is not in your PATH.
+
+**Fix (macOS/Homebrew):**
+```bash
+brew reinstall openstatusHQ/cli/openstatus --cask
+```
+
+**Fix (install script):** Ensure `~/.local/bin` is in your PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### "unauthorized" or "invalid token" error
+
+**Cause:** Your API token is missing or incorrect.
+
+**Fix:**
+1. Verify the token is set: `echo $OPENSTATUS_API_TOKEN`
+2. Regenerate the token in your workspace settings (Settings → API)
+3. Make sure there are no extra spaces or newlines in the token value
+
+### "no monitors found" on import
+
+**Cause:** Your workspace has no monitors, or the token belongs to a different workspace.
+
+**Fix:** Create at least one monitor in the dashboard first, then retry the import.
+
 ## What's next?
 
 Now that you have the CLI set up, you can:

apps/docs/src/content/docs/tutorial/getting-started.mdx

@@ -6,7 +6,7 @@ sidebar:
   order: 1
 ---
 
-## 📚 Tutorials
+## Tutorials
 
 ### What you'll learn
 
@@ -20,20 +20,21 @@ Our tutorials are designed to help you:
 
 Start your journey with openstatus:
 
-- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Learn the fundamentals by setting up uptime monitoring for your first endpoint
-- **[Create a Status Page](/tutorial/how-to-create-status-page)** - Build a public status page to communicate service health to your users
-- **[Configure Your Status Page](/tutorial/how-to-configure-status-page)** - Customize your status page with monitors, domains, and protection
+- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** (~5 min) - Learn the fundamentals by setting up uptime monitoring for your first endpoint
+- **[Create a Status Page](/tutorial/how-to-create-status-page)** (~5 min) - Build a public status page to communicate service health to your users
+- **[Configure Your Status Page](/tutorial/how-to-configure-status-page)** (~10 min) - Customize your status page with monitors, domains, and protection
+- **[Set Up the Slack Agent](/tutorial/how-to-setup-slack-agent)** (~5 min) - Manage incidents directly from Slack
 
 ### Advanced Tutorials
 
 Once you're comfortable with the basics:
 
-- **[Create a Private Location (Beta)](/tutorial/how-to-create-private-location)** - Set up monitoring from your own infrastructure
-- **[Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)** - Automate monitor management with our command-line tool
+- **[Create a Private Location (Beta)](/tutorial/how-to-create-private-location)** (~15 min) - Set up monitoring from your own infrastructure
+- **[Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)** (~10 min) - Automate monitor management with our command-line tool
 
 ### What's next?
 
 After completing these tutorials, you'll be ready to:
-- Explore [how-to guides](/guides/getting-started/) for specific tasks and advanced scenarios
-- Dive into [explanations](/concept/getting-started/) to understand the concepts behind the features
-- Reference our [technical documentation](/reference) for detailed specifications
+- Explore [how-to guides](/guides/getting-started) for specific tasks and advanced scenarios
+- Dive into [explanations](/concept/getting-started) to understand the concepts behind the features
+- Reference our [technical documentation](/reference/cli-reference) for detailed specifications

apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx

@@ -32,19 +32,19 @@ By the end of this tutorial, you'll have:
 - Links to important resources
 - Preview and live configuration experience
 
-## Status Page Redesign (Beta)
+## Status Page Customization
 
-We are releasing a new version of our status pages with enhanced customization options.
+OpenStatus offers enhanced status page customization with multiple themes and display options.
 
 Explore available themes: [https://themes.openstatus.dev](https://themes.openstatus.dev)
 
 ## Get started
 
-Go to the **Status Page Redesign (beta)** section in your status page settings. Toggle the `Enable New Version` to support it. Once enabled, you'll see two subsections:
+Go to the **Status Page Redesign** section in your status page settings and toggle `Enable New Version`. Once enabled, you'll see three subsections:
 
 1. **Tracker Configuration**
 2. **Theme Explorer**
-2. **Links**
+3. **Links**
 
 <Image
     src={ConfigureStatusPage1}
@@ -73,7 +73,7 @@ We have three new status tracker configurations to provide you with a maximum ch
 
 **Card Type**: The card type is only configurable if the bar type is **absolute**. You'll then be able to choose between **duration**, which will show the duration of "success", "error", "degraded" or "maintenance" reports or **requests** where we will share the number of request status itself. If **manual** bar type is chosen, we will only show the most significant status of the day.
 
-**Show Uptime**: The uptime is calculated by ither the **duration** of the different reports _or_ the **request** values depending on what you've chosen for the **absolute** value (incl. incidents). If you've chosen **manual**, it only gets calculated by the duration of your status reports.
+**Show Uptime**: The uptime is calculated by either the **duration** of the different reports _or_ the **request** values depending on what you've chosen for the **absolute** value (incl. incidents). If you've chosen **manual**, it only gets calculated by the duration of your status reports.
 
 A few examples to understand it:
 
@@ -110,7 +110,7 @@ Visit [themes.openstatus.dev](https://themes.openstatus.dev) to see the list of
 
 ### 3. Links
 
-Let's have a closer look to your status page header navigation:
+Let's have a closer look at your status page header navigation:
 
 <Image
     src={StatusPageBeta1}
@@ -123,12 +123,12 @@ Let's have a closer look to your status page header navigation:
 
 ---
 
-We are adding some additional features. Feel free to let us know what's missing!
+We are continuously adding new features. Feel free to let us know what's missing!
 
 ## What you've accomplished
 
 Excellent work! You've successfully:
-- ✅ Enabled and configured the new status page design (beta)
+- ✅ Enabled and configured the new status page design
 - ✅ Customized status tracker display options
 - ✅ Explored and applied theme settings
 - ✅ Added navigation links to your status page

apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx

@@ -5,6 +5,7 @@ description: "Set up your first uptime monitor with OpenStatus — track respons
 
 import { Image } from 'astro:assets';
 import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
 import monitorOverview from '../../../assets/tutorial/create-monitor/monitor-overview.png';
 import createMonitor from '../../../assets/tutorial/create-monitor/create-monitor-1.png';
 import createMonitor2 from '../../../assets/tutorial/create-monitor/create-monitor-2.png';
@@ -36,7 +37,7 @@ Let's get your first uptime check up and running.
 
   <Image
     src={createMonitor}
-    alt="Charts with status code and response time"
+    alt="Monitors page showing the Create Monitor button in the sidebar"
   />
 
 Navigate to the **Monitors** page from the sidebar and click the **Create Monitor** button. This will open a new configuration screen.
@@ -46,7 +47,7 @@ Navigate to the **Monitors** page from the sidebar and click the **Create Monito
 
   <Image
     src={createMonitor2}
-    alt="Charts with status code and response time"
+    alt="Monitor creation form with name and URL fields"
   />
 
 To get your monitor started, you only need to provide two essential pieces of information:
@@ -62,17 +63,19 @@ As soon as you enter the URL, our monitoring tool will automatically begin track
 
   <Image
     src={monitorOverview}
-    alt="Charts with status code and response time"
+    alt="Monitor overview dashboard showing response time and status code charts"
   />
 
+**Checkpoint:** After saving, you should see your monitor's overview page with response time and status code charts. If data appears within a few seconds, your monitor is running.
+
 
 ### 3. Customizing the HTTP Request
 
 Your monitor doesn't just have to be a simple `GET` request. You can customize the HTTP request to simulate real-world traffic and test specific scenarios.
 
 #### HTTP Method
 
-Choose the appropriate HTTP method for your check. While `GET` is the default and most common for simple health checks, you can also select `POST`, `HEAD`, `OPTIONS`, `PUT`, `PATCH`, `DELETE`, `TRACE`. `OPTIONS`
+Choose the appropriate HTTP method for your check. While `GET` is the default and most common for simple health checks, you can also select `POST`, `HEAD`, `OPTIONS`, `PUT`, `PATCH`, `DELETE`, or `TRACE`.
 
 - `GET`: Retrieve data from an endpoint. The most common choice for health checks.
 - `POST`: Send data to an endpoint, for example, to test a form submission or API creation endpoint.
@@ -91,15 +94,15 @@ If you select the `POST` method, you can add a Request Body to your monitor's co
 
 You can add any number of custom HTTP headers to your request. This is particularly useful for:
 
-- **Authentication:**: Sending an Authorization token (e.g., a Bearer token) to test a protected endpoint.
-- **Content Type:**: Setting an `content-type` header  to specify a content type (e.g., `application/json`).
+- **Authentication:** Sending an Authorization token (e.g., a Bearer token) to test a protected endpoint.
+- **Content Type:** Setting a `content-type` header to specify a content type (e.g., `application/json`).
 - **Content Negotiation:** Setting an Accept header to request a specific content type from the server (e.g., `application/json`).
 - **Simulating Clients:** Adding a User-Agent header to simulate traffic from a specific browser or device.
 
-    Heads Up: We've got your User-Agent covered!
-    openstatus automatically includes the `"User-Agent": "openstatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.
-
 
+<Aside title="We've got your User-Agent covered!">
+openstatus automatically includes the `"User-Agent": "openstatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.
+</Aside>
 
 
 ## Important Considerations