@paradigma-inc/flywheel 0.1.53 → 0.1.60

package/README.md

@@ -38,6 +38,31 @@ Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
 ```
 
+## Uninstall
+
+One-shot uninstaller (macOS and Linux):
+
+```bash
+curl -fsSL https://flywheel.paradigma.inc/uninstall | sh
+```
+
+The script removes Flywheel MCP entries, bundled skills, the global
+`@paradigma-inc/flywheel` package, the `flywheel` binary, default CLI
+config/profiles under `~/.config/flywheel-cli`, and the local runtime cache
+under `~/.flywheel`. It does not delete remote Flywheel account data, nodes,
+artifacts, billing data, GitHub connections, or other remote resources.
+
+Manual fallback:
+
+```bash
+npx --yes @paradigma-inc/flywheel@latest uninstall --yes --scope all
+npm uninstall -g @paradigma-inc/flywheel
+rm -rf "$HOME/.config/flywheel-cli" "$HOME/.flywheel"
+```
+
+With `--yes --scope all` and no host selectors, `flywheel uninstall` targets
+every supported host.
+
 ## Setup Modes
 
 ```bash
@@ -156,15 +181,18 @@ npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill \
 
 ## Host Matrix
 
-| Host         | MCP wiring (`--mode mcp`) | CLI-mode bundled skill install (`--mode cli`) |
-| ------------ | ------------------------- | --------------------------------------------- |
-| Claude Code  | yes                       | yes                                           |
-| OpenCode     | yes                       | yes                                           |
-| Codex        | yes                       | yes                                           |
-| Cursor       | yes                       | yes                                           |
-| Pi (pi-mono) | yes                       | yes                                           |
-| OpenClaw     | yes                       | yes                                           |
-| Hermes Agent | yes                       | no (MCP-only host)                            |
+| Host                          | MCP wiring (`--mode mcp`) | CLI-mode bundled skill install (`--mode cli`) |
+| ----------------------------- | ------------------------- | --------------------------------------------- |
+| Claude Code                   | yes                       | yes                                           |
+| Cursor                        | yes                       | yes                                           |
+| Universal (`.agents/skills`)  | no (skill-only)           | yes                                           |
+| Antigravity (`.agent/skills`) | no (skill-only)           | yes                                           |
+| OpenCode                      | yes                       | yes                                           |
+| Codex                         | yes                       | yes                                           |
+| Gemini CLI                    | yes                       | yes                                           |
+| Pi (pi-mono)                  | yes                       | yes                                           |
+| OpenClaw                      | yes                       | yes                                           |
+| Hermes Agent                  | yes                       | no (MCP-only host)                            |
 
 CLI mode handling for Hermes Agent:
 
@@ -172,6 +200,88 @@ CLI mode handling for Hermes Agent:
 - mixed supported + unsupported selection: command continues for supported
   hosts and reports skipped unsupported hosts
 
+### New flags (ctx7 alignment)
+
+These flags align the `flywheel setup` surface with the `npx ctx7 setup`
+convention while keeping every Flywheel-specific flag intact. They are
+additive: existing invocations continue to behave as before.
+
+#### `--oauth`
+
+Writes an MCP config that omits the `Authorization` header and delegates
+authentication to the IDE's MCP 2.0 OAuth discovery flow. No API key is
+minted, stored, or transmitted by `flywheel setup` itself.
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode mcp --claude --oauth --project
+```
+
+The resulting `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "flywheel": {
+      "type": "http",
+      "url": "https://flywheel.paradigma.inc/mcp-server"
+    }
+  }
+}
+```
+
+The IDE must support MCP 2.0 OAuth discovery (Claude Code, Cursor, and
+Gemini CLI currently do). On the first MCP tool call the IDE hits
+`/mcp-server`, follows the `WWW-Authenticate` hint to
+`/.well-known/oauth-protected-resource`, registers itself via
+`/oauth/register`, completes the browser flow, and from then on manages
+its own refresh tokens. No API key ever touches the user's filesystem.
+
+`--api-key` and `--oauth` are mutually exclusive; passing both produces a
+usage error (`exit 2`).
+
+If a previous `flywheel setup` run wrote an MCP entry with an
+`Authorization` header against the same URL, re-running with `--oauth`
+will classify that entry as matching and leave the header in place. To
+rewrite the config to drop the header, first run
+`flywheel uninstall --<host> --project` and then re-run setup with
+`--oauth`.
+
+#### `--gemini`
+
+Registers Flywheel as an MCP server for Gemini CLI at
+`.gemini/settings.json` (project) or `~/.gemini/settings.json` (global).
+Gemini CLI uses the `mcpServers.flywheel.httpUrl` key (not `url`); when
+`--api-key <key>` is supplied, the setup writes a `Bearer <key>`
+`Authorization` header. With `--oauth` the header is omitted.
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode mcp --gemini --project --api-key <token>
+```
+
+#### `--universal`
+
+Skill-only target that writes Flywheel's bundled skills into
+`./.agents/skills/<skill-name>/` (project) or `~/.agents/skills/<skill-name>/`
+(global). Writes no MCP server config and no agent-specific rules. Useful
+for toolchains that read the conventional `.agents/skills/` layout without
+needing a Flywheel MCP binding. Requires `--mode cli` explicitly and is
+never auto-detected; opt-in only.
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode cli --universal --project
+```
+
+#### `--antigravity`
+
+Same skill-only shape as `--universal` but targets
+`./.agent/skills/<skill-name>/` (project) or `~/.agent/skills/<skill-name>/`
+(global) — note the singular `.agent` directory. Writes no MCP server
+config. Requires `--mode cli` explicitly and is never auto-detected.
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode cli --antigravity --project
+```
+
 ## Public Update Flow
 
 After a new release:
@@ -200,7 +310,8 @@ flags.
 
 - `setup`: setup flow with explicit mode routing.
 - `uninstall`: removes Flywheel MCP entries from host configs and removes
-  bundled skills from supported hosts.
+  bundled skills from supported hosts. Use the one-shot uninstaller above for a
+  full local cleanup, including the global npm package and default local state.
 
 ```bash
 npx --yes @paradigma-inc/flywheel uninstall

package/package.json

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

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

@@ -237,6 +237,14 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel artifacts:list`, `flywheel artifacts:get` inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
 - `flywheel nodes:commit-new`, `flywheel nodes:commit` publish the caller's full staged payload for an existing node once terminal and contract-complete; commit on an existing node requires an active stage lease and explicit `--base_committed_revision`.
 
+## Admin only (FLY-359)
+
+These commands require `FLYWHEEL_ADMIN_KEY` in the environment (forwarded as the `X-Admin-Key` header) or an authenticated `@paradigma.inc` session. The server rejects all other callers with 401/403. 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: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`.
+
 ## See Also
 
 - `flywheel-mcp-tool-map.md` — the matching MCP routing reference.

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

@@ -194,3 +194,11 @@ Hook workflow-if contract (first version):
 - `flywheel_delete_artifact`: remove an accidental/obsolete node artifact.
 - `flywheel_list_artifacts`, `flywheel_get_artifact`: inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
 - `flywheel_commit_new_node`, `flywheel_commit_node`: publish the caller's full staged payload for an existing node once terminal and contract-complete; requires an active stage lease and explicit `base_committed_revision`.
+
+### Admin only (FLY-359)
+
+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_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/src/agents.mjs

@@ -5,23 +5,33 @@ import path from "node:path";
 export const SERVER_NAME = "flywheel";
 export const ALL_HOST_NAMES = [
   "claude",
+  "cursor",
+  "universal",
+  "antigravity",
   "opencode",
   "codex",
-  "cursor",
+  "gemini",
   "pi-mono",
   "hermes-agent",
   "openclaw",
 ];
 export const SETUP_HOST_NAMES = {
   claude: "Claude Code",
+  cursor: "Cursor",
+  universal: "Universal (.agents/skills)",
+  antigravity: "Antigravity (.agent/skills)",
   opencode: "OpenCode",
   codex: "Codex",
-  cursor: "Cursor",
+  gemini: "Gemini CLI",
   "pi-mono": "Pi (pi-mono)",
   "hermes-agent": "Hermes Agent",
   openclaw: "OpenClaw",
 };
 
+export function isSkillOnlyHost(host) {
+  return host != null && host.mcp == null;
+}
+
 const HOME = os.homedir();
 
 const hosts = {
@@ -33,13 +43,13 @@ const hosts = {
       projectPaths: [".mcp.json"],
       globalPaths: [path.join(HOME, ".claude.json")],
       configKey: "mcpServers",
-      buildEntry: ({ serverUrl, apiKey }) => ({
-        type: "http",
-        url: serverUrl,
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-        },
-      }),
+      buildEntry: ({ serverUrl, apiKey }) => {
+        const entry = { type: "http", url: serverUrl };
+        if (apiKey) {
+          entry.headers = { Authorization: `Bearer ${apiKey}` };
+        }
+        return entry;
+      },
     },
     detect: {
       projectPaths: [".mcp.json", ".claude"],
@@ -67,14 +77,13 @@ const hosts = {
         path.join(HOME, ".config", "opencode", ".opencode.jsonc"),
       ],
       configKey: "mcp",
-      buildEntry: ({ serverUrl, apiKey }) => ({
-        type: "remote",
-        url: serverUrl,
-        enabled: true,
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-        },
-      }),
+      buildEntry: ({ serverUrl, apiKey }) => {
+        const entry = { type: "remote", url: serverUrl, enabled: true };
+        if (apiKey) {
+          entry.headers = { Authorization: `Bearer ${apiKey}` };
+        }
+        return entry;
+      },
     },
     detect: {
       projectPaths: [
@@ -94,13 +103,13 @@ const hosts = {
       projectPaths: [path.join(".codex", "config.toml")],
       globalPaths: [path.join(HOME, ".codex", "config.toml")],
       configKey: "mcp_servers",
-      buildEntry: ({ serverUrl, apiKey }) => ({
-        type: "http",
-        url: serverUrl,
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-        },
-      }),
+      buildEntry: ({ serverUrl, apiKey }) => {
+        const entry = { type: "http", url: serverUrl };
+        if (apiKey) {
+          entry.headers = { Authorization: `Bearer ${apiKey}` };
+        }
+        return entry;
+      },
     },
     detect: {
       projectPaths: [".codex", path.join(".codex", "config.toml")],
@@ -115,18 +124,43 @@ const hosts = {
       projectPaths: [path.join(".cursor", "mcp.json")],
       globalPaths: [path.join(HOME, ".cursor", "mcp.json")],
       configKey: "mcpServers",
-      buildEntry: ({ serverUrl, apiKey }) => ({
-        url: serverUrl,
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-        },
-      }),
+      buildEntry: ({ serverUrl, apiKey }) => {
+        const entry = { url: serverUrl };
+        if (apiKey) {
+          entry.headers = { Authorization: `Bearer ${apiKey}` };
+        }
+        return entry;
+      },
     },
     detect: {
       projectPaths: [".cursor", path.join(".cursor", "mcp.json")],
       globalPaths: [path.join(HOME, ".cursor")],
     },
   },
+  gemini: {
+    name: "gemini",
+    displayName: "Gemini CLI",
+    mcp: {
+      configType: "json",
+      projectPaths: [path.join(".gemini", "settings.json")],
+      globalPaths: [path.join(HOME, ".gemini", "settings.json")],
+      configKey: "mcpServers",
+      buildEntry: ({ serverUrl, apiKey }) => {
+        const entry = { httpUrl: serverUrl };
+        if (apiKey) {
+          entry.headers = { Authorization: `Bearer ${apiKey}` };
+        }
+        return entry;
+      },
+    },
+    detect: {
+      projectPaths: [".gemini", path.join(".gemini", "settings.json")],
+      globalPaths: [
+        path.join(HOME, ".gemini"),
+        path.join(HOME, ".gemini", "settings.json"),
+      ],
+    },
+  },
   "pi-mono": {
     name: "pi-mono",
     displayName: "Pi (pi-mono)",
@@ -135,12 +169,13 @@ const hosts = {
       projectPaths: [path.join(".pi", "settings.json")],
       globalPaths: [path.join(HOME, ".pi", "agent", "settings.json")],
       configKey: ["mcp", "servers"],
-      buildEntry: ({ serverUrl, apiKey }) => ({
-        url: serverUrl,
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-        },
-      }),
+      buildEntry: ({ serverUrl, apiKey }) => {
+        const entry = { url: serverUrl };
+        if (apiKey) {
+          entry.headers = { Authorization: `Bearer ${apiKey}` };
+        }
+        return entry;
+      },
     },
     detect: {
       projectPaths: [".pi", path.join(".pi", "settings.json")],
@@ -155,18 +190,31 @@ const hosts = {
       projectPaths: [path.join(".hermes", "config.yaml")],
       globalPaths: [path.join(HOME, ".hermes", "config.yaml")],
       configKey: "mcp_servers",
-      buildEntry: ({ serverUrl, apiKey }) => ({
-        url: serverUrl,
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-        },
-      }),
+      buildEntry: ({ serverUrl, apiKey }) => {
+        const entry = { url: serverUrl };
+        if (apiKey) {
+          entry.headers = { Authorization: `Bearer ${apiKey}` };
+        }
+        return entry;
+      },
     },
     detect: {
       projectPaths: [".hermes", path.join(".hermes", "config.yaml")],
       globalPaths: [path.join(HOME, ".hermes"), path.join(HOME, ".hermes", "config.yaml")],
     },
   },
+  universal: {
+    name: "universal",
+    displayName: "Universal (.agents/skills)",
+    mcp: null,
+    detect: { projectPaths: [], globalPaths: [] },
+  },
+  antigravity: {
+    name: "antigravity",
+    displayName: "Antigravity (.agent/skills)",
+    mcp: null,
+    detect: { projectPaths: [], globalPaths: [] },
+  },
   openclaw: {
     name: "openclaw",
     displayName: "OpenClaw",
@@ -175,12 +223,13 @@ const hosts = {
       projectPaths: [path.join(".openclaw", "openclaw.json")],
       globalPaths: [path.join(HOME, ".openclaw", "openclaw.json")],
       configKey: ["mcp", "servers"],
-      buildEntry: ({ serverUrl, apiKey }) => ({
-        url: serverUrl,
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-        },
-      }),
+      buildEntry: ({ serverUrl, apiKey }) => {
+        const entry = { url: serverUrl };
+        if (apiKey) {
+          entry.headers = { Authorization: `Bearer ${apiKey}` };
+        }
+        return entry;
+      },
     },
     detect: {
       projectPaths: [".openclaw", path.join(".openclaw", "openclaw.json")],
@@ -200,6 +249,23 @@ export function getHost(name) {
   return host;
 }
 
+/**
+ * Names of hosts whose only role is installing skill directories — they have
+ * no MCP configuration surface and therefore no "mode" to conflict with.
+ *
+ * Code that reasons about cross-mode conflicts, ownership of shared skill
+ * paths, or skill-only retain/rollback rules must iterate THIS list rather
+ * than the wider set of hosts that happen to use the direct-copy skill
+ * install path. Specifically, Gemini CLI is MCP-capable (full `mcp` block,
+ * `httpUrl`-keyed config under `.gemini/settings.json`) but also uses the
+ * direct-copy skill path; treating it as skill-only would silently let a
+ * CLI-to-MCP transition proceed without the canonical `--force`
+ * reconciliation and leave both wirings active.
+ */
+export const SKILL_ONLY_HOST_NAMES = Object.freeze(
+  ALL_HOST_NAMES.filter((name) => isSkillOnlyHost(hosts[name])),
+);
+
 async function pathExists(filePath) {
   try {
     await access(filePath);