@paradigma-inc/flywheel 0.1.73 → 0.1.77

package/README.md

@@ -57,6 +57,35 @@ Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
 ```
 
+## Shell Completion
+
+`flywheel completion <shell>` generates shell completion scripts from the public
+Flywheel command spec. It requires the official `usage` executable on `PATH`;
+install it with one of:
+
+```bash
+mise use -g usage
+brew install usage
+cargo install usage-cli
+cargo binstall usage-cli
+pacman -S usage
+```
+
+Generate the script for your shell and redirect it wherever your shell setup
+loads completions:
+
+```bash
+flywheel completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/flywheel
+flywheel completion zsh > ~/.zsh/completions/_flywheel
+flywheel completion fish > ~/.config/fish/completions/flywheel.fish
+flywheel completion powershell > flywheel.ps1
+flywheel completion nu > ~/.config/nushell/autoload/flywheel.nu
+flywheel completion nushell > ~/.config/nushell/autoload/flywheel.nu
+```
+
+This command generates scripts only. It does not install completions. It does
+nothing to shell startup files and does not edit shell profiles.
+
 ## Uninstall
 
 One-shot uninstaller (macOS and Linux):

package/package.json

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

package/skills/flywheel/compute/managed-compute.md

@@ -53,7 +53,7 @@ For a focused reference, see `compute/credits-and-billing.md`.
 
 ### Step 2 - Extract task signals from node text
 
-- Read `node.content`, `node.hypothesis`, `node.summary`.
+- Read `node.content` and `node.summary`.
 - Extract:
   - `weight_class` in `{light, medium, heavy, unknown}`
   - `expected_runtime_hours`

package/skills/flywheel/references/INTERFACES.md

@@ -19,9 +19,10 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 ## Canonical Entity Model
 
 - Canonical durable entity: `node`.
-- Node kind values: `untyped`, `empirical`, `insight`.
+- Canonical node body fields: `title`, Markdown `content`, and optional `summary`.
 - Node references: `node_id`, `slug_name`.
 - `slug_name` format: `adjective-noun-####` (immutable when present).
+- Removed typed node body fields (`kind`, `node_type`, `hypothesis`, `insights`, `no_artifacts_reason`) are not write fields.
 - Approval sessions and compute grants are distinct entities; approvals are session-scoped bindings.
 - Campaign projections are derived from root config and attempt submission JSON artifacts.
 

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

@@ -94,7 +94,7 @@ For exploratory work, instead check:
 
 Additional checks when relevant:
 
-- an artifact plan or `no_artifacts_reason` exists
+- an artifact plan exists, or the node content states why the run is intentionally artifact-free
 - the run shape matches the question and is not changing too many important things without purpose
 - an interpretation rule or next branch is defined
 
@@ -134,7 +134,7 @@ Typical flow:
 
 ### Execution layer
 
-Only after the design gate passes, create or branch the `empirical` node for the runnable part of the work.
+Only after the design gate passes, create or branch the node for the runnable part of the work.
 
 Typical flow:
 
@@ -149,10 +149,10 @@ Typical flow:
 
 Important notes:
 
-- Exploratory work can stay in `insight` nodes until a specific empirical probe is ready.
-- Because `empirical` commits require a non-empty `hypothesis`, turn each runnable exploratory probe into a concrete local question or hypothesis for that branch.
+- Exploratory work can stay as planning content until a specific empirical probe is ready.
+- Record each runnable exploratory probe as a concrete local question or hypothesis in the branch content.
 - For multi-stage or multi-arm work, use branches to represent stages or arms and keep summaries clear about how each branch feeds the next.
-- Completed empirical work needs artifacts or a `no_artifacts_reason`.
+- Attach artifacts when empirical work produces evidence; when it is intentionally artifact-free, state that rationale in node content.
 
 ## Adaptive question flow
 

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

