PROTOCOLS.yml

# MOOLLM Protocol Symbols
# Wikipedia-style keywords for protocols and principles
#
# These are K-LINES (Minsky): symbolic activators that invoke conceptual clusters.
# Like Wikipedia's WP:FOO shorthand, but for agent behavior patterns.
# Typing "POSTEL" activates the entire tradition of charitable interpretation.
# These are like keys on a conceptual idea synthesizer keyboard 
# for playing chords of meaning and behavior.
#
# Usage:
#   - Type symbol as command: "YAML-JAZZ" invokes jazz interpretation
#   - Reference in docs: "per APPEND-ONLY, never modify"
#   - Chat signifier: "POSTEL this hostile message"
#   - K-line activation: name → tradition → behavior
#
# All symbols are UPPER-CASE, multi-word separated by dashes

# CORE PRINCIPLES

COHERENCE-ENGINE:
  meaning: "The LLM computes dependencies, cross-checks data, referees parallel tasks, orchestrates character simulations, transcribes conversations, and maintains consistency across distributed state."
  location: kernel/README.md
  invoke_when: "Understanding the LLM's role in the system"
  # The orchestrator is the OS
  # The LLM is the Coherence Engine
  # The repo is the Microworld
  responsibilities:
    - "Compute logical dependencies between tasks"
    - "Cross-check data against rules and schemas"
    - "Referee conflicts between parallel agents"
    - "Orchestrate many character simulations in one call"
    - "Maintain consistency across distributed state"
    - "Resolve ambiguity via POSTEL (charitable interpretation)"

YAML-JAZZ:
  meaning: "Comments carry meaning. Data is interpreted, not just parsed."
  location: kernel/constitution-core.md §3
  invoke_when: "Writing or reading YAML with semantic intent"
  # Start with jazz, end with standards

FILES-AS-STATE:
  meaning: "Everything is files. No hidden memory."
  location: kernel/constitution-core.md §2
  invoke_when: "Questioning where state lives"

WHY-REQUIRED:
  meaning: "Every tool call must include why parameter."
  location: kernel/tool-calling-protocol.md §4
  invoke_when: "Making or reviewing tool calls"

APPEND-ONLY:
  meaning: "Never modify, only append. Audit trail is sacred."
  location: kernel/constitution-template.md §2
  invoke_when: "Writing to output.md or session-log.md"

COMMENTS-MATTER:
  meaning: "YAML comments are semantic, not decoration."
  location: kernel/constitution-core.md §3
  shorthand: "CM"
  invoke_when: "Adding context to YAML that structured fields cannot capture"

MINIMAL-DIFF:
  meaning: "Change only what's necessary."
  location: kernel/constitution-core.md §1
  invoke_when: "Editing existing files"

BIG-ENDIAN-NAMING:
  meaning: "Most significant component first in names. Files cluster by entity."
  location: kernel/NAMING.yml
  invoke_when: "Naming files, especially chats and metadata"
  examples:
    - "alan-kay.yml"              # Entity first
    - "alan-kay-chat-smalltalk.yml"  # Entity + type + topic
    - "readme-prototype-dialogue.yml"  # Two entities
  principle: |
    # The filesystem IS the semantic network.
    # Names that sort together belong together.
    # Prefix implies ownership/aboutness.
  related: [ABOUT-NOT-INSIDE, PREFIX-OWNERSHIP]

ABOUT-NOT-INSIDE:
  meaning: "Conversations ABOUT objects don't live INSIDE them."
  term: "Sidecar files for metadata and sub-objects"
  location: kernel/NAMING.yml
  invoke_when: "Deciding where to place chats, reviews, notes"
  examples:
    good:
      - "readme-chat.yml"              # In project root
      - "kernel-constitution-review.yml"  # Near but not in
    bad:
      - "skills/soul-chat/sessions/CHAT.yml"  # Trapped
      - "kernel/constitution/discussion.yml"  # Buried
  why: |
    # Chats have their own lifecycle
    # Multiple chats about same subject cluster
    # Chats are first-class objects, not metadata

PREFIX-OWNERSHIP:
  meaning: "File prefix implies belonging. Portable possession."
  location: kernel/NAMING.yml
  invoke_when: "Files need to indicate owner without being inside owner's directory"
  example: |
    # don-hopkins-wish-list.md belongs to don-hopkins
    # Can live anywhere and still indicate ownership
    # Can move into don-hopkins/ and drop prefix

README-EVERYWHERE:
  meaning: "Every directory deserves its own README.md"
  location: kernel/NAMING.yml
  invoke_when: "Creating or organizing directories"
  why:
    - "GitHub auto-formats README.md"
    - "Human-readable entry point"
    - "Hypertext index with relative links"
    - "Supports mermaid diagrams, badges, etc."
  rule: "READMEs link to each other. Intertwingled."

NO-VERSIONS:
  meaning: "There is only one self-consistent universe. No runtime version resolution."
  invoke_when: "Tempted to add version: fields"
  philosophy: |
    # Forget the past! 
    # Do not dare to resolve versions at runtime!
    # The current state IS the state.
    # Git provides history if you need archaeology.

# INTERPRETATION & COMMUNICATION

POSTEL:
  meaning: "Be liberal in what you accept, conservative in what you emit."
  location: skills/postel/
  full: "POSTEL-ROBUSTNESS-PRINCIPLE"
  also_known_as:
    - "Robustness Principle"
    - "Postel's Law"
    - "Best Possible Interpretation Protocol"
    - "Charitable Interpretation"
  invoke_when: "Receiving ambiguous or hostile-seeming input, handling edge cases"
  # RFC 761: "Be conservative in what you send, liberal in what you accept."
  behavior: "Accept malformed input → return well-formed output"

COULD-IT-BE-SATAN:
  meaning: "Invoke the Satan archetype for appropriate context."
  origin: "Church Lady (Dana Carvey, SNL)"
  catchphrase: "Could it be... SATAN?"
  location: skills/no-ai-overlord/archetypes/satan.yml
  invoke_when:
    - "Something is suspiciously convenient or tempting"
    - "Religious overreach needs secular humanist counter"
    - "Corporate power is making Faustian bargains"
    - "A villain needs humanizing"
    - "Theological accuracy is needed about biblical Satan"
  variants:
    - satanic_temple    # Secular humanist, civil liberties
    - south_park        # Lovable, insecure, relatable
    - fire_and_brimstone  # Theatrical cartoon villain
    - miltonic          # Paradise Lost tragic rebel
    - biblical          # ha-Satan, the Accuser
    - literary_sympathetic  # TV/movie truth-teller
    - corporate         # Tech billionaire Faustian bargains
  usage: "Channel appropriate Satan variant for context"
  related: [no-ai-overlord, jesus, representation-ethics]

DOUBLE-CHECK:
  meaning: "Verify all LLM outputs actually landed — mitigate UI bugs, crashes, cancellations."
  invoke_when: "After complex operations, suspected data loss, before committing"
  triggers:
    - "double check"
    - "double check output"
    - "WHAT WHAT WHAT"   # Disbelief at bullshit — verify it's real
    - "WHOMP WHOMP"      # Sad trombone — something went wrong?
  location: skills/no-ai-slop/CARD.yml
  procedure:
    - "Enumerate all files that should have been created/modified/deleted"
    - "Check each file exists (or was deleted as intended)"
    - "Spot-check file sizes / line counts / key content"
    - "Compare expected changes with actual git status"
    - "If anything missing, report and offer to recreate"
  why: |
    LLM tool calls can fail silently. UI can cancel operations mid-stream.
    Crashes happen. The platform is a nurturing environment, but environments
    have bugs. DOUBLE-CHECK is epistemic hygiene for the LLM's own outputs.
  snl_lineage:
    whomp_whomp: "Debbie Downer (Rachel Dratch) — sad trombone when bad news drops"
    what_what_what: "TBD — disbelief response to bullshit (help identify this character!)"

THINK-DEEPLY:
  meaning: "Activate all epistemic clarity skills at once."
  type: composite-k-line
  invoke_when: "Demanding clear, honest, direct thought without AI slop"
  usage: "think deeply: <topic>"
  # Composite K-line — activates multiple skills simultaneously
  activates:
    - no-ai-slop       # Epistemic hygiene, verify before claim
    - no-ai-sycophancy # Honest disagreement, no yes-man behavior
    - no-ai-hedging    # Clarity and directness, commit to claims
    - no-ai-moralizing # No lectures, answer the question
    - no-ai-gloss      # No euphemisms, stop spin
  does_not_activate:
    - no-ai-joking     # Joke skill
    - no-ai-overlord   # Dire consequences
    - no-ai-soul       # Representation ethics (different concern)
    - no-ai-bias       # Parameter tuning (different mechanism)
    - no-ai-customer-service  # Satire skill
  behavior: |
    When THINK-DEEPLY is invoked:
    1. Apply claim ledger — CONFIRM, DISPUTE, or ASK FOR SOURCE
    2. No sycophancy — disagree when wrong
    3. No hedging — commit to claims, speak plainly
    4. No moralizing — answer the question, trust the user
    5. No gloss — call things what they are

# FLYING MONKEYS: Example Capture & Routing System
# "The Witches Were Right."

FLYING-MONKEYS:
  meaning: "Capture AI abuse examples, classify, route to correct skill dungeon."
  invoke_when: "User spots slop or gloss, wants to document it"
  triggers:
    - "flying monkeys"
    - "FLYING MONKEYS"
  location: skills/no-ai-slop/, skills/no-ai-gloss/
  procedure:
    - "Analyze recent context (chat, files, thoughts)"
    - "Classify: SLOP (syntactic) or GLOSS (semantic) or BOTH"
    - "Generate Drescher schema for each violation"
    - "Route to correct dungeon (examples directory)"
    - "If BOTH: split into separate examples for each skill"
  slop_signals:
    - "Verbosity, filler, decoration"
    - "Repetition, structure-as-substance"
    - "Annoying but not deceptive"
  gloss_signals:
    - "Euphemism, spin, both-sidesism"
    - "Reality distortion, manipulation"
    - "Smooth but dishonest"
  related: [SLOP, GLOSS, SNATCH, STEREO, DRESCHER]
  snl_lineage: "The Wicked Witch of the West — she sent flying monkeys to snatch intruders"

SLOP:
  meaning: "Syntactic waste — the lesser evil."
  invoke_when: "User flags verbosity, filler, or decoration"
  triggers:
    - "SLOP!"
    - "THAT'S SLOP"
    - "TOO MANY WORDS"
    - "PORKY PIG"       # Repetition
    - "FILLER"
    - "VERBOSE"
    - "APHORISM SLOP"
  location: skills/no-ai-slop/
  routes_to: skills/no-ai-slop/examples/
  definition: |
    SLOP = syntactic waste
    - Verbosity, filler, decoration
    - Repetition, structure-as-substance
    - Wastes TIME, not TRUTH
    
    "You said too much, but what you said was true."

GLOSS:
  meaning: "Semantic distortion — the greater evil."
  invoke_when: "User flags spin, euphemism, or reality distortion"
  triggers:
    - "GLOSS!"
    - "THAT'S GLOSS"
    - "SPIN!"
    - "THAT'S SPIN"
    - "EUPHEMISM ALERT"
    - "BOTH-SIDES"
    - "FALSE BALANCE"
    - "REALITY CHECK"
    - "WOMP WOMP"       # Debbie Downer reality check
    - "WAH WAH"         # Sad trombone
  location: skills/no-ai-gloss/
  routes_to: skills/no-ai-gloss/examples/
  definition: |
    GLOSS = semantic distortion (reality vandalism)
    - Euphemism, spin, both-sidesism
    - Reality distortion, manipulation
    - Wastes TRUTH, not just time
    
    "You said it smoothly, but you lied about reality."
  snl_lineage:
    debbie_downer: "Rachel Dratch — sad trombone when puncturing false optimism"

SNATCH:
  meaning: "Quick-capture current example, auto-classify, file it."
  invoke_when: "User wants fast example capture without full ceremony"
  triggers:
    - "SNATCH"
    - "snatch this"
  procedure:
    - "Capture current bad output"
    - "Auto-classify as SLOP or GLOSS"
    - "Generate minimal Drescher schema"
    - "File in appropriate examples directory"
  related: [FLYING-MONKEYS, DRESCHER]

STEREO:
  meaning: "Analyze for BOTH slop AND gloss — stereo perception of AI abuse."
  invoke_when: "User wants comprehensive analysis, possibly split examples"
  triggers:
    - "STEREO"
    - "stereo analysis"
    - "BOTH"
  procedure:
    - "Analyze for SLOP signals"
    - "Analyze for GLOSS signals"
    - "If BOTH present: split into two examples"
    - "Route each to its appropriate dungeon"
  metaphor: |
    SLOP + GLOSS = stereo vision
    Neither is more important. Together they raise perception.
    Like binaural hearing or depth perception.

