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

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

@@ -4,7 +4,7 @@ Initial project onboarding — define project context, connect to provider, and
 create an initial backlog. This command handles two scenarios: new projects
 and FlyDocs version updates (including legacy content migration).
 
-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: "setup flydocs", "onboard project", "flydocs init"
@@ -48,7 +48,7 @@ Example:
 
 ```
 Detected: New project setup (cloud tier)
-I'll walk you through project definition, Linear setup, and initial backlog.
+I'll walk you through project definition, provider setup, and initial backlog.
 Ready to begin?
 ```
 
@@ -73,13 +73,99 @@ If the directory exists and contains files:
 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).
+   skill-led reasoning, workflow 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 0c: Topology Detection
+
+Detect the project's physical layout. This affects Phase 1.5 (service
+descriptor generation) and cross-repo context assembly.
+
+**Step 1: Check for workspace config files.**
+
+Look for these in the project root (in order):
+
+- `pnpm-workspace.yaml` → Type 3 (monorepo multi-service)
+- `nx.json` → Type 3
+- `turbo.json` → Type 3
+- `lerna.json` → Type 3
+- `Cargo.toml` with `[workspace]` section → Type 3
+- `go.work` → Type 3
+
+If any found → **Type 3: Monorepo, multi-service**. Record which config file
+was detected.
+
+**Step 2: Check parent directory for sibling repos.**
+
+If no workspace config found, check one directory up from the project root:
+
+- List subdirectories of the parent directory
+- Check which ones contain a `.git` directory
+- If 2+ sibling directories (including this one) have `.git` → **Type 4: Sibling repos**
+- Record the sibling repo directory names
+
+**Step 3: Determine single-app vs monorepo-single.**
+
+If neither workspace config nor sibling repos detected:
+
+- Check if the project has multiple `package.json` files in subdirectories
+  (e.g., `apps/*/package.json`, `packages/*/package.json`)
+- If yes → **Type 2: Monorepo, single app** (monorepo tooling without workspace config)
+- If no → **Type 1: Single repo, single app**
+
+**Step 4: Report and store.**
+
+Tell the user what was detected:
+
+```
+Topology: Monorepo multi-service (Type 3)
+Detected via: pnpm-workspace.yaml
+```
+
+Update `.flydocs/config.json` with the `topology` field:
+
+```json
+{
+  "topology": {
+    "type": 3,
+    "label": "monorepo-multi",
+    "detectedVia": "pnpm-workspace.yaml"
+  }
+}
+```
+
+For Type 4 (sibling repos), also include:
+
+```json
+{
+  "topology": {
+    "type": 4,
+    "label": "sibling-repos",
+    "detectedVia": "parent directory scan",
+    "siblingRepos": ["flydocs-core", "flydocs-app", "flydocs-marketing"]
+  }
+}
+```
+
+For Type 3 with a workspace root different from project root:
+
+```json
+{
+  "topology": {
+    "type": 3,
+    "label": "monorepo-multi",
+    "detectedVia": "turbo.json",
+    "workspaceRoot": "."
+  }
+}
+```
+
+---
+
 ## Phase 1: Project Definition
 
 The goal is to fill every section of `flydocs/context/project.md` with real
@@ -283,6 +369,114 @@ may be useful:
 
 ---
 
+## Phase 1.5: Service Descriptor Generation
+
+Generate `flydocs/context/service.json` — the dual-purpose descriptor that
+provides cross-repo context AND intra-repo orientation. This phase uses the
+topology detected in Phase 0c and stack detected in Phase 1.
+
+Read `.claude/skills/flydocs-context-graph/service-descriptor-schema.md` for
+the full schema reference before proceeding.
+
+**Step 1: Scan for cross-repo export surface.**
+
+Identify what this repo exposes to the outside world:
+
+- **REST/GraphQL APIs** — scan for route definitions, API directories, endpoint
+  patterns. Look in common locations: `src/app/api/`, `src/routes/`,
+  `pages/api/`, `server/routes/`, `api/`.
+- **Published packages** — check `package.json` for `name` field if it looks
+  like a library (`@scope/package` or explicitly `"private": false`).
+- **Events/messages** — check for pub/sub, message queue, or webhook patterns.
+- **gRPC** — check for `.proto` files.
+
+For each API surface found, capture: type, path, description, and methods
+(for REST).
+
+**Step 2: Scan for dependencies on other services.**
+
+Identify what this repo consumes from external services:
+
+- Check environment variables (`.env.example`, `.env.local`) for service URLs,
+  API keys, or connection strings that reference other internal services.
+- Check `package.json` for internal package references (`workspace:*`).
+- Check import patterns for cross-service API clients.
+- Check config files for external service endpoints.
+
+For each dependency, capture: service name, interface type, and description.
+
+**Step 3: Scan for intra-repo structure.**
+
+Help the agent orient within THIS repo:
+
+- **Entry points** — where does request handling or app logic start?
+  - Web frameworks: `src/app/`, `pages/`, `src/routes/`
+  - CLI tools: `src/cli.ts`, `src/index.ts`, `src/main.ts`
+  - Workers: `src/worker/`, `src/jobs/`
+- **Shared types** — where do type definitions live?
+  - `src/types/`, `src/lib/types.ts`, `types/`, `packages/shared/`
+- **Build system** — what builds the project?
+  - Read from `package.json` scripts, config files: turbo, nx, next, vite,
+    tsup, webpack, cargo, go
+- **Packages** (monorepo Type 3 only) — scan workspace packages:
+  - Read `pnpm-workspace.yaml`, `turbo.json`, or `nx.json` for package list
+  - For each package: name, path, one-line purpose
+
+**Step 4: Compose and confirm the descriptor.**
+
+Build the `service.json` from scan results. Show the user the complete
+descriptor and ask for confirmation or corrections:
+
+```
+Service Descriptor for [repo name]:
+
+Purpose: [one-sentence description]
+Stack: [technology list]
+
+APIs exposed:
+  - REST /api/relay/* — Relay API for CLI operations
+  - package @flydocs/cli — npm CLI binary
+
+Dependencies:
+  - plastrlab/flydocs-app (REST /api/relay/*) — cloud tier operations
+
+Structure:
+  - Entry: src/cli.ts
+  - Types: src/lib/types.ts
+  - Build: tsup
+
+Write to flydocs/context/service.json?
+```
+
+**Step 5: Write the descriptor.**
+
+After user approval, write `flydocs/context/service.json` with the confirmed
+content. Use the schema version `1`.
+
+**Step 6: Push to relay (cloud tier only).**
+
+For cloud tier projects, push the descriptor to the relay:
+
+```bash
+python3 .claude/skills/flydocs-context-graph/scripts/push_service.py
+```
+
+This calls `PUT /api/relay/workspace/service` with the descriptor content
+(excluding the `structure` section which is local-only).
+
+**Step 7: Pull workspace composite (cloud tier only).**
+
+After pushing, pull the workspace composite to see sibling descriptors:
+
+```bash
+python3 .claude/skills/flydocs-context-graph/scripts/pull_services.py
+```
+
+This calls `GET /api/relay/workspace/services` and caches the result for
+graph building and prompt hook orientation.
+
+---
+
 ## Phase 2: Provider Setup — Cloud Only
 
 > **Local tier:** Skip this phase entirely. Print: "Local tier — no provider
@@ -301,60 +495,109 @@ 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 or create team.**
+**Step 2: Detect or select provider.**
+
+Query connected providers:
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py list-integrations
+```
+
+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-workflow/scripts/workspace.py set-provider <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_teams.py
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py teams
 ```
 
 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,
+Add a final option: **"Create a new team/project"**. If only one team exists,
 confirm it.
 
-If the user selects **"Create a new team"**:
+If the user selects **"Create a new team/project"**:
 
 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")
+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>]
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-team --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>
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-team <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).**
 
-**Step 3: Get or create project.**
+> **Jira provider:** Skip this step. Jira organizes issues directly within
+> projects (selected in Step 3). There is no secondary project container.
 
 Query existing projects:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_projects.py
+python3 .claude/skills/flydocs-workflow/scripts/projects.py list-projects
 ```
 
 If matching projects exist, let the user select one. Otherwise, offer to
 create a new project:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/create_project.py --name "Project Name"
+python3 .claude/skills/flydocs-workflow/scripts/projects.py create-project --name "Project Name"
+```
+
+**Step 4b: Set active project.**
+
+After selecting or creating a project, store it as the active project:
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-active-project <project_id>
 ```
 
-**Step 4: Configure labels.**
+This writes `workspace.activeProjects` in `.flydocs/config.json`. All
+subsequent operations (issue listing, captures, milestones, project updates)
+use this to scope work to the active project. This is a critical step —
+without it, product scope filtering and project-update targeting won't work.
+
+**Step 5: Configure labels.**
 
 Fetch available labels from the provider:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_labels.py
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py labels
 ```
 
 **Auto-detect type mapping:** Scan the returned labels for common names
@@ -376,7 +619,7 @@ available labels as options.
 Store the configuration on the relay:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/set_labels.py \
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-labels \
   --defaults '["app"]' \
   --type-map '{"feature":["Feature"],"bug":["Bug"],"chore":["Chore"],"idea":["Improvement"]}'
 ```
@@ -384,7 +627,49 @@ python3 .claude/skills/flydocs-cloud/scripts/set_labels.py \
 If the relay returns `LABELS_NOT_FOUND`, show the invalid names and ask the
 user to correct them.
 
-**Step 5: Configure product identity.**
+**Step 6: Configure status mapping.**
+
+Map provider workflow states to FlyDocs statuses. Run auto-mapping first:
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-status-mapping --auto
+```
+
+The relay auto-maps by case-insensitive name matching (e.g., "In Progress"
+maps to `IMPLEMENTING`, "Done" maps to `COMPLETE`, "Backlog" maps to
+`BACKLOG`).
+
+**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-workflow/scripts/workspace.py statuses
+```
+
+Then store the corrected mapping:
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-status-mapping \
+  --mapping '{"BACKLOG":"Backlog","IMPLEMENTING":"In Progress","BLOCKED":"On Hold",...}'
+```
+
+**Step 7: Configure product identity.**
 
 Ask about product metadata:
 
@@ -392,28 +677,51 @@ Ask about product metadata:
   from project.md)
 - **Icon and color** — optional, ask if they have preferences
 
-**Step 6: Save to config.**
+**Step 8: Generate config from relay.**
+
+The setup scripts in Steps 2-7 all POST to the relay — they no longer write
+to local config. After all setup steps complete, pull the canonical config:
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py config
+```
+
+This calls `GET /config/generate` which returns all server-owned fields
+(`workspaceId`, `setupComplete`, `workspace`, `issueLabels`). The script
+merges these with local-only fields (`tier`, `detectedStack`, `skills`,
+`designSystem`, `aiLabor`, `paths`) and writes `.flydocs/config.json`.
+
+It also cleans up ghost fields (`provider`, `statusMapping`, `labels`) that
+were previously written by individual setup scripts but aren't in the TS
+type system.
 
-Update `.flydocs/config.json`:
+If the response includes `missing` or `warnings`, show them to the user
+but don't block — they can fix in the dashboard and re-run later.
 
-- `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
+**Step 9: Fetch user identity.**
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py get-me
+```
+
+This calls `GET /auth/me` (no workspace required) and writes
+`.flydocs/me.json` with `displayName`, `email`, `providerId`, and
+`providerIdentities`. The file is gitignored — each developer gets their own.
+
+This enables `--mine` filters and personalizes session output.
 
 ---
 
 ## 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.**
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_milestones.py
+python3 .claude/skills/flydocs-workflow/scripts/projects.py list-milestones
 ```
 
 **Step 2: If milestones exist** — show them and confirm they'll be used for
@@ -436,11 +744,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
+python3 .claude/skills/flydocs-workflow/scripts/projects.py create-milestone \
+  --name "Phase 1: Foundation" --project <project_id> --target-date YYYY-MM-DD
 ```
 
 Record the milestone IDs for use in Phase 4.
@@ -468,21 +776,25 @@ 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 workflow 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
+  python3 .claude/skills/flydocs-workflow/scripts/issues.py create \
+    --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:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/assign_milestone.py \
+python3 .claude/skills/flydocs-workflow/scripts/projects.py assign-milestone \
   <issue-ref> <milestone-id>
 ```
 
@@ -494,7 +806,7 @@ based on the issue content.
 **Step 1: Check if backlog is populated.**
 
 ```bash
-python3 .claude/skills/flydocs-{tier}/scripts/list_issues.py --limit 10
+python3 .claude/skills/flydocs-workflow/scripts/issues.py list --limit 10
 ```
 
 If issues exist, skip this phase:
@@ -520,7 +832,7 @@ Only if the user wants to add more.
 List all issues in Backlog status:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_issues.py --status BACKLOG
+python3 .claude/skills/flydocs-workflow/scripts/issues.py list --status BACKLOG
 ```
 
 **Step 2: Set priorities.**
@@ -533,10 +845,10 @@ For each issue, suggest a priority and let the user confirm or adjust:
 - **4 (Low)** — Nice to have, no urgency
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/priority.py <issue-ref> <0-4>
+python3 .claude/skills/flydocs-workflow/scripts/issues.py priority <issue-ref> <0-4>
 ```
 
-Note: Linear uses 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low.
+Note: Priority scale is 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low.
 
 **Step 3: Set estimates.**
 
@@ -549,13 +861,13 @@ For each issue, suggest a t-shirt size estimate:
 - **5** — XL (1+ week, consider breaking down)
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/estimate.py <issue-ref> <1-5>
+python3 .claude/skills/flydocs-workflow/scripts/issues.py estimate <issue-ref> <1-5>
 ```
 
 **Step 4: Identify dependencies.**
 
 Ask about blocking relationships between issues. If any exist, note them
-(Linear handles dependency tracking natively).
+(most providers handle dependency tracking natively).
 
 **Step 5: Recommend implementation order.**
 
@@ -573,7 +885,7 @@ Recommended implementation order:
 
 ## Phase 6: Completion & Onboarding
 
-Summarize what was accomplished and provide a guided onboarding experience.
+Summarize what was accomplished and guide the developer to onboarding.
 
 ### Step 1: Completion summary
 
@@ -585,7 +897,7 @@ Tier: [local / cloud]
 
 ✓ Project context: flydocs/context/project.md
 ✓ Stack detected: [framework list]
-✓ Provider: [Linear connected / Local file-based]      (if applicable)
+✓ Provider: [Connected / Local file-based]              (if applicable)
 ✓ Milestones: [N created]                               (cloud only)
 ✓ Backlog: [N issues captured]
 ✓ Priorities set                                         (cloud only)
@@ -593,43 +905,44 @@ Tier: [local / cloud]
 
 **Mark setup as complete.**
 
-Update `.flydocs/config.json` to set `setupComplete` to `true`. This disables
-the setup reminder in the prompt hook. Read the config, set the field, and
-write it back:
+For **cloud tier**: Setup completion is determined by the relay. The
+`workspace.py config` call in Phase 2 Step 8 already sets `setupComplete`
+based on the relay's validation result. If the relay returns `valid: true`,
+config will have `setupComplete: true`. If not, run `workspace.py validate` to
+check what's still missing.
+
+For **local tier**: Update `.flydocs/config.json` to set `setupComplete` to
+`true`. Read the config, set the field, and write it back:
 
 ```json
 { "setupComplete": true }
 ```
 
-### Step 2: Quick-start guide
+### Step 2: Direct to /onboard
 
-Present the core workflow commands with brief descriptions:
+Check `.flydocs/config.json` for the `onboardComplete` field. If it is not
+`true`, direct the developer to run `/onboard` for full project orientation:
 
 ```
-Here's how to work with FlyDocs:
+Setup is done! Next step:
 
-Getting started:
-  /start-session        Begin a work session (sets focus, loads context)
-  /activate             Pick your next issue to work on
-  /capture              Capture a new issue or idea anytime
+  Run /onboard to get oriented to the codebase, active work, and available
+  commands. This is especially helpful for new team members joining the project.
+```
 
-During development:
-  /implement            Start implementation on your active issue
-  /status               Check current session and issue status
-  /block                Flag a blocker on the current issue
+If `onboardComplete` is already `true` (developer has onboarded before),
+skip the nudge and go straight to the quick-start reminder:
 
-Wrapping up:
-  /review               Submit work for code review
-  /validate             Run QE validation on completed work
-  /wrap-session         End your session (posts summary, saves progress)
+```
+Setup refreshed. Run /start-session to begin working.
 ```
 
 ### Step 3: Tier-specific notes
 
 **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)
+- Recommend reviewing milestones in your provider's UI for timeline view
 
 **For local tier:**
 
@@ -683,11 +996,11 @@ Docs and updates: https://www.flydocs.ai
 
 Throughout the setup flow:
 
-- **Script failures** — If any mechanism script returns exit code 1, show the
+- **Script failures** — If any workflow script returns exit code 1, show the
   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
@@ -698,18 +1011,18 @@ Throughout the setup flow:
 
 ## Key Rules
 
-1. **Always read the mechanism skill's `SKILL.md`** before running any script.
-   Script calling conventions may differ between tiers.
+1. **Always read the workflow skill's `SKILL.md`** before running any script.
+   Script calling conventions are documented there.
 2. **All script paths** follow the pattern:
-   `python3 .claude/skills/flydocs-{tier}/scripts/<script>.py`
-   where `{tier}` is read from `.flydocs/config.json`.
+   `python3 .claude/skills/flydocs-workflow/scripts/<dispatcher>.py <subcommand>`
+   The unified client auto-detects tier from `.flydocs/config.json`.
 3. **Never skip user confirmation** on project.md content. This is their
    project definition — they must approve it.
-4. **Never hardcode tier** — always read from config. A project can switch
-   tiers via `flydocs --tier <tier>`.
-5. **Cloud scripts only for cloud tier.** Extended scripts (estimate, priority,
-   milestones, projects) only exist in `flydocs-cloud`. Do not attempt to call
-   them for local tier.
+4. **Never hardcode tier** — the dispatcher scripts auto-detect tier from
+   config. A project can switch tiers via `flydocs --tier <tier>`.
+5. **Cloud-only operations.** Extended operations (estimate, priority,
+   milestones, projects) are cloud-only. The dispatchers will error if called
+   on local tier for unsupported operations.
 6. **Capture procedure** — when creating issues during Phase 4, follow the
    full capture procedure from `.claude/skills/flydocs-workflow/stages/capture.md`.