Architecture & extension boundaries

The system boundary

KOS organizes Markdown knowledge, instruction routing and project context. An editor presents the files. An AI provider applies its own instruction-loading and execution behavior. Installer and package tools manage their own state and lifecycle.

Keep these responsibilities separate. A filesystem integration is not automatically a trusted context source or permission to execute external actions.

Contracts worth preserving

Boundary	Preserve
Instruction routing	The selected distribution’s root router and task-relevant context policy
Project context	Durable approved facts, current handoff, unresolved proposals and access classification
Installer authority	Version identity, receipts, journals and recovery semantics
Role folders	Configured locations, not hardcoded assumptions from a private vault
Package lifecycle	Manifest compatibility, reviewed permissions and explicit state transitions

Build against an exact release

Pin your target package and Core contract. Inspect its actual schemas and scripts before implementing adapters, Power-Ups or integrations. The Community repository and tagged package guide are the public implementation references for Starter Kit 1.2.0.

For Pro, use the source and contract materials supplied under its applicable License. The Community command surface is not a substitute for Pro’s installed scripts.

Validate the integration

Use a disposable vault and synthetic fixtures. Verify narrow file access, explicit approval for mutations, compatibility checks, preserved user modifications, interrupted-operation behavior and recovery. Test a fresh session to confirm that generated context can actually be consumed.

Documentation scope

This page explains the verified boundaries. It does not invent a universal adapter SDK, hosted API, marketplace or unqualified package template. A step-by-step extension guide needs a specific release contract and an exercised example before publication.