inventory

# INVENTORY > **"Carry pointers or values. Set them down, they become real."** The universal protocol for carrying, storing, and transferring objects. Applies to ANY container: characters, bags, rooms, artifacts, vehicles. --- ## Files in This Skill - `SKILL.md` — Full protocol documentation (this file) - `README.md` — Human landing page - `CARD.yml` — Interface definition - `INVENTORY.yml.tmpl` — Standalone inventory template --- ## Core Philosophy **Inventory holds two kinds of things: POINTERS and VALUES.** Your character's home directory is their "bag." Items in it are: | Type | Weight | What You Have | |------|--------|---------------| | **Pointer** | 0 | Reference to where something lives | | **Value** | varies | Text, number, array, object, subtree | | **Object** | item.weight | Deep copy of the actual thing | | **Fungible** | per-item | Stack with count, no individual tracking | **Pointers are lightweight:** You don't carry the brass lantern. You carry a *path* to where it lives. **Values are direct:** You can also carry raw text, numbers, arrays, entire subtrees — any YAML/JSON value. When you drop either kind, it gets **boxed** into a YAML file with its own existence. --- ## Universal Application Inventory applies to ANY container, not just characters: | Container | Has Inventory? | Example | |-----------|---------------|---------| | **Character** | ✓ | Palm's backpack | | **Bag** | ✓ | Bag of holding | | **Room** | ✓ (implicit) | Objects in the pub | | **Chest** | ✓ | Treasure chest contents | | **Vehicle** | ✓ | Cargo hold | | **Artifact** | ✓ | Ring with stored spell | **Embedding inventory:** ```yaml # In CHARACTER.yml (most common) inventory: refs: - pub/bar/brass-lantern.yml fungibles: - { proto: economy/gold.yml, count: 500 } # Or standalone INVENTORY.yml for any container # bag-of-holding/INVENTORY.yml inventory: refs: - kitchen/cookie-jar.yml#cookie - street/acme-catalog.yml objects: - { id: magic-sword, name: "Vorpal Blade", weight: 3 } ``` --- ## Reference Types References can point into ANY file type. A reference is just a string that locates something. ### Pointer Syntax | Syntax | Points To | Example | |--------|-----------|---------| | `path/to/file.yml` | Whole YAML file | `pub/cookie-jar.yml` | | `file.yml#id` | Section by id | `pub/cookie-jar.yml#cookie` | | `file.yml#parent.child` | Nested path | `seating.yml#bar.stool-1` | | `file.md#heading` | Markdown heading | `characters/README.md#doctor-no` | | `file.json#/json/path` | JSON pointer | `config.json#/settings/defaults` | | `file.ext?search=pat` | Search pattern | `npcs.yml?name=Henk` | | `file.cpp:42` | Line number | `engine.cpp:142` | | `file.py:10-25` | Line range | `adventure.py:100-150` | **The pointer is the reference.** It can point to: - A prototype in a YAML file - A section embedded in a larger file - A heading in a markdown document - A JSON field - Even a line in source code ### Unified Addressing This pointer syntax is shared across ALL systems: | System | Uses Pointers For | |--------|-------------------| | **Inventory** | What you carry (`refs:`) | | **Location** | Where you are (`location:`) | | **Postal** | Where to deliver mail (`to:`) | | **Structural Editing** | Where to PEEK/POKE | Same syntax, everywhere. Mail a letter to a function. Stand on a JSON key. POKE a value into a YAML path. It's all the same address space. **Not all addresses make sense — but they're all valid.** You can stand on `package.json#/devDependencies/vitest`. Weird? Sure. Works? Yes. ### Reference Structure Simple reference (just a string): ```yaml inventory: refs: - pub/bar/brass-lantern.yml - street/acme-catalog.yml#portable-hole ``` Rich reference (with metadata): ```yaml inventory: refs: - ref: pub/bar/brass-lantern.yml acquired: "2026-01-23T10:00:00Z" condition: "good" note: "Found in the cellar" ``` --- ## Location as Pointer (Code as Space) **The pointer syntax is bidirectional.** Not just "what you carry" — also "where you ARE." Any object's `location:` field uses the same pointer syntax. This means characters, artifacts, and entities can exist *inside* any file type: ```yaml # Character standing on a TypeScript function name: Alice location: src/lib/utils.ts#fetchData note: "Reviewing this function with the team" # Artifact placed at a specific line range name: Bug Marker location: src/auth/login.ts:45-67 note: "The authentication bug lives here" # Entity inside a JSON config name: Config Watcher location: package.json#/dependencies/svelte note: "Monitoring version changes" ``` ### Code Review as Adventure A hacking party can literally stand inside source code: ```yaml # The review party participants: - { name: Alice, location: "src/api/handler.ts#processRequest" } - { name: Bob, location: "src/api/handler.ts#validateInput" } - { name: Carol, location: "src/api/handler.ts:89-95" } # The problematic lines session: topic: "Why does validation fail on unicode input?" room: "src/api/handler.ts" context: "Standing around the processRequest function" ``` ### What This Enables | Use Case | Location Pointer | |----------|------------------| | **Code review** | Stand on functions, discuss them | | **Bug hunting** | Place markers at suspicious lines | | **Pair programming** | Multiple characters at same location | | **Architecture tours** | Walk through a codebase as rooms | | **Documentation** | Annotate code with character observations | **The codebase becomes a dungeon.** Files are rooms. Functions are objects. Line ranges are specific spots. Characters can go there, look around, leave notes, argue about what they see. --- ## Pickup Modes Two fundamentally different ways to pick something up: ### TAKE REF — Lightweight Pointer ``` > TAKE REF TO brass-lantern You now have a reference to the brass lantern. (weight: 0) ``` **What happens:** 1. Create pointer in your inventory 2. Object stays where it is 3. Object's `location` field updates: `location: "characters/don/inventory"` 4. You have zero weight added **Use when:** - Just need access to it - Don't want to carry weight - Shared resource (dispenser, catalog) - Can't physically move it (too heavy) ### TAKE OBJECT — Deep Copy ``` > TAKE OBJECT cookie You pick up the cookie. (weight: 0.1) ``` **What happens:** 1. Copy entire object into your inventory 2. Your file gets bigger (embedded object) 3. Weight added to your load 4. Original MAY stay or be deleted (your choice) **Use when:** - Small object, negligible weight - Want to OWN it completely - Need to modify it freely - Don't want inheritance chain ### Picking Up Boxed Items **GOLDEN RULE: Once boxed, always boxed.** If something already has a file (is "boxed"), picking it up preserves everything: ```yaml # kitchen/acme-catalog-001.yml already exists with: # inherits: street/acme-catalog.yml # annotations: ["circled portable hole"] # dropped_by: palm # Don picks it up AS OBJECT: # File moves to: characters/don/acme-catalog-001.yml # All annotations preserved! # Don picks it up AS REF: # inventory: [ref: "kitchen/acme-catalog-001.yml"] # File stays in kitchen, Don just has pointer. ``` --- ## Drop Modes Three fundamentally different ways to put something down: ### DROP AS BOX — Create New File ``` > DROP brass-lantern AS BOX Created: kitchen/brass-lantern-001.yml ``` **What happens:** 1. Create new YAML file at destination 2. New file `inherits:` from your ref's target 3. Adds boxed metadata (who, when, where) 4. You can KEEP your original ref (sharing) or consume it 5. Boxed item now has its own existence and local state **Boxing creates an instance:** ```yaml # kitchen/brass-lantern-001.yml object: inherits: "pub/bar/brass-lantern.yml" # Instance metadata instantiated_at: "2026-01-23T14:00:00Z" instantiated_by: "don" instantiated_from: "inventory" # Local state (can now diverge from prototype) condition: "slightly worn" inscribed: "Property of Don" ``` ### DROP AS BEAM — Move Actual File ``` > DROP brass-lantern AS BEAM File moved to: garden/brass-lantern.yml ``` **What happens:** 1. Actual file relocates to destination 2. No inheritance created 3. All properties preserved (it's the same file) 4. You NO LONGER have it 5. Origin is now empty (file moved) **Use when:** - Giving something away permanently - Moving heavy objects - Avoiding inheritance chains - The thing should BE here now ### DROP INTO — Insert in Container List ``` > DROP cookie INTO treasure-chest Cookie added to treasure-chest.yml contents list. ``` **What happens:** 1. Target file has a list (contents, items, inventory) 2. Your item inserted into that list 3. No new file created 4. Packed storage in existing file **Container file structure:** ```yaml # treasure-chest.yml object: name: "Treasure Chest" contents: - { id: gold-coins, proto: economy/gold.yml, count: 100 } - { id: ruby, name: "Ruby", weight: 0.5 } - ref: magic-scroll.yml # ← your item inserted here ``` --- ## Boxing Protocol **Boxing (like Java boxing) — instantiating a pointer into a real file with identity.** When you have a lightweight pointer and DROP AS BOX, the reference gets **boxed** — instantiated into a YAML file that inherits from the pointer's target. Like Java's `int` → `Integer`, but here it's `pointer` → `YAML file with identity`. ### The Journey of an Object ```yaml # THE JOURNEY OF A CATALOG: # 1. ORIGIN: street/acme-catalog.yml (prototype, dispenser) # 2. DON TAKES REF at street: don.inventory: [ref → street/acme-catalog.yml] # (No file created yet, just pointer) # 3. DON DROPS AS BOX in kitchen: # Creates: kitchen/acme-catalog-001.yml # inherits: street/acme-catalog.yml # boxed_by: don, annotations: ["circled hole"] # Don's ref is consumed. # 4. PALM TAKES AS OBJECT from kitchen: # File moves: palm.inventory/acme-catalog-001.yml # All annotations preserved! # Kitchen is now empty. # 5. PALM DROPS AS BEAM in study: # File moves: study/acme-catalog-001.yml # Still has Don's annotations! # Palm no longer has it. # 6. BUMBLEWICK TAKES AS REF from study: bumblewick.inventory: [ref → study/acme-catalog-001.yml] # File stays in study. # 7. BUMBLEWICK DROPS AS BOX in garden: # Creates: garden/acme-catalog-002.yml # inherits: study/acme-catalog-001.yml # boxed_by: bumblewick, annotations: ["added doodles"] # Now there are TWO catalogs: # - study/acme-catalog-001.yml (Don's original box) # - garden/acme-catalog-002.yml (Bumblewick's copy) # Full provenance chain preserved at every step! ``` ### Boxing Golden Rules 1. **Once boxed, always boxed** — Instances travel intact 2. **Instances accumulate history** — Each handler can add provenance 3. **Inheritance chains** — Instances can inherit from instances 4. **Local state divergence** — Instances can override their prototype --- ## Transport Modes For heavy objects you can't carry: ### BEAM / TRANSPORTER Use a reference as a targeting system: ``` > TAKE REF TO grand-piano You have a reference to the grand piano. (weight: 0) > GO concert-hall You arrive at the concert hall. > BEAM grand-piano HERE *shimmer* Piano materialized! concert-hall/grand-piano.yml created. ``` **How it works:** 1. Take lightweight REF to heavy object 2. Travel to destination (carrying only the pointer) 3. BEAM command uses ref as target 4. Object teleported/moved to your location 5. Ref consumed, you have actual object here ### FORKLIFT Mode Mechanical assistance for moving heavy objects: ``` > SUMMON FORKLIFT Forklift arrives. > LOAD bronze-statue ONTO forklift Statue loaded. > GO garden You move to garden, forklift follows. > UNLOAD bronze-statue AS BEAM Statue placed in garden/bronze-statue.yml ``` --- ## Fungibles Fungible items are **identical and interchangeable**. No individual tracking — just a count. **Counts can be fractional!** 3.5 gold coins, 0.25 moolah, 2.7 kg of flour — why not? ### Fungible Stack Structure ```yaml inventory: fungibles: