KB

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 PRD §9.12 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 PRD §11.2 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 vn-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