@paradigma-inc/flywheel 0.1.82 → 0.1.85

package/README.md

@@ -71,8 +71,34 @@ cargo binstall usage-cli
 pacman -S usage
 ```
 
-Generate the script for your shell and redirect it wherever your shell setup
-loads completions:
+Install generated completions into user-level locations:
+
+```bash
+flywheel completion install bash
+flywheel completion install zsh --update-profile --yes
+flywheel completion install fish
+flywheel completion install powershell --update-profile --yes
+flywheel completion install nu
+flywheel completion install nushell
+```
+
+Remove Flywheel-managed completion files and profile blocks with the matching
+uninstall command:
+
+```bash
+flywheel completion uninstall bash
+flywheel completion uninstall zsh --update-profile --yes
+flywheel completion uninstall fish
+flywheel completion uninstall powershell --update-profile --yes
+flywheel completion uninstall nu
+```
+
+Profile/startup file edits are opt-in. Without `--update-profile`, installation
+writes only the generated completion file. Use `--dry-run` to inspect planned
+changes, `--dir <path>` to choose a destination directory, and `--force` only
+when replacing an existing unmarked completion file.
+
+You can also generate the script for your shell and redirect it yourself:
 
 ```bash
 flywheel completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/flywheel
@@ -83,8 +109,10 @@ 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.
+`flywheel completion <shell>` generates scripts only. It does not install
+completions, touch shell startup files, or edit shell profiles. `flywheel setup`
+also does not install completions; completion installation remains an explicit
+`flywheel completion install <shell>` action.
 
 ## Uninstall
 

package/package.json

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

package/skills/flywheel/references/INTERFACES.md

@@ -26,6 +26,13 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - 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.
 
+Node detail reads are cardinality-safe: `flywheel_get_node` / `GET /nodes/{node_id}`
+return node fields plus `has_children` / `has_parents` presence booleans, but do
+not guarantee complete `incoming_ids` or `outgoing_ids` arrays. Use
+`flywheel_get_node_children` / `GET /nodes/{node_id}/children` and
+`flywheel_get_node_parents` / `GET /nodes/{node_id}/parents` for complete
+direct-neighbor traversal.
+
 ## MCP Tool Surface
 
 ### Discovery and sharing
@@ -42,6 +49,8 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_get_node` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_children` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_parents` (read; scopes: `read`; core surface; binding: `operation`)
 - `flywheel_create_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_update_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)

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

@@ -35,7 +35,9 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `flywheel nodes:sharing:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node_sharing`): Get sharing (access policy) for a node.
 - `flywheel nodes:sharing:set` (mutating; scopes: `write`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_set_sharing_for_node`): Replace sharing (access policy) for a node.
 - `flywheel nodes:sharing:set-bulk` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; MCP equivalent: `flywheel_set_sharing_for_nodes`): Apply one sharing policy to multiple nodes.
-- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier.
+- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier. Relationship arrays are not guaranteed complete; use relationship paging commands for traversal.
+- `flywheel nodes:children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; MCP equivalent: `flywheel_get_node_children`): Page direct visible children with `--first`, `--after`, and `--projection`.
+- `flywheel nodes:parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; MCP equivalent: `flywheel_get_node_parents`): Page direct visible parents with `--first`, `--after`, and `--projection`.
 - `flywheel tags:create` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; MCP equivalent: `flywheel_create_node_tag`): Create a reusable tag on a graph root.
 - `flywheel tags:update` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_update_node_tag`): Update a tag definition.
 - `flywheel tags:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_delete_node_tag`): Delete a tag definition from the graph.

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

@@ -39,7 +39,9 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `tool-mediated`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `tool-mediated`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
-- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id. Relationship arrays are not guaranteed complete; use relationship paging tools for traversal.
+- `flywheel_get_node_children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; core surface): Page direct visible children with `first`, `after`, and `projection`.
+- `flywheel_get_node_parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; core surface): Page direct visible parents with `first`, `after`, and `projection`.
 - `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node. `track_history` is effective only when `one_only=true`; when `one_only=false`, the effective track_history=false.
 - `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.

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

