docs(code-execution): document HERMES_* env narrowing + passthrough workaround

The execute_code sandbox-child env scrub (108397726, #27303) deliberately
dropped the broad HERMES_ prefix passthrough, keeping only an operational
4-var allowlist (HERMES_HOME/PROFILE/CONFIG/ENV). A script that relied on a
non-secret HERMES_* var (HERMES_BASE_URL, HERMES_KANBAN_DB, HERMES_*_WEBHOOK,
or a plugin-defined one) now sees it unset in the child.

Document the behavior change and the two recovery routes (terminal.env_passthrough
in config.yaml, or required_environment_variables in skill frontmatter), plus
the debug log line that surfaces the drop for diagnosis.

.github/workflows/nix.yml

@@ -37,16 +37,23 @@ jobs:
 
       - name: Check flake
         id: flake
+        if: runner.os == 'Linux'
         continue-on-error: true
         run: nix flake check --print-build-logs
 
-      # When the flake check fails, run a targeted diagnostic to see if
+      - name: Build package
+        id: build
+        if: runner.os == 'Linux'
+        continue-on-error: true
+        run: nix build --print-build-logs
+
+      # When the real Nix build fails, run a targeted diagnostic to see if
       # the failure is specifically a stale npm lockfile hash in one of the
       # known npm subpackages (tui / web).  This avoids surfacing a generic
       # "build failed" message when the fix is a single known command.
       - name: Diagnose npm lockfile hashes
         id: hash_check
-        if: steps.flake.outcome == 'failure' && runner.os == 'Linux'
+        if: (steps.flake.outcome == 'failure' || steps.build.outcome == 'failure') && runner.os == 'Linux'
         continue-on-error: true
         env:
           LINK_SHA: ${{ steps.sha.outputs.full }}
@@ -81,25 +88,30 @@ jobs:
             - Or [run the Nix Lockfile Fix workflow](${{ github.server_url }}/${{ github.repository }}/actions/workflows/nix-lockfile-fix.yml) manually (pass PR `#${{ github.event.pull_request.number }}`)
             - Or locally: `nix run .#fix-lockfiles` and commit the diff
 
-      # Clear the sticky comment when either the flake check passed outright (no
+      # Clear the sticky comment when either the build passed outright (no
       # hash check needed) or the hash check explicitly returned stale=false
-      # (check failed for a non-hash reason).
+      # (build failed for a non-hash reason).
       - name: Clear sticky PR comment (resolved)
         if: |
           github.event_name == 'pull_request' &&
+          runner.os == 'Linux' &&
           (steps.hash_check.outputs.stale == 'false' ||
-           steps.flake.outcome == 'success')
+           (steps.flake.outcome == 'success' && steps.build.outcome == 'success'))
         uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728  # v2.9.1
         with:
           header: nix-lockfile-check
           delete: true
 
-      - name: Final fail if flake check failed
-        if: steps.flake.outcome == 'failure'
+      - name: Final fail if build or flake failed
+        if: steps.flake.outcome == 'failure' || steps.build.outcome == 'failure'
         run: |
           if [ "${{ steps.hash_check.outputs.stale }}" == "true" ]; then
             echo "::error::Nix build failed due to stale npm lockfile hash. Run: nix run .#fix-lockfiles"
           else
-            echo "::error::Nix flake check failed. See logs above."
+            echo "::error::Nix build/flake check failed. See logs above."
           fi
           exit 1
+
+      - name: Evaluate flake (macOS)
+        if: runner.os == 'macOS'
+        run: nix flake show --json > /dev/null

.gitignore

@@ -3,7 +3,6 @@
 /_pycache/
 *.pyc*
 __pycache__/
-build/
 .venv/
 .vscode/
 .env

hermes_cli/main.py

@@ -13390,11 +13390,6 @@ Examples:
         "--yes", "-y", action="store_true", help="Skip confirmation"
     )
 
