opencode-gemiterm-skills 0.5.0 → 0.6.0

package/AGENTS.md

@@ -1,10 +1,11 @@
 # AGENTS.md - opencode-gemiterm-skills
 
 <critical_rules priority="highest">
-1. The bundled `debate-with-gemini` skill depends on the `gemiterm` Python CLI being installed and authenticated on the host.
+1. The bundled `debate-with-gemini` skill depends on the `gemiterm` Bun-native CLI being installed (or available via `bunx gemiterm`) and authenticated on the host.
 2. This package ships a real installer (`src/installer.ts`) that copies skill assets to the consumer's `.opencode/skills/` and registers them in `opencode.json`. The `src/cli.ts` is the CLI entry point (install/uninstall/status subcommands), resolved by `package.json#bin`. Only add code under `src/` that supports the install/uninstall/status commands.
-3. Skill frontmatter is the source of truth. Do not edit `assets/skills/*/SKILL.md` frontmatter in ways that break the `name` / `description` contract.
-4. The `metadata.requires: gemiterm` link on `debate-with-gemini` must remain so consumers know to install the Python CLI first.
+3. Skill frontmatter is the source of truth. Do not edit `skills/*/SKILL.md` frontmatter in ways that break the `name` / `description` contract.
+4. The `metadata.requires: gemiterm` link on `debate-with-gemini` must remain so consumers know to install the CLI first.
+5. GemiTerm is a Bun-native CLI — all skill documents assume Bun as the runtime. Do not reference Python, `pipx`, or `pip` install paths.
 </critical_rules>
 
 <context_hierarchy>
@@ -21,13 +22,13 @@
 </role>
 
 <bundled_skills>
-<skill name="gemiterm" path="assets/skills/gemiterm/SKILL.md" requires="Python CLI gemiterm" />
-<skill name="debate-with-gemini" path="assets/skills/debate-with-gemini/SKILL.md" requires="gemiterm skill + Python CLI gemiterm" />
+<skill name="gemiterm" path="skills/gemiterm/SKILL.md" requires="Bun-native CLI gemiterm" />
+<skill name="debate-with-gemini" path="skills/debate-with-gemini/SKILL.md" requires="gemiterm skill + Bun-native CLI gemiterm" />
 </bundled_skills>
 
 <self_config>
 <location>.opencode/opencode.json</location>
-<purpose>Register assets/skills/ as a skill path and pre-allow both skills</purpose>
+<purpose>Register skills/ as a skill path and pre-allow both skills</purpose>
 <pointer_in_package_json>opencode.plugin → .opencode/opencode.json</pointer_in_package_json>
 </self_config>
 
@@ -53,7 +54,7 @@
 <use_case>Local development against a checkout of this repo</use_case>
 </file_fallback>
 <prerequisites>
-  - pip install gemiterm
+  - bun install gemiterm -g
   - gemiterm install-browser
   - gemiterm auth
 </prerequisites>

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `opencode-gemiterm-skills` will be documented in this fil
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-06-10
+
+### Changed
+- **GemiTerm is now a Bun-native CLI** — the underlying `gemiterm` CLI has been rewritten to run on Bun instead of Python. All skill documents updated to reflect the new runtime: skills first check for a global `gemiterm` install, fall back to `bunx gemiterm` for transparent npx-style invocation, and if Bun itself is missing emit platform-aware install instructions (`curl -fsSL https://bun.sh/install | bash` on macOS/Linux, `powershell -c "irm bun.sh/install.ps1 | iex"` on Windows) before erroring out.
+- Added `metadata.runtime: bun` to both skill frontmatter entries.
+- Updated `debate-with-gemini` REFERENCE.md subagent template to mention `bunx gemiterm` fallback for every command and added `bunx gemiterm *` to the permissions block.
+- **Rewrote both skill documents** — `gemiterm` and `debate-with-gemini` SKILL.md and REFERENCE.md now contain richer, more structured content: the `debate-with-gemini` skill includes tactical patterns (Concede-and-Counter, Force Concrete Example, Decision Matrix, Reframe the Question, Line-in-the-Sand), explicit stopping criteria, and a structured debate-report format; the `gemiterm` skill has an expanded command reference with detailed flags and common automation patterns.
+- **Directory restructure** — moved `assets/skills/{gemiterm,debate-with-gemini}` → `skills/{gemiterm,debate-with-gemini}` so both skills sit at the standard `skills/<name>/SKILL.md` path recognized by Vercel's `skills` CLI (and the broader skills ecosystem).
+- `.claude-plugin/plugin.json` and `.opencode/opencode.json` updated to reference the new `./skills` path; `package.json#files` now whitelists `skills` instead of `assets`.
+- `src/installer.ts` and `tests/skills.test.ts` source-path constants updated accordingly.
+- Docs (`AGENTS.md`, `CONTRIBUTING.md`) updated to reflect the new layout.
+
+### Removed
+- `assets/` directory (no longer needed; skills moved to repo root).
+- All references to `pipx install gemiterm` and Python-based install paths.
+
+## [0.5.1] - 2026-06-07
+
+### Added
+- `CONTRIBUTING.md` — developer-facing docs with architecture, file layout, coding rules, and troubleshooting (extracted from README)
+
+### Changed
+- **README rewrite** — refocused for end-users and SEO: HTML meta comment with keywords, centered hero header, streamlined examples with emoji headers, "Why this plugin?" value-proposition section, call-to-action footer
+- README generalized to be agent-agnostic: describes "any AI agent" instead of only OpenCode-specific framing; shows both `bunx` and `npx` install commands; "CLI install (any agent)" as the primary install method
+- `debate-with-gemini` skill frontmatter: removed `metadata.requires` field; added `compatibility` and `license` fields
+- `gemiterm` skill frontmatter: added `compatibility` and `license` fields
+
+### Removed
+- Test for `metadata.requires: gemiterm` on `debate-with-gemini` (field no longer exists)
+
 ## [0.5.0] - 2026-06-07
 
 _Initial public release._

package/README.md

@@ -1,217 +1,144 @@
+<!-- 
+  SEO description: AI agent skills for Google Gemini — list, search, export Gemini chats and run 
+  structured debates with Gemini. Works with OpenCode, Claude Code, and any skill-compatible AI agent.
+  Keywords: Gemini CLI, gemiterm, AI agent skills, Google Gemini terminal, Gemini chat export, 
+  AI debate, multi-turn debate, terminal AI, agent skills, Gemini terminal
+-->
+
+<div align="center">
+
 # opencode-gemiterm-skills
 
