Polish Reference Api Discovery Seams
Artifacts
Official change artifacts tracked under openspec/.
A cold-start integrator (human or agent) hitting the reference AS/RS today has no obvious entry point. Probing /, /health, /v1 returns uniform 404s. Two independent fresh-eyes assessments (see tmp/pdpp-review-memo.md) both wasted significant time before reaching the well-known endpoint and /v1/schema. One observer concluded the server was non-functional. The recall surface, query API, and discovery endpoint behind the bearer are strong; the rough edges are at the seam an unauthenticated probe sees first.
The query/recall surface (records, search lexical/semantic/hybrid, aggregations, blobs) is in good shape. The seam where cold-start clients fail is the uniform 404 at common entry points. The two fresh-eyes failures recorded in tmp/pdpp-review-memo.md both came from probing /, /v1, /api/v1/... and getting nothing — even though the well-known endpoint and /v1/schema already publish everything an integrator needs.
Affected capabilities
Capability specs this change proposes to modify.
Project notes
Change-local notes that support this workstream but have not been promoted into the official change artifacts.
Polish Reference Api Discovery Seams
1 notes · 1 working note · updated