@paradigma-inc/flywheel 0.1.115 → 0.1.134

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

@@ -11,11 +11,11 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - Node body state is `title`, Markdown `content`, and optional `summary`; represent observations, decisions, experiments, and evidence with Markdown structure, tags, artifacts, and executions.
 - Node references include immutable `node_id` and optional immutable `slug_name`; prefer communicating both together for human clarity and disambiguation.
 - Graph topology should encode logical/causal relations between concepts and experiments. Avoid defaulting to shallow root-only branching unless work items are truly independent.
-- Node staging is local (non-canonical) and commit is the only canonical persistence boundary (`commit_new_node`, `commit_node`).
-- Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision` or `base_committed_revision` as required, and handle `409 conflict` with explicit reconciliation.
-- Mutating operations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
-- Existing-node field editing may use a session-scoped stage lease (`flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`) to coordinate local staged state before commit.
-- Existing-node commit publishes a full staged payload under an active stage lease: commit requests require `stage_session_id`, `base_committed_revision`, and `staged_payload`; conflicts on stale committed revisions are surfaced directly and are not transport-retried.
+- Node-body staging for `flywheel_commit_new_node` and `flywheel_commit_node` is caller-local until commit. Topology mutations such as `flywheel_branch_node`, `flywheel_merge_nodes`, `flywheel_add_parent`, and `flywheel_remove_parent` become canonical immediately when they succeed.
+- A new-node commit uses caller-local `local_temp_node_id`, `parent_ids`, and a full `staged_payload`; on success it returns the persisted canonical node. The correlation ID is not a canonical node ID and the operation does not use an existing-node stage lease or `base_committed_revision`.
+- An existing-node commit starts by reading the node, then acquiring `flywheel_acquire_stage_lease` with its `node_id`, caller-chosen `stage_session_id`, and current `base_committed_revision`. Commit with that same session ID/revision and a full `staged_payload`. A successful commit releases the lease; acquire a fresh lease before another commit.
+- MCP mutations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
+- Existing-node stage leases (`flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`) coordinate caller-local staged state before commit.
 - Committed node state uses the same canonical body fields for every node; `summary` may be empty when the node body is intentionally represented by content, artifacts, tags, or executions.
 - When code is involved, pass `repo_url`/`branch_name`/`head_commit_sha` and align git structure with graph topology where practical (without forcing one-to-one mapping).
 - Content, summaries, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
@@ -48,15 +48,15 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_get_node_tree` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/tree`; full-surface only): Get a root-aware bounded tree/DAG projection for an anchor node.
 - `flywheel_get_node_ancestry` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/ancestry`; full-surface only): Get ordered ancestry metadata from an anchor node to root boundaries.
 - `flywheel_get_campaign_snapshot` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/campaign/snapshot`; core surface): Read the current campaign snapshot for a node's root campaign, including configured views and derived records.
-- `flywheel_list_audit` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/audit`; full-surface only): List node MCP audit events.
+- `flywheel_admin_nodes_audit_list` (admin-only read; scopes: `read`; HTTP: `GET /admin/nodes/{node_id}/audit`; full-surface only): List audit events from every actor on the node; requires admin authorization.
 
 ### Node stage and commit
 
-- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
-- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
+- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /nodes/commit-new`; full-surface only): Commit a caller-local new node to canonical storage with `local_temp_node_id`, `parent_ids`, and full `staged_payload`; no existing-node stage lease or base revision applies.
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire an existing-node session-scoped stage lease with `node_id`, caller-chosen `stage_session_id`, and current `base_committed_revision`.
 - `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
 - `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
-- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
+- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; core surface): Commit an existing node with the acquired `stage_session_id`, its current `base_committed_revision`, and full `staged_payload`.
 - `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; full-surface only): Create a child branch node with optimistic locking (`expected_revision` required); on 409, reread the node and retry with the current revision.
 - `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
 - `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/add`; full-surface only): Attach an additional parent edge to an existing node (keeps node identity, validates against cycles).
@@ -82,7 +82,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 ### Compute and budgets
 
-- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /compute/catalog`; core surface): List managed compute options allowed for a node. When using grant-backed compute, pass the same compute_grant_id you will use for acquire.
+- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /compute/catalog`; core surface): List managed compute catalog options and their policy `allowed` flags for a node when no suitable active lease exists; no compute grant is required. This catalog-only read excludes grant/budget money fields. Filter `compute.options` to `allowed=true`; copy the exact provider-qualified `compute.options[].offer_id` (`provider::offer_id`) verbatim (not a display name or partial ID), and select region as described in the empirical workflow.
 - `flywheel_compute_funding` (read; scopes: `compute`; HTTP: `GET /compute/funding`; core surface): Read grant-scoped funding context (`grant_cents`, `remaining_cents`, and backing budget fields) for a `compute_grant_id` before compute acquire.
 - `flywheel_compute_status` (read; scopes: `compute`; HTTP: `GET /compute/status`; core surface): Read managed compute lease status for the current user and current lease_control_token scope. Lease rows include ownership flags so hosts can distinguish user-owned leases from sponsor-visible campaign leases. When checking a grant-backed lease, reuse the same compute_grant_id passed to acquire.
 - `flywheel_compute_connection` (read; scopes: `compute`; HTTP: `GET /compute/connection`; core surface): Read SSH connection material for an active managed compute lease once flywheel_compute_status indicates the lease is usable. This tool is token-scoped to lease_control_token and only leases owned by the current user are connectable. Pass lease_id or node_id to disambiguate when needed.
@@ -96,7 +96,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_create_campaign_budget` (mutating; scopes: `compute`; HTTP: `POST /nodes/{root_node_id}/campaign-budgets`; full-surface only): Create an organizer-funded campaign compute budget shared with participants.
 - `flywheel_update_campaign_budget` (mutating; scopes: `compute`; HTTP: `PATCH /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; full-surface only): Update hard caps or metadata for an organizer-funded campaign compute budget.
 - `flywheel_revoke_campaign_budget` (mutating; scopes: `compute`; HTTP: `DELETE /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; full-surface only): Revoke an organizer-funded campaign compute budget.
-- `flywheel_compute_acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Acquire managed compute for a node with explicit SKU + region and required compute_grant_id (returns accepted/completed lease state only; poll flywheel_compute_status for readiness, not SSH key material). This tool forwards approval_session_id. Set `requested_sku` to the exact `offer_id` returned by `flywheel_compute_list_options` (`options[].offer_id`), including provider prefixes (for example `nebius::...`); do not pass display names or partial IDs.
+- `flywheel_compute_acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Acquire managed compute for a node with explicit SKU, a region when the selected offer requires one, and required compute_grant_id (returns accepted/completed lease state only; poll flywheel_compute_status for readiness, not SSH key material). This tool forwards approval_session_id. Set `requested_sku` to the exact `offer_id` from an `allowed=true` option returned by `flywheel_compute_list_options` (`compute.options[].offer_id`), including provider prefixes (for example `nebius::...`); do not pass display names or partial IDs. Capture `compute.lease_control_token` from the response for follow-up lease-control tools.
 - `flywheel_compute_release` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Asynchronously release one managed compute lease by lease_id within the current lease_control_token scope.
 - `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Asynchronously release active managed compute leases in the current lease_control_token scope; set `force=true` with `lease_control_token` for explicit account-wide cleanup for the current user.
 
@@ -118,26 +118,27 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 1. `flywheel_list_nodes` with `{'owners': ['me'], 'projection': 'core'}`.
 
-### Safe Node Update
+### Existing-node update
 
-1. `flywheel_get_node`: Read latest node state before mutating fields.
-2. `flywheel_acquire_stage_lease`: Acquire a session-scoped stage lease before editing an existing node locally.
-3. `flywheel_commit_node`: Commit with `stage_session_id`, `base_committed_revision`, and full `staged_payload` once terminal and contract-complete.
+1. `flywheel_get_node`: Read the current canonical node and revision.
+2. `flywheel_acquire_stage_lease`: Acquire with the node ID, caller-chosen `stage_session_id`, and that current `base_committed_revision`.
+3. `flywheel_commit_node`: Commit with the same session ID/revision and the full `staged_payload`.
+4. If commit returns a stale-revision `409`, release the caller's stale lease, reread and reconcile the node, then acquire a fresh lease at the latest revision before retrying.
 
 ### Empirical Workflow
 
-1. `flywheel_commit_new_node`: Commit a local staged new node to canonical storage as the first persistence boundary.
-2. `flywheel_commit_node`: Commit staged empirical fields with `stage_session_id`, `base_committed_revision`, and a full `staged_payload` once the working state is ready to publish.
-3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval context first. Branch on response status.
-4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`).. if `already_approved` then `reuse_compute_grant_id`: Use returned `compute_grant_id` directly for flywheel_compute_acquire.. if `approval_required` then `present_approval_url_to_user`: Present `approval_url` to the user; the user opens it and confirms budget approval.; `flywheel_list_compute_grants`: After approval, list active grants for the current `approval_session_id` and use the returned `compute_grant_id` for acquire.. if `insufficient_credits` then `request_user_credit_top_up`: No `approval_url` is returned. Ask the user to add credits, then retry flywheel_request_compute_grant_approval.
-5. `flywheel_compute_acquire`: Acquire lease with `compute_grant_id`; include `approval_session_id` from approval response and set `requested_sku` to the exact selected `options[].offer_id`.
+1. `flywheel_commit_new_node`: Persist the caller-local new empirical node with `local_temp_node_id`, `parent_ids`, and full `staged_payload`.
+2. For an existing empirical node: `flywheel_get_node`, then `flywheel_acquire_stage_lease` with node ID, caller-chosen session ID, and current base revision; then `flywheel_commit_node` with that same session ID/revision and full `staged_payload`.
+3. If compute is needed, call `flywheel_compute_list_options` with `detail="full"`, filter `compute.options` to `allowed=true`, and select the exact `offer_id`. For `region_selection_mode` `required_from_list`, choose `region` from the selected option's `regions`. For `provider_validated`, pass `region=""` to `flywheel_request_compute_grant_approval`, then omit `region` from acquisition. Call approval with the selected option's `provider`, that `requested_sku`, the selected region or empty string, the intended `grant_action`, purpose, and budget source.
+4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`). If `already_approved`, use the returned `compute_grant_id` directly for `flywheel_compute_acquire`. If `approval_required`, present `approval_url` to the user; after approval, `flywheel_list_compute_grants` for the current `approval_session_id` and use its `compute_grant_id`. If `insufficient_credits`, ask the user to add credits, then retry `flywheel_request_compute_grant_approval`.
+5. `flywheel_compute_acquire`: Acquire lease with `compute_grant_id`; include `approval_session_id`, set `requested_sku` to the exact selected `compute.options[].offer_id`, and include the selected `region` when `region_selection_mode` is `required_from_list`.
 6. `flywheel_compute_status`: Poll until the active lease is ready; follow `recommended_next_action`.
 7. `flywheel_launch_execution`: Launch execution once compute and inputs are ready.
 8. `flywheel_list_executions`: Poll until execution reaches terminal status.
 9. `flywheel_prepare_artifact_uploads`: Prepare signed upload URLs for empirical evidence.
 10. `raw_file_upload`: Upload raw bytes to each signed URL with required headers.
 11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit when the work produced evidence artifacts.
-12. `flywheel_commit_node`: Commit terminal empirical node once contract requirements are satisfied.
+12. Re-read the node and acquire a fresh stage lease at its latest committed revision. Use `flywheel_commit_node` to publish the result fields and terminal state together in one full `staged_payload`.
 
 ## Runtime Guidance
 
@@ -152,13 +153,10 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_list_compute_grants`: list active compute grants (funded by user/root budgets) and select one `compute_grant_id` for acquisition.
 - `flywheel_request_compute_grant_approval`: request/confirm budget before acquire and choose a budget source (`user` or `root`); branch on status (`already_approved`, `approval_required`, `insufficient_credits`).
 - `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable, scoped by lease_control_token.
-- `flywheel_compute_list_options`: use when a lease is needed and no suitable active lease exists, then select the exact provider-qualified `offer_id` from `options[].offer_id` (`provider::offer_id`) and `region`. Copy `offer_id` verbatim; do not strip prefixes or substitute display names. This is a catalog-only read and excludes grant/budget money fields.
 - `flywheel_compute_funding`: read grant-scoped funding context (`grant_cents`, `remaining_cents`, backing budget fields) for the selected `compute_grant_id` before acquire.
-- `flywheel_compute_acquire`: provision compute once requirements are clear. This requires a valid `compute_grant_id`; set `requested_sku` to the exact selected `options[].offer_id`; and returns lease/provisioning state only (not SSH key material). Capture `compute.lease_control_token` from the response for follow-up lease control tools.
 - `flywheel_compute_release`: release compute when no longer needed, scoped by lease_control_token.
 - `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution status transitions.
 - `flywheel_prepare_artifact_uploads`: prepare one or more signed raw-file upload requests for concrete deliverables/evidence produced by the work.
 - `flywheel_finalize_artifact_uploads`: finalize a staged artifact batch and append all uploaded artifacts in one revision bump.
 - `flywheel_delete_artifact`: remove an accidental/obsolete node artifact.
 - `flywheel_list_artifacts`, `flywheel_get_artifact`: inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
-- `flywheel_commit_new_node`, `flywheel_commit_node`: publish the caller's full staged payload for an existing node once terminal and contract-complete; requires an active stage lease and explicit `base_committed_revision`.

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

@@ -16,26 +16,14 @@ Infer the best selector string from the user request (node id or slug).
 Do not call `flywheel_get_node_tree` in the agent and then re-emit large JSON.
 Run `scripts/render_tree_via_mcp.py`, which calls MCP tools and renders in-process.
 
+`<skill-root>` is the installed `flywheel-tree` directory that contains the
+loaded `SKILL.md`. Use that loaded directory directly; do not search candidate
+host installation paths or require a repository checkout.
+
 ```bash
 # Ubuntu/macOS (bash/zsh)
-SKILL_ROOT=""
-for CANDIDATE in \
-  "$(pwd)/.agents/skills/flywheel-tree" \
-  "$HOME/.agents/skills/flywheel-tree" \
-  "$HOME/.codex/skills/flywheel-tree" \
-  "${CODEX_HOME:+$CODEX_HOME/skills/flywheel-tree}"; do
-  if [ -n "$CANDIDATE" ] && [ -f "$CANDIDATE/scripts/render_tree_via_mcp.py" ]; then
-    SKILL_ROOT="$CANDIDATE"
-    break
-  fi
-done
-if [ -z "$SKILL_ROOT" ]; then
-  echo "flywheel-tree skill not found" >&2
-  exit 2
-fi
-# No repository checkout is required.
 uv run --quiet --with mcp python \
-  "$SKILL_ROOT/scripts/render_tree_via_mcp.py" \
+  "<skill-root>/scripts/render_tree_via_mcp.py" \
   --selector "<node-id-or-slug>" \
   --projection topology \
   --max-nodes 1000
@@ -43,27 +31,8 @@ uv run --quiet --with mcp python \
 
 ```powershell
 # Windows (PowerShell)
-$candidates = @(
-  (Join-Path (Get-Location).Path ".agents/skills/flywheel-tree"),
-  (Join-Path $HOME ".agents/skills/flywheel-tree"),
-  (Join-Path $HOME ".codex/skills/flywheel-tree")
-)
-if ($env:CODEX_HOME) {
-  $candidates += (Join-Path $env:CODEX_HOME "skills/flywheel-tree")
-}
-$skillRoot = $null
-foreach ($candidate in $candidates) {
-  if (Test-Path (Join-Path $candidate "scripts/render_tree_via_mcp.py")) {
-    $skillRoot = $candidate
-    break
-  }
-}
-if (-not $skillRoot) {
-  throw "flywheel-tree skill not found"
-}
-# No repository checkout is required.
 uv run --quiet --with mcp python `
-  "$skillRoot/scripts/render_tree_via_mcp.py" `
+  "<skill-root>/scripts/render_tree_via_mcp.py" `
   --selector "<node-id-or-slug>" `
   --projection topology `
   --max-nodes 1000