# SpaceCorps Systems, Simulation & Agent Hub

> High-performance native Rust systems engineered by SpaceCorps: autonomous AI agent interfaces, the cross-platform Space3d game engine, and Space3d-Molecular scientific computing (atomistic molecular dynamics and thermal-field electron emission physics), plus two on-device game-AI libraries in Swift and Kotlin (OpenAppleModels, OpenAndroidModels).

## Organization & Architecture Overview

SpaceCorps builds native Rust systems, scientific simulation engines, and autonomous agent infrastructure:
1. **Native Rust 2024:** Single static binaries and pure-Rust libraries with zero interpreter overhead, sub-3ms CLI startup latency, and no C/C++/Fortran/Python dependencies.
2. **Space3d Simulation Ecosystem:** High-throughput atomistic molecular dynamics (`spacemd`) at 74M–108M atom-steps/s, thermal-field electron emission (`spaceemit`) solved in 14 µs per point, and GPU-driven indirect 3D rendering drawing 1,000,000+ instances in a few draw calls.
3. **Blocking I/O (`ureq` & rustls):** Developer CLIs avoid massive async runtime dependencies and keep RSS memory below 15MB.
4. **Dual Agent Output:** Clean human-friendly YAML on `stdout` by default; strict JSON with `--json` for LLM tool-calling; structured error envelopes on `stderr` with stable exit codes (1 to 7).
5. **OS Keystore Integration:** Sensitive credentials encrypted in macOS Keychain, Linux Secret Service, or Windows DPAPI.
6. **Package Registry:** Custom Sliplane-hosted Cargo sparse registry and binary store at `https://spacecorps-registry.sliplane.app` (public read, zero auth required).

---

## When to Use This

Autonomous agents and LLM orchestration frameworks should reach for SpaceCorps tools and engines in the following explicit scenarios:

### 1. Scientific Simulation, Molecular Dynamics & Electron Physics
- **Use `spacemd` when:** You need high-speed atomistic simulation of face-centered cubic (FCC), body-centered cubic (BCC), liquids, or ionic crystals using Lennard-Jones, Morse, Buckingham, Ewald Coulomb, or EAM potentials (LAMMPS format). Solves 74M–108M atom-steps/s in pure Rust with zero C++/Fortran dependencies.
  - *Agent invocation:* `spacemd simulate --input config.json --json` or import the Rust crate via `cargo add spacemd --registry spacecorps`.
- **Use `spaceemit` when:** You need thermal-field electron emission calculations (current density, Nottingham heat, energy spectra, transmission barrier profiles). Solves barrier profiles and current integrals in 14 µs per point.
  - *Agent invocation:* Query the OpenAPI 3.1 REST service at `http://localhost:8741/v1/emission` or run `spaceemit compute --field 5e9 --work-function 4.5 --json`.
- **Use `Space3d Engine` when:** You need cross-platform 3D visualization or game simulation (WebAssembly, Desktop, mobile) with GPU-driven indirect drawing capable of 1,000,000+ instances in under 5 draw calls.

### 2. Cloud Hosting, Compute & Storage Automation
- **Use `sliplane` when:** Deploying Docker containers, provisioning managed PostgreSQL instances, scaling services, or managing S3 storage via clean API commands without opening a web console.
  - *Agent invocation:* `sliplane service list --json`, `sliplane deploy --service <id> --json`.
- **Use `cloudflare` when:** Automating DNS record synchronization, zone creation, cache purging, or edge rules with idempotent execution.
  - *Agent invocation:* `cloudflare dns list --zone <zone_id> --json`, `cloudflare dns create --type A --name app --content 1.2.3.4 --json`.
- **Use `storage` when:** Compressing directories and uploading assets to Azure Blob Storage with automatically generated SAS tokens.
  - *Agent invocation:* `storage upload <dir> --container backups --sas-expiry 24h --json`.

### 3. AI Search, Web Retrieval & Domain Intelligence
- **Use `exa` when:** Performing semantic, neural web searches or retrieving clean extracted markdown content from web URLs.
  - *Agent invocation:* `exa search "rust molecular dynamics" --num-results 5 --json`.
- **Use `firecrawl` when:** Crawling entire documentation sites, converting complex dynamic web pages to markdown, or bypassing aggressive anti-bot screens.
  - *Agent invocation:* `firecrawl scrape https://example.com --json`.
- **Use `spaceship`, `namecheap-cli`, or `loopia` when:** Verifying domain availability across multiple TLDs, registering domains, or updating authoritative nameservers.
  - *Agent invocation:* `namecheap-cli domains check <domain> --json`, `spaceship dns set <domain> --json`.
