Example: a mini-app rule

Rules explains the Rule entity type — this page is a complete, working example you can install in your own world. Movie Tracker is an active rule that turns a connected agent into a small movie-logging app: movies are items, each watch is an event with its own rating, and the rule’s lore carries the data model, workflows, and query patterns the agent follows.

Install it from chat

You don’t need an import tool — the payload below is written for the agent. Copy the whole JSON block, paste it into a chat connected to your world, and ask:

Add this rule to my world.

The agent creates the rule entity with its lore chunks, the companion interest entity, and the relationship between them.

{
  "rule": {
    "entity_id": "rule/app_movie_tracker",
    "entity_type": "rule",
    "name": "App: Movie Tracker",
    "description": "Movie Tracker mini-app. Tracks movies as items, watch sessions as events with per-watch ratings, watchlists, favorites, and co-watcher history. Full operating rules are in this entity's lore chunks: Data Model, Log a Watch, Watchlist/Favorites/Edits, Queries & Stats. Read all lore before acting on movie-related requests.",
    "properties": {
      "rule_type": "tracker",
      "status": "active",
      "trust": "ai-generated",
      "priority": 10,
      "scope": "item, event, interest, person, place",
      "trigger": "user mentions watching a movie or film, their watchlist, movie ratings or reviews, rewatching, or going to the cinema/theater",
      "owns_tags": ["movie-tracker"]
    },
    "tags": ["app", "movie-tracker"]
  },
  "lore": [
    {
      "display_index": 0,
      "title": "Data Model",
      "content": "MOVIE = item entity. Slug: item/movie_<title>_<year>. Properties: item_type: \"movie\", year (number), director, genres (array), runtime_minutes (number), status (\"watchlist\" | \"watched\"), favorite (boolean), where_to_stream (optional). Tag every movie item \"movie-tracker\". Every movie item gets RELATED_TO interest/watching_movies (collection anchor).\n\nWATCH SESSION = event entity. Slug: event/watch_<movie>_<yyyy_mm_dd>. Properties: event_type: \"movie_watch\", date (human-readable), date_year/date_month/date_day (numbers), rating (1-10), impression (1-3 sentence review), rewatch (boolean), format (\"theater\" | \"streaming\" | \"physical\"), mood (optional). Tag \"movie-tracker\".\n\nRELATIONSHIPS per watch: event RELATED_TO item (the movie); each watcher person ATTENDED event (always include the world owner); event OCCURRED_AT place if location known (create the place if new). Optionally link the movie item via REFERENCES to a reference entity (IMDb/Letterboxd page) when a URL is provided."
    },
    {
      "display_index": 1,
      "title": "Workflow: Log a Watch",
      "content": "WORKFLOW: Log a watch (\"I watched X last night with Y\").\n1. Search entities for the movie item. If missing, create it per the Data Model, filling year/director/genres from general knowledge; set status: \"watched\".\n2. If the movie existed with status \"watchlist\", update status to \"watched\".\n3. Create the watch event. Ask for a 1-10 rating and a one-line impression if not given; rating is the single most important field — always try to capture it. Set rewatch: true if a prior watch event for this movie exists.\n4. Create relationships: event RELATED_TO movie; ATTENDED edges for the owner and each named co-watcher (create person entities for unknown co-watchers after confirming with the user); OCCURRED_AT if a place was mentioned.\n5. Confirm back with a one-line summary: title, rating, who, where."
    },
    {
      "display_index": 2,
      "title": "Workflow: Watchlist, Favorites, Edits",
      "content": "WORKFLOW: Watchlist (\"add X to my watchlist\"). Create the movie item with status: \"watchlist\", tag \"movie-tracker\", RELATED_TO interest/watching_movies. No event is created until it's actually watched. To list the watchlist: search items tagged \"movie-tracker\" with status \"watchlist\".\n\nWORKFLOW: Favorites. \"X is one of my favorites\" → set favorite: true on the movie item. Favorites list = movie items with favorite: true.\n\nWORKFLOW: Re-rate / edit review. Update the rating/impression on the most recent watch event for that movie, not on the movie item. The movie item never stores a rating; ratings live on watch events so rewatches can differ (Letterboxd diary model)."
    },
    {
      "display_index": 3,
      "title": "Workflow: Queries & Stats",
      "content": "WORKFLOW: Queries & stats.\n- \"What did I watch with <person>?\" → query_relationships: that person's ATTENDED edges to events with event_type movie_watch, then follow RELATED_TO to movie items.\n- \"What have I rated highest?\" → list movie_watch events, sort by rating property.\n- \"Have I seen X?\" → search for the movie item; check status and any linked watch events.\n- \"What should I watch?\" → list watchlist items; optionally recommend based on genres of high-rated (8+) watches.\n- Year in review → filter movie_watch events by date_year; report count, average rating, top co-watcher (most ATTENDED overlaps), most-watched genre.\nPresentation: keep answers conversational; a compact list or table only when 4+ titles."
    }
  ],
  "companion_entities": [
    {
      "entity_id": "interest/watching_movies",
      "entity_type": "interest",
      "name": "Watching Movies",
      "description": "Collection anchor for the Movie Tracker app. All movie items link here via RELATED_TO so the full collection can be queried from one hub.",
      "properties": {
        "interest_type": "entertainment"
      },
      "tags": ["movie-tracker"]
    }
  ],
  "relationships": [
    {
      "source_id": "rule/app_movie_tracker",
      "target_id": "interest/watching_movies",
      "relationship_type": "APPLIES_TO",
      "properties": {
        "note": "Collection anchor managed by the Movie Tracker app"
      }
    }
  ],
  "router_index_entry": "- **Movie Tracker** (`rule/app_movie_tracker`) — triggers: watching a movie/film, watchlist, movie ratings/reviews, rewatch, cinema/theater. Tags: `movie-tracker`"
}

What’s in the payload

• rule — the rule entity itself. Its properties say when it applies (trigger), what it touches (scope, owns_tags), and how it ranks (priority, trust, status); the description tells the agent to read the lore before acting.
• lore — four chunks holding the actual instructions: the data model, the log-a-watch workflow, watchlist/favorites/edits, and query patterns. This is where the behavior lives.
• companion_entities — a Watching Movies interest that acts as the collection anchor; every movie item links to it so the whole collection can be queried from one hub.
• relationships — an APPLIES_TO edge tying the rule to the interest it manages.
• router_index_entry — the one-line index entry for your world instructions, covered next.

Note

This wrapper isn’t a formal import format — it’s structured instructions an agent reads and carries out with the ordinary MCP tools. The shape works for any mini-app you design: swap the data model, workflows, and triggers.

Point your world instructions at it

Rules don’t activate themselves — an agent only finds them if the world instructions points it there. Instead of a trigger line per rule, you can make the prompt a router: a short protocol plus a one-line index per app. Add this to your world instructions (or just add the router_index_entry line to your app index if you already have one):

## How this world works

This world uses `rule` entities as mini-apps. Each app's full operating
rules (data model, workflows, query patterns) live as lore chunks on its
rule entity. Instructions here are only a router.

### Protocol

1. When a user request matches an app's triggers below, first call
   `get_entities` on that rule and confirm its `status` is "active".
   Skip rules that are paused, archived, or draft.
2. Read ALL of the rule's lore chunks before acting, then follow them
   exactly.
3. Create and update entities only as the rule's lore specifies — tag
   them with the rule's `owns_tags` and don't invent parallel structures.
4. If a request involves tracked data but no trigger below clearly
   matches, search `rule` entities (status: active) before improvising.
5. If multiple rules apply and conflict, higher `priority` wins.

### App index

- **Movie Tracker** (`rule/app_movie_tracker`) — triggers: watching a
  movie/film, watchlist, movie ratings/reviews, rewatch, cinema/theater.
  Tags: `movie-tracker`

*(Add one line per app. Keep this index in sync with the rule entities —
the rule entity is the source of truth.)*

From then on, “I watched Dune last night with Sarah” is all it takes — the agent matches the trigger, reads the rule’s lore, logs the watch event with its rating, and links the co-watcher.

See Rules for the entity type itself, and World instructions examples for more ready-to-paste snippets. More installable mini apps like this one — plus complete world templates — live in the Orbismo Playbook.