@flydocs/cli 0.5.0-beta.9 → 0.6.0-alpha.10

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

@@ -0,0 +1,342 @@
+# FlyDocs Upgrade — Local to Cloud Migration (PM/Planning Agent)
+
+AI-guided migration from local tier to cloud tier. Handles API connection,
+issue migration, and local content disposition in a single guided flow.
+
+Read the active mechanism skill's `SKILL.md` for script calling conventions
+before executing any scripts.
+
+Triggers: "upgrade to cloud", "migrate to cloud", "local to cloud", "flydocs upgrade"
+
+---
+
+## IMPORTANT: Use Plan Mode
+
+**Before executing any migration steps, enter plan mode.** This migration
+involves multiple phases with irreversible actions. Planning first ensures
+the user understands what will happen:
+
+1. Run pre-flight checks (Phase 0) to inventory the current state
+2. Present a migration summary with issue counts and what each phase does
+3. Get user approval before making any changes
+
+Only exit plan mode and begin execution after the user approves the plan.
+
+---
+
+## Phase 0: Pre-flight Checks
+
+Before starting, verify the project is eligible for migration.
+
+**Step 1: Read config and verify tier.**
+
+Read `.flydocs/config.json` and check the `tier` field.
+
+- If `tier` is `cloud`: abort with message:
+  ```
+  This project is already on the cloud tier. No migration needed.
+  Run /flydocs-setup to configure your cloud workspace.
+  ```
+- If `tier` is not `local`: abort with error about unexpected tier value.
+
+**Step 2: Inventory local issues.**
+
+Scan `flydocs/issues/` for all issue files across status directories:
+
+```
+flydocs/issues/backlog/*.md
+flydocs/issues/ready/*.md
+flydocs/issues/implementing/*.md
+flydocs/issues/review/*.md
+flydocs/issues/validating/*.md
+flydocs/issues/done/*.md
+flydocs/issues/closed/*.md
+```
+
+For each issue file found, read the YAML frontmatter to extract:
+
+- Title
+- Type (feature, bug, chore, idea)
+- Priority
+- Status (from parent directory name)
+- Any comments in the body
+
+Count totals by status and type.
+
+**Step 3: Check for API readiness.**
+
+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.**
+
+```
+Migration Summary
+─────────────────
+Current tier: local
+Target tier: cloud
+
+Local issues found: [N total]
+  - Backlog: [n]
+  - Ready: [n]
+  - Implementing: [n]
+  - Review: [n]
+  - Done: [n]
+
+Migration will:
+  1. Connect to cloud provider (Linear) via flydocs connect
+  2. Create [N] issues in Linear with matching status
+  3. Archive, delete, or keep local issue files (your choice)
+
+API key: [set / not set — will be needed in Phase 1]
+
+Ready to proceed?
+```
+
+Confirm with the user before continuing.
+
+---
+
+## Phase 1: Connect to Cloud
+
+Guide the user through connecting to the cloud provider. This swaps the
+tier, stores the API key, and prepares the cloud mechanism skill.
+
+**Step 1: Get API key.**
+
+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:
+
+```
+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
+```
+
+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 the swap, verify:
+
+1. Read `.flydocs/config.json` — `tier` should now be `cloud`
+2. Check that `.claude/skills/flydocs-cloud/scripts/` exists
+3. Run a test command to verify the connection:
+   ```bash
+   python3 .claude/skills/flydocs-cloud/scripts/list_issues.py --limit 1
+   ```
+
+If any check fails, help the user troubleshoot before proceeding.
+
+---
+
+## Phase 2: Issue Migration
+
+Migrate local issues to the cloud provider. After `flydocs connect` swaps
+the mechanism skill, the local scripts are gone — read issue files directly.
+
+**IMPORTANT:** The local mechanism scripts are no longer available after
+Phase 1. Read the markdown files directly from `flydocs/issues/`.
+
+**Step 1: Read local issue files.**
+
+For each issue file in `flydocs/issues/{status}/*.md`, parse:
+
+- **YAML frontmatter** — between `---` markers at the top of the file.
+  Fields: `title`, `type`, `priority`, `estimate`, `created`, `assigned`.
+- **Body** — everything after the frontmatter closing `---`.
+  This is the issue description in markdown.
+- **Comments** — look for `## Comments` section in the body.
+  Each comment has a timestamp header and content.
+- **Status** — derived from the parent directory name. Map to cloud status:
+  - `backlog` -> `BACKLOG`
+  - `ready` -> `READY`
+  - `implementing` -> `IMPLEMENTING`
+  - `review` -> `REVIEW`
+  - `validating` -> `VALIDATING`
+  - `done` -> `DONE`
+  - `closed` -> `CLOSED`
+
+**Step 2: Create issues in cloud.**
+
+For each local issue, create it in the cloud provider. Read the cloud
+mechanism skill's `SKILL.md` first for exact calling conventions.
+
+For issues with long descriptions, write the description body to a temp file
+and use `--description-file`:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/create_issue.py \
+  --title "Issue title" \
+  --type feature \
+  --priority 3 \
+  --estimate 2 \
+  --description-file /tmp/flydocs-migrate-desc.md
+```
+
+If the issue had comments in its local file, append them to the description
+body under a `## Migration Notes` section:
+
+```markdown
+## Migration Notes
+
+Migrated from local tier on YYYY-MM-DD.
+
+### Previous Comments
+
+**YYYY-MM-DD HH:MM** — [comment content]
+```
+
+**Step 3: Transition non-backlog issues.**
+
+Issues created via `create_issue.py` start in BACKLOG status. For issues
+that were in other statuses locally, transition them to match:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/transition.py \
+  <new-issue-ref> <TARGET_STATUS> \
+  --comment "Migrated from local tier — original status was [status]"
+```
+
+Status transitions must follow the workflow — you may need intermediate
+transitions for some statuses. Read
+`.claude/skills/flydocs-workflow/reference/status-workflow.md` for valid
+transitions.
+
+**Step 4: Track the mapping.**
+
+Maintain and display an old-to-new ID mapping as issues are migrated:
+
+```
+Migration Progress
+──────────────────
+[1/N] local-1 "Setup auth" -> FLY-234 (BACKLOG)
+[2/N] local-2 "Fix header" -> FLY-235 (IMPLEMENTING)
+[3/N] local-3 "Add tests"  -> FLY-236 (READY)
+...
+```
+
+**Step 5: Handle failures.**
+
+If any issue fails to create or transition:
+
+- Log the error with the local issue reference
+- Continue with remaining issues (don't abort the whole migration)
+- Report all failures at the end with suggestions for manual resolution
+
+---
+
+## Phase 3: Content Disposition
+
+After migration, handle the local issue files. Present three options
+(same pattern as the uninstall command):
+
+```
+All [N] issues have been migrated to Linear.
+
+What would you like to do with the local issue files?
+
+1. Archive — Rename flydocs/issues/ to flydocs/issues-archive/
+   (keeps files as read-only reference)
+
+2. Delete — Remove flydocs/issues/ and .flydocs/issues.counter
+   (clean slate, issues live in Linear now)
+
+3. Keep — Leave files as-is
+   (local files remain alongside cloud issues)
+```
+
+Execute the user's choice:
+
+- **Archive**: Rename `flydocs/issues/` to `flydocs/issues-archive/`
+- **Delete**: Remove `flydocs/issues/` directory and `.flydocs/issues.counter` file
+- **Keep**: No action needed
+
+---
+
+## Phase 4: Completion
+
+Summarize the migration and provide next steps.
+
+**Step 1: Migration summary.**
+
+```
+Migration Complete
+──────────────────
+Tier: local -> cloud
+Issues migrated: [N] ([success] succeeded, [fail] failed)
+Local files: [archived / deleted / kept]
+
+ID Mapping:
+  local-1 -> FLY-234
+  local-2 -> FLY-235
+  ...
+```
+
+**Step 2: Next steps.**
+
+```
+Next steps:
+  1. Run /flydocs-setup to configure milestones and labels
+  2. Review migrated issues in Linear
+  3. Start working with /start-session
+```
+
+**Step 3: Commit prompt.**
+
+Offer to commit the configuration changes:
+
+```
+The tier change and skill swap modified several files.
+Want to commit these changes?
+```
+
+If the user agrees, create a commit with message:
+`Upgrade FlyDocs from local to cloud tier`
+
+Stage: `.flydocs/config.json`, `.claude/skills/`, `.claude/CLAUDE.md`,
+`.cursor/rules/`, and any archive/deletion changes.
+
+---
+
+## Error Handling
+
+- **Already cloud tier** — Abort in Phase 0 with helpful message.
+- **Zero local issues** — Skip Phase 2 entirely, proceed to Phase 4.
+- **flydocs connect fails** — Help troubleshoot; do not proceed to Phase 2.
+- **Partial migration failure** — Report which issues succeeded and which
+  failed. Offer to retry failed issues or proceed with what succeeded.
+- **Cancel mid-migration** — Report current state: which issues were already
+  created in cloud, which local files remain. The user can re-run to
+  continue (Phase 0 will re-inventory remaining local issues).
+
+---
+
+## Key Rules
+
+1. **Always read the cloud mechanism skill's `SKILL.md`** before running
+   scripts in Phase 2. Calling conventions may have changed.
+2. **Never delete local files without explicit user consent** in Phase 3.
+3. **After `flydocs connect`, local scripts are gone.** Read issue files
+   directly — do not attempt to call `flydocs-local` scripts.
+4. **Status transitions must follow the workflow.** Read the status workflow
+   reference for valid transition paths.
+5. **Report progress continuously.** Show the mapping table after each
+   issue is migrated so the user can follow along.
+
+$ARGUMENTS

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

@@ -1,8 +1,9 @@
 ---
 name: flydocs-cloud
 description: |
-  Connected issue management via Linear GraphQL API.
-  Implements the FlyDocs mechanism contract with extended cloud-only operations.
+  Connected issue management via FlyDocs Relay API.
+  Implements the FlyDocs mechanism contract with extended cloud operations.
+  All provider translation (Linear, Jira) happens server-side.
 triggers:
   - create issue
   - transition
@@ -12,13 +13,14 @@ triggers:
   - update description
   - update issue
   - project update
-  - Linear
   - cloud
 ---
 
 # FlyDocs Cloud Mechanism
 
-Issues managed in Linear. Reads config from `.flydocs/config.json` and API key from `.env`.
+Issues managed via the FlyDocs Relay API. The relay handles provider translation server-side — scripts are thin REST wrappers.
+
+Reads config from `.flydocs/config.json` and API key (`FLYDOCS_API_KEY`) from `.env`.
 
 ## Script Catalog
 
@@ -26,42 +28,64 @@ 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] [--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 (cloud-only)
-
-| Script | Usage | Output |
-|--------|-------|--------|
-| `update_issue.py` | `<ref> [--title "..."] [--priority 0-4] [--estimate 1-5] [--assignee STR] [--state STATUS] [--description "..."] [--description-file PATH] [--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}` — defaults to first activeProject |
-| `assign_milestone.py` | `<ref> <milestone_id>` | `{success, issue, milestone}` |
+| 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 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_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
 
-- **`list_issues.py` product scope**: Automatically scopes results using config cascade — `activeProjects` → `product.labelIds` → team-wide. Explicit `--project` overrides. All flags (`--active`, `--status`, `--mine`, `--assignee`) filter within the scoped results.
-- **`list_issues.py --active`**: Returns all non-terminal issues (excludes Done, Archived, Canceled, Duplicate). Replaces `status_summary.py` — group results by status field instead.
-- **`list_issues.py --milestone`**: Filter issues by project milestone ID. Get IDs from `list_milestones.py`.
+- **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 when comments aren't needed.
-- **`update_issue.py`**: Bulk update — sets multiple fields in a single API call. Prefer over separate `estimate.py`/`priority.py`/`assign.py` calls when updating more than one field.
-- **Shell-safe text input**: For descriptions, comments, or any text with special characters (apostrophes, quotes, parentheses), pipe via stdin with a single-quoted heredoc instead of `--text`:
+- **`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'
   Description with 'apostrophes', (parens), and "quotes"
