✨ knowledge: owner-switched, read-only public MCP endpoint for external agents

[clubanderson]

Closes #10615. cc @castrojo — this is the "public knowledge" switch for Bluefin's Troubleshooting / mcp.projectbluefin.io.

Stacked on #10617 (v5 currently panics at pkg/dashboard/pkg/hub init, so nothing in those packages can be tested until it lands). The first three commits here are that fix; this PR's own diff starts at ✨ knowledge: owner-switched read-only public MCP endpoint.

What

An owner-controlled, strictly read-only MCP endpoint that lets any external agent (Goose, Claude, Copilot CLI, curl) read a hive's operational knowledge with no credentials — but only after the hive owner opts in.

Endpoint	POST /mcp/knowledge — MCP Streamable HTTP, JSON-RPC 2.0, JSON responses (no SSE)
Switch	HIVE_PUBLIC_KNOWLEDGE=1|true|yes|on — default off → 404, even for the owner. Read per-request; close it without a pod roll.
Narrowing	HIVE_PUBLIC_KNOWLEDGE_TAGS=linux,troubleshooting — optional tag allow-list
Tools	knowledge_search {query,type?,limit?} · knowledge_get {slug} · knowledge_export {} (Markdown + ETag)

Read-only guarantees

• The handler serves initialize, ping, notifications/*, tools/list, tools/call and nothing else (-32601 otherwise).
• No code path from this file reaches CreateFact/UpdateFact/DeleteFact, import, promotion, or vault mutation. Tests assert no tool name contains create/update/delete/write/import/promote and that every tool is annotated readOnlyHint: true, destructiveHint: false.
• POST-only (mux 405s other verbs), 64 KiB body cap, ≤50 results per search.

What leaves the hive

Only operational types: pattern, gotcha, regression, test_scaffold, integration, coverage_rule, general. Ideation/governance types (idea, vision, constitution, requirement, constraint, stakeholder, decision) are filtered at a single choke point (publicKnowledgeFilter); fetching one by slug answers not found, not forbidden. Each fact is projected to slug/title/type/body/tags/related (+confidence only when scored) — sources, usage_count, confidence_reason, last_used, phase are stripped.

Plumbing

• dashboard.isPublicPath admits /mcp/knowledge only while the switch is on; the handler re-checks and 404s.
• hub.publicExactPaths adds the exact path so the nginx auth_request gate doesn't bounce credential-less agents to login (same mechanism/rationale as knowledgeExportPath, 🐛 bug(contribute): on a hosted hive the contributor's knowledge download always fails, silently — agent.md is never installed #8294). Test asserts /mcp, /mcp/, /mcp/knowledge/admin, /mcp/other stay gated.
• Docs: docs/public-knowledge-mcp.md (what's exposed, what's impossible, Goose/Claude/Copilot/curl config), env-vars.md, api-reference.md (+ citation refresh), documentation map, changelog fragment.

Try it

HIVE_PUBLIC_KNOWLEDGE=1 ...
curl -s $HIVE/mcp/knowledge -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"knowledge_search","arguments":{"query":"bluetooth"}}}'

Goose: extensions: { hive: { type: streamable_http, uri: https://<hive>/mcp/knowledge } }

Verification

• go test -run 'PublicKnowledge|GithubLogin' ./pkg/dashboard/ ✅ (9 tests: default-off, off-even-when-authenticated, spellings, handshake/tools-list, private-type hiding in search/get/export, tag allow-list, write/bad-input rejection, no-KB, path constant)
• go test -run PublicKnowledgeMCP ./pkg/hub/ ✅
• go test -cover ./pkg/hub/ ✅ 89.2%; ./pkg/dashboard/ 85.0% — two failures there (TestOpenAPISpecCoversEveryRegisteredRoute: undocumented GET /api/feedback/status; TestAgentsCollapsedSummaryRendersPerAgentTiles) are pre-existing on v5 and unrelated.
• go vet, check-api-reference-citations.sh ✅

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign danathar for approval. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

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

[github-actions]

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
#10618	✨ Improve collapsed Advisory and ACMM headers	same files	src/docs/api-reference.md
#10517	📖 docs: add unreviewed ACMM Level 6 operating guide	same files	src/docs/documentation-map.md
#10608	📖 docs: refresh api-reference citations after #10607	same files	src/docs/api-reference.md
#10602	✨ feat: label-driven repos skip un-park notice and keep needs-human	same files	src/docs/api-reference.md
#10638	🐛 dashboard: Overview open-issue/PR totals explain their gap to the forge counts	same files	src/docs/api-reference.md src/pkg/dashboard/server.go
#10594	🧪 test: restore pkg/github coverage floor after reporter-trust wait	same files	src/docs/api-reference.md
#10632	✨ dashboard: Agents sidebar link + up-next agent tiles in top navbar	same files	src/docs/api-reference.md
#10604	🐛 hub dashboard: NPS section header matches sibling section styling	same files	src/docs/api-reference.md
#10589	🐛 fix: route reporter-trust waits through poller relay	same files	src/docs/api-reference.md

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback