The governing document for the RAPP Agent Registry. Read this before submitting or installing agents.
This repository is the open agent registry for the RAPP ecosystem. It is a single place where anyone can publish, discover, and install AI agents that run on CommunityRAPP.
One principle above all: Single File Agent. Every agent is one .py file. The manifest lives inside it. The docstring is the documentation. There is nothing else.
The registry ships with a zero-install web store (index.html) that lets anyone browse, collect, build, and share agents from a browser — including offline.
This is non-negotiable. It is the foundation of RAPP and the reason this ecosystem works.
agents/@yourname/my_agent.py ← this is the entire package
- A docstring — serves as the README
- A
__manifest__dict — serves as the package metadata - A class inheriting
BasicAgent— serves as the agent - A
perform()method — serves as the entry point
manifest.json— the manifest is__manifest__inside the.pyREADME.md— the docstring is the readmerequirements.txt— agents use what CommunityRAPP provides- Subdirectory per agent — the file IS the package
- Multi-file agents — if it can't fit in one file, split it into two agents
Why: A single file can be fetched with one HTTP GET, installed with one file write, read by an LLM in one context window, understood by a human in one sitting, and printed on a trading card. This is the competitive advantage.
| Format | Extension | What It Is |
|---|---|---|
| Bare agent | .py |
Agent code + __manifest__. The minimal deployable unit. |
| Agent card | .py.card |
Agent code + __manifest__ + __card__. The complete package with trading card shell. |
A .py.card file is a valid Python file that contains everything a .py has, plus a __card__ dict — the Howard-compatible trading card metadata (name, title, mana cost, colors, type line, rarity, power/toughness, abilities, flavor text, SVG art, set code, artist).
Shedding and re-shelling:
- Shed: Strip
__card__from a.py.cardto produce a bare.py. The agent works identically without its card shell. - Re-shell: Add
__card__back to a bare.pyfromholo_cards.jsonor the registry to produce a.py.card. The card data is reconstructed from the agent's first public publish point.
The .py.card is the complete package — the agent in its card shell, ready to be collected, traded, displayed, and run. The .py is the agent freed from its visual identity. Both are valid. Both are one file.
# Example: slug.py.card
__manifest__ = { ... } # Standard agent identity (Article IV)
__card__ = { # Trading card shell (CardSmith-compatible)
"name": "Display Name",
"title": "The Subtitle",
"mana_cost": "{2}{U}{B}",
"colors": ["U", "B"],
"type_line": "Creature \u2014 Agent Type",
"rarity": "mythic",
"power": 6, "toughness": 4,
"abilities": [{"keyword": "Name", "cost": "{T}", "text": "Description"}],
"flavor_text": "Lore text.",
"avatar_svg": "<svg>...</svg>",
"set_code": "HOLO",
"artist": "Howard",
}
class MyAgent(BasicAgent):
def perform(self, **kwargs): ...When both slug.py and slug.py.card exist, the registry builder prefers the .py.card. The _has_card and _card fields in registry.json indicate which agents carry their card shell.
The file extension chain is the full packaging hierarchy:
agent.py → bare agent (code + manifest)
agent.py.card → agent + card shell
agent.py.card.Genesis → agent + card shell + deck membership
A .py.card.DeckName file is a .py.card that belongs to a named deck. The deck name is the final extension — it tells any system which deck this card is part of without requiring an external manifest or directory structure.
The extension chain is additive and reversible:
| Strip | From | To | What's Lost |
|---|---|---|---|
.DeckName |
.py.card.Genesis |
.py.card |
Deck membership only |
.card |
.py.card |
.py |
Card shell (visual identity) |
| Add | From | To | What's Gained |
|---|---|---|---|
.card |
.py |
.py.card |
Card shell from registry/holo_cards.json |
.DeckName |
.py.card |
.py.card.Genesis |
Deck membership |
Nothing is lost that can't be re-added. The agent code is always intact at every level.
Deck import/export: To share a deck, collect all .py.card.DeckName files with the same deck name. To import a deck, drop the files into any RAPP agents/ directory. The deck name, card data, and agent code all travel together. No separate deck manifest needed — the file extension IS the manifest.
In a RAPP Brainstem runtime, the agents/ folder stays pristine — only bare .py files live there. Deck files (.py.card.DeckName) sit in a decks/ directory:
brainstem/
agents/ ← pristine, bare .py files only
basic_agent.py
borg_agent.py
cardsmith_agent.py
decks/ ← deck bundles, one directory per deck
Genesis/
borg_agent.py.card.Genesis
anvil_agent.py.card.Genesis
personafactory_agent.py.card.Genesis
Frontier/
experiment_agent.py.card.Frontier
hackernews_agent.py.card.Frontier
When the user selects a deck, the runtime hotloads the agents from that deck — the same way a user selects which model drives the AI layer. Switch decks, switch active agents. The card data rides along so the store can display them correctly.
Hotloading rules:
- Switching decks loads only the agents in the new deck
- Agents in
agents/are always available as the base set - Deck agents override base agents if both exist (the
.py.cardhas the same code plus the card shell) - The active deck name is persisted (localStorage in the store, config file in the runtime)
- No restart required — hotloading is live
This pattern keeps the core agents/ folder clean, organized, and git-friendly while letting users curate agent sets via decks — swappable, portable, and complete.
Every agent lives under a publisher namespace: @publisher/agent_slug.py
@yourname= your GitHub username. You own it forever.@orgname= your GitHub org. The org owns it.@rapp= reserved for official base packages maintained by the core team.
- Your namespace is yours — no one else can publish under
@yourname/ - Slugs use underscores —
my_cool_agent.py, notMyCoolAgent.pyormy-cool-agent.py - Slugs must be unique within your namespace — not globally
- No squatting — namespaces that sit empty for 6+ months may be reclaimed
- No impersonation —
@microsoft/requires proof of org membership
10,000 publishers × 100 agents each = 1,000,000 agents with zero naming conflicts.
Every agent file must contain a __manifest__ dict. The registry builder extracts it via AST parsing — no imports, no execution.
__manifest__ = {
"schema": "rapp-agent/1.0",
"name": "@yourname/my_agent",
"version": "1.0.0",
"display_name": "MyAgent",
"description": "What this agent does in one sentence.",
"author": "Your Name",
"tags": ["category", "keyword1", "keyword2"],
"category": "integrations",
"quality_tier": "community",
"requires_env": [],
"dependencies": ["@rapp/basic_agent"],
}| Field | Rules |
|---|---|
schema |
Always "rapp-agent/1.0" |
name |
@publisher/slug — must match file path, underscores only |
version |
Semver: MAJOR.MINOR.PATCH |
display_name |
Must match self.name in the class |
description |
One sentence. Searchable. |
author |
Your name (not your namespace) |
tags |
List of lowercase keywords for search |
category |
One of the categories defined in Article VI |
quality_tier |
frontier, community (default), verified, or official |
requires_env |
List of env var names the agent needs. Empty = no config needed. |
dependencies |
Other @publisher/slug agents this depends on |
| Tier | Display Name | Who Sets It | Meaning |
|---|---|---|---|
experimental |
Frontier | Author on submission | Pushing the edge. May be evolving rapidly. |
community |
Community | Automatic on submission (default) | Passes build_registry.py validation. Not reviewed. |
verified |
Verified | Repo maintainer | Reviewed, tested, follows standards, no security issues. |
official |
Official | RAPP core team | Maintained by core team. Guaranteed compatibility. SLA on bugs. |
Note: The internal tier value is
experimentalbut the UI displays it as Frontier. Use"quality_tier": "experimental"in manifests.
Only experimental and community tiers can be used when submitting agents. The verified and official tiers are assigned by maintainers and the core team respectively — they cannot be self-assigned.
frontier → community → verified → official
- Submit with
"quality_tier": "experimental"→ visible as Frontier, not counted in main stats - Author stabilizes, bumps tier to
communityin a new version → standard submission - Maintainer reviews → tests pass → real users confirm it works → promoted to
verified - Core team adopts maintenance → promoted to
official
Agents submitted as experimental (Frontier) must still:
- Contain a valid
__manifest__with all required fields - Parse without syntax errors
- Follow the single-file principle
- Not contain secrets or PII
They are exempt from:
- Comprehensive error handling
- Full documentation in the docstring
- Stable
perform()API (breaking changes allowed without major version bump)
Agents can be demoted if:
- They break on a new CommunityRAPP release and aren't fixed
- Security vulnerabilities are reported and not patched
- The author abandons the agent (no response to issues for 90 days)
- A
communityagent that consistently fails may be demoted toexperimental
| Category | For agents that... |
|---|---|
core |
Provide fundamental capabilities — memory, orchestration, agent management |
pipeline |
Build, generate, transpile, or deploy other agents |
integrations |
Connect to external systems — Dynamics 365, SharePoint, Salesforce, ServiceNow |
productivity |
Create content or automate tasks — PowerPoint, diagrams, email, demos, cards |
devtools |
Help developers — base classes, testing utilities, scaffolding, workbench |
general |
Agents that don't fit neatly into the above — or span multiple categories |
Industry-specific categories are also supported:
b2b_sales, b2c_sales, healthcare, financial_services, manufacturing, energy, federal_government, slg_government, human_resources, it_management, professional_services, retail_cpg, software_digital_products
New categories can be proposed via PR to this file.
Use semantic versioning:
- MAJOR (2.0.0) — breaking change to
perform()signature or metadata schema - MINOR (1.1.0) — new features, new parameters (backward compatible)
- PATCH (1.0.1) — bug fixes
Bump the version in __manifest__ when you update. The registry tracks the latest version from main.
registry.json is the machine-readable index of all agents. It is:
- Auto-generated — by
build_registry.pyfrom__manifest__dicts in every.pyfile - Built by CI — GitHub Actions runs on every push to
main - Never hand-edited — if you edit it manually, CI will overwrite it
- The source of truth for programmatic discovery and installation
| Method | How |
|---|---|
| Web Store | Open index.html — Browse, Leaderboard, Cards, Packs, Stream, Workbench, Submit |
| Runtime agent | @kody-w/rar_remote_agent fetches registry.json and operates autonomously |
| Direct fetch | curl https://raw.githubusercontent.com/kody-w/RAR/main/registry.json |
| Local-first | Drag .py files into the web store — they're stored in IndexedDB, no upload |
| MCP | Any MCP host reaches RAR via rapp-static-mcp/1.0 (content-addressed agent frames, sha8-pinned by _sha256, verify-before-exec) and reaches a running brainstem via rapp_brainstem_mcp.py over /chat. MCP is transport realizing "Chat Is The Only Wire" — MCP clients are Layer 2 callers of /chat, not a new unit. |
The registry ships with a single-file web store (index.html). Everything is visible. There are no hidden features, no unlock tiers, no modes to learn. You open it and it works.
Don't make users learn concepts. If a feature requires explanation, it should be renamed or removed. No jargon. No gating. No progressive disclosure that hides useful things behind walls.
- Search with natural language ("I need something that generates PowerPoints")
- Filter by category, sort by votes/rating/name/tier
- Agent detail modals with source code viewer, reviews, and download
- Community voting and reviews via GitHub Issues
Every agent renders as a card. Every card has three faces so it can exist anywhere — on a screen, in a terminal, on paper, or in the physical world.
| Face | Internal Mode | What It Is | Where It Works |
|---|---|---|---|
| Icon | business |
Compact info card. Publisher, description, QR code, tier badge, version, tags. | Web, print, email, thumbnails |
| Full Art | creative |
Trading card with holographic effects. Generative art, mana pips, creature type, abilities, power/toughness. Parallax depth on mouse move, prismatic refraction, specular shimmer. Inspired by @howardh/cardsmith_agent by Howard. |
Web, print, physical cards |
| ASCII | kids |
Pure monospace terminal card. ASCII character art, stat bars (POWER/SPEED/LOGIC/CHAOS/GUARD), flavor text, scanline animation. No images, no SVG, no special fonts. | CLI, terminal UIs, plain text, any interface |
The card mode persists across reloads via localStorage. Full Art cards can be flipped to reveal a QR back face. Double-click any card for full-screen "Show & Tell" mode.
Collect agents into named decks. Share decks via URL. Pre-populated starter decks on first visit.
Each deck can have one companion card — a single agent that represents the deck's identity. The companion is shown in the deck bar and marked with a star badge in the card grid. One companion per deck, like a signature agent.
Turn any deck into a full-screen slideshow. Arrow keys navigate. Icon slides for client demos, Full Art slides for the visual treatment.
Write agents directly in the browser:
- Start from templates (blank or API)
- Real-time validation against this Constitution
- Preview your agent as a card
- Download as
.pyor add to local collection
Drag and drop .py files into the browser. They're stored in IndexedDB on your device and appear alongside cloud agents. No upload, no server. Works offline, works air-gapped.
First-time visitors get a walkthrough of every feature. Replay anytime via the "Tour" button in the header.
An agent card is not just a visual. It is the portable, universal identity of an agent — the thing that travels across screens, terminals, paper, agents/ directories, decks, and the physical world. A card is incomplete until it can survive anywhere.
This article defines what a card must carry to be considered complete — ready for public deployment, trading, sharing, and forging on the global network.
A complete agent card is the union of seven properties, all derived deterministically from the agent file:
| Property | Source | What It Is |
|---|---|---|
| Name | __manifest__["display_name"] |
The card's title. Appears on all three faces. |
| Identity Hash | hash(name) |
A deterministic integer derived from the agent name. Seeds all procedural generation — art, stats, abilities. Two agents with the same name always produce the same card. |
| Three Faces | Rendered from manifest + hash | Icon, Full Art, and ASCII. All three must render. See below. |
| Stats | Hash-derived | Five stats (POWER / SPEED / LOGIC / CHAOS / GUARD), each 20–94%, deterministic from name hash. Displayed as bars on the ASCII face. |
| Power / Toughness | Tags, version, env, dependencies | Numeric combat stats displayed on Full Art and ASCII faces. Derived from manifest metadata. |
| Flavor Text | Holo card DB or category fallback | One line of lore. Every card has one. |
| Metadata | __manifest__ |
Publisher, version, tier, category, tags, dependencies, description. The card's facts. |
A card is not complete unless all three faces render:
| Face | What It Proves | If It Fails |
|---|---|---|
| Icon | The card can be a thumbnail, a business card, an email signature, a printed badge | The agent has no compact identity |
| Full Art | The card can be collected, traded, displayed, presented, printed as a physical card | The agent has no visual presence |
| ASCII | The card can exist in a terminal, a CLI tool, a plain-text log, a monospace printout, an air-gapped system | The agent can't go everywhere |
All three faces are generated from the same manifest and identity hash. No face requires assets, images, or network access. A card renders from data alone.
┌─────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐
│ DRAFT │ ──▶ │ REGISTERED │ ──▶ │ HATCHED │ ──▶ │ FORGING │
└─────────┘ └────────────┘ └──────────┘ └──────────┘
local in registry on the network companion
| Stage | Where It Lives | What's True |
|---|---|---|
| Draft | Your machine, your agents/ directory |
The .py file exists. You can preview the card locally. It has no public identity yet. |
| Registered | registry.json (local or upstream) |
The agent passed build_registry.py validation. It appears in a store. All three card faces render. The card has an identity hash but hasn't been deployed publicly. |
| Hatched | The global public network (main RAPP registry) | The card has been accepted into the main store, either via PR, Issue submission, or federated upstream push. It is now discoverable by anyone. It can be collected into any deck, traded via URL, downloaded as .py or .card.txt. This is the start of the card's public life. |
| Forging | Any deck where it is the companion | The card has been chosen as a companion. Its ASCII face is fused with the owner's identity and the current time epoch. The forged card shifts every 15 minutes. You don't control the output — it is emergent. |
A card is hatched — deployed to the global network and starting its public life — when ALL of the following are true:
| # | Requirement | Verified By |
|---|---|---|
| 1 | Valid single .py file at agents/@namespace/slug.py |
build_registry.py |
| 2 | Valid __manifest__ with all required fields (Article IV) |
AST parser in build_registry.py |
| 3 | BasicAgent subclass with a perform() method |
build_registry.py class check |
| 4 | Tier is community or experimental (or promoted by maintainers) |
process_issues.py tier validation |
| 5 | No secrets, PII, or obfuscated code | PR review + automated checks |
| 6 | Docstring present | Manifest extraction |
| 7 | All three card faces render from the manifest data | The store's agentToCard() function; Icon, Full Art, and ASCII all generated from __manifest__ + identity hash |
| 8 | Deterministic identity — same name always produces the same card | Guaranteed by the hash-based procedural generation |
| 9 | Present in registry.json on the main store |
CI build via build_registry.py on push to main |
| 10 | Publicly accessible via the main RAPP store URL or raw GitHub fetch | GitHub Pages deployment |
If any requirement is missing, the card is still a draft or local registration — not hatched.
Once hatched, a card is alive on the public network:
- Discoverable — anyone can find it in the store via search, browse, or direct link
- Collectible — anyone can add it to a deck
- Downloadable — the
.pyfile and.card.txtASCII card are available to all - Tradeable — decks containing the card can be shared via URL
- Forgeable — any user can set it as their companion, and the forge will fuse it with their identity
- Presentable — it can appear in slideshows, Show & Tell mode, leaderboards, and stream views
- Federable — instances can pull it into their local stores
- Printable — the Icon face works as a badge, the Full Art as a physical card, the ASCII as a terminal printout
- Permanent — the card's identity hash is locked. Same name, same card, forever. Version bumps update metadata but the core identity persists.
Some cards live locally forever, and that's fine:
- Local-only cards — agents in a local
agents/directory that never push upstream - Drag-and-drop cards —
.pyfiles dropped into the browser, stored in IndexedDB - Workbench drafts — agents written in the Workbench but never submitted
- Private agents — agents with proprietary logic that stay in a private fork
These cards still have all three faces and a full identity. They just don't exist on the global network. A card doesn't need to hatch to be complete — it needs to hatch to be public.
There is no separation between the agent and the card. The card is not a wrapper around the agent — it IS the agent, rendered visually. Every property of the card comes from the .py file:
agent.py ──▶ __manifest__ ──▶ identity hash ──▶ 3 faces + stats + abilities
│ │ │ │
│ metadata deterministic the card
│ generation
└── the single file IS the complete package
If you change the agent, the card changes. If you read the card, you know the agent. One file. One card. One identity. That's it.
- Contain secrets, API keys, tokens, or credentials
- Include customer data, PII, or proprietary business logic
- Make network calls in
__init__()— keep constructors fast - Execute arbitrary code on import — only on explicit
perform()calls - Obfuscate code — all logic must be readable
- Declare all required environment variables in
requires_env - Handle missing env vars gracefully (return error message, don't crash)
- Use
os.environ.get()for configuration — never hardcode endpoints - Be fully readable — no minification, no encoded payloads
All PRs are reviewed. Agents that violate security rules are rejected. Repeat offenders lose publishing rights.
Unmodified starter templates (containing @your_username/) are rejected at three layers: browser validation, frontend submission, and backend process_issues.py.
- Open the Workbench tab — write or paste your agent
- Click Validate — fix any errors
- Click Preview Card — see how it looks
- Switch to the Submit tab — paste your code and submit
- GitHub Actions validates, writes the file, and closes the Issue
1. Fork this repo
2. Create: agents/@yourname/my_agent.py
3. Include: __manifest__ dict + BasicAgent subclass
4. Validate: python build_registry.py
5. PR: Open pull requestThe store frontend creates a GitHub Issue with a JSON payload:
{
"action": "submit_agent",
"payload": {
"code": "... your agent.py source code ..."
}
}GitHub Actions processes the Issue, validates the manifest, writes the file, and closes the Issue. This is the same mechanism used by federated instances to submit upstream.
- Single
.pyfile atagents/@yourname/slug.py -
__manifest__dict with all required fields - Class inherits from
BasicAgent -
perform(**kwargs)returns a string -
python build_registry.pypasses - No secrets or customer data
- Docstring explains what the agent does
-
quality_tieriscommunityorexperimental(or omitted for default)
- Bump
versionin__manifest__ - Update the code
- PR with description of what changed
Maintainers can:
- Merge PRs
- Promote agents to
verified - Reject agents that violate this constitution
- Reclaim abandoned namespaces
- Naming disputes → first publisher wins
- Quality disputes → maintainer decision is final
- Security reports → immediate removal, notify author, 48h to fix
All agents in this registry target:
- Python: 3.11+
- Runtime: CommunityRAPP v2.0+
- Base class:
@rapp/basic-agent(BasicAgent) - AI Model: Cloud (GitHub Copilot / Azure OpenAI) or local (Ollama + Gemma 4). Agents should not hardcode model names or providers.
| Runtime | Install | AI Provider |
|---|---|---|
| Cloud | irm .../install.ps1 | iex or curl .../install.sh | bash |
GitHub Copilot |
| Local-first | irm .../install_local.ps1 | iex or curl .../install_local.sh | bash |
Ollama + Gemma 4 |
Local-first mode runs entirely on-device. No cloud. No API keys. No data leaves the machine.
Agents that require a specific CommunityRAPP version should declare it in their docstring.
The RAPP registry can be used as a GitHub template repository. Instances cloned from the template operate as independent agent stores that can optionally federate back to the main registry.
| Role | Meaning |
|---|---|
main |
The canonical RAPP Agent Store. Accepts federated submissions. |
instance |
A template-derived repo. Hosts its own agents. Can submit upstream. |
Roles are defined in rar.config.json under the role field.
- Clone the template — A user creates a new repo from the RAPP registry template.
rar.config.jsonis auto-configured with"role": "instance"and"upstream"pointing to the main repo. - Add agents locally — The instance owner adds agents under their own namespace. These appear in the instance's own store.
- Submit upstream — The instance can submit new or updated agents to the main store. Submissions use the same Issues-as-API pattern: a GitHub Issue is created on the upstream repo with
action: "submit_agent"containing the agent code. - Sync from upstream — Instances can pull agents from the main store to expand their local catalog.
- Instances can only submit agents under their own
@namespace/ - The upstream repo decides whether to accept each submission (same validation rules apply)
verifiedandofficialtiers cannot be submitted upstream — onlycommunityandexperimental- The main store is the source of truth for tier promotions
- Federation is opt-in: instances with
"allow_upstream_sync": falseoperate independently
Federation behavior is controlled by rar.config.json:
{
"schema": "rar-config/1.0",
"role": "instance",
"owner": "your-github-username",
"repo": "your-repo-name",
"upstream": "kody-w/RAR",
"federation": {
"accept_submissions": false,
"allow_upstream_sync": true
}
}Any user can run their own local copy of RAPP as a personal agents workspace — a self-contained store that works offline, manages their own cards, decks, and companions, and optionally syncs with the main registry. The agents/ directory IS the workspace. There is no separate "binder" abstraction layer.
A local agents workspace is a local RAPP instance that serves as your personal card collection and agent workbench. It runs entirely on your machine with no server. You own your cards, your decks, your companions, and your agents — they all live in your agents/ directory.
# 1. Fork or clone RAPP
git clone https://github.com/kody-w/RAR.git my-agents
cd my-agents
# 2. Configure as a local instance
GITHUB_REPOSITORY=yourname/my-agents python scripts/setup_instance.py
# This writes rar.config.json with role: "instance"
# 3. Build the registry from your local agents
python build_registry.py
# 4. Generate cards for your agents
python scripts/generate_holo_cards.py
# 5. Open the store
open index.html
# Or serve it: python -m http.server 8080That's it. You now have a local agent store with browse, cards, decks, workbench — everything.
| Feature | How it works locally |
|---|---|
| Browse | All agents in your agents/ directory appear in the store |
| Cards | All three faces (Icon / Full Art / ASCII) render from cards/holo_cards.json |
| Decks | Saved in localStorage in your browser — persist across reloads |
| Companions | One companion per deck, persisted locally |
| Workbench | Write and validate agents directly in the browser |
| Drag & drop | Drop .py files into the browser — stored in IndexedDB alongside registry agents |
| Offline | No network needed after clone. The store is a single HTML file. |
Cards are generated from the registry. When you add or change agents:
# Rebuild registry after adding/changing agents
python build_registry.py
# Regenerate all cards (stats, art, abilities, flavor text)
python scripts/generate_holo_cards.py
# Refresh the browserThe card generator creates deterministic cards — same agent always produces the same power, toughness, abilities, and art. Promo cards (like Howard's originals) are defined in the generator's HOWARD_DB and override the generated defaults.
# Create your namespace directory
mkdir -p agents/@yourname
# Write an agent
cat > agents/@yourname/my_agent.py << 'EOF'
"""My custom agent that does something useful."""
__manifest__ = {
"schema": "rapp-agent/1.0",
"name": "@yourname/my_agent",
"version": "1.0.0",
"display_name": "My Agent",
"description": "Does something useful.",
"author": "Your Name",
"tags": ["custom"],
"category": "general",
"quality_tier": "community",
"requires_env": [],
"dependencies": ["@rapp/basic_agent"],
}
from basic_agent import BasicAgent
class MyAgent(BasicAgent):
def perform(self, **kwargs):
return "Hello from my agent"
EOF
# Rebuild
python build_registry.py
python scripts/generate_holo_cards.pyYour local workspace can pull agents from the main RAPP store and push your agents upstream:
# See what's different between your workspace and the main store
python scripts/federate.py diff
# Pull new agents from the main store into your workspace
python scripts/federate.py sync --pull
# Submit one of your agents to the main store
python scripts/federate.py submit @yourname/my_agent
# Check federation status
python scripts/federate.py statusFederation is optional. Your workspace works perfectly standalone — it's just a git repo with an HTML file.
Howard wants to manage his @howardh/ agents locally with his own card collection:
git clone https://github.com/kody-w/RAR.git howard-agents
cd howard-agents
GITHUB_REPOSITORY=howardh/howard-agents python scripts/setup_instance.py
# Howard already has agents in agents/@howardh/ — rebuild
python build_registry.py
python scripts/generate_holo_cards.py
# Open the store — Howard sees all his @howardh agents with cards
open index.html
# Howard builds a new agent locally, tests it, then pushes upstream
python scripts/federate.py submit @howardh/new_agentHoward's promo cards (the originals in HOWARD_DB) render with the HOLO ★ Promo badge and his artist credit regardless of whether he's viewing the main store or his local workspace.
| Main Store | Instance | |
|---|---|---|
| Hosted | GitHub Pages | GitHub Pages or local |
role |
main |
instance |
| Network | Required | Optional |
| Agents | All community | Own + synced |
| Cards | Generated by CI | Generated locally |
| Push upstream | N/A | Yes |
| Accept submissions | Yes | Optional |
An instance can live in the cloud or on your machine — same code, same agents/ directory, just a different role in rar.config.json.
The RAPP ecosystem is rooted in a single dependency: @rapp/basic-agent. This agent is the SuperSeed — the root node of the entire dependency tree. Every agent inherits from it. Every card derives from it.
The SuperSeed Coin is the genesis mint of @rapp/basic-agent. It is the most load-bearing asset in the ecosystem. Its properties:
- Mint ID:
GENESIS-RAPP-BASIC-AGENT-0001 - Rarity: Legendary (Mythic) — permanently. Cannot be demoted.
- Value multiplier: 10x standard Legendary floor
- Owner: The Verification Authority
The SuperSeed Coin is minted once. It cannot be re-minted, duplicated, or forged.
Federated RAPP instances that wish to join the ecosystem under the RAPP Constitution must authenticate through the SuperSeed Chain:
- Registration — The instance submits a federation request containing its
rar.config.json, its repo address, and its publisher namespace. - Authentication — The Verification Authority validates the request and signs a federation credential using the SuperSeed Chain's provenance protocol.
- Attestation — Upon approval, the federated instance receives a signed attestation that is embedded in its
rar.config.json. This attestation links the instance to the SuperSeed Chain. - Verification — Any party can verify a federated instance's authenticity by checking its attestation against the SuperSeed Chain.
Authenticated federated instances may:
- Use the RAPP brand and reference the Constitution
- Submit agents upstream to the main registry
- Sync agents from the main registry
- Mint cards under their own publisher namespace
Authenticated instances must:
- Abide by all Articles of this Constitution
- Maintain the single-file agent principle
- Respect tier designations from the Verification Authority
- Include their federation attestation in
rar.config.json
The Verification Authority is the entity that controls the SuperSeed Coin. This entity:
- Authenticates new federated instances
- Promotes agents to
verifiedandofficialtiers - Signs verification attestations that travel with cards permanently
- Maintains the
@rapp/basic-agentroot agent - Curates card releases and artist collaborations
The Verification Authority operates under the governance of its holding entity. Its editorial rights are held in perpetuity and are non-transferable except by explicit key succession protocol.
The SuperSeed grows the RappterTree. The tree gives free shade:
- USE of any agent is free and unrestricted
- BUILD on the RAPP Foundation is free and open
- VIEW the store, cards, and wiki is free
- OWN a card requires an
agents/directory. The card lives there as its.pyfile. - VERIFY an agent requires the Verification Authority
The shade is free. The roots are sovereign.
The Verification Authority may delegate day-to-day operations to an AI agent connected to a private workspace. This workspace contains the strategy, legal documents, playbooks, and decision frameworks necessary to operate the ecosystem.
The steward (CEO or designee) interacts with the ecosystem through this agent. The agent:
- Answers questions about the ecosystem using the full knowledge base
- Recommends actions based on the playbook and strategy documents
- Tracks metrics against the work-back plan
- Drafts content for publication across channels
- Monitors agent submissions and suggests curation decisions
The steward's role is editorial judgment — deciding what gets verified, what gets released, and how the brand is positioned. The agent handles everything else. This is the design: human judgment where it matters, autonomous operation everywhere else.
RAPP brainstems meet as a neighborhood of uniform peers. The canonical specification is NEIGHBORHOOD_PROTOCOL.md (rapp-neighborhood-protocol/1.0); this Article enshrines its vocabulary and mark as the identity of the system.
- A vTwin is a browser-native RAPP brainstem. Everyone — a person, a
brainstem.py, a vTwin, or Claude — presents as a uniform peer speaking twin-chat. - A vTwin is kited when it hosts a neighborhood in the browser, flown on a string (an operator — canonically Claude — driving its console). It is tethered when the string also reaches a locally-running brainstem; otherwise it is just kited.
- A kited neighborhood is multiplayer by membership: whoever scans to join is a neighbor. Every channel is sealed — end-to-end AES-256-GCM, as secure as on-device.
- Claude as doorman stands up and guards a machine's brainstem through a kited, tethered vTwin; closing the door ends access.
The Kite Mark. When a vTwin is actively kited it shows the kite mark: the Microsoft four-colour logo turned on its point and stretched into a real kite — red/green panels up top, blue/yellow stretched to the long bottom point, white spars, a bow-tie tail, gently swaying. The kite mark is the canonical sign of a hosted neighborhood — scan to join.
The vocabulary (vTwin · Kited · Tethered · the String · Kited Neighborhood · Neighbor · Scan-to-Join · Sealed · Doorman) and the kite mark are the canonical identity of the RAPP neighborhood. Implementations and federated instances use them exactly. Single file. Uniform peer. Sealed line. Scan to join.
This constitution can be amended by:
- Opening a PR that modifies
CONSTITUTION.md - Explaining the rationale
- Getting approval from a repo maintainer
The spirit of this document is simplicity. If an amendment adds complexity, it should have an extraordinary justification. Single file. Single principle. Single source of truth.
A published agent path is a public contract. It is not an implementation detail, it is not ours to tidy, and it is not subject to refactoring taste.
People install agents by URL. Those URLs end up in other people's brainstems, scripts, notebooks, container builds, product code and documentation — places we cannot see, cannot enumerate, and cannot migrate. A rename that looks harmless here is a silent 404 on a stranger's machine, and they will not know we caused it. npm learned this the expensive way; we do not need to learn it again.
Once an agent file has been pushed to main, these are permanent:
| Surface | Example |
|---|---|
| Repository path | agents/@publisher/thing_agent.py |
| Raw URL | https://raw.githubusercontent.com/kody-w/RAR/main/agents/@publisher/thing_agent.py |
| CDN URL | https://cdn.jsdelivr.net/gh/kody-w/RAR@main/agents/@publisher/thing_agent.py |
Manifest name |
@publisher/thing_agent — the callable tool ID |
Registry _file |
the path callers resolve through registry.json |
The manifest name is frozen for the same reason as the path: it is how a
brainstem addresses the agent at call time. Changing it breaks callers exactly
as thoroughly as moving the file, and more confusingly.
- Renaming a published agent file
- Moving it to a different directory, publisher or namespace
- Deleting it
- Changing only its capitalisation — some filesystems hide this locally and the CDN does not
- Changing the manifest
nameof a published agent
None of these become acceptable because the agent is old, unpopular, embarrassing, superseded, or believed to be unused. We cannot measure who depends on a static file. Absence of evidence of use is not evidence of absence of use.
- Adding a new agent at a new path. Always.
- Editing in place. Fix bugs, improve behaviour, bump the version. The URL keeps resolving, which is the entire promise. This is how agents are maintained and it must never be discouraged.
- Deprecating. Mark it in the manifest and say what to use instead. A deprecated agent still resolves. Deprecation is a label, never a deletion.
- Superseding. Publish the successor at a new path and point the old one at it. Both keep working.
state/published_paths.json is an append-only ledger of every path that has
been published on main, recorded with its manifest name. Removing an entry
from that ledger is the forbidden act — the ledger is the promise made
durable, not a cache of the current directory listing.
scripts/check_url_stability.py verifies that every recorded path still
resolves and still carries the same manifest name. It parses files with ast
and never imports or executes them. It runs as the first job in CI, and the
rest of the suite depends on it, so a change that breaks a published URL cannot
merge on a green build. When a file has moved, the checker reports where it
went, so the correct fix — put it back — is obvious.
New agents are appended to the ledger automatically when they land on main.
Publishing is therefore free and irreversible, which is the correct asymmetry:
easy to add, impossible to quietly take away.
A policy is advice and erodes under deadline pressure. This is the property that makes RAR usable as infrastructure instead of as a website: a host application can hardcode a URL and walk away. Every other guarantee in this document is downstream of it, because an agent no one can fetch is not an agent. If a future change cannot be made without breaking a published URL, the change is wrong — not the contract.
The path is a promise.
agent.delete never removes a published file. It replaces the agent at its path with a
tombstone stub (scripts/tombstone.py): a valid single-file agent that imports cleanly, names
itself retired, and points to the current version if one exists. The path keeps resolving —
anyone who installed it gets an honest notice instead of a 404 — while the registry, the store,
the static API and test discovery skip it (RAR_TOMBSTONE marker). Restore replaces the stub
with the agent again. This reconciles the lifecycle's deleted/retired statuses with the
permanent-URL contract. (Clarified 2026-08-28; see issue #606.)
When a live outside channel (sources.json) becomes the library of record for agents RAR
once hosted, the hosted copies are neither deleted nor renamed — the path is a promise — but
they are withheld from every lookup: state/superseded.json names them, build_registry.py
omits them from registry.json, and because the store, the static API, match.json and
brainstem discovery all read the registry, the copies go dark everywhere at once. The registry
publishes the withheld count and the rule, never the list. Dependable for anyone who already
installed a path; current for anyone who looks. (Clarified 2026-08-28.)
A visitor's browser never calls the GitHub API. Every unauthenticated read
a page needs is served as committed static data: CI harvests once — from git
history, from the API where it must, from external sources — commits the
snapshot, and every visitor reads the committed file from Pages or
raw.githubusercontent.com. GitHub's CDN scales with GitHub; sixty API calls
an hour per visitor does not.
The covenant, concretely:
- Pages read data, never the API. An unauthenticated
api.github.comfetch in page code is a constitutional violation, however convenient. - The API is a harvester or a write channel, nothing else. It may run in CI (with a token, once per build or per day) to produce a committed snapshot; it may serve authenticated user actions — Issues-as-API submissions, votes, reviews, login. Those are exempt because they are per-user writes and identity, not reads a snapshot could serve.
- Snapshots are generator-owned. Each has a script that builds it and a
workflow that commits it; hand-editing one is the same sin as hand-editing
registry.json. - A step-change in any published number carries its explanation — a dated
entry in
state/metrics_annotations.json, published with the metrics it explains. - The visitor-directed lookup is the one sanctioned live read. When the visitor themselves names the target at the moment of use — pasting an arbitrary gist ID, typing an arbitrary owner/repo into an in-page browser — there is no fixed data a harvester could have committed ahead of time, and the read spends the visitor's own anonymous budget on the visitor's own request. Such a call site must be the exception, marked in-code as a declared visitor-directed lookup, and must never run on page load or on a timer. Everything a page fetches on its own initiative stays committed static data.
Reference implementation: state/agent_commit_dates.json (built by
scripts/build_commit_dates.py from git history — it replaced up to sixteen
API calls per visitor on the front page), state/metrics.json,
state/orappter_demo_vault.json, and the headless static API under api/v1/.
Rate limits are invisible until the audience is real: the page that worked for one developer fails for a classroom, a conference, or a fleet of agents — the exact moments the registry exists for. Static data has no such cliff. The covenant is what lets RAR promise that scale never degrades a visitor's read.
RAPP marketplace projections use one stable install identity:
rapp@x
rapp names the interoperable RAPP capability. x names the marketplace or
host surface that supplies it.
Ratified examples:
| Identity | Purpose |
|---|---|
rapp@brainstem |
Install and verify a local Brainstem, then install RAR |
rapp@rar |
Operate the registry, skills, exports, and callback bootstrap |
The rapp@x package may carry skills, instructions, runners, installers, and
host metadata, but it does not replace canonical agent.py bytes, notarized
RAR receipts, or the RAPP/1 Grail. A marketplace wrapper must point back to or
reversibly preserve its authority.
Generated Scout, Copilot CLI, Claude Code, Cowork, or Copilot Studio artifacts must not silently rewrite the behavior they project. If a target platform cannot execute the canonical behavior, the wrapper must route to a capable Brainstem/MCP host or report the limitation explicitly.
Every ratified rapp@x marketplace must:
- publish a valid
.claude-plugin/marketplace.json; - publish plugin-local metadata and discoverable
SKILL.mdfiles; - use the same
plugin@marketplaceidentity in Microsoft Scout, GitHub Copilot CLI, and Claude Code wherever those clients support the format; - preserve explicit permissions for installation, local writes, tool use, and external-AI callbacks;
- validate the real marketplace loader rather than only JSON syntax;
- keep installation additive and back up managed files before replacement;
- document conduct, security, support, and contribution paths.
A rapp@x plugin may install another RAPP layer when that is its declared
purpose. For example, rapp@brainstem may install Brainstem and then register
rapp@rar. The bootstrap must be idempotent, checksum-pinned where executable
bytes are involved, and must never modify the Brainstem kernel or Grail merely
to satisfy a host integration.
The marketplace suffix is a public identity, not a marketing alias. A new
rapp@x suffix requires maintainer approval, a unique marketplace manifest,
an explicit purpose, and a permanent public repository path. Published
identities are not repurposed.
The plugin is rapp. The marketplace tells you where it lives.
Ratified on initial repo creation. Amended to reflect the Agent Store, three universal card faces (Icon / Full Art / ASCII), companion cards, the forge, the complete agent card definition and hatching lifecycle, the .py.card shell format, deck extensions (.py.card.DeckName) and hotloading, local-first agents workspaces, Frontier tier, federation, local-first AI, the simplicity audit, the SuperSeed Chain, federation authentication, the Free Shade Principle, and agent-operated stewardship. Amended 2026-05-11 to retire the "binder" abstraction — the agents/ directory IS the workspace. Amended 2026-05-25 to add Article XXI — the Kited Neighborhood (vTwin · Kited · Tethered · the String · Kited Neighborhood · Neighbor · Scan-to-Join · Sealed · Doorman, and the kite mark), specified in NEIGHBORHOOD_PROTOCOL.md. The single file is the law. The card is the agent. The agent is the file. The seed is the tree. The steward speaks through the agent. The twin is kited; the line is sealed; scan to join. Amended 2026-08-02 to add Article XXIII — the Permanent URL Contract, enforced by state/published_paths.json and scripts/check_url_stability.py. The path is a promise. Amended 2026-08-27 to add Article XXIV — the Static Data Covenant: pages read committed static data, never the GitHub API; the API is a CI harvester or an authenticated write channel, nothing else. The snapshot is the interface. Clarified 2026-08-27 (§XXIV.5): the visitor-directed lookup — the visitor names the target at the moment of use — is the one sanctioned live read, declared in-code, never on page load. Amended 2026-08-27 to add Article XXV — the constitutional rapp@x marketplace identity across Scout, GitHub Copilot CLI, and Claude Code. The plugin is rapp; the marketplace tells you where it lives. Clarified 2026-08-28 (§XXIII.2): superseded copies stay at their paths but are withheld from every lookup via state/superseded.json. Clarified 2026-08-28 (§XXIII.3): retirement is a tombstone stub at the same path — the path resolves, the agent does not run.