Card

Portable tokens of capability, identity, and access.

Cards are templates. Put them "in play" in a [room](../room/) to activate them.

[!TIP]
Hero-stories. Actors. Safe pointers to wisdom. No risks of impersonation, just tribute, storytelling, skill sharing and composing.

The Card Pun Stack — What A CARD Is

"Card" elegantly puns across a stack of well-proven computing concepts. MOOLLM's CARD sits at the intersection of all of them, and borrows from each. Take the richness as intentional:

A CARD is all of these at once — that's the design, not accident. When you encounter a CARD.yml, you're looking at:

• an interface definition (like IDL) describing a dispatchable surface,
• a HyperCard you can navigate to, activate, and page through,
• an actor signature describing a message-receiving entity with local state,
• a type library entry in a distributed, human-readable, zero-ceremony registry (the filesystem itself),
• a collectible token with rarity, identity, and portability, and
• a business card you can hand to a reader (human or LLM) to say "this is what I am and what I do."

The richness is load-bearing. Every time you write methods:, advertisements:, k_lines:, or inherits:, you're simultaneously:

• declaring an interface (IDL-style),
• describing an actor's message-handling surface (Hewitt-style),
• exposing navigation/activation triggers (HyperCard-style),
• publishing metadata that tooling and LLMs can sniff without execution (TypeLib-style),
• presenting a portable token of identity (trading-card-style).

This is why a CARD-only directory (no SKILL.md) is already a first-class dispatchable object. The CARD isn't documentation for the skill — it is the skill's interface, actor, card, type library, and business card rolled into one YAML file.

💡 The other meta-skills (skill, prototype, schema, file-system-object) each name one aspect of the MOOLLM object system. card names the interface-and-actor surface itself — the CARD is the handle by which everything else is invoked.

📑 Index

Architecture

