Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/docs-link-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,11 @@ jobs:
- name: Check src/docs file:line citations
run: python3 src/scripts/check-docs-citations.py src/docs

# The sidebar and Settings tables in the dashboard UI map are generated
# from the dashboard source so their labels match the screen (#19182).
- name: Check the dashboard UI map is current
run: python3 src/pkg/dashboard/uimap/render-dashboard-ui-map.py --check

# Security docs must stay readable by a non-expert: Flesch-Kincaid grade
# 11 or lower for SECURITY.md and the src/docs/security*/ioscan* set.
- name: Self-test the security docs readability checker
Expand Down
1 change: 1 addition & 0 deletions changelog.d/added-19182-dashboard-ui-map.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Dashboard help now opens docs.hivecommons.dev: on the v5 line, a section or setting "?" mark that points at a page the docs site publishes opens it there instead of the Markdown on GitHub, so the site search and its Ask AI widget can cite the same page; other pages and other release lines still open GitHub. A new [Dashboard UI map](src/docs/dashboard-ui-map.md) page lists the sidebar entries, the Settings tabs and the per-agent tabs with their on-screen labels, how to sign in to the hosted hub, a hosted hive and a self-hosted hive, and where common actions live; its tables are generated from the dashboard source by `src/pkg/dashboard/uimap/render-dashboard-ui-map.py` and CI fails when they go stale. Dashboard settings explained now has an entry for every Settings tab ([#19182](https://github.com/hivecommons/hive/issues/19182)).
2 changes: 2 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

This page explains every section of the Hive dashboard in plain words. It is written for someone running Hive for the first time.

To find where a section or a setting is on screen, see the [Dashboard UI map](dashboard-ui-map.md).

Every section title on the dashboard has a small **?** mark next to it. Rest the pointer on it, or move to it with the Tab key, to see one sentence about the section. Click it, tap it, or press Enter on it to open this page at that section's entry.

Each entry answers the same questions in the same order:
Expand Down
154 changes: 154 additions & 0 deletions src/docs/dashboard-ui-map.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
# Dashboard UI map

Where things are in the Hive dashboard, using the words the screen shows. Use
this page to find a section or a Setting by name, then follow the link for the
full explanation. For what each section means, see
[Dashboard sections explained](dashboard-sections.md); for every Settings tab,
see [Dashboard settings explained](settings.md); for the words the dashboard
uses, see the [dashboard glossary](dashboard-glossary.md).

The tables under [The map](#the-map) are generated from the dashboard source
(the sidebar markup, the section help registry and the Settings tab lists) by
`src/pkg/dashboard/uimap/render-dashboard-ui-map.py`, and CI fails when they go stale, so
the labels here match the labels on screen. The rest of the page is written by
hand.

## Signing in

Which sign-in you need depends on where the dashboard runs.

**The hosted hub** (<https://hive.hivecommons.dev>). Click **Sign in** or open
<https://hive.hivecommons.dev/login>, then pick a provider: the hosted hub
offers **Continue with GitHub**, **Continue with Google**, **Continue with
IBMid** and **Continue with Microsoft**. After signing in, **My Hives**
(`/dashboard`, also `/my-hives`) lists your hives. A self-hosted hub shows only
the providers its operator configured, and goes straight to the provider when
there is only one; see
[Self-hosted hub deployment](hub-deployment.md#minimal-hub-environment). The
full hosted walkthrough is [Hosted Hive Hub onboarding](hosted-hub.md#1-sign-in).

**A hosted hive's dashboard** (`<id>.hive.hivecommons.dev`). Open it from
**My Hives** on the hub. The hub checks your hub sign-in before it lets a
request through to the hive, so there is no second login; if you are not
signed in you land on the hub sign-in page.

**A self-hosted hive's dashboard.** Click **Sign in** in the top bar. The
dashboard opens **Sign in with GitHub** and shows a short code: click **Copy**,
then **Open GitHub →**, enter the code at <https://github.com/login/device> and
approve. The dashboard notices the approval and signs you in. If it shows
**GitHub App Setup Required** instead, the hive has no GitHub App or OAuth
client configured yet; follow the choice it offers. Who may sign in, and which
paths stay public, are set under `dashboard:` in `hive.yaml`; see
[Dashboard auth and access problems](troubleshooting.md#dashboard-auth-and-access-problems).

Signing in to the dashboard is not the same as logging in an agent's coding
tool. The **Login** buttons on an agent card, and `/login` inside an agent's
terminal, sign in that agent's CLI (for example Copilot or Claude); see
[Troubleshooting](troubleshooting.md).

## Common actions

| To do this | Go here |
|---|---|
| Open Settings | **⚙ Settings** in the top bar, or **Settings** in the account menu. A link of the form `<dashboard>/#config/governor/<tab>` opens a given tab ([Linking to a setting](settings.md#linking-to-a-setting)). |
| Find a setting by name | Open Settings and type in its search box. |
| Add a repository | Settings, **Repos** tab: type `org/repo` or a GitHub URL, click **+ Add**, then **Save & close**. See [Repos](settings.md#repos). |
| Pause or resume one agent | Sidebar, **Admin**, **Agents**: on the agent's card click **⏸ pause**, and **▶ resume** to lift it. Owner only. See [Resuming a paused agent](dashboard.md#resuming-a-paused-agent). |
| Pause every agent at once | The fleet breaker chip in the top bar. Releasing it restores only the agents the breaker paused. |
| Configure one agent | The ⚙ button on the agent's card opens its settings tabs (listed below). |
| Add an agent | Sidebar, **Agents** group: **+ Add agent**. |
| Change the ACMM level | The level chip in the top bar, or Settings, **General**. See [ACMM levels](agent-configuration.md#acmm-levels-agent-rosters-as-packs). |
| See what is waiting on you | Sidebar, **Dashboard**, **Hive activity monitor**. |
| Approve or reject a proposed action | The **Approvals** section. |
| Change the dashboard theme | Settings, **Appearance**. See [Appearance themes](dashboard.md#appearance-themes). |
| Choose which sections show and in what order | Drag a section by its ⠿ grip, or reorder the **Dashboard** group in the sidebar. See [Reorder sections](dashboard.md#reorder-sections). |
| Read what a section means | The **?** mark beside its heading opens its entry in [Dashboard sections explained](dashboard-sections.md). |
| Report a bug | Sidebar, **Help**, **Report an Issue**. |

## The map

<!-- BEGIN GENERATED: dashboard-ui-map (src/pkg/dashboard/uimap/render-dashboard-ui-map.py) -->

### Sidebar

| Sidebar group | Entry | Section heading | What it shows | Help |
|---|---|---|---|---|
| Dashboard | **Overview** | Overview | How many issues and pull requests Hive is tracking right now, and how many of them it can work on. | [Overview](dashboard-sections.md#overview) |
| Dashboard | **Hive activity monitor** | Hive activity monitor | A progress strip per open issue and pull request showing which step of the pipeline it is on and who must act next. | [Hive activity monitor](dashboard-sections.md#hive-activity-monitor) |
| Dashboard | **Governor** | Governor | How busy Hive thinks your projects are right now, and how often it wakes its workers as a result. | [Governor](dashboard-sections.md#governor) |
| Dashboard | **Throughput** | Throughput | How many pull requests were opened, merged and closed over a chosen time window, and who did the work. | [Throughput](dashboard-sections.md#throughput) |
| Collaborate | **Inbox** | Inbox | Voice recordings and dictations waiting for you to file them as an RFC or keep as knowledge. | [Inbox](dashboard-sections.md#inbox) |
| Collaborate | **Calendar** | Calendar | Meetings hive will join, about a minute before each starts: add one, approve or decline requests, or skip and cancel. | [Calendar](dashboard-sections.md#calendar) |
| Collaborate | **Meetings** | Meetings | Meetings hive joins to take notes: send it to one, follow the live transcript, notes and research, or make it leave. | [Meetings](dashboard-sections.md#meetings) |
| Collaborate | **Customers** (only when switched on) | Customers | The people you build for: who each one is, what they are trying to get done, and how it is going for them. | [Customers](dashboard-sections.md#customers) |
| Collaborate | **Inception (spek)** (only when switched on) | Inception (spek) | Named terminal sessions running command-line AI tools inside Hive; everyone who can see one watches live and one person at a time holds the keyboard. | [Inception (spek)](dashboard-sections.md#inception-spek) |
| Agents | One entry per agent, plus **+ Add agent** and **+ Group** | | Opens that agent's card. | [Agents](dashboard-sections.md#agents) |
| Resources | **Projects** | Projects | One card per repository Hive looks after, listing its open issues and pull requests grouped by what each one needs next. | [Projects](dashboard-sections.md#projects) |
| Resources | **Contributors** | Contributors | The people who lend their computers or AI helpers to your projects, and how far Hive trusts each of them. | [Contributors](dashboard-sections.md#contributors) |
| Intelligence | **Advisory** | Advisory | Reports, advice and suggestions Hive has written about your projects and about how it is running. | [Advisory](dashboard-sections.md#advisory) |
| Intelligence | **ACMM Eval** | ACMM Eval | How ready your repositories are for Hive to work on them alone, scored against a published checklist. | [ACMM Eval](dashboard-sections.md#acmm-eval) |
| Intelligence | **Knowledge** | Knowledge | The facts Hive has learned about your projects, where they came from, and how much Hive trusts each one. | [Knowledge](dashboard-sections.md#knowledge) |
| Intelligence | **Experiment Lab (nous)** (only when switched on) | Experiment Lab | An experimental planner that tries out code changes in your repositories and records what it learned. | [Experiment Lab](dashboard-sections.md#experiment-lab) |
| Admin | **Tokens** | Tokens | How much text the AI models read and wrote for Hive recently, broken down by model and by worker. | [Tokens](dashboard-sections.md#tokens) |
| Admin | **Cost** | Cost | What Hive's use of AI models would cost at public per-token list prices; an estimate, not a bill. | [Cost](dashboard-sections.md#cost) |
| Admin | **Review** | Review | Review Pipeline shows pull requests by stage first; Review Queue lists the same open pull requests in Hive's suggested review order. | [Review](dashboard-sections.md#review) |
| Admin | **Agents** | Agents | Each worker Hive runs, what it is doing now, and buttons to pause, restart or configure it. | [Agents](dashboard-sections.md#agents) |
| Admin | **Agent activity** | Agent activity | One line per worker showing what it is doing now, how long since it last acted, and which issues it has reserved. | [Agent activity](dashboard-sections.md#agent-activity) |
| Admin | **Audit Log** | Audit Log | A searchable record of everything Hive has done, newest first. The collapsed “sensitive” badge opens a 24h sensitive-only view, matching the server-side risk count. | [Audit Log](dashboard-sections.md#audit-log) |
| Admin | **Lifecycle Timeline** | Lifecycle Timeline | A timeline of recent pull requests, from when they were opened to when they were merged or got stuck. | [Lifecycle Timeline](dashboard-sections.md#lifecycle-timeline) |
| Admin | **Diagnostics** | Diagnostics | Health checks for Hive itself, such as its connections, credentials and safety switches, to help you find out why something is not working. | [Diagnostics](dashboard-sections.md#diagnostics) |
| Help | **FAQ** | FAQ | Short answers to the questions people ask once a hive is running, each linking to the guide that explains it fully. | [FAQ](dashboard-sections.md#faq) |
| Help | **Getting Started** | | A link or dialog, not a dashboard section. | |
| Help | **API Spec (Redoc)** | | A link or dialog, not a dashboard section. | |
| Help | **Getting Started Guide** | | A link or dialog, not a dashboard section. | |
| Help | **Join our Discord** | | A link or dialog, not a dashboard section. | |
| Help | **Watch live on Twitch** | | A link or dialog, not a dashboard section. | |
| Help | **Report an Issue** | | A link or dialog, not a dashboard section. | |

### Settings tabs

Open **⚙ Settings** in the top bar. The tabs, in the order the dialog shows them:

| Tab | Explained in |
|---|---|
| **General** | [Settings: General](settings.md#general) |
| **Appearance** | [Settings: Appearance](settings.md#appearance) |
| **Dashboard** | [Settings: Dashboard](settings.md#dashboard) |
| **Agents** | [Settings: Agents](settings.md#agents) |
| **Thresholds** | [Settings: Thresholds](settings.md#thresholds) |
| **Labels** | [Settings: Labels](settings.md#labels) |
| **Repos** | [Settings: Repos](settings.md#repos) |
| **Workflows** | [Settings: Workflows](settings.md#workflows) |
| **Budget** | [Settings: Budget](settings.md#budget) |
| **Notifications** | [Settings: Notifications](settings.md#notifications) |
| **Health** | [Settings: Health](settings.md#health) |
| **Sensing** | [Settings: Sensing](settings.md#sensing) |
| **Logging** | [Settings: Logging](settings.md#logging) |
| **Features** | [Settings: Features](settings.md#features) |
| **Knowledge** | [Settings: Knowledge](settings.md#knowledge) |
| **Inbox** | [Settings: Inbox](settings.md#inbox) |
| **Project Observability** | [Settings: Project Observability](settings.md#project-observability) |
| **Meetings** | [Settings: Meetings](settings.md#meetings) |
| **Meeting attendee** | [Settings: Meeting attendee](settings.md#meeting-attendee) |
| **Advisory** | [Settings: Advisory](settings.md#advisory) |
| **Work Source** | [Settings: Work Source](settings.md#work-source) |
| **Hub** | [Settings: Hub](settings.md#hub) |
| **Forge App** | [Settings: Forge App](settings.md#forge-app) |
| **Model Gateways** | [Settings: Model Gateways](settings.md#model-gateways) |
| **Bob** | [Settings: Bob](settings.md#bob) |
| **Variables** | [Settings: Variables](settings.md#variables) |
| **Security** | [Settings: Security and Access](settings.md#security-and-access) |
| **Compliance** | [Settings: Compliance](settings.md#compliance) |

### Agent settings tabs

Open an agent's settings from its card (the ⚙ button) or from **+ Add agent**. The tabs:

**General**, **Cadences**, **Pipeline**, **Hooks**, **Restrictions**, **Channels**, **Tools**, **Connections**, **Variables**, **Stats**, **Prompt Template**, **Prior Prompts**, **Export**.

<!-- END GENERATED: dashboard-ui-map -->

Sections without a sidebar entry (for example **Governor** sub-cards such as
**PRs by model**, **Advisory Digest** and **Hive Advice**) appear inside the
section above them and are explained in
[Dashboard sections explained](dashboard-sections.md).
34 changes: 34 additions & 0 deletions src/docs/design/dashboard-ask-ai-help.md
Original file line number Diff line number Diff line change
Expand Up @@ -456,6 +456,40 @@ Work that follows from it:
top-question analytics to feed unclear docs and labels back into the pages
above.

### Status of the docs coverage work (#19182)

Re-checked against `hivecommons/docs` main on 2026-11-18:

- **Sync list.** The main dashboard page (`dashboard.md`), the Settings page
(`settings.md`), hosted hub onboarding (`hosted-hub.md`), hub deployment
(`hub-deployment.md`) and the telemetry page (`telemetry.md`) were on the docs
repo's deliberate-omission list, so the site and Kapa had none of them. The
docs repo change that follows this issue moves them onto the site.
- **UI map.** [Dashboard UI map](../dashboard-ui-map.md) lists the sidebar
entries, the Settings tabs and the per-agent tabs with their on-screen labels,
how to sign in to each kind of dashboard, and where common actions live. Its
tables are generated by `src/pkg/dashboard/uimap/render-dashboard-ui-map.py` and checked in
CI. [Dashboard settings explained](../settings.md) now has an entry for every
Settings tab.
- **Help links.** On the v5 line, `dashboardDocsHref` opens docs.hivecommons.dev
for pages the site publishes and GitHub for the rest; other lines stay on
GitHub because the site follows v5 only.
- **Ingestion.** The vendor's website source does offer per-source "Exclude
URLs" (substring or regex) and "Exclude selectors" (skip a page that contains
a CSS or XPath selector), which settles the earlier unverified note. ADRs share
a URL prefix and can be excluded by URL; design records are mixed into the
site's Reference section, so the docs site marks them with an element the
vendor can exclude by selector. Adding those two exclusions is a source edit
for the project owner.
- **Vendor-side checklist.** Done: PII masking for questions is on (all six
built-in entity types); a website widget integration exists for
`https://docs.hivecommons.dev` only; a customization scopes answers to Hive
Commons help and politely refuses off-topic questions, and the widget uses it.
Requested from the vendor: a higher per-team chat limit, GitHub Discussions as
a source, and a corrected name for the issues source. Still to do: the two
ingestion exclusions above, a regular look at coverage gaps and top questions,
and the Ask-specific telemetry and consent wording once phases 1 and 2 ship.

## Phases

Hub first, then hive. Each phase is its own issue, is off by default, and is
Expand Down
Loading
Loading