@paradigma-inc/flywheel 0.1.9 → 0.1.11

package/package.json

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

package/skills/flywheel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flywheel
-description: Use for Flywheel experiment design, MCP-assisted execution, and platform setup/troubleshooting across supported hosts.
+description: Use for Flywheel experiment design, turning source material into Flywheel graphs, staged frontier planning with `/lookahead`, budgeted autonomous research with `/fsd`, MCP-assisted execution, and platform setup/troubleshooting across supported hosts.
 ---
 
 # Flywheel Skill
@@ -12,6 +12,9 @@ Use this skill to structure research work and to route setup/support questions t
 Use this skill when the conversation is about any of the following:
 
 - planning experiments, hypotheses, comparisons, or next-branch decisions
+- turning source material into a Flywheel graph
+- using command-like Flywheel workflows such as `/to-graph`, `/reproduce`,
+  `/lookahead`, or `/fsd`
 - running or interpreting empirical work in Flywheel
 - choosing between `insight` and `empirical` nodes
 - setting up, updating, authenticating, or troubleshooting Flywheel MCP
@@ -23,17 +26,23 @@ If the request is ambiguous, default to experiment-design guidance before platfo
 
 1. Classify the request as research guidance, platform support, or mixed.
 2. Load only the minimum files needed for the current task.
-3. For research requests, run a short design pass before execution:
+3. If the user is using command-like language such as `/to-graph`,
+   `/reproduce`, `/lookahead`, or `/fsd`, load
+   `reference/command-presets.md` first.
+4. For research requests, run a short design pass before execution:
    ask 1-2 questions to clarify objective, assumptions, and decision criteria.
-4. If design is solid and the user wants to proceed, shift to execution support.
-5. Use Flywheel MCP tools for live behavior/contract checks when available.
-6. Summarize evidence and propose the most likely next branch.
+5. If design is solid and the user wants to proceed, shift to execution support.
+6. Use Flywheel MCP tools for live behavior/contract checks when available.
+7. Summarize evidence and propose the most likely next branch.
 
 ## Routing Map
 
 Choose one primary file first, then add at most one supporting file only if needed:
 
 - `reference/experiment-design-protocol.md` for structured experiment design and readiness checks
+- `reference/command-presets.md` for `/to-graph`, `/reproduce`, `/lookahead`,
+  and `/fsd`
+- `reference/wiki-porting.md` when the user asks to port a markdown/wiki corpus
 - `reference/flywheel-mcp-tool-map.md` for exact tool surface and contract behavior
 - `getting-started/flywheel-tutorial-overview.md` for orientation and learning path
 - `getting-started/flywheel-quickstart.md` for fastest first-use setup and auth recovery
@@ -50,3 +59,12 @@ Choose one primary file first, then add at most one supporting file only if need
 - Prefer concrete steps and decision points over long narrative explanations.
 - Do not run broad document reads; load only what is required by the current request.
 - Do not start compute-heavy execution before design intent is clear.
+- Keep `/reproduce` narrow: validate existing knowledge claims rather than
+  expanding an open-ended research frontier.
+- Treat `/lookahead` as planning only and `/fsd` as budgeted autonomous
+  frontier advancement.
+
+## Wiki Porting
+
+When asked to port a markdown wiki, load `reference/wiki-porting.md` before
+acting.

package/skills/flywheel/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Flywheel"
-  short_description: "Guide Flywheel experiment design, setup, tools, and workflows"
-  default_prompt: "Use $flywheel to answer Flywheel experiment, setup, MCP tool, compute, campaign, or Web UI questions."
+  short_description: "Guide Flywheel graph planning, research, and setup"
+  default_prompt: "Use $flywheel to answer Flywheel experiment, graph, setup, MCP tool, compute, campaign, or Web UI questions. Treat /to-graph as graph construction only, /reproduce as budgeted validation of existing knowledge, /lookahead as staged frontier planning, and /fsd as budgeted autonomous frontier advancement that stays n steps ahead."
 
 dependencies:
   tools:

package/skills/flywheel/reference/command-presets.md

