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

changelog.d/added-10621.md

@@ -0,0 +1 @@
+- knowledge: owner-switched, read-only public MCP endpoint for external agents (#10621)

src/docs/documentation-map.md

@@ -118,6 +118,7 @@ Documentation for the current Hive line (branch `v5`; the code and docs live und
 - [Branding a hive](branding.md) — persistent per-deployment name, mark, and colours via `<data>/branding/branding.json` and `custom.css` (`HIVE_BRANDING_JSON`/`HIVE_BRANDING_CSS`); distinct from the per-request `?style=` stylesheets above.
 - [Portable AgentDefinition format](../AGENT-DEFINITION.md) — standalone YAML schema for importing/exporting agent definitions.
 - [Knowledge curator](knowledge-curator.md) — automatic fact extraction and promotion knobs, plus the other `knowledge:` sub-sections: `git_sources` (indexing a remote repo, layer semantics, private-repo auth (unsupported), diagnosing a failed source), `vaults` (local Obsidian vaults, git-sync), `documents` (PDF/URL import), and `bead_synthesizer` (on-by-default bead→wiki synthesis and retention policy, and how to turn it off). See also [knowledge confidence scoring](knowledge-confidence.md) for dashboard confidence badges and score explanations.
+- [Public knowledge MCP endpoint](public-knowledge-mcp.md) — the owner-switched, read-only `POST /mcp/knowledge` surface that lets any external agent (Goose, Claude, Copilot) read a hive's operational knowledge without a session; what is and is not exposed, and client configuration.
 - [Skill registry](skills.md) — the `/data/skills/` file format and front-matter fields. **Delivered to agents today**: skills are opt-in per agent via `skills: [name, ...]`, resolved registry-first with an `AGENTS.md` repo-local fallback, and the rendered block is prepended to the kick's `${KNOWLEDGE}`. Both sources reload on every kick. An 8 KiB whole-skill cap applies; a skill that would exceed it is dropped whole, never truncated.
 - [AGENTS.md repo instructions](agents-md.md) — the per-repo `AGENTS.md` file format Hive's parser (`pkg/agentsmd`) understands, including front-matter `skills:` and inline `## Skill:` sections. **Wired into kicks, but needs a checkout**: Hive agents keep no clones, so set `project.checkouts_dir` to a directory holding one checkout per repo. Without it there is no root to read and injection stays a no-op, which is the default.
 - [Agent peer-awareness logging (pluk)](agent-logging.md) — pluk log format, `hive-panes`, availability, and retention.

src/docs/env-vars.md

@@ -48,6 +48,8 @@ This reference is compiled by hand from the Go source under `src/`, the deployme
 | `HIVE_METRICS_ENABLED` | No | disabled | Registers Prometheus `/metrics` when set to `1`, `true`, `yes`, or `on`. Requires `HIVE_METRICS_TOKEN` — enabled-but-tokenless returns 403 ([#3804](https://github.com/hivecommons/hive/pull/3804)). |
 | `HIVE_METRICS_TOKEN` | Yes when metrics enabled | none | Bearer token read by `pkg/dashboard/metrics_prometheus.go` for `/metrics` (`Authorization: Bearer ...`; Prometheus `bearer_token`). `/metrics` bypasses dashboard session auth, so this token is its only guard; enabled-but-tokenless fails closed and the cost/agent series are never served without it. |
 | `HIVE_METRICS_FILE` | No | `/var/run/hive-metrics/contribute.json` | Contributor metrics JSON file override. |
+| `HIVE_PUBLIC_KNOWLEDGE` | No | disabled | Owner switch for the anonymous, **read-only** MCP knowledge endpoint `POST /mcp/knowledge` (`1`, `true`, `yes`, or `on` — same spelling as `HIVE_METRICS_ENABLED`). Off → 404 even for authenticated callers. Read on each request so it can be closed without a pod roll. Only operational fact types (pattern, gotcha, regression, test_scaffold, integration, coverage_rule, general) are served; ideation/governance types, sources, and usage data never leave the hive. See [public-knowledge-mcp.md](public-knowledge-mcp.md) ([#10615](https://github.com/hivecommons/hive/issues/10615)). |
+| `HIVE_PUBLIC_KNOWLEDGE_TAGS` | No | none (all public-type facts) | Comma-separated tag allow-list that further narrows what `/mcp/knowledge` serves to facts carrying at least one listed tag (case-insensitive). |
 | `HIVE_COPILOT_INTEGRATION_ID` | No | compiled Copilot integration id | Overrides the integration id used by Copilot model discovery. |
 | `HIVE_CONTRIBUTORS_DIR` | No | hub default | Contributor registry directory override. |
 | `HIVE_CONTRIBUTE_SKIP_LABELS` | No | `blocked,tracking,epic,discussion,question,needs-decision,needs-triage` | Comma-separated, case-insensitive label patterns for issues that are not contributor work and must never be offered by the relay. Patterns use `path.Match`-style `*` globs; `blocked` is always unioned into the effective set even if omitted. Same setting as `hub.contribute_skip_labels`. |

src/docs/public-knowledge-mcp.md

@@ -0,0 +1,112 @@
+# Public knowledge MCP endpoint
+
+A hive accumulates operational knowledge — gotchas, patterns, regressions,
+integration notes — as its agents work. Normally that knowledge is reachable
+only with a hub session, the dashboard token, or a contributor registration
+token (`/api/knowledge/*`, `hivectl knowledge export`).
+
+The **public knowledge** switch lets a hive owner open a second, strictly
+**read-only** surface so *any* agent — Goose, Claude Desktop/Code, Copilot
+CLI, a shell script — can consult the hive without credentials. The
+motivating case is a distro's troubleshooting assistant reasoning from the
+project's own accumulated fixes instead of only what its model was trained on
+([#10615](https://github.com/hivecommons/hive/issues/10615)).
+
+## Owner switch
+
+| Variable | Effect |
+|---|---|
+| `HIVE_PUBLIC_KNOWLEDGE=1` (`true`/`yes`/`on`) | Enables `POST /mcp/knowledge`. Unset or anything else → the path returns **404**, even to the owner. |
+| `HIVE_PUBLIC_KNOWLEDGE_TAGS=linux,troubleshooting` | Optional. Only facts carrying at least one listed tag are served. |
+
+Both are read on every request, so the surface can be closed instantly
+without restarting the spoke.
+
+## What is exposed
+
+Only operational fact types leave the hive:
+
+`pattern`, `gotcha`, `regression`, `test_scaffold`, `integration`,
+`coverage_rule`, `general`
+
+Ideation and governance types (`idea`, `vision`, `constitution`,
+`requirement`, `constraint`, `stakeholder`, `decision`) are never served,
+and a request for one by slug answers "not found" rather than "forbidden".
+
+Each public fact carries `slug`, `title`, `type`, `body`, `tags`, `related`
+and (only when scored) `confidence`. Sources (PR, comment, author), usage
+counters, confidence reasoning, and lifecycle phase are stripped.
+
+## What is *not* possible
+
+There is no write method on this surface. The endpoint serves the MCP
+handshake (`initialize`, `ping`, `notifications/*`), `tools/list`, and
+`tools/call` for three tools. Nothing in the handler reaches
+`CreateFact`, `UpdateFact`, `DeleteFact`, import, promotion, or vault
+mutation. Anonymous callers cannot alter a knowledge base, and every tool is
+annotated `readOnlyHint: true` so MCP clients run them without confirmation.
+
+Other hard limits: POST only (no SSE stream), 64 KiB request body, one
+JSON-RPC request per POST (batch arrays are answered with `-32600`; the
+endpoint speaks MCP `2025-06-18`, which dropped batching), and
+`knowledge_search` returns at most 50 results per call.
+
+A fact's `related` list is filtered to public slugs, so a public fact cannot
+disclose even the name of a private one. `knowledge_get` and
+`knowledge_export` return complete bodies; `knowledge_search` results do too,
+re-read per hit.
+
+## Tools
+
+| Tool | Arguments | Returns |
+|---|---|---|
+| `knowledge_search` | `query` (required), `type`, `limit` (default 10, max 50) | JSON `{query, count, results[]}` |
+| `knowledge_get` | `slug` (required) | One public fact as JSON, or an `isError` "fact not found" |
+| `knowledge_export` | none | The whole public base as one Markdown document, grouped by type; `_meta.etag` and `_meta.facts` |
+
+## Client configuration
+
+The endpoint speaks MCP Streamable HTTP with plain JSON responses.
+
+**Goose** (`~/.config/goose/config.yaml`):
+
+```yaml
+extensions:
+  bluefin-hive:
+    type: streamable_http
+    uri: https://hive.example.org/mcp/knowledge
+    enabled: true
+```
+
+**Claude Code**:
+
+```sh
+claude mcp add --transport http bluefin-hive https://hive.example.org/mcp/knowledge
+```
+
+**Copilot CLI** (`~/.copilot/mcp-config.json`):
+
+```json
+{ "mcpServers": { "bluefin-hive": { "type": "http", "url": "https://hive.example.org/mcp/knowledge" } } }
+```
+
+**curl**:
+
+```sh
+curl -s https://hive.example.org/mcp/knowledge \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"knowledge_search","arguments":{"query":"bluetooth"}}}'
+```
+
+## Hub-fronted spokes
+
+On hosted hives the hub's nginx `auth_request` gate waves `/mcp/knowledge`
+through (same mechanism as `/api/knowledge/export`, #8294) so an agent with
+no browser session is not bounced to the login page. This opens nothing by
+itself: the spoke re-checks `HIVE_PUBLIC_KNOWLEDGE` and 404s when it is off.
+
+## Related
+
+- [Environment variable reference](env-vars.md)
+- [Knowledge curator](knowledge-curator.md) — how facts are produced and promoted
+- [Knowledge system design](design/knowledge-system.md)

src/pkg/dashboard/api.go

@@ -319,6 +319,9 @@ func (s *Server) RegisterAPI(deps *Dependencies) {
 	s.mux.HandleFunc("GET /api/knowledge", s.handleKnowledgeList)
 	s.mux.HandleFunc("GET /api/knowledge/export", s.handleKnowledgeExport)
 	s.mux.HandleFunc("GET /api/knowledge/search", s.handleKnowledgeSearch)
+	// Anonymous, owner-switched, read-only MCP surface (#10615). POST only —
+	// the mux answers other verbs with 405, and there is no SSE stream.
+	s.mux.HandleFunc("POST /mcp/knowledge", s.handlePublicKnowledgeMCP) // path == publicKnowledgeMCPPath
 	s.mux.HandleFunc("GET /api/knowledge/health", s.handleKnowledgeHealth)
 	s.mux.HandleFunc("GET /api/knowledge/stats", s.handleKnowledgeStats)
 	s.mux.HandleFunc("GET /api/knowledge/graph", s.handleKnowledgeGraph)