> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberskill.world/llms.txt
> Use this file to discover all available pages before exploring further.

# KB: Markdown Knowledge Base, Search, and AI Grounding

> CyberOS KB is a versioned markdown knowledge base with three-layer search (lexical, semantic, reranker) and AI Q&A grounded in your own documents.

KB is CyberOS's documentation surface and the canonical source for AI-grounded retrieval. It plays three roles simultaneously: it is the RAG corpus that gives CUO (Genie) something credible to cite, the memory companion where curated long-form documents live alongside the audit-chained memory store, and the runbook catalogue that the OBS auto-runbook router consults during alert triage. Strip KB out and CUO has nothing to ground answers in — "ask the docs" becomes "make things up." Every document you write in KB is a first-class citation source, every AI answer cites span-level back to KB, and every "Promote to canonical" elevates a document to a high-authority source for cross-tenant AI synthesis. KB is where institutional knowledge becomes a system property, not a person property.

<Note>
  KB is a P1 module currently in the design phase. This page describes the planned functionality from the user perspective. Refer to the platform roadmap for GA availability details.
</Note>

***

## Document model

Every KB document is a structured artefact, not a free-form wiki page.

<CardGroup cols={2}>
  <Card title="Slug" icon="link">
    A unique, stable URL identifier per tenant (for example, `how-to-file-leave`). Slugs are immutable once set — rename by creating a new document and redirecting from the old slug.
  </Card>

  <Card title="Markdown body" icon="file-text">
    Documents are written in CommonMark + GFM markdown. The server renders sanitised HTML on every read — no client-side execution, no XSS surface.
  </Card>

  <Card title="YAML frontmatter" icon="code">
    Each document carries frontmatter with `title`, `category`, `language` (`vi` or `en`), `permission`, and optional `translation_of` (link to a counterpart document in the other language).
  </Card>

  <Card title="Category" icon="tag">
    One of six closed categories: `how-to`, `reference`, `decision-log`, `policy`, `runbook`, or `trust-center`. The category determines retention rules and default permissions.
  </Card>
</CardGroup>

### Versioning

Every save produces a new **immutable version**. The document's current version pointer advances to the new version; prior versions are never modified. Versions are retained in the audit history — you can always reconstruct exactly what a document said at any point in time.

<Note>
  There is no "edit in place" in KB. Every keystroke that results in a save produces a new version. This is intentional: KB documents are cited by AI answers and referenced by PROJ Issues. If the underlying content could change silently, those citations would become untrustworthy.
</Note>

***

## Creating and editing documents

<Steps>
  <Step title="Create a new document">
    Open **KB → New Document**. Set the slug, title, category, language (`vi` or `en`), and permission tier. The document is created in draft state — it is not yet searchable or accessible to other members.
  </Step>

  <Step title="Write in markdown">
    Use the built-in editor (or any markdown tool via the REST API). Include YAML frontmatter at the top of the file. Attachments (images, PDFs) upload directly in the editor and are stored securely.
  </Step>

  <Step title="Set permissions">
    Choose one of the permission tiers (see below) before publishing. You can tighten permissions later, but loosening them requires an explicit permission change that is logged in the audit history.
  </Step>

  <Step title="Save and publish">
    Click **Save**. CyberOS renders the markdown to sanitised HTML, creates an immutable version, and queues a re-indexing job. The document is live and searchable within seconds.
  </Step>
</Steps>

### Permission tiers

| Tier              | Visible to                                                                     | Typical use                                            |
| ----------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
| `public`          | Anyone with the URL, including anonymous visitors (if Trust Center is enabled) | Trust Center pages, public marketing docs              |
| `org`             | Any authenticated member of your tenant                                        | How-to guides, reference docs, decision logs (default) |
| `role-restricted` | Members holding one of the allowed roles                                       | HR policy, compensation references, security runbooks  |
| `share-link`      | Anyone holding a valid time-bound token                                        | External client review of a specific document          |

To generate a share link for external access, open the document and click **Share → Create time-bound link**. Set an expiry date and optionally a view limit. The link auto-expires and can be revoked at any time from the document's **Share links** panel.

### Dual-language support

Documents in KB carry a `language` field (`vi` or `en`). Link a Vietnamese document to its English counterpart (or vice versa) by setting `translation_of` in the frontmatter or using **Document → Link translation** in the editor. When a member reads a document, KB serves the version matching their locale preference. The AI Q\&A engine grounds answers across both language versions when both are available.

***

## Three-layer search

KB search is a sequential pipeline designed for Vietnamese-language precision and AI retrieval quality.

<Steps>
  <Step title="Step 1 — Lexical (FTS5 / PGroonga)">
    Full-text search using FTS5 for Latin-script content and PGroonga with Vietnamese bigram tokenisation for Vietnamese. This step returns up to 100 candidate document versions based on keyword overlap. Vietnamese queries like *"hóa đơn cấp khi nào"* are tokenised correctly without needing the user to segment words manually.
  </Step>

  <Step title="Step 2 — Semantic (BGE-M3 embeddings)">
    The query is embedded using BGE-M3, a multilingual embedding model. Cosine similarity over the candidate set narrows the results to the top 30 most semantically relevant chunks.
  </Step>

  <Step title="Step 3 — Reranker (BGE-rerank-v2-m3)">
    The BGE-rerank-v2-m3 cross-encoder scores the top-30 chunks against the query in a single pass and returns the final top-10 results. The reranker accounts for query-document relevance at the sentence level, not just token overlap.
  </Step>
