@paradigma-inc/flywheel 0.2.32 → 0.2.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.2.32",
+  "version": "0.2.45",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [

package/skills/flywheel/SKILL.md

@@ -17,6 +17,7 @@ Use this skill when the conversation is about any of the following:
 - setting up, updating, authenticating, or troubleshooting Flywheel MCP
 - configuring hooks, hook secrets, and hook-run monitoring
 - managed compute, local hardware, campaigns, or Flywheel Web UI navigation
+- working in a local Flywheel repository (`repo:*` commands, `.flywheel/`, history, pull, conflicts, push) or administering a hosted repository: hand off to the `flywheel-repo` skill
 
 If the request is ambiguous, default to experiment-design guidance before platform mechanics.
 
@@ -50,6 +51,7 @@ Choose one primary file first, then add at most one supporting file only if need
 
 - `references/experiment-design-protocol.md` for structured experiment design and readiness checks
 - `references/flywheel-mcp-tool-map.md` (MCP) or `references/flywheel-cli-tool-map.md` (CLI) for exact tool surface and contract behavior in the matching install mode
+- the `flywheel-repo` skill for local-repository work (`repo:*`) and hosted repository ownership or membership (`hosted:repository:*`); this skill stays background only
 - `getting-started/flywheel-tutorial-overview.md` for orientation and learning path
 - `getting-started/flywheel-quickstart.md` for fastest first-use setup and auth recovery
 - `setting-up-flywheel/` for host-specific installation and update procedures

package/skills/flywheel/references/flywheel-cli-tool-map.md

@@ -2,7 +2,7 @@
 
 Contract-aligned routing guide for the Flywheel runtime CLI.
 
-The Flywheel CLI (`flywheel <command>`) is the runtime command surface shipped by `@paradigma-inc/flywheel`. It wraps the canonical Flywheel HTTP API and is the parallel surface to Flywheel MCP. Use this map when the host install is `--mode cli` (skills installed without an MCP server entry) or whenever scripted / direct-API workflows are preferable to MCP tool calls.
+The Flywheel CLI (`flywheel <command>`) is the runtime command surface shipped by `@paradigma-inc/flywheel`. `hosted:` and most other commands call the Flywheel HTTP API and are the parallel surface to Flywheel MCP; `repo:` commands work on a local repository on disk and touch the network only for `repo:clone`, `repo:pull`, `repo:push`, `repo:purge`, and `repo:artifact:download` (which fetches remote-only objects). Use this map when the host install is `--mode cli` (skills installed without an MCP server entry) or whenever scripted / direct-API workflows are preferable to MCP tool calls.
 
 For MCP routing, see `flywheel-mcp-tool-map.md`. The families below group related capabilities; CLI repository commands and MCP tools do not share the same staging or commit workflow.
 
@@ -17,6 +17,7 @@ Follow `flywheel-mcp-tool-map.md` for MCP-specific payload and lease workflows.
 - `repo:` and `hosted:` commands default to human output. Pass `--format=json` explicitly for scripts; other available formats are listed by command help.
 - Attach an artifact with `flywheel hosted:artifact:attach node <owner-id> --repository-id <uuid> --file <path> --metadata-file artifact.json --format=json`; the CLI prepares the upload, sends raw bytes, and commits the attachment.
 - Mutating commands are subject to per-user write limits: 120 node creates per minute, 2,000 node creates per 24 hours, and 120 graph writes per minute. Graph writes include existing-node commits, edge changes, deletes, merges, tags, sharing, artifact finalization, artifact deletion, and artifact-note updates. On `429`, honor `Retry-After` and retry the same idempotent command after waiting.
+- A `426 client_version_unsupported` or `repository_snapshot_format_unsupported` response means the installed client is incompatible. Run `flywheel update --yes`, retry the original command, and do not discard local state.
 - Run `flywheel help <command>` for canonical per-command flags, types, defaults, examples, and related commands.
 
 ## CLI Families and Related MCP Operations
@@ -49,15 +50,15 @@ The families below group CLI capabilities alongside related MCP tools. A related
 
 ### Hosted graph mutations and stage leases
 
-- `flywheel hosted:node:create` (mutating; scopes: `write`; MCP equivalent: `flywheel_commit_new_node`): Create a node in one hosted commit.
+- `flywheel hosted:node:create` (mutating; scopes: `write`; MCP equivalent: `flywheel_commit_new_node`): Create a node in the hosted repository named by `--repository-id`; this never selects a default workspace or creates another repository.
 - `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; MCP equivalent: `flywheel_acquire_stage_lease`): Acquire a session-scoped edit lease for an existing-node MCP staged-payload workflow, not local CLI `repo:` authoring or direct `hosted:` mutations.
 - `flywheel nodes:stage:lease:heartbeat` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; MCP equivalent: `flywheel_heartbeat_stage_lease`): Heartbeat an active node stage lease.
 - `flywheel nodes:stage:lease:release` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; MCP equivalent: `flywheel_release_stage_lease`): Release a node stage lease.
 - `flywheel hosted:node:set` (mutating; scopes: `write`; MCP equivalent: `flywheel_commit_node`): Set one node field in one hosted commit.
-- `flywheel hosted:node:branch` (mutating; scopes: `write`; MCP equivalent: `flywheel_branch_node`): Create a child branch in one hosted commit. Pass `--expected-head` when the caller must reject concurrent hosted changes.
-- `flywheel hosted:node:merge` (mutating; scopes: `write`; MCP equivalent: `flywheel_merge_nodes`): Merge repeated `--source` nodes into one node in one hosted commit.
-- `flywheel hosted:lineage:add` (mutating; scopes: `write`; MCP equivalent: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted commit.
-- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; MCP equivalent: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted commit.
+- `flywheel hosted:node:branch` (mutating; scopes: `write`; MCP equivalent: `flywheel_branch_node`): Create a child branch in the hosted repository named by `--repository-id`. Pass `--expected-head` when the caller must reject concurrent hosted changes.
+- `flywheel hosted:node:merge` (mutating; scopes: `write`; MCP equivalent: `flywheel_merge_nodes`): Merge repeated `--source` nodes into one node in the hosted repository named by `--repository-id`.
+- `flywheel hosted:lineage:add` (mutating; scopes: `write`; MCP equivalent: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted commit; include `--parent-repository-id` when the parent lives across a repository boundary.
+- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; MCP equivalent: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted commit; include `--parent-repository-id` for a cross-repository parent.
 - `flywheel hosted:node:tombstone` (mutating; scopes: `write`; MCP equivalent: `flywheel_delete_node`): Tombstone one node in one hosted commit.
 - There is no hosted bulk-tombstone command; run `flywheel hosted:node:tombstone` once per node.
 

package/skills/flywheel-auto/references/flywheel-cli-tool-map.md

@@ -18,6 +18,7 @@ The CLI has its own destination and commit lifecycle:
 - Every hosted graph mutation requires `--repository-id <uuid>`. For an associated local workspace, read `repository_id` from `flywheel repo:status --repo <path> --format=json`.
 - Node values, tag definitions, edge content, and artifact metadata use the file flags documented by each graph command.
 - `repo:` and `hosted:` commands default to human output. Pass `--format=json` explicitly for scripts; other available formats are listed by command help.
+- A `426 client_version_unsupported` or `repository_snapshot_format_unsupported` response means the installed client is incompatible. Run `flywheel update --yes`, retry the original command, and do not discard local state.
 - Run `flywheel help <command>` for canonical per-command flags, types, defaults, examples, and related commands.
 
 ## Related MCP Operations
@@ -50,15 +51,15 @@ The families below identify related MCP operations for discovery and terminology
 
 ### Hosted graph mutations and stage leases
 
-- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in one hosted repository commit; it is not an MCP staged-payload commit.
+- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in the hosted repository named by `--repository-id`; this never selects a default workspace or creates another repository.
 - `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; related MCP operation: `flywheel_acquire_stage_lease`): Acquire a session-scoped edit lease for an existing MCP node workflow.
 - `flywheel nodes:stage:lease:heartbeat` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; related MCP operation: `flywheel_heartbeat_stage_lease`): Heartbeat an active node stage lease.
 - `flywheel nodes:stage:lease:release` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; related MCP operation: `flywheel_release_stage_lease`): Release a node stage lease.
 - `flywheel hosted:node:set` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_node`): Set one node field in one hosted repository commit; it is not an MCP staged-payload commit.
-- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in one hosted repository commit. Pass `--expected-head` when the caller must reject concurrent hosted changes.
-- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes into one hosted repository commit.
-- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted repository commit.
-- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted repository commit.
+- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in the hosted repository named by `--repository-id`. Pass `--expected-head` when the caller must reject concurrent hosted changes.
+- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes in the hosted repository named by `--repository-id`.
+- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted commit; include `--parent-repository-id` when the parent lives across a repository boundary.
+- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted commit; include `--parent-repository-id` for a cross-repository parent.
 - `flywheel hosted:node:tombstone` (mutating; scopes: `write`; related MCP operation: `flywheel_delete_node`): Tombstone one node in one hosted repository commit.
 - There is no hosted bulk-tombstone command; run `flywheel hosted:node:tombstone` once per node.
 

package/skills/flywheel-llm-proof-paper/scripts/check_paper.py

@@ -206,7 +206,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     args = parser.parse_args(argv)
     try:
         report = run_check(Path(args.project).expanduser().resolve(), args)
-    except Exception as exc:
+    except (OSError, RuntimeError, ValueError, ET.ParseError) as exc:
         print(f"paper-llm-proof could not complete: {exc}", file=sys.stderr)
         return 3
 

package/skills/flywheel-lookahead/references/flywheel-cli-tool-map.md

@@ -18,6 +18,7 @@ The CLI has its own destination and commit lifecycle:
 - Every hosted graph mutation requires `--repository-id <uuid>`. For an associated local workspace, read `repository_id` from `flywheel repo:status --repo <path> --format=json`.
 - Node values, tag definitions, edge content, and artifact metadata use the file flags documented by each graph command.
 - `repo:` and `hosted:` commands default to human output. Pass `--format=json` explicitly for scripts; other available formats are listed by command help.
+- A `426 client_version_unsupported` or `repository_snapshot_format_unsupported` response means the installed client is incompatible. Run `flywheel update --yes`, retry the original command, and do not discard local state.
 - Run `flywheel help <command>` for canonical per-command flags, types, defaults, examples, and related commands.
 
 ## Related MCP Operations
@@ -50,15 +51,15 @@ The families below identify related MCP operations for discovery and terminology
 
 ### Hosted graph mutations and stage leases
 
-- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in one hosted repository commit; it is not an MCP staged-payload commit.
+- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in the hosted repository named by `--repository-id`; this never selects a default workspace or creates another repository.
 - `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; related MCP operation: `flywheel_acquire_stage_lease`): Acquire a session-scoped edit lease for an existing MCP node workflow.
 - `flywheel nodes:stage:lease:heartbeat` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; related MCP operation: `flywheel_heartbeat_stage_lease`): Heartbeat an active node stage lease.
 - `flywheel nodes:stage:lease:release` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; related MCP operation: `flywheel_release_stage_lease`): Release a node stage lease.
 - `flywheel hosted:node:set` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_node`): Set one node field in one hosted repository commit; it is not an MCP staged-payload commit.
-- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in one hosted repository commit. Pass `--expected-head` when the caller must reject concurrent hosted changes.
-- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes into one hosted repository commit.
-- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted repository commit.
-- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted repository commit.
+- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in the hosted repository named by `--repository-id`. Pass `--expected-head` when the caller must reject concurrent hosted changes.
+- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes in the hosted repository named by `--repository-id`.
+- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted commit; include `--parent-repository-id` when the parent lives across a repository boundary.
+- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted commit; include `--parent-repository-id` for a cross-repository parent.
 - `flywheel hosted:node:tombstone` (mutating; scopes: `write`; related MCP operation: `flywheel_delete_node`): Tombstone one node in one hosted repository commit.
 - There is no hosted bulk-tombstone command; run `flywheel hosted:node:tombstone` once per node.
 

package/skills/flywheel-prove/assets/pipeline_template/src/tproof/cli.py

@@ -1,6 +1,7 @@
 import shutil
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Annotated
 
 import typer
 from rich import print as rprint
@@ -137,7 +138,9 @@ def init(build: bool = typer.Option(True, "--build/--no-build")) -> None:
 
 
 @app.command("reindex")
-def reindex(project_dir: Path | None = typer.Option(None, "--project-dir")) -> None:
+def reindex(
+    project_dir: Annotated[Path | None, typer.Option("--project-dir")] = None,
+) -> None:
     paths = _paths()
     target = project_dir or paths.lean_project_dir
     all_proofs_path = reindex_allproofs(target)
@@ -146,10 +149,10 @@ def reindex(project_dir: Path | None = typer.Option(None, "--project-dir")) -> N
 
 @app.command("start-run")
 def start_run(
-    prompt_file: Path | None = typer.Option(None, "--prompt-file"),
-    prompt_text: str | None = typer.Option(None, "--prompt-text"),
-    run_label: str | None = typer.Option(None, "--run-label"),
-    context_file: Path | None = typer.Option(None, "--context-file"),
+    prompt_file: Annotated[Path | None, typer.Option("--prompt-file")] = None,
+    prompt_text: Annotated[str | None, typer.Option("--prompt-text")] = None,
+    run_label: Annotated[str | None, typer.Option("--run-label")] = None,
+    context_file: Annotated[Path | None, typer.Option("--context-file")] = None,
 ) -> None:
     paths = _paths()
     task_prompt = read_task_prompt(prompt_file=prompt_file, prompt_text=prompt_text)
@@ -220,7 +223,9 @@ def set_status(
 
 
 @app.command("verify")
-def verify(project_dir: Path | None = typer.Option(None, "--project-dir")) -> None:
+def verify(
+    project_dir: Annotated[Path | None, typer.Option("--project-dir")] = None,
+) -> None:
     paths = _paths()
     target = project_dir or paths.lean_project_dir
     code, output = lake_build(target)

package/skills/flywheel-prove/scripts/scaffold_pipeline.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """
 Scaffold a local Lean theorem proving pipeline into a target repository.
 """

package/skills/flywheel-repo/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: flywheel-repo
+description: "Work in a local Flywheel repository with the flywheel CLI: create or clone, stage, diff, commit, inspect history, pull, resolve conflicts, and, only when asked, push; plus hosted repository ownership and membership. Use for repo:* and hosted:repository:* tasks; use the flywheel skill for direct hosted repository writes, MCP, and setup."
+---
+
+# Flywheel Repository Skill
+
+A repository is one user's Flywheel project workspace: a graph of nodes with history. A local repository is the on-disk copy of that repository, rooted at a `.flywheel/` directory, with its own staging area and commit log; `repo:` commands operate on it. A hosted repository is the server-side copy that collaborators read through the web app, API, CLI, or MCP; `hosted:` commands change it directly. A staged change is a pending operation that a `repo:` mutation command saved in the local repository but that is not yet part of history. A local commit is the result of `repo:commit`: the staged changes become one entry in the local commit log, and nothing leaves the machine. A hosted commit is one entry in the hosted repository's history; `repo:push` turns local commits into hosted commits, and each `hosted:` mutation posts one hosted commit immediately.
+
+## Precondition
+
+Run `flywheel --help` first. If `flywheel` is not on `PATH`, use `npx --yes @paradigma-inc/flywheel` in place of `flywheel` for every command in this skill. If neither runs, stop and tell the user the CLI is not available; do not fall back to MCP tools or `hosted:` commands for local-repository work.
+
+## When To Use
+
+- the user wants to create, clone, inspect, edit, commit, back up, or repair a local Flywheel repository
+- the user asks about local history, staged work, a failed pull, a rebase, or conflicts
+- the user asks to publish local commits, or to list, transfer, retire, or change members of a hosted repository
+
+Not for: direct hosted node edits (`hosted:node:*`, `hosted:tag:*`, and every other `hosted:*` family except `hosted:repository:*`), MCP tools, setup, or authentication. Use the `flywheel` skill for those.
+
+## Rules
+
+- Flags are never listed here. Before running any command, run `flywheel help <command>`; use `flywheel help <command> --format=json` when you need to parse the output.
+- Select the local repository explicitly: a `--repo <path>` repository, an explicitly requested `--personal` repository, or a repository found from the current directory. If none is selected, stop and ask; never switch to `hosted:` commands instead.
+- Never run `flywheel repo:push` (with or without `--create-remote`) unless the user asked for or approved publication in this conversation. Staging and `repo:commit` never leave the machine.
+- A 426 `client_version_unsupported` or `repository_snapshot_format_unsupported` response is a client compatibility refusal, not a repository conflict. Run `flywheel update --yes`, retry the original command (snapshot-format negotiation applies only to clone and pull), and never discard local state to work around it.
+- `hosted:repository:transfer`, `hosted:repository:retire`, `hosted:repository:member:set`, and `hosted:repository:member:remove` change who owns or who can read a repository. Run one only on the user's explicit instruction for that exact change, and ask one direct confirmation question naming the repository and the change before running it. Never run one as a side effect of another task. `retire` is irreversible: every node in the repository stops being readable.
+- `repo:purge` and `repo:staging:discard` destroy data. State what will be lost and get the user's confirmation first.
+
+## Workflow
+
+Each phase names its commands only; look up flags with `flywheel help <command>`.
+
+1. Obtain a local repository: `repo:init` creates or adopts only the selected local repository, `repo:clone` reads an existing hosted projection v4 repository, and `repo:restore` reads a backup archive. Then run `repo:status` to confirm the repository is selected and healthy.
+2. Read before writing: `repo:node:get`, `repo:lineage:list`, `repo:tag:list`, `repo:edge:list`, `repo:edge:get`, `repo:containment:list`, `repo:containment:get`, and the artifact reads (`repo:artifact:get`, `repo:artifact:download`, `repo:node-artifact:list`, `repo:edge-artifact:list`). These default to committed local state; the staged option described in each command's help shows pending work instead. Lineage rows name `parent_repository_id`; `boundary:true` means the parent remains in another repository and is not a missing local node.
+3. Stage changes with the node, tag, relation, and artifact commands listed in the reference file. Every `repo:` mutation stages in the selected local repository; nothing is committed or placed in a different repository.
+4. Review with `repo:diff` (its staged option shows the complete pending result). Discard with `repo:staging:discard` only on request.
+5. Commit with `repo:commit`; the commit keeps its immutable author if another principal later pushes it. Inspect history with `repo:log`; undo a commit with `repo:revert`, which stages inverse operations for the reversible changes of that commit.
+6. Sync: `repo:pull` applies hosted history and atomically removes nodes that departed to a reported target repository. On ordinary conflicts, use `repo:conflicts:list`, `repo:conflicts:show`, and `repo:conflicts:resolve`, then `repo:rebase:continue` or `repo:rebase:abort`. Publish with `repo:push` only when requested; its create-remote option is for the first publication only, when the hosted repository does not exist yet (there is no `hosted:repository:create`). If a push fails with `repository_node_departed`, run `repo:recover-departed <current_repository_id> <directory> --repo <source-checkout>` to clone the current repository and replay the unpublished commits there; never redirect the old repository-bound push.
+7. Maintain: `repo:backup` before risky work, `repo:doctor` to diagnose availability or interrupted-sync problems, `repo:gc` to reclaim unreferenced artifact objects; `repo:purge` only on explicit request.
+8. Hosted repository administration: `hosted:repository:list`, `hosted:repository:head`, and `hosted:repository:members` are reads. `hosted:repository:member:set`, `hosted:repository:member:remove`, `hosted:repository:transfer`, and `hosted:repository:retire` follow the confirmation rule above.
+
+## Reference
+
+- [references/repository-commands.md](references/repository-commands.md): every `repo:*` and `hosted:repository:*` command with its summary, grouped by the phases above.
+- `flywheel help <command>`: flags, positionals, examples, and related commands.

package/skills/flywheel-repo/references/repository-commands.md

@@ -0,0 +1,104 @@
+# Flywheel Repository Commands
+
+Each line names a command and its summary; run `flywheel help <command>` (add `--format=json` for machine-readable output) for flags, positionals, examples, and related commands.
+
+## Commands by lifecycle phase
+
+### Create or obtain a local repository
+
+- `flywheel repo:init`: Initialize or adopt the selected local repository at a directory; this command does not choose a hosted default workspace or fork.
+- `flywheel repo:clone`: Clone a projection v4 hosted repository, including boundary-parent and cross-repository tag-scope identities, into a new local directory. If the server requires a newer client, run `flywheel update --yes` and retry.
+- `flywheel repo:restore`: Restore a verified backup archive into an empty directory.
+
+### Inspect state
+
+- `flywheel repo:status`: Show local repository status, including interrupted push or pull (interrupted_sync) and an unpublished hosted remote (stranded_remote). Rerun an interrupted command with the same --idempotency-key; stranded_remote names the existing repo:push recovery flow.
+- `flywheel repo:doctor`: Report local object availability disagreements and interrupted push or pull operations (interrupted_sync). Confirmed availability repair changes records only and refuses pending work.
+
+### Read committed or staged content
+
+- `flywheel repo:node:get`: Read one node and its comparison digests. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:tag:list`: List tags and holder digests. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:lineage:list`: List lineage relations with `parent_repository_id` and boundary status. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:node-artifact:list`: List node artifact references. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:edge-artifact:list`: List edge artifact references. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:artifact:get`: Read one artifact and its references. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:artifact:download`: Download current-head artifact bytes, fetching and caching a remote-only object when needed; requires --out.
+- `flywheel repo:containment:get`: Read active containment for one child. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:containment:list`: List active contained nodes. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:edge:list`: List semantic edges in one graph. Defaults to committed local state; use --staged to inspect saved pending work.
+- `flywheel repo:edge:get`: Read one semantic edge. Defaults to committed local state; use --staged to inspect saved pending work.
+
+### Stage changes (nodes)
+
+- `flywheel repo:node:create`: Stage a root node in the selected local repository from --title or the full six-field JSON values file; this command never creates or selects another repository.
+- `flywheel repo:node:set`: Stage a new value for one field of a node.
+- `flywheel repo:node:tombstone`: Stage the removal of a node; its history stays in the repository.
+- `flywheel repo:node:restore`: Stage the restoration of a tombstoned node.
+- `flywheel repo:node:branch`: Stage one branched node in the selected local repository and one lineage relation copying the source's title.
+- `flywheel repo:node:merge`: Stage one merged node in the selected local repository and one lineage relation from each supplied source, in argument order.
+
+### Stage changes (tags)
+
+- `flywheel repo:tag:define`: Stage a new tag definition under a scope node.
+- `flywheel repo:tag:update`: Stage a changed tag definition.
+- `flywheel repo:tag:retire`: Stage the retirement of a tag definition.
+- `flywheel repo:node-tag:assign`: Stage assigning a tag to a node.
+- `flywheel repo:node-tag:remove`: Stage removing a tag from a node.
+
+### Stage changes (relations)
+
+- `flywheel repo:lineage:add`: Stage a parent-child lineage relation between two nodes.
+- `flywheel repo:lineage:remove`: Stage the removal of a lineage relation.
+- `flywheel repo:containment:assign`: Stage placing a node inside a container node.
+- `flywheel repo:containment:remove`: Stage the removal of a containment relation.
+- `flywheel repo:edge:add`: Stage an edge between distinct descendants of a graph in this repository.
+- `flywheel repo:edge:set-content`: Stage new content for a semantic edge.
+- `flywheel repo:edge:remove`: Stage the removal of a semantic edge.
+
+### Stage changes (artifacts)
+
+- `flywheel repo:artifact:attach`: Stage an artifact attachment from --metadata-file or the inline --name/--media-type/--notes/--tags flags.
+- `flywheel repo:artifact:detach`: Stage detaching an artifact from its node or edge.
+- `flywheel repo:artifact:set-metadata`: Stage a replacement for exactly one artifact metadata field from --metadata-file or one inline flag.
+
+### Review and discard staged work
+
+- `flywheel repo:diff`: Show committed-history differences or the complete pending staged result.
+- `flywheel repo:staging:discard`: Discard all saved pending operations and associated values from only the selected local repository. Uncommitted work is not recoverable through graph history. Optional repo:backup preserves the batch, but restoring it does not repair invalid staging. No backup is required or created automatically; no export or network transfer occurs. Discard is never implicit in reads, edits, validation, failed commit, pull, push, revert, startup, migration, or upgrade.
+
+### Commit and history
+
+- `flywheel repo:commit`: Commit the exact current staging digest with its immutable author principal.
+- `flywheel repo:log`: List commits reachable from the local head, newest first.
+- `flywheel repo:revert`: Append inverse operations for a target commit's supported reversible changes; node/edge latest-value fields and the legacy artifact.metadata.set.v1 operation are not reversible and are skipped.
+
+### Sync with the hosted repository
+
+- `flywheel repo:pull`: Pull and atomically apply hosted history, preserving boundary references and removing departed nodes while reporting each `target_repository_id`. If the server requires a newer client, run `flywheel update --yes` and retry.
+- `flywheel repo:conflicts:list`: List structured rebase conflicts.
+- `flywheel repo:conflicts:show`: Show one structured conflict.
+- `flywheel repo:conflicts:resolve`: Resolve one structured conflict.
+- `flywheel repo:rebase:continue`: Continue one exact rebase.
+- `flywheel repo:rebase:abort`: Abort one exact rebase.
+- `flywheel repo:push`: Publish local commits to the hosted repository (use --create-remote for the first publication). `repository_node_departed` names `current_repository_id`; the push is never redirected.
+- `flywheel repo:recover-departed`: Clone `current_repository_id` and atomically replay the selected source checkout's unpublished commits there in one client-side follow-up.
+
+### Maintenance
+
+- `flywheel repo:backup`: Create and verify a local repository backup.
+- `flywheel repo:gc`: Delete local artifact objects that no commit, staging entry, or backup still references.
+- `flywheel repo:purge`: Permanently remove one node from the hosted repository and local history (irreversible; requires --confirm).
+
+### Hosted repository administration (reads)
+
+- `flywheel hosted:repository:list`: List hosted repositories where you hold a role.
+- `flywheel hosted:repository:head`: Show the published head of a hosted repository.
+- `flywheel hosted:repository:members`: List the collaborators of a hosted repository with their roles (owner or admin only).
+
+### Hosted repository administration (writes)
+
+- `flywheel hosted:repository:member:set`: Add a collaborator or change their role.
+- `flywheel hosted:repository:member:remove`: Remove a collaborator from a hosted repository.
+- `flywheel hosted:repository:transfer`: Transfer ownership of a hosted repository to another member; you remain admin.
+- `flywheel hosted:repository:retire`: Permanently retire a hosted repository (irreversible; the ID can never be reused). Local clones keep working offline but can no longer sync; publishing the graph again needs repo:init in a new directory plus a re-import under a new identity.

package/skills/flywheel-reproduce/references/flywheel-cli-tool-map.md

@@ -19,6 +19,7 @@ The CLI has its own destination and commit lifecycle:
 - Every hosted graph mutation requires `--repository-id <uuid>`. For an associated local workspace, read `repository_id` from `flywheel repo:status --repo <path> --format=json`.
 - Node values, tag definitions, edge content, and artifact metadata use the file flags documented by each graph command.
 - `repo:` and `hosted:` commands default to human output. Pass `--format=json` explicitly for scripts; other available formats are listed by command help.
+- A `426 client_version_unsupported` or `repository_snapshot_format_unsupported` response means the installed client is incompatible. Run `flywheel update --yes`, retry the original command, and do not discard local state.
 - Run `flywheel help <command>` for canonical per-command flags, types, defaults, examples, and related commands.
 
 ## Related MCP Operations
@@ -51,15 +52,15 @@ The families below identify related MCP operations for discovery and terminology
 
 ### Hosted graph mutations and stage leases
 
-- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in one hosted repository commit; it is not an MCP staged-payload commit.
+- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in the hosted repository named by `--repository-id`; this never selects a default workspace or creates another repository.
 - `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; related MCP operation: `flywheel_acquire_stage_lease`): Acquire a session-scoped edit lease for an existing MCP node workflow.
 - `flywheel nodes:stage:lease:heartbeat` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; related MCP operation: `flywheel_heartbeat_stage_lease`): Heartbeat an active node stage lease.
 - `flywheel nodes:stage:lease:release` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; related MCP operation: `flywheel_release_stage_lease`): Release a node stage lease.
 - `flywheel hosted:node:set` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_node`): Set one node field in one hosted repository commit; it is not an MCP staged-payload commit.
-- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in one hosted repository commit. Pass `--expected-head` when the caller must reject concurrent hosted changes.
-- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes into one hosted repository commit.
-- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted repository commit.
-- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted repository commit.
+- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in the hosted repository named by `--repository-id`. Pass `--expected-head` when the caller must reject concurrent hosted changes.
+- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes in the hosted repository named by `--repository-id`.
+- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted commit; include `--parent-repository-id` when the parent lives across a repository boundary.
+- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted commit; include `--parent-repository-id` for a cross-repository parent.
 - `flywheel hosted:node:tombstone` (mutating; scopes: `write`; related MCP operation: `flywheel_delete_node`): Tombstone one node in one hosted repository commit.
 - There is no hosted bulk-tombstone command; run `flywheel hosted:node:tombstone` once per node.
 

package/skills/flywheel-to-graph/references/flywheel-cli-tool-map.md

@@ -19,6 +19,7 @@ The CLI has its own destination and commit lifecycle:
 - Every hosted graph mutation requires `--repository-id <uuid>`. For an associated local workspace, read `repository_id` from `flywheel repo:status --repo <path> --format=json`.
 - Node values, tag definitions, edge content, and artifact metadata use the file flags documented by each graph command.
 - `repo:` and `hosted:` commands default to human output. Pass `--format=json` explicitly for scripts; other available formats are listed by command help.
+- A `426 client_version_unsupported` or `repository_snapshot_format_unsupported` response means the installed client is incompatible. Run `flywheel update --yes`, retry the original command, and do not discard local state.
 - Run `flywheel help <command>` for canonical per-command flags, types, defaults, examples, and related commands.
 
 ## Related MCP Operations
@@ -51,15 +52,15 @@ The families below identify related MCP operations for discovery and terminology
 
 ### Hosted graph mutations and stage leases
 
-- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in one hosted repository commit; it is not an MCP staged-payload commit.
+- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in the hosted repository named by `--repository-id`; this never selects a default workspace or creates another repository.
 - `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; related MCP operation: `flywheel_acquire_stage_lease`): Acquire a session-scoped edit lease for an existing MCP node workflow.
 - `flywheel nodes:stage:lease:heartbeat` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; related MCP operation: `flywheel_heartbeat_stage_lease`): Heartbeat an active node stage lease.
 - `flywheel nodes:stage:lease:release` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; related MCP operation: `flywheel_release_stage_lease`): Release a node stage lease.
 - `flywheel hosted:node:set` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_node`): Set one node field in one hosted repository commit; it is not an MCP staged-payload commit.
-- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in one hosted repository commit. Pass `--expected-head` when the caller must reject concurrent hosted changes.
-- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes into one hosted repository commit.
-- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted repository commit.
-- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted repository commit.
+- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in the hosted repository named by `--repository-id`. Pass `--expected-head` when the caller must reject concurrent hosted changes.
+- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes in the hosted repository named by `--repository-id`.
+- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted commit; include `--parent-repository-id` when the parent lives across a repository boundary.
+- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted commit; include `--parent-repository-id` for a cross-repository parent.
 - `flywheel hosted:node:tombstone` (mutating; scopes: `write`; related MCP operation: `flywheel_delete_node`): Tombstone one node in one hosted repository commit.
 - There is no hosted bulk-tombstone command; run `flywheel hosted:node:tombstone` once per node.
 

package/skills/flywheel-tree/scripts/render_tree.py

@@ -13,10 +13,12 @@ Output:
 from __future__ import annotations
 
 import argparse
+import io
 import json
 import sys
+from collections.abc import Iterable, Iterator
 from pathlib import Path
-from typing import Any, Dict, Iterable, Iterator, List, NamedTuple, Set, Tuple
+from typing import Any, NamedTuple
 
 DEFAULT_COLORS = [
     "\u001b[94m",
@@ -52,8 +54,8 @@ BOX_SPACE = "    "
 class Node(NamedTuple):
     title: str
     slug_name: str
-    parent_ids: Tuple[str, ...]
-    child_ids: Tuple[str, ...]
+    parent_ids: tuple[str, ...]
+    child_ids: tuple[str, ...]
 
 
 def _normalize_ansi(value: str) -> str:
@@ -92,7 +94,7 @@ def _read_json_from_path(path: str) -> dict:
     return _extract_tree_payload(payload)
 
 
-def _load_palette(asset_path: Path) -> tuple[List[str], str]:
+def _load_palette(asset_path: Path) -> tuple[list[str], str]:
     if not asset_path.exists():
         return DEFAULT_COLORS, DEFAULT_RESET
 
@@ -123,8 +125,8 @@ def _clean_text(value: Any) -> str:
     return value.strip() if isinstance(value, str) else ""
 
 
-def _build_node_map(nodes_payload: Iterable[dict]) -> Dict[str, Node]:
-    node_map: Dict[str, Node] = {}
+def _build_node_map(nodes_payload: Iterable[dict]) -> dict[str, Node]:
+    node_map: dict[str, Node] = {}
 
     for raw in nodes_payload:
         if not isinstance(raw, dict):
@@ -159,11 +161,11 @@ def _build_node_map(nodes_payload: Iterable[dict]) -> Dict[str, Node]:
 
 
 def _collect_descendants(
-    anchor_node_id: str, node_map: Dict[str, Node]
-) -> tuple[Set[str], List[str]]:
-    descendants: Set[str] = set()
-    order: List[str] = []
-    stack: List[str] = [anchor_node_id]
+    anchor_node_id: str, node_map: dict[str, Node]
+) -> tuple[set[str], list[str]]:
+    descendants: set[str] = set()
+    order: list[str] = []
+    stack: list[str] = [anchor_node_id]
 
     while stack:
         current = stack.pop()
@@ -176,8 +178,7 @@ def _collect_descendants(
 
         descendants.add(current)
         order.append(current)
-        for child_id in reversed(node.child_ids):
-            stack.append(child_id)
+        stack.extend(reversed(node.child_ids))
 
     return descendants, order
 
@@ -218,8 +219,8 @@ def _iter_render_lines(
     if anchor not in descendants:
         raise ValueError(f"Could not build descendant subgraph for anchor '{anchor}'.")
 
-    retained_children: Dict[str, Tuple[str, ...]] = {}
-    multi_parent_nodes: List[str] = []
+    retained_children: dict[str, tuple[str, ...]] = {}
+    multi_parent_nodes: list[str] = []
 
     for node_id in ordered_descendants:
         node = node_map[node_id]
@@ -239,13 +240,13 @@ def _iter_render_lines(
         _load_palette(palette_path) if palette_path else (DEFAULT_COLORS, DEFAULT_RESET)
     )
 
-    multi_parent_color: Dict[str, str] = {}
+    multi_parent_color: dict[str, str] = {}
     for idx, node_id in enumerate(multi_parent_nodes):
         multi_parent_color[node_id] = colors[idx % len(colors)]
 
-    seen_multi_parent: Dict[str, int] = {node_id: 0 for node_id in multi_parent_nodes}
-    ancestry: Set[str] = set()
-    expanded_nodes: Set[str] = set()
+    seen_multi_parent: dict[str, int] = {node_id: 0 for node_id in multi_parent_nodes}
+    ancestry: set[str] = set()
+    expanded_nodes: set[str] = set()
 
     def line_for(node_id: str) -> str:
         node = node_map[node_id]
@@ -274,7 +275,7 @@ def _iter_render_lines(
         return rendered
 
     # Iterative DFS avoids RecursionError on very deep trees.
-    stack: List[Tuple[Any, ...]] = [("enter", anchor, "", True, True)]
+    stack: list[tuple[Any, ...]] = [("enter", anchor, "", True, True)]
 
     while stack:
         frame = stack.pop()
@@ -365,10 +366,8 @@ def main() -> int:
         print(f"render_tree.py error: {exc}", file=sys.stderr)
         return 1
 
-    try:
-        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
-    except Exception:  # noqa: BLE001
-        pass
+    if isinstance(sys.stdout, io.TextIOWrapper):
+        sys.stdout.reconfigure(encoding="utf-8")
 
     wrote_any = False
     for line in rendered_lines: