From ccdaa161613ba362369340ebdad9aaacd624eab8 Mon Sep 17 00:00:00 2001 From: Som Samantray <92726151+SomSamantray@users.noreply.github.com> Date: Thu, 6 Aug 2026 02:23:33 +0530 Subject: [PATCH] docs(persona-pack): fix stale desktop import instructions (#4500) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 Co-authored-by: Wes Co-authored-by: Carl --- crates/buzz-persona/PERSONA_PACK_SPEC.md | 24 ++++++++++++++---------- examples/meadow-core/README.md | 10 +++++++--- 2 files changed, 21 insertions(+), 13 deletions(-) diff --git a/crates/buzz-persona/PERSONA_PACK_SPEC.md b/crates/buzz-persona/PERSONA_PACK_SPEC.md index 3c5611ba0..cb3a7d1c0 100644 --- a/crates/buzz-persona/PERSONA_PACK_SPEC.md +++ b/crates/buzz-persona/PERSONA_PACK_SPEC.md @@ -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 -> `/agents/packs//` 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. --- diff --git a/examples/meadow-core/README.md b/examples/meadow-core/README.md index 416ea1510..3eedd1391 100644 --- a/examples/meadow-core/README.md +++ b/examples/meadow-core/README.md @@ -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 ```