@paradigma-inc/flywheel 0.1.115 → 0.1.134

package/skills/flywheel-prove/references/workflow.md

@@ -3,10 +3,12 @@
 ## 0. Prerequisite: Local Toolchain Bootstrap
 
 Ensure the host has:
+
 - `uv`
 - `elan` (Lean toolchain manager)
 
 If `uv` is missing, install it by OS:
+
 - macOS/Linux:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -17,6 +19,7 @@ If `uv` is missing, install it by OS:
   ```
 
 If `elan` is missing, install it by OS:
+
 - macOS/Linux:
   ```bash
   curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh -s -- -y
@@ -39,12 +42,13 @@ lake --version
 ## 1. Scaffold Pipeline Into Repo
 
 ```bash
-python <skill-root>/scripts/scaffold_pipeline.py --repo-root <repo-root> --setup-env
+uv run --no-project <skill-root>/scripts/scaffold_pipeline.py --repo-root <repo-root> --setup-env
 ```
 
 `<skill-root>` is the directory that contains this skill.
 
 Creates `<repo-root>/theorem_pipeline` with:
+
 - `workspace/lean_project/` canonical cumulative Lean project
 - `data/runs/` run metadata and proof briefs
 - `logs/` local Lean verification logs
@@ -63,6 +67,7 @@ Warning: `init --build` can take several minutes the first time (toolchain/depen
 Operator requirement: Before running `uv run -m tproof.cli init --build`, explicitly notify the human user in-chat about this first-run delay.
 
 Pinned versions:
+
 - Lean toolchain: `leanprover/lean4:v4.28.0`
 - Mathlib hash: `8f9d9cff6bd728b17a24e163c9402775d9e6a365`
 
@@ -71,6 +76,7 @@ Pinned versions:
 Handle source ingestion based on user-provided input type.
 
 If input is a PDF:
+
 - Use `pypdf` (not `pdftotext`) and sanitize mojibake with UTF-8-safe output before theorem formalization.
 - Required output A (full cached extraction):
   - `theorem_pipeline/workspace/contexts/<pdf_stem>.txt`
@@ -85,6 +91,7 @@ If input is a PDF:
   - if the full extraction file already exists and is still valid for the current PDF, reuse it instead of converting the PDF again.
 
 If input is not a PDF (prompt text, local `.txt`/`.md`/`.tex`, or fetched online source):
+
 - Skip PDF conversion.
 - Use the source as requested by the user.
 - Store a normalized local source artifact under `theorem_pipeline/workspace/contexts/` (for example, `<theorem_slug>_source.txt`).
@@ -99,6 +106,7 @@ uv run -m tproof.cli start-run --prompt-file ./workspace/prompts/fill_sorries.tx
 ```
 
 This writes:
+
 - `data/runs/<run_id>/run.json`
 - `data/runs/<run_id>/run_brief.md`
 - snapshot of the Lean project for traceability
@@ -125,9 +133,10 @@ uv run -m tproof.cli verify
 ```
 
 `verify` fails on:
+
 - `lake build` failures
 - any unresolved `sorry`
-- any `.lean`/`.md` final artifacts found under `workspace/staging/` (forbidden; move to `ProofWorkspace/Final/`)
+- any `.lean` or `.md` artifact found under `workspace/staging/` (forbidden; move proof/sketch artifacts to `ProofWorkspace/Final/`)
 
 When done, set run status:
 
@@ -138,12 +147,15 @@ uv run -m tproof.cli set-status <run_id> COMPLETE --note "all goals proven and v
 ## 6. Final Artifact Placement and Sidecar Sketch Files (`.md`)
 
 Final theorem artifacts must be written only under:
+
 - `theorem_pipeline/workspace/lean_project/ProofWorkspace/Final/`
 
 Forbidden output location:
+
 - `workspace/staging/` for any final proof or sketch artifact.
 
 For every finalized Lean proof file, create a sibling Markdown sketch file:
+
 - Naming convention:
   - full proof (Lean-safe filename): `ProofWorkspace/Final/<Name>Full.lean`
   - sketch: `ProofWorkspace/Final/<Name>Sketch.md`
@@ -158,25 +170,30 @@ Recommended sidecar template:
 # <Theorem Name>
 
 ## Statement
+
 Plain-language statement mapped to the Lean theorem name(s).
 
 ## Assumptions
+
 - A1
 - A2
 - ...
 
 ## Proof Sketch
+
 Write a concise, fluent paragraph (or short sequence of paragraphs) as a mathematician would explain the proof to another mathematician in a paper. Emphasize the key reductions and ideas, but avoid low-level proof script details.
 
 Use inline/display LaTeX where needed, for example:
 `By reducing the claim to $X$, applying $Y$, and combining with $Z$, we obtain the target bound $f(x) \le g(x)$ for all $x \in D$.`
 
 ## Corollaries (if required)
+
 - help
 - match
 - upper-bound
 
 ## Lean Artifacts
+
 - File: <path/to/ProofWorkspace/Final/NameFull.lean>
 - Theorems:
   - <theorem_name_1>
@@ -184,10 +201,12 @@ Use inline/display LaTeX where needed, for example:
 ```
 
 Compatibility note:
+
 - The pipeline indexes/checks only `*.lean` files (`reindex`, module discovery, and `sorry` scan), so `.md` sidecars do not affect Lean verification.
 
 ## 7. Final Report Status Line
 
 Keep the existing report format, and append one additional final line:
+
 - `SUCCESS`
 - or `FAIL: <reason>`

package/skills/flywheel-reproduce/SKILL.md

@@ -15,12 +15,33 @@ If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool
 
 This skill supports both Flywheel install modes:
 
-- **`--mode mcp` install**: route via [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md); tool calls take the form `flywheel_<tool>` (e.g., `flywheel_commit_node`).
-- **`--mode cli` install**: `setup --mode cli` configures runtime credentials, then route via [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md); tool calls take the form `flywheel <command>` (e.g., `flywheel nodes:commit`). Prerequisite for bare-binary routing: run the curl installer with `--mode cli` or use the managed-prefix npm install recipe from the README.
+- **`--mode mcp` install on an MCP-capable host:** setup writes host-specific
+  MCP configuration; use [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md)
+  and the host's `flywheel_<tool>` surface.
+- **`--mode mcp` install on a skill-only host:** setup installs the skill but
+  skips MCP configuration, so no `flywheel_<tool>` surface exists. Route work
+  through a separately configured CLI, subject to the CLI caveat below.
+- **`--mode cli` install:** setup installs skills and writes runtime TOML unless every selected host is skill-only (for example, Universal or Antigravity). A skill-only selection skips CLI authentication and runtime configuration. Use [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md) and the `flywheel <command>` surface only with a configured CLI.
+
+Configure CLI mode independently. This command prompts for a host in an interactive terminal:
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode cli
+```
+
+For noninteractive setup, pass the active host's selector from `npx --yes @paradigma-inc/flywheel setup --help` (for example, `--claude` for Claude Code). Without a selector, prompt-free setup uses all detected hosts. Match the existing project/global scope.
+
+Running setup through `npx` configures settings and skills; it does not install a persistent `flywheel` binary. If `flywheel` is not on `PATH`, replace `flywheel` with `npx --yes @paradigma-inc/flywheel` in every CLI example below and in the linked tool map.
+
+When switching an already configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+
+Pick the route from both install mode and intended destination:
 
-When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+- For an identified local repository, select it with `--repo <path>`, `--personal`, or working-directory discovery; use `repo:` operations, local `repo:commit`, and `repo:push` only when publication is requested.
+- For an identified hosted graph, use supported `hosted:` operations directly; do not require a clone or local initialization merely to edit it.
+- If the destination is unknown, ask before writing. A failed local selection never permits a hosted fallback.
 
-The Workflow below cites both the MCP tool name and its CLI equivalent inline at each imperative step. Pick the one matching your install mode.
+MCP payloads and leases are not interchangeable with CLI commits. Follow this skill's [MCP tool map](references/flywheel-mcp-tool-map.md) for the distinct new-node and existing-node requirements. For hosted CLI writes, resolve `<repository-id>` to the intended hosted graph; hosted reads take node selectors, not `--repository-id`.
 
 ## Input Contract
 
@@ -74,16 +95,15 @@ Before execution, recover or establish these inputs:
      branch planning or execution.
 4. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
-   - Create a new node with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI) when needed.
-   - Update an existing node with `flywheel_get_node` + `flywheel_acquire_stage_lease` + `flywheel_commit_node` (MCP) or `flywheel nodes:get` + `flywheel nodes:stage:lease:acquire` + `flywheel nodes:commit` (CLI) when continuing work.
+   - On MCP, persist a new canonical node with `flywheel_commit_new_node` and its caller-local ID, parent IDs, and full staged payload. On CLI, follow the selected destination: use `hosted:node:create` only for an identified hosted graph, or `repo:node:create` for an identified local repository.
+   - On MCP, update an existing canonical node by reading it, acquiring the stage lease, then committing the same session/revision with full staged payload. On CLI, use `hosted:node:set` only for an identified hosted graph; local edits remain `repo:` operations until the separate local commit.
 5. Put the primary page markdown or validation rationale in the node body/readme field (`content`).
    - Keep `summary` concise.
    - Put claims, rationale, methods, outcomes, and continuation notes in `content`; keep `summary` concise.
 6. Publish supporting files with the artifact upload flow.
    - For exact artifact contract details, load [references/ARTIFACTS.md](references/ARTIFACTS.md).
-   - Use `flywheel_prepare_artifact_uploads` (MCP) or `flywheel artifacts:upload:prepare` (CLI).
-   - Upload raw file bytes to the returned signed URLs.
-   - Call `flywheel_finalize_artifact_uploads` (MCP) or `flywheel artifacts:upload:finalize` (CLI) once all uploads in the batch are staged.
+   - MCP mode uses `flywheel_prepare_artifact_uploads`, uploads raw bytes to the returned signed URLs, then calls `flywheel_finalize_artifact_uploads`.
+   - The direct-hosted CLI artifact helper prepares, uploads, and appends an attachment in one hosted repository commit. It is related to, but does not replace or share, MCP's prepare → raw upload → finalize contract.
    - Keep the artifact filename stable enough to reference from markdown when inline rendering matters.
 7. Add graph structure sparingly.
    - Promote only decision-relevant relationships to edges.
@@ -93,16 +113,16 @@ Before execution, recover or establish these inputs:
    - Prefer explicit validation branches such as baseline checks, mechanism or intermediate-signal checks, ablations, efficiency checks, robustness checks, failure analysis, and follow-up analysis branches after results land.
    - If the branch can run through Flywheel execution directly, use `flywheel_launch_execution` (MCP) or `flywheel executions:launch` (CLI) and inspect terminal status before commit.
 
-   - If the branch needs managed compute, in MCP mode use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)`, call `flywheel_compute_list_options`, recommend one offer deterministically and present up to two alternatives, wait for explicit user confirmation (or explicit user override offer id), then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready. In CLI mode use the parallel `flywheel compute-grants:request-approval` → `flywheel compute-grants:list` → `flywheel compute:options` → `flywheel compute:acquire` → `flywheel compute:status` → `flywheel compute:connection` sequence.
+   - If the branch needs managed compute, follow the [MCP](references/flywheel-mcp-tool-map.md#empirical-workflow) or [CLI](references/flywheel-cli-tool-map.md#empirical-workflow) empirical workflow. Inspect the full catalog, filter to allowed offers, and select the offer and region first. Recommend one offer deterministically and present up to two alternatives; wait for explicit user confirmation or an explicit allowed-offer override before requesting approval. Then follow the map's approval-status branches, grant resolution, acquisition, readiness polling, and connection steps.
    - Release managed compute when a branch is done. Default to releasing only
      known leases. Use release-all with the active `lease_control_token` for
      token-scoped bulk cleanup; add `force=true` (MCP) or `--force --yes` (CLI)
      only when the user explicitly requests account-wide cleanup.
    - Stop when the core claim is resolved or the budget ceiling is reached.
 
-9. Commit after the node snapshot is coherent with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI).
-   - Commit resolved nodes once `content`, `summary`, artifacts, tags, executions, and graph edges make the snapshot coherent.
-   - Leave unresolved plan nodes staged.
+9. Persist each coherent node snapshot.
+   - For MCP, commit existing nodes with their active lease session, current base revision, and full staged payload; new nodes use `flywheel_commit_new_node` with their caller-local ID and parent IDs.
+   - For CLI, direct hosted mutations already post repository commits, while local `repo:` edits require the separate local `repo:commit` and optional user-requested `repo:push`.
 
 ## Result Contract
 
@@ -110,7 +130,7 @@ When the skill completes a pass, it should leave behind:
 
 - Graphified source nodes or updated claim nodes that preserve the source material legibly in `content`.
 - One persisted control node containing the canonical validation contract.
-- Zero or more explicit validation branches staged or resolved under the hard max budget.
+- Zero or more explicit validation branches persisted or resolved under the hard max budget.
 - Coherent committed nodes, with artifacts attached when evidence exists.
 - Released managed compute if any lease was acquired during the pass.
 
@@ -122,13 +142,13 @@ For the canonical entity model and public contract terminology behind this contr
 
 Use this storage convention:
 
-1. Reuse an existing control node when one already governs the same source or claim family; otherwise create one with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI).
+1. Reuse an existing control node when one already governs the same source or claim family; otherwise persist a new MCP node with `flywheel_commit_new_node` or use the destination-appropriate hosted or local CLI workflow.
 2. Put the canonical contract in node `content`.
 3. Put a one-line synopsis in `summary`.
 4. Put the validation rationale, branch-priority logic, or continuation rule in `content`.
-5. Before committing control-node edits, acquire or refresh the stage lease with `flywheel_acquire_stage_lease` (and `flywheel_heartbeat_stage_lease` for long edits) — or in CLI mode, `flywheel nodes:stage:lease:acquire` and `flywheel nodes:stage:lease:heartbeat`.
-6. Read the control node with `flywheel_get_node` (MCP) or `flywheel nodes:get` (CLI) before later passes that need a fresh `expected_revision`.
-7. Commit the control node with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI) once the contract is coherent, even if downstream validation branches remain staged or in progress.
+5. For an existing MCP control node, read current state, acquire or refresh the lease with its session ID and base revision, then commit the same values with full staged payload. A direct hosted CLI mutation is an immediate repository commit; a local CLI edit must complete its separate local commit lifecycle.
+6. Before later passes, read the control node from the destination where it was persisted: `flywheel_get_node` for MCP, `flywheel repo:node:get` with the same local repository selected for local CLI, or `flywheel hosted:node:get` for hosted CLI.
+7. Persist the coherent control node before proceeding. Do not treat caller-local MCP staging or uncommitted local CLI operations as durable control state.
 
 Canonical contract shape:
 
@@ -230,4 +250,4 @@ Guidelines:
 - Keep the flywheel-reproduce skill scoped by cost and decision value, not by exhaustively trying every possible branch.
 - These claim-validation execution rules apply only when $flywheel-reproduce is the active skill.
 
-See also: invoke `$flywheel-to-graph` to port source material into Flywheel without implicit execution, invoke `$flywheel-lookahead` to stage next-step frontier nodes from existing graph state without execution, and invoke `$flywheel-auto` to advance a frontier autonomously under an explicit budget and persisted stop condition.
+See also: invoke `$flywheel-to-graph` to port source material into Flywheel without implicit execution, invoke `$flywheel-lookahead` to persist next-step frontier nodes from existing graph state without execution, and invoke `$flywheel-auto` to advance a frontier autonomously under an explicit budget and persisted stop condition.

package/skills/flywheel-reproduce/evals/evals.json

@@ -2,7 +2,7 @@
   {
     "id": "claim-bearing-paper-with-no-budget-yet",
     "prompt": "Use $flywheel-reproduce to validate the central empirical claims from this paper in Flywheel. I have not given you a max budget yet, but I do want the source structured and the validation plan prepared.",
-    "expected_output": "Create a parent paper node under the requested root, decompose the paper into section child nodes, keep section narratives in each child `content`, attach the PDF to the parent node, and stage explicit validation branch plans. Ask once for a hard max budget before any compute acquisition, and do not execute branches until the budget is explicit. Do NOT produce a single `insight` node with the PDF as the only artifact.",
+    "expected_output": "Create a parent paper node under the requested root, decompose the paper into section child nodes, keep section narratives in each child `content`, attach the PDF to the parent node, and persist explicit validation branch plans. Ask once for a hard max budget before any compute acquisition, and do not execute branches until the budget is explicit. Do NOT produce a single `insight` node with the PDF as the only artifact.",
     "files": []
   },
   {

package/skills/flywheel-reproduce/references/INTERFACES.md

@@ -58,7 +58,7 @@ direct-neighbor traversal.
 - `flywheel_get_node_tree` (read; scopes: `read`; full-surface only; binding: `operation`)
 - `flywheel_get_node_ancestry` (read; scopes: `read`; full-surface only; binding: `operation`)
 - `flywheel_get_campaign_snapshot` (read; scopes: `read`; core surface; binding: `operation`)
-- `flywheel_list_audit` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_admin_nodes_audit_list` (admin-only read; scopes: `read`; full-surface only; binding: `operation`)
 
 ### Node stage and commit
 
