YAI

YAI is a governed runtime environment built around one native object: the case.

A case is not just a process group, a workspace, a container, or a policy tag. It is the execution object through which YAI binds runtime state, supervision, policy, legal materialization, evidence, graph lineage, and review. The system is trying to make governance part of execution itself, not a document layer added after the fact.

The shortest way to understand YAI is:

1. a user enters a governed YAI session
2. work happens inside cases and scopes
3. the supervisor observes acts and mediates them against qualified case context
4. the runtime emits records, evidence, outcomes, and graph state
5. legal, governance, graph, and higher surfaces consume those native objects

What YAI Is

YAI is an attempt to answer a systems question: what does an operating environment look like when execution is organized around governed objects instead of loose process supervision plus detached policy and compliance files.

Its core concepts are:

• case as the primary runtime anchor
• scope as the practical addressing surface for user, system, and nested work
• supervisor mediation as the canonical point where an observed act becomes a decision
• evidence, outcomes, and audit records as first-class runtime artifacts
• legal and governance materialization as native runtime context
• graph and state surfaces as explanations of what the system is doing and why

YAI is therefore not just a CLI. It is a runtime model with a CLI/TUI front door.

Operating Model

Today YAI runs above a host substrate such as Linux or macOS, but it tries to treat the host as carrier rather than as the primary semantic model. That is why the system talks in terms such as:

• root context
• user case
• case resolution snapshot
• supervisor mediation
• runtime carrier outcome
• review_required

These names are not cosmetic. They mark the intended ownership split between:

• what was observed
• what was decided
• what was applied
• what evidence and governance context justify the result

What You Can Inspect

In practical terms, YAI already exposes surfaces for:

• governed session entry and user binding
• case and scope identity
• process attachment and watch state
• supervisor mediation and carrier outcomes
• governance and legal materialization
• graph lineage and decision topology
• state and audit inspection

That is the right mental model for the project: a governed runtime with inspectable decision surfaces, not just a codebase full of helpers.

Install

YAI is currently source-first and developer-oriented. The normal installation path is to build the runtime tools locally.

Typical host requirements:

• make
• clang or gcc
• zsh
• ripgrep
• duckdb
• LMDB development/runtime support

Clone and build:

git clone git@github.com:yailabs/yai.git
cd yai
make yai-runtime-tools

This produces the runtime tools under build/bin and materializes the runtime filesystem under dist/rootfs.

First Boot

Start a governed session with:

./build/bin/yai start

Attach the CLI client to a YAI user explicitly with:

./build/bin/yai cli --user <username>

Once inside YAI, the first commands worth running are:

yai status
yai whoami
yai case status
yai watch 20
top 20
yai state db bootstrap-supervisor-views
yai state db supervisor-runtime 20
yai state db supervisor-processes 20
yai state db supervisor-watch 20
yai state db supervisor-carrier 20
yai graph summary user

If you want to inspect the legal and governance side:

yai legal materialize-db
yai legal materialize-case --scope finance.audit.v6
yai state governance case-surface 20
yai state legal case-resolution-snapshot 20
yai state legal policy-profile-bridge 20

How To Read YAI

The best short reading path is:

• Documentation/yai/YAI_initial_guide.md
• Documentation/yai/README.md
• Documentation/yai/YAI_OS_TOPOLOGY.md
• governance/README.md
• spec/README.md

That path gives you:

• the user-facing runtime model
• the topology and documentation plane
• the governance plane
• the formal schema and registry plane

Project Status

YAI is under active refoundation. The important thing is not whether every surface is already polished; it is that the ownership model is getting sharper: fewer ad hoc wrappers, more canonical runtime objects, and tighter linkage between execution, governance, and explanation.

Some areas are already meaningfully usable:

• session entry and user/case identity
• supervisor mediation
• runtime state and process mapping
• legal materialization
• graph and state inspection

Other areas still carry transitional residue. The direction is nevertheless clear: YAI is moving toward a system where runtime behavior, normative context, and explainability are part of the same object model.

Security And Governance

• SECURITY.md
• GOVERNANCE.md