@flydocs/cli 0.6.0-alpha.32 → 0.6.0-alpha.34

package/package.json

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

package/template/.claude/CLAUDE.md

@@ -63,6 +63,32 @@ scripts in `flydocs-workflow/scripts/`. The unified client auto-detects tier
 | `flydocs/context/service.json` | Service descriptor, topology, cross-repo context  |
 | `.flydocs/config.json`         | Tier, provider, labels, active projects, topology |
 
+## Dev Override: skipPaths
+
+To prevent `flydocs sync` from overwriting paths you're actively developing,
+add `artifactOverrides.skipPaths` to `.flydocs/config.json`:
+
+```json
+{
+  "artifactOverrides": {
+    "skipPaths": [".claude/skills/flydocs-workflow/"]
+  }
+}
+```
+
+Paths listed here are excluded from artifact sync. This is CLI-local only —
+not stored on the server, not visible in the portal, and preserved across syncs.
+
+## Credentials (Cloud Tier)
+
+API keys are stored globally at `~/.flydocs/credentials`, written by:
+
+- `flydocs init` — interactive setup (recommended)
+- `flydocs auth` — set or update key directly
+
+Resolution order: `FLYDOCS_API_KEY` env var > `~/.flydocs/credentials` > `.env.local` (legacy).
+Never commit credentials to git.
+
 ## Hooks
 
 | Hook                       | Trigger                 | Purpose                                                    |

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

@@ -65,8 +65,9 @@ Count totals by status and type.
 
 **Step 3: Check for API readiness.**
 
-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.
+Check if an API key is available via environment variable (`FLYDOCS_API_KEY`),
+global credentials (`~/.flydocs/credentials`), or legacy `.env.local`. If not
+found, warn the user to run `flydocs init` or `flydocs auth` before Phase 1.
 
 **Step 4: Present migration summary.**
 

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

@@ -30,8 +30,9 @@ python3 .claude/skills/flydocs-workflow/scripts/workspace.py get-me
      ```
      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
+     Option A: Run `flydocs init` (interactive setup — recommended)
+     Option B: Run `flydocs auth` (set API key directly)
+     Option C: Set FLYDOCS_API_KEY in environment (CI/CD)
 
      Once set, run /onboard again.
      ```

package/template/.claude/skills/flydocs-workflow/scripts/flydocs_api.py

@@ -52,17 +52,17 @@ class RelayBackend:
         self.api_key = self._load_api_key()
         if not self.api_key:
             fail(
-                "FLYDOCS_API_KEY not found.\n"
-                "Checked: environment, .env.local, .env, .env.development, .env.production\n"
-                "To get your API key:\n"
-                "  1. Go to app.flydocs.ai → Settings → API Keys\n"
-                "  2. Generate a key (starts with fdk_)\n"
-                "  3. Add FLYDOCS_API_KEY=fdk_... to .env.local"
+                "FlyDocs API key not found.\n"
+                "Checked: environment, ~/.flydocs/credentials, .env.local (legacy)\n"
+                "To set up your API key:\n"
+                "  1. Run: flydocs init   (interactive setup)\n"
+                "  2. Or:  flydocs auth   (set key directly)\n"
+                "  3. CI/CD: set FLYDOCS_API_KEY environment variable"
             )
 
-        self.workspace_id = config.get("workspaceId")
+        self.workspace_id = self._resolve_workspace_id(config)
         if not self.workspace_id:
-            fail("workspaceId not found in .flydocs/config.json. Run 'flydocs setup'")
+            fail("workspaceId not found. Run 'flydocs init' to set up your workspace.")
 
         self.repo_slug = self._detect_repo_slug()
         self.base_url = self._resolve_base_url()
@@ -72,9 +72,21 @@ class RelayBackend:
         self.team_id = config.get("provider", {}).get("teamId")
 
     def _load_api_key(self) -> Optional[str]:
+        # 1. Environment variable (CI/CD override)
         if os.environ.get("FLYDOCS_API_KEY"):
             return os.environ["FLYDOCS_API_KEY"]
-        for name in [".env.local", ".env", ".env.development", ".env.production"]:
+        # 2. Global credential file (v2 — written by flydocs auth/init)
+        cred_file = Path.home() / ".flydocs" / "credentials"
+        if cred_file.exists():
+            try:
+                cred_data = json.loads(cred_file.read_text())
+                key = cred_data.get("apiKey") or cred_data.get("api_key")
+                if key:
+                    return key
+            except (json.JSONDecodeError, OSError):
+                pass
+        # 3. Legacy per-project env files (v1 fallback)
+        for name in [".env.local", ".env"]:
             env_file = self.project_root / name
             if env_file.exists():
                 key = self._parse_env_file(env_file, "FLYDOCS_API_KEY")
@@ -82,6 +94,23 @@ class RelayBackend:
                     return key
         return None
 
+    def _resolve_workspace_id(self, config: dict) -> Optional[str]:
+        # 1. Config file (v2 — written by flydocs init/sync)
+        ws_id = config.get("workspaceId")
+        if ws_id:
+            return ws_id
+        # 2. Global credential file (v2 fallback)
+        cred_file = Path.home() / ".flydocs" / "credentials"
+        if cred_file.exists():
+            try:
+                cred_data = json.loads(cred_file.read_text())
+                ws_id = cred_data.get("workspaceId")
+                if ws_id:
+                    return ws_id
+            except (json.JSONDecodeError, OSError):
+                pass
+        return None
+
     def _parse_env_file(self, path: Path, key: str) -> Optional[str]:
         with open(path, "r") as f:
             for line in f:

package/template/.env.example

@@ -22,12 +22,15 @@
 #
 
 # ===========================================
-# CLOUD TIER: FlyDocs API Key (Recommended)
+# CLOUD TIER: FlyDocs API Key
 # ===========================================
-# Use this if connecting via FlyDocs Cloud (managed relay).
-# Get from: your FlyDocs dashboard → API Keys
+# Recommended: Use global credentials (stored in ~/.flydocs/credentials):
+#   flydocs init   — interactive setup
+#   flydocs auth   — set key directly
+#
+# For CI/CD: Set FLYDOCS_API_KEY as an environment variable.
+# Legacy: Setting it here still works as a fallback.
 # Format: fdk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-# Set up with: flydocs connect
 FLYDOCS_API_KEY=
 
 # ===========================================

package/template/.flydocs/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.32",
+  "version": "0.6.0-alpha.34",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.32
+0.6.0-alpha.34

package/template/AGENTS.md

@@ -19,6 +19,16 @@ the work — do not wait for explicit commands.
 
 All scripts: `python3 .claude/skills/flydocs-workflow/scripts/<dispatcher>`
 
+## Credentials
+
+Cloud tier requires an API key. Resolution order:
+
+1. `FLYDOCS_API_KEY` environment variable (CI/CD)
+2. `~/.flydocs/credentials` (set by `flydocs init` or `flydocs auth`)
+3. `.env.local` (legacy fallback)
+
+If scripts fail with "API key not found", run `flydocs init` or `flydocs auth`.
+
 ## Efficiency
 
 Do NOT read skill files or workflow documentation before writing code.

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.32",
+  "version": "0.6.0-alpha.34",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",