kandev/docs/plans/plugins/host-data-api/task-07-docs.md

---
id: "07-docs"
title: "Author docs: Host data API + manifest api_read/api_write resource list"
status: done
wave: 4
depends_on: ["04-host-data-impl"]
plan: "plan.md"
spec: "../../../specs/plugins/spec.md"
adr: "../../../decisions/0043-plugin-host-data-api.md"
---

# Task 07: Author docs for the Host data API

Document the Host data API for plugin authors: which resources are readable, the
`api_read`/`api_write` capability vocabulary, and the SDK accessor surface.

## Scope
- **Wire reference (`docs/plans/plugins/GRPC-CONTRACT.md`):** add the Host data
  RPCs to the `service Host` block (§3) and note capability gating uses
  `api_read:<resource>` / `api_write:<resource>` (§5), replacing the "reserved"
  language. Note write RPCs are deferred (`Unimplemented`).
- **SDK reference (`docs/plans/plugins/GRPC-CONTRACT.md` §4 and/or
  `PLUGIN-API.md`):** document the author accessors (`host.Tasks().List(...)`,
  `host.Sessions().List(...)`, `host.Sessions().CodeStats(...)`, etc.) and that
  they return Go-native structs.
- **Manifest reference:** wherever the manifest `capabilities` block is documented
  for authors, list the `api_read` / `api_write` resource vocabulary (`tasks`,
  `sessions`, `workspaces`, `workflows`, `agents`, `repositories`, `comments`) and
  what each unlocks, with the `api_read: ["sessions"]` example from the agent-stats
  plugin.
- **Public docs:** if a user-facing plugin authoring page exists under
  `docs/public/**` at implementation time, add the resource list there too; there
  is none today, so the authoritative author docs are the plans references above.
  Do not invent a new public page in this task.

## Acceptance
- `GRPC-CONTRACT.md` lists the Host data RPCs and the per-resource capability
  gating; the "reserved / not implemented" wording for `api_read`/`api_write` is
  removed or scoped to the deferred write RPCs.
- The manifest capability vocabulary is documented with the readable-resource
  list and an example.

## Verification
- Markdown-only; no build. `cd apps && pnpm --filter @kandev/web lint` only if a
  `docs/public` page is touched (none expected).

## Files likely touched
- `docs/plans/plugins/GRPC-CONTRACT.md`
- `docs/plans/plugins/PLUGIN-API.md` (if the SDK/author surface is documented
  there)

## Inputs
- Final RPC set + accessor names from tasks 01/03/04.
- Spec: "Host data API"; ADR 0043.

## Dependencies
Task 04 (behavior finalized).

## Output contract
Summary, files changed, and status update here + in `plan.md`.

## Output

**Summary:** Documented the Host data API (ADR 0043) in the wire/SDK contract
reference and reconciled the spec section against the shipped code.

**Files changed:**
- `docs/plans/plugins/GRPC-CONTRACT.md` — added the 9 read RPCs + 3 deferred
  write RPCs to the `service Host` block (§3); added a new "§3a. Host data API
  (ADR 0043)" subsection covering the resource/capability table, deferred
  writes, service-layer/DTO conventions, pagination/timestamp/nullable/scoping
  conventions; added the `Host` interface's 6 data accessors plus the 6 reader
  interfaces (`TaskReader`, `SessionReader`, `WorkspaceReader`,
  `WorkflowReader`, `AgentProfileReader`, `RepositoryReader`) with their real Go
  signatures, and an authoring example (manifest snippet + `Sessions().CodeStats`
  call) to §4; rewrote the §5 "Capability gating" bullet to remove the stale
  "api_read/api_write reserved" wording and describe the real per-RPC gating
  plus the write RPCs' current `Unimplemented` behavior.
- `docs/specs/plugins/spec.md` — fixed capability-vocabulary drift against code
  (see below) and added a "Declaring data access" note under the manifest
  capabilities section; reworded the interceptor description to match the
  actual per-RPC inline checks (no shared unary interceptor exists in code);
  updated the readable-resources table's `ListAgentProfiles` row.
- `docs/plans/plugins/host-data-api/plan.md` — marked task-07 done in the wave
  list.

**Code-vs-doc drift found and corrected (spec.md only; code is source of
truth, left unchanged):**
- The `ListAgentProfiles` capability is `api_read:agent_profiles` in code
  (`internal/plugins/host_data.go: resourceAgentProfiles = "agent_profiles"`,
  confirmed by `host_data_test.go`), not `api_read:agents` as the spec had it
  in the manifest example, the resource-vocabulary sentence, and the readable-
  resources table. Fixed all three.
- The spec's manifest example listed `"projects"` as an `api_read` resource;
  there is no `ListProjects` RPC, resource constant, or reader anywhere in the
  proto or `internal/plugins/host_data.go`. Removed it from the example.
- The spec described `api_read`/`api_write` as "reserved for future Host RPCs"
  in the manifest example comments and said the capability-gating interceptor
  covers "state, secrets; api_read/api_write reserved" — both predate this
  ADR shipping; `api_read` is live now (write RPCs remain deferred/
  `Unimplemented`). Reworded both.
- The spec attributed capability gating to "a unary server interceptor on
  Host"; there is no `grpc.UnaryServerInterceptor` in `internal/plugins` or
  `pkg/pluginsdk` — each Host/Host-data method checks its own capability
  inline at the top of the handler (`host.go`, `host_data.go`). Reworded to
  describe the actual per-RPC check without implying a shared interceptor
  layer (this was pre-existing drift, unrelated to ADR 0043, caught while
  editing the same paragraph).
- `GRPC-CONTRACT.md`'s pre-ADR text already read "api_read/api_write reserved
  for future" in §5 and the `service Host` proto snippet only listed the 6
  pre-ADR RPCs; both were stale relative to the shipped proto and are now
  updated in place.

**Not touched (out of scope / already correct):**
- `docs/decisions/0043-plugin-host-data-api.md` — read for context per the
  task's Inputs; its `Status: proposed` front matter looks stale given the
  code is fully implemented, but the task's edit scope was spec.md, not the
  ADR, so it is left for whoever finalizes the ADR's status.
- `docs/plans/plugins/PLUGIN-API.md` — this is the native frontend (JS) UI
  plugin contract; it has no backend Host/SDK content and the Host data API
  has no UI surface, so nothing there needed updating. The SDK reference went
  into `GRPC-CONTRACT.md` §4 per the task's "and/or" framing.
- `docs/public/plugins*.md` — do not exist on this branch (confirmed); per the
  task instructions these live on `feature/kandev-plugin-system-docs` and are
  out of scope here.
- `apps/backend/internal/plugins/manifest/manifest_test.go` has an unrelated
  test fixture using `api_read: ["tasks", "agents"]` as a manifest capability
  example — manifest capability values are freeform strings with no vocabulary
  validation at that layer (confirmed: no enum/allow-list check in
  `internal/plugins/manifest`), so this is a test fixture choice, not a
  functional bug; flagged here as a code-side echo of the same naming drift,
  left unchanged since it's code, not docs.
</content>