@sqaoss/flowy 1.6.0 → 1.6.1

package/README.md

@@ -14,40 +14,107 @@ You get full observability on what every agent planned, built, and shipped.
 
 ## Get Started
 
-### Install (once)
+Flowy runs in one of two modes. Pick the one that fits:
+
+- **Self-hosted** — a local server you run yourself (`flowy serve`). No account, no subscription, your data stays on your machine. Start here if you just want to try Flowy.
+- **Remote (hosted)** — the managed service at `flowy-ai.fly.dev`. Register with an email, then subscribe at checkout. The hosted server gates data operations behind an active subscription.
+
+### Quickstart (self-hosted, no account)
 
 ```bash
 npm i -g @sqaoss/flowy
-flowy setup remote --email you@example.com
+flowy setup local          # installs the bundled server, points the CLI at localhost
+flowy serve &              # starts the local server on 127.0.0.1:4000
+
+cd my-project
+flowy init                 # auto-detects the git repo, creates + maps a project
+
+flowy feature create --title "User Auth" --description "Email + OAuth login"
+flowy feature set "User Auth"
+
+flowy task create --title "Implement OAuth" --description "Wire up the OAuth provider"
+flowy status <task-id> in_progress
+flowy status <task-id> done
 ```
 
-### Initialize a project
+`flowy serve` runs in the foreground; the `&` backgrounds it. Stop it with `kill %1` or run it in a separate terminal. Data lives in `./flowy.sqlite`.
+
+### Quickstart (remote/hosted)
 
 ```bash
+npm i -g @sqaoss/flowy
+flowy setup remote --email you@example.com   # registers; prints an apiKey + checkoutUrl
+
 cd my-project
-flowy init           # auto-detects repo, creates project
+flowy init                                   # auto-detects the git repo, creates + maps a project
+flowy task create --title "First task" --description "Try it out"
 ```
 
-### Start planning
+`setup remote` registers your email and stores the returned API key. It prints a `checkoutUrl` — **open it to start a subscription**. Until you do, the hosted server may reject data operations with `An active subscription is required`. You no longer need to choose a tier up front (`--tier` is optional); pick one at checkout.
+
+Every command outputs JSON. Your agent reads it, acts on it, moves to the next task.
+
+### Descriptions: literal vs. file
+
+`--description` is **always literal text** — it is never read as a file path. To load a description from a file (or stdin), use `--description-file`:
 
 ```bash
-flowy feature create --title "User Auth" --description auth-spec.md
-flowy feature set "User Auth"
+flowy task create --title "Write tests"   --description "Unit + integration tests"
+flowy feature create --title "User Auth"  --description-file auth-spec.md
+flowy task create --title "From stdin"    --description-file -      # reads stdin
+```
 
-flowy task create --title "Implement OAuth" --description oauth.md
-flowy task create --title "Write tests" --description "Unit + integration"
+### Dependencies and ready work
 
-flowy status <task-id> in_progress
-flowy status <task-id> done
+Tasks can block one another. Mark a dependency, inspect it, and ask for only the tasks that are actually actionable right now:
+
+```bash
+flowy task block <blocker-id> <blocked-id>   # blocker must finish before blocked
+flowy task deps <id>                          # what blocks this task, and what it blocks
+flowy task show <id>                          # task details, now including blockedBy/blocks
+
+flowy task list --ready                        # only unblocked, not-done tasks (active project)
+flowy task list --ready --project <project-id> # ...scoped to a specific project
+flowy task list --all                          # every task across the whole backlog
 ```
 
