feat(grid-agent): establish architecture and config (#118)

crates/metacrate-grid-agent/README.md

@@ -0,0 +1,40 @@
+# MetaCrate grid agent
+
+This package is the bounded, provider-neutral foundation for the MetaCrate
+OpenSim grid agent. It contains a reusable library and the
+`metacrate-grid-agent` service binary. The first implementation is deliberately
+offline: it publishes a deterministic ready event, accepts control commands,
+and shuts down both owned tasks without contacting a grid or LLM. The
+`live-grid` feature exposes the side-effect-free owner for the existing
+`libremetaverse::GridClient`; later live adapters must extend that manager graph
+instead of adding a protocol client.
+
+The LLM connection identity has exactly two resolved fields:
+`llm.endpoint_url` and `llm.api_key`. The endpoint is used exactly as supplied;
+there are no providers, presets, base-URL rewrites, model catalogs, discovery,
+or provider SDKs. `Debug`/`Display` output removes API keys, grid passwords, URL
+user information, and URL query values. Secret wrappers are not serializable.
+
+Configuration precedence, from lowest to highest, is built-in defaults, an
+optional JSON file, its referenced secret files, then environment values (an
+environment-referenced secret file is below a direct environment secret).
+Supported secret environment variables are
+`METACRATE_AGENT_LLM_API_KEY[_FILE]` and
+`METACRATE_AGENT_GRID_PASSWORD[_FILE]`. Secret files must be bounded regular,
+non-symlink UTF-8 files containing one line. Operators must restrict their OS
+ACLs to the service identity; the core uses only portable `std::fs` checks and
+does not assume Unix permission bits.
+
+Run the focused offline gate with:
+
+```sh
+cargo test --locked -p metacrate-grid-agent
+cargo clippy --locked -p metacrate-grid-agent --all-targets -- -D warnings
+cargo run --locked -p metacrate-grid-agent -- \
+  --config config/grid-agent.example.json --check-config
+cargo run --locked -p metacrate-grid-agent -- \
+  --config config/grid-agent.example.json --run-once
+```
+
+See [`../../docs/grid-agent-architecture.md`](../../docs/grid-agent-architecture.md)
+for queue/task ownership, shutdown, and trust boundaries.