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
1 change: 1 addition & 0 deletions changelog.d/added-ask-ai-docs-coverage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- 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)).
28 changes: 28 additions & 0 deletions src/docs/dashboard.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.
Expand Down
127 changes: 73 additions & 54 deletions src/docs/design/dashboard-ask-ai-help.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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
Expand Down
12 changes: 12 additions & 0 deletions src/docs/hosted-hub.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://github.com/hivecommons/hive/issues> and include the hive name, repo,
and the visible fleet/dashboard error text. Do not include API keys, private
Expand Down
9 changes: 9 additions & 0 deletions src/docs/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<key>.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
Expand Down
Loading
Loading