This is the architecture specification for the HC Page Agent system. It documents how an embedded LLM agent discovers and reads HC pages to answer questions without traditional RAG infrastructure.
Read the visual HTML below. Each section has diagrams, code examples, and implementation notes. The design system uses Poppins/Source Sans 3 to match the Phase 1 execution page format.
--- ## hc-context-public { "document_type": "architecture_specification", "version": "1.0.0", "sections": [ { "id": "core-premise", "title": "Core Premise: HC Pages as Knowledge Base", "key_points": [ "Every HC page contains structured JSON metadata (hc-metadata, hc-context-public)", "hc-instructions tells the agent HOW to interpret each page", "No vector database, no embeddings, no chunking pipeline needed", "Registry pages serve as table-of-contents for all linked pages", "Updates are instant — publish a page, agent sees it on next query" ] }, { "id": "discovery-protocol", "title": "Discovery Protocol: Registry Crawl", "steps": [ "1. Agent reads OWN page's hc-metadata (already in DOM, zero-cost)", "2. Agent reads registry_stack to find parent registries", "3. Agent fetches registry's hc-metadata (one API call per registry)", "4. Registry metadata contains meetings[], artifacts[], blockers[] arrays", "5. Agent matches user query against registry entries", "6. Agent fetches relevant linked pages on demand (targeted reads)", "7. Agent answers with citations to specific pages/dates" ] }, { "id": "existing-implementation", "title": "Existing Implementation", "components": { "ChatAgent": { "file": "templates/athio-registry-jsx.jsx", "lines": "237-348", "description": "React component embedded in Athio JSX registry. Floating chat widget with message history. Calls /api/hc/registry-agent first, falls back to /api/chat.", "current_limitations": [ "Passes full metadata blob (truncated to 12KB) as system prompt context", "No on-demand page fetching — only reads own registry data", "No streaming — waits for full response", "No conversation persistence across page reloads" ] }, "registry_agent_api": { "file": "app/api/hc/registry-agent/route.ts", "endpoint": "POST /api/hc/registry-agent", "actions": ["assess", "rebuild", "cleanup", "chat"], "description": "Server-side LLM proxy. Receives registry data or fetches by ID. Truncates to 15K chars. Calls Claude Sonnet with structured system prompt.", "current_limitations": [ "No tool-use — agent cannot fetch linked pages mid-conversation", "Single-turn only (no multi-turn memory)", "Context window limited to 15K chars of registry metadata", "No cross-registry discovery" ] }, "skill_injector": { "file": "lib/hc/skill-injector.ts", "description": "Client-side registry walk. Fetches registry stack, discovers cross-references, injects cards. Already implements the crawl pattern the agent needs.", "key_functions": ["buildRegistryCrossRefScript", "toHcFormat", "injectHcEnhancements"] }, "hc_format_export": { "file": "lib/hc/skill-injector.ts", "function": "toHcFormat(html, sourceUrl)", "description": "Converts any HC page HTML to a plain-text .hc format optimized for LLM consumption. Extracts hc-metadata, hc-instructions, and hc-context-public blocks into readable sections." } } }, { "id": "planned-architecture", "title": "Planned Architecture: Tool-Using Agent", "design": { "agent_model": "claude-sonnet-4-20250514", "tool_use": true, "tools": [ { "name": "read_own_page", "description": "Read the hc-metadata and hc-context-public from the page the agent lives on", "input": {}, "output": "Parsed JSON metadata object" }, { "name": "list_registry_entries", "description": "Fetch the parent registry and return all entries (meetings, artifacts, blockers, actions)", "input": { "registry_url": "string (optional, defaults to registry_stack[0])" }, "output": "Array of registry entries with name, url, summary, tags, date" }, { "name": "read_page", "description": "Fetch any HC page by URL and return its hc-metadata + hc-context-public as structured data", "input": { "page_url": "string" }, "output": "Parsed page metadata and context" }, { "name": "search_registry", "description": "Search registry entries by keyword, tag, date range, or person filter", "input": { "query": "string", "filters": { "tags": "string[]", "person": "string", "date_from": "string", "date_to": "string" } }, "output": "Filtered array of matching entries" }, { "name": "walk_meta_registry", "description": "Discover all registries from the meta-registry, returning their names, URLs, modes, and entry counts", "input": { "meta_registry_url": "string (defaults to /meta-registry)" }, "output": "Array of registry descriptors" } ], "conversation_flow": [ "User sends message", "Agent receives: system prompt + page metadata + user message", "Agent decides which tools to call based on question", "For 'what blockers exist?' → list_registry_entries → filter blockers", "For 'what did Jason discuss in Day 3?' → search_registry(person=Jason, query=Day 3) → read_page(matching URL)", "For 'show all registries' → walk_meta_registry", "Agent synthesizes answer with citations", "Response streamed to chat widget" ] } }, { "id": "security-and-limits", "title": "Security & Context Management", "policies": { "page_fetch_limit": "Max 5 pages per conversation turn (prevent runaway crawls)", "context_budget": "Total fetched content capped at 50K tokens per turn", "auth": "Registry-agent API uses session auth (no public access)", "rate_limit": "10 requests per minute per user", "allowed_domains": "Agent can only fetch pages from domains the user owns", "no_write": "Agent is read-only in v1 — cannot update registries or dismiss items", "api_key": "Anthropic API key stored as ANTHROPIC_API_KEY env var on Vercel" } } ], "open_questions": [ "How many pages can the agent read in one conversation? (context window vs latency)", "Should we cache registry data between messages? (freshness vs speed)", "Cross-registry discovery: agent on Athio registry wants AIROI data — allow or restrict?", "Should agent support WRITE operations in v2? (dismiss items, add notes)", "Streaming: SSE from registry-agent API for real-time chat UX?", "Conversation persistence: localStorage or server-side session?" ], "rollback_strategy": { "git_sha": "e715500", "description": "This page is a new artifact — rollback is simply deleting the page from Supabase. No existing pages are modified.", "registry_versioning": "Auto-versioned on registration via update-registry API" } }