@flydocs/cli 0.6.0-alpha.1 → 0.6.0-alpha.10

package/package.json

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

package/template/.claude/CLAUDE.md

@@ -31,6 +31,8 @@ The FlyDocs development lifecycle. Read the workflow skill before taking any wor
 | QE validation        | `flydocs-workflow` | `stages/validate.md`              |
 | Close issue          | `flydocs-workflow` | `stages/close.md`                 |
 | Start / wrap session | `flydocs-workflow` | `session.md`                      |
+| Knowledge capture    | `flydocs-workflow` | `/knowledge` command              |
+| PR & git workflow    | `flydocs-workflow` | `reference/pr-workflow.md`        |
 | Comment templates    | `flydocs-workflow` | `reference/comment-templates.md`  |
 | Status transitions   | `flydocs-workflow` | `reference/status-workflow.md`    |
 | Priority & estimates | `flydocs-workflow` | `reference/priority-estimates.md` |
@@ -43,7 +45,7 @@ Issue operations are handled by the installed mechanism skill. Only one is activ
 | Tier              | Skill           | Backend                        |
 | ----------------- | --------------- | ------------------------------ |
 | Local (free)      | `flydocs-local` | File-based (`flydocs/issues/`) |
-| Cloud (connected) | `flydocs-cloud` | Linear GraphQL API             |
+| Cloud (connected) | `flydocs-cloud` | FlyDocs Relay API              |
 
 Read the active mechanism skill's `SKILL.md` for script catalog and calling conventions.
 
@@ -113,13 +115,13 @@ response — session summaries, issue comments, status updates, and plans.
 IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
 Consult the relevant skill BEFORE writing code or making workflow decisions.
 
-| Skill             | Triggers                                                                                                                | Entry                                     |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, Linear, cloud | .claude/skills/flydocs-cloud/SKILL.md     |
-| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                               | .claude/skills/flydocs-context7/SKILL.md  |
-| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                   | .claude/skills/flydocs-estimates/SKILL.md |
-| flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                           | .claude/skills/flydocs-figma/SKILL.md     |
-| flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                       | .claude/skills/flydocs-local/SKILL.md     |
-| flydocs-workflow  | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue             | .claude/skills/flydocs-workflow/SKILL.md  |
+| Skill             | Triggers                                                                                                                                           | Entry                                     |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, cloud                                    | .claude/skills/flydocs-cloud/SKILL.md     |
+| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                                                          | .claude/skills/flydocs-context7/SKILL.md  |
+| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                                              | .claude/skills/flydocs-estimates/SKILL.md |
+| flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                                                      | .claude/skills/flydocs-figma/SKILL.md     |
+| flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                                                  | .claude/skills/flydocs-local/SKILL.md     |
+| flydocs-workflow  | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue, knowledge, document, PR, pull request | .claude/skills/flydocs-workflow/SKILL.md  |
 
 <!-- flydocs:skills-manifest:end -->

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

@@ -301,7 +301,35 @@ 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 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/project.**
+
+> For Linear, this selects a team. For Jira, this selects a project. The relay
+> normalizes both as "teams" in the API.
 
 If `provider.teamId` in config is null, discover available teams:
 
@@ -309,10 +337,27 @@ If `provider.teamId` in config is null, discover available teams:
 python3 .claude/skills/flydocs-cloud/scripts/list_teams.py
 ```
 
-Present the teams to the user as a numbered list showing name and key. Let
-them select. If only one team exists, confirm it.
+Present the teams to the user as a numbered list showing name and key.
+Add a final option: **"Create a new team/project"**. If only one team exists,
+confirm it.
+
+If the user selects **"Create a new team/project"**:
+
+1. Ask for team name (required) and key (optional — auto-generated if omitted)
+2. **Linear only:** Ask if this should be a sub-team under an existing team
+   (show the list again for parent selection, or "None — top-level team").
+   For Jira, skip the parent option — Jira projects do not have a parent
+   hierarchy.
+3. Create via:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/create_team.py --name "Team Name" [--key KEY] [--parent <parent_team_id>]
+```
+
+> The `--parent` flag is Linear-only (sub-teams). Omit for Jira.
 
-After selection, store the preference on the relay and in local config:
+After selection or creation, store the preference on the relay and in local
+config:
 
 ```bash
 python3 .claude/skills/flydocs-cloud/scripts/set_team.py <team_id>
@@ -320,8 +365,12 @@ 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.
+For Jira, this sets the active Jira project.
 
-**Step 3: Get or create project.**
+**Step 4: Get or create project (Linear only).**
+
+> **Jira provider:** Skip this step. Jira organizes issues directly within
+> projects (selected in Step 3). There is no secondary project container.
 
 Query existing projects:
 
@@ -336,7 +385,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:
 
@@ -371,7 +420,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 `matched` (number of statuses
+successfully mapped) and `total` (total FlyDocs statuses). Show the user
+the `mapping` object:
+
+```
+Status mapping (matched 6/10):
+  BACKLOG      -> Backlog
+  READY        -> Ready
+  IMPLEMENTING -> In Progress
+  REVIEW       -> In Review
+  COMPLETE     -> Done
+  CANCELED     -> Canceled
+```
+
+If `matched < total`, 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:
 
@@ -379,14 +470,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
 
@@ -395,6 +487,7 @@ Update `.flydocs/config.json`:
 ## Phase 3: Milestones — Cloud Only
 
 > **Local tier:** Skip this phase entirely.
+> **Jira provider:** Skip this phase. Milestone support for Jira is planned for a future release.
 > **FlyDocs Update:** Skip if milestones already exist.
 
 **Step 1: Check existing milestones.**
@@ -423,11 +516,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.
@@ -455,16 +548,20 @@ 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 for
+  Linear; omit `--project` for Jira — issues are scoped to the team/project
+  selected in Phase 2 Step 3):
   ```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
 
-**Step 3: Milestone assignment (cloud only).**
+**Step 3: Milestone assignment (Linear only).**
 
 > **Local tier:** Skip this step.
+> **Jira provider:** Skip this step.
 
 After creating issues, assign them to milestones:
 
@@ -615,8 +712,8 @@ Wrapping up:
 
 **For cloud tier:**
 
-- Linear project URL (if available from create_project response)
-- Recommend reviewing milestones in Linear's UI for timeline view
+- Provider project URL (if available from create_project response)
+- For Linear: recommend reviewing milestones in Linear's UI for timeline view
 
 **For local tier:**
 
@@ -674,7 +771,7 @@ Throughout the setup flow:
   error message from stderr and ask the user how to proceed. Do not retry
   silently.
 - **Missing API key** — For cloud tier, cannot proceed past Phase 2 without
-  `LINEAR_API_KEY`. Guide the user to set it up.
+  `FLYDOCS_API_KEY`. Guide the user to set it up.
 - **Missing config** — If `.flydocs/config.json` doesn't exist, the user
   likely needs to run `flydocs` (install) first. Advise them accordingly.
 - **Partial completion** — If the user needs to stop mid-setup, note which

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/commands/knowledge.md

@@ -0,0 +1,61 @@
+# Knowledge (All Agents)
+
+Create or update a knowledge document — decisions, notes, features, or product docs.
+
+Read `flydocs/knowledge/README.md` for categories and guidance.
+Read `flydocs/knowledge/INDEX.md` for existing entries.
+
+## Procedure
+
+### 1. Determine Intent
+
+From user input or `$ARGUMENTS`, determine:
+
+- **New doc** or **update existing doc**?
+- **Category**: decision, feature, note, or product
+
+If unclear, ask the user. Default to `note` for discoveries and learnings.
+
+### 2. For New Docs
+
+1. Read the template from `flydocs/knowledge/templates/<category>.md`
+2. Gather content from the user — ask clarifying questions if context is thin
+3. Fill in the frontmatter:
+   - `title`: Descriptive, specific title
+   - `created`: Today's date (`YYYY-MM-DD`)
+   - `lastUpdated`: Today's date
+   - `relatedIssues`: Any issue IDs discussed in this session
+   - Category-specific fields (see template)
+4. Write the doc to the correct directory:
+   - Decisions: `flydocs/knowledge/decisions/NNN-title.md` (auto-increment NNN)
+   - Features: `flydocs/knowledge/features/feature-name.md`
+   - Notes: `flydocs/knowledge/notes/topic-name.md`
+   - Product: `flydocs/knowledge/product/document-name.md`
+5. Update `flydocs/knowledge/INDEX.md`:
+   - Add entry to the appropriate table
+   - Update the Quick Reference count
+   - Use a concise description (helps agents assess relevance without loading the full doc)
+
+### 3. For Existing Docs
+
+1. Find the doc in INDEX.md or by searching `flydocs/knowledge/`
+2. Read the current content
+3. Apply the update
+4. Update the `lastUpdated` field in frontmatter
+5. Update the INDEX.md entry if the description changed
+
+### 4. Confirm
+
+Report what was created or updated:
+
+- File path
+- Category and title
+- INDEX.md entry added/updated
+
+## Triggers
+
+- "document this" / "knowledge" / "add to knowledge base"
+- "create an ADR" / "record this decision" / "capture this learning"
+- "add a note about" / "document this discovery"
+
+$ARGUMENTS

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

@@ -13,7 +13,6 @@ triggers:
   - update description
   - update issue
   - project update
-  - Linear
   - cloud
 ---
 
