ZQK Core Documentation Index
Welcome to the canonical documentation for ZQK Core, the Cellular Knowledge Operating System for autonomous AI agent swarms and human engineering teams.
🚀 Onboarding & First-Run
| Guide | Description |
|---|---|
| Community First-Run | Complete first-run walkthrough: build, initialize, agent-onboard, MCP setup, and DAG discovery. |
| Quickstart & MCP | Fast onboarding cheatsheet and Model Context Protocol (MCP) server configuration. |
| AI Agent Onboarding | Mandatory directives, workspace seating, and continuous autonomous loop discipline for AI agents. |
| First-Run Object Tutorial | Step-by-step tutorial: creating, querying, and updating kernel objects (question, task, plan). |
| Edge & Headless Mode | Headless daemon startup, edge node runtime, and CLI-only autonomous operation. |
| Getting Started Pointer | High-level index and roadmap pointer for new contributors. |
🏛️ Core Architecture & Foundation
| Specification | Description |
|---|---|
| Architecture Overview | Core system architecture, Knowledge Kernel data plane, and daemon topology. |
| Lifecycle State Machines | Visual finite state machines, check-valves, roles, and cryptographic quality gates. |
| Ambient Signal Action Rubric | Anti-thrashing precedence hierarchy (P0–P5) and deterministic CLI action gates for agents. |
| Modular Pack Composition | Pack manifests (pack.yaml), builder codegen (bldr_cli_cmd_v1), and composition root. |
| Cellular Membrane Mode B | Privileged writer configuration, membrane isolation, and security guardrails. |
| CLI Command Taxonomy | Canonical taxonomy standards, verb-noun structures, and AST verification rules. |
| Tiered Storage Lifecycle | Storage compaction, subtree flattening, and historical capsule archival. |
| Tray Cryptographic Security | HMAC envelopes, payload attestation, and secure indirect command execution. |
| Polyglot AST Search Roadmap | In-process Tree-sitter architecture, cross-language symbol taxonomy, and token budgeting for zqk grep. |
| Pack Composition Root | Architecture, manifests, and CLI tool generation contracts. |
📜 Declarative Languages & Specifications
| Technical Specification | Description |
|---|---|
| ZPARQL Graph Traversal Grammar | Declarative graph query language for pattern matching and relationship traversal. |
| ZPARQL Query Planner | Index-accelerated query planner, cycle-safe traversal engine, and AST optimizer. |
| ZPARQL Streaming & Result Envelopes | Portable result envelopes, reactive streaming, and backpressure protocols. |
| ZQL Declarative Mutation Grammar | Declarative ACID mutation language grammar, variable resolution, and AST. |
| ZQL Preflight Validation | In-memory preflight validation, constraint checking, and diagnostic receipts. |
| ZQL ACID Transaction Execution | Staged transaction isolation, atomic commits, rollback journals, and CAS writes. |
| Interactive Object Inspector Spec | Interactive console specification, TUI navigation, and live Policy Studio. |
📖 Reference Manuals & Guides
| Reference / Guide | Description |
|---|---|
| Knowledge Kernel Object Model & Usage Guide | Comprehensive taxonomy across all 14 ontological domains and packs (70+ kinds), standard envelopes, VDS cascade, and copy-pasteable CLI recipes. |
| Knowledge Management, Vocabularies & Semantic Recall | Operational glossaries, lens taxonomies, composable libraries, docman CAS verification, and on-demand recall protocols. |
| CLI Reference Manual | Comprehensive CLI command flags, environment variables, and exit codes. |
| ZPARQL Query Language Manual | Developer manual and syntax guide for querying the Knowledge Kernel graph. |
| ZQL Declarative Mutations Manual | Developer manual for crafting declarative atomic mutations and batch updates. |
| Object Inspector & Policy Studio | Reference manual for the interactive object inspector, keybindings, and policy testing. |
| Mission Control UI & Diagnostics Visual Guide | Complete visual walkthrough of all 8 TUI tabs, Web Studio timeline/DAG, and test dashboards with ASCII captures. |
| ZQL & ZPARQL Agent Guide | Field guide for AI agents executing queries, mutating graph state, and handling errors. |
🚨 Operational Incident Runbooks
| Runbook | Trigger & Incident Triage |
|---|---|
| Incident Runbooks Overview | Directory of operational incident runbooks and triage procedures. |
| RB-CAS-001: CAS Corruption Recovery | Resolving Content-Addressed Storage hash mismatches and quarantine exhaustion. |
| RB-LCK-001: Lock Contention & Deadlocks | Diagnosing concurrency lock contention, stale lock cleanup, and deadlock breaking. |
| RB-SCH-001: Scheduler Daemon Triage | Recovering from scheduler daemon exit cascades, stuck recurring jobs, and restarts. |
| RB-WAL-001: WAL Compaction Failures | Triage and repair for Write-Ahead Log compaction corruption and disk saturation. |
🛠️ How-To & Tutorials
| Guide / Tutorial | Description |
|---|---|
| How-To Guides Overview | Practical, goal-oriented guides for common administrative and engineering tasks. |
| Inspect & Validate Objects | Inspecting objects via dual TUI/JSON projections and running live policy dry-runs. |
| Scheduler & Maintenance Jobs | Configuring background daemons, cron intervals, and kernel self-healing jobs. |
| Tutorials Overview | Learning-oriented walkthroughs exploring kernel capabilities step-by-step. |
| Object Inspector Tutorial | Hands-on walkthrough: navigating the graph, authoring policies, and verifying constraints. |
| Interactive Demonstrations & Visual Showcase | Visual showcase with authentic terminal SVG recordings and command walk-throughs. |
🔧 Maintenance, Development & Evaluation
| Document | Description |
|---|---|
| Development Overview | Contributor conventions, build instructions, and local testing workflows. |
| Policy Governance & Durability | Durability tiers, AST linters, and cryptographically verified policy packs. |
| Quality & Verification Gates | Definition of Done (DoD), Verification Done-Gates (VDS), and chunk evaluation. |
| Codebase Evaluation Framework (CEF) | Multi-agent evaluation framework, 52 evaluation lens rubrics, and Diamond Scale grading. |
| System Explanation & Philosophy | Architectural philosophy: why ZQK is designed as a Cellular Knowledge Operating System. |
🤖 Agent Operating Directives & Protocols
| Directive / Guide | Description |
|---|---|
| AI Agent Onboarding & Operating Protocol | Directives, MCP integration, persona seating, and continuous autonomous loop discipline. |
| Ambient Signal Action Rubric | Anti-thrashing precedence hierarchy (P0–P5) and deterministic CLI action gates for agents. |
| First-Run Quality & Verification Gates | Definition of Done (DoD), Verification Done-Gates (VDS), and chunk evaluation. |
| ZQL & ZPARQL Agent Guide | Field guide for AI agents executing queries, mutating graph state, and handling errors. |
📦 Kernel Subsystems & Package Architecture
| Subsystem / Package | Architectural Focus |
|---|---|
| Storage Subsystem | Unified storage abstraction, pluggable file/graph providers, and change journals. |
| Graph Backend | MemGraph P2P provider, connection pooling, and Cypher query execution. |
| MCP Server Architecture | Model Context Protocol engine, tool dispatch, and client adapters. |
| Concurrency & Synchronization | Lock contention management, timeouts, and goroutine leak prevention. |
| Pipeline Execution Engine | Step-based mutation pipelines, stage checkpoints, and rollback handlers. |
| Telemetry & Diagnostics | Structured metrics, performance telemetry, and event streaming. |
| Bootstrap Subsystem | Embedded tarball packaging, unpack logic, and zero-friction initialization. |
| CLI Kernel Architecture | Command routing, context profiles, and fail-closed CLI execution contracts. |
| In-Process Code Search Engine | Pure-Go trigram inverted indexer, AST symbol search, and LLM token-budgeted output (zqk grep). |
| Screen Capture & Terminal Automation | OS-level window/region capture, interactive terminal timeline recording, and visual verification. |
| Seat Worker Subsystem | Persistent background agent seat supervisor for launchd (macOS) and systemd (Linux). |
| Cellular Specialization Tiers | Biological node roles (neuron, muscle, heart, lung) and shielded simulation environments. |
| Positional Binary Storage | High-density binary object serialization using stable Field ID registries. |
⚖️ Open Core Governance
| Document | Description |
|---|---|
| Contributing Guide | Developer Certificate of Origin (DCO), pull request standards, and code review rules. |
| Project Governance | Open-core boundaries, RFC process, technical steering, and maintainer roles. |
| Security Policy | Vulnerability disclosure policy, response SLAs, and security advisories. |
| Code of Conduct | Community standards and Contributor Covenant guidelines. |