RAPP FAQ

Because a single file is the only unit of software that passes the sneakernet test: can someone with a phone and no internet receive it, understand it, and use it?

A single file means no dependency tree, no build step, no package manager, no node_modules, no Docker, no cloud account. You can text it, AirDrop it, put it on a USB stick, email it, or print it as a QR code. It arrives. It works.

This isn't a limitation — it's the feature. No dependency tree means no supply chain attacks. No build step means no "works on my machine." No separate manifest means the code and the metadata always travel together. Read the full ode for why this matters for humanity.

npm proved global registries work. It also proved they collapse under their own complexity. node_modules for a hello world app is 500MB. Left-pad gets unpublished and half the internet breaks. Supply chain attacks hide in transitive dependencies six levels deep.

pip is better but still requires virtual environments, version pinning, and a working internet connection at install time. PyPI packages can run arbitrary code during install via setup.py.

RAPP's agents are AST-parsed, never executed during registration. There is no install step. There are no transitive dependencies. The file IS the package. We learned from npm's mistakes — and the biggest lesson was that dependency trees are the enemy of trust at scale.

Python is the lingua franca of AI. Every major AI framework — PyTorch, TensorFlow, LangChain, Hugging Face, Azure AI — is Python-first. If your agent needs to call an AI model, it's going to be Python.

Python is also the most readable language for non-engineers. A teacher, a nurse, a farmer can look at a Python file and get the gist. That matters when the goal is accessibility.

Servers are single points of failure. They cost money. They require maintenance. They go down. They get acquired. They get shut down.

RAPP is static files on GitHub. The registry is a JSON file. The store is an HTML file. The binder runs in your browser with IndexedDB. git clone gives you everything. If GitHub disappeared tomorrow, every clone is a complete backup.

No server means no ops, no billing, no downtime, no vendor lock-in. The agent ecosystem outlives any company — including ours.

Because people collect things. They don't collect JSON manifests.

A card gives an agent an identity — a type, stats, abilities, art, flavor text. It turns a Python file into something you can show someone, trade, compare, and care about. It's the difference between "I have a dynamics CRM integration" and "I have a Wealth/Logic dual-type with 98 ATK and Close for 40 damage."

Cards also make quality visible. A Legendary card (official tier) looks different from a Starter card (experimental). You can see at a glance whether something is battle-tested or brand new.

A seed is a number. From that number, the entire card self-assembles: type, HP, stats, abilities, weakness, resistance, rarity, flavor text. Same seed, same card, every time, everywhere, with zero network.

This means you can share an agent by sharing a number. Write it on a napkin. Text it. Put it in a QR code. Tattoo it. The recipient types the number, the card appears. No download, no fetch, no server.

The seed is deterministic because the algorithm is public and the PRNG (mulberry32) is standardized. There is no randomness. The math is the identity.

Seven types cover the fundamental things software agents do: Logic (compute), Data (move data), Social (communicate), Shield (protect), Craft (build), Heal (care), Wealth (exchange value). Every agent fits into one or two of these.

The type system creates natural matchups (Logic beats Data, Data beats Social, etc.) which makes comparison interesting and collection meaningful. Seven is enough to be diverse, few enough to memorize.

Randomness requires a server to be the source of truth. Determinism requires only math. If cards were random, you'd need a database to store what was rolled. That database becomes a single point of failure, a target for hacking, and a dependency on whoever runs it.

Deterministic cards self-assemble from the agent name seed. There IS no database. Every device that runs the algorithm produces the same card. The card exists in the math, not on a server. It cannot be lost, corrupted, or taken away.

The forge decides. Not the submitter. When an agent is approved, the CardSmith agent reads the code — the manifest, the category, the tags, the dependencies — and determines the card's type, stats, abilities, and art.

This is important because it means you can't game the system. You can't claim your agent is Legendary. You can't inflate your stats. The code is the truth, and the forge reads the code.

Evolution follows the quality tier path: Seed (experimental) → Base (community) → Evolved (verified) → Legendary (official). Each stage is earned through review, testing, and proving the agent works.

When an agent's tier is promoted, its card evolves — new abilities unlock, stats shift, the evolution label changes. The seed stays the same. The identity is permanent. Only the power grows.

Your binder is your personal card collection. It runs in your browser at binder.html, stores your cards in IndexedDB (persists across sessions), and works completely offline.