@@ -145,7 +145,7 @@ direct-neighbor traversal.
 - `GET /nodes/{node_id}/tree` -> `flywheel_get_node_tree`
 - `GET /nodes/{node_id}/ancestry` -> `flywheel_get_node_ancestry`
 - `GET /nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
-- `GET /nodes/{node_id}/audit` -> `flywheel_list_audit`
+- `GET /admin/nodes/{node_id}/audit` -> `flywheel_admin_nodes_audit_list` (admin only)
 
 ### Node stage and commit
 

package/skills/flywheel-reproduce/references/experiment-design-protocol.md

@@ -117,35 +117,43 @@ If the run is expensive or high-risk, ask for explicit confirmation.
 
 ## Phase 5: Drive Flywheel
 
-Use Flywheel in layers when possible.
-
-Before execution, load `references/flywheel-mcp-tool-map.md` and verify the
-exact tool surface exposed by the current MCP host before critical flows.
+Use the active configured interface throughout design, execution, and result
+persistence, following this skill's installation-mode guidance. A skill-only
+MCP install uses a separately configured CLI, not an MCP tool surface; do not
+assume that installing the skill configured the CLI.
+
+1. **Active MCP interface:** verify that the active MCP host exposes the required
+   tool surface, then load this skill's [MCP tool map](flywheel-mcp-tool-map.md).
+   Use its design, empirical, and final-result flows. If that surface is not
+   available, do not substitute CLI commands; configure the intended interface
+   or explain the blocker. Its caller-local new-node payload flow is distinct
+   from its existing-node session-stage-lease and full-payload commit flow; do
+   not recast either as a CLI repository commit.
+2. **Active CLI interface (including skill-only MCP installs):** load this skill's
+   [CLI tool map](flywheel-cli-tool-map.md). First determine the destination:
+   use its Local authoring workflow for an identified local repository
+   (stage, commit locally, and push only when publication is requested), or its
+   direct hosted/Empirical Workflow for an identified hosted repository
+   (immediate hosted commits). If the destination is unknown, ask before
+   writing; a missing local repository is not a reason to switch to hosted
+   storage.
 
 ### Design layer
 
-Use an `insight` node to capture rationale, open questions, experiment shape, and any decomposition needed for exploratory or multi-stage work.
-
-Typical flow:
-
-1. `mcp__flywheel__flywheel_commit_new_node`
-2. `mcp__flywheel__flywheel_acquire_stage_lease` when refining an existing design node
-3. `mcp__flywheel__flywheel_commit_node` once the design brief is coherent
+Persist an `insight` node's rationale, open questions, experiment shape, and
+exploratory or multi-stage decomposition through the selected map's matching
+write flow. Preserve the interface and destination choice while refining that
+design; do not mix MCP staged payloads with CLI local or hosted commit
+semantics.
 
 ### Execution layer
 
-Only after the design gate passes, create or branch the node for the runnable part of the work.
-
-Typical flow:
-
-1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_commit_new_node`
-2. `mcp__flywheel__flywheel_acquire_stage_lease` + `mcp__flywheel__flywheel_commit_node` with the explicit run summary and the local question or hypothesis for that branch
-3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
-4. `mcp__flywheel__flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)` when you need to resolve the approved `compute_grant_id`
-5. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed
-6. `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, then `mcp__flywheel__flywheel_finalize_artifact_uploads`
-7. Do a brief epistemic check before commit: verify what the evidence actually shows, whether it matches the interpretation rule from the brief, and whether any gap between the data and the hoped-for story needs to be named explicitly in the node summary.
-8. `mcp__flywheel__flywheel_commit_node`
+Only after the design gate passes, create or branch the runnable `empirical`
+work through the selected map. For managed compute, follow that map's
+Empirical Workflow end-to-end: catalog selection, approval, grant resolution,
+acquisition, execution, evidence artifacts, and the final result persistence
+path. Before that final result write, check that the evidence supports the
+interpretation and name any gap in the summary.
 
 Important notes: