@flydocs/cli 0.5.0-beta.2 → 0.5.0-beta.4

package/dist/cli.js

@@ -15,7 +15,7 @@ var CLI_VERSION, CLI_NAME, PACKAGE_NAME;
 var init_constants = __esm({
   "src/lib/constants.ts"() {
     "use strict";
-    CLI_VERSION = "0.5.0-beta.2";
+    CLI_VERSION = "0.5.0-beta.4";
     CLI_NAME = "flydocs";
     PACKAGE_NAME = "@flydocs/cli";
   }
@@ -149,24 +149,29 @@ function printInfo(message) {
   console.log(`${pc2.cyan("\u2139")} ${message}`);
 }
 function printStub(command) {
-  printWarning(`${pc2.bold(command)} is not yet implemented in the Node CLI.`);
-  console.log(`  Use ${pc2.cyan("bash install.sh")} for now.`);
+  printWarning(`${pc2.bold(command)} is not yet implemented.`);
 }
 function printBanner(version) {
-  const pink = pc2.magenta;
-  const purple = (t) => pc2.cyan(t);
+  const pink = (t) => pc2.bold(pc2.magenta(t));
+  const purple = (t) => pc2.bold(pc2.cyan(t));
   const dim = pc2.dim;
   const bold = pc2.bold;
+  const pinkBlock12 = pink("\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588");
+  const pinkBlock4 = pink("\u2588\u2588\u2588\u2588");
+  const purpleBlock12 = purple("\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588");
+  const purpleBlock4 = purple("\u2588\u2588\u2588\u2588");
   console.log();
-  console.log(`  ${bold(pink("\u2588\u2588\u2588\u2588\u2588\u2588"))}`);
+  console.log(`  ${pinkBlock12}`);
+  console.log(`  ${pinkBlock12}`);
+  console.log(`  ${pinkBlock4}`);
   console.log(
-    `  ${bold(pink("\u2588\u2588"))}      ${bold(purple("\u2588\u2588\u2588\u2588\u2588\u2588"))}  ${bold(pink("Fly"))}${bold(purple("Docs"))} ${bold(pink("Core"))}`
+    `  ${pinkBlock4}  ${purpleBlock12}  ${bold("Fly")}${bold("Docs")} ${bold("Core")}`
   );
   console.log(
-    `        ${bold(purple("\u2588\u2588\u2588\u2588\u2588\u2588"))}  ${dim("Context-as-a-Service Platform Built for Engineering at Altitude")}`
+    `        ${purpleBlock12}  ${dim("Context-as-a-Service Platform Built for Engineering at Altitude")}`
   );
-  console.log(`        ${bold(purple("\u2588\u2588"))}`);
-  console.log(`        ${bold(purple("\u2588\u2588"))}      ${dim(`v${version}`)}`);
+  console.log(`        ${purpleBlock4}`);
+  console.log(`        ${purpleBlock4}          ${dim(`v${version}`)}`);
   console.log();
 }
 function printCompletionBox(title, lines) {
@@ -433,6 +438,12 @@ async function detectStack(targetDir) {
     if ("next" in allDeps) detected.add("nextjs");
     if ("expo" in allDeps) detected.add("expo");
     if ("react" in allDeps) detected.add("react");
+    if ("vue" in allDeps) detected.add("vue");
+    if ("nuxt" in allDeps) detected.add("nuxt");
+    if (Object.keys(allDeps).some((k) => k.startsWith("@angular/")))
+      detected.add("angular");
+    if ("svelte" in allDeps || "@sveltejs/kit" in allDeps)
+      detected.add("svelte");
     if ("convex" in allDeps) detected.add("convex");
     if ("prisma" in allDeps) detected.add("prisma");
     if (Object.keys(allDeps).some((k) => k.startsWith("@clerk")))
@@ -462,14 +473,39 @@ async function detectStack(targetDir) {
   if (await pathExists(join5(targetDir, "tsconfig.json"))) {
     detected.add("typescript");
   }
+  if (await pathExists(join5(targetDir, "nuxt.config.ts")) || await pathExists(join5(targetDir, "nuxt.config.js"))) {
+    detected.add("nuxt");
+    detected.add("vue");
+  }
+  if (await pathExists(join5(targetDir, "angular.json"))) {
+    detected.add("angular");
+  }
+  if (await pathExists(join5(targetDir, "svelte.config.js")) || await pathExists(join5(targetDir, "svelte.config.ts"))) {
+    detected.add("svelte");
+  }
+  if (await pathExists(join5(targetDir, "pyproject.toml")) || await pathExists(join5(targetDir, "requirements.txt")) || await pathExists(join5(targetDir, "setup.py"))) {
+    detected.add("python");
+  }
+  if (await pathExists(join5(targetDir, "go.mod"))) {
+    detected.add("go");
+  }
+  if (await pathExists(join5(targetDir, "Cargo.toml"))) {
+    detected.add("rust");
+  }
   const raw = Array.from(detected);
   return {
     raw,
-    frameworks: raw.filter((s) => ["nextjs", "react", "expo"].includes(s)),
+    frameworks: raw.filter(
+      (s) => ["nextjs", "react", "expo", "vue", "nuxt", "angular", "svelte"].includes(
+        s
+      )
+    ),
     database: raw.filter((s) => ["convex", "prisma"].includes(s)),
     auth: raw.filter((s) => ["clerk", "workos"].includes(s)),
     styling: raw.filter((s) => ["tailwind"].includes(s)),
-    language: raw.filter((s) => ["typescript"].includes(s)),
+    language: raw.filter(
+      (s) => ["typescript", "python", "go", "rust"].includes(s)
+    ),
     testing: raw.filter(
       (s) => ["vitest", "jest", "testing-library"].includes(s)
     )
@@ -947,12 +983,14 @@ async function promptCommunitySkills(targetDir, stack, autoYes) {
     const options = suggestions.map((s) => ({
       value: s,
       label: s.name,
-      hint: s.description
+      hint: s.description,
+      initialValue: true
     }));
     const result = await multiselect({
-      message: "Select community skills to install",
+      message: "Select community skills to install (space to toggle, enter to confirm)",
       options,
-      required: false
+      required: false,
+      initialValues: suggestions
     });
     if (isCancel(result)) {
       cancel("Skipped community skills");
@@ -991,6 +1029,7 @@ var init_community_skills = __esm({
     init_ui();
     init_skill_manager();
     COMMUNITY_SKILLS_MAP = [
+      // React / Next.js (Vercel official)
       {
         stackTrigger: "nextjs",
         repo: "vercel-labs/agent-skills",
@@ -1009,6 +1048,34 @@ var init_community_skills = __esm({
         name: "react-best-practices",
         description: "React performance optimization (40+ rules from Vercel)"
       },
+      // Vue / Nuxt
+      {
+        stackTrigger: "nuxt",
+        repo: "onmax/nuxt-skills",
+        name: "nuxt",
+        description: "Nuxt framework patterns and best practices"
+      },
+      {
+        stackTrigger: "vue",
+        repo: "onmax/nuxt-skills",
+        name: "vue",
+        description: "Vue.js composition API and component patterns"
+      },
+      // Angular
+      {
+        stackTrigger: "angular",
+        repo: "Jeffallan/claude-skills",
+        name: "angular-architect",
+        description: "Angular architecture, modules, and component patterns"
+      },
+      // Svelte / SvelteKit
+      {
+        stackTrigger: "svelte",
+        repo: "spences10/svelte-skills-kit",
+        name: "svelte-skills",
+        description: "Svelte 5 runes, SvelteKit routing, and component patterns"
+      },
+      // Convex
       {
         stackTrigger: "convex",
         repo: "waynesutton/convexskills",
@@ -1021,17 +1088,26 @@ var init_community_skills = __esm({
         name: "convex-functions",
         description: "Convex query/mutation/action patterns"
       },
+      // Python
       {
-        stackTrigger: "tailwind",
-        repo: "blencorp/claude-code-kit",
-        name: "tailwind-v4",
-        description: "Tailwind CSS v4 patterns and configuration"
+        stackTrigger: "python",
+        repo: "wdm0006/python-skills",
+        name: "python-skills",
+        description: "Python library quality, packaging, and testing patterns"
       },
+      // Go
       {
-        stackTrigger: "clerk",
-        repo: "blencorp/claude-code-kit",
-        name: "clerk-auth",
-        description: "Clerk authentication patterns"
+        stackTrigger: "go",
+        repo: "saisudhir14/golang-agent-skill",
+        name: "golang",
+        description: "Go concurrency, error handling, and testing patterns"
+      },
+      // Rust
+      {
+        stackTrigger: "rust",
+        repo: "leonardomso/rust-skills",
+        name: "rust-skills",
+        description: "Rust ownership, concurrency, and safety patterns (179 rules)"
       }
     ];
   }
@@ -1414,7 +1490,7 @@ function printUpdateNotice(result) {
     `  ${pc5.dim("Update available:")} ${pc5.cyan(result.currentVersion)} ${pc5.dim("->")} ${pc5.cyan(result.latestVersion)}`
   );
   console.log(
-    `  ${pc5.dim("Run:")} ${pc5.yellow(`npm update -g ${PACKAGE_NAME}`)}`
+    `  ${pc5.dim("Run:")} ${pc5.yellow(`npm install -g ${PACKAGE_NAME}@beta`)}`
   );
   console.log();
 }
@@ -1438,7 +1514,7 @@ __export(install_exports, {
 import { defineCommand } from "citty";
 import { resolve as resolve2 } from "path";
 import { join as join11 } from "path";
-import { select, isCancel as isCancel3, cancel as cancel2 } from "@clack/prompts";
+import { confirm as confirm2, isCancel as isCancel3, cancel as cancel2 } from "@clack/prompts";
 var install_default;
 var init_install = __esm({
   "src/commands/install.ts"() {
@@ -1526,26 +1602,15 @@ var init_install = __esm({
           }
         }
         if (!tier) {
-          const tierChoice = await select({
-            message: "Select your tier",
-            options: [
-              {
-                value: "local",
-                label: "local",
-                hint: "File-based issues. No accounts, no API keys, works offline."
-              },
-              {
-                value: "cloud",
-                label: "cloud",
-                hint: "Linear integration. Real-time sync with your team."
-              }
-            ]
+          const shouldInstall = await confirm2({
+            message: `Install FlyDocs here? (local tier)
+  Directory: ${targetDir}`
           });
-          if (isCancel3(tierChoice)) {
+          if (isCancel3(shouldInstall) || !shouldInstall) {
             cancel2("Installation cancelled.");
             process.exit(0);
           }
-          tier = tierChoice;
+          tier = "local";
           console.log();
         }
         if (!await pathExists(join11(targetDir, ".git"))) {
@@ -1797,8 +1862,72 @@ var init_install = __esm({
           "",
           "Documentation: flydocs/README.md"
         ];
+        let copiedToClipboard = false;
+        try {
+          const clipboard = await import("clipboardy");
+          await clipboard.default.write("/flydocs-setup");
+          copiedToClipboard = true;
+        } catch {
+        }
+        if (copiedToClipboard) {
+          const localSteps = nextSteps.findIndex(
+            (l) => l.includes("/flydocs-setup")
+          );
+          if (localSteps !== -1) {
+            nextSteps[localSteps] = nextSteps[localSteps] + "  (copied to clipboard)";
+          }
+        }
         printCompletionBox("Installation Complete!", nextSteps);
         printBetaCta();
+        try {
+          const { execSync: execSync4, spawn } = await import("child_process");
+          const isInstalled = (cmd) => {
+            try {
+              execSync4(`which ${cmd}`, { stdio: "pipe" });
+              return true;
+            } catch {
+              return false;
+            }
+          };
+          const hasClaude = isInstalled("claude");
+          const hasCursor = isInstalled("cursor");
+          const hasCode = isInstalled("code");
+          if (hasClaude) {
+            const launchClaude = await confirm2({
+              message: "Open Claude Code and run /flydocs-setup now?"
+            });
+            if (!isCancel3(launchClaude) && launchClaude) {
+              spawn("claude", ["/flydocs-setup"], {
+                cwd: targetDir,
+                stdio: "inherit"
+              });
+              return;
+            }
+          } else if (hasCursor) {
+            const launchCursor = await confirm2({
+              message: copiedToClipboard ? "Open Cursor? (paste /flydocs-setup from clipboard)" : "Open Cursor?"
+            });
+            if (!isCancel3(launchCursor) && launchCursor) {
+              spawn("cursor", [targetDir], {
+                stdio: "ignore",
+                detached: true
+              }).unref();
+              printInfo("Cursor opening \u2014 paste /flydocs-setup in the chat panel");
+            }
+          } else if (hasCode) {
+            const launchCode = await confirm2({
+              message: copiedToClipboard ? "Open VS Code? (paste /flydocs-setup from clipboard)" : "Open VS Code?"
+            });
+            if (!isCancel3(launchCode) && launchCode) {
+              spawn("code", [targetDir], {
+                stdio: "ignore",
+                detached: true
+              }).unref();
+              printInfo("VS Code opening \u2014 paste /flydocs-setup in the chat panel");
+            }
+          }
+        } catch {
+        }
         try {
           const updateResult = await checkForUpdate();
           if (updateResult) {
@@ -1819,7 +1948,7 @@ __export(update_exports, {
 import { defineCommand as defineCommand2 } from "citty";
 import { resolve as resolve3, join as join12 } from "path";
 import { mkdir as mkdir5, cp as cp2, readFile as readFile8, readdir as readdir3, rm as rm4 } from "fs/promises";
-import { select as select2, text, confirm as confirm2, isCancel as isCancel4, cancel as cancel3 } from "@clack/prompts";
+import { select, text, confirm as confirm3, isCancel as isCancel4, cancel as cancel3 } from "@clack/prompts";
 import pc6 from "picocolors";
 var update_default;
 var init_update = __esm({
@@ -1885,7 +2014,7 @@ var init_update = __esm({
         } else if (args.here) {
           targetDir = process.cwd();
         } else {
-          const choice = await select2({
+          const choice = await select({
             message: "Which project would you like to update?",
             options: [
               {
@@ -1956,7 +2085,7 @@ var init_update = __esm({
           printWarning(
             `Project version (${currentVersion}) is newer than installer (${version})`
           );
-          const shouldContinue = await confirm2({
+          const shouldContinue = await confirm3({
             message: "Continue anyway?"
           });
           if (isCancel4(shouldContinue) || !shouldContinue) {
@@ -2336,7 +2465,7 @@ __export(connect_exports, {
   default: () => connect_default
 });
 import { defineCommand as defineCommand5 } from "citty";
-import { text as text2, confirm as confirm3, isCancel as isCancel5, cancel as cancel4 } from "@clack/prompts";
+import { text as text2, confirm as confirm4, isCancel as isCancel5, cancel as cancel4 } from "@clack/prompts";
 import pc8 from "picocolors";
 import { readFile as readFile9, writeFile as writeFile5, appendFile as appendFile2 } from "fs/promises";
 import { join as join13 } from "path";
@@ -2386,7 +2515,7 @@ var init_connect = __esm({
         if (config.tier === "cloud") {
           printInfo("This project is already connected to the cloud tier.");
           console.log();
-          const reconnect = await confirm3({
+          const reconnect = await confirm4({
             message: "Want to update your API key?"
           });
           if (isCancel5(reconnect) || !reconnect) {
@@ -2612,14 +2741,16 @@ var init_self_update = __esm({
         console.log(`  Updating ${pc10.cyan(PACKAGE_NAME)}...`);
         console.log();
         try {
-          execSync3(`npm update -g ${PACKAGE_NAME}`, {
+          execSync3(`npm install -g ${PACKAGE_NAME}@beta`, {
             stdio: "inherit",
             timeout: 6e4
           });
           console.log();
           printStatus("FlyDocs CLI updated successfully");
         } catch {
-          printError(`Update failed. Try manually: npm update -g ${PACKAGE_NAME}`);
+          printError(
+            `Update failed. Try manually: npm install -g ${PACKAGE_NAME}@beta`
+          );
           process.exit(1);
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.5.0-beta.2",
+  "version": "0.5.0-beta.4",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {
@@ -22,6 +22,7 @@
   "dependencies": {
     "@clack/prompts": "^0.9.1",
     "citty": "^0.1.6",
+    "clipboardy": "^5.3.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {

package/template/.claude/CLAUDE.md

@@ -21,29 +21,29 @@ These are non-negotiable and enforced by hooks:
 
 The FlyDocs development lifecycle. Read the workflow skill before taking any workflow action.
 
-| Action | Skill | Entry Point |
-|--------|-------|-------------|
-| Capture issue | `flydocs-workflow` | `stages/capture.md` |
-| Refine / triage | `flydocs-workflow` | `stages/refine.md` |
-| Activate work | `flydocs-workflow` | `stages/activate.md` |
-| Implement | `flydocs-workflow` | `stages/implement.md` |
-| Code review | `flydocs-workflow` | `stages/review.md` |
-| QE validation | `flydocs-workflow` | `stages/validate.md` |
-| Close issue | `flydocs-workflow` | `stages/close.md` |
-| Start / wrap session | `flydocs-workflow` | `session.md` |
-| Comment templates | `flydocs-workflow` | `reference/comment-templates.md` |
-| Status transitions | `flydocs-workflow` | `reference/status-workflow.md` |
+| Action               | Skill              | Entry Point                       |
+| -------------------- | ------------------ | --------------------------------- |
+| Capture issue        | `flydocs-workflow` | `stages/capture.md`               |
+| Refine / triage      | `flydocs-workflow` | `stages/refine.md`                |
+| Activate work        | `flydocs-workflow` | `stages/activate.md`              |
+| Implement            | `flydocs-workflow` | `stages/implement.md`             |
+| Code review          | `flydocs-workflow` | `stages/review.md`                |
+| QE validation        | `flydocs-workflow` | `stages/validate.md`              |
+| Close issue          | `flydocs-workflow` | `stages/close.md`                 |
+| Start / wrap session | `flydocs-workflow` | `session.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` |
-| Issue templates | `flydocs-workflow` | `templates/` |
+| Issue templates      | `flydocs-workflow` | `templates/`                      |
 
 ## Mechanism Scripts
 
 Issue operations are handled by the installed mechanism skill. Only one is active at a time.
 
-| Tier | Skill | Backend |
-|------|-------|---------|
-| Local (free) | `flydocs-local` | File-based (`flydocs/issues/`) |
-| Cloud (connected) | `flydocs-cloud` | Linear GraphQL API |
+| Tier              | Skill           | Backend                        |
+| ----------------- | --------------- | ------------------------------ |
+| Local (free)      | `flydocs-local` | File-based (`flydocs/issues/`) |
+| Cloud (connected) | `flydocs-cloud` | Linear GraphQL API             |
 
 Read the active mechanism skill's `SKILL.md` for script catalog and calling conventions.
 
@@ -54,37 +54,71 @@ Read the active mechanism skill's `SKILL.md` for script catalog and calling conv
 
 FlyDocs platform skills with premium functionality.
 
-| Skill | When to Read |
-|-------|--------------|
-| `flydocs-figma` | Building UI from Figma designs — extraction, token mapping |
-| `flydocs-estimates` | Estimating AI token usage and costs (opt-in via config) |
+| Skill               | When to Read                                               |
+| ------------------- | ---------------------------------------------------------- |
+| `flydocs-figma`     | Building UI from Figma designs — extraction, token mapping |
+| `flydocs-estimates` | Estimating AI token usage and costs (opt-in via config)    |
 
 ## Project Context
 
-| File | Purpose |
-|------|---------|
+| File                         | Purpose                                      |
+| ---------------------------- | -------------------------------------------- |
 | `flydocs/context/project.md` | Product scope, tech stack, active priorities |
-| `.flydocs/config.json` | Tier, provider, labels, active projects |
+| `.flydocs/config.json`       | Tier, provider, labels, active projects      |
 
 ## Hooks
 
-| Hook | Trigger | Purpose |
-|------|---------|---------|
-| `PostToolUse` (Edit/Write) | After code changes | Auto-format |
-| `UserPromptSubmit` | Before prompt | Inject git/issue context |
-| `PreToolUse` | Before script execution | Auto-approve mechanism scripts |
+| Hook                       | Trigger                 | Purpose                        |
+| -------------------------- | ----------------------- | ------------------------------ |
+| `PostToolUse` (Edit/Write) | After code changes      | Auto-format                    |
+| `UserPromptSubmit`         | Before prompt           | Inject git/issue context       |
+| `PreToolUse`               | Before script execution | Auto-approve mechanism scripts |
+
+## Output Formatting
+
+Consistent formatting across all agent output. Follow these rules in every
+response — session summaries, issue comments, status updates, and plans.
+
+**Structure:**
+
+- Lead with a one-line summary or status before detail.
+- Use `##` for major sections, `###` for subsections. Never skip levels.
+- Use bullet lists for 3+ related items. Use numbered lists only for sequences.
+- One blank line between sections. No double-blank lines.
+
+**Readability:**
+
+- Keep paragraphs to 2-3 sentences. Break long blocks into scannable lists.
+- Bold key terms and status labels on first use: **Completed**, **Blocked**, **Next**.
+- Use inline code for file paths, commands, and identifiers: `project.md`, `/start-session`, `FLY-123`.
+- Use code blocks with language tags for multi-line code or script examples.
+
+**Consistency:**
+
+- Status labels: **Completed**, **In Progress**, **Blocked**, **Next Up** (always bolded).
+- Issue references: `FLY-123` format (uppercase prefix, hyphen, number).
+- File paths: relative from project root, in backticks.
+- Dates: `YYYY-MM-DD` format.
+- No emoji in output unless the user explicitly requests it.
+
+**Tables:**
+
+- Use tables for structured comparisons (3+ items with 2+ attributes).
+- Left-align text columns, keep headers short.
 
 <!-- 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, Linear, cloud | .claude/skills/flydocs-cloud/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, Linear, cloud | .claude/skills/flydocs-cloud/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  |
+
 <!-- flydocs:skills-manifest:end -->

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

@@ -11,6 +11,22 @@ Triggers: "setup flydocs", "onboard project", "flydocs init"
 
 ---
 
+## IMPORTANT: Use Plan Mode
+
+**Before executing any setup steps, enter plan mode.** This setup involves
+multiple phases with user decisions at each stage. Planning first ensures a
+better experience:
+
+1. Run scenario detection (Phase 0) to understand the project state
+2. Scan for existing documentation and the tech stack
+3. Present a structured setup plan showing all phases and what each will do
+4. Get user approval before making any changes
+
+This lets the user see the full picture before committing. Only exit plan
+mode and begin execution after the user approves the plan.
+
+---
+
 ## Phase 0: Scenario Detection
 
 Before starting, detect the project state by checking the filesystem:
@@ -541,7 +557,26 @@ Wrapping up:
 - No account or API key needed — everything is local and offline
 - Run `/status` anytime to see your backlog at a glance
 
-### Step 4: Beta CTA
+### Step 4: Commit setup
+
+FlyDocs setup creates and modifies many files. Prompt the user to commit
+everything as a clean baseline:
+
+```
+Ready to commit the FlyDocs setup? This creates a clean baseline with all
+configuration, context, and initial backlog in one commit.
+```
+
+If the user agrees, create a single commit with a message like:
+`Add FlyDocs project setup (local tier)` or `Add FlyDocs project setup (cloud tier)`
+
+Stage all new and modified FlyDocs files (`.flydocs/`, `.claude/`, `.cursor/`,
+`flydocs/`, `AGENTS.md`, `.gitignore`). Do not stage unrelated changes.
+
+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
 
 Always end with the beta call-to-action:
 

package/template/.flydocs/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.5.0-beta.2",
+  "version": "0.5.0-beta.4",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "cloud",
   "setupComplete": false,

package/template/.flydocs/version

@@ -1 +1 @@
-0.5.0-beta.2
+0.5.0-beta.4

package/template/AGENTS.md

@@ -21,15 +21,15 @@ The development lifecycle follows seven stages:
 Capture → Refine → Activate → Implement → Review → Validate → Close
 ```
 
-| Stage | What Happens |
-|-------|--------------|
-| Capture | Create issue from input (feature, bug, chore, idea) |
-| Refine | Triage, fill template, set priority and estimate |
-| Activate | Assign to person, transition to In Progress |
+| Stage     | What Happens                                         |
+| --------- | ---------------------------------------------------- |
+| Capture   | Create issue from input (feature, bug, chore, idea)  |
+| Refine    | Triage, fill template, set priority and estimate     |
+| Activate  | Assign to person, transition to In Progress          |
 | Implement | Build incrementally, document decisions, self-review |
-| Review | Code quality check against acceptance criteria |
-| Validate | User acceptance testing, collect approval |
-| Close | Verify approval, mark as Done |
+| Review    | Code quality check against acceptance criteria       |
+| Validate  | User acceptance testing, collect approval            |
+| Close     | Verify approval, mark as Done                        |
 
 Detailed procedures: `.claude/skills/flydocs-workflow/`
 
@@ -43,10 +43,10 @@ Script location: `.claude/skills/flydocs-local/scripts/` or `.claude/skills/flyd
 
 ## Premium Skills
 
-| Skill | Documentation |
-|-------|---------------|
-| Figma Integration | `.claude/skills/flydocs-figma/` — design extraction, token mapping |
-| Cost Estimation | `.claude/skills/flydocs-estimates/` — AI token/labor estimates (opt-in) |
+| Skill             | Documentation                                                           |
+| ----------------- | ----------------------------------------------------------------------- |
+| Figma Integration | `.claude/skills/flydocs-figma/` — design extraction, token mapping      |
+| Cost Estimation   | `.claude/skills/flydocs-estimates/` — AI token/labor estimates (opt-in) |
 
 ## Writing Style
 
@@ -64,32 +64,48 @@ When writing or editing any copy — product docs, marketing pages, website copy
 - Don't repeat the same stat or claim more than once per page. Cross-page repetition is fine — readers land on individual pages.
 - When differentiating, name what the alternative does and where it falls short. Don't just assert we're better — show the specific gap.
 
+## Output Formatting
+
+Follow these rules in every response for consistent, scannable output.
+
+- Lead with a one-line summary before detail.
+- Use `##` for major sections, `###` for subsections. Never skip heading levels.
+- Bullet lists for 3+ related items. Numbered lists only for ordered sequences.
+- Bold status labels: **Completed**, **In Progress**, **Blocked**, **Next Up**.
+- Inline code for file paths, commands, identifiers: `project.md`, `/start-session`, `FLY-123`.
+- Code blocks with language tags for multi-line code.
+- Tables for structured comparisons (3+ items with 2+ attributes).
+- Keep paragraphs to 2-3 sentences. Break long blocks into scannable lists.
+- Dates in `YYYY-MM-DD` format. No emoji unless explicitly requested.
+
 ## 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/config.json`       | Configuration — tier, provider, labels, active projects |
 
 <!-- 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, Linear, cloud | .claude/skills/flydocs-cloud/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, Linear, cloud | .claude/skills/flydocs-cloud/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  |
+
 <!-- flydocs:skills-manifest:end -->
 
 ## Platform Configuration
 
-| Platform | Primary Config |
-|----------|----------------|
-| Claude Code | `.claude/CLAUDE.md` |
-| Cursor | `.cursor/rules/*.mdc` |
+| Platform                  | Primary Config          |
+| ------------------------- | ----------------------- |
+| Claude Code               | `.claude/CLAUDE.md`     |
+| Cursor                    | `.cursor/rules/*.mdc`   |
 | Codex / Windsurf / Others | This file (`AGENTS.md`) |

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.5.0-beta.2",
+  "version": "0.5.0-beta.4",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",