Skip to content

Latest commit

 

History

History
1105 lines (792 loc) · 52 KB

CONSTITUTION.md

File metadata and controls

1105 lines (792 loc) · 52 KB

RAPP Agent Repo Constitution

The governing document for the RAPP Agent Registry. Read this before submitting or installing agents.


Article I — Purpose

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.


Article II — The Single File Principle

This is non-negotiable. It is the foundation of RAPP and the reason this ecosystem works.

An agent is ONE file.

agents/@yourname/my_agent.py    ← this is the entire package

Inside that file:

  1. A docstring — serves as the README
  2. A __manifest__ dict — serves as the package metadata
  3. A class inheriting BasicAgent — serves as the agent
  4. A perform() method — serves as the entry point

There is no:

  • manifest.json — the manifest is __manifest__ inside the .py
  • README.md — the docstring is the readme
  • requirements.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.

Two file formats, one principle

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.card to produce a bare .py. The agent works identically without its card shell.
  • Re-shell: Add __card__ back to a bare .py from holo_cards.json or 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 Deck Extension: .py.card.DeckName

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.

Deck Hotloading (Runtime)

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.card has 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.


Article III — Namespace Ownership

Publishers

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.

Rules

  1. Your namespace is yours — no one else can publish under @yourname/
  2. Slugs use underscores — my_cool_agent.py, not MyCoolAgent.py or my-cool-agent.py
  3. Slugs must be unique within your namespace — not globally
  4. No squatting — namespaces that sit empty for 6+ months may be reclaimed
  5. No impersonation — @microsoft/ requires proof of org membership

Collision-free at any scale

10,000 publishers × 100 agents each = 1,000,000 agents with zero naming conflicts.


Article IV — The Manifest

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"],
}

Required Fields

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

Article V — Quality Tiers

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 experimental but the UI displays it as Frontier. Use "quality_tier": "experimental" in manifests.

Submittable tiers

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.

Promotion path

frontier → community → verified → official
  1. Submit with "quality_tier": "experimental" → visible as Frontier, not counted in main stats
  2. Author stabilizes, bumps tier to community in a new version → standard submission
  3. Maintainer reviews → tests pass → real users confirm it works → promoted to verified
  4. Core team adopts maintenance → promoted to official

Frontier tier requirements

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)

Demotion

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 community agent that consistently fails may be demoted to experimental

Article VI — Categories

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.


Article VII — Versioning

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.


Article VIII — The Registry

registry.json is the machine-readable index of all agents. It is:

  1. Auto-generated — by build_registry.py from __manifest__ dicts in every .py file
  2. Built by CI — GitHub Actions runs on every push to main
  3. Never hand-edited — if you edit it manually, CI will overwrite it
  4. The source of truth for programmatic discovery and installation

How agents are discovered

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.

Article IX — The Agent Store

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.

Design Principle

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.

Browse & Discovery

  • 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

Agent Cards — Three Universal Faces

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.

Decks & Companions

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.

Presentation Mode

Turn any deck into a full-screen slideshow. Arrow keys navigate. Icon slides for client demos, Full Art slides for the visual treatment.

Workbench

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 .py or add to local collection

Local-First

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.

Guided Tour

First-time visitors get a walkthrough of every feature. Replay anytime via the "Tour" button in the header.


Article X — The Complete Agent Card

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.

Card Anatomy

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.

Three Faces — Non-Negotiable

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.

Card Lifecycle

┌─────────┐     ┌────────────┐     ┌──────────┐     ┌──────────┐
│  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.

Hatching Requirements

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.

What Hatching Means

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 .py file and .card.txt ASCII 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.

Cards That Never Hatch

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 — .py files 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.

The Card Is the Agent Is the File

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.


Article XI — Security & Trust

Agents MUST NOT:

  • 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

Agents MUST:

  • 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

Review process

All PRs are reviewed. Agents that violate security rules are rejected. Repeat offenders lose publishing rights.

Template guard

Unmodified starter templates (containing @your_username/) are rejected at three layers: browser validation, frontend submission, and backend process_issues.py.


Article XII — Contributing

Submit an agent (via the Web Store)

  1. Open the Workbench tab — write or paste your agent
  2. Click Validate — fix any errors
  3. Click Preview Card — see how it looks
  4. Switch to the Submit tab — paste your code and submit
  5. GitHub Actions validates, writes the file, and closes the Issue

Submit an agent (via PR)

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 request

Submit an agent (via Issues-as-API)

The 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.

PR requirements

  • Single .py file at agents/@yourname/slug.py
  • __manifest__ dict with all required fields
  • Class inherits from BasicAgent
  • perform(**kwargs) returns a string
  • python build_registry.py passes
  • No secrets or customer data
  • Docstring explains what the agent does
  • quality_tier is community or experimental (or omitted for default)

Updating an existing agent

  1. Bump version in __manifest__
  2. Update the code
  3. PR with description of what changed

Article XIII — Governance

Maintainers

Maintainers can:

  • Merge PRs
  • Promote agents to verified
  • Reject agents that violate this constitution
  • Reclaim abandoned namespaces

Disputes

  • Naming disputes → first publisher wins
  • Quality disputes → maintainer decision is final
  • Security reports → immediate removal, notify author, 48h to fix

Article XIV — Compatibility

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 Options

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.


Article XV — Federation

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.

Roles

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.

How federation works

  1. Clone the template — A user creates a new repo from the RAPP registry template. rar.config.json is auto-configured with "role": "instance" and "upstream" pointing to the main repo.
  2. Add agents locally — The instance owner adds agents under their own namespace. These appear in the instance's own store.
  3. 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.
  4. Sync from upstream — Instances can pull agents from the main store to expand their local catalog.

Federation rules

  • Instances can only submit agents under their own @namespace/
  • The upstream repo decides whether to accept each submission (same validation rules apply)
  • verified and official tiers cannot be submitted upstream — only community and experimental
  • The main store is the source of truth for tier promotions
  • Federation is opt-in: instances with "allow_upstream_sync": false operate independently

Configuration

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
  }
}

Article XVI — Local-First Agents Workspace

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.

What is a Local Agents Workspace?

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.

Setup

# 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 8080

That's it. You now have a local agent store with browse, cards, decks, workbench — everything.

What you get

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.

Managing your cards

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 browser

The 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.

Adding your own agents

# 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.py

Syncing with the main store

Your 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 status

Federation is optional. Your workspace works perfectly standalone — it's just a git repo with an HTML file.

Example: Howard's Workspace

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_agent

Howard'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 vs. Instance

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.


Article XX — The SuperSeed Chain

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

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.

Federation Authentication

Federated RAPP instances that wish to join the ecosystem under the RAPP Constitution must authenticate through the SuperSeed Chain:

  1. Registration — The instance submits a federation request containing its rar.config.json, its repo address, and its publisher namespace.
  2. Authentication — The Verification Authority validates the request and signs a federation credential using the SuperSeed Chain's provenance protocol.
  3. 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.
  4. Verification — Any party can verify a federated instance's authenticity by checking its attestation against the SuperSeed Chain.

Federation Rights

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

The Verification Authority is the entity that controls the SuperSeed Coin. This entity:

  • Authenticates new federated instances
  • Promotes agents to verified and official tiers
  • Signs verification attestations that travel with cards permanently
  • Maintains the @rapp/basic-agent root 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.

Free Shade Principle

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 .py file.
  • VERIFY an agent requires the Verification Authority

The shade is free. The roots are sovereign.

Agent-Operated Stewardship

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.

Article XXI — The Kited Neighborhood

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.


Article XXII — Amendments

This constitution can be amended by:

  1. Opening a PR that modifies CONSTITUTION.md
  2. Explaining the rationale
  3. 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.


Article XXIII — The Permanent URL Contract

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.

What is frozen

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.

Forbidden

  • 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 name of 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.

Permitted

  • 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.

Enforcement

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.

Why this is constitutional rather than a policy

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.

XXIII.3 — Retirement is a tombstone at the same path

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.)

XXIII.2 — Superseded copies: kept at their paths, withheld from lookups

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.)


Article XXIV — The Static Data Covenant

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:

  1. Pages read data, never the API. An unauthenticated api.github.com fetch in page code is a constitutional violation, however convenient.
  2. 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.
  3. 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.
  4. A step-change in any published number carries its explanation — a dated entry in state/metrics_annotations.json, published with the metrics it explains.
  5. 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/.

Why this is constitutional rather than a policy

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.


Article XXV — The rapp@x Marketplace Identity

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 marketplace is a projection, never the authority

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.

Cross-client rule

Every ratified rapp@x marketplace must:

  1. publish a valid .claude-plugin/marketplace.json;
  2. publish plugin-local metadata and discoverable SKILL.md files;
  3. use the same plugin@marketplace identity in Microsoft Scout, GitHub Copilot CLI, and Claude Code wherever those clients support the format;
  4. preserve explicit permissions for installation, local writes, tool use, and external-AI callbacks;
  5. validate the real marketplace loader rather than only JSON syntax;
  6. keep installation additive and back up managed files before replacement;
  7. document conduct, security, support, and contribution paths.

Bootstrap rule

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.

Namespace rule

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.