@flydocs/cli 0.6.0-alpha.5 → 0.6.0-alpha.7

package/dist/cli.js

@@ -15,7 +15,7 @@ var CLI_VERSION, CLI_NAME, PACKAGE_NAME, POSTHOG_API_KEY;
 var init_constants = __esm({
   "src/lib/constants.ts"() {
     "use strict";
-    CLI_VERSION = "0.6.0-alpha.5";
+    CLI_VERSION = "0.6.0-alpha.7";
     CLI_NAME = "flydocs";
     PACKAGE_NAME = "@flydocs/cli";
     POSTHOG_API_KEY = "phc_v1MSJTQDFkMS90CBh3mxIz3v8bYCCnKU6v1ir6bz0Xn";
@@ -50,6 +50,7 @@ async function ensureDirectories(targetDir, tier) {
     "flydocs/knowledge/decisions",
     "flydocs/knowledge/notes",
     "flydocs/knowledge/product",
+    "flydocs/knowledge/templates",
     "flydocs/design-system"
   ];
   if (tier === "local") {
@@ -2357,6 +2358,45 @@ var init_install = __esm({
             ),
             label: "flydocs/knowledge/product/user-flows.md"
           },
+          {
+            src: join15(
+              templateDir,
+              "flydocs",
+              "knowledge",
+              "templates",
+              "decision.md"
+            ),
+            dest: join15(
+              targetDir,
+              "flydocs",
+              "knowledge",
+              "templates",
+              "decision.md"
+            ),
+            label: "flydocs/knowledge/templates/decision.md"
+          },
+          {
+            src: join15(
+              templateDir,
+              "flydocs",
+              "knowledge",
+              "templates",
+              "feature.md"
+            ),
+            dest: join15(
+              targetDir,
+              "flydocs",
+              "knowledge",
+              "templates",
+              "feature.md"
+            ),
+            label: "flydocs/knowledge/templates/feature.md"
+          },
+          {
+            src: join15(templateDir, "flydocs", "knowledge", "templates", "note.md"),
+            dest: join15(targetDir, "flydocs", "knowledge", "templates", "note.md"),
+            label: "flydocs/knowledge/templates/note.md"
+          },
           {
             src: join15(templateDir, "flydocs", "design-system", "README.md"),
             dest: join15(targetDir, "flydocs", "design-system", "README.md"),
@@ -2911,6 +2951,22 @@ var init_update = __esm({
           await copyFile(envExampleSrc, join16(targetDir, ".env.example"));
           printStatus(".env.example");
         }
+        const knowledgeTemplatesDir = join16(
+          targetDir,
+          "flydocs",
+          "knowledge",
+          "templates"
+        );
+        if (!await pathExists(knowledgeTemplatesDir)) {
+          await mkdir8(knowledgeTemplatesDir, { recursive: true });
+        }
+        for (const tmpl of ["decision.md", "feature.md", "note.md"]) {
+          const src = join16(templateDir, "flydocs", "knowledge", "templates", tmpl);
+          const dest = join16(knowledgeTemplatesDir, tmpl);
+          if (await pathExists(src) && !await pathExists(dest)) {
+            await copyFile(src, dest);
+          }
+        }
         await runManifestGeneration(targetDir);
         await runContextGraphBuild(targetDir);
         console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.6.0-alpha.5",
+  "version": "0.6.0-alpha.7",
   "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` |
@@ -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, 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/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

@@ -28,32 +28,34 @@ 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] [--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}`                                                                                                                            |
+| 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>`                                                                                                                                                                                         | `{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
 
@@ -68,6 +70,10 @@ All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
 | `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 |
 
 ### Script Notes
 
@@ -76,6 +82,8 @@ All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
 - **`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/create_issue.py

@@ -15,11 +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()
 
@@ -52,6 +53,22 @@ def main():
         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/delete_milestone.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Delete a milestone 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, fail
+
+if len(sys.argv) < 2:
+    fail("Usage: delete_milestone.py <milestone_id>")
+
+milestone_id = sys.argv[1]
+
+client = get_client()
+result = client.delete(f"/milestones/{milestone_id}")
+
+output_json({
+    "success": result.get("success", True),
+    "id": result.get("id", milestone_id),
+})

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

@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
-"""Set estimate on an issue via the FlyDocs Relay API."""
+"""Set estimate on an issue via the FlyDocs Relay API.
+
+The relay validates the estimate against the provider's scale server-side.
+Use get_estimate_scale.py to discover valid values before setting.
+"""
 
 import sys
 from pathlib import Path
@@ -8,16 +12,16 @@ sys.path.insert(0, str(Path(__file__).parent))
 from flydocs_api import get_client, output_json, fail
 
 if len(sys.argv) < 3:
-    fail("Usage: estimate.py <ref> <1-5>")
+    fail("Usage: estimate.py <ref> <points>")
 
 ref = sys.argv[1]
 try:
     estimate = int(sys.argv[2])
 except ValueError:
-    fail("Estimate must be a number (1-5)")
+    fail("Estimate must be a number")
 
-if estimate not in (1, 2, 3, 5):
-    fail("Estimate must be 1 (XS), 2 (S), 3 (M), or 5 (L)")
+if estimate < 0:
+    fail("Estimate must be a non-negative integer")
 
 client = get_client()
 result = client.put(f"/issues/{ref}/estimate", {"estimate": estimate})

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

@@ -160,6 +160,10 @@ class FlyDocsClient:
         """PATCH request to relay API."""
         return self._request("PATCH", path, body=body)
 
+    def delete(self, path: str) -> dict:
+        """DELETE request to relay API."""
+        return self._request("DELETE", path)
+
     def _log_operation(self, method: str, path: str, status: int, result: dict | list):
         """Log operation metadata to local log file."""
         try:

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

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""Get the provider's estimate scale via the FlyDocs Relay API.
+
+Returns the valid estimate values for the connected provider.
+Linear: fixed scale [0, 1, 2, 3, 5, 8, 13, 21]
+Jira: freeform (any positive number)
+"""
+
+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/estimates")
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Refresh label config from the relay — validates and updates local config.
+
+Fetches current team labels from the relay, compares against local config,
+and reports any stale or missing label IDs. With --fix, updates local config
+to match the relay's current state.
+"""
+
+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():
+    fix_mode = "--fix" in sys.argv
+
+    client = get_client()
+
+    # Fetch current labels from relay
+    labels = client.get("/labels")
+    label_map = {l["id"]: l["name"] for l in labels}
+    label_by_name = {l["name"].lower(): l["id"] for l in labels}
+
+    # Load local config
+    config_path = client.config_path
+    if not config_path.exists():
+        fail("No .flydocs/config.json found")
+
+    with open(config_path, "r") as f:
+        config = json.load(f)
+
+    issue_labels = config.get("issueLabels", {})
+    stale: list[dict] = []
+    valid: list[dict] = []
+
+    # Check each label ID in config against relay
+    for category, entries in issue_labels.items():
+        if isinstance(entries, dict):
+            for key, label_id in entries.items():
+                if label_id in label_map:
+                    valid.append({"category": category, "key": key, "id": label_id, "name": label_map[label_id]})
+                else:
+                    # Try to find by key name
+                    resolved = label_by_name.get(key.lower())
+                    stale.append({
+                        "category": category,
+                        "key": key,
+                        "staleId": label_id,
+                        "resolvedId": resolved,
+                        "resolvedName": key if resolved else None,
+                    })
+
+    if fix_mode and stale:
+        # Update stale IDs in config
+        fixed = 0
+        for item in stale:
+            if item["resolvedId"]:
+                issue_labels[item["category"]][item["key"]] = item["resolvedId"]
+                fixed += 1
+
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+        output_json({
+            "success": True,
+            "valid": len(valid),
+            "stale": len(stale),
+            "fixed": fixed,
+            "unfixable": len(stale) - fixed,
+            "details": stale,
+        })
+    else:
+        output_json({
+            "valid": len(valid),
+            "stale": len(stale),
+            "totalProviderLabels": len(labels),
+            "details": stale if stale else "All label IDs are current",
+            "hint": "Run with --fix to update stale IDs" if stale else None,
+        })
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Set provider identity via the FlyDocs Relay API.
+
+Binds the user's provider-specific ID to their FlyDocs user record.
+Once set, ?mine=true resolves via exact provider ID matching.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+VALID_PROVIDERS = ("linear", "jira", "gitlab")
+
+if len(sys.argv) < 3:
+    fail(f"Usage: set_identity.py <provider> <provider-user-id>\n  Providers: {', '.join(VALID_PROVIDERS)}")
+
+provider = sys.argv[1].lower()
+provider_id = sys.argv[2]
+
+if provider not in VALID_PROVIDERS:
+    fail(f"Invalid provider: {provider}. Must be one of: {', '.join(VALID_PROVIDERS)}")
+
+if not provider_id:
+    fail("Provider user ID cannot be empty")
+
+client = get_client()
+result = client.post("/auth/identity", {
+    "provider": provider,
+    "providerId": provider_id,
+})
+
+output_json({
+    "success": result.get("success", True),
+    "provider": result.get("provider", provider),
+    "providerId": result.get("providerId", provider_id),
+})

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

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Get or set user preferences via the FlyDocs Relay API.
+
+With no arguments, returns current preferences (GET).
+With flags, updates preferences (POST).
+"""
+
+import argparse
+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="Get or set user preferences")
+    parser.add_argument("--workspace", default=None, help="Default workspace ID")
+    parser.add_argument("--assignee", default=None, help="Default assignee ('self' or user ID)")
+    parser.add_argument("--display", default=None, help="Display preferences (JSON string)")
+    args = parser.parse_args()
+
+    client = get_client()
+
+    # If no flags provided, GET current preferences
+    if args.workspace is None and args.assignee is None and args.display is None:
+        result = client.get("/auth/preferences")
+        output_json(result)
+        return
+
+    # Build update body from provided flags
+    body: dict = {}
+    if args.workspace is not None:
+        body["defaultWorkspaceId"] = args.workspace
+    if args.assignee is not None:
+        body["defaultAssignee"] = args.assignee
+    if args.display is not None:
+        body["displayPreferences"] = args.display
+
+    result = client.post("/auth/preferences", body)
+
+    output_json({
+        "success": result.get("success", True),
+        "preferences": result.get("preferences", body),
+    })
+
+
+if __name__ == "__main__":
+    main()

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

@@ -13,13 +13,14 @@ def main():
     parser = argparse.ArgumentParser(description="Update issue fields")
     parser.add_argument("ref", help="Issue reference (e.g., ENG-123)")
     parser.add_argument("--title", default=None)
-    parser.add_argument("--priority", type=int, choices=range(5))
-    parser.add_argument("--estimate", type=int, choices=range(1, 6))
+    parser.add_argument("--priority", type=int, help="Priority (0-4, relay translates per provider)")
+    parser.add_argument("--estimate", type=int, help="Estimate points (relay translates per provider)")
     parser.add_argument("--assignee", default=None)
     parser.add_argument("--state", default=None)
     parser.add_argument("--description", default=None)
     parser.add_argument("--description-file", default=None)
     parser.add_argument("--labels", default=None, help="Comma-separated label names")
+    parser.add_argument("--milestone", default=None, help="Milestone ID or name (resolved by name lookup)")
     parser.add_argument("--comment", default=None)
     args = parser.parse_args()
 
@@ -65,10 +66,27 @@ def main():
         body["comment"] = args.comment
         updated_fields.append("comment")
 
-    if not body:
-        fail("No fields to update. Use --title, --priority, --estimate, --assignee, --state, --description, --labels, or --comment")
+    if not body and args.milestone is None:
+        fail("No fields to update. Use --title, --priority, --estimate, --assignee, --state, --description, --labels, --milestone, or --comment")
 
     client = get_client()
+
+    if args.milestone is not None:
+        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
+        updated_fields.append("milestone")
+
     result = client.patch(f"/issues/{args.ref}", body)
 
     output_json({