Skip to content

docs: persona-pack .zip import instructions are stale — app now rejects them in favor of buzz-team-snapshot v1 #4468

Description

@justanotherkevin

Summary

PERSONA_PACK_SPEC.md and examples/meadow-core/README.md document importing a team via a .zip persona pack through My Teams → Import. That path no longer works — the app now rejects .zip team files outright with:

Legacy team files are no longer supported. Export a buzz-team-snapshot v1 .team.json or .team.png instead.

Steps to reproduce

  1. cd examples/meadow-core && zip -r meadow-core.zip meadow-core
  2. In the desktop app, open Agent Teams (note: also renamed from "My Agents" in the current UI, another place the docs are behind) → Import
  3. Select the zip
  4. App shows the "Legacy team files are no longer supported" error instead of importing

Root cause

Where the stale docs live

  • crates/buzz-persona/PERSONA_PACK_SPEC.md — "Desktop App Import" section describes the .zipMy Teams → Import flow as current, and separately references a "future 'Install Pack' UI button" that also doesn't exist yet.
  • examples/meadow-core/README.md — usage instructions say to use the "Install Pack" button, which isn't implemented, and don't mention the zip-import path being retired.

Proposed changes

  • Update PERSONA_PACK_SPEC.md's "Desktop App Import" section to reflect that .zip persona-pack import for teams is retired, and either document the actual current path to get a multi-agent pack into the app, or mark the feature as not-yet-supported if there truly isn't one
  • Update examples/meadow-core/README.md's usage instructions to match whatever the current supported import path is (drop the "Install Pack" button reference until it ships)
  • Either implement a persona-pack-directory → buzz-team-snapshot v1 conversion path (CLI or in-app), or explicitly document that persona packs and team snapshots are two separate, non-interchangeable concepts today
  • Audit other docs/examples for the same "My Agents" → "Agent Teams" naming drift, since that rename doesn't appear to be reflected everywhere either

Environment

  • Found while running the app from a fresh local build off main, following the documented Quick Start / persona pack instructions as written

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions