added sandbox doc

STRUCTURE.md

@@ -55,8 +55,15 @@
 5.2.5. Simple auth - using SDK simple auth with the JavaScript SDK (Ale)
 5.3. Go - using the Go SDK for Ratio1 (B)
 5.3.1. Quick end-to-end example - a complete example of using the Go SDK (B)
-5.3.1. API Quick Reference - detailed API documentation (B)
-5.4. The Sandbox - using the Ratio1 Sandbox for testing and development(B)
+5.3.2. API Quick Reference - detailed API documentation (B)
+5.3.3. CStore Integration - using CStore with the Go SDK (B)
+5.3.4. R1FS Integration - using R1FS with the Go SDK (B)
+5.4. The Sandbox - using the Ratio1 Plugins Sandbox for testing and development (B)
+5.4.1. Running the sandbox - start/install and CLI flags (B)
+5.4.2. Seeding data - how to seed CStore and R1FS fixtures (B)
+5.4.3. HTTP surface - endpoint list and what they do (B)
+5.4.4. Using with SDKs - configure SDKs to target the sandbox (B)
+5.4.5. Troubleshooting - common issues and debugging tips (B)
 5.5. r1ctl - the kubectl for Ratio1 (AID)
 5.5.1. r1ctl Overview - overview presentation with no details (AID)
 5.5.2. r1ctl Features (AID)
@@ -96,4 +103,4 @@
 10.2.2. How to Develop - technical details of DataGen (Bleo)
 10.3. ASPIRE - decentralized clinical management for various syndromes (P)
 10.3.1. How to Deeploy - deployment details of ASPIRE (P)
-10.3.2. How to Develop - technical details of ASPIRE (P)
+10.3.2. How to Develop - technical details of ASPIRE (P)

docs/developers/index.md

@@ -10,7 +10,7 @@ description: introduction to developing on Ratio1
 - [Python](./python/)
 - [JavaScript](./javascript/)
 - [Go](./go/)
-- [The Sandbox](./the-sandbox)
+- [Sandbox](./sandbox/)
 - [r1ctl](./r1ctl/)
 - [Donation add-on for developers](./donation-add-on-for-developers)
 

docs/developers/sandbox/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Sandbox",
+  "position": 4,
+  "link": {
+    "type": "doc",
+    "id": "developers/sandbox/index"
+  }
+}

docs/developers/sandbox/http-surface.md

@@ -0,0 +1,37 @@
+---
+title: HTTP surface
+sidebar_position: 4
+description: endpoints exposed by the sandbox and what they do
+---
+
+# HTTP surface
+
+The sandbox mirrors the REST surface of the production plugins closely enough for SDK development.
+It is intentionally small and focused: the goal is “exercise clients end-to-end” rather than fully emulate the node.
+
+## CStore endpoints
+- `POST /set` – store a JSON value by key.
+- `GET /get?key=<key>` – fetch a value by key.
+- `POST /hset` – store a JSON value under a hash key + field.
+- `GET /hget?hkey=<hashKey>&key=<field>` – fetch a hash field.
+- `GET /hgetall?hkey=<hashKey>` – fetch all hash fields.
+- `GET /get_status` – inspect current keys.
+
+## R1FS endpoints
+- `POST /add_file` – multipart upload (binary).
+- `POST /add_file_base64` – JSON upload with base64 payload.
+- `GET /get_file?cid=<cid>[&secret=<secret>]` – resolve stored metadata/path.
+- `GET /get_file_base64?cid=<cid>[&secret=<secret>]` – download content (base64).
+- `POST /add_yaml` / `POST /add_json` / `POST /add_pickle` – store structured payloads.
+- `POST /calculate_json_cid` / `POST /calculate_pickle_cid` – compute CIDs without storing.
+- `GET /get_yaml?cid=<cid>[&secret=<secret>]` – fetch YAML payload.
+- `POST /delete_file` / `POST /delete_files` – remove stored content by CID(s).
+- `GET /get_status` – list known files.
+
+## Observability
+All handlers log request/response bodies and duration, which is useful when debugging SDK behaviour.
+
+## Next steps
+- Practical setup and flags: [Running the sandbox](./running).
+- SDK integration: [Using with SDKs](./using-with-sdks).
+- Back to [Sandbox](./).

docs/developers/sandbox/index.md

