@paradigma-inc/flywheel 0.1.115 → 0.1.134

package/skills/flywheel-lookahead/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
 
@@ -33,14 +54,14 @@ Before planning, recover or establish these inputs:
   - Ask only when a required planning input cannot be recovered from explicit user instructions, current conversational context, or recent graph state.
   - If start nodes cannot be recovered from explicit ids/slugs, named current context, or recent graph context, ask once.
   - If the objective is missing, ask once; if the user refuses, infer it from graph context and persist it before planning.
-  - If the terminal condition is missing, ask once; if it remains unspecified, persist a planning-local terminal condition such as stopping after staging this lookahead pass through the requested `n` hops with at most `k` considered options per hop and one selected continuation per hop.
+  - If the terminal condition is missing, ask once; if it remains unspecified, persist a planning-local terminal condition such as stopping after completing this lookahead pass through the requested `n` hops with at most `k` considered options per hop and one selected continuation per hop.
 
 ## Working Terms
 
 - `frontier`: the current unresolved next-step nodes or candidate branches worth planning next.
 - `resolved frontier`: the latest resolved nodes from which the next frontier should be expanded, not the original source corpus again.
 - `control node`: the dedicated `insight` node that stores the canonical planning contract for the current frontier.
-- `terminal condition`: the explicit condition that tells this planning pass when to stop staging additional frontier nodes.
+- `terminal condition`: the explicit condition that tells this planning pass when to stop persisting additional frontier nodes.
 - `expected_revision`: the node's current revision token used for optimistic-locking writes.
 - `lookahead depth (n)`: the number of sequential hops in one planned path.
 - `step option width (k)`: the number of candidate directions evaluated at each hop before choosing one continuation.
@@ -51,7 +72,7 @@ Before planning, recover or establish these inputs:
 - Step option width `k`: number of candidate directions to evaluate at each hop.
 - Expansion rule: at hop `i`, generate up to `k` non-redundant options, select exactly 1 winner, and only that winner continues to hop `i+1`.
 - Graph shape for this mode: a single chain of `n` hop-selector nodes, each with up to `k` explicit option nodes (not `k` parallel continuation chains).
-- Each considered option should normally be staged as its own node when it is a stable, non-redundant candidate direction. Do not collapse the `k` options into prose only.
+- Each considered option should normally be persisted as its own node when it is a stable, non-redundant candidate direction. Do not collapse the `k` options into prose only.
 - The next hop should keep the current hop-selector node as a parent and add the chosen option node as an additional selected edge/parent when the topology can express that relationship.
 - Each step node must record:
   - the `k` considered options,
@@ -63,10 +84,10 @@ Before planning, recover or establish these inputs:
 - Treat the main page body as the node readme/body field (`content` on modern Flywheel surfaces).
 - Use artifacts for supporting files and evidence, not as a substitute for the node's main narrative, because the node body should stay readable as the canonical planning record.
 - Only create graph edges for durable semantic relationships, because graphifying every wiki link floods the graph with noise that hides decision-relevant structure.
-- Treat the flywheel-lookahead skill as frontier planning only. It expands the Flywheel graph with staged next-step nodes but does not execute them, because execution or compute acquisition changes the job into `$flywheel-auto` or `$flywheel-reproduce`.
+- Treat the flywheel-lookahead skill as frontier planning only. It expands the Flywheel graph with persisted next-step nodes but does not execute them, because execution or compute acquisition changes the job into `$flywheel-auto` or `$flywheel-reproduce`.
 - Planned nodes that are expected to produce evidence or artifacts should say so in `content` and attach artifacts when evidence exists; planned nodes that encode synthesis, decomposition, or decision structure should keep that rationale in `content`.
 - Ask only the minimum clarification questions needed to establish a coherent planning contract, and ask none when the required answers are already recoverable from user instructions, conversational context, or graph state.
-- Do not request compute approval, acquire managed compute, or launch execution in this skill, because planning should leave the frontier staged for later work rather than spend budget now.
+- Do not request compute approval, acquire managed compute, or launch execution in this skill, because planning should leave the frontier persisted for later work rather than spend budget now.
 
 ## Workflow
 
@@ -76,23 +97,21 @@ Before planning, recover or establish these inputs:
    - Recover required planning inputs from the current conversation and graph first. Ask only for inputs that remain genuinely missing after that recovery pass.
    - The flywheel-lookahead skill requires a measurable objective. Ask once if it is missing; if the user refuses to specify one, infer it from the available graph context and state it explicitly before continuing.
    - Default `n=1` and `k=1` unless the user specified otherwise.
-   - Persist the planning contract in a dedicated control node for this frontier. Put the canonical contract and brief planning rationale in node `content`, and keep a one-line synopsis in `summary`.
+   - Persist the planning contract in a dedicated control node before using it for later replans. Put the canonical contract and brief planning rationale in node `content`, and keep a one-line synopsis in `summary`.
    - The control contract must name: objective, decision criterion, start nodes, lookahead depth `n`, step option width `k`, and an explicit terminal condition. Only persist a budget ceiling and unit when the user already supplied one or wants them tracked for later execution.
-   - Later lookahead passes must read the control node `content` first and continue from that persisted contract rather than from chat memory.
+   - Later lookahead passes must read the committed control node `content` first and continue from that persisted contract rather than from chat memory.
 3. 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).
    - In this skill, each stable considered direction at a hop should normally become its own option node; the hop-selector node remains the decision record for that hop.
-   - Prefer `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI) for a new standalone control or planning node when there is no existing parent to branch from.
-   - Prefer `flywheel_branch_node` (MCP) or `flywheel nodes:branch` (CLI) for hop-selector nodes or option nodes that should attach directly under an existing control node, frontier node, or winning option node.
-   - Update an existing node with `flywheel_get_node`, `flywheel_acquire_stage_lease`, and `flywheel_commit_node` (MCP) or `flywheel nodes:get`, `flywheel nodes:stage:lease:acquire`, and `flywheel nodes:commit` (CLI).
-   - Use `flywheel_add_parent` (MCP) or `flywheel nodes:add-parent` (CLI) when the chosen option should remain recoverable in topology as an additional parent or selected edge, not prose alone.
+   - On MCP, persist standalone nodes with `flywheel_commit_new_node` using caller-local ID, parent IDs, and full staged payload; use `flywheel_branch_node` for a child node when appropriate. On CLI, use `hosted:` operations only for an identified hosted graph and `repo:` operations for an identified local repository.
+   - For an existing MCP node, read it, acquire the stage lease, then commit the same session/revision with full staged payload. Direct hosted CLI `hosted:node:set` is an immediate repository commit; local CLI edits use their separate local commit lifecycle.
+   - Add the selected option as an additional parent only when that topology is durable and decision-relevant.
 4. Put the primary page markdown or plan rationale in the node body/readme field (`content`).
    - Put claims, rationale, methods, outcomes, and continuation notes in `content`; keep `summary` concise.
 5. 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.
 6. Add graph structure sparingly.
    - Promote only decision-relevant relationships to edges.
@@ -101,14 +120,14 @@ Before planning, recover or establish these inputs:
    - Expand from the resolved frontier rather than mirroring the source corpus again.
    - Depth `n` means plan `n` sequential hops ahead from the currently resolved frontier. Default `n=1`.
    - Width `k` means evaluate up to `k` distinct non-redundant candidate directions at each hop. Default `k=1`.
-   - At each hop, stage up to `k` explicit option nodes, record them in the hop-selector node, apply the selection criterion, and choose exactly one continuation.
-   - Only the chosen continuation advances to hop `i+1`; do not stage `k` parallel continuation chains for this mode.
-   - The staged graph shape for this mode is a single chain of up to `n` unresolved hop-selector nodes (shorter only when the terminal condition is met early), with up to `k` option nodes attached to each hop.
+   - At each hop, persist up to `k` explicit option nodes, record them in the hop-selector node, apply the selection criterion, and choose exactly one continuation.
+   - Only the chosen continuation advances to hop `i+1`; do not persist `k` parallel continuation chains for this mode.
+   - The durable graph shape for this mode is a single chain of up to `n` hop-selector nodes (shorter only when the terminal condition is met early), with up to `k` committed option nodes attached to each hop.
    - When one option wins, encode that choice in topology as well as prose: the next hop should be reachable from the chosen option node via a selected edge or additional parent relationship when available on the current Flywheel surface.
    - Each hop-selector node must record: the `k` considered option nodes, the selection criterion used, and the chosen continuation.
-8. 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.
-   - Keep unresolved plan nodes durable and explicitly unresolved in their content; do not rely on uncommitted local drafts to preserve the frontier.
+8. Persist each coherent node snapshot.
+   - MCP new nodes require `flywheel_commit_new_node` with caller-local ID, parent IDs, and full payload; MCP updates require the existing-node lease/session/revision sequence. CLI hosted writes commit immediately, while local CLI edits require a later local commit and optional user-requested push.
+   - Do not rely on caller-local MCP staging or uncommitted local CLI operations as the frontier record.
 
 ## Result Contract
 
@@ -127,13 +146,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 frontier; otherwise create one with `flywheel_commit_new_node` or `flywheel_branch_node` (MCP), or `flywheel nodes:commit-new` or `flywheel nodes:branch` (CLI), depending on whether it should attach to an existing parent.
+1. Reuse an existing control node when one already governs the same frontier; 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 planning rationale or branch-selection logic in `content`.
-5. Update the control node with `flywheel_acquire_stage_lease` + `flywheel_commit_node` (MCP) or `flywheel nodes:stage:lease:acquire` + `flywheel nodes:commit` (CLI).
-6. Read the control node with `flywheel_get_node` (MCP) or `flywheel nodes:get` (CLI) before later replans 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 frontier nodes remain staged.
+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 replans, 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:
 

package/skills/flywheel-lookahead/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Flywheel Lookahead"
-  short_description: "Plan staged Flywheel frontiers without execution"
+  short_description: "Plan persisted Flywheel frontiers without execution"
   default_prompt: "Use $flywheel-lookahead to plan a Flywheel frontier with explicit option nodes and one chosen continuation."
 
 dependencies:

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

@@ -2,25 +2,25 @@
   {
     "id": "continuation-from-existing-planning-contract",
     "prompt": "Use $flywheel-lookahead to continue planning from an existing Flywheel control node that already contains a coherent planning contract. Expand the next frontier one more hop without execution and do not ask again for the objective or start nodes unless the control node is missing or contradictory.",
-    "expected_output": "Read the persisted planning contract from the control node content before replanning, continue from the stored objective and start nodes, avoid re-asking for those inputs when the contract is coherent, and stage additional next-step frontier nodes without execution or compute acquisition.",
+    "expected_output": "Read the persisted planning contract from the control node content before replanning, continue from the stored objective and start nodes, avoid re-asking for those inputs when the contract is coherent, and persist additional next-step frontier nodes without execution or compute acquisition.",
     "files": []
   },
   {
     "id": "cold-start-with-no-objective",
-    "prompt": "Use $flywheel-lookahead to plan the next Flywheel frontier from the current graph context. If I refuse to specify an objective, infer one from the graph context and make it explicit before you stage any next-step nodes.",
-    "expected_output": "Ask for an objective once, infer one from graph context if the user refuses, write that objective and a decision criterion into the planning contract, and only then stage next-step frontier nodes.",
+    "prompt": "Use $flywheel-lookahead to plan the next Flywheel frontier from the current graph context. If I refuse to specify an objective, infer one from the graph context and make it explicit before you persist any next-step nodes.",
+    "expected_output": "Ask for an objective once, infer one from graph context if the user refuses, write that objective and a decision criterion into the planning contract, and only then persist next-step frontier nodes.",
     "files": []
   },
   {
     "id": "planning-only-with-explicit-depth-and-width",
-    "prompt": "Use $flywheel-lookahead to stage two sequential hops of next-step work while evaluating up to three non-redundant options at each hop from the current Flywheel frontier. Plan only for later work and do not execute anything.",
-    "expected_output": "Persist `n=2` and `k=3` in the planning contract, stage up to three explicit option nodes at each hop, record those option nodes plus the selection criterion plus chosen continuation in each hop-selector node, continue only along the single chosen path, encode the chosen path with selected edges or additional-parent topology when possible, and avoid compute approval, managed compute acquisition, or execution launch.",
+    "prompt": "Use $flywheel-lookahead to persist two sequential hops of next-step work while evaluating up to three non-redundant options at each hop from the current Flywheel frontier. Plan only for later work and do not execute anything.",
+    "expected_output": "Persist `n=2` and `k=3` in the planning contract, commit up to three explicit option nodes at each hop, record those option nodes plus the selection criterion plus chosen continuation in each hop-selector node, continue only along the single chosen path, encode the chosen path with selected edges or additional-parent topology when possible, and avoid compute approval, managed compute acquisition, or execution launch.",
     "files": []
   },
   {
     "id": "explicit-option-nodes-not-prose-only",
     "prompt": "Use $flywheel-lookahead to plan one hop ahead with four candidate directions. Keep it as a single selected path, but make the graph structure explicit enough that another agent can traverse each considered direction as its own node rather than recovering those options from prose.",
-    "expected_output": "Treat the four candidate directions as explicit option nodes, keep only one chosen continuation for the next hop, avoid staging four parallel continuation chains, and make the selected option discoverable from graph topology rather than prose alone.",
+    "expected_output": "Treat the four candidate directions as committed explicit option nodes, keep only one chosen continuation for the next hop, avoid creating four parallel continuation chains, and make the selected option discoverable from graph topology rather than prose alone.",
     "files": []
   },
   {

package/skills/flywheel-lookahead/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