On this page
Documentation Quickstart
How the source documentation is organized
The primary sources already exist in the repository and this wiki treats them as such, not duplicates:
| Document | Role |
|---|---|
README.md (repository root) | Executive overview: problem statement, 12 core principles, 12-layer architecture sketch, tech stack, event/workflow model summary. |
docs/DOCS.md | The authoritative topic map — every category/topic maps to a canonical file path or an explicit TBD. This is the single source of truth for “where is X specified?” |
| Synedrix OS - Consolidated Canonical Reference | Single-file synthesis of all OS canon, for a fast executive read. Per-topic files remain authoritative for edits. |
What this wiki covers
| Section | Answers |
|---|---|
| Architecture → Agent Runtime & Orchestration | How do n8n (orchestration) and LangGraph (agent runtime) divide responsibility? What is an agent, a workflow contract, an event, an outcome envelope, and how is tool access authorized? |
| Architecture → Governance and Controls | How does the Policy Guard Agent block finality work? How does the HITL Gateway Agent mediate approvals? What are L0–L5 autonomy levels, the six human control roles, and the three-layer tool authorization model? |
| Architecture → Governed Agent Accountability | ADR-028: the five execution invariants (explicit purpose, delegated authority, traceable evidence, honest uncertainty, conditional completion), the GADLC conformance profile, verification gates, and remediation lifecycle. |
| Architecture → Memory Fabric | What is the memory fabric? How do the eight memory tiers work together? What is the memory record envelope and its lifecycle? How does the memory control plane operate across os-agt-010, os-agt-011, and os-agt-012? |
| Architecture → Observability | What metric families does Layer 10 produce? How do Langfuse, QuestDB, PostHog, and the Grafana LGTM Stack cover LLM engineering, temporal metrics, behavioral analytics, and operational monitoring? |
| Operations → Tech Stack & Deployment | What are the 12 platform components? What are the three deployment modes (cloud/hybrid/air-gapped)? How does MCP/A2A interoperability work? |
| Operations → Tenancy, Identity, and Metering | How does the pooled control plane / per-tenant data plane model work? What are principals, organizations, roles, authentication, and approval chains? How does the governed goal serve as the metering unit? |
Where to start depending on your goal
- Understand the system as a whole → read Architecture → Platform Overview, then the canonical master (Synedrix OS - Consolidated Canonical Reference).
- Understand governance models and controls → read Architecture → Governance and Controls.
- Understand how agents are held accountable during execution → read Architecture → Governed Agent Accountability.
- Understand observability and tracing → read Architecture → Observability.
- Understand how an agent actually executes (n8n vs. LangGraph) → read Architecture → Agent Runtime & Orchestration.
- Understand infrastructure/deployment posture → read Operations → Tech Stack & Deployment.
- Understand tenancy, identity, or metering → read Operations → Tenancy, Identity, and Metering.
Invariants every change must respect
- Synedrix OS remains domain-agnostic at its core — no domain logic is promoted to the OS layer.
- Domain packs cannot bypass OS governance or observability layers.
- No agent writes to production systems without policy-aware orchestration visibility.
- Every workflow is observable end-to-end; every agent has explicit authority boundaries and an escalation path.
- No MCP or A2A protocol interaction bypasses governance.
- The Audit & Lineage Agent (
os-agt-008) is strictly read-only and must never appear in any agent’stools_allowed. - The agent registry is append-only at runtime.
- Only the Memory Curator (
os-agt-010) may commit durable memory; every other agent proposes. Memory recall is an authorized tool call, never ambient context. - No memory record crosses a tier boundary without a governed
memory.record.promotedevent; erasure leaves a tombstone.
Future agents editing this repository: never write documentation code assuming a running system exists. Everything here is a specification artifact. When asked to “implement” something, check whether the request means (a) authoring/updating a spec document in this repo, or (b) building the actual runtime in a separate implementation repository — this repo only supports the former.