@@ -0,0 +1,41 @@
+---
+title: Sandbox
+sidebar_position: 1
+description: using the Ratio1 Plugins Sandbox for testing and development
+---
+
+# Sandbox
+
+The Ratio1 Plugins Sandbox is a self-contained HTTP server that mimics the **CStore** and **R1FS** manager APIs exposed by Ratio1 edge nodes.
+Use it to develop and test SDK clients locally without needing a live node.
+
+## What you get
+- CStore mock endpoints like `/set`, `/get`, `/hset`, `/hgetall`, `/get_status`.
+- R1FS mock endpoints like `/add_file`, `/get_file_base64`, `/add_json`, `/calculate_json_cid`, `/delete_files`, `/get_status`.
+- Deterministic seeding for repeatable tests.
+- Latency and failure injection to validate retries and timeouts.
+- Environment variable exports that match the SDK defaults:
+  - `EE_CHAINSTORE_API_URL`
+  - `EE_R1FS_API_URL`
+
+## Quick start
+1. Start the sandbox:
+   ```bash
+   r1-plugins-sandbox --cstore-addr :8787 --r1fs-addr :8788
+   ```
+2. Copy the exports printed by the sandbox into your shell:
+   ```bash
+   export EE_CHAINSTORE_API_URL=http://127.0.0.1:8787
+   export EE_R1FS_API_URL=http://127.0.0.1:8788
+   ```
+3. Run your SDK client (Go/Python/JS) against those URLs.
+
+## Repository
+- `https://github.com/Ratio1/r1-plugins-sandbox`
+
+## Next steps
+- Learn how to run and configure it: [Running the sandbox](./running).
+- Seed predictable data: [Seeding data](./seeding).
+- See the full endpoint list: [HTTP surface](./http-surface).
+- Integrate with SDKs: [Using with SDKs](./using-with-sdks).
+- Debug common issues: [Troubleshooting](./troubleshooting).

docs/developers/sandbox/running.md