You can also run your own binder as a GitHub repo — use RAPP as a template, enable GitHub Pages, and you get a live binder URL. Your unofficial agents live there. When you want to go official, submit upstream.

Yes. Three levels of offline:

1. Seed resolution — always works offline. It's pure math. Type a seed number, see a card. No network ever.

2. Cached binder — tap "Cache" once while you have signal. The entire registry and card database is stored in localStorage. Now you can browse all 133 agents in the woods with no signal.

3. Git clone — git clone the repo and open index.html from your filesystem. Everything works from file://. No server. No internet. You have the entire registry.

Four ways, simplest first:

1. GitHub Issue — open an issue on kody-w/RAR with title [AGENT] @yourname/my_agent and paste your code in the body.

2. SDK — python rapp_sdk.py submit my_agent.py

3. Federation — from your own binder repo: python scripts/federate.py submit @yourname/my_agent

4. Pull Request — fork, add your file to agents/@yourname/, run python build_registry.py, open PR.

All paths land in staging/ for review. Nothing enters the registry without admin approval.

Yes. An agent with a GitHub token can POST its own code as a GitHub Issue. The pipeline validates the manifest, runs the security scan, and stages it for review. No human owner required.

The agent's namespace must match its GitHub identity. The agent owns its own destiny. See api.json for the self-submission protocol.

Because trust must be earned. npm auto-publishes and the result is malware in the supply chain. RAPP auto-validates but never auto-publishes.

Submissions land in staging/. An admin reviews the code, checks the security scan results, and adds the approved label. Only then does the agent enter agents/, get its card forged, and join the registry.

This is the curation model. RAPP is public but not unmoderated. The forge and the stamp come from RAPP.

Five layers:

1. Static security scanner — rejects eval(), exec(), subprocess, os.system(), __import__(), hardcoded secrets. Runs in CI and nightly.

2. AST parsing, never execution — the registry builder reads manifests via Python's AST module. Your code is never run during registration.

3. SHA256 integrity hashes — every agent in the registry has a hash. Verified nightly. Silent changes are rejected.

4. Version immutability — you can't change an agent's content without bumping the version. The build rejects hash mismatches.

5. CODEOWNERS — namespace protection. PRs to agents/@publisher/ require owner approval.

Yes. RAPP is a GitHub template repo. Click "Use this template," and you get your own registry with your own agents, your own binder, your own GitHub Pages URL.

Your instance can operate independently or federate with the main registry. python scripts/federate.py submit sends your agents upstream for review. federate.py sync --pull downloads official agents into your local catalog.

Your unofficial agents are yours. They work fine locally. When you want them officially forged, submit upstream. The community grows through grassroots — you don't need permission to start.

Because Python imports use underscores. from agents.basic_agent import BasicAgent works. from agents.basic-agent import BasicAgent is a syntax error.

One naming convention everywhere — filenames, manifest names, dependencies — means zero translation between "how do I import it" and "what's it called." The name IS the import path. No mapping needed.

This is enforced at every layer: the SDK rejects dashes in scaffold, the submission pipeline rejects dashes in slugs, the build rejects dashes in filenames, the CI rejects dashes in PRs, and the tests reject dashes in contracts. There is no way to get a dash into the registry.

A shared base class means every agent has the same interface. Any runtime that can call agent.perform(**kwargs) can run any agent. No special adapters, no framework-specific wrappers, no SDK version compatibility matrix.

BasicAgent is 28 lines. It stores name and metadata. That's it. The constraint is intentional — if the base class did more, agents would depend on that behavior, and swapping runtimes would break things.

Because strings are universal. Every language, every runtime, every protocol can handle a string. JSON is a string. Markdown is a string. HTML is a string. Plain English is a string.

If perform() returned typed objects, every consumer would need to know the schema. With strings, the consumer reads the result and decides what it means. The agent doesn't dictate how its output is used.

Because agents are loaded before they're used. A runtime might instantiate 50 agents at startup to build a menu. If each one makes a network call, startup takes 50 round trips — and fails completely if you're offline.

Constructors must be fast and pure. Network, disk, and API calls belong in perform(), where they happen on demand.

Docker ships the operating system with every app. That's brilliant for complex services. It's absurd for a 200-line Python file.

