feat/rmg core bootstrap

.gitignore

@@ -2,6 +2,7 @@
 node_modules
 dist
 coverage
+target
 
 # Editor cruft
 .DS_Store

AGENTS.md

@@ -3,25 +3,26 @@
 Welcome to the **Echo** project. This file captures expectations for any LLM agent (and future-human collaborator) who touches the repo.
 
 ## Core Principles
-- **Honor the Vision**: Echo is a deterministic, multiverse-aware ECS. Consult `docs/echo/architecture-outline.md` before touching runtime code.
-- **Document Ruthlessly**: Every meaningful design choice should land in `docs/echo/` (spec, diagrams, memorials) or a Neo4j journal entry tagged `Echo`.
+- **Honor the Vision**: Echo is a deterministic, multiverse-aware ECS. Consult `docs/architecture-outline.md` before touching runtime code.
+- **Document Ruthlessly**: Every meaningful design choice should land in `docs/` (specs, diagrams, memorials) or a Neo4j journal entry tagged `Echo`.
+- **Docstrings Aren't Optional**: Public APIs across crates (`rmg-core`, `rmg-ffi`, `rmg-wasm`, etc.) must carry rustdoc comments that explain intent, invariants, and usage. Treat missing docs as a failing test.
 - **Determinism First**: Avoid introducing sources of nondeterminism without a mitigation plan.
 - **Temporal Mindset**: Think in timelines—branching, merging, entropy budgets. Feature work should map to Chronos/Kairos/Aion axes where appropriate.
 
 ## Shared Memory (Neo4j)
 We use the agent-collab Neo4j instance as a temporal journal.
 
-Scripts live in `/Users/james/git/agent-collab/scripts/neo4j-msg.js`.
+Scripts live in `<agent-collab checkout>/scripts/neo4j-msg.js`.
 
 ### Setup
 ```bash
 # Register yourself once. Choose a display name that identifies the agent.
-node /Users/james/git/agent-collab/scripts/neo4j-msg.js agent-init "Echo Codex"
+node path/to/agent-collab/scripts/neo4j-msg.js agent-init "Echo Codex"
 ```
 
 ### Writing a Journal Entry
 ```bash
-node /Users/james/git/agent-collab/scripts/neo4j-msg.js msg-send \
+node path/to/agent-collab/scripts/neo4j-msg.js msg-send \
   --from "Echo Codex" \
   --to "Echo Archive" \
   --text "[Echo] short summary of what you changed or decided." \
@@ -35,10 +36,11 @@ Guidelines:
 - Prefix the message with `[Echo]` so the tag survives future searches.
 - Summarise intent, work done, and next steps for future agents.
 - Use the thread `echo-devlog` unless a more specific thread already exists.
+- **Cadence:** Log when you start work (intent), when you hit a major milestone or decision, when you reference external sources (paths, specs), and when you finish a session (outcome + next steps). Treat Neo4j as the authoritative timeline.
 
 ### Reading Past Entries
 ```bash
-node /Users/james/git/agent-collab/scripts/neo4j-msg.js messages \
+node path/to/agent-collab/scripts/neo4j-msg.js messages \
   --thread "echo-devlog" \
   --limit 20
 ```
@@ -48,14 +50,22 @@ Use `messages-search --text "Echo"` for ad-hoc queries.
 ## Repository Layout
 - `packages/echo-core`: Runtime core (ECS, scheduler, Codex’s Baby, timelines).
 - `apps/playground`: Vite sandbox and inspector (future).
-- `docs/echo`: Specs, diagrams, memorials.
+- `docs/`: Specs, diagrams, memorials.
 - `docs/legacy`: Preserved artifacts from the Caverns era.
 
 ## Working Agreement
 - Keep `main` pristine. Feature work belongs on branches named `echo/<feature>` or `timeline/<experiment>`.
 - Tests and benchmarks are mandatory for runtime changes once the harness exists.
 - Update the Neo4j log before you down tools, even if the work is incomplete.
 - Respect determinism: preferably no random seeds without going through the Echo PRNG.
+- Run `cargo clippy --all-targets -- -D missing_docs` and `cargo test` before every PR; CI will expect a zero-warning, fully documented surface.
+
+## Git Real
+1. **NEVER** use `--force` with any git command. If you think you need it, stop and ask the human for help.
+2. **NEVER** use rebase. Embrace messy distributed history; plain merges capture the truth, rebases rewrite it.
+3. **NEVER** amend a commit. Make a new commit instead of erasing recorded history.
+
+In short: no one cares about a tidy commit graph, but everyone cares if you rewrite commits on origin.
 
 ## Contact Threads
 - Neo4j Thread `echo-devlog`: Daily journal, decisions, blockers.

CODEOWNERS

@@ -2,5 +2,5 @@
 # Reference: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 
 *       @flyingrobots
-/docs/echo/ @flyingrobots
+/docs/ @flyingrobots
 /packages/echo-core/ @flyingrobots

CONTRIBUTING.md

@@ -19,8 +19,8 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize:
 - **Temporal Tooling**: features support branching timelines and merges.
 
 ## Getting Started
-1. Clone the repo and run `pnpm install`.
-2. Read `docs/echo/architecture-outline.md` and `docs/echo/execution-plan.md`.
+1. Clone the repo and run `cargo check` to ensure the Rust workspace builds.
+2. Read `docs/architecture-outline.md` and `docs/execution-plan.md`.
 3. Register yourself in Neo4j via `AGENTS.md` instructions and note your display handle.
 
 ## Branching & Workflow
@@ -30,16 +30,16 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize:
 
 ## Testing Expectations
 - Write tests before or alongside code changes.
-- `pnpm test` must pass locally before PR submission.
-- Add Vitest coverage for new logic; integration tests will live under `apps/playground` when ready.
+- `cargo test` must pass locally before PR submission.
+- Add unit/integration coverage for new logic; Lua/TypeScript tooling will regain coverage when reintroduced.
 
 ## Documentation & Telemetry
-- Update relevant docs in `docs/echo/` whenever behavior or architecture changes.
+- Update relevant docs in `docs/` whenever behavior or architecture changes.
 - Record major decisions or deviations in the execution plan or decision log tables.
 - Use Neo4j to leave breadcrumbs for future Codex agents.
 
 ## Submitting Changes
-1. Run `pnpm lint` and `pnpm test`.
+1. Run `cargo fmt`, `cargo clippy`, and `cargo test`.
 2. Commit with meaningful messages (no conventional prefixes; tell the story).
 3. Push your branch and open a PR. Include:
    - Summary of changes and motivation.
@@ -48,9 +48,10 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize:
 4. Request review from maintainers (see CODEOWNERS).
 
 ## Code Style
-- TypeScript + ESLint + Prettier (config provided).
-- Prefer explicit types when clarity improves comprehension.
-- Avoid non-deterministic APIs (no `Math.random`, `Date.now`, etc.). Use Echo’s math/PRNG services.
+- Rust code must pass `cargo fmt` and `cargo clippy` without warnings.
+- Lua scripts should remain deterministic (no uncontrolled globals, RNG via engine services).
+- TypeScript tooling (when active) lives in `reference/typescript/`; follow local lint configs when reactivated.
+- Avoid non-deterministic APIs (no wall-clock, no uncontrolled randomness). Use Echo’s deterministic services.
 
 ## Communication
 - Major updates logged in Neo4j threads (`echo-devlog`, `echo-spec`).