-Every command outputs JSON. Your agent reads it, acts on it, moves to the next task.
+`--ready` returns tasks that are not `done`/`cancelled` and have zero unfinished blockers — the work an agent can pick up next.
+
+### Import and export
+
+Move a whole backlog in or out as a single JSON manifest. Import is **idempotent**: each node carries a stable `key` (a client-key), so re-importing updates the matching nodes in place instead of duplicating them. Edges (`part_of`, `blocks`) round-trip through the real edge model, so a `block` you created by hand is captured on export and not re-created on the next import.
+
+```bash
+flowy export                 # print the active project's manifest to stdout
+flowy export backlog.json    # ...or write it to a file
+flowy import backlog.json    # ingest a manifest (create new, update existing by key)
+```
+
+A manifest looks like:
+
+```json
+{
+  "version": 1,
+  "nodes": [
+    { "key": "proj", "type": "project", "title": "My Project" },
+    { "key": "auth", "type": "feature", "title": "User Auth", "parent": "proj" },
+    { "key": "oauth", "type": "task", "title": "Implement OAuth", "parent": "auth", "status": "draft" }
+  ],
+  "edges": [
+    { "source": "oauth", "target": "auth", "relation": "part_of" }
+  ]
+}
+```
+
+Each node's `parent` implies a `part_of` edge, so the simplest manifests need no explicit `edges`. `blocks` dependencies go in `edges`. The reserved `__flowyKey` metadata field stores the client-key; your own `metadata` is preserved alongside it and stripped back out on export.
 
 ## Agent Skill
 
-Flowy installs an agent skill during setup. Your AI agent automatically knows every command. No manual configuration needed.
+`flowy setup` installs an agent skill so your AI agent automatically knows every command. If that install step fails (offline, no `npx`, registry hiccup), setup prints a warning telling you to install it manually:
 
-Or install the skill manually: `npx skills add sqaoss/flowy`
+```bash
+npx skills add sqaoss/flowy
+```
 
 See [skills/using-flowy/SKILL.md](skills/using-flowy/SKILL.md) for the full skill reference.
 
@@ -70,50 +137,65 @@ Also: `blocked`, `cancelled`. Only `pending_review` entities can be approved.
 
 ## Self-Hosted
 
-Run Flowy on your own machine with SQLite and Docker. Same CLI, same commands.
+Run Flowy on your own machine — no Docker, no account, no subscription. `flowy setup local` installs a bundled server pinned to your CLI version and points the CLI at `localhost`; `flowy serve` runs it natively over SQLite.
 
 ```bash
-flowy setup local    # starts a local server via Docker
-flowy init           # auto-detects repo
+flowy setup local            # install the bundled server, configure the CLI
+flowy serve                  # bind 127.0.0.1:4000, store data in ./flowy.sqlite
+flowy serve --port 5000 --host 0.0.0.0 --db ~/flowy.sqlite   # override defaults
 ```
 
+The self-hosted server supports the full planning workflow — `init`, `project`/`feature`/`task` CRUD, `status`, `approve`, `search`, `tree`, `task deps`, `task list --ready/--all`, and `import`/`export`. Account-only commands (`whoami`, `billing`, `key`) are remote-mode features and don't apply locally.
+
 ## Command Reference
 
 | Command | Description |
 |---------|-------------|
-| `setup remote --email <email>` | Register and connect to the hosted server |
-| `setup local` | Start a local Docker server and configure the CLI |
+| `setup local` | Install the bundled local server and point the CLI at it |
+| `setup remote --email <email> [--tier <tier>]` | Register with the hosted server (`--tier` optional) |
+| `serve [--port] [--host] [--db]` | Run the bundled local server (self-hosted mode) |
 | `init` | Auto-detect repo and create/map project |
-| `whoami` | Show current user |
 | `client set name <name>` | Set client display name |
 | `project create <name>` | Create project |
-| `project set <name>` | Map current directory to project |
+| `project set <name>` | Map current directory to a project |
 | `project list` | List all projects |