@@ -83,14 +107,17 @@ All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
 
 ### Issue Reference
 
-`<ref>`: Provider identifier, e.g., `ENG-123`. Resolved via Linear search API.
+`<ref>`: Provider identifier, e.g., `ENG-123`. Resolved server-side by the relay.
 
 ## Error Handling
 
 Exit 0 = success (JSON on stdout). Exit 1 = error (message on stderr).
 Network errors: exponential backoff, 3 retries, 2s base delay.
+Relay errors include `code` and optional `provider_error` for debugging.
 
 ## Configuration
 
-Reads from `.flydocs/config.json`: tier, provider.teamId, statusMapping, issueLabels.
-Reads `LINEAR_API_KEY` from environment or `.env` / `.env.local`.
+Reads from `.flydocs/config.json`: tier, relay URL override.
+Reads `FLYDOCS_API_KEY` from environment or `.env` / `.env.local`.
+
+Optional: `FLYDOCS_RELAY_URL` env var or `relay.url` in config to override the base URL (e.g., for local development).

package/template/.claude/skills/flydocs-cloud/cursor-rule.mdc

@@ -1,5 +1,5 @@
 ---
-description: Connected issue management via Linear — cloud mechanism for FlyDocs
+description: Connected issue management via FlyDocs Relay API — cloud mechanism for FlyDocs
 alwaysApply: true
 ---
 
