Chain · Interpretation — a visitor asks, the corpus answers in your voice
Parent: requirements-to-design
L0 · Vision
- introduction — "inverts the compression": a curated knowledge base a visitor queries, answered by an AI in your voice, grounded in your own words, with citations; "modes are roles — four apps sharing one corpus (self / public / recruiter / friend)"; ACL is the hard wall, role the soft framing.
- lossy-self-presentation — three losses (memory / capture / delivery); StandMeet stores the graph and linearizes at query time for the specific question.
- dont-repeat-myself — every repeated explanation the system absorbs is time reclaimed.
- differentiation — retrieval is dialogic: a specific question gets a specific answer, not a ranking.
L1 · Promise
Anyone can ask a specific question and receive a specific answer phrased in the owner's voice, grounded and cited, framed for their role — one corpus, linearized per question per audience.
L2 · Requirements (journeys & features)
The visitor journey set (features-and-journeys), running on three feature surfaces: public pages — the root is the homepage microsite (a5e1cada9, 2026-09-04; the rich DefaultHome built from SDK widgets is served from code when no microsite is attached, 28f750caf / 185c4321b, app/src/app/default-home.tsx) with ChatRoom as the built-in coded chat (app/src/app/visitor-root.tsx:10), plus the /wiki / /output / /writings readers — the inference/chat engine, and the visitor session — including AskAboutThis on the readers (the earlier FloatingChatDock is gone, 1d9500acd, 2026-08-16). (The doc's per-journey details live there; this chain doesn't restate them.)
L3 · Design decisions
- Role framing — the visitor's rules and persona come from the RoleSnapshot frozen at code issue; the "four apps" of the vision are role configurations over one corpus.
- Retrieval — corpus-retrieval: a Meilisearch lexical index (Postgres FTS as the fallback) + tree navigation; deliberately no vector (relevance = the owner's own links). The graph walk landed too, but not as the bounded-depth BFS sketched here — it is
corpus_links, a 1-hop op returning{outgoing, backlinks}, and the agent decides whether to go further by calling again on a neighbour. The BFS was the wrong mental model: relevance is the links, so depth is a reading decision, not a query parameter. "Linearizes the graph" now holds at the retrieval layer as well as the data layer. - Grounding — citations ride the persisted turn as
grounding_refs(Citation VOs written atomically with the message rows,backend/internal/routes/public/agent_turn.go:205,conversation/ops/conversations_shape.go:85) and render as the transcript's CitationsList (app/src/components/visitor/ChatTranscript.tsx); the oldchat.show_groundingop went with the dispatcher refactor (5bd5ed95f, 2026-08-01). - Loop termination — force-final-answer:
ask_visitorwithReturnDirectlyends the loop. - Result surfaces — ui-cards (
ui://cards for corpus_search/list, summarize, calendar slots). - Entry neutrality — entry-agnostic-agent: the chat entry is one consumer of the neutral launch boundary.
L4 · Engineering artifacts
backend/internal/conversation/inference— the eino ADK loop (Anthropic native / OpenAI-compatible adapters); the SSE proxy lives here (unbuffered-sse-passthrough).backend/agentcore—BuildVisitorAgent(driver, input)(visitor_build.go:50), the launch seam.- prompts — the
visitor-headerfragment (backend/internal/owner/entity/prompt_fragments.go, assembled inconversation/usecase/visitor_chat_prompt.go); part_ids + hash are the drift instrument (system-prompt-hash-regression), pinning assembled-prompt identity. mcp-servers/retrieval— eight tools,corpus_search / read / list / links / map / resolve / peek / grep(main.go:39-46), sandboxed, reaching host data via capsocket (isolation, one narrow socket).backend/internal/infra/session—visitor_session,query_queue.go.app/src/lib/page/use-chat.ts,use-chat-session.ts— the thin SSE consumer;ChatRoom/ChatTranscript/AskAboutThiscomponents; the SDK'sCorpusWidgetwith its subtree / sort / limit query language (113ba6a1a, 2026-09-06) lets a microsite show corpus inline.
L5 · Verification
E2e spec tags (as recorded in features-and-journeys): [✓ public-page], [✓ byoai-chat], [✓ visitor-chat-permissions-deny], plus the visitor-chat suites; eval-harness drives the same real loop via EvalDriver (golden/plugin/retrieval assembly + launch tests).
Status & gaps
Loop, persona freezing, grounding surface, and cards are landed — and so are the two faces this chain used to wait on: the crawl face (corpus_links over note_refs, mcp-servers/retrieval/main.go:42; corpus_grep as the never-miss channel; corpus_search says so when its tokenizer cannot see a query, bd45353f4) and the render face (KaTeX / Mermaid / callouts / TikZ on the readers, rendering-engines). "Answers from your linked thinking" is now a walk of the owner's links, not FTS-over-text (corpus-retrieval). What remains thin is not mechanism but measurement: quality is checked by the eval-harness offline, not on the live loop (eight-controls-applied).