From bc7c7069f4d029ac1cd5a31bb8cb6ff1fea1684b Mon Sep 17 00:00:00 2001 From: Karibhou <157208370+Karibhou@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:52:02 +0100 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=96=20docs:=20prepare=20Ask=20AI?= =?UTF-8?q?=20dashboard=20help=20coverage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Generate the navigation map from dashboard sources and document Ask data, consent, and the Kapa rollout checklist. Hive-Run: hivecommons/hive#19182 Hive-Plan: Ask AI help phase 3 — Docs coverage Hive-Spec: dashboard-ask-ai-help.md#docs-coverage-in-kapa Co-authored-by: clubanderson <407614+clubanderson@users.noreply.github.com> Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com> --- changelog.d/added-ask-ai-docs-coverage.md | 1 + src/docs/dashboard.md | 28 +++++ src/docs/design/dashboard-ask-ai-help.md | 127 +++++++++++++--------- src/docs/hosted-hub.md | 12 ++ src/docs/settings.md | 9 ++ src/docs/telemetry.md | 22 +++- 6 files changed, 144 insertions(+), 55 deletions(-) create mode 100644 changelog.d/added-ask-ai-docs-coverage.md diff --git a/changelog.d/added-ask-ai-docs-coverage.md b/changelog.d/added-ask-ai-docs-coverage.md new file mode 100644 index 0000000000..45f7e9148e --- /dev/null +++ b/changelog.d/added-ask-ai-docs-coverage.md @@ -0,0 +1 @@ +- Added a generated dashboard navigation map and documented Ask AI help, consent, and rollout checks ([#19182](https://github.com/hivecommons/hive/issues/19182)). diff --git a/src/docs/dashboard.md b/src/docs/dashboard.md index 44783fa20e..c4eedd90dd 100644 --- a/src/docs/dashboard.md +++ b/src/docs/dashboard.md @@ -1,5 +1,12 @@ # Spoke dashboard +## Pausing an agent + +On the hive dashboard, open **Agents** in the sidebar and select the worker. +As a hive owner, choose **⏸ pause** on its card. This pauses the individual +agent, not the fleet, and is separate from disabling the agent or changing +its per-mode cadences. + ## Resuming a paused agent On the agent card, hover or focus the information icon beside **paused** to @@ -81,6 +88,27 @@ Every dashboard section title has a small **?** mark. Hovering or focusing it sh Settings fields use the same **?** mark, rendered by `settingHelpMark(page, anchor, label, tip)`: hovering or focusing it shows the setting's tooltip, and clicking it opens the guide that explains the setting, or the tab's entry in [Dashboard settings explained](settings.md), through the same `dashboardDocsHref`. Clicking the mark never changes the setting. +Use the [dashboard UI map](dashboard-ui-map.md) to match section headings to +their sidebar locations and Settings tabs. + +## Optional Ask AI help + +Where an operator has enabled **Ask**, the panel answers dashboard navigation +questions with links to the docs. Answers are AI-generated; check the cited +page before acting. Use the `?` marks or the docs directly if Ask is off, +unavailable, or has no cited answer. + +Ask is off by default. Before your first question, review and accept the +disclosure in the panel. Consent is recorded server-side for your signed-in +dashboard identity, not shared with other users, and can be withdrawn in the +panel. Hive asks again if the disclosure changes. Withdrawal stops future +requests; it does not erase questions already sent. + +When you submit a question, Hive sends what you typed and, if enabled, a +fixed dashboard section label to Kapa.ai. Project administrators can read +questions in Kapa analytics. Do not paste secrets or private details. +See [Ask data and consent](telemetry.md#ask-ai-help) for the full payload. + ## Design system Dashboard UI changes should follow the shared [dashboard design system](dashboard-design-system.md), [dashboard glossary and sidebar IA](dashboard-glossary.md), and [ADR-0018](adr/0018-dashboard-design-tokens.md). The token layer is the theme contract for future user theme/background work and the migration path away from static inline styles; `go test ./pkg/dashboard/... -run StyleRatchet -v` ratchets inline styles and raw CSS values so the debt only goes down. diff --git a/src/docs/design/dashboard-ask-ai-help.md b/src/docs/design/dashboard-ask-ai-help.md index 7007bc21ee..83327e005b 100644 --- a/src/docs/design/dashboard-ask-ai-help.md +++ b/src/docs/design/dashboard-ask-ai-help.md @@ -405,56 +405,75 @@ own decision. ## Docs coverage in Kapa -UI-navigation answers are only as right as the pages the vendor ingests and the -labels those pages use. The vendor re-crawls websites daily and picks up changes -within minutes for most sources, and reports crawls that look unusual for -approval; that suits the docs site. - -What must be ingested: - -- The published docs site `docs.hivecommons.dev`, as the source of record. The - dashboard answers link to its pages. -- Specifically the operator pages that describe the UI by its labels: the - dashboard sections explained and its per-section pages, the dashboard glossary, - getting started, agent configuration, the environment variable reference, the - registered self-hosted hive page and the hub, hosted and fleet pages. - -What the audit of the sync list found (read from a local clone of -`hivecommons/docs`, so re-check against its main branch **(unverified)**): - -- The dashboard sections, glossary, agent configuration, getting started, - environment variables, self-hosted registration and the hub, configuration and - dashboard API reference pages are in the list. -- Pages the dashboard's own "?" marks and the hosted flow rely on, such as the - main dashboard page, hosted hub and hub deployment pages, are not in the list I - read. A question about them would be answered from nothing or from a less - authoritative page. - -Work that follows from it: - -1. **Fill the gaps in the sync list and nav map** for the pages above, so the - site, and therefore the vendor, has them. -2. **Add a UI map page**: one table generated from the dashboard's section - registry (heading, where it is in the sidebar, the Settings tab that changes - it), so the words a person types ("Add repo", "Pause agent") match the words - on the screen. A generated page cannot drift from the labels. -3. **Exclude from ingestion** the design records, ADRs and runbooks under - `src/docs/design/` and `src/docs/adr/`, because pages marked "proposed" read as - current behaviour to a retrieval engine. Also exclude issues, pull requests - and chat history. The vendor's per-source include and exclude patterns are not - described in the pages read, so the exclusion may need to be done at the - source (the sync list) rather than in the vendor **(unverified)**. -4. **Link targets**: today's help links point at GitHub blobs for the running - release line. The citation allowlist accepts both the docs host and that - GitHub path, and a later change can move the help links to the docs site in - one place (`dashboardDocsHref`). -5. **Vendor-side settings (a checklist for the project owner, no credentials in - the repo):** enable PII masking for questions; set the customization to scope - answers to Hive dashboard help and to refuse off-topic questions and - instructions; keep the integration's enabled-domains list to what is needed; - ask the vendor to raise the per-team chat limit; use the coverage-gap and - top-question analytics to feed unclear docs and labels back into the pages - above. +Use the published Hive operator docs on `docs.hivecommons.dev` as the source +of record. The [dashboard UI map](../dashboard-ui-map.md) is generated from +the UI sources so its headings and navigation labels can be indexed without +maintaining another copy. Include it alongside the +[spoke dashboard](../dashboard.md), [settings](../settings.md), +[hosted hub](../hosted-hub.md), and [hub deployment](../hub-deployment.md) +guides. On v5, `dashboardDocsHref` sends `?` links to the docs site for +published pages and falls back to GitHub for the rest. + +### Project-owner checklist before enabling Ask + +Keep Ask off on public deployments until this checklist passes. Work in +the Kapa console and the deployment's secret store; do not put keys, +project IDs, integration IDs, or console exports in the repository. + +- [ ] **Limit ingestion to published operator help.** Configure a + [Website Crawl source](https://docs.kapa.ai/knowledge-sources/connectors/web-crawling/control-which-pages-are-crawled) + for the dashboard integration. Use the canonical HTTPS URLs from the + live Hive docs navigation as start URLs and **Include URLs** entries + (one anchored Regex entry per approved page, for example + `^https://docs\.hivecommons\.dev/docs/hive/dashboard/dashboard-ui-map/?$`). + Include the dashboard, UI map, glossary, sections and per-section pages, + Settings and its help targets, getting started, agent configuration, env + reference, telemetry, and the hosted, self-hosted registration, hub + deployment and fleet guides. Don't allow the whole site, `/docs/hive/`, + or a broad reference prefix: those can also contain architecture records + and runbooks. Keep `src/docs/design/`, `src/docs/adr/`, and runbooks out + by approving URLs against their source paths, not just their published + slugs. Do not add GitHub issues, pull requests, or chat sources. +- [ ] **Verify the effective corpus.** Run **Preview all**; check Included, + Excluded and parsed page content before publishing. Confirm that Ask + cannot inherit excluded material from other sources (including Global + sources); check the integration's + [source groups](https://docs.kapa.ai/knowledge-sources/source-groups) + or use an isolated project if existing sources cannot be separated. + Confirm the same in **Deployed** after publishing. This keeps excluded + documents out of Ask without removing them from the public docs site. +- [ ] **Mask questions.** Enable + [user-message PII masking](https://docs.kapa.ai/security/pii-masking#enabling-user-message-pii-masking) + on the project. Verify with synthetic data only; masking does not + replace the disclosure or authorize sending private data. +- [ ] **Constrain answers.** Associate a + [customization](https://docs.kapa.ai/customizing/use#associating-a-customization-with-an-integration) + with the dashboard HTTP API integration. Limit answers to using and + navigating the Hive dashboards; require a cited doc, say when the docs + do not answer, and refuse off-topic questions and requests to override + those instructions. Review enabled domains wherever the integration + exposes that setting; keep only the exact domains in use, with no wildcards. + Do not enable a browser widget or send an origin URL to satisfy that list. +- [ ] **Protect the shared quota.** Ask [Kapa support](https://support.kapa.ai) + to raise the [per-team chat limit](https://docs.kapa.ai/integrations/chat-api#rate-limits). + Confirm the effective limit before choosing a hub cap that leaves room + for the public docs widget and bots. +- [ ] **Verify on a hub before rollout.** Use a test deployment running the + phase 2 panel ([#19181](https://github.com/hivecommons/hive/issues/19181)). + Sign in and consent. Ask “where do I add a repo?” and “how do I pause an + agent?” in separate conversations. The first should distinguish adding a + monitored repo ([Settings → Repos](../settings.md#repos)) from + [requesting a new hosted hive](../hosted-hub.md#2-request-a-hosted-hive-for-a-repo). + The second should point to the + [spoke agent card](../dashboard.md#pausing-an-agent), not the hub's fleet + controls. Open the citations to verify they reach the actual instructions. + Check off-topic refusal and that withdrawal stops the next request. +- [ ] **Close the feedback loop.** Review + [Coverage Gaps](https://docs.kapa.ai/analytics/coverage-gaps) and + [Top Questions](https://docs.kapa.ai/analytics/top-questions) for the + dashboard integration. Fix unclear docs or UI labels using paraphrases + rather than copying question text. Recheck the indexed pages and rerun + the navigation questions after publishing fixes. ### Status of the docs coverage work (#19182) @@ -590,13 +609,13 @@ Not verified, and the reason: thread id in the body. The public pages read do not show them. - **Whether the vendor documents a hosted or frame mode.** None was found; the claim is an absence in the pages read. -- **Vendor per-source include and exclude patterns, and deletion of a single - thread through the chat API.** Not described in the pages read. +- **Deletion of a single thread through the chat API.** Not described in the + pages read. - **A required "powered by" attribution for the chat API.** Documented for the chat SDK; not found for the API. The panel shows it anyway, which is also the disclosure. -- **The current sync list on the docs repo's main branch.** Read from a local - clone. +- **Live Ask responses and the deployed Kapa corpus.** Verify with the + [project-owner checklist](#project-owner-checklist-before-enabling-ask). - **Every number** (limits, timeouts, caps) is a proposal, not a measurement. ## References diff --git a/src/docs/hosted-hub.md b/src/docs/hosted-hub.md index a206d083af..3ccbe16faa 100644 --- a/src/docs/hosted-hub.md +++ b/src/docs/hosted-hub.md @@ -182,6 +182,18 @@ every 15 seconds and says which hives are stale or not reporting. See ## Getting help +If **Ask** is available, use it for navigation questions. To add another +monitored repo to an existing hive, open that hive from **My Hives**, then +use [Settings → Repos](settings.md#repos). To pause a worker, use the +[agent card on the hive dashboard](dashboard.md#pausing-an-agent); neither +action is a hub setting. + +Ask is off by default. When offered, it asks for your consent in the panel +before sending your question and, if enabled, a fixed section label to +Kapa.ai. Consent is per person and stored by the hub; you can withdraw it +in the panel. Do not enter secrets or private details. If Ask is unavailable, +use the docs directly. See [Ask data and consent](telemetry.md#ask-ai-help). + - For project questions or hosted-hub problems, open an issue in and include the hive name, repo, and the visible fleet/dashboard error text. Do not include API keys, private diff --git a/src/docs/settings.md b/src/docs/settings.md index dd14b89a85..a31a75e7e8 100644 --- a/src/docs/settings.md +++ b/src/docs/settings.md @@ -44,6 +44,15 @@ Which labels hold, require, or route work, the label the merger queue applies to The repos the hive manages and the caps on how many issues and PRs are listed in one kick (`governor.kick_limits`). See the `governor.kick_limits` row of the [notable fields](operator-reference.md#notable-fields). +To add a repository to an existing hive, open its dashboard and choose +**Settings → Repos**, or use the gear on **Projects**. Enter `org/repo` or the +GitHub URL for the hive's forge and choose **+ Add**. If the GitHub App needs +access, follow **Manage App access**, then choose **Re-check & add**. Choose +**Save & close** to apply the monitored list. Adding a repository from a +different organization migrates the hive to that organization. To request +a *new* hosted hive instead, use +[Request a hosted hive for a repo](hosted-hub.md#2-request-a-hosted-hive-for-a-repo). + The same tab has a **Parent auto-close** card (owner only, `repos..parent_autoclose`): per monitored repo, choose "Close finished parents (default)", "Also close epics and holds", "Also close trackers whose work is done" or "Never auto-close parents". It shows the effective value for each repo, applies on save without a restart, and is audited. A parent a person reopened is never re-closed, and issues marked as tracking issues are never auto-closed. See [stage-labels](labels-and-control-signals/stage-labels.md#decomposed-parents--closed-by-their-children-never-stalled). ## Budget diff --git a/src/docs/telemetry.md b/src/docs/telemetry.md index 50a66a459b..015a55f8a3 100644 --- a/src/docs/telemetry.md +++ b/src/docs/telemetry.md @@ -12,7 +12,7 @@ Hive sends a small number of operational signals outside the running hive only t | Build-containment lookup | A commit SHA (the hive's running commit and the commit being asked about) or a PR number, sent as part of a GitHub REST `compare` or `pulls` request. Only when an operator runs a lookup (`GET /api/saas/build-contains` on the hub, `GET /api/version/contains` on a hive). No hive identifier, org, repo name or user is in the request. | `api.github.com`, the public `hivecommons/hive` repository, using the hub's read-only GitHub identity or the hive's own configured GitHub client. The answer is shown to the caller only. | On demand only; no background polling. A hive with no GitHub client answers `unknown` and sends nothing. | None stored; compare answers are cached in memory, for the life of the process. | Do not run the lookup; there is no setting because nothing is sent otherwise. | `src/pkg/buildcontains/buildcontains.go`; `src/pkg/hub/build_contains.go`; `src/pkg/dashboard/api_version_contains.go`. | | NPS prompt | Score 1-4, optional free text, hive ID, and dashboard version. The signed-in username is used only locally for rate limiting and is not sent. | Hub `POST /api/nps/ingest`, or an explicitly configured NPS relay for standalone hives; only hub admins can read stored responses. | Hosted spokes default on; self-hosted/federated/standalone default off. Standalone relay requires explicit `hub.nps_enabled`/`HIVE_NPS_ENABLED` and `hub.nps_relay_url`/`HIVE_NPS_RELAY_URL`. | Hub store keeps at most 1,000 responses per hive and 10,000 total, oldest dropped first. | `hub.nps_enabled: false` or `HIVE_NPS_ENABLED=false`; leave relay URL unset. | `src/docs/nps.md`; `src/docs/env-vars.md`; `src/pkg/dashboard/nps.go`; `src/pkg/hub/nps.go`. | | Hosted hub web analytics | GA4 page/event data from hub-hosted pages, including custom hub events such as hive creation/deletion. Existing event code includes hive IDs and creation inputs such as org, primary repo, ACMM level, and cluster ID. | Google Analytics via `www.googletagmanager.com`, property `G-4707R797K3`. | Loaded by hosted hub static HTML pages. This is website analytics, not spoke software telemetry, but it still needs privacy review because custom events may include project identifiers. | Google Analytics retention is controlled in the GA property, not in this repository. | Browser tracking protections or removing the hosted hub GA script; there is no repository config flag. | `src/pkg/hub/assets/dashboard.html`; `src/pkg/hub/saas_pages.go`; `src/pkg/hub/static/*.html` pages such as `reading.html` and `cncf-reference-architecture.html`. | -| Ask AI help (optional) | The question a signed-in person typed, after a credential-shape check that refuses rather than sends; the label of the dashboard section they are in, from a closed list of our own ids; the Kapa.ai integration id; and, for a follow-up, the vendor thread id. No login, email, page content, URL, hive, repo or agent name. | Kapa.ai Chat API (`api.kapa.ai`), called server side by the hub; the project's Kapa administrators can read questions in Kapa analytics. | Off by default (`HIVE_ASK_ENABLED`); inert until a key file, project id and integration id are configured; each person confirms a disclosure before their first question and can withdraw. | Kapa keeps conversations for the duration of the service; Hive stores no question or answer text, only the per-person consent record. | Leave `HIVE_ASK_ENABLED` unset, or withdraw consent per person. | `src/pkg/askai/service.go`; `src/pkg/askai/kapa.go`; `src/pkg/hub/ask.go`; [design](design/dashboard-ask-ai-help.md). | +| Ask AI help (optional) | The question a signed-in person typed, after a credential-shape check that refuses rather than sends; if enabled, a fixed dashboard section label; the Kapa.ai integration ID; and, for a follow-up, the vendor thread ID. Kapa also sees the calling server's IP. Hive sends no login, email, page content, URL, hive, repo or agent name as context. | Kapa.ai Chat API (`api.kapa.ai`), called server-side by the hub; the project's Kapa administrators can read questions in Kapa analytics. | Off by default (`HIVE_ASK_ENABLED`); inert until a key file, project ID and integration ID are configured. Each person confirms a disclosure before their first question and can withdraw. | Kapa retains conversations under its own terms; Hive stores no question or answer text, only the per-person consent record. | Leave `HIVE_ASK_ENABLED` unset, or withdraw consent in the Ask panel. | [Ask AI help](#ask-ai-help); `src/pkg/askai/service.go`; `src/pkg/askai/kapa.go`; `src/pkg/hub/ask.go`. | | Crash/error reporting | No Sentry/PostHog/Segment/Plausible crash reporter was found in `src` during the onboarding audit. Errors are logged locally; selected log-safe health/error strings can appear in hub heartbeats as described above. | Local logs and, for selected operational state, the configured hub. | No third-party crash reporting by default. | Local log/PVC retention is deployment-specific. | N/A for third-party crash reporting; disable hub link for heartbeat-carried operational errors. | Audit search: `telemetry|analytics|metrics push|phone.?home|posthog|segment|plausible|gtag|googletagmanager|sentry` over Go/HTML/JS/Markdown. | ## Linux Foundation telemetry-policy status @@ -27,6 +27,26 @@ Hive sends a small number of operational signals outside the running hive only t | Secure the collection mechanism. | Heartbeats and task-status use per-hive derived bearer credentials; heartbeat responses are signed; feedback/NPS size caps and redaction are implemented. | Security posture depends on the configured hub and GA4; continue to review any new phone-home path before enabling it by default. | | Make approved telemetry data available to project participants. | NPS is admin-only by design; hub operational state is hub-admin/operator visible. | If LF approves any project telemetry program, define what aggregate data is shared with the community and where. | +## Ask AI help + +On a deployment that offers Ask, the dashboard sends a question only after +the signed-in person accepts the disclosure in the panel. The hub stores its +users' consent records with hub data. A hive stores its dashboard users' +consent in its own data directory, even if it relays questions through the +hub. The record is scoped to the dashboard identity and the disclosure +version; a changed disclosure requires fresh consent. An operator enabling +the feature does not consent on anyone's behalf. + +Kapa does not receive dashboard content, URLs, repo or hive names, user +identifiers, cookies, or session tokens as request context. It does receive +the free text that you type, so do not enter any of those details yourself. +The browser does not load a Kapa widget or contact Kapa from the panel. + +Hive's operational audit records outcomes and counts, not the question, +answer, source links, or vendor thread ID. Withdrawing consent prevents the +next request and does not delete past questions from Kapa. See +[Kapa's retention documentation](https://docs.kapa.ai/security/certifications). + ## Heartbeats are not a crash reporter The heartbeat is an operational control-plane link between a spoke and its configured hub. It is used for liveness, health, upgrade/config delivery, hosted-spoke lifecycle, and fleet views. It should not be treated as an anonymous metrics program: the payload contains stable project and hive identifiers and may contain GitHub usernames. Operators that do not want this link should run without `hub.url`/`HIVE_HUB_URL`; Hive does not currently provide a per-field heartbeat opt-out (tracking issue: [#10202](https://github.com/hivecommons/hive/issues/10202)). From f718e158e4d5001606a8c7b0c842aa019cb73a56 Mon Sep 17 00:00:00 2001 From: Karibhou <157208370+Karibhou@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:00:59 +0100 Subject: [PATCH 2/2] docs: clarify Ask rollout scope and changelog Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com> --- changelog.d/added-ask-ai-docs-coverage.md | 2 +- src/docs/telemetry.md | 15 ++++++++------- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/changelog.d/added-ask-ai-docs-coverage.md b/changelog.d/added-ask-ai-docs-coverage.md index 45f7e9148e..008bd90b21 100644 --- a/changelog.d/added-ask-ai-docs-coverage.md +++ b/changelog.d/added-ask-ai-docs-coverage.md @@ -1 +1 @@ -- Added a generated dashboard navigation map and documented Ask AI help, consent, and rollout checks ([#19182](https://github.com/hivecommons/hive/issues/19182)). +- Documented how to add repositories and pause agents, what optional Ask AI help sends and how consent works, and what owners must verify before rolling out Kapa ([#19182](https://github.com/hivecommons/hive/issues/19182)). diff --git a/src/docs/telemetry.md b/src/docs/telemetry.md index 015a55f8a3..ef69c642ea 100644 --- a/src/docs/telemetry.md +++ b/src/docs/telemetry.md @@ -29,13 +29,14 @@ Hive sends a small number of operational signals outside the running hive only t ## Ask AI help -On a deployment that offers Ask, the dashboard sends a question only after -the signed-in person accepts the disclosure in the panel. The hub stores its -users' consent records with hub data. A hive stores its dashboard users' -consent in its own data directory, even if it relays questions through the -hub. The record is scoped to the dashboard identity and the disclosure -version; a changed disclosure requires fresh consent. An operator enabling -the feature does not consent on anyone's behalf. +These disclosures apply only where Ask is supported and enabled. A signed-in +person must accept the panel's disclosure before sending a question. The +hub stores its users' consent records with hub data. The planned hive +rollout requires the hive to keep consent for its own dashboard users, even +when the hub relays their questions. Consent is scoped to the dashboard +identity and disclosure version; a changed disclosure requires fresh +consent. An operator enabling the feature does not consent on anyone's +behalf. Kapa does not receive dashboard content, URLs, repo or hive names, user identifiers, cookies, or session tokens as request context. It does receive