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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.5.0-beta.9",
+  "version": "0.6.0-alpha.10",
   "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` |
@@ -43,7 +45,7 @@ Issue operations are handled by the installed mechanism skill. Only one is activ
 | Tier              | Skill           | Backend                        |
 | ----------------- | --------------- | ------------------------------ |
 | Local (free)      | `flydocs-local` | File-based (`flydocs/issues/`) |
-| Cloud (connected) | `flydocs-cloud` | Linear GraphQL API             |
+| Cloud (connected) | `flydocs-cloud` | FlyDocs Relay API              |
 
 Read the active mechanism skill's `SKILL.md` for script catalog and calling conventions.
 
@@ -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, Linear, 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/agents/implementation-agent.md

@@ -1,7 +1,6 @@
 ---
 name: implementation-agent
 description: "Builds features, fixes bugs, writes code. Invoke for implementation, coding, or technical work."
-model: opus
 tools: [Read, Glob, Grep, Bash, Write, Edit, WebFetch, WebSearch]
 skills:
   - flydocs-workflow

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

@@ -1,7 +1,6 @@
 ---
 name: pm-agent
 description: "Specs, workflow, issue management. Invoke for capturing, refining, activating, reviewing, closing, or session management."
-model: opus
 tools: [Read, Glob, Grep, Bash, WebFetch]
 disallowedTools: [Write, Edit]
 skills:

package/template/.claude/agents/research-agent.md

@@ -1,7 +1,6 @@
 ---
 name: research-agent
 description: "Codebase exploration and research. Invoke for understanding code structure, finding patterns, or gathering technical context."
-model: sonnet
 tools: [Read, Glob, Grep, WebFetch, WebSearch]
 disallowedTools: [Bash, Write, Edit]
 skills:

package/template/.claude/agents/review-agent.md

@@ -1,7 +1,6 @@
 ---
 name: review-agent
 description: "Code review and quality analysis. Invoke for reviewing implementations, checking quality, or validating acceptance criteria."
-model: sonnet
 tools: [Read, Glob, Grep, Bash]
 disallowedTools: [Write, Edit]
 skills:

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

@@ -54,6 +54,32 @@ Ready to begin?
 
 ---
 
+## Phase 0b: Import Previous Configuration (if applicable)
+
+After detecting the scenario, check if `.flydocs/backup-originals/` exists.
+This directory is created by the installer when it finds pre-existing config
+files (`.claude/CLAUDE.md`, `.claude/settings.json`, `.cursor/hooks.json`,
+`AGENTS.md`) before overwriting them with FlyDocs versions.
+
+If the directory exists and contains files:
+
+1. List the backed-up files and tell the user what was preserved.
+2. Read the backed-up `.claude/CLAUDE.md` (if present).
+3. Summarize what custom instructions, rules, or project-specific context it
+   contained.
+4. Identify which rules are still relevant and worth preserving alongside
+   FlyDocs — focus on project-specific conventions, team standards, and custom
+   tool configurations.
+5. Offer to add relevant rules to `flydocs/context/project.md` (Standards
+   section) or note them for the user to review.
+6. Skip rules that conflict with or duplicate FlyDocs workflow rules (e.g.,
+   skill-led reasoning, mechanism scripts, session management).
+
+This is agent-guided — review and suggest, let the user confirm. No automated
+merging. If no backup directory exists, skip this phase silently.
+
+---
+
 ## Phase 1: Project Definition
 
 The goal is to fill every section of `flydocs/context/project.md` with real
@@ -262,34 +288,89 @@ may be useful:
 > **Local tier:** Skip this phase entirely. Print: "Local tier — no provider
 > setup needed. Issues will be stored in `flydocs/issues/`."
 
-For cloud tier, connect to Linear:
+For cloud tier, connect via the FlyDocs Relay API:
 
 **Step 1: Verify API key.**
 