@@ -29,49 +28,63 @@ 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 N] [--estimate N] [--assignee STR] [--project ID] [--labels "a,b"] [--milestone ID_OR_NAME] [--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> \| --unassign`                                                                                                                                                                           | `{success, issue, assignee}`                                                                                                                  |
+| `update_description.py` | `<ref> --text "..." \| --file PATH \| stdin`                                                                                                                                                               | `{success, issue}`                                                                                                                            |
 
 ### Extended Scripts
 
-| Script                | Usage                                                                                                                                                                          | Output                                                 |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
-| `update_issue.py`     | `<ref> [--title "..."] [--priority 0-4] [--estimate 1-5] [--assignee STR] [--state STATUS] [--description "..."] [--description-file PATH] [--labels "a,b"] [--comment "..."]` | `{success, issue, updated[]}`                          |
-| `estimate.py`         | `<ref> <1-5>`                                                                                                                                                                  | `{success, issue, estimate}`                           |
-| `priority.py`         | `<ref> <0-4>`                                                                                                                                                                  | `{success, issue, priority}`                           |
-| `link.py`             | `<ref> <related_ref> <type>`                                                                                                                                                   | `{success, type}`                                      |
-| `project_update.py`   | `--health STATUS --body "..." [--body-file PATH]`                                                                                                                              | `{success, id}`                                        |
-| `list_projects.py`    | `[--active] [--all]`                                                                                                                                                           | `[{id, name, state}]` — `--all` bypasses product scope |
-| `create_project.py`   | `--name "..." [--description "..."]`                                                                                                                                           | `{id, name, url}`                                      |
-| `assign_cycle.py`     | `<ref> [cycle_id]`                                                                                                                                                             | `{success, issue, cycle}`                              |
-| `list_cycles.py`      | `[--active]`                                                                                                                                                                   | `[{id, name, number, startsAt, endsAt}]`               |
-| `list_milestones.py`  | `[--all]`                                                                                                                                                                      | `[{id, name, targetDate}]`                             |
-| `create_milestone.py` | `--name "..." [--project ID] [--target-date DATE]`                                                                                                                             | `{id, name}`                                           |
-| `assign_milestone.py` | `<ref> <milestone_id>`                                                                                                                                                         | `{success, issue, milestone}`                          |
+| Script                | Usage                                                                                                                                                                                               | Output                                                                |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `update_issue.py`     | `<ref> [--title "..."] [--priority N] [--estimate N] [--assignee STR] [--state STATUS] [--description "..."] [--description-file PATH] [--labels "a,b"] [--milestone ID_OR_NAME] [--comment "..."]` | `{success, issue, updated[]}`                                         |
+| `estimate.py`         | `<ref> <points>`                                                                                                                                                                                    | `{success, issue, estimate}` — relay validates against provider scale |
+| `priority.py`         | `<ref> <0-4>`                                                                                                                                                                                       | `{success, issue, priority}`                                          |
+| `link.py`             | `<ref> <related_ref> <type>`                                                                                                                                                                        | `{success, type}`                                                     |
+| `project_update.py`   | `--health STATUS --body "..." [--body-file PATH]`                                                                                                                                                   | `{success, id}`                                                       |
+| `list_projects.py`    | `[--active] [--all]`                                                                                                                                                                                | `[{id, name, state}]` — `--all` bypasses product scope                |
+| `create_project.py`   | `--name "..." [--description "..."]`                                                                                                                                                                | `{id, name, url}`                                                     |
+| `assign_cycle.py`     | `<ref> [cycle_id]`                                                                                                                                                                                  | `{success, issue, cycle}`                                             |
+| `list_cycles.py`      | `[--active]`                                                                                                                                                                                        | `[{id, name, number, startsAt, endsAt}]`                              |
+| `list_milestones.py`  | `[--all]`                                                                                                                                                                                           | `[{id, name, targetDate}]`                                            |
+| `create_milestone.py` | `--name "..." [--project ID] [--target-date DATE]`                                                                                                                                                  | `{id, name}`                                                          |
+| `update_milestone.py` | `<milestone_id> [--name "..."] [--target-date DATE] [--description "..."]`                                                                                                                          | `{success, id, name}`                                                 |
+| `delete_milestone.py` | `<milestone_id>`                                                                                                                                                                                    | `{success, id}`                                                       |
+| `assign_milestone.py` | `<ref> <milestone_id>`                                                                                                                                                                              | `{success, issue, milestone}`                                         |
 
 ### Workspace Scripts
 
-| Script           | Usage                                                            | Output                                                                    |
-| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `list_teams.py`  | (no args)                                                        | `[{id, name, key}]`                                                       |
-| `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}]` — returns Linear teams or Jira projects (relay normalizes)                  |
+| `create_team.py`        | `--name "..." [--key KEY] [--description "..."] [--parent <team_id>]` | `{id, name, key}` — `--parent` is Linear-only (sub-teams)                                       |
+| `set_team.py`           | `<team_id>`                                                           | `{success}` — updates relay preference and local config; for Jira, sets the active Jira project |
+| `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)                                                             | `{states, currentMapping, flydocsStatuses}` — provider workflow states and current mapping      |
+| `set_status_mapping.py` | `--auto \| --mapping '{"BACKLOG":"Backlog",...}' \| stdin`            | `{success, mapping, matched, total}` — stores status mapping on relay                           |
+| `set_identity.py`       | `<provider> <provider-user-id>`                                       | `{success, provider, providerId}` — binds provider user ID for `--mine` resolution              |
+| `set_preferences.py`    | `[--workspace ID] [--assignee self\|ID] [--display JSON]`             | `{success, preferences}` — no flags = GET current; with flags = POST update                     |
+| `get_estimate_scale.py` | (no args)                                                             | `{scale, type}` — provider's valid estimate values (fixed or freeform)                          |
+| `refresh_labels.py`     | `[--fix]`                                                             | `{valid, stale, details}` — validates config label IDs against relay; `--fix` updates stale IDs |
+| `validate_setup.py`     | (no args)                                                             | `{valid, checks, missing[]}` — validates workspace config, caches result, sets setupComplete    |
 
 ### Script Notes
 
-- **How it works**: Scripts call the FlyDocs Relay REST API, which translates to the provider (Linear, Jira) server-side. Same interface and output as before — the transport changed from direct GraphQL to managed REST.
+- **How it works**: Scripts call the FlyDocs Relay REST API, which translates to the provider (Linear, Jira) server-side. Same interface and output as before — the transport changed from direct GraphQL to managed REST. For Jira, the relay handles Markdown-to-ADF (Atlassian Document Format) conversion automatically.
 - **`list_issues.py --active`**: Returns all non-terminal issues (excludes Done, Archived, Canceled, Duplicate).
 - **`list_issues.py --status`**: Accepts comma-separated statuses: `--status READY,IMPLEMENTING,BLOCKED`
 - **`get_issue.py --fields basic`**: Skips comment fetch for faster responses.
 - **`update_issue.py`**: Bulk update — sets multiple fields in a single API call. Prefer over separate scripts when updating more than one field.
