docs(persona-pack): fix stale desktop import instructions (#4500)

## Summary

The desktop app no longer imports persona packs the way the docs
described. `PERSONA_PACK_SPEC.md` and the `meadow-core` example still
pointed users at a `.zip` import through "My Teams / My Agents → Import"
and a future "Install Pack" button — none of that exists anymore. The
app only imports agent/team **snapshots** (`.agent.json`/`.agent.png`,
`.team.json`/`.team.png`), and a persona-pack `.zip` is explicitly
rejected.

## Fix

Updated both docs to describe the current import paths (Agents / Agent
teams sections, snapshot files only) and added a note that persona packs
and desktop snapshots are separate, non-interchangeable formats today.

Fixes #4468

---------

Signed-off-by: SomSamantray <92726151+SomSamantray@users.noreply.github.com>
Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
This commit is contained in:
Som Samantray
2026-08-05 13:53:33 -07:00
committed by GitHub
co-authored by Wes Carl
parent 7334ad1e16
commit ccdaa16161
2 changed files with 21 additions and 13 deletions
+14 -10
View File
@@ -909,18 +909,22 @@ at agent startup.
### Desktop App Import
The Buzz desktop app can import persona packs via the Import button:
The Buzz desktop app's **Agents** page does not import persona-pack `.zip` archives or
`.persona.md` files directly. It imports personas and teams as **snapshots** — files exported
from an agent or team that already exists inside the app:
- **My Agents → Import**: Accepts `.persona.md` files (individual personas) or `.zip` files
(persona packs detected by `.plugin/plugin.json`). Pack zips are resolved in a temp directory;
each persona is previewed and imported individually into the persona library.
- **My Teams → Import**: Accepts `.zip` files (persona packs). The pack name becomes the team
name; each persona becomes a team member.
- **Agents section → Import**: Accepts `.agent.json` or `.agent.png` (an agent snapshot).
- **Agent teams section → Import**: Accepts `.team.json` or `.team.png` (a `buzz-team-snapshot
v1`). A persona-pack `.zip` is rejected outright with an error directing you to export a team
snapshot instead.
> **Note**: The Import button parses and previews personas from the pack — it does not install the
> pack directory itself. For full pack installation (which copies the pack to
> `<AppDataDir>/agents/packs/<pack-id>/` with re-validation), use the `install_persona_pack`
> Tauri command or a future "Install Pack" UI button.
> **Persona packs and desktop snapshots are two separate, non-interchangeable formats today.**
> This spec's pack format (portable, hand-authored, git-friendly) is validated and inspected via
> `buzz pack validate` / `buzz pack inspect` (Section 11). A snapshot is captured *from* an
> already-running agent or team inside the desktop app. Neither format converts into the other:
> there is no command that turns a pack into a snapshot, or a snapshot back into pack source. To
> get a pack's personas running inside the desktop app today, recreate them there by hand using
> `buzz pack inspect`'s resolved config as reference.
---
+7 -3
View File
@@ -16,11 +16,15 @@ buzz pack validate ./examples/meadow-core
# Inspect resolved config
buzz pack inspect ./examples/meadow-core
# Import into the desktop app
# Use the "Install Pack" button and point to this directory
```
The desktop app's Import button does not accept this pack directory or a zip of it — it imports
agent/team *snapshots* (`.agent.json`/`.team.json`, exported from agents already running in the
app), not persona-pack source. `buzz pack inspect` above shows the fully-resolved per-agent
config; use it as reference to recreate these agents in the desktop app by hand. Direct
persona-pack runtime integration is not currently implemented. See "Desktop App Import" in
`crates/buzz-persona/PERSONA_PACK_SPEC.md` for the current import paths.
## Structure
```