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

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

@@ -3,7 +3,7 @@
 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
+Read the workflow skill's `SKILL.md` for script calling conventions
 before executing any scripts.
 
 Triggers: "upgrade to cloud", "migrate to cloud", "local to cloud", "flydocs upgrade"
@@ -65,7 +65,7 @@ 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
+Check if `FLYDOCS_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.**
@@ -84,8 +84,8 @@ Local issues found: [N total]
   - Done: [n]
 
 Migration will:
-  1. Connect to cloud provider (Linear) via flydocs connect
-  2. Create [N] issues in Linear with matching status
+  1. Connect to cloud provider via flydocs connect
+  2. Create [N] issues in your cloud provider with matching status
   3. Archive, delete, or keep local issue files (your choice)
 
 API key: [set / not set — will be needed in Phase 1]
@@ -100,33 +100,44 @@ 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`.
+tier, stores the API key, and configures the workflow skill for cloud access.
 
-**Step 1: Run flydocs connect.**
+**Step 1: Get API key.**
 
-Instruct the user to run `flydocs connect --here` from their terminal
-(this is a CLI command, not an AI command). Explain what it does:
+Ask the user for their FlyDocs API key (`fdk_...`). If `FLYDOCS_API_KEY`
+is already set in the environment, confirm they want to use the existing
+key or enter a new one.
+
+If no key is available, instruct the user:
 
 ```
-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
+You'll need a FlyDocs API key (fdk_...) from your dashboard at app.flydocs.ai.
+
+Option A: Run `flydocs connect --here` in your terminal (handles everything)
+Option B: Add FLYDOCS_API_KEY=fdk_... to your .env or .env.local file
 ```
 
-**Step 2: Wait for completion.**
+Wait for the user to confirm the key is set before proceeding.
+
+**Step 2: Update config to cloud tier.**
+
+Read `.flydocs/config.json`, update `tier` to `"cloud"`, and write it back.
+Preserve all existing config values (detected stack, skills, etc.).
+
+**Step 3: Complete tier configuration.**
+
+Instruct the user to run `flydocs connect --here` from their terminal if
+they haven't already. This handles the tier configuration update and
+connects to the relay API.
+
+**Step 4: Verify connection.**
 
-After the user confirms they ran `flydocs connect`, verify:
+After the user confirms the connection, 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:
+2. Run a test command to verify the connection:
    ```bash
-   python3 .claude/skills/flydocs-cloud/scripts/list_issues.py --limit 1
+   python3 .claude/skills/flydocs-workflow/scripts/issues.py list --limit 1
    ```
 
 If any check fails, help the user troubleshoot before proceeding.
@@ -135,11 +146,11 @@ 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.
+Migrate local issues to the cloud provider. After `flydocs connect` updates
+the tier, the workflow skill now routes to the cloud API.
 
-**IMPORTANT:** The local mechanism scripts are no longer available after
-Phase 1. Read the markdown files directly from `flydocs/issues/`.
+**IMPORTANT:** For migration, read the local issue markdown files directly
+from `flydocs/issues/` rather than using dispatcher scripts.
 
 **Step 1: Read local issue files.**
 
@@ -162,14 +173,14 @@ For each issue file in `flydocs/issues/{status}/*.md`, parse:
 
 **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 each local issue, create it in the cloud provider. Read the workflow
+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 \
+python3 .claude/skills/flydocs-workflow/scripts/issues.py create \
   --title "Issue title" \
   --type feature \
   --priority 3 \
@@ -192,11 +203,11 @@ Migrated from local tier on YYYY-MM-DD.
 
 **Step 3: Transition non-backlog issues.**
 
-Issues created via `create_issue.py` start in BACKLOG status. For issues
+Issues created via `issues.py create` 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 \
+python3 .claude/skills/flydocs-workflow/scripts/issues.py transition \
   <new-issue-ref> <TARGET_STATUS> \
   --comment "Migrated from local tier — original status was [status]"
 ```
@@ -235,7 +246,7 @@ After migration, handle the local issue files. Present three options
 (same pattern as the uninstall command):
 
 ```
-All [N] issues have been migrated to Linear.
+All [N] issues have been migrated to your cloud provider.
 
 What would you like to do with the local issue files?
 
@@ -243,7 +254,7 @@ What would you like to do with the local issue files?
    (keeps files as read-only reference)
 
 2. Delete — Remove flydocs/issues/ and .flydocs/issues.counter
-   (clean slate, issues live in Linear now)
+   (clean slate, issues live in your cloud provider now)
 
 3. Keep — Leave files as-is
    (local files remain alongside cloud issues)
@@ -281,7 +292,7 @@ ID Mapping:
 ```
 Next steps:
   1. Run /flydocs-setup to configure milestones and labels
-  2. Review migrated issues in Linear
+  2. Review migrated issues in your cloud provider
   3. Start working with /start-session
 ```
 
@@ -290,7 +301,7 @@ Next steps:
 Offer to commit the configuration changes:
 
 ```
-The tier change and skill swap modified several files.
+The tier change and configuration update modified several files.
 Want to commit these changes?
 ```
 
@@ -317,11 +328,11 @@ Stage: `.flydocs/config.json`, `.claude/skills/`, `.claude/CLAUDE.md`,
 
 ## Key Rules
 
-1. **Always read the cloud mechanism skill's `SKILL.md`** before running
+1. **Always read the workflow 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.
+3. **For migration, read issue files directly.** Do not use dispatcher
+   scripts to read local tier issue files during migration.
 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

package/template/.claude/commands/implement.md

@@ -3,7 +3,7 @@
 Build the feature or fix, following the implementation checklist.
 
 Read `.claude/skills/flydocs-workflow/stages/implement.md` and follow the procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "implement", "build this", "start coding", "pick up"
 

package/template/.claude/commands/knowledge.md

@@ -0,0 +1,61 @@
+# Knowledge (All Agents)
+
+Create or update a knowledge document — decisions, notes, features, or product docs.
+
+Read `flydocs/knowledge/README.md` for categories and guidance.
+Read `flydocs/knowledge/INDEX.md` for existing entries.
+
+## Procedure
+
+### 1. Determine Intent
+
+From user input or `$ARGUMENTS`, determine:
+
+- **New doc** or **update existing doc**?
+- **Category**: decision, feature, note, or product
+
+If unclear, ask the user. Default to `note` for discoveries and learnings.
+
+### 2. For New Docs
+
+1. Read the template from `flydocs/knowledge/templates/<category>.md`
+2. Gather content from the user — ask clarifying questions if context is thin
+3. Fill in the frontmatter:
+   - `title`: Descriptive, specific title
+   - `created`: Today's date (`YYYY-MM-DD`)
+   - `lastUpdated`: Today's date
+   - `relatedIssues`: Any issue IDs discussed in this session
+   - Category-specific fields (see template)
+4. Write the doc to the correct directory:
+   - Decisions: `flydocs/knowledge/decisions/NNN-title.md` (auto-increment NNN)
+   - Features: `flydocs/knowledge/features/feature-name.md`
+   - Notes: `flydocs/knowledge/notes/topic-name.md`
+   - Product: `flydocs/knowledge/product/document-name.md`
+5. Update `flydocs/knowledge/INDEX.md`:
+   - Add entry to the appropriate table
+   - Update the Quick Reference count
+   - Use a concise description (helps agents assess relevance without loading the full doc)
+
+### 3. For Existing Docs
+
+1. Find the doc in INDEX.md or by searching `flydocs/knowledge/`
+2. Read the current content
+3. Apply the update
+4. Update the `lastUpdated` field in frontmatter
+5. Update the INDEX.md entry if the description changed
+
+### 4. Confirm
+
+Report what was created or updated:
+
+- File path
+- Category and title
+- INDEX.md entry added/updated
+
+## Triggers
+
+- "document this" / "knowledge" / "add to knowledge base"
+- "create an ADR" / "record this decision" / "capture this learning"
+- "add a note about" / "document this discovery"
+
+$ARGUMENTS

package/template/.claude/commands/new-project.md

@@ -2,7 +2,7 @@
 
 Create a new project and add it to active projects in config.
 
-Use `create_project.py` from the active mechanism skill (cloud only).
+Use `projects.py create-project` from `.claude/skills/flydocs-workflow/scripts/` (cloud only).
 For local tier: create project directory structure manually.
 Update `.flydocs/config.json` with the new project ID in `workspace.activeProjects`.
 

package/template/.claude/commands/onboard.md

