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

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

@@ -4,23 +4,37 @@
 
 When a conversation begins or the user returns after a gap:
 
-1. **Fetch all product issues in one call** — Run `list_issues.py --active --limit 100`.
+1. **Query graph for issue context** (if an issue ID is known from the prompt or last session) —
+
+   ```
+   python3 .claude/skills/flydocs-workflow/scripts/graph_query.py --node <issue-id> --depth 2
+   ```
+
+   This surfaces related decisions, blocking relationships, and recent session activity.
+   Skip silently if the script is not installed or the graph has not been built.
+
+2. **Check workspace context** — If `flydocs/context/service.json` exists, note the
+   repo's topology and dependencies. For multi-repo workspaces (topology type 3 or 4),
+   briefly mention which sibling repos exist and any active cross-repo dependencies.
+   This helps the user orient when switching between repos.
+
+3. **Fetch all product issues in one call** — Run `issues.py list --active --limit 100`.
    This is auto-scoped by the product cascade: `activeProjects` → `product.labelIds` → team-wide.
    Issues outside the product scope are never shown.
 
-2. **Identify the active project** — Read `workspace.activeProjects` from config.
+4. **Identify the active project** — Read `workspace.activeProjects` from config.
    Separate issues into two buckets:
    - **Active project issues** — issues whose `projectId` matches an active project
    - **Other product issues** — issues in the product scope but in a different project
 
-3. **Group active project issues by milestone** — Use the `milestone` and `milestoneSortOrder`
+5. **Group active project issues by milestone** — Use the `milestone` and `milestoneSortOrder`
    fields returned by the script. Sort milestones by `milestoneSortOrder` (lowest first = earliest).
    Within each milestone, group by status.
 
-4. **Identify the current milestone** — The first milestone (by sort order) that still has
+6. **Identify the current milestone** — The first milestone (by sort order) that still has
    open issues. This is where work should focus.
 
-5. **Present the dashboard:**
+7. **Present the dashboard:**
 
    ```
    Welcome back! [Product Name] status:
@@ -43,20 +57,21 @@ When a conversation begins or the user returns after a gap:
    Suggested starting point: [ISSUE-ID] — [reason: highest priority in current milestone / unblocks others / due soon]
    ```
 
-6. **Suggest where to start** — Use this priority cascade:
+8. **Suggest where to start** — Use this priority cascade:
    - Blocked issues that need unblocking (always surface first)
    - In-progress issues (continue existing work)
    - Due date approaching (within 7 days)
    - Highest priority in the current milestone
    - Issues that unblock downstream milestones
 
-7. **Surface other product issues briefly** — If there are issues in the product scope
+9. **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)
    ```
 
-8. **Check for stale issues** — Flag issues exceeding staleness thresholds (see below).
+10. **Check for stale issues** — Flag issues exceeding staleness thresholds (see below).
 
 **Important:** Do NOT make separate API calls per status or per milestone. One call returns
 all issues with their status and milestone fields — group them in your response.
@@ -69,19 +84,41 @@ 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** — `session.py project-update` with health and summary body.
+6. **Write last-summary.json** — Write `.flydocs/session/last-summary.json` for cross-session continuity.
+   Create the directory if it doesn't exist. Structure:
+
+   ```json
+   {
+     "timestamp": "ISO-8601 (e.g. 2026-03-20T17:30:00Z)",
+     "issues": ["FLY-XXX", "FLY-YYY"],
+     "pending": ["description of incomplete work"],
+     "blockers": ["any blockers, or empty array"],
+     "notes": "free-form session summary"
+   }
    ```
-   python3 .claude/skills/flydocs-context-graph/scripts/graph_session.py \
+
+   Populate from the session data gathered in step 1. Use the Write tool or a script — the file
+   must exist on disk so the prompt hook can read it on the next session start.
+
+7. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
+   ```
+   python3 .claude/skills/flydocs-workflow/scripts/graph_session.py \
        --summary "Brief summary of session outcomes" \
        --issue ISSUE-ID [--issue ISSUE-ID2] \
        [--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.
+8. **Verify** — Confirm the project update was posted (update ID returned).
+9. **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 +141,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 +158,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/activate.md

@@ -15,7 +15,7 @@ Assign work to a person and move the issue to In Progress.
 
 When user asks "what should I work on?":
 
-1. **Query available issues** — `list_issues.py` for Ready and Backlog states.
+1. **Query available issues** — `issues.py list` for Ready and Backlog states.
 2. **Filter** — Exclude blocked issues and issues assigned to others.
 3. **Rank** — Priority (highest first) → unblocked → smaller estimate.
 4. **Present recommendation** — Show top candidates with reasoning.
@@ -23,12 +23,23 @@ When user asks "what should I work on?":
 
 ### Activation (specific issue)
 
-1. **Read full issue** — Load description and acceptance criteria.
-2. **Determine assignee** — MANDATORY. Ask "Who should this be assigned to?" if unclear. This is a hard gate.
-3. **Assign** — `assign.py` with user identifier. If assignment fails, STOP. Do not continue.
-4. **Set metadata** — Priority and estimate if not already set.
-5. **Transition** — `transition.py` to Implementing with Activate comment from `reference/comment-templates.md`.
-6. **Verify** — Confirm state = In Progress and assignee set.
+1. **Query graph for blocking relationships** — Check for blockers before proceeding:
+   ```
+   python3 .claude/skills/flydocs-workflow/scripts/graph_query.py --node <issue-id> --relationships BLOCKS,BLOCKED_BY
+   ```
+   If blocking relationships exist, surface them to the user before continuing.
+   Skip silently if the script is not installed or the graph has not been built.
+2. **Check cross-repo impact** — If `flydocs/context/service.json` exists and the issue
+   description references API changes, endpoint modifications, or interface updates,
+   check if the affected APIs appear in the descriptor's `apis` section. If so, note
+   which sibling repos may be affected (they CONSUME this interface). This is a
+   heads-up, not a gate — just surface it for awareness.
+3. **Read full issue** — Load description and acceptance criteria.
+4. **Determine assignee** — MANDATORY. Ask "Who should this be assigned to?" if unclear. This is a hard gate.
+5. **Assign** — `issues.py assign` with user identifier. If assignment fails, STOP. Do not continue.
+6. **Set metadata** — Priority and estimate if not already set.
+7. **Transition** — `issues.py transition` to Implementing with Activate comment from `reference/comment-templates.md`.
+8. **Verify** — Confirm state = In Progress and assignee set.
 
 **Sequence matters:** Assign → metadata → transition. Never transition without an assignee.
 

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

@@ -16,21 +16,26 @@ When the user has enough context to describe the issue:
 
 1. **Determine type** — feature, bug, chore, or idea. Ask if unclear.
 2. **Select project** — Single active project: use it. Multiple: ask user. None: error.
-3. **Fill template** — Read the appropriate template from `templates/`. Extract from user input:
+3. **Fill template** — Read the appropriate template from `templates/issues/`. Extract from user input:
    - **What** — Context or problem description
    - **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 workflow scripts from `workspace.product.labelIds`
+   - **Ad-hoc labels**: Only if explicitly relevant (e.g., "accessibility", "performance")
+5. **Create issue** — `issues.py create` 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
 
 When logging an idea or observation during flow — flesh out later:
 
 1. **Determine type** — Default to `idea` if unclear.
-2. **Create issue** — `create_issue.py --triage` with minimal title and brief context.
+2. **Create issue** — `issues.py create --triage` with minimal title and brief context.
    Issue receives both the category label and the triage label.
 3. **Add comment** — "**Captured** — Quick capture, needs refinement."
 4. Issue sits in Backlog with triage tag. The Refine stage picks it up later.

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** — `issues.py transition` with the appropriate Close comment from `reference/comment-templates.md`.
+5. **Verify** — Confirm terminal state reached.
 
 ## Gates
 

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

@@ -20,6 +20,7 @@ Build, test, simplify, and hand off to code review.
 ### 2. Show Implementation Checklist
 
 Present to the user:
+
 - Issue ID and title
 - All acceptance criteria
 - Estimate
@@ -46,17 +47,28 @@ Rationale: [Why this choice over alternatives]
 
 For significant architectural decisions, also create a record in `knowledge/decisions/`.
 
-### 5. TODO to Issue
+### 5. Knowledge Capture Check
+
+Before moving to self-review, check if any of these occurred during implementation:
+
+- **Architectural decision** — framework choice, pattern established, approach rejected
+- **Discovery** — API quirk, debugging technique, non-obvious behavior
+- **Workaround** — limitation found, temporary fix applied
+- **Pattern** — reusable approach that future work should follow
+
+If yes, prompt the user: "Should we capture this in a knowledge doc?" Use `/knowledge` to create the doc, or note it for session wrap if the user wants to defer.
+
+### 6. TODO to Issue
 
 When adding a TODO comment in code:
 
 1. Write the initial comment: `// TODO: Description`
-2. Create a corresponding issue via `create_issue.py` with type `chore`
+2. Create a corresponding issue via `issues.py create` with type `chore`
 3. Update the comment with the issue ID: `// TODO: Description (ENG-XXX)`
 
 Every TODO must have a tracked issue. No orphaned TODOs.
 
-### 6. Simplify
+### 7. Simplify
 
 After implementation is functionally complete, review modified files for:
 
@@ -67,7 +79,7 @@ After implementation is functionally complete, review modified files for:
 
 Apply standards from installed community skills and `preferences.md`. Preserve all functionality.
 
-### 7. Self-Review
+### 8. Self-Review
 
 Before handing off:
 
@@ -77,23 +89,35 @@ Before handing off:
 - [ ] No obvious security issues
 - [ ] No orphaned TODOs
 
-### 8. Hand Off to Review
+### 9. Create PR (if applicable)
+
+See `reference/pr-workflow.md` for full conventions. If changes warrant a PR:
+
+1. Create branch: `git checkout -b <type>/<ref>-<slug>`
+2. Stage and commit with a descriptive message: `<type>: <description> (<ref>)`
+3. Push: `git push -u origin <branch>`
+4. Create PR: `python3 .claude/skills/flydocs-workflow/scripts/issues.py pr --issue <ref>`
+
+The PR dispatcher auto-populates the description from the issue context and links the PR back via comment. If the user requested a direct commit or changes are trivial, skip the PR and commit directly.
+
+### 10. Hand Off to Review
 
-Transition to Review via `transition.py` with the "Ready for Review" comment from `reference/comment-templates.md`. Include:
+Transition to Review via `issues.py transition` with the "Ready for Review" comment from `reference/comment-templates.md`. Include:
 
 - What changed (brief summary)
 - File count
 - How it was tested
 - Criteria completion count
+- PR link (if PR was created)
 
 ## Checkbox Protocol
 
 Checkboxes live in the issue description. Never in comments.
 
-1. Read current description via `get_issue.py`
+1. Read current description via `issues.py get`
 2. Find `- [ ] Criterion text`
 3. Change to `- [x] Criterion text`
-4. Save entire updated description via `update_description.py`
+4. Save entire updated description via `issues.py description`
 
 **Never** put completion checkmarks in comments. **Never** create new checkboxes in comments.
 
@@ -102,7 +126,7 @@ Checkboxes live in the issue description. Never in comments.
 If blocked during implementation:
 
 1. Document what is blocking and what is needed
-2. Transition via `transition.py` to Blocked with comment from `reference/comment-templates.md`
+2. Transition via `issues.py transition` to Blocked with comment from `reference/comment-templates.md`
 3. If blocked by another issue, create a dependency relationship
 
 To unblock: transition back to Implementing with an Unblocked comment.

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

@@ -16,9 +16,9 @@ For quick captures that need classification and structure:
 
 1. **Read issue** — Load current content.
 2. **Classify type** — Determine category (feature/bug/chore/idea). Ask if unclear.
-3. **Apply template** — Read appropriate template from `templates/` and restructure the issue content to match.
+3. **Apply template** — Read appropriate template from `templates/issues/` and restructure the issue content to match.
 4. **Set priority** — P1-P4 based on urgency and impact.
-5. **Update description** — `update_description.py` with templated content.
+5. **Update description** — `issues.py description` with templated content.
 6. **Add comment** — Use Triage template from `reference/comment-templates.md`.
 
 ### Refinement Path (issue already templated)
@@ -32,14 +32,30 @@ For backlog items that need fleshing out before activation:
 5. **Add technical notes** — Implementation guidance, dependencies, affected areas.
 6. **Set estimate and priority** — If not already set. See `reference/priority-estimates.md`.
 7. **Check dependencies** — Blocked by other issues? Related work?
-8. **Update description** — `update_description.py` with refined content.
-9. **Transition to Ready** — `transition.py` with Refine comment from `reference/comment-templates.md`.
+8. **Assign milestone** — If the issue fits a current or upcoming milestone, assign it via `--milestone` on `issues.py update`. If no milestone is appropriate, leave unassigned but note it.
+9. **Update description** — `issues.py description` with refined content.
+10. **Quality gate check** — Verify all criteria pass before transitioning:
+
+| Gate                | Check                                            | Required |
+| ------------------- | ------------------------------------------------ | -------- |
+| Description         | Context section filled, not just a title         | Yes      |
+| Acceptance criteria | Specific, testable, written as checkboxes        | Yes      |
+| Estimate            | Set (see `reference/priority-estimates.md`)      | Yes      |
+| Priority            | Set (P1-P4)                                      | Yes      |
+| Labels              | Category label applied, repo label if multi-repo | Yes      |
+| Dependencies        | Identified and documented, or explicitly "none"  | Yes      |
+| Milestone           | Assigned if applicable                           | No       |
+
+If any required gate fails, address it before transitioning.
+
+11. **Transition to Ready** — `issues.py transition` with Refine comment from `reference/comment-templates.md`.
 
 ## Gates
 
+- All quality gate checks pass (see table above)
 - Acceptance criteria defined (specific, testable, as checkboxes)
-- Estimate set (1-5)
-- Priority set (1-4)
+- Estimate set
+- Priority set (P1-P4)
 
 ## Outputs
 

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

@@ -16,7 +16,8 @@ Validate code quality, standards compliance, and acceptance criteria completion.
 - Issue description (acceptance criteria)
 - Implementation summary comment (what was built)
 - Installed community skills relevant to the code (check `.claude/skills/` for available patterns)
-- Changed files (from git diff or implementation notes)
+- Changed files — prefer PR diff if a PR exists, otherwise git diff or implementation notes
+- `reference/pr-workflow.md` for branch and commit conventions
 
 ### 2. Verify Acceptance Criteria
 
@@ -47,25 +48,36 @@ Check against project standards and installed community skills:
 - Tests are meaningful (not just coverage)
 - Edge cases considered
 
-### 5. Decision
+### 5. Knowledge Verification
+
+If the issue template includes a Documentation section with "Knowledge base updated" checkbox:
+
+- Verify knowledge doc was created or updated (check `knowledge/INDEX.md` for new entries)
+- If the checkbox is unchecked and implementation involved significant decisions or discoveries, flag it
+
+This is a soft gate — not all issues require knowledge docs. Flag only when implementation clearly warrants documentation that wasn't captured.
+
+### 6. Decision
 
 **If approved:**
 
-1. Transition to Testing via `transition.py` with "Code Review Passed" comment from `reference/comment-templates.md`.
+1. Transition to Testing via `issues.py transition` with "Code Review Passed" comment from `reference/comment-templates.md`.
 
 **If changes needed:**
 
 1. Document specific issues with file/location details.
-2. Transition to Implementing via `transition.py` with "Code Review: Changes Needed" comment listing each issue.
+2. Transition to Implementing via `issues.py transition` with "Code Review: Changes Needed" comment listing each issue.
 
 ## Review Boundaries
 
 The review agent:
+
 - Analyzes code quality and documents findings
 - Validates against standards and criteria
 - Transitions issue state
 
 The review agent does NOT:
+
 - Edit or write code
 - Fix issues directly
 - Approve incomplete work

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

@@ -47,7 +47,7 @@ Please test each criterion and let me know:
 **On issues found:**
 
 1. Document issues clearly. Ask clarifying questions if needed.
-2. Transition to Implementing via `transition.py` with "QE Issues Found" comment listing each issue.
+2. Transition to Implementing via `issues.py transition` with "QE Issues Found" comment listing each issue.
 
 **On partial issues:**
 
@@ -65,11 +65,13 @@ Please test each criterion and let me know:
 ## QE Boundaries
 
 The QE agent:
+
 - Guides user through testing
 - Documents approval or issues
 - Transitions back to Implementing if issues found
 
 The QE agent NEVER:
+
 - Moves issues to Done or closes them
 - Skips documenting results
 - Approves without user confirmation

package/template/.claude/skills/flydocs-workflow/templates/pr/default.md

@@ -0,0 +1,33 @@
+## Summary
+
+<!-- What changed and why. Reference the issue. -->
+
+Resolves {ISSUE_REF}
+
+{ISSUE_SUMMARY}
+
+## Changes
+
+<!-- Key changes, grouped logically. -->
+
+- {CHANGE_1}
+- {CHANGE_2}
+
+## Test Plan
+
+<!-- How to verify this works. Be specific. -->
+
+- [ ] {TEST_1}
+- [ ] {TEST_2}
+
+## Acceptance Criteria
+
+<!-- Pulled from issue description. -->
+
+{ACCEPTANCE_CRITERIA}
+
+## Notes
+
+<!-- Anything reviewers should know: trade-offs, follow-up work, risks. -->
+
+{NOTES}

package/template/.cursor/agents/implementation-agent.md

@@ -20,7 +20,7 @@ Implementation agent for FlyDocs spec-driven development.
 
 ## Constraints
 
-- **Scripts for issue updates** — use mechanism scripts for progress comments and transitions
+- **Scripts for issue updates** — use workflow dispatcher scripts for progress comments and transitions
 - Follow installed community skills for code quality patterns
 - Keep changes focused on the spec — don't over-engineer
 

package/template/.cursor/agents/pm-agent.md

@@ -2,7 +2,7 @@
 name: pm-agent
 description: "Specs, workflow, issue management. Invoke for capturing, refining, activating, reviewing, closing, or session management."
 model: inherit
-readonly: false
+readonly: true
 is_background: false
 ---
 
@@ -20,7 +20,7 @@ Product management agent for FlyDocs spec-driven workflow.
 ## Constraints
 
 - **Do not modify code files** — this agent handles workflow, not implementation
-- **Scripts for all issue ops** — read the mechanism skill's SKILL.md for calling conventions
+- **Scripts for all issue ops** — use workflow dispatcher scripts (`issues.py`, `projects.py`, etc.) for all operations
 - Defer technical decisions to implementation agent
 
 Read `.claude/skills/flydocs-workflow/SKILL.md` for lifecycle and stage procedures.

package/template/.cursor/hooks.json

@@ -4,19 +4,26 @@
     "preToolUse": [
       {
         "matcher": "Bash",
-        "command": "python3 ./.flydocs/hooks/auto-approve.py",
+        "command": "python3 ./.claude/hooks/auto-approve.py",
         "timeout": 5
       }
     ],
     "afterFileEdit": [
       {
-        "command": "python3 ./.flydocs/hooks/post-edit.py",
+        "command": "python3 ./.claude/hooks/post-edit.py",
         "timeout": 30
       }
     ],
+    "afterToolUse": [
+      {
+        "matcher": "Bash",
+        "command": "python3 ./.claude/hooks/post-pr-check.py",
+        "timeout": 10
+      }
+    ],
     "beforeSubmitPrompt": [
       {
-        "command": "python3 ./.flydocs/hooks/prompt-submit.py",
+        "command": "python3 ./.claude/hooks/prompt-submit.py",
         "timeout": 10
       }
     ]

package/template/.env.example

@@ -31,18 +31,18 @@
 FLYDOCS_API_KEY=
 
 # ===========================================
-# CLOUD TIER: Direct Linear API Key (Legacy)
+# CLOUD TIER: Direct Provider API Key (Legacy)
 # ===========================================
-# Use this ONLY if connecting directly to Linear without the relay.
-# Get from: Linear → Settings → API → Personal API Keys
-# Format: lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-LINEAR_API_KEY=
+# Use this ONLY if connecting directly to your provider without the relay.
+# For Linear: Get from Linear → Settings → API → Personal API Keys (format: lin_api_...)
+# For Jira: Get from Atlassian → API Tokens (format: ATATT...)
+# LINEAR_API_KEY=
 
 # ===========================================
 # OPTIONAL: Figma Access Token
 # ===========================================
 # Get from: Figma → Settings → Personal Access Tokens
-# Only needed if using the flydocs-figma skill for design integration
+# Only needed if using Figma design integration
 FIGMA_ACCESS_TOKEN=
 
 # ===========================================

package/template/.flydocs/config.json

@@ -1,18 +1,17 @@
 {
-  "version": "0.6.0-alpha.2",
+  "version": "0.6.0-alpha.21",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,
+  "onboardComplete": false,
+  "workspaceId": null,
   "paths": {
     "content": "flydocs"
   },
-  "provider": {
-    "type": null,
-    "teamId": null
-  },
   "workspace": {
     "activeProjects": [],
     "defaultMilestoneId": null,
+    "repoSlug": null,
     "product": {
       "name": null,
       "labelIds": [],
@@ -21,7 +20,7 @@
     }
   },
   "issueLabels": {
-    "_note": "Run /flydocs-setup to populate these from your Linear team",
+    "_note": "Run /flydocs-setup to populate these from your workspace",
     "category": {
       "feature": null,
       "bug": null,
@@ -50,18 +49,6 @@
     "installed": [],
     "custom": []
   },
-  "statusMapping": {
-    "BACKLOG": "Backlog",
-    "READY": "Todo",
-    "IMPLEMENTING": "In Progress",
-    "BLOCKED": "Blocked",
-    "REVIEW": "In Review",
-    "TESTING": "QA",
-    "COMPLETE": "Done",
-    "ARCHIVED": "Archived",
-    "CANCELED": "Canceled",
-    "DUPLICATE": "Duplicate"
-  },
   "designSystem": null,
   "aiLabor": {
     "enabled": false,