-| `project show [<id>]` | Show project details |
-| `feature create --title <t> --description <d>` | Create feature (requires active project) |
+| `project show [<id>]` | Show project details (defaults to active) |
+| `project update [<id>] [--title] [--description\|--description-file] [--metadata]` | Update a project |
+| `project delete [<id>]` | Delete a project (defaults to active) |
+| `feature create --title <t> [--description <text>\|--description-file <path>]` | Create feature (requires active project) |
 | `feature set <name-or-id>` | Set active feature |
 | `feature unset` | Clear active feature |
 | `feature list` | List features in active project |
-| `feature show [<id>]` | Show feature details |
-| `task create --title <t> --description <d>` | Create task (requires active feature) |
-| `task list` | List tasks in active feature |
-| `task show <id>` | Show task details |
-| `task block <id1> <id2>` | Mark task as blocking another |
-| `task unblock <id1> <id2>` | Remove block |
+| `feature show [<id>]` | Show feature details (defaults to active) |
+| `feature update [<id>] [--title] [--description\|--description-file] [--metadata]` | Update a feature |
+| `feature delete [<id>]` | Delete a feature (defaults to active) |
+| `task create --title <t> [--description <text>\|--description-file <path>]` | Create task (requires active feature) |
+| `task list [--ready] [--all] [--project <id>]` | List tasks: active feature, or `--ready`/`--all` (optionally scoped to a project) |
+| `task show <id>` | Show task details, including `blockedBy`/`blocks` |
+| `task update <id> [--title] [--description\|--description-file] [--metadata]` | Update a task |
+| `task delete <id>` | Delete a task |
+| `task block <id1> <id2>` | Mark `id1` as blocking `id2` |
+| `task unblock <id1> <id2>` | Remove a blocking relationship |
+| `task deps <id>` | Show what blocks a task and what it blocks |
 | `status <id> <status>` | Update status (shorthand) |
 | `approve <id>` | Approve (must be pending_review) |
 | `search <query> [--type] [--status] [--limit]` | Full-text search |
-| `tree <id> [--depth N]` | Show subtree |
+| `tree <id> [--depth N]` | Show subtree from any entity |
+| `import <manifest>` | Ingest a JSON manifest of nodes + edges (idempotent by client-key) |
+| `export [output]` | Dump the active project as a manifest (stdout or file) |
+| `whoami` | Show current user (remote mode) |
+| `billing checkout --tier <tier>` | Get a checkout URL for a subscription (remote mode) |
+| `key rotate` | Revoke all API keys and issue a new one (remote mode) |
 
-All commands output JSON to stdout.
+All commands output JSON to stdout; errors go to stderr as `{ "error": "message" }`.
 
 ## Configuration
 