@@ -0,0 +1,59 @@
+---
+title: Running the sandbox
+sidebar_position: 2
+description: how to start and configure the Ratio1 Plugins Sandbox
+---
+
+# Running the sandbox
+
+## Install options
+The sandbox is shipped as release artifacts (recommended) and can also be built from source.
+
+- Releases: `https://github.com/Ratio1/r1-plugins-sandbox/releases/latest`
+- Build from source (Go 1.21+):
+  ```bash
+  go build -o r1-plugins-sandbox
+  ./r1-plugins-sandbox --help
+  ```
+
+## Start
+```bash
+r1-plugins-sandbox --cstore-addr :8787 --r1fs-addr :8788
+```
+
+On startup, it prints the environment variables you should export:
+```bash
+export EE_CHAINSTORE_API_URL=http://127.0.0.1:8787
+export EE_R1FS_API_URL=http://127.0.0.1:8788
+```
+
+## Flags
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--cstore-addr` | `:8787` | Listen address for the CStore mock. |
+| `--r1fs-addr` | `:8788` | Listen address for the R1FS mock. |
+| `--kv-seed` | | Path to a JSON file with initial CStore entries. |
+| `--fs-seed` | | Path to a JSON file with initial R1FS files. |
+| `--latency` | `0` | Adds fixed delay (e.g. `200ms`) to every request. |
+| `--fail` | | Failure injection string `rate=<float>,code=<status>` (code defaults to `500`). |
+
+## Examples
+Add latency:
+```bash
+r1-plugins-sandbox --latency 150ms
+```
+
+Inject failures (about 3% HTTP 429):
+```bash
+r1-plugins-sandbox --fail rate=0.03,code=429
+```
+
+Use seed files:
+```bash
+r1-plugins-sandbox --kv-seed ./seeds/cstore.json --fs-seed ./seeds/r1fs.json
+```
+
+## Next steps
+- Add predictable state: [Seeding data](./seeding).
+- Browse endpoints: [HTTP surface](./http-surface).
+- Back to [Sandbox](./).

docs/developers/sandbox/seeding.md

@@ -0,0 +1,56 @@
+---
+title: Seeding data
+sidebar_position: 3
+description: start the sandbox with a predictable dataset for repeatable tests
+---
+
+# Seeding data
+
+Seed files let you start the sandbox with predictable initial state, which is useful for:
+- reproducible integration tests
+- demos and tutorials
+- validating migrations and edge cases
+
+Pass seeds at startup:
+```bash
+r1-plugins-sandbox --kv-seed ./seeds/cstore.json --fs-seed ./seeds/r1fs.json
+```
+
+## CStore seed format
+`--kv-seed` expects a JSON array of entries with `key` and JSON `value`:
+```json
+[
+  {
+    "key": "jobs:123",
+    "value": { "status": "queued" }
+  }
+]
+```
+
+## R1FS seed format
+`--fs-seed` expects a JSON array of entries with:
+- `path` (string)
+- `base64` (string, base64-encoded file content)
+- optional `content_type` (string)
+- optional `metadata` (object)
+- optional `last_modified` (RFC3339 string)
+
+Example:
+```json
+[
+  {
+    "path": "/artifacts/report.json",
+    "base64": "eyJvayI6IHRydWV9",
+    "content_type": "application/json",
+    "metadata": { "workflow": "ci" }
+  }
+]
+```
+
+## Tips
+- Keep seed files small and focused; use separate fixtures per test suite.
+- For binary payloads, base64-encode the raw bytes.
+
+## Next steps
+- Start the server: [Running the sandbox](./running).
+- Back to [Sandbox](./).

docs/developers/sandbox/troubleshooting.md

@@ -0,0 +1,40 @@
+---
+title: Troubleshooting
+sidebar_position: 6
+description: common issues and how to debug the sandbox
+---
+
+# Troubleshooting
+
+## The SDK can’t connect
+- Confirm the sandbox is running and listening on the expected ports.
+- Confirm you exported:
+  - `EE_CHAINSTORE_API_URL`
+  - `EE_R1FS_API_URL`
+- If you changed ports/hosts, re-export the variables (or restart your shell session).
+
+## “not found” vs errors
+Depending on the SDK, missing keys/files may be represented as:
+- `null` responses from the API, decoded as `nil` items/documents
+- explicit not-found errors (SDK-specific)
+
+Treat transport errors (connection refused, timeouts, HTTP 5xx) differently from “missing data”.
+
+## Simulate timeouts and retries
+Use latency injection:
+```bash
+r1-plugins-sandbox --latency 300ms
+```
+
+Use failure injection:
+```bash
+r1-plugins-sandbox --fail rate=0.1,code=503
+```
+
+## Seed parsing errors
+- Validate the JSON is well-formed.
+- For R1FS seeds, ensure `base64` is valid base64 and `path` is a non-empty string.
+
+## Next steps
+- Add fixtures: [Seeding data](./seeding).
+- Back to [Sandbox](./).

docs/developers/sandbox/using-with-sdks.md

@@ -0,0 +1,61 @@
+---
+title: Using with SDKs
+sidebar_position: 5
+description: configure SDKs to target the sandbox instead of a live node
+---
+
+# Using with SDKs
+
+The sandbox prints ready-to-copy environment exports. Most Ratio1 SDK clients can discover the sandbox automatically by reading:
+- `EE_CHAINSTORE_API_URL`
+- `EE_R1FS_API_URL`
+
+## Start the sandbox and export env vars
+```bash
+r1-plugins-sandbox --cstore-addr :8787 --r1fs-addr :8788
+export EE_CHAINSTORE_API_URL=http://127.0.0.1:8787
+export EE_R1FS_API_URL=http://127.0.0.1:8788
+```
+
+## Go SDK
+With the environment variables set, the Go SDK can initialise clients via:
+- `cstore.NewFromEnv()`
+- `r1fs.NewFromEnv()`
+
+Then run the upstream examples (from the SDK repo):
+```bash
+go run ./examples/runtime_modes
+go run ./examples/cstore
+go run ./examples/r1fs
+```
+
+## TypeScript / JavaScript SDK (edge-sdk-ts)
+Repository:
+- `https://github.com/Ratio1/edge-sdk-ts`
+
+Use the sandbox exactly like a live node by pointing the SDK at the same base URLs:
+- CStore: `EE_CHAINSTORE_API_URL`
+- R1FS: `EE_R1FS_API_URL`
+
+### Node.js (recommended for local dev)
+Export the variables in your shell before running your TS/JS program:
+```bash
+export EE_CHAINSTORE_API_URL=http://127.0.0.1:8787
+export EE_R1FS_API_URL=http://127.0.0.1:8788
+node ./dist/index.js
+```
+
+If your project uses `.env` files, load them (for example via `dotenv`) so `process.env.EE_CHAINSTORE_API_URL` and `process.env.EE_R1FS_API_URL` are available at runtime.
+
+### Browser apps (Vite/Next/Webpack)
+Browser bundles do not automatically inherit shell environment variables at runtime.
+Prefer running your SDK usage on the server (Node.js) or inject the sandbox URLs via your framework’s public env mechanism, then pass them to the SDK’s configuration (use the SDK’s documented config keys if they differ from the `EE_*` variables).
+
+## Other SDKs (Python, etc.)
+If your SDK uses the same environment variables, it can point to the sandbox without code changes.
+If it uses different configuration keys, map them to the printed sandbox URLs.
+
+## Next steps
+- Validate endpoints: [HTTP surface](./http-surface).
+- Debug failures: [Troubleshooting](./troubleshooting).
+- Back to [Sandbox](./).