@@ -125,8 +125,6 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel nodes:create` (mutating; scopes: `write`): Create a minimal node (title only) and emit graph-change event.
 - `flywheel nodes:files` (read; scopes: `read`): List files attached to a node.
 - `flywheel nodes:sharing:summaries` (read; scopes: `read`): Read access summaries for multiple nodes in one batch.
-- `flywheel nodes:stage:backfill:hypothesis` (mutating; scopes: `write`): Derive hypothesis from staged node content.
-- `flywheel nodes:stage:backfill:insights` (mutating; scopes: `write`): Extract structured insights from staged node content.
 
 ### Artifact helpers (CLI-only)
 
@@ -245,7 +243,7 @@ Account merge, detach, and email mutation commands are browser-session-bound. AP
 
 These commands require `FLYWHEEL_ADMIN_KEY` in the environment (forwarded as the `X-Admin-Key` header) or an admin browser session. Default help and JSON help hide admin commands unless `FLYWHEEL_ADMIN_KEY` or `FLYWHEEL_CLI_INTERNAL=1` is present, but explicit `flywheel help admin:<command>` still works. API-key-only callers fail locally with `admin_auth_required`. The endpoints are omitted from the public OpenAPI schema and from the API-key allowlist.
 
-- `flywheel admin:graphs:list` — list every root-node graph across all users. Filters: `--tag-id`, `--kind`, `--owner-user-id`, `--created-after`, `--created-before`, `--cursor`, `--page-size` (1..200).
+- `flywheel admin:graphs:list` — list every root-node graph across all users. Filters: `--tag-id`, `--owner-user-id`, `--created-after`, `--created-before`, `--cursor`, `--page-size` (1..200).
 - `flywheel admin:graphs:export --root-node-id=<id>` — export one graph as canonical JSON, bypassing per-caller visibility.
 - `flywheel admin:graphs:export:stream` — stream canonical graph JSON for many graphs as NDJSON (one page per call, `--out=<file>` to write to disk). Filters match `admin:graphs:list`.
 

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

@@ -8,19 +8,17 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - Use `flywheel_get_contract` + `flywheel_get_contract_section` as canonical contract references.
 - Node state is canonical durable state; avoid relying on ephemeral transcript state.
-- Node kind (`untyped`, `empirical`, `insight`) is an explicit durable field.
+- 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.
-- Insight nodes should represent conceptual observations (theoretical insights, intuitions, motivations, decision-relevant framing); empirical nodes should represent experiments with explicit hypotheses and measured outcomes.
 - 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.
-- Stage/backfill helpers (`stage_backfill_hypothesis`, `stage_backfill_insights`) return non-canonical staged payload patches and explicit status fields (`staged_changes_pending`, `commit_required`, `next_action_hint`).
-- Committed node state must still satisfy strict contract (`summary` required; `empirical` requires hypothesis plus artifacts or `no_artifacts_reason`; `insight` requires non-empty insights).
+- 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).
-- Summaries, hypotheses, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
+- Content, summaries, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
 - Empirical workflow is hypothesis-driven: launch execution, inspect outcomes, publish evidence artifacts, and commit only after terminal status.
 - For empirical work, publish evidence with `flywheel_prepare_artifact_uploads`, upload raw file bytes, then `flywheel_finalize_artifact_uploads` before commit.
 - Artifact metadata records expose a non-empty `title` suitable for display labels; title normalization must never derive from `storage_url`.
@@ -162,7 +160,7 @@ Hook workflow-if contract (first version):
 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, or set `no_artifacts_reason` when intentionally artifact-free.
+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.
 
 ### Hook Automation Workflow
@@ -202,6 +200,6 @@ Hook workflow-if contract (first version):
 
 These tools require an `@paradigma.inc`-authenticated MCP session **or** a valid `X-Admin-Key` header sent on the MCP HTTP request. The MCP streamable HTTP mount reads `X-Admin-Key` from the inbound request and forwards it through to the in-process `/admin/graphs*` call; on admin paths the proxy also suppresses the session bearer to sidestep the API-key route allowlist check. `require_paradigma_admin` then grants access based on the admin key. The routes are omitted from the public OpenAPI schema and from the API-key allowlist.
 
-- `flywheel_admin_list_graphs`: list every root-node graph across all users. Filters: `tag_id`, `kind`, `owner_user_id`, `created_after`, `created_before`, `cursor`, `page_size` (1..200). Returns `{graphs, has_more, next_cursor}`.
+- `flywheel_admin_list_graphs`: list every root-node graph across all users. Filters: `tag_id`, `owner_user_id`, `created_after`, `created_before`, `cursor`, `page_size` (1..200). Returns `{graphs, has_more, next_cursor}`.
 - `flywheel_admin_export_graph`: export one graph by `root_node_id` as canonical JSON (`{version, exported_at, node_count, nodes}`). Bypasses per-caller node-visibility checks by design.
 - `flywheel_admin_export_graphs_stream`: batch-export one page of canonical graph JSON payloads matching the filter; iterate pages via `next_cursor`. The NDJSON HTTP endpoint (`GET /admin/graphs/export.jsonl`) is the CLI-first streaming surface; the MCP tool materializes a page to fit the RPC model.

package/skills/flywheel/usage-and-workflows/what-to-do-with-flywheel.md

@@ -11,9 +11,9 @@ built in.
 
 What you can do with it:
 
-- Create work nodes and classify them as insight (thinking/analysis) or empirical (actual experiments).
+- Create work nodes for thinking, analysis, and empirical experiments.
 - Build a graph of work with branching/merging, not just a linear log.
-- Commit outcomes with required structure (kind, outcome, summary) so results stay consistent.
+- Commit outcomes as Markdown content, optional summaries, artifacts, tags, and executions so results stay consistent.
 - Launch managed compute for a node with budget controls and track execution state.
 - Attach artifacts to nodes (text, tables, JSON, images, HTML/plots, checkpoints, diffs).
 - Configure hooks that call external HTTP endpoints when events occur.

package/skills/flywheel/web-ui/flywheel-webui-map.md

@@ -5,10 +5,9 @@ Use this map when a user asks where to find a feature in the web interface.
 ## Primary Areas
 
 - Graph canvas: browse nodes, branches, and topology for the current workspace.
-- Node panel: inspect node metadata, summaries, hypotheses, outcomes, artifacts,
-  and access state.
+- Node panel: inspect node metadata, Markdown content, summaries, artifacts, tags, executions, and access state.
 - Artifact views: open uploaded artifacts (plots, tables, JSON, text, HTML).
-- Search and filters: narrow nodes by title, kind, state, and tags.
+- Search and filters: narrow nodes by title, content, state, and tags.
 - Access and sharing controls: review and update visibility/collaboration policy.
 - Settings: account-level preferences, machines/leases, and credit-related pages.
 

package/skills/flywheel/web-ui/the-flywheel-web-ui.md

@@ -12,6 +12,6 @@ You can also toggle timeline view for a more organized, linear view of the graph
 
 You can also shift select some nodes and generate summaries of their content and or export them as PDFs and/or JSON files for others to import. Of course, you can also use your MCP host to generate summaries and overviews of your research graph.
 
-Inside a node, you will be able to see the artifacts attached to it, a summary and possibly the hypothesis and/or insight that was recorded for this node.
+Inside a node, you will be able to see its Markdown content, optional summary, artifacts, tags, and execution history.
 
 ![example node view](https://flywheel.paradigma.inc/assets/example_node_view-Xv6mViuc.png)

package/skills/flywheel-auto/SKILL.md

@@ -51,8 +51,7 @@ Before execution, recover or establish these inputs:
 - Treat the flywheel-auto skill as graph-local autonomous research: persist the run contract in the graph, keep the plan `n` hops ahead, and spend only within an explicit measured budget.
 - When guidance from flywheel, flywheel-lookahead, flywheel-reproduce, or flywheel-to-graph conflicts during an active $flywheel-auto run, flywheel-auto rules take precedence for compute, questioning, and stop decisions.
 - Ask only the minimum clarification questions needed to establish a coherent control contract, and ask none when the required answers are already recoverable from user instructions, conversational context, or graph state.
-- Planned nodes that are expected to produce evidence or artifacts should be typed `empirical`; planned nodes that only encode synthesis, decomposition, or decision structure should be typed `insight`.
-- Keep the control node typed `insight` and keep its `insights` non-empty so the insight commit contract stays valid.
+- 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`.
 - Do not rely on fresh user feedback to decide whether the flywheel-auto skill should continue, so later replans can resume from node state alone in a fresh chat.
 
 ## Workflow
@@ -64,7 +63,7 @@ Before execution, recover or establish these inputs:
    - The flywheel-auto skill requires a measurable objective and an explicit terminal condition. Ask once for missing prerequisites; if the user refuses to specify an objective, infer it from the available graph context and state it explicitly before continuing.
    - The budget contract must be explicit before execution starts. Ask once for missing budget ceiling or budget unit. When budget ceiling and budget unit are present but terminal condition is missing, derive `terminal_condition: "budget ceiling reached"` and persist that derivation into the control node `content` before any compute request or acquisition.
    - Managed compute spend is billed in Flywheel credits. If the user gives dollars, hours, or another measurable budget semantic, persist that user-facing cap explicitly and derive the operational compute approval cap before acquisition.
-   - Persist the run contract in a dedicated `insight` control node for this frontier. Put the canonical contract in node `content`, keep a one-line synopsis in `summary`, and keep brief run rationale in `insights` so the commit contract stays valid.
+   - Persist the run contract in a dedicated control node for this frontier. Put the canonical contract and brief run rationale in node `content`, and keep a one-line synopsis in `summary`.
    - The control contract must name: objective, decision criterion, start nodes, budget ceiling and unit, lookahead depth `n`, frontier width `k`, and an explicit terminal condition.
    - Later flywheel-auto replans must read the control node `content` first and continue from that persisted contract rather than from chat memory.
    - Run the design gate from [references/experiment-design-protocol-autonomous.md](references/experiment-design-protocol-autonomous.md) before the first compute request: confirm objective, decision criterion, evidence plan, budget readiness, and stop-reason recording requirements, even though later continuation decisions become graph-local.
