@ory/gemini-cli 0.3.0 → 0.5.0

package/README.md

@@ -7,7 +7,7 @@ You don't need an Ory account or any prior Ory experience to start.
 ## Prerequisites
 
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and signed in
-- Node.js **≥ 24**
+- Node.js **≥ 24** (matches the Ory plugin toolchain — `nvm use 24` or `volta install node@24`)
 - [Docker](https://docs.docker.com/get-docker/) (only needed for the local Ory stack)
 - macOS or Linux. Windows works via WSL2.
 
@@ -16,7 +16,7 @@ You don't need an Ory account or any prior Ory experience to start.
 In your shell:
 
 ```bash
-gemini extensions install ory-agent-extension
+gemini extensions install https://github.com/ory/gemini-cli-extension
 ```
 
 That's it — skills, TOML slash commands, hooks, and the Ory MCP server are now registered.
@@ -24,20 +24,14 @@ That's it — skills, TOML slash commands, hooks, and the Ory MCP server are now
 <details>
 <summary>Alternative install paths</summary>
 
-If the public extension registry isn't available, either of these registers the same extension:
-
-```bash
-# Ory-hosted extension source
-gemini extensions install https://github.com/ory/gemini-cli-extension
-```
-
 ```bash
-# Direct installer, no prior npm install required
-npx @ory/gemini-cli install
-npx @ory/gemini-cli uninstall
+# Direct installer; renders a fresh extension manifest and invokes
+# `gemini extensions install` for you. No prior npm install required.
+npx -y @ory/gemini-cli install
+npx -y @ory/gemini-cli uninstall
 ```
 
-If the `gemini` binary isn't on your `PATH`, `npx -y -p @ory/gemini-cli ory-gemini-setup` writes the extension config directly.
+If the `gemini` binary isn't on your `PATH`, `npx -y -p @ory/gemini-cli ory-gemini-setup` writes the extension config directly into your project's `.gemini/settings.json`.
 
 </details>
 
@@ -59,18 +53,27 @@ From any project where you'd like Ory authentication, inside Gemini CLI:
 
 3. **Sign in.** Start your app, visit the login page Gemini added, and sign in with the seeded credentials. You now have a real Ory session backed by a real Ory stack — locally, offline, with zero configuration.
 
+4. **Turn on Ory login for the Gemini session itself.** *(Optional but recommended.)* Out of the box the extension only governs your *app*. To also attach an Ory identity to *Gemini's* session — so every tool call is attributed to you, not a fallback `session:<id>` subject — set:
+
+   ```bash
+   export ORY_AUTH_GATE=1
+   ```
+
+   Then restart Gemini CLI. On next session start, Gemini opens an Ory login in your browser; sign in with the same seeded credentials from step 1. This is what makes `permissions enforce` (see [Agent security](#agent-security)) deny on the right identity later.
+
 That's the full Ory DX path. Stop here if you're just evaluating the extension. Continue to [Agent security](#agent-security) when you're ready to enforce.
 
 ## What's included
 
 ### Skills for scaffolding Ory into your application
 
-The extension bundles four skills that Gemini auto-invokes by description. Ask Gemini in natural language or invoke a skill directly:
+The extension bundles five skills that Gemini auto-invokes by description. Ask Gemini in natural language or invoke a skill directly:
 
 - **`ory-auth-setup`** — full project setup. Install the Ory CLI, create an Ory Network project (or use the local one), add Ory Elements, configure the SDK, build the auth pages, wire session middleware.
 - **`ory-login-flow`** — login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
 - **`ory-social-login`** — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
 - **`ory-local-dev`** — drive the local Ory stack from within Gemini to prototype and test without a remote project.
+- **`ory-permissions-onboarding`** — bootstrap permission tuples for built-in tools, switch between observe and enforce mode, troubleshoot denials.
 
 ### Ory MCP server
 

package/dist/cli/assets.d.ts

@@ -1,14 +1,17 @@
 /**
- * Materialize / clean the Ory skill catalog and slash commands for the
- * Gemini CLI plugin. Used both by the primary install path (which seeds
- * the bundled extension dir before `gemini extensions install`) and by
- * the manual-setup fallback (which writes into the project's `.gemini/`
- * tree).
+ * Materialize / clean the Ory skill catalog, slash commands, hook
+ * registration, and extension manifest for the Gemini CLI plugin.
+ *
+ * The manifest and hooks.json are rendered at install time (not shipped
+ * static) so the version pin baked into the hook command always matches
+ * the installed package, and the mcpServers entry stays in sync with the
+ * @ory/mcp-server package we depend on.
  */
 /**
- * Write all Ory skills (4 guide skills) and TOML slash commands (local-up,
- * local-down) under a Gemini-conventional root containing `skills/` and
- * `commands/`. For the bundled extension that's the `gemini-extension`
+ * Write all Ory skills, TOML slash commands, the rendered manifest, and
+ * the rendered hooks.json under a Gemini-conventional root containing
+ * `skills/`, `commands/`, `hooks/`, `gemini-extension.json`, and
+ * `GEMINI.md`. For the bundled extension that's the `gemini-extension`
  * directory; for the manual-setup fallback it's `<projectDir>/.gemini`.
  */
 export declare function installGeminiOryAssets(root: string): void;

package/dist/cli/assets.js

@@ -1,10 +1,12 @@
 "use strict";
 /**
- * Materialize / clean the Ory skill catalog and slash commands for the
- * Gemini CLI plugin. Used both by the primary install path (which seeds
- * the bundled extension dir before `gemini extensions install`) and by
- * the manual-setup fallback (which writes into the project's `.gemini/`
- * tree).
+ * Materialize / clean the Ory skill catalog, slash commands, hook
+ * registration, and extension manifest for the Gemini CLI plugin.
+ *
+ * The manifest and hooks.json are rendered at install time (not shipped
+ * static) so the version pin baked into the hook command always matches
+ * the installed package, and the mcpServers entry stays in sync with the
+ * @ory/mcp-server package we depend on.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -45,9 +47,13 @@ exports.uninstallGeminiOryAssets = uninstallGeminiOryAssets;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const argus_1 = require("@ory/argus");
+const PACKAGE_NAME = "@ory/gemini-cli";
+const MCP_PACKAGE_NAME = "@ory/mcp-server";
+const MCP_BIN_NAME = "ory-mcp-server";
+const EXTENSION_NAME = "ory";
 const RENDER_OPTS = {
     binName: "ory-gemini",
-    packageName: "@ory/gemini-cli",
+    packageName: PACKAGE_NAME,
 };
 /**
  * Subdir under `commands/` for our TOML files. The folder name becomes the
@@ -56,12 +62,92 @@ const RENDER_OPTS = {
  */
 const CMD_SUBDIR = "ory";
 /**
- * Write all Ory skills (4 guide skills) and TOML slash commands (local-up,
- * local-down) under a Gemini-conventional root containing `skills/` and
- * `commands/`. For the bundled extension that's the `gemini-extension`
+ * Read the plugin's own version from its package.json, walking up from
+ * dist/cli to the package root. Used to version-pin the npx invocation
+ * shipped in hooks.json so installs keep running against the version
+ * they were registered with.
+ */
+function readPackageVersion() {
+    const pkgPath = path.resolve(__dirname, "..", "..", "package.json");
+    const raw = fs.readFileSync(pkgPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed.version) {
+        throw new Error(`Could not read version from ${pkgPath}`);
+    }
+    return parsed.version;
+}
+/**
+ * Render the hooks.json that Gemini CLI registers when it copies the
+ * extension into ~/.gemini/extensions/ory. The hook command is a
+ * self-contained `npx -y -p @ory/gemini-cli@<version> ory-gemini-hook`
+ * so the binary doesn't have to be on PATH after install.
+ */
+function renderHooks(version) {
+    const command = `npx -y -p ${PACKAGE_NAME}@${version} ory-gemini-hook`;
+    const entry = (name, description, timeout) => [
+        {
+            matcher: "",
+            hooks: [{ name, type: "command", command, timeout, description }],
+        },
+    ];
+    return {
+        hooks: {
+            SessionStart: entry("ory-session-start", "Verify the user and agent identities via Ory", 10000),
+            SessionEnd: entry("ory-session-end", "Record session termination via Ory tracing", 5000),
+            BeforeTool: entry("ory-before-tool", "Check tool permissions via Ory Permissions", 5000),
+            AfterTool: entry("ory-after-tool", "Record trace spans for tool executions via Ory", 5000),
+            BeforeToolSelection: entry("ory-before-tool-selection", "Audit-only span for the upcoming tool-selection decision", 5000),
+            Notification: entry("ory-notification", "Audit permission and notification prompts", 5000),
+            PreCompress: entry("ory-pre-compress", "Audit history compaction events", 5000),
+        },
+    };
+}
+/**
+ * Render gemini-extension.json. Ships:
+ *
+ *  - `name` / `version` so Gemini's `extensions list` shows the right
+ *    package and tracks updates.
+ *  - `contextFileName: GEMINI.md` for the model-facing context briefing.
+ *  - `mcpServers.ory` so the Ory MCP server is auto-registered alongside
+ *    the hooks. Resolved via npx for the same reason as the hook command:
+ *    the binary needn't be on PATH.
+ *  - A minimal `settings` block. Only `ORY_PROJECT_URL` is prompted now —
+ *    the agent identity is resolved via Dynamic Client Registration, and
+ *    the legacy ORY_API_KEY / ORY_SESSION_TOKEN prompts were teaching
+ *    users the deprecated path.
+ */
+function renderManifest(version) {
+    return {
+        name: EXTENSION_NAME,
+        version,
+        description: "Ory authentication, authorization, and distributed tracing for Gemini CLI",
+        contextFileName: "GEMINI.md",
+        mcpServers: {
+            [EXTENSION_NAME]: {
+                command: "npx",
+                args: ["-y", "-p", `${MCP_PACKAGE_NAME}@${version}`, MCP_BIN_NAME],
+            },
+        },
+        settings: [
+            {
+                name: "Ory Project URL",
+                description: "Your Ory project URL (e.g. https://your-project.projects.oryapis.com). Leave unset to run in pass-through mode against a local stack.",
+                envVar: "ORY_PROJECT_URL",
+                sensitive: false,
+            },
+        ],
+    };
+}
+/**
+ * Write all Ory skills, TOML slash commands, the rendered manifest, and
+ * the rendered hooks.json under a Gemini-conventional root containing
+ * `skills/`, `commands/`, `hooks/`, `gemini-extension.json`, and
+ * `GEMINI.md`. For the bundled extension that's the `gemini-extension`
  * directory; for the manual-setup fallback it's `<projectDir>/.gemini`.
  */
 function installGeminiOryAssets(root) {
+    const version = readPackageVersion();
+    fs.mkdirSync(root, { recursive: true });
     const skillsDir = path.join(root, "skills");
     fs.rmSync(skillsDir, { recursive: true, force: true });
     (0, argus_1.writeSkillTree)(skillsDir, (0, argus_1.renderOrySkills)("gemini-cli", RENDER_OPTS));
@@ -71,6 +157,10 @@ function installGeminiOryAssets(root) {
     for (const cmd of (0, argus_1.renderOryCommands)("gemini-cli", RENDER_OPTS)) {
         fs.writeFileSync(path.join(cmdDir, `${cmd.slug}.toml`), (0, argus_1.commandToToml)(cmd));
     }
+    const hooksDir = path.join(root, "hooks");
+    fs.mkdirSync(hooksDir, { recursive: true });
+    fs.writeFileSync(path.join(hooksDir, "hooks.json"), JSON.stringify(renderHooks(version), null, 2) + "\n");
+    fs.writeFileSync(path.join(root, "gemini-extension.json"), JSON.stringify(renderManifest(version), null, 2) + "\n");
 }
 function safeRmEmpty(dir) {
     try {

package/dist/cli/main.js

@@ -83,7 +83,10 @@ function main() {
             require("./setup.js");
             break;
         case "status":
-            status();
+            status().then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
             break;
         case "local":
             (0, argus_1.runLocalCommand)("ory-gemini", args).catch((err) => {
@@ -120,6 +123,7 @@ function install(args) {
             if (result.status === 0) {
                 console.log("");
                 console.log("Ory extension linked for development.");
+                printQuickstart();
                 (0, argus_1.printEnvHelp)("ory-gemini");
             }
             else {
@@ -133,6 +137,7 @@ function install(args) {
             if (result.status === 0) {
                 console.log("");
                 console.log("Ory extension installed.");
+                printQuickstart();
                 (0, argus_1.printEnvHelp)("ory-gemini");
             }
             else {
@@ -171,22 +176,31 @@ async function postInstallPermissions(binName, harness) {
         bootstrappedAutomatically: bootstrapped,
     });
 }
-function status() {
-    console.log("Ory Agent Plugin Status (Gemini CLI)");
-    console.log("====================================");
-    console.log("");
-    (0, argus_1.printOryConfig)();
-    (0, argus_1.printEnvironment)();
-    // Extension-specific status
+/**
+ * Print a three-line quickstart so a fresh user sees the happy path
+ * before the more detailed credentials and permissions banners scroll
+ * by. Mirrors the "Quickstart" section in the README.
+ */
+function printQuickstart() {
     console.log("");
-    console.log("Extension:");
-    console.log(`  Directory: ${EXTENSION_DIR}`);
-    console.log(`  Manifest:  ${fs.existsSync(path.join(EXTENSION_DIR, "gemini-extension.json")) ? "found" : "MISSING"}`);
-    console.log(`  Hook script: ${fs.existsSync(path.join(PACKAGE_ROOT, "dist", "hook.js")) ? "built" : "NOT BUILT (run pnpm build)"}`);
-    const home = process.env.HOME ?? process.env.USERPROFILE ?? "~";
-    const extensionInstalled = fs.existsSync(path.join(home, ".gemini", "extensions", "ory"));
-    console.log(`  Installed:   ${extensionInstalled ? "yes (~/.gemini/extensions/ory)" : "no"}`);
-    (0, argus_1.printLogTail)();
+    console.log("Quickstart:");
+    console.log("  1. Inside Gemini, run /ory:local-up to start a local Ory stack.");
+    console.log("  2. Ask Gemini \"add Ory auth to this app\" to scaffold login/signup.");
+    console.log("  3. Set ORY_AUTH_GATE=1 when you're ready for the PKCE login gate.");
+}
+async function status() {
+    await (0, argus_1.runStatusCommand)("ory-gemini", "gemini-cli", {
+        title: "Gemini CLI",
+        printPluginSection: () => {
+            console.log("Hooks & plugin:");
+            console.log(`  Directory:   ${EXTENSION_DIR}`);
+            console.log(`  Manifest:    ${fs.existsSync(path.join(EXTENSION_DIR, "gemini-extension.json")) ? "found" : "MISSING"}`);
+            console.log(`  Hook script: ${fs.existsSync(path.join(PACKAGE_ROOT, "dist", "hook.js")) ? "built" : "NOT BUILT (run pnpm build)"}`);
+            const home = process.env.HOME ?? process.env.USERPROFILE ?? "~";
+            const extensionInstalled = fs.existsSync(path.join(home, ".gemini", "extensions", "ory"));
+            console.log(`  Installed:   ${extensionInstalled ? "yes (~/.gemini/extensions/ory)" : "no"}`);
+        },
+    });
 }
 function help() {
     console.log(`

package/gemini-extension/GEMINI.md

@@ -1,5 +1,48 @@
-This project has the Ory agent plugin installed. Tool invocations are checked against Ory Permissions (Zanzibar-style) and traced automatically.
+# Ory for Gemini CLI
 
-If a tool call is blocked, the reason will indicate which permission is missing. The user may need to update their Ory Permissions configuration to grant access.
+This Gemini CLI session has the Ory extension installed. It ships skills for
+scaffolding Ory into the user's project, slash commands for driving a local
+Ory stack, and lifecycle hooks that authenticate, authorize, and audit every
+tool call.
 
-To check configuration status, the user can run: `npx ory-gemini status`
+## When to invoke the skills
+
+- **`ory-auth-setup`** — full project setup: install the Ory CLI, create or
+  reuse a project, add Ory Elements, configure the SDK, build the login /
+  registration / recovery / verification / settings pages, wire session
+  middleware. Use this when the user says "add Ory auth to this app."
+- **`ory-login-flow`** — just the auth pages with Ory Elements (Next.js App
+  Router or React SPA). Use when auth is already partially set up.
+- **`ory-social-login`** — Google, GitHub, Apple, Microsoft, Discord, and
+  other OIDC providers with Jsonnet data mappers.
+- **`ory-local-dev`** — drive the local Ory stack from within the session to
+  prototype and test without a remote project.
+- **`ory-permissions-onboarding`** — bootstrap permission tuples for the
+  built-in tools, switch between observe and enforce mode, troubleshoot
+  denials.
+
+## Slash commands
+
+- `/ory:local-up` — start a local Ory instance in Docker (Identities, OAuth2,
+  Permissions, plus a login UI on `:3000` and Jaeger on `:16686`, reachable
+  through `http://localhost:4000`). Prints seeded test-user credentials.
+- `/ory:local-down` — tear it all down.
+
+## Permission mode
+
+After install the extension runs in **observe** mode by default: permission
+denies are recorded as audit spans but tools still execute. Tell the user to
+run `npx -y -p @ory/gemini-cli ory-gemini permissions enforce` once their
+permission set is correct.
+
+If a tool call *is* blocked, the denial reason names the missing relation.
+Suggest `npx -y -p @ory/gemini-cli ory-gemini permissions bootstrap` (grants
+`use` on every built-in tool to the current user) or ask the Ory MCP server
+to write a specific relation tuple.
+
+## Diagnostics
+
+- `npx -y -p @ory/gemini-cli ory-gemini status` — show configuration and
+  installation state.
+- Set `ORY_AGENT_DEBUG=true` and `ORY_AGENT_LOG_FILE=~/.config/ory-agent-plugins/ory.log`
+  to capture structured logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/gemini-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Ory extension for Gemini CLI: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",
@@ -57,7 +57,6 @@
     }
   },
   "bin": {
-    "gemini-cli": "dist/cli/main.js",
     "ory-gemini": "dist/cli/main.js",
     "ory-gemini-hook": "dist/hook.js",
     "ory-gemini-setup": "dist/cli/setup.js"
@@ -69,10 +68,10 @@
     "gemini-extension"
   ],
   "dependencies": {
-    "@ory/argus": "0.3.0"
+    "@ory/argus": "0.5.0"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsc",

package/gemini-extension/gemini-extension.json

@@ -1,26 +0,0 @@
-{
-  "name": "ory",
-  "version": "0.1.0",
-  "description": "Ory authentication, authorization, and distributed tracing for Gemini CLI",
-  "contextFileName": "GEMINI.md",
-  "settings": [
-    {
-      "name": "Ory Project URL",
-      "description": "Your Ory project URL (e.g. https://your-project.projects.oryapis.com)",
-      "envVar": "ORY_PROJECT_URL",
-      "sensitive": false
-    },
-    {
-      "name": "Ory API Key",
-      "description": "Your Ory API key (starts with ory_pat_)",
-      "envVar": "ORY_API_KEY",
-      "sensitive": true
-    },
-    {
-      "name": "Session Token",
-      "description": "Session token for agent authentication",
-      "envVar": "ORY_SESSION_TOKEN",
-      "sensitive": true
-    }
-  ]
-}

package/gemini-extension/hooks/hooks.json

@@ -1,102 +0,0 @@
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "name": "ory-session-start",
-            "type": "command",
-            "command": "ory-gemini-hook",
-            "timeout": 10000,
-            "description": "Verify agent session via Ory Identities"
-          }
-        ]
-      }
-    ],
-    "SessionEnd": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "name": "ory-session-end",
-            "type": "command",
-            "command": "ory-gemini-hook",
-            "timeout": 5000,
-            "description": "Record session termination via Ory tracing"
-          }
-        ]
-      }
-    ],
-    "BeforeTool": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "name": "ory-before-tool",
-            "type": "command",
-            "command": "ory-gemini-hook",
-            "timeout": 5000,
-            "description": "Check tool permissions via Ory Permissions"
-          }
-        ]
-      }
-    ],
-    "AfterTool": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "name": "ory-after-tool",
-            "type": "command",
-            "command": "ory-gemini-hook",
-            "timeout": 5000,
-            "description": "Record trace spans for tool executions via Ory"
-          }
-        ]
-      }
-    ],
-    "BeforeToolSelection": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "name": "ory-before-tool-selection",
-            "type": "command",
-            "command": "ory-gemini-hook",
-            "timeout": 5000,
-            "description": "Audit-only span for the upcoming tool-selection decision"
-          }
-        ]
-      }
-    ],
-    "Notification": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "name": "ory-notification",
-            "type": "command",
-            "command": "ory-gemini-hook",
-            "timeout": 5000,
-            "description": "Audit permission and notification prompts"
-          }
-        ]
-      }
-    ],
-    "PreCompress": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "name": "ory-pre-compress",
-            "type": "command",
-            "command": "ory-gemini-hook",
-            "timeout": 5000,
-            "description": "Audit history compaction events"
-          }
-        ]
-      }
-    ]
-  }
-}