@@ -0,0 +1,230 @@
+# Command Presets
+
+Use this guide when the user frames the request as `/to-graph`,
+`/reproduce`, `/lookahead`, `/fsd`, or equivalent command-like language.
+
+These are workflow presets inside the Flywheel skill. They are not separate
+product surfaces.
+
+## `/to-graph`
+
+Use `/to-graph` when the user's main goal is to convert unstructured source
+material into a Flywheel graph.
+
+Typical inputs:
+
+- paper
+- blogpost
+- README
+- markdown wiki
+- research notes
+
+Output contract:
+
+- create or update a root node or subtree
+- put the primary narrative in node `content`
+- attach supporting files as artifacts
+- add only durable graph edges
+
+Execution policy:
+
+- do not acquire compute by default
+- do not spend budget implicitly
+- execution only happens if the user explicitly asks to run branches
+
+Default mapping:
+
+- stable page or concept -> one node
+- main markdown/text -> `content`
+- short synopsis -> `summary`
+- figures, PDFs, datasets, notebooks, code, tables -> artifacts
+- durable semantic relationships -> edges
+- ordinary hyperlinks or citations -> remain in markdown unless they deserve an
+  actual graph relationship
+
+## `/reproduce`
+
+Use `/reproduce` when the source is claim-bearing and the user wants Flywheel
+to both structure the source and run empirical validation.
+
+`/reproduce` is conceptually:
+
+```text
+/to-graph --mode reproduce --execute
+```
+
+That means:
+
+1. graphify the source first
+2. split it into explicit validation branches
+3. execute those branches within a hard maximum budget
+
+Typical sources:
+
+- research papers
+- benchmark claims
+- blogposts with strong empirical claims
+- replication requests on an existing Flywheel graph
+
+Budget semantics:
+
+- a max budget is a hard ceiling, not a soft preference
+- if no max budget is given, ask for one before any compute acquisition
+- until the budget is explicit, planning and graph construction may proceed, but
+  empirical execution should not start
+- prefer the highest-information, lowest-cost branches first
+- stop when the claim is resolved or the budget limit is reached
+
+Default branch types:
+
+- baseline sanity check
+- mechanism or intermediate-signal check
+- ablation
+- efficiency or overhead check
+- robustness or failure-mode check
+- follow-up analysis branch after results land
+
+## `/lookahead`
+
+Use `/lookahead` when the user wants Flywheel to plan the next frontier of work
+from an existing set of nodes without executing it yet.
+
+`/lookahead` is conceptually:
+
+```text
+/plan-frontier --execute=false
+```
+
+That means:
+
+1. resolve a starting set of Flywheel nodes
+2. resolve a measurable objective for those nodes
+3. expand the frontier into staged next-step nodes
+
+Starting-node policy:
+
+- prefer explicit node ids, slugs, or directly named nodes
+- otherwise use the focused or recently referenced graph context
+- if no stable starting set can be recovered, ask
+
+Objective policy:
+
+- if the objective is missing, ask for one
+- if the user insists on not specifying it, infer the objective from the graph
+  context and state it explicitly before planning
+- the objective must be measurable enough to rank frontier branches
+
+Lookahead policy:
+
+- depth `n` means plan `n` hops ahead from the currently resolved frontier
+- default `n=1`
+- width `k` means expand up to `k` non-redundant frontier directions
+- avoid redundant siblings that only restate the same branch with different
+  wording
+
+Node-typing policy:
+
+- if a planned node is expected to produce evidence or artifacts, type it
+  `empirical`
+- otherwise type it `insight`
+- leave planned nodes staged until the underlying work has a resolution
+
+Output contract:
+
+- create or update a graph-local planning contract
+- write the objective, depth `n`, width `k`, and terminal condition into the
+  graph
+- stage the next frontier of nodes without hidden execution
+
+## `/fsd`
+
+Use `/fsd` ("full self-driving") when the user wants Flywheel to keep
+advancing a research frontier autonomously under a specified budget.
+
+`/fsd` is conceptually:
+
+```text
+/lookahead --execute --replan-after-each-resolution
+```
+
+That means:
+
+1. resolve starting nodes
+2. resolve a measurable objective
+3. resolve a hard budget
+4. expand the frontier up to depth `n` and width `k`
+5. execute up to `k` frontier branches in parallel
+6. refresh the lookahead after each resolved node so the graph stays `n` hops
+   ahead
+
+Budget semantics:
+
+- credits are the default budget unit unless the user specifies another
+  measurable budget semantic
+- the budget is a hard ceiling, not a soft preference
+- if no budget is given, ask before execution starts
+- if the user supplies a non-credit budget unit, persist that exact unit in the
+  graph-local control contract
+
+Objective policy:
+
+- if the objective is missing, ask for one
+- if the user refuses to specify it, infer it from the existing graph context
+  and state it explicitly before execution
+- the objective must be precise enough that the model can decide whether a
+  branch is advancing or stalling it
+
+Width and worker policy:
+
+- `k` always means maximum distinct frontier directions
+- in `/fsd`, that same `k` also caps concurrent workers
+- if more than `k` worthwhile branches exist, route the extra branches in
+  sequence via the parent model
+
+Termination policy:
+
+- do not rely on new user feedback to decide whether to continue
+- before execution, persist a graph-local terminal condition that later steps
+  can read directly from node state
+- stop when the persisted condition is met, for example:
+  - objective reached
+  - hard budget exhausted
+  - no non-redundant frontier branch with positive expected value remains
+
+Graph-maintenance policy:
+
+- keep unresolved planned nodes staged
+- commit nodes only when their work has a resolution
+- empirical nodes should accumulate the expected evidence or artifact before
+  completion
+- insight nodes should only be committed once the synthesis is actually known
+
+## Choosing Between Them
+
+Use `/to-graph` when the user wants structure from source material.
+
+Use `/reproduce` when the user wants structure plus budgeted validation of
+existing knowledge.
+
+Use `/lookahead` when the user wants staged next-step planning from existing
+nodes.
+
+Use `/fsd` when the user wants budgeted autonomous frontier advancement.
+
+If a graph starts as `/lookahead`, `/fsd` should resume from the same graph and
+keep it `n` steps ahead rather than planning from scratch each time.
+
+## Guardrails
+
+- Do not hide spend behind `/to-graph`.
+- Do not treat `/reproduce` as a magical bulk importer.
+- Do not blur `/reproduce` and `/fsd`.
+- `/reproduce` validates existing knowledge claims.
+- `/fsd` expands the frontier to create new knowledge 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 `/reproduce` scoped by cost and decision value, not by exhaustively
+  trying every possible branch.
+- Keep `/fsd` graph-local: future continuation and stopping decisions should be
+  derivable from the persisted node state rather than from fresh chat context.