+**Gemini terminal skills for AI agents — chat export, search & AI-powered debates**
+
 [![OpenCode Plugin](https://img.shields.io/badge/OpenCode-Plugin-blue?link=https://opencode.ai)](https://opencode.ai)
 [![npm version](https://img.shields.io/npm/v/opencode-gemiterm-skills?label=npm)](https://www.npmjs.com/package/opencode-gemiterm-skills)
 [![MIT License](https://img.shields.io/badge/License-MIT-green?link=LICENSE)](LICENSE)
 
-Local OpenCode plugin package that bundles the `gemiterm` and `debate-with-gemini` skills for OpenCode agents. Install once and the skills are available to every OpenCode session on the machine.
+[Quick Start](#quick-start) · [Skills](#bundled-skills) · [Examples](#examples) · [Requirements](#requirements) · [Contributing](CONTRIBUTING.md)
+
+</div>
 
-[`gemiterm`](https://github.com/Expert-Vision-Software/gemiterm) is a CLI for interacting with Google Gemini from the terminal — listing, fetching, exporting, and managing Gemini chat history. This plugin wraps it into OpenCode skills so agents can use Gemini conversational data directly in workflows.
+---
+
+Bring the power of [Google Gemini](https://gemini.google.com) directly into your AI agent sessions. This package bundles two skills — **gemiterm** and **debate-with-gemini** — so any compatible agent can search your Gemini chats, export conversation history, and run structured multi-turn debates with Gemini to validate ideas before you commit to code.
+
+Works with [OpenCode](https://opencode.ai), and any agent that supports the `skill` tool or can invoke CLI-installed skills via `bunx`/`npx`.
 
 ## Bundled skills
 
-| Skill | Purpose |
-|-------|---------|
-| `gemiterm` | Google Gemini Terminal CLI wrapper for listing, fetching, exporting, and managing Gemini chat history. |
-| `debate-with-gemini` | Conducts structured multi-turn technical debates with Gemini AI via the `gemiterm` CLI, delegating the back-and-forth to a subagent. |
+| Skill | What it does |
+|-------|-------------|
+| **gemiterm** | Search, list, export, and manage your Google Gemini chat history from the terminal. |
+| **debate-with-gemini** | Run structured multi-turn technical debates with Gemini AI — perfect for validating architecture decisions, trade-offs, and design choices. |
 
-Both skills are loaded on demand via the native `skill` tool. The metadata of each skill (name + description) is pre-loaded at session start; the full `SKILL.md` body is loaded only when the agent decides the skill is relevant.
+Both skills are loaded on demand. Metadata (name + description) is pre-loaded at session start; the full skill body loads only when the agent decides it's relevant — zero overhead when not in use.
 
 ## Quick start
 
 ```bash
-# Install skills and register them with OpenCode
-bunx opencode-gemiterm-skills install
+# Install skills via bunx
+bunx opencode-gemiterm-skills install [--scope global]
 
-# Or globally (for all projects on this machine)
-bunx opencode-gemiterm-skills install --scope global
-```
+# Or with npx
+npx opencode-gemiterm-skills install [--scope global]
 
-That's it. After install, both `gemiterm` and `debate-with-gemini` appear in the `skill` tool's `<available_skills>` list. No restart needed — OpenCode loads skills on demand.
+# Or skills.sh
+npx skills add expert-vision-software/opencode-gemiterm-skills --skill [gemiterm/debate-with-gemini]
+```
 
-For global install, skills are placed in `~/.config/opencode/skills/`. For local install (default), they are placed in `{project}/.opencode/skills/`.
+That's it — skills are available immediately.
 
-## Example use cases
+## Examples
 
-### List and search Gemini chats (`gemiterm` skill)
+### 🔍 Search and export Gemini chats
 
 > **You:** "Find my Gemini chats about React Server Components and export them."
 
-Agent loads the `gemiterm` skill, then:
+Agent loads the `gemiterm` skill, searches your Gemini history, and exports matches:
 
-```bash
-gemiterm list --all-profiles --format json
-# → filters chats by title/keyword "React Server Components"
-gemiterm export <chat_id> --output ./exports/rsc-chat.md
+```
+Found 3 matching chats. Exported all to ./exports/ — here's a summary of each…
 ```
 
-**Agent:** "Found 3 matching chats. Exported all to `./exports/` — here's a summary of each…"
-
----
-
-### Bulk export for analysis (`gemiterm` skill)
+### 📦 Bulk export for offline analysis
 
 > **You:** "Export all my recent Gemini chats so I can grep through them."
 
-Agent loads the `gemiterm` skill, then:
+Agent lists and exports chats in parallel:
 
-```bash
-gemiterm list --limit 20 --sort recent --format json
-gemiterm export-all --output ./gemini-exports --format md --parallel 4
+```
+Exported 18 chats to ./gemini-exports/ in Markdown. Search with: grep -r "topic" ./gemini-exports/
 ```
 
-**Agent:** "Exported 18 chats to `./gemini-exports/` in Markdown. You can search them with `grep -r "topic" ./gemini-exports/`."
-
----
-
-### Structured debate with Gemini (`debate-with-gemini` skill)
+### 🗣️ Structured debate with Gemini
 
 > **You:** "Debate Gemini for/against using SQLite as the primary database for a SaaS app. Context: docs/arch.md. 5 turns."
 
-Agent loads both skills, verifies auth, reads context, seeds a new Gemini chat with the opposing stance, and spawns a subagent that runs 5 rounds of back-and-forth autonomously.
-
-**Agent:** "Debate complete (5 turns). Gemini argued **for** SQLite (simplicity, zero-config, adequate for early-stage). I argued **against** (concurrency limits, no network access, scaling ceiling). Key agreements: fine for prototyping, migrate to Postgres before 100+ concurrent users. Full transcript saved via `gemiterm export`."
+Agent reads your context, seeds a new Gemini chat with the opposing stance, and runs 5 rounds of autonomous back-and-forth:
 
----
+```
+Debate complete (5 turns). Gemini argued FOR SQLite (simplicity, zero-config).
+I argued AGAINST (concurrency limits, no network access, scaling ceiling).
+Key agreements: fine for prototyping, migrate to Postgres before 100+ concurrent users.
+```
 
-### Continue a previous debate (`debate-with-gemini` skill)
+### 🔄 Continue a previous debate
 
 > **You:** "Continue that SQLite debate for 3 more turns. Here's the chat_id: c_abc123."
 
-Agent loads the `debate-with-gemini` skill, fetches the existing chat to resume context, and picks up where the last round left off.
-
-**Agent:** "Resumed debate on chat `c_abc123`. Ran 3 additional turns. Gemini conceded on the replication point but raised WAL-mode mitigations. Updated debate report ready."
-
-## Requirements
-
-| | Component | Notes |
-| --- | --- | --- |
-| **Runtime** | [`gemiterm`](https://github.com/Expert-Vision-Software/gemiterm) CLI | Must be installed and authenticated. Both bundled skills depend on it. |
-| **Optional** | Bun `>=1.0.0` | Required only for the CLI installer (`bunx opencode-gemiterm-skills install`) and the test suite (`bun test`). |
-
-## Troubleshooting
+Agent picks up exactly where the last round left off:
 
-| Symptom | Likely cause | Fix |
-| --- | --- | --- |
-| Skill not in `<available_skills>` list | Not installed yet | Run `bunx opencode-gemiterm-skills install` (or `--scope global`) |
-| Skill not in `<available_skills>` list after install | `gemiterm` auth expired or incomplete | Run `gemiterm status` and re-authenticate if needed |
-| `bunx opencode-gemiterm-skills` not found | Bun `<1.0.0` or package not in PATH | Ensure Bun `>=1.0.0` is installed; try `npx opencode-gemiterm-skills` as fallback |
-
-## Install (file:// reference)
-
-For local development against a checkout of this repo, reference the package directory directly from the consumer's `opencode.json`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugins": [
-    "file:///absolute/path/to/opencode-gemiterm-skills"
-  ]
-}
 ```
-
-This skips the npm install. OpenCode will auto-install skills from the local checkout on first load.
-
-## File layout
-
-```
-opencode-gemiterm-skills/
-├── .opencode/
-│   └── opencode.json              # self-config: skills.paths + permission.skill
-├── assets/
-│   └── skills/
-│       ├── gemiterm/
-│       │   ├── SKILL.md
-│       │   └── REFERENCE.md
-│       └── debate-with-gemini/
-│           ├── SKILL.md
-│           └── REFERENCE.md
-├── src/
-│   ├── cli.ts                     # CLI entry: install / uninstall / status
-│   ├── commands/
-│   │   ├── install.ts
-│   │   ├── uninstall.ts
-│   │   └── status.ts
-│   └── installer.ts               # core install logic
-├── tests/
-│   └── skills.test.ts             # smoke test
-├── .gitignore
-├── AGENTS.md
-├── CHANGELOG.md
-├── LICENSE
-├── README.md
-├── index.ts                       # module entry: re-exports plugin.ts
-├── package.json
-├── plugin.ts                      # plugin entry with config hook (auto-install on load)
-└── tsconfig.json
+Resumed debate on chat c_abc123. Ran 3 additional turns.
+Gemini conceded on the replication point but raised WAL-mode mitigations.
 ```
 
-## How it works
-
-### Install command
-
-`bunx opencode-gemiterm-skills install` copies skill files to the target `skills/` directory and registers the package in `opencode.json`:
-
-- **Local** (default): copies to `{project}/.opencode/skills/{gemiterm,debate-with-gemini}/` and updates `{project}/.opencode/opencode.json`
-- **Global**: copies to `~/.config/opencode/skills/{gemiterm,debate-with-gemini}/` and updates `~/.config/opencode/opencode.json`
-
-It also pre-grants `permission.skill: "allow"` for both skills and writes a `.version` marker to skip re-install on subsequent loads.
+## Requirements
 
-### Plugin auto-install
+| Component | Notes |
+|-----------|-------|
+| **[gemiterm](https://github.com/Expert-Vision-Software/gemiterm) CLI** | Must be installed and authenticated. Both skills depend on it. |
+| **Google Account** | Required for gemini web. Expiring cookie is stored locally only. |
 
-When OpenCode loads the package via `opencode.json` plugins array, `plugin.ts` runs the same (local) install logic with a version-marker check — so the package auto-installs skills on first use if not already installed.
+## Installation
 
-### CLI commands
+### CLI install (any agent)
 
-| Command | Description |
-| --- | --- |
-| `bunx opencode-gemiterm-skills install` | Install skills locally (or `--scope global`) |
-| `bunx opencode-gemiterm-skills uninstall` | Remove installed skills |
-| `bunx opencode-gemiterm-skills status` | Check install status and version |
+```bash
+# Via bunx
+bunx opencode-gemiterm-skills install
 
-`index.ts` is the module entry, a one-line re-export of `plugin.ts`.
+# Via npx
+npx opencode-gemiterm-skills install
+```
 
-## Development
+### OpenCode plugin
 
-Run the test suite:
+Add to your `opencode.json`:
 
-```bash
-bun test
+```json
+{
+  "plugins": ["opencode-gemiterm-skills"]
+}
 ```
 
-The smoke test verifies:
+## Why this plugin?
 
-- Both `assets/skills/*/SKILL.md` files exist and parse as valid YAML frontmatter.
-- `name` matches the directory name.
-- `description` is non-empty and within the 1024-character limit.
-- The `metadata.requires: gemiterm` link on `debate-with-gemini` is preserved.
-- The `metadata.tool: gemiterm` link on `gemiterm` is preserved.
-- `.opencode/opencode.json` exists and registers at least one skill path.
-- `package.json` points `opencode.plugin` at `.opencode/opencode.json`.
-
-## Notes for consumers
-
-- The `metadata.requires: gemiterm` field is preserved verbatim on `debate-with-gemini`. OpenCode does not enforce skill-to-skill dependencies — the agent must check `metadata.requires` and the prerequisites above before invoking `debate-with-gemini`.
-- The `metadata.tool`, `metadata.requires`, and `metadata.workflow` fields are stored under the `metadata` map (which OpenCode recognises). Sub-keys beyond `metadata` itself are not formally specified in the OpenCode skill schema, so they may be ignored by some agents — this package treats them as documentation only.
-- The CLI is exposed as `opencode-gemiterm-skills` via the `bin` field, implemented in `src/cli.ts`. Run it with `bunx opencode-gemiterm-skills` or `npx opencode-gemiterm-skills`.
+- **No context switching** — access your Gemini conversations without leaving your agent.
+- **Zero-config debates** — let your agent argue both sides of a technical decision with real Gemini responses.
+- **Portable chat data** — export Gemini history to Markdown for grep, archival, or feeding into other tools.
+- **Lightweight** — pure skill bundle, no runtime dependencies, loads on demand.
 
 ## Acknowledgments
 
 - [OpenCode](https://opencode.ai) — plugin architecture and skill loader
-- [Bun](https://bun.sh) — fast JS runtime used as the package's CLI host
-- [DeepWiki](https://deepwiki.com) — research and context tool for codebase exploration
-
-## Publishing
-
-This package is published to npm as `opencode-gemiterm-skills`. To cut a new release:
+- [gemiterm](https://github.com/Expert-Vision-Software/gemiterm) — underlying Gemini CLI
 
-```bash
-npm version patch   # or minor / major
-npm publish --access public
-```
+---
 
-The `prepublishOnly` script runs `tsc --noEmit` and `bun test` before publishing.
+<div align="center">
 
-## License
+**[📦 Install from npm](https://www.npmjs.com/package/opencode-gemiterm-skills)** · **[🤝 Contribute](CONTRIBUTING.md)** · **[📄 License](LICENSE)**
 
-MIT. See [LICENSE](LICENSE).
+</div>

package/package.json

@@ -1,21 +1,22 @@
 {
   "name": "opencode-gemiterm-skills",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "module": "index.ts",
-  "description": "OpenCode plugin bundling the gemiterm and debate-with-gemini skills.",
+  "description": "AI agent skills for Google Gemini — list, search, export Gemini chats and run structured debates with Gemini. Works with OpenCode, Claude Code, and any skill-compatible AI agent.",
   "license": "MIT",
   "publisher": "Expert Vision Software",
   "keywords": [
     "opencode",
     "opencode-plugin",
     "opencode-skills",
+    "agent-skills",
     "gemiterm",
     "gemini",
     "debate"
   ],
   "bin": {
-    "opencode-gemiterm-skills": "./src/cli.ts"
+    "opencode-gemiterm-skills": "src/cli.ts"
   },
   "engines": {
     "bun": ">=1.0.0"
@@ -25,7 +26,7 @@
     "index.ts",
     "plugin.ts",
     "src",
-    "assets",
+    "skills",
     "README.md",
     "AGENTS.md",
     "CHANGELOG.md",
@@ -46,7 +47,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Expert-Vision-Software/opencode-gemiterm-skills.git"
+    "url": "git+https://github.com/Expert-Vision-Software/opencode-gemiterm-skills.git"
   },
   "homepage": "https://github.com/Expert-Vision-Software/opencode-gemiterm-skills#readme",
   "bugs": {

package/{assets/skills → skills}/debate-with-gemini/REFERENCE.md

@@ -2,6 +2,8 @@
 
 Subagent prompt template, tactical patterns, and report format for the `debate-with-gemini` skill.
 
+> **Runtime note:** GemiTerm is a Bun-native CLI. Replace every `gemiterm` invocation with `bunx gemiterm` if the tool is not globally installed. See execution-loop details below.
+
 ---
 
 ## Subagent Prompt Template
@@ -30,14 +32,17 @@ For each turn:
 1. Send your message:
    gemiterm continue "{{GEMINI_CHAT_ID}}" "your message here"
 
+   If gemiterm is not globally installed, use:
+   bunx gemiterm continue "{{GEMINI_CHAT_ID}}" "your message here"
+
    Wait for Gemini's response written to the console.
 2. Analyze the response — concessions? New arguments? Weaknesses?
 3. Craft next response using Tactical Patterns below
 4. Repeat until turn limit or stop condition
 
-Prefer `gemiterm continue` because it returns Gemini's last response inline and avoids an extra round-trip.
+Prefer `gemiterm continue` (or `bunx gemiterm continue`) because it returns Gemini's last response inline and avoids an extra round-trip.
 
-Use `gemiterm fetch "{{GEMINI_CHAT_ID}}" --format json` ONLY if console output has parsing issues or times out.
+Use `gemiterm fetch "{{GEMINI_CHAT_ID}}" --format json` (or `bunx gemiterm fetch ...`) ONLY if console output has parsing issues or times out.
 
 ## Stopping Criteria
 - {{TURN_LIMIT}} turns completed
@@ -108,12 +113,13 @@ If the opencode config lacks bash permissions for `gemiterm`, add:
 {
   "permission": {
     "bash": {
-      "gemiterm *": "allow"
+      "gemiterm *": "allow",
+      "bunx gemiterm *": "allow"
     }
   }
 }
 ```
 
-This allows the subagent to run `gemiterm new`, `gemiterm continue`, `gemiterm fetch`, and `gemiterm list` without prompting.
+This allows the subagent to run `gemiterm new`, `gemiterm continue`, `gemiterm fetch`, `gemiterm list`, and their `bunx gemiterm` equivalents without prompting.
 
 Drop this into the top-level `permission` object in `opencode.json`. For per-agent override, nest it under `agent.<name>.permission`.

package/{assets/skills → skills}/debate-with-gemini/SKILL.md

@@ -2,10 +2,11 @@
 name: debate-with-gemini
 description: Conduct structured multi-turn technical debates with Gemini AI via gemiterm CLI. Delegates a subagent to argue a position (for/against) autonomously for up to N turns. Use when user says "debate gemini", "argue with gemini", "have gemini defend/attack X", "continue debate", or wants a technical position stress-tested against Gemini. Triggers on: debate, argue, gemini, position, for/against, stress-test, counter-argument. Requires gemiterm CLI installed and authenticated.
 license: MIT
-compatibility: opencode
+compatibility: opencode, claude-code, and any skill-compatible agent
 metadata:
-  requires: gemiterm
+  tool: gemiterm
   workflow: debate
+  runtime: bun
 ---
 
 # Debate with Gemini
@@ -16,7 +17,7 @@ metadata:
 User: "Debate gemini on for/against using X. Context: docs/arch.md. 5 turns."
 
 1. skill("gemiterm")                              — load CLI commands
-2. gemiterm status                                — verify auth
+2. gemiterm status                                — verify auth (or bunx gemiterm status)
 3. Read docs/arch.md, build seeding prompt
 4. gemiterm new "You argue AGAINST X. [context]"  — seed Gemini, capture chat_id
 5. Build opening argument for the FOR position
@@ -26,11 +27,24 @@ User: "Debate gemini on for/against using X. Context: docs/arch.md. 5 turns."
 
 ## Prerequisites
 
+GemiTerm is a **Bun-native** CLI. Before running any commands, resolve the executable:
+
+1. `gemiterm --version` — if this succeeds, use `gemiterm` directly.
+2. If not found, use `bunx gemiterm` as a transparent fallback for all commands.
+3. If `bun` is not installed, print the platform-appropriate install command and stop:
+
+| Platform | Command |
+|----------|---------|
+| macOS / Linux | `curl -fsSL https://bun.sh/install \| bash` |
+| Windows | `powershell -c "irm bun.sh/install.ps1 \| iex"` |
+
+Then:
+
 ```bash
 gemiterm status
 ```
 
-If not connected: `pipx install gemiterm && gemiterm install-browser && gemiterm auth`
+If not connected: install gemiterm globally (`bun install gemiterm -g`), then `gemiterm install-browser && gemiterm auth`.
 
 ## Inputs
 

package/{assets/skills → skills}/gemiterm/REFERENCE.md

@@ -2,6 +2,8 @@
 
 Complete command reference for GemiTerm CLI. Loaded on demand by [SKILL.md](SKILL.md).
 
+> **Runtime note:** GemiTerm is a Bun-native application. All commands below assume `gemiterm` is available. If not globally installed, prefix every command with `bunx` (e.g. `bunx gemiterm list --format json`). See [SKILL.md](SKILL.md) > "Install & invocation" for the full resolution flow.
+
 ## Contents
 
 - [Commands](#commands)

package/{assets/skills → skills}/gemiterm/SKILL.md

@@ -1,26 +1,55 @@
 ---
 name: gemiterm
-description: Google Gemini Terminal CLI wrapper for listing chats, fetching transcripts, exporting conversations, and managing profiles via the gemiterm Python CLI. Use when the user asks to read, list, export, or interact with Gemini chat history from a terminal, or invokes "gemiterm" commands.
+description: Google Gemini Terminal CLI wrapper for listing chats, fetching transcripts, exporting conversations, and managing profiles via the gemiterm Bun-native CLI. Use when the user asks to read, list, export, or interact with Gemini chat history from a terminal, or invokes "gemiterm" commands.
 license: MIT
-compatibility: opencode
+compatibility: opencode, claude-code, and any skill-compatible agent
 metadata:
   tool: gemiterm
+  runtime: bun
 ---
 
 # GemiTerm — Google Gemini Terminal CLI
 
 GemiTerm provides terminal access to Google Gemini chat history: list, fetch, export, delete, and manage profiles. Commands that emit `--format json` are automation-friendly; `auth` and `continue` require interactive flows.
 
-## Install check
+## Install & invocation
+
+GemiTerm is a **Bun-native** CLI. All `gemiterm` commands below assume the tool is available. The agent must resolve the executable at runtime:
+
+### 1. Check if globally installed
 
 ```bash
 gemiterm --version
 ```
 
-If missing:
+If this succeeds, use `gemiterm` directly for all commands.
+
+### 2. Fallback: `bunx gemiterm`
+
+If not globally installed, use `bunx gemiterm` as a transparent fallback. This downloads and runs the latest version on first use:
+
+```bash
+bunx gemiterm --version
+bunx gemiterm list --format json
+bunx gemiterm auth
+# … etc — prefix every command with "bunx"
+```
+
+### 3. Bun not installed
+
+If `bun` is not available either, print the appropriate install command for the user's platform and stop:
+
+| Platform | Command |
+|----------|---------|
+| macOS / Linux | `curl -fsSL https://bun.sh/install \| bash` |
+| Windows | `powershell -c "irm bun.sh/install.ps1 \| iex"` |
+
+After the user installs Bun, re-run from step 1. Auto-detect the platform from `$OSTYPE`, `uname`, or `process.platform`.
+
+**To install gemiterm globally (optional):**
 
 ```bash
-pipx install gemiterm
+bun install gemiterm -g
 gemiterm install-browser
 gemiterm auth
 ```

package/src/installer.ts

@@ -169,7 +169,7 @@ export async function install(
   }
 
   for (const name of SKILL_NAMES) {
-    const srcSkillDir = join(pkgDir, "assets", "skills", name);
+    const srcSkillDir = join(pkgDir, "skills", name);
     const destSkillDir = join(configBase, "skills", name);
     await copyDir(srcSkillDir, destSkillDir);
     skillPaths.push(destSkillDir);