Cut the Fog.
Governed operational systems for accountable action.
YAI is a governed case-native runtime.
It is designed for environments where operators, software, models, providers, and agents can all contribute to work, but action still has to remain attached to context, authority, evidence, durable state, and reviewable outcomes.
YAI is not a chat wrapper, not a ticket board, and not a loose collection of automation hooks. It is a system for governed action: work enters with case meaning, passes through decision posture, executes through bounded runtime surfaces, and leaves behind inspectable facts.
The case is the operational boundary. Control decides whether action is fit to proceed. Runtime carries out the work. State preserves what became true. Lineage and analytics help reuse what was learned without turning derived views into authority.
Organizations do not usually struggle to generate output. They struggle to keep output attached to responsibility.
YAI exists for environments where teams need:
- AI activity tied to business context instead of disconnected prompts
- accountable execution rather than silent side effects
- durable records instead of fragile session memory
- reviewable operational history instead of opaque agent behavior
- reusable insight without confusing recall, projections, or analytics with primary truth
YAI is built to keep the full operating chain explicit and separated by plane:
identity -> case -> governance -> control -> orchestration
-> agents / skills / providers / models
-> runtime -> events / records / state records
-> state -> knowledge / lineage -> analytics
In the repository today, that stack is expressed like this:
- Identity in
identity/defines principal, authorization, machine posture, and entitlement vocabulary for the runtime boundary. - Case in
case/localizes the work boundary through identity, continuity, structure, topology, progression, qualification, chronology, and surface nuclei. - Governance in
governance/qualifies posture and resolves declarative control inputs into runtime decisions, effects, and evidence linkage. - Control in
control/is the canonical control-plane root for mediation, observation, enforcement, registry, subjects, and evidence capture. - Orchestration in
orchestration/coordinates planning, routing, handoff, recovery, and state; the separateflow/root remains a graph/flow surface that orchestration projects through. - Agents, skills, providers, and models live in
agents/,skills/,providers/, andmodels/as the operating capability planes that compose, route, bind, and execute work under governance and control. - Runtime in
runtime/carries execution through boundary adapters, carriers, connections, lifecycle, machine, observation, sessions, and operator surfaces. - Public contracts are exposed in
include/events/,include/records/, andinclude/state_records/as the current event, record, and State Records contract spine. - State in
state/owns persisted operational state throughstate/records/and backend substrates throughstate/substrate/. - Knowledge in
knowledge/owns ingest, context, retrieval, inference, memory, query, topology, and lineage-related surfaces. In the current repo, lineage is still surfaced inside the knowledge plane rather than as a separate root. - Analytics in
analytics/remains the observation/inspection side of the system: useful for derived understanding, but not the primary truth surface.
Around that operating chain, specs/ holds canonical spec surfaces, tools/ supports repository and runtime operations, tests/ carries harnesses, packaging/ carries distribution layouts, and Documentation/ explains the system.
The architectural point is deliberate: YAI separates qualification, control, execution, durable state, lineage, and observation so that no derived surface quietly becomes authority.
This repository also contains development and ops bootstrap surfaces such as
make yai, make info, make install, and make install-service.
Those surfaces are dev-wrapper surfaces. They can build, inspect, install, or
bootstrap local runtime artifacts, but they are not the canonical domain command
model and they do not own auth, case selection, operator context, readiness, or
operational authorization.
The installed yai CLI remains the canonical user-facing command surface.
Makefile targets and service bootstrap assets are repository and host-ops
surfaces around the runtime, not replacements for yai auth ...,
yai case ..., yai runtime status, or future runtime-control commands.
V19 adds one more boundary: future controlPlan semantics are declarative plan
or projection only. They are not proof that runtime start/stop/restart executed,
and they do not turn Makefile or service bootstrap surfaces into canonical
runtime control.
At a system level, YAI brings together a few distinct responsibilities:
- Case keeps work tied to a real operational boundary.
- Control governs whether action should proceed and under what posture.
- Runtime carries work into executable surfaces.
- State preserves accepted facts, records, and outcomes.
- Lineage keeps connection and traceability across meaning and reuse.
- Analytics provides observation and derived understanding without becoming truth.
This repository is the core YAI runtime/source tree. It contains the runtime, governance, case, state, knowledge, analytics, and public contract surfaces that make that model concrete. It is under active development, with the newer Event, Record, and State Records contracts now forming the stabilization spine.
If you want the fast path into the system, start here:
- Documentation/product/overview.md for the external system overview
- Documentation/architecture/controlled-act-lifecycle.md for the governed action spine
- Documentation/system/README.md for system-facing architecture and topology docs
- Documentation/operator/README.md for operator and deployment material
- Documentation/reference/README.md for contracts, commands, and reference surfaces
Canonical operator flow for the CLI:
which yai
yai ...If you are looking at the current contract spine specifically, begin with:
- include/events/event_envelope.h
- include/records/record_envelope.h
- include/state_records/state_records_api.h
YAI is the YAI Community Source Tree.
It is available for learning, evaluation, development, research, prototyping, and other non-production use. Production, organizational, persistent, collaborative, customer-affecting, or business-critical use requires a commercial license.
Use these as the licensing source of truth:
Repository governance and contribution rules live here: