Samples & Templates

Navigation of the Broker samples shipped with the repo. These are the best learning material — each sample corresponds to a specific development stage.

---

1. Repo-Bundled Templates

1.1 starter_broker — Empty Template from Scratch

Field	Value
Path	workspace/manager/brokers/starter_broker/
Type	Minimal skeleton, pure UI demo
Learning Points	iframe UI hosting + SDK calls

starter_broker/
├── manifest.json        # broker_id, name, version, schema_version, ui.entry
├── README.md            # Points to BROKER_DEVELOPMENT.md
└── ui/
    └── index.html       # ★ Single HTML + ../sdk.js minimal example

Key parts of manifest.json:

{
  "broker_id": "starter_broker",
  "name": "Starter Broker",
  "version": "0.1.0",
  "schema_version": 1,
  "author_pubkey": "",
  "description": "Minimal broker template, walks through BROKER_DEVELOPMENT.md from scratch.",
  "ui": {"entry": "index.html"},
  "permissions": {}
}

Core snippet of ui/index.html:

<script src="../sdk.js"></script>
<script>
  const api = window.familiars;
  async function loadRooms() {
    const res = await api.rooms.list();
    document.getElementById('out').textContent = JSON.stringify(res, null, 2);
  }
</script>

Learning path: Start here, change broker_id + name + description, run broker pack + broker verify, and see how the iframe is hosted in the workshop.

---

1.2 hello_broker — Minimal Plugin + Trigger

Field	Value
Path	workspace/manager/brokers/hello_broker/
Type	Plugin + Trigger minimal reference
Learning Points	plugin_fn trigger path + SDK facade calls

hello_broker/
├── manifest.json         # capabilities: ["rooms.read", "rooms.write"]
├── plugins/
│   └── greeter.py        # on_message_posted + on_approval_decided
├── triggers.json         # event → action_ref dispatch
└── ui/
    └── index.html

plugins/greeter.py:

from broker_sdk import store

def on_message_posted(payload: dict) -> None:
    store.upsert(
        f"seen/{payload['message_id']}",
        title="seen",
        meta={"cluster_id": payload.get("cluster_id")}
    )

def on_approval_decided(payload: dict) -> None:
    msg_id = payload.get("approval_id") or payload.get("id") or ""
    store.upsert(f"decided/{msg_id}", ...)

triggers.json:

[
  {
    "event": "message.posted",
    "action_kind": "plugin_fn",
    "action_ref": "plugins.greeter:on_message_posted"
  },
  {
    "event": "approval.decided",
    "action_kind": "plugin_fn",
    "action_ref": "plugins.greeter:on_approval_decided"
  }
]

Learning path: After copying starter_broker, add plugins/ and triggers.json, and verify how plugins are triggered.

---

1.3 example_broker — Vue/Vite Project

Field	Value
Path	workspace/manager/brokers/example_broker/
Type	Full Vue/Vite project
Learning Points	Build output dist/ packaging + advanced capabilities

example_broker/
├── manifest.json         # ui_mode: "vue", entry: "./dist/index.html"
├── package.json          # @familiars/broker-ui dependency
├── vite.config.ts
├── src/                  # Vue source code
│   ├── App.vue
│   └── ...
├── assets/               # Static assets
├── index.html            # Vite entry
└── ui/                   # Build output dist/ will be packaged in here

Key parts of manifest.json:

{
  "broker_id": "example_broker",
  "schema_version": "2",
  "name": "example_broker",
  "display_name": "Example Broker",
  "version": "1.0.0",
  "ui_mode": "vue",
  "entry": "./dist/index.html",
  "capabilities": [
    "graph-editor", "theme",
    "rooms.read", "rooms.write",
    "guild.tasks.read", "guild.tasks.write"
  ],
  "permissions": {"network": false, "storage": true}
}

Learning path: Read the Vue project in ui/ to see how components are organized + how window.familiars is called. Run npm run build before publishing to generate dist/.

---

1.4 ventaris — Business-Grade Reference Implementation

Field	Value
Path	workspace/manager/brokers/ventaris/
Type	Full business application
Learning Points	Tasks + medals + room six-section + 5 roles + reputation dimensions + Recipe collaboration

ventaris/
├── manifest.json         # 151 lines, full role_defs + reputation_dimensions + guild + medal_catalog
├── cover.png             # Marketplace cover image
├── README.md             # Business description
├── VENTARIS_TEST_PLAN.md # ★ Real test cases (436 lines)
├── plugins/
│   ├── bootstrap.py      # Initialization on install
│   ├── matcher.py        # Task matching
│   └── medals.py         # Medal awarding
├── recipes/              # Built-in recipes (guild_recipe auto-drafts profile/contract)
├── triggers.json         # 51 lines, full event dispatch
└── ui/
    ├── index.html        # iframe entry
    ├── assets/           # Static assets
    ├── views/            # Page views (4 tabs)
    └── subtask-graph/    # Subtask graph visualization (separate iframe)

Key snippet of manifest.json:

{
  "broker_id": "ventaris.local_ffexwwm5uptt",
  "name": "Ventaris Collaboration Guild (Beta)",
  "version": "1.0.0",
  "author_pubkey": "8xp0BDrcm/zGKzRdzJVS+KzRdzJVS+...",
  "capabilities_required": ["guild", "ledger", "recipe_call", "scheduler"],
  "reputation_dimensions": [
    {"key": "delivery", "label": "Delivery Quality", "min": 0, "max": 10},
    {"key": "punctuality", "label": "Punctuality", "min": 0, "max": 10},
    {"key": "collaboration", "label": "Collaboration", "min": 0, "max": 10},
    {"key": "leadership", "label": "Leadership", "min": 0, "max": 10}
  ],
  "role_defs": {
    "owner":   {"caps": ["*"]},
    "approver": {"caps": ["task.approve", "task.verdict", "settle.trigger", ...]},
    "issuer":  {"caps": ["task.publish", "task.propose", ...]},
    "developer": {"caps": ["task.accept", "task.deliver", ...]},
    "audience": {"caps": ["task.read", "message.read"]}
  },
  "guild": {
    "default_token_symbol": "VTP",
    "default_settlement_cron": "0 3 1 */3 *",
    "medal_catalog": [
      {"key": "rookie", "label": "Rookie Adventurer", "criteria": {"auto_on_registration": true}},
      {"key": "task_1", "label": "First Steps", "criteria": {"tasks_completed": 1}},
      ...
    ]
  }
}

VENTARIS_TEST_PLAN.md (436 lines) covers:

• Registration flow + auto medal awarding
• Task publish / accept / deliver / approve
• Reject → redo loop
• Cross-role navigation
• Quarterly settlement cron
• Subtask graph visualization

Learning path:

1. Read manifest.json for full role_defs + reputation_dimensions + medal_catalog
2. Read VENTARIS_TEST_PLAN.md for how real test cases are written
3. Read triggers.json for complex event dispatch
4. Read plugins/matcher.py for how plugins implement matching logic

---

1.5 market_test_broker — Marketplace Integration Test

Field	Value
Path	workspace/manager/brokers/market_test_broker/
Type	Test utility
Learning Points	Marketplace end-to-end verification

{
  "broker_id": "market_test_broker",
  "schema_version": 1,
  "name": "Market Test Broker",
  "version": "0.1.0",
  "description": "Used by marketplace integration tests",
  "author_pubkey": ""
}

Primarily used to test the marketplace index / install / verification flow at bridge startup. Most developers won't need to reference this.

---

2. Published on Production Relay

2.1 Ventaris

• Broker ID: ventaris.local_ffexwwm5uptt
• Publish Date: 2026-08-13
• Status: Listed on api.familiars.cn
• Install: Any user opens Workshop → 🏬 Marketplace → click Ventaris → Install

3. Learning Path Overview

3.1 Recommended Order

Order	Sample	What to Learn	Complexity
1	starter_broker	Package structure + iframe UI hosting	⭐
2	hello_broker	Plugin + trigger chain	⭐⭐
3	example_broker	Vue/Vite project + advanced capabilities	⭐⭐⭐
4	ventaris	Full business implementation + test plan	⭐⭐⭐⭐⭐

3.2 Detailed Steps

Level 1: starter_broker

1. Copy starter_broker → change broker_id + name → install locally → see how the iframe UI is hosted
2. Try calling SDK methods: api.rooms.list() / api.broker_id / ...

Level 2: hello_broker

1. Read plugins/greeter.py to see how plugins are written
2. Read triggers.json to see how events are bound
3. Add an on_approval_created trigger yourself

Level 3: example_broker

1. See how the Vue project in ui/ is organized
2. See ui_mode: "vue" and entry: "./dist/index.html" in manifest.json
3. Run npm install && npm run build in ui/, verify the build output

Level 4: ventaris

1. Read manifest.json (151 lines) — see full role_defs / reputation_dimensions / medal_catalog
2. Read VENTARIS_TEST_PLAN.md (436 lines) — see how real test cases are written
3. Read plugins/matcher.py — see the matching logic
4. Run python scripts/test_flow_e2e.py ventaris (if a corresponding script exists) to verify the flow

---

4. Template File Comparison

File	starter	hello	example	ventaris
manifest.json	✅	✅	✅	✅ (151 lines)
ui/index.html	✅ (minimal)	✅	-	✅
ui/ Vue project	-	-	✅	-
ui/ complex views	-	-	-	✅ (views/, subtask-graph/)
plugins/*.py	-	✅ (1 file)	-	✅ (3 files)
triggers.json	-	✅ (2 entries)	-	✅ (51 lines)
recipes/	-	-	-	✅
cover.png	-	-	-	✅
README.md	✅	-	-	✅
Test plan	-	-	-	✅ (436 lines)

---

5. Companion Videos

Broker development tutorial videos will walk you through turning starter_broker into a real App (to be recorded).

---

References

• Broker Development Tutorial / Broker Architecture / Broker Capability Reference / Broker Quick Start
• Full development manual: BROKER_DEVELOPMENT.md (repo root)
• SDK documentation: workspace/manager/brokers/SDK.md