-Config is stored at `~/.config/flowy/config.json`.
+Config is stored at `~/.config/flowy/config.json`. These environment variables override config:
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `FLOWY_API_URL` | GraphQL endpoint | `https://flowy-ai.fly.dev/graphql` |
+| `FLOWY_API_URL` | GraphQL endpoint | `https://flowy-ai.fly.dev/graphql` (remote) / `http://localhost:4000/graphql` (local) |
 | `FLOWY_API_KEY` | API key (remote mode) | -- |
 | `FLOWY_PROJECT` | Override active project by name | -- |
 | `FLOWY_FEATURE` | Override active feature by ID | -- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {

package/skills/using-flowy/SKILL.md

@@ -11,30 +11,54 @@ Flowy gives you a persistent store for plans and execution tracking. Features ar
 
 Without Flowy, your plans live in markdown files that clutter git history, get deleted when done, and leave no record of what you accomplished. With Flowy, plans persist in a database. You flow through work without friction. Your human gets full observability.
 
+## Two Modes
+
+Flowy runs against one of two backends. Which one you're in determines which commands work — check `~/.config/flowy/config.json` (`mode` is `local` or `remote`).
+
+| | Local (self-hosted) | Remote (hosted SaaS) |
+|---|---|---|
+| Setup | `flowy setup local` then `flowy serve` | `flowy setup remote --email <email>` |
+| Server | A bundled server you run (`flowy serve`, SQLite, `127.0.0.1:4000`) | `flowy-ai.fly.dev` |
+| Account / API key | None | Email registration; API key stored in config |
+| Subscription | None — fully free | Data operations require an active subscription |
+| Planning workflow | Full (`init`, project/feature/task CRUD, status, approve, search, tree, `task deps`, `task list --ready/--all`, `import`/`export`) | Full, same commands |
+| `whoami` / `billing` / `key` | **Not available** — these hard-fail locally | Available |
+
+The planning workflow is **identical** in both modes. Only the account/billing commands differ.
+
 ## First Time in a Project
 
 ```bash
 flowy init           # auto-detects the git repo, creates a project, maps this directory
 ```
 
-If Flowy isn't set up yet, the human needs to run:
+If Flowy isn't set up yet, the human needs to choose a mode:
+
 ```bash
 npm i -g @sqaoss/flowy
-flowy setup remote --email their@email.com --tier explorer
+
+# Self-hosted (free, no account):
+flowy setup local    # installs the bundled server, points the CLI at localhost
+flowy serve          # starts the local server on 127.0.0.1:4000 (run in its own terminal)
+
+# OR hosted (managed service):
+flowy setup remote --email their@email.com   # registers; prints apiKey + checkoutUrl
 ```
 
-After registration, complete payment at the checkout URL provided.
+`setup remote` prints a `checkoutUrl`. On the hosted server, data operations are rejected until a subscription is active — the human opens that URL to subscribe. `--tier` is optional at registration; a tier is chosen at checkout.
+
+`flowy setup` also installs this agent skill via `npx skills add sqaoss/flowy`. If that step fails, setup prints a warning with the manual install command — the skill is not installed until you run it.
 
 ## Core Workflow
 
 ```bash
 # 1. Plan a feature (master plan)
-flowy feature create --title "User Auth" --description auth-spec.md
+flowy feature create --title "User Auth" --description "Email + OAuth login"
 flowy feature set "User Auth"
 
 # 2. Break into tasks (execution steps)
-flowy task create --title "Implement OAuth" --description oauth.md
-flowy task create --title "Write tests" --description "Unit + integration tests"
+flowy task create --title "Implement OAuth" --description "Wire up the OAuth provider"
+flowy task create --title "Write tests"     --description-file tests-plan.md
 
 # 3. Execute and track
 flowy status <task-id> in_progress
@@ -42,31 +66,19 @@ flowy status <task-id> in_progress
 flowy status <task-id> done
 
 # 4. Move to next task or feature
-flowy feature create --title "API Rate Limiting" --description rate-limit.md
+flowy feature create --title "API Rate Limiting" --description-file rate-limit.md
 flowy feature set "API Rate Limiting"
 ```
 
 ## Entity Hierarchy
 
 ```
-project -> feature -> task
-  1:many     1:many
+client -> project -> feature -> task
+            1:many     1:many
 ```
 
 Every task belongs to a feature. Every feature belongs to a project. No orphans. The project is set automatically by `flowy init`.
 
-## Subscription Tiers
-
-Flowy requires an active subscription for all data operations.
-
-| Tier | Projects | Description |
-|------|----------|-------------|
-| `explorer` | Up to 10 | For individual developers |
-| `pro` | Unlimited | For power users |
-| `team` | Unlimited | For teams |
-
-After registration, complete payment at the checkout URL. Existing users can get a new checkout URL with `flowy billing checkout --tier <tier>`.
-
 ## Status Flow
 
 ```
@@ -75,85 +87,145 @@ draft -> pending_review -> approved -> in_progress -> done
 
 Also: `blocked`, `cancelled`
 
-Only `pending_review` entities can be approved via `flowy approve <id>`.
+Use `flowy status <id> <status>` to move a node. Only `pending_review` nodes can be approved via `flowy approve <id>`.
 
 ## Commands
 
+### Setup and Server
+```bash
+flowy setup local                          # install bundled local server, configure CLI
+flowy serve                                 # run the local server (127.0.0.1:4000, ./flowy.sqlite)
+flowy serve --port 5000 --host 0.0.0.0 --db ~/flowy.sqlite
+flowy setup remote --email <email>          # register with the hosted server (--tier optional)
+flowy setup remote --email <email> --tier explorer
+```
+
 ### Project Context
 ```bash
-flowy init                            # Auto-detect repo, create + set project
-flowy project list                    # List all projects
-flowy project show [<id>]             # Show project details
+flowy init                                  # auto-detect repo, create + map project
+flowy project create <name>                 # create a project by name
+flowy project set <name>                    # map current directory to an existing project
+flowy project list                          # list all projects
+flowy project show [<id>]                   # show project details (defaults to active)
+flowy project update [<id>] --title <t>     # update title/description/metadata
+flowy project delete [<id>]                 # delete project (defaults to active)
 ```
 
 ### Features (requires active project)
 ```bash
-flowy feature create --title "Title" --description "description or file.md"
-flowy feature set "Title or ID"       # Set active feature
-flowy feature unset                   # Clear active feature
-flowy feature list                    # List features in project
-flowy feature show [<id>]             # Show feature details
+flowy feature create --title "Title" --description "text"
+flowy feature create --title "Title" --description-file spec.md
+flowy feature set "Title or ID"             # set active feature
+flowy feature unset                         # clear active feature
+flowy feature list                          # list features in active project
+flowy feature show [<id>]                   # show feature (defaults to active)
+flowy feature update [<id>] --title <t>     # update title/description/metadata
+flowy feature delete [<id>]                 # delete feature (defaults to active)
 ```
 
 ### Tasks (requires active feature)
 ```bash
-flowy task create --title "Title" --description "description or file.md"
-flowy task list                       # List tasks in feature
-flowy task show <id>                  # Show task details
-flowy task block <blocker> <blocked>  # Mark dependency
-flowy task unblock <blocker> <blocked>
+flowy task create --title "Title" --description "text"
+flowy task create --title "Title" --description-file spec.md
+flowy task list                             # tasks in active feature
+flowy task list --ready                     # only actionable tasks (active project)
+flowy task list --ready --project <id>      # ...scoped to a specific project
+flowy task list --all                       # every task across the whole backlog
+flowy task show <id>                        # task details, incl. blockedBy/blocks
+flowy task update <id> --title <t>          # update title/description/metadata
+flowy task delete <id>                      # delete task
+flowy task block <id1> <id2>                # mark id1 as blocking id2
+flowy task unblock <id1> <id2>              # remove a blocking relationship
+flowy task deps <id>                        # what blocks this task, and what it blocks
 ```
 
+`task list --ready` returns only tasks that are not `done`/`cancelled` and have zero unfinished blockers — the next work an agent can pick up. Without `--project` it scopes to the active project; with `--all` it spans the whole backlog. `task deps <id>` (and the `blockedBy`/`blocks` fields on `task show`) report the dependency graph built from `task block`.
+
 ### Status and Approval
 ```bash
 flowy status <id> in_progress
 flowy status <id> pending_review
-flowy approve <id>                    # Only works on pending_review
+flowy approve <id>                          # only works on pending_review
 flowy status <id> done
 ```
 
 ### Search and Explore
 ```bash
 flowy search "query" --type task --status draft --limit 10
-flowy tree <project-id> --depth 3     # Show full subtree
+flowy tree <id> --depth 3                    # show subtree from any entity
 ```
 
-### Setup
+### Import and Export
 ```bash
-flowy setup remote --email <email> --tier <tier>  # Register (tier: explorer, pro, team)
-flowy setup local                                  # Self-hosted Docker server
-flowy whoami                                       # Show user info (includes grace period)
+flowy export                                 # print active project's manifest to stdout
+flowy export backlog.json                    # ...or write it to a file
+flowy import backlog.json                    # ingest a manifest (idempotent by client-key)
 ```
 
-### Billing
+A manifest is a single JSON document describing a backlog: `nodes` (projects, features, tasks) plus dependency `edges`. Each node is addressed by a stable **client-key** (`key`), not a server id:
+
+```json
+{
+  "version": 1,
+  "nodes": [
+    { "key": "proj", "type": "project", "title": "My Project" },
+    { "key": "auth", "type": "feature", "title": "User Auth", "parent": "proj" },
+    { "key": "oauth", "type": "task", "title": "Implement OAuth", "parent": "auth", "status": "draft" }
+  ],
+  "edges": [
+    { "source": "oauth", "target": "auth", "relation": "part_of" }
+  ]
+}
+```
+
+**Idempotency:** import upserts by client-key — re-importing the same manifest updates the matching nodes in place instead of creating duplicates. The key is stored in node metadata under the reserved `__flowyKey` field (your own `metadata` is preserved alongside it and stripped back out on export). A node's `parent` implies a `part_of` edge, so simple manifests need no explicit `edges`; `blocks` dependencies are listed in `edges`. Edges live in the real edge model (`createEdge` / `Query.edges`), so a `blocks` edge created by hand with `task block` is captured on export and never re-created on the next import. Works in both local and remote modes.
+
+### Remote-only (hosted mode)
+These hit account/billing resolvers that do **not** exist on the local server; they fail in local mode.
 ```bash
-flowy billing checkout --tier <tier>              # Get checkout URL for subscription
+flowy whoami                                # show current user (id, email, tier, graceEndsAt)
+flowy billing checkout --tier <tier>        # get a checkout URL (tier: explorer, pro, team)
+flowy key rotate                            # revoke all API keys and issue a new one
 ```
 
-### API Key Management
+### Client Settings (local config)
 ```bash
-flowy key rotate                                  # Revoke all keys and generate a new one
+flowy client set name "Your Name"           # set client display name in local config
+```
+
+## Descriptions: literal vs. file
+
+`create` and `update` commands take a description two ways. They are mutually exclusive.
+
+- `--description <text>` — **always literal**. The text is used verbatim and is *never* interpreted as a file path. `--description plan.md` stores the string `plan.md`, not the file's contents.
+- `--description-file <path>` — reads the file's contents as the description. Use `-` to read from stdin.
+
+```bash
+flowy task create --title "T" --description "Do the thing"
+flowy task create --title "T" --description-file plan.md
+flowy task create --title "T" --description-file -          # from stdin
 ```
 
 ## Validation Rules
 
-- **Title is required** and cannot be empty
-- **Description** is optional, but if provided cannot be empty
-- **--description** accepts a file path (reads content) or an inline string
-- **Search** requires at least 3 characters
-- **Status** must be one of: draft, pending_review, approved, in_progress, done, blocked, cancelled
-- **Blocking**: a task cannot block itself
-- **Edges**: both source and target nodes must exist
+- **Title is required** on every `create` (cannot be empty).
+- **Description is required** on `create`: pass exactly one of `--description` or `--description-file`. Passing both is an error; passing neither is an error.
+- **Search** requires a non-empty query and returns up to `--limit` results (default 50).
+- **Status** must be one of: `draft`, `pending_review`, `approved`, `in_progress`, `done`, `blocked`, `cancelled`.
+- **Blocking** creates a `blocks` edge between two existing tasks; both nodes must exist.
+- **Approve** only succeeds on a node currently in `pending_review`.
 
 ## Output Format
 
-All commands output JSON to stdout. Errors go to stderr as `{ "error": "message" }`.
+All commands output JSON to stdout. Errors go to stderr as `{ "error": "message" }` (with an optional `code`), and the process exits non-zero.
+
+On the hosted server, an expired or missing subscription surfaces as an error like `An active subscription is required. Run \`flowy billing checkout\` to subscribe.` This never happens in local mode.
 
 ## Environment Variables
 
 | Variable | Description |
 |----------|-------------|
+| `FLOWY_API_URL` | GraphQL endpoint (defaults: hosted in remote mode, `http://localhost:4000/graphql` in local mode) |
+| `FLOWY_API_KEY` | API key (remote mode; set by `flowy setup remote`) |
 | `FLOWY_PROJECT` | Override active project by name |
 | `FLOWY_FEATURE` | Override active feature by ID |
-| `FLOWY_API_URL` | GraphQL endpoint |
-| `FLOWY_API_KEY` | API key (from setup) |

package/src/commands/setup.test.ts

@@ -97,16 +97,37 @@ describe('setup command', () => {
     )
   })
 
