Skip to content

AncientOS Knowledge Surfaces

Phase 1 OKF knowledge surfaces live in knowledge/.

They are documentation and discoverability artifacts only. They do not modify runtime behavior, routing, governance decisions, execution paths, approvals, persistence models, database schemas, MCP behavior, transport behavior, or application logic.

Each registered component has:

  • identity.md
  • capabilities.md
  • runbooks.md
  • limitations.md

Normalized Metadata

Every component knowledge document uses the same machine-readable front matter:

---
component: <component_slug>
document_type: <identity|capabilities|runbooks|limitations>
status: <active|partial|planned|deprecated|unknown>
maturity: <production|partial|planned|experimental|unknown>
authority: documentation_only
execution_authority: false
mutation_authority: false
approval_authority: false
approval_required_for_execution: <true|false|unknown>
transport_neutral: true
generated: false
last_reviewed: 2026-06-15
---

Allowed status values are active, partial, planned, deprecated, and unknown. Allowed maturity values are production, partial, planned, experimental, and unknown.

Authority fields are descriptive only. They let Luna and future Knowledge Capsules reason about governance posture, but they never grant execution, mutation, approval, tool, routing, persistence, MCP, or transport authority. The enforced authority value is always documentation_only, and all authority booleans remain fail-closed.

The top-level knowledge/component_catalog.md is the Phase 1 registry. Tests validate that every cataloged component exposes the required files and that each file carries component and document-type front matter.

Luna Read-Only Discovery

Luna can inspect the repository knowledge surfaces through app/knowledge/discovery.py. The discovery layer reads only:

  • knowledge/README.md
  • knowledge/component_catalog.md
  • knowledge/<component>/knowledge/identity.md
  • knowledge/<component>/knowledge/capabilities.md
  • knowledge/<component>/knowledge/runbooks.md
  • knowledge/<component>/knowledge/limitations.md

The service resolves every path under the repository knowledge/ directory, rejects path traversal, parses catalog entries into structured records, and returns explicit read-only authority flags and normalized metadata. It does not write files, execute commands, call the network, update databases, index LifeVault, mutate MCP state, or grant approvals.

Transport-neutral runtime access is exposed through the existing governed architecture-inspection rendering path. Questions such as "What components are documented?", "What does Oracle do?", "What are Prophet's limitations?", and "Which components require governance approval?" are answered from the knowledge surface files.

Read-Only Query Rendering

app/knowledge/query.py and app/knowledge/rendering.py provide the read-only query layer used by Luna's architecture/knowledge inspection path.

The query layer consumes discovery records and normalized metadata. It can answer deterministic structured questions such as:

  • which components are documented
  • which components are partial, planned, deprecated, experimental, or unknown
  • which components require approval for execution
  • which components explicitly have no execution authority
  • what a component does
  • a component's capabilities, limitations, runbooks, and knowledge file paths
  • which component documents mention terms such as MCP, LifeVault, Zeus, Lich, Prophet, or Oracle

Every rendered answer includes source paths so a human or agent can inspect the underlying knowledge file. Source paths are evidence references, not authority grants. The renderer returns explicit fail-closed flags for execution, mutation, approval, tool, MCP execution, persistence-write, and routing authority.

This is not a semantic search system, permission system, planner, MCP bridge, LifeVault ingestion path, or execution path. It is a deterministic read-only view over repository documentation, prepared for future Knowledge Capsules after separate governance review.

Knowledge Surface Review

app/knowledge/review.py audits the knowledge surfaces for documentation quality. It reads the same discovery records and reports findings without modifying files or changing authority.

Review categories include:

  • unknown information markers such as Unknown - requires maintainer review and unknown
  • planned, partial, experimental, deprecated, or unknown metadata posture
  • thin documentation, using documented thresholds of 350 non-front-matter characters and four second-level sections
  • future-behavior mentions such as future, planned, roadmap, not implemented, stub, and placeholder
  • metadata consistency issues
  • authority safety issues

Authority safety verification is report-only. Any deviation from authority: documentation_only, execution_authority: false, mutation_authority: false, or approval_authority: false is reported as a high-priority finding. The review system does not repair metadata, grant permissions, create approvals, call MCP tools, write LifeVault records, or alter routing.

Recommendations are evidence-based. Examples include maintainer review for unknown markers, sparse runbook/limitations documentation, future behavior mentions in active components, and status mismatch between catalog and document metadata.

Luna can render review reports through the same read-only architecture/knowledge inspection path for questions such as "Show me knowledge quality issues", "Which docs are incomplete?", and "Are any authority fields unsafe?" This helps decide whether the knowledge layer is ready to become a future Knowledge Capsule foundation.

Visibility by default does not imply operational capability. Documentation visibility remains separate from Lich approval, Zeus evidence, Roshan validation, Underlord escalation, LifeVault memory authority, MCP execution, and all mutation paths.

These surfaces are prepared for later generated documentation, Knowledge Capsules, MCP resource export, formal OKF export, and LifeVault ingestion. Those future capabilities are not implemented in Phase 1.

Knowledge Capsule Registry

Phase 2A adds the initial read-only Knowledge Capsule Registry in app/knowledge_capsules/.

Capsules are deterministic projections from knowledge/; they are not a new source of truth. The registry consumes the existing discovery and review APIs, loads the same component catalog and component knowledge files, and emits structured capsule records for components that pass eligibility checks.

Each capsule includes:

  • component slug
  • status and maturity from source metadata
  • purpose from the identity surface
  • capabilities from the capabilities surface
  • limitations from the limitations surface
  • dependencies from documented inputs, evidence, and configuration requirements
  • governance summary from source metadata and governance restriction sections
  • approval-required metadata
  • transport-neutral metadata
  • source paths

Capsule eligibility is fail-closed. A component is excluded if any required knowledge document fails metadata validation, authority validation fails, status is unknown, maturity is unknown, approval_required_for_execution is unknown, or an unresolved review blocker exists. Phase 2A treats metadata issues, authority issues, and unknown-information findings as capsule-blocking review evidence.

Exclusions are explicit records with source paths and evidence-backed reasons. Underlord, Nyx, and Kunkka are excluded in this phase because their current knowledge metadata has approval_required_for_execution: unknown and their knowledge review contains unknown-information findings. They can become eligible only after maintainers resolve that uncertainty in the authoritative knowledge surfaces and review output.

The registry is descriptive only. It does not execute commands, modify files, write databases, write LifeVault, call MCP execution paths, create approvals, alter routing, or change governance decisions. Every registry, capsule, and exclusion record carries explicit fail-closed authority flags for execution, mutation, approval, tools, routing, persistence writes, and MCP execution.

Luna can inspect capsule information through the existing transport-neutral architecture/knowledge inspection path. Supported read-only questions include "Show me registered capsules", "Which components are capsule eligible?", "Why is Nyx capsule excluded?", "Show me the Prophet capsule", and "Show me the Oracle capsule".

Future work may add generated capsule exports or formal bundle formats. Those exports must remain projections from knowledge/ unless a separate governed change designates another authority.

Capsule Registry Health Reports

Phase 2B adds read-only capsule health reporting in app/knowledge_capsules/review.py.

The health report observes the generated Capsule Registry and validates that it remains traceable, eligible, and authority-free. It does not repair capsules, modify knowledge files, update metadata, create approvals, write persistence, write LifeVault records, call MCP execution paths, alter routing, or change governance behavior.

Health reports include:

  • registry summary counts for total, eligible, and excluded capsules
  • excluded components with evidence-backed exclusion reasons and source paths
  • authority safety findings for any capsule whose execution, mutation, or approval authority flags are not fail-closed
  • metadata consistency findings for status, maturity, approval_required_for_execution, and transport_neutral
  • source traceability findings when capsule source references are missing
  • eligibility drift findings for capsules that would no longer qualify under the current eligibility rules
  • inherited knowledge quality signals from app/knowledge/review.py, including unknown markers, planned components, partial components, future behavior mentions, sparse documents, and maintainer recommendations
  • deterministic maintainer recommendations based on the findings

Authority issues are critical report findings only. The review system never corrects them automatically. Metadata issues, traceability issues, and eligibility drift are also report-only. Knowledge quality signals are informational and do not become authority findings by themselves.

Traceability is verified by checking that each registered capsule has source paths and that those paths still resolve to knowledge files. This keeps capsules anchored to knowledge/ rather than becoming independent claims.

Luna can inspect capsule health through the same transport-neutral architecture/knowledge inspection path. Supported read-only questions include "Show capsule health", "Are there any unsafe capsules?", "Which capsules have review concerns?", "Would any capsule fail eligibility today?", "Which capsules are excluded?", and "Why is a component excluded?".

The relationship remains:

Knowledge Surface
      ↓
Knowledge Capsule
      ↓
Capsule Review

Each layer is descriptive and read-only. Visibility remains separate from execution permission, Lich approval, Zeus evidence, Roshan validation, Underlord escalation, LifeVault memory authority, MCP execution, persistence, routing, and governance authority.