+- **Estimate validation**: The relay validates estimates server-side against the provider's scale. Use `get_estimate_scale.py` to discover valid values before setting. Linear uses a fixed scale `[0, 1, 2, 3, 5, 8, 13, 21]`; Jira accepts freeform values.
+- **Label staleness**: Label IDs are team-scoped and can go stale when switching teams or projects. Use `refresh_labels.py` to validate config label IDs, and `refresh_labels.py --fix` to auto-update stale ones.
 - **Shell-safe text input**: For text with special characters, pipe via stdin with a single-quoted heredoc:
   ```bash
   python3 update_description.py ENG-123 <<'EOF'

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Assign an issue to a user via the FlyDocs Relay API."""
+"""Assign or unassign an issue via the FlyDocs Relay API."""
 
 import sys
 from pathlib import Path
@@ -7,10 +7,16 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 from flydocs_api import get_client, output_json, fail
 
-if len(sys.argv) < 3:
-    fail("Usage: assign.py <ref> <assignee>")
+if len(sys.argv) < 2:
+    fail("Usage: assign.py <ref> <assignee> | assign.py <ref> --unassign")
 
-ref, assignee = sys.argv[1], sys.argv[2]
+ref = sys.argv[1]
+unassign = "--unassign" in sys.argv
+
+if not unassign and len(sys.argv) < 3:
+    fail("Usage: assign.py <ref> <assignee> | assign.py <ref> --unassign")
+
+assignee = None if unassign else sys.argv[2]
 client = get_client()
 
 result = client.post(f"/issues/{ref}/assign", {"assignee": assignee})

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

@@ -15,10 +15,12 @@ def main():
     parser.add_argument("--type", required=True, choices=["feature", "bug", "chore", "idea"], dest="issue_type")
     parser.add_argument("--description", default="")
     parser.add_argument("--description-file", default="", dest="description_file")
-    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("--priority", type=int, default=3, help="Priority (0-4, relay translates per provider)")
+    parser.add_argument("--estimate", type=int, default=0, help="Estimate points (relay translates per provider)")
     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("--milestone", default=None, help="Milestone ID or name (resolved by name lookup)")
     parser.add_argument("--triage", action="store_true")
     args = parser.parse_args()
 
@@ -43,12 +45,30 @@ 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:
         body["triage"] = True
 
     client = get_client()
+
+    if args.milestone:
+        milestone_id = args.milestone
+        # If it doesn't look like a UUID, resolve by name
+        if len(milestone_id) != 36 or "-" not in milestone_id:
+            milestones = client.get("/milestones")
+            match = None
+            for m in milestones:
+                if m["name"].lower() == milestone_id.lower():
+                    match = m
+                    break
+            if not match:
+                fail(f"Milestone not found: {milestone_id}")
+            milestone_id = match["id"]
+        body["milestoneId"] = milestone_id
+
     result = client.post("/issues", body)
 
     output_json({

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Create a team/project via the FlyDocs Relay API."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Create team or project")
+    parser.add_argument("--name", required=True)
+    parser.add_argument("--key", default=None, help="Team key (e.g., PROD). Auto-generated if omitted.")
+    parser.add_argument("--description", default=None)
+    parser.add_argument("--parent", default=None, dest="parent_id", help="Parent team ID for sub-team (Linear only, ignored for Jira)")
+    args = parser.parse_args()
+
+    body: dict = {"name": args.name}
+    if args.key:
+        body["key"] = args.key
+    if args.description:
+        body["description"] = args.description
+    if args.parent_id:
+        body["parentId"] = args.parent_id
+
+    client = get_client()
+    result = client.post("/teams", body)
+
+    output_json({
+        "id": result["id"],
+        "name": result["name"],
+        "key": result.get("key", ""),
+    })
+
+
+if __name__ == "__main__":
+    main()