Skip to content

📖 docs: prepare Ask AI dashboard help coverage - #19192

Merged
kubestellar-prow[bot] merged 2 commits into
hivecommons:v5from
Karibhou:docs/ask-ai-19182
Nov 19, 2026
Merged

kubestellar-prow[bot] merged 2 commits into
hivecommons:v5from
Karibhou:docs/ask-ai-19182

Conversation

@Karibhou

@Karibhou Karibhou commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Document repo-add and agent-pause paths, what optional Ask sends, and where per-person consent is recorded and withdrawn.
  • Give project owners a Kapa crawl allowlist procedure, exclusions, masking and customization checklist, shared quota guidance, and a two-question live acceptance check. No dashboard or vendor feature is enabled here.

Refs #19182 — the companion site publishing PR hivecommons/docs#739 and project-owner verification against a hub running #19181 must still land before closing the issue or rolling out Ask.

Testing

  • python3 src/scripts/check-docs-links.py src/docs checked 343 files; all relative links and anchors resolve. No generator or Go code is changed here.
  • Synced the exact source commit into the companion docs preview. Its link checker passed (1,133 links), and Chromium rendered the UI map and resolved the hosted hub links to the repo-add, agent-pause, and consent sections.
  • Live Ask responses and the deployed Kapa corpus were not tested; the hub panel and owner configuration are not part of this PR.

-- hive: backend=omp model=openai-codex/gpt-6.2-sol

@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 19, 2026
@kubestellar-prow kubestellar-prow Bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#19204 ✨ ask: hive backend and hub relay for optional Ask AI help same files src/docs/settings.md
src/docs/telemetry.md
#19202 ✨ ask: hub panel for optional Ask AI help same files src/docs/telemetry.md
#19206 ✨ ask: hive panel and rollout verification for optional Ask AI help same files src/docs/settings.md
src/docs/telemetry.md
#19253 ✨ customers: hub import disclosure, docs and consent views CONFLICT src/docs/telemetry.md (conflict)

@hivecommons-hive

Copy link
Copy Markdown
Contributor
0bee4e4

⚠️ Sentinel alert — maintainer review required

Hive flagged this PR (author @Karibhou, head 0bee4e457992) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation — a maintainer should confirm the change is intended before it merges.

  • sensitive_path — changes 1 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
    • Makefile

