docs: rewrite for end users and scrub org-specific references

- Rewrote README, getting-started, overlay-guide, troubleshooting,
  and installation docs for clear onboarding
- Added "How it works" section explaining Pi SDK integration
- Removed all internal org references from docs and smoke test
- Deleted internal design docs (000-009), kept user-facing docs only
- Renamed 007-installation.md to installation.md

Author: mr-karan

README.md

@@ -1,112 +1,132 @@
 # pi-sre-mode
 
-A Pi-native incident investigation package for Pi, with support for private overlays.
+An incident investigation mode for [Pi](https://github.com/mariozechner/pi-coding-agent). Open a terminal, start an incident, investigate with real tools, write a report — all without leaving Pi.
 
-## What this is
+## Why
 
-`pi-sre-mode` aims to distill the best parts of the llmduck idea into a Pi package:
+During an incident you're juggling metrics dashboards, log viewers, SSH sessions, and a dozen browser tabs. `pi-sre-mode` puts the investigation loop inside Pi so you can query metrics, grep logs, check service health, and build a timeline in one place.
 
-- guided incident workflow inside Pi
-- reusable SRE skills and prompts
-- read-only safety guardrails
-- connector / environment preflight checks
-- support for private organization overlays without forking the public package
+It ships read-only guardrails by default so you don't accidentally `rm` or `systemctl restart` something mid-investigation.
 
-This repo started docs-first and now includes the initial working scaffold:
+## What you get
 
-- `extensions/incident-mode.ts` — main public extension
-- `src/` — overlay types, state, checks, report helpers, template catalog
-- `skills/` — generic SRE skills
-- `prompts/` — generic incident prompt templates
-- `examples/local-overlay/` — sample overlay package for local testing
+- **`/incident`** — set up investigation context: pick a template (5xx spike, high latency, OOM, etc.), name the service, set a time window. That context follows every subsequent prompt automatically.
+- **`/check-connectors`** — preflight check that your CLIs, auth, and environment are ready before you start digging.
+- **`/report`** — turn the investigation into a markdown report.
+- **`/sudo`** / **`/sudo-off`** — bypass or re-enable the read-only guardrails when you need to.
+- **Built-in investigation skills** — SRE methodology and a generic investigation playbook that guide Pi's reasoning.
+- **7 incident templates** — 5xx spike, high latency, OOM/crash loop, broker issues, service down, deploy regression, resource exhaustion, plus a blank "custom" template.
 
-## Documentation map
+## Quick start
 
-- `docs/README.md` — doc index
-- `docs/000-overview.md` — project thesis, goals, and non-goals
-- `docs/001-product-shape.md` — what the public package should feel like
-- `docs/002-overlay-model.md` — how private overlays layer on top
-- `docs/003-public-package-architecture.md` — public package structure and runtime behavior
-- `docs/004-private-overlay-architecture.md` — private overlay package model
-- `docs/005-mvp.md` — initial build scope
-- `docs/006-build-plan.md` — phased implementation plan
-- `docs/007-installation.md` — installation patterns for global public package + project overlay
-- `docs/008-ecosystem-notes.md` — notes from the Pi package ecosystem
-- `docs/009-release-checklist.md` — first public release checklist
+Install globally:
 
-## Installation
-
-### Recommended real usage
+```bash
+pi install npm:pi-sre-mode
+```
 
-Install the public package globally in `~/.pi/agent/settings.json`:
+Or add to `~/.pi/agent/settings.json`:
 
 ```json
 {
-  "packages": [
-    "npm:pi-sre-mode"
-  ]
+  "packages": ["npm:pi-sre-mode"]
 }
 ```
 
-Install a private overlay project-locally in `.pi/settings.json`:
+Then in Pi:
 
-```json
-{
-  "packages": [
-    "git:git@github.com:your-org/pi-sre-overlay-zerodha.git"
-  ]
-}
+```
+/check-connectors          # verify your environment
+/incident                  # set up context — pick a template, name the service
+investigate elevated p99 for payments-api, start with the timeline
+/report                    # generate a markdown report
 ```
 
-### Local development
+## You don't always need `/incident`
 
-```json
-{
-  "packages": [
-    "/path/to/pi-sre-mode",
-    "/path/to/pi-sre-overlay-zerodha"
-  ]
-}
+Use plain Pi for quick questions:
+
+- "check p99 latency for payments-api over the last 2h"
+- "compare error rates before and after the last deploy"
+- "summarize the Nomad allocation restarts today"
+
+Use `/incident` when you want persistent context, a structured template, guardrails, and a report at the end.
+
+## Private overlays
+
+The public package is generic on purpose. Your team's topology, runbooks, and internal tooling live in a **private overlay** — a separate Pi package that layers org-specific templates, skills, prompts, connector checks, and report paths on top.
+
+Install an overlay per-project:
+
+```bash
+pi install -l git:git@github.com:your-org/pi-sre-overlay.git
 ```
 
-More detailed installation examples are in `docs/007-installation.md`.
+See the [overlay guide](./docs/overlay-guide.md) for how to build one.
 
-## Status
+## Read-only by default
 
-MVP scaffold implemented and validated with both public-only and overlay smoke tests.
+During an active incident, `pi-sre-mode` blocks:
 
-## Smoke test
+- file writes and edits
+- `rm`, `mv`, `sudo`, `kill`, `chmod`, `chown`
+- `systemctl restart/stop`, `nomad job run/stop`
+- mutating AWS CLI commands (create, delete, terminate, etc.)
+- shell trampolines (`bash -c`, `eval`, subshells)
 
-A local smoke test is included at:
+Use `/sudo` to temporarily disable these guardrails. `/sudo-off` re-enables them.
 
-- `examples/smoke-test/smoke-test.mjs`
+## Commands
 
-Example:
+| Command | Purpose |
+|---|---|
+| `/incident` | Start or update investigation context |
+| `/incident-reset` | Clear incident context |
+| `/check-connectors` | Run environment preflight checks |
+| `/report` | Generate a markdown investigation report |
+| `/sudo` | Bypass read-only guardrails |
+| `/sudo-off` | Re-enable read-only guardrails |
 
-```bash
-cd /path/to/pi-sre-mode
+## How it works
+
+`pi-sre-mode` is built entirely on Pi's extension API — no external server, no separate UI, no agent framework. Everything runs inside your Pi session.
+
+- **Prompt injection** — when incident mode is active, `before_agent_start` automatically prepends the incident context (template, service, time window, guardrails) to every prompt. Pi investigates with full awareness of what you're looking at.
+- **Tool interception** — `tool_call` hooks inspect every command before execution and block dangerous ones. This is how read-only guardrails work without a custom sandbox.
+- **Session state** — incident context is persisted in Pi's session entries, so it survives reloads, branches, and forks. Navigate the session tree and your incident follows.
+- **Interactive UI** — `/incident` uses Pi's built-in `select`, `input`, and `confirm` primitives for the setup wizard. Status line and widget show the active incident at a glance.
+- **Inter-extension events** — overlays register themselves by emitting events that the public package listens for. No tight coupling, no imports between packages.
+- **Skills and prompts** — shipped as standard Pi skills/prompts in the package manifest. Pi discovers them automatically.
+
+This means the extension is thin orchestration. The real value is in the skills, prompts, and templates — content that's easy to write and easy to override.
+
+## Docs
+
+- [Getting started](./docs/getting-started.md)
+- [Building an overlay](./docs/overlay-guide.md)
+- [Installation patterns](./docs/installation.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+
+## Examples
+
+- [`examples/local-overlay/`](./examples/local-overlay/) — minimal overlay for testing
+- [`examples/smoke-test/`](./examples/smoke-test/) — automated smoke test via Pi RPC
+
+## Local development
 
-# Public package only
+```json
+{
+  "packages": [
+    "/path/to/pi-sre-mode",
+    "/path/to/your-overlay"
+  ]
+}
+```
+
+```bash
+# public package only
 bun run smoke-test -- --public-only
 
-# Public package + overlay
+# with an overlay
 bun run smoke-test -- --overlay /path/to/private-overlay
 ```
-
-Current commands in the public extension:
-- `/incident`
-- `/incident-reset`
-- `/sudo`
-- `/sudo-off`
-- `/check-connectors`
-- `/report`
-
-Current features:
-- persisted incident-mode session state
-- prompt injection via `before_agent_start`
-- read-only blocking for `write` / `edit` and unsafe bash patterns while incident guardrails are active
-- separate `/sudo` mode to bypass incident permission checks when needed
-- connector preflight checks
-- markdown report generation
-- overlay registration via `incident-mode:register-overlay`
-- RPC-based smoke test for package + overlay integration