@@ -7,7 +7,7 @@ alwaysApply: true
 
 # FlyDocs Cloud Mechanism
 
-Issues managed in Linear. Reads config from `.flydocs/config.json` and API key from `.env`.
+Issues managed via FlyDocs Relay API. Reads config from `.flydocs/config.json` and API key (`FLYDOCS_API_KEY`) from `.env`.
 
 ## Shared Contract Scripts
 
@@ -23,7 +23,7 @@ All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
 | `assign.py` | `<ref> <assignee>` |
 | `update_description.py` | `<ref> --text "..." \| --file PATH` |
 
-## Extended Scripts (cloud-only)
+## Extended Scripts
 
 | Script | Key Arguments |
 |--------|---------------|
@@ -46,5 +46,5 @@ Network errors: exponential backoff, 3 retries, 2s base delay.
 
 ## Configuration
 
-Reads from `.flydocs/config.json`: tier, provider.teamId, statusMapping, issueLabels.
-Reads `LINEAR_API_KEY` from environment or `.env` / `.env.local`.
+Reads from `.flydocs/config.json`: tier, relay URL override.
+Reads `FLYDOCS_API_KEY` from environment or `.env` / `.env.local`.

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Assign an issue to a person."""
+"""Assign or unassign an issue via the FlyDocs Relay API."""
 
 import sys
 from pathlib import Path
@@ -7,32 +7,22 @@ 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_query = 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()
 
-issue_uuid = client.resolve_issue_id(ref)
-if not issue_uuid:
-    fail(f"Issue not found: {ref}")
-
-user_id, user_name = client.resolve_user_id(assignee_query)
-if not user_id:
-    fail(f"User not found: {assignee_query}")
-
-result = client.query(
-    """mutation($id: String!, $assigneeId: String!) {
-        issueUpdate(id: $id, input: { assigneeId: $assigneeId }) {
-            success
-            issue { identifier }
-        }
-    }""",
-    {"id": issue_uuid, "assigneeId": user_id},
-)
-
-if not result.get("data", {}).get("issueUpdate", {}).get("success"):
-    fail(f"Failed to assign: {result}")
-
-issue = result["data"]["issueUpdate"]["issue"]
-output_json({"success": True, "issue": issue["identifier"], "assignee": user_name})
+result = client.post(f"/issues/{ref}/assign", {"assignee": assignee})
+
+output_json({
+    "success": result.get("success", True),
+    "issue": result.get("issue", ref),
+    "assignee": result.get("assignee", assignee),
+})