</Steps>

<Note>
  Permission filtering happens **before** the reranker — documents you are not permitted to read never reach the reranker, the Q\&A composer, or the search results. A permission leak via search is a severity-0 bug.
</Note>

***

## "Ask this page" AI Q\&A

Every document has an **Ask this page** button that lets you pose natural-language questions and receive answers grounded exclusively in that document and any documents it explicitly links.

<Steps>
  <Step title="Ask a question">
    Open a document and click **Ask this page**, or type a question in the document's Q\&A panel. For example: *"When must we issue the hóa đơn?"*
  </Step>

  <Step title="KB retrieves relevant spans">
    KB embeds your question with BGE-M3, finds the top-8 most relevant text spans across the current document and its linked documents, and passes them to the Q\&A composer.
  </Step>

  <Step title="AI composes a cited answer">
    The Q\&A composer calls the AI Gateway with a system instruction requiring every claim to cite a span ID. The AI returns a structured answer with inline citations.
  </Step>

  <Step title="Validate citations">
    KB validates that every cited span ID actually exists in the source document at the claimed location. If a citation does not match — a hallucination — KB rejects the answer and returns *"I don't know"* rather than a fabricated response.
  </Step>
</Steps>

You can hover any citation in the answer to jump directly to the source paragraph in the document. Citation accuracy targets ≥ 95% on the monthly human review sample.

<Tip>
  Use **Ask the KB** (the whole-corpus Q\&A, accessible from the search bar) when you are not sure which document holds the answer. Ask this page is best when you are already reading the right document and want to query it conversationally.
</Tip>

***

## Memory ingestion

Every time you save a document, KB automatically re-indexes it within **5 seconds p95**. The ingestion pipeline:

1. Strips markdown syntax to clean plaintext
2. Chunks the text at semantic boundaries (paragraph and heading level)
3. Embeds each chunk with BGE-M3
4. Updates the search index with the new chunks and embeddings
5. Confirms the ingestion is complete

Because ingestion is automatic on every save, the AI retrieval layer is never more than seconds out of date. You do not need to manually trigger re-indexing.

***

## OBS integration

KB stores the runbooks that the OBS auto-runbook router consults during alert triage. When OBS receives an alert, its triage engine calls KB to find runbooks whose `applicability` tags (provider, region, severity) match the alert's signature.

Write runbooks as `category: runbook` documents with an `applicability` frontmatter block. After every incident post-mortem, publish a new or updated runbook — the growth loop is built-in: novel incidents become new runbooks, and old runbooks gain confidence as OBS correlates their use with successful triage outcomes.

<Warning>
  KB outages affect the OBS auto-runbook router. OBS caches the last-known-good runbook catalogue with a 1-hour TTL, so short KB outages degrade — but do not break — alert triage. If KB is unreachable for more than one hour, OBS falls back to static severity routing and pages the on-call engineer.
</Warning>

***

## Promoting to canonical

**Promote to canonical** elevates a document from a regular knowledge base page to a high-authority source used by Lumi cross-tenant AI synthesis (where `sync_class` permits).

<Steps>
  <Step title="Request promotion">
    Open the document and click **Promote to canonical**. Enter the canonical memory path (for example, `memories/policy/leave.md`). This triggers a CHAT notification to the CDO seat for approval.
  </Step>

  <Step title="CDO approves">
    The CDO reviews the document to confirm it represents authoritative, stable knowledge suitable for cross-tenant synthesis. Approval is logged in the audit history.
  </Step>

  <Step title="Canonical entry created">
    KB registers a high-authority canonical entry mirroring the document. AI answers that cite it carry higher confidence weighting than answers citing ordinary search index chunks.
  </Step>
</Steps>

<Tip>
  Use "Promote to canonical" for company policy documents, architectural decision records (ADRs), and compensation references — documents that represent stable ground truth your whole organisation should be able to rely on. Do not promote drafts or documents you expect to change frequently.
</Tip>


## Related topics

- [MCP Gateway: Connect Any AI Agent to CyberOS Tools](/modules/mcp-gateway.md)
- [OBS: CyberOS Observability, Alerting, and Runbooks](/modules/obs.md)
- [What Is CyberOS? The AI-Native Operations Platform](/introduction.md)
- [CyberOS CHAT: Team Messaging, Calls, and AI Teammates](/modules/chat.md)
- [CyberOS Platform Changelog](/reference/changelog.md)
- [CyberOS Glossary: Terms, Acronyms, and Concepts](/reference/glossary.md)
- [AI Gateway: Multi-Provider AI Routing with Cost Controls](/modules/ai-gateway.md)
- [CyberOS AUTH: Sign-In Options, Roles, and MFA Setup](/modules/auth.md)
- [Vietnamese Market Compliance in CyberOS](/guides/vn-compliance.md)
- [LEARN Module: Skill Catalogue, VP Engine, and Promotions](/modules/learn.md)