From ea86c396f046514ac85fa99dcb3eb3e15b674df0 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 20:44:23 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=96=20Dashboard=20UI=20map,=20help?= =?UTF-8?q?=20links=20to=20docs.hivecommons.dev,=20and=20a=20Settings=20en?= =?UTF-8?q?try=20per=20tab?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add src/docs/dashboard-ui-map.md with sign-in steps for each kind of dashboard, common actions, and sidebar and Settings tables generated from the dashboard source by src/scripts/render-dashboard-ui-map.py (checked in the docs link workflow). Point v5 help links at docs.hivecommons.dev for pages the docs site publishes. Add the missing Settings tab entries and record the Kapa-side checklist status in the Ask AI design. Refs #19182 Signed-off-by: Andy Anderson --- .github/workflows/docs-link-check.yml | 5 + changelog.d/added-19182-dashboard-ui-map.md | 1 + src/docs/dashboard-sections.md | 2 + src/docs/dashboard-ui-map.md | 154 +++++++++++++++ src/docs/design/dashboard-ask-ai-help.md | 34 ++++ src/docs/settings.md | 38 +++- src/pkg/dashboard/dashboard_docs_href.test.js | 47 +++++ src/pkg/dashboard/static-src/js/sections.js | 17 +- src/pkg/dashboard/static/index.html | 17 +- src/scripts/render-dashboard-ui-map.py | 178 ++++++++++++++++++ 10 files changed, 486 insertions(+), 7 deletions(-) create mode 100644 changelog.d/added-19182-dashboard-ui-map.md create mode 100644 src/docs/dashboard-ui-map.md create mode 100644 src/pkg/dashboard/dashboard_docs_href.test.js create mode 100644 src/scripts/render-dashboard-ui-map.py diff --git a/.github/workflows/docs-link-check.yml b/.github/workflows/docs-link-check.yml index d119c8c47b..911bc5beb5 100644 --- a/.github/workflows/docs-link-check.yml +++ b/.github/workflows/docs-link-check.yml @@ -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/scripts/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 diff --git a/changelog.d/added-19182-dashboard-ui-map.md b/changelog.d/added-19182-dashboard-ui-map.md new file mode 100644 index 0000000000..972e56117f --- /dev/null +++ b/changelog.d/added-19182-dashboard-ui-map.md @@ -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/scripts/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)). diff --git a/src/docs/dashboard-sections.md b/src/docs/dashboard-sections.md index e2aa88ec1b..4e4551a998 100644 --- a/src/docs/dashboard-sections.md +++ b/src/docs/dashboard-sections.md @@ -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: diff --git a/src/docs/dashboard-ui-map.md b/src/docs/dashboard-ui-map.md new file mode 100644 index 0000000000..03293ef6f0 --- /dev/null +++ b/src/docs/dashboard-ui-map.md @@ -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/scripts/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** (). Click **Sign in** or open +, 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** (`.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 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 `/#config/governor/` 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 + + + +### 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**. + + + +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). diff --git a/src/docs/design/dashboard-ask-ai-help.md b/src/docs/design/dashboard-ask-ai-help.md index 680c7d2a16..ccb9719010 100644 --- a/src/docs/design/dashboard-ask-ai-help.md +++ b/src/docs/design/dashboard-ask-ai-help.md @@ -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/scripts/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 diff --git a/src/docs/settings.md b/src/docs/settings.md index 3d6aa43d61..4023630d0a 100644 --- a/src/docs/settings.md +++ b/src/docs/settings.md @@ -4,7 +4,7 @@ This page is the starting point for the dashboard's **Settings** tabs. It has on Every setting on a Settings tab has a small **?** mark next to its name. Rest the pointer on it, or move to it with the Tab key, to see a short explanation of the setting. Click it, tap it, or press Enter on it to open the page that explains the setting in a new tab. When a setting has its own guide, the mark opens that guide; otherwise it opens this page at the tab's entry. Clicking a mark never changes the setting. -For the dashboard's other sections, see [Dashboard sections explained](dashboard-sections.md). If a key has no editable control, see [Editing `hive.yaml`](editing-hive-yaml.md) for file locations and reload behavior. +For the dashboard's other sections, see [Dashboard sections explained](dashboard-sections.md); to find a section or a tab by its on-screen name, see the [Dashboard UI map](dashboard-ui-map.md). If a key has no editable control, see [Editing `hive.yaml`](editing-hive-yaml.md) for file locations and reload behavior. ## Linking to a setting @@ -118,6 +118,42 @@ The **Hub settings** block at the bottom of the tab sets explicit task acceptanc The OpenAI-compatible gateways (LiteLLM, OpenRouter, vLLM, and others) agents send inference through, and their keys. See [Configure model gateways and keys](hosted-hub.md#configure-model-gateways-and-keys). +## Appearance + +The dashboard's look, stored under `dashboard.theme_overrides`: a background image (URL, opacity, position, size, attachment), the UI and monospace fonts, CSS token overrides and custom CSS. See [Appearance themes](dashboard.md#appearance-themes). + +## Agents + +The managed agents (click a name to open that agent's settings tabs, described under [Agent: General](#agent-general) and below) and the **Backend placement policy**, which restricts the CLI or inference backends agents may use. Deny wins over allow, and an empty allow list permits every supported backend. See [Agent Configuration](agent-configuration.md). + +## Workflows + +The workflow library: the workflows this hive can run for its repos. Each control's **?** tooltip explains it. + +## Inbox + +Settings for the [Inbox](dashboard-sections.md#inbox) section. See [Input methods and the Inbox](inbox-input-methods.md) and [Inbox and voice sources](inbox-voice-sources.md). + +## Project Observability + +Targets for the managed project's telemetry and operations agents. Platforms are referenced by name only (an endpoint environment variable and a credential secret reference); literal URLs, tokens and API keys are refused. Hive's own OpenTelemetry export is set elsewhere. See [How to opt in](telemetry.md#how-to-opt-in-governorproject_observability). + +## Meetings + +The connections Hive uses to join meetings: the Vexa tenant key and, for Discord, the bot token and the transcription and speech tokens. The tab shows only whether each secret is set. See [Meetings](meetings.md). + +## Forge App + +The GitHub App (or other forge app) this hive authenticates as, the per-app key files it holds, and the GitHub API budget. See [GitHub App setup](github-app-setup.md) and [GitHub API budget governor](operator-reference/sweeps-and-operations.md#github-api-budget-governor). + +## Bob + +The hive-wide API key for the IBM Bob CLI backend (agents that use bob cannot start without it) and the Bob session prefix. See [Tagging Bob sessions for Bobalytics](backend-support-tiers.md#tagging-bob-sessions-for-bobalytics). + +## Variables + +Named variables that agents' prompt templates can use: each has a name, a type, a scope, and a value or an environment variable, with an optional default. + ## Dashboard Settings for the dashboard itself (`dashboard.*`): its port and agent poll interval, the Experiment Lab, whether the header also shows the usage gauge, hub-proxied auth, Sessions, the dashboard auth token, the access allowlist, and the issue bands. diff --git a/src/pkg/dashboard/dashboard_docs_href.test.js b/src/pkg/dashboard/dashboard_docs_href.test.js new file mode 100644 index 0000000000..593af2a87c --- /dev/null +++ b/src/pkg/dashboard/dashboard_docs_href.test.js @@ -0,0 +1,47 @@ +// Help links on the v5 line open docs.hivecommons.dev for pages the docs site +// publishes, and GitHub for everything else (#19182). +const test = require('node:test'); +const assert = require('node:assert'); +const fs = require('node:fs'); +const path = require('node:path'); + +const src = fs.readFileSync(path.join(__dirname, 'static-src', 'js', 'sections.js'), 'utf8'); +const m = src.match(/ {4}function dashboardDocsHref\(page, anchor\) \{[\s\S]*?\n {4}\}\n/); +assert.ok(m, 'dashboardDocsHref not found'); + +function hrefOn(line) { + const window = { _hiveDocsLine: line }; + return new Function('window', m[0] + '; return dashboardDocsHref;')(window); +} + +test('a published page on v5 opens the docs site with its anchor', () => { + assert.strictEqual( + hrefOn('v5')('dashboard-sections', 'governor'), + 'https://docs.hivecommons.dev/docs/hive/dashboard-sections#governor' + ); + assert.strictEqual( + hrefOn('v5')('dashboard-sections/activity-monitor', ''), + 'https://docs.hivecommons.dev/docs/hive/dashboard-sections/activity-monitor' + ); +}); + +test('an unknown line falls back to v5 and still uses the docs site', () => { + assert.strictEqual( + hrefOn('')('agent-configuration', 'acmm-levels'), + 'https://docs.hivecommons.dev/docs/hive/agent-configuration#acmm-levels' + ); +}); + +test('a page the docs site does not publish opens GitHub', () => { + assert.strictEqual( + hrefOn('v5')('governor-thresholds', 'scaling'), + 'https://github.com/hivecommons/hive/blob/v5/src/docs/governor-thresholds.md#scaling' + ); +}); + +test('another release line opens GitHub, because the docs site follows v5 only', () => { + assert.strictEqual( + hrefOn('v6')('dashboard-sections', 'runs'), + 'https://github.com/hivecommons/hive/blob/v6/src/docs/dashboard-sections.md#runs' + ); +}); diff --git a/src/pkg/dashboard/static-src/js/sections.js b/src/pkg/dashboard/static-src/js/sections.js index cf4ef9ad2f..e1be8f73e9 100644 --- a/src/pkg/dashboard/static-src/js/sections.js +++ b/src/pkg/dashboard/static-src/js/sections.js @@ -186,12 +186,23 @@ 'faq-section': { heading: 'FAQ', help: 'Short answers to the questions people ask once a hive is running, each linking to the guide that explains it fully.' }, }); // The one place that decides where dashboard help lives: every help mark and - // Overview "Learn more" link is built here, so moving them (for example to - // docs.hivecommons.dev) is a single change. Builds that are not on a known + // Overview "Learn more" link is built here. Builds that are not on a known // release line (forks, feature branches, unknown versions) open v5's help. + // docs.hivecommons.dev publishes the v5 line from a curated list + // (hivecommons/docs scripts/sync-hive-docs.files.json), so on v5 a page that + // is on that list opens on the docs site, where the help search and Ask AI + // answers cite it (#19182). Every other page, and every other line, opens + // the Markdown on GitHub. Add a page here only once the docs site serves it + // at /docs/hive/; the constants live inside the function because tests + // evaluate it on its own. function dashboardDocsHref(page, anchor) { + const docsSiteLine = 'v5'; + const docsSiteBase = 'https://docs.hivecommons.dev/docs/hive/'; + const docsSitePages = ['dashboard-sections', 'dashboard-sections/overview-and-metrics', 'dashboard-sections/workflow-and-agents', 'dashboard-sections/activity-monitor', 'dashboard-glossary', 'getting-started', 'agent-configuration', 'acmm-policy-matrix', 'contributor-relay', 'running-at-level-6', 'release-channels', 'stable-soak-policy', 'work-sources', 'webhooks', 'troubleshooting', 'kick-refusals', 'labels-and-control-signals', 'meetings', 'inbox-voice-sources', 'inbox-uploads', 'inbox-recording', 'inbox-input-methods', 'env-vars', 'register-self-hosted-hive']; const line = (typeof window !== 'undefined' && window._hiveDocsLine) || 'v5'; - return `https://github.com/hivecommons/hive/blob/${line}/src/docs/${page}.md${anchor ? '#' + anchor : ''}`; + const hash = anchor ? '#' + anchor : ''; + if (line === docsSiteLine && docsSitePages.includes(page)) return `${docsSiteBase}${page}${hash}`; + return `https://github.com/hivecommons/hive/blob/${line}/src/docs/${page}.md${hash}`; } function dashboardDocsHrefFromPath(path) { const m = /^\/docs\/([\w-]+(?:\/[\w-]+)*)\.md(?:#([\w-]+))?$/.exec(String(path || '')); diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 74e4144f74..5d261aef20 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -11297,12 +11297,23 @@