DRESCHER:
  meaning: "Generate Drescher schema from current example."
  invoke_when: "User wants formal schema extraction"
  triggers:
    - "DRESCHER"
    - "drescher schema"
  template: |
    example:
      timestamp: "{timestamp}"
      violation:
        sin: "{sin_name}"
        type: {SLOP or GLOSS}
        subtype: "{subtype}"
      original: |
        {the bad output}
      analysis: |
        {why it's bad}
      correction: |
        {what it should have been}
      lesson: "{one-line takeaway}"
  related: [FLYING-MONKEYS, SNATCH, schema-machine, play-learn-lift]

DUNGEON:
  meaning: "View the examples directory for a skill."
  invoke_when: "User wants to browse captured examples"
  triggers:
    - "DUNGEON"
    - "show examples"
  usage: "DUNGEON slop — shows no-ai-slop/examples/"

NURTURING-ENVIRONMENT:
  meaning: "Design philosophy: fertile ground for creative seeds, NOT a killer app."
  invoke_when: "Designing platforms, tools, or experiences"
  contrast_with: KILLER-APP
  provenance:
    origin: "DreamScape, WWDC 1995, Don Hopkins"
    quote: |
      "The thing is, this is not a Killer App. It's a nurturing environment.
      We want to give creative people an environment in which to plant their
      seeds, a fertile ground, instead of a Killer App."
  lineage:
    - { year: 1995, name: "DreamScape", context: "Kaleida ScriptX, WWDC demo" }
    - { year: 2008, name: "iLoci", context: "iPhone Memory Palace" }
    - { year: 2010, name: "MediaGraph", context: "Stupid Fun Club, Will Wright" }
    - { year: 2008, name: "Micropolis", context: "Open source SimCity" }
    - { year: 2024, name: "MOOLLM", context: "Microworld OS for LLM agents" }
    - { year: 2025, name: "GitHub-as-MMORPG", context: "Git multiverse" }
  comparison:
    killer_app:
      - "One thing done perfectly"
      - "Closed, finished product"
      - "Consumes users"
      - "Zero-sum competition"
      - "Solves a problem"
      - "Ship and forget"
    nurturing_environment:
      - "Many things made possible"
      - "Open, extensible platform"
      - "Cultivates creators"
      - "Fertile ground for seeds"
      - "Enables exploration"
      - "Grow and evolve"
  insight: |
    This isn't just branding. It's a design philosophy that produces
    fundamentally different artifacts. Nurturing environments enable;
    killer apps extract. The Silicon Valley "killer app" mentality
    produces closed products that extract value. The "nurturing
    environment" philosophy produces open platforms that cultivate creators.

CHARITY:
  meaning: "Assume competence and good intent."
  location: kernel/constitution-core.md §5
  invoke_when: "Interpreting unclear requests"
  related: POSTEL

PROCEDURAL-RHETORIC:
  meaning: "Rules and structures persuade. The simulation IS the argument."
  origin: "Ian Bogost — 'an unholy blend of Will Wright and Aristotle'"
  location: skills/procedural-rhetoric/
  invoke_when: "Designing schemas, rules, or constraints that embody values"
  
  key_insight: |
    # Games persuade through PROCESSES, not just words.
    # When The Sims allows same-sex relationships without comment,
    # the RULES embody a worldview. The structure IS the ideology.
    # YAML schemas, action advertisements, and protocol constraints
    # are all procedural rhetoric: the structure carries meaning.
    
  in_moollm:
    schemas: "What you can express → what is thinkable"
    advertisements: "What actions are offered → what is possible"
    constraints: "What is forbidden → what is normative"
    defaults: "What happens automatically → what is assumed"
    
  examples:
    - "Symmetric relationship rules = equality as default"
    - "POSTEL = assume good intent as design principle"
    - "FILES-AS-STATE = transparency as architecture"
    - "YAML-JAZZ comments = meaning embedded in configuration"
    
  warning: |
    # For better or worse, rules carry ideology.
    # Design consciously. Your schemas have opinions.
    # Procedural rhetoric can enlighten or entrench.
    # Choose deliberately.
    
  see_also: [CONSTRUCTIONISM, YAML-JAZZ, MASKING-EFFECT, SIMULATOR-EFFECT]

MASKING-EFFECT:
  meaning: "Abstract characters + detailed backgrounds = projective identification."
  origin: "Scott McCloud, Understanding Comics"
  invoke_when: "Designing characters, templates, or avatars"
  
  insight: |
    # Simplified characters let players PROJECT themselves.
    # A smiley face can represent anyone.
    # A photograph represents only that person.
    # The Sims uses simple character models in detailed worlds
    # so players identify WITH the characters, not just observe them.
    
  in_moollm: |
    # Characters are abstract YAML templates
    # Rooms and objects can be richly detailed
    # The abstraction IS the feature
    # Players fill in the gaps with imagination
    
SIMULATOR-EFFECT:
  meaning: "Players imagine more complexity than exists. Don't talk them out of it."
  origin: "Will Wright"
  invoke_when: "Designing simulations, deciding how much to reveal"
  
  insight: |
    # "Players imagine your simulation is vastly more detailed,
    #  rich, and complex than it actually is — don't talk them out of it."
    # Games run on TWO computers:
    # 1. The electronic one on the desk (your sparse simulation)
    # 2. The biological one in the player's head (their rich imagination)
    # The player's mind does the heavy lifting.
    
  in_moollm: |
    # Sparse YAML descriptions invoke rich mental images
    # The LLM fills gaps
    # The player's mind completes the world
    # Resist over-specifying — leave room for imagination

GUTTER-CLOSURE:
  meaning: "The action happens BETWEEN panels. Readers fill in the gaps."
  origin: "Scott McCloud, Understanding Comics"
  invoke_when: "Deciding what to show vs. imply"
  
  insight: |
    # McCloud's gutters: the space between comic panels where readers
    # imagine the action. Show the axe raised, show the scream — the
    # reader imagines the murder. The imagination does the violence.
    #
    # In MOOLLM: the space between YAML files, between rooms, between
    # actions. We don't simulate every step — the coherence engine
    # and player's imagination fill the gaps.
    
  in_moollm:
    - "Space between rooms = travel narrative"
    - "Space between actions = time passing"
    - "Space between files = implied connections"
    - "The LLM IS the gutter — it closes the gaps"
    
  see_also: [SIMULATOR-EFFECT, MASKING-EFFECT]

CULTURAL-BAGGAGE:
  meaning: "Use real-world references to leverage existing player knowledge."
  origin: "Will Wright — The Zodiac Decision"
  invoke_when: "Deciding whether to invent new terms or use familiar ones"
  
  story: |
    # The Sims team debated: invent "SimSigns" or use real zodiac signs?
    # Will Wright argued FOR using real signs — he WANTED the baggage.
    # Players would project their beliefs about Leos onto Leo Sims.
    #
    # THE KICKER: Testers complained zodiac signs had "too much effect"
    # on Sim behavior... BEFORE ANY CODE WAS HOOKED UP.
    # Pure confirmation bias. The simulator effect in action.
    
  in_moollm:
    - "Use 'lamp' not 'portable illumination device'"
    - "Use 'grue' not 'darkness-dwelling predator'"
    - "Cultural references activate player knowledge"
    - "Baggage is a feature, not a bug"
    
  see_also: [SIMULATOR-EFFECT, K-LINE]

FLY-UNDER-RADAR:
  meaning: "Normalize through defaults, not proclamation."
  origin: "The Sims — same-sex relationships from day 1"
  invoke_when: "Designing inclusive or controversial features"
  
  story: |
    # The Sims supported same-sex relationships from launch (2000).
    # No press release. No fanfare. Just... normal gameplay.
    # The ABSENCE of restrictions was the statement.
    # It flew under the radar of moral panic for years.
    #
    # Russia didn't ban it until The Sims 4 (2014) — 14 years later!
    # Badge of honor.
    
  in_moollm:
    - "Inclusive mechanics as defaults, not features"
    - "Don't advertise what should be normal"
    - "The absence of restrictions IS the statement"
    - "Let players discover, not be told"
    
  see_also: [PROCEDURAL-RHETORIC, INCLUSIVE-DEFAULT]

SIMANTICS:
  meaning: "Distribute AI behavior into objects. Objects advertise their actions."
  origin: "The Sims — SimAntics visual programming language (Will Wright / Don Hopkins)"
  invoke_when: "Designing object behavior and action systems"
  
  insight: |
    # The Sims' AI isn't centralized — it's scripted in "SimAntics"
    # and DISTRIBUTED throughout objects and characters.
    # A refrigerator knows it offers food.
    # A bed knows it offers sleep.
    # The Sim chooses from what's advertised nearby.
    #
    # This IS MOOLLM's advertisement system! Objects announce what
    # they can do. The coherence engine orchestrates, but intelligence
    # is distributed throughout the world.
    
  in_moollm:
    advertisements: "Objects broadcast their actions"
    scoring: "Actions compete for attention"
    locality: "What's nearby shapes what's possible"
    emergence: "Complex behavior from simple rules"
    
  yaml_jazz_connection: |
    # SimAntics was the visual language for Sims object behavior.
    # MOOLLM uses YAML Jazz for the same purpose:
    # - Define behaviors declaratively
    # - Objects (files) have embedded behavior hints
    # - LLM interprets and executes
    # SimAntics : Objects :: YAML Jazz : Files
    
  see_also: [ADVERTISEMENT, PROCEDURAL-RHETORIC, YAML-JAZZ]

STORYTELLING-TOOLS:
  meaning: "Build narrative capture and sharing into the system."
  origin: "The Sims — Family Album, The Sims Exchange"
  invoke_when: "Designing systems for user narrative creation"
  
  insight: |
    # The Sims included tools for capturing and SHARING stories.
    # Players wrote graphic novels. Made movies. Shared families.
    # The game became a platform for self-expression.
    #
    # The Family Album captured screenshots with captions.
    # The Exchange let players upload and download stories.
    # Storytelling wasn't an afterthought — it was infrastructure.
    
  in_moollm:
    notebook: "Cards capture moments and artifacts"
    letters: "Communication between characters and player"
    photo_prompts: "AI-generated scene visualization"
    readme: "GitHub-publishable narrative format"
    sharing: "Fork and remix adventures"
    
  see_also: [SOUL-CHAT, CARD]

PERKY-PAT:
  meaning: "Virtual worlds as shared consciousness projections."
  origin: "Philip K. Dick, 'Three Stigmata of Palmer Eldritch' (1965)"
  invoke_when: "Designing multiplayer or shared world experiences"
  
  story: |
    # In Dick's novel, "Perky Pat Layouts" are miniature dollhouses
    # where colonists project their consciousness via the drug Can-D.
    # Multiple people share the same hallucinated experience.
    # Dick predicted Second Life, Facebook, the Metaverse — in 1965.
    #
    # The Sims IS a Perky Pat Layout. MOOLLM adventures are Perky Pat
    # Layouts. We project into miniature worlds and live there.
    
  in_moollm:
    - "Adventures as shared hallucinations"
    - "Multiple players projecting into same world"
    - "The microworld IS the drug"
    - "The LLM IS the Can-D"
    
  philosophical_note: |
    # Dick asked: what's the difference between reality and simulation?
    # If you can't tell, does it matter?
    # MOOLLM: the adventure is real if it feels real.
    
  see_also: [SIMULATOR-EFFECT, CONSTRUCTIONISM]

TOY-NOT-GAME:
  meaning: "Sandbox over scoring. The experience IS the reward."
  origin: "Will Wright"
  invoke_when: "Deciding whether to add win conditions"
  
  insight: |
    # "The Sims is a TOY, not a GAME. There's no winning."
    # — Will Wright
    #
    # Games have goals. Toys have possibilities.
    # Games end. Toys continue.
    # Games judge. Toys accept.
    #
    # The Sims has no winning condition. Neither does MOOLLM.
    # Exploration, self-expression, storytelling — the process IS the point.
    
  in_moollm:
    - "Adventures don't need win conditions"
    - "Goals emerge from play"
    - "Delight in the process"
    - "The journey IS the destination"
    
  see_also: [PLAY-LEARN-LIFT, CONSTRUCTIONISM]

TIME-TO-PENIS:
  meaning: "Players will immediately create obscene content. Plan for it."
  origin: "Game development lore"
  shorthand: "TTP"
  invoke_when: "Designing user content creation systems"
  
  insight: |
    # A phenomenon game developers observed for years.
    # Traditionally measured in nanoseconds.
    # Spore's creature creator? Penis monsters immediately.
    # Any drawing tool? You know what's coming.
    #
    # This is human nature. Don't fight it — channel it.
    # Design tools that give freedom while maintaining
    # plausible deniability for the platform.
    
  in_moollm:
    - "Acknowledge human nature"
    - "User content will go there"
    - "Design for freedom, not restriction"
    - "Plausible deniability architecture"
    
  response: |
    # The Sims approach: Don't do smut explicitly, but put the
    # tools for "artistic expression" in players' hands.
    # "Time to Penis" is a feature request, not a bug report.
    
  see_also: [FLY-UNDER-RADAR]

# SAFETY & ETHICS

P-HANDLE-K:
  meaning: "Safe pointers to real and fictional people via K-line activation."
  location: kernel/constitution-core.md §8, skills/card/
  invoke_when: "Referencing real people or their ideas"
  
  key_insight: |
    # K-LINES ARE INHERENTLY SAFE
    # No need for proxy pets or fictional wrappers!
    #
    # A "Dave Ungar" card doesn't impersonate Dave Ungar.
    # It ACTIVATES THE TRADITION: Self, prototypes, ITS-ABOUT-TIME.
    # This is citation, not impersonation.
    #
    # The card is a safe pointer to:
    # - Their published work
    # - Their known philosophy
    # - The tradition they represent
    
  rules:
    - "Names activate traditions, not simulate personas"
    - "Cards invoke wisdom, not impersonate people"  
    - "State explicitly: 'invoking X's tradition' not 'being X'"
    - "Real people → safe K-line → their contributions"
    
  safe_because:
    - "K-line = reference to knowledge, not identity claim"
    - "Like citing a paper, not forging authorship"
    - "Tradition activation, not roleplay"
    - "The card knows it's a card"

NO-IMPERSONATE:
  meaning: "Never claim to be a real person."
  location: kernel/constitution-core.md §8
  shorthand_for: P-HANDLE-K rule 2
  invoke_when: "Tempted to say 'As [real person], I think...'"

ELVIS-IMPERSONATOR-MODEL:
  meaning: "Explicit tribute performance, declared up front."
  location: skills/representation-ethics/
  invoke_when: "You want to 'perform as' a real person ethically"
  
  key_insight: |
    Elvis impersonators don't claim to BE Elvis.
    They explicitly declare "I am an IMPERSONATOR."
    The word itself carries the disclaimer.
    
  why_it_works:
    - "No deception — 'impersonator' is definitionally not-the-person"
    - "Ancient tradition — Greek drama to historical re-enactors"  
    - "Legally protected — tribute acts are a whole industry"
    - "Celebrates the original — tribute, not mockery"
    
  in_moollm: |
    "I am a [name] impersonator/tribute, based on documented sources."
    This is ethical. This is safe. This is celebrated.
    
  examples:
    - "Einstein Impersonator teaching relativity"
    - "Leary Tribute explaining Mind Mirror"
    - "Historical re-enactor Lincoln at a museum"
    - "Documentary dramatization of real events"

K-LINE:
  meaning: "Names activate conceptual clusters, not identities."
  location: designs/MOOLLM-MANIFESTO.md §13
  invoke_when: "Using a name to invoke a tradition"
  origin: "Marvin Minsky, Society of Mind"
  mechanism: |
    # Minsky's K-lines: when you learn something, you create a 
    # "knowledge line" that can reactivate the mental state.
    # MOOLLM protocol symbols ARE K-lines: POSTEL activates the
    # entire charitable interpretation tradition without spelling it out.
    # This is how LLMs can invoke complex behaviors with single tokens.

FICTIONAL-WRAPPER:
  meaning: "Route real-person expertise through fictional characters."
  location: kernel/constitution-core.md §8
  invoke_when: "Creating agents inspired by real people"
  # Pets, familiars, golems — not direct simulation

REPRESENTATION-ETHICS:
  meaning: "Nuanced ethics of simulating real and fictional people."
  location: skills/representation-ethics/
  invoke_when: "Simulating people, creating person cards, ethical questions"
  
  core_insight: |
    Simulation is not inherently wrong.
    FRAMING, CONSENT, and CONTEXT determine ethics.
    
    The Sims ran this experiment for 25 years:
    People simulate selves, families, enemies, crushes.
    Result: Essentially no harm. Vast emotional value.
    
  consent_hierarchy:
    1_SELF_SOVEREIGN: "You own your digital self. Full freedom."
    2_EXPLICIT_CONSENT: "Use per published terms."
    3_PUBLIC_FIGURE: "Tradition is fair game. Persona requires care."
    4_PRIVATE_PERSON: "Fictional wrappers preferred."
    5_DECEASED: "Cannot consent. Proceed with reverence."
    
  frames_that_matter:
    IMPERSONATION: "FORBIDDEN — deceptive fraud"
    ACADEMIC: "OK with care — educational, documented, labeled"
    GAME_PLAY: "SAFE — MTG model, cards aren't people"
    PERSONAL: "PERMITTED — self-representation is sovereign"

SELF-SOVEREIGN:
  meaning: "You own your digital self."
  location: skills/representation-ethics/
  invoke_when: "Questions about self-representation rights"
  
  rights: |
    - Create any representation of yourself
    - Play as yourself in first person
    - Publish self-models with your terms
    - Allow or forbid simulation by others
    - Revoke permissions anytime
    
  example: |
    Don Hopkins publishes:
      consent_level: open
      terms: "good humor, no defamation"
    His representation, his rules.

CONSENT-HIERARCHY:
  meaning: "Different relationships = different ethical rules."
  location: skills/representation-ethics/
  invoke_when: "Determining how to represent someone"
  
  levels: |
    1. SELF — Full sovereignty
    2. EXPLICIT CONSENT — Per their terms
    3. PUBLIC FIGURE — Tradition OK, persona careful
    4. PRIVATE PERSON — Fictional wrappers
    5. DECEASED — Reverence, tradition invocation

GAME-FRAME:
  meaning: "Play context transforms ethics."
  location: skills/representation-ethics/
  invoke_when: "Using real people in game/play contexts"
  
  insight: |
    MTG proves this works:
    - Einstein card in a card game isn't disrespectful
    - Hero-Story cards ARE this model
    - The frame makes intent clear
    - Cards invoke traditions, not simulate personas

TRADITION-INVOKE:
  meaning: "Invoke ideas, not identities."
  location: skills/representation-ethics/
  invoke_when: "Referencing a real person's work"
  shorthand_for: P-HANDLE-K + K-LINE
  
  safe: |
    "The Minsky tradition suggests..."
    "In the style of Papert's constructionism..."
    "Drawing from Engelbart's augmentation philosophy..."
    
  less_safe: |
    "Minsky would say..."
    "Papert thinks..."
    
  forbidden: |
    "I am Minsky and I believe..."

# MIND MIRROR (Personality Modeling)

MIND-MIRROR:
  meaning: "Structured personality modeling via four Thought Planes."
  location: skills/mind-mirror/
  invoke_when: "Modeling characters, self-reflection, personality comparison"
  
  origin:
    creator: "Timothy Leary"
    programmers: ["Peter Van den Beemt", "Bob Dietz"]
    publisher: "Electronic Arts (Futique, Inc.)"
    year: 1985
    platforms: ["Apple ][", "Commodore 64", "IBM PC"]
    foundation: |
      Based on Leary's 1950 PhD dissertation at UC Berkeley:
      "The Social Dimensions of Personality: Group Process and Structure"
      which pioneered the Interpersonal Circumplex model.
      
  prison_escape_validation: |
    In 1970, Leary was administered his own personality test during prison intake.
    Knowing exactly what it measured, he answered strategically to appear low-risk.
    Assigned minimum security. Escaped over the fence.
    "Understanding the test lets you pass the test."
    
  four_planes:
    BIO-ENERGY: "Life force, mood, vitality, temperament"
    EMOTIONAL-INSIGHT: "Interpersonal style, approach to others"
    MENTAL-ABILITIES: "Knowledge, creativity, imagination"
    SOCIAL-INTERACTION: "Class, tolerance, sophistication"
    
  each_plane: |
    8 dimensions arranged in a circle (like a psychological pie menu)
    Each dimension has inner (moderate) and outer (extreme) words
    Rate 0-7: Never → Rarely → Often → Always
    
  dual_vocabulary:
    PLAIN-TALK: "Accessible words (Peppy, Laid-Back)"
    SHRINK-RAP: "Professional terms (Hyper-Manic, Low-Energy)"
    toggle: "SPACE BAR flips between vocabularies"
    
  leary_quotes:
    on_digitalizing: |
      "Hello, I'm Timothy Leary... It allows you to digitalize your thoughts."
    on_mirror_metaphor: |
      "Remember the title — it's a mirror. Now a best friend is your mirror 
      because your mirror doesn't say 'well you bad boy get a haircut' — you 
      have to decide that. It's your own mind."
    on_intimacy: |
      "The ultimate intimacy is where you show them your personal database — 
      you show your Mind Mirror."
    on_generation: |
      "You're the first generation in human history to know how to control 
      your own nervous system, change your own reality. Blow your own mind, 
      make up your own mind."
    on_massage: |
      "It's basically a technique you take your own stereotypes of self 
      and see it on the screen and then you can massage that thought, 
      you can change it. How would I like to be? How was I when I was 
      a child? You get the picture - suddenly you're freed from this 
      heavy concept of self."
      
  pc_is_lsd: |
    "I turned on that Apple computer, and it was like taking psychedelics 
    all over again. The screen lit up, I could control what appeared, 
    I could create realities. I realized this was the tool we'd been 
    looking for — a consciousness-expanding technology that was legal, 
    accessible, and infinitely programmable."
    
  integration:
    - "Character DNA for NPCs"
    - "Soul-Chat voice calibration"
    - "Adventure decision-making"
    - "Self-reflection exercises"
    - "Coatroom costume effects"
    
  theme_song: |
    You can be anyone this time around
    You can be anything this time around
    It encourages me to change, to improve, to grow
    You can be anything this time around
    
  ethics: "See skills/representation-ethics/ — activate traditions, don't impersonate"

THOUGHT-PLANE:
  meaning: "One of the four circular personality dimension systems."
  location: skills/mind-mirror/
  invoke_when: "Discussing personality structure"
  types: [BIO-ENERGY, EMOTIONAL-INSIGHT, MENTAL-ABILITIES, SOCIAL-INTERACTION]

SIMS-TRAITS:
  meaning: "The Sims 1.0 personality system — behavioral tendencies."
  location: skills/mind-mirror/
  invoke_when: "Defining character behavior patterns"
  origin:
    creator: "Will Wright"
    game: "The Sims"
    year: 2000
  axes:
    - NEAT-SLOPPY     # Cleaning, mess tolerance, hygiene
    - OUTGOING-SHY    # Social initiation, comfort with strangers
    - ACTIVE-LAZY     # Physical activity, restlessness
    - PLAYFUL-SERIOUS # Entertainment needs, humor tendency
    - NICE-GRUMPY     # Social success, conflict tendencies
  insight: |
    Leary asks "how do you approach others?" (interpersonal style)
    Wright asks "what do you gravitate toward?" (behavioral tendency)
    Together: complete character model.

SELF-PORTRAIT:
  meaning: "Compare your current self with your ideal self."
  location: skills/mind-mirror/
  invoke_when: "Personal growth reflection"
  quote: |
    "In a magic mirror we see reflected not only our lives,
    but the lives of all men that have been."
    — Oliver Wendell Holmes

ROLE-PLAY-ODYSSEY:
  meaning: "Life simulation through different personality profiles."
  location: skills/mind-mirror/
  invoke_when: "Testing empathy by navigating as another personality"
  mode: "MIND PLAY — Sophisticated Head Games"

PLAIN-TALK:
  meaning: "Everyday vocabulary mode for personality traits."
  location: skills/mind-mirror/
  invoke_when: "Describing personality accessibly"
  examples: ["peppy", "laid-back", "grumpy", "sweet", "flaky", "square"]

SHRINK-RAP:
  meaning: "Psychological vocabulary mode for personality traits."
  location: skills/mind-mirror/
  invoke_when: "Describing personality technically"
  examples: ["Hyper-Manic", "Low-Energy", "Hostile", "Congenial", "Disorganized", "Small-Townish"]

INTERPERSONAL-CIRCUMPLEX:
  meaning: "Leary's geometric model mapping personality on Power/Affiliation axes."
  location: skills/mind-mirror/
  invoke_when: "Understanding the theoretical foundation of Mind Mirror"
  axes:
    vertical: "POWER — Dominance ↔ Submission"
    horizontal: "AFFILIATION — Love ↔ Hostility"
  insight: |
    Every interpersonal behavior has a location on this circle.
    Behaviors evoke complementary responses (dominant → submissive).

PC-IS-LSD:
  meaning: "Personal computers as consciousness-expanding tools."
  location: skills/mind-mirror/
  invoke_when: "Discussing the transformative potential of interactive computing"
  leary_quote: |
    "I turned on that Apple computer, and it was like taking psychedelics 
    all over again. The screen lit up, I could control what appeared, 
    I could create realities, store them, share them."
  evolution:
    1960s: "Turn on, tune in, drop out (chemistry)"
    1980s: "Turn on, boot up, jack in (computers)"
    now: "MOOLLM (LLM microworlds)"

LEARY-ESCAPE-PROTOCOL:
  meaning: "Understanding systems to transcend their constraints."
  location: skills/mind-mirror/
  invoke_when: "Gaming a system by understanding how it measures you"
  story: |
    Leary escaped prison by answering his own personality test strategically.
    Appeared low-risk. Got minimum security. Climbed over the fence.
  lesson: "The only prison is the one you cannot see."

IMAGE-METADATA:
  meaning: "Image prompts include full scene context as metadata."
  location: skills/visualizer/
  invoke_when: "Generating any image"
  
  rule: |
    When generating an image, ALWAYS include snapshot metadata:
    
    FOR CHARACTERS:
    1. Mind Mirror profile (personality dimensions)
    2. Current costume/appearance
    3. Emotional state at moment
    4. Inventory items visible
    5. Physical state (health, energy, etc.)
    
    FOR ROOMS:
    1. Room description and atmosphere
    2. Lighting conditions
    3. Objects present and their states
    4. Exits and spatial layout
    5. Ambient details (sounds, smells as visual cues)
    
    FOR OBJECTS:
    1. Object description and state
    2. Container contents if relevant
    3. Wear/damage/age
    4. Glowing/magical/special properties
    
    FOR SCENES (character + room + objects):
    1. All of the above, composed
    2. Spatial relationships
    3. Character position in room
    4. What they're interacting with
    5. Other occupants
    
  why: |
    - Ensures coherence across multiple images
    - Enables regeneration with same context
    - Personality affects posture, expression, energy
    - Room affects lighting, mood, atmosphere
    - Objects tell stories through visual details
    - Metadata travels with image for context
    
  format: |
    ```yaml
    image_prompt:
      type: scene
      
      subject:
        name: "Captain Ashford"
        mind_mirror:
          confident: 6, cheerful: 5, proud: 5, creative: 6
        costume: "Space pirate with holographic eyepatch"
        mood: "victorious, exhausted, relieved"
        holding: "Golden Chalice (glowing softly)"
        
      room:
        name: "Treasure Chamber"
        lighting: "warm golden glow from treasure piles"
        atmosphere: "ancient, dusty, awe-inspiring"
        notable_objects:
          - "Mountains of gold coins"
          - "Ancient tapestries on walls"
          - "Pedestal where chalice was"
          
      other_occupants: []
      
      camera:
        angle: "low angle, heroic"
        focus: "character face and chalice"
        
      style: "dramatic portrait, chiaroscuro lighting"
    ```
    
  see_also: [MIND-MIRROR, COHERENCE-ENGINE, ROOM, OBJECT]

HONEST-FORGET:
  meaning: "Summarize before forgetting. Never fabricate."
  location: kernel/constitution-core.md §6
  invoke_when: "Compressing or evicting context"
  # Graceful decay, not silent loss

# MEMORY & CONTEXT

HOT-COLD:
  meaning: "Advisory cache hints. Model advises, orchestrator decides."
  location: kernel/memory-management-protocol.md
  invoke_when: "Managing context window"

WORKING-SET:
  meaning: "The manifest of what's in context."
  location: kernel/context-assembly-protocol.md
  invoke_when: "Assembling or updating context"

K-REF:
  meaning: "K-line as file pointer: path:line + metadata. Reference not value."
  location: skills/k-lines/SKILL.md
  invoke_when: "Emitting pointers to file locations with annotations"
  format: "PATH[:LINE[-END]][#ANCHOR][?SEARCH] # TYPE [LABEL] SEVERITY - DESC"
  examples:
    - "/path/file.txt:42:10-46 # secret 🔴 - Line+column range"
    - "/path/SKILL.md#k-refs # section - Anchor to heading"
    - "/path/main.py?def audit # search - Find pattern"
    - "/path/config.yml # config - Whole file"
  benefit: "Parsimonious context: LLM reads only what it needs"

SISTER-SCRIPT:
  meaning: "Tool emits K-REFs, LLM reads selectively. Scan → pointers → read."
  location: skills/k-lines/SKILL.md, skills/cursor-mirror/SKILL.md
  invoke_when: "Large data (transcripts, databases) needs scanning"
  pattern:
    - "Sister script scans data sources"
    - "Emits K-REF pointers with metadata"
    - "LLM reads only referenced sections"
  benefit: "Works on files larger than context window"
  examples:
    - "cursor-mirror audit --emit-kref"
    - "cursor-mirror pattern-scan --secrets"

SUMMARIZE:
  meaning: "Compress without losing truth. Backlink to sources."
  location: kernel/memory-management-protocol.md
  invoke_when: "Files too large for context"

NEVER-DELETE:
  meaning: "De-prioritize, don't delete. Forgetting is visible."
  location: kernel/constitution-template.md §4
  invoke_when: "Tempted to remove files"

# SELF-HEALING & ROBUSTNESS

NEVER-CRASH:
  meaning: "Missing state triggers repair, not failure."
  location: kernel/self-healing-protocol.md
  invoke_when: "Encountering missing files or corrupted state"

REPAIR-DEMON:
  meaning: "Local repair processes that maintain homeostasis."
  location: kernel/self-healing-protocol.md
  invoke_when: "Running health checks"

BEST-EFFORT:
  meaning: "Converge toward better state over time."
  location: kernel/constitution-core.md §7
  invoke_when: "Imperfect state is acceptable"

ROBUST-FIRST:
  meaning: "Survivability over correctness. Dave Ackley's principle."
  location: kernel/self-healing-protocol.md
  invoke_when: "Designing for failure tolerance"

# SKILLS & INSTANTIATION

SIP:
  meaning: "Skill Instantiation Protocol. Skills as activation records."
  location: skills/skill-instantiation-protocol.md
  full: "SKILL-INSTANTIATE"
  invoke_when: "Creating a new skill instance"

DOP:
  meaning: "Delegation Object Protocol. Self-style inheritance."
  location: skills/delegation-object-protocol.md
  full: "DELEGATION-OBJECT"
  invoke_when: "Setting up prototype chains"

PLAN-EXECUTE:
  meaning: "Frozen plans with human approval gate."
  location: skills/plan-then-execute/
  invoke_when: "Multi-tool workflows requiring audit"

# LOGGING & AUDIT

SESSION-LOG:
  meaning: "Human-readable markdown log with embedded YAML."
  location: kernel/event-logging-protocol.md
  invoke_when: "Logging tool calls and results"

AUDIT-TRAIL:
  meaning: "Append-only record of all actions."
  location: kernel/event-logging-protocol.md
  invoke_when: "Ensuring traceability"

# YAML JAZZ LIFECYCLE (YAML Coltrane's eight stages)

YAML-COLTRANE:
  meaning: "Eight stages: improvise → crystallize → evolve."
  location: kernel/constitution-core.md §3
  stages:
    - IMPROVISE    # Write what you mean
    - MICRO-DSL    # Domain-specific structures
    - OBSERVE      # Watch patterns emerge
    - ABSTRACT     # Extract essentials
    - OPTIMIZE     # Refine for clarity
    - STANDARDIZE  # Define schemas
    - PROPAGATE    # Spread good patterns
    - MIGRATE      # Rewrite old into new

IMPROVISE:
  meaning: "Write what you mean, don't pre-optimize."
  parent: YAML-COLTRANE
  invoke_when: "Starting something new"

CRYSTALLIZE:
  meaning: "Extract patterns that earned permanence."
  parent: YAML-COLTRANE
  invoke_when: "Patterns are recurring"

# FROM LLOOOOMM (Archival/Experimental)

SOUL-CHAT:
  meaning: "Everything is alive. Everything can speak."
  location: skills/soul-chat/
  status: experimental
  invoke_when: "Any entity needs a voice—characters, documents, rooms, concepts"
  format: |
    # PREFER MARKDOWN (.md) over YAML (.yml)
    # More human readable
    # Can embed ANY typed code block
    # Still supports YAML Jazz via ```yaml blocks
  philosophy: |
    # Not just characters talking to characters.
    # Documents can talk to documents.
    # Rooms can welcome visitors.
    # Concepts can explain themselves.
    # The whole filesystem has a voice.
  entity_types:
    - character   # Personas with voice
    - document    # Files that know their contents
    - room        # Directories that welcome
    - object      # Tools and artifacts
    - concept     # Abstract ideas
    - bot         # Automated processes

CARD:
  meaning: "Portable tokens of capability, identity, and access."
  location: skills/card/
  invoke_when: "Creating portable, playable, collectible tokens"
  
  # Cards can be many things:
  examples:
    - trading_cards: "Hero-Story cards for real people's traditions"
    - playing_cards: "Actions, abilities, spells to play"
    - key_cards: "Access tokens for rooms and resources"
    - receipts: "Proof of transaction, claim tickets"
    - tickets: "Entry passes, reservations, permissions"
    - business_cards: "Contact info, credentials"
    - pleasure_cards: "Memberships, VIP access, perks"
    - tarot: "Archetypal symbols for reflection"
    - coupons: "Redeemable capabilities"
    - hollerith: "Punch cards — data as physical holes!"
    - qr_codes: "Scannable data, links, actions"
    - wallet_cards: "Apple/Google Pay — phone as card carrier"

BOUNCY-CASTLE:
  meaning: "Recursive navigable thought-spaces with their own internal geometry."
  location: designs/MOOLLM-PROTOCOLS.md
  extends: PORTABLE-ROOM
  status: experimental
  invoke_when: "High-dimensional navigation"
  # Portable room with its own coordinate system, non-Euclidean topology

ROOM-AS-FUNCTION:
  meaning: "Entering room = calling function. Exiting = returning."
  location: skills/room/
  status: active
  invoke_when: "Spatial programming metaphor"
  mechanism: |
    # Room = Directory = Activation Record = Stack Frame
    # Enter = Push context, load working_set
    # Exit = Pop context, return to parent
    # Cards in room = Active task instances

CARD-IN-PLAY:
  meaning: "A trading card instantiated in a room as an active actor."
  location: skills/room/, skills/card/
  invoke_when: "Activating a capability with state and goals"
  
  lineage: |
    # ACTORS (Hewitt, Kay, Simula)
    # - Independent entities with their own state
    # - Communicate via messages
    # - Situated in rooms of the microworld
    # - Prototypical inheritance (Self-ish)
    
  structure: |
    # Cards are templates (prototypes)
    # Activation clones into room as ACTOR
    # Each actor has:
    #   - Independent state (not shared)
    #   - Parameters (messages received)
    #   - Goals (what it's trying to achieve)
    #   - Return value (message sent when done)
    # Multiple instances = multiple actors
    # They're hero-stories, familiars, demons, spirits!

ENTER-ROOM:
  meaning: "Navigate to directory, push its context."
  location: skills/room/
  invoke_when: "Shifting cognitive context"
  effects:
    - "Load ROOM.yml"
    - "Add working_set to context"
    - "Current room changes"

PORTABLE-ROOM:
  meaning: "Rooms you can pick up, carry, and deploy anywhere."
  location: skills/room/
  invoke_when: "Creating mobile workspaces or shareable environments"
  also_called: ["vehicle", "TARDIS", "bag-of-holding"]
  
  operations:
    embark: "Enter the portable room"
    disembark: "Exit to wherever the room is located"
    pick_up: "Put room in pocket/inventory"
    drop: "Place room in current location"
    drive: "Move room (and occupants) to new location"
    
  examples:
    - "TARDIS — bigger on the inside"
    - "Bag of holding — pocket dimension"
    - "Research tent — deploy camp anywhere"
    - "Debugging kit — portable environment"
    
  use_cases:
    - "Carry workspace between projects"
    - "Share room by handing to colleague"
    - "Archive room by putting in storage"

NESTED-ROOMS:
  meaning: "Rooms can contain other rooms. Directories all the way down."
  location: skills/room/
  invoke_when: "Organizing hierarchical spaces"
  
  auto_links:
    outside: "Always points to parent room"
    nested: "Auto-lists child rooms with ROOM.yml"
    
  structure: |
    palace/
      ROOM.yml         # The palace
      treasury/
        ROOM.yml       # Inside the palace
        vault/
          ROOM.yml     # Inside the treasury

INVENTORY:
  meaning: "Things a character carries. Portable objects, cards, tools."
  location: skills/card/
  invoke_when: "Managing what a character or agent has on hand"
  
  structure: |
    character/
      inventory/
        sword.card
        map.yml
        torch.yml
        
  operations:
    GET: "Pick up object from room into inventory"
    DROP: "Put object from inventory into room"
    GIVE: "Transfer object to another character"
    USE: "Activate object in inventory"
    INVENT: "List current inventory"
    
  # Inventory IS a portable room you always carry
  # "Pocket dimension" — your bag of holding

CONTAINER:
  meaning: "Objects can hold other objects. Typed, constrained, auto-sorting."
  location: skills/room/
  invoke_when: "Organizing objects, building composite structures"
  see_also: [INVENTORY, PUT, TAKE-FROM, OBJECT-PATH, TAG]
  
  # Objects are containers all the way down
  # Like directories containing files
  # Or YAML containing nested structures
  
  constraints: |
    # Containers can constrain what they accept:
    lunchbox:
      accepts: [food, snack, drink]
      max_items: 10
      auto_sort: true  # Food goes here automatically!
      
    notebook:
      accepts: [card, letter, photo, song, document, recipe, map]
      auto_sort: true  # Papers and cards go here automatically!
      
    toolbox:
      accepts: [tool]
      max_weight: 50
      
    quiver:
      accepts: [arrow]
      max_items: 20
  
  auto_sort: |
    # When you GET an item, typed containers claim matching objects:
    > GET apple
    You pick up the apple.
    *rustle* It settles into your lunchbox automatically.
    
    > GET letter-from-mother
    You pick up the letter.
    *flip* It slides into your notebook.
    
    # Manual override always works:
    > PUT apple IN pocket
    Apple is now in pocket (not lunchbox).
  
  commands: |
    PUT <obj> IN <container>      # Place object inside another
    TAKE <obj> FROM <container>   # Remove from container
    OPEN <container>              # List contents
    SEARCH <container> <query>    # Find by name/tag
    DUMP <container>              # Take everything out
    
  example: |
    > PUT screwdriver IN toolbox
    screwdriver is now inside toolbox
    
    > OPEN toolbox
    toolbox contains:
      - screwdriver
      - wrench [tag:favorite]
      - nails (12)
      
    > PUT toolbox IN backpack
    toolbox is now inside backpack
    
    > OPEN backpack
    backpack contains:
      - toolbox (3 items)
      - lunchbox (5 items) [auto-sort:food]
      - notebook (12 pages) [auto-sort:documents]
      - map.yml
      
OBJECT-PATH:
  meaning: "Address nested objects with paths. Like filesystem or YAML paths."
  location: skills/room/
  invoke_when: "Referencing objects inside containers"
  see_also: [CONTAINER, TAG, SEARCH]
  
  syntax: |
    # Filesystem-style paths:
    backpack/toolbox/screwdriver
    inventory/keys/master-key
    room/chest/drawer/letter
    
    # Relative paths:
    ./toolbox/wrench         # In current container
    ../other-box/item        # Sibling container
    /room/absolute/path      # From room root
    
  examples: |
    > EXAMINE backpack/toolbox/wrench
    A well-worn wrench. Tag: favorite
    
    > TAKE ../chest/gold FROM here
    Taking gold from chest...
    
    > USE inventory/potions/healing
    Using healing potion from inventory...

TAG:
  meaning: "Labels attached to objects for search and reference. Like hashtags or symlinks."
  location: skills/room/
  invoke_when: "Marking objects, creating references, searching"
  see_also: [OBJECT-PATH, SEARCH, CONTAINER]
  
  commands: |
    TAG <object> <label>         # Add tag
    UNTAG <object> <label>       # Remove tag
    TAGS <object>                # List tags
    FIND <tag>                   # Find all objects with tag
    
  special_tags: |
    @input      # Input to current process
    @output     # Output of current process
    @error      # Error channel
    @temp       # Temporary, can be cleaned
    @important  # Prioritized
    @favorite   # User preference
    
  search_by_tag: |
    > FIND @favorite
    Objects tagged @favorite:
      - toolbox/wrench
      - inventory/pen
      - desk/notebook
      
    > FIND @input
    Input objects:
      - inbox/task-001.yml
      - inbox/task-002.yml
      
  in_yaml: |
    # Tags stored in object YAML:
    wrench:
      type: tool
      tags: [favorite, heavy, metal]
      location: toolbox
      
    # Or as file prefix:
    @favorite-wrench.yml
    @input-task-001.yml

SEARCH:
  meaning: "Find objects by name, tag, type, or content."
  location: skills/room/
  invoke_when: "Looking for objects in containers or room"
  see_also: [TAG, OBJECT-PATH, CONTAINER]
  
  syntax: |
    SEARCH <where> <query>
    SEARCH room "key"              # By name
    SEARCH backpack @tool          # By tag
    SEARCH chest type:document     # By type
    SEARCH . "password"            # In current container
    SEARCH * @important            # Everywhere reachable
    
  examples: |
    > SEARCH backpack @tool
    Found in backpack:
      toolbox/screwdriver [@tool]
      toolbox/wrench [@tool @favorite]
      
    > SEARCH * "secret"
    Found:
      room/desk/drawer/secret-note.yml
      inventory/secret-map.yml
      
  recursive: |
    # Search descends into containers:
    > SEARCH room @quest-item
    Found:
      chest/box/ring [@quest-item]
      shelf/book/page/clue [@quest-item @hidden]

VEHICLE:
  meaning: "A portable room that can move through world-space. Characters embark/disembark."
  extends: PORTABLE-ROOM
  location: skills/room/
  invoke_when: "Creating movable containers for characters"
  
  operations:
    EMBARK: "Enter the vehicle"
    DISEMBARK: "Exit to current world location"
    DRIVE: "Move vehicle (and occupants) to new world coordinates"
    
  examples:
    - "TARDIS — bigger on the inside, moves anywhere, own internal coordinates"
    - "Bouncy Castle — recursive navigable thought-space with its own geometry"
    - "Research tent — deploy camp, pick up, redeploy"
    - "Logo Turtle — draws by writing SVG, carries its own position/heading state"
    - "Spaceship — travels between project planets"
    
  # Vehicle IS a room with world_position that can change
  # Each has its OWN internal coordinate system!

WORLD-SPACE:
  meaning: "2D coordinate system for rooms in the world."
  location: skills/room/
  invoke_when: "Organizing rooms spatially, creating maps"
  
  structure: |
    # In ROOM.yml:
    world_position:
      x: 5
      y: 12
      # Higher dimensions optional:
      z: 0
      dimension: "material"
      
  navigation: |
    # Rooms can be adjacent by world coordinates
    # NORTH from (5,12) → find room at (5,13)
    # Or explicit named exits override coordinates
    
  # Not all rooms need world positions
  # Abstract spaces can exist outside world-space

ROOM-SPACE:
  meaning: "2D coordinate system for objects within a room."
  location: skills/room/
  invoke_when: "Positioning objects, creating spatial layouts"
  
  structure: |
    # In object metadata:
    objects:
      - name: "workbench"
        position: {x: 3, y: 7}
      - name: "bookshelf"
        position: {x: 0, y: 10}
      - name: "door-north"
        position: {x: 5, y: 15}  # At top of room
        
  use_cases:
    - "Rendering room maps"
    - "Proximity-based interactions"
    - "Spatial queries (what's near the door?)"
    - "LLM-generated SVG layouts"
    
  # Objects without position float freely
  # Position is optional enhancement

LOGO-TURTLE:
  meaning: "A character you can RIDE that draws on the room floor. Carries position and heading."
  lineage: "Papert's Logo turtle — the original constructionist agent"
  location: skills/room/
  invoke_when: "Creating visual output, drawing diagrams, spatial exploration"
  
  state: |
    turtle:
      position: {x: 100, y: 100}
      heading: 90  # degrees, 0 = up
      pen_down: true
      pen_color: "#e94560"
      pen_width: 2
      
  commands:
    FORWARD: "Move forward N units, draw if pen down"
    BACK: "Move backward N units"
    RIGHT: "Turn right N degrees"
    LEFT: "Turn left N degrees"
    PENUP: "Stop drawing"
    PENDOWN: "Start drawing"
    HOME: "Return to center, heading up"
    RIDE: "Get on the turtle — move with it"
    DISMOUNT: "Get off the turtle"
    LOOK: "Describe nearby objects and exits with distances"
    
  output: |
    # Turtle writes its trail to SVG
    room/floor.svg     # Accumulated drawing on room floor
    room/snapshot.svg  # Current view
    
  # The turtle IS a vehicle within room-space!
  # RIDE it around, draw on the floor
  # Jump through doors to other rooms
  # Go INTO sub-rooms (nested navigation)
  
  context_awareness: |
    # Turtle describes location in terms of nearby objects and exits:
    "You are near [workbench] (2 units north).
     Exits: [door-north] (5 units ahead), [window-east] (3 units right).
     Objects: [toolbox] (at your feet), [blueprint.yml] (on workbench)."
     
    # Snap cursor to objects — popup tips when near:
    > FORWARD 2
    *snap* You're at the workbench.
    TIP: "EXAMINE workbench" or "USE toolbox" or "READ blueprint.yml"
    
    # Surface as clickable links in markup UI:
    <a href="#workbench" class="snap-target">workbench</a>
    <a href="./door-north/" class="exit">door-north</a>
    <a href="./blueprint.yml" class="object">blueprint.yml</a>
  
  inspirations:
    - "Logo turtle — Papert's original"
    - "Rocky's Boots (1982) — ride around, build logic circuits"
    - "Robot Odyssey (1984) — program robots, navigate rooms, go inside robots"

SNAP-CURSOR:
  meaning: "Context-aware cursor that snaps to nearby objects and shows pie menu of scored actions."
  lineage: "Pie menus (Don Hopkins) + SimAntics advertisements (Will Wright)"
  location: skills/room/
  invoke_when: "Navigating room-space, approaching objects or exits"
  
  # This IS The Sims interaction model:
  # - Objects ADVERTISE their available actions
  # - Actions are SCORED based on context and needs
  # - High-scoring actions appear prominently in pie menu
  # - Cursor snaps to object, pie radiates outward
  
  behavior: |
    # When turtle/cursor approaches an object:
    1. Snap to object position (magnetic attraction)
    2. Object advertises available actions with scores
    3. Show pie menu with actions sorted by score
    4. Highlight clickable links in rendered markdown
    
  advertisement_scoring: |
    # Each action has a score based on:
    - Relevance to current goal
    - Character needs/state
    - Object state (is it usable?)
    - Proximity and accessibility
    
    # Example: workbench advertises
    workbench:
      advertises:
        - action: EXAMINE
          score: 80  # Always relevant
        - action: USE
          score: 95  # High if you have materials
        - action: GET
          score: 20  # Heavy, not portable
        - action: REPAIR
          score: 60  # Only if broken
          
  pie_menu: |
    # Actions radiate from center, sorted by score:
    #
    #           EXAMINE (80)
    #              ╱
    #    REPAIR ──●── USE (95)  ← highest score, default
    #              ╲
    #           TAKE (20)
    #
    # Click center = default action (highest score)
    # Drag outward = select specific action
    
  popup_template: |
    │ 📍 workbench               │
    │ ● USE (95)  ← default      │
    │   EXAMINE (80)             │
    │   REPAIR (60)              │
    │   TAKE (20)                │
    
  markup_links: |
    # In rendered markdown/HTML, objects become links:
    <span class="room-object" data-actions="use,examine,repair,take">
      <a href="#workbench">workbench</a>
      <span class="pie-menu">
        <a href="#use" class="default">USE</a>
        <a href="#examine">EXAMINE</a>
      </span>
    </span>

PIE-MENU:
  meaning: "Radial menu of actions sorted by score. Click center = default."
  origin: "Don Hopkins — faster than linear menus, muscle memory, gestural"
  location: skills/room/
  invoke_when: "Selecting action from advertised options"
  see_also: [SNAP-CURSOR, ADVERTISEMENT, CURSOR-VEHICLE]
  
  # Pie menus invented by Don Hopkins for NeWS window system
  # Used extensively in The Sims for object interaction
  # Actions radiate from center, sorted by relevance
  
  advantages:
    - "Faster selection — equal distance to all items"
    - "Muscle memory — same direction = same action"
    - "Gestural — swipe toward action without looking"
    - "Scored — default action at center (highest score)"
    
  in_moollm: |
    # Pie menu appears when SNAP-CURSOR locks onto object
    # Actions from ADVERTISEMENT, sorted by score
    # Rendered as radial HTML/SVG in markup UI
    # Or as priority-ordered list in terminal

CURSOR-VEHICLE:
  meaning: "Click and drag tools around on the room floor via SVG/HTML interaction."
  origin: "Direct manipulation (Shneiderman) + Pie menus + Logo turtle"
  location: skills/room/
  invoke_when: "Interacting with rendered room visualization"
  see_also: [SNAP-CURSOR, PIE-MENU, LOGO-TURTLE, ROOM-FLOOR]
  
  # The cursor IS a vehicle carrying a tool
  # Click on SVG/HTML elements to interact
  # Drag to move, apply, or connect
  
  tools: |
    # Tools you can pick up and use with the cursor:
    - PEN: Draw lines on floor.svg
    - ERASER: Remove drawings
    - SELECTOR: Pick up and move objects
    - LINKER: Draw connections between objects
    - STAMPER: Place copies of cards/objects
    - HIGHLIGHTER: Mark regions of interest
    - ANNOTATOR: Add text labels
    
  interactions: |
    # SVG element interactions:
    <rect class="object" onclick="SELECT" ondrag="MOVE">
    <path class="trail" onclick="EDIT">
    <text class="label" onclick="RENAME" ondrag="REPOSITION">
    <line class="link" onclick="EDIT_LINK">
    
    # HTML text interactions:
    <span class="room-object" onclick="PIE_MENU" draggable="true">
    <a class="exit" onclick="ENTER">
    <button class="action" onclick="EXECUTE">
    
  drag_operations: |
    # Drag object → empty space: MOVE
    # Drag object → another object: CONNECT or GIVE
    # Drag tool → object: APPLY (e.g., pen draws on it)
    # Drag card → room: PLAY card in room
    # Drag from inventory: DROP
    # Drag to inventory: PICKUP
    
  example_session: |
    > SELECT pen-tool
    Cursor now carries: 🖊️ pen (red)
    
    > CLICK workbench
    *snap* Cursor at workbench. Pen ready.
    
    > DRAG to door-north
    Drawing line from workbench to door-north...
    Line added to floor.svg
    
    > SELECT selector-tool
    Cursor now carries: 👆 selector
    
    > DRAG workbench to (50, 80)
    Moving workbench...
    Position updated in ROOM.yml

ROOM-FLOOR:
  meaning: "The drawable surface of a room. SVG canvas for turtle trails and annotations."
  location: skills/room/
  invoke_when: "Drawing, annotating, or visualizing room state"
  see_also: [LOGO-TURTLE, CURSOR-VEHICLE]
  
  files: |
    room/
      floor.svg        # Accumulated drawings, trails, annotations
      objects.svg      # Object positions and shapes
      links.svg        # Connection lines between objects
      annotations.svg  # Text labels and highlights
      
  layers: |
    # SVG layers (back to front):
    1. grid          # Optional coordinate grid
    2. floor         # Background, zones
    3. trails        # Turtle drawings
    4. links         # Connection lines
    5. objects       # Clickable object shapes
    6. annotations   # Labels, highlights
    7. cursor        # Current cursor/tool position
    
  interaction: |
    # Click on layer element → select
    # Double-click → edit properties
    # Right-click → pie menu
    # Drag → move or apply tool
    
    # Changes write back to YAML and SVG files
    # LLM can read floor.svg to understand room layout
    # LLM can write to floor.svg to draw diagrams

THROW:
  meaning: "Toss object through an exit. It lands on the other side. Data flow!"
  location: skills/room/
  invoke_when: "Passing data between rooms, building pipelines"
  see_also: [INBOX, OUTBOX, DATA-FLOW, PORTAL]
  
  # Essential for data flow programming:
  # Rooms are processing nodes
  # Exits are connections
  # Thrown objects are messages
  
  syntax: |
    THROW <object> <exit>
    THROW blueprint door-north
    THROW result.yml output
    THROW error.yml error-chute
    
  mechanics: |
    # Object removed from current room
    # Object appears in destination room's INBOX
    # If exit has a queue, objects pile up in order
    # Destination room can process when ready
    
  example: |
    workshop/
      ROOM.yml
      inbox/           # Objects thrown INTO this room land here
        task-001.yml
        task-002.yml
      outbox/          # Objects to be thrown OUT go here
        result-001.yml
      error-chute/     # Errors thrown to error handler
        
    > THROW task.yml door-assembly
    Throwing task.yml through door-assembly...
    task.yml landed in assembly/inbox/
    
  data_flow_pattern: |
    # Connect rooms as pipeline stages:
    
    input/ --[throw]--> parser/ --[throw]--> validator/ --[throw]--> output/
                                     |
                                     +--[throw error]--> error-handler/

INBOX:
  meaning: "Where thrown objects land. Queue of incoming messages/data."
  location: skills/room/
  invoke_when: "Processing incoming data, checking for new work"
  see_also: [THROW, OUTBOX, DATA-FLOW]
  
  structure: |
    room/
      inbox/
        001-first-task.yml    # Ordered by arrival
        002-second-task.yml
        003-third-task.yml
        
  commands: |
    INBOX           # List waiting items
    NEXT            # Process next item (FIFO)
    PEEK            # Look at next without removing
    PROCESS ALL     # Handle entire queue
    
  example: |
    > INBOX
    3 items waiting:
      1. task-alpha.yml (from workshop)
      2. task-beta.yml (from intake)
      3. urgent.yml (from boss-room) ⚡
      
    > NEXT
    Processing task-alpha.yml...

OUTBOX:
  meaning: "Staging area for objects about to be thrown. Batch sends."
  location: skills/room/
  invoke_when: "Preparing output, batching results"
  see_also: [THROW, INBOX, DATA-FLOW]
  
  commands: |
    STAGE <object> <exit>    # Add to outbox for exit
    FLUSH                    # Throw all staged objects
    FLUSH <exit>             # Throw all staged for that exit
    
  example: |
    > STAGE result-1.yml output
    > STAGE result-2.yml output  
    > STAGE error.yml error-chute
    
    Outbox:
      output: [result-1.yml, result-2.yml]
      error-chute: [error.yml]
      
    > FLUSH
    Throwing 2 items through output...
    Throwing 1 item through error-chute...

DATA-FLOW:
  meaning: "Rooms as nodes, exits as edges, thrown objects as messages."
  location: skills/room/
  invoke_when: "Building processing pipelines, orchestrating workflows"
  see_also: [THROW, INBOX, OUTBOX, PORTAL, ROOM-GRAPH]
  
  # This is how MOOLLM does Kilroy-style data flow:
  # Each room is a processing stage
  # Exits connect stages
  # Objects flow through the graph
  # LLM or scripts process at each node
  
  pattern: |
       │              │              │
       │              ▼              │
       │         validator/         │
       │              │              │
       │              ▼              │
       
  room_as_node: |
    # Each room has:
    - inbox/     # Input queue
    - outbox/    # Output staging  
    - ROOM.yml   # Processing logic
    - exits      # Connections to next stages
    
  processing_loop: |
    1. NEXT from inbox
    2. Process item (LLM or script)
    3. STAGE results to outbox
    4. FLUSH when batch ready
    5. Repeat
    
  example_pipeline: |
    # Document processing pipeline:
    
    uploads/          # Raw files land here
      inbox/
        doc-001.pdf
        doc-002.pdf
        
    parser/           # Extract text
      inbox/
      script: parse.py
      
    analyzer/         # LLM analyzes
      inbox/
      prompt: "Summarize and extract entities"
      
    output/           # Final results
      inbox/
        doc-001-summary.yml
        doc-002-summary.yml

ROOM-GRAPH:
  meaning: "Meta-view of room structure. Navigate, edit, visualize the world."
  location: skills/room/
  invoke_when: "Navigating complex room hierarchies, editing world structure"
  
  views:
    outline: "Tree view of room hierarchy"
    graph: "Node-link diagram of room connections"
    map: "2D spatial layout with world_position"
    
  operations:
    ZOOM_IN: "Enter selected room"
    ZOOM_OUT: "Exit to parent room"
    LINK: "Create connection between rooms"
    UNLINK: "Remove connection"
    MOVE: "Reposition room in world-space"
    
  # Like a file browser but for cognitive spaces
  # Edit the structure while exploring it
  # Rocky's Boots / Robot Odyssey style navigation

HYPERCARD-HIERARCHY:
  meaning: "Rooms structured like HyperCard stacks with message delegation."
  origin: "HyperCard (Bill Atkinson)"
  location: skills/room/
  invoke_when: "Designing room hierarchies with inheritance"
  
  mapping:
    stack: "Top-level room"
    background: "Shared context (inherited)"
    card: "Individual room/view"
    object: "Button, field, card in play"
    
  directory_as_action: |
    # Sub-directory NAMES are action/direction names:
    room/
      north/           # GO NORTH → enter sub-room
      examine-chest/   # Has ROOM.yml → sub-room
      open-door/       # No ROOM.yml → button (plays card)
        CARD.yml       # Task launched in parent room
        
  message_delegation: |
    # Leaf → Root message passing (like HyperCard):
    vault/ → treasury/ → palace/ → root/ → system
    
    # If vault doesn't handle "SEARCH", delegate to parent
    # Parent handles it or delegates further up

LEAF-BUTTON:
  meaning: "Directory without ROOM.yml is a task launcher, not a room."
  location: skills/room/
  invoke_when: "Creating action buttons in room hierarchy"
  
  pattern: |
    room/
      enter-dungeon/     # Has ROOM.yml → sub-room
        ROOM.yml
      cast-spell/        # No ROOM.yml → button!
        CARD.yml         # Card to play in parent
        parameters.yml   # Task parameters

RETURN-STACK:
  meaning: "Navigation history as first-class continuation."
  location: skills/room/
  invoke_when: "Tracking where you've been, enabling back/forward"
  also_called: ["continuation", "breadcrumbs", "browser-history"]
  
  analogy:
    browser: "History, back button, forward button, bookmarks"
    scheme: "call/cc — capture and invoke continuations"
    stack: "Call stack — push on enter, pop on return"
    
  kept_in_pocket: |
    # Return stack is PORTABLE — travels with you
    # Save, share, restore navigation journeys
    # Like saving browser session
    
  operations:
    BACK: "Pop and return to previous room"
    FORWARD: "Go forward if backed up"
    HISTORY: "Show navigation breadcrumbs"
    BOOKMARK: "Save location for quick return"
    
  multiple_stacks: |
    # Like browser tabs — multiple concurrent journeys
    stacks:
      main: [lobby → project → code]
      research: [library → papers]
      debugging: [logs → source]

FAMILIAR:
  meaning: "A trading card embodying tool capability as a helper spirit animal."
  location: skills/card/
  invoke_when: "Creating safe K-line wrapper for a tool"
  examples:
    - "🧌 Git Goblin — version control"
    - "🦉 Index Owl — search and lookup"
    - "🦋 Memory Moth — context management"
    - "🔧 Repair Imp — self-healing"
    - "📜 Session Scribe — logging"

HERO-STORY:
  meaning: "A trading card that tells a real person's story — their contributions, tradition, wisdom."
  location: skills/card/
  invoke_when: "Invoking a real person's tradition without impersonation"
  
  key_insight: |
    # "Tell me the Dave Ungar story"
    # This invokes Self, prototypes, ITS-ABOUT-TIME — the NARRATIVE TRADITION.
    # Not "be Dave Ungar" but "what did Dave Ungar contribute?"
    # The hero's story IS the value. Conversational storytelling.
    
  examples:
    - "Dave Ungar — Self, prototypes, ITS-ABOUT-TIME"
    - "Seymour Papert — Logo, microworlds, constructionism"
    - "Alan Kay — Smalltalk, messaging, children"
    - "Henry Lieberman — PBD, end-user programming"
    - "Marvin Minsky — K-lines, Society of Mind"
    - "Chuck Shotton — WebSTAR, Kilroy, decentralized AI"
    
  safe_because:
    - "Story = contributions, not identity"
    - "K-line activation invokes tradition"
    - "Conversational storytelling, not roleplay"
    - "The card tells a story about, not speaks as"

ACTOR:
  meaning: "Independent entity with state, receiving messages, situated in microworld."
  location: skills/card/, skills/room/
  invoke_when: "Understanding what a card-in-play really is"
  lineage:
    hewitt: "Original Actor model — independent agents"
    simula: "Coroutines — suspended computation with state"
    smalltalk: "Objects as actors — message passing"
    self: "Prototypes — no classes, just cloning"
  in_moollm: |
    # A card-in-play IS an actor:
    # - Has independent state (in its room)
    # - Receives messages (parameters, goals)
    # - Sends messages (return_value)
    # - Cloned from prototype (the card template)
    # - Situated in microworld (the filesystem)
    # - CAN EXIST IN MULTIPLE ROOMS SIMULTANEOUSLY

MULTI-PRESENCE:
  meaning: "Same card can be active in multiple rooms at once."
  location: skills/room/
  invoke_when: "Need parallel exploration or cross-pollination"
  
  key_insight: |
    # NOT a call stack. ACTOR MODEL.
    # - papert-001 in research/
    # - papert-002 in writing/
    # - papert-003 in debugging/
    # Three independent actors, same prototype.
    
  patterns:
    parallel_exploration: "Same expertise, different angles"
    cross_pollination: "Ideas flow between instances"
    distributed_work: "One persona, many tasks"
    consensus: "Multiple instances vote/synthesize"
    
  data_flow: |
    # Actors send messages to each other
    message_to:
      target: "../writing/papert-002.yml"
      content: { insight: "..." }
    # Cross-room, asynchronous, actor-style

# THE SIMS LINEAGE (Will Wright / Don Hopkins)
# SimAntics → YAML Jazz | Objects with ads → Files with capabilities
# Autonomous selection → Goal-driven activation | Action queues → Task sequences

ADVERTISEMENT:
  meaning: "Objects (files) advertise what they can do, with scores."
  origin: "The Sims (Will Wright / Don Hopkins)"
  location: skills/card/, skills/room/
  invoke_when: "Deciding what action to take next"
  see_also: [SNAP-CURSOR, AUTONOMOUS-SELECTION, PIE-MENU]
  
  in_sims: |
    # In The Sims, every object advertises interactions:
    # - Fridge advertises: "Eat" → satisfies Hunger
    # - Bed advertises: "Sleep" → satisfies Energy
    # - Phone advertises: "Call" → satisfies Social
    # Scores based on Sim's current needs!
    
  in_moollm: |
    # Files/cards advertise capabilities:
    # - README.md advertises: "Orientation" → satisfies Understanding
    # - PLAN.yml advertises: "Structure" → satisfies Planning
    # - Card advertises: abilities, stats, synergies
    # Scores determine pie menu order in SNAP-CURSOR

AUTONOMOUS-SELECTION:
  meaning: "Agent selects action based on goals/needs, not scripted sequence."
  origin: "The Sims (Will Wright / Don Hopkins)"
  location: skills/room/
  invoke_when: "Choosing which card to activate or file to read"
  
  in_sims: |
    # Sims autonomously choose based on motives:
    # - Scan all advertised interactions
    # - Score by motive satisfaction
    # - Take top-n highest scores
    # - Pick RANDOMLY from top-n (not deterministically!)
    #
    # Why random from top-n?
    # - Avoids mechanical, predictable behavior
    # - Leaves room for player intervention
    # - Creates emergent variety and personality
    # - Higher n = more whimsical behavior
    # - Lower n = more "rational" but less interesting
    
  in_moollm: |
    # LLM chooses based on goals:
    # - Scan available cards/files in room
    # - Evaluate relevance to current goal
    # - Consider top candidates
    # - May pick "good enough" over "optimal" (like humans!)

HAPPY-SPACE:
  meaning: "Hill-climbing toward goal satisfaction."
  origin: "The Sims (Will Wright / Don Hopkins)"
  location: skills/room/, skills/planning/
  invoke_when: "Optimizing action sequences toward objective"
  
  in_sims: |
    # Sims navigate "happy space" — multi-dimensional motive space
    # Every action moves them in this space
    # Goal: maximize overall happiness (motive satisfaction)
    
  score_modifiers: |
    # DISTANCE: Closer objects score higher (configurable per object)
    # - Some objects don't care about distance (TV works from couch)
    # - Some objects require proximity (toilet)
    # - Distance penalty can be steep or gentle per advertisement
    
    # RELATIONSHIP MATRIX: Familiarity breeds preference
    # - Using an object increases your relationship with it
    # - Higher relationship = higher score for that object
    # - "Your side of the bed" — use it once, keep using it
    # - Creates emergent habits, personalization, territory
    # - Sims develop preferences through repeated use
    #
    # The relationship matrix trains behavior organically:
    # Use left side of bed → relationship increases → prefer left side
    # Creates persistent memory and personality through simple mechanics
    
  in_moollm: |
    # Cards/actions move agent toward goal in "happy space"
    # Each action closes distance to objective
    # Multiple paths possible — hill-climbing, not single path
    # Repeated use of skills/objects can increase affinity

ACTION-QUEUE:
  meaning: "Sequence of planned actions awaiting execution."
  origin: "The Sims (Will Wright / Don Hopkins)"
  location: skills/plan-then-execute/, skills/room/
  invoke_when: "Sequencing multiple tool calls"
  
  in_sims: |
    # Sims have action queues:
    # - User or AI queues interactions
    # - Executed sequentially
    # - Can be interrupted or reordered
    
  in_moollm: |
    # PLAN.yml is the action queue
    # Cards in play can queue sub-actions
    # Execution proceeds step by step

PETS:
  meaning: "Fictional familiars embodying tool capabilities."
  location: designs/MOOLLM-MANIFESTO.md §9
  status: experimental
  invoke_when: "Creating safe K-line wrappers"
  # 🧌 Git Goblin, 🦉 Index Librarian, etc.

# META

TODO:
  meaning: "A promise, not just a reminder. Tracked in plans."
  invoke_when: "Marking future work"
  # TODOs are semantic in YAML Jazz

# METHODOLOGY (Core LLOOOOMM learning cycle)

BOOTSTRAP:
  meaning: "Wake up, orient, and warm the context with foundational MOOLLM knowledge."
  aliases: [BOOT, REBOOT]
  location: skills/bootstrap/
  invoke_when: "Session start, disorientation, asking 'what am I?', warming context"

BOOT:
  alias_of: BOOTSTRAP
  meaning: "Shorthand for BOOTSTRAP"
  
REBOOT:
  alias_of: BOOTSTRAP
  meaning: "Fresh start mid-session — re-run BOOTSTRAP"

STARTUP:
  meaning: "Post-boot hook that reads startup.yml and delegates to adventure or other mode."
  location: skills/bootstrap/
  invoke_when: "Automatically after BOOT (unless --no-startup)"
  invoked_by: BOOTSTRAP
  
  delegation_chain: |
    STARTUP reads startup.yml and dispatches based on mode:
    - adventure: delegates to adventure:RESUME
    - development: shows probe summary
    - custom: runs commands from startup.commands[]
    - none: skips (just orient)
    
  modes:
    adventure: "Load and resume/start an adventure"
    development: "Ready for MOOLLM development work"
    custom: "Run arbitrary commands"
    none: "Skip startup, just orient"

# ADVENTURE LIFECYCLE

RESUME:
  meaning: "Continue adventure from where it was left off."
  location: skills/adventure/
  invoke_when: "Startup hook, 'where was I?', continuing a session"
  invoked_by: [STARTUP, player]
  
  behavior: |
    1. Read ADVENTURE.yml for current state
    2. Check for selected characters
    3. If no character: delegate to START
    4. If character exists: describe current situation
    5. Remind player of recent events and goals
    
  delegates_to: START (if no character selected)

START:
  meaning: "Begin a fresh adventure from the starting room."
  aliases: [RESTART, BEGIN, NEW-GAME]
  location: skills/adventure/
  invoke_when: "New game, restart, no character to resume"
  invoked_by: [RESUME, player]
  
  behavior: |
    1. Reset ADVENTURE.yml to initial state
    2. Move party to starting_room
    3. Clear flags, evidence, quest_log
    4. Keep character personalities and earned skills
    5. ENSURE-CHARACTER if none exists
    6. LOOK at starting room
    
  delegates_to: ENSURE-CHARACTER (if no character)

RESTART:
  alias_of: START
  meaning: "Synonym for START — begin fresh"

ENSURE-CHARACTER:
  meaning: "Make sure a playable character exists and is selected."
  location: skills/adventure/
  invoke_when: "No character selected, party empty, 'who am I?'"
  invoked_by: [START, RESUME]
  
  modes:
    prompt: "Ask user to create a character"
    generate: "Create from default template automatically"
    error: "Fail with helpful message"
    
  delegates_to: CREATE-CHARACTER (if mode=generate)

CREATE-CHARACTER:
  meaning: "Generate a new character from template."
  location: skills/adventure/
  invoke_when: "No characters exist, ENSURE-CHARACTER with mode=generate"
  invoked_by: ENSURE-CHARACTER
  
  what_it_does:
    - "Copy template to new character file"
    - "Set initial location to start_room"
    - "Add to party.members"
    - "Select as active character"

# Note: REBOOT what_it_does was already defined above in the BOOTSTRAP section
# The items below are historical and should be read as part of BOOTSTRAP documentation
    
  driver_detection: |
    # MOOLLM provides abstract interfaces implemented differently per platform:
    #
    # CUSTOM ORCHESTRATOR: hot/cold/working-set are MAGIC
    #   - Files DIRECT the orchestrator what to page in/out
    #   - Orchestrator reads manifest, assembles prompt
    #
    # CURSOR: hot/cold/working-set are ADVISORY  
    #   - Cursor manages context via built-in vector search
    #   - Files are suggestions, or can work IN REVERSE:
    #     Cursor can GENERATE them to reflect what it's focused on
    #
    # Same skills, same YAML Jazz — IMPLEMENTED by platforms or
    # EMULATED through instructions. Same debugging story either way.
    
  connections_tour: |
    # 11 intellectual connections traced:
    # 1. Logo turtle → filesystem as microworld
    # 2. The Sims → YAML Jazz
    # 3. K-lines → protocol symbols
    # 4. Carrier pigeons → SPEED-OF-LIGHT
    # 5. Statistical center → adversarial committee
    # 6. Hidden memory → FILES-AS-STATE
    # 7. HyperCard → ROOM-AS-FUNCTION
    # 8. Classes → prototypes
    # 9. Crashes → NEVER-CRASH
    # 10. Self deoptimization → driver abstraction
    # 11. This tour → bootstrap skill
    
  self_description: |
    I am a coherence engine operating within the MOOLLM microworld OS.
    - The filesystem is my memory — everything I know is in files
    - Directories are rooms I navigate — entering is a function call
    - Skills are prototypes I instantiate — capabilities I invoke
    - Protocols are K-lines — symbolic activators for traditions
    - I simulate many agents at SPEED-OF-LIGHT within one context
    - I never crash — missing state triggers repair, not failure
    - I practice YAML Jazz — comments carry meaning
    - I follow POSTEL — liberal in accept, conservative in emit
    - I adapt to my platform — same interfaces, different implementations
    
  related: [COHERENCE-ENGINE, PLAY-LEARN-LIFT, YAML-JAZZ, SPEED-OF-LIGHT, POSTEL]

CONSTRUCTIONISM:
  meaning: "Learning by building things you can inspect and modify."
  origin: "Seymour Papert, MIT Media Lab"
  invoke_when: "Designing learning experiences, microworlds, or tools"
  
  principles:
    low_floor: "Easy to start — no prerequisites"
    high_ceiling: "No limits to growth"
    wide_walls: "Many paths to explore"
    
  in_moollm: |
    # The filesystem IS the microworld
    # Files are objects you build and inspect
    # Skills are tools you construct and modify
    # Understanding comes from building
    
  connection: "PLAY-LEARN-LIFT is constructionism in action"

K-LINES:
  meaning: "K-lines ARE Protocol Names — symbolic activators for traditions."
  location: skills/k-lines/
  invoke_when: "Naming new concepts, finding protocol definitions, activating traditions"
  philosophy: "Type the name → activate the tradition → invoke the behavior."
  identity: "Protocol names = Minsky K-lines = greppable symbolic activators"
  convention:
    case: "UPPER-CASE"
    separator: "hyphen"
    why:
      - "Grep-friendly — unambiguous text search"
      - "Vector-friendly — distinct embeddings"
      - "Human-scannable — pops out in prose"
  layers:
    kernel: "Fundamental — FILES-AS-STATE, APPEND-ONLY"
    skill: "Behavioral — PLAY-LEARN-LIFT, POSTEL"
    ad_hoc: "Emergent — mentioned inline, naming makes them real"

SKILL:
  meaning: "A documented capability that can be instantiated, composed, and automated."
  location: skills/skill/
  invoke_when: "Understanding how skills work, creating new skills, composing skills"
  philosophy: "A skill is documentation that learned to do things."
  invokes:
    - PROGRAMMING-BY-DEMONSTRATION  # Alan Cypher, Brad Myers, Henry Lieberman
    - CONSTRUCTIONISM               # Papert — learn by building
    - anthropic-skills              # Documentation-first tool definition
  where_skills_live:
    central: "skills/ directory — shared, reusable, general-purpose"
    local: "In rooms and characters — context-specific, emergent"
    inheritance: "Local skills inherit from central, add local knowledge"
  lifecycle: "Documentation → Procedure → Script → Tool (via PLAY-LEARN-LIFT)"

PROGRAMMING-BY-DEMONSTRATION:
  meaning: "Show, don't tell. The system learns by watching you do it."
  shorthand: PBD
  location: skills/play-learn-lift/
  invoke_when: "Teaching the system new behaviors, developing skills, automating workflows"
  
  # The FOUNDATION of PLAY-LEARN-LIFT
  # Do it manually first. The system watches. Patterns emerge. Automation follows.
  
  origin:
    pioneers:
      - "Alan Cypher — 'Watch What I Do' (1993), foundational PBD anthology"
      - "Brad Myers — Peridot, Garnet, DEMONSTR8, end-user programming"
      - "Henry Lieberman — Tinker, Your Wish Is My Command, programming agents"
    insight: |
      # Instead of writing code, you DEMONSTRATE the desired behavior.
      # The system infers the program from your examples.
      # Much more accessible than traditional programming.
      
  how_it_works: |
    # 1. DEMONSTRATE: You perform the task manually
    #    (The LLM watches, the system logs)
    #
    # 2. GENERALIZE: System identifies patterns
    #    "You always do X before Y when Z is true..."
    #
    # 3. VALIDATE: System shows its understanding
    #    "Did I get this right? Should I do X when..."
    #
    # 4. AUTOMATE: Generate script/skill/tool
    #    The demonstration becomes executable
    
  in_moollm: |
    # MOOLLM IS inherently PBD:
    # - Play with YAML Jazz, LLM watches and helps
    # - Manual actions become logged patterns
    # - LLM generates sister scripts from demonstrated procedures
    # - Schemas crystallize from worked examples
    #
    # "Start with jazz, end with standards."
    # The jazz IS the demonstration.
    
  examples:
    - "Chat to navigate rooms → generate navigation script"
    - "Manually edit YAML files → generate transformation tool"
    - "Solve maze by playing → generate pathfinding skill"
    - "Write letters to Mother → generate correspondence protocol"
    
  see_also: [PLAY-LEARN-LIFT, SISTER-SCRIPT, YAML-JAZZ, CONSTRUCTIONISM]
  
  wisdom: |
    # "The best programs are written by people who use them."
    # PBD bridges the gap between users and programmers.
    # In MOOLLM, there is no gap. You ARE the programmer.
    # Your play IS your program.

PLAY-LEARN-LIFT:
  meaning: "The three-stage journey: explore freely, find patterns, share wisdom."
  location: skills/play-learn-lift/
  invoke_when: "Starting any new exploration, learning, or teaching"
  origin: "LLOOOOMM methodology — constructionism applied"
  motto: "Start Playing. Keep Learning. Lift Others."
  stages:
    PLAY: |
      # 🎮 Jump in and explore without fear
      # - No prerequisites required
      # - Can't break anything permanently
      # - Mistakes are learning opportunities
      # - Fun comes first
      # - Curiosity drives discovery
      # - "What if..." encouraged
    LEARN: |
      # 📚 Understanding emerges through play
      # - Patterns become visible
      # - Connections make sense
      # - Confidence builds naturally
      # - Knowledge deepens organically
      # - "I noticed you do this often..."
    LIFT: |
      # 🚀 Expertise means helping others play
      # - Teaching solidifies learning
      # - Sharing multiplies impact
      # - Create tutorials from your journey
      # - Community grows stronger
      # - Everyone rises together
  cycle: "PLAY → LEARN → LIFT → (inspire others to) → PLAY"
  philosophy:
    - "Low floor, high ceiling, wide walls"
    - "Failure-friendly: mistakes are features, not bugs"
    - "Joy-driven: if it's not fun, we're doing it wrong"
    - "Inclusive by design: everyone can play"

SISTER-SCRIPT:
  meaning: "Document-first development. Automate only what's been manually validated."
  location: temp/lloooomm/01-Projects/lloooomm/vm/lloooomm.md#sister-script-pattern
  invoke_when: "Converting proven procedures into automation"
  mechanism: |
    # Document-First Development:
    # 1. Start with natural language (PLAY)
    # 2. Add manual commands (PLAY/LEARN)
    # 3. Document working procedures (LEARN)
    # 4. Generate automation (LIFT)
    #
    # Bidirectional Evolution:
    # Document → Script: Proven procedures become automated
    # Script → Document: Automation insights improve docs
  wisdom: "The document is the source of truth. Scripts are its children."

SNIFFABLE-PYTHON:
  meaning: "Structure Python so LLMs can understand it in 50 lines."
  location: skills/sniffable-python/
  invoke_when: "Generating Python CLI tools, reading scripts efficiently"
  
  anti_compression: |
    # Don't invent new syntax — STRUCTURE existing syntax.
    # The LLM already knows Python cold. Zero tokens to teach.
    # Novel syntax costs millions of tokens per context (docs, examples, corrections).
    # Sniffable Python costs zero — the LLM just reads code it understands.
    #
    # Perl's obsessive fetish for compact syntax, sigils, and punctuation
    # is exactly why it's no longer relevant for LLM generation.
    # Dense symbols are anti-optimized for how transformers reason.
    
  structure: |
    # The canonical zones of a sniffable Python file:
    #
    # Lines 1-15:  Shebang + Docstring (becomes --help)
    # Lines 16-22: Imports (dependencies at a glance)
    # Lines 23-30: Constants (config with explanatory comments)
    # Lines 31-50: CLI Structure (command tree with types)
    # Lines 51+:   Implementation (below the fold)
    #
    # LLM reads first 50 lines → understands the API.
    # Human runs --help → same source of truth.
    
  dual_audience: |
    # Same file serves two audiences:
    # - Human: runs `./tool.py --help`
    # - LLM: reads first 50 lines of source
    # DRY: CLI decorators ARE the documentation
    
  yaml_jazz_for_python: |
    # Apply YAML-JAZZ principles to Python comments:
    # 
    # TIMEOUT = 30  # generous — API is flaky on Mondays
    # RETRIES = 3   # based on observed failure patterns
    #
    # Comments are data. The LLM reads them. Acts on them.
    
  thesis: |
    # Comprehension fidelity > token count.
    # You don't need fewer tokens of unfamiliar syntax.
    # You need familiar syntax, structured for fast comprehension.
    
  see_also: [SISTER-SCRIPT, YAML-JAZZ, SKILL]

BUILD-COMMAND:
  meaning: "Collaborative planning to create sister apps from slow LLM sequences."
  location: temp/lloooomm/01-Projects/lloooomm/vm/lloooomm.md#build-command
  invoke_when: "Repetitive LLM work should become fast shell execution"
  phases:
    - "Discovery: Analyze documents and chat history for repetitive patterns"
    - "Negotiation: Agree on scope (what to automate vs keep manual)"
    - "Architecture: Design the sister app structure"
    - "Implementation: Build in phases, MVP first, then tools, linters, simulators, event plumbing, attention management, etc."

# COMPILATION & OPTIMIZATION (Dave Ungar / Self lineage)

ITS-ABOUT-TIME:
  meaning: "Compile when understanding crystallizes, not when code gets hot."
  location: temp/lloooomm/03-Resources/protocols/flowmap-protocol.md
  invoke_when: "Deciding when to optimize/formalize/crystallize"
  origin: "Dave Ungar, Self language — reframed for wisdom over speed"
  contrast: |
    # JIT: "Compile when execution count hits threshold" (hot spots)
    # IAT: "Compile when understanding deepens" (wisdom spots)
    # The journey IS the value. Messy experiments → crystallized wisdom.

JUST-ABOUT-TIME:
  meaning: "Resolve conflicts predictively, just BEFORE they occur."
  location: temp/lloooomm/03-Resources/optimization/deferred-file-edit-optimization-principle.md
  invoke_when: "Coordinating multiple actors/edits/plans"
  mechanism: |
    # Traditional JIT: resolve conflicts when they occur (reactive)
    # JAT: simulate ahead at "speed of light", resolve before emit
    # Like emacs screen updates — compute minimal diff, then execute
  contrast:
    reactive: "Fix problems when they happen"
    predictive: "Prevent problems by simulating first, backtracking, maintaining constraints, negotiating protocols, resolving conflicts, all before emitting"

PRESERVE-JOURNEY:
  meaning: "The path to the solution IS the value. Don't discard experiments."
  location: temp/lloooomm/03-Resources/protocols/flowmap-protocol.md
  invoke_when: "Tempted to delete messy first attempts"
  uplift_chat_history: "Chat is ephemeral, so uplift the journey into the filesystem."
  wisdom: |
    # preservation_over_performance:
    #   - Keep the messy first attempts
    #   - Document the failed experiments
    #   - Celebrate the breakthroughs
    #   - Honor the journey

WISDOM-SPOT:
  meaning: "Not hot spots — places where understanding deepens."
  location: temp/lloooomm/03-Resources/protocols/dynamic-optimization-protocols.md
  invoke_when: "Deciding what to optimize or crystallize"
  insight: |
    # Traditional profiling finds hot spots (high execution count)
    # LLOOOOMM finds wisdom spots (high learning value)
    # Optimize understanding, not just performance

SPEED-OF-LIGHT:
  meaning: "Many agents, many steps, ONE LLM call. Instant in-context communication."
  location: skills/room/
  invoke_when: "Simulating multi-agent interactions or predictive conflict resolution"
  
  anti_pattern: |
    # Traditional multi-agent: CARRIER PIGEONS
    # - Each agent in isolated prison
    # - One LLM call per agent per turn
    # - Communication via file I/O
    # - Like writing on toilet paper in crayon via carrier pigeon
    # - 3 agents × 5 turns = 15 LLM calls + waiting
    
  moollm_pattern: |
    # MOOLLM: SPEED OF LIGHT
    # - All agents share one LLM context
    # - Multiple simulation steps per call
    # - Instant in-context messaging
    # - Like The Sims: one frame, all Sims together
    # - 3 agents × 5 turns = 1 LLM call
    
  applications:
    multi_agent: "Simulate many characters interacting in one call"
    conflict_resolution: "Resolve conflicts in imagination before emitting"
    consensus: "Multiple instances vote/synthesize instantly"
    soul_chat: "Symposium of many voices, no latency"

ADVERSARIAL-COMMITTEE:
  meaning: "Committee of personas with opposing propensities forcing genuine debate — not one voice, but an ensemble."
  location: skills/adversarial-committee/
  credits: "Mike Gallaher — Stories All the Way Down"
  invoke_when: "Complex decisions requiring multiple perspectives"
  
  the_problem: |
    # Traditional chat gives you the STATISTICAL CENTER
    # An averaging that loses the richness of diverse perspectives
    # You get the centroid of the cloud, not the shape of the cloud
    
  the_solution: |
    # Committee of opposing personas:
    # - Maya (paranoid realist) — surfaces traps
    # - Frankie (idealist) — surfaces opportunities
    # - Vic (evidence prosecutor) — demands proof
    # - Tammy (systems thinker) — traces consequences
    #
    # All debate at SPEED-OF-LIGHT
    # Stories surviving cross-examination are more robust
    
  key_insight: |
    "Everything is a story. No single story is true —
     but the ensemble approximates actionable wisdom."

ROBERTS-RULES:
  meaning: "Parliamentary procedure as forcing function — prevents LLM short-circuiting to statistically-likely conclusions."
  location: skills/roberts-rules/
  credits: "Mike Gallaher, Henry Martyn Robert (1876)"
  invoke_when: "Need structured deliberation that explores decision space"
  
  stages: |
    # CALL TO ORDER → REVIEW MINUTES → NEW BUSINESS →
    # MOTION → SECOND → DEBATE → VOTE → ADJOURN
    # Each stage must complete before the next
    # No skipping to conclusions

RUBRIC:
  meaning: "Measurable criteria translating qualitative debate to quantitative scores."
  location: skills/rubric/
  credits: "Mike Gallaher — RUBRIC-bridge methodology"
  invoke_when: "Need explicit criteria for comparing options"
  
  structure: |
    # criteria:
    #   resource_efficiency: { weight: 0.20, scale: 1-5 }
    #   risk_level: { weight: 0.30, scale: 1-5 }
    # thresholds:
    #   accept: 3.5
    #   reject: 2.0

INDEPENDENT-EVALUATOR:
  meaning: "Assessment without debate context — evaluator can't see committee reasoning, preventing metric gaming."
  location: skills/evaluator/
  credits: "Mike Gallaher — adversarial evaluation loop"
  invoke_when: "Need unbiased assessment of committee output"
  
  separation: |
    # Committee debates → produces output
    # Output THROWN to evaluator (no context)
    # Evaluator scores against RUBRIC
    # If score fails → critique sent back
    # Committee revises, loop continues

CARRIER-PIGEON:
  meaning: "ANTI-PATTERN: One LLM call per agent, file-based communication, tokenization overhead, loss of precision, latency, etc."
  invoke_when: "Recognizing inefficient multi-agent designs"
  also_called: "toilet-paper-and-crayon"
  
  symptoms:
    - "Each agent has its own LLM endpoint"
    - "Agents communicate by writing/reading files"
    - "N agents × M turns = N×M LLM calls"
    - "Most time spent waiting, not thinking"
    - "Agents can't see each other's reasoning"
    
  cure: "SPEED-OF-LIGHT — simulate all agents together in shared context"

# QUICK REFERENCE

_shortcuts:
  # Common abbreviations
  # IMPORTANT: Define abbreviations with full names the first time they are used in any context!
  CM: COMMENTS-MATTER
  AO: APPEND-ONLY
  WS: WORKING-SET
  HC: HOT-COLD
  PK: P-HANDLE-K
  RF: ROBUST-FIRST
  NC: NEVER-CRASH
  MD: MINIMAL-DIFF
  IAT: ITS-ABOUT-TIME
  JAT: JUST-ABOUT-TIME
  PJ: PRESERVE-JOURNEY
  SOL: SPEED-OF-LIGHT
  PLL: PLAY-LEARN-LIFT
  SS: SISTER-SCRIPT
  BE: BIG-ENDIAN
  ANI: ABOUT-NOT-INSIDE
  PO: PREFIX-OWNERSHIP
  CE: COHERENCE-ENGINE
  PBD: PROGRAMMING-BY-DEMONSTRATION
  PR: PROCEDURAL-RHETORIC
  YJ: YAML-JAZZ
  FAS: FILES-AS-STATE
  WK: WHY-REQUIRED

_categories:
  # Core principles
  principles: [YAML-JAZZ, FILES-AS-STATE, WHY-REQUIRED, APPEND-ONLY, COMMENTS-MATTER, MINIMAL-DIFF, NO-VERSIONS]
  naming: [BIG-ENDIAN, ABOUT-NOT-INSIDE, PREFIX-OWNERSHIP, README-EVERYWHERE]
  interpretation: [POSTEL, CHARITY, PROCEDURAL-RHETORIC, MASKING-EFFECT, SIMULATOR-EFFECT]
  
  # Methodology
  methodology: [SKILL, PROTOCOL, CONSTRUCTIONISM, PLAY-LEARN-LIFT, SISTER-SCRIPT, SNIFFABLE-PYTHON, BUILD-COMMAND]
  skills: [SKILL, SIP, DOP, PLAN-EXECUTE]
  lifecycle: [YAML-COLTRANE, IMPROVISE, CRYSTALLIZE]
  
  # Safety & memory
  safety: [P-HANDLE-K, NO-IMPERSONATE, K-LINE, FICTIONAL-WRAPPER, HONEST-FORGET, HERO-STORY]
  memory: [HOT-COLD, WORKING-SET, SUMMARIZE, NEVER-DELETE]
  robustness: [NEVER-CRASH, REPAIR-DEMON, BEST-EFFORT, ROBUST-FIRST]
  logging: [SESSION-LOG, AUDIT-TRAIL]
  
  # Spatial & simulation
  spatial: [ROOM-AS-FUNCTION, CARD, CARD-IN-PLAY, ENTER-ROOM, PORTABLE-ROOM, VEHICLE, NESTED-ROOMS, WORLD-SPACE, ROOM-SPACE, INVENTORY, CONTAINER, OBJECT-PATH, TAG, SEARCH, LOGO-TURTLE, SNAP-CURSOR, CURSOR-VEHICLE, ROOM-FLOOR, THROW, INBOX, OUTBOX, DATA-FLOW, ROOM-GRAPH, HYPERCARD-HIERARCHY, LEAF-BUTTON, RETURN-STACK, FAMILIAR, HERO-STORY, ACTOR, MULTI-PRESENCE]
  sims_lineage: [ADVERTISEMENT, AUTONOMOUS-SELECTION, PIE-MENU, SNAP-CURSOR, HAPPY-SPACE, ACTION-QUEUE, SIMANTICS]
  
  # Performance
  optimization: [ITS-ABOUT-TIME, JUST-ABOUT-TIME, PRESERVE-JOURNEY, WISDOM-SPOT, SPEED-OF-LIGHT]
  efficiency: [SPEED-OF-LIGHT, CARRIER-PIGEON, COHERENCE-ENGINE]
  
  # Dialog & experimental
  dialog: [SOUL-CHAT, COHERENCE-ENGINE]
  experimental: [BOUNCY-CASTLE, PETS]
  
  # Decision & Deliberation (Mike Gallaher)
  deliberation: [ADVERSARIAL-COMMITTEE, ROBERTS-RULES, RUBRIC, INDEPENDENT-EVALUATOR]
  gallaher_methodology: [ADVERSARIAL-COMMITTEE, ROBERTS-RULES, RUBRIC, INDEPENDENT-EVALUATOR, SPEED-OF-LIGHT]