-    sessions_subparsers.add_parser(
-        "optimize",
-        help="Reclaim disk space: merge FTS5 segments + VACUUM (no data change)",
-    )
-
     sessions_subparsers.add_parser("stats", help="Show session store statistics")
 
     sessions_rename = sessions_subparsers.add_parser(
@@ -13567,34 +13562,6 @@ Examples:
             relaunch(["--resume", selected_id])
             return  # won't reach here after execvp
 
-        elif action == "optimize":
-            db_path = db.db_path
-            before_mb = (
-                os.path.getsize(db_path) / (1024 * 1024)
-                if db_path.exists()
-                else 0.0
-            )
-            print("Optimizing session store (FTS merge + VACUUM)…")
-            try:
-                # vacuum() merges FTS5 segments (optimize_fts) then VACUUMs,
-                # and returns the number of indexes it merged.
-                n = db.vacuum()
-            except Exception as e:
-                print(f"Error: optimization failed: {e}")
-                db.close()
-                return
-            after_mb = (
-                os.path.getsize(db_path) / (1024 * 1024)
-                if db_path.exists()
-                else 0.0
-            )
-            saved = before_mb - after_mb
-            print(f"Optimized {n} FTS index(es).")
-            print(
-                f"Database size: {before_mb:.1f} MB -> {after_mb:.1f} MB "
-                f"(reclaimed {saved:.1f} MB)"
-            )
-
         elif action == "stats":
             total = db.session_count()
             msgs = db.message_count()

hermes_cli/models.py

@@ -49,7 +49,7 @@ OPENROUTER_MODELS: list[tuple[str, str]] = [
     ("xiaomi/mimo-v2.5-pro",                   ""),
     ("tencent/hy3-preview",                    ""),
     ("google/gemini-3-pro-image-preview",      ""),
-    ("google/gemini-3.5-flash",                ""),
+    ("google/gemini-3-flash-preview",          ""),
     ("google/gemini-3.1-pro-preview",          ""),
     ("google/gemini-3.1-flash-lite-preview",   ""),
     ("qwen/qwen3.6-35b-a3b",                   ""),
@@ -156,7 +156,7 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
         "xiaomi/mimo-v2.5-pro",
         "tencent/hy3-preview",
         "google/gemini-3-pro-preview",
-        "google/gemini-3.5-flash",
+        "google/gemini-3-flash-preview",
         "google/gemini-3.1-pro-preview",
         "google/gemini-3.1-flash-lite-preview",
         "qwen/qwen3.6-35b-a3b",

hermes_state.py

@@ -3251,59 +3251,7 @@ class SessionDB:
 
     # ── Space reclamation ──
 
-    # FTS5 virtual tables whose b-tree segments we merge on optimize. The
-    # trigram table is created lazily / may be disabled, so we probe before
-    # touching it (see optimize_fts).
-    _FTS_TABLES = ("messages_fts", "messages_fts_trigram")
-
-    def _fts_table_exists(self, name: str) -> bool:
-        """True if an FTS5 virtual table is queryable in this DB."""
-        try:
-            self._conn.execute(f"SELECT 1 FROM {name} LIMIT 0")
-            return True
-        except sqlite3.OperationalError:
-            return False
-
-    def optimize_fts(self) -> int:
-        """Merge fragmented FTS5 b-tree segments into one per index.
-
-        FTS5 indexes grow as a series of incremental segments — one per
-        ``INSERT`` batch driven by the message triggers. Over tens of
-        thousands of messages these segments accumulate, which both bloats
-        the ``*_data`` shadow tables and slows ``MATCH`` queries that must
-        scan every segment. The special ``'optimize'`` command rewrites each
-        index as a single merged segment.
-
-        This is purely a maintenance operation — it changes neither search
-        results nor ``snippet()`` output, only on-disk layout and query
-        speed. It is complementary to VACUUM: ``optimize`` compacts the FTS
-        index internally, then VACUUM returns the freed pages to the OS.
-
-        Skips any FTS table that does not exist (e.g. the trigram index when
-        disabled via ``HERMES_DISABLE_FTS_TRIGRAM`` or not yet created), so
-        it is safe to call unconditionally.
-
-        Returns the number of FTS indexes that were optimized.
-        """
-        optimized = 0
-        with self._lock:
-            for tbl in self._FTS_TABLES:
-                if not self._fts_table_exists(tbl):
-                    continue
-                try:
-                    # The column name in the INSERT must match the table name
-                    # for FTS5 special commands.
-                    self._conn.execute(
-                        f"INSERT INTO {tbl}({tbl}) VALUES('optimize')"
-                    )
-                    optimized += 1
-                except sqlite3.OperationalError as exc:
-                    logger.warning(
-                        "FTS optimize failed for %s: %s", tbl, exc
-                    )
-        return optimized
-
-    def vacuum(self) -> int:
+    def vacuum(self) -> None:
         """Run VACUUM to reclaim disk space after large deletes.
 
         SQLite does not shrink the database file when rows are deleted —
@@ -3316,21 +3264,7 @@ class SessionDB:
         exclusive lock, so callers must ensure no other writers are
         active. Safe to call at startup before the gateway/CLI starts
         serving traffic.
-
-        FTS5 segments are merged first via :meth:`optimize_fts` so the
-        subsequent VACUUM reclaims the pages freed by the merge. This is a
-        layout-only optimization — search results are unchanged.
-
-        Returns the number of FTS indexes that were optimized (0 if the
-        merge step failed or no FTS tables exist).
         """
-        # Merge FTS5 segments before VACUUM so the freed pages are returned
-        # to the OS in the same pass. optimize_fts() manages its own lock.
-        optimized = 0
-        try:
-            optimized = self.optimize_fts()
-        except Exception as exc:
-            logger.warning("FTS optimize before VACUUM failed: %s", exc)
         # VACUUM cannot be executed inside a transaction.
         with self._lock:
             # Best-effort WAL checkpoint first, then VACUUM.
@@ -3339,7 +3273,6 @@ class SessionDB:
             except Exception:
                 pass
             self._conn.execute("VACUUM")
-        return optimized
 
     def maybe_auto_prune_and_vacuum(
         self,

nix/checks.nix

@@ -58,22 +58,6 @@ json.dump(sorted(leaf_paths(DEFAULT_CONFIG)), sys.stdout, indent=2)
             echo "ok" > $out/result
           ''
         );
-
-        # Verify the default package builds successfully (cross-platform).
-        # On Linux the runtime checks below already depend on the package,
-        # but this ensures darwin builders also build it during flake check.
-        build-package = pkgs.runCommand "hermes-build-package" { } ''
-          echo "PASS: package built at ${hermes-agent}"
-          mkdir -p $out
-          echo "ok" > $out/result
-        '';
-
-        # Verify the devShell builds successfully (cross-platform).
-        build-devshell = pkgs.runCommand "hermes-build-devshell" { } ''
-          echo "PASS: devShell built at ${self'.devShells.default}"
-          mkdir -p $out
-          echo "ok" > $out/result
-        '';
       } // lib.optionalAttrs pkgs.stdenv.hostPlatform.isLinux {
         # Verify binaries exist and are executable
         package-contents = pkgs.runCommand "hermes-package-contents" { } ''

optional-skills/autonomous-ai-agents/antigravity-cli/SKILL.md

@@ -1,177 +0,0 @@
----
-name: antigravity-cli
-description: "Operate the Antigravity CLI (agy): plugins, auth, sandbox."
-version: 0.1.0
-author: Tony Simons (asimons81), Hermes Agent
-license: MIT
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [Coding-Agent, Antigravity, CLI, Auth, Plugins, Sandbox]
-    related_skills: [grok, codex, claude-code, hermes-agent]
----
-
-# Antigravity CLI (`agy`)
-
-Operator guide for the Antigravity CLI, invoked as `agy`. Run all `agy`
-commands through the Hermes `terminal` tool; inspect its config and logs with
-`read_file`. This skill is reference + procedure — it does not wrap a network
-API, so there is nothing to authenticate from Hermes itself.
-
-## When to Use
-
-- Installing, updating, or smoke-testing the `agy` binary
-- Driving non-interactive `agy --print` / `agy -p` one-shots
-- Debugging Antigravity auth, sandbox, permissions, or plugin state
-- Reading Antigravity settings, keybindings, conversations, or logs
-
-## Mental model
-
-Antigravity has two layers — keep them distinct or the guidance will be wrong:
-
-1. **Shell wrapper commands** — `agy help`, `agy install`, `agy plugin`,
-   `agy update`, `agy changelog`. Run these through the `terminal` tool.
-2. **Interactive in-session slash commands** — `/config`, `/permissions`,
-   `/skills`, `/agents`, etc. These only exist inside a running `agy` TUI
-   session, not on the shell wrapper.
-
-`agy help` shows the shell wrapper surface, NOT the in-session slash commands.
-
-## Prerequisites
-
-- The `agy` binary on PATH. Verify through the `terminal` tool:
-  `command -v agy && agy --version`.
-- No env vars or API keys required by this skill — Antigravity manages its own
-  auth via the OS keyring / browser sign-in (see Authentication below).
-
-## How to Run
-
-Invoke every `agy` command through the `terminal` tool. Examples:
-
-```
-terminal(command="agy --version")
-terminal(command="agy help")
-terminal(command="agy plugin list")
-terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project")
-```
-
-For an interactive multi-turn TUI session, launch `agy` with `pty=true` (and
-tmux for capture/monitoring), the same pattern the `codex` / `claude-code`
-skills use. For one-shot smoke tests and scripted prompts, prefer
-`agy --print` (non-interactive).
-
-To inspect Antigravity's own files, use `read_file` on the paths under Core
-paths below — do not `cat` them through the terminal.
-
-## Core paths
-
-- Binary / entrypoint: `agy`
-- App data dir: `~/.gemini/antigravity-cli/`
-- Settings file: `~/.gemini/antigravity-cli/settings.json`
-- Keybindings file: `~/.gemini/antigravity-cli/keybindings.json`
-- Logs: `~/.gemini/antigravity-cli/log/cli-*.log`
-- Conversations: `~/.gemini/antigravity-cli/conversations/`
-- Brain artifacts: `~/.gemini/antigravity-cli/brain/`
-- History: `~/.gemini/antigravity-cli/history.jsonl`
-- Plugin staging: `~/.gemini/antigravity-cli/plugins/<plugin_name>/`
-
-## Quick Reference
-
-### Wrapper commands
-- `agy changelog`
-- `agy help`
-- `agy install`
-- `agy plugin` / `agy plugins`
-- `agy update`
-
-### Useful flags
-- `--add-dir`
-- `--continue` / `-c`
-- `--conversation`
-- `--dangerously-skip-permissions`
-- `--print` / `-p`
-- `--print-timeout`
-- `--prompt`
-- `--prompt-interactive` / `-i`
-- `--sandbox`
-- `--log-file`
-- `--version`
-
-### Plugin subcommands (`agy plugin --help`)
-- `list`, `import [source]`, `install <target>`, `uninstall <name>`,
-  `enable <name>`, `disable <name>`, `validate [path]`, `link <mp> <target>`,
-  `help`
-
-### Install flags (`agy install --help`)
-- `--dir`, `--skip-aliases`, `--skip-path`
-
-### In-session slash commands
-- **Conversation control:** `/resume` (`/switch`), `/rewind` (`/undo`),
-  `/rename <name>`, `/clear`, `/fork`, `/reset`, `/new`
-- **Settings & tools:** `/config`, `/settings`, `/permissions`, `/model`,
-  `/keybindings`, `/statusline`, `/tasks`, `/skills`, `/mcp`, `/open <path>`,
-  `/usage`, `/logout`, `/agents`
-- **Prompt helpers:** `@` path autocomplete, `esc esc` clears the prompt (when
-  not streaming), `!` runs a terminal command directly, `?` opens help
-
-## Settings and permissions
-
-### Common settings keys (`settings.json`)
-- `allowNonWorkspaceAccess`
-- `colorScheme`
-- `permissions.allow`
-- `trustedWorkspaces`
-
-### Permission modes
-`request-review`, `always-proceed`, `strict`, `proceed-in-sandbox`.
-
-### Sandbox behavior
-- `enableTerminalSandbox` is a boolean in `settings.json`; default `false`.
-- Launch-time overrides (`--sandbox`, `--dangerously-skip-permissions`) can
-  supersede persistent settings for the current session.
-
-## Authentication behavior
-
-- The CLI tries the OS secure keyring first.
-- With no saved session, it falls back to browser-based Google sign-in.
-- Locally it opens the default browser; over SSH it prints an authorization URL
-  and expects the auth code pasted back.
-- `/logout` removes saved credentials.
-
-## Plugins
-
-- Plugins stage under `~/.gemini/antigravity-cli/plugins/<plugin_name>/`.
-- They can bundle skills, agents, rules, MCP servers, and hooks.
-- `agy plugin list` returning no imported plugins is a valid empty state.
-
-## Pitfalls
-
-- `agy help` shows wrapper commands, not interactive slash commands.
-- `agy --version` is the safe non-interactive version check; `agy version` is
-  interactive and can fail without a real TTY.
-- First place to look for failures: `~/.gemini/antigravity-cli/log/cli-*.log`
-  (read with `read_file`).
-- Don't confuse persistent JSON settings with launch-time overrides.
-- `~/.gemini/antigravity-cli/bin/agentapi` is a thin wrapper to `agy agentapi`.
-- On WSL, token storage is file-based, so auth issues are usually local-file /
-  session-state problems, not browser-only problems.
-- Workspace identity can depend on launch directory and the `.antigravitycli`
-  project marker.
-
-## Verification
-
-Confirm the install is real and usable, all through the `terminal` tool (read
-files with `read_file`):
-
-1. `terminal(command="command -v agy")`
-2. `terminal(command="agy --version")`
-3. `terminal(command="agy help")`
-4. `terminal(command="agy plugin list")`
-5. `read_file` on `~/.gemini/antigravity-cli/settings.json`
-6. `read_file` on the latest `~/.gemini/antigravity-cli/log/cli-*.log`
-7. If needed, `read_file` on `~/.gemini/antigravity-cli/keybindings.json`
-
-## Support files
-
-- `references/cli-docs.md` — condensed notes from the getting-started, usage,
-  and features docs.

optional-skills/autonomous-ai-agents/antigravity-cli/references/cli-docs.md

@@ -1,64 +0,0 @@
-# Antigravity CLI docs, condensed
-
-Source pages reviewed:
-- `/docs/cli-getting-started`
-- `/docs/cli-using`
-- `/docs/cli-features`
-
-## Install
-- macOS/Linux: `curl -fsSL https://antigravity.google/cli/install.sh | bash`
-- Windows PowerShell: `irm https://antigravity.google/cli/install.ps1 | iex`
-- Windows CMD: `curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd`
-
-## Authentication
-- Tries secure keyring first.
-- If no saved session exists, falls back to browser-based Google sign-in.
-- Local machine: opens the default browser.
-- SSH/remote: prints a secure authorization URL, then expects the auth code to be pasted back.
-- `/logout` removes saved credentials.
-
-## Config and files
-- Settings: `~/.gemini/antigravity-cli/settings.json`
-- Keybindings: `~/.gemini/antigravity-cli/keybindings.json`
-- Plugins: `~/.gemini/antigravity-cli/plugins/<plugin_name>/`
-
-## Useful slash commands
-- `/config`, `/settings`
-- `/permissions`
-- `/resume` / `/switch`
-- `/rewind` / `/undo`
-- `/rename <name>`
-- `/model`
-- `/keybindings`
-- `/statusline`
-- `/tasks`
-- `/skills`
-- `/mcp`
-- `/open <path>`
-- `/usage`
-- `/logout`
-- `/agents`
-
-## Prompt helpers
-- `@` path autocomplete
-- `esc esc` clears prompt when not streaming
-- `!` runs a terminal command
-- `?` opens help / slash command list
-
-## Permissions and sandbox
-- Permission modes: `request-review`, `always-proceed`, `strict`, `proceed-in-sandbox`
-- Launch overrides: `--sandbox`, `--dangerously-skip-permissions`
-- Sandbox setting: `enableTerminalSandbox` in `settings.json` (default `false`)
-
-## Plugins
-- Plugins can bundle skills, agents, rules, MCP servers, and hooks.
-- They are staged locally and auto-discovered once installed.
-
-## Subagents
-- `/agents` opens the panel for active/completed subagents.
-- Subagents can run in parallel and request approvals.
-
-## Keybindings
-- `~/.gemini/antigravity-cli/keybindings.json`
-- Malformed JSON falls back to defaults for broken actions.
-- Docs list default bindings for clear, submit, cancel, exit, suspend, editor, approval yes/no, navigation, clipboard, undo/redo, and newline insertion.

optional-skills/autonomous-ai-agents/grok/SKILL.md

@@ -1,301 +0,0 @@
----
-name: grok
-description: "Delegate coding to xAI Grok Build CLI (features, PRs)."
-version: 0.1.0
-author: Matt Maximo (MattMaximo), Hermes Agent
-license: MIT
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [Coding-Agent, Grok, xAI, Code-Review, Refactoring, Automation]
-    related_skills: [codex, claude-code, hermes-agent]
----
-
-# Grok Build CLI — Hermes Orchestration Guide
-
-Delegate coding tasks to [Grok Build](https://docs.x.ai/build/overview) (xAI's
-autonomous coding agent CLI, the `grok` command) via the Hermes terminal. Grok
-can read files, write code, run shell commands, spawn subagents, and manage git
-workflows. It runs three ways: an interactive TUI, **headless** (`-p`), and as
-an **ACP agent** over JSON-RPC.
-
-This is the third sibling to `codex` and `claude-code`. The orchestration
-pattern is nearly identical — **prefer headless `-p` for one-shots**, use a PTY
-for interactive sessions.
-
-## When to use
-
-- Building features
-- Refactoring
-- PR reviews
-- Batch issue fixing
-- Any task where you'd otherwise reach for Codex / Claude Code but want Grok
-
-## Prerequisites
-
-- **Install (preferred):** `npm install -g @xai-official/grok`
-  - The official installer `curl -fsSL https://x.ai/cli/install.sh | bash` also
-    works, but the `x.ai` host is Cloudflare-walled in some environments. The
-    npm path avoids that dependency entirely.
-- **Auth — SuperGrok / X Premium+ subscription (primary path):**
-  - Run `grok login` once → opens a browser for OAuth → token cached in
-    `~/.grok/auth.json`. This uses your **SuperGrok or X Premium+** subscription
-    (no per-token API billing).
-  - Check sign-in state by looking for `~/.grok/auth.json`, or run a cheap
-    headless smoke test: `grok --no-auto-update -p "Say ok."`
-  - In the TUI, `/logout` signs out and `/login` (or relaunching) signs back in.
-- **No git repo required** — unlike Codex, Grok runs fine outside a git
-  directory (good for scratch/throwaway tasks).
-- **Claude Code / AGENTS.md compatible with zero config** — Grok auto-reads
-  `CLAUDE.md`, `.claude/` (skills, agents, MCPs, hooks, rules), and the
-  `AGENTS.md` family. Existing project context just works.
-
-> **API-key fallback (not the default for this user):** Grok also supports
-> setting the `XAI_API_KEY` environment variable for pay-as-you-go billing
-> via `api.x.ai`. Only use
-> this if `grok login` / SuperGrok auth is unavailable. The subscription path
-> (`grok login`) is the intended setup here.
-
-## Two Orchestration Modes
-
-### Mode 1: Headless (`-p`) — Non-Interactive (PREFERRED)
-
-Runs a one-shot task, prints the result, and exits. No PTY, no interactive
-dialogs to navigate. This is the cleanest integration path — the analog of
-`claude -p` and `codex exec`.
-
-```
-terminal(command="grok --no-auto-update -p 'Add a dark mode toggle to settings'", workdir="/path/to/project", timeout=180)
-```
-
-Always pass `--no-auto-update` in automation to skip background update checks.
-
-**When to use headless:**
-- One-shot coding tasks (fix a bug, add a feature, refactor)
-- CI/CD automation and scripting
-- Structured output parsing with `--output-format json`
-- Any task that doesn't need multi-turn conversation
-
-### Mode 2: Interactive PTY — Multi-Turn TUI Sessions
-
-The TUI is a fullscreen, mouse-interactive app. Drive it with `pty=true`. For
-robust monitoring/input use tmux (same pattern as the `claude-code` skill).
-
-```
-# Launch in a tmux session for capture-pane monitoring
-terminal(command="tmux new-session -d -s grok-work -x 140 -y 40")
-terminal(command="tmux send-keys -t grok-work 'cd /path/to/project && grok' Enter")
-
-# Wait for startup, then send a task
-terminal(command="sleep 5 && tmux send-keys -t grok-work 'Refactor the auth module to use JWT' Enter")
-
-# Monitor progress
-terminal(command="sleep 15 && tmux capture-pane -t grok-work -p -S -50")
-
-# Exit when done
-terminal(command="tmux send-keys -t grok-work '/quit' Enter && sleep 1 && tmux kill-session -t grok-work")
-```
-
-**Tip for headless-but-inline output:** if you want TUI-style output without the
-fullscreen alt-screen takeover (e.g. for cleaner logs), add `--no-alt-screen`.
-For pure automation, headless `-p` is still cleaner than the TUI.
-
-## Headless Deep Dive
-
-### Common Flags
-
-| Flag | Effect |
-|------|--------|
-| `-p, --single <PROMPT>` | Send one prompt, run headless, exit |
-| `-m, --model <MODEL>` | Choose a model |
-| `-s, --session-id <ID>` | Create or resume a named headless session |
-| `-r, --resume <ID>` | Resume an existing session |
-| `-c, --continue` | Continue the most recent session in the current directory |
-| `--cwd <PATH>` | Set the working directory |
-| `--output-format <FMT>` | `plain` (default), `json`, or `streaming-json` |
-| `--always-approve` | Auto-approve all tool executions (the `--full-auto` / `--yolo` equivalent) |
-| `--no-alt-screen` | Run inline, no fullscreen TUI takeover |
-| `--no-auto-update` | Skip background update checks (use in all automation) |
-
-### Output Formats
-
-- `plain` — human-readable text (default)
-- `json` — one JSON object at the end of the run (parse the result cleanly)
-- `streaming-json` — newline-delimited JSON events as they arrive
-
-```
-# Structured result for parsing
-terminal(command="grok --no-auto-update -p 'List all TODO comments in src/' --output-format json", workdir="/project", timeout=120)
-
-# Auto-approve for autonomous building
-terminal(command="grok --no-auto-update --always-approve -p 'Refactor the database layer and run the tests'", workdir="/project", timeout=300)
-```
-
-### Background Mode (Long Tasks)
-
-```
-# Start headless in background
-terminal(command="grok --no-auto-update --always-approve -p 'Refactor the auth module'", workdir="/project", background=true, notify_on_complete=true)
-# Returns session_id
-
-# Monitor
-process(action="poll", session_id="<id>")
-process(action="log", session_id="<id>")
-
-# Kill if needed
-process(action="kill", session_id="<id>")
-```
-
-For an interactive (TUI) background session, use `pty=true` + tmux and monitor
-with `tmux capture-pane`, exactly like the `claude-code` / `codex` skills.
-
-### Session Continuation
-
-```
-# Start a named session
-terminal(command="grok --no-auto-update -s refactor-db -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)
-
-# Resume it later
-terminal(command="grok --no-auto-update -r refactor-db -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)
-
-# Or continue the most recent session in this directory
-terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60)
-```
-
-## Read-Only Audit → Markdown Note Pattern
-
-To have Grok review local artifacts and return a clean markdown note (for
-Obsidian or a repo) without mutating anything:
-
-1. Prepare stable input files first with Hermes tools (`read_file`,
-   `write_file`). Snapshot only the relevant context into a temp file rather
-   than dumping raw paths.
-2. Run Grok headless **without** `--always-approve` so it cannot auto-write, and
-   demand `markdown only, no preamble`.
-3. Save Grok's stdout straight into the destination note with `write_file()`.
-
-```
-grok --no-auto-update -p "Read /tmp/current.md and /tmp/inventory.md. Produce markdown only, no preamble. Output a clean note titled 'Cleanup Review'." --output-format plain
-```
-
-**Pitfall (same as Claude Code):** for document rewrites, a loose "rewrite this"
-prompt may return a change summary instead of the full file. Instead: pipe the
-file in, and demand `Return ONLY the full revised markdown document. No intro,
-no explanation, no code fences. Start immediately with '# Title'.` Verify the
-first lines with `read_file()` before overwriting the destination.
-
-## PR Review Patterns
-
-### Quick Review (Headless)
-
-```
-terminal(command="cd /path/to/repo && git diff main...feature-branch | grok --no-auto-update -p 'Review this diff for bugs, security issues, and style problems. Be thorough.'", timeout=120)
-```
-
-### Clone-to-temp Review (safe, no repo mutation)
-
-```
-terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && grok --no-auto-update -p 'Review the changes vs origin/main. Check bugs, security, race conditions, missing tests.'", pty=true, timeout=300)
-```
-
-### Post the review
-
-```
-terminal(command="gh pr comment 42 --body '<review text>'", workdir="/path/to/repo")
-```
-
-## Parallel Issue Fixing with Worktrees
-
-```
-# Create worktrees
-terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
-terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
-
-# Launch Grok headless in each (background)
-terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, notify_on_complete=true)
-terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, notify_on_complete=true)
-
-# Monitor
-process(action="list")
-
-# After completion: push and open PRs
-terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
-terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")
-
-# Cleanup
-terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
-```
-
-## Useful Subcommands & TUI Commands
-
-| Command | Purpose |
-|---------|---------|
-| `grok` | Start the interactive TUI |
-| `grok -p "query"` | Headless one-shot |
-| `grok login` / `grok logout` | Sign in / out (SuperGrok / X Premium+ OAuth) |
-| `grok inspect` | Show what Grok discovered in cwd: config sources, instructions, skills, plugins, hooks, MCP servers |
-| `grok agent stdio` | Run as an ACP agent over JSON-RPC (for IDE/tool integration) |
-| `grok update` | Update the CLI (needs the `x.ai` host; skip in automation) |
-
-TUI slash commands (interactive only): `/model <name>`, `/always-approve`,
-`/plan`, `/context`, `/compact`, `/resume`, `/sessions`, `/fork`, `/usage`,
-`/quit`. `Shift+Tab` cycles session modes (including Plan mode, which blocks
-write tools except the session plan file).
-
-## Config (`~/.grok/config.toml`)
-
-```toml
-[cli]
-auto_update = false          # skip background update checks persistently
-
-[ui]
-permission_mode = "ask"      # or "always-approve" to skip tool prompts by default
-
-[models]
-default = "grok-build-0.1"
-```
-
-Put global preferences in `~/.grok/config.toml` (not project-scoped
-`.grok/config.toml`). `permission_mode` supersedes the legacy `approval_mode` /
-`yolo = true` keys.
-
-## Pitfalls & Gotchas
-
-1. **Auth is subscription-gated.** `grok login` requires a SuperGrok or X
-   Premium+ subscription. If login fails or there's no `~/.grok/auth.json`,
-   confirm the subscription is active before falling back to `XAI_API_KEY`.
-2. **Don't conflate Hermes' xAI auth with the `grok` CLI's auth.** Hermes'
-   `x_search` runs on its own xAI OAuth; the standalone `grok` CLI has a
-   separate token in `~/.grok/auth.json`. A working `x_search` does NOT mean
-   `grok` is logged in.
-3. **Always pass `--no-auto-update` in automation** — otherwise Grok phones home
-   for update checks (and `x.ai`/`storage.googleapis.com` may be unreachable).
-4. **Prefer npm install over the curl installer** — `npm install -g
-   @xai-official/grok` avoids the Cloudflare-walled `x.ai` host.
-5. **`--always-approve` is the autonomous-build switch.** Without it, headless
-   runs may stall waiting on tool-approval prompts. Omit it deliberately for
-   read-only review/audit work so Grok can't mutate files.
-6. **Headless `-p` skips TUI dialogs**; the TUI needs `pty=true` (+ tmux for
-   monitoring), just like Claude Code.
-7. **Use `--no-alt-screen`** if you run the TUI inline and the fullscreen
-   alt-screen takeover garbles captured output.
-8. **No git repo needed**, but for PR/commit workflows you still want one — use
-   `mktemp -d && git init` for scratch commit tasks.
-9. **Clean up tmux sessions** with `tmux kill-session -t <name>` when done.
-
-## Rules for Hermes Agents
-
-1. **Prefer headless `-p`** for single tasks — cleanest integration, structured
-   output via `--output-format json`.
-2. **Always set `workdir`** (or `--cwd`) so Grok targets the right project.
-3. **Pass `--no-auto-update`** in every automated invocation.
-4. **Use `--always-approve` only when Grok should write autonomously**; omit it
-   for read-only reviews and audits.
-5. **Background long tasks** with `background=true, notify_on_complete=true` and
-   monitor via the `process` tool.
-6. **Use tmux for multi-turn interactive work** and monitor with
-   `tmux capture-pane -t <session> -p -S -50`.
-7. **Verify auth before relying on it** — check `~/.grok/auth.json` or run a
-   cheap `grok -p "Say ok."` smoke test; don't assume Hermes' xAI auth carries
-   over.
-8. **Report results to the user** — summarize what Grok changed and what's left.

tests/test_hermes_state.py

@@ -2676,64 +2676,6 @@ class TestVacuum:
         db.vacuum()
 
 
-class TestOptimizeFts:
-    def test_optimize_returns_index_count(self, db):
-        """A fresh DB has both FTS indexes; optimize merges both."""
-        db.create_session(session_id="s1", source="cli")
-        db.append_message(session_id="s1", role="user", content="hello world")
-        assert db.optimize_fts() == 2
-
-    def test_optimize_preserves_search_and_snippet(self, db):
-        """Optimize is layout-only: MATCH results + snippets are unchanged."""
-        db.create_session(session_id="s1", source="cli")
-        for i in range(50):
-            db.append_message(
-                session_id="s1",
-                role="user",
-                content=f"needle alpha bravo charlie message {i}",
-            )
-        before = db.search_messages("needle")
-        n = db.optimize_fts()
-        assert n == 2
-        after = db.search_messages("needle")
-        assert len(after) == len(before)
-        assert len(after) > 0
-        # Snippet must still be populated (would be empty/None if the FTS
-        # content shadow were lost during optimize).
-        assert all(row.get("snippet") for row in after)
-        # IDs and snippets are identical before/after — pure layout change.
-        assert [r["id"] for r in after] == [r["id"] for r in before]
-        assert [r["snippet"] for r in after] == [r["snippet"] for r in before]
-
-    def test_optimize_skips_missing_trigram_table(self, db):
-        """When the trigram index is absent, optimize handles only the porter
-        index and does not raise."""
-        db.create_session(session_id="s1", source="cli")
-        db.append_message(session_id="s1", role="user", content="hello")
-        # Drop the trigram table + triggers to simulate a disabled/absent index.
-        with db._lock:
-            for trig in (
-                "messages_fts_trigram_insert",
-                "messages_fts_trigram_delete",
-                "messages_fts_trigram_update",
-            ):
-                db._conn.execute(f"DROP TRIGGER IF EXISTS {trig}")
-            db._conn.execute("DROP TABLE IF EXISTS messages_fts_trigram")
-        assert db._fts_table_exists("messages_fts_trigram") is False
-        assert db._fts_table_exists("messages_fts") is True
-        # Only the porter index remains -> 1 optimized, no error.
-        assert db.optimize_fts() == 1
-
-    def test_optimize_idempotent(self, db):
-        """Running optimize twice is safe (second pass is a no-op merge)."""
-        db.create_session(session_id="s1", source="cli")
-        db.append_message(session_id="s1", role="user", content="repeat me")
-        assert db.optimize_fts() == 2
-        assert db.optimize_fts() == 2
-        # Search still works after repeated optimization.
-        assert len(db.search_messages("repeat")) == 1
-
-
 class TestAutoMaintenance:
     def _make_old_ended(self, db, sid: str, days_old: int = 100):
         """Create a session that is ended and was started `days_old` days ago."""

website/docs/reference/optional-skills-catalog.md

@@ -31,9 +31,7 @@ hermes skills uninstall <skill-name>
 
 | Skill | Description |
 |-------|-------------|
-| [**antigravity-cli**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli) | Operate the Antigravity CLI (agy): plugins, auth, sandbox. |
 | [**blackbox**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox) | Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key. |
-| [**grok**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok) | Delegate coding to xAI Grok Build CLI (features, PRs). |
 | [**honcho**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho) | Configure and use Honcho memory with Hermes -- cross-session user modeling, multi-profile peer isolation, observation config, dialectic reasoning, session summaries, and context budget enforcement. Use when setting up Honcho, troubleshoo... |
 | [**openhands**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands) | Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). |
 

