#Glaze Companion Design (Exploration)

Build a macOS app called "FPF Companion": a read-only reader and lookup client
for the First Principles Framework reference, backed by exactly one external
service, the hosted MCP endpoint:

  https://mcp.fpf.sh/api/mcp/fpf_reference/mcp   (server name: fpf_reference)

IMPORTANT — runtime transport: Glaze's own MCP integration is build-time
only (it equips the build agent, not the shipped app). The app itself must
implement a plain HTTP client for the endpoint above using the MCP
Streamable HTTP transport, with the full lifecycle:
1. every request sends header "Accept: application/json, text/event-stream";
2. POST a JSON-RPC 2.0 initialize request whose params include
   protocolVersion ("2025-06-18"), capabilities ({} suffices for this
   read-only client), and clientInfo ({ name: "fpf-companion", version });
   then POST the notifications/initialized notification;
3. after initialize, send header "MCP-Protocol-Version: <the version
   returned in the initialize result>" (currently 2025-06-18) on every
   subsequent request;
4. if any response returns an Mcp-Session-Id header, echo it as a header
   on every subsequent request;
5. then POST tools/call requests with the tool name and arguments; each
   response arrives as Content-Type application/json (parse directly) or
   text/event-stream (read the SSE stream until the JSON-RPC message whose
   id matches the request id; earlier events may be notifications or
   server requests — answer a ping request with an empty result, answer
   any other server request with JSON-RPC error -32601 (method not
   found), and skip only notifications the app does not handle) —
   support both, as the Accept header promises;
6. handle failures without crashing: a JSON-RPC response may carry an
   "error" member instead of "result" — surface its message in the UI as
   a readable error state; an HTTP 404 received while sending
   Mcp-Session-Id means the session expired — discard the session id and
   re-run the initialize flow once before concluding anything is wrong;
   other HTTP failures and timeouts (use a 15 s request timeout and at
   most one retry, consistent with the bounded-request rule) switch the
   app to the offline state of behavior 6, keeping cached content
   readable and labeled.
Where this recipe is silent, follow the official MCP Streamable HTTP
transport and lifecycle spec (modelcontextprotocol.io, revision
2025-06-18) — it wins over any shortcut a code generator might prefer. In every tools/call response, the tool payload lives in the
JSON-RPC envelope's result.structuredContent — NOT directly on result
(result.content is only a human-readable text fallback); read all fields
below from structuredContent. Do not depend on any Glaze MCP server
connection existing at runtime — if the generated app cannot reach the
endpoint with its own HTTP client, the build has failed its primary
acceptance test: the app must function with this endpoint as its only
network dependency.

Call only these five tools through that client, nothing else:
- get_fpf_index_status {} -> { sourcePath, sourceHash?, builtAt?,
  snapshotExists, currentSourceHash, fresh, compilerMode, artifacts,
  sessionCache }
  (sourceHash and builtAt are OMITTED when no snapshot could be loaded —
  exactly the degraded case; parse them as optional or the degraded render
  itself breaks)
- search_fpf { query (<=1000 chars), kind?: pattern|route|lexeme|preface,
  limit?: 1..100 } -> { hits: [{ id, kind, title, status?, part?, score,
  snippet }], total, snapshot }
- browse_fpf_catalog { part?, status?, kind?, limit?: 1..500, offset? }
  -> { entries: [{ id, kind, title, status?, part?, description }], total,
  nextOffset?, didYouMean?, snapshot }
- ask_fpf { question (<=2000 chars), mode?: compact|verbose|proof }
  -> { markdown, ids, citations, constraints, gaps, confidence (nullable),
  candidateIds?, status, snapshot }
  (candidateIds carries the structured suggestions rendered as chips when
  status is "ambiguous" — never scrape them from the markdown. ALWAYS send
  mode explicitly, "compact" unless the user toggles otherwise: the
  server-side default is deployment-configured and is verbose in
  production, so omitting mode gives slow verbose answers)
- read_fpf_doc { selector (<=256 chars), mode?: preview|full, maxChars? }
  -> { status: ok|not_found, resolvedAs: id|route|lexeme|not_found,
  title?, nodeId?, markdown?, markdownChars?, truncated?, headings?,
  preview?, docRef?: { staticPath }, snapshot }
  (on status "not_found" the content fields are absent — render the
  Reader's not-found recovery state offering Search, never an empty page)

(The endpoint also exposes a sixth public tool, query_fpf_spec; it returns an
agent-facing structured envelope and is intentionally NOT used by this app —
do not call it or generate code for it.)

App shape: a menu-bar icon with a global-shortcut quick-search (top 5
search_fpf hits; Enter opens the reader; typing an exact ID like "A.1.1" or
"route:project-alignment" opens the reader directly), and a main window with
a sidebar: Ask, Search, Catalog, Reader, Status.

Non-negotiable behaviors:
1. Call get_fpf_index_status at launch, on manual refresh, after any
   stale_snapshot_prevented answer, and on network reconnect — never on a
   timer. Trusted state
   requires snapshotExists && fresh && currentSourceHash === sourceHash.
   Show a green "Fresh" pill when trusted, amber "Degraded" otherwise, and
   label all content "unverified" in degraded state.
2. Every answer and page shows a footer with the response's own
   snapshot.sourceHash (first 12 hex chars) and builtAt. If it differs from
   the status hash, show a stale banner.
3. ask_fpf answers are grounded summaries. For exact spec wording always
   fetch read_fpf_doc and say so in the UI ("Exact text").
4. Handle the answer status enum: ok; not_found (offer search); ambiguous
   (render candidateIds as suggestions); unsupported (explain);
   stale_snapshot_prevented (stale banner + status re-check).
5. Reader fetches use maxChars 20000 first; when truncated is true show
   "Load full page (N chars)" and re-fetch with maxChars = min(N, 200000)
   — maxChars must always stay within the schema bounds [100, 200000].
   Preview/hover cards use mode "preview".
6. Cache responses keyed by (tool, arguments, sourceHash); drop the cache
   when the status hash changes. NEVER cache get_fpf_index_status itself —
   it is the invalidation oracle and always goes to the network. Offline:
   cached pages stay readable, labeled "offline — freshness unverified"
   with their snapshot hash.
7. Enforce input bounds client-side: question <= 2000 characters and never
   empty, search query <= 1000 and never empty, selector <= 256 and never
   empty, catalog part/status filters <= 64, maxChars within [100, 200000];
   omit empty optional fields entirely instead of sending empty strings.
   Debounce search by >= 300 ms (or fire on submit); page the catalog with
   nextOffset, and when a browse response carries didYouMean.part, offer it
   as a one-tap corrected filter; never poll.
8. Freshness means internal consistency of the deployed snapshot only —
   never display any claim that upstream FPF is current.
9. The service name is fpf_reference. Never reference "fpf_memory" anywhere:
   not in code, settings, copy, or the store listing. Any store or unlisted
   listing must name fpf_reference and link https://fpf.sh/.
10. The app is read-only: no notes, no memory, no editing, no workflow
    features. Link out to https://fpf.sh/ for the full site, and give
    every Reader page an "open on fpf.sh" link built from its
    docRef.staticPath.

Visual design: default native macOS look — standard system appearance,
system fonts, light and dark mode both supported. Do not invent a custom
brand palette. The only required visual elements are functional:
- Layout: left sidebar (Ask, Search, Catalog, Reader, Status) + content
  pane; freshness pill at the sidebar bottom with the snapshot
  short-hash beneath it; window footer with endpoint name, snapshot
  short-hash, and freshness state.
- Semantic states: the freshness pill uses the platform's standard
  positive color when trusted and warning color when degraded; the stale
  banner uses the warning color. Kind badges (pattern / route / lexeme /
  preface) are visually distinct from each other using system-appropriate
  tints.
- Monospace for every FPF ID, snapshot hash, and payload value.
- Components: search hits as rows (kind badge, title + monospace ID,
  part/status, one-line snippet, score); FPF IDs rendered as chips that
  open the Reader; every answer ends with a grounding footer
  (confidence · status · snapshot short-hash · builtAt), with the
  answer's citations, constraints, and gaps listed beneath it; every
  Reader page ends with a footer (status · snapshot short-hash ·
  builtAt); the Status surface's detail view lists sourcePath,
  sourceHash, builtAt, compilerMode, and the artifact booleans.