FRAME
=====

FRAME is a universal runtime for structured systems. Everything it hosts is a
FRAME in a governed relationship graph. Clients project and submit Intents —
they do not own state.

Quick Start
-----------

* Report issues: https://github.com/frameprotocol/frame/issues
* Organization: https://github.com/frameprotocol
* Documentation: https://github.com/frameprotocol/docs
* Build and run: see Essential Documentation below
* Integrity check: ./tools/architecture-check.sh

Essential Documentation
-----------------------

All users should be familiar with:

* Identity and laws: docs/FRAME.md
* Ontology · Algebra · Physics · Runtime: docs/FRAME-ARCHITECTURE.md
* Legal transformations: docs/FRAME-ALGEBRA.md
* Platform operations: docs/FRAME-PLATFORM.md
* Package Contract: docs/FRAME-PACKAGE.md
* Conformance: docs/FRAME-CONFORMANCE.md

Normative documents are marked Status: Normative. Only those define FRAME.

Who Are You?
============

Find your role below:

* New FRAME Developer — Building on the substrate
* Package Author — Shipping .frame packages
* Client / UI Developer — Browser, desktop, phone, shell
* Runtime / Host Engineer — Persistence, authority, execution
* Security / Authority — Sessions, identity, trust, governance
* Connected Host / Mesh — Multi-host sync
* AI Integrator — Participants and packages (not Core model wiring)
* Operator — Install, boot, backup, recover
* Researcher — Studying the architecture
* AI Coding Assistant — Working in this repository


For Specific Users
==================

New FRAME Developer
-------------------

* Entry path: README → docs/FRAME.md
* Build host: cargo build --manifest-path frame_runtime_host/Cargo.toml
* Run: ./frame start
* Integrity: ./tools/architecture-check.sh

Package Author
--------------

Create things WITH FRAME, not inside Core:

* Package Contract: docs/FRAME-PACKAGE.md
* Built-in package layout: packages/
* RFCs: docs/rfc/

Client / UI Developer
---------------------

* Interaction model: docs/FRAME-INTERACTION.md
* Wire: docs/rfc/RFC-0002-CORE-WIRE-PROTOCOL.md
* Session: docs/rfc/RFC-0003-RUNTIME-TRANSPORT-SESSION.md
* Browser UI: ui/
* Client contract: frame.client.v1

Runtime / Host Engineer
-----------------------

* Architecture: docs/FRAME-ARCHITECTURE.md
* Platform ops: docs/FRAME-PLATFORM.md
* Host source: frame_runtime_host/
* Architecture freeze: .cursor/rules/architecture-freeze.mdc

Security / Authority
--------------------

Only governed mutation writes the Runtime Graph:

* Intent → Governance → Mutation
* Package trust and signatures: docs/FRAME-PACKAGE.md
* Conformance: docs/FRAME-CONFORMANCE.md

AI Integrator
-------------

Architectural rule:

  Model / provider → AI dApp / package → AiParticipant → governed Act → FRAME Core

Never:

  FRAME Core → OpenAI / Ollama / llama.cpp / model server

FRAME knows that an AI participant may exist. It does not know what a model is.
Live inference belongs in an admitted package (see sibling frame-ai-dapp).

Operator
--------

* ./frame --help
* Data dir: FRAME_DATA_DIR (default ~/.local/share/frame)
* Release layout: dist/frame/README-RUN.txt
* Package release: ./tools/package-release.sh

AI Coding Assistant
-------------------

CRITICAL: FRAME is frozen. Do not invent new Core nouns, mutation paths, or
parallel authorities.

* Architecture freeze: .cursor/rules/architecture-freeze.mdc
* Must pass: ./tools/architecture-check.sh
* Entry path: docs/FRAME.md → docs/FRAME-ARCHITECTURE.md → docs/FRAME-ALGEBRA.md


Build and Validate
==================

Requires: Rust (cargo), Node 18+, rg (ripgrep), Python 3.

::

    ./tools/architecture-check.sh
    cargo test --manifest-path frame_runtime_host/Cargo.toml --lib -- --test-threads=1
    (cd runtimes/frame_wire_ts && npm test && npm run verify)
    (cd ui && npm test)
    ./frame start


What FRAME Is Not
=================

FRAME is the substrate. Domain products (vehicles, weather stations, marketplaces,
hardware demos, and similar) are built WITH FRAME in other repositories.


Authority
=========

The Rust host Runtime Graph is the sole authority.

::

    Observe → Runtime Graph → Context → Perspective → Projection
      → Recommendation → Intent → Governance → Mutation
      → Event → History → Re-project

Clients do not own state.