KB

The naive read of KB: "it's our wiki." The real read: KB is what makes Genie a useful agent and OBS a useful operations console. Strip KB out and CUO has nothing to cite, OBS's auto-runbook router has nothing to consult, and "ask the docs" becomes "make stuff up." KB is the structured-knowledge half of the BRAIN protocol — long-form versioned, ACL-aware, server-rendered docs — that the audit-chained memory store doesn't replace but complements.

KB in the platform — who reads, who consults

Auto vs human-in-loop operations matrix

Three jobs in one module: (a) the docs surface a team needs for how-tos, runbooks, decision logs, and policies; (b) the canonical source for grounded AI retrieval — if you do not control where the AI answer comes from, you do not control what it says; (c) a per-doc permissioned publishing layer for Trust Center pages and client-shared documents. Off-the-shelf wikis (Notion, Confluence) handle (a) but treat (b) and (c) as afterthoughts. CyberOS treats (b) as the central design force: every KB document is a first-class BRAIN Layer 2 citation source, every Q&A answer cites span-level back to KB, and every "promote to canonical" elevates a doc to a high-authority BRAIN source. That property is only credible when KB owns its versioning, ACL, and ingestion path.

The bet is that the docs surface and the AI retrieval surface are the same surface. The cost is that KB is more constrained than a free-form wiki — every doc has a category, every save is versioned, every ingestion respects ACL. The benefit is that "ask the KB" is a credible AI feature, not a vibes-shaped hallucination machine, because every answer cites a specific span of a specific doc.

A structured decomposition of KB's scope. Every cell traces back to and §19.7.

KB is one axum service. Four surfaces (GraphQL subgraph, REST admin, public-readable HTML for Trust Center pages, MCP tool catalogue). Three stores (PostgreSQL canonical + PGroonga + FTS5, Redis hot cache, S3 for attachments). The renderer and the BRAIN ingester are separate concerns: the renderer produces HTML for humans; the BRAIN ingester produces a sanitised plaintext + chunking stream for vectorisation.

Document categories (closed)

Internal components

Documents have a slug, current version pointer, category, permission tier, language, and optional translation_of link. Versions are immutable; the document row's current_version_id points at the latest. Permissions cascade by category (tenant default) and can be tightened per doc.

Permission tiers

Four surfaces: a federated GraphQL subgraph; a REST surface for editor + reader (with rendered HTML caching at the edge); a public HTML endpoint for Trust Center pages; and an MCP tool catalogue (search + ask) for CUO.

GraphQL subgraph

extend schema
 @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@requiresScopes"])

type Document @key(fields: "id") {
 id: ID!
 slug: String!
 title: String!
 category: Category!
 permission: PermissionTier!
 language: Language!
 translationOf: Document
 translations: [Document!]!
 currentVersion: Version!
 versions(limit: Int = 20): [Version!]!
 renderedHtml: String!
 tags: [String!]!
 attachments: [Attachment!]!
 backlinks: [Document!]!
 trustCenterPublished: Boolean!
 brainIngestState: BrainIngestState
 promotion: Promotion
}

type Version @key(fields: "id") {
 id: ID!
 documentId: ID!
 versionNum: Int!
 savedAt: DateTime!
 savedBy: Subject!
 changeSummary: String
 wordCount: Int!
 diffFrom(version: ID!): String!
}

type SearchResult {
 document: Document!
 snippet: String!
 score: Float!
}

type QAResult {
 question: String!
 answer: String!
 citations: [Citation!]!
 confidence: Float!
}

type Citation {
 documentId: ID!
 documentTitle: String!
 versionId: ID!
 charStart: Int!
 charEnd: Int!
 snippet: String!
}

enum Category { HOW_TO REFERENCE DECISION_LOG POLICY RUNBOOK TRUST_CENTER }
enum PermissionTier { PUBLIC ORG ROLE_RESTRICTED EXPLICIT SHARE_LINK }
enum Language { VI EN }

type Query {
 document(id: ID, slug: String): Document
 searchDocuments(query: String!, category: Category, limit: Int = 10): [SearchResult!]!
 askPage(documentId: ID!, question: String!): QAResult!
 askKb(question: String!, scope: AskKbScope): QAResult! @requiresScopes(scopes: [["kb.ask"]])
}

