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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.5.0-beta.9",
+  "version": "0.6.0-alpha.2",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {

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,33 +288,52 @@ 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: Select or create team.**
 
 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"**. If only one team exists,
 confirm it.
 
+If the user selects **"Create a new team"**:
+
+1. Ask for team name (required) and key (optional — auto-generated if omitted)
+2. Ask if this should be a sub-team under an existing team (show the list
+   again for parent selection, or "None — top-level team")
+3. Create via:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/create_team.py --name "Team Name" [--key KEY] [--parent <parent_team_id>]
+```
+
+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.
+
 **Step 3: Get or create project.**
 
 Query existing projects:
@@ -304,24 +349,59 @@ create a new project:
 python3 .claude/skills/flydocs-cloud/scripts/create_project.py --name "Project Name"
 ```
 
-**Step 4: Configure product identity.**
+**Step 4: Configure labels.**
 
-Ask about product metadata for Linear:
+Fetch available labels from the provider:
 
-- **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
+```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 5: 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 6: Save to config.**
 
 Update `.flydocs/config.json`:
 
-- `provider.teamId` — selected team ID
+- `provider.type` — `"linear"` (set by connect command)
+- `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`)
 - `workspace.activeProjects` — add the project ID
 - `workspace.product.name` — product name
-- `issueLabels` — map label IDs if created
 
 ---
 
@@ -576,20 +656,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
 
 ─────────────────────────────────────────────────────
 ```

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

@@ -0,0 +1,330 @@
+# FlyDocs Upgrade — Local to Cloud Migration (PM/Planning Agent)
+
+AI-guided migration from local tier to cloud tier. Handles API connection,
+issue migration, and local content disposition in a single guided flow.
+
+Read the active mechanism skill's `SKILL.md` for script calling conventions
+before executing any scripts.
+
+Triggers: "upgrade to cloud", "migrate to cloud", "local to cloud", "flydocs upgrade"
+
+---
+
+## IMPORTANT: Use Plan Mode
+
+**Before executing any migration steps, enter plan mode.** This migration
+involves multiple phases with irreversible actions. Planning first ensures
+the user understands what will happen:
+
+1. Run pre-flight checks (Phase 0) to inventory the current state
+2. Present a migration summary with issue counts and what each phase does
+3. Get user approval before making any changes
+
+Only exit plan mode and begin execution after the user approves the plan.
+
+---
+
+## Phase 0: Pre-flight Checks
+
+Before starting, verify the project is eligible for migration.
+
+**Step 1: Read config and verify tier.**
+
+Read `.flydocs/config.json` and check the `tier` field.
+
+- If `tier` is `cloud`: abort with message:
+  ```
+  This project is already on the cloud tier. No migration needed.
+  Run /flydocs-setup to configure your cloud workspace.
+  ```
+- If `tier` is not `local`: abort with error about unexpected tier value.
+
+**Step 2: Inventory local issues.**
+
+Scan `flydocs/issues/` for all issue files across status directories:
+
+```
+flydocs/issues/backlog/*.md
+flydocs/issues/ready/*.md
+flydocs/issues/implementing/*.md
+flydocs/issues/review/*.md
+flydocs/issues/validating/*.md
+flydocs/issues/done/*.md
+flydocs/issues/closed/*.md
+```
+
+For each issue file found, read the YAML frontmatter to extract:
+
+- Title
+- Type (feature, bug, chore, idea)
+- Priority
+- Status (from parent directory name)
+- Any comments in the body
+
+Count totals by status and type.
+
+**Step 3: Check for API readiness.**
+
+Check if `FLYDOCS_RELAY_API_KEY` is set in the environment (from `.env` or
+`.env.local`). If not, warn the user they will need it for Phase 1.
+
+**Step 4: Present migration summary.**
+
+```
+Migration Summary
+─────────────────
+Current tier: local
+Target tier: cloud
+
+Local issues found: [N total]
+  - Backlog: [n]
+  - Ready: [n]
+  - Implementing: [n]
+  - Review: [n]
+  - Done: [n]
+
+Migration will:
+  1. Connect to cloud provider (Linear) via flydocs connect
+  2. Create [N] issues in Linear with matching status
+  3. Archive, delete, or keep local issue files (your choice)
+
+API key: [set / not set — will be needed in Phase 1]
+
+Ready to proceed?
+```
+
+Confirm with the user before continuing.
+
+---
+
+## Phase 1: Connect to Cloud
+
+Guide the user through connecting to the cloud provider. This swaps the
+mechanism skill from `flydocs-local` to `flydocs-cloud`.
+
+**Step 1: Run flydocs connect.**
+
+Instruct the user to run `flydocs connect --here` from their terminal
+(this is a CLI command, not an AI command). Explain what it does:
+
+```
+Run this in your terminal:
+  flydocs connect --here
+
+This will:
+  - Prompt for your relay API key (from flydocs.ai account)
+  - Update .flydocs/config.json to cloud tier
+  - Swap mechanism skills (local -> cloud)
+  - Verify the connection works
+```
+
+**Step 2: Wait for completion.**
+
+After the user confirms they ran `flydocs connect`, verify:
+
+1. Read `.flydocs/config.json` — `tier` should now be `cloud`
+2. Check that `.claude/skills/flydocs-cloud/scripts/` exists
+3. Run a test command to verify the connection:
+   ```bash
+   python3 .claude/skills/flydocs-cloud/scripts/list_issues.py --limit 1
+   ```
+
+If any check fails, help the user troubleshoot before proceeding.
+
+---
+
+## Phase 2: Issue Migration
+
+Migrate local issues to the cloud provider. After `flydocs connect` swaps
+the mechanism skill, the local scripts are gone — read issue files directly.
+
+**IMPORTANT:** The local mechanism scripts are no longer available after
+Phase 1. Read the markdown files directly from `flydocs/issues/`.
+
+**Step 1: Read local issue files.**
+
+For each issue file in `flydocs/issues/{status}/*.md`, parse:
+
+- **YAML frontmatter** — between `---` markers at the top of the file.
+  Fields: `title`, `type`, `priority`, `estimate`, `created`, `assigned`.
+- **Body** — everything after the frontmatter closing `---`.
+  This is the issue description in markdown.
+- **Comments** — look for `## Comments` section in the body.
+  Each comment has a timestamp header and content.
+- **Status** — derived from the parent directory name. Map to cloud status:
+  - `backlog` -> `BACKLOG`
+  - `ready` -> `READY`
+  - `implementing` -> `IMPLEMENTING`
+  - `review` -> `REVIEW`
+  - `validating` -> `VALIDATING`
+  - `done` -> `DONE`
+  - `closed` -> `CLOSED`
+
+**Step 2: Create issues in cloud.**
+
+For each local issue, create it in the cloud provider. Read the cloud
+mechanism skill's `SKILL.md` first for exact calling conventions.
+
+For issues with long descriptions, write the description body to a temp file
+and use `--description-file`:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/create_issue.py \
+  --title "Issue title" \
+  --type feature \
+  --priority 3 \
+  --estimate 2 \
+  --description-file /tmp/flydocs-migrate-desc.md
+```
+
+If the issue had comments in its local file, append them to the description
+body under a `## Migration Notes` section:
+
+```markdown
+## Migration Notes
+
+Migrated from local tier on YYYY-MM-DD.
+
+### Previous Comments
+
+**YYYY-MM-DD HH:MM** — [comment content]
+```
+
+**Step 3: Transition non-backlog issues.**
+
+Issues created via `create_issue.py` start in BACKLOG status. For issues
+that were in other statuses locally, transition them to match:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/transition.py \
+  <new-issue-ref> <TARGET_STATUS> \
+  --comment "Migrated from local tier — original status was [status]"
+```
+
+Status transitions must follow the workflow — you may need intermediate
+transitions for some statuses. Read
+`.claude/skills/flydocs-workflow/reference/status-workflow.md` for valid
+transitions.
+
+**Step 4: Track the mapping.**
+
+Maintain and display an old-to-new ID mapping as issues are migrated:
+
+```
+Migration Progress
+──────────────────
+[1/N] local-1 "Setup auth" -> FLY-234 (BACKLOG)
+[2/N] local-2 "Fix header" -> FLY-235 (IMPLEMENTING)
+[3/N] local-3 "Add tests"  -> FLY-236 (READY)
+...
+```
+
+**Step 5: Handle failures.**
+
+If any issue fails to create or transition:
+
+- Log the error with the local issue reference
+- Continue with remaining issues (don't abort the whole migration)
+- Report all failures at the end with suggestions for manual resolution
+
+---
+
+## Phase 3: Content Disposition
+
+After migration, handle the local issue files. Present three options
+(same pattern as the uninstall command):
+
+```
+All [N] issues have been migrated to Linear.
+
+What would you like to do with the local issue files?
+
+1. Archive — Rename flydocs/issues/ to flydocs/issues-archive/
+   (keeps files as read-only reference)
+
+2. Delete — Remove flydocs/issues/ and .flydocs/issues.counter
+   (clean slate, issues live in Linear now)
+
+3. Keep — Leave files as-is
+   (local files remain alongside cloud issues)
+```
+
+Execute the user's choice:
+
+- **Archive**: Rename `flydocs/issues/` to `flydocs/issues-archive/`
+- **Delete**: Remove `flydocs/issues/` directory and `.flydocs/issues.counter` file
+- **Keep**: No action needed
+
+---
+
+## Phase 4: Completion
+
+Summarize the migration and provide next steps.
+
+**Step 1: Migration summary.**
+
+```
+Migration Complete
+──────────────────
+Tier: local -> cloud
+Issues migrated: [N] ([success] succeeded, [fail] failed)
+Local files: [archived / deleted / kept]
+
+ID Mapping:
+  local-1 -> FLY-234
+  local-2 -> FLY-235
+  ...
+```
+
+**Step 2: Next steps.**
+
+```
+Next steps:
+  1. Run /flydocs-setup to configure milestones and labels
+  2. Review migrated issues in Linear
+  3. Start working with /start-session
+```
+
+**Step 3: Commit prompt.**
+
+Offer to commit the configuration changes:
+
+```
+The tier change and skill swap modified several files.
+Want to commit these changes?
+```
+
+If the user agrees, create a commit with message:
+`Upgrade FlyDocs from local to cloud tier`
+
+Stage: `.flydocs/config.json`, `.claude/skills/`, `.claude/CLAUDE.md`,
+`.cursor/rules/`, and any archive/deletion changes.
+
+---
+
+## Error Handling
+
+- **Already cloud tier** — Abort in Phase 0 with helpful message.
+- **Zero local issues** — Skip Phase 2 entirely, proceed to Phase 4.
+- **flydocs connect fails** — Help troubleshoot; do not proceed to Phase 2.
+- **Partial migration failure** — Report which issues succeeded and which
+  failed. Offer to retry failed issues or proceed with what succeeded.
+- **Cancel mid-migration** — Report current state: which issues were already
+  created in cloud, which local files remain. The user can re-run to
+  continue (Phase 0 will re-inventory remaining local issues).
+
+---
+
+## Key Rules
+
+1. **Always read the cloud mechanism skill's `SKILL.md`** before running
+   scripts in Phase 2. Calling conventions may have changed.
+2. **Never delete local files without explicit user consent** in Phase 3.
+3. **After `flydocs connect`, local scripts are gone.** Read issue files
+   directly — do not attempt to call `flydocs-local` scripts.
+4. **Status transitions must follow the workflow.** Read the status workflow
+   reference for valid transition paths.
+5. **Report progress continuously.** Show the mapping table after each
+   issue is migrated so the user can follow along.
+
+$ARGUMENTS