Skip to main content
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.
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.

​
Document model

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

Slug

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.

Markdown body

Documents are written in CommonMark + GFM markdown. The server renders sanitised HTML on every read — no client-side execution, no XSS surface.

YAML frontmatter

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).

Category

One of six closed categories: how-to, reference, decision-log, policy, runbook, or trust-center. The category determines retention rules and default permissions.

​
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.
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.

​
Creating and editing documents

1

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.
2

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.
3

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.
4

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.

​
Permission tiers

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.
KB search is a sequential pipeline designed for Vietnamese-language precision and AI retrieval quality.
1

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.
2

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.
3

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.
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.

​
”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.
1

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?”
2

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.
3

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.
4

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.
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.
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.

​
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.
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.

​
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).
1

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.
2

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.
3

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.
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.