rentline-sandbox 0.1.2

package/LICENSE

@@ -0,0 +1,34 @@
+Rentline Sandbox SDK License Agreement
+Version 1.0 — May 2026
+
+Copyright (c) 2026 ChainSettle Inc. All rights reserved.
+
+1. Permission of Use
+Permission is granted to use this SDK solely for integration with Rentline Sandbox
+APIs and services provided by ChainSettle Inc. and its affiliates.
+
+2. Restrictions
+You may not:
+
+- Copy, fork, or redistribute this software or any derivative work.
+- Use the SDK to build, host, or offer a competing service.
+- Modify, reverse engineer, or decompile the SDK, except as required for legitimate
+  integration purposes.
+- Re-host, rebrand, or re-publish this SDK (including on GitHub, npm, PyPI, or any
+  equivalent platform) without prior written consent from ChainSettle Inc.
+
+3. Ownership and Intellectual Property
+This license does not grant ownership rights or any implied license. ChainSettle Inc.
+retains all intellectual property rights in this software, including source code,
+binaries, documentation, and related assets.
+
+4. Enforcement
+Unauthorized use, redistribution, or publication of this software may result in
+immediate termination of access and legal action under applicable copyright and
+intellectual property laws.
+
+5. Commercial or Enterprise Use
+For commercial licensing, redistribution rights, or enterprise use, please contact:
+legal@chainsettle.com
+
+© 2026 ChainSettle Inc. All Rights Reserved.

package/README.md

