@puffinstudio/fizzyx 0.5.5 → 0.6.1

package/README.md

@@ -1,5 +1,7 @@
 # fizzyx
 
+<img src="./src/planner/logo.svg" alt="fizzyx logo" width="120" />
+
 CLI tool for Fizzy board workflow, OSS/S3-compatible storage, and OpenAPI client generation.
 
 ## Install
@@ -18,12 +20,12 @@ Manage a Fizzy board from a repository-local `.fizzy.yaml`.
 fizzyx setup <board-id>
 fizzyx auth login <token>
 fizzyx auth status
-fizzyx flow doctor
+fizzyx flow mine --fresh
 ```
 
-`flow doctor` shows account, board, workflow columns, and whether the CLI is ready to operate on the board.
+`flow doctor` can still be run for an explicit health check, but new `fizzyx flow ...` commands auto-repair workflow columns and ids when needed.
 
-### Create A Card
+### Create A Card (Manual)
 
 Use `--draft` to create a unique project-local draft file. This automatically creates `.fizzyx/` when needed and avoids collisions between multiple agents.
 
@@ -46,6 +48,7 @@ fizzyx flow add <user> "<title>" --desc <file|->
 ```sh
 fizzyx flow mine --fresh
 fizzyx flow next --fresh
+fizzyx flow next --fresh --start
 fizzyx flow show <card>
 fizzyx flow start <card>
 fizzyx flow complete-steps <card>
@@ -62,8 +65,8 @@ fizzyx flow status [--fresh]
 fizzyx flow assign <card> <user|me> [user...]
 fizzyx flow block <card> "<reason>"
 fizzyx flow repair-markdown <card>
-fizzyx flow std <card>
-fizzyx flow std-all
+fizzyx flow standardize <card> (alias: std)
+fizzyx flow standardize-all (alias: std-all)
 fizzyx flow workflow
 fizzyx flow skill
 fizzyx flow skill init [--force]
@@ -74,6 +77,48 @@ fizzyx flow skill init [--force]
 - `flow block` moves the card to Not Now.
 - `flow workflow`, `flow skill`, and `flow template` prefer project-local overrides under `.agents/skills/fizzyx/`.
 
+![Flow command lifecycle](./docs/images/flow-workflow.svg)
+
+## Planner Dashboard
+
+Start a local planner dashboard backed directly by the Fizzy API:
+
+```sh
+fizzyx planner start
+fizzyx planner snapshot
+fizzyx planner snapshot --auto-fix
+fizzyx planner health
+fizzyx planner repair-metadata
+fizzyx planner repair-metadata --apply
+fizzyx planner repair-metadata --apply --default-priority p2 --default-type chore
+```
+
+![Planner dashboard workflow](./docs/images/planner-workflow.svg)
+
+`planner snapshot` prints the same JSON used by the web dashboard. Project workflow uses `BACKLOG → READY → IN PROGRESS → REVIEW → DONE`, with `DONE` coming from closed cards and `BLOCKED` from Not Now/postponed cards.
+
+`planner repair-metadata` is dry-run by default. It inserts/syncs deterministic frontmatter from existing tags and assignees. Missing priority/type are only filled when explicit defaults are passed.
+
+Planner conventions use tags for filtering:
+
+```text
+priority:p0 priority:p1 priority:p2
+type:bug type:feature type:chore type:blocker
+area:frontend area:api phase:integration
+```
+
+Cards can also include frontmatter for richer project details:
+
+```md
+---
+priority: P1
+type: feature
+owner: ellen
+depends_on: [123]
+api_status: not_connected
+---
+```
+
 ## OSS Commands
 
 Manage S3-compatible object storage (Alibaba Cloud OSS, AWS S3, MinIO, etc.).
@@ -97,6 +142,8 @@ fizzyx oss setup --env dev
 - Credentials are stored in OS keychain via `Bun.secrets`, never in config files or shell history
 - Without `--env`, keys are stored as `default` — all environments fall back to it
 
+![OSS command workflow](./docs/images/oss-workflow.svg)
+
 ### Sync
 
 Upload local files to the remote bucket:
@@ -239,6 +286,14 @@ const result = await someAction();
 fizzyx openapi list
 ```
 
+![OpenAPI generation workflow](./docs/images/openapi-workflow.svg)
+
+### Initialize OpenAPI config
+
+```sh
+fizzyx openapi init
+```
+
 ### Config (`.fizzy.yaml`)
 
 ```yaml