# Publishing a node-pack

Once your `.nodepack.json` validates locally (every kind shows in the picker + compiles cleanly), publish to the Hub for others to install. Two paths — local-test then publish, or smoke-test in a fresh project first.

## Local test loop

The fastest iteration loop bypasses the Hub entirely:

```
1. packs.node.install { manifest: <your full .nodepack.json object> }
2. packs.list         { kind: "node" }                → confirm packId, isBundled:false
3. documents.add        { type: "builder", title: "Pack test" }        → module_id
4. builder.graph.node.add       { module_id, kind: "<your_kind_id>" }          → node id
5. builder.graph.node.add       { module_id, kind: "output" }                  → out id
6. builder.graph.connect        { module_id, source_node_id: <yours>, target_node_id: <out>, target_port: "in_l" }
7. dsp.compile        { module_id }
8. builder.source.get     { module_id }   → verify your toBox emits what you expect
```

(Not a click-chain — steps 1, 4 and 6 need YOUR pack's manifest + kind ids; ask the assistant to run the loop against your file.)

If compile fails, the error string includes the libfaust diagnostic — usually a missing param ref, an arity mismatch, or a typo in a `lib()` call. Fix the `.nodepack.json`, `packs.node.install` again (writes overwrite atomic), retry.

## Publishing to the Hub

When the local loop is happy:

```
hub.publish {
  kind: "node-pack",
  file_path: "asset:assets/my-pack.nodepack.json",
  slug: "my-pack",
  title: "My Pack — short tagline",
  description: "Longer description for the Hub item page."
}
```

The Hub backend's `NodePackInspector` validates the manifest server-side + extracts derived metadata (kindCount, packId, ownerHandle). On success you get back the item's `id` — record it for follow-up version uploads.

### Subsequent versions

```
hub.version.upload {
  kind: "node-pack",
  item_id: "<id from the publish response>",
  file_path: "asset:assets/my-pack-v2.nodepack.json"
}
```

The Hub computes the new version number automatically (existing-version + 1). The local pack store refuses to downgrade (incoming version must be ≥ installed) — bump the `version` field in the manifest on every upload.

### Forking + iterating

Hub items can be forked: `hub.fork { item_id }` creates a copy in your namespace. Useful for "I want to base my pack on `faust-vocal` but add a new vocal effect" — fork, edit, publish under your handle.

## Kb-pack-style packs as a doc surface

If your node-pack covers a meaningful domain (a vocal effects suite, a granular synth toolkit, a vintage gear bundle), pair it with a **book** documenting the kinds. The book lives separately on the Hub (`hub.publish kind:"book"`) but Users find both when searching for the domain.

The Book Reader module's tutorial blocks can link to your kinds with `companionPatches` references + assistant hints. See **FaustWave — Hub** §3 for the publish flow.

## Bundling for FaustWave team packs

If you're shipping a FaustWave-team pack that should auto-restore on launch:

1. Drop the `.nodepack.json` in `packages/app/build-resources/bundled-node-packs/`.
2. Add the packId to `BUNDLED_PACK_IDS` in `packages/app/electron/node-pack-store.ts`.
3. Bump the `version` field — `restoreBundledPacks` compares against installed and only re-writes when the bundled file is newer.

Community packs DON'T go in `BUNDLED_PACK_IDS`. They stay Hub-only — users install them on demand.

## Common rejection paths

The validator + adapter at install time check for the most common authoring traps. If any fail, the install rejects + emits a per-line error in Logs:

- **Unknown port `id` referenced from `input('xyz')`** — the input port `xyz` doesn't exist in `inputs[]`.
- **Unknown param `id` referenced from `param('xyz')`** — same for params.
- **Forward def ref** — `def('A')` referenced before `defs.A` is declared (defs resolve in declaration order).
- **Arity mismatch in `seq(a, b)`** — `a`'s output arity != `b`'s input arity.
- **Missing `toBox.outputs.<port>`** — every output port needs a key. Sinks (zero outputs) use the reserved `__process` key.
- **Bare-name kind not in scope** — `prim('XYZ', …)` where `XYZ` isn't in stdfaust + the kind doesn't list the relevant library in `imports`. Add the lib to the kind's `imports` field.
- **`imports` entry not ending in `.lib`** — the validator rejects entries that don't end in the `.lib` suffix.

## Where to read more

- **Source of truth** — `packages/extension-dsp-builder/src/lib/packKindData.ts` carries the `NodeKindData` validator + the `validateNodeKindData()` function that runs at install time. The validator's error strings are precise; read it when in doubt.
- **Adapter** — `packKindAdapter.ts` walks `toBox` and produces the runtime `NodeKindDef`. Read it to understand the evaluation order + the substitution env.
- **Examples** — every file under `packages/app/build-resources/bundled-node-packs/` is real production code. Look at the simpler ones first (`faust-physical-models`, `faust-spatial`) for clean templates.
- **Architecture** — `docs/NODE-PACK-ARCHITECTURE-ZIEL.md` for the bundled-vs-Hub classification and the long-term direction.