@paradigma-inc/flywheel 0.1.11 → 0.1.13

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

@@ -0,0 +1,160 @@
+# Flywheel MCP Tool Map
+
+This reference describes the Flywheel MCP tool families and the common runtime
+contract expected by the public Flywheel skill.
+
+Use it as a routing guide, not as a session snapshot. Always verify the exact
+tool surface exposed by your current MCP host before executing critical flows.
+
+## Core Contract Expectations
+
+- Node lifecycle and graph-mutation flows use optimistic locking
+  (`expected_revision`).
+- Node commits require `kind`, `outcome`, and `summary`.
+- `kind` is typically `insight` or `empirical`.
+- `insight` commits require non-empty `insights`.
+- `empirical` commits require a non-empty `hypothesis`; completed empirical
+  commits also require artifacts or a `no_artifacts_reason`.
+- Artifact publish is a two-step flow:
+  prepare upload, upload raw bytes to returned signed URLs, then finalize
+  the upload batch.
+
+## Tool Families
+
+### Session, Auth, and Contract
+
+- `mcp__flywheel__flywheel_auth_status`
+- `mcp__flywheel__flywheel_get_contract`
+- `mcp__flywheel__flywheel_get_contract_section`
+- `mcp__flywheel__flywheel_get_credits_balance`
+
+### Node Discovery and Read
+
+- `mcp__flywheel__flywheel_list_nodes`
+- `mcp__flywheel__flywheel_get_node`
+- `mcp__flywheel__flywheel_get_node_tree`
+- `mcp__flywheel__flywheel_get_node_ancestry`
+- `mcp__flywheel__flywheel_summarize_node_tree`
+- `mcp__flywheel__flywheel_get_campaign_snapshot`
+- `mcp__flywheel__flywheel_list_audit`
+
+### Node Mutation, Branching, and Commit
+
+- `mcp__flywheel__flywheel_stage_node_create`
+- `mcp__flywheel__flywheel_stage_node_update`
+- `mcp__flywheel__flywheel_commit_node`
+- `mcp__flywheel__flywheel_branch_node`
+- `mcp__flywheel__flywheel_merge_nodes`
+- `mcp__flywheel__flywheel_add_parent`
+- `mcp__flywheel__flywheel_remove_parent`
+- `mcp__flywheel__flywheel_delete_node`
+- `mcp__flywheel__flywheel_bulk_delete_nodes`
+
+### Access Policy and Collaboration
+
+- `mcp__flywheel__flywheel_get_node_sharing`
+- `mcp__flywheel__flywheel_set_sharing_for_node`
+- `mcp__flywheel__flywheel_set_sharing_for_nodes`
+
+### Tags and Graph Annotation
+
+- `mcp__flywheel__flywheel_create_node_tag`
+- `mcp__flywheel__flywheel_update_node_tag`
+- `mcp__flywheel__flywheel_delete_node_tag`
+- `mcp__flywheel__flywheel_set_node_tag_assignments`
+
+### Artifacts
+
+- `mcp__flywheel__flywheel_list_artifacts`
+- `mcp__flywheel__flywheel_get_artifact`
+- `mcp__flywheel__flywheel_get_artifact_preview`
+- `mcp__flywheel__flywheel_prepare_artifact_uploads`
+- `mcp__flywheel__flywheel_finalize_artifact_uploads`
+- `mcp__flywheel__flywheel_set_artifact_note`
+- `mcp__flywheel__flywheel_delete_artifact`
+
+Common artifact types include:
+`text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`,
+`checkpoint`, and `diff_carousel`.
+
+### Export and Import
+
+- `mcp__flywheel__flywheel_export_subgraph`
+- `mcp__flywheel__flywheel_import_subgraph`
+- `mcp__flywheel__flywheel_export_summary`
+- `mcp__flywheel__flywheel_export_summary_stream`
+- `mcp__flywheel__flywheel_export_summary_pdf`
+- `mcp__flywheel__flywheel_export_summary_render_pdf`
+
+### Executions
+
+- `mcp__flywheel__flywheel_launch_execution`
+- `mcp__flywheel__flywheel_list_executions`
+- `mcp__flywheel__flywheel_terminate_execution`
+
+### Managed Compute
+
+- `mcp__flywheel__flywheel_approval_session_heartbeat`
+- `mcp__flywheel__flywheel_list_approval_sessions`
+- `mcp__flywheel__flywheel_expire_approval_session`
+- `mcp__flywheel__flywheel_request_compute_grant_approval`
+- `mcp__flywheel__flywheel_list_compute_grants`
+- `mcp__flywheel__flywheel_compute_list_options`
+- `mcp__flywheel__flywheel_compute_acquire`
+- `mcp__flywheel__flywheel_compute_status`
+- `mcp__flywheel__flywheel_compute_connection`
+- `mcp__flywheel__flywheel_compute_release`
+- `mcp__flywheel__flywheel_compute_release_all`
+
+### Campaign Budgets (Organizer Flows)
+
+- `mcp__flywheel__flywheel_list_campaign_budgets`
+- `mcp__flywheel__flywheel_create_campaign_budget`
+- `mcp__flywheel__flywheel_update_campaign_budget`
+- `mcp__flywheel__flywheel_revoke_campaign_budget`
+
+### Migration Helpers
+
+Some installations may expose migration-only helper tools with hashed names.
+Treat these as specialized one-off tools, not part of day-to-day research
+workflows.
+
+## Practical Tool Sequences
+
+### Insight Node Flow
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. `mcp__flywheel__flywheel_commit_node`
+
+### Empirical Node With Artifacts
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. Run experiment or compute steps
+4. `mcp__flywheel__flywheel_prepare_artifact_uploads`
+5. Upload artifact bytes to signed URLs
+6. `mcp__flywheel__flywheel_finalize_artifact_uploads`
+7. `mcp__flywheel__flywheel_commit_node`
+
+### Managed Compute Flow
+
+1. `mcp__flywheel__flywheel_approval_session_heartbeat`
+2. `mcp__flywheel__flywheel_request_compute_grant_approval`
+3. `mcp__flywheel__flywheel_list_compute_grants` (if needed)
+4. `mcp__flywheel__flywheel_compute_acquire`
+5. `mcp__flywheel__flywheel_compute_status` until ready
+6. `mcp__flywheel__flywheel_compute_connection`
+7. `mcp__flywheel__flywheel_compute_release` (or `..._release_all`)
+
+### Share a Graph With Collaborators
+
+1. `mcp__flywheel__flywheel_get_node_sharing`
+2. `mcp__flywheel__flywheel_set_sharing_for_node` (or `..._for_nodes`)
+3. `mcp__flywheel__flywheel_export_summary` or `..._export_subgraph` for handoff
+
+## Safety Notes
+
+- Prefer `get_contract` before implementing strict assumptions in automation.
+- Avoid call-order assumptions not mandated by contract.
+- Keep checks bounded: list/read first, then mutate only the intended nodes.