@@ -42,9 +42,9 @@ Hooks are event-driven automations:
   `artifact.finalized` and `node.published`.
 - **Hook**: a durable rule configured on a node (trigger + scope + action).
 - **Run**: one execution record when a hook reacts to an event.
-- Hooks are dispatched by `worker-projection` and executed by ephemeral Fly Machines runners.
+- Hooks are dispatched by `worker-hooks` and executed by ephemeral Fly Machines runners.
 - Each hook run launches `python -m server.run_hook_runner` in the same Fly app (`FLYWHEEL_HOOK_RUNNER_FLY_APP`).
-- Deployments roll out `worker-projection`; runner launches require `FLYWHEEL_HOOK_RUNNER_FLY_API_TOKEN` and `FLYWHEEL_HOOK_RUNNER_FLY_APP`.
+- Deployments roll out `worker-hooks` before `worker-projection`; runner launches require `FLYWHEEL_HOOK_RUNNER_FLY_API_TOKEN` and `FLYWHEEL_HOOK_RUNNER_FLY_APP`.
 
 Typical setup:
 

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

@@ -26,6 +26,13 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - 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.
 
+Node detail reads are cardinality-safe: `flywheel_get_node` / `GET /nodes/{node_id}`
+return node fields plus `has_children` / `has_parents` presence booleans, but do
+not guarantee complete `incoming_ids` or `outgoing_ids` arrays. Use
+`flywheel_get_node_children` / `GET /nodes/{node_id}/children` and
+`flywheel_get_node_parents` / `GET /nodes/{node_id}/parents` for complete
+direct-neighbor traversal.
+
 ## MCP Tool Surface
 
 ### Discovery and sharing
@@ -42,6 +49,8 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_get_node` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_children` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_parents` (read; scopes: `read`; core surface; binding: `operation`)
 - `flywheel_create_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_update_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)

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

@@ -34,7 +34,9 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `flywheel nodes:sharing:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node_sharing`): Get sharing (access policy) for a node.
 - `flywheel nodes:sharing:set` (mutating; scopes: `write`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_set_sharing_for_node`): Replace sharing (access policy) for a node.
 - `flywheel nodes:sharing:set-bulk` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; MCP equivalent: `flywheel_set_sharing_for_nodes`): Apply one sharing policy to multiple nodes.
-- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier.
+- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier. Relationship arrays are not guaranteed complete; use relationship paging commands for traversal.
+- `flywheel nodes:children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; MCP equivalent: `flywheel_get_node_children`): Page direct visible children with `--first`, `--after`, and `--projection`.
+- `flywheel nodes:parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; MCP equivalent: `flywheel_get_node_parents`): Page direct visible parents with `--first`, `--after`, and `--projection`.
 - `flywheel tags:create` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; MCP equivalent: `flywheel_create_node_tag`): Create a reusable tag on a graph root.
 - `flywheel tags:update` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_update_node_tag`): Update a tag definition.
 - `flywheel tags:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_delete_node_tag`): Delete a tag definition from the graph.

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

@@ -38,7 +38,9 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `tool-mediated`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `tool-mediated`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
-- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id. Relationship arrays are not guaranteed complete; use relationship paging tools for traversal.
+- `flywheel_get_node_children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; core surface): Page direct visible children with `first`, `after`, and `projection`.
+- `flywheel_get_node_parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; core surface): Page direct visible parents with `first`, `after`, and `projection`.
 - `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node. `track_history` is effective only when `one_only=true`; when `one_only=false`, the effective track_history=false.
 - `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.

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

@@ -26,6 +26,13 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - 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.
 
+Node detail reads are cardinality-safe: `flywheel_get_node` / `GET /nodes/{node_id}`
+return node fields plus `has_children` / `has_parents` presence booleans, but do
+not guarantee complete `incoming_ids` or `outgoing_ids` arrays. Use
+`flywheel_get_node_children` / `GET /nodes/{node_id}/children` and
+`flywheel_get_node_parents` / `GET /nodes/{node_id}/parents` for complete
+direct-neighbor traversal.
+
 ## MCP Tool Surface
 
 ### Discovery and sharing
@@ -42,6 +49,8 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_get_node` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_children` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_parents` (read; scopes: `read`; core surface; binding: `operation`)
 - `flywheel_create_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_update_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)

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

@@ -34,7 +34,9 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `flywheel nodes:sharing:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node_sharing`): Get sharing (access policy) for a node.
 - `flywheel nodes:sharing:set` (mutating; scopes: `write`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_set_sharing_for_node`): Replace sharing (access policy) for a node.
 - `flywheel nodes:sharing:set-bulk` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; MCP equivalent: `flywheel_set_sharing_for_nodes`): Apply one sharing policy to multiple nodes.
-- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier.
+- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier. Relationship arrays are not guaranteed complete; use relationship paging commands for traversal.
+- `flywheel nodes:children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; MCP equivalent: `flywheel_get_node_children`): Page direct visible children with `--first`, `--after`, and `--projection`.
+- `flywheel nodes:parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; MCP equivalent: `flywheel_get_node_parents`): Page direct visible parents with `--first`, `--after`, and `--projection`.
 - `flywheel tags:create` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; MCP equivalent: `flywheel_create_node_tag`): Create a reusable tag on a graph root.
 - `flywheel tags:update` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_update_node_tag`): Update a tag definition.
 - `flywheel tags:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_delete_node_tag`): Delete a tag definition from the graph.

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

@@ -38,7 +38,9 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `tool-mediated`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `tool-mediated`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
-- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id. Relationship arrays are not guaranteed complete; use relationship paging tools for traversal.
+- `flywheel_get_node_children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; core surface): Page direct visible children with `first`, `after`, and `projection`.
+- `flywheel_get_node_parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; core surface): Page direct visible parents with `first`, `after`, and `projection`.
 - `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node. `track_history` is effective only when `one_only=true`; when `one_only=false`, the effective track_history=false.
 - `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.

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

@@ -26,6 +26,13 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - 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.
 
+Node detail reads are cardinality-safe: `flywheel_get_node` / `GET /nodes/{node_id}`
+return node fields plus `has_children` / `has_parents` presence booleans, but do
+not guarantee complete `incoming_ids` or `outgoing_ids` arrays. Use
+`flywheel_get_node_children` / `GET /nodes/{node_id}/children` and
+`flywheel_get_node_parents` / `GET /nodes/{node_id}/parents` for complete
+direct-neighbor traversal.
+
 ## MCP Tool Surface
 
 ### Discovery and sharing
@@ -42,6 +49,8 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_get_node` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_children` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_parents` (read; scopes: `read`; core surface; binding: `operation`)
 - `flywheel_create_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_update_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)

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

@@ -34,7 +34,9 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `flywheel nodes:sharing:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node_sharing`): Get sharing (access policy) for a node.
 - `flywheel nodes:sharing:set` (mutating; scopes: `write`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_set_sharing_for_node`): Replace sharing (access policy) for a node.
 - `flywheel nodes:sharing:set-bulk` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; MCP equivalent: `flywheel_set_sharing_for_nodes`): Apply one sharing policy to multiple nodes.
-- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier.
+- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier. Relationship arrays are not guaranteed complete; use relationship paging commands for traversal.
+- `flywheel nodes:children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; MCP equivalent: `flywheel_get_node_children`): Page direct visible children with `--first`, `--after`, and `--projection`.
+- `flywheel nodes:parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; MCP equivalent: `flywheel_get_node_parents`): Page direct visible parents with `--first`, `--after`, and `--projection`.
 - `flywheel tags:create` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; MCP equivalent: `flywheel_create_node_tag`): Create a reusable tag on a graph root.
 - `flywheel tags:update` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_update_node_tag`): Update a tag definition.
 - `flywheel tags:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_delete_node_tag`): Delete a tag definition from the graph.

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

@@ -38,7 +38,9 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `tool-mediated`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `tool-mediated`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
-- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id. Relationship arrays are not guaranteed complete; use relationship paging tools for traversal.
+- `flywheel_get_node_children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; core surface): Page direct visible children with `first`, `after`, and `projection`.
+- `flywheel_get_node_parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; core surface): Page direct visible parents with `first`, `after`, and `projection`.
 - `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node. `track_history` is effective only when `one_only=true`; when `one_only=false`, the effective track_history=false.
 - `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.

package/skills/flywheel-to-graph/references/INTERFACES.md

@@ -26,6 +26,13 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - 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.
 
+Node detail reads are cardinality-safe: `flywheel_get_node` / `GET /nodes/{node_id}`
+return node fields plus `has_children` / `has_parents` presence booleans, but do
+not guarantee complete `incoming_ids` or `outgoing_ids` arrays. Use
+`flywheel_get_node_children` / `GET /nodes/{node_id}/children` and
+`flywheel_get_node_parents` / `GET /nodes/{node_id}/parents` for complete
+direct-neighbor traversal.
+
 ## MCP Tool Surface
 
 ### Discovery and sharing
@@ -42,6 +49,8 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_get_node` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_children` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_parents` (read; scopes: `read`; core surface; binding: `operation`)
 - `flywheel_create_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_update_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)

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

@@ -34,7 +34,9 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `flywheel nodes:sharing:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node_sharing`): Get sharing (access policy) for a node.
 - `flywheel nodes:sharing:set` (mutating; scopes: `write`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_set_sharing_for_node`): Replace sharing (access policy) for a node.
 - `flywheel nodes:sharing:set-bulk` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; MCP equivalent: `flywheel_set_sharing_for_nodes`): Apply one sharing policy to multiple nodes.
-- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier.
+- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier. Relationship arrays are not guaranteed complete; use relationship paging commands for traversal.
+- `flywheel nodes:children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; MCP equivalent: `flywheel_get_node_children`): Page direct visible children with `--first`, `--after`, and `--projection`.
+- `flywheel nodes:parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; MCP equivalent: `flywheel_get_node_parents`): Page direct visible parents with `--first`, `--after`, and `--projection`.
 - `flywheel tags:create` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; MCP equivalent: `flywheel_create_node_tag`): Create a reusable tag on a graph root.
 - `flywheel tags:update` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_update_node_tag`): Update a tag definition.
 - `flywheel tags:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_delete_node_tag`): Delete a tag definition from the graph.

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

@@ -38,7 +38,9 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `tool-mediated`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
 - `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `tool-mediated`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
 - `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
-- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id. Relationship arrays are not guaranteed complete; use relationship paging tools for traversal.
+- `flywheel_get_node_children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; core surface): Page direct visible children with `first`, `after`, and `projection`.
+- `flywheel_get_node_parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; core surface): Page direct visible parents with `first`, `after`, and `projection`.
 - `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node. `track_history` is effective only when `one_only=true`; when `one_only=false`, the effective track_history=false.
 - `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
 - `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.

package/src/cli.mjs

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { checkbox, select } from "@inquirer/prompts";
+import { checkbox, confirm, select } from "@inquirer/prompts";
 import ora from "ora";
 import pc from "picocolors";
 import { access, readFile, rm } from "node:fs/promises";
@@ -16,6 +16,10 @@ import {
   normalizeHosts,
 } from "./agents.mjs";
 import { generateCompletionScript } from "./completion.mjs";
+import {
+  installCompletion,
+  uninstallCompletion,
+} from "./completion-install.mjs";
 import {
   readEntryServerUrl,
   readNamedConfigEntry,
@@ -491,6 +495,52 @@ async function runCompletionCommand(shell, options) {
   }
 }
 
+async function runCompletionInstallCommand(shell, options) {
+  try {
+    await installCompletion({
+      shell,
+      dir: options.dir,
+      force: options.force === true,
+      dryRun: options.dryRun === true,
+      updateProfile: options.updateProfile === true,
+      yes: options.yes === true,
+      isInteractive:
+        process.stdin.isTTY === true && process.stdout.isTTY === true,
+      stdout: (chunk) => process.stdout.write(chunk),
+      stderr: (chunk) => process.stderr.write(chunk),
+      confirmProfileUpdate: async ({ message, default: defaultValue }) =>
+        await confirm({ message, default: defaultValue }),
+      generateCompletionScript,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+async function runCompletionUninstallCommand(shell, options) {
+  try {
+    await uninstallCompletion({
+      shell,
+      dir: options.dir,
+      dryRun: options.dryRun === true,
+      updateProfile: options.updateProfile === true,
+      yes: options.yes === true,
+      isInteractive:
+        process.stdin.isTTY === true && process.stdout.isTTY === true,
+      stdout: (chunk) => process.stdout.write(chunk),
+      stderr: (chunk) => process.stderr.write(chunk),
+      confirmProfileUpdate: async ({ message, default: defaultValue }) =>
+        await confirm({ message, default: defaultValue }),
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  }
+}
+
 function parseUninstallScope(value) {
   const normalized = String(value || "")
     .trim()
@@ -1162,9 +1212,10 @@ Examples:
 `,
     );
 
-  program
-    .command("completion <shell>")
+  const completionCommand = program
+    .command("completion")
     .description("Generate a shell completion script")
+    .argument("[shell]", "Shell to generate completions for")
     .addHelpText(
       "before",
       `${pc.bold(pc.cyan("✻ Flywheel Completion"))}
@@ -1198,9 +1249,74 @@ Examples:
 `,
     )
     .action(async (shell, options) => {
+      if (!shell) {
+        completionCommand.help();
+        return;
+      }
       await runCompletionCommand(shell, options);
     });
 
+  completionCommand
+    .command("install <shell>")
+    .description("Install generated shell completion scripts")
+    .option("--dir <path>", "Override completion script destination directory")
+    .option("--force", "Replace an existing unmarked destination file")
+    .option("--dry-run", "Print planned changes without writing files")
+    .option("--update-profile", "Allow shell startup/profile file updates")
+    .option("-y, --yes", "Skip confirmation prompts")
+    .addHelpText(
+      "before",
+      `${pc.bold(pc.cyan("✻ Flywheel Completion Install"))}
+
+Install generated Flywheel shell completions to user-level locations.
+Supported shells: ${COMPLETION_SHELL_CHOICES.join(", ")}.
+`,
+    )
+    .addHelpText(
+      "after",
+      `
+Examples:
+  ${pc.green("flywheel completion install bash")}
+  ${pc.green("flywheel completion install zsh --update-profile --yes")}
+  ${pc.green("flywheel completion install fish")}
+  ${pc.green("flywheel completion install powershell --update-profile --yes")}
+  ${pc.green("flywheel completion install nu")}
+`,
+    )
+    .action(async (shell, options) => {
+      await runCompletionInstallCommand(shell, options);
+    });
+
+  completionCommand
+    .command("uninstall <shell>")
+    .description("Uninstall Flywheel-managed shell completion scripts")
+    .option("--dir <path>", "Override completion script destination directory")
+    .option("--dry-run", "Print planned removals without writing files")
+    .option("--update-profile", "Allow shell startup/profile file updates")
+    .option("-y, --yes", "Skip confirmation prompts")
+    .addHelpText(
+      "before",
+      `${pc.bold(pc.cyan("✻ Flywheel Completion Uninstall"))}
+
+Remove only Flywheel-managed shell completion files and profile blocks.
+Supported shells: ${COMPLETION_SHELL_CHOICES.join(", ")}.
+`,
+    )
+    .addHelpText(
+      "after",
+      `
+Examples:
+  ${pc.green("flywheel completion uninstall bash")}
+  ${pc.green("flywheel completion uninstall zsh --update-profile --yes")}
+  ${pc.green("flywheel completion uninstall fish")}
+  ${pc.green("flywheel completion uninstall powershell --update-profile --yes")}
+  ${pc.green("flywheel completion uninstall nu")}
+`,
+    )
+    .action(async (shell, options) => {
+      await runCompletionUninstallCommand(shell, options);
+    });
+
   program
     .command("setup")
     .description("Set up Flywheel for your AI coding host")