-  test('setup remote requires --tier', async () => {
+  test('setup remote registers without --tier (tier is optional)', async () => {
+    const mockGraphql = vi.fn().mockResolvedValue({
+      register: {
+        user: {
+          id: 'user_1',
+          email: 'test@example.com',
+          tier: null,
+          createdAt: '2026-06-13T00:00:00Z',
+          graceEndsAt: null,
+        },
+        apiKey: 'flowy_key',
+        checkoutUrl: null,
+      },
+    })
+    vi.doMock('../util/client.ts', () => ({
+      graphql: mockGraphql,
+    }))
+    mockSpawnSync.mockReturnValue({ status: 0, stdout: Buffer.from('') })
+
     const { setupCommand } = await import('./setup.ts')
     await setupCommand.parseAsync(['remote', '--email', 'test@example.com'], {
       from: 'user',
     })
 
-    expect(mockOutputError).toHaveBeenCalledWith(
-      expect.objectContaining({
-        message: expect.stringContaining('--tier is required'),
-      }),
+    // No tier required: registration proceeds, no usage error raised.
+    expect(mockOutputError).not.toHaveBeenCalled()
+    expect(mockGraphql).toHaveBeenCalledOnce()
+    const [, variables] = mockGraphql.mock.calls[0]!
+    expect(variables).toEqual({ email: 'test@example.com', tier: undefined })
+    expect(mockSaveConfig).toHaveBeenCalledWith(
+      expect.objectContaining({ mode: 'remote', apiKey: 'flowy_key' }),
     )
   })
 
@@ -221,4 +242,68 @@ describe('setup command', () => {
       }),
     )
   })
+
+  test('setup local warns when the skill install fails', async () => {
+    // bun add succeeds, npx skills add fails (non-zero status).
+    mockSpawnSync.mockImplementation((cmd: string) =>
+      cmd === 'npx' ? { status: 1 } : { status: 0 },
+    )
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(['local'], { from: 'user' })
+
+    const warned = errSpy.mock.calls.map((c) => String(c[0])).join('\n')
+    expect(warned).toMatch(/skill/i)
+    expect(warned).toContain('npx skills add sqaoss/flowy')
+    // Setup itself still completes successfully (config saved, result emitted).
+    expect(mockOutput).toHaveBeenCalled()
+    expect(mockOutputError).not.toHaveBeenCalled()
+    errSpy.mockRestore()
+  })
+
+  test('setup local does not warn when the skill install succeeds', async () => {
+    mockSpawnSync.mockReturnValue({ status: 0 })
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(['local'], { from: 'user' })
+
+    const warned = errSpy.mock.calls.map((c) => String(c[0])).join('\n')
+    expect(warned).not.toMatch(/skill/i)
+    errSpy.mockRestore()
+  })
+
+  test('setup remote warns when the skill install fails', async () => {
+    const mockGraphql = vi.fn().mockResolvedValue({
+      register: {
+        user: {
+          id: 'user_1',
+          email: 'a@b.com',
+          tier: null,
+          createdAt: '2026-06-13T00:00:00Z',
+          graceEndsAt: null,
+        },
+        apiKey: 'flowy_key',
+        checkoutUrl: null,
+      },
+    })
+    vi.doMock('../util/client.ts', () => ({ graphql: mockGraphql }))
+    mockSpawnSync.mockImplementation((cmd: string) =>
+      cmd === 'npx' ? { status: 1 } : { status: 0 },
+    )
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(['remote', '--email', 'a@b.com'], {
+      from: 'user',
+    })
+
+    const warned = errSpy.mock.calls.map((c) => String(c[0])).join('\n')
+    expect(warned).toMatch(/skill/i)
+    expect(warned).toContain('npx skills add sqaoss/flowy')
+    expect(mockOutput).toHaveBeenCalled()
+    expect(mockOutputError).not.toHaveBeenCalled()
+    errSpy.mockRestore()
+  })
 })

package/src/commands/setup.ts

@@ -8,6 +8,32 @@ export const setupCommand = new Command('setup').description(
   'Configure the Flowy CLI \u2014 use "flowy setup local" or "flowy setup remote"',
 )
 
+const SKILL_PACKAGE = 'sqaoss/flowy'
+
+/**
+ * Install the Flowy agent skill, surfacing failure instead of swallowing it.
+ *
+ * `npx skills add` can fail (offline, npx unavailable, registry hiccup). If it
+ * does, setup should still succeed \u2014 but the user must be told the skill was
+ * NOT installed, with the exact command to retry, rather than silently
+ * assuming their agent now knows the commands (F14).
+ */
+function installSkill(): void {
+  const result = spawnSync('npx', ['skills', 'add', SKILL_PACKAGE, '--yes'], {
+    stdio: 'inherit',
+  })
+  if (result.error != null || result.status !== 0) {
+    const reason = result.error
+      ? result.error.message
+      : `exit code ${result.status}`
+    console.error(
+      `Warning: failed to install the Flowy agent skill (${reason}). ` +
+        `Your agent will not know Flowy's commands until you install it manually:\n` +
+        `  npx skills add ${SKILL_PACKAGE}`,
+    )
+  }
+}
+
 setupCommand
   .command('local')
   .description('Set up Flowy with a native local server (no Docker)')
@@ -26,9 +52,7 @@ setupCommand
       config.mode = 'local'
       config.apiUrl = apiUrl
       saveConfig(config)
-      spawnSync('npx', ['skills', 'add', 'sqaoss/flowy', '--yes'], {
-        stdio: 'inherit',
-      })
+      installSkill()
 
       output({
         mode: 'local',
@@ -46,20 +70,16 @@ setupCommand
   .description('Connect to the hosted Flowy service')
   .option('--email <email>', 'Email address for registration')
   .addOption(
-    new Option('--tier <tier>', 'Subscription tier').choices([
-      'explorer',
-      'pro',
-      'team',
-    ]),
+    new Option(
+      '--tier <tier>',
+      'Subscription tier (optional — pick one later at checkout)',
+    ).choices(['explorer', 'pro', 'team']),
   )
   .action(async (opts) => {
     try {
       if (!opts.email) {
         throw new Error('--email is required for registration')
       }
-      if (!opts.tier) {
-        throw new Error('--tier is required for registration')
-      }
 
       const { graphql } = await import('../util/client.ts')
 
@@ -81,7 +101,7 @@ setupCommand
           checkoutUrl: string
         }
       }>(
-        `mutation Register($email: String!, $tier: String!) {
+        `mutation Register($email: String!, $tier: String) {
           register(email: $email, tier: $tier) {
             user { id email tier createdAt graceEndsAt }
             apiKey
@@ -94,9 +114,7 @@ setupCommand
       config.apiKey = data.register.apiKey
       saveConfig(config)
 
-      spawnSync('npx', ['skills', 'add', 'sqaoss/flowy', '--yes'], {
-        stdio: 'inherit',
-      })
+      installSkill()
 
       output(data.register)
     } catch (error) {