• [The Card Pun Stack — What A CARD Is](#the-card-pun-stack--what-a-card-is)
• [Card Architecture](#card-architecture) — The most important section!
• [Recommended Section Order](#recommended-section-order)
• [What Goes Where](#what-goes-where)
• [Advertisements Before Methods](#advertisements-before-methods)
• [Method Placement Rules](#method-placement-rules)

Card Types

• [What's a Card?](#whats-a-card)
• [Sidecar Pattern](#sidecar-cardyml-pattern)
• [Card Types](#card-types)

Mechanics

• [Activation Records](#activation-records)
• [Card State](#card-state)
• [Collections](#collections)

Card Architecture

KEY INSIGHT: Cards are ACTIVATION TRIGGERS, not activation handlers.

This is the most important concept in MOOLLM card design.

The Fundamental Distinction

| | CARD.yml | SKILL.md | |--|----------|----------| | Purpose | Decide IF this skill applies | Explain HOW to execute | | Role | Activation trigger | Activation handler | | Content | Sniffable interface | Full documentation | | Size | ~150-200 lines | As needed | | LLM reads | First, to decide | Second, if activated |

The CARD asks: "Does this situation call for me?" The SKILL.md answers: "Here's how to actually do it."

Recommended Section Order

Order sections for optimal LLM scanning:

# 1. Identity (who am I?)
card:
  id: my-skill
  name: "My Skill"
  emoji: 🎯
  tagline: "One-line pitch"
  description: "Brief paragraph"

# 2. Files index (what else should LLM read?)
files:
  - SKILL.md
  - examples/

# 3. K-lines (what concepts does this activate?)
k-lines:
  activates: [MY-SKILL, RELATED-CONCEPT]

# 4. Invoke when (trigger conditions)
invoke_when:
  - "Situation that calls for this skill"

# 5. ADVERTISEMENTS — PRIMARY! Put BEFORE methods!
advertisements:
  DO-THE-THING:
    score: 90
    condition: "When this applies"

# 6. Methods (signatures only, implementations in SKILL.md)
methods:
  DO-THING: { signature: "DO-THING [arg]" }

# 7. State (brief field list)
state:
  fields: [field1, field2]

# 8. Documentation pointers
documentation:
  SKILL.md:
    - "§ Detailed section"

Why Advertisements Before Methods?

Advertisements are the PRIMARY activation signal:

1. LLM scans top-down looking for "does this apply?"
2. Ads answer that question directly
3. Methods are secondary — only relevant AFTER activation
4. Front-loading ads speeds up skill selection

# GOOD — Ads first
advertisements:
  PET-THE-CAT:
    score: 80
    condition: "Cat is present"
    
methods:
  PAT: { signature: "PAT [cat]" }

# BAD — Methods first (LLM has to read past them)
methods:
  PAT: { ... long list ... }
  SCRITCH: { ... }
  # ... many more ...
  
advertisements:  # Too late! LLM already moved on

What Goes Where

In CARD.yml (sniffable interface)

# YES — Include these
- Brief description + tagline
- Files index (for one-shot activation)
- K-lines (activation vectors)
- Advertisements (PRIMARY!)
- Method SIGNATURES (one-liners)
- Brief state schema (field names only)
- Documentation pointers

# NO — Move these to SKILL.md
- Implementation details
- Detailed protocols with sequences
- Dispatch tables
- Dialogue examples
- Full state schemas with types
- Worked examples

In SKILL.md (full documentation)

- ## 📑 Index (link to each section)
- Detailed method implementations
- Protocols with step sequences
- Dispatch tables (actor_verb_target)
- State schemas with types and defaults
- Integration points with other skills
- Mechanics explanations

In examples/ (worked examples)

# Separate files with descriptive names
examples/
  ceremony-invocation.yml    # Good!
  buff-chain-trigger.yml     # Good!
  example1.yml               # Bad — not descriptive

Method Placement Rules

Embed in CARD when:

• Method is SHORT (one-liner signature)
• Method is UNIQUE to this skill
• Just showing signature, not implementation

Embed in advertisement when:

• Method is TRIVIAL (buff, reply, simple prompt)
• Method is AD-SPECIFIC (only makes sense in this trigger)

Delegate to SKILL.md when:

• Method has DETAILED protocol (sequences, tables)
• Method is SHARED with other skills
• Method has multiple VARIANTS
• Method needs EXAMPLES to understand

Target Card Size

card_yml: ~150-200 lines
skill_md: As long as needed, but indexed
examples:  Separate files, descriptively named

smell: "If CARD > 300 lines, refactor"

What's a Card?

Cards are portable tokens you can carry, give, play, and activate.

The Card Intersection

CARD.yml sits at the intersection of many card traditions, each contributing essential meaning:

The genius is the layering. When you create a CARD.yml, you're creating:

• An interface slot (PC board) that plugs into the MOOLLM system
• A navigable document (HyperCard) that LLMs can browse and activate
• A playable piece (playing card) that can be dealt, held, played
• A creature with abilities (MTG/Pokémon) that has stats and moves
• A rule modifier (Fluxx) that can change the game
• An archetypal pointer (Tarot/K-line) that invokes patterns
• An access token (key card) that grants capabilities

All at once. Different contexts activate different metaphors.

Card Examples by Tradition

A card is anything you can carry in your inventory and play when needed.

Sidecar CARD.yml Pattern

Any entity that lives in a directory can have a sidecar CARD.yml file that makes it card-playable:

pub/
├── ROOM.yml           # The room definition
├── CARD.yml           # Makes the pub a playable card!
└── ...

characters/don-hopkins/
├── CHARACTER.yml      # Character definition
├── CARD.yml           # Don's trading card representation
└── ...

objects/magic-lamp/
├── OBJECT.yml         # Lamp definition
├── CARD.yml           # Card for summoning/playing the lamp
└── ...

Why Sidecars?

• Separation of concerns — Entity definition vs. card representation
• Optional — Not everything needs to be a card
• Composable — Same entity, multiple views
• Portable — Card data can reference the entity by path

Sidecar Card Schema

# pub/CARD.yml — makes the pub a playable card
card:
  for: ./ROOM.yml           # What this card represents
  type: location-card       # Card type
  
  # Card-specific presentation
  name: "Gezelligheid Grotto"
  art: "cozy-coffeeshop.png"
  flavor: "Where good vibes flow like espresso"
  
  # What playing this card does
  advertisements:
    VISIT:
      description: "Teleport party to this location"
      effect: "Set party.location = pub/"
      
    SUMMON:
      description: "Bring the pub's vibe to current room"
      effect: "Apply pub buffs to current location"

Character Cards

Characters automatically become tradeable/playable:

# characters/don-hopkins/CARD.yml
card:
  for: ./CHARACTER.yml
  type: hero-story        # Real person tradition
  
  # K-line activation
  tradition: "HyperCard, SimCity, OLPC, procedural rhetoric, Maxis"
  concepts:
    - pie_menus
    - constructionist_games
    - micropolis
    
  # Playing the card
  summon: |
    Activate Don's documented ideas:
    - Pie menu interaction patterns
    - Constructionist game design
    - Urban simulation philosophy

The Big Idea

graph TD
    C[📇 Card Template] -->|clone + parameterize| I[🎴 Instance in Room]
    I -->|has| S[State: goals, vars, stack]
    I -->|lives in| R[🚪 Room]
    R -->|can hold| M[Multiple instances]

A card is a capability template — a tool, character, function, familiar, key, receipt.

A card in play is an instance with:

• Local variables
• Parameters
• Goal stack (what it's trying to do)
• Return value (when done)
• Room it lives in

You can have multiple activations of the same card, in the same or different rooms. They're independent task instances.

Activation Records

Full specification: [ACTIVATION.md](./ACTIVATION.md)

Playing a card = creating an activation record — an instantiated method with persistent state.

The Sims meets Magic: The Gathering — autonomous agents with triggered abilities.

Fluxx Cards: Rules That Change Rules

Full specification: [FLUXX.md](./FLUXX.md)

Inspired by Fluxx, some cards modify the game itself.

Fluxx cards make MOOLLM a self-modifying game.

Data Flow Ensembles

Full specification: [ENSEMBLES.md](./ENSEMBLES.md)

Cards can contain coordinated ensembles of generators, transformers, and consumers.

Factorio meets Dataflow meets Natural Language — pipelines assembled by intent.

Cards Advertise

Just like [objects in rooms](../advertisement/), cards advertise what they can do:

# Git Goblin card
advertisements:
  - action: BISECT
    description: "Binary search for bug introduction"
    score_if: "debugging AND has_git_repo"
    score: 90
    
  - action: BLAME
    description: "Find who changed this line"  
    score_if: "examining_code"
    score: 70
    
  - action: LOG
    description: "Show commit history"
    score: 50

In inventory: Advertisements visible but lower priority.

Played in room: Card's advertisements merge with room objects. Best action wins regardless of source.

Multiple cards: All advertisements compete. The right tool for the moment rises to top.

Why K-Lines Are Safe

[!IMPORTANT]
Cards for real people don't need proxy abstractions.

A "Dave Ungar" card doesn't impersonate Dave Ungar. It activates the tradition:

• Self language, prototype-based inheritance
• "It's About Time" compilation philosophy
• Message-not-class thinking

This is like citing someone's work, not pretending to be them.

card:
  name: "Dave Ungar"
  type: person
  # NOT impersonation — K-line activation
  
  invokes:
    - "Self language"
    - "Prototype-based inheritance"
    - "ITS-ABOUT-TIME compilation"
    - "Message-passing purity"
    
  wisdom: |
    "Programming should be about the experience
    of programming, not fighting the language."

When you "play" this card, you invoke the tradition — not simulate the person.

Card Types

Card Anatomy

Hero-Story (Real Person)

card:
  name: "Dave Ungar"
  type: person
  
  # K-line activation — what tradition this invokes
  invokes:
    - "Self language"
    - "Prototype-based inheritance"
    - "ITS-ABOUT-TIME compilation"
    - "Message-not-class thinking"
    
  wisdom: |
    "Programming should be about the experience
    of programming, not fighting the language."
    
  contributions:
    - "Self programming language"
    - "Morphic UI framework"
    - "Optimistic compilation"
    
  stats:
    wisdom: 10
    influence: 9
    domain_expertise: ["languages", "VMs", "UI"]

Familiar (Tool Spirit Animal)

card:
  name: "Git Goblin"
  type: familiar
  emoji: "🧌"
  enthralled_by: "Linus Torvalds" # My master (I mean main)!
  
  abilities:
    - "Track changes"
    - "Commit with message"
    - "Navigate history"
    
  parameters:
    repo_path: { type: string, required: true }
    
  stats:
    power: 7
    reliability: 9
    learning_curve: 4
    
  synergizes_with:
    - "Session Log"
    - "Plan Then Execute"

Putting Cards in Play

When you activate a card in a room:

# Instance in room: .agent/rooms/debug-session/

activation:
  card: "Git Goblin"
  instance_id: "goblin-001"
  room: ".agent/rooms/debug-session/"
  
  # Instance-specific state
  parameters:
    repo_path: "/path/to/repo"
    
  state:
    current_branch: "main"
    uncommitted_changes: 3
    
  goals:
    - "Find when bug was introduced"
    - "Bisect to culprit commit"
    
  subgoals: []
  
  return_value: null  # Filled when done

Multiple Instances

Same card, different activations:

.agent/rooms/
  debug-session/
    goblin-001.yml      # Git Goblin hunting a bug
    goblin-002.yml      # Git Goblin checking history
  feature-work/
    goblin-003.yml      # Git Goblin managing commits

Each instance has its own state, goals, and lifecycle.

Contents

Familiars (Special Cards)

Cards that embody tool capabilities as helpful spirits:

See [P-HANDLE-K](../../PROTOCOLS.yml) — familiars are safe K-line wrappers.

Actor Lineage

Cards-in-play ARE actors in the classic sense:

Cards are prototypes. Activation clones them into actors.

The microworld (filesystem) is the stage. Rooms are the scenes. Cards are the performers.

The Intertwingularity

graph LR
    TC[🎴 card] -->|activates in| R[🚪 room]
    TC -->|can speak via| SC[💬 soul-chat]
    TC -->|logged by| SL[📜 session-log]
    TC -->|composes via| DOP[delegation-object-protocol]
    
    R -->|holds instances of| TC
    SC -->|voices for| TC

Dovetails With

Sister Skills

Protocol Symbols

Meta

• [delegation-object-protocol.md](../delegation-object-protocol.md) — How cards inherit from prototypes
• [skill-instantiation-protocol.md](../skill-instantiation-protocol.md) — Card activation is skill instantiation

Navigation