-Check that `LINEAR_API_KEY` is set in the environment (from `.env` or
+Check that `FLYDOCS_API_KEY` is set in the environment (from `.env` or
 `.env.local`). If not:
 
 ```
-LINEAR_API_KEY is not set. Add it to your .env file:
-LINEAR_API_KEY=lin_api_xxxxx
-
-Get your key from: Linear → Settings → API → Personal API keys
+FLYDOCS_API_KEY is not set. Run `flydocs connect` first to set up your API key.
 ```
 
 Do not proceed until the key is available.
 
-**Step 2: Select team.**
+**Step 2: Detect or select provider.**
+
+Query connected providers:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_providers.py
+```
+
+This returns `[{type, name, connected}]`. Handle based on results:
+
+- **One connected provider** — auto-select it and confirm with the user.
+- **Multiple connected providers** — present a numbered list, let the user
+  choose which to use for this project.
+- **No connected providers** — error: "No providers connected. Connect Linear
+  or Jira at app.flydocs.ai before running setup."
+
+After selection, store the preference:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/set_provider.py <provider_type>
+```
+
+This stores the provider type on the relay (for routing) and updates
+`provider.type` in local config.
+
+**Step 3: Select or create team/project.**
+
+> For Linear, this selects a team. For Jira, this selects a project. The relay
+> normalizes both as "teams" in the API.
 
 If `provider.teamId` in config is null, discover available teams:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_projects.py --all
+python3 .claude/skills/flydocs-cloud/scripts/list_teams.py
 ```
 
-Present the teams to the user. Let them select. If only one team exists,
+Present the teams to the user as a numbered list showing name and key.
+Add a final option: **"Create a new team/project"**. If only one team exists,
 confirm it.
 
-**Step 3: Get or create project.**
+If the user selects **"Create a new team/project"**:
+
+1. Ask for team name (required) and key (optional — auto-generated if omitted)
+2. **Linear only:** Ask if this should be a sub-team under an existing team
+   (show the list again for parent selection, or "None — top-level team").
+   For Jira, skip the parent option — Jira projects do not have a parent
+   hierarchy.
+3. Create via:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/create_team.py --name "Team Name" [--key KEY] [--parent <parent_team_id>]
+```
+
+> The `--parent` flag is Linear-only (sub-teams). Omit for Jira.
+
+After selection or creation, store the preference on the relay and in local
+config:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/set_team.py <team_id>
+```
+
+This stores the team preference server-side (the relay uses it for all
+team-scoped operations) and updates `provider.teamId` in local config.
+For Jira, this sets the active Jira project.
+
+**Step 4: Get or create project (Linear only).**
+
+> **Jira provider:** Skip this step. Jira organizes issues directly within
+> projects (selected in Step 3). There is no secondary project container.
 
 Query existing projects:
 
@@ -304,30 +385,109 @@ create a new project:
 python3 .claude/skills/flydocs-cloud/scripts/create_project.py --name "Project Name"
 ```
 
-**Step 4: Configure product identity.**
+**Step 5: Configure labels.**
+
+Fetch available labels from the provider:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_labels.py
+```
+
+**Auto-detect type mapping:** Scan the returned labels for common names
+(case-insensitive match):
+
+- "Feature" → `feature`
+- "Bug" → `bug`
+- "Chore" → `chore`
+- "Improvement" → `idea`
+
+Build a `typeMap` from the matches. Show the user the proposed mapping and
+let them adjust. If no matches found, ask the user to map manually from the
+available labels.
+
+**Default labels:** Ask if there are labels that should be applied to every
+new issue (e.g., a project-scope label like "app" or "core"). Present the
+available labels as options.
+
+Store the configuration on the relay:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/set_labels.py \
+  --defaults '["app"]' \
+  --type-map '{"feature":["Feature"],"bug":["Bug"],"chore":["Chore"],"idea":["Improvement"]}'
+```
+
+If the relay returns `LABELS_NOT_FOUND`, show the invalid names and ask the
+user to correct them.
+
+**Step 6: Configure status mapping.**
+
+Map provider workflow states to FlyDocs statuses. Run auto-mapping first:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/set_status_mapping.py --auto
+```
 
-Ask about product metadata for Linear:
+The relay auto-maps by case-insensitive name matching (e.g., "In Progress"
+maps to `IMPLEMENTING`, "Done" maps to `COMPLETE`, "Backlog" maps to
+`BACKLOG`).
 
-- **Product name** — how it appears in Linear (default: project name from
-  project.md)
-- **Labels** — auto-create category labels (feature, bug, chore, idea) and
-  role labels (design, development, operations) if they don't exist
+**Review the result:** The response includes `matched` (number of statuses
+successfully mapped) and `total` (total FlyDocs statuses). Show the user
+the `mapping` object:
+
+```
+Status mapping (matched 6/10):
+  BACKLOG      -> Backlog
+  READY        -> Ready
+  IMPLEMENTING -> In Progress
+  REVIEW       -> In Review
+  COMPLETE     -> Done
+  CANCELED     -> Canceled
+```
+
+If `matched < total`, some statuses are unmapped — **warn but don't block**.
+Transitions for unmapped statuses will fall back to provider name matching.
+If the user wants to fix unmapped statuses, fetch available provider states
+and let them map manually:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_statuses.py
+```
+
+Then store the corrected mapping:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/set_status_mapping.py \
+  --mapping '{"BACKLOG":"Backlog","IMPLEMENTING":"In Progress","BLOCKED":"On Hold",...}'
+```
+
+**Step 7: Configure product identity.**
+
+Ask about product metadata:
+
+- **Product name** — how it appears in the provider (default: project name
+  from project.md)
 - **Icon and color** — optional, ask if they have preferences
 
-**Step 5: Save to config.**
+**Step 8: Save to config.**
 
 Update `.flydocs/config.json`:
 
-- `provider.teamId` — selected team ID
+- `provider.type` — set by `set_provider.py`
+- `provider.teamId` — selected team ID (set by `set_team.py`)
+- `labels.defaults` — default label names (set by `set_labels.py`)
+- `labels.typeMap` — type-to-label mapping (set by `set_labels.py`)
+- `statusMapping` — FlyDocs-to-provider status mapping (set by `set_status_mapping.py`)
 - `workspace.activeProjects` — add the project ID
 - `workspace.product.name` — product name
-- `issueLabels` — map label IDs if created
 
 ---
 
 ## Phase 3: Milestones — Cloud Only
 
 > **Local tier:** Skip this phase entirely.
+> **Jira provider:** Skip this phase. Milestone support for Jira is planned for a future release.
 > **FlyDocs Update:** Skip if milestones already exist.
 
 **Step 1: Check existing milestones.**
@@ -356,11 +516,11 @@ Let the user customize names, descriptions, and target dates.
 
 **Step 4: Create milestones.**
 
-For each approved milestone:
+For each approved milestone, pass the project ID from Phase 2 Step 3:
 
 ```bash
 python3 .claude/skills/flydocs-cloud/scripts/create_milestone.py \
-  --name "Phase 1: Foundation" --target-date YYYY-MM-DD
+  --name "Phase 1: Foundation" --project <project_id> --target-date YYYY-MM-DD
 ```
 
 Record the milestone IDs for use in Phase 4.
@@ -388,16 +548,20 @@ For each work item, follow the capture procedure from
 `.claude/skills/flydocs-workflow/stages/capture.md`:
 
 - Determine type (feature, bug, chore, idea)
-- Create via the mechanism script:
+- Create via the mechanism script (cloud: pass `--project` from Phase 2 for
+  Linear; omit `--project` for Jira — issues are scoped to the team/project
+  selected in Phase 2 Step 3):
   ```bash
   python3 .claude/skills/flydocs-{tier}/scripts/create_issue.py \
-    --title "Issue title" --type feature --priority 3 --estimate 2
+    --title "Issue title" --type feature --priority 3 --estimate 2 \
+    --project <project_id>
   ```
 - For quick ideas, use `--triage` flag
 
-**Step 3: Milestone assignment (cloud only).**
+**Step 3: Milestone assignment (Linear only).**
 
 > **Local tier:** Skip this step.
+> **Jira provider:** Skip this step.
 
 After creating issues, assign them to milestones:
 
@@ -548,8 +712,8 @@ Wrapping up:
 
 **For cloud tier:**
 
-- Linear project URL (if available from create_project response)
-- Recommend reviewing milestones in Linear's UI for timeline view
+- Provider project URL (if available from create_project response)
+- For Linear: recommend reviewing milestones in Linear's UI for timeline view
 
 **For local tier:**
 
@@ -576,20 +740,23 @@ Stage all new and modified FlyDocs files (`.flydocs/`, `.claude/`, `.cursor/`,
 If the user declines, remind them to commit before starting work:
 "No problem — just remember to commit these files before your first session."
 
-### Step 5: Beta CTA
+### Step 5: Community CTA
 
-Always end with the beta call-to-action:
+Always end with the community call-to-action:
 
 ```
 ─────────────────────────────────────────────────────
 
-FlyDocs is in active development. Premium features coming soon:
-  → Cloud sync with Linear, Jira, and more
-  → AI-powered skills and automation
-  → Team analytics and cost intelligence
+What's coming next:
+  → Project management tool sync — Linear, Jira, and more
+  → Web portal — project setup, team visibility, session analytics
+  → Cost intelligence — AI usage tracking and spend analysis
+
+Join the Discord for upcoming features, support, and early access to what's next.
+  Invite link:
+  https://discord.com/invite/YAkjePmZTQ
 
-Join the beta for early access and updates:
-  https://www.flydocs.ai?utm_source=cli&utm_medium=setup&utm_campaign=beta
+Docs and updates: https://www.flydocs.ai
 
 ─────────────────────────────────────────────────────
 ```
@@ -604,7 +771,7 @@ Throughout the setup flow:
   error message from stderr and ask the user how to proceed. Do not retry
   silently.
 - **Missing API key** — For cloud tier, cannot proceed past Phase 2 without
-  `LINEAR_API_KEY`. Guide the user to set it up.
+  `FLYDOCS_API_KEY`. Guide the user to set it up.
 - **Missing config** — If `.flydocs/config.json` doesn't exist, the user
   likely needs to run `flydocs` (install) first. Advise them accordingly.
 - **Partial completion** — If the user needs to stop mid-setup, note which