@@ -0,0 +1,275 @@
+# Onboard (All Agents)
+
+Orient a new developer to the codebase, active project, and FlyDocs workflow.
+This is a one-time orientation (or re-run after major changes) distinct from
+the daily `/start-session`.
+
+Triggers: "onboard", "get oriented", "new here", "walk me through this project"
+
+---
+
+## Pre-Check: User Config (cloud tier only)
+
+Before starting orientation, verify the user has the config needed for a
+personalized experience. Skip this entire step for local tier.
+
+1. **Read `.flydocs/config.json`** — check the `tier` field.
+   - If `tier` is `"local"` or config doesn't exist: skip to Step 1.
+
+2. **Check for `.flydocs/me.json`** — if it exists and has `displayName`, proceed to Step 1.
+
+3. **If `me.json` is missing, try to create it:**
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py get-me
+```
+
+4. **If `workspace.py get-me` fails** (no API key, network error):
+   - Show a clear message:
+
+     ```
+     To connect to your workspace, you need a FlyDocs API key.
+
+     Option A: Set FLYDOCS_API_KEY in .env.local (ask your team admin for the key)
+     Option B: Run `npx flydocs install` which will prompt for the key
+
+     Once set, run /onboard again.
+     ```
+
+   - **Do not block** — continue with the remaining onboard steps using a generic
+     greeting. The user can still see the project overview and commands.
+
+---
+
+## Step 1: Greet the Developer
+
+Read `.flydocs/me.json` for the user's name. If the file exists and has a
+`displayName` field, greet them personally:
+
+```
+Hello, [Name]! Let me orient you to this project.
+```
+
+If `me.json` doesn't exist (local tier or pre-check was skipped), use a
+generic greeting.
+
+---
+
+## Step 2: Install Integrity Check
+
+Check that the FlyDocs installation is healthy. Read `.flydocs/integrity.json`
+and verify all owned files and directories exist:
+
+```python
+import json
+from pathlib import Path
+
+data = json.loads(Path('.flydocs/integrity.json').read_text())
+missing = []
+for f in data.get('ownedFiles', []):
+    if not Path(f).exists():
+        missing.append(f)
+for d in data.get('ownedDirectories', []):
+    if not Path(d).exists():
+        missing.append(d)
+```
+
+Report the result:
+
+- **All present** — "Installation verified — all framework files intact."
+- **Missing files** — List what's missing and suggest: "Run `/flydocs-update`
+  to restore missing files."
+
+If `integrity.json` doesn't exist, note: "No integrity file found — run
+`flydocs update` to generate one."
+
+---
+
+## Step 3: Project Overview
+
+Read `flydocs/context/project.md` and present a concise summary:
+
+- **What this is** — extract the "What This Is" section (first content section)
+- **Tech stack** — extract the Stack section
+- **Active priorities** — extract the Active Priorities section
+- **Standards** — summarize any project-specific conventions
+
+Present this as a structured overview, not a raw file dump. Example:
+
+```
+## Project: FlyDocs Core
+
+CLI tool that installs structured context for AI coding tools.
+
+**Stack:** TypeScript, Node.js, Citty (CLI), tsup (build)
+**Priorities:** Skill consolidation, onboarding flow, cloud beta prep
+**Standards:** Strict TypeScript, kebab-case files, template-first dev
+```
+
+If `project.md` is missing or has only placeholder content, note it and
+suggest running `/flydocs-setup`.
+
+---
+
+## Step 4: Topology and Related Services
+
+Read `.flydocs/config.json` for the `topology` field and check for sibling
+repo context.
+
+**Single repo (Type 1):** Simply note this is a standalone project.
+
+**Monorepo (Type 2/3):** Show the workspace structure. If available, list
+packages from `flydocs/context/service.json` structure.packages.
+
+**Sibling repos (Type 4):** List sibling repos from topology.siblingRepos.
+If `flydocs/context/graph.json` exists, check for repo nodes and show
+cross-repo relationships:
+
+```
+## Related Services
+
+This project is part of a multi-repo workspace:
+- **flydocs-core** (this repo) — CLI tool, template system
+- **flydocs-app** — Web application, relay API
+- **flydocs-marketing** — Marketing site, docs
+
+Dependencies: flydocs-core -> flydocs-app (REST /api/relay/*)
+```
+
+If service descriptors exist in sibling repos, mention key integration points.
+If no topology is configured, note: "Topology not detected. Run `/flydocs-setup`
+to configure."
+
+---
+
+## Step 5: Active Work Summary
+
+Show what's currently happening in the project.
+
+**First: Check active project.** Read `workspace.activeProjects` from
+`.flydocs/config.json`. If set, mention the active project. If not set
+(cloud tier with `setupComplete: true`), warn:
+
+```
+No active project configured. Issue listing and project updates won't be
+scoped correctly. Run /flydocs-setup or:
+  workspace.py set-active-project <PROJECT_ID>
+```
+
+**Cloud tier:**
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/issues.py list --status "all" --limit 20
+```
+
+Summarize by status:
+
+- How many issues in each status (Backlog, Ready, In Progress, Review, etc.)
+- List any In Progress or Review issues with assignees
+- Show the active project name and active milestone if `workspace.defaultMilestoneId` is set
+
+**Local tier:**
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/issues.py list
+```
+
+Show issue count and status breakdown.
+
+**Both tiers:** If `.flydocs/session/last-summary.json` exists, show the last
+session summary for continuity:
+
+```
+## Last Session
+Issues worked: FLY-380, FLY-381
+Pending: 2 items
+Notes: Completed skill consolidation phase 1
+```
+
+---
+
+## Step 6: Command Quick Reference
+
+Present the key commands organized by workflow stage:
+
+```
+## FlyDocs Commands
+
+**Getting started:**
+  /start-session     — Begin a work session (daily)
+  /activate          — Pick your next issue
+  /capture           — Log a new issue or idea
+
+**During development:**
+  /implement         — Start implementation on active issue
+  /status            — Check current session and issue status
+  /block             — Flag a blocker
+  /attach            — Attach to an existing issue
+
+**Completing work:**
+  /review            — Submit for code review
+  /validate          — Run QE validation
+  /close             — Close a completed issue
+  /wrap-session      — End session (saves progress)
+
+**Project management:**
+  /refine            — Triage and refine backlog items
+  /project-update    — Post a project status update
+  /knowledge         — Capture a decision, note, or feature doc
+
+**System:**
+  /flydocs-setup     — Re-run project setup
+  /flydocs-update    — Update FlyDocs to latest version
+  /onboard           — Re-run this orientation
+```
+
+---
+
+## Step 7: Set Onboard Complete
+
+Update `.flydocs/config.json` to set `onboardComplete: true`:
+
+Read the config, set the field, write it back:
+
+```python
+import json
+from pathlib import Path
+
+config_path = Path('.flydocs/config.json')
+config = json.loads(config_path.read_text())
+config['onboardComplete'] = True
+config_path.write_text(json.dumps(config, indent=2) + '\n')
+```
+
+---
+
+## Step 8: Next Steps
+
+End with a clear call to action:
+
+```
+You're all set! To start working:
+  1. Run /start-session to begin your first work session
+  2. Run /activate to pick an issue from the backlog
+  3. Or run /capture to log something new
+
+Need help anytime? Run /status for a quick overview.
+```
+
+---
+
+## Key Rules
+
+1. **This is developer onboarding, not FlyDocs setup.** Focus on orienting the
+   developer to the codebase and active work. Don't reconfigure anything.
+2. **Keep it concise.** Present summaries, not raw file contents. A developer
+   should be oriented in under 2 minutes of reading.
+3. **Gracefully handle missing data.** If project.md is empty, topology isn't
+   configured, or there are no issues — note it and move on. Don't block.
+4. **Script paths** use the consolidated pattern:
+   `python3 .claude/skills/flydocs-workflow/scripts/<dispatcher>.py <subcommand>`
+5. **Both tiers supported.** Cloud tier has richer data (milestones, assignees,
+   projects). Local tier shows what's available. Never call cloud-only scripts
+   on local tier.
+
+$ARGUMENTS

package/template/.claude/commands/project-update.md

@@ -2,7 +2,7 @@
 
 Post a project health update (onTrack, atRisk, offTrack).
 
-Use `project_update.py` from the active mechanism skill (cloud only).
+Use `session.py project-update` from `.claude/skills/flydocs-workflow/scripts/` (cloud only).
 For local tier: append update to `flydocs/context/project.md` Active Priorities section.
 
 Triggers: "project update", "health update", "post update"

package/template/.claude/commands/refine.md

@@ -3,7 +3,7 @@
 Triage a raw capture or refine an existing issue's spec, priority, and estimate.
 
 Read `.claude/skills/flydocs-workflow/stages/refine.md` and follow the procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "refine this", "triage", "flesh out", "add details to"
 

package/template/.claude/commands/review.md

@@ -3,7 +3,7 @@
 Code review — verify acceptance criteria, code quality, and test coverage.
 
 Read `.claude/skills/flydocs-workflow/stages/review.md` and follow the procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "review", "code review", "check this"
 

package/template/.claude/commands/start-session.md

@@ -3,7 +3,7 @@
 Begin a work session — check active work, stale issues, and present a status dashboard.
 
 Read `.claude/skills/flydocs-workflow/session.md` and follow the session start procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "start session", "what's going on", "pick up where I left off"
 

package/template/.claude/commands/status.md

@@ -3,7 +3,7 @@
 Quick status dashboard — issue counts by status for active projects.
 
 Read `.claude/skills/flydocs-workflow/session.md` for dashboard format.
-Use `list_issues.py --active` from the active mechanism skill and group results by status.
+Use `issues.py list --active` from `.claude/skills/flydocs-workflow/scripts/` and group results by status.
 
 Triggers: "status", "where are we", "what's the status"
 

package/template/.claude/commands/validate.md

@@ -3,7 +3,7 @@
 Present the implementation for user acceptance testing.
 
 Read `.claude/skills/flydocs-workflow/stages/validate.md` and follow the procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "validate", "test this", "QA", "looks good", "approve"
 

package/template/.claude/commands/wrap-session.md

@@ -3,7 +3,7 @@
 End a work session — summarize progress, update issues, post project health update.
 
 Read `.claude/skills/flydocs-workflow/session.md` and follow the session wrap procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "wrap up", "end session", "that's it for today", "let's wrap"