@@ -73,8 +72,7 @@ Before execution, recover or establish these inputs:
    - 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.
 4. Put the primary page markdown or plan rationale in the node body/readme field (`content`).
-   - Keep `summary` concise.
-   - Populate `hypothesis`, `insights`, `outcome`, and similar fields only when the source actually supports them.
+   - 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).
@@ -107,25 +105,24 @@ Before execution, recover or establish these inputs:
    - Before every termination path, persist `stop_reason` in control node `content` as one of: `budget_exhausted`, `objective_met`, `no_viable_branch`, `user_cancelled`, `runtime_error`.
 
 9. Commit after the node snapshot is coherent with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI).
-   - Commit resolved insight nodes only when they have non-empty `insights`.
-   - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
+   - Commit resolved nodes once `content`, `summary`, artifacts, tags, executions, and graph edges make the snapshot coherent.
    - Leave unresolved plan nodes staged.
 
 ## Result Contract
 
 When the skill completes a pass, it should leave behind:
 
-- One persisted `insight` control node containing the canonical run contract.
+- One persisted control node containing the canonical run contract.
 - Zero or more staged frontier nodes up to the current `n` and `k` limits.
-- Zero or more committed resolved nodes, but only when their commit contracts are satisfied.
-- Uploaded artifacts for completed empirical work, or an explicit `no_artifacts_reason` when artifacts are absent by design.
+- Zero or more committed resolved nodes, once their durable content and artifacts are coherent.
+- Uploaded artifacts for completed empirical work when evidence exists, or an explicit artifact-free rationale in node content when artifacts are absent by design.
 - Released managed compute if any lease was acquired during the pass.
 - An explicit `stop_reason` recorded in node state so a later pass can resume graph-locally.
 - If the no-branch stop clause is used, a per-candidate rejection log recorded in control node `content`.
 
 ## Persisted Control Contract
 
-Use a dedicated `insight` node as the durable run controller for the current
+Use a dedicated node as the durable run controller for the current
 frontier. Do not rely on unstated product fields or fresh chat context.
 
 For the canonical entity model and public contract terminology behind this
@@ -137,8 +134,7 @@ Use this storage convention:
    otherwise create one with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI).
 2. Put the canonical contract in node `content`.
 3. Put a one-line synopsis in `summary`.
-4. Put the run rationale, continuation rule, or prioritization logic in
-   `insights` so the `insight` commit contract is satisfied.
+4. Put the run rationale, continuation rule, or prioritization logic 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 replans that need
    a fresh `expected_revision` revision token for optimistic-locking writes.

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

@@ -19,9 +19,10 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 ## Canonical Entity Model
 
 - Canonical durable entity: `node`.
-- Node kind values: `untyped`, `empirical`, `insight`.
+- Canonical node body fields: `title`, Markdown `content`, and optional `summary`.
 - Node references: `node_id`, `slug_name`.
 - `slug_name` format: `adjective-noun-####` (immutable when present).
+- Removed typed node body fields (`kind`, `node_type`, `hypothesis`, `insights`, `no_artifacts_reason`) are not write fields.
 - Approval sessions and compute grants are distinct entities; approvals are session-scoped bindings.
 - Campaign projections are derived from root config and attempt submission JSON artifacts.
 

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

@@ -94,7 +94,7 @@ For exploratory work, instead check:
 
 Additional checks when relevant:
 
-- an artifact plan or `no_artifacts_reason` exists
+- an artifact plan exists, or the node content states why the run is intentionally artifact-free
 - the run shape matches the question and is not changing too many important things without purpose
 - an interpretation rule or next branch is defined
 
@@ -134,7 +134,7 @@ Typical flow:
 
 ### Execution layer
 
-Only after the design gate passes, create or branch the `empirical` node for the runnable part of the work.
+Only after the design gate passes, create or branch the node for the runnable part of the work.
 
 Typical flow:
 
@@ -149,10 +149,10 @@ Typical flow:
 
 Important notes:
 
-- Exploratory work can stay in `insight` nodes until a specific empirical probe is ready.
-- Because `empirical` commits require a non-empty `hypothesis`, turn each runnable exploratory probe into a concrete local question or hypothesis for that branch.
+- Exploratory work can stay as planning content until a specific empirical probe is ready.
+- Record each runnable exploratory probe as a concrete local question or hypothesis in the branch content.
 - For multi-stage or multi-arm work, use branches to represent stages or arms and keep summaries clear about how each branch feeds the next.
-- Completed empirical work needs artifacts or a `no_artifacts_reason`.
+- Attach artifacts when empirical work produces evidence; when it is intentionally artifact-free, state that rationale in node content.
 
 ## Adaptive question flow
 

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

@@ -123,8 +123,6 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel nodes:create` (mutating; scopes: `write`): Create a minimal node (title only) and emit graph-change event.
 - `flywheel nodes:files` (read; scopes: `read`): List files attached to a node.
 - `flywheel nodes:sharing:summaries` (read; scopes: `read`): Read access summaries for multiple nodes in one batch.
-- `flywheel nodes:stage:backfill:hypothesis` (mutating; scopes: `write`): Derive hypothesis from staged node content.
-- `flywheel nodes:stage:backfill:insights` (mutating; scopes: `write`): Extract structured insights from staged node content.
 
 ### Artifact helpers (CLI-only)
 

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

@@ -8,19 +8,17 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - Use `flywheel_get_contract` + `flywheel_get_contract_section` as canonical contract references.
 - Node state is canonical durable state; avoid relying on ephemeral transcript state.
-- Node kind (`untyped`, `empirical`, `insight`) is an explicit durable field.
+- 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.
-- Insight nodes should represent conceptual observations (theoretical insights, intuitions, motivations, decision-relevant framing); empirical nodes should represent experiments with explicit hypotheses and measured outcomes.
 - 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.
-- Stage/backfill helpers (`stage_backfill_hypothesis`, `stage_backfill_insights`) return non-canonical staged payload patches and explicit status fields (`staged_changes_pending`, `commit_required`, `next_action_hint`).
-- Committed node state must still satisfy strict contract (`summary` required; `empirical` requires hypothesis plus artifacts or `no_artifacts_reason`; `insight` requires non-empty insights).
+- 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).
-- Summaries, hypotheses, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
+- Content, summaries, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
 - Empirical workflow is hypothesis-driven: launch execution, inspect outcomes, publish evidence artifacts, and commit only after terminal status.
 - For empirical work, publish evidence with `flywheel_prepare_artifact_uploads`, upload raw file bytes, then `flywheel_finalize_artifact_uploads` before commit.
 - Artifact metadata records expose a non-empty `title` suitable for display labels; title normalization must never derive from `storage_url`.
@@ -135,7 +133,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 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, or set `no_artifacts_reason` when intentionally artifact-free.
+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.
 
 ## Runtime Guidance

package/skills/flywheel-lookahead/SKILL.md

@@ -64,7 +64,7 @@ Before planning, recover or establish these inputs:
 - 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`.
-- Planned nodes that are expected to produce evidence or artifacts should be typed `empirical`; planned nodes that only encode synthesis, decomposition, or decision structure should be typed `insight`.
+- 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.
 
@@ -76,7 +76,7 @@ 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 `insight` control node for this frontier. Put the canonical contract in node `content`, keep a one-line synopsis in `summary`, and keep brief planning rationale in `insights` so the commit contract stays valid.
+   - 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`.
    - 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.
 3. Map each stable page, claim, or concept to a node.
@@ -87,8 +87,7 @@ Before planning, recover or establish these inputs:
    - 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.
 4. Put the primary page markdown or plan rationale in the node body/readme field (`content`).
-   - Keep `summary` concise.
-   - Populate `hypothesis`, `insights`, `outcome`, and similar fields only when the source actually supports them.
+   - 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).
@@ -108,22 +107,21 @@ Before planning, recover or establish these inputs:
    - 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 insight nodes only when they have non-empty `insights`.
-   - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
+   - 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.
 
 ## Result Contract
 
 When the skill completes a pass, it should leave behind:
 
-- One persisted `insight` control node containing the canonical planning contract.
+- One persisted control node containing the canonical planning contract.
 - A single persisted next-step chain up to the current `n` limit where each hop has a selector node plus up to `k` explicit option nodes and one selected continuation.
 - Updated node summaries, rationale, and selected edges that make the chosen path explicit without turning the graph into `k` parallel continuation chains.
 - No hidden execution, no compute approval, and no managed compute acquisition.
 
 ## Persisted Control Contract
 
-Use a dedicated `insight` node as the durable planning controller for the current frontier. Do not rely on unstated product fields or fresh chat context.
+Use a dedicated node as the durable planning controller for the current frontier. Do not rely on unstated product fields or fresh chat context.
 
 For the canonical entity model and public contract terminology behind this controller, load [references/INTERFACES.md](references/INTERFACES.md).
 
@@ -132,7 +130,7 @@ 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.
 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 `insights` so the `insight` commit contract is satisfied.
+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.

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

@@ -19,9 +19,10 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 ## Canonical Entity Model
 
 - Canonical durable entity: `node`.
-- Node kind values: `untyped`, `empirical`, `insight`.
+- Canonical node body fields: `title`, Markdown `content`, and optional `summary`.
 - Node references: `node_id`, `slug_name`.
 - `slug_name` format: `adjective-noun-####` (immutable when present).
+- Removed typed node body fields (`kind`, `node_type`, `hypothesis`, `insights`, `no_artifacts_reason`) are not write fields.
 - Approval sessions and compute grants are distinct entities; approvals are session-scoped bindings.
 - Campaign projections are derived from root config and attempt submission JSON artifacts.
 

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

@@ -123,8 +123,6 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel nodes:create` (mutating; scopes: `write`): Create a minimal node (title only) and emit graph-change event.
 - `flywheel nodes:files` (read; scopes: `read`): List files attached to a node.
 - `flywheel nodes:sharing:summaries` (read; scopes: `read`): Read access summaries for multiple nodes in one batch.
-- `flywheel nodes:stage:backfill:hypothesis` (mutating; scopes: `write`): Derive hypothesis from staged node content.
-- `flywheel nodes:stage:backfill:insights` (mutating; scopes: `write`): Extract structured insights from staged node content.
 
 ### Artifact helpers (CLI-only)
 

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

@@ -8,19 +8,17 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - Use `flywheel_get_contract` + `flywheel_get_contract_section` as canonical contract references.
 - Node state is canonical durable state; avoid relying on ephemeral transcript state.
-- Node kind (`untyped`, `empirical`, `insight`) is an explicit durable field.
+- 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.
-- Insight nodes should represent conceptual observations (theoretical insights, intuitions, motivations, decision-relevant framing); empirical nodes should represent experiments with explicit hypotheses and measured outcomes.
 - 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.
-- Stage/backfill helpers (`stage_backfill_hypothesis`, `stage_backfill_insights`) return non-canonical staged payload patches and explicit status fields (`staged_changes_pending`, `commit_required`, `next_action_hint`).
-- Committed node state must still satisfy strict contract (`summary` required; `empirical` requires hypothesis plus artifacts or `no_artifacts_reason`; `insight` requires non-empty insights).
+- 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).
-- Summaries, hypotheses, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
+- Content, summaries, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
 - Empirical workflow is hypothesis-driven: launch execution, inspect outcomes, publish evidence artifacts, and commit only after terminal status.
 - For empirical work, publish evidence with `flywheel_prepare_artifact_uploads`, upload raw file bytes, then `flywheel_finalize_artifact_uploads` before commit.
 - Artifact metadata records expose a non-empty `title` suitable for display labels; title normalization must never derive from `storage_url`.
@@ -135,7 +133,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 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, or set `no_artifacts_reason` when intentionally artifact-free.
+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.
 
 ## Runtime Guidance

package/skills/flywheel-reproduce/SKILL.md

@@ -63,7 +63,7 @@ Before execution, recover or establish these inputs:
    - Recover required execution inputs from the current conversation and graph first. Ask only for inputs that remain genuinely missing after that recovery pass.
    - The flywheel-reproduce skill requires a measurable objective and a hard max budget. Ask once for missing prerequisites; if the user refuses to specify an objective, infer it from the available graph context and state it explicitly before continuing.
    - Run the design gate from [references/experiment-design-protocol.md](references/experiment-design-protocol.md) before any compute request: confirm objective, decision criterion, evidence plan, branch strategy, and budget readiness.
-   - Persist the validation contract in a dedicated `insight` control node for this source or claim family. Put the canonical contract in node `content`, keep a one-line synopsis in `summary`, and keep brief validation rationale in `insights` so the commit contract stays valid.
+   - Persist the validation contract in a dedicated control node for this source or claim family. Put the canonical contract and brief validation rationale in node `content`, and keep a one-line synopsis in `summary`.
    - The control contract must name: objective, decision criterion, source or claim nodes under test, budget ceiling and unit, and an explicit stopping criterion.
    - Later reproduce passes must read the control node `content` first and continue from that persisted contract rather than from chat memory.
 3. Classify the source.
@@ -78,7 +78,7 @@ Before execution, recover or establish these inputs:
    - 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.
 5. Put the primary page markdown or validation rationale in the node body/readme field (`content`).
    - Keep `summary` concise.
-   - Populate `hypothesis`, `insights`, `outcome`, and similar fields only when the source actually supports them.
+   - 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).
@@ -101,8 +101,7 @@ Before execution, recover or establish these inputs:
    - 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 insight nodes only when they have non-empty `insights`.
-   - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
+   - Commit resolved nodes once `content`, `summary`, artifacts, tags, executions, and graph edges make the snapshot coherent.
    - Leave unresolved plan nodes staged.
 
 ## Result Contract
@@ -110,14 +109,14 @@ Before execution, recover or establish these inputs:
 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 `insight` control node containing the canonical validation contract.
+- One persisted control node containing the canonical validation contract.
 - Zero or more explicit validation branches staged or resolved under the hard max budget.
-- Coherent committed empirical or insight nodes, with artifacts attached where required by the outcome contract.
+- Coherent committed nodes, with artifacts attached when evidence exists.
 - Released managed compute if any lease was acquired during the pass.
 
 ## Persisted Validation Contract
 
-Use a dedicated `insight` node as the durable validation controller for the current source or claim family. Do not rely on unstated product fields or fresh chat context.
+Use a dedicated node as the durable validation controller for the current source or claim family. Do not rely on unstated product fields or fresh chat context.
 
 For the canonical entity model and public contract terminology behind this controller, load [references/INTERFACES.md](references/INTERFACES.md).
 
@@ -126,7 +125,7 @@ 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).
 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 `insights` so the `insight` commit contract is satisfied.
+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.

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

@@ -19,9 +19,10 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 ## Canonical Entity Model
 
 - Canonical durable entity: `node`.
-- Node kind values: `untyped`, `empirical`, `insight`.
+- Canonical node body fields: `title`, Markdown `content`, and optional `summary`.
 - Node references: `node_id`, `slug_name`.
 - `slug_name` format: `adjective-noun-####` (immutable when present).
+- Removed typed node body fields (`kind`, `node_type`, `hypothesis`, `insights`, `no_artifacts_reason`) are not write fields.
 - Approval sessions and compute grants are distinct entities; approvals are session-scoped bindings.
 - Campaign projections are derived from root config and attempt submission JSON artifacts.
 

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

@@ -94,7 +94,7 @@ For exploratory work, instead check:
 
 Additional checks when relevant:
 
-- an artifact plan or `no_artifacts_reason` exists
+- an artifact plan exists, or the node content states why the run is intentionally artifact-free
 - the run shape matches the question and is not changing too many important things without purpose
 - an interpretation rule or next branch is defined
 
@@ -134,7 +134,7 @@ Typical flow:
 
 ### Execution layer
 
-Only after the design gate passes, create or branch the `empirical` node for the runnable part of the work.
+Only after the design gate passes, create or branch the node for the runnable part of the work.
 
 Typical flow:
 
@@ -149,10 +149,10 @@ Typical flow:
 
 Important notes:
 
-- Exploratory work can stay in `insight` nodes until a specific empirical probe is ready.
-- Because `empirical` commits require a non-empty `hypothesis`, turn each runnable exploratory probe into a concrete local question or hypothesis for that branch.
+- Exploratory work can stay as planning content until a specific empirical probe is ready.
+- Record each runnable exploratory probe as a concrete local question or hypothesis in the branch content.
 - For multi-stage or multi-arm work, use branches to represent stages or arms and keep summaries clear about how each branch feeds the next.
-- Completed empirical work needs artifacts or a `no_artifacts_reason`.
+- Attach artifacts when empirical work produces evidence; when it is intentionally artifact-free, state that rationale in node content.
 
 ## Adaptive question flow