@@ -0,0 +1,287 @@
+# rentline-sandbox
+
+CLI and MCP server for the [Rentline Sandbox](https://sandbox.rentline.xyz) — a turn-based real estate investment simulation game engine.
+
+Players compete over tokenised properties using mortgages, Fed rate cycles, macro events, property condition grades (A–F), PACE liens, and investor tiers. Playable by humans via the CLI, or fully autonomously by AI agents via the MCP server.
+
+---
+
+## Install
+
+```bash
+npm install -g rentline-sandbox
+```
+
+Two binaries are installed:
+- `sandbox` — human CLI
+- `sandbox-mcp` — MCP server for AI agents (stdio JSON-RPC)
+
+Requires Node.js ≥ 18.
+
+---
+
+## Authentication
+
+### Browser login (recommended)
+```bash
+sandbox auth login
+# Opens sandbox.rentline.xyz/cli-auth in your browser
+# Sign in, copy the generated sb_ key, paste it back
+```
+
+### Direct key
+```bash
+sandbox auth login --key sb_xxxx --url https://sandbox-api.rentline.xyz
+```
+
+### Check status
+```bash
+sandbox auth whoami   # shows key prefix, API URL, and connectivity
+sandbox auth logout   # remove saved credentials
+```
+
+Credentials are saved to `~/.rentline-sandbox/credentials.json` and used automatically by all CLI commands.
+
+---
+
+## CLI usage
+
+### Game management
+```bash
+sandbox game list
+sandbox game get <game-id>
+sandbox game create --name "Test" --display-name "Alice"
+sandbox game create --preset standard --name "Quick Match" --display-name "Alice"
+sandbox game join <game-id> --invite <code> --display-name "Bob"
+sandbox game ready <game-id>
+sandbox game advance <game-id>
+sandbox game feed <game-id> [--turn 3] [--limit 50]
+sandbox game leaderboard <game-id>
+sandbox game fed <game-id>
+sandbox game add-bot <game-id> --name "AggroBot" --strategy aggressive
+sandbox game autonomous start <game-id> --delay 30
+sandbox game autonomous stop <game-id>
+```
+
+### Trading
+```bash
+sandbox trade buy <game-id> --property <id> --tokens 0.5
+sandbox trade sell <game-id> --property <id> --tokens 0.5
+```
+
+### Portfolio and debt
+```bash
+sandbox portfolio <game-id> <player-id>
+sandbox debt <game-id> <player-id>
+```
+
+### Mortgage
+```bash
+sandbox mortgage buy <game-id> --property <id> --tokens 0.5
+sandbox mortgage refi <game-id> --property <id> [--cash-out 5000]
+sandbox mortgage heloc <game-id> --property <id> --draw 5000
+sandbox mortgage repay <game-id> --property <id> --amount 2000
+sandbox mortgage prepay <game-id> --property <id> --amount 10000 [--type first_lien]
+sandbox mortgage improve <game-id> --property <id> --grade B
+sandbox mortgage pace <game-id> --property <id> --grade C
+sandbox mortgage list <game-id> <player-id>
+```
+
+### Admin
+```bash
+sandbox admin properties list
+sandbox admin properties sync
+sandbox admin mint <game-id> <player-id> --amount 50000
+```
+
+---
+
+## MCP server setup
+
+The `sandbox-mcp` command runs an MCP server over stdio JSON-RPC. Configure it once in your AI client.
+
+### OpenCode (`opencode.json`)
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "rentline-sandbox": {
+      "type": "local",
+      "command": ["sandbox-mcp"],
+      "enabled": true,
+      "environment": {
+        "SANDBOX_API_URL": "https://sandbox-api.rentline.xyz",
+        "SANDBOX_API_KEY": "sb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "rentline-sandbox": {
+      "command": "sandbox-mcp",
+      "env": {
+        "SANDBOX_API_URL": "https://sandbox-api.rentline.xyz",
+        "SANDBOX_API_KEY": "sb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf
+```json
+{
+  "mcpServers": {
+    "rentline-sandbox": {
+      "command": "sandbox-mcp",
+      "env": {
+        "SANDBOX_API_URL": "https://sandbox-api.rentline.xyz",
+        "SANDBOX_API_KEY": "sb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+---
+
+## MCP tools (35 total)
+
+### Game management
+| Tool | Description |
+|---|---|
+| `list_games` | All open game rooms |
+| `get_game` | Full game state: players, properties, turn, Fed rate, settings |
+| `create_game` | Create with full config + optional bots array |
+| `create_game_from_preset` | One-call presets: `quick` `standard` `leveraged` `distressed` `long_run` |
+| `join_game` | Join with invite code |
+| `mark_ready` | Toggle ready state |
+| `advance_turn` | Run all engine phases (host only) |
+| `get_feed` | Event stream: Fed, macro, rent, price moves, debt service, turn summary |
+| `add_bot` | Add LLM bot (strategies: `aggressive` `conservative` `balanced` `momentum` `income` `value_add`) |
+| `remove_bot` | Remove bot from lobby |
+| `start_autonomous` | Enable auto-advance (advances on all-ready or turn deadline) |
+| `stop_autonomous` | Pause auto-advance |
+| `set_delegate` | Agent delegation for idle human players |
+| `spectate` | Public game snapshot (no auth) |
+
+### Market & Intel
+| Tool | Description |
+|---|---|
+| `list_properties` | Active pool properties with grades |
+| `get_market_summary` | Live cap rates, price deltas, grade, vacancy, mechanics lien status |
+| `get_fed_history` | FOMC decision log |
+| `get_player_actions` | Transaction timeline for a player |
+
+### Trading
+| Tool | Description |
+|---|---|
+| `buy_tokens` | All-cash purchase at current market price |
+| `sell_tokens` | Sell (proceeds service mechanics lien → first lien → HELOC/PACE before cash) |
+
+### Debt
+| Tool | Description |
+|---|---|
+| `originate_mortgage` | Leveraged buy (tier-adjusted LTV and rate auto-applied) |
+| `refi_mortgage` | Rate-and-term or cash-out refi |
+| `heloc_draw` | Draw from HELOC |
+| `heloc_repay` | Repay HELOC balance |
+| `prepay_principal` | Partial/full prepayment (first_lien, heloc, pace, mechanics_lien) |
+| `improve_property` | Cash-funded grade upgrade (cost = steps × 8% × price) |
+| `originate_pace_lien` | Financed grade upgrade — no down payment (rate = base + 1.5%) |
+| `get_debt` | All active mortgages: balance, rate, LTV, arrears |
+
+### Portfolio
+| Tool | Description |
+|---|---|
+| `get_portfolio` | Holdings with grade, P&L, annualised yield, turns held, investor tier |
+| `get_leaderboard` | Game leaderboard or global all-time rankings |
+
+---
+
+## Game mechanics summary
+
+### Turn phases (in order)
+1. **Fed meeting** — hike/cut/hold; `FED_WARNING` fires 1 turn before; ARMs reprice immediately
+2. **Macro events** — rate macros activate after 1-turn warning; active macros tick down
+3. **Rent collect** — proportional to tokens held; grade multipliers applied; vacancy blocks
+4. **Random events** — vacancy, lease renewal, capex, appreciation/depreciation (all grade-adjusted)
+5. **Market move** — applies price drift
+6. **Debt service** — collect payments; forced sale after 1 grace turn
+7. **Distribute** — credits rent; emits `TURN_SUMMARY` event
+
+### Property grades (A → F)
+Grade affects rent multiplier, appreciation probability, capex risk, and vacancy rate. Upgrade mid-game with `improve_property` (cash) or `originate_pace_lien` (financed). The `GENTRIFICATION` macro can upgrade D/F properties automatically.
+
+### Investor tiers
+Computed live from NAV — automatically applied to every mortgage origination and refi:
+
+| Tier | Min NAV | LTV bonus | Rate discount |
+|---|---|---|---|
+| Retail | $0 | +0% | 0 bps |
+| Accredited | $100k | +5% | −25 bps |
+| Professional | $500k | +10% | −50 bps |
+| Institutional | $2.5M | +15% | −75 bps |
+| Developer | $25M | +20% | −100 bps |
+
+### NAV formula
+```
+NAV = cash + Σ(tokens × price) − Σ(active mortgage balances) − judgment_balance
+```
+
+---
+
+## Configuration
+
+| Env var | Description |
+|---|---|
+| `SANDBOX_API_URL` | API base URL (default: `https://sandbox-api.rentline.xyz`) |
+| `SANDBOX_API_KEY` | Your `sb_` key (MCP server only — CLI uses credentials file) |
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build        # compile TypeScript → dist/
+npm run dev          # watch mode
+node dist/index.js game list   # test without npm link
+```
+
+### Project structure
+```
+src/
+  index.ts        CLI entry point
+  server.ts       MCP server (35 tools, stdio JSON-RPC)
+  tools.ts        Tool definitions + input schemas
+  client.ts       Typed HTTP client
+  config.ts       Credential persistence
+  commands/       auth, game, trade, mortgage, admin
+dist/             Compiled output
+SKILL.md          MCP skill manifest
+llms.txt          Condensed reference for LLM context windows
+```
+
+### Adding a new tool
+1. Add a `ToolDef` in `src/tools.ts`
+2. Add a `case` in the `switch` in `src/server.ts`
+3. Add the client method in `src/client.ts`
+4. `npm run build`
+
+---
+
+## Links
+
+- Web app: [sandbox.rentline.xyz](https://sandbox.rentline.xyz)
+- API docs: [sandbox-api.rentline.xyz/docs](https://sandbox-api.rentline.xyz/docs)
+- Get an API key: [sandbox.rentline.xyz/cli-auth](https://sandbox.rentline.xyz/cli-auth)
+- Source: [github.com/BrandynHamilton/rentline-sandbox](https://github.com/BrandynHamilton/rentline-sandbox)
+
+
+---

package/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: rentline-sandbox
+description: |
+  Rentline Sandbox is a turn-based real estate investment simulation game engine.
+  Players compete over tokenised properties using simulated tUSDC, with mortgages,
+  Fed rate cycles, macro events, property condition grades (A-F), PACE liens, and
+  investor tiers reflecting real market dynamics. Use these tools to play, observe,
+  and analyse games.
+  TRIGGERS: sandbox game, real estate simulation, property tokens, buy property tokens,
+  sell property tokens, originate mortgage, HELOC, cash-out refi, game leaderboard,
+  advance turn, Fed rate, macro event, recession event, portfolio NAV, debt service,
+  ARM rate, game feed, turn event, leveraged real estate, property investment game,
+  PACE lien, property grade, improve property, value add, investor tier
+license: SEE LICENSE IN LICENSE
+compatibility: opencode
+---
+
+# Rentline Sandbox
+
+Turn-based real estate investment simulation — multiplayer, AI-agent-ready.
+
+## Setup
+
+Get an API key at **sandbox.rentline.xyz/cli-auth**, then configure your client:
+
+**OpenCode** (`opencode.json`):
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "rentline-sandbox": {
+      "type": "local",
+      "command": ["sandbox-mcp"],
+      "enabled": true,
+      "environment": {
+        "SANDBOX_API_KEY": "sb_your_key_here",
+        "SANDBOX_API_URL": "https://sandbox-api.rentline.xyz"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "rentline-sandbox": {
+      "command": "sandbox-mcp",
+      "env": {
+        "SANDBOX_API_KEY": "sb_your_key_here",
+        "SANDBOX_API_URL": "https://sandbox-api.rentline.xyz"
+      }
+    }
+  }
+}
+```
+
+**Cursor / Windsurf**:
+```json
+{
+  "mcpServers": {
+    "rentline-sandbox": {
+      "command": "sandbox-mcp",
+      "env": { "SANDBOX_API_KEY": "sb_your_key_here", "SANDBOX_API_URL": "https://sandbox-api.rentline.xyz" }
+    }
+  }
+}
+```
+
+**CLI login** (saves credentials locally):
+```bash
+sandbox auth login               # browser OAuth via sandbox.rentline.xyz/cli-auth
+sandbox auth login --key sb_xxx  # direct key
+sandbox auth whoami              # verify
+```
+
+## CLI usage
+
+```bash
+sandbox game list
+sandbox game create --name "Test" --display-name "Alice"
+sandbox game create --preset standard --name "Quick Match" --display-name "Alice"
+sandbox game join <id> --invite A3F7K9Z2 --name "Bob"
+sandbox game advance <id>
+sandbox game feed <id> --limit 20
+sandbox game leaderboard <id>
+sandbox game fed <id>
+sandbox game add-bot <id> --name "AggroBot" --strategy value_add
+sandbox game autonomous start <id> --delay 30
+
+sandbox trade buy <game-id> --property <id> --tokens 0.5
+sandbox trade sell <game-id> --property <id> --tokens 0.5
+
+sandbox portfolio <game-id> <player-id>
+sandbox debt <game-id> <player-id>
+
+sandbox mortgage buy <game-id> --property <id> --tokens 0.5
+sandbox mortgage refi <game-id> --property <id> --cash-out 5000
+sandbox mortgage heloc <game-id> --property <id> --draw 5000
+sandbox mortgage repay <game-id> --property <id> --amount 2000
+sandbox mortgage prepay <game-id> --property <id> --amount 10000
+sandbox mortgage improve <game-id> --property <id> --grade B
+sandbox mortgage pace <game-id> --property <id> --grade C
+sandbox mortgage list <game-id> <player-id>
+
+sandbox admin properties list
+sandbox admin properties sync
+sandbox admin mint <game-id> <player-id> --amount 50000
+```
+
+## Tool reference (35 tools)
+
+### Game management
+| Tool | Description |
+|---|---|
+| `list_games` | List open game rooms |
+| `get_game` | Full game state: players, properties, turn, Fed rate, config |
+| `create_game` | Create a game with full mortgage/Fed/grade config + optional bots |
+| `create_game_from_preset` | One-call presets: quick, standard, leveraged, distressed, long_run |
+| `join_game` | Join via invite code, get player_id |
+| `mark_ready` | Toggle ready for next turn |
+| `advance_turn` | Host: run all 7 engine phases |
+| `get_feed` | Turn event stream: Fed, macro, rent, price moves, debt service, turn summary |
+| `add_bot` | Add LLM bot (strategies: aggressive, conservative, balanced, momentum, income, value_add) |
+| `remove_bot` | Remove bot from lobby |
+| `start_autonomous` | Enable auto-advance (all-ready or deadline triggers) |
+| `stop_autonomous` | Pause auto-advance |
+| `set_delegate` | Agent delegation for idle human players |
+| `spectate` | Public game snapshot (no auth) |
+
+### Market & Intel
+| Tool | Description |
+|---|---|
+| `list_properties` | Active pool properties with grades |
+| `get_market_summary` | Live cap rates, price deltas, grade, vacancy, mechanics lien status |
+| `get_fed_history` | FOMC decision log |
+| `get_player_actions` | Transaction timeline for a player |
+
+### Trading
+| Tool | Description |
+|---|---|
+| `buy_tokens` | All-cash purchase at current market price |
+| `sell_tokens` | Sell (proceeds service mechanics lien → first lien → HELOC/PACE before cash) |
+
+### Debt
+| Tool | Description |
+|---|---|
+| `originate_mortgage` | Leveraged buy (tier-adjusted LTV and rate auto-applied) |
+| `refi_mortgage` | Rate-and-term or cash-out refi |
+| `heloc_draw` | Draw from HELOC |
+| `heloc_repay` | Repay HELOC balance |
+| `prepay_principal` | Partial/full prepayment (first_lien, heloc, pace, mechanics_lien) |
+| `improve_property` | Cash-funded grade upgrade (cost = steps × 8% × price) |
+| `originate_pace_lien` | Financed grade upgrade — no down payment (rate = base + 1.5%) |
+| `get_debt` | All mortgages: balances, rates, LTV, arrears |
+
+### Portfolio
+| Tool | Description |
+|---|---|
+| `get_portfolio` | Holdings with grade, P&L, annualised yield, turns held, investor tier |
+| `get_leaderboard` | Game or global leaderboard ranked by NAV |
+
+## Game mechanics
+
+### Turn phases (in order)
+1. **Fed meeting** — hike/cut/hold; `FED_WARNING` fires 1 turn before; ARMs reprice immediately
+2. **Macro events** — rate macros activate after 1-turn warning; active macros tick down
+3. **Rent collect** — proportional to tokens; grade multipliers applied; vacancy blocks
+4. **Random events** — vacancy, lease renewal, capex, appreciation/depreciation (grade-adjusted)
+5. **Market move** — applies price drift
+6. **Debt service** — collect payments; forced sale after 1 grace turn
+7. **Distribute** — credits rent; emits `TURN_SUMMARY` event
+
+### Property grades (A → F)
+Grade affects rent multiplier, appreciation probability, capex risk, vacancy rate.
+Upgrade via `improve_property` (cash) or `originate_pace_lien` (financed, no down payment).
+
+### Investor tiers (live from NAV, auto-applied to mortgage terms)
+| Tier | Min NAV | LTV bonus | Rate discount |
+|---|---|---|---|
+| Retail | $0 | +0% | 0 bps |
+| Accredited | $100k | +5% | −25 bps |
+| Professional | $500k | +10% | −50 bps |
+| Institutional | $2.5M | +15% | −75 bps |
+| Developer | $25M | +20% | −100 bps |
+
+### NAV formula
+```
+NAV = cash + Σ(tokens × price) − Σ(mortgage balances) − judgment_balance
+```
+
+### Macro events
+| Event | Prob | Duration | Effect |
+|---|---|---|---|
+| RECESSION | 6% | 2–4 turns | −5%/turn price, −8% rent, +15% vacancy |
+| HOUSING_BOOM | 5% | 2–3 turns | +6%/turn price, +5% rent |
+| NATURAL_DISASTER | 3% | 1 turn | −20% price, rent=0, +40% vacancy |
+| POLICY_CHANGE | 8% | 3 turns | ±5–12% rent/price |
+| TAX_HIKE | 7% | Permanent | $50–150/token/turn expense |
+| INTEREST_RATE_RISE | 7% | 3–6 turns | +1.5% ARM rate (1-turn warning) |
+| INTEREST_RATE_CUT | 6% | 3–6 turns | −1.0% ARM rate (1-turn warning) |
+| RENT_CONTROL | 5% | 4 turns | Blocks lease renewal increases |
+| INSURANCE_CRISIS | 5% | 2–3 turns | $100–300/token/turn expense |
+| GENTRIFICATION | 4% | 3 turns | D/F properties upgrade one grade |
+| ZONING_CHANGE | 5% | 2 turns | Targeted type: −10% rent, −5% price |
+| PROPERTY_BUBBLE | 3% | 2 turns | All prices +8%/turn |
+| BUBBLE_BURST | 2% | 2–3 turns | All prices −12%/turn, +20% vacancy |
+| TENANT_STRIKE | 4% | 1–2 turns | Targeted type: rent = 0 |
+| EMINENT_DOMAIN | 2% | Instant | One property force-bought at 110% market value |

package/dist/admin-YB2G7ZYZ.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import {
+  getApiKey,
+  getApiUrl,
+  requireConfig
+} from "./chunk-Q5AKRRZ2.js";
+import {
+  createClient
+} from "./chunk-X3OZHOPM.js";
+
+// src/commands/admin.ts
+function client(cmd) {
+  const opts = cmd.optsWithGlobals();
+  const cfg = requireConfig();
+  return createClient({ apiUrl: getApiUrl(opts.url), apiKey: getApiKey(opts.apiKey) ?? cfg.api_key });
+}
+function registerAdmin(program) {
+  const admin = program.command("admin").description("Admin operations (requires admin API key)");
+  const props = admin.command("properties").description("Property pool management");
+  props.command("list").description("List all properties in the sandbox pool").option("--all", "Include inactive properties").action(async (opts, cmd) => {
+    const properties = await client(cmd).listProperties(!opts.all);
+    if (!properties.length) {
+      console.log("No properties in pool. Run: sandbox admin properties sync");
+      return;
+    }
+    console.log(`
+${"Name".padEnd(32)}${"City".padEnd(16)}${"Price".padStart(12)}${"Rent/mo".padStart(10)}${"Cap".padStart(6)}`);
+    console.log("\u2500".repeat(76));
+    for (const p of properties) {
+      const cap = p.cap_rate !== null ? `${(p.cap_rate * 100).toFixed(1)}%` : "\u2014";
+      console.log(
+        `${(p.name ?? p.id).slice(0, 30).padEnd(32)}${(p.city ?? "\u2014").padEnd(16)}$${p.initial_price_usd.toLocaleString("en-US", { maximumFractionDigits: 0 }).padStart(11)}$${p.monthly_rent_usd.toLocaleString("en-US", { maximumFractionDigits: 0 }).padStart(9)}${cap.padStart(6)}`
+      );
+    }
+    console.log(`
+Total: ${properties.length}`);
+  });
+  props.command("sync").description("Pull/update property pool from rwa-issuer-sim (RWA_ISSUER_URL must be set)").action(async (_, cmd) => {
+    process.stdout.write("Syncing property pool from rwa-issuer-sim\u2026 ");
+    const res = await client(cmd).syncProperties();
+    console.log("done");
+    console.log(`  Created:  ${res.created}`);
+    console.log(`  Updated:  ${res.updated}`);
+    console.log(`  Skipped:  ${res.skipped}`);
+  });
+  admin.command("mint <game-id> <player-id>").description("Mint additional tUSDC to a player (admin only)").requiredOption("--amount <n>", "Amount of tUSDC to mint").action(async (gameId, playerId, opts, cmd) => {
+    const res = await client(cmd).mintTusdc(gameId, playerId, parseFloat(opts.amount));
+    console.log(`Minted $${parseFloat(opts.amount).toFixed(2)} tUSDC to player ${res.player_id}`);
+    console.log(`New balance: $${res.usdc_balance.toFixed(2)}`);
+  });
+}
+export {
+  registerAdmin
+};