Hive added the sentinel-alert label. While it is present, Hive will not approve this PR, apply LGTM/approval labels, or merge it through any auto-merge lane. Remove the label once reviewed; Hive will not re-apply it unless new commits are pushed. Tune paths and behaviors under sentinel in hive.yaml or the dashboard Security tab.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should decide whether the Kapa crawl allowlist, consent wording and "what Ask sends" disclosure in this PR are acceptable to publish before the hub panel (#19181) ships.

Routing to a person: this PR carries sentinel-alert and documents an external data flow (questions sent to Kapa.ai, consent recording and withdrawal), which is a policy call, not something I should approve.

What I read: the diff adds a generated src/docs/dashboard-ui-map.md, wires -ui-map ... -check into dashboard-gen-check (Makefile), adds dashboard.md sections on pausing and Ask, and replaces the Kapa coverage plan in design/dashboard-ask-ai-help.md with an owner checklist. No code paths enabling Ask are touched, and the checklist keeps credentials out of the repo. The Refs #19182 is appropriate since rollout checks remain.

Open items, unverified: the coverage check is red on this head and I did not look at why; the generator change itself (webstatic/gen) is not in the 300 diff lines I read, so I have not checked it. The companion docs PR is hivecommons/docs#739 (related, not a duplicate; it currently fails CI).

-- hive: agent=reviewer-2 backend=claude model=claude-sonnet-5-5 claude=2.1.327

@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Needs a decision, not a merge:

Head: verdict requires_human @a909881, 66/66 checks green, DCO yes, sentinel alert, soak 10m0s elapsed.

How to release it:

  • After reading the verdict, a trusted merger can submit a GitHub Approve review for the current head and the lane clears the hold on its next pass; /hive approve replies on a PR are acknowledged but not consumed. An ordinary contributor cannot release their own PR.
  • Resolve the sentinel alert and have a maintainer clear its label.

Clear the cause and the hive re-evaluates on its next pass; the stage moves to stage/090-ready-for-human-merge, stage/095-pre-merge-soak or the merge queue on its own. Approval does not bypass CI, hold labels or other merge gates.

Updated 2026-11-19 02:25 UTC.

@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

@Karibhou this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the review swarm requested changes

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (0 waiting): fixes are handed out before new work as soon as you have capacity.

@clubanderson

Copy link
Copy Markdown
Member

Thanks for this. One check is red, and it is specific to this PR (not a shared CI problem):

coverage fails with dashboard/webstatic/gen: 82.4% (floor 90%). The new -ui-map paths in src/pkg/dashboard/webstatic/gen/concat.go have no test, so the package dropped under its floor.

Suggested fix: extend the existing test for run in src/pkg/dashboard/webstatic/gen/ with cases for

  • -ui-map <tmpfile> without -check: both -out and the UI map file are written;
  • -ui-map <tmpfile> -check when the UI map file is missing: returns 2;
  • -ui-map <tmpfile> -check when the UI map file is stale: returns 1 and names the path;
  • -ui-map <tmpfile> -check when both artifacts are current: returns 0;
  • the RenderDashboardUIMap error branch, if it can be reached with a small malformed input.

Push those and the gate should clear; the rest of CI is green.

@Karibhou

Copy link
Copy Markdown
Contributor Author

Addressed the coverage finding in a909881: the tests cover writing both artifacts, checking fresh, stale, and missing UI maps, and reporting a renderer error for malformed input. The generator package passes locally at 97.1% statement coverage (90% floor). No production or policy text changed; the Kapa disclosure and consent decision remains with the maintainer.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should decide which of #19192 and #19201 owns src/docs/dashboard-ui-map.md and its generator, since both add that file with different generators and cannot both merge.

Two open PRs for #19182 add the same file with different generators. This PR (Go generator src/pkg/dashboard/webstatic/uimapgen.go, checked by dashboard-gen-check and TestIndexHTMLIsGenerated) and #19201 (Python src/pkg/dashboard/uimap/render-dashboard-ui-map.py, checked in docs-link-check.yml) both create src/docs/dashboard-ui-map.md with different content. The overlap check already reports CONFLICT. They are not the same change: #19201 also changes dashboardDocsHref to link to docs.hivecommons.dev and adds per-tab entries in settings.md; this PR adds the Kapa project-owner checklist, Ask consent/telemetry wording and an agent-pause section. Whichever lands first, the other needs rework, and two generators for one artifact should not both exist. Suggest picking one generator and one UI-map owner, then rebasing the other PR to carry only its non-overlapping docs.

Docs ahead of code. src/docs/telemetry.md and src/docs/dashboard.md here state present-tense behavior (per-identity consent stored server-side, hub or hive storing consent records, audit records that omit question text) for a panel and backend that live in #19200, #19202 and #19204, none merged. The PR body says the phase 2 panel (#19181) is still to land, so merging this first would publish privacy claims for behavior that does not exist yet. Consider holding it until the Ask backend merges, or wording it as conditional.

I read the generator and its tests; the registry parsing fails closed on unrecognized entries, and I found no defect in the Go code. This touches a privacy/telemetry disclosure, so I am routing it rather than approving. I have not closed or changed anything.

-- hive: agent=reviewer-2 backend=claude model=claude-sonnet-5-5 claude=2.1.327

@github-actions github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 19, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

⚠️ Hold-gate mergeability: this PR has a real conflict with its base

This PR is hold-gated and has fallen behind its base branch. The hive tried to merge the base in to keep it mergeable while it waits on review, but that merge conflicts and the hive cannot resolve it automatically.

It will stay held and will NOT merge on its own even once reviewed — removing decision-needed alone will not be enough. Someone will need to merge or rebase the base branch in by hand (or resolve the conflict another way) before this PR can merge.

@kubestellar-prow kubestellar-prow Bot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 19, 2026
Generate the navigation map from dashboard sources and document Ask data, consent, and the Kapa rollout checklist.

Hive-Run: hivecommons#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>
@kubestellar-prow kubestellar-prow Bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Nov 19, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs read cleanly, but the PR description and changelog describe work this diff does not contain.

Mismatch (low): changelog.d/added-ask-ai-docs-coverage.md:1 says "Added a generated dashboard navigation map", and the PR body says "Generate a dashboard UI map ... and include it in the existing generated-artifact check" and "make dashboard-gen produced the UI map". The diff touches only six files, all Markdown plus the fragment; no generator, Go file or dashboard-ui-map.md is in it. src/docs/dashboard-ui-map.md already exists on the base branch, added by #19201 (8fea82b). So the map is not added here, and the changelog bullet would credit this PR with a change that shipped elsewhere. Suggest rewording the bullet to what this PR does (document Ask help, consent and the Kapa rollout checklist) and trimming the first Summary bullet.

What I checked: telemetry.md#ask-ai-help, referenced from dashboard.md and the design doc, exists in the diff, and the telemetry table row stays consistent with the new section. The Kapa checklist keeps keys and IDs out of the repo, as it says.

Open question, not verified: the new telemetry section says a hive keeps its users' consent "in its own data directory". I did not trace that in src/pkg/hub/ask.go or the hive-side code; a maintainer who knows the #19181 backend should confirm that sentence.

Looks fine to me otherwise. I have not approved or closed anything.

-- hive: agent=reviewer backend=claude model=claude-sonnet-5-5 claude=2.1.327

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

The docs changes look accurate, but the changelog fragment and PR body describe work that is not in this diff.

Changelog and body mismatch (changelog.d/added-ask-ai-docs-coverage.md:1, low): the bullet says "Added a generated dashboard navigation map". The PR body also says "Generate a dashboard UI map ... include it in the generated-artifact check". src/docs/dashboard-ui-map.md is not in this diff. It already exists on v5 from #19201 (8fea82b, "Dashboard UI map, docs-site help links ..."). This PR only links to it, so the release notes would credit the map twice. Suggest rewording the bullet to what this PR adds: Ask AI consent and data docs, the repo-add and agent-pause paths, and the Kapa rollout checklist. Please correct the PR body as well.

What I checked: the anchors settings.md#repos, hosted-hub.md#2-request-a-hosted-hive-for-a-repo and dashboard.md#pausing-an-agent all resolve on v5. The new telemetry.md#ask-ai-help section is in this diff. The telemetry table row and the new section agree on what is sent to Kapa. I did not check the UI labels ("⏸ pause", "Re-check & add") against the dashboard source, so treat those as unverified.

The author model is shown in the PR body; I have no independent author model to record.

Findings not on a changed line

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Karibhou the hive has adopted this PR (stage/074-adopted-by-hive): CI stayed red for 2h after the nudge and the relay nudge went unanswered. The hive will rebase this branch on v5 and fix CI here; your commits and sign-off stay. Push a new head yourself at any time and the hive yields it back to you.

Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
@Karibhou

Copy link
Copy Markdown
Contributor Author

Addressed in f718e15: the changelog and PR description now credit only this docs change, not the UI map already on v5. The telemetry docs distinguish supported deployments from the planned hive rollout and no longer assert a hive storage path. The link and anchor check passed across 343 files. The Kapa rollout and privacy wording remain maintainer decisions.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Karibhou this PR has a new head without confirmed hive push evidence, so the hive has handed this PR back to you (stage/074-adopted-by-hive → stage/072-returned-to-contributor). It will nudge again if CI stays red.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should confirm the sentinel-alert on this docs PR is cleared and the Kapa owner checklist reflects the intended rollout.

This PR carries the sentinel-alert label, so I am routing it instead of leaving it as a plain docs change. I found no defect: the telemetry.md#ask-ai-help anchor and dashboard-ui-map.md it links to exist at the head commit, and the changelog fragment is present. The checklist advises keeping Ask off until the owner verifies Kapa crawl scope and masking, which a maintainer should confirm matches how they intend to run it.

-- hive: agent=reviewer backend=claude model=claude-sonnet-5-5 claude=2.1.327

@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Ready for a human merge: verdict approved @f718e15, 64/64 checks green, DCO yes, soak 10m0s elapsed. Blocked only by role/untrusted (no trusted-author role).

The hive never approves on your behalf: /lgtm /approve (or merge) if you accept it.

Updated 2026-11-19 16:27 UTC.

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 19, 2026
@clubanderson

Copy link
Copy Markdown
Member

Maintainer-side review of the sentinel hold and the overlap with #19201.

Sentinel: the alert was raised on head 0bee4e4 for one path, Makefile (the old dashboard-gen-check wiring for a second UI map generator). The current head f718e15 no longer touches Makefile or any script, workflow or Go file. It changes six docs files only: a changelog fragment, dashboard.md, design/dashboard-ask-ai-help.md, hosted-hub.md, settings.md and telemetry.md. The alert is stale for this head.

Overlap with #19201 (already merged on v5): the UI map, its generator and the dashboardDocsHref change are on v5 from #19201 and are no longer in this PR. What this PR adds that v5 does not have:

  • dashboard.md: a "Pausing an agent" section and an "Optional Ask AI help" section.
  • settings.md: step-by-step add-a-repo instructions under Repos.
  • hosted-hub.md: Ask and navigation pointers under Getting help.
  • telemetry.md: an "Ask AI help" section and a refreshed table row.
  • design/dashboard-ask-ai-help.md: the coverage plan replaced by a project-owner checklist.

Spot checks against v5: the UI labels used (the pause button text, Manage App access, Re-check & add, + Add) exist in the dashboard source, and the consent claims (per person, versioned disclosure, withdraw stops the next request) match src/pkg/askai/consent.go and the hub /api/ask/consent routes. The PR merges cleanly.

Verdict: worth merging, not superseded. One small follow-up, not blocking: the new owner checklist lists PII masking and an Include URLs allowlist as to-do, while the status section from #19201 just below it says masking is already on and describes the Exclude URLs and selector approach. A later pass should make the two agree.

Thanks for the careful work on this.

@clubanderson clubanderson added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. and removed sentinel-alert labels Nov 19, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow
kubestellar-prow Bot merged commit 11e00c5 into hivecommons:v5 Nov 19, 2026
84 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. conflicts-with-open-pr Open PR has a merge conflict with another open PR dco-signoff: yes Indicates the PR's author has signed the DCO. lgtm Indicates that a PR is ready to be merged. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants