@flydocs/cli 0.6.0-alpha.2 → 0.6.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.6.0-alpha.2",
+  "version": "0.6.0-alpha.4",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {

package/template/.claude/commands/flydocs-setup.md

@@ -301,7 +301,32 @@ FLYDOCS_API_KEY is not set. Run `flydocs connect` first to set up your API key.
 
 Do not proceed until the key is available.
 
-**Step 2: Select or create team.**
+**Step 2: Detect or select provider.**
+
+Query connected providers:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_providers.py
+```
+
+This returns `[{type, name, connected}]`. Handle based on results:
+
+- **One connected provider** — auto-select it and confirm with the user.
+- **Multiple connected providers** — present a numbered list, let the user
+  choose which to use for this project.
+- **No connected providers** — error: "No providers connected. Connect Linear
+  or Jira at app.flydocs.ai before running setup."
+
+After selection, store the preference:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/set_provider.py <provider_type>
+```
+
+This stores the provider type on the relay (for routing) and updates
+`provider.type` in local config.
+
+**Step 3: Select or create team.**
 
 If `provider.teamId` in config is null, discover available teams:
 
@@ -334,7 +359,7 @@ python3 .claude/skills/flydocs-cloud/scripts/set_team.py <team_id>
 This stores the team preference server-side (the relay uses it for all
 team-scoped operations) and updates `provider.teamId` in local config.
 
-**Step 3: Get or create project.**
+**Step 4: Get or create project.**
 
 Query existing projects:
 
@@ -349,7 +374,7 @@ create a new project:
 python3 .claude/skills/flydocs-cloud/scripts/create_project.py --name "Project Name"
 ```
 
-**Step 4: Configure labels.**
+**Step 5: Configure labels.**
 
 Fetch available labels from the provider:
 
@@ -384,7 +409,49 @@ python3 .claude/skills/flydocs-cloud/scripts/set_labels.py \
 If the relay returns `LABELS_NOT_FOUND`, show the invalid names and ask the
 user to correct them.
 
-**Step 5: Configure product identity.**
+**Step 6: Configure status mapping.**
+
+Map provider workflow states to FlyDocs statuses. Run auto-mapping first:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/set_status_mapping.py --auto
+```
+
+The relay auto-maps by case-insensitive name matching (e.g., "In Progress"
+maps to `IMPLEMENTING`, "Done" maps to `COMPLETE`, "Backlog" maps to
+`BACKLOG`).
+
+**Review the result:** The response includes which FlyDocs statuses were
+mapped and which were not. Show the user:
+
+```
+Status mapping:
+  BACKLOG      -> Backlog
+  READY        -> Ready
+  IMPLEMENTING -> In Progress
+  REVIEW       -> In Review
+  COMPLETE     -> Done
+  CANCELED     -> Canceled
+  (unmapped)   -> BLOCKED, TESTING
+```
+
+If some statuses are unmapped, **warn but don't block** — transitions for
+unmapped statuses will fall back to provider name matching. If the user
+wants to fix unmapped statuses, fetch available provider states and let
+them map manually:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_statuses.py
+```
+
+Then store the corrected mapping:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/set_status_mapping.py \
+  --mapping '{"BACKLOG":"Backlog","IMPLEMENTING":"In Progress","BLOCKED":"On Hold",...}'
+```
+
+**Step 7: Configure product identity.**
 
 Ask about product metadata:
 
@@ -392,14 +459,15 @@ Ask about product metadata:
   from project.md)
 - **Icon and color** — optional, ask if they have preferences
 
-**Step 6: Save to config.**
+**Step 8: Save to config.**
 
 Update `.flydocs/config.json`:
 
-- `provider.type` — `"linear"` (set by connect command)
+- `provider.type` — set by `set_provider.py`
 - `provider.teamId` — selected team ID (set by `set_team.py`)
 - `labels.defaults` — default label names (set by `set_labels.py`)
 - `labels.typeMap` — type-to-label mapping (set by `set_labels.py`)
+- `statusMapping` — FlyDocs-to-provider status mapping (set by `set_status_mapping.py`)
 - `workspace.activeProjects` — add the project ID
 - `workspace.product.name` — product name
 
@@ -436,11 +504,11 @@ Let the user customize names, descriptions, and target dates.
 
 **Step 4: Create milestones.**
 
-For each approved milestone:
+For each approved milestone, pass the project ID from Phase 2 Step 3:
 
 ```bash
 python3 .claude/skills/flydocs-cloud/scripts/create_milestone.py \
-  --name "Phase 1: Foundation" --target-date YYYY-MM-DD
+  --name "Phase 1: Foundation" --project <project_id> --target-date YYYY-MM-DD
 ```
 
 Record the milestone IDs for use in Phase 4.
@@ -468,10 +536,11 @@ For each work item, follow the capture procedure from
 `.claude/skills/flydocs-workflow/stages/capture.md`:
 
 - Determine type (feature, bug, chore, idea)
-- Create via the mechanism script:
+- Create via the mechanism script (cloud: pass `--project` from Phase 2):
   ```bash
   python3 .claude/skills/flydocs-{tier}/scripts/create_issue.py \
-    --title "Issue title" --type feature --priority 3 --estimate 2
+    --title "Issue title" --type feature --priority 3 --estimate 2 \
+    --project <project_id>
   ```
 - For quick ideas, use `--triage` flag
 

package/template/.claude/commands/flydocs-upgrade.md

@@ -65,7 +65,7 @@ Count totals by status and type.
 
 **Step 3: Check for API readiness.**
 
-Check if `FLYDOCS_RELAY_API_KEY` is set in the environment (from `.env` or
+Check if `FLYDOCS_API_KEY` is set in the environment (from `.env` or
 `.env.local`). If not, warn the user they will need it for Phase 1.
 
 **Step 4: Present migration summary.**
@@ -100,27 +100,39 @@ Confirm with the user before continuing.
 ## Phase 1: Connect to Cloud
 
 Guide the user through connecting to the cloud provider. This swaps the
-mechanism skill from `flydocs-local` to `flydocs-cloud`.
+tier, stores the API key, and prepares the cloud mechanism skill.
 
-**Step 1: Run flydocs connect.**
+**Step 1: Get API key.**
 
-Instruct the user to run `flydocs connect --here` from their terminal
-(this is a CLI command, not an AI command). Explain what it does:
+Ask the user for their FlyDocs API key (`fdk_...`). If `FLYDOCS_API_KEY`
+is already set in the environment, confirm they want to use the existing
+key or enter a new one.
+
+If no key is available, instruct the user:
 
 ```
-Run this in your terminal:
-  flydocs connect --here
-
-This will:
-  - Prompt for your relay API key (from flydocs.ai account)
-  - Update .flydocs/config.json to cloud tier
-  - Swap mechanism skills (local -> cloud)
-  - Verify the connection works
+You'll need a FlyDocs API key (fdk_...) from your dashboard at app.flydocs.ai.
+
+Option A: Run `flydocs connect --here` in your terminal (handles everything)
+Option B: Add FLYDOCS_API_KEY=fdk_... to your .env or .env.local file
 ```
 
-**Step 2: Wait for completion.**
+Wait for the user to confirm the key is set before proceeding.
+
+**Step 2: Update config to cloud tier.**
+
+Read `.flydocs/config.json`, update `tier` to `"cloud"`, and write it back.
+Preserve all existing config values (detected stack, skills, etc.).
+
+**Step 3: Swap mechanism skill.**
+
+Instruct the user to run `flydocs connect --here` from their terminal if
+they haven't already. This handles the mechanism skill swap (installs
+`flydocs-cloud`, removes `flydocs-local`).
+
+**Step 4: Verify connection.**
 
-After the user confirms they ran `flydocs connect`, verify:
+After the user confirms the swap, verify:
 
 1. Read `.flydocs/config.json` — `tier` should now be `cloud`
 2. Check that `.claude/skills/flydocs-cloud/scripts/` exists

package/template/.claude/skills/flydocs-cloud/SKILL.md

@@ -29,15 +29,15 @@ All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
 
 ### Shared Contract Scripts
 
-| Script                  | Usage                                                                                                                                                                  | Output                                                                                                                                        |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `create_issue.py`       | `--title "..." --type feature [--description "..."] [--description-file PATH] [--priority 0-4] [--estimate 1-5] [--assignee STR] [--labels "a,b"] [--triage] \| stdin` | `{id, identifier, title, url}`                                                                                                                |
-| `transition.py`         | `<ref> <STATUS> "<comment>"`                                                                                                                                           | `{success, issue, previousStatus, newStatus}`                                                                                                 |
-| `comment.py`            | `<ref> ["<comment>"] \| stdin`                                                                                                                                         | `{success, commentId}`                                                                                                                        |
-| `list_issues.py`        | `[--status STATUS[,STATUS]] [--active] [--project ID] [--milestone ID] [--assignee STR] [--mine] [--limit N]`                                                          | `[{id, identifier, title, status, assignee, priority, dueDate, milestone, milestoneId, milestoneSortOrder, project, projectId}]`              |
-| `get_issue.py`          | `<ref> [--fields basic\|full]`                                                                                                                                         | `{id, identifier, title, description, status, assignee, priority, estimate, dueDate, milestone, milestoneId, project, projectId, comments[]}` |
-| `assign.py`             | `<ref> <assignee>`                                                                                                                                                     | `{success, issue, assignee}`                                                                                                                  |
-| `update_description.py` | `<ref> --text "..." \| --file PATH \| stdin`                                                                                                                           | `{success, issue}`                                                                                                                            |
+| Script                  | Usage                                                                                                                                                                                 | Output                                                                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create_issue.py`       | `--title "..." --type feature [--description "..."] [--description-file PATH] [--priority 0-4] [--estimate 1-5] [--assignee STR] [--project ID] [--labels "a,b"] [--triage] \| stdin` | `{id, identifier, title, url}`                                                                                                                |
+| `transition.py`         | `<ref> <STATUS> "<comment>"`                                                                                                                                                          | `{success, issue, previousStatus, newStatus}`                                                                                                 |
+| `comment.py`            | `<ref> ["<comment>"] \| stdin`                                                                                                                                                        | `{success, commentId}`                                                                                                                        |
+| `list_issues.py`        | `[--status STATUS[,STATUS]] [--active] [--project ID] [--milestone ID] [--assignee STR] [--mine] [--limit N]`                                                                         | `[{id, identifier, title, status, assignee, priority, dueDate, milestone, milestoneId, milestoneSortOrder, project, projectId}]`              |
+| `get_issue.py`          | `<ref> [--fields basic\|full]`                                                                                                                                                        | `{id, identifier, title, description, status, assignee, priority, estimate, dueDate, milestone, milestoneId, project, projectId, comments[]}` |
+| `assign.py`             | `<ref> <assignee>`                                                                                                                                                                    | `{success, issue, assignee}`                                                                                                                  |
+| `update_description.py` | `<ref> --text "..." \| --file PATH \| stdin`                                                                                                                                          | `{success, issue}`                                                                                                                            |
 
 ### Extended Scripts
 
@@ -58,13 +58,17 @@ All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
 
 ### Workspace Scripts
 
-| Script           | Usage                                                                 | Output                                                                    |
-| ---------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `list_teams.py`  | (no args)                                                             | `[{id, name, key}]`                                                       |
-| `create_team.py` | `--name "..." [--key KEY] [--description "..."] [--parent <team_id>]` | `{id, name, key}` — `--parent` creates a sub-team                         |
-| `set_team.py`    | `<team_id>`                                                           | `{success}` — updates relay preference and local config `provider.teamId` |
-| `list_labels.py` | (no args)                                                             | `[{id, name, color}]` — requires team to be set first                     |
-| `set_labels.py`  | `--defaults '["a"]' --type-map '{"feature":["F"],...}' \| stdin`      | `{success, validated, defaults, typeMap}` — stores label config on relay  |
+| Script                  | Usage                                                                 | Output                                                                    |
+| ----------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `list_providers.py`     | (no args)                                                             | `[{type, name, connected}]`                                               |
+| `set_provider.py`       | `<provider_type>` (`linear` or `jira`)                                | `{success}` — updates relay routing and local config `provider.type`      |
+| `list_teams.py`         | (no args)                                                             | `[{id, name, key}]`                                                       |
+| `create_team.py`        | `--name "..." [--key KEY] [--description "..."] [--parent <team_id>]` | `{id, name, key}` — `--parent` creates a sub-team                         |
+| `set_team.py`           | `<team_id>`                                                           | `{success}` — updates relay preference and local config `provider.teamId` |
+| `list_labels.py`        | (no args)                                                             | `[{id, name, color}]` — requires team to be set first                     |
+| `set_labels.py`         | `--defaults '["a"]' --type-map '{"feature":["F"],...}' \| stdin`      | `{success, validated, defaults, typeMap}` — stores label config on relay  |
+| `list_statuses.py`      | (no args)                                                             | `[{name, type, color}]` — provider workflow states for manual mapping     |
+| `set_status_mapping.py` | `--auto \| --mapping '{"BACKLOG":"Backlog",...}' \| stdin`            | `{success, mapping, unmapped[]}` — stores status mapping on relay         |
 
 ### Script Notes
 

package/template/.claude/skills/flydocs-cloud/scripts/create_issue.py

@@ -18,6 +18,7 @@ def main():
     parser.add_argument("--priority", type=int, default=3, choices=range(5))
     parser.add_argument("--estimate", type=int, default=0, choices=[0, 1, 2, 3, 5])
     parser.add_argument("--assignee", default=None)
+    parser.add_argument("--project", default=None, help="Project ID")
     parser.add_argument("--labels", default=None, help="Comma-separated ad-hoc label names")
     parser.add_argument("--triage", action="store_true")
     args = parser.parse_args()
@@ -43,6 +44,8 @@ def main():
         body["estimate"] = args.estimate
     if args.assignee:
         body["assignee"] = args.assignee
+    if args.project:
+        body["projectId"] = args.project
     if args.labels:
         body["labels"] = [l.strip() for l in args.labels.split(",") if l.strip()]
     if args.triage:

package/template/.claude/skills/flydocs-cloud/scripts/list_providers.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""List available providers via the FlyDocs Relay API."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json
+
+
+def main():
+    client = get_client()
+    result = client.get("/providers")
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-cloud/scripts/list_statuses.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""List provider workflow states via the FlyDocs Relay API."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json
+
+
+def main():
+    client = get_client()
+    result = client.get("/auth/statuses")
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-cloud/scripts/set_provider.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Set provider preference via the FlyDocs Relay API.
+
+Stores the provider type on the relay (for server-side routing)
+and updates the local config (for display/reference).
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Set provider preference")
+    parser.add_argument(
+        "provider_type",
+        choices=["linear", "jira"],
+        help="Provider type",
+    )
+    args = parser.parse_args()
+
+    client = get_client()
+    result = client.post("/auth/provider", {"providerType": args.provider_type})
+
+    # Update local config with provider type
+    config_path = client.config_path
+    if config_path.exists():
+        with open(config_path, "r") as f:
+            config = json.load(f)
+        if "provider" not in config:
+            config["provider"] = {"type": args.provider_type, "teamId": None}
+        else:
+            config["provider"]["type"] = args.provider_type
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-cloud/scripts/set_status_mapping.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Set status mapping on the relay API key.
+
+Maps provider workflow states to FlyDocs statuses. Pass "auto" for
+case-insensitive auto-mapping, or provide a manual mapping object.
+
+Usage:
+    set_status_mapping.py --auto
+    set_status_mapping.py --mapping '{"BACKLOG":"Backlog","IMPLEMENTING":"In Progress",...}'
+    echo '{"mapping":"auto"}' | set_status_mapping.py
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Set status mapping on relay")
+    parser.add_argument(
+        "--auto",
+        action="store_true",
+        help="Auto-map provider states to FlyDocs statuses by name",
+    )
+    parser.add_argument(
+        "--mapping",
+        default=None,
+        help="JSON object mapping FlyDocs statuses to provider state names",
+    )
+    args = parser.parse_args()
+
+    if args.auto:
+        body: dict = {"mapping": "auto"}
+    elif args.mapping is not None:
+        try:
+            body = {"mapping": json.loads(args.mapping)}
+        except json.JSONDecodeError:
+            fail("Invalid JSON for --mapping")
+    elif not sys.stdin.isatty():
+        try:
+            body = json.loads(sys.stdin.read().strip())
+        except json.JSONDecodeError:
+            fail("Invalid JSON on stdin")
+    else:
+        fail("Provide --auto, --mapping '{...}', or pipe JSON via stdin")
+
+    client = get_client()
+    result = client.post("/auth/statuses", body)
+
+    # Store status mapping in local config as reference
+    config_path = client.config_path
+    if config_path.exists():
+        with open(config_path, "r") as f:
+            config = json.load(f)
+        if isinstance(result.get("mapping"), dict):
+            config["statusMapping"] = result["mapping"]
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

package/template/.flydocs/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.2",
+  "version": "0.6.0-alpha.4",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.2
+0.6.0-alpha.4

package/template/CHANGELOG.md

@@ -7,6 +7,45 @@ Versioning: [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.6.0-alpha.4] — 2026-03-13
+
+### Added
+
+- **Status mapping** — new `list_statuses.py` and `set_status_mapping.py`
+  scripts. Setup flow auto-maps provider workflow states to FlyDocs statuses
+  after label config, warns on unmapped statuses without blocking.
+
+---
+
+## [0.6.0-alpha.3] — 2026-03-13
+
+### Added
+
+- **Provider selection** — new `list_providers.py` and `set_provider.py`
+  scripts for multi-provider support (Linear + Jira). Setup flow detects
+  connected providers before team selection.
+- **Inline API key prompt** — `flydocs install` now prompts for FlyDocs API
+  key when cloud tier is selected. No separate `flydocs connect` step needed.
+- **Existing config detection** — install detects pre-existing `.claude/CLAUDE.md`,
+  `settings.json`, `hooks.json`, and `AGENTS.md`. Prompts user to overwrite
+  (with backup) or preserve.
+- **`--project` flag** — `create_issue.py` accepts `--project <id>` to scope
+  issues to a specific project. Fixes milestone/project mismatch during setup.
+- **Team creation** — `create_team.py` with `--parent` flag for sub-teams.
+
+### Changed
+
+- **Setup flow restructured** — Phase 2 now starts with provider detection,
+  then team selection, project, labels. Milestones and issues pass `--project`.
+- **Community skill output** — install shows one line per skill instead of
+  4-5 verbose lines. "No triggers" warning suppressed for community skills.
+- **`/flydocs-upgrade` streamlined** — Phase 1 inlines API key handling
+  instead of requiring a separate terminal step.
+- **API key helpers extracted** — shared `api-key.ts` module used by both
+  `install` and `connect` commands.
+
+---
+
 ## [0.6.0-alpha.1] — 2026-03-12
 
 ### Added

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.2",
+  "version": "0.6.0-alpha.4",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",