type Mutation {
 createDocument(input: CreateDocumentInput!): Document!
 @requiresScopes(scopes: [["kb.write"]])
 saveDocument(id: ID!, markdown: String!, changeSummary: String!): Version!
 setPermission(id: ID!, tier: PermissionTier!, allowedRoleCodes: [String!]): Document!
 @requiresScopes(scopes: [["kb.permission"]])
 promoteToCanonical(id: ID!, brainCanonicalPath: String!): Promotion!
 @requiresScopes(scopes: [["kb.promote"]])
 createShareLink(id: ID!, validUntil: DateTime!, maxViews: Int): ShareLinkResult!
 importNotionZip(zipS3Key: String!): NotionImportJob!
 @requiresScopes(scopes: [["kb.import"]])
}

REST surface

MCP tool catalogue

Flow 1 — Create / edit a doc with BRAIN re-ingest

Flow 2 — Triple-layer search

Flow 3 — "Ask this page" with citations

Flow 4 — Promote to canonical

Flow 5 — Notion import

A document's status is implicit (it always has a current version). Versions are immutable; archive / restore moves the current_version_id pointer. Promotion is a one-way state transition that registers the doc as a BRAIN canonical source.

Version retention

NFRs from that KB must satisfy.

KB depends on AUTH (RBAC + ACL), BRAIN (Layer 2 ingestion target + audit), AI Gateway (Q&A composer), MCP (CUO tools), and OBS. It is depended on by CUO (grounded answers), Trust Center readers, and downstream agents that ask KB questions.

KB holds policy and decision-log documents that are themselves compliance artefacts; it must satisfy retention, residency, and access-audit obligations.

KB-specific risks tracked in the risk register.

KB rolls up 9 KPIs covering search quality, Q&A grounding, ingestion latency, and editorial health.

KB is owned by CDO seat (interim CEO).

cyberos-kb for tenant operators, bulk import / export, and CDO promotion review.

1. Create a doc from markdown

$ cyberos-kb create \
 --slug how-to-file-leave \
 --category how-to \
 --language vi \
 --file./leave.md

[create] doc id: 01HZL1…
[render] markdown → HTML (sanitised)
[brain] enqueued ingest job
[audit] brain seq=15401 chain=…

2. Link a translation

$ cyberos-kb link-translation \
 --vi how-to-file-leave \
 --en how-to-file-leave-en

[link] translation_of pair created (vi ↔ en)
[audit] brain seq=15402 chain=…

3. Search

$ cyberos-kb search "hóa đơn cấp khi nào" --limit 5

rank slug score snippet
1 how-to-issue-hoadon 0.94 "...cấp hóa đơn khi giao hàng hoặc..."
2 policy-hoadon-issuance 0.89 "...Theo Circular 78/2021, hóa đơn phải cấp..."
3 runbook-hoadon-failure 0.76 "...nếu cấp hóa đơn thất bại, kiểm tra..."
4 decision-log-hoadon-migration 0.71 "...chúng tôi chọn vietnam-vat-invoice vì..."
5 reference-hoadon-fields 0.68 "...trường mst, đơn vị tính, thuế suất..."

4. Ask a page

$ cyberos-kb ask-page \
 --slug how-to-issue-hoadon \
 "When must we issue the hóa đơn?"

answer (confidence: 0.91):
 The hóa đơn must be issued at the time of delivery of goods or completion
 of service provision [1], with the exception of advance payment scenarios
 where it must be issued within 5 working days of receipt [2].

citations:
 [1] how-to-issue-hoadon · v3 · spans 142-298
 [2] policy-hoadon-issuance · v7 · spans 1402-1490

5. Promote to canonical

$ cyberos-kb promote --slug policy-leave --canonical-path memories/policy/leave.md

[validate] requesting CDO approval (CHAT Notify sent)
[approved] by stephen@cyberskill.world at 2026-05-14T09:32Z
[brain] canonical entry created at memories/policy/leave.md
[audit] brain seq=15418 chain=…

6. Notion import

$ cyberos-kb import notion --zip notion-export.zip --map cat=how-to

[parse] 247 pages found in zip
[convert] blocks → markdown
[create] ✓ 244 docs created · ✗ 3 (in errors.csv)
[brain] all enqueued
[audit] brain seq=15489 chain=…

7. Export a tree

$ cyberos-kb export --root policy --format markdown --output./policies/

[export] 28 docs · 4 categories · written to./policies/
[manifest] policies/INDEX.md generated

KB is the curated-canonical-docs companion to BRAIN's audit-chained memory. Of the 47 CUO personas, the knowledge-stewardship ones below feed KB the most.

KB documents marked canonical elevate to high-authority BRAIN sources used by Lumi cross-tenant synthesis (when sync_class permits). See BRAIN page §3.4.