# SeoWatcher — Admin Runbook (reporter onboarding)

Short guide for the administrator: how to get access yourself and how to connect the
people who run sites and submit the daily report (`/report`), and then read those
reports through `/seoinsights`.

> All links are at `https://seowatcher.org`. Sign in everywhere with a `key-g.com` Google account.

## 0. Access model (in a nutshell)

- **One server, each person has their own MCP by name.** The MCP name is derived from the email
  of whoever connects (e.g. `ivan.petrov@key-g.com` → `ivan-petrov`). Your own name is shown on
  `/account` (the "MCP NAME" field). The admin does not get a separate server.
- **Permissions = the token's role**, not a separate MCP:
  - `reader` — read inventory/GSC **+ can submit `/report`**;
  - `editor` — same + edit whitelisted inventory fields;
  - `admin` — same + read the team reports (`/seoinsights` → `seoreport_*`) + manage access (`auth_*`).
- **The `admin` role is granted and approved only by the super-admin** — `a.sherbinin@key-g.com`.
  A regular admin approves `reader`/`editor` themselves.

## 1. How you (a new admin) get access

1. Go to `/signup`, sign in with Google (`key-g.com`). The key (`psk_…`) is shown
   **once** — save it right away. Status will be `pending`.
2. Message Alexander (`a.sherbinin@key-g.com`) — he'll approve you and grant the `admin` role
   on `/admin` (only he can grant `admin`).
3. After approval, connect the MCP + skills **in one command** (take/regenerate the key on
   `/account` → **Regenerate** button; your MCP name is there too — the "MCP NAME" field):
   ```sh
   curl -fsSL https://seowatcher.org/install.sh | sh -s -- <YOUR_KEY> <your-mcp-name> admin
   ```
   The `admin` argument installs `/report` **and** `/seoinsights` and connects your MCP.
4. Restart `claude`. Check: `/seoinsights` runs, and the tool list now shows
   `mcp__<your-mcp-name>__seoreport_*`.

## 2. How you onboard reporters (the people who run sites)

For each person:

1. They go to `/signup`, sign in with Google (`key-g.com`), **save the key**.
   Status — `pending`.
2. You on `/admin` → in the **Pending approval** queue click **Approve** (the `reader` role
   is enough for reporting; a regular admin approves `reader`/`editor`, no super-admin needed).
3. They install the `/report` skill and connect the MCP (**without** the `admin` argument; key
   from their own `/account`):
   ```sh
   curl -fsSL https://seowatcher.org/install.sh | sh -s -- <THEIR_KEY> <their-mcp-name>
   ```
4. Once a day they run `/report` — the skill asks for the domain(s), the period, a short summary
   and (once) GitHub/Telegram, then uploads the day's activity **with secrets redacted**.

> ⚠️ Reporting only works with an **email-bound** token (i.e. a self-signup key from
> `/signup` or `/account`). An admin token without an email gets **403** — `/report` needs
> the signup key specifically.

## 3. How you read reports — `/seoinsights`

Run `/seoinsights`, pick a slice:

- **by user** (email) — activity, which skills/MCP they use and which they **don't**
  (what to recommend), their domains and GSC for them;
- **by site** (domain) — who worked, with which methods, owners, the site's GSC;
- **overall overview** of everyone — a per-person table + recommendations;
- a user's **sessions** / a single **transcript**;
- **effectiveness** (`by: skill | mcp | domain`) — success rate, time, errors;
  with `by=domain` it additionally joins GSC (method↔SEO).

The data source is `inventory_claude_sessions` (filled when people run `/report`).
If a person has never submitted `/report`, there'll be no data on them.

## 4. Permissions & guards cheat sheet

- `reader` is enough for reporters. Editing the inventory — `editor`. Reading the team reports — `admin`.
- The `admin` role is granted/approved **only** by the super-admin (`a.sherbinin@key-g.com`).
- The last active admin cannot be demoted/revoked/deleted (lock-out protection).
- Approval / role change / revoke take effect within **~60 seconds** (token cache).

## 5. If it doesn't work

- `/seoinsights` sees no tools → the token isn't `admin`, or the MCP isn't connected, or
  `claude` wasn't restarted.
- `/report` → `HTTP 403 no associated email` → token without an email; regenerate on `/account`
  (**Regenerate**) and configure the new one.
- `/report` → `HTTP 503 export disabled` → the `EXPORT_ENABLED` flag is off on the server,
  message Alexander.