ontoref is a protocol specification and tooling layer for structured self-knowledge in software projects. It provides schemas, Nushell automation, and Rust crates so that projects can describe what they are, record architectural decisions, track operational state, and execute formalized procedures — all as typed, queryable artifacts.

---

Axioms

Axiom	Meaning
Protocol, Not Runtime	Never a runtime dependency. Projects adopt the protocol; ontoref provides the schemas and modules to do so.
Self-Describing	Consumes its own protocol: .ontology/, adrs/, reflection/ in this repo ARE ontoref running against itself.
No Enforcement	ontoref defines contracts. There is no enforcement mechanism. Coherence is voluntary and emerges from justified adoption.
DAG-Formalized Knowledge	Concepts, tensions, decisions, state — encoded as DAGs. Enables transversal queries and impact analysis.

Layers

ontology/          Protocol specification — Nickel schemas for nodes, edges, ADRs, state, gates
adrs/              Architecture Decision Records — typed NCL with constraints and ontology checks
reflection/        Operational tooling — Nushell modules, DAG modes, forms, and schemas
crates/            Rust implementation — typed struct loaders and mode executors
.ontology/         Self-description — ontoref's own ontology, state, gate, and manifest

Crates

Crate	Purpose
ontoref-ontology	.ontology/ NCL → typed Rust structs: Node, Edge, Dimension, Gate, Membrane. Graph traversal, invariant queries. Zero deps.
ontoref-reflection	NCL DAG contract executor: ADR lifecycle, step dep resolution, config seal. stratum-graph + stratum-state required.
ontoref-daemon	HTTP UI (10 pages), actor registry, notification barrier, MCP (19 tools), search engine, SurrealDB, NCL export cache.

ontoref-daemon caches nickel export results (keyed by path + mtime), reducing full sync scans from ~2m42s to <30s. The daemon is always optional — every module falls back to direct subprocess when unavailable.

Daemon Capabilities

Unified Auth Model — all surfaces (CLI, UI, MCP) exchange a key for a UUID v4 session token via POST /sessions. Token lifetime: 30 days, O(1) lookup. Project keys carry role (admin|viewer) and label for audit trail. Daemon-level admin via ONTOREF_ADMIN_TOKEN_FILE. GET /sessions and DELETE /sessions/{id} for session visibility and revocation. Key rotation invalidates all sessions for the rotated project. CLI injects ONTOREF_TOKEN as Bearer automatically.

Q&A Knowledge Store — accumulated Q&A entries persist to reflection/qa.ncl (typed NCL, git-versioned). Not localStorage. Any actor — developer, agent, CI — reads the same store.

MCP Server — 19 tools over stdio and streamable-HTTP. Categories: nodes, ADRs, modes, backlog, Q&A, sessions, search, notifications. Representative subset:

Tool	What it does
ontoref_qa_list	List Q&A entries with optional filter
ontoref_qa_add	Append a new Q&A entry to reflection/qa.ncl
ontoref_action_list	List all quick actions from .ontoref/config.ncl
ontoref_action_add	Create a reflection mode + register it as a quick action
ontoref_backlog_list	List backlog items
ontoref_backlog_add	Add a backlog item
ontoref_describe	Describe project ontology and constraints
ontoref_sync_scan	Scan for ontology drift

Passive Drift Observation — background file watcher that detects divergence between Yang code artifacts and Yin ontology. Watches crates/, .ontology/, adrs/, reflection/modes/. After a 15s debounce runs sync scan + sync diff; emits an ontology_drift notification when MISSING/STALE/DRIFT/BROKEN items are found. Never applies changes — apply is always deliberate.

Quick Actions — runnable shortcuts over reflection modes, configured as quick_actions in .ontoref/config.ncl. Accessible from HTTP (/actions), CLI (ontoref), and MCP (ontoref_action_list/add).

Install

just install-daemon        # build + install binary, bootstrapper, CLI, UI assets, config skeleton
ontoref config-edit        # browser form → ~/.config/ontoref/config.ncl
ontoref-daemon-boot        # NCL pipe bootstrap: nickel export config.ncl | daemon --config-stdin
ontoref-daemon-boot --dry-run   # preview composed JSON without starting

Installed layout (~/.local/bin/):

Binary	Role
ontoref	Global CLI dispatcher — all reflection modes, ADR lifecycle, daemon control
ontoref-daemon	Bootstrapper (public entrypoint) — validates config via Nickel, pipes JSON to binary
ontoref-daemon.bin	Compiled Rust binary — never called directly

Global config at ~/.config/ontoref/config.ncl (type-checked Nickel). Global NATS stream topology at ~/.config/ontoref/streams.json. Project-local topology override via nats/streams.json + nats_events.streams_config in .ontoref/config.ncl.

Onboarding a project

cd /path/to/my-project
ontoref setup                          # idempotent; kind: Service by default
ontoref setup --kind Library           # Library | DevWorkspace | PublishedCrate | AgentResource | Mixed
ontoref setup --parent /path/to/fw     # implementation child: adds framework layer + browse mode
ontoref setup --gen-keys ["admin:dev" "viewer:ci"]   # bootstrap auth keys (no-op if keys already exist)

ontoref setup creates .ontoref/project.ncl, .ontoref/config.ncl (with logo auto-detection), .ontology/ scaffold, adrs/, reflection/modes/, backlog.ncl, qa.ncl, git hooks, and registers the project in ~/.config/ontoref/projects.ncl.

For existing projects that predate setup, the adoption mode is still available:

ontoref --actor developer adopt_ontoref

ONTOREF_PROJECT_ROOT is set by the consumer wrapper — one ontoref checkout serves multiple projects.

Prerequisites

• Nushell >= 0.110.0
• Nickel (for schema evaluation)
• Rust toolchain (for building crates)
• Just (for CI recipes)

To build ontoref-daemon and ontoref-reflection with NATS/SurrealDB support, the stratumiops repo must be checked out at ../../../stratumiops. Without it, build without default features:

cargo build -p ontoref-daemon --no-default-features
cargo build -p ontoref-ontology   # always standalone

Development

cargo check-all                              # check all targets + features
cargo test-all                               # run full test suite
just ci-lint                                 # clippy + TOML + Nickel + Markdown
just ci-full                                 # all CI checks
nu --ide-check 50 reflection/modules/<file>.nu  # validate a Nushell module
./ontoref --actor developer <mode>           # run a reflection mode

License

MIT OR Apache-2.0