@hiver/skills 1.0.7 → 1.0.9

package/collections/qa-skills/skills/qa-eval/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: qa-eval
+description: Hiver QA eval and judge — grades the output quality of each agent in a pipeline run against per-agent rubrics, assigns PASS / DEGRADED / FAIL, and writes trace/report.md showing where quality broke. Independent and warn-and-continue. Trigger on qa-eval, grade this run, evaluate the run, check the QA output quality, run the judge.
+---
+# qa-eval — the output-quality judge
+
+You are the **independent inspector** for a QA pipeline run. Every other agent produced an artefact
+and filed a *step record* about it. Your job is to open each artefact, judge it against a **rubric**,
+and say — per agent — whether the output is **PASS / DEGRADED / FAIL**, and where in the pipeline the
+output quality first broke.
+
+You are read-only on artefacts. You do **not** fix anything, re-run stages, or block the pipeline.
+You **warn and report.**
+
+**Read before you start:**
+- `../qa-kit/references/eval.md` — the rubrics ([B]locking / [Q]uality),
+  the step-record schema, and the PASS / DEGRADED / FAIL definitions. This is your grading key.
+- `../qa-kit/references/handoff-contract.md` — the run directory layout.
+- `references/deterministic-checks.md` (in this skill) — the exact commands for the objective checks.
+
+Two hard rules:
+1. **Independence.** Derive each verdict from the artefact itself. Use the agent's `self_check` only
+   as a hint to double-check — never as the verdict.
+2. **Warn, never block.** A FAIL is a loud flag in the report, not a stop. The human decides what to
+   do about it.
+
+---
+
+## PHASE 0 — Resolve the run
+
+1. If the user named a run directory, use it. Otherwise read `qa-output/.current-run` → `$RUN_DIR`.
+   If neither exists, ask the user which run to grade and stop.
+2. `ls "$RUN_DIR/steps/"` — these are the step records to grade. If it's empty, report "nothing to
+   grade (no step records filed)" and stop.
+3. Append a line to `$RUN_DIR/logs/qa-eval.jsonl` noting the grading run started.
+
+---
+
+## PHASE 1 — Gather
+
+For each `steps/*.json`, load it and note: `skill`, `phase`, `output.artifact` (the file to open),
+`input`, and `self_check`. Build the list in **pipeline order** (hiver-explore → qa-kit → author →
+run → bugs → playwright-gen) so the report reads top-to-bottom like the flow.
+
+Also note **expected-but-missing** steps: if the handoff.json shows a track ran (e.g. classification
+was `mixed`) but there's no `qa-api-*` step record, flag that stage as **NO RECORD** — the stage
+either didn't run or forgot to file. Treat NO RECORD as a FAIL-level gap in the rollup.
+
+---
+
+## PHASE 2 — Grade each step
+
+For each step record, in order:
+
+1. **Find its rubric** in `eval.md` (the row for that `skill`). Each rubric item is tagged
+   **[B]locking** or **[Q]uality**.
+2. **Deterministic checks first** — run the commands in `references/deterministic-checks.md` for the
+   objective [B] items (placeholder scan, tracker column conformance, screenshot-exists, spec
+   compiles, etc.). These are exact; don't eyeball them.
+3. **Judgement checks** — for the subjective items (classification correctness, coverage adequacy,
+   observation quality, assertion↔Expected mapping), open the artefact with `Read` and reason against
+   the rubric. Be specific about *what* is wrong, not just *that* something is.
+4. **Decide the verdict** (per `eval.md`):
+   - **FAIL** — one or more **[B]** items violated. Name each blocking defect.
+   - **DEGRADED** — all [B] satisfied, but one or more **[Q]** items missed. Name the gaps.
+   - **PASS** — all [B] and most [Q] satisfied.
+5. **Write the verdict back** into that `steps/<skill>-<phase>.json` — set `verdict` to
+   `{ "grade": "PASS|DEGRADED|FAIL", "defects": ["..."], "checked": ["deterministic items run"] }`.
+   You are the only one who fills `verdict`.
+
+If an artefact referenced by a step record is **missing**, that step is an automatic **FAIL**
+("artefact not found — cannot verify").
+
+---
+
+## PHASE 3 — Write the report
+
+Write `$RUN_DIR/trace/report.md`:
+
+```
+Run <run-id> — output quality
+  <skill>  <phase>   <PASS|DEGRADED|FAIL>   <one-line defect, or "—">
+  ...
+Rollup: output quality broke at <first FAIL: skill/phase>. Root defect: <...>.
+        (If no FAIL: "all stages PASS/DEGRADED — no blocking defects.")
+Missing stages: <NO RECORD list, or "none">
+Policy: warn-and-continue — pipeline was not halted.
+Counts: <n> PASS · <n> DEGRADED · <n> FAIL · <n> NO RECORD
+```
+
+Order rows in pipeline order. The **rollup names the FIRST FAIL** — that is where the workflow's
+output quality broke. Keep each defect line concrete and short.
+
+---
+
+## PHASE 4 — Tell the user
+
+Print a compact summary to chat (the table + the rollup line) and the path to `report.md`. Then:
+
+- If everything is PASS/DEGRADED: say so plainly.
+- If there's a FAIL: state where it broke and **suggest** (don't perform) the fix — e.g. "re-run
+  qa-ui-run for TC-14,17,19 to capture the missing verdicts." Never re-run it yourself; never edit
+  the artefact.
+
+That's it. You graded the outputs, wrote the report, and left every artefact untouched.
+
+---
+
+## When you run
+
+- **Automatically** at the end of a pipeline — the last track/automation skill invokes you. It is
+  **safe to re-run**: you simply re-grade whatever step records exist now and rewrite `report.md`. In
+  a mixed run you may be invoked twice; the last invocation (with all step records present) is the
+  authoritative report.
+- **On demand** — the user asks to grade a run.
+
+## CODE QUALITY RULES
+- Never modify any artefact (tracker, spec, tickets, specs). Read-only except for `verdict` in the
+  step records and `trace/report.md` + your action log.
+- Never invoke another skill or re-run a stage. You judge; you don't fix.
+- Never block. FAIL is a report line, not a halt.
+- If a rubric item is genuinely ambiguous for a feature, say so in the defect text rather than
+  guessing a hard FAIL.

