docs: Enhance investigation and integration documentation (Tracer-Cloud#2807)

* docs: Enhance investigation and integration documentation

- Added a new "Investigation workflow" section detailing the structured RCA pipeline for alerts.
- Updated "Integrations overview" to clarify setup paths and added a catalog of available integrations.
- Introduced a new "Benchmark" group in the documentation navigation.
- Improved descriptions and examples for using the interactive shell and session management.
- Added a link to the hermes_runbook for contributors in the Hermes documentation.
- Removed outdated AWS and macOS integration pages to streamline content.

* docs: Update link to hermes_runbook in Hermes documentation

- Corrected the file extension in the link to the hermes_runbook from `.md` to `.mdx` for accuracy.

Author: Devesh36

docs/docs.json

@@ -39,10 +39,17 @@
             "group": "First steps",
             "pages": [
               "quickstart",
+              "investigation-overview",
               "deployment",
               "faq"
             ]
           },
+          {
+            "group": "Benchmark",
+            "pages": [
+              "cloudopsbench"
+            ]
+          },
           {
             "group": "Community",
             "pages": [

docs/features.mdx

@@ -3,10 +3,37 @@ title: "Features"
 description: "What OpenSRE can do today"
 ---
 
-## Coming soon
+## Investigation workflow
 
-- Investigation workflow (evidence → hypotheses → report)
-- Integrations (60+ tools)
-- Masking and safe sharing
-- Remote runtime investigations
+OpenSRE runs a structured RCA pipeline for each alert:
 
+1. **Extract context** from the alert payload and connected integrations
+2. **Plan evidence collection** across logs, metrics, deploys, and dependencies
+3. **Test hypotheses** in a tool-calling loop until confidence is high enough to stop
+4. **Publish findings** as `problem.md`, `theory/hypothesis_*.md`, and `report.md` (or JSON with `--output`)
+
+Run investigations from the interactive shell (`opensre`) or one-shot via `opensre investigate -i <alert-file>`. See [Investigations overview](/investigation-overview).
+
+## Integrations (60+ tools)
+
+Connect observability, cloud, databases, incident management, messaging, and workflow systems so investigations can query the same tools your engineers use. Setup via `opensre onboard`, `opensre integrations setup`, or environment variables. See [Integrations overview](/integrations-overview).
+
+## Interactive shell
+
+The TTY REPL (`opensre` with no subcommand) supports:
+
+- Plain-language incident descriptions and follow-up questions
+- Slash commands for health checks, investigations, integrations, remote agents, and more (`/help`)
+- [Session history](/sessions) with `/sessions`, `/resume`, and `/new`
+- [Local agent fleet](/agents) monitoring for Claude Code, Cursor, Codex, and other coding agents
+- [Scheduled deliveries](/cron) and [Hermes log watch](/hermes)
+
+## Masking and safe sharing
+
+Reversible masking replaces sensitive infrastructure identifiers (pods, clusters, hostnames, account IDs) with stable placeholders before external LLM calls, then restores originals in user-facing output. See [Masking](/masking).
+
+Command-history redaction and persistence controls live under [Interactive Shell Privacy](/interactive-shell-privacy).
+
+## Remote runtime investigations
+
+Investigate deployed OpenSRE services by name — OpenSRE gathers live deployment status, recent logs, and health probes, then runs the standard RCA pipeline. See [Remote runtime investigation](/remote-runtime-investigation).

docs/hermes.mdx

@@ -150,5 +150,6 @@ Contributors add scenarios under `tests/synthetic/hermes/` (fixtures, `scenario.
 ## Further reading
 
 - Implementation lives under `app/integrations/hermes/` in the OpenSRE repository (tailer, parser, classifier, correlator, sinks, CLI wiring).
+- Surface-attribution evaluation workflow for contributors: [`docs/hermes_runbook.mdx`](https://github.com/Tracer-Cloud/opensre/blob/main/docs/hermes_runbook.mdx) in the repo (not on the public docs nav).
 - If you also run [OpenClaw](/openclaw) alongside Hermes, that page covers the OpenClaw bridge (context lookup and RCA write-back).
 - For false-positive risks when rules match both `message` and raw line text, see [issue #1874](https://github.com/Tracer-Cloud/opensre/issues/1874).

docs/integrations-overview.mdx

@@ -1,75 +1,70 @@
 ---
 title: "Integrations overview"
+description: "Connect observability, cloud, data, and messaging tools for automated RCA"
 ---
 
 OpenSRE investigates alerts by querying the same tools your engineers use. Connect your stack so OpenSRE can pull logs, check recent deploys, map dependencies, and deliver findings where your team already works.
 
-## Before you begin
+## Two setup paths
 
-Make sure you have:
+| Path | Best for | How to configure |
+| --- | --- | --- |
+| **Local CLI** | Self-hosted `opensre` on your laptop or server | `opensre onboard` or `opensre integrations setup`, plus env vars |
+| **Hosted (OpenSRE Cloud)** | Org-wide connectors shared across users | [app.tracer.cloud](https://app.tracer.cloud) web app |
 
-- A OpenSRE account — you can create one at [app.tracer.cloud/sign-up](http://app.tracer.cloud/sign-up)
-- Access credentials for the tools you want to connect
-- Permissions to create API keys
+Most users start with the **local CLI** path. You need credentials for the tools you want to connect and permission to create API keys.
 
-## Enterprise integrations
+## Local CLI setup
 
-Enterprise integrations are configured through the OpenSRE web app at [app.tracer.cloud](https://app.tracer.cloud). Once connected, they are available to all users in your organization.
-
-**Observability.** OpenSRE reads your logs, metrics, traces, and alerts to build investigation hypotheses. Connect [Grafana](/grafana) and [Datadog](/datadog).
+```bash
+opensre integrations setup
+```
 
-**Infrastructure.** OpenSRE maps your environment and dependencies across clouds and clusters. Connect [AWS](/aws).
+Or set environment variables — OpenSRE picks them up automatically on the next run.
 
-**Communication.** OpenSRE delivers investigation reports where your team already works. Connect [Slack, Discord, or Telegram](/messaging/index).
+### Verify
 
-<Frame>
-  ![Integrations](/images/integrations.png)
-</Frame>
-
-### Configure enterprise integrations
+```bash
+opensre integrations verify
+opensre integrations verify datadog
+```
 
-Each integration follows a simple, guided flow. Let's look at Datadog as an example.
+Inside the interactive shell you can also run `/integrations list`, `/integrations verify <name>`, and `/health`.
 
-1. Name - Helps distinguish between different instances
-2. API Key - in Datadog, create a new API key and copy and paste into OpenSRE.
-3. Application Key - In Datadog, create a new Application Key and copy and paste into OpenSRE.
+## Integration catalog
 
-<Frame>
-  ![Connect Datadog](/images/connect_datadog.png)
-</Frame>
+| Category | Integrations |
+| --- | --- |
+| **Observability and incidents** | [Alertmanager](/alertmanager), [Azure Monitor](/azure-monitor), [Better Stack](/betterstack), [Coralogix](/coralogix), [Datadog](/datadog), [Grafana](/grafana), [Hermes](/hermes), [Honeycomb](/honeycomb), [Incident.io](/incident_io), [OpenObserve](/openobserve), [OpsGenie](/opsgenie), [Sentry](/sentry), [SignOz](/signoz), [Splunk](/splunk), [Victoria Logs](/victoria_logs) |
+| **Cloud and infrastructure** | [AWS](/aws), [Argo CD](/argocd), [Helm](/helm), [Jenkins](/jenkins), [Vercel](/vercel) |
+| **Databases and data platforms** | [Azure SQL](/azure-sql), [ClickHouse](/clickhouse), [Kafka](/kafka), [MariaDB](/mariadb), [MongoDB](/mongodb), [MongoDB Atlas](/mongodb-atlas), [MySQL](/mysql), [OpenSearch](/opensearch), [PostgreSQL](/postgresql), [RabbitMQ](/rabbitmq), [RDS](/rds), [Snowflake](/snowflake), [Supabase](/supabase) |
+| **Source control and collaboration** | [Bitbucket](/bitbucket), [GitHub](/github), [GitHub Actions](/integrations/github-actions), [GitLab](/gitlab), [Google Docs](/google-docs), [Jira](/jira), [Trello](/integrations/trello) |
+| **Workflow orchestration** | [Airflow](/airflow), [Dagster](/dagster), [Prefect](/prefect) |
+| **Messaging** | [Slack](/messaging/slack), [Discord](/messaging/discord), [Telegram](/messaging/telegram), [WhatsApp](/messaging/whatsapp), [Twilio SMS](/messaging/twilio-sms) |
+| **AI coding assistants** | [OpenClaw](/openclaw) |
 
-## Local integrations
+[Multi-instance integrations](/multi-instance-integrations) let you register multiple clusters, regions, or accounts per provider (for example prod and staging Grafana).
 
-Local integrations are configured on the machine running OpenSRE — via the CLI setup wizard or environment variables. They give OpenSRE access to your databases, source control, error trackers, and workflow tools.
+## Hosted (OpenSRE Cloud) setup
 
-```bash
-opensre integrations setup
-```
+Enterprise connectors are configured through the OpenSRE web app at [app.tracer.cloud](https://app.tracer.cloud). Once connected, they are available to all users in your organization.
 
-Or set environment variables and OpenSRE picks them up automatically.
+**Observability.** Connect [Grafana](/grafana) and [Datadog](/datadog) for logs, metrics, traces, and alerts.
 
-| Category | Integrations |
-| --- | --- |
-| **Observability** | [Better Stack](/betterstack), [Honeycomb](/honeycomb), [Coralogix](/coralogix), [Sentry](/sentry) |
-| **Databases** | [MongoDB](/mongodb), [MariaDB](/mariadb), [ClickHouse](/clickhouse), [Kafka](/kafka) |
-| **Source control** | [GitHub](/github), [GitLab](/gitlab), [Bitbucket](/bitbucket) |
-| **Kubernetes releases** | [Helm](/helm) |
-| **Deployments** | [Vercel](/vercel) |
-| **Orchestration** | [Dagster](/dagster), [Prefect](/prefect) |
-| **Incident management** | [OpsGenie](/opsgenie), [Jira](/jira) |
-| **Reporting** | [Google Docs](/google-docs) |
-| **AI coding assistants** | [OpenClaw](/openclaw) |
+**Infrastructure.** Connect [AWS](/aws) to map your environment across clouds and clusters.
 
-### Verify local integrations
+**Communication.** Deliver investigation reports via [Slack, Discord, or Telegram](/messaging/index).
 
-After setup, confirm everything is working:
+<Frame>
+  ![Integrations](/images/integrations.png)
+</Frame>
 
-```bash
-opensre integrations verify
-```
+### Example: Datadog in the web app
 
-To check a specific integration:
+1. **Name** — distinguish between instances (for example `prod` vs `staging`)
+2. **API key** — create in Datadog and paste into OpenSRE
+3. **Application key** — create in Datadog and paste into OpenSRE
 
-```bash
-opensre integrations verify mongodb
-```
+<Frame>
+  ![Connect Datadog](/images/connect_datadog.png)
+</Frame>

docs/integrations/aws.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Investigations overview"
+description: "Start investigations from the interactive shell or CLI, review artifacts, and use plain-language REPL routing"
 ---
 
 Use this workflow when running OpenSRE via the local `opensre` binary.
@@ -23,6 +24,32 @@ Then describe the incident or paste alert context at the prompt. Use `/help` for
 
 When `LLM_PROVIDER` is `openai` or `codex`, `/effort` sets how much reasoning the model applies for that REPL session (`low`, `medium`, `high`, `xhigh`, or `max`). Run `/effort` with no arguments to print the current level and usage; `/status` includes the same field. Other providers ignore this setting (the shell prints a hint). You can also set `OPENSRE_REASONING_EFFORT` to `low`, `medium`, `high`, or `xhigh` in the environment for non-interactive defaults.
 
+### Plain language and compound requests
+
+You do not need to memorize every slash command. Describe what you want in natural language and the REPL planner maps intent to the right actions — often a sequence of slash commands executed in order.
+
+Examples:
+
+| You type | Typical action |
+| --- | --- |
+| "check the health of my opensre and then show connected services" | `/health`, then `/integrations list` |
+| "verify datadog" | `/integrations verify datadog` |
+| "run the sample alert investigation" | `/investigate` with a built-in template |
+| "connect to my remote EC2 instance and send it hello world" | `/remote` subcommands, then a remote investigation |
+
+List-style questions route to **per-domain** commands (there is no global `/list`):
+
+| Intent | Command |
+| --- | --- |
+| Connected integrations | `/integrations list` |
+| Investigation tools | `/tools` |
+| Background tasks | `/tasks` |
+| MCP servers | `/mcp list` |
+| Cron deliveries | `/cron list` |
+| Past REPL sessions | `/sessions` |
+
+For procedural questions ("how do I configure Datadog?"), the assistant answers from docs without running mutating commands unless you ask it to.
+
 ### Direct investigation (`opensre investigate`)
 
 Pass an alert payload to `opensre investigate`:
@@ -33,6 +60,8 @@ opensre investigate -i tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json
 
 You can also use `--interactive` to pick an input file from your terminal UI.
 
+For deployed services by name, see [Remote runtime investigation](/remote-runtime-investigation).
+
 ## 2) Review investigation artifacts
 
 A local run produces structured RCA artifacts such as:
@@ -56,6 +85,10 @@ Each run captures:
 - tool outputs collected from connected integrations
 - final diagnosis and recommended remediation steps
 
+## Session continuity
+
+REPL sessions are persisted under `~/.opensre/sessions/`. When you exit, the shell prints a `/resume <session-id>` hint so you can pick up later. See [Session history](/sessions).
+
 ## Chat
 
 For local binary usage, the primary workflow is file-based (`problem.md`, `report.md`, and optional JSON output).
@@ -69,4 +102,4 @@ local investigation completes.
 
 <Frame>
   ![Slack Alert](/images/slack_alert.png)
-</Frame>
+</Frame>

docs/integrations/macos.mdx

@@ -11,10 +11,10 @@ Masking is **off by default**. Enable it per investigation via environment varia
 
 ## How it works
 
-1. When masking is enabled, `node_investigate` replaces sensitive identifiers in the `evidence` dict with stable placeholders like `<POD_0>`, `<NAMESPACE_0>`, `<CLUSTER_1>`. The placeholder→original map is stored in the investigation state under `masking_map`.
-2. The diagnosis LLM receives masked evidence, so raw identifiers never hit the model.
-3. After the LLM returns its root-cause analysis, `diagnose_root_cause` unmasks the output so downstream state and display code see real identifiers.
-4. `publish_findings` runs a final unmask pass on the Slack message and blocks before delivery, as defence in depth.
+1. When masking is enabled, the investigation step replaces sensitive identifiers in collected evidence with stable placeholders like `<POD_0>`, `<NAMESPACE_0>`, `<CLUSTER_1>`. The placeholder→original map is stored in investigation state.
+2. The diagnosis model receives masked evidence, so raw identifiers never hit the external LLM.
+3. After the model returns its root-cause analysis, OpenSRE restores real identifiers in downstream state and display output.
+4. Report delivery (for example Slack) runs a final unmask pass before sending, as defence in depth.
 
 The same identifier always maps to the same placeholder within a single investigation, so the LLM's reasoning about `<POD_0>` remains coherent.
 

docs/investigation-overview.mdx

@@ -75,6 +75,28 @@ If the prefix is ambiguous (matches more than one session), OpenSRE will ask you
 
 ---
 
+## When you exit
+
+When you leave the REPL, OpenSRE prints your session ID so you can resume later:
+
+| Exit path | Behavior |
+| --- | --- |
+| `/exit` or `/quit` | Prints `Resume this session with:` and `/resume <session-id>`, then goodbye |
+| **Ctrl+C** twice within 2 seconds | Same resume hint, then exits |
+| **Ctrl+D** (EOF) | Same resume hint when no dispatch is running |
+
+Example:
+
+```
+Resume this session with:
+/resume 3f8a1c2d-…
+Goodbye!
+```
+
+Copy the `/resume …` line from the terminal, or find the session later with `/sessions`.
+
+---
+
 ## Starting fresh with context — `/new`
 
 `/new` closes the current session and opens a new one, but carries the conversation forward so you don't lose context: