Browsing + installing

The Hub tab is the entry point for finding + installing other people's work. Search, filter by kind, open an item card, hit install. The whole flow is sign-in-gated; the underlying primitives are also MCP-callable so the assistant can browse on your behalf.

#Opening the Hub

Three paths to the same place:

• Topbar cloud icon — the cloud cluster's first icon. Opens the Hub tab.
• Knowledge rail panel → Open Hub button — contextual when you're already browsing the KB.
• MCP / palette — hub.open {} (action id hub.open). Pops the same tab.

The Hub is a regular IDE module — it lives in tabs alongside Builders, book readers, editors. You can have it open and a Builder open simultaneously, drag a Hub-installed sample into the Builder without leaving the IDE.

#Anatomy of the tab

Top to bottom:

• Search bar — free-text. Matches against title, description, tags. Case-insensitive substring match.
• Kind filter chips — narrow to one of builder, dsp, lib, book, sample-pack, node-pack, project. Multi-select.
• Sort affordance — recency (default) or star count.
• Results grid — cards, each carrying title, kind badge, owner handle, tags, star count, fork count, license.

Click a card to open the item detail — description, version history, artifacts, license, install / fork / star buttons.

#Search via MCP

The same search the UI runs:

actions:
  - action_id: hub.search
    input:
      kind: book
      q: faustwave
    save_as: hits
    label: "▶ 1. Search public books matching 'faustwave'"
  - action_id: hub.item.get
    input:
      item_id: "{{hits.data.0.id}}"
    save_as: top
    label: "▶ 2. Fetch the top result's full detail"

#Installing

From the item detail, click Install. Or via MCP:

hub.install { item_id: "<id from hub.search>" }

The action is kind-aware — you don't pass kind. Behaviour per kind:

#Inspecting before installing

For a heavyweight or unfamiliar item, peek before installing:

1. hub.item.get   { item_id: "<id from hub.search>" }   → full ItemDto incl. artifacts
2. hub.items.user { username: "<its owner.username>" }  → the author's other work
3. hub.install    { item_id: "<id>" }                   → OK, install

(Not a click-chain — the item id comes from your own hub.search.)

Step 1 returns the full ItemDto including latestVersion.artifacts[].downloadUrl for direct artifact fetching (useful if you want to inspect a .builder graph in your editor before installing). Step 2 lets you see other items by the same author — useful for vetting (a prolific publisher whose other items look good is less risky than a one-off mystery upload).

#Browsing another user's catalogue

actions:
  - action_id: hub.items.user
    input:
      username: mani
    save_as: their_kb
    label: "▶ List @mani's public + unlisted items"

Returns public + unlisted items (private items stay invisible). Useful for catalogue browsing by author.

#Starring

Star items you find useful — stars surface in search ranking and signal to other users "this is worth looking at":

hub.star.set { item_id: "<id from hub.search>", starred: true }

Returns the new starCount. Idempotent both ways (re-starring or re-unstarring is a no-op).

#The book install loop

A book install does more than file movement — it indexes the content into your local KB so the AI assistant can ground in it. After installing a book:

1. The kb corpus gains its sections (find them via kb.search { corpus: "community", query: "..." }).
2. The Knowledge rail panel's Installed Packs list grows by one row.
3. The pack is available to the Book Reader — book.open { book_id } opens a Reader tab.
4. The assistant can scope to the pack's content for ground-truth answers about it.

This IS how the FaustWave manual you're reading works in practice — each pack installs, its sections index, the Reader opens, the assistant grounds in the content when you ask it about FaustWave.

#Common moves

• "Show me popular Builders" — hub.search { kind: "builder" }. Without a q filter you get the most-recent.
• "Install everything from one user" — hub.items.user { username } then iterate hub.install per item.id. (Mind that lib installs each pop a dialog.)
• "Vet then install" — hub.item.get { item_id }, inspect latestVersion.changelog, install if it looks good.
• "Unstar something I starred by accident" — hub.star.set { item_id, starred: false }.

#Common gotchas

• lib install blocks on the file dialog — when scripting library installs in an action chain, the chain pauses until you accept / cancel the dialog. Plan accordingly.
• Re-installing the same book upgrades it — doesn't duplicate. The local KB store keys by book_id so installing v3 of a pack you have at v1 simply replaces the indexed sections with v3's.
• hub.install { item_id } errors out if you're not signed in — sign in first, or the call returns an auth error.
• hub.search returns a page of results — the response envelope carries total / page / totalPages, so check total before assuming you've seen everything.

Next section: publishing + iterating — the hub.publish flow, version uploads, forks, the My Items view, and the safety rails (delete, account.delete).