Knowledge Base Guide

The real knowledge base lives at /knowledge, but the UI and database read surface are admin-only. Docs keeps this guide so product, engineering, and admin users can understand how knowledge entries flow into Agent generation.

Product Boundary

• /knowledge stores admin-curated design principles, page patterns, accessibility guidance, and Agent directives.
• /docs stores platform documentation, operating notes, and usage guidance.
• Draft, review, private, rejected, and archived knowledge never enters public Agent generation context.
• Only published public knowledge can be retrieved by backend RAG through the service role; public users cannot browse the knowledge UI or call the matching RPC directly.

Knowledge Entry Shape

Each knowledge entry has:

• Title, slug, category, tags, status, visibility, author, quality score, and published timestamp.
• A versioned body with bilingual summary, principle, apply/avoid scenarios, Agent directive, and retrieval queries.
• Published section chunks used for full-text and embedding retrieval.
• RAG event logs that record which chunks were used by which workflow stage, including empty-hit events so coverage can be measured honestly.

RAG Flow

1. A user starts a workflow from the creation page.
2. The workflow loads selected Skills.
3. Sable also acts as the knowledge retrieval manager.
4. The retrieval query is built from the user brief, requirement summary, selected Skills, page type, and asset summaries.
5. If embedding is configured, pgvector retrieves top matching published section chunks.
6. If embedding is unavailable or fails, the system falls back to full-text and keyword scoring.
7. The workflow applies a lightweight section-aware rerank before keeping 4-8 compact hits. agent-directive, apply-when, retrieval-queries, and principle receive stronger task-fit weight; avoid-when is boosted when the request contains negative intent such as "no", "avoid", or "不要".
8. The kept hits include title, summary, principle, Agent directive, source ID, matched section, matched chunk content, and rerank metadata such as sectionRole, sectionWeight, baseScore, and lexicalOverlap.
9. Cleo, Isolde, Sable, and Orson read those constraints during planning and QA.
10. After generation, qa_report.knowledgeAdherence records lightweight evidence signals from the generated HTML/source: matched knowledge item, section, evidence terms, missing terms, and whether each hit is evidence-found, needs-review, or missing-signals.
11. Admins can review recent knowledge_rag_events in /knowledge/manage, including query, stage, query type, hit section/source, rerank score, base score, and section weight. The panel also summarizes recent event count, hit coverage, average hits, average top score, query type distribution, section/source distribution, and low-confidence queries. This is the first observability surface before a full production RAG dashboard.
12. Engineers can run npm run knowledge:rag-events -- --format=eval-candidates to turn no-hit and low-confidence production queries into draft eval cases. Humans must fill expected slugs in docs/KNOWLEDGE_RAG_EVAL_CASES.md before adding them to scripts/evaluate-knowledge-rag.mjs.

Chunk Strategy

Published knowledge is split by language and section instead of stored as one coarse record per language. Current sections are:

• summary
• principle
• apply-when
• avoid-when
• agent-directive
• retrieval-queries
• body

Each chunk keeps metadata with slug, category, tags, section, section role, and chunkVersion: 2. Retrieval now uses this section shape during rerank, and vector/fallback hits keep the base score plus the adjusted score metadata so ranking decisions can be inspected later.

The current adherence report is intentionally conservative. It verifies that generated output contains source-level or visible-text signals related to retrieved knowledge; it does not prove design quality, accessibility, or full policy compliance yet. Future versions should turn section hits into explicit checklists, tune rerank weights with negative cases, and feed missing signals into Elara repair prompts.

Generation Rule

Knowledge is not page copy. Agents must transform retrieved principles into layout, component, interaction, accessibility, and responsive constraints. The visible page should never quote agent_directive verbatim unless the user explicitly asks to build a knowledge/detail surface.

Admin Workflow

• Admins save drafts, submit review, publish, reject, archive, or rebuild chunks.
• Publishing syncs the current version into knowledge_chunks.
• Rebuilding chunks refreshes retrieval material and optionally embeddings.
• /knowledge/manage shows recent RAG events and a lightweight retrieval health summary so admins can inspect which chunks actually reached workflow planning and which queries need review.
• npm run knowledge:rag-events prints a JSON retrieval-health summary from recent production events; pass -- --format=eval-candidates to produce draft regression cases from low-confidence queries.
• docs/KNOWLEDGE_RAG_EVAL_CASES.md is the human review queue between production telemetry and the fixed regression suite.

Configuration

Embedding is optional for the first version.

• EMBEDDING_API_KEY
• EMBEDDING_BASE_URL
• EMBEDDING_MODEL

When these are missing, published knowledge remains searchable through the fallback retrieval path.