README.md

Rey Documentation

This directory contains Rey's foundational contracts, implementation bearings, and current decision plane. Start with the project scope and constitution, then follow the subject document for the plane being changed. The documents describe both implemented behavior and target boundaries; each document must say which is which.

Start Here

Document	Purpose
Project README	Product landmark, installation, first bearing, runtime loop, admission grammar, and foundational bearings.
Constitution	Durable values and invariants that outrank architecture, plans, and implementation details.
Contributor Instructions	Required reading order, working loop, verification expectations, and repository conventions.
Architecture	System ownership, planes, data flow, crate boundaries, security boundaries, and current implementation posture.
Glossary	Canonical vocabulary and the semantic distinctions that other documents rely on.
CLI	Agent-facing command philosophy, HEAD → INDEX → WORKING revision loops, command groups, formats, streams, colors, and exit behavior.

Runtime And Evidence

Document	Purpose
Environment	Process-owned discovery, reasoning maps, providers, capability snapshots, environment admission history, trust, and limits.
Mining	Relational and source mining families, request/result lineage, native artifacts, visualization, and provider boundaries.
Workloads	The public unit of computation: workspace packages, graphs, scenarios, qualification, admission, execution, retained results, and exact scenario/delta inspection.
Runtime	Deterministic transition state, nested campaigns, reasoning surfaces, stop guards, and semantic convergence.
Scheduling	Supervised schedules, semantic invalidations, controls, and retention.
Frontier	Unresolved work, directional progress, readiness, deterministic scheduling, and workload attention placement.
Diffs	Authoritative typed relational, text, and structural deltas, direction, normalization, invalidation, and portable projections.
Proofs	Claims, evidence manifests, qualification, certificates, completeness, staleness, verification, and retention profiles.

Context And Collaboration

Document	Purpose
Explorer	First principles and the globe → map → terrain fidelity standard for the evidence-bound spatial engine.
Locators	Canonical candidate addresses, bounded resolution outcomes, and the distinction between locating and reading.
Git	Repository identity, refs, commits, semantic index state, polling cursors, ref movement, and workload activation.
Journal	Retained human/agent synthesis, typed notebook blocks, exact browser addresses, authored opportunities, separately admitted read-only query evidence, and deliberately narrow authority.
Observations	Immutable collaboration statements, exact evidence/source bindings, Channel-admission edges, retained partial broadcast outcomes, resolution/supersession, and the bounded catch-up frontier.
Conversations	Bounded workspace-local sessions and append-only transcripts, declared participants/writers, ordering, retention, availability, and effect boundaries.

Research Context

Document	Purpose
Research References	Versioned external research summaries, mappings to Rey, incorporation candidates, non-fit boundaries, and evidence posture; references are design inputs rather than accepted decisions.

Interfaces And Delivery

Document	Purpose
Interfaces	High-level ownership map across CLI, API, browser, evidence projections, provider/policy authority, identity, errors, and persistence.
Agent HTTP API	Axum server model, API-root discovery, Swagger/OpenAPI, versioned routes, transport, writes, exposure, and typed errors.
@rey/explorer technical guide	React Three Fiber package boundary, shared projection contract, globe and terrain pipelines, renderer lifecycle, limits, APIs, and tests.
Development	Pinned Nix/Rust/TypeScript environment, root just tasks, build outputs, dependency updates, and qualification commands.
Releases	GitHub Actions quality gates, cargo-dist artifact planning, version tags, release permissions, and operator procedure.
Roadmap	Delivery sequence from local environment evidence through workloads, topography, admitted mutation, and policy.
Current Decision Plane	Accepted structural choices grouped by ownership plane, with current implementation posture and authoritative contract links.
Current Plans	Current executable slices, dependency order, completion criteria, and human verification paths.

How The Documents Relate

Use Architecture to decide ownership, Interfaces to find the responsible surface, CLI for the agent contract, API for HTTP, and the subject document to define semantic behavior. The current decision plane summarizes accepted structure; plans track only bounded current and logically queued work. Superseded rationale and completed delivery history remain in Git. When a higher-level decision changes a lower-level description, update the stale document in the same change.