@flydocs/cli 0.6.0-alpha.23 → 0.6.0-alpha.26

package/package.json

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

package/template/.claude/hooks/session-start.py

@@ -84,7 +84,17 @@ def get_active_issue_context() -> str | None:
 
 
 def get_config_freshness() -> str | None:
-    """Warn if validation cache is stale or missing."""
+    """Warn if validation cache is stale or missing (v1 configs)."""
+    # v2 configs use get_config_freshness_v2() instead
+    config_file = Path('.flydocs/config.json')
+    if config_file.exists():
+        try:
+            config = json.loads(config_file.read_text())
+            if config.get('configFormat') == 2:
+                return None  # Skip v1 check for v2 configs
+        except (json.JSONDecodeError, OSError):
+            pass
+
     cache_file = Path('.flydocs/validation-cache.json')
     if not cache_file.exists():
         return None
@@ -102,6 +112,104 @@ def get_config_freshness() -> str | None:
     return None
 
 
+def get_config_freshness_v2() -> str | None:
+    """Check config freshness via config/check endpoint (v2 configs only, FLY-540)."""
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+
+    try:
+        config = json.loads(config_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    if config.get('configFormat') != 2 or config.get('tier') != 'cloud':
+        return None
+
+    # Resolve API key: env var > global credentials
+    api_key = os.environ.get('FLYDOCS_API_KEY')
+    if not api_key:
+        cred_file = Path.home() / '.flydocs' / 'credentials'
+        if cred_file.exists():
+            try:
+                cred = json.loads(cred_file.read_text())
+                api_key = cred.get('apiKey')
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    if not api_key:
+        return None
+
+    # Call config/check — lightweight, ~50ms
+    base_url = os.environ.get('FLYDOCS_RELAY_URL', 'https://app.flydocs.ai/api/relay').rstrip('/')
+    try:
+        import urllib.request
+        req = urllib.request.Request(
+            f'{base_url}/config/check',
+            headers={
+                'Authorization': f'Bearer {api_key}',
+                'Accept': 'application/json',
+            },
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read().decode('utf-8'))
+    except Exception:
+        # Server unreachable — silently continue, never block a session
+        return None
+
+    if data.get('needsSync'):
+        stale_fields: list[str] = []
+        local_config_version = config.get('configVersion', 0)
+        if data.get('configVersion', 0) > local_config_version:
+            stale_fields.append('config')
+        if data.get('templateVersion', 0) > 0:
+            stale_fields.append('templates')
+        if data.get('contextVersion', 0) > 0:
+            stale_fields.append('context')
+        detail = f' ({", ".join(stale_fields)})' if stale_fields else ''
+        return f'Config updated{detail} — run `flydocs sync`'
+
+    return None
+
+
+def check_skills_manifest() -> str | None:
+    """Alert-mode skills manifest validation (FLY-541)."""
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+
+    try:
+        config = json.loads(config_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    expected = config.get('skills', {}).get('installed', [])
+    if not expected:
+        return None
+
+    skills_dir = Path('.claude/skills')
+    if not skills_dir.is_dir():
+        return f'Skills directory missing — run `flydocs sync`'
+
+    # Check for installed directories
+    try:
+        installed = {d.name for d in skills_dir.iterdir() if d.is_dir()}
+    except OSError:
+        return None
+
+    expected_set = set(expected)
+    missing = expected_set - installed
+    unexpected = installed - expected_set
+
+    warnings: list[str] = []
+    if missing:
+        warnings.append(f'Missing skills: {", ".join(sorted(missing))} — run `flydocs sync`')
+    if unexpected:
+        warnings.append(f'Unexpected skills: {", ".join(sorted(unexpected))}')
+
+    return ' | '.join(warnings) if warnings else None
+
+
 def main() -> None:
     """Main hook execution."""
     try:
@@ -129,6 +237,14 @@ def main() -> None:
     if freshness:
         parts.append(freshness)
 
+    freshness_v2 = get_config_freshness_v2()
+    if freshness_v2:
+        parts.append(freshness_v2)
+
+    skills_warning = check_skills_manifest()
+    if skills_warning:
+        parts.append(skills_warning)
+
     if not parts:
         print('{}')
         sys.exit(0)

package/template/.claude/skills/flydocs-workflow/reference/service-descriptor-schema.md

@@ -14,13 +14,14 @@ The service descriptor serves two roles from a single file:
   where things are: entry points, shared types, build system, package boundaries.
   Not exported cross-repo.
 
-Generated by the user's coding agent during `/flydocs-setup` Phase 1.5.
+Generated by the user's coding agent during `/flydocs-setup` Phase 1.5, or by the
+server-side AI scanning pipeline (v2).
 
 ## Schema
 
 ```typescript
 interface ServiceDescriptor {
-  version: 1;
+  version: 1 | 2;
   name: string; // Human-readable service name
   repoSlug: string; // owner/repo format (matches workspace.repoSlug)
   purpose: string; // One-sentence description of what this service does
@@ -32,6 +33,10 @@ interface ServiceDescriptor {
 
   // Intra-repo orientation (what THIS repo's agent uses)
   structure: ServiceStructure;
+
+  // v2 fields (present when version is 2, optional for backward compat)
+  generatedBy?: "server" | "agent"; // Who generated this descriptor
+  generatedAt?: string; // ISO 8601 timestamp of generation
 }
 
 interface ApiSurface {
@@ -63,12 +68,16 @@ interface PackageInfo {
 
 ## Field Notes
 
-- `version` is always `1`. Will increment on breaking schema changes.
+- `version` is `1` (agent-generated, legacy) or `2` (supports server generation).
+  All consumers accept both versions. The v2 fields are additive — v1 descriptors
+  remain valid and fully functional.
 - `repoSlug` must match the slug registered in the workspace dashboard.
 - `structure` is local-only — not pushed to relay or included in workspace composite.
 - `apis` and `dependencies` create PROVIDES/CONSUMES edges in the graph.
 - `stack` is a flat array of lowercase identifiers (framework names, languages).
-- Agent scans the codebase to populate all fields during setup Phase 1.5.
+- `generatedBy` distinguishes server-generated (AI scanning pipeline) from
+  agent-generated (local `/flydocs-setup`) descriptors. Absent on v1 descriptors.
+- `generatedAt` tracks freshness for server-generated descriptors. ISO 8601 format.
 
 ## Examples
 

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

@@ -219,7 +219,7 @@ def scan_service_descriptor(root):
     except (json.JSONDecodeError, OSError):
         return nodes, edges
 
-    if data.get("version") != 1:
+    if data.get("version") not in (1, 2):
         return nodes, edges
 
     repo_slug = data.get("repoSlug", "")
@@ -290,7 +290,7 @@ def scan_sibling_descriptors(root):
         except (json.JSONDecodeError, OSError):
             continue
 
-        if data.get("version") != 1:
+        if data.get("version") not in (1, 2):
             continue
 
         repo_slug = data.get("repoSlug", "")

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

@@ -50,8 +50,8 @@ CHECK_MESSAGES: dict[str, str] = {
     "statusMapping": "Status mapping not configured — configure in FlyDocs dashboard",
     "labelConfig": "Label config not configured — configure in FlyDocs dashboard",
     "userIdentity": (
-        "Provider identity not linked — run: "
-        "python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-identity <provider> <id>"
+        "Provider identity not linked — link your identity in the FlyDocs dashboard "
+        "profile page, or run: workspace.py set-identity <provider> <your-account-id>"
     ),
     "repos": "No repos linked — GitHub features won't work until you push and link a repo",
 }
@@ -115,6 +115,39 @@ def _check_integrity(client: "FlyDocsClient") -> dict:
     }
 
 
+def _try_auto_resolve_identity(client: "FlyDocsClient") -> bool:
+    """Attempt to auto-resolve provider identity via get-me. Returns True if resolved."""
+    try:
+        result = client.relay.get("/auth/me")
+    except Exception:
+        return False
+
+    provider_id = result.get("providerId")
+    if not provider_id:
+        # Check providerIdentities array as fallback
+        identities = result.get("providerIdentities", [])
+        if identities:
+            provider_id = identities[0].get("providerId")
+
+    if not provider_id:
+        return False
+
+    # Write me.json
+    me_data = {
+        "displayName": result.get("displayName"),
+        "email": result.get("email"),
+        "providerId": provider_id,
+        "provider": result.get("provider"),
+        "providerIdentities": result.get("providerIdentities", []),
+        "preferences": result.get("preferences", {}),
+    }
+
+    me_path = client.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")
+    return True
+
+
 def cmd_validate(args: argparse.Namespace) -> None:
     """Validate workspace setup via GET /auth/config."""
     client = get_client()
@@ -126,6 +159,15 @@ def cmd_validate(args: argparse.Namespace) -> None:
     missing_keys: list[str] = config_response.get("missing", [])
     warning_keys: list[str] = config_response.get("warnings", [])
 
+    # Auto-resolve identity if missing — try get-me before requiring manual step
+    if "userIdentity" in missing_keys or "userIdentity" in warning_keys:
+        if _try_auto_resolve_identity(client):
+            missing_keys = [k for k in missing_keys if k != "userIdentity"]
+            warning_keys = [k for k in warning_keys if k != "userIdentity"]
+            # Re-check validity — if userIdentity was the only missing item, we're valid now
+            if not missing_keys:
+                is_valid = True
+
     # Build structured missing/warning lists with messages
     missing = [
         {"check": k, "action": CHECK_MESSAGES.get(k, DEFAULT_MESSAGE)}

package/template/.flydocs/config.json

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

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.23
+0.6.0-alpha.26

package/template/CHANGELOG.md

@@ -7,6 +7,22 @@ Versioning: [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.6.0-alpha.24] — 2026-03-30
+
+### Added
+
+- **Auto-resolve provider identity** — `workspace.py validate` now attempts
+  `GET /auth/me` before requiring manual `set-identity` step. If the relay
+  returns a provider identity, `me.json` is written automatically (FLY-520)
+
+### Changed
+
+- **Friendlier identity fallback** — when auto-resolve fails, the validation
+  message now points to the dashboard profile page instead of showing a raw
+  script command
+
+---
+
 ## [0.6.0-alpha.23] — 2026-03-29
 
 ### Changed

package/template/manifest.json

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