@flydocs/cli 0.6.0-alpha.13 → 0.6.0-alpha.20

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

@@ -7,29 +7,34 @@ When a conversation begins or the user returns after a gap:
 1. **Query graph for issue context** (if an issue ID is known from the prompt or last session) —
 
    ```
-   python3 .claude/skills/flydocs-context-graph/scripts/graph_query.py --node <issue-id> --depth 2
+   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. **Fetch all product issues in one call** — Run `list_issues.py --active --limit 100`.
+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.
 
-3. **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
 
-4. **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.
 
-5. **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.
 
-6. **Present the dashboard:**
+7. **Present the dashboard:**
 
    ```
    Welcome back! [Product Name] status:
@@ -52,21 +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]
    ```
 
-7. **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
 
-8. **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)
    ```
 
-9. **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.
@@ -87,7 +92,7 @@ When the user indicates they're done for the session:
      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.
+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:
 
@@ -106,7 +111,7 @@ When the user indicates they're done for the session:
 
 7. **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 \
+   python3 .claude/skills/flydocs-workflow/scripts/graph_session.py \
        --summary "Brief summary of session outcomes" \
        --issue ISSUE-ID [--issue ISSUE-ID2] \
        [--decision NNN]

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.
@@ -25,16 +25,21 @@ When user asks "what should I work on?":
 
 1. **Query graph for blocking relationships** — Check for blockers before proceeding:
    ```
-   python3 .claude/skills/flydocs-context-graph/scripts/graph_query.py --node <issue-id> --relationships BLOCKS,BLOCKED_BY
+   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. **Read full issue** — Load description and acceptance criteria.
-3. **Determine assignee** — MANDATORY. Ask "Who should this be assigned to?" if unclear. This is a hard gate.
-4. **Assign** — `assign.py` with user identifier. If assignment fails, STOP. Do not continue.
-5. **Set metadata** — Priority and estimate if not already set.
-6. **Transition** — `transition.py` to Implementing with Activate comment from `reference/comment-templates.md`.
-7. **Verify** — Confirm state = In Progress and assignee set.
+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,7 +16,7 @@ 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)
@@ -24,9 +24,9 @@ When the user has enough context to describe the issue:
 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`
+   - **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** — `create_issue.py` with title, type, description, priority, estimate (if known), and labels.
+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.
 
@@ -35,7 +35,7 @@ When the user has enough context to describe the issue:
 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

