# The Hub model — items, kinds, versions

The Hub is FaustWave's community-publishing surface. You publish DSPs, sample packs, knowledge packs, full projects. Other users install with one click. Everything in this manual you're reading right now is on the Hub — each domain pack is its own item.

This section is the conceptual model: what you can publish, the item / version shape, how sign-in works. The next two sections cover browsing + installing, and publishing + iterating.

## What you can publish

| Kind | Source format | What install does |
|---|---|---|
| **builder** | `.builder` graph document | Saves into the project's `assets/` (Documents → PROJECT); no editor tab. Add to the mixer via "+ ADD AUDIO"/"+ ADD FX", or open from PROJECT to edit. |
| **dsp** | `.dsp` Faust source | Opens in a Faust DSP module. |
| **lib** | `.lib` Faust library | Pops a file dialog; writes to disk; mounts in libfaust's VFS so `import("name.lib")` resolves immediately in any compile. |
| **book** | `.md` markdown bundle with `## Section`-headed blocks | Indexes sections into the local KB's `community` corpus; opens in the Book Reader. |
| **sample-pack** | A single `.wav` / `.flac` / `.aiff` audio file | Writes bytes to the sample store (sha-keyed; idempotent on re-install). |
| **node-pack** | A `.nodepack.json` manifest | Installs into `userData/node-packs/`; the Builder picks up the new node kinds on next refresh. The pack-author surface (Box-DSL `toBox`, per-kind `imports`, paired-port stereo) is covered in **FaustWave — Node-Pack Authoring**. |
| **project** | A `.fwproject.zip` (project.json + workspace.json + assets/) exported via `project.export` | Imports as a new project with the source's name (or server-suggested on collision). |

Each kind has its own **content reader** on the publish side (parses + validates the source) and its own **installer** on the install side (puts it where the IDE expects it). The reader / installer pairs are wired such that publishing a `.builder` then installing it back gets you bytes-identical content — round-trip-clean.

## Items, versions, artifacts

A Hub **item** is the metadata row — slug, title, owner, license, visibility, tags, description. Items live forever (until you delete them) and carry a stable id.

Each item has one or more **versions** — `v1`, `v2`, `v3`, … — each with its own content + a changelog. Users install "the latest" by default but can browse to an older version. Version numbers are server-assigned (you don't pick `v17`; you upload, the server picks the next number).

Each version has one or more **artifacts** — the actual content bytes. A `book` version has a `bundle` artifact (the markdown) + a `manifest` artifact (metadata). A `builder` version has one artifact (the .builder file). A `sample-pack` version's artifact is the audio bytes.

The item-version-artifact split lets the Hub serve metadata cheap (search results carry summaries only) and download bytes on demand (the `downloadUrl` on each artifact).

## Visibility

When you publish, pick one of:

- **`public`** — listed in search; anyone can install.
- **`unlisted`** — installable by direct link / id, but not surfaced in search. Like a YouTube unlisted video.
- **`private`** — only YOU can see it. Drafts, work-in-progress.
- **`friends`** — planned visibility tier (not yet wired in the backend; the publish call accepts the string but treat it as `private` today).
- **`team`** — planned collaborative spaces (same caveat).

Visibility is mutable; use `hub.item.update { visibility }` to flip it.

> 🟦 **PRACTICAL**: publish as `unlisted` first, share the link with one or two readers, switch to `public` once you're happy. The user manual you're reading was built this way — every pack started `private`, flipped to `public` once it covered enough ground.

## License

Every item requires an SPDX license identifier. The Hub doesn't enforce licensing on installs (it can't — a content download is a download) but the license is visible on every item card so installers know what they're licensing. Common choices:

- `CC0-1.0` — public domain, no strings. Everything FaustWave itself publishes (the manual, the demo projects, the bundled instruments) is CC0.
- `CC-BY-4.0` — attribution required.
- `MIT` — permissive; usually for code-bearing items (libs, builders).
- `CC0-1.0` — public domain dedication. "Use this for anything."
- `GPL-3.0-or-later` — copyleft. Derivatives must be GPL too.

The FaustWave manual you're reading is `CC0-1.0` — copy from it freely.

## Sign in

Hub access is sign-in-gated. FaustWave uses **Logto OIDC** for auth; the same account works for browsing, installing, publishing.

Not signed in yet? Click the **user icon** at the bottom-left of the rail (or Settings → Account). The login modal opens in a windowed flow; complete it and you're back in the IDE with your handle (`@your-username`) visible in the topbar.

> 🔘 **MCP**: `hub.status {}` returns whether you're signed in + whether you've picked a username. Cheap precheck. `auth.login {}` opens the modal; `auth.logout {}` signs you out + clears local tokens.

The IDE stays fully usable signed-out — only the Hub features (browse, install, publish) require sign-in. You can build DSPs, run the sequencer, record takes, install local samples, all without a Hub account.

## Items have owners

Every item has exactly one owner: the user who published it. You can:

- **Update YOUR items' metadata** via `hub.item.update`.
- **Upload new versions of YOUR items** via `hub.version.upload`.
- **Delete YOUR items** via `hub.item.delete` (permanent; artifact bytes go too).

You CANNOT directly edit somebody else's item. To evolve another user's work into your own version, **fork** — see § 3.

## A `hub.status` chain to ground orientation

```yaml
actions:
  - action_id: hub.open
    input: {}
    label: "▶ 0. Open the Hub tab"
  - action_id: hub.status
    input: {}
    save_as: hs
    label: "▶ 1. Am I signed in?"
  - action_id: hub.items.my
    input: {}
    save_as: mine
    label: "▶ 2. What have I published?"
```

> 🟦 **HANDS-FREE PATH**: step 1 returns `{ signedIn, hasUsername }`. Step 2 returns the full ItemSummary list of your own items. Useful as a first orient when stepping into a fresh session — you know whether you can publish (signed in + has username) and what you already have on the Hub.

## What the Hub doesn't do (yet)

- **Payments / commerce** — every item is free. License governs reuse.
- **Comments / discussion** — no threads per item.
- **Download counts in search ranking** — sort is recency + star count.
- **Automated content moderation** — community-flag + manual admin review.
- **Notifications** — "somebody forked your item" pushes are planned, not wired.

Tracked in TODOs.

Next section: browsing + installing — the search bar, the kind filter, what `hub.install` actually does per kind.