# Web Console: Notifications & Human-Attention Routing (#648)

- **Status:** Phase 3 Live
- **Tracking Issue:** [#648](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/648)
- **Parent Epic:** [#631](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/631)
- **Attention Boundary Reference:** [#628](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/628)

---

## 1. Overview

The **Notifications & Human-Attention Console** (`/notifications`, `/api/v1/notifications`) provides intelligent event classification and human-attention routing for autonomous workflow operations.

To prevent alert fatigue while ensuring critical escalation boundaries are never missed, events are classified into three distinct **Attention Classes**:

1. **`human-required`** (Urgent Escalation Boundary):
   - Items requiring immediate human intervention or business decisions.
   - Triggers: Auth failures, hard stops, irrecoverable state, decision locks, failed report validations, critical probe errors.
   - Display: Highlighted in red (`badge-blocked`) with a `HUMAN REQUIRED` badge.

2. **`operator`** (Operational Inbox):
   - Items requiring controller or operator review/triage during routine execution.
   - Triggers: Blocked PRs (merge conflicts), stale leases, duplicate PRs on issues, unassigned ready work.
   - Display: Displayed in orange/yellow (`badge-claimed`).

3. **`routine`** (Background Workflow Transitions):
   - Normal, healthy workflow transitions and state progressions.
   - Triggers: Active PRs/issues in standard state, clean branch creation, routine heartbeats.
   - Display: Filtered out of default inbox views to eliminate notification spam; viewable on demand via the "Routine" or "All" tab.

---

## 2. API Endpoints

### `GET /api/v1/notifications`
*Compatibility Alias:* `GET /api/notifications`

#### Query Parameters:
- `project_id` (optional): Filter notifications by project ID.
- `attention_class` (optional): `inbox` (default: human-required + operator), `human-required`, `operator`, `routine`, `all`.

#### Example JSON Response:
```json
{
  "project_id": "gitea-tools",
  "repo_label": "Scaled-Tech-Consulting/Gitea-Tools",
  "human_required_count": 0,
  "operator_count": 2,
  "routine_count": 5,
  "total_count": 7,
  "fetch_error": null,
  "inbox_items": [
    {
      "id": "notif-pr-block-742",
      "attention_class": "operator",
      "category": "blocker",
      "title": "Blocked PR #742",
      "summary": "PR #742 requires merge conflict resolution.",
      "work_kind": "pr",
      "work_number": 742,
      "project_id": "gitea-tools",
      "repo_label": "Scaled-Tech-Consulting/Gitea-Tools",
      "created_at": "2026-07-25T16:39:47Z",
      "deep_link": "/traffic",
      "requires_human": false,
      "extra": {}
    }
  ],
  "all_items": [...]
}
```

---

## 3. UI Navigation

- Access via the **Traffic** navigation menu: **Traffic → Notifications**.
- The main view displays:
  - **Metrics Summary Bar**: Highlighting counts for Human Required, Operator Inbox, and Routine items.
  - **Attention Filter Tabs**: Toggle between Inbox (Human + Operator), Human Required, Operator, Routine, and All.
  - **Structured Event Table**: Displays category, title, summary, work item links, and timestamps.