@@ -16,7 +16,7 @@ Archive verified and completed work.
    - **Done** — Work completed and verified (normal path)
    - **Archived** — Deferring to a later date (not cancelled, may return)
    - **Canceled** — Not pursuing (won't be done)
-4. **Transition** — `transition.py` with the appropriate Close comment from `reference/comment-templates.md`.
+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

@@ -63,7 +63,7 @@ If yes, prompt the user: "Should we capture this in a knowledge doc?" Use `/know
 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.
@@ -96,13 +96,13 @@ 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 linking the issue, using the PR description template
+4. Create PR: `python3 .claude/skills/flydocs-workflow/scripts/issues.py pr --issue <ref>`
 
-If the user requested a direct commit or changes are trivial, skip the PR and commit directly.
+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
@@ -114,10 +114,10 @@ Transition to Review via `transition.py` with the "Ready for Review" comment fro
 
 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.
 
@@ -126,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,8 +32,8 @@ 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. **Assign milestone** — If the issue fits a current or upcoming milestone, assign it via `--milestone` on `update_issue.py`. If no milestone is appropriate, leave unassigned but note it.
-9. **Update description** — `update_description.py` with refined content.
+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 |
@@ -48,7 +48,7 @@ For backlog items that need fleshing out before activation:
 
 If any required gate fails, address it before transitioning.
 
-11. **Transition to Ready** — `transition.py` with Refine comment from `reference/comment-templates.md`.
+11. **Transition to Ready** — `issues.py transition` with Refine comment from `reference/comment-templates.md`.
 
 ## Gates
 

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

@@ -61,12 +61,12 @@ This is a soft gate — not all issues require knowledge docs. Flag only when im
 
 **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
 

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,8 +1,9 @@
 {
-  "version": "0.6.0-alpha.13",
+  "version": "0.6.0-alpha.20",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,
+  "onboardComplete": false,
   "workspaceId": null,
   "paths": {
     "content": "flydocs"

package/template/.flydocs/templates/README.md

@@ -1,31 +1,33 @@
 # Issue Templates
 
-This folder contains templates for creating and refining Linear issues. Each template includes agent instructions to ensure consistent, high-quality issue structure.
+This folder contains templates for creating and refining issues. Each template includes agent instructions to ensure consistent, high-quality issue structure.
 
 ## Template Usage
 
 **Agents use these templates when:**
+
 - Creating new issues via `/capture`
 - Refining issues via `/refine`
 - Triaging quick captures with `triage` label
 
-**Humans use `quick-capture.md` in Linear** as the default template for fast idea/bug capture.
+**Humans use `quick-capture.md` in their issue tracker** as the default template for fast idea/bug capture.
 
 ## Available Templates
 
-| Template | Purpose | When to Use |
-|----------|---------|-------------|
-| `feature.md` | New functionality | Building something new with user story |
-| `bug.md` | Fix defects | Something is broken |
-| `chore.md` | Maintenance/cleanup | Refactoring, polish, improvements |
-| `idea.md` | Capture concepts | Rough ideas for future exploration |
-| `quick-capture.md` | Fast capture | Human entry in Linear (default template) |
+| Template           | Purpose             | When to Use                                     |
+| ------------------ | ------------------- | ----------------------------------------------- |
+| `feature.md`       | New functionality   | Building something new with user story          |
+| `bug.md`           | Fix defects         | Something is broken                             |
+| `chore.md`         | Maintenance/cleanup | Refactoring, polish, improvements               |
+| `idea.md`          | Capture concepts    | Rough ideas for future exploration              |
+| `quick-capture.md` | Fast capture        | Human entry in issue tracker (default template) |
 
 ## Agent Instructions
 
-Each template contains `<!-- AGENT: ... -->` comments that guide the AI when filling out sections. These instructions are removed from the final issue in Linear.
+Each template contains `<!-- AGENT: ... -->` comments that guide the AI when filling out sections. These instructions are removed from the final issue in your provider.
 
 **Key principles:**
+
 1. Fill all `[bracketed]` sections with specific content
 2. Don't remove sections - mark as "N/A" if not applicable
 3. Be specific in acceptance criteria (testable, measurable)
@@ -35,12 +37,9 @@ Each template contains `<!-- AGENT: ... -->` comments that guide the AI when fil
 ## Template Evolution
 
 Update these templates as your workflow evolves:
+
 - Add sections that are consistently needed
 - Remove sections that are never used
 - Improve agent instructions based on what works
 
 Changes here apply to all future issues.
-
-
-
-

package/template/.flydocs/templates/quick-capture.md

@@ -1,8 +1,8 @@
-<!-- 
-LINEAR DEFAULT TEMPLATE
+<!--
+PROVIDER DEFAULT TEMPLATE
 ========================
-Copy this to Linear as the default issue template.
-This is the ONLY template humans need in Linear.
+Copy this to your issue tracker as the default issue template.
+This is the ONLY template humans need in their issue tracker.
 Agents apply full templates via /refine.
 -->
 
@@ -29,7 +29,3 @@ Agents apply full templates via /refine.
 ---
 
 _Add `triage` label. Agent will classify and structure via `/refine`._
-
-
-
-

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.13
+0.6.0-alpha.20

package/template/AGENTS.md

@@ -1,17 +1,24 @@
 # FlyDocs Agent Instructions
 
-Prefer reading project documentation over guessing from training data.
-When performing workflow, issue management, or process tasks, consult the
-relevant documentation files before acting.
+## Automatic Workflow Behavior
 
-## Rules
+These behaviors are **always on**. Execute them automatically as part of doing
+the work — do not wait for explicit commands.
 
-1. **Use scripts for all issue operations.** Create, transition, comment, assign — execute scripts, don't describe actions.
-2. **Every status transition gets a comment.** No silent moves.
-3. **Assignment required before In Progress.** Always assign before starting work.
-4. **Checkboxes live in issue description, never comments.** Update the description to track progress.
-5. **Session wrap posts a summary.** Summarize progress at end of session.
-6. **No secrets in commits.** Never commit `.env`, credentials, or API keys.
+- **Starting work on an issue** → transition to In Progress (assign first if needed)
+- **Completing implementation** → transition to Review with summary
+- **Closing** → verify acceptance criteria, transition to Complete
+- **Every transition gets a comment** — no silent moves, no exceptions
+- **Checkboxes in description, never comments** — update AC as you go
+- **Session wrap posts a summary** via `session.py project-update`
+
+Use dispatcher scripts for all issue operations — execute, don't describe.
+
+## Efficiency
+
+Do NOT read skill files or workflow documentation before writing code.
+The rules above are already in your context. For general coding, research,
+and building features — just do the work.
 
 ## Workflow
 
@@ -37,16 +44,20 @@ Detailed procedures: `.claude/skills/flydocs-workflow/`
 
 Scripts handle all issue management. The active backend (local files or cloud provider) determines the implementation.
 
-**Available operations:** create issue, transition status, add comment, list issues, get issue details, assign, update description, status summary.
+**Available operations:** create issue, transition status, add comment, list issues, get issue details, assign, update description, estimate, priority, link, block, project update, status summary.
 
-Script location: `.claude/skills/flydocs-local/scripts/` or `.claude/skills/flydocs-cloud/scripts/`
+Scripts use grouped dispatchers in `.claude/skills/flydocs-workflow/scripts/`:
 
-## Premium Skills
+| Dispatcher       | Operations                                                   |
+| ---------------- | ------------------------------------------------------------ |
+| `issues.py`      | create, get, list, transition, assign, update, comment, etc. |
+| `projects.py`    | list-projects, create-project, milestones, cycles            |
+| `workspace.py`   | validate, labels, statuses, teams, config, identity          |
+| `session.py`     | project-update, status-summary                               |
+| `graph_*.py`     | build, query, update, session recording                      |
+| `push/pull_*.py` | Service descriptor sync (cloud tier)                         |
 
-| Skill             | Documentation                                                           |
-| ----------------- | ----------------------------------------------------------------------- |
-| Figma Integration | `.claude/skills/flydocs-figma/` — design extraction, token mapping      |
-| Cost Estimation   | `.claude/skills/flydocs-estimates/` — AI token/labor estimates (opt-in) |
+The unified client auto-detects tier (cloud vs local) — scripts never check tier directly.
 
 ## Writing Style
 
@@ -80,26 +91,22 @@ Follow these rules in every response for consistent, scannable output.
 
 ## Project Context
 
-| File                         | Purpose                                                 |
-| ---------------------------- | ------------------------------------------------------- |
-| `flydocs/context/project.md` | Product scope, tech stack, active priorities            |
-| `.flydocs/config.json`       | Configuration — tier, provider, labels, active projects |
+| File                           | Purpose                                           |
+| ------------------------------ | ------------------------------------------------- |
+| `flydocs/context/project.md`   | Product scope, tech stack, active priorities      |
+| `flydocs/context/service.json` | Service descriptor, topology, cross-repo context  |
+| `.flydocs/config.json`         | Tier, provider, labels, active projects, topology |
 
 <!-- flydocs:skills-manifest:start -->
 
 ## Skills Index
 
-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, knowledge, document, PR, pull request | .claude/skills/flydocs-workflow/SKILL.md  |
+Consult the workflow skill for **issue operations and status transitions only**.
+For general coding tasks, skip this — just write code.
+
+| Skill            | Triggers                                                                                                                                                                                                                         | Entry                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| flydocs-workflow | create issue, capture issue, log a bug, add to backlog, transition, move to, mark as, set status, assign issue, close issue, start session, wrap session, project update, status update, add comment, set priority, set estimate | .claude/skills/flydocs-workflow/SKILL.md |
 
 <!-- flydocs:skills-manifest:end -->
 

package/template/flydocs/README.md

@@ -30,8 +30,6 @@ FlyDocs will **never overwrite** these files during updates - they're yours to m
 ├── config.json            # Tier, provider settings, workspace config
 ├── version                # For upgrade detection
 ├── rules/                 # Workflow rules
-├── scripts/               # Automation scripts
-├── hooks/                 # Workflow hooks
 └── templates/             # Issue templates (source)
 
 flydocs/                   # PROJECT CONTENT (evolves with project)
@@ -153,7 +151,7 @@ See `.flydocs/config.json` for:
 - FlyDocs version
 - `tier` - "local" (free) or "cloud" (connected to provider)
 - `paths.content` - This folder name (default: "flydocs")
-- `provider.type` - Issue tracker provider (null for local, "linear" for cloud)
+- `provider.type` - Issue tracker provider (null for local, e.g. "linear", "jira" for cloud)
 - `workspace.activeProjects` - Array of active project IDs (cloud tier)
 - `workspace.product` - Product identity (name, labelIds, icon, color)
 - `statusMapping` - Workflow state names