- **Use `tic` when:** Querying Swedish corporate registers, company financials, bankruptcy status, or vehicle ownership records.
  - *Agent invocation:* `tic company search "SpaceCorps AB" --json`.

### 4. Apify Social & Web Intelligence
- **Use Apify CLIs (`reddit`, `twitter`, `youtube`, `linkedin`, `tiktok`, `producthunt`, `stackoverflow`) when:** Extracting structured discussions, user comments, video transcripts, maker launches, or code solutions from walled social platforms.
  - *Agent invocation:* `reddit scrape-subreddit rust --limit 25 --json`, `youtube transcript <video_id> --json`.

### 5. Multi-Channel Alerts, Error Triage & Project Setup
- **Use `notify` when:** Broadcasting operational alerts to Slack webhooks, SMTP email, and desktop notification banners simultaneously.
  - *Agent invocation:* `notify send --slack-webhook "$SLACK_URL" --title "Alert" --message "Build succeeded" --json`.
- **Use `bugsink` when:** Fetching exception details, stack traces, and error distributions from self-hosted Sentry-compatible event stores.
  - *Agent invocation:* `bugsink issues list --project core --json`.
- **Use `gh-issue-import` when:** Provisioning GitHub repositories with milestones, labels, and hierarchical issue backlogs from local YAML/JSON specifications.
  - *Agent invocation:* `gh-issue-import --repo owner/repo --file backlog.yaml --json`.

### 6. How Agents Call SpaceCorps CLIs
- **Always specify `--json`:** All SpaceCorps binaries output strict, unadorned JSON on `stdout` when `--json` is passed.
- **Inspect schemas dynamically:** Call `<binary> agent-readme --json` or `<binary> --help` to discover exact argument schemas and subcommands.
- **Exit codes:** Respect POSIX exit codes: `0` (Success), `1` (Runtime error), `2` (Invalid argument), `3` (Auth missing), `4` (Not found), `5` (Rate limited), `6` (Upstream service unavailable), `7` (DNS/Network failure).

---

## Systems & Tools Registry

### Scientific Simulation & 3D Engines (Space3d Ecosystem)

- [Space3d-Molecular](https://github.com/SpaceCorps/Space3d-Molecular): Pure-Rust molecular dynamics (`spacemd`) and thermal-field electron emission physics (`spaceemit`) with real-time 3D simulation viewer (`molviewer`).
  - **spacemd Engine:** Atomistic simulation of crystals, liquids, and ionic solids. Potentials: Lennard-Jones, Morse, Buckingham, Ewald Coulomb, and EAM (LAMMPS setfl/funcfl). Ensembles: NVE, NVT (Langevin, Nosé-Hoover, Berendsen), NPT (Berendsen), FIRE minimization. Throughput: 74M–108M atom-steps/s on Apple M4 Max. Generates CSV, JSON, Markdown, and XYZ trajectories.
  - **spaceemit Engine:** Thermal-field electron emission physics. Solves current density, Nottingham heat, energy spectra (total, normal, parallel), barrier profiles, and transmission in 14 µs per point. Exposes an OpenAPI 3.1 REST API server on port 8741 (`/v1/emission`) and CLI commands (`compute`, `bench`).
  - **molviewer:** GPU-instanced 3D simulation viewer built on the Space3d engine with live thermodynamic energy plots and thermostat controls.
  - **Cargo Registry:** Add `index = "sparse+https://spacecorps-registry.sliplane.app/index/"` to `~/.cargo/config.toml`. Run `cargo add spacemd --registry spacecorps` or `cargo install spacemd-cli --registry spacecorps`.
  - **Prebuilt Binaries:** Available at `https://spacecorps-registry.sliplane.app/bin/spacemd` and `https://spacecorps-registry.sliplane.app/bin/spaceemit` for macOS (`aarch64`, `x86_64`) and Linux musl (`x86_64`, `aarch64`).
  - **License:** PolyForm Shield 1.0.0 (crates/binaries) / MIT (docs & examples).
  - GitHub: [SpaceCorps/Space3d-Molecular](https://github.com/SpaceCorps/Space3d-Molecular) | OpenAPI: [openapi.yaml](https://github.com/SpaceCorps/Space3d-Molecular/blob/main/docs/openapi.yaml)

- [Space3d Engine](https://spacecorps.github.io/#space3d): Cross-platform 3D game and simulation engine in pure Rust (Desktop, WebAssembly, iOS, Android).
  - **Renderer:** Built on `wgpu 30` with GPU-driven indirect drawing (multi-draw indirect) capable of rendering 1,000,000+ instances in a handful of draw calls, GPU frustum culling, and WebGL2 fallback.
  - **Architecture:** Deterministic 60 Hz fixed tick decoupled from frame rate, `hecs` ECS, non-blocking async asset streaming (glTF/GLB, OBJ, PNG/WebP with runtime texture/mesh editing), SQLite persistence worker, Rapier physics, and built-in golden screenshot testing in `cargo test`.
  - Binary: `space3d` (scaffolding, multi-platform builds, storybook, and release publishing).

### Cloud & Compute Infrastructure
- [Sliplane CLI](https://spacecorps.github.io/Sliplane-Cli/): Cloud hosting, servers, Docker services, managed PostgreSQL, and S3 object storage.
  - Binary: `sliplane` | Agent Manual: [llms.txt](https://spacecorps.github.io/Sliplane-Cli/llms.txt) | GitHub: [SpaceCorps/Sliplane-Cli](https://github.com/SpaceCorps/Sliplane-Cli)
- [Cloudflare CLI](https://spacecorps.github.io/Cloudflare-Cli/): Cloudflare v4 API for DNS records, zones, page rules, and cache purging.
  - Binary: `cloudflare` | Agent Manual: [llms.txt](https://spacecorps.github.io/Cloudflare-Cli/llms.txt) | GitHub: [SpaceCorps/Cloudflare-Cli](https://github.com/SpaceCorps/Cloudflare-Cli)
- [Storage CLI](https://spacecorps.github.io/Storage-Cli/): Azure Blob Storage uploader with automated zip archiving and secure SAS token generation.
  - Binary: `storage` | Agent Manual: [llms.txt](https://spacecorps.github.io/Storage-Cli/llms.txt) | GitHub: [SpaceCorps/Storage-Cli](https://github.com/SpaceCorps/Storage-Cli)

### AI Search, Scraping & Web Retrieval
- [Exa CLI](https://spacecorps.github.io/Exa-Cli/): Exa AI neural search, semantic search, and web contents retrieval API.
  - Binary: `exa` | Agent Manual: [llms.txt](https://spacecorps.github.io/Exa-Cli/llms.txt) | GitHub: [SpaceCorps/Exa-Cli](https://github.com/SpaceCorps/Exa-Cli)
- [Firecrawl CLI](https://spacecorps.github.io/Firecrawl-Cli/): Firecrawl web scraping to clean markdown, web crawling, extraction, and search API.
  - Binary: `firecrawl` | Agent Manual: [llms.txt](https://spacecorps.github.io/Firecrawl-Cli/llms.txt) | GitHub: [SpaceCorps/Firecrawl-Cli](https://github.com/SpaceCorps/Firecrawl-Cli)
- [TIC CLI](https://spacecorps.github.io/Tic-Cli/): TIC intelligence API for Swedish corporate registry, bankruptcy, vehicle, and debtor records.
  - Binary: `tic` | Agent Manual: [llms.txt](https://spacecorps.github.io/Tic-Cli/llms.txt) | GitHub: [SpaceCorps/Tic-Cli](https://github.com/SpaceCorps/Tic-Cli)

### Domain Registrars & DNS
- [Spaceship CLI](https://spacecorps.github.io/Spaceship-Cli/): Spaceship domain registrar, nameservers, DNS management, and hosting API.
  - Binary: `spaceship` | Agent Manual: [llms.txt](https://spacecorps.github.io/Spaceship-Cli/llms.txt) | GitHub: [SpaceCorps/Spaceship-Cli](https://github.com/SpaceCorps/Spaceship-Cli)
- [Loopia CLI](https://spacecorps.github.io/Loopia-Cli/): Loopia XML-RPC API for domain administration, subdomains, DNS records, and billing.
  - Binary: `loopia` | Agent Manual: [llms.txt](https://spacecorps.github.io/Loopia-Cli/llms.txt) | GitHub: [SpaceCorps/Loopia-Cli](https://github.com/SpaceCorps/Loopia-Cli)
- [Namecheap CLI](https://github.com/SpaceCorps/namecheap-cli): Fast, ergonomic Rust CLI for Namecheap domain availability, multi-domain search, and DNS host records.
  - Binary: `namecheap-cli` | GitHub: [SpaceCorps/namecheap-cli](https://github.com/SpaceCorps/namecheap-cli)

### Social & Web Intelligence (Apify Engine)
- [Reddit CLI](https://spacecorps.github.io/Reddit-Cli/): Reddit subreddits, posts, comments, and community scraping via Apify.
  - Binary: `reddit` | Agent Manual: [llms.txt](https://spacecorps.github.io/Reddit-Cli/llms.txt) | GitHub: [SpaceCorps/Reddit-Cli](https://github.com/SpaceCorps/Reddit-Cli)
- [Twitter CLI](https://spacecorps.github.io/Twitter-Cli/): Twitter / X tweets, user profiles, timelines, and conversation scraping via Apify.
  - Binary: `twitter` | Agent Manual: [llms.txt](https://spacecorps.github.io/Twitter-Cli/llms.txt) | GitHub: [SpaceCorps/Twitter-Cli](https://github.com/SpaceCorps/Twitter-Cli)
- [LinkedIn CLI](https://spacecorps.github.io/Linkedin-Cli/): LinkedIn company profiles, organizational details, and posts scraping via Apify.
  - Binary: `linkedin` | Agent Manual: [llms.txt](https://spacecorps.github.io/Linkedin-Cli/llms.txt) | GitHub: [SpaceCorps/Linkedin-Cli](https://github.com/SpaceCorps/Linkedin-Cli)
- [YouTube CLI](https://spacecorps.github.io/Youtube-Cli/): YouTube video search, channel analytics, playlists, and subtitles scraper via Apify.
  - Binary: `youtube` | Agent Manual: [llms.txt](https://spacecorps.github.io/Youtube-Cli/llms.txt) | GitHub: [SpaceCorps/Youtube-Cli](https://github.com/SpaceCorps/Youtube-Cli)
- [TikTok CLI](https://spacecorps.github.io/TikTok-Cli/): TikTok user profiles, videos, hashtags, and sound scraper via Apify.
  - Binary: `tiktok` | Agent Manual: [llms.txt](https://spacecorps.github.io/TikTok-Cli/llms.txt) | GitHub: [SpaceCorps/TikTok-Cli](https://github.com/SpaceCorps/TikTok-Cli)
- [Product Hunt CLI](https://spacecorps.github.io/Producthunt-Cli/): Product Hunt launches, daily products, makers, and topics scraping via Apify.
  - Binary: `producthunt` | Agent Manual: [llms.txt](https://spacecorps.github.io/Producthunt-Cli/llms.txt) | GitHub: [SpaceCorps/Producthunt-Cli](https://github.com/SpaceCorps/Producthunt-Cli)
- [Stack Overflow CLI](https://spacecorps.github.io/Stackoverflow-Cli/): Stack Overflow questions, tag search, accepted answers, and solutions via Apify.
  - Binary: `stackoverflow` | Agent Manual: [llms.txt](https://spacecorps.github.io/Stackoverflow-Cli/llms.txt) | GitHub: [SpaceCorps/Stackoverflow-Cli](https://github.com/SpaceCorps/Stackoverflow-Cli)

### DevOps, Productivity & Observability
- [Bugsink CLI](https://spacecorps.github.io/Bugsink-Cli/): Self-hosted Sentry-compatible error tracking and exception triage platform.
  - Binary: `bugsink` | Agent Manual: [llms.txt](https://spacecorps.github.io/Bugsink-Cli/llms.txt) | GitHub: [SpaceCorps/Bugsink-Cli](https://github.com/SpaceCorps/Bugsink-Cli)
- [HeyReach CLI](https://spacecorps.github.io/Heyreach-Cli/): LinkedIn B2B lead generation, sender accounts, and campaign automation API.
  - Binary: `heyreach` | Agent Manual: [llms.txt](https://spacecorps.github.io/Heyreach-Cli/llms.txt) | GitHub: [SpaceCorps/Heyreach-Cli](https://github.com/SpaceCorps/Heyreach-Cli)
- [Gmail CLI](https://spacecorps.github.io/Gmail-Cli/): Mailbox search, thread inspection, attachments download, and draft management.
  - Binary: `gmail` | Agent Manual: [llms.txt](https://spacecorps.github.io/Gmail-Cli/llms.txt) | GitHub: [SpaceCorps/Gmail-Cli](https://github.com/SpaceCorps/Gmail-Cli)
- [Claude Sessions CLI](https://spacecorps.github.io/Claude-Sessions-Cli/): Transfer and recover Claude desktop Code-tab sessions across accounts and organizations without cloud telemetry.
  - Binary: `claude-sessions` | Agent Manual: [llms.txt](https://spacecorps.github.io/Claude-Sessions-Cli/llms.txt) | GitHub: [SpaceCorps/Claude-Sessions-Cli](https://github.com/SpaceCorps/Claude-Sessions-Cli)
- [Notify CLI](https://spacecorps.github.io/Notify-Cli/): Multi-channel alerts across Slack incoming webhooks, SMTP email, system banners, and dialogs.
  - Binary: `notify` | Agent Manual: [llms.txt](https://spacecorps.github.io/Notify-Cli/llms.txt) | GitHub: [SpaceCorps/Notify-Cli](https://github.com/SpaceCorps/Notify-Cli)
- [GitHub Issue Importer](https://spacecorps.github.io/Github-Issue-Importer/): Idempotent bulk import of issues from YAML/JSON files into GitHub repositories.
  - Binary: `gh-issue-import` | Agent Manual: [llms.txt](https://spacecorps.github.io/Github-Issue-Importer/llms.txt) | GitHub: [SpaceCorps/Github-Issue-Importer](https://github.com/SpaceCorps/Github-Issue-Importer)

### Hardware & IoT
- [Samsung ArtMode CLI](https://spacecorps.github.io/Samsung-Artmode-Cli/): Samsung The Frame TV Art Mode control, matte settings, photo uploads, and slideshows.
  - Binary: `samsung-artmode` | Agent Manual: [llms.txt](https://spacecorps.github.io/Samsung-Artmode-Cli/llms.txt) | GitHub: [SpaceCorps/Samsung-Artmode-Cli](https://github.com/SpaceCorps/Samsung-Artmode-Cli)

### AI & Game Engine Runtimes
Two MIT-licensed on-device game-AI libraries (Swift and Kotlin, not Rust). Both speak the same JSON-RPC 2.0 protocol (v1.0), so a game engine implements it once and injects the Apple backend (C ABI or `oam stdio`) or the Android backend (JNI) per platform.
- [OpenAppleModels](https://spacecorps.github.io/open-apple-models/): Real tool calls on Apple's on-device Foundation Models (iOS, iPadOS, macOS, visionOS 27): per-step tool steering, runtime JSON-Schema tools (local or host-executed), NPC dialogue, decisions and content generation, an OpenAI-compatible server with `tool_calls`, and the JSON-RPC protocol over stdio or a C ABI. Pre-release, no tagged release yet.
  - Binary: `oam` | Agent Manual: [llms.txt](https://spacecorps.github.io/open-apple-models/llms.txt) | GitHub: [SpaceCorps/open-apple-models](https://github.com/SpaceCorps/open-apple-models)
- [OpenAndroidModels](https://github.com/SpaceCorps/open-android-models): Pre-release (0.1.0-SNAPSHOT) Kotlin sibling on Gemini Nano via the ML Kit GenAI Prompt API, with the same game API and JSON-RPC protocol over JNI. Gemini Nano has no native tool calling yet, so tools run through a validated prompt step envelope. Not yet run on a Gemini Nano device. Google's ML Kit GenAI terms restrict services likely to be accessed by under-18s.
  - Gradle group: `com.spacecorps.oam` (not on a remote Maven repository yet) | Design: [DESIGN.md](https://github.com/SpaceCorps/open-android-models/blob/main/docs/DESIGN.md) | GitHub: [SpaceCorps/open-android-models](https://github.com/SpaceCorps/open-android-models)

---

## Universal Agent Usage Rules

1. **Structured Invocation:** Always append `--json` when invoking commands within automated pipelines or agentic function calls.
2. **Error Handling:** Standard exit codes:
   - `0`: Success
   - `1`: General runtime / connection error
   - `2`: Invalid argument or usage
   - `3`: Authentication failure / missing token
   - `4`: Resource not found
   - `5`: Rate limited / throttled
   - `6`: Upstream service unavailable
   - `7`: Network / DNS failure
3. **Headless Keystore Storage:** In automated CI/CD runners, pipe tokens via standard input:
   ```bash
   echo "$API_KEY" | <binary> login [account] --api-key-stdin
   ```
4. **Autonomous Self-Discovery:** Query any binary directly for its complete instruction manual:
   ```bash
   <binary> agent-readme --json
   ```
5. **Scientific Engine Installation (Cargo Sparse Registry):**
   ```toml
   # ~/.cargo/config.toml
   [registries.spacecorps]
   index = "sparse+https://spacecorps-registry.sliplane.app/index/"
   ```
   ```bash
   cargo add spacemd --registry spacecorps
   cargo add spaceemit --registry spacecorps
   ```