card

Files (47)

• ACTIVATION.md
• CARD.yml
• CARD.yml.tmpl
• COLLECTION.yml.tmpl
• ENSEMBLES.md
• FLUXX.md
• GLANCE.yml
• README.md
• SKILL.md
• adapter-multi-surface.yml · examples/
• boop-polymorphism.yml · examples/
• buff-chain-trigger.yml · examples/
• buff-pie-menu.yml · examples/
• buff-stacking.yml · examples/
• collective-leela-ai.yml · examples/
• collective-maker-guild.yml · examples/
• collective-neighborhood-council.yml · examples/
• collective-open-guild.yml · examples/
• collective-open-observatory.yml · examples/
• collective-research-coop.yml · examples/
• entity-abstract-accountability.yml · examples/
• entity-abstract-clarity.yml · examples/
• entity-abstract-empathy.yml · examples/
• entity-abstract-justice.yml · examples/
• entity-abstract-stewardship.yml · examples/
• guarded-score-ad.yml · examples/
• monster-clockwork-dragon.yml · examples/
• monster-gelatinous-cube.yml · examples/
• monster-mimic.yml · examples/
• monster-owlbear.yml · examples/
• monster-shadow.yml · examples/
• moollm-fluxx-cards.yml · examples/
• moollm-mooxx-cards.yml · examples/
• party-dnd-delvers.yml · examples/
• party-dnd-scouts.yml · examples/
• peewee-herman-secret-word.yml · examples/
• person-fictional-mentor.yml · examples/
• person-fictional-rogue-ai.yml · examples/
• person-real-historian.yml · examples/
• person-real-moderator.yml · examples/
• property-get-set.yml · examples/
• pub-bard-shanty.yml · examples/
• random-toys.yml · examples/
• room-context-nav.yml · examples/
• worm-pointer.yml · examples/
• worm-sitemap-caster.yml · examples/
• skill-snitch-report.md

SKILL.md (first lines)

# 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)
- [What a CARD carries](#what-a-card-carries) — the standard keys, defaults, copy-down, projection
- [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)

---

## What a CARD carries

`CARD.yml` is the one file a model reads to learn what an object does
([constitution §15](../../kernel/constitution-core.md#15-the-semantic-image-pyramid-concentrated-not-dry-universal)).
The standard is the `schema:` section of [CARD.yml](CARD.yml): every key's shape, default,
meaning and aliases, in the format of
[SCHEMA.md § Schema files](../../designs/object-system/SCHEMA.md#schema-files).

### One file, concentrated, not DRY

A card holds the object's advertisements, methods, k-lines, state, Dublin Core, card face,
relations and its own YAML Jazz, all in one file. There is no `ADVERTISEMENTS.yml`,
`METHODS.yml` or `K-LINES.yml` beside it. A directory with several interfaces (`ROOM.yml` and
`CHARACTER.yml`) still has one CARD, and every interface feeds it.

Repeating a key that `SKILL.md`, an interface file or the prototype file already has is the
point, not a defect. Never remove something from a card because a larger file says it; ask
whether it is among the most important things at card size. Lint keeps the copies in
agreement; the fix for a disagreement is updating the copy.

### The keys

| Group | Keys | Defaults when omitted |
|---|---|---|
| Identity, Dublin Core | `id`, `name`, `type`, `tags`, `description`, `credits`, `license` | `id` the directory name; `name` the id in title case; `type` `skill` in `skills/`, else the implied skill of the first interface file; `license` the repo's |
| Card face | `emoji`, `tier`, `rarity`, `tagline`, `t_shirt`, `tools {required, optional}`, `files` | `tier: 2`; `rarity: common`; `tagline` the first sentence of description; `files` the directory listing |
| Behavior | `advertisements` (map of [advertisement](../advertisement/)), `methods` (map of method, [OBJECT.yml](../object/OBJECT.yml)) | empty |
| Activation | `k_lines` | the id in UPPER-DASHES |
| State | `state` | empty |
| Copy-down | `interfaces` | the directory's interface files and the skill's prototype file, nothing copied |
| Relations | `inherits`, `inherited_by`, `related` (`{id, role, when, why}`), `see_also`, `lineage` | `see_also` is SKILL.md and README.md when present |
| Common jazz | `schema`, `examples`, `principles`, `anti_patterns` | `examples` the `examples/` directory |

`type:` is one id; other kinds go in `tags:`. `k_lines:` is a flat list of K-LINE words, run by
the same matcher as an advertisement's `trigger:` words. Situations that call for the card
are advertisement `score_if:` lines, not a separate `invoke_when:` list. `status:` and
`version:` are retired (git knows), and so are `card:` and `skill:` envelopes: cards are
flat.

Readers accept the older spellings listed as `aliases:` in the schema (`one_liner`,
`documentation`, `related_skills`, `activates`, `invoke_when`, `allowed_tools`, ...); writers
emit only the canonical key. Lint reports an alias as a finding.

### Copy-down from interfaces

Interface files stay canonical for instances: `skills/room/ROOM.yml` is what every room
inherits. The card copies down their most important slots and methods so the card level of
the pyramid represents them. A model reading the room card learns that every room answers

From SimHacker/moollm, MIT.

More from SimHacker/moollm