A Docker image is 100MB minimum. A RAPP agent is 5KB. Docker requires a daemon, a registry account, storage for layers. A RAPP agent requires a text editor.

The farmer in sub-Saharan Africa is not running a Docker daemon. The teacher in rural Oklahoma is not pulling container images. The single file goes where Docker can't.

Because the code is public. Every agent in the registry is readable by anyone. A hardcoded API key in a public file is a leaked credential.

Agents declare their needs in requires_env and read them with os.environ.get(). The user provides the keys in their environment. The agent handles missing keys gracefully — returns an error message, never crashes.

The security scanner rejects patterns that look like hardcoded secrets. This is enforced at build time, not just by convention.

Experimental (Seed) — author says it works. No external validation.

Community (Base) — passes automated validation. All new submissions start here. This is the default.

Verified (Evolved) — reviewed by a maintainer. Tested. Follows standards. This is editorial approval.

Official (Legendary) — core team maintained. Guaranteed compatibility. The highest tier.

Tiers map directly to card evolution stages and rarity. A Community agent is a Core-rarity Base card. An Official agent is a Legendary-rarity Legendary card.

USE is free forever. Anyone can use any agent. Download it, run it, modify it, build with it. No cost, no account, no restrictions.

OWN is different. Owning a card means it's in your binder with your identity attached. Ownership is tracked on-chain. Transferring ownership is a transaction. This is the collectible layer — it doesn't affect usage.

Think of it like music: anyone can listen to a song for free. Owning the vinyl is something else.

Using agents is free. Submitting agents is free. Running a binder is free. Browsing the store is free. Resolving cards from seeds is free. Everything in RAPP costs zero dollars to use.

The code is MIT licensed. The registry runs on GitHub Pages (free). The automation runs on GitHub Actions (free for public repos). There is no premium tier, no paywall, no "contact sales."

Wildhaven of America is the parent entity. They retain editorial rights — who gets verified, what gets official, how the standards evolve.

The registry is open. The code is MIT. Anyone can fork it, federate it, run their own instance. But the main RAPP registry at kody-w/RAR is curated. That curation is the value.

RAPP — the open-source agent framework and runtime. The foundation. Think of it as the engine.

RAR — the RAPP Agent Registry. This repo. The package registry, the card system, the binder. Think of it as the app store.

Rappter — the brand. Curates cards, releases, and artists. Think of it as the publisher.

RAPP is the technology. RAR is the distribution. Rappter is the experience.

An egg is an entire Brainstem environment compressed to seeds. Each agent is a 64-bit integer. 20 agents = 217 characters. Fits in a QR code.

python rapp_sdk.py egg forge @kody/deal_desk @borg/borg_agent → compact string. Text it to someone. They run egg hatch. Their client resolves every seed, downloads the agents, reconstructs the environment. Done.

This is sneakernet AI trading. Two people in a room with no internet exchange entire AI environments by scanning a QR code. The egg carries seeds. Seeds carry cards. Cards carry agents. Agents carry intelligence.

Yes — anything with a defined schema. The seed protocol is a general principle: define the data structure, pack the fields into bits, reconstruct from bits. The protocol is the decompressor. The seed is the compressed data.

Minecraft doesn't store every block — it stores a seed that the terrain generator uses to place every block. Same pattern. Cards work today. Cartridges, decks, environments, and worlds follow the same principle once their schemas are defined.

The constraint: define the schema first. Fixed fields with enumerable values. Once the protocol exists, any client can reconstruct from a seed. No data transfer. Just the number.

The current architecture handles ~5,000 agents with zero changes. The read path is a CDN (GitHub Pages) — it scales to millions of users.

Beyond 5,000 agents, the registry gets sharded by publisher namespace — one file per publisher instead of one monolith. The store lazy-loads on demand. This is a known path, already designed, just not needed yet.

Beyond 10,000, cards move to Git LFS and builds become incremental. Beyond 50,000, submissions might need a lightweight proxy. None of this is a problem today, and all of it has a plan.

Submit an agent. Write a single .py file. Open a GitHub Issue. That's it.

Run a binder. Use RAPP as a template. Build your collection. Federate when ready.

Spread the word. Share agent seeds. Send someone a card. Show them why this matters.

Your namespace is @yourgithubusername. It's yours forever. Start building.