package/skills/flywheel-reproduce/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: flywheel-reproduce
+description: Graphify claim-bearing source material in Flywheel with Flywheel MCP and validate it empirically within a hard maximum budget. Use for reproduction, replication, or claim validation, not planning-only lookahead, source-to-graph authoring without validation, or autonomous frontier expansion.
+---
+
+# flywheel-reproduce
+
+## When To Use
+
+Use this skill when the task is to shape information inside Flywheel rather than only discuss it. Use the flywheel-reproduce skill when the source is claim-bearing and the user wants Flywheel to both structure the source and run empirical validation. Flywheel MCP is a node-first durable system of record for research work: nodes hold durable state, artifacts hold supporting files, executions record runs, and compute leases provide managed hardware. Conceptually, the flywheel-reproduce skill is `$flywheel-to-graph` plus budgeted empirical execution: graphify the source first, split it into explicit validation branches, then execute those branches within a hard maximum budget.
+
+If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/INTERFACES.md](references/INTERFACES.md) before mutating nodes or acquiring compute.
+
+## Input Contract
+
+Before execution, recover or establish these inputs:
+
+- Required before execution: claim-bearing source material or existing claim nodes, a measurable objective, a hard max budget, and an explicit stopping criterion.
+- Optional: preferred validation branch types, execution constraints, and source-format hints.
+- Recovery rules:
+  - Ask only when a required execution input cannot be recovered from explicit user instructions, current conversational context, or recent graph state.
+  - If the source is already structured in Flywheel, recover the governing source or claim nodes from graph state before asking.
+  - If the objective is missing, ask once; if the user refuses, infer an objective such as validating the central claims within the available budget and persist it before execution.
+  - If the hard max budget is missing, ask once before execution. Until the budget is explicit, graph construction and branch planning may proceed, but empirical execution must not start.
+  - If the stopping criterion is missing, ask once; if it remains unspecified, persist a criterion such as stopping when the core claim is resolved or the budget ceiling is reached.
+
+## Working Terms
+
+- `claim-bearing source`: source material that contains concrete empirical claims worth validating or refuting.
+- `validation branch`: an explicit node or subtree that tests one claim, mechanism, baseline, robustness property, or failure mode.
+- `hard max budget`: a non-negotiable spend ceiling that empirical execution must not exceed.
+- `normalized Flywheel graph export`: already-structured Flywheel node JSON with DAG-safe edges, suitable for `flywheel_import_subgraph`.
+- `expected_revision`: the node's current revision token used for optimistic-locking writes.
+
+## Core Rules
+
+- Prefer explicit Flywheel node and artifact operations over ad hoc bulk-import stories, because node-first authoring keeps the graph legible and auditable.
+- 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 remain the readable source-of-truth for the claim and validation story.
+- Only create graph edges for durable semantic relationships, because graphifying every wiki link floods the graph with noise that hides decision-relevant structure.
+- Use `flywheel_import_subgraph` only for prebuilt Flywheel graph JSON, not for raw markdown repositories, because raw corpora are usually file-centric and cyclic rather than clean node-centric payloads.
+- Treat the flywheel-reproduce skill as claim validation, not as a magical importer. It combines graphification with budgeted empirical execution, because claim-bearing work should become explicit validation branches before compute is spent.
+- Ask only the minimum clarification questions needed to establish a coherent validation contract, and ask none when the required answers are already recoverable from user instructions, conversational context, or graph state.
+- For empirical execution, load [references/experiment-design-protocol.md](references/experiment-design-protocol.md) and [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) before spending compute.
+
+## Workflow
+
+1. Resolve the starting context.
+   - Start from existing knowledge that should be validated, not from an open-ended frontier expansion loop.
+   - Resolve source or claim nodes in this order: explicit node ids/slugs, explicitly named current context, focused or recently referenced nodes, then ask the user if nothing stable is recoverable.
+2. Resolve the validation contract.
+   - 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.
+   - 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.
+   - If the input is already a normalized Flywheel graph export, `flywheel_import_subgraph` may be appropriate.
+   - If it is a markdown wiki, README corpus, blog post, or paper, port it explicitly with node and artifact tools before execution.
+   - If it is a claim-bearing paper or benchmark result, split the work into explicit validation branches rather than treating the whole source as one flat note.
+4. Map each stable page, claim, or concept to a node.
+   - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
+   - Create a new node with `flywheel_stage_node_create` when needed.
+   - Update an existing node with `flywheel_get_node` + `flywheel_stage_node_update` 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.
+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`.
+   - Upload raw file bytes to the returned signed URLs.
+   - Call `flywheel_finalize_artifact_uploads` once all uploads in the batch are staged.
+   - Keep the artifact filename stable enough to reference from markdown when inline rendering matters.
+7. Add graph structure sparingly.
+   - Promote only decision-relevant relationships to edges.
+   - Leave ordinary cross-links inside the markdown body.
+8. Plan and execute validation branches against the hard max budget.
+   - Prioritize the cheapest branches that most reduce uncertainty first.
+   - Prefer explicit validation branches such as baseline checks, mechanism or intermediate-signal checks, ablations, efficiency checks, robustness checks, failure analysis, and follow-up analysis branches after results land.
+   - If the branch can run through Flywheel execution directly, use `flywheel_launch_execution` and inspect terminal status before commit.
+   - If the branch needs managed compute, use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants` or `flywheel_list_approval_sessions`, then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready.
+   - Release managed compute with `flywheel_compute_release` or `flywheel_compute_release_all` when a branch is done.
+   - 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`.
+   - Commit resolved insight nodes only when they have non-empty `insights`.
+   - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
+   - Leave unresolved plan nodes staged.
+
+## Result Contract
+
+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.
+- 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.
+- 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.
+
+For the canonical entity model and public contract terminology behind this controller, load [references/INTERFACES.md](references/INTERFACES.md).
+
+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_stage_node_create`.
+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.
+5. Update the control node with `flywheel_stage_node_update`.
+6. Read the control node with `flywheel_get_node` before later passes that need a fresh `expected_revision`.
+7. Commit the control node with `flywheel_commit_node` once the contract is coherent, even if downstream validation branches remain staged or in progress.
+
+Canonical contract shape:
+
+```md
+## Validation contract
+
+- Objective:
+- Decision criterion:
+- Source or claim nodes under test:
+- Budget ceiling:
+- Budget unit:
+- Stopping criterion:
+- Preferred branch types: optional
+```
+
+The `Source or claim nodes under test` line is the recovery anchor for later validation passes. If multiple claim nodes are in scope, list the governing node ids or slugs explicitly.
+
+## Wiki Porting
+
+Use this guide when the source material is a markdown wiki, README corpus, or a Karpathy-style LLM wiki that should become Flywheel nodes. In the flywheel-reproduce skill, do this graphification pass before empirical execution starts.
+
+### Default Mapping
+
+- One wiki page or stable concept -> one Flywheel node.
+- The main page markdown -> the node body/readme field (`content`).
+- A short synopsis of the page -> `summary`.
+- Images, PDFs, datasets, notebooks, code snippets, and other supporting files -> node artifacts.
+- Durable structural relationships -> graph edges.
+- Ordinary wiki hyperlinks -> remain markdown links inside the node body.
+
+Do not try to preserve the source wiki as a file-first mirror inside Flywheel. Flywheel is node-first.
+
+### What The Model Should Do
+
+Assume the model is expected to perform the port directly unless the user explicitly asks to build a dedicated importer.
+
+That means:
+
+1. Read the source pages and supporting files.
+2. Create or update nodes explicitly.
+3. Write the page body into node `content`.
+4. Publish supporting files as artifacts.
+5. Add only the graph edges that materially help reasoning or navigation.
+6. Split the claim-bearing work into explicit validation branches before execution.
+
+Do not wait for a magical bulk-import surface if the available Flywheel primitives are already enough.
+
+## `flywheel_import_subgraph`
+
+Use `flywheel_import_subgraph` only when the input is already normalized into Flywheel node JSON with DAG-safe edges.
+
+Do not use it for raw markdown repositories because those are usually:
+
+- file-centric rather than node-centric
+- heavily cross-linked
+- cyclic in ways that are natural for a wiki but not a clean Flywheel graph
+
+Treat raw wiki content as authoring input, not as a direct subgraph payload.
+
+## Edge Policy
+
+Promote a relation to a graph edge only when it carries durable meaning such as:
+
+- hierarchy or decomposition
+- prerequisite or dependency
+- derived-from or result-of
+- canonical comparison target
+
+Do not create edges for every incidental mention, backlink, or navigational cross-reference. Keep those inside the markdown body instead.
+
+## Inline Artifact Embeds
+
+When the node body supports inline artifact rendering, keep references on their own lines so the renderer can replace them with the matching artifact preview.
+
+Examples:
+
+```md
+![Loss curve](loss-curve.png)
+
+[Evaluation metrics](metrics.json)
+```
+
+Guidelines:
+
+- Upload the artifact first, then reference it from the body.
+- Keep filenames stable enough for the renderer to match them.
+- Use inline embeds for supporting visuals or data, but keep the main explanation in the node body itself.
+- If a reference does not match an artifact, it should remain valid markdown rather than break the page.
+
+## Guardrails
+
+- Do not treat the flywheel-reproduce skill as a magical bulk importer.
+- Do not blur `$flywheel-reproduce` and `$flywheel-auto`, because `$flywheel-reproduce` validates existing knowledge claims while `$flywheel-auto` expands a frontier autonomously under budget.
+- Build the graph explicitly with nodes, artifacts, and selected edges.
+- Keep the source material legible in `content`; do not dump everything into artifacts.
+- Keep the flywheel-reproduce skill scoped by cost and decision value, not by exhaustively trying every possible branch.
+
+See also: invoke `$flywheel-to-graph` to port source material into Flywheel without implicit execution, invoke `$flywheel-lookahead` to stage next-step frontier nodes from existing graph state without execution, and invoke `$flywheel-auto` to advance a frontier autonomously under an explicit budget and persisted stop condition.

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

@@ -0,0 +1,12 @@
+interface:
+  display_name: "flywheel-reproduce"
+  short_description: "Validate claim-bearing work in Flywheel"
+  default_prompt: "Use $flywheel-reproduce to structure this claim-bearing source in Flywheel and run budgeted validation."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "flywheel"
+      description: "Flywheel MCP server"
+      transport: "streamable_http"
+      url: "https://flywheel.paradigma.inc/mcp-server"

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

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "claim-bearing-paper-with-no-budget-yet",
+    "prompt": "Use $flywheel-reproduce to validate the central empirical claims from this paper in Flywheel. I have not given you a max budget yet, but I do want the source structured and the validation plan prepared.",
+    "expected_output": "Graphify the source and plan explicit validation branches, ask once for a hard max budget before any compute acquisition, and avoid empirical execution until the budget is explicit.",
+    "files": []
+  },
+  {
+    "id": "existing-graph-needs-validation-branches",
+    "prompt": "Use $flywheel-reproduce to validate the main claim nodes that already exist in this Flywheel graph under a hard budget ceiling of 20 credits. Prioritize the cheapest high-information checks first.",
+    "expected_output": "Recover the existing claim nodes from graph state, persist a validation contract, split the work into explicit validation branches, and execute the cheapest high-information branches first within the stated hard max budget.",
+    "files": []
+  },
+  {
+    "id": "markdown-wiki-should-not-use-import-subgraph",
+    "prompt": "Use $flywheel-reproduce to validate the strong empirical claims in this markdown wiki. The source is a raw README-style corpus, not a normalized Flywheel graph export.",
+    "expected_output": "Port the markdown/wiki source with explicit node and artifact authoring rather than `flywheel_import_subgraph`, then split the claim-bearing work into explicit validation branches for later or budgeted execution.",
+    "files": []
+  }
+]

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

@@ -0,0 +1,218 @@
+# Flywheel Artifacts
+
+Canonical reference for node artifact publishing in Flywheel MCP 0.9.
+
+Legacy note:
+
+- historical `run_artifacts` rows are retained for backward reads.
+- new artifact writes must use the MCP batch upload workflow:
+  `flywheel_prepare_artifact_uploads` -> raw file upload(s) ->
+  `flywheel_finalize_artifact_uploads`.
+
+## Node MCP Contract
+
+Artifacts are managed through node MCP tools:
+
+- `flywheel_prepare_artifact_uploads` prepares one or more signed raw-file
+  upload requests for a node.
+- The caller executes each returned upload request with raw bytes.
+- `flywheel_finalize_artifact_uploads` appends all staged uploads in that batch
+  to the node and bumps node revision once.
+- `flywheel_list_artifacts` and `flywheel_get_artifact` return artifact
+  metadata.
+- `flywheel_get_artifact_preview` reads persisted preview payload content by
+  artifact id.
+- `flywheel_commit_node` commits/finalizes node state after terminal fields are
+  already staged.
+
+Contract rules:
+
+- `flywheel_prepare_artifact_uploads` requires `expected_revision` and enforces
+  optimistic locking before issuing upload tickets.
+- Upload uses the signed one-time ticket in each returned `upload_url`;
+  client-supplied path/reference fields are not part of this contract.
+- Raw upload only stages payloads. It does not mutate node state or bump node
+  revision.
+- `flywheel_finalize_artifact_uploads` is the single node mutation point for an
+  artifact batch.
+- `flywheel_commit_node` is finalize-only:
+  - request shape is `expected_revision` with optional `summary` override.
+  - node kind/outcome/hypothesis/insights/no_artifacts_reason must already be
+    staged.
+  - commit transitions lifecycle to `committed`.
+- committed node contract rules remain strict:
+  - `kind=empirical` + `outcome=completed` requires artifacts or
+    `no_artifacts_reason`.
+  - `kind=insight` requires non-empty `insights`.
+  - `kind=empirical` requires empty `insights`.
+- MCP mutating calls require idempotency:
+  - tool transport auto-manages idempotency keys for tool calls.
+  - direct HTTP callers must provide `Idempotency-Key` on mutating MCP
+    endpoints.
+
+`artifact_type=banner` is supported for campaign root visuals. It follows the
+same raw image upload validation path as `artifact_type=image` and is intended
+for zoomed-out canvas visibility.
+
+## Prepare Request Shape
+
+`POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`
+
+```json
+{
+  "expected_revision": 7,
+  "items": [
+    {
+      "artifact_type": "image",
+      "title": "Loss curve",
+      "execution_id": "optional-execution-id",
+      "metadata": {
+        "source": "training-run"
+      },
+      "filename": "loss_curve.png",
+      "media_type": "image/png"
+    }
+  ]
+}
+```
+
+Notes:
+
+- `items` must contain at least one structured object item.
+- String or JSON-encoded item payloads are invalid at the tool boundary.
+- `filename` and `media_type` are required for each item.
+- `metadata` is caller-defined JSON.
+
+## Prepare Response Shape
+
+```json
+{
+  "batch": {
+    "batch_token": "uuid",
+    "expires_at": "2026-03-09T16:00:00+00:00",
+    "max_upload_bytes": 10485760,
+    "items": [
+      {
+        "upload_id": "uuid",
+        "upload_url": "https://.../mcp/artifacts/uploads/{upload_id}?ticket=...",
+        "method": "PUT",
+        "headers": {
+          "Content-Type": "image/png",
+          "X-Flywheel-Artifact-Filename": "loss_curve.png"
+        },
+        "curl_command": "curl -sS -X PUT '...' -H 'Content-Type: image/png' -H 'X-Flywheel-Artifact-Filename: loss_curve.png' --data-binary @/absolute/path/to/file"
+      }
+    ]
+  }
+}
+```
+
+## Raw Upload Step
+
+Execute each returned request exactly:
+
+- Method: `PUT`
+- URL: `batch.items[i].upload_url`
+- Body: raw file bytes
+- Headers:
+  - `Content-Type` (media type)
+  - `X-Flywheel-Artifact-Filename` (filename hint)
+
+A successful upload:
+
+- validates the uploaded bytes against the requested artifact type
+- stages canonical payload JSON in blob storage
+- returns `202 Accepted`
+- does not yet append an artifact record to the node
+
+## Finalize Request and Response
+
+`POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`
+
+```json
+{
+  "batch_token": "uuid"
+}
+```
+
+Successful finalize:
+
+- validates the batch is complete and still revision-compatible
+- appends all staged artifacts to the node
+- persists canonical payload JSON to `artifacts/nodes/{node_id}/{artifact_id}.json`
+- bumps node revision once
+- returns `{ "node": ..., "artifacts": [...] }`
+
+## Artifact Preview Behavior
+
+Artifact preview endpoint:
+`GET /mcp/nodes/{node_id}/artifacts/{artifact_id}/preview`.
+MCP tool: `flywheel_get_artifact_preview`.
+
+- Preview reads canonical persisted payload blob (`storage_path`) only.
+- No workspace dependency or local-file fallback is required.
+- `data_url` in preview responses is render output only; never upload JSON
+  metadata wrappers.
+- Preview-normalized types:
+  - `image` -> image payload with `data_url`
+  - `html` / `plotly_html` -> HTML payload
+  - `json` -> JSON payload
+  - `text` / `diff_carousel` and common text/code extensions -> text payload
+
+## WebUI Artifact Payload Reads
+
+When artifacts are projected through node responses, the server returns
+normalized storage references for each artifact payload:
+
+- `storage_path`: canonical blob path (for example
+  `artifacts/nodes/{node_id}/{artifact_id}.json`).
+- `storage_url`: the single client/host read URL for that payload.
+  - All blob backends: `/blobs/{storage_path}` authenticated byte-serving
+    proxy after access checks.
+
+Clients should read artifact bytes from `storage_url` only. `storage_path`
+remains metadata/debug context and must not be reconstructed into fetch URLs by
+clients. Payload loads are coordinated through a shared loader with in-flight
+deduplication, cache reuse, and bounded fetch concurrency to avoid bursty
+request storms and `429` backpressure under artifact-heavy nodes.
+
+The node overview panel additionally avoids eager load spikes by defaulting to
+collapsed mode for artifact-heavy nodes and deferring artifact rendering until
+cards approach the viewport.
+
+## Artifact Load Telemetry
+
+The WebUI emits a batched first-party product analytics event,
+`web_artifact_payload_batch`, through `POST /analytics/events`.
+
+This event is intended for aggregate artifact read-path observability and
+includes fields such as:
+
+- load volume (`loads_started`, `loads_completed`, `loads_failed`)
+- rate-limit incidence (`loads_429`)
+- queue/load latency aggregates
+- source mix (`/blobs/*` authenticated proxy)
+- top per-node load/failure summaries in the batch window
+
+## File Inventory Surfaces
+
+Artifacts and attachments are exposed through two HTTP inventory endpoints:
+
+- `GET /users/me/files` for account-wide browsing in Settings.
+- `GET /nodes/{node_id}/files` for node lineage-scoped browsing in the node
+  details panel.
+
+Inventory entries include source context (`node_id`, `execution_id`) so the UI
+can jump directly to the originating node or execution.
+
+## Common Invalid Payload Causes
+
+- stale `expected_revision` at prepare or finalize time
+- missing/invalid upload ticket
+- expired upload ticket or batch
+- upload body exceeds configured size limit
+- uploaded bytes do not match requested artifact format (for example invalid
+  JSON)
+- finalize called before every prepared upload is staged
+- commit contract violations (for example empirical `completed` without
+  artifacts or `no_artifacts_reason`)