@puffinstudio/fizzyx 0.6.2 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # fizzyx
 
-<img src="./src/planner/logo.svg" alt="fizzyx logo" width="120" />
+<img src="./docs/images/fizzyx-logo.png" alt="fizzyx logo" width="120" />
 
 CLI tool for Fizzy board workflow, OSS/S3-compatible storage, and OpenAPI client generation.
 
@@ -12,72 +12,44 @@ bun add -g @puffinstudio/fizzyx
 
 ## Flow Commands
 
-Manage a Fizzy board from a repository-local `.fizzy.yaml`.
-
-### Setup
-
-```sh
-fizzyx setup <board-id>
-fizzyx auth login <token>
-fizzyx auth status
-fizzyx flow mine --fresh
-```
-
-`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 (Manual)
-
-Use `--draft` to create a unique project-local draft file. This automatically creates `.fizzyx/` when needed and avoids collisions between multiple agents.
-
-```sh
-draft=$(fizzyx flow template --draft)
-$EDITOR "$draft"
-fizzyx flow add Ellen "Implement feature" --desc "$draft"
-rm "$draft"
-```
-
-You can also pipe or provide your own file:
-
-```sh
-fizzyx flow template
-fizzyx flow add <user> "<title>" --desc <file|->
-```
-
-### Work A Card
+Use `.fizzyx.yaml` as the project config file for board and workflow settings.
 
 ```sh
-fizzyx flow mine --fresh
-fizzyx flow next --fresh
-fizzyx flow next --fresh --start
+fizzyx flow work
+fizzyx flow create <user> "<title>" --desc <file|->
 fizzyx flow show <card>
 fizzyx flow start <card>
-fizzyx flow complete-steps <card>
+fizzyx flow review <card>
 fizzyx flow done <card> "commit <sha>: <subject>"
+fizzyx flow block <card> "<reason>"
+fizzyx flow improve
+fizzyx flow doctor
+fizzyx flow repair
 ```
 
 `flow done` requires all steps to be complete and closes the card into Done.
 
-### Other Flow Commands
+Use `fizzyx skill ...` for bundled skills and project pins. Use flow commands for repair and health checks.
+
+![Flow command lifecycle](./docs/images/flow-workflow.png)
+
+## Skill Commands
 
 ```sh
-fizzyx flow sync
-fizzyx flow status [--fresh]
-fizzyx flow assign <card> <user|me> [user...]
-fizzyx flow block <card> "<reason>"
-fizzyx flow repair-markdown <card>
-fizzyx flow standardize <card> (alias: std)
-fizzyx flow standardize-all (alias: std-all)
-fizzyx flow workflow
-fizzyx flow skill
-fizzyx flow skill init [--force]
+fizzyx skill list
+fizzyx skill add <source>
+fizzyx skill remove <name>
+fizzyx skill update [name]
+fizzyx skill info <name>
+fizzyx skill run <name>
+fizzyx skill doctor
+fizzyx skill migrate --check
+fizzyx skill migrate --apply
 ```
 
-- `flow assign <card> me` assigns the card to the authenticated Fizzy user.
-- `flow assign` skips users who are already assigned.
-- `flow block` moves the card to Not Now.
-- `flow workflow`, `flow skill`, and `flow template` prefer project-local overrides under `.agents/skills/fizzyx/`.
+Built-in skills are bundled. `skill update [name]` refreshes the local copy from the current fizzyx release.
 
-![Flow command lifecycle](./docs/images/flow-workflow.svg)
+![Skill command workflow](./docs/images/skill-workflow.png)
 
 ## Planner Dashboard
 
@@ -86,19 +58,12 @@ 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 dashboard workflow](./docs/images/planner-workflow.png)
 
 `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
@@ -115,10 +80,11 @@ priority: P1
 type: feature
 owner: ellen
 depends_on: [123]
-api_status: not_connected
 ---
 ```
 
+`api_status:*` and `skill:*` are not standard tags in 1.0 and are treated as free-form tags only.
+
 ## OSS Commands
 
 Manage S3-compatible object storage (Alibaba Cloud OSS, AWS S3, MinIO, etc.).
@@ -142,7 +108,7 @@ 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)
+![OSS command workflow](./docs/images/oss-workflow.png)
 
 ### Sync
 
@@ -216,7 +182,7 @@ Options:
 | `--runtime-name <name>`    | Runtime filename (default: `wx-request.ts`)             |
 | `--run <script\|cmd>`      | npm script or shell command after generation            |
 
-If `--input`/`--output`/`--client` are omitted, values from `.fizzy.yaml` `openapi[0]` are used.
+If `--input`/`--output`/`--client` are omitted, values from `.fizzyx.yaml` `openapi[0]` are used.
 
 Output is 3 files — runtime, types, and tree-shakeable endpoint functions:
 
@@ -286,7 +252,7 @@ const result = await someAction();
 fizzyx openapi list
 ```
 
-![OpenAPI generation workflow](./docs/images/openapi-workflow.svg)
+![OpenAPI generation workflow](./docs/images/openapi-workflow.png)
 
 ### Initialize OpenAPI config
 
@@ -294,7 +260,7 @@ fizzyx openapi list
 fizzyx openapi init
 ```
 
-### Config (`.fizzy.yaml`)
+### Config (`.fizzyx.yaml`)
 
 ```yaml
 openapi:
@@ -307,7 +273,7 @@ openapi:
     run: check
 ```
 
-## Config File (`.fizzy.yaml`)
+## Config File (`.fizzyx.yaml`)
 
 Minimal OSS-only config:
 
@@ -340,6 +306,6 @@ Credentials are resolved in this priority order:
 
 1. OS keychain (`Bun.secrets` — set via `fizzyx oss setup`)
 2. Environment variables: `OSS_<ENV>_ACCESS_KEY_ID` / `OSS_<ENV>_SECRET_ACCESS_KEY`
-3. `.fizzy.yaml` `access_key_id` / `secret_access_key` fields (legacy, discouraged)
+3. `.fizzyx.yaml` `access_key_id` / `secret_access_key` fields (legacy, discouraged)
 
 Credentials stored as `default` (without `--env`) are used as a fallback for all environments when no env-specific key is found. This means you only need to run `fizzyx oss setup` once — dev, prod, and any other env will reuse the same keys.