package/skills/flywheel/reference/wiki-porting.md

@@ -0,0 +1,92 @@
+# 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.
+
+## 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/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.
+
+Do not wait for a magical "import this wiki" product 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/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/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.
+
+## Recommended Node Authoring Sequence
+
+1. Create the node with `flywheel_stage_node_create` if it does not exist.
+2. Read the latest node with `flywheel_get_node` before writes that need fresh
+   `expected_revision`.
+3. Stage node fields with `flywheel_stage_node_update`, putting the primary
+   markdown in `content`.
+4. Publish each supporting file with `flywheel_prepare_artifact_publish`.
+5. Add selected graph structure through the relevant graph tools when that
+   relationship matters.
+6. Commit once the node snapshot is coherent.

package/skills/flywheel/setting-up-flywheel/how-can-i-get-an-authorized-client_id-for-the-oauth-flow.md

@@ -14,7 +14,7 @@ That response includes the OAuth endpoints (`authorization_endpoint`, `token_end
 
 Then register your OAuth client using the `registration_endpoint`.
 
-## [](https://flywheel-staging.paradigma.inc/tutorial#public-client-default)Public client (default)
+## [](https://flywheel.paradigma.inc/tutorial#public-client-default)Public client (default)
 
 This is the default for interactive MCP hosts (for example Claude Code, IDE hosts, local desktop clients). If `token_endpoint_auth_method` is omitted, we default to `none`.
 
@@ -31,7 +31,7 @@ curl -sS -X POST https://flywheel.paradigma.inc/mcp-server/register \
 
 The response returns a `client_id` and no `client_secret`.
 
-## [](https://flywheel-staging.paradigma.inc/tutorial#confidential-client-optional)Confidential client (optional)
+## [](https://flywheel.paradigma.inc/tutorial#confidential-client-optional)Confidential client (optional)
 
 Use this when your app has a trusted backend that can securely store secrets.
 

package/skills/flywheel/setting-up-flywheel/installation-overview.md

@@ -4,7 +4,7 @@ We are in the business of automating science. As such, our first interface to Fl
 
 MCP enables you to natively connect and authenticate Flywheel to any compatible hosts. We recommend using Flywheel with [Codex](https://github.com/openai/codex) or [Claude code](https://github.com/anthropics/claude-code), but any MCP host should work.
 
-## [](https://flywheel-staging.paradigma.inc/tutorial#one-command-setup-recommended)One-command setup (recommended)
+## [](https://flywheel.paradigma.inc/tutorial#one-command-setup-recommended)One-command setup (recommended)
 
 Simply run:
 
@@ -12,7 +12,7 @@ Simply run:
 npx @paradigma-inc/flywheel setup
 ```
 
-## [](https://flywheel-staging.paradigma.inc/tutorial#reinstall--cleanup)Reinstall / cleanup
+## [](https://flywheel.paradigma.inc/tutorial#reinstall--cleanup)Reinstall / cleanup
 
 ```bash
 npx @paradigma-inc/flywheel setup
@@ -21,6 +21,6 @@ npx @paradigma-inc/flywheel uninstall
 
 `uninstall` removes Flywheel MCP entries from host config files.
 
-## [](https://flywheel-staging.paradigma.inc/tutorial#web-connector-hosts-chatgptcom--claudeai--etc-)Web connector hosts (ChatGPT.com / Claude.ai / etc. )
+## [](https://flywheel.paradigma.inc/tutorial#web-connector-hosts-chatgptcom--claudeai--etc-)Web connector hosts (ChatGPT.com / Claude.ai / etc. )
 
 Web connector hosts can still use OAuth-style connector flows. Keep using those host-native connector install UIs for ChatGPT.com custom apps, Claude.ai custom connectors, etc. Simply put `https://flywheel.paradigma.inc/mcp-server` as the URL when prompted.