card

# 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: | Lineage | What it contributes | How it shows up in `CARD.yml` | |---|---|---| | 🎴 **HyperCard** (Bill Atkinson, 1987) | A card as a **self-contained navigable unit** with fields, buttons, scripts — a little interactive object you can page through, link to, and stack. "Everything is a card." | `card:` identity, `navigation:`, `advertisements:` that surface actions the way HyperCard buttons did | | 💾 **Type Library / IDL / ActiveX / OLE Control** (Microsoft, 1990s) | **Dispatch metadata** describing an object's interface: its methods, properties, events, IDs. Binary in COM; human-readable YAML for us. | `methods:`, `state:`, `k_lines:` (our stand-in for UUIDs), `inherits:` (analog to COM aggregation) | | 🎭 **Actor** (Hewitt 1973; Agha 1986) | A **message-receiving autonomous entity** with its own state, responding to messages by sending messages or changing state. Concurrency is inherent. | The whole card is an actor signature; advertisements describe the messages this actor handles | | 🧵 **Thread / Process** | A **unit of control** with its own identity, lifecycle, and dispatchable surface. | Cards are dispatchable in parallel; `state:` is the actor-thread's local memory | | 📬 **Message Dispatching Surface** (Smalltalk/Self/Objective-C) | The OO insight: methods aren't called, **messages are sent**, and the receiver decides what to do. Late binding, polymorphism, duck typing. | `methods:` ≠ functions; they're the messages this card responds to. DOP delegation composes dispatch across parent cards. | | 🃏 **Trading / Playing Card** | **Portable token of identity and capability** — you collect them, play them, trade them. Front = identity/rarity; back = mechanical rules. | `rarity:`, `tier:`, `emoji:`, `tagline:`, the whole collectible ethos (hero-stories, soul-chat) | | 🎯 **Business Card / Index Card** | **Sniffable surface.** Hand it to someone, they know who you are, how to reach you, what you do. | `tagline:`, `description:`, the entire "sniffable interface" framing | 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: ```yaml # 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 ```yaml # 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) ```yaml # 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) ```markdown - ## 📑 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) ```yaml # Separate files with descriptive names examples/ ceremony-invocation.yml # Good! buff-chain-trigger.yml # Good! example1.yml # Bad — not descriptive ``` ### Method Placement Rules | Situation | Place In | Example | |-----------|----------|---------| | Short signature | CARD methods | `PAT: { signature: "PAT [cat]" }` | | Trivial inline | Advertisement | `method: "PAT [nearest-pet]"` | | Detailed protocol | SKILL.md | Dispatch tables, sequences | | Multiple variants | SKILL.md | Species-specific versions | | Dispatch table | SKILL.md | `cat_sniffs_dog`, etc. | #### 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 ```yaml 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: | Tradition | What It Contributes | In CARD.yml | |-----------|---------------------|-------------| | **PC Board Card** | Slot/interface — plugs into a system | Cards plug into rooms, skills, activations | | **HyperCard** | Navigable unit of content | Each card is a stack, browsable, clickable | | **Playing Cards** | Combinable, playable, deckable | Cards compose into decks, hands, plays | | **Magic: The Gathering** | Abilities, costs, types, combos | Methods, state, synergies, triggered effects | | **Pokémon** | Creatures with stats, evolution | Characters with sims_traits, mind_mirror, growth | | **Fluxx** | Cards that change the rules | Meta-cards that modify the game itself | | **Tarot** | Archetypal symbols, prompts | K-lines as archetypal activation | | **Business Cards** | Contact, credentials, intro | Hero-Story cards introduce traditions | | **Key Cards** | Access tokens | Room access, capability gates | | **Hollerith Cards** | Data as physical artifact | YAML as punchable, portable data | **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 | Type | Examples | |------|----------| | **Trading cards** | Hero-Story cards for real people's traditions | | **Playing cards** | Actions, abilities, spells to play | | **Magic: The Gathering** | Complex cards with costs, effects, combos | | **Pokémon cards** | Characters with stats, moves, evolution | | **Fluxx cards** | Rule-changing cards — play to modify the game itself | | **Tarot cards** | Archetypal symbols, prompts for reflection | | **Business cards** | Contact info, credentials, introductions | | **Pleasure cards** | Memberships, VIP access, perks | | **Key cards** | Access tokens for rooms and resources | | **Receipts** | Proof of transaction, claim tickets | | **Tickets** | Entry passes, reservations, permissions | | **Coupons** | Redeemable capabilities, discounts | | **Hollerith cards** | Punch cards — data as physical holes! | | **QR codes** | Scannable data, links, actions | | **Wallet cards** | Apple/Google Pay — phone as card carrier | 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 ```yaml # 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"