Where to get help

'faq-section': { heading: 'FAQ', help: 'Short answers to the questions people ask once a hive is running, each linking to the guide that explains it fully.' }, }); // The one place that decides where dashboard help lives: every help mark and - // Overview "Learn more" link is built here, so moving them (for example to - // docs.hivecommons.dev) is a single change. Builds that are not on a known + // Overview "Learn more" link is built here. Builds that are not on a known // release line (forks, feature branches, unknown versions) open v5's help. + // docs.hivecommons.dev publishes the v5 line from a curated list + // (hivecommons/docs scripts/sync-hive-docs.files.json), so on v5 a page that + // is on that list opens on the docs site, where the help search and Ask AI + // answers cite it (#19182). Every other page, and every other line, opens + // the Markdown on GitHub. Add a page here only once the docs site serves it + // at /docs/hive/; the constants live inside the function because tests + // evaluate it on its own. function dashboardDocsHref(page, anchor) { + const docsSiteLine = 'v5'; + const docsSiteBase = 'https://docs.hivecommons.dev/docs/hive/'; + const docsSitePages = ['dashboard-sections', 'dashboard-sections/overview-and-metrics', 'dashboard-sections/workflow-and-agents', 'dashboard-sections/activity-monitor', 'dashboard-glossary', 'getting-started', 'agent-configuration', 'acmm-policy-matrix', 'contributor-relay', 'running-at-level-6', 'release-channels', 'stable-soak-policy', 'work-sources', 'webhooks', 'troubleshooting', 'kick-refusals', 'labels-and-control-signals', 'meetings', 'inbox-voice-sources', 'inbox-uploads', 'inbox-recording', 'inbox-input-methods', 'env-vars', 'register-self-hosted-hive']; const line = (typeof window !== 'undefined' && window._hiveDocsLine) || 'v5'; - return `https://github.com/hivecommons/hive/blob/${line}/src/docs/${page}.md${anchor ? '#' + anchor : ''}`; + const hash = anchor ? '#' + anchor : ''; + if (line === docsSiteLine && docsSitePages.includes(page)) return `${docsSiteBase}${page}${hash}`; + return `https://github.com/hivecommons/hive/blob/${line}/src/docs/${page}.md${hash}`; } function dashboardDocsHrefFromPath(path) { const m = /^\/docs\/([\w-]+(?:\/[\w-]+)*)\.md(?:#([\w-]+))?$/.exec(String(path || '')); diff --git a/src/scripts/render-dashboard-ui-map.py b/src/scripts/render-dashboard-ui-map.py new file mode 100644 index 0000000000..3e66e2c4fa --- /dev/null +++ b/src/scripts/render-dashboard-ui-map.py @@ -0,0 +1,178 @@ +#!/usr/bin/env python3 +"""Render the generated tables in src/docs/dashboard-ui-map.md (#19182). + +The UI map page lists the dashboard's sidebar entries and Settings tabs with +the exact words the screen shows, so a person (or a docs search or Ask AI +answer) can match what they type to what they see. The tables are generated +from the dashboard sources so they cannot drift from the labels: + +- the sidebar groups and entries: src/pkg/dashboard/static-src/html/sidebar.html +- each section's heading and one-line help: DASHBOARD_SECTION_HELP in + src/pkg/dashboard/static-src/js/sections.js +- the Settings tabs and the per-agent tabs: GOVERNOR_CONFIG_TABS and + AGENT_CONFIG_TABS in src/pkg/dashboard/static-src/js/config-state.js + +Only the text between the BEGIN and END markers is rewritten; the rest of the +page is hand-written. + +Usage: + python3 src/scripts/render-dashboard-ui-map.py # rewrite the page + python3 src/scripts/render-dashboard-ui-map.py --check # exit 1 if stale +""" + +import html +import os +import re +import sys + +ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) +DASH = os.path.join(ROOT, "src", "pkg", "dashboard", "static-src") +SIDEBAR = os.path.join(DASH, "html", "sidebar.html") +SECTIONS = os.path.join(DASH, "js", "sections.js") +CONFIG_STATE = os.path.join(DASH, "js", "config-state.js") +DOCS = os.path.join(ROOT, "src", "docs") +PAGE = os.path.join(DOCS, "dashboard-ui-map.md") +SETTINGS_PAGE = os.path.join(DOCS, "settings.md") +SECTIONS_PAGE = "dashboard-sections.md" + +BEGIN = "" +END = "" + +# The Agents group is a live tree of the hive's own agents, not fixed entries. +AGENT_TREE_GROUP = "Agents" + + +def read(path): + with open(path, encoding="utf-8") as f: + return f.read() + + +def anchor(heading): + """GitHub-style heading anchor, matching dashboardSectionHelpAnchor.""" + s = re.sub(r"[^\w\s-]", "", heading.lower()).strip() + return re.sub(r"\s", "-", s) + + +def cell(text): + return html.unescape(text).replace("|", "\\|").strip() + + +def section_help(): + src = read(SECTIONS) + block = re.search(r"const DASHBOARD_SECTION_HELP = Object\.freeze\(\{(.*?)\n\s*\}\);", src, re.S) + if not block: + sys.exit("render-dashboard-ui-map: DASHBOARD_SECTION_HELP not found in sections.js") + entries = {} + pattern = re.compile( + r"'([\w-]+)':\s*\{\s*heading:\s*'((?:[^'\\]|\\.)*)',\s*help:\s*(?:'((?:[^'\\]|\\.)*)'|\"((?:[^\"\\]|\\.)*)\")\s*\}" + ) + for m in pattern.finditer(block.group(1)): + help_text = m.group(3) if m.group(3) is not None else m.group(4) + entries[m.group(1)] = (m.group(2).replace("\\'", "'"), help_text.replace("\\'", "'").replace('\\"', '"')) + if not entries: + sys.exit("render-dashboard-ui-map: no entries parsed from DASHBOARD_SECTION_HELP") + return entries + + +def sidebar_groups(): + src = read(SIDEBAR) + groups = [] + for chunk in re.split(r'
([^<]+)
', chunk) + tree = re.search(r'
]*>.*?([^<]+)', chunk, re.S) + name = (label or tree).group(1).strip() if (label or tree) else "" + items = [] + for m in re.finditer(r']*)>(.*?)', chunk, re.S): + attrs, body = m.group(1), m.group(2) + text = re.search(r'([^<]+)', body) + if not text: + continue + section = re.search(r'data-section="([\w-]+)"', attrs) + items.append((html.unescape(text.group(1)).strip(), section.group(1) if section else None, " hidden" in attrs or "data-feature=" in attrs)) + groups.append((name, items)) + return groups + + +def js_string_list(src, name, consts): + m = re.search(r"const " + name + r" = \[(.*?)\];", src, re.S) + if not m: + sys.exit("render-dashboard-ui-map: %s not found in config-state.js" % name) + out = [] + for tok in re.findall(r"'([^']*)'|([A-Z_]+)", m.group(1)): + if tok[0]: + out.append(tok[0]) + elif tok[1] in consts: + out.append(consts[tok[1]]) + return out + + +def config_tabs(): + src = read(CONFIG_STATE) + consts = dict(re.findall(r"const ([A-Z_]+) = '([^']*)';", src)) + return js_string_list(src, "GOVERNOR_CONFIG_TABS", consts), js_string_list(src, "AGENT_CONFIG_TABS", consts) + + +def settings_headings(): + return {h.strip(): anchor(h.strip()) for h in re.findall(r"^## (.+)$", read(SETTINGS_PAGE), re.M)} + + +def render(): + help_map = section_help() + lines = [BEGIN, "", "### Sidebar", ""] + lines.append("| Sidebar group | Entry | Section heading | What it shows | Help |") + lines.append("|---|---|---|---|---|") + for group, items in sidebar_groups(): + if group == AGENT_TREE_GROUP: + lines.append("| Agents | One entry per agent, plus **+ Add agent** and **+ Group** | | Opens that agent's card. | [Agents](%s#agents) |" % SECTIONS_PAGE) + continue + for text, section, optional in items: + entry = "**%s**%s" % (cell(text), " (only when switched on)" if optional else "") + if section and section in help_map: + heading, help_text = help_map[section] + lines.append("| %s | %s | %s | %s | [%s](%s#%s) |" % (group, entry, cell(heading), cell(help_text), cell(heading), SECTIONS_PAGE, anchor(heading))) + elif section: + lines.append("| %s | %s | | | |" % (group, entry)) + else: + lines.append("| %s | %s | | A link or dialog, not a dashboard section. | |" % (group, entry)) + governor_tabs, agent_tabs = config_tabs() + documented = settings_headings() + lines += ["", "### Settings tabs", ""] + lines.append("Open **⚙ Settings** in the top bar. The tabs, in the order the dialog shows them:") + lines.append("") + lines.append("| Tab | Explained in |") + lines.append("|---|---|") + for tab in governor_tabs: + # A tab's entry is the heading named after it, or one that starts with + # its name ("Security and Access" covers the Security tab). + heading = tab if tab in documented else next((h for h in documented if h.startswith(tab + " ")), None) + ref = "[Settings: %s](settings.md#%s)" % (heading, documented[heading]) if heading else "[Dashboard settings explained](settings.md)" + lines.append("| **%s** | %s |" % (tab, ref)) + lines += ["", "### Agent settings tabs", ""] + lines.append("Open an agent's settings from its card (the ⚙ button) or from **+ Add agent**. The tabs:") + lines.append("") + lines.append(", ".join("**%s**" % t for t in agent_tabs) + ".") + lines += ["", END] + return "\n".join(lines) + + +def main(): + check = "--check" in sys.argv[1:] + page = read(PAGE) + start, end = page.find(BEGIN), page.find(END) + if start < 0 or end < start: + sys.exit("render-dashboard-ui-map: markers not found in %s" % os.path.relpath(PAGE, ROOT)) + updated = page[:start] + render() + page[end + len(END):] + if updated == page: + print("dashboard-ui-map.md is up to date") + return 0 + if check: + print("dashboard-ui-map.md is stale: run python3 src/scripts/render-dashboard-ui-map.py", file=sys.stderr) + return 1 + with open(PAGE, "w", encoding="utf-8") as f: + f.write(updated) + print("rewrote %s" % os.path.relpath(PAGE, ROOT)) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From 20b79ddda2c07c0172be840e3dc36fcf2be5c6b0 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 20:52:44 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=9A=9A=20Move=20the=20UI=20map=20gene?= =?UTF-8?q?rator=20out=20of=20the=20pinned=20src/scripts=20tree?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit src/scripts is pinned by TRUSTED_SCRIPTS_TREE for the integration governance verifier; a docs generator does not belong in that closure. Refs #19182 Signed-off-by: Andy Anderson --- .github/workflows/docs-link-check.yml | 2 +- changelog.d/added-19182-dashboard-ui-map.md | 2 +- src/docs/dashboard-ui-map.md | 4 ++-- src/docs/design/dashboard-ask-ai-help.md | 2 +- .../dashboard/uimap}/render-dashboard-ui-map.py | 10 +++++----- 5 files changed, 10 insertions(+), 10 deletions(-) rename src/{scripts => pkg/dashboard/uimap}/render-dashboard-ui-map.py (94%) diff --git a/.github/workflows/docs-link-check.yml b/.github/workflows/docs-link-check.yml index 911bc5beb5..c0b69f99d6 100644 --- a/.github/workflows/docs-link-check.yml +++ b/.github/workflows/docs-link-check.yml @@ -127,7 +127,7 @@ jobs: # 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/scripts/render-dashboard-ui-map.py --check + 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. diff --git a/changelog.d/added-19182-dashboard-ui-map.md b/changelog.d/added-19182-dashboard-ui-map.md index 972e56117f..2fa2e7ac9d 100644 --- a/changelog.d/added-19182-dashboard-ui-map.md +++ b/changelog.d/added-19182-dashboard-ui-map.md @@ -1 +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/scripts/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)). +- 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)). diff --git a/src/docs/dashboard-ui-map.md b/src/docs/dashboard-ui-map.md index 03293ef6f0..ede96e8f77 100644 --- a/src/docs/dashboard-ui-map.md +++ b/src/docs/dashboard-ui-map.md @@ -9,7 +9,7 @@ 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/scripts/render-dashboard-ui-map.py`, and CI fails when they go stale, so +`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. @@ -67,7 +67,7 @@ terminal, sign in that agent's CLI (for example Copilot or Claude); see ## The map - + ### Sidebar diff --git a/src/docs/design/dashboard-ask-ai-help.md b/src/docs/design/dashboard-ask-ai-help.md index ccb9719010..7007bc21ee 100644 --- a/src/docs/design/dashboard-ask-ai-help.md +++ b/src/docs/design/dashboard-ask-ai-help.md @@ -468,7 +468,7 @@ Re-checked against `hivecommons/docs` main on 2026-11-18: - **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/scripts/render-dashboard-ui-map.py` and checked in + 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 diff --git a/src/scripts/render-dashboard-ui-map.py b/src/pkg/dashboard/uimap/render-dashboard-ui-map.py similarity index 94% rename from src/scripts/render-dashboard-ui-map.py rename to src/pkg/dashboard/uimap/render-dashboard-ui-map.py index 3e66e2c4fa..aede5ee10e 100644 --- a/src/scripts/render-dashboard-ui-map.py +++ b/src/pkg/dashboard/uimap/render-dashboard-ui-map.py @@ -16,8 +16,8 @@ page is hand-written. Usage: - python3 src/scripts/render-dashboard-ui-map.py # rewrite the page - python3 src/scripts/render-dashboard-ui-map.py --check # exit 1 if stale + python3 src/pkg/dashboard/uimap/render-dashboard-ui-map.py # rewrite the page + python3 src/pkg/dashboard/uimap/render-dashboard-ui-map.py --check # exit 1 if stale """ import html @@ -25,7 +25,7 @@ import re import sys -ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) +ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", "..")) DASH = os.path.join(ROOT, "src", "pkg", "dashboard", "static-src") SIDEBAR = os.path.join(DASH, "html", "sidebar.html") SECTIONS = os.path.join(DASH, "js", "sections.js") @@ -35,7 +35,7 @@ SETTINGS_PAGE = os.path.join(DOCS, "settings.md") SECTIONS_PAGE = "dashboard-sections.md" -BEGIN = "" +BEGIN = "" END = "" # The Agents group is a live tree of the hive's own agents, not fixed entries. @@ -166,7 +166,7 @@ def main(): print("dashboard-ui-map.md is up to date") return 0 if check: - print("dashboard-ui-map.md is stale: run python3 src/scripts/render-dashboard-ui-map.py", file=sys.stderr) + print("dashboard-ui-map.md is stale: run python3 src/pkg/dashboard/uimap/render-dashboard-ui-map.py", file=sys.stderr) return 1 with open(PAGE, "w", encoding="utf-8") as f: f.write(updated)