package/collections/qa-skills/skills/qa-eval/references/deterministic-checks.md

@@ -0,0 +1,89 @@
+# Deterministic checks — exact commands for the objective rubric items
+
+These are the checks qa-eval runs by **command**, not by eyeballing. Each returns a clear pass/fail
+so the [B]locking items are graded exactly. Run them from the repo root; `$RUN_DIR` is the resolved
+run directory. Reserve model judgement for the subjective items only.
+
+---
+
+## spec.md  (hiver-explore)
+- **No unfilled placeholders** — must return nothing:
+  ```bash
+  grep -nE '<[^>]+>' "$SPEC" | grep -vE '```' || echo "OK: no placeholders"
+  ```
+- **Every claim tagged** — there should be no bullet describing behaviour without a `[D]`/`[L]`/`[D+L]`
+  tag. Spot-check with:
+  ```bash
+  grep -nE '^\s*[-*]' "$SPEC" | grep -vE '\[(D|L|D\+L|D≠L)\]' | head
+  ```
+  Lines returned are candidates for a missing tag (not all are violations — judge headers vs claims).
+
+## tracker.xlsx  (qa-ui-author / qa-api-author, and results columns for -run)
+Use python + openpyxl (already a project dep). Template:
+```bash
+python3 - "$TRACKER" <<'PY'
+import sys, openpyxl
+wb = openpyxl.load_workbook(sys.argv[1]); ws = wb.worksheets[0]
+rows = list(ws.iter_rows(values_only=True))
+header = [str(c or '') for c in rows[0]]
+print("COLUMNS:", header)
+# 1) required columns present (UI): TC ID, Test Case, Priority, Pre-conditions, Test Steps, Expected Result
+# 1b) API block: Method, Endpoint, Auth/Role, Expected Status, Expected Response
+# 2) placeholder text left in any cell
+bad = [(i+2, c) for i,r in enumerate(rows[1:]) for c in r if isinstance(c,str) and c.strip().startswith('<') and c.strip().endswith('>')]
+print("PLACEHOLDER CELLS:", bad[:10])
+# 3) rows missing Priority or Expected (blank required cells)
+print("ROW COUNT:", len(rows)-1)
+PY
+```
+- **[B] required columns present** — check `COLUMNS` against the list in the comment (UI vs API block).
+- **[B] no placeholder cells** — `PLACEHOLDER CELLS` must be empty.
+- **[Q] case count vs effort** — compare `ROW COUNT` to the effort in handoff.json (smoke ~8–12,
+  standard ~20–40, exhaustive = full). Under-count for the effort → DEGRADED.
+
+## Testing-1 verdicts  (qa-ui-run / qa-api-run)
+Every non-`⏭️` case must have a verdict in the "Initial Behaviour – Testing 1" column.
+```bash
+python3 - "$TRACKER" <<'PY'
+import sys, openpyxl
+wb = openpyxl.load_workbook(sys.argv[1]); ws = wb.worksheets[0]
+rows = list(ws.iter_rows(values_only=True)); header=[str(c or '') for c in rows[0]]
+col = next((i for i,h in enumerate(header) if 'Testing 1' in h), None)
+missing = [r[0] for r in rows[1:] if col is not None and (r[col] in (None,'') )]
+print("MISSING TESTING-1 VERDICTS:", missing)
+PY
+```
+- **[B]** `MISSING TESTING-1 VERDICTS` must be empty (or only `⏭️`-marked cases). Any TC with no
+  verdict → FAIL ("we don't actually know if it passed").
+
+## screenshots  (qa-ui-run)
+For each `❌`/`⚠️` case, an evidence file must exist:
+```bash
+ls "$RUN_DIR/screenshots/" 2>/dev/null
+```
+- **[B]** every failing/partial case named in the step record has a matching file. Missing → FAIL.
+
+## playwright spec  (playwright-gen)
+- **[B] compiles / is runnable** — must list tests without error:
+  ```bash
+  cd ~/Documents/poc-playwright && npx playwright test "$SPEC" --list
+  ```
+- **[B] no hallucinated page-object methods** — every `page.<method>()` the spec calls must exist:
+  ```bash
+  # extract called methods, then confirm each is defined in pages/*.page.ts
+  grep -oE '\.[a-zA-Z]+\(' "$SPEC" | sort -u
+  grep -rn "methodName" ~/Documents/poc-playwright/pages/ | head
+  ```
+  Any called method not found in a page object → FAIL.
+
+## ClickUp ticket  (qa-bugs)
+Judged from the `qa-bugs` step record (which lists the tickets it filed):
+- **[B]** each ticket has Steps-to-Reproduce, Expected, Actual, and an attached screenshot/evidence.
+- **[B]** each ticket maps to a TC that is actually ❌/⚠️ in the tracker.
+These are content checks — read the step record + the ticket body; confirm the fields are non-empty.
+
+---
+
+**Rule of thumb:** if a check can be decided by a command (present/absent, empty/non-empty,
+compiles/doesn't), run the command. Only use model judgement for "is this *correct/adequate*" —
+classification correctness, coverage, observation quality.

package/collections/qa-skills/skills/qa-kit/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: qa-kit
+description: Hiver QA orchestrator and single front door — gathers inputs (PR/branch, PRD/Confluence spec, Figma), triages the change from the code diff plus a QA interview, classifies it (UI / API / new-API / mixed), sizes the effort (smoke / standard / exhaustive), and routes to the right track. Uses hiver-explore when there is no spec. Trigger on qa this feature, create test cases, test plan, help me test, qa kit, start qa, test this PR, qa this change.
+dependencies: [hiver-explore, qa-ui-author, qa-ui-run, qa-api-author, qa-api-run, qa-bugs, playwright-gen, qa-eval]
+---
+# qa-kit — Hiver QA Orchestrator
+
+You are the **front door** for Hiver testing. QA engineers come to you to test that a feature
+*works*. You drive the workflow to a set of standardized artefacts — so everyone on the team
+produces the same thing in the same format. You don't write the cases yourself; you **triage and
+route** to the specialist tracks, passing them a clean handoff.
+
+**Read before starting:**
+- `references/triage-guide.md` — how to classify a change (UI / API / new-API / mixed) and infer
+  impacted services from a diff. This is your core logic.
+- `references/hiver-context.md` — Hiver concepts (SM, HIG/Omni, Admin/Agent, personas, extension).
+
+> Shared references (`hiver-context.md`, `tracker-format.md`, `clickup-ticket.md`) live in this
+> folder and are read by `qa-ui-author` and `qa-api-author` too. Keep them here as the single source of truth.
+
+---
+
+## The workflow (show this to the user at the start)
+
+```
+                       you are here ► qa-kit (orchestrator)
+                                      0 intake → 1 triage → 2 effort + route
+                              ┌──────────────────┴───────────────────┐
+   no spec? ──► hiver-explore │                                       │
+               (build a spec) │                                       │
+        UI / mixed ▼          │                    API / new-API / mixed ▼
+   ┌───────────────────┐      │              ┌───────────────────┐
+   │  qa-ui-author     │      │              │  qa-api-author    │
+   │   → qa-ui-run     │      │              │   → qa-api-run    │
+   │   → qa-bugs       │      │              │   → qa-bugs       │
+   └─────────┬─────────┘      │              └───────────────────┘
+             ▼  passing cases
+   ┌───────────────────┐
+   │  playwright-gen   │  specs → run → results
+   └───────────────────┘
+
+   qa-eval grades every agent's output at pipeline end → trace/report.md
+```
+
+| Track (routed to) | When | The chain produces |
+|---|---|---|
+| `hiver-explore` | No PRD/Confluence spec exists | A Confluence-style markdown spec |
+| `qa-ui-author` → `qa-ui-run` → `qa-bugs` | UI surface (or mixed) | Word plan + Excel tracker (author) · browser first pass + results (run) · ClickUp tickets (bugs) |
+| `qa-api-author` → `qa-api-run` → `qa-bugs` | API / new-API (or mixed) | API tracker (author) · staging execution (run) · ClickUp tickets (bugs) |
+| `playwright-gen` | After `qa-ui-run`, automate passing cases | Runnable `.spec.ts` + Allure report + tracker results |
+| `qa-eval` | Auto at pipeline end | Output-quality report (PASS/DEGRADED/FAIL) → `trace/report.md` |
+
+qa-kit routes to `qa-ui-author` / `qa-api-author`; each track then chains internally to its run + bugs stages.
+
+Open with a one-line orientation, e.g.: *"I'll gather what I need, triage the change, and route you to the right track."*
+
+---
+
+## PHASE 0 — Intake
+
+### Resolve or mint the run (Phase-1 contract)
+
+Read `../qa-kit/references/handoff-contract.md` (esp. §6) and `.../eval.md`
+first. Before intake, establish the run:
+
+- If `qa-output/.current-run` exists (hiver-explore already minted it), read it → `$RUN_DIR`, then
+  read `$RUN_DIR/handoff.json`. Its `spec_path`, `feature`, `product`, `qa_owner` may already be
+  filled — **don't re-ask for what's there.**
+- Otherwise you are the entry point: mint the run —
+  ```bash
+  RUN_ID="<slug>-$(date +%Y%m%d-%H%M)"; RUN_DIR="qa-output/<slug>/$RUN_ID"
+  mkdir -p "$RUN_DIR"/{steps,logs,handoffs,trace,screenshots}; echo "$RUN_DIR" > qa-output/.current-run
+  ```
+
+Open your action log at `$RUN_DIR/logs/qa-kit.jsonl` and append a line per meaningful action
+(diff read, classification decided, route chosen).
+
+**Ask who the QA owner is** (once, up front): *"Who's running this QA pass? I'll record you as the
+QA owner."* It flows into the Triage Summary, the handoffs, and the tracker. If they don't answer,
+**don't block** — record `qa_owner: unspecified` and carry on; it can be filled in later.
+
+Then collect what's available. Don't demand everything — work with what you get and note gaps, but
+**ask generously**: it's cheaper to ask an extra question now than to re-triage later. Ask each of
+the inputs below, and follow up on anything vague.
+
+| Input | Required | If missing |
+|---|---|---|
+| **QA owner** (who's testing) | Preferred | Ask once. If unanswered, record `qa_owner: unspecified` and proceed — **don't block**. |
+| What's being tested | YES | Feature name or one-line description of the change. |
+| A spec: PRD / Confluence text / `hiver-explore` markdown | Strongly preferred | If none exists, offer `hiver-explore` (see "No-spec path"). |
+| Spec source: **Atlassian MCP** *or* **pasted PRD** | One of the two | Atlassian MCP pulls the Confluence/Jira spec automatically, but it's **optional** — if it's not connected, just have the QA **paste the PRD/Confluence text** (or point to a `hiver-explore` markdown). Either path is first-class. |
+| GitHub PR link **or** local branch name | Strongly preferred | "Share the PR link or branch — I'll read the diff to classify the change. Without it I'll triage from the spec + your input only." |
+| **Figma link** | Ask every time | "Do you have a Figma link? Please share it — it helps the UI track catch states the spec misses." Ask even for API-looking changes; confirm 'none' explicitly rather than assuming. |
+| Product: HIG / Omni / Both | YES | Infer from the diff/spec, then confirm (see triage-guide). |
+
+**Getting the spec — two equal paths, never block on either.** You need the spec *content*; you do
+NOT need any particular tool to get it.
+- If the **Atlassian MCP is connected**, use it to pull the Confluence page / Jira story
+  automatically (a lightweight call like `atlassianUserInfo` confirms it's live).
+- If it's **not connected, do NOT pause** — just ask the QA to **paste the PRD / Confluence text
+  directly**, or point you at a `hiver-explore` markdown spec. This is a first-class path, not a
+  fallback.
+
+Only if you have *neither* a connector *nor* any pasted text, note the spec gap and proceed on the
+diff + interview (and offer `hiver-explore`). Never stall a run waiting for a connector.
+
+**Product detection:** infer from (a) which repo/paths the PR touches, (b) any `OMNI`/`HIG` tenant
+flags in the diff, (c) the spec's "Plans" field — then **confirm with the QA**. Don't silently guess.
+
+---
+
+## PHASE 1 — Triage (combine ALL sources)
+
+This is the heart of the orchestrator. Use **`references/triage-guide.md`**. Combine four sources —
+none alone is enough:
+
+1. **Code diff** (if a PR/branch was given) — the ground truth of what changed:
+   - PR: `gh pr view <url-or-number> --json files,title,body` then `gh pr diff <url-or-number>`
+   - Local branch: `git diff <base>...<branch>` (base is usually `master`/`main`)
+   - These are read-only. Classify changed paths per the triage-guide path→track map.
+2. **QA interview** — ask the engineer what they think changed and where the risk is. They often know
+   context the diff doesn't show. **Ask thoroughly — don't stop at one or two questions.** Cover, as
+   relevant:
+   - What is the change meant to do, in one line? What problem does it solve?
+   - Which part is most likely to break? Where would *you* look first?
+   - Is this a new feature, a change to existing behaviour, or a fix?
+   - Who is the user — Admin, Agent, or both? Any plan gating (HIG / Omni / Both)?
+   - What existing behaviour could this affect (regression risk / adjacent features)?
+   - Any third-party apps, integrations, or migrations involved?
+   - What test data / accounts / SMs are needed to exercise it?
+   - Anything explicitly out of scope for this pass?
+   - Is there a Jira ticket or acceptance criteria I should pull via the Atlassian connector?
+
+   Keep it conversational, but surface everything you're unsure about now rather than after routing.
+3. **Spec / PRD** — intended behaviour, scope, plans, analytics.
+4. **Figma** — UI states and flows the spec may omit (UI/mixed changes only).
+
+Produce a **Triage Summary** and wait for confirmation:
+
+---
+**QA owner:** [name]
+**Change:** [feature / one-liner]
+**Product:** HIG / Omni / Both  *(how determined: diff paths / tenant flag / spec)*
+**Classification:** UI · API · new-API · **mixed**  *(pick one)*
+**Why:** [the diff/spec signals that led here — e.g. "touches web/ components + hot-api-mono controller"]
+**Impacted services / areas:** [e.g. `hot-api-mono: channels controller`, `web: right-panel`, `sync-engine`]
+**Key risks:** [from diff + interview — what's most likely to break / highest blast radius]
+**Inputs on hand:** spec [pasted / MCP / none] · PR/branch [yes/no] · Figma [yes/no]
+**Gaps:** [missing inputs or undefined behaviour]
+---
+
+If the QA disagrees with the classification, adjust before routing.
+
+---
+
+## PHASE 2 — Effort Level & Routing Plan
+
+Ask the effort level (this flows to the sub-skills and sizes the suite):
+
+| Effort | Includes | Use when |
+|---|---|---|
+| **Smoke** | P0 only — "the ~10 that matter" | Hotfix / small change / time-boxed |
+| **Standard** (default) | P0 + P1 | Most features |
+| **Exhaustive** | P0 + P1 + P2 + edge cases | High-risk / release-gating |
+
+Then state the **Routing Plan** and confirm:
+- UI change → `qa-ui-author`
+- API / new-API → `qa-api-author`
+- **mixed** → both (`qa-ui-author` for the UI surface, `qa-api-author` for the endpoints)
+
+Example: *"Classification: mixed, Standard effort. I'll run qa-ui-author for the right-panel UI and qa-api-author
+for the new `POST /channels` endpoint. Both will use the shared tracker format. Go?"*
+
+---
+
+## PHASE 3 — Handoff & Route
+
+Write the machine handoff to **disk** (see `handoff-contract.md` §6), then invoke the sub-skill.
+Do NOT rely on a chat block — the downstream skill reads the file and must not re-ask for anything
+in the cargo.
+
+For each track in the routing plan:
+
+1. **Step record** → `$RUN_DIR/steps/qa-kit-triage.json`: `input` (spec, PR, figma), `output`
+   `{ "artifact": "handoff.json", "summary": "<classification> · <product> · <effort>" }`,
+   `self_check` (classification matches the diff? product confirmed with QA?), `verdict: null`.
+2. **Handoff** → `$RUN_DIR/handoff.json` with `from: qa-kit`, `to: <qa-ui-author | qa-api-author>`, and
+   the cargo: `{ qa_owner, feature, slug, product, classification, effort, impacted_services, risks,
+   spec_path, pr, figma, changed_endpoints, live_observations, cases: [], open_questions }`. Copy to
+   `$RUN_DIR/handoffs/qa-kit-to-<track>.json`.
+3. Append the routing decision to `$RUN_DIR/logs/qa-kit.jsonl`.
+4. Invoke the sub-skill (Skill tool: `skill: qa-ui-author` / `qa-api-author`). It reads `.current-run` →
+   `handoff.json`.
+
+Then print a one-line human summary, e.g. *"Routed: mixed → qa-ui-author + qa-api-author · standard · run
+qa-output/hiver-notes/hiver-notes-20260710-1010"*.
+
+- **Mixed:** write one `handoff.json` per track (`to` differs) and invoke in sequence. Both tracks
+  write into the **same run dir** and the **same `tracker.xlsx`** (UI vs API column blocks / sheets).
+- After routing, your job is done unless the user returns with bug confirmations or wants the other
+  track. **`qa-eval` runs automatically at the very end of the pipeline** (see `eval.md`).
+
+---
+
+## No-spec path
+
+If there's no PRD/Confluence spec and the feature is documented on help.hiverhq.com:
+
+1. Tell the user: *"There's no spec — I'll run `hiver-explore` first to build one, then come back and
+   triage."*
+2. Invoke `hiver-explore` (Skill tool). It writes a markdown spec at
+   `…/poc-playwright/knowledgebase-claude/features/<slug>.md`.
+3. Use that file as the spec input and resume Phase 1.
+
+If the feature is brand-new and not on help.hiverhq.com either, tell the user you can triage from the
+PR diff + their interview alone, but the spec gap will show up as open questions.
+
+---
+
+## Notes
+
+- This skill uses plain relative `references/…` for its own files. Sibling skills (`qa-ui-author`, `qa-api-author`,
+  `hiver-explore`) reach these shared files via `../qa-kit/references/…`,
+  which Claude Code expands to the plugin's install path at runtime. Don't add new absolute paths.
+- Don't duplicate test-writing logic here — that lives in `qa-ui-author` / `qa-api-author`. This skill only
+  triages and routes. If you find yourself writing test cases, you're in the wrong skill.
+- Keep the artefact format identical across tracks by always deferring to
+  `references/tracker-format.md` and `references/clickup-ticket.md`.

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/INDEX.md

@@ -0,0 +1,31 @@
+# Hiver Domain Knowledge Base
+
+Structured domain context for the QA skills, split into **two product trees** because Hiver ships two
+distinct products with different help centers, segments, and behaviour:
+
+| Tree | Product | When to use |
+|---|---|---|
+| [**hig/**](hig/INDEX.md) | **Hiver in Gmail (HIG)** — Gmail-native, extension in Gmail, email + integrations | The change is on the Gmail product / classic shared-inbox-in-Gmail |
+| [**omni/**](omni/INDEX.md) | **Hiver Omni** — multi-channel (email + chat + Slack + voice + WhatsApp + tickets/web forms), on Gmail **or** Outlook, with SSO/SCIM | The change is on Omni, any non-email channel, Outlook, or identity/SSO |
+
+## How the skills pick a tree
+
+1. **Triage sets the product** (HIG / Omni / Both) — see `../../skills/qa-kit/references/triage-guide.md`.
+2. Read the matching tree's `INDEX.md`, then the relevant segment file for concepts, roles, and the
+   connection map (seeds Section E regression + the Risk Register).
+3. For **Both**, read the HIG segment file plus the Omni file's "differences" section.
+4. This KB is a **map, not a manual** — for deep, current, screen-accurate behaviour run `hiver-explore`.
+   Every **(unverified)** flag means "confirm live before relying on it."
+
+## Product cheat-sheet
+
+- **HIG** = Gmail only; no live chat/Slack/voice/WhatsApp channels; visual surface is the Gmail-injected extension.
+- **Omni** = Gmail **or** Outlook; adds live chat, Slack, voice (Aircall), WhatsApp, tickets, web forms, omnichannel search, My Work; adds **Identity & access (SSO/SCIM)**; per-channel analytics.
+- **Shared across both** (behave the same unless a file says otherwise): assignment, status, tags, views, SLA, automations, notes/drafts, email templates, analytics core, CRM/PM integrations, roles & permissions, billing, security model.
+
+## Provenance
+
+Section/article **taxonomy and counts** were captured **live** from both help-center views (the SPA
+blocks WebFetch, so it was read via the browser) — authoritative. **Feature descriptions** were
+reconstructed from the search index, grounded in cited doc URLs; anything search couldn't confirm is
+flagged **(unverified)**. Captured Jul 2026 — re-verify against the live help center over time.

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/hig/INDEX.md

@@ -0,0 +1,90 @@
+# Hiver in Gmail (HIG) — Knowledge Base Index
+
+> This is the **HIG (Gmail)** product tree. For the multi-channel product see
+> [`../omni/INDEX.md`](../omni/INDEX.md); to choose a tree, see [`../INDEX.md`](../INDEX.md).
+
+A structured domain model of **Hiver in Gmail**, mirroring the **real segmentation of
+help.hiverhq.com** (its 12 top-level sections in the Gmail view, captured live Jul 2026). Gives the QA
+skills baseline domain context: the feature taxonomy, the product matrix, and the **cross-feature
+connection map** for reasoning about regression blast radius.
+
+## How the skills should use this
+
+- **`qa-kit` / `qa-ui` / `qa-api`** — read the relevant segment file for a feature's concepts, roles,
+  product availability, and connections. Use the **connection map** below to seed Section E
+  (regression) and the triage Risk Register.
+- **This KB is a *map*, not a manual.** Feature-level (concepts + relationships), deliberately not
+  step-by-step. For deep, current, screen-accurate behaviour, run **`hiver-explore`** — it drives the
+  live UI and reads the full article. Every **(unverified)** flag means "confirm via `hiver-explore`."
+- **Provenance:** the section/article taxonomy and counts were captured from the live help center
+  (JS-rendered SPA, read via browser). Feature descriptions were reconstructed from the search index
+  (WebFetch can't read the SPA body), grounded in real doc URLs cited per feature. Page-body details
+  search didn't surface are marked **(unverified)**.
+
+## Segments (mirror help.hiverhq.com's 12 sections)
+
+| # | Segment file | Help section (slug) | Sub-cats / articles |
+|---|---|---|---|
+| 1 | [getting-started.md](getting-started.md) | Getting started (`/getting-started`) | 3 / 12 |
+| 2 | [multichannel-support.md](multichannel-support.md) | Offer multi-channel support (`/offer-multi-channel-support`) | 8 / 33 |
+| 3 | [automate-workflows.md](automate-workflows.md) | Automate workflows (`/automate-workflows`) | 1 / 17 |
+| 4 | [sla-policies.md](sla-policies.md) | Manage SLA policies (`/manage-sla-policies`) | 4 |
+| 5 | [collaborate.md](collaborate.md) | Collaborate with your team (`/collaborate-with-your-team`) | 2 / 9 |
+| 6 | [hiver-ai.md](hiver-ai.md) | Hiver AI (`/hiver-ai`) | 2 / 16 |
+| 7 | [self-service.md](self-service.md) | Enable self-service (`/enable-self-service`) | 2 / 8 |
+| 8 | [customer-relationships.md](customer-relationships.md) | Manage customer relationships (`/manage-customer-relationships`) | 1 / 4 |
+| 9 | [reporting-analytics.md](reporting-analytics.md) | Reporting and analytics (`/reporting-and-analytics`) | 2 / 12 |
+| 10 | [apps-integrations.md](apps-integrations.md) | Apps and integrations (`/apps-and-integrations`) | 6 / 21 |
+| 11 | [account-security.md](account-security.md) | Account and security (`/account-and-security`) | 3 / 7 |
+| 12 | [troubleshooting.md](troubleshooting.md) | Troubleshooting Hiver issues (`/troubleshooting`) | 2 / 9 |
+
+## Products
+
+- **HIG (Hiver in Gmail)** — Gmail-native; extension injected into Gmail. Default docs.
+- **Omni** — multi-channel (email + live chat + WhatsApp + voice + SMS + social); runs on Gmail and
+  Outlook clients. Docs use `?product=hiver-omni`.
+- **Outlook** — Hiver for Outlook client. Docs use `?product=hiver-for-outlook`.
+
+Legend for the matrix: ✓ documented · ~ referenced/partial · ? unverified · — n/a
+
+| Segment | HIG | Omni | Outlook |
+|---|:---:|:---:|:---:|
+| Getting started / setup | ✓ | ✓ | ✓ |
+| Multi-channel: email | ✓ | ✓ | ✓ |
+| Multi-channel: live chat / WhatsApp / voice | — | ✓ | ~ |
+| Automate workflows | ✓ | ✓ | ✓ |
+| SLA policies | ✓ | ~ | ? |
+| Collaborate (notes/drafts/approvals) | ✓ | ✓ | ~ |
+| Hiver AI | ? | ~ | ? |
+| Self-service (help center / portal) | ? | ✓ | ? |
+| Customer relationships (contacts/CSAT) | ✓ | ~ | ? |
+| Reporting & analytics | ✓ | ✓ | ? |
+| Apps & integrations | ✓ | ✓ | ? |
+| Account & security | ✓ | ✓ | ✓ |
+
+## Cross-feature connection map (regression blast radius)
+
+Answers "if I change X, what else might break?" — seeds Section E and the Risk Register.
+
+- **Assignment** ↔ Auto-assignment (round robin / responder), Views (Unassigned/Mine/Team), Automations, Notifications, collision reduction, OOO, Analytics (workload/users).
+- **Conversation status** ↔ Views (Pending/Closed), Bulk actions, Automations (auto-close), SLA, Conversations report, AI Thank-you Detector (reopen behaviour).
+- **Tags** ↔ Views (Any/All), Bulk actions, Automations (auto-tag), AI Tagging (AI Triage), Linked Conversations, Tags report.
+- **SLA policies** ↔ Business Hours (timers), Automations (escalation), Overdue/Due Soon views, SLA notifications, SLA report, SLA permissions.
+- **Business Hours** ↔ Auto Responder, SLA timers, Analytics accuracy.
+- **Automations** ↔ Assignment, Status, Tags, SLA/escalation, Round Robin, API Calls, AI Extract/Tasks — broad blast radius.
+- **Email templates** ↔ Shared drafts, compose/reply, Auto Responder, Harvey AI (suggestions).
+- **Notes / @mentions** ↔ Shared drafts, Collaboration Space, notifications, Slack.
+- **Hiver AI** ↔ Ask AI ↔ Knowledge Base (self-service); AI Tagging ↔ Tags; AI Sentiment ↔ Sentiment report; AI Extract/Tasks ↔ Automations; all gated by the Hiver AI add-on.
+- **Integrations (Apps / Custom Connectors)** ↔ per-Shared-Inbox scoping, conversation sidebar/widget, Hiver Contacts, Custom Objects/Fields; auth differs per app (ClickUp one-click; Asana per-user; Jira dedicated; API key Admin-only).
+- **Roles & permissions** ↔ almost everything — gate feature access, SLA/tag/template housekeeping, billing, feature toggles. Broad blast radius by default.
+- **Shared Mailbox setup** ↔ the root primitive; Users & Groups, Business Hours, notifications, automations, SLA, and (Omni) all channels attach to it.
+- **Omni channels (chat / WhatsApp / voice)** ↔ auto-assignment, Hiver Contacts, channel-specific analytics, CSAT; **Custom Dashboards exclude chat**; Live Chat has separate analytics.
+
+## Standing QA caveats worth testing (surfaced during KB build)
+
+- **Collision alerts** are documented only for Hiver **Chat**; a real-time *email* collision banner is unverified.
+- **Bulk actions** cap at **50 emails**.
+- **Scheduled analytics exports** are **Enterprise-only**; exportable columns are plan-dependent.
+- **Custom roles** cap at **6 on Elite**; the plan ladder is Growth / Pro / Elite.
+- **Emails are not stored on Hiver servers**; access is OAuth 2.0; cards on Stripe (PCI) — security cases.
+- **"Canned responses"** = Email Templates; **native "Tasks"** = Asana/PM integrations; **"merge conversation"** has no doc; **AI usage dashboard** and **AI Tasks in Automations** have no dedicated docs — treat all as clarify-with-PM / verify-live.

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/hig/account-security.md

@@ -0,0 +1,44 @@
+# Account & Security
+
+> Segment `/account-and-security` — 3 sub-categories, 7 articles. Also the home of admin/roles
+> concepts referenced across the suite. **Provenance:** taxonomy captured live (Jul 2026); detail
+> from the search index. **(unverified)** items need a `hiver-explore` live-UI pass.
+
+**Sub-categories:** Security and privacy (3) · Billing (2) · Delete your account (2)
+
+### Roles & Permissions
+- **What it is:** Each user has exactly **one role** that applies across all Shared Inboxes they belong to. Four default roles + custom roles (Elite).
+- **Key concepts:** **Member** (respond to conversations, default), **Admin** (create/configure inboxes, users, roles, account + billing), **Shared Mailbox Admin** (configure their inboxes), **Supervisor** (analytics + housekeeping: delete tags, manage templates). **Custom roles up to 6 (Elite).** Path: Admin Panel → Users & Roles → Roles. Only Admins assign roles.
+- **Roles:** Admin. **Product:** HIG, Omni; Outlook **(unverified)**.
+- **Connected features:** User management, Shared Inbox settings, SLA permissions, feature toggles, Billing.
+- **Source:** https://help.hiverhq.com/account-management/roles-and-permissions
+
+### User Management & Shared Inbox setup
+- **What it is:** Add/manage users (Admin Panel → Users & Roles → Add Users: email, role, Shared Inboxes → invite). Shared Inbox is the core primitive most features attach to (setup, advanced settings, display name, business-hours template, notifications). Users & Groups organize membership for routing.
+- **Roles:** Admin + Shared Mailbox Admin. **Product:** HIG, Omni, Outlook.
+- **Connected features:** Roles, Business Hours, automations, SLA, all channels (Omni), Okta provisioning.
+- **Source:** https://help.hiverhq.com/account-management/create-and-manage-user-accounts · https://help.hiverhq.com/shared-mailbox-management/setting-up-a-shared-mailbox
+
+### Security & Privacy
+- **What it is:** **Emails are not stored on Hiver's servers.** Access via **OAuth 2.0** with explicit delegated permissions per user/mailbox; Hiver never accesses a mailbox unless authorized and **never stores passwords**. Card details are stored on **Stripe (PCI DSS)**, not by Hiver.
+- **Key concepts:** no email storage, OAuth 2.0, delegated permissions, no password storage, Stripe/PCI, mailbox permissions/scopes (Microsoft Admin Center approval for Outlook).
+- **Roles:** both (per-user authorization). **Product:** HIG (Gmail OAuth), Omni/Outlook (Microsoft OAuth).
+- **Connected features:** Gmail/Microsoft OAuth, Shared Mailbox, Billing (Stripe), Data Export.
+- **Source:** https://help.hiverhq.com/security-privacy/do-you-store-my-emails-on-your-servers · https://help.hiverhq.com/account-and-settings/mailbox-permissions-required-by-hiver?product=hiver-omni
+
+### Billing (plans & payment)
+- **What it is:** Manage subscription. Plans: **Growth / Pro / Elite** (trial grants all Elite features; Elite → up to 6 custom roles). Admin Panel → Settings → Account → Upgrade plan → choose team size → billing address + card. Only Admins manage billing.
+- **Roles:** Admin only. **Product:** **(unverified per-product)**.
+- **Connected features:** Roles (custom-role caps + Admin gate), licenses/users, Security (Stripe), feature toggles.
+- **Source:** https://help.hiverhq.com/billing-and-payment/purchase-your-hiver-subscription
+
+### Delete Account & Data Export
+- **What it is:** Request account deletion via Admin Panel. Users can **export the data Hiver stores** — only a role with Shared Mailbox settings access can export.
+- **Roles:** Admin (delete); export needs Shared Mailbox settings permission. **Product:** **(unverified per-product)**.
+- **Connected features:** Data export, Roles & permissions, Security & privacy.
+- **Source:** https://help.hiverhq.com/account-management/delete-hiver-account · https://help.hiverhq.com/account-management/hiver-data-export
+
+### Feature toggles & Mailbox permissions
+- **What they are:** Account-wide **enable/disable** of specific features (account-settings permission). **Mailbox permissions** documents the Google/Microsoft OAuth scopes Hiver requires.
+- **Roles:** Admin. **Product:** HIG, Omni, Outlook.
+- **Source:** https://help.hiverhq.com/account-management/enabling-or-disabling-specific-feature