@flydocs/cli 0.6.0-alpha.11 → 0.6.0-alpha.12

package/dist/cli.js

@@ -15,7 +15,7 @@ var CLI_VERSION, CLI_NAME, PACKAGE_NAME, POSTHOG_API_KEY;
 var init_constants = __esm({
   "src/lib/constants.ts"() {
     "use strict";
-    CLI_VERSION = "0.6.0-alpha.11";
+    CLI_VERSION = "0.6.0-alpha.12";
     CLI_NAME = "flydocs";
     PACKAGE_NAME = "@flydocs/cli";
     POSTHOG_API_KEY = "phc_v1MSJTQDFkMS90CBh3mxIz3v8bYCCnKU6v1ir6bz0Xn";
@@ -294,6 +294,7 @@ function extractPreservedValues(config) {
     tier: config.tier,
     setupComplete: config.setupComplete ?? false,
     workspaceId: config.workspaceId ?? null,
+    configVersion: config.configVersion,
     workspace: config.workspace ?? {},
     issueLabels: config.issueLabels ?? {},
     detectedStack: config.detectedStack ?? {},
@@ -312,6 +313,9 @@ async function mergeConfig(templateDir, version, tierFlag, preserved) {
   config.tier = tierFlag ?? preserved.tier;
   config.setupComplete = preserved.setupComplete;
   config.workspaceId = preserved.workspaceId;
+  if (preserved.configVersion !== void 0) {
+    config.configVersion = preserved.configVersion;
+  }
   if (Object.keys(preserved.workspace).length > 0) {
     config.workspace = preserved.workspace;
   }
@@ -1523,6 +1527,8 @@ var init_gitignore = __esm({
       ".flydocs/session.json",
       ".flydocs/logs/",
       ".flydocs/backup-*/",
+      ".flydocs/me.json",
+      ".flydocs/validation-cache.json",
       "flydocs/context/graph.json"
     ];
     FULL_GITIGNORE_TEMPLATE = `# Environment
@@ -1534,6 +1540,8 @@ var init_gitignore = __esm({
 .flydocs/session.json
 .flydocs/logs/
 .flydocs/backup-*/
+.flydocs/me.json
+.flydocs/validation-cache.json
 flydocs/context/graph.json
 
 # Dependencies
@@ -2881,6 +2889,7 @@ var init_update = __esm({
           tier: "cloud",
           setupComplete: false,
           workspaceId: null,
+          configVersion: void 0,
           workspace: {},
           issueLabels: {},
           detectedStack: {},

package/package.json

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

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

@@ -470,17 +470,38 @@ Ask about product metadata:
   from project.md)
 - **Icon and color** — optional, ask if they have preferences
 
-**Step 8: Save to config.**
+**Step 8: Generate config from relay.**
 
-Update `.flydocs/config.json`:
+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:
 
-- `provider.type` — set by `set_provider.py`
-- `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`)
-- `statusMapping` — FlyDocs-to-provider status mapping (set by `set_status_mapping.py`)
-- `workspace.activeProjects` — add the project ID
-- `workspace.product.name` — product name
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/generate_config.py
+```
+
+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.
+
+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.
+
+**Step 9: Fetch user identity.**
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/get_me.py
+```
+
+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.
 
 ---
 
@@ -677,9 +698,14 @@ 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
+`generate_config.py` 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 `validate_setup.py` 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 }

package/template/.claude/skills/flydocs-cloud/SKILL.md

@@ -59,26 +59,29 @@ All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
 
 ### Workspace Scripts
 
-| Script                  | Usage                                                                 | Output                                                                                                         |
-| ----------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `list_providers.py`     | (no args)                                                             | `[{type, name, connected}]`                                                                                    |
-| `set_provider.py`       | `<provider_type>` (`linear` or `jira`)                                | `{success}` — updates relay routing and local config `provider.type`                                           |
-| `list_teams.py`         | (no args)                                                             | `[{id, name, key}]` — returns Linear teams or Jira projects (relay normalizes)                                 |
-| `create_team.py`        | `--name "..." [--key KEY] [--description "..."] [--parent <team_id>]` | `{id, name, key}` — `--parent` is Linear-only (sub-teams)                                                      |
-| `set_team.py`           | `<team_id>`                                                           | `{success}` — updates relay preference and local config; for Jira, sets the active Jira project                |
-| `list_labels.py`        | (no args)                                                             | `[{id, name, color}]` — requires team to be set first                                                          |
-| `set_labels.py`         | `--defaults '["a"]' --type-map '{"feature":["F"],...}' \| stdin`      | `{success, validated, defaults, typeMap}` — stores label config on relay                                       |
-| `list_statuses.py`      | (no args)                                                             | `{states, currentMapping, flydocsStatuses}` — provider workflow states and current mapping                     |
-| `set_status_mapping.py` | `--auto \| --mapping '{"BACKLOG":"Backlog",...}' \| stdin`            | `{success, mapping, matched, total}` — stores status mapping on relay                                          |
-| `set_identity.py`       | `<provider> <provider-user-id>`                                       | `{success, provider, providerId}` — binds provider user ID for `--mine` resolution                             |
-| `set_preferences.py`    | `[--workspace ID] [--assignee self\|ID] [--display JSON]`             | `{success, preferences}` — no flags = GET current; with flags = POST update                                    |
-| `get_estimate_scale.py` | (no args)                                                             | `{scale, type}` — provider's valid estimate values (fixed or freeform)                                         |
-| `refresh_labels.py`     | `[--fix]`                                                             | `{valid, stale, details}` — validates config label IDs against relay; `--fix` updates stale IDs                |
-| `validate_setup.py`     | (no args)                                                             | `{valid, checks, passed[], missing[], warnings[]}` — reads relay validation, caches result, sets setupComplete |
+| Script                  | Usage                                                                 | Output                                                                                                                |
+| ----------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `list_providers.py`     | (no args)                                                             | `[{type, name, connected}]`                                                                                           |
+| `set_provider.py`       | `<provider_type>` (`linear` or `jira`)                                | `{success}` — updates relay routing (no local config write)                                                           |
+| `list_teams.py`         | (no args)                                                             | `[{id, name, key}]` — returns Linear teams or Jira projects (relay normalizes)                                        |
+| `create_team.py`        | `--name "..." [--key KEY] [--description "..."] [--parent <team_id>]` | `{id, name, key}` — `--parent` is Linear-only (sub-teams)                                                             |
+| `set_team.py`           | `<team_id>`                                                           | `{success}` — updates relay preference (no local config write); for Jira, sets the active Jira project                |
+| `list_labels.py`        | (no args)                                                             | `[{id, name, color}]` — requires team to be set first                                                                 |
+| `set_labels.py`         | `--defaults '["a"]' --type-map '{"feature":["F"],...}' \| stdin`      | `{success, validated, defaults, typeMap}` — stores label config on relay                                              |
+| `list_statuses.py`      | (no args)                                                             | `{states, currentMapping, flydocsStatuses}` — provider workflow states and current mapping                            |
+| `set_status_mapping.py` | `--auto \| --mapping '{"BACKLOG":"Backlog",...}' \| stdin`            | `{success, mapping, matched, total}` — stores status mapping on relay                                                 |
+| `set_identity.py`       | `<provider> <provider-user-id>`                                       | `{success, provider, providerId, meJson}` — binds provider user ID for `--mine` resolution; writes `.flydocs/me.json` |
+| `set_preferences.py`    | `[--workspace ID] [--assignee self\|ID] [--display JSON]`             | `{success, preferences}` — no flags = GET current; with flags = POST update                                           |
+| `get_estimate_scale.py` | (no args)                                                             | `{scale, type}` — provider's valid estimate values (fixed or freeform)                                                |
+| `refresh_labels.py`     | `[--fix]`                                                             | `{valid, stale, details}` — validates config label IDs against relay; `--fix` updates stale IDs                       |
+| `generate_config.py`    | `[--dry-run]`                                                         | `{success, configVersion, valid, missing[], warnings[]}` — pulls server config, merges with local, writes config.json |
+| `get_me.py`             | (no args)                                                             | `{success, displayName, email, provider, meJson}` — fetches user identity, writes `.flydocs/me.json` (no workspace)   |
+| `validate_setup.py`     | (no args)                                                             | `{valid, checks, passed[], missing[], warnings[]}` — reads relay validation, caches result, sets setupComplete        |
 
 ### Script Notes
 
 - **How it works**: Scripts call the FlyDocs Relay REST API, which translates to the provider (Linear, Jira) server-side. Same interface and output as before — the transport changed from direct GraphQL to managed REST. For Jira, the relay handles Markdown-to-ADF (Atlassian Document Format) conversion automatically.
+- **Config cascade**: Setup scripts (`set_provider`, `set_team`, `set_labels`, `set_status_mapping`) only POST to the relay — they do not write local config. After all setup steps, run `generate_config.py` to pull the canonical server config and merge with local-only fields. This eliminates ghost fields and ensures config.json stays in sync with the relay.
 - **`list_issues.py --active`**: Returns all non-terminal issues (excludes Done, Archived, Canceled, Duplicate).
 - **`list_issues.py --status`**: Accepts comma-separated statuses: `--status READY,IMPLEMENTING,BLOCKED`
 - **`get_issue.py --fields basic`**: Skips comment fetch for faster responses.

package/template/.claude/skills/flydocs-cloud/scripts/generate_config.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Generate config.json from the relay's canonical workspace config.
+
+Calls GET /config/generate which returns server-owned fields (workspace,
+issueLabels, provider, statusMapping, etc.). Merges with local-only fields
+(tier, detectedStack, skills, designSystem, aiLabor, paths) to produce
+the final .flydocs/config.json.
+
+This replaces the pattern where each setup script (set_provider, set_team,
+set_labels, set_status_mapping) independently wrote to local config.
+Now those scripts only POST to the relay, and this script pulls the
+merged result once at the end of setup.
+
+Usage:
+    python3 generate_config.py
+    python3 generate_config.py --dry-run   # Print merged config without writing
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+# Fields owned by the server — overwritten from generate response
+SERVER_OWNED_FIELDS = {
+    "workspaceId",
+    "setupComplete",
+    "workspace",
+    "issueLabels",
+}
+
+# Fields owned locally — never overwritten by generate
+LOCAL_ONLY_FIELDS = {
+    "version",
+    "sourceRepo",
+    "tier",
+    "paths",
+    "detectedStack",
+    "skills",
+    "designSystem",
+    "aiLabor",
+}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate config from relay")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print merged config without writing to disk",
+    )
+    args = parser.parse_args()
+
+    client = get_client()
+
+    # Fetch server-owned config from relay
+    response = client.get("/config/generate")
+
+    if not response.get("valid", False):
+        missing = response.get("missing", [])
+        warnings = response.get("warnings", [])
+        parts = []
+        if missing:
+            parts.append(f"missing: {', '.join(missing)}")
+        if warnings:
+            parts.append(f"warnings: {', '.join(warnings)}")
+        detail = "; ".join(parts) if parts else "unknown reason"
+        print(f"WARNING: Config not fully valid — {detail}", file=sys.stderr)
+
+    server_config = response.get("config", {})
+
+    # Read existing local config
+    config_path = client.config_path
+    if config_path.exists():
+        with open(config_path, "r") as f:
+            local_config = json.load(f)
+    else:
+        local_config = {}
+
+    # Merge: server-owned fields overwrite, local-only fields preserved
+    merged = dict(local_config)
+
+    # Apply server-owned fields
+    if "workspaceId" in server_config:
+        merged["workspaceId"] = server_config["workspaceId"]
+    if "setupComplete" in server_config:
+        merged["setupComplete"] = server_config["setupComplete"]
+    if "workspace" in server_config:
+        merged["workspace"] = server_config["workspace"]
+    if "issueLabels" in server_config:
+        merged["issueLabels"] = server_config["issueLabels"]
+
+    # Store configVersion for freshness tracking
+    if "configVersion" in response:
+        merged["configVersion"] = response["configVersion"]
+
+    # Clean up ghost fields that are now server-owned
+    # These were written by old setup scripts but aren't in the TS type system
+    for ghost in ("provider", "statusMapping", "labels"):
+        merged.pop(ghost, None)
+
+    if args.dry_run:
+        output_json(merged)
+        return
+
+    # Write merged config
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "w") as f:
+        json.dump(merged, f, indent=2)
+        f.write("\n")
+
+    output_json({
+        "success": True,
+        "configVersion": response.get("configVersion"),
+        "valid": response.get("valid", False),
+        "missing": response.get("missing", []),
+        "warnings": response.get("warnings", []),
+    })
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-cloud/scripts/get_me.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Fetch current user identity from the FlyDocs Relay API.
+
+Calls GET /auth/me (no X-Workspace needed — user-scoped endpoint).
+Writes .flydocs/me.json for local identity resolution (--mine filters,
+display name in comments, etc.). This file is gitignored.
+
+Usage:
+    python3 get_me.py
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import find_project_root, output_json, fail
+
+
+def load_api_key(project_root: Path) -> str | None:
+    """Load API key from environment or .env files."""
+    if os.environ.get("FLYDOCS_API_KEY"):
+        return os.environ["FLYDOCS_API_KEY"]
+    for name in [".env.local", ".env"]:
+        env_file = project_root / name
+        if env_file.exists():
+            with open(env_file, "r") as f:
+                for line in f:
+                    line = line.strip()
+                    if line.startswith("#") or "=" not in line:
+                        continue
+                    k, _, v = line.partition("=")
+                    if k.strip() == "FLYDOCS_API_KEY":
+                        v = v.strip().strip("\"'")
+                        return v if v else None
+    return None
+
+
+def resolve_base_url() -> str:
+    """Resolve relay base URL from environment."""
+    env_url = os.environ.get("FLYDOCS_RELAY_URL")
+    if env_url:
+        return env_url.rstrip("/")
+    return "https://app.flydocs.ai/api/relay"
+
+
+def main() -> None:
+    import urllib.request
+    import urllib.error
+
+    project_root = find_project_root()
+    api_key = load_api_key(project_root)
+    if not api_key:
+        fail("FLYDOCS_API_KEY not found. Set in environment or .env/.env.local file")
+
+    base_url = resolve_base_url()
+    url = f"{base_url}/auth/me"
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Accept": "application/json",
+    }
+
+    try:
+        req = urllib.request.Request(url, headers=headers, method="GET")
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode("utf-8") if e.fp else ""
+        try:
+            error_data = json.loads(error_body)
+        except json.JSONDecodeError:
+            error_data = {"error": error_body}
+        fail(f"API error ({e.code}): {error_data.get('error', 'Unknown')}")
+    except (urllib.error.URLError, TimeoutError):
+        fail("Network error: unable to reach relay API")
+
+    # Write me.json
+    me_data = {
+        "displayName": result.get("displayName"),
+        "email": result.get("email"),
+        "providerId": result.get("providerId"),
+        "provider": result.get("provider"),
+        "providerIdentities": result.get("providerIdentities", []),
+        "preferences": result.get("preferences", {}),
+    }
+
+    me_path = project_root / ".flydocs" / "me.json"
+    me_path.parent.mkdir(parents=True, exist_ok=True)
+    me_path.write_text(json.dumps(me_data, indent=2) + "\n")
+
+    output_json({
+        "success": True,
+        "displayName": me_data["displayName"],
+        "email": me_data["email"],
+        "provider": me_data["provider"],
+        "meJson": str(me_path),
+    })
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-cloud/scripts/set_identity.py

@@ -3,8 +3,12 @@
 
 Binds the user's provider-specific ID to their FlyDocs user record.
 Once set, ?mine=true resolves via exact provider ID matching.
+
+Also writes .flydocs/me.json for local identity resolution (e.g. --mine
+in list_issues.py). This file is gitignored — each developer has their own.
 """
 
+import json
 import sys
 from pathlib import Path
 
@@ -31,8 +35,20 @@ result = client.post("/auth/identity", {
     "providerId": provider_id,
 })
 
-output_json({
-    "success": result.get("success", True),
+# Write me.json for local identity resolution
+me_data = {
     "provider": result.get("provider", provider),
     "providerId": result.get("providerId", provider_id),
+    "displayName": result.get("displayName"),
+    "email": result.get("email"),
+}
+me_path = Path(".flydocs/me.json")
+me_path.parent.mkdir(parents=True, exist_ok=True)
+me_path.write_text(json.dumps(me_data, indent=2) + "\n")
+
+output_json({
+    "success": result.get("success", True),
+    "provider": me_data["provider"],
+    "providerId": me_data["providerId"],
+    "meJson": str(me_path),
 })

package/template/.claude/skills/flydocs-cloud/scripts/set_labels.py

@@ -47,20 +47,6 @@ def main():
 
     client = get_client()
     result = client.post("/auth/labels", body)
-
-    # Store label config in local config as reference
-    config_path = client.config_path
-    if config_path.exists():
-        with open(config_path, "r") as f:
-            config = json.load(f)
-        config["labels"] = {
-            "defaults": body.get("defaults", []),
-            "typeMap": body.get("typeMap", {}),
-        }
-        with open(config_path, "w") as f:
-            json.dump(config, f, indent=2)
-            f.write("\n")
-
     output_json(result)
 
 

package/template/.claude/skills/flydocs-cloud/scripts/set_provider.py

@@ -1,12 +1,11 @@
 #!/usr/bin/env python3
 """Set provider preference via the FlyDocs Relay API.
 
-Stores the provider type on the relay (for server-side routing)
-and updates the local config (for display/reference).
+Stores the provider type on the relay for server-side routing.
+Local config is updated by generate_config.py after all setup steps complete.
 """
 
 import argparse
-import json
 import sys
 from pathlib import Path
 
@@ -25,20 +24,6 @@ def main():
 
     client = get_client()
     result = client.post("/auth/provider", {"providerType": args.provider_type})
-
-    # Update local config with provider type
-    config_path = client.config_path
-    if config_path.exists():
-        with open(config_path, "r") as f:
-            config = json.load(f)
-        if "provider" not in config:
-            config["provider"] = {"type": args.provider_type, "teamId": None}
-        else:
-            config["provider"]["type"] = args.provider_type
-        with open(config_path, "w") as f:
-            json.dump(config, f, indent=2)
-            f.write("\n")
-
     output_json(result)
 
 

package/template/.claude/skills/flydocs-cloud/scripts/set_status_mapping.py

@@ -50,18 +50,6 @@ def main():
 
     client = get_client()
     result = client.post("/auth/statuses", body)
-
-    # Store status mapping in local config as reference
-    config_path = client.config_path
-    if config_path.exists():
-        with open(config_path, "r") as f:
-            config = json.load(f)
-        if isinstance(result.get("mapping"), dict):
-            config["statusMapping"] = result["mapping"]
-        with open(config_path, "w") as f:
-            json.dump(config, f, indent=2)
-            f.write("\n")
-
     output_json(result)
 
 

package/template/.claude/skills/flydocs-cloud/scripts/set_team.py

@@ -1,13 +1,12 @@
 #!/usr/bin/env python3
 """Set team/project preference via the FlyDocs Relay API.
 
-Stores the team preference on the relay (for server-side scoping)
-and updates the local config (for display/reference).
+Stores the team preference on the relay for server-side scoping.
+Local config is updated by generate_config.py after all setup steps complete.
 For Jira, this sets the active Jira project.
 """
 
 import argparse
-import json
 import sys
 from pathlib import Path
 
@@ -22,19 +21,6 @@ def main():
 
     client = get_client()
     result = client.post("/auth/team", {"teamId": args.team_id})
-
-    # Update local config with team ID
-    config_path = client.config_path
-    if config_path.exists():
-        with open(config_path, "r") as f:
-            config = json.load(f)
-        if "provider" not in config:
-            config["provider"] = {"type": None, "teamId": None}
-        config["provider"]["teamId"] = args.team_id
-        with open(config_path, "w") as f:
-            json.dump(config, f, indent=2)
-            f.write("\n")
-
     output_json(result)
 
 

package/template/.claude/skills/flydocs-local/scripts/list_issues.py

@@ -12,6 +12,22 @@ from flydocs_api import list_issues
 
 TERMINAL_STATUSES = {"COMPLETE", "ARCHIVED", "CANCELED", "DUPLICATE"}
 
+
+def resolve_identity() -> str:
+    """Resolve current user identity from me.json, falling back to $USER."""
+    me_path = Path(".flydocs/me.json")
+    if me_path.exists():
+        try:
+            me = json.loads(me_path.read_text())
+            # Prefer displayName for local file matching, fall back to email
+            name = me.get("displayName") or me.get("email") or ""
+            if name:
+                return name
+        except (json.JSONDecodeError, OSError):
+            pass
+    return os.environ.get("USER", os.environ.get("USERNAME", ""))
+
+
 parser = argparse.ArgumentParser(description="List issues")
 parser.add_argument("--status", default="")
 parser.add_argument("--active", action="store_true",
@@ -24,7 +40,7 @@ try:
     args = parser.parse_args()
     assignee = args.assignee
     if args.mine:
-        assignee = os.environ.get("USER", os.environ.get("USERNAME", ""))
+        assignee = resolve_identity()
     result = list_issues(status=args.status.upper() if args.status else "", assignee=assignee, limit=args.limit)
     if args.active:
         result = [r for r in result if r.get("status") not in TERMINAL_STATUSES]

package/template/.flydocs/config.json

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

package/template/.flydocs/hooks/prompt-submit.py

@@ -205,6 +205,43 @@ def get_setup_nudge() -> str | None:
     return None
 
 
+def get_config_freshness_nudge() -> str | None:
+    """Nudge if validation cache is stale (>24h old).
+
+    Only applies to cloud tier with setupComplete=true. Encourages
+    periodic re-validation so config stays in sync with the server.
+    """
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+    try:
+        config = json.loads(config_file.read_text())
+        # Only check freshness for cloud tier with completed setup
+        if config.get('tier') != 'cloud' or config.get('setupComplete') is not True:
+            return None
+
+        cache_file = Path('.flydocs/validation-cache.json')
+        if not cache_file.exists():
+            return '[Config not validated — run: python3 .claude/skills/flydocs-cloud/scripts/validate_setup.py]'
+
+        from datetime import datetime, timezone
+        cache = json.loads(cache_file.read_text())
+        timestamp_str = cache.get('timestamp')
+        if not timestamp_str:
+            return None
+
+        # Parse ISO timestamp
+        cached_at = datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
+        now = datetime.now(timezone.utc)
+        age_hours = (now - cached_at).total_seconds() / 3600
+
+        if age_hours > 24:
+            return '[Config stale (>24h) — run: python3 .claude/skills/flydocs-cloud/scripts/validate_setup.py]'
+    except (json.JSONDecodeError, OSError, IOError, ValueError):
+        pass
+    return None
+
+
 def main() -> None:
     """Main hook execution."""
     debug_log('=== Hook invoked ===')
@@ -268,10 +305,14 @@ def main() -> None:
     if ac_progress:
         context_parts.append(ac_progress)
 
-    # Setup completion nudge
+    # Setup completion nudge OR config freshness nudge (mutually exclusive)
     setup_nudge = get_setup_nudge()
     if setup_nudge:
         context_parts.append(setup_nudge)
+    else:
+        freshness_nudge = get_config_freshness_nudge()
+        if freshness_nudge:
+            context_parts.append(freshness_nudge)
 
     # FlyDocs version
     version = get_flydocs_version()

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.11
+0.6.0-alpha.12

package/template/manifest.json

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