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

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/set_team.py

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
-"""Set team preference via the FlyDocs Relay API.
+"""Set team/project preference via the FlyDocs Relay API.
 
 Stores the team preference on the relay (for server-side scoping)
 and updates the local config (for display/reference).
+For Jira, this sets the active Jira project.
 """
 
 import argparse
@@ -15,8 +16,8 @@ from flydocs_api import get_client, output_json, fail
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Set team preference")
-    parser.add_argument("team_id", help="Linear team UUID")
+    parser = argparse.ArgumentParser(description="Set team or project preference")
+    parser.add_argument("team_id", help="Provider team/workspace UUID")
     args = parser.parse_args()
 
     client = get_client()
@@ -28,7 +29,7 @@ def main():
         with open(config_path, "r") as f:
             config = json.load(f)
         if "provider" not in config:
-            config["provider"] = {"type": "linear", "teamId": None}
+            config["provider"] = {"type": None, "teamId": None}
         config["provider"]["teamId"] = args.team_id
         with open(config_path, "w") as f:
             json.dump(config, f, indent=2)

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({

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Update a milestone 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, fail
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Update milestone")
+    parser.add_argument("milestone_id", help="Milestone UUID")
+    parser.add_argument("--name", default=None)
+    parser.add_argument("--target-date", default=None, dest="target_date")
+    parser.add_argument("--description", default=None)
+    args = parser.parse_args()
+
+    body: dict = {}
+    if args.name is not None:
+        body["name"] = args.name
+    if args.target_date is not None:
+        body["targetDate"] = args.target_date
+    if args.description is not None:
+        body["description"] = args.description
+
+    if not body:
+        fail("No fields to update. Use --name, --target-date, or --description")
+
+    client = get_client()
+    result = client.patch(f"/milestones/{args.milestone_id}", body)
+
+    output_json({
+        "success": result.get("success", True),
+        "id": result.get("id", args.milestone_id),
+        "name": result.get("name", args.name),
+    })
+
+
+if __name__ == "__main__":
+    main()

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

@@ -17,6 +17,10 @@ triggers:
   - transition
   - status
   - issue
+  - knowledge
+  - document
+  - PR
+  - pull request
 ---
 
 # FlyDocs Workflow
@@ -35,32 +39,33 @@ Capture → Refine → Activate → Implement → Review → Validate → Close
 
 ## Stage Index
 
-| Stage | File | Intent | Agent |
-|-------|------|--------|-------|
-| Capture | stages/capture.md | Create issue from input | PM |
-| Refine | stages/refine.md | Triage + spec completion | PM |
-| Activate | stages/activate.md | Assign + start work | PM |
-| Implement | stages/implement.md | Build + test + simplify | Implementation |
-| Review | stages/review.md | Code quality validation | Review |
-| Validate | stages/validate.md | User acceptance testing | QE |
-| Close | stages/close.md | Archive completed work | PM |
+| Stage     | File                | Intent                   | Agent          |
+| --------- | ------------------- | ------------------------ | -------------- |
+| Capture   | stages/capture.md   | Create issue from input  | PM             |
+| Refine    | stages/refine.md    | Triage + spec completion | PM             |
+| Activate  | stages/activate.md  | Assign + start work      | PM             |
+| Implement | stages/implement.md | Build + test + simplify  | Implementation |
+| Review    | stages/review.md    | Code quality validation  | Review         |
+| Validate  | stages/validate.md  | User acceptance testing  | QE             |
+| Close     | stages/close.md     | Archive completed work   | PM             |
 
 ## Session
 
-| Action | File |
-|--------|------|
-| Start session | session.md |
-| Wrap session | session.md |
+| Action          | File       |
+| --------------- | ---------- |
+| Start session   | session.md |
+| Wrap session    | session.md |
 | Stale detection | session.md |
 
 ## Reference
 
-| Topic | File |
-|-------|------|
-| Comment templates | reference/comment-templates.md |
-| Status transitions | reference/status-workflow.md |
+| Topic                | File                            |
+| -------------------- | ------------------------------- |
+| Comment templates    | reference/comment-templates.md  |
+| Status transitions   | reference/status-workflow.md    |
 | Priority & estimates | reference/priority-estimates.md |
-| Golden rules | reference/golden-rules.md |
+| PR & git workflow    | reference/pr-workflow.md        |
+| Golden rules         | reference/golden-rules.md       |
 
 ## Templates
 

package/template/.claude/skills/flydocs-workflow/reference/comment-templates.md

@@ -56,6 +56,7 @@ Canonical templates for all workflow transitions. Copy exactly, fill bracketed v
 **Files:** [count] modified
 **Testing:** [How it was verified]
 **Criteria:** [X]/[Y] complete
+**PR:** [link or "direct commit"]
 ```
 
 ## Code Review Passed

package/template/.claude/skills/flydocs-workflow/reference/pr-workflow.md

@@ -0,0 +1,105 @@
+# PR & Git Workflow
+
+## Branch Naming
+
+Format: `<type>/<ref>-<slug>`
+
+| Type      | When                                   |
+| --------- | -------------------------------------- |
+| `feature` | New functionality                      |
+| `fix`     | Bug fixes                              |
+| `chore`   | Maintenance, refactoring, dependencies |
+| `docs`    | Documentation only                     |
+
+Examples:
+
+- `feature/FLY-255-knowledge-capture`
+- `fix/FLY-301-login-timeout`
+- `chore/FLY-290-upgrade-deps`
+
+Keep the slug short (2-4 words, kebab-case). Include the issue reference.
+
+## Commit Messages
+
+Format: `<type>: <description> (<ref>)`
+
+- Lead with what changed, not how
+- Use imperative mood ("Add", not "Added")
+- Keep the first line under 72 characters
+- Add a body for non-obvious changes
+
+Examples:
+
+```
+feat: Add knowledge doc templates and /knowledge command (FLY-255)
+fix: Handle null milestone in create_issue response (FLY-301)
+chore: Remove deprecated auth middleware (FLY-290)
+```
+
+## When to Create a PR
+
+**Create a PR when:**
+
+- Changes affect shared code (not just local config or docs)
+- Multiple files changed across different concerns
+- Changes need review before merging
+- Working on a branch (not committing directly to main)
+
+**Commit directly when:**
+
+- Single-file documentation updates
+- Config changes for local development
+- Trivial fixes (typos, formatting)
+- The user explicitly requests direct commit
+
+When in doubt, create a PR. It's easier to merge a PR than to revert a direct commit.
+
+## PR Description Template
+
+```markdown
+## Summary
+
+[1-3 bullet points describing what changed and why]
+
+Closes [ISSUE-REF]
+
+## Changes
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+
+## Test Plan
+
+- [ ] [How to verify change 1]
+- [ ] [How to verify change 2]
+
+## Notes
+
+[Anything reviewers should know — tradeoffs, follow-up work, decisions made]
+```
+
+## PR Workflow in Practice
+
+### During Implement Stage
+
+After self-review (step 7 in `implement.md`), before handing off to review:
+
+1. Create branch: `git checkout -b <type>/<ref>-<slug>`
+2. Stage and commit changes with a descriptive message
+3. Push branch: `git push -u origin <branch>`
+4. Create PR with the template above, linking the issue
+5. Include the PR link in the "Ready for Review" comment
+
+### During Review Stage
+
+The reviewer should:
+
+- Review the PR diff (not just local git diff)
+- Leave comments on the PR for specific code feedback
+- Reference the PR in review comments on the issue
+
+### After Review
+
+- **Approved**: Merge the PR, then transition issue to Testing
+- **Changes needed**: Push fixes to the same branch, re-request review

package/template/.claude/skills/flydocs-workflow/reference/priority-estimates.md

@@ -2,27 +2,49 @@
 
 ## Priority Values
 
-| Value | Name | Use When |
-|-------|------|----------|
-| 0 | None | Not yet triaged |
-| 1 | Urgent | Drop everything, fix now |
-| 2 | High | Next up, unblocks others |
-| 3 | Medium | Normal priority (default) |
-| 4 | Low | Nice to have |
+| Value | Name   | Use When                  |
+| ----- | ------ | ------------------------- |
+| 0     | None   | Not yet triaged           |
+| 1     | Urgent | Drop everything, fix now  |
+| 2     | High   | Next up, unblocks others  |
+| 3     | Medium | Normal priority (default) |
+| 4     | Low    | Nice to have              |
 
 ## Estimate Values (Complexity)
 
-| Value | Name | Rough Effort |
-|-------|------|--------------|
-| 1 | XS | < 1 hour |
-| 2 | S | 1-4 hours |
-| 3 | M | Half day to full day |
-| 4 | L | 2-3 days |
-| 5 | XL | Week+ |
+| Value | Name | Rough Effort         |
+| ----- | ---- | -------------------- |
+| 1     | XS   | < 1 hour             |
+| 2     | S    | 1-4 hours            |
+| 3     | M    | Half day to full day |
+| 4     | L    | 2-3 days             |
+| 5     | XL   | Week+                |
 
 ## Guidance
 
 - Set priority during Refine or Activate stages
 - Set estimate during Refine stage (before Ready)
 - If estimate is missing at Activate, set it before transitioning
-- XL estimates often indicate the issue should be broken into smaller pieces
+- Estimate values may vary by provider — the relay translates per provider configuration
+
+## Decomposition
+
+When an estimate is large (XL / 5+ or provider equivalent), prompt for decomposition:
+
+1. **Identify natural boundaries** — separate concerns, independent deliverables, sequential phases
+2. **Create child issues** — each should be independently estimable at M or smaller
+3. **Link parent to children** — use `link.py` with type `blocks` (parent blocks children conceptually)
+4. **Re-estimate parent** — set to 0 or remove estimate, since children carry the work
+5. **Move parent to a tracking role** — it becomes the "epic" or summary issue
+
+**Split pattern:**
+
+```
+Original: FLY-100 "Build auth system" (XL)
+  → FLY-101 "Add login endpoint" (S)
+  → FLY-102 "Add session management" (M)
+  → FLY-103 "Add role-based access control" (M)
+  → FLY-104 "Add password reset flow" (S)
+```
+
+Don't force decomposition on every large issue — some are genuinely large and atomic. Use judgment. The prompt is: "This is estimated as XL. Can it be broken into smaller, independently deliverable pieces?"

package/template/.claude/skills/flydocs-workflow/session.md

@@ -52,6 +52,7 @@ When a conversation begins or the user returns after a gap:
 
 7. **Surface other product issues briefly** — If there are issues in the product scope
    but outside the active project, mention the count with a one-line summary:
+
    ```
    Also in [Product Name]: [N] issues across other projects (use --all to see)
    ```
@@ -69,10 +70,16 @@ automatically via the config cascade.
 When the user indicates they're done for the session:
 
 1. **Gather session data** — What was completed, what's in progress, what's blocked.
-2. **Compose summary** using the template below.
-3. **Determine health status** — See health table.
-4. **Post project update** — `project_update.py` with health and summary body.
-5. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
+2. **Knowledge capture check** — Review the session's work for uncaptured knowledge:
+   - Were any architectural decisions made?
+   - Were any non-obvious behaviors or workarounds discovered?
+   - Were any patterns established that future work should follow?
+   - Did debugging reveal something worth documenting?
+     If yes, prompt the user: "This session involved [specific discovery]. Should we capture it in a knowledge doc before wrapping?" Use `/knowledge` if they agree.
+3. **Compose summary** using the template below.
+4. **Determine health status** — See health table.
+5. **Post project update** — `project_update.py` with health and summary body.
+6. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
    ```
    python3 .claude/skills/flydocs-context-graph/scripts/graph_session.py \
        --summary "Brief summary of session outcomes" \
@@ -80,8 +87,8 @@ When the user indicates they're done for the session:
        [--decision NNN]
    ```
    This creates a session node for cross-session continuity. Skip silently if the script is not installed.
-6. **Verify** — Confirm the project update was posted (update ID returned).
-7. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
+7. **Verify** — Confirm the project update was posted (update ID returned).
+8. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
 
 Do not just summarize in chat. Actually post the update. Do not skip if the user seems in a hurry.
 
@@ -104,15 +111,16 @@ Do not just summarize in chat. Actually post the update. Do not skip if the user
 
 ### Health Status
 
-| Status | When to Use |
-|--------|-------------|
-| onTrack | Progress made, no blockers |
-| atRisk | Minor delays, attention needed |
+| Status   | When to Use                     |
+| -------- | ------------------------------- |
+| onTrack  | Progress made, no blockers      |
+| atRisk   | Minor delays, attention needed  |
 | offTrack | Major blockers, behind schedule |
 
 ### Wrap Detection Phrases
 
 Offer session wrap when the user says:
+
 - "I'm done for today" / "wrapping up" / "that's it for now"
 - "save progress" / "end of day" / "stopping here"
 
@@ -120,9 +128,9 @@ Offer session wrap when the user says:
 
 Proactively surface issues that may be stuck:
 
-| State | Threshold | Action |
-|-------|-----------|--------|
-| Implementing | > 7 days without activity | Warn |
-| Review | > 3 days without activity | Warn |
-| Testing/QA | > 3 days without activity | Warn |
-| Blocked | Any | Always surface |
+| State        | Threshold                 | Action         |
+| ------------ | ------------------------- | -------------- |
+| Implementing | > 7 days without activity | Warn           |
+| Review       | > 3 days without activity | Warn           |
+| Testing/QA   | > 3 days without activity | Warn           |
+| Blocked      | Any                       | Always surface |

package/template/.claude/skills/flydocs-workflow/stages/capture.md

@@ -21,9 +21,14 @@ When the user has enough context to describe the issue:
    - **Why** — User story or business value
    - **How** — Technical notes or approach (if known)
    - **Done when** — Acceptance criteria as checkboxes
-4. **Create issue** — `create_issue.py` with title, type, description, priority, and estimate (if known).
-5. **Add comment** — Use the Capture template from `reference/comment-templates.md`.
-6. **Verify** — Confirm issue identifier returned.
+4. **Apply labels** — Include appropriate labels from config:
+   - **Category label**: Automatic from issue type (feature, bug, chore, idea) via `issueLabels.category` in config
+   - **Repo label**: If multi-repo workspace, apply the repo label from `issueLabels.repo` in config
+   - **Product labels**: Applied automatically by the mechanism scripts from `workspace.product.labelIds`
+   - **Ad-hoc labels**: Only if explicitly relevant (e.g., "accessibility", "performance")
+5. **Create issue** — `create_issue.py` with title, type, description, priority, estimate (if known), and labels.
+6. **Add comment** — Use the Capture template from `reference/comment-templates.md`.
+7. **Verify** — Confirm issue identifier returned.
 
 ### Quick Capture
 

package/template/.claude/skills/flydocs-workflow/stages/close.md

@@ -11,12 +11,13 @@ Archive verified and completed work.
 ## Steps
 
 1. **Verify QE approval** — Check issue comments for a "QE Approved" comment. If not found, do not close — direct to Validate stage first.
-2. **Determine terminal state:**
+2. **Final knowledge check** — If the issue involved significant implementation, verify `knowledge/INDEX.md` reflects any decisions or discoveries. This is informational — don't block close, but prompt the user if notable knowledge appears uncaptured.
+3. **Determine terminal state:**
    - **Done** — Work completed and verified (normal path)
    - **Archived** — Deferring to a later date (not cancelled, may return)
    - **Canceled** — Not pursuing (won't be done)
-3. **Transition** — `transition.py` with the appropriate Close comment from `reference/comment-templates.md`.
-4. **Verify** — Confirm terminal state reached.
+4. **Transition** — `transition.py` with the appropriate Close comment from `reference/comment-templates.md`.
+5. **Verify** — Confirm terminal state reached.
 
 ## Gates