website/docs/user-guide/features/code-execution.md

@@ -219,6 +219,62 @@ terminal:
 
 See the [Security guide](/user-guide/security#environment-variable-passthrough) for full details.
 
+### `HERMES_*` variables in the child
+
+The child process receives only a small, fixed set of operational `HERMES_*`
+variables by exact name:
+
+- `HERMES_HOME`
+- `HERMES_PROFILE`
+- `HERMES_CONFIG`
+- `HERMES_ENV`
+
+(plus `HERMES_RPC_DIR` / `HERMES_RPC_SOCKET` / `TZ` / `HOME`, which Hermes
+injects explicitly so the RPC channel works).
+
+:::note Behavior change
+Earlier versions passed **any** variable whose name began with `HERMES_`
+through to the child. That broad prefix was removed for security hardening: it
+could leak `HERMES_*`-named configuration that doesn't match a secret substring
+(for example `HERMES_BASE_URL`, `HERMES_KANBAN_DB`, or a `HERMES_*_WEBHOOK`
+endpoint) into arbitrary sandboxed code.
+
+If an `execute_code` script — or a repo/plugin module it imports at import time
+— relied on a `HERMES_*` variable outside the four operational names above, it
+will now find that variable **unset** in the child. The drop is intentional,
+not a bug.
+:::
+
+**Workaround — opt the variable back in explicitly.** Both routes pass the
+variable through `execute_code` *and* `terminal` children, and neither weakens
+the secret-stripping guarantee (Hermes-managed provider credentials can never
+be re-allowed this way):
+
+1. **Per-machine, in `config.yaml`** — add the exact variable name to the
+   passthrough allowlist:
+
+   ```yaml
+   terminal:
+     env_passthrough:
+       - HERMES_KANBAN_DB
+       - HERMES_BASE_URL
+   ```
+
+2. **Per-skill, in the skill's frontmatter** — declare it so it is registered
+   automatically whenever that skill is loaded:
+
+   ```yaml
+   required_environment_variables:
+     - HERMES_KANBAN_DB
+   ```
+
+**Diagnosing it.** When the child drops one or more non-allowlisted `HERMES_*`
+variables, Hermes emits a one-line `debug` log naming them and pointing at the
+`env_passthrough` escape hatch. Run with debug logging (`hermes logs --level
+DEBUG`, or check `~/.hermes/logs/agent.log`) and look for
+`execute_code: dropped N non-allowlisted HERMES_* var(s)` if a script behaves
+as though a `HERMES_*` variable is missing.
+
 Hermes always writes the script and the auto-generated `hermes_tools.py` RPC stub into a temp staging directory that is cleaned up after execution. In `strict` mode the script also *runs* there; in `project` mode it runs in the session's working directory (the staging directory stays on `PYTHONPATH` so imports still resolve). The child process runs in its own process group so it can be cleanly killed on timeout or interruption.
 
 ## execute_code vs terminal

website/docs/user-guide/features/credential-pools.md

@@ -22,11 +22,8 @@ Your request
   → Pick key from pool (round_robin / least_used / fill_first / random)
   → Send to provider
   → 429 rate limit?
-      → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
-          → Rotate to next pool key immediately (no retry — the cap won't clear on retry)
-      → Generic / transient 429?
-          → Retry same key once (transient blip)
-          → Second 429 → rotate to next pool key
+      → Retry same key once (transient blip)
+      → Second 429 → rotate to next pool key
       → All keys exhausted → fallback_model (different provider)
   → 402 billing error?
       → Immediately rotate to next pool key (24h cooldown)

website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md

@@ -1,195 +0,0 @@
----
-title: "Antigravity Cli — Operate the Antigravity CLI (agy): plugins, auth, sandbox"
-sidebar_label: "Antigravity Cli"
-description: "Operate the Antigravity CLI (agy): plugins, auth, sandbox"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Antigravity Cli
-
-Operate the Antigravity CLI (agy): plugins, auth, sandbox.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/antigravity-cli` |
-| Path | `optional-skills/autonomous-ai-agents/antigravity-cli` |
-| Version | `0.1.0` |
-| Author | Tony Simons (asimons81), Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Coding-Agent`, `Antigravity`, `CLI`, `Auth`, `Plugins`, `Sandbox` |
-| Related skills | [`grok`](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Antigravity CLI (`agy`)
-
-Operator guide for the Antigravity CLI, invoked as `agy`. Run all `agy`
-commands through the Hermes `terminal` tool; inspect its config and logs with
-`read_file`. This skill is reference + procedure — it does not wrap a network
-API, so there is nothing to authenticate from Hermes itself.
-
-## When to Use
-
-- Installing, updating, or smoke-testing the `agy` binary
-- Driving non-interactive `agy --print` / `agy -p` one-shots
-- Debugging Antigravity auth, sandbox, permissions, or plugin state
-- Reading Antigravity settings, keybindings, conversations, or logs
-
-## Mental model
-
-Antigravity has two layers — keep them distinct or the guidance will be wrong:
-
-1. **Shell wrapper commands** — `agy help`, `agy install`, `agy plugin`,
-   `agy update`, `agy changelog`. Run these through the `terminal` tool.
-2. **Interactive in-session slash commands** — `/config`, `/permissions`,
-   `/skills`, `/agents`, etc. These only exist inside a running `agy` TUI
-   session, not on the shell wrapper.
-
-`agy help` shows the shell wrapper surface, NOT the in-session slash commands.
-
-## Prerequisites
-
-- The `agy` binary on PATH. Verify through the `terminal` tool:
-  `command -v agy && agy --version`.
-- No env vars or API keys required by this skill — Antigravity manages its own
-  auth via the OS keyring / browser sign-in (see Authentication below).
-
-## How to Run
-
-Invoke every `agy` command through the `terminal` tool. Examples:
-
-```
-terminal(command="agy --version")
-terminal(command="agy help")
-terminal(command="agy plugin list")
-terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project")
-```
-
-For an interactive multi-turn TUI session, launch `agy` with `pty=true` (and
-tmux for capture/monitoring), the same pattern the `codex` / `claude-code`
-skills use. For one-shot smoke tests and scripted prompts, prefer
-`agy --print` (non-interactive).
-
-To inspect Antigravity's own files, use `read_file` on the paths under Core
-paths below — do not `cat` them through the terminal.
-
-## Core paths
-
-- Binary / entrypoint: `agy`
-- App data dir: `~/.gemini/antigravity-cli/`
-- Settings file: `~/.gemini/antigravity-cli/settings.json`
-- Keybindings file: `~/.gemini/antigravity-cli/keybindings.json`
-- Logs: `~/.gemini/antigravity-cli/log/cli-*.log`
-- Conversations: `~/.gemini/antigravity-cli/conversations/`
-- Brain artifacts: `~/.gemini/antigravity-cli/brain/`
-- History: `~/.gemini/antigravity-cli/history.jsonl`
-- Plugin staging: `~/.gemini/antigravity-cli/plugins/<plugin_name>/`
-
-## Quick Reference
-
-### Wrapper commands
-- `agy changelog`
-- `agy help`
-- `agy install`
-- `agy plugin` / `agy plugins`
-- `agy update`
-
-### Useful flags
-- `--add-dir`
-- `--continue` / `-c`
-- `--conversation`
-- `--dangerously-skip-permissions`
-- `--print` / `-p`
-- `--print-timeout`
-- `--prompt`
-- `--prompt-interactive` / `-i`
-- `--sandbox`
-- `--log-file`
-- `--version`
-
-### Plugin subcommands (`agy plugin --help`)
-- `list`, `import [source]`, `install <target>`, `uninstall <name>`,
-  `enable <name>`, `disable <name>`, `validate [path]`, `link <mp> <target>`,
-  `help`
-
-### Install flags (`agy install --help`)
-- `--dir`, `--skip-aliases`, `--skip-path`
-
-### In-session slash commands
-- **Conversation control:** `/resume` (`/switch`), `/rewind` (`/undo`),
-  `/rename <name>`, `/clear`, `/fork`, `/reset`, `/new`
-- **Settings & tools:** `/config`, `/settings`, `/permissions`, `/model`,
-  `/keybindings`, `/statusline`, `/tasks`, `/skills`, `/mcp`, `/open <path>`,
-  `/usage`, `/logout`, `/agents`
-- **Prompt helpers:** `@` path autocomplete, `esc esc` clears the prompt (when
-  not streaming), `!` runs a terminal command directly, `?` opens help
-
-## Settings and permissions
-
-### Common settings keys (`settings.json`)
-- `allowNonWorkspaceAccess`
-- `colorScheme`
-- `permissions.allow`
-- `trustedWorkspaces`
-
-### Permission modes
-`request-review`, `always-proceed`, `strict`, `proceed-in-sandbox`.
-
-### Sandbox behavior
-- `enableTerminalSandbox` is a boolean in `settings.json`; default `false`.
-- Launch-time overrides (`--sandbox`, `--dangerously-skip-permissions`) can
-  supersede persistent settings for the current session.
-
-## Authentication behavior
-
-- The CLI tries the OS secure keyring first.
-- With no saved session, it falls back to browser-based Google sign-in.
-- Locally it opens the default browser; over SSH it prints an authorization URL
-  and expects the auth code pasted back.
-- `/logout` removes saved credentials.
-
-## Plugins
-
-- Plugins stage under `~/.gemini/antigravity-cli/plugins/<plugin_name>/`.
-- They can bundle skills, agents, rules, MCP servers, and hooks.
-- `agy plugin list` returning no imported plugins is a valid empty state.
-
-## Pitfalls
-
-- `agy help` shows wrapper commands, not interactive slash commands.
-- `agy --version` is the safe non-interactive version check; `agy version` is
-  interactive and can fail without a real TTY.
-- First place to look for failures: `~/.gemini/antigravity-cli/log/cli-*.log`
-  (read with `read_file`).
-- Don't confuse persistent JSON settings with launch-time overrides.
-- `~/.gemini/antigravity-cli/bin/agentapi` is a thin wrapper to `agy agentapi`.
-- On WSL, token storage is file-based, so auth issues are usually local-file /
-  session-state problems, not browser-only problems.
-- Workspace identity can depend on launch directory and the `.antigravitycli`
-  project marker.
-
-## Verification
-
-Confirm the install is real and usable, all through the `terminal` tool (read
-files with `read_file`):
-
-1. `terminal(command="command -v agy")`
-2. `terminal(command="agy --version")`
-3. `terminal(command="agy help")`
-4. `terminal(command="agy plugin list")`
-5. `read_file` on `~/.gemini/antigravity-cli/settings.json`
-6. `read_file` on the latest `~/.gemini/antigravity-cli/log/cli-*.log`
-7. If needed, `read_file` on `~/.gemini/antigravity-cli/keybindings.json`
-
-## Support files
-
-- `references/cli-docs.md` — condensed notes from the getting-started, usage,
-  and features docs.

website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md

@@ -1,319 +0,0 @@
----
-title: "Grok — Delegate coding to xAI Grok Build CLI (features, PRs)"
-sidebar_label: "Grok"
-description: "Delegate coding to xAI Grok Build CLI (features, PRs)"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Grok
-
-Delegate coding to xAI Grok Build CLI (features, PRs).
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/grok` |
-| Path | `optional-skills/autonomous-ai-agents/grok` |
-| Version | `0.1.0` |
-| Author | Matt Maximo (MattMaximo), Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Coding-Agent`, `Grok`, `xAI`, `Code-Review`, `Refactoring`, `Automation` |
-| Related skills | [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Grok Build CLI — Hermes Orchestration Guide
-
-Delegate coding tasks to [Grok Build](https://docs.x.ai/build/overview) (xAI's
-autonomous coding agent CLI, the `grok` command) via the Hermes terminal. Grok
-can read files, write code, run shell commands, spawn subagents, and manage git
-workflows. It runs three ways: an interactive TUI, **headless** (`-p`), and as
-an **ACP agent** over JSON-RPC.
-
-This is the third sibling to `codex` and `claude-code`. The orchestration
-pattern is nearly identical — **prefer headless `-p` for one-shots**, use a PTY
-for interactive sessions.
-
-## When to use
-
-- Building features
-- Refactoring
-- PR reviews
-- Batch issue fixing
-- Any task where you'd otherwise reach for Codex / Claude Code but want Grok
-
-## Prerequisites
-
-- **Install (preferred):** `npm install -g @xai-official/grok`
-  - The official installer `curl -fsSL https://x.ai/cli/install.sh | bash` also
-    works, but the `x.ai` host is Cloudflare-walled in some environments. The
-    npm path avoids that dependency entirely.
-- **Auth — SuperGrok / X Premium+ subscription (primary path):**
-  - Run `grok login` once → opens a browser for OAuth → token cached in
-    `~/.grok/auth.json`. This uses your **SuperGrok or X Premium+** subscription
-    (no per-token API billing).
-  - Check sign-in state by looking for `~/.grok/auth.json`, or run a cheap
-    headless smoke test: `grok --no-auto-update -p "Say ok."`
-  - In the TUI, `/logout` signs out and `/login` (or relaunching) signs back in.
-- **No git repo required** — unlike Codex, Grok runs fine outside a git
-  directory (good for scratch/throwaway tasks).
-- **Claude Code / AGENTS.md compatible with zero config** — Grok auto-reads
-  `CLAUDE.md`, `.claude/` (skills, agents, MCPs, hooks, rules), and the
-  `AGENTS.md` family. Existing project context just works.
-
-> **API-key fallback (not the default for this user):** Grok also supports
-> setting the `XAI_API_KEY` environment variable for pay-as-you-go billing
-> via `api.x.ai`. Only use
-> this if `grok login` / SuperGrok auth is unavailable. The subscription path
-> (`grok login`) is the intended setup here.
-
-## Two Orchestration Modes
-
-### Mode 1: Headless (`-p`) — Non-Interactive (PREFERRED)
-
-Runs a one-shot task, prints the result, and exits. No PTY, no interactive
-dialogs to navigate. This is the cleanest integration path — the analog of
-`claude -p` and `codex exec`.
-
-```
-terminal(command="grok --no-auto-update -p 'Add a dark mode toggle to settings'", workdir="/path/to/project", timeout=180)
-```
-
-Always pass `--no-auto-update` in automation to skip background update checks.
-
-**When to use headless:**
-- One-shot coding tasks (fix a bug, add a feature, refactor)
-- CI/CD automation and scripting
-- Structured output parsing with `--output-format json`
-- Any task that doesn't need multi-turn conversation
-
-### Mode 2: Interactive PTY — Multi-Turn TUI Sessions
-
-The TUI is a fullscreen, mouse-interactive app. Drive it with `pty=true`. For
-robust monitoring/input use tmux (same pattern as the `claude-code` skill).
-
-```
-# Launch in a tmux session for capture-pane monitoring
-terminal(command="tmux new-session -d -s grok-work -x 140 -y 40")
-terminal(command="tmux send-keys -t grok-work 'cd /path/to/project && grok' Enter")
-
-# Wait for startup, then send a task
-terminal(command="sleep 5 && tmux send-keys -t grok-work 'Refactor the auth module to use JWT' Enter")
-
-# Monitor progress
-terminal(command="sleep 15 && tmux capture-pane -t grok-work -p -S -50")
-
-# Exit when done
-terminal(command="tmux send-keys -t grok-work '/quit' Enter && sleep 1 && tmux kill-session -t grok-work")
-```
-
-**Tip for headless-but-inline output:** if you want TUI-style output without the
-fullscreen alt-screen takeover (e.g. for cleaner logs), add `--no-alt-screen`.
-For pure automation, headless `-p` is still cleaner than the TUI.
-
-## Headless Deep Dive
-
-### Common Flags
-
-| Flag | Effect |
-|------|--------|
-| `-p, --single <PROMPT>` | Send one prompt, run headless, exit |
-| `-m, --model <MODEL>` | Choose a model |
-| `-s, --session-id <ID>` | Create or resume a named headless session |
-| `-r, --resume <ID>` | Resume an existing session |
-| `-c, --continue` | Continue the most recent session in the current directory |
-| `--cwd <PATH>` | Set the working directory |
-| `--output-format <FMT>` | `plain` (default), `json`, or `streaming-json` |
-| `--always-approve` | Auto-approve all tool executions (the `--full-auto` / `--yolo` equivalent) |
-| `--no-alt-screen` | Run inline, no fullscreen TUI takeover |
-| `--no-auto-update` | Skip background update checks (use in all automation) |
-
-### Output Formats
-
-- `plain` — human-readable text (default)
-- `json` — one JSON object at the end of the run (parse the result cleanly)
-- `streaming-json` — newline-delimited JSON events as they arrive
-
-```
-# Structured result for parsing
-terminal(command="grok --no-auto-update -p 'List all TODO comments in src/' --output-format json", workdir="/project", timeout=120)
-
-# Auto-approve for autonomous building
-terminal(command="grok --no-auto-update --always-approve -p 'Refactor the database layer and run the tests'", workdir="/project", timeout=300)
-```
-
-### Background Mode (Long Tasks)
-
-```
-# Start headless in background
-terminal(command="grok --no-auto-update --always-approve -p 'Refactor the auth module'", workdir="/project", background=true, notify_on_complete=true)
-# Returns session_id
-
-# Monitor
-process(action="poll", session_id="<id>")
-process(action="log", session_id="<id>")
-
-# Kill if needed
-process(action="kill", session_id="<id>")
-```
-
-For an interactive (TUI) background session, use `pty=true` + tmux and monitor
-with `tmux capture-pane`, exactly like the `claude-code` / `codex` skills.
-
-### Session Continuation
-
-```
-# Start a named session
-terminal(command="grok --no-auto-update -s refactor-db -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)
-
-# Resume it later
-terminal(command="grok --no-auto-update -r refactor-db -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)
-
-# Or continue the most recent session in this directory
-terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60)
-```
-
-## Read-Only Audit → Markdown Note Pattern
-
-To have Grok review local artifacts and return a clean markdown note (for
-Obsidian or a repo) without mutating anything:
-
-1. Prepare stable input files first with Hermes tools (`read_file`,
-   `write_file`). Snapshot only the relevant context into a temp file rather
-   than dumping raw paths.
-2. Run Grok headless **without** `--always-approve` so it cannot auto-write, and
-   demand `markdown only, no preamble`.
-3. Save Grok's stdout straight into the destination note with `write_file()`.
-
-```
-grok --no-auto-update -p "Read /tmp/current.md and /tmp/inventory.md. Produce markdown only, no preamble. Output a clean note titled 'Cleanup Review'." --output-format plain
-```
-
-**Pitfall (same as Claude Code):** for document rewrites, a loose "rewrite this"
-prompt may return a change summary instead of the full file. Instead: pipe the
-file in, and demand `Return ONLY the full revised markdown document. No intro,
-no explanation, no code fences. Start immediately with '# Title'.` Verify the
-first lines with `read_file()` before overwriting the destination.
-
-## PR Review Patterns
-
-### Quick Review (Headless)
-
-```
-terminal(command="cd /path/to/repo && git diff main...feature-branch | grok --no-auto-update -p 'Review this diff for bugs, security issues, and style problems. Be thorough.'", timeout=120)
-```
-
-### Clone-to-temp Review (safe, no repo mutation)
-
-```
-terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && grok --no-auto-update -p 'Review the changes vs origin/main. Check bugs, security, race conditions, missing tests.'", pty=true, timeout=300)
-```
-
-### Post the review
-
-```
-terminal(command="gh pr comment 42 --body '<review text>'", workdir="/path/to/repo")
-```
-
-## Parallel Issue Fixing with Worktrees
-
-```
-# Create worktrees
-terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
-terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
-
-# Launch Grok headless in each (background)
-terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, notify_on_complete=true)
-terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, notify_on_complete=true)
-
-# Monitor
-process(action="list")
-
-# After completion: push and open PRs
-terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
-terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")
-
-# Cleanup
-terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
-```
-
-## Useful Subcommands & TUI Commands
-
-| Command | Purpose |
-|---------|---------|
-| `grok` | Start the interactive TUI |
-| `grok -p "query"` | Headless one-shot |
-| `grok login` / `grok logout` | Sign in / out (SuperGrok / X Premium+ OAuth) |
-| `grok inspect` | Show what Grok discovered in cwd: config sources, instructions, skills, plugins, hooks, MCP servers |
-| `grok agent stdio` | Run as an ACP agent over JSON-RPC (for IDE/tool integration) |
-| `grok update` | Update the CLI (needs the `x.ai` host; skip in automation) |
-
-TUI slash commands (interactive only): `/model <name>`, `/always-approve`,
-`/plan`, `/context`, `/compact`, `/resume`, `/sessions`, `/fork`, `/usage`,
-`/quit`. `Shift+Tab` cycles session modes (including Plan mode, which blocks
-write tools except the session plan file).
-
-## Config (`~/.grok/config.toml`)
-
-```toml
-[cli]
-auto_update = false          # skip background update checks persistently
-
-[ui]
-permission_mode = "ask"      # or "always-approve" to skip tool prompts by default
-
-[models]
-default = "grok-build-0.1"
-```
-
-Put global preferences in `~/.grok/config.toml` (not project-scoped
-`.grok/config.toml`). `permission_mode` supersedes the legacy `approval_mode` /
-`yolo = true` keys.
-
-## Pitfalls & Gotchas
-
-1. **Auth is subscription-gated.** `grok login` requires a SuperGrok or X
-   Premium+ subscription. If login fails or there's no `~/.grok/auth.json`,
-   confirm the subscription is active before falling back to `XAI_API_KEY`.
-2. **Don't conflate Hermes' xAI auth with the `grok` CLI's auth.** Hermes'
-   `x_search` runs on its own xAI OAuth; the standalone `grok` CLI has a
-   separate token in `~/.grok/auth.json`. A working `x_search` does NOT mean
-   `grok` is logged in.
-3. **Always pass `--no-auto-update` in automation** — otherwise Grok phones home
-   for update checks (and `x.ai`/`storage.googleapis.com` may be unreachable).
-4. **Prefer npm install over the curl installer** — `npm install -g
-   @xai-official/grok` avoids the Cloudflare-walled `x.ai` host.
-5. **`--always-approve` is the autonomous-build switch.** Without it, headless
-   runs may stall waiting on tool-approval prompts. Omit it deliberately for
-   read-only review/audit work so Grok can't mutate files.
-6. **Headless `-p` skips TUI dialogs**; the TUI needs `pty=true` (+ tmux for
-   monitoring), just like Claude Code.
-7. **Use `--no-alt-screen`** if you run the TUI inline and the fullscreen
-   alt-screen takeover garbles captured output.
-8. **No git repo needed**, but for PR/commit workflows you still want one — use
-   `mktemp -d && git init` for scratch commit tasks.
-9. **Clean up tmux sessions** with `tmux kill-session -t <name>` when done.
-
-## Rules for Hermes Agents
-
-1. **Prefer headless `-p`** for single tasks — cleanest integration, structured
-   output via `--output-format json`.
-2. **Always set `workdir`** (or `--cwd`) so Grok targets the right project.
-3. **Pass `--no-auto-update`** in every automated invocation.
-4. **Use `--always-approve` only when Grok should write autonomously**; omit it
-   for read-only reviews and audits.
-5. **Background long tasks** with `background=true, notify_on_complete=true` and
-   monitor via the `process` tool.
-6. **Use tmux for multi-turn interactive work** and monitor with
-   `tmux capture-pane -t <session> -p -S -50`.
-7. **Verify auth before relying on it** — check `~/.grok/auth.json` or run a
-   cheap `grok -p "Say ok."` smoke test; don't assume Hermes' xAI auth carries
-   over.
-8. **Report results to the user** — summarize what Grok changed and what's left.

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/credential-pools.md

@@ -18,11 +18,8 @@ Your request
   → Pick key from pool (round_robin / least_used / fill_first / random)
   → Send to provider
   → 429 rate limit?
-      → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
-          → Rotate to next pool key immediately (no retry — the cap won't clear on retry)
-      → Generic / transient 429?
-          → Retry same key once (transient blip)
-          → Second 429 → rotate to next pool key
+      → Retry same key once (transient blip)
+      → Second 429 → rotate to next pool key
       → All keys exhausted → fallback_model (different provider)
   → 402 billing error?
       → Immediately rotate to next pool key (24h cooldown)

website/sidebars.ts

@@ -389,9 +389,7 @@ const sidebars: SidebarsConfig = {
                   key: 'skills-optional-autonomous-ai-agents',
                   collapsed: true,
                   items: [
-                    'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli',
                     'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox',
-                    'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok',
                     'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho',
                     'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands',
                   ],

website/static/api/model-catalog.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "updated_at": "2026-05-29T11:20:16Z",
+  "updated_at": "2026-05-29T06:55:44Z",
   "metadata": {
     "source": "hermes-agent repo",
     "docs": "https://hermes-agent.nousresearch.com/docs/reference/model-catalog"
@@ -81,7 +81,7 @@
           "description": ""
         },
         {
-          "id": "google/gemini-3.5-flash",
+          "id": "google/gemini-3-flash-preview",
           "description": ""
         },
         {
@@ -198,7 +198,7 @@
           "id": "google/gemini-3-pro-preview"
         },
         {
-          "id": "google/gemini-3.5-flash"
+          "id": "google/gemini-3-flash-preview"
         },
         {
           "id": "google/gemini-3.1-pro-preview"