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

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.13";
     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;
   }
@@ -1482,8 +1486,9 @@ async function ensureGitignore(targetDir) {
 async function migrateGitignore(targetDir) {
   const gitignorePath = join11(targetDir, ".gitignore");
   if (!await pathExists(gitignorePath)) return;
-  const content = await readFile6(gitignorePath, "utf-8");
-  if (!content.includes("flydocs/context/graph.json")) {
+  let content = await readFile6(gitignorePath, "utf-8");
+  for (const entry of FLYDOCS_GITIGNORE_ENTRIES) {
+    if (content.includes(entry)) continue;
     if (content.includes("# FlyDocs")) {
       const lines = content.split("\n");
       const flyDocsIdx = lines.findIndex((l) => l.trim() === "# FlyDocs");
@@ -1492,23 +1497,22 @@ async function migrateGitignore(targetDir) {
         while (insertIdx < lines.length && lines[insertIdx].trim() !== "" && !lines[insertIdx].startsWith("#")) {
           insertIdx++;
         }
-        lines.splice(insertIdx, 0, "flydocs/context/graph.json");
-        await writeFile4(gitignorePath, lines.join("\n"), "utf-8");
+        lines.splice(insertIdx, 0, entry);
+        content = lines.join("\n");
+        await writeFile4(gitignorePath, content, "utf-8");
       } else {
-        await appendFile(
-          gitignorePath,
-          "\nflydocs/context/graph.json\n",
-          "utf-8"
-        );
+        content += `
+${entry}
+`;
+        await writeFile4(gitignorePath, content, "utf-8");
       }
     } else {
-      await appendFile(
-        gitignorePath,
-        "\nflydocs/context/graph.json\n",
-        "utf-8"
-      );
+      content += `
+${entry}
+`;
+      await writeFile4(gitignorePath, content, "utf-8");
     }
-    printStatus("Added flydocs/context/graph.json to .gitignore");
+    printStatus(`Added ${entry} to .gitignore`);
   }
 }
 var FLYDOCS_GITIGNORE_ENTRIES, FULL_GITIGNORE_TEMPLATE;
@@ -1523,6 +1527,9 @@ var init_gitignore = __esm({
       ".flydocs/session.json",
       ".flydocs/logs/",
       ".flydocs/backup-*/",
+      ".flydocs/me.json",
+      ".flydocs/validation-cache.json",
+      ".flydocs/session/",
       "flydocs/context/graph.json"
     ];
     FULL_GITIGNORE_TEMPLATE = `# Environment
@@ -1534,6 +1541,9 @@ var init_gitignore = __esm({
 .flydocs/session.json
 .flydocs/logs/
 .flydocs/backup-*/
+.flydocs/me.json
+.flydocs/validation-cache.json
+.flydocs/session/
 flydocs/context/graph.json
 
 # Dependencies
@@ -2881,6 +2891,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.13",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {

package/template/.claude/CLAUDE.md

@@ -115,13 +115,14 @@ response — session summaries, issue comments, status updates, and plans.
 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, cloud                                    | .claude/skills/flydocs-cloud/SKILL.md     |
-| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                                                          | .claude/skills/flydocs-context7/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, knowledge, document, PR, pull request | .claude/skills/flydocs-workflow/SKILL.md  |
+| Skill                 | Triggers                                                                                                                                           | Entry                                         |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| flydocs-cloud         | create issue, transition, comment, list issues, assign, update description, update issue, project update, cloud                                    | .claude/skills/flydocs-cloud/SKILL.md         |
+| flydocs-context7      | context7, library docs, documentation lookup, framework docs, package docs, API reference                                                          | .claude/skills/flydocs-context7/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-context-graph | context graph, knowledge graph, relationships, dependencies, architecture                                                                          | .claude/skills/flydocs-context-graph/SKILL.md |
+| flydocs-workflow      | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue, knowledge, document, PR, pull request | .claude/skills/flydocs-workflow/SKILL.md      |
 
 <!-- flydocs:skills-manifest:end -->

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-context-graph/SKILL.md

@@ -16,9 +16,15 @@ triggers:
 
 # Context Graph
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
-knowledge navigation. Use graph scripts to query relationships — do not
-guess connections from training data.
+On-demand query layer for structural relationships in the project knowledge
+graph. Use graph scripts to explore dependencies, impact, and cross-references
+between skills, ADRs, issues, and sessions.
+
+The graph is **not** auto-injected into prompts. The prompt hook reads
+lightweight orientation files directly (`.flydocs/session/last-summary.json`,
+`flydocs/context/project.md`). Use the graph scripts below when you need
+deeper structural queries — relationship traversal, impact analysis, or
+dependency chains.
 
 ## Key Rules
 
@@ -32,16 +38,16 @@ guess connections from training data.
 
 All scripts: `python3 .claude/skills/flydocs-context-graph/scripts/<script>`
 
-| Script | Usage | Output |
-|--------|-------|--------|
-| `graph_build.py` | `[--root PATH]` | Rebuild graph from skills, ADRs. Writes `graph.json` |
-| `graph_query.py` | `--node ID [--depth N] [--rel TYPE] [--reverse] [--format json\|md]` | Context block (markdown or JSON) |
-| `graph_update.py` | `add-node ID --type TYPE [--label STR] [--path STR]` | `{success, node}` |
-| | `remove-node ID` | `{success, removed}` |
-| | `add-edge FROM TO REL [--weight N] [--manual]` | `{success, edge}` |
-| | `remove-edge FROM TO REL` | `{success, removed}` |
-| `graph_context.py` | `[--issue REF] [--branch NAME]` | Plain text context block for prime hook |
-| `graph_session.py` | `--summary "..." [--issue REF]... [--decision NNN]...` | `{success, sessionId, edges[]}` |
+| Script             | Usage                                                                | Output                                               |
+| ------------------ | -------------------------------------------------------------------- | ---------------------------------------------------- |
+| `graph_build.py`   | `[--root PATH]`                                                      | Rebuild graph from skills, ADRs. Writes `graph.json` |
+| `graph_query.py`   | `--node ID [--depth N] [--rel TYPE] [--reverse] [--format json\|md]` | Context block (markdown or JSON)                     |
+| `graph_update.py`  | `add-node ID --type TYPE [--label STR] [--path STR]`                 | `{success, node}`                                    |
+|                    | `remove-node ID`                                                     | `{success, removed}`                                 |
+|                    | `add-edge FROM TO REL [--weight N] [--manual]`                       | `{success, edge}`                                    |
+|                    | `remove-edge FROM TO REL`                                            | `{success, removed}`                                 |
+| `graph_context.py` | `[--issue REF] [--branch NAME]`                                      | Plain text context block for prime hook              |
+| `graph_session.py` | `--summary "..." [--issue REF]... [--decision NNN]...`               | `{success, sessionId, edges[]}`                      |
 
 ### Script Notes
 
@@ -52,36 +58,37 @@ All scripts: `python3 .claude/skills/flydocs-context-graph/scripts/<script>`
   returns more context but may be noisy.
 - **`graph_query.py --reverse`**: Follow edges in reverse direction (who points to this node?).
 - **`graph_update.py --manual`**: Mark edge as manually added (preserved on rebuild).
-- **`graph_context.py`**: Called by the prime hook automatically. Assembles compressed
+- **`graph_context.py`**: Available for manual queries. Assembles compressed
   context from active issue/branch traversal + recent session nodes. ~200-400 tokens max.
+  Not called automatically by the prompt hook (replaced by direct file reads in v0.6.0).
 - **`graph_session.py`**: Called during session wrap. Creates a session node with
   WORKED_ON edges to issues. Session nodes older than 30 days get reduced weight;
   nodes within 7 days get full weight.
 
 ## Node Types
 
-| Type | ID Pattern | Source |
-|------|-----------|--------|
-| `skill` | `skill:{name}` | SKILL.md frontmatter |
-| `decision` | `decision:{number}` | ADR directory |
-| `issue` | `issue:{identifier}` | Issue tracker |
-| `module` | `module:{name}` | Manual |
-| `session` | `session:{date-seq}` | Session wrap |
-| `concept` | `concept:{name}` | Manual |
+| Type       | ID Pattern           | Source               |
+| ---------- | -------------------- | -------------------- |
+| `skill`    | `skill:{name}`       | SKILL.md frontmatter |
+| `decision` | `decision:{number}`  | ADR directory        |
+| `issue`    | `issue:{identifier}` | Issue tracker        |
+| `module`   | `module:{name}`      | Manual               |
+| `session`  | `session:{date-seq}` | Session wrap         |
+| `concept`  | `concept:{name}`     | Manual               |
 
 ## Edge Types
 
-| Relationship | Meaning |
-|-------------|---------|
-| `EXTENDS` | Builds on, refines |
-| `IMPLEMENTS` | Realizes in code/config |
-| `DELEGATES_TO` | Hands off execution |
-| `PRECEDES` | Should load/execute before |
-| `MODIFIES` | Changes/affects |
-| `WORKED_ON` | Session activity |
-| `PRODUCED` | Created as output |
-| `RELATES_TO` | General association |
-| `SUPERSEDES` | Replaces |
-| `BLOCKS` | Prevents progress |
+| Relationship   | Meaning                    |
+| -------------- | -------------------------- |
+| `EXTENDS`      | Builds on, refines         |
+| `IMPLEMENTS`   | Realizes in code/config    |
+| `DELEGATES_TO` | Hands off execution        |
+| `PRECEDES`     | Should load/execute before |
+| `MODIFIES`     | Changes/affects            |
+| `WORKED_ON`    | Session activity           |
+| `PRODUCED`     | Created as output          |
+| `RELATES_TO`   | General association        |
+| `SUPERSEDES`   | Replaces                   |
+| `BLOCKS`       | Prevents progress          |
 
 For full schema details, see `schema.md`.

package/template/.claude/skills/flydocs-context-graph/scripts/graph_session.py

@@ -35,15 +35,6 @@ from graph_utils import (
 DEFAULT_RETENTION_DAYS = 30
 
 
-def generate_session_id(session_date):
-    """Generate a session ID like session:2026-02-17-a.
-
-    If a session with the same date exists, increment the sequence letter.
-    """
-    base = f"session:{session_date}"
-    return base
-
-
 def find_next_session_id(graph, session_date):
     """Find the next available session ID for a given date."""
     nodes = graph.get("nodes", {})

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/.claude/skills/flydocs-workflow/session.md

@@ -4,23 +4,32 @@
 
 When a conversation begins or the user returns after a gap:
 
-1. **Fetch all product issues in one call** — Run `list_issues.py --active --limit 100`.
+1. **Query graph for issue context** (if an issue ID is known from the prompt or last session) —
+
+   ```
+   python3 .claude/skills/flydocs-context-graph/scripts/graph_query.py --node <issue-id> --depth 2
+   ```
+
+   This surfaces related decisions, blocking relationships, and recent session activity.
+   Skip silently if the script is not installed or the graph has not been built.
+
+2. **Fetch all product issues in one call** — Run `list_issues.py --active --limit 100`.
    This is auto-scoped by the product cascade: `activeProjects` → `product.labelIds` → team-wide.
    Issues outside the product scope are never shown.
 
-2. **Identify the active project** — Read `workspace.activeProjects` from config.
+3. **Identify the active project** — Read `workspace.activeProjects` from config.
    Separate issues into two buckets:
    - **Active project issues** — issues whose `projectId` matches an active project
    - **Other product issues** — issues in the product scope but in a different project
 
-3. **Group active project issues by milestone** — Use the `milestone` and `milestoneSortOrder`
+4. **Group active project issues by milestone** — Use the `milestone` and `milestoneSortOrder`
    fields returned by the script. Sort milestones by `milestoneSortOrder` (lowest first = earliest).
    Within each milestone, group by status.
 
-4. **Identify the current milestone** — The first milestone (by sort order) that still has
+5. **Identify the current milestone** — The first milestone (by sort order) that still has
    open issues. This is where work should focus.
 
-5. **Present the dashboard:**
+6. **Present the dashboard:**
 
    ```
    Welcome back! [Product Name] status:
@@ -43,21 +52,21 @@ When a conversation begins or the user returns after a gap:
    Suggested starting point: [ISSUE-ID] — [reason: highest priority in current milestone / unblocks others / due soon]
    ```
 
-6. **Suggest where to start** — Use this priority cascade:
+7. **Suggest where to start** — Use this priority cascade:
    - Blocked issues that need unblocking (always surface first)
    - In-progress issues (continue existing work)
    - Due date approaching (within 7 days)
    - Highest priority in the current milestone
    - Issues that unblock downstream milestones
 
-7. **Surface other product issues briefly** — If there are issues in the product scope
+8. **Surface other product issues briefly** — If there are issues in the product scope
    but outside the active project, mention the count with a one-line summary:
 
    ```
    Also in [Product Name]: [N] issues across other projects (use --all to see)
    ```
 
-8. **Check for stale issues** — Flag issues exceeding staleness thresholds (see below).
+9. **Check for stale issues** — Flag issues exceeding staleness thresholds (see below).
 
 **Important:** Do NOT make separate API calls per status or per milestone. One call returns
 all issues with their status and milestone fields — group them in your response.
@@ -79,7 +88,23 @@ When the user indicates they're done for the session:
 3. **Compose summary** using the template below.
 4. **Determine health status** — See health table.
 5. **Post project update** — `project_update.py` with health and summary body.
-6. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
+6. **Write last-summary.json** — Write `.flydocs/session/last-summary.json` for cross-session continuity.
+   Create the directory if it doesn't exist. Structure:
+
+   ```json
+   {
+     "timestamp": "ISO-8601 (e.g. 2026-03-20T17:30:00Z)",
+     "issues": ["FLY-XXX", "FLY-YYY"],
+     "pending": ["description of incomplete work"],
+     "blockers": ["any blockers, or empty array"],
+     "notes": "free-form session summary"
+   }
+   ```
+
+   Populate from the session data gathered in step 1. Use the Write tool or a script — the file
+   must exist on disk so the prompt hook can read it on the next session start.
+
+7. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
    ```
    python3 .claude/skills/flydocs-context-graph/scripts/graph_session.py \
        --summary "Brief summary of session outcomes" \
@@ -87,8 +112,8 @@ When the user indicates they're done for the session:
        [--decision NNN]
    ```
    This creates a session node for cross-session continuity. Skip silently if the script is not installed.
-7. **Verify** — Confirm the project update was posted (update ID returned).
-8. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
+8. **Verify** — Confirm the project update was posted (update ID returned).
+9. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
 
 Do not just summarize in chat. Actually post the update. Do not skip if the user seems in a hurry.
 

package/template/.claude/skills/flydocs-workflow/stages/activate.md

@@ -23,12 +23,18 @@ When user asks "what should I work on?":
 
 ### Activation (specific issue)
 
-1. **Read full issue** — Load description and acceptance criteria.
-2. **Determine assignee** — MANDATORY. Ask "Who should this be assigned to?" if unclear. This is a hard gate.
-3. **Assign** — `assign.py` with user identifier. If assignment fails, STOP. Do not continue.
-4. **Set metadata** — Priority and estimate if not already set.
-5. **Transition** — `transition.py` to Implementing with Activate comment from `reference/comment-templates.md`.
-6. **Verify** — Confirm state = In Progress and assignee set.
+1. **Query graph for blocking relationships** — Check for blockers before proceeding:
+   ```
+   python3 .claude/skills/flydocs-context-graph/scripts/graph_query.py --node <issue-id> --relationships BLOCKS,BLOCKED_BY
+   ```
+   If blocking relationships exist, surface them to the user before continuing.
+   Skip silently if the script is not installed or the graph has not been built.
+2. **Read full issue** — Load description and acceptance criteria.
+3. **Determine assignee** — MANDATORY. Ask "Who should this be assigned to?" if unclear. This is a hard gate.
+4. **Assign** — `assign.py` with user identifier. If assignment fails, STOP. Do not continue.
+5. **Set metadata** — Priority and estimate if not already set.
+6. **Transition** — `transition.py` to Implementing with Activate comment from `reference/comment-templates.md`.
+7. **Verify** — Confirm state = In Progress and assignee set.
 
 **Sequence matters:** Assign → metadata → transition. Never transition without an assignee.
 

package/template/.flydocs/config.json

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

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

@@ -129,31 +129,53 @@ def get_workflow_reminder(status: str) -> str | None:
     return reminders.get(status)
 
 
-def get_graph_context(issue_id: str | None, branch: str | None) -> str | None:
-    """Get context graph output for the current session."""
-    graph_script = Path('.claude/skills/flydocs-context-graph/scripts/graph_context.py')
-    if not graph_script.exists():
-        return None
+def get_orientation_context() -> str | None:
+    """Read lightweight orientation files directly (no subprocess).
 
-    try:
-        cmd = ['python3', str(graph_script)]
-        if issue_id:
-            cmd.extend(['--issue', issue_id])
-        if branch:
-            cmd.extend(['--branch', branch])
+    Replaces the old get_graph_context() which shelled out to graph_context.py.
+    graph_context.py still exists for manual use — we just don't call it from
+    the prompt hook anymore.
+    """
+    parts = []
 
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            timeout=5
-        )
-        if result.returncode == 0 and result.stdout.strip():
-            return result.stdout.strip()
-    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
-        pass
+    # 1. Previous session continuity
+    summary_file = Path('.flydocs/session/last-summary.json')
+    if summary_file.exists():
+        try:
+            data = json.loads(summary_file.read_text())
+            pending = data.get('pending', [])
+            blockers = data.get('blockers', [])
+            issues = data.get('issues', [])
+            bits = []
+            if issues:
+                bits.append(f'issues={",".join(issues)}')
+            if pending:
+                bits.append(f'pending={len(pending)}')
+            if blockers:
+                bits.append(f'blockers={len(blockers)}')
+            if bits:
+                parts.append(f'Last session: {", ".join(bits)}')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
 
-    return None
+    # 2. Product context (first ~10 lines)
+    project_file = Path('flydocs/context/project.md')
+    if project_file.exists():
+        try:
+            lines = project_file.read_text().splitlines()[:10]
+            # Extract title line (first non-empty, non-heading-marker line)
+            for line in lines:
+                stripped = line.strip().lstrip('#').strip()
+                if stripped:
+                    parts.append(f'Product: {stripped}')
+                    break
+        except (OSError, IOError):
+            pass
+
+    if not parts:
+        return None
+
+    return ' | '.join(parts)
 
 
 def get_flydocs_version() -> str | None:
@@ -205,6 +227,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 +327,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()
@@ -286,11 +349,11 @@ def main() -> None:
         debug_log(f'Outputting plain text context: {context}')
         print(context)
 
-    # Graph context (appended as separate block below status line)
-    graph_context = get_graph_context(issue_id, branch)
-    if graph_context:
-        debug_log(f'Graph context: {graph_context[:100]}...')
-        print(graph_context)
+    # Orientation context (lightweight file reads, no subprocess)
+    orientation = get_orientation_context()
+    if orientation:
+        debug_log(f'Orientation context: {orientation[:100]}...')
+        print(orientation)
 
     debug_log('=== Hook completed successfully ===')
     sys.exit(0)

package/template/.flydocs/version

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

package/template/manifest.json

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