Initial commit: AirCoding V1.0.0 Alpha architecture baseline

Complete architecture document set with multi-model review remediation:
- Frozen interface contracts, runtime semantics, DB schemas
- Event/tool/error/provider registries
- Scheduler and main agent state machines
- C4 module/code views, solution architecture, baseline V1
- Multi-model review reports and joint assessment
- Phase-gate remediation complete (P0/P1/P2/UX resolved)
- Implementation plan with T-000A through T-045
- Reference folders kept as placeholders only

reference/anthropic-skills/.claude-plugin/marketplace.json

@@ -0,0 +1,55 @@
+{
+  "name": "anthropic-agent-skills",
+  "owner": {
+    "name": "Keith Lazuka",
+    "email": "klazuka@anthropic.com"
+  },
+  "metadata": {
+    "description": "Anthropic example skills",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "document-skills",
+      "description": "Collection of document processing suite including Excel, Word, PowerPoint, and PDF capabilities",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/xlsx",
+        "./skills/docx",
+        "./skills/pptx",
+        "./skills/pdf"
+      ]
+    },
+    {
+      "name": "example-skills",
+      "description": "Collection of example skills demonstrating various capabilities including skill creation, MCP building, visual design, algorithmic art, internal communications, web testing, artifact building, Slack GIFs, and theme styling",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/algorithmic-art",
+        "./skills/brand-guidelines",
+        "./skills/canvas-design",
+        "./skills/doc-coauthoring",
+        "./skills/frontend-design",
+        "./skills/internal-comms",
+        "./skills/mcp-builder",
+        "./skills/skill-creator",
+        "./skills/slack-gif-creator",
+        "./skills/theme-factory",
+        "./skills/web-artifacts-builder",
+        "./skills/webapp-testing"
+      ]
+    }
+    ,
+    {
+      "name": "claude-api",
+      "description": "Claude API and SDK documentation skill for building LLM-powered applications",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/claude-api"
+      ]
+    }
+  ]
+}

reference/anthropic-skills/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+__pycache__/
+.idea/
+.vscode/
+

reference/asciinema-3.2.0/.cargo/config.toml

@@ -0,0 +1,2 @@
+[env]
+RUST_TEST_THREADS = "1"

reference/asciinema-3.2.0/.gitattributes

@@ -0,0 +1 @@
+assets/asciinema-player.* linguist-vendored

reference/asciinema-3.2.0/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,101 @@
+name: Bug Report
+description: Report a bug to help improve asciinema CLI
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **This is a bug tracker for asciinema CLI (the recorder).**
+        
+        - If your issue is with the JavaScript player or server, please open an issue in the related repository
+        - If you're experiencing issues with asciinema.org, contact admin@asciinema.org
+        - For feature requests, questions, and discussions, use the [forum](https://discourse.asciinema.org) or [GitHub discussions](https://github.com/orgs/asciinema/discussions)
+        
+        Thanks for taking the time to report a bug! Please fill out the sections below.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-submission checks
+      description: Please confirm the following before submitting your bug report
+      options:
+        - label: I have searched existing issues and this bug has not been reported yet
+          required: true
+        - label: This is a bug report for asciinema CLI (not player or server)
+          required: true
+
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction-steps
+    attributes:
+      label: Steps to Reproduce
+      description: Provide detailed steps to reproduce the behavior
+      placeholder: |
+        1. Run command `asciinema ...`
+        2. Do action '...'
+        3. Observe error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.
+      placeholder: What should have happened instead?
+    validations:
+      required: true
+
+  - type: input
+    id: os-version
+    attributes:
+      label: Operating System
+      description: Which OS and version are you using?
+      placeholder: e.g., Ubuntu 24.04, macOS 14.0, Fedora 39
+    validations:
+      required: true
+
+  - type: input
+    id: cli-version
+    attributes:
+      label: asciinema CLI Version
+      description: What version of asciinema CLI are you using? Run `asciinema --version` to check.
+      placeholder: e.g., 2.4.0
+    validations:
+      required: true
+
+  - type: dropdown
+    id: installation-method
+    attributes:
+      label: Installation Method
+      description: How did you install asciinema CLI?
+      options:
+        - Package manager (apt, yum, brew, etc.)
+        - pip/pipx
+        - Built from source
+        - Downloaded binary
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: terminal-info
+    attributes:
+      label: Terminal Information
+      description: What terminal emulator and shell are you using?
+      placeholder: |
+        Terminal: e.g., GNOME Terminal, iTerm2, Ghostty
+        Shell: e.g., bash 5.1, zsh 5.8, fish 3.6
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or relevant information about the problem here.

reference/asciinema-3.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Forum
+    url: https://discourse.asciinema.org/
+    about: Ideas, feature requests, help requests, questions and general discussions should be posted here.
+  - name: GitHub discussions
+    url: https://github.com/orgs/asciinema/discussions
+    about: Ideas, feature requests, help requests, questions and general discussions should be posted here.

reference/asciinema-3.2.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: ["develop"]
+  pull_request:
+    branches: ["develop"]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        rust: [default, msrv]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install Nix
+        uses: nixbuild/nix-quick-install-action@v34
+
+      - name: Setup Nix cache
+        uses: nix-community/cache-nix-action@v6
+        with:
+          primary-key: nix-${{ runner.os }}-${{ matrix.rust }}-${{ hashFiles('**/*.nix', '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ matrix.rust }}-
+
+      - name: Build
+        run: nix develop .#${{ matrix.rust }} --command cargo build --verbose
+
+      - name: Run cargo tests
+        run: nix develop .#${{ matrix.rust }} --command cargo test --verbose
+
+      - name: Run integration tests
+        run: nix develop .#${{ matrix.rust }} --command tests/integration.sh
+
+      - name: Check formatting
+        run: nix develop .#${{ matrix.rust }} --command cargo fmt --check
+
+      - name: Lint with clippy
+        run: nix develop .#${{ matrix.rust }} --command cargo clippy

reference/asciinema-3.2.0/.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release
+
+permissions:
+  contents: write
+
+on:
+  push:
+    tags:
+      - v[0-9]+.*
+
+jobs:
+  create-release:
+    name: Create GH release draft
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Create the release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release create ${{ github.ref_name }} --draft --verify-tag --title ${{ github.ref_name }}
+
+  upload-binary:
+    needs: create-release
+    name: ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            use-cross: false
+
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-musl
+            use-cross: false
+
+          - os: ubuntu-latest
+            target: aarch64-unknown-linux-gnu
+            use-cross: true
+
+          - os: macos-latest
+            target: x86_64-apple-darwin
+            use-cross: false
+
+          - os: macos-latest
+            target: aarch64-apple-darwin
+            use-cross: false
+
+    env:
+      CARGO: cargo
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Install cross
+        if: matrix.use-cross
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cross
+
+      - name: Overwrite build command env variable
+        if: matrix.use-cross
+        shell: bash
+        run: echo "CARGO=cross" >> $GITHUB_ENV
+
+      - name: Install build deps
+        shell: bash
+        run: |
+          if [[ ${{ matrix.target }} == x86_64-unknown-linux-musl ]]; then
+              sudo apt-get update
+              sudo apt-get install -y musl-tools
+          fi
+
+      - name: Build release binary
+        run: ${{ env.CARGO }} build --release --locked --target ${{ matrix.target }}
+
+      - name: Upload the binary to the release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mv target/${{ matrix.target }}/release/asciinema target/release/asciinema-${{ matrix.target }}
+          gh release upload ${{ github.ref_name }} target/release/asciinema-${{ matrix.target }}

reference/asciinema-3.2.0/.gitignore

@@ -0,0 +1,4 @@
+target/
+.envrc
+.direnv
+/result

reference/atuin-18.16.1/.atuin/skills/release/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: release
+description: >
+  Orchestrate a multi-step Atuin CLI release — version bumping, changelog
+  generation, PR creation, tagging, and crates.io publishing. Invoke with
+  /release or /release <version>.
+disable-model-invocation: true
+argument-hint: [version]
+---
+
+# Atuin CLI Release
+
+You are orchestrating a release of the Atuin CLI. Follow the steps below
+**in order**, pausing at each checkpoint for user confirmation. Do not skip
+steps or combine them.
+
+## Current State
+
+- Workspace version: !`sed -n '/^\[workspace\.package\]/,/^\[/s/^version = "\(.*\)"/\1/p' Cargo.toml`
+- Latest tag: !`git describe --tags --abbrev=0 2>/dev/null || echo "none"`
+- Suggested next version: !`git-cliff --bumped-version 2>/dev/null | sed 's/^v//' || echo "(unknown)"`
+
+---
+
+## Step 1 — Check Dependencies
+
+Verify these tools are installed: `git`, `gsed`, `cargo`, `gh`, `git-cliff`.
+
+Use `command -v` for each. If any are missing, report which ones and stop.
+
+Remember to use `gsed`, or else macOS flags to regular `sed`, later in the workflow.
+
+---
+
+## Step 2 — Determine Version
+
+The target version may be provided as `$ARGUMENTS`. If it's empty, use
+AskUserQuestion to ask for the new version (show the current state above
+for reference).
+
+After determining the version:
+- If it contains a `-` (e.g. `18.15.0-beta.1`), it is a **prerelease**.
+  Note this — it affects changelog and publish behavior later.
+- Show the user: `current → new` and whether it's a prerelease.
+- **Checkpoint:** Ask the user to confirm before proceeding.
+
+---
+
+## Step 3 — Set Up Working Directory
+
+Clone a fresh copy into a temp directory:
+
+```bash
+WORKDIR=$(mktemp -d)
+git clone git@github.com:atuinsh/atuin.git "$WORKDIR"
+```
+
+Print the working directory path so the user can find it if needed.
+
+NOTE:
+ALL subsequent Bash commands run from `$WORKDIR`.
+
+---
+
+## Step 4 — Create Branch & Update Versions
+
+1. Create a release branch named after the version (no `v` prefix):
+   `git checkout -b <VERSION>`
+
+2. Replace the old version with the new one in all `Cargo.toml` files.
+   **Escape dots** in the old version so sed treats them literally:
+
+   ```bash
+   VERSION_PATTERN="${OLD_VERSION//./\\.}"
+   find . -type f -name 'Cargo.toml' -not -path './.git/*' \
+       -exec gsed -i "s/$VERSION_PATTERN/$NEW_VERSION/g" {} \;
+   ```
+
+3. Run `cargo check` to update `Cargo.lock`.
+
+4. Show `git diff --stat` and the version-related lines from the diff:
+   ```bash
+   git diff --unified=0 -- '*.toml' | grep '^\+.*version' | grep -vF '+++'
+   ```
+   Remember to use macOS grep arguments on macOS systems.
+
+5. Verify the workspace version was actually updated by re-reading it
+   from `Cargo.toml`.
+
+6. **Checkpoint:** Show the diff summary and ask the user to confirm the
+   version changes look correct.
+
+---
+
+## Step 5 — Update Changelog
+
+The changelog strategy differs for prereleases vs stable releases:
+
+- **Prerelease:** Maintain a running `## [unreleased]` section containing
+  all changes since the last stable release. Use:
+  `git-cliff --unreleased --strip all`
+  (cliff.toml's `ignore_tags` already ignores beta/alpha tags, so
+  `--unreleased` spans back to the last stable release automatically.)
+
+- **Stable release:** Generate a versioned entry that replaces the
+  `[unreleased]` section. Use:
+  `git-cliff --unreleased --tag "v<VERSION>" --strip all`
+
+Then update `CHANGELOG.md`:
+
+1. If an existing `## [unreleased]` or `## [Unreleased]` section exists,
+   **remove it entirely** (the heading and all content up to the next
+   `## ` heading).
+
+2. Insert the new entry before the first existing `## ` version heading.
+
+3. **Checkpoint:** Read and display the new changelog entry to the user.
+   Ask if they want any edits. If so, make the requested changes using
+   the Edit tool. Repeat until they're satisfied.
+
+---
+
+## Step 6 — Commit & Push
+
+Stage all changes and commit:
+
+```
+chore(release): prepare for release <VERSION>
+```
+
+Push the branch with `--set-upstream origin`.
+
+---
+
+## Step 7 — Create PR & Wait for Merge
+
+### Create the PR
+
+Extract the changelog entry body (everything between the new `## ` heading
+and the next one) for the PR description.
+
+For prereleases, the heading to match is `## [unreleased]`.
+For stable releases, it's `## <VERSION>` (escape dots in the awk pattern).
+
+Create the PR:
+```bash
+gh pr create \
+    --title "chore(release): prepare for release <VERSION>" \
+    --body "<body with changelog>" \
+    --repo atuinsh/atuin
+    --draft
+```
+
+Show the PR URL to the user. Tell the user to go review and merge the PR.
+
+When the user reports the PR is merged, proceed to the next step.
+
+---
+
+## Step 8 — Tag Release
+
+Back in the working directory:
+
+```bash
+git checkout main
+git pull
+git tag "v<VERSION>"
+git push --tags
+```
+
+Tell the user the tag was pushed and the release CI workflow has been
+triggered.
+
+---
+
+## Step 9 — Publish to crates.io
+
+**If this is a prerelease**, skip this step entirely and tell the user.
+
+**If this is a stable release**, ask the user whether to publish.
+
+If yes, publish each crate **in dependency order** using `--no-verify`
+(the code already passed CI, and verification fails when crates.io
+hasn't indexed a freshly-published dependency yet):
+
+```
+atuin-common, atuin-client, atuin-ai, atuin-dotfiles, atuin-history,
+atuin-nucleo/matcher, atuin-nucleo, atuin-daemon, atuin-kv,
+atuin-scripts, atuin-server-database, atuin-server-postgres,
+atuin-server-sqlite, atuin-server, atuin-pty-proxy, atuin
+```
+
+For each crate, run from `crates/<name>`:
+```bash
+cargo publish --no-verify 2>&1
+```
+
+If it fails with "already uploaded", report it as a skip (not an error) —
+some crates like `atuin-nucleo` are versioned independently and may
+already be published at their current version.
+
+If it fails for any other reason, stop and report the error.
+
+---
+
+## Completion
+
+Summarize what was done:
+- Version released
+- PR URL
+- Tag name
+- Which crates were published (if any)
+- Working directory path and how to clean it up (`rm -rf`)

reference/atuin-18.16.1/.cargo/audit.toml

@@ -0,0 +1,9 @@
+[advisories]
+ignore = [
+  # This is a vuln on RSA. RSA is in our lockfile, but not in cargo-tree. 
+  # It is a issue with sqlx/cargo, and does not affect Atuin.
+  # See:
+  # - https://github.com/launchbadge/sqlx/issues/3211
+  # - https://github.com/rust-lang/cargo/issues/10801
+  "RUSTSEC-2023-0071"
+]

reference/atuin-18.16.1/.claude/skills/hunk/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: hunk-review
+description: Interacts with live Hunk diff review sessions via CLI. Inspects review focus, navigates files and hunks, reloads session contents, and adds inline review comments. Use when the user has a Hunk session running or wants to review diffs interactively.
+---
+
+# Hunk Review
+
+Hunk is an interactive terminal diff viewer. The TUI is for the user -- do NOT run `hunk diff`, `hunk show`, or other interactive commands directly. Use `hunk session *` CLI commands to inspect and control live sessions through the local daemon.
+
+If no session exists, ask the user to launch Hunk in their terminal first.
+
+## Workflow
+
+```text
+1. hunk session list                                    # find live sessions
+2. hunk session get --repo .                            # inspect path / repo / source
+3. hunk session review --repo . --json                  # inspect file/hunk structure first
+4. hunk session review --repo . --include-patch --json  # opt into raw diff text only when needed
+5. hunk session context --repo .                        # check current focus when needed
+6. hunk session navigate ...                            # move to the right place
+7. hunk session reload -- <command>                     # swap contents if needed
+8. hunk session comment add ...                         # leave one review note
+9. hunk session comment apply ...                       # apply many agent notes in one stdin batch
+```
+
+## Session selection
+
+Most session commands accept:
+
+- `--repo <path>` -- match the live session by its current loaded repo root (most common)
+- `<session-id>` -- match by exact ID (use when multiple sessions share a repo)
+- If only one session exists, it auto-resolves
+
+`reload` also supports:
+
+- `--session-path <path>` -- match the live Hunk window by its current working directory
+- `--source <path>` -- load the replacement `diff` / `show` command from a different directory
+
+Use `--source` only for advanced reloads where the live session you want to control is not already associated with the checkout you want to load next. For a normal worktree session, prefer selecting it directly with `--repo /path/to/worktree`.
+
+## Commands
+
+### Inspect
+
+```bash
+hunk session list [--json]
+hunk session get (--repo . | <id>) [--json]
+hunk session context (--repo . | <id>) [--json]
+hunk session review (--repo . | <id>) [--json] [--include-patch]
+```
+
+- `get` shows the session `Path`, `Repo`, and `Source`, which helps when choosing between `--repo` and `--session-path`
+- `Repo` is what `--repo` matches; `Path` is what `--session-path` matches
+- `review --json` returns file and hunk structure by default; add `--include-patch` only when a caller truly needs raw unified diff text
+
+### Navigate
+
+Absolute navigation requires `--file` and exactly one of `--hunk`, `--new-line`, or `--old-line`:
+
+```bash
+hunk session navigate --repo . --file src/App.tsx --hunk 2
+hunk session navigate --repo . --file src/App.tsx --new-line 372
+hunk session navigate --repo . --file src/App.tsx --old-line 355
+```
+
+Relative comment navigation jumps between annotated hunks and does not require `--file`:
+
+```bash
+hunk session navigate --repo . --next-comment
+hunk session navigate --repo . --prev-comment
+```
+
+- `--hunk <n>` is 1-based
+- `--new-line` / `--old-line` are 1-based line numbers on that diff side
+- Use either `--next-comment` or `--prev-comment`, not both
+
+### Reload
+
+Swaps the live session's contents. Pass a Hunk review command after `--`:
+
+```bash
+hunk session reload --repo . -- diff
+hunk session reload --repo . -- diff main...feature -- src/ui
+hunk session reload --repo . -- show HEAD~1
+hunk session reload --repo . -- show HEAD~1 -- README.md
+hunk session reload --repo /path/to/worktree -- diff
+hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff
+```
+
+- Always include `--` before the nested Hunk command
+- `--repo` or `<session-id>` usually selects the session you want
+- `--source` is advanced: it does not select the session; it only changes where the replacement review command runs
+- If the live session is already showing the target worktree, prefer `hunk session reload --repo /path/to/worktree -- diff`
+- `--session-path` targets the live window when you need to keep session selection separate from reload source
+
+### Comments
+
+```bash
+hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" [--rationale "..."] [--author "agent"] [--focus]
+printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' | hunk session comment apply --repo . --stdin [--focus]
+hunk session comment list --repo . [--file README.md]
+hunk session comment rm --repo . <comment-id>
+hunk session comment clear --repo . --yes [--file README.md]
+```
+
+- `comment add` is best for one note; `comment apply` is best when an agent already has several notes ready
+- `comment add` requires `--file`, `--summary`, and exactly one of `--old-line` or `--new-line`
+- `comment apply` payload items require `filePath`, `summary`, and exactly one target such as `hunk`, `hunkNumber`, `oldLine`, or `newLine`
+- `comment apply` reads a JSON batch from stdin and validates the full batch before mutating the live session
+- Pass `--focus` when you want to jump to the new note or the first note in a batch
+- `comment list` and `comment clear` accept optional `--file`
+- Quote `--summary` and `--rationale` defensively in the shell
+
+## New files in working-tree reviews
+
+`hunk diff` includes untracked files by default. If the user wants tracked changes only, reload with `--exclude-untracked`:
+
+```bash
+hunk session reload --repo . -- diff --exclude-untracked
+```
+
+## Guiding a review
+
+The user may ask you to walk them through a changeset or review code using Hunk. Start with `hunk session review --json` to understand the file/hunk structure without inflating agent context, then use `--include-patch` only for the files you truly need to read in raw diff form. Use `context` and `navigate` to line up the user's current view before adding comments.
+
+Your role is to narrate: steer the user's view to what matters and leave comments that explain what they're looking at.
+
+Typical flow:
+
+1. Load the right content (`reload` if needed)
+2. Navigate to the first interesting file / hunk
+3. Add a comment explaining what's happening and why
+4. If you already have several notes ready, prefer one `comment apply` batch over many separate shell invocations
+5. Summarize when done
+
+Guidelines:
+
+- Work in the order that tells the clearest story, not necessarily file order
+- Navigate before commenting so the user sees the code you're discussing
+- Use `comment apply` for agent-generated batches and `comment add` for one-off notes
+- Use `--focus` sparingly when the note itself should actively steer the review
+- Keep comments focused: intent, structure, risks, or follow-ups
+- Don't comment on every hunk -- highlight what the user wouldn't spot themselves
+
+## Common errors
+
+- **"No visible diff file matches ..."** -- the file is not in the loaded review. Check `context`, then `reload` if needed.
+- **"No active Hunk sessions"** -- ask the user to open Hunk in their terminal.
+- **"Multiple active sessions match"** -- pass `<session-id>` explicitly.
+- **"No active Hunk session matches session path ..."** -- for advanced split-path reloads, verify the live window `Path` via `hunk session get` or `list`, then use `--session-path`.
+- **"Pass the replacement Hunk command after `--`"** -- include `--` before the nested `diff` / `show` command.
+- **"Pass --stdin to read batch comments from stdin JSON."** -- `comment apply` only reads its batch payload from stdin.
+- **"Specify exactly one navigation target"** -- pick one of `--hunk`, `--old-line`, or `--new-line`.
+- **"Specify either --next-comment or --prev-comment, not both."** -- choose one comment-navigation direction.

reference/atuin-18.16.1/.claude/skills/release/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: release
+description: >
+  Orchestrate a multi-step Atuin CLI release — version bumping, changelog
+  generation, PR creation, tagging, and crates.io publishing. Invoke with
+  /release or /release <version>.
+disable-model-invocation: true
+argument-hint: [version]
+---
+
+# Atuin CLI Release
+
+You are orchestrating a release of the Atuin CLI. Follow the steps below
+**in order**, pausing at each checkpoint for user confirmation. Do not skip
+steps or combine them.
+
+## Current State
+
+- Workspace version: !`sed -n '/^\[workspace\.package\]/,/^\[/s/^version = "\(.*\)"/\1/p' Cargo.toml`
+- Latest tag: !`git describe --tags --abbrev=0 2>/dev/null || echo "none"`
+- Suggested next version: !`git-cliff --bumped-version 2>/dev/null | sed 's/^v//' || echo "(unknown)"`
+
+---
+
+## Step 1 — Check Dependencies
+
+Verify these tools are installed: `git`, `gsed`, `cargo`, `gh`, `git-cliff`.
+
+Use `command -v` for each. If any are missing, report which ones and stop.
+
+---
+
+## Step 2 — Determine Version
+
+The target version may be provided as `$ARGUMENTS`. If it's empty, use
+AskUserQuestion to ask for the new version (show the current state above
+for reference).
+
+After determining the version:
+- If it contains a `-` (e.g. `18.15.0-beta.1`), it is a **prerelease**.
+  Note this — it affects changelog and publish behavior later.
+- Show the user: `current → new` and whether it's a prerelease.
+- **Checkpoint:** Ask the user to confirm before proceeding.
+
+---
+
+## Step 3 — Set Up Working Directory
+
+Clone a fresh copy into a temp directory:
+
+```bash
+WORKDIR=$(mktemp -d)
+git clone git@github.com:atuinsh/atuin.git "$WORKDIR"
+```
+
+Print the working directory path so the user can find it if needed.
+All subsequent Bash commands run from `$WORKDIR`.
+
+---
+
+## Step 4 — Create Branch & Update Versions
+
+1. Create a release branch named after the version (no `v` prefix):
+   `git checkout -b <VERSION>`
+
+2. Replace the old version with the new one in all `Cargo.toml` files.
+   **Escape dots** in the old version so sed treats them literally:
+
+   ```bash
+   VERSION_PATTERN="${OLD_VERSION//./\\.}"
+   find . -type f -name 'Cargo.toml' -not -path './.git/*' \
+       -exec gsed -i "s/$VERSION_PATTERN/$NEW_VERSION/g" {} \;
+   ```
+
+3. Run `cargo check` to update `Cargo.lock`.
+
+4. Show `git diff --stat` and the version-related lines from the diff:
+   ```bash
+   git diff --unified=0 -- '*.toml' | grep -E '^\+.*version' | grep -v '^\+\+\+'
+   ```
+
+5. Verify the workspace version was actually updated by re-reading it
+   from `Cargo.toml`.
+
+6. **Checkpoint:** Show the diff summary and ask the user to confirm the
+   version changes look correct.
+
+---
+
+## Step 5 — Update Changelog
+
+The changelog strategy differs for prereleases vs stable releases:
+
+- **Prerelease:** Maintain a running `## [unreleased]` section containing
+  all changes since the last stable release. Use:
+  `git-cliff --unreleased --strip all`
+  (cliff.toml's `ignore_tags` already ignores beta/alpha tags, so
+  `--unreleased` spans back to the last stable release automatically.)
+
+- **Stable release:** Generate a versioned entry that replaces the
+  `[unreleased]` section. Use:
+  `git-cliff --unreleased --tag "v<VERSION>" --strip all`
+
+Then update `CHANGELOG.md`:
+
+1. If an existing `## [unreleased]` or `## [Unreleased]` section exists,
+   **remove it entirely** (the heading and all content up to the next
+   `## ` heading).
+
+2. Insert the new entry before the first existing `## ` version heading.
+
+3. **Checkpoint:** Read and display the new changelog entry to the user.
+   Ask if they want any edits. If so, make the requested changes using
+   the Edit tool. Repeat until they're satisfied.
+
+---
+
+## Step 6 — Commit & Push
+
+Stage all changes and commit:
+
+```
+chore(release): prepare for release <VERSION>
+```
+
+Push the branch with `--set-upstream origin`.
+
+---
+
+## Step 7 — Create PR & Wait for Merge
+
+### Create the PR
+
+Extract the changelog entry body (everything between the new `## ` heading
+and the next one) for the PR description.
+
+For prereleases, the heading to match is `## [unreleased]`.
+For stable releases, it's `## <VERSION>` (escape dots in the awk pattern).
+
+Create the PR:
+```bash
+gh pr create \
+    --title "chore(release): prepare for release <VERSION>" \
+    --body "<body with changelog>" \
+    --repo atuinsh/atuin
+```
+
+Show the PR URL to the user.
+
+### Wait for merge
+
+Start a **persistent Monitor** that polls the PR status every 30 seconds.
+The monitor script must:
+- **Only emit output** on meaningful state changes: all checks green, PR
+  merged, or PR closed. Silent polls keep the monitor quiet and avoid
+  flooding notifications.
+- Handle transient API errors gracefully (don't crash on a single failure)
+- Exit 0 on `MERGED`, exit 1 on `CLOSED`
+
+The rollup mixes two entry shapes: `CheckRun` entries use `status` +
+`conclusion`, while `StatusContext` entries use `state`. A check counts
+as "passing" when it's in a terminal state with a non-failing outcome.
+Treat `SUCCESS`, `SKIPPED`, and `NEUTRAL` as passing — some release
+workflows (e.g. `announce`, `build-global-artifacts`) are conditional
+and report `SKIPPED` on non-tag events, which is expected, not a
+failure.
+
+Example monitor script (substitute the actual PR number):
+```bash
+checks_passed=false
+while true; do
+  json=$(gh pr view PR_NUM --repo atuinsh/atuin --json state,statusCheckRollup 2>/dev/null) || { sleep 30; continue; }
+  state=$(echo "$json" | jq -r '.state')
+  case "$state" in
+    MERGED) echo "PR #PR_NUM has been merged!"; exit 0 ;;
+    CLOSED) echo "PR #PR_NUM was closed without merging."; exit 1 ;;
+  esac
+  # Only notify once when all checks reach a terminal passing state.
+  # CheckRun entries carry `status`/`conclusion`; StatusContext entries
+  # carry `state`. SKIPPED and NEUTRAL count as passing.
+  if [ "$checks_passed" = false ]; then
+    counts=$(echo "$json" | jq -r '
+      [.statusCheckRollup[]?] as $all
+      | ($all | map(select(
+          (.status == "COMPLETED" and (.conclusion | IN("SUCCESS","SKIPPED","NEUTRAL")))
+          or .state == "SUCCESS"
+        )) | length) as $passing
+      | ($all | map(select(
+          (.status == "COMPLETED" and (.conclusion | IN("FAILURE","TIMED_OUT","CANCELLED","ACTION_REQUIRED","STALE")))
+          or (.state | IN("FAILURE","ERROR"))
+        )) | length) as $failing
+      | "\($all | length) \($passing) \($failing)"
+    ' 2>/dev/null)
+    read -r total passing failing <<<"$counts"
+    if [ "${failing:-0}" -gt 0 ] 2>/dev/null; then
+      echo "PR #PR_NUM has $failing failing check(s) — investigate before merging."
+      checks_passed=true  # don't re-notify
+    elif [ "${total:-0}" -gt 0 ] 2>/dev/null && [ "$total" = "$passing" ]; then
+      echo "All $total checks passed on PR #PR_NUM — ready to merge!"
+      checks_passed=true
+    fi
+  fi
+  sleep 30
+done
+```
+
+Tell the user to go review and merge the PR. While the monitor runs, you
+can respond to other questions — the monitor notifications will arrive
+asynchronously.
+
+When the monitor reports `MERGED`, proceed to the next step.
+If it reports `CLOSED`, inform the user and stop the release.
+
+---
+
+## Step 8 — Tag Release
+
+Back in the working directory:
+
+```bash
+git checkout main
+git pull
+git tag "v<VERSION>"
+git push --tags
+```
+
+Tell the user the tag was pushed and the release CI workflow has been
+triggered.
+
+---
+
+## Step 9 — Publish to crates.io
+
+**If this is a prerelease**, skip this step entirely and tell the user.
+
+**If this is a stable release**, ask the user whether to publish.
+
+If yes, publish each crate **in dependency order** using `--no-verify`
+(the code already passed CI, and verification fails when crates.io
+hasn't indexed a freshly-published dependency yet):
+
+```
+atuin-common, atuin-client, atuin-ai, atuin-dotfiles, atuin-history,
+atuin-nucleo/matcher, atuin-nucleo, atuin-daemon, atuin-kv,
+atuin-scripts, atuin-server-database, atuin-server-postgres,
+atuin-server-sqlite, atuin-server, atuin-pty-proxy, atuin
+```
+
+For each crate, run from `crates/<name>`:
+```bash
+cargo publish --no-verify 2>&1
+```
+
+If it fails with "already uploaded", report it as a skip (not an error) —
+some crates like `atuin-nucleo` are versioned independently and may
+already be published at their current version.
+
+If it fails for any other reason, stop and report the error.
+
+---
+
+## Completion
+
+Summarize what was done:
+- Version released
+- PR URL
+- Tag name
+- Which crates were published (if any)
+- Working directory path and how to clean it up (`rm -rf`)

reference/atuin-18.16.1/.codespellrc

@@ -0,0 +1,7 @@
+[codespell]
+# Ref: https://github.com/codespell-project/codespell#using-a-config-file
+skip = .git*,*.lock,.codespellrc,CODE_OF_CONDUCT.md,CONTRIBUTORS
+check-hidden = true
+# ignore-regex = 
+ignore-words-list = crate,ratatui,inbetween,iterm,fo,brunch
+

reference/atuin-18.16.1/.depot/workflows/codespell.yml

@@ -0,0 +1,28 @@
+# Depot CI Migration
+# Source: .github/workflows/codespell.yml
+#
+# No changes were necessary.
+
+# Codespell configuration is within .codespellrc
+name: Codespell
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  codespell:
+    name: Check for spelling errors
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Codespell
+        uses: codespell-project/actions-codespell@v2
+        with:
+          # This is regenerated from commit history
+          # we cannot rewrite commit history, and I'd rather not correct it
+          # every time
+          exclude_file: CHANGELOG.md

reference/atuin-18.16.1/.depot/workflows/installer.yml

@@ -0,0 +1,36 @@
+# Depot CI Migration
+# Source: .github/workflows/installer.yml
+#
+# No changes were necessary.
+
+name: Install
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths: .github/workflows/installer.yml
+env:
+  CARGO_TERM_COLOR: always
+jobs:
+  install:
+    strategy:
+      matrix:
+        os: [depot-ubuntu-24.04, macos-14]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install zsh for ubuntu
+        if: matrix.os == 'depot-ubuntu-24.04'
+        run: |
+          sudo apt install zsh
+      - name: Test install script on bash
+        run: |
+          /bin/bash -c "$(curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh)"
+          [ -d "$HOME/.atuin" ] && source $HOME/.atuin/bin/env
+          atuin --help
+      - name: Test install script on zsh
+        shell: zsh {0}
+        run: |
+          /bin/bash -c "$(curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh)"
+          [ -d "$HOME/.atuin" ] && source $HOME/.atuin/bin/env
+          atuin --help

reference/atuin-18.16.1/.depot/workflows/nix.yml

@@ -0,0 +1,33 @@
+# Depot CI Migration
+# Source: .github/workflows/nix.yml
+#
+# No changes were necessary.
+
+# Verify the Nix build is working
+# Failures will usually occur due to an out of date Rust version
+# That can be updated to the latest version in nixpkgs-unstable with `nix flake update`
+name: Nix
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'ui/**'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - 'ui/**'
+jobs:
+  check:
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - uses: cachix/install-nix-action@v31
+      - name: Run nix flake check
+        run: nix flake check --print-build-logs
+  build-test:
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - uses: cachix/install-nix-action@v31
+      - name: Run nix build
+        run: nix build --print-build-logs

reference/atuin-18.16.1/.depot/workflows/rust.yml

@@ -0,0 +1,187 @@
+# Depot CI Migration
+# Source: .github/workflows/rust.yml
+#
+# No changes were necessary.
+
+name: Rust
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "ui/**"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "ui/**"
+env:
+  CARGO_TERM_COLOR: always
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [depot-ubuntu-24.04, macos-14, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.94.0
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-release-${{ hashFiles('**/Cargo.lock') }}
+      - name: Run cargo build common
+        run: cargo build -p atuin-common --locked --release
+      - name: Run cargo build client
+        run: cargo build -p atuin-client --locked --release
+      - name: Run cargo build server
+        run: cargo build -p atuin-server --locked --release
+      - name: Run cargo build main
+        run: cargo build --all --locked --release
+  cross-compile:
+    strategy:
+      matrix:
+        # There was an attempt to make cross-compiles also work on FreeBSD, but that failed with:
+        #
+        # warning: libelf.so.2, needed by <...>/libkvm.so, not found (try using -rpath or -rpath-link)
+        target: [x86_64-unknown-illumos]
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install cross
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cross
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ matrix.target }}-cross-compile-${{ hashFiles('**/Cargo.lock') }}
+      - name: Run cross build common
+        run: cross build -p atuin-common --locked --target ${{ matrix.target }}
+      - name: Run cross build client
+        run: cross build -p atuin-client --locked --target ${{ matrix.target }}
+      - name: Run cross build server
+        run: cross build -p atuin-server --locked --target ${{ matrix.target }}
+      - name: Run cross build main
+        run: |
+          cross build --all --locked --target ${{ matrix.target }}
+  unit-test:
+    strategy:
+      matrix:
+        os: [depot-ubuntu-24.04, macos-14, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.94.0
+      - uses: taiki-e/install-action@v2
+        name: Install nextest
+        with:
+          tool: cargo-nextest
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+             ~/.cargo/git
+             target
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+      - name: Run cargo test
+        run: cargo nextest run --lib --bins
+  check:
+    strategy:
+      matrix:
+        os: [depot-ubuntu-24.04, macos-14, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.94.0
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+             ~/.cargo/git
+             target
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+      - name: Run cargo check (all features)
+        run: cargo check --all-features --workspace
+      - name: Run cargo check (no features)
+        run: cargo check --no-default-features --workspace
+      - name: Run cargo check (sync)
+        run: cargo check --no-default-features --features sync --workspace
+      - name: Run cargo check (server)
+        run: cargo check -p atuin-server
+      - name: Run cargo check (client only)
+        run: cargo check --no-default-features --features client --workspace
+  integration-test:
+    runs-on: depot-ubuntu-24.04
+    services:
+      postgres:
+        image: postgres
+        env:
+          POSTGRES_USER: atuin
+          POSTGRES_PASSWORD: pass
+          POSTGRES_DB: atuin
+        ports:
+          - 5432:5432
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.94.0
+      - uses: taiki-e/install-action@v2
+        name: Install nextest
+        with:
+          tool: cargo-nextest
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+             ~/.cargo/git
+             target
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+      - name: Run cargo test
+        run: cargo nextest run --test '*'
+        env:
+          ATUIN_DB_URI: postgres://atuin:pass@localhost:5432/atuin
+  clippy:
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install latest rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.94.0
+          components: clippy
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+      - name: Run clippy
+        run: cargo clippy -- -D warnings -D clippy::redundant_clone
+  format:
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install latest rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.94.0
+          components: rustfmt
+      - name: Format
+        run: cargo fmt -- --check

reference/atuin-18.16.1/.depot/workflows/shellcheck.yml

@@ -0,0 +1,20 @@
+# Depot CI Migration
+# Source: .github/workflows/shellcheck.yml
+#
+# No changes were necessary.
+
+name: Shellcheck
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  shellcheck:
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - name: Run shellcheck
+        uses: ludeeus/action-shellcheck@master
+        env:
+          SHELLCHECK_OPTS: "-e SC2148"

reference/atuin-18.16.1/.depot/workflows/update-nix-deps.yml

@@ -0,0 +1,25 @@
+# Depot CI Migration
+# Source: .github/workflows/update-nix-deps.yml
+#
+# No changes were necessary.
+
+name: Update Nix Deps
+on:
+  workflow_dispatch: # allows manual triggering
+  schedule:
+    - cron: '0 0 1 * *' # runs monthly on the first day of the month at 00:00
+jobs:
+  lockfile:
+    runs-on: depot-ubuntu-24.04
+    if: github.repository == 'atuinsh/atuin'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+      - name: Update flake.lock
+        uses: DeterminateSystems/update-flake-lock@main
+        with:
+          pr-title: "chore(deps): update flake.lock"
+          pr-labels: |
+            dependencies

reference/atuin-18.16.1/.dockerignore

@@ -0,0 +1,2 @@
+./target
+Dockerfile

reference/atuin-18.16.1/.gitattributes

@@ -0,0 +1,5 @@
+*.sh eol=lf
+*.nix eol=lf
+*.zsh eol=lf
+
+*.sql eol=lf

reference/atuin-18.16.1/.github/DISCUSSION_TEMPLATE/support.yml

@@ -0,0 +1,84 @@
+body:
+  - type: input
+    attributes:
+      label: Operating System
+      description: What operating system are you using?
+      placeholder: "Example: macOS Big Sur"
+    validations:
+      required: true
+
+  - type: input
+    attributes:
+      label: Shell
+      description: What shell are you using?
+      placeholder: "Example: zsh 5.8.1"
+    validations:
+      required: true
+
+  - type: dropdown
+    attributes:
+      label: Version
+      description: What version of atuin are you running?
+      multiple: false
+      options: # how often will I forget to update this? a lot.
+        - v17.0.0 (Default)
+        - v16.0.0
+        - v15.0.0
+        - v14.0.1
+        - v14.0.0
+        - v13.0.1
+        - v13.0.0
+        - v12.0.0
+        - v11.0.0
+        - v0.10.0
+        - v0.9.1
+        - v0.9.0
+        - v0.8.1
+        - v0.8.0
+        - v0.7.2
+        - v0.7.1
+        - v0.7.0
+        - v0.6.4
+        - v0.6.3
+      default: 0
+    validations:
+      required: true
+
+  - type: checkboxes
+    attributes:
+      label: Self hosted
+      description: Are you self hosting atuin server?
+      options:
+        - label: I am self hosting atuin server
+
+  - type: checkboxes
+    attributes:
+      label: Search the issues
+      description: Did you search the issues and discussions for your problem?
+      options:
+        - label: I checked that someone hasn't already asked about the same issue
+          required: true
+
+  - type: textarea
+    attributes:
+      label: Behaviour
+      description: "Please describe the issue - what you expected to happen, what actually happened"
+      
+  - type: textarea
+    attributes:
+      label: Logs
+      description: "If possible, please include logs from atuin, especially if you self host the server - ATUIN_LOG=debug"
+
+  - type: textarea
+    attributes:
+      label: Extra information
+      description: "Anything else you'd like to add?"
+
+  - type: checkboxes
+    attributes:
+      label: Code of Conduct
+      description: The Code of Conduct helps create a safe space for everyone. We require
+        that everyone agrees to it.
+      options:
+        - label: I agree to follow this project's [Code of Conduct](https://github.com/atuinsh/atuin/blob/main/CODE_OF_CONDUCT.md)
+          required: true

reference/atuin-18.16.1/.github/FUNDING.yml

@@ -0,0 +1,13 @@
+# These are supported funding model platforms
+
+github: [atuinsh]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

reference/atuin-18.16.1/.github/ISSUE_TEMPLATE/bug.yaml

@@ -0,0 +1,39 @@
+name: Bug Report
+description: File a bug report
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: what-expected
+    attributes:
+      label: What did you expect to happen?
+      placeholder: Tell us what you expected to see!
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      placeholder: Tell us what you see!
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    validations:
+      required: true
+    attributes:
+      label: Atuin doctor output
+      description: Please run 'atuin doctor' and share the output. If it fails to run, share any errors. This requires Atuin >=v18.1.0
+      render: yaml
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/atuinsh/atuin/blob/main/CODE_OF_CONDUCT.md)
+      options:
+        - label: I agree to follow this project's Code of Conduct
+          required: true

reference/atuin-18.16.1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "cargo" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "docker" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

reference/atuin-18.16.1/.github/pull_request_template.md

@@ -0,0 +1,5 @@
+<!-- Thank you for making a PR! Bug fixes are always welcome, but if you're adding a new feature or changing an existing one, we'd really appreciate if you open an issue, post on the forum, or drop in on Discord -->
+
+## Checks
+- [ ] I am happy for maintainers to push small adjustments to this PR, to speed up the review cycle
+- [ ] I have checked that there are no existing pull requests for the same thing

reference/atuin-18.16.1/.github/workflows/codespell.yml

@@ -0,0 +1,28 @@
+# Codespell configuration is within .codespellrc
+---
+name: Codespell
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  codespell:
+    name: Check for spelling errors
+    runs-on: depot-ubuntu-24.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Codespell
+        uses: codespell-project/actions-codespell@v2
+        with:
+          # This is regenerated from commit history
+          # we cannot rewrite commit history, and I'd rather not correct it
+          # every time
+          exclude_file: CHANGELOG.md

reference/atuin-18.16.1/.github/workflows/docker.yaml

@@ -0,0 +1,61 @@
+name: build-docker
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    concurrency:
+      group: ${{ github.ref }}-docker
+      cancel-in-progress: true
+    permissions:
+      packages: write
+      contents: read
+      id-token: write
+
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Get Repo Owner
+        id: get_repo_owner
+        run: echo "REPO_OWNER=$(echo ${{ github.repository_owner }} | tr '[:upper:]' '[:lower:]')" > $GITHUB_ENV
+
+      - uses: depot/setup-action@v1
+
+      - name: Login to container Registry
+        uses: docker/login-action@v3
+        with:
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          registry: ghcr.io
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ env.REPO_OWNER }}/atuin
+          flavor: |
+            latest=false
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push
+        uses: depot/build-push-action@v1
+        with:
+          push: true
+          platforms: linux/amd64,linux/arm64
+          file: ./Dockerfile
+          context: .
+          provenance: false
+          build-args: |
+            Version=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.version'] || 'dev' }}
+            GitCommit=${{ github.sha }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

reference/atuin-18.16.1/.github/workflows/installer.yml

@@ -0,0 +1,38 @@
+name: Install
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths: .github/workflows/installer.yml
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  install:
+    strategy:
+      matrix:
+        os: [depot-ubuntu-24.04, macos-14]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install zsh for ubuntu
+        if: matrix.os == 'depot-ubuntu-24.04' 
+        run: | 
+          sudo apt install zsh
+
+      - name: Test install script on bash
+        run: | 
+          /bin/bash -c "$(curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh)"
+          [ -d "$HOME/.atuin" ] && source $HOME/.atuin/bin/env
+          atuin --help
+
+      - name: Test install script on zsh
+        shell: zsh {0}
+        run: | 
+          /bin/bash -c "$(curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh)"
+          [ -d "$HOME/.atuin" ] && source $HOME/.atuin/bin/env
+          atuin --help

reference/atuin-18.16.1/.github/workflows/nix.yml

@@ -0,0 +1,34 @@
+# Verify the Nix build is working
+# Failures will usually occur due to an out of date Rust version
+# That can be updated to the latest version in nixpkgs-unstable with `nix flake update`
+name: Nix
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - 'ui/**'
+  pull_request:
+    branches: [ main ]
+    paths-ignore:
+      - 'ui/**'
+
+jobs:
+  check:
+    runs-on: depot-ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: cachix/install-nix-action@v31
+
+      - name: Run nix flake check
+        run: nix flake check --print-build-logs
+
+  build-test:
+    runs-on: depot-ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: cachix/install-nix-action@v31
+
+      - name: Run nix build
+        run: nix build --print-build-logs

reference/atuin-18.16.1/.github/workflows/release.yml

@@ -0,0 +1,304 @@
+# This file was autogenerated by dist: https://axodotdev.github.io/cargo-dist
+#
+# Copyright 2022-2024, axodotdev
+# SPDX-License-Identifier: MIT or Apache-2.0
+#
+# CI that:
+#
+# * checks for a Git Tag that looks like a release
+# * builds artifacts with dist (archives, installers, hashes)
+# * uploads those artifacts to temporary workflow zip
+# * on success, uploads the artifacts to a GitHub Release
+#
+# Note that the GitHub Release will be created with a generated
+# title/body based on your changelogs.
+
+name: Release
+permissions:
+  "contents": "write"
+
+# This task will run whenever you push a git tag that looks like a version
+# like "1.0.0", "v0.1.0-prerelease.1", "my-app/0.1.0", "releases/v1.0.0", etc.
+# Various formats will be parsed into a VERSION and an optional PACKAGE_NAME, where
+# PACKAGE_NAME must be the name of a Cargo package in your workspace, and VERSION
+# must be a Cargo-style SemVer Version (must have at least major.minor.patch).
+#
+# If PACKAGE_NAME is specified, then the announcement will be for that
+# package (erroring out if it doesn't have the given version or isn't dist-able).
+#
+# If PACKAGE_NAME isn't specified, then the announcement will be for all
+# (dist-able) packages in the workspace with that version (this mode is
+# intended for workspaces with only one dist-able package, or with all dist-able
+# packages versioned/released in lockstep).
+#
+# If you push multiple tags at once, separate instances of this workflow will
+# spin up, creating an independent announcement for each one. However, GitHub
+# will hard limit this to 3 tags per commit, as it will assume more tags is a
+# mistake.
+#
+# If there's a prerelease-style suffix to the version, then the release(s)
+# will be marked as a prerelease.
+on:
+  pull_request:
+  push:
+    tags:
+      - '**[0-9]+.[0-9]+.[0-9]+*'
+
+jobs:
+  # Run 'dist plan' (or host) to determine what tasks we need to do
+  plan:
+    runs-on: "ubuntu-22.04"
+    outputs:
+      val: ${{ steps.plan.outputs.manifest }}
+      tag: ${{ !github.event.pull_request && github.ref_name || '' }}
+      tag-flag: ${{ !github.event.pull_request && format('--tag={0}', github.ref_name) || '' }}
+      publishing: ${{ !github.event.pull_request }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Install dist
+        # we specify bash to get pipefail; it guards against the `curl` command
+        # failing. otherwise `sh` won't catch that `curl` returned non-0
+        shell: bash
+        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.31.0/cargo-dist-installer.sh | sh"
+      - name: Cache dist
+        uses: actions/upload-artifact@v6
+        with:
+          name: cargo-dist-cache
+          path: ~/.cargo/bin/dist
+      # sure would be cool if github gave us proper conditionals...
+      # so here's a doubly-nested ternary-via-truthiness to try to provide the best possible
+      # functionality based on whether this is a pull_request, and whether it's from a fork.
+      # (PRs run on the *source* but secrets are usually on the *target* -- that's *good*
+      # but also really annoying to build CI around when it needs secrets to work right.)
+      - id: plan
+        run: |
+          dist ${{ (!github.event.pull_request && format('host --steps=create --tag={0}', github.ref_name)) || 'plan' }} --output-format=json > plan-dist-manifest.json
+          echo "dist ran successfully"
+          cat plan-dist-manifest.json
+          echo "manifest=$(jq -c "." plan-dist-manifest.json)" >> "$GITHUB_OUTPUT"
+      - name: "Upload dist-manifest.json"
+        uses: actions/upload-artifact@v6
+        with:
+          name: artifacts-plan-dist-manifest
+          path: plan-dist-manifest.json
+
+  # Build and packages all the platform-specific things
+  build-local-artifacts:
+    name: build-local-artifacts (${{ join(matrix.targets, ', ') }})
+    # Let the initial task tell us to not run (currently very blunt)
+    needs:
+      - plan
+    if: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix.include != null && (needs.plan.outputs.publishing == 'true' || fromJson(needs.plan.outputs.val).ci.github.pr_run_mode == 'upload') }}
+    strategy:
+      fail-fast: false
+      # Target platforms/runners are computed by dist in create-release.
+      # Each member of the matrix has the following arguments:
+      #
+      # - runner: the github runner
+      # - dist-args: cli flags to pass to dist
+      # - install-dist: expression to run to install dist on the runner
+      #
+      # Typically there will be:
+      # - 1 "global" task that builds universal installers
+      # - N "local" tasks that build each platform's binaries and platform-specific installers
+      matrix: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix }}
+    runs-on: ${{ matrix.runner }}
+    container: ${{ matrix.container && matrix.container.image || null }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      BUILD_MANIFEST_NAME: target/distrib/${{ join(matrix.targets, '-') }}-dist-manifest.json
+    permissions:
+      "attestations": "write"
+      "contents": "read"
+      "id-token": "write"
+    steps:
+      - name: enable windows longpaths
+        run: |
+          git config --global core.longpaths true
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Install Rust non-interactively if not already installed
+        if: ${{ matrix.container }}
+        run: |
+          if ! command -v cargo > /dev/null 2>&1; then
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+            echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+          fi
+      - name: Install dist
+        run: ${{ matrix.install_dist.run }}
+      # Get the dist-manifest
+      - name: Fetch local artifacts
+        uses: actions/download-artifact@v7
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      - name: Install dependencies
+        run: |
+          ${{ matrix.packages_install }}
+      - name: Build artifacts
+        run: |
+          # Actually do builds and make zips and whatnot
+          dist build ${{ needs.plan.outputs.tag-flag }} --print=linkage --output-format=json ${{ matrix.dist_args }} > dist-manifest.json
+          echo "dist ran successfully"
+      - name: Attest
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-path: "target/distrib/*${{ join(matrix.targets, ', ') }}*"
+      - id: cargo-dist
+        name: Post-build
+        # We force bash here just because github makes it really hard to get values up
+        # to "real" actions without writing to env-vars, and writing to env-vars has
+        # inconsistent syntax between shell and powershell.
+        shell: bash
+        run: |
+          # Parse out what we just built and upload it to scratch storage
+          echo "paths<<EOF" >> "$GITHUB_OUTPUT"
+          dist print-upload-files-from-manifest --manifest dist-manifest.json >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+          cp dist-manifest.json "$BUILD_MANIFEST_NAME"
+      - name: "Upload artifacts"
+        uses: actions/upload-artifact@v6
+        with:
+          name: artifacts-build-local-${{ join(matrix.targets, '_') }}
+          path: |
+            ${{ steps.cargo-dist.outputs.paths }}
+            ${{ env.BUILD_MANIFEST_NAME }}
+
+  # Build and package all the platform-agnostic(ish) things
+  build-global-artifacts:
+    needs:
+      - plan
+      - build-local-artifacts
+    runs-on: "ubuntu-22.04"
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      BUILD_MANIFEST_NAME: target/distrib/global-dist-manifest.json
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Install cached dist
+        uses: actions/download-artifact@v7
+        with:
+          name: cargo-dist-cache
+          path: ~/.cargo/bin/
+      - run: chmod +x ~/.cargo/bin/dist
+      # Get all the local artifacts for the global tasks to use (for e.g. checksums)
+      - name: Fetch local artifacts
+        uses: actions/download-artifact@v7
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      - id: cargo-dist
+        shell: bash
+        run: |
+          dist build ${{ needs.plan.outputs.tag-flag }} --output-format=json "--artifacts=global" > dist-manifest.json
+          echo "dist ran successfully"
+
+          # Parse out what we just built and upload it to scratch storage
+          echo "paths<<EOF" >> "$GITHUB_OUTPUT"
+          jq --raw-output ".upload_files[]" dist-manifest.json >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+          cp dist-manifest.json "$BUILD_MANIFEST_NAME"
+      - name: "Upload artifacts"
+        uses: actions/upload-artifact@v6
+        with:
+          name: artifacts-build-global
+          path: |
+            ${{ steps.cargo-dist.outputs.paths }}
+            ${{ env.BUILD_MANIFEST_NAME }}
+  # Determines if we should publish/announce
+  host:
+    needs:
+      - plan
+      - build-local-artifacts
+      - build-global-artifacts
+    # Only run if we're "publishing", and only if plan, local and global didn't fail (skipped is fine)
+    if: ${{ always() && needs.plan.result == 'success' && needs.plan.outputs.publishing == 'true' && (needs.build-global-artifacts.result == 'skipped' || needs.build-global-artifacts.result == 'success') && (needs.build-local-artifacts.result == 'skipped' || needs.build-local-artifacts.result == 'success') }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    runs-on: "ubuntu-22.04"
+    outputs:
+      val: ${{ steps.host.outputs.manifest }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Install cached dist
+        uses: actions/download-artifact@v7
+        with:
+          name: cargo-dist-cache
+          path: ~/.cargo/bin/
+      - run: chmod +x ~/.cargo/bin/dist
+      # Fetch artifacts from scratch-storage
+      - name: Fetch artifacts
+        uses: actions/download-artifact@v7
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      - id: host
+        shell: bash
+        run: |
+          dist host ${{ needs.plan.outputs.tag-flag }} --steps=upload --steps=release --output-format=json > dist-manifest.json
+          echo "artifacts uploaded and released successfully"
+          cat dist-manifest.json
+          echo "manifest=$(jq -c "." dist-manifest.json)" >> "$GITHUB_OUTPUT"
+      - name: "Upload dist-manifest.json"
+        uses: actions/upload-artifact@v6
+        with:
+          # Overwrite the previous copy
+          name: artifacts-dist-manifest
+          path: dist-manifest.json
+      # Create a GitHub Release while uploading all files to it
+      - name: "Download GitHub Artifacts"
+        uses: actions/download-artifact@v7
+        with:
+          pattern: artifacts-*
+          path: artifacts
+          merge-multiple: true
+      - name: Cleanup
+        run: |
+          # Remove the granular manifests
+          rm -f artifacts/*-dist-manifest.json
+      - name: Create GitHub Release
+        env:
+          PRERELEASE_FLAG: "${{ fromJson(steps.host.outputs.manifest).announcement_is_prerelease && '--prerelease' || '' }}"
+          ANNOUNCEMENT_TITLE: "${{ fromJson(steps.host.outputs.manifest).announcement_title }}"
+          ANNOUNCEMENT_BODY: "${{ fromJson(steps.host.outputs.manifest).announcement_github_body }}"
+          RELEASE_COMMIT: "${{ github.sha }}"
+        run: |
+          # Write and read notes from a file to avoid quoting breaking things
+          echo "$ANNOUNCEMENT_BODY" > $RUNNER_TEMP/notes.txt
+
+          gh release create "${{ needs.plan.outputs.tag }}" --target "$RELEASE_COMMIT" $PRERELEASE_FLAG --title "$ANNOUNCEMENT_TITLE" --notes-file "$RUNNER_TEMP/notes.txt" artifacts/*
+
+  announce:
+    needs:
+      - plan
+      - host
+    # use "always() && ..." to allow us to wait for all publish jobs while
+    # still allowing individual publish jobs to skip themselves (for prereleases).
+    # "host" however must run to completion, no skipping allowed!
+    if: ${{ always() && needs.host.result == 'success' }}
+    runs-on: "ubuntu-22.04"
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          submodules: recursive

reference/atuin-18.16.1/.github/workflows/rust.yml

@@ -0,0 +1,230 @@
+name: Rust
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "ui/**"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "ui/**"
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [depot-ubuntu-24.04, macos-14, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-release-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Run cargo build common
+        run: cargo build -p atuin-common --locked --release
+
+      - name: Run cargo build client
+        run: cargo build -p atuin-client --locked --release
+
+      - name: Run cargo build server
+        run: cargo build -p atuin-server --locked --release
+
+      - name: Run cargo build main
+        run: cargo build --all --locked --release
+
+  cross-compile:
+    strategy:
+      matrix:
+        # There was an attempt to make cross-compiles also work on FreeBSD, but that failed with:
+        #
+        # warning: libelf.so.2, needed by <...>/libkvm.so, not found (try using -rpath or -rpath-link)
+        target: [x86_64-unknown-illumos]
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install cross
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cross
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ matrix.target }}-cross-compile-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Run cross build common
+        run: cross build -p atuin-common --locked --target ${{ matrix.target }}
+
+      - name: Run cross build client
+        run: cross build -p atuin-client --locked --target ${{ matrix.target }}
+
+      - name: Run cross build server
+        run: cross build -p atuin-server --locked --target ${{ matrix.target }}
+
+      - name: Run cross build main
+        run: |
+          cross build --all --locked --target ${{ matrix.target }}
+
+  unit-test:
+    strategy:
+      matrix:
+        os: [depot-ubuntu-24.04, macos-14, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+
+      - uses: taiki-e/install-action@v2
+        name: Install nextest
+        with:
+          tool: cargo-nextest
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+             ~/.cargo/git
+             target
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Run cargo test
+        run: cargo nextest run --lib --bins
+
+  check:
+    strategy:
+      matrix:
+        os: [depot-ubuntu-24.04, macos-14, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+             ~/.cargo/git
+             target
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Run cargo check (all features)
+        run: cargo check --all-features --workspace
+
+      - name: Run cargo check (no features)
+        run: cargo check --no-default-features --workspace
+
+      - name: Run cargo check (sync)
+        run: cargo check --no-default-features --features sync --workspace
+
+      - name: Run cargo check (server)
+        run: cargo check -p atuin-server
+
+      - name: Run cargo check (client only)
+        run: cargo check --no-default-features --features client --workspace
+
+  integration-test:
+    runs-on: depot-ubuntu-24.04
+
+    services:
+      postgres:
+        image: postgres
+        env:
+          POSTGRES_USER: atuin
+          POSTGRES_PASSWORD: pass
+          POSTGRES_DB: atuin
+        ports:
+          - 5432:5432
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+
+      - uses: taiki-e/install-action@v2
+        name: Install nextest
+        with:
+          tool: cargo-nextest
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+             ~/.cargo/git
+             target
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Run cargo test
+        run: cargo nextest run --test '*'
+        env:
+          ATUIN_DB_URI: postgres://atuin:pass@localhost:5432/atuin
+
+  clippy:
+    runs-on: depot-ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install latest rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+          components: clippy
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Run clippy
+        run: cargo clippy -- -D warnings -D clippy::redundant_clone
+
+  format:
+    runs-on: depot-ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install latest rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+          components: rustfmt
+
+      - name: Format
+        run: cargo fmt -- --check

reference/atuin-18.16.1/.github/workflows/shellcheck.yml

@@ -0,0 +1,18 @@
+name: Shellcheck
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  shellcheck:
+    runs-on: depot-ubuntu-24.04
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Run shellcheck
+      uses: ludeeus/action-shellcheck@master
+      env:
+        SHELLCHECK_OPTS: "-e SC2148"

reference/atuin-18.16.1/.github/workflows/update-nix-deps.yml

@@ -0,0 +1,21 @@
+name: Update Nix Deps
+on:
+  workflow_dispatch: # allows manual triggering
+  schedule:
+    - cron: '0 0 1 * *' # runs monthly on the first day of the month at 00:00
+
+jobs:
+  lockfile:
+    runs-on: depot-ubuntu-24.04
+    if: github.repository == 'atuinsh/atuin'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+      - name: Update flake.lock
+        uses: DeterminateSystems/update-flake-lock@main
+        with:
+          pr-title: "chore(deps): update flake.lock"
+          pr-labels: |
+            dependencies

reference/atuin-18.16.1/.gitignore

@@ -0,0 +1,17 @@
+.DS_Store
+/target
+*/target
+.env
+.idea/
+.vscode/
+result
+publish.sh
+.envrc
+.planning/
+
+ui/backend/target
+ui/backend/gen
+
+sqlite-server.db*
+
+.atuin/permissions.*.toml

reference/atuin-18.16.1/.mailmap

@@ -0,0 +1,14 @@
+networkException <git@nwex.de> <github@nwex.de>
+Violet Shreve <github@shreve.io> <jacob@shreve.io>
+Chris Rose <offline@offby1.net> <offbyone@github.com>
+Conrad Ludgate <conradludgate@gmail.com> <conrad.ludgate@truelayer.com>
+Cristian Le <github@lecris.me> <cristian.le@mpsd.mpg.de>
+Dennis Trautwein <git@dtrautwein.eu> <dennis.trautwein@posteo.de>
+Ellie Huxtable <ellie@atuin.sh> <e@elm.sh> 
+Ellie Huxtable <ellie@atuin.sh> <ellie@elliehuxtable.com> 
+Frank Hamand <frankhamand@gmail.com> <frank.hamand@coinbase.com>
+Jakob Schrettenbrunner <dev@schrej.net> <jakob.schrettenbrunner@telekom.de>
+Nemo157 <git@nemo157.com> <github@nemo157.com>
+Richard de Boer <git@tubul.net> <github@tubul.net>
+Sandro <sandro.jaeckel@gmail.com> <sandro.jaeckel@sap.com>
+TymanWasTaken <tbeckman530@gmail.com> <ty@blahaj.land>

reference/atuin-18.16.1/.rustfmt.toml

@@ -0,0 +1,4 @@
+reorder_imports = true
+# uncomment once stable
+#imports_granularity = "crate"
+#group_imports = "StdExternalCrate"

reference/claude-hud-0.0.12/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "claude-hud",
+  "owner": {
+    "name": "Jarrod Watts",
+    "email": "jarrodwattsyt@gmail.com"
+  },
+  "metadata": {
+    "description": "Real-time statusline HUD for Claude Code - context health, tool activity, agent tracking, and todo progress",
+    "version": "0.0.12"
+  },
+  "plugins": [
+    {
+      "name": "claude-hud",
+      "source": "./",
+      "description": "Real-time statusline showing context usage, active tools, running agents, and todo progress. Always visible below your input, zero config required.",
+      "category": "monitoring",
+      "tags": ["hud", "statusline", "monitoring", "context", "tools", "agents", "todos"]
+    }
+  ]
+}

reference/claude-hud-0.0.12/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "claude-hud",
+  "description": "Real-time statusline HUD for Claude Code - context health, tool activity, agent tracking, and todo progress",
+  "version": "0.0.12",
+  "author": {
+    "name": "Jarrod Watts",
+    "url": "https://github.com/jarrodwatts"
+  },
+  "commands": [
+    "./commands/setup.md",
+    "./commands/configure.md"
+  ],
+  "homepage": "https://github.com/jarrodwatts/claude-hud",
+  "repository": "https://github.com/jarrodwatts/claude-hud",
+  "license": "MIT",
+  "keywords": ["hud", "monitoring", "statusline", "context", "tools", "agents", "todos", "claude-code"]
+}

reference/claude-hud-0.0.12/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

reference/claude-hud-0.0.12/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @jarrodwatts

reference/claude-hud-0.0.12/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Report a reproducible problem
+labels: bug
+---
+
+## Summary
+
+## Steps to Reproduce
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Environment
+
+- OS:
+- Node/Bun version:
+- Claude Code version:
+
+## Logs or Screenshots

reference/claude-hud-0.0.12/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: mailto:jarrodwttsyt@gmail.com
+    about: Please report security vulnerabilities via email.

reference/claude-hud-0.0.12/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Suggest an idea or enhancement
+labels: enhancement
+---
+
+## Summary
+
+## Problem to Solve
+
+## Proposed Solution
+
+## Alternatives Considered
+
+## Additional Context

reference/claude-hud-0.0.12/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

reference/claude-hud-0.0.12/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Summary
+
+## Testing
+
+- [ ] `npm test`
+- [ ] `npm run test:coverage`
+
+## Checklist
+
+- [ ] Tests updated or not needed
+- [ ] Docs updated if behavior changed

reference/claude-hud-0.0.12/.github/workflows/build-dist.yml

@@ -0,0 +1,42 @@
+name: Build dist
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: build-dist
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, '[auto]')"
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+
+      - name: Verify build output
+        run: test -f dist/index.js || exit 1
+
+      - name: Commit dist/
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add dist/ --force
+          git diff --staged --quiet || git commit -m "build: compile dist/ [auto]"
+          git push

reference/claude-hud-0.0.12/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'dist/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run test:coverage

reference/claude-hud-0.0.12/.github/workflows/claude.yml

@@ -0,0 +1,48 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          claude_args: '--model claude-opus-4-5-20251101'
+

reference/claude-hud-0.0.12/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20.x
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm run test:coverage
+      - name: Extract release notes from CHANGELOG
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v version="$version" '
+            $0 ~ "^## \\[" version "\\]" { in_section = 1; next }
+            in_section && $0 ~ "^## \\[" { exit }
+            in_section { print }
+          ' CHANGELOG.md > RELEASE_NOTES.md
+
+          if [ ! -s RELEASE_NOTES.md ]; then
+            echo "No changelog section found for version $version"
+            exit 1
+          fi
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: RELEASE_NOTES.md

reference/claude-hud-0.0.12/.gitignore

@@ -0,0 +1,59 @@
+# Dependencies
+node_modules/
+
+# Build artifacts
+# dist/ is gitignored but exists on main - CI builds and commits it after each merge.
+# See .github/workflows/build-dist.yml
+dist/
+*.tsbuildinfo
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.fifo
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Environment/secrets (safety)
+.env
+.env.*
+.claude/settings.json
+.claude/*.local.json
+*.pem
+*.key
+secrets/
+credentials/
+
+# Test coverage
+coverage/
+.nyc_output/
+
+# Temp files
+tmp/
+temp/
+*.tmp
+
+# Lock files (keep package-lock.json for npm)
+yarn.lock
+bun.lock

reference/hermes-agent-2026.5.16/.dockerignore

@@ -0,0 +1,31 @@
+# Git
+.git
+.gitignore
+.gitmodules
+
+# Dependencies
+node_modules
+**/node_modules
+.venv
+**/.venv
+
+# Built artifacts that are regenerated inside the image.  Excluded so local
+# rebuilds on the developer's machine don't invalidate the npm-install layer
+# that now depends on the full ui-tui/packages/hermes-ink/ tree being present.
+ui-tui/dist/
+ui-tui/packages/hermes-ink/dist/
+
+# CI/CD
+.github
+
+# Environment files
+.env
+
+*.md
+
+# Runtime data (bind-mounted at /opt/data; must not leak into build context)
+data/
+
+# Compose/profile runtime state (bind-mounted; avoid ownership/secret issues)
+hermes-config/
+runtime/

reference/hermes-agent-2026.5.16/.env.example

@@ -0,0 +1,469 @@
+# Hermes Agent Environment Configuration
+# Copy this file to .env and fill in your API keys
+
+# =============================================================================
+# LLM PROVIDER (OpenRouter)
+# =============================================================================
+# OpenRouter provides access to many models through one API
+# All LLM calls go through OpenRouter - no direct provider keys needed
+# Get your key at: https://openrouter.ai/keys
+# OPENROUTER_API_KEY=
+
+# Default model is configured in ~/.hermes/config.yaml (model.default).
+# Use 'hermes model' or 'hermes setup' to change it.
+# LLM_MODEL is no longer read from .env — this line is kept for reference only.
+# LLM_MODEL=anthropic/claude-opus-4.6
+
+# =============================================================================
+# LLM PROVIDER (NovitaAI)
+# =============================================================================
+# NovitaAI — 90+ models, pay-per-use
+# Get your key at: https://novita.ai/settings/key-management
+# NOVITA_API_KEY=
+# NOVITA_BASE_URL=https://api.novita.ai/openai/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (Google AI Studio / Gemini)
+# =============================================================================
+# Native Gemini API via Google's OpenAI-compatible endpoint.
+# Get your key at: https://aistudio.google.com/app/apikey
+# GOOGLE_API_KEY=your_google_ai_studio_key_here
+# GEMINI_API_KEY=your_gemini_key_here  # alias for GOOGLE_API_KEY
+# Optional base URL override (default: Google's OpenAI-compatible endpoint)
+# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+
+# =============================================================================
+# LLM PROVIDER (Ollama Cloud)
+# =============================================================================
+# Cloud-hosted open models via Ollama's OpenAI-compatible endpoint.
+# Get your key at: https://ollama.com/settings
+# OLLAMA_API_KEY=your_ollama_key_here
+# Optional base URL override (default: https://ollama.com/v1)
+# OLLAMA_BASE_URL=https://ollama.com/v1
+
+# =============================================================================
+# LLM PROVIDER (z.ai / GLM)
+# =============================================================================
+# z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.)
+# Get your key at: https://z.ai or https://open.bigmodel.cn
+# GLM_API_KEY=
+# GLM_BASE_URL=https://api.z.ai/api/paas/v4  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (Kimi / Moonshot)
+# =============================================================================
+# Kimi Code provides access to Moonshot AI coding models (kimi-k2.5, etc.)
+# Get your key at: https://platform.kimi.ai (Kimi Code console)
+# Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default.
+# Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below.
+# KIMI_API_KEY=
+# KIMI_BASE_URL=https://api.kimi.com/coding/v1  # Default for sk-kimi- keys
+# KIMI_BASE_URL=https://api.moonshot.ai/v1      # For legacy Moonshot keys
+# KIMI_BASE_URL=https://api.moonshot.cn/v1       # For Moonshot China keys
+# KIMI_CN_API_KEY=                               # Dedicated Moonshot China key
+
+# =============================================================================
+# LLM PROVIDER (Arcee AI)
+# =============================================================================
+# Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*)
+# Get an Arcee key at: https://chat.arcee.ai/
+# ARCEEAI_API_KEY=
+# ARCEE_BASE_URL=                                 # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (MiniMax)
+# =============================================================================
+# MiniMax provides access to MiniMax models (global endpoint)
+# Get your key at: https://www.minimax.io
+# MINIMAX_API_KEY=
+# MINIMAX_BASE_URL=https://api.minimax.io/v1  # Override default base URL
+
+# MiniMax China endpoint (for users in mainland China)
+# MINIMAX_CN_API_KEY=
+# MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (OpenCode Zen)
+# =============================================================================
+# OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi)
+# Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth
+# OPENCODE_ZEN_API_KEY=
+# OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (OpenCode Go)
+# =============================================================================
+# OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5)
+# $10/month subscription. Get your key at: https://opencode.ai/auth
+# OPENCODE_GO_API_KEY=
+
+# =============================================================================
+# LLM PROVIDER (Hugging Face Inference Providers)
+# =============================================================================
+# Hugging Face routes to 20+ open models via unified OpenAI-compatible endpoint.
+# Free tier included ($0.10/month), no markup on provider rates.
+# Get your token at: https://huggingface.co/settings/tokens
+# Required permission: "Make calls to Inference Providers"
+# HF_TOKEN=
+# OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (Qwen OAuth)
+# =============================================================================
+# Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth).
+# No API key needed — credentials come from ~/.qwen/oauth_creds.json.
+# Optional base URL override:
+# HERMES_QWEN_BASE_URL=https://portal.qwen.ai/v1
+
+# =============================================================================
+# LLM PROVIDER (Xiaomi MiMo)
+# =============================================================================
+# Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash).
+# Get your key at: https://platform.xiaomimimo.com
+# XIAOMI_API_KEY=your_key_here
+# Optional base URL override:
+# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1
+
+# =============================================================================
+# TOOL API KEYS
+# =============================================================================
+
+# Exa API Key - AI-native web search and contents
+# Get at: https://exa.ai
+# EXA_API_KEY=
+
+# Parallel API Key - AI-native web search and extract
+# Get at: https://parallel.ai
+# PARALLEL_API_KEY=
+
+# Firecrawl API Key - Web search, extract, and crawl
+# Get at: https://firecrawl.dev/
+# FIRECRAWL_API_KEY=
+
+
+# FAL.ai API Key - Image generation
+# Get at: https://fal.ai/
+# FAL_KEY=
+
+# Honcho - Cross-session AI-native user modeling (optional)
+# Builds a persistent understanding of the user across sessions and tools.
+# Get at: https://app.honcho.dev
+# Also requires ~/.honcho/config.json with enabled=true (see README).
+# HONCHO_API_KEY=
+
+# =============================================================================
+# HYPERLIQUID OPTIONAL SKILL
+# =============================================================================
+# Optional defaults for the Hyperliquid skill in optional-skills/blockchain/hyperliquid
+#
+# Hyperliquid API base URL override
+# Default: https://api.hyperliquid.xyz
+# HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz
+#
+# Default address for account-level commands like state, fills, orders, and review
+# HYPERLIQUID_USER_ADDRESS=0x0000000000000000000000000000000000000000
+
+# =============================================================================
+# TERMINAL TOOL CONFIGURATION
+# =============================================================================
+# Backend type: "local", "singularity", "docker", "modal", or "ssh"
+# Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).
+# Use 'hermes setup' or 'hermes config set terminal.backend docker' to change.
+# Supported: local, docker, singularity, modal, ssh
+#
+# Only override here if you need to force a backend without touching config.yaml:
+# TERMINAL_ENV=local
+
+# Override the container runtime binary (e.g. to use Podman instead of Docker).
+# Useful on systems where Docker's storage driver is broken or unavailable.
+# HERMES_DOCKER_BINARY=/usr/local/bin/podman
+
+# Container images (for singularity/docker/modal backends)
+# TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+# TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20
+TERMINAL_MODAL_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+
+
+# Working directory for terminal commands
+# For local backend: "." means current directory (resolved automatically)
+# For remote backends (ssh/docker/modal/singularity): use an absolute path
+#   INSIDE the target environment, or leave unset for the backend's default
+#   (/root for modal, / for docker, ~ for ssh). Do NOT use a host-local path.
+# Usually managed by config.yaml (terminal.cwd) — uncomment to override
+# TERMINAL_CWD=.
+
+# Default command timeout in seconds
+TERMINAL_TIMEOUT=60
+
+# Cleanup inactive environments after this many seconds
+TERMINAL_LIFETIME_SECONDS=300
+
+# =============================================================================
+# SSH REMOTE EXECUTION (for TERMINAL_ENV=ssh)
+# =============================================================================
+# Run terminal commands on a remote server via SSH.
+# Agent code stays on your machine, commands execute remotely.
+#
+# SECURITY BENEFITS:
+# - Agent cannot read your .env file (API keys protected)
+# - Agent cannot modify its own code
+# - Remote server acts as isolated sandbox
+# - Can safely configure passwordless sudo on remote
+#
+# TERMINAL_SSH_HOST=192.168.1.100
+# TERMINAL_SSH_USER=agent
+# TERMINAL_SSH_PORT=22
+# TERMINAL_SSH_KEY=~/.ssh/id_rsa
+
+# =============================================================================
+# SUDO SUPPORT (works with ALL terminal backends)
+# =============================================================================
+# If set, enables sudo commands by piping password via `sudo -S`.
+# Works with: local, docker, singularity, modal, and ssh backends.
+# 
+# SECURITY WARNING: Password stored in plaintext. Only use on trusted machines.
+# 
+# ALTERNATIVES:
+# - For SSH backend: Configure passwordless sudo on the remote server
+# - For containers: Run as root inside the container (no sudo needed)
+# - For local: Configure /etc/sudoers for specific commands
+# - For CLI: Leave unset - you'll be prompted interactively with 45s timeout
+#
+# SUDO_PASSWORD=your_password_here
+
+# =============================================================================
+# MODAL CLOUD BACKEND (Optional - for TERMINAL_ENV=modal)
+# =============================================================================
+# Modal uses CLI authentication, not environment variables.
+# Run: pip install modal && modal setup
+# This will authenticate via browser and store credentials locally.
+# No API key needed in .env - Modal handles auth automatically.
+
+# =============================================================================
+# BROWSER TOOL CONFIGURATION (agent-browser + Browserbase)
+# =============================================================================
+# Browser automation requires Browserbase cloud service for remote browser execution.
+# This allows the agent to navigate websites, fill forms, and extract information.
+#
+# STEALTH MODES:
+# - Basic Stealth: ALWAYS active (random fingerprints, auto CAPTCHA solving)
+# - Advanced Stealth: Requires BROWSERBASE_ADVANCED_STEALTH=true (Scale Plan only)
+
+# Browserbase API Key - Cloud browser execution
+# Get at: https://browserbase.com/
+# BROWSERBASE_API_KEY=
+
+# Browserbase Project ID - From your Browserbase dashboard
+# BROWSERBASE_PROJECT_ID=
+
+# Enable residential proxies for better CAPTCHA solving (default: true)
+# Routes traffic through residential IPs, significantly improves success rate
+BROWSERBASE_PROXIES=true
+
+# Enable advanced stealth mode (default: false, requires Scale Plan)
+# Uses custom Chromium build to avoid bot detection altogether
+BROWSERBASE_ADVANCED_STEALTH=false
+
+# Browser engine for local mode (default: auto = Chrome)
+# "auto"       — use Chrome (don't pass --engine flag)
+# "lightpanda" — use Lightpanda (1.3-5.8x faster navigation, no screenshots)
+# "chrome"     — explicitly request Chrome
+# Requires agent-browser v0.25.3+. Lightpanda commands that fail or return
+# empty results are automatically retried with Chrome.
+# Also configurable via browser.engine in config.yaml.
+# AGENT_BROWSER_ENGINE=auto
+
+# Browser session timeout in seconds (default: 300)
+# Sessions are cleaned up after this duration of inactivity
+BROWSER_SESSION_TIMEOUT=300
+
+# Browser inactivity timeout - auto-cleanup inactive sessions (default: 120 = 2 min)
+# Browser sessions are automatically closed after this period of no activity
+BROWSER_INACTIVITY_TIMEOUT=120
+
+# Extra Chromium launch flags passed to agent-browser, comma- or newline-separated.
+# Hermes auto-injects "--no-sandbox,--disable-dev-shm-usage" when it detects root
+# or AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark,
+# many container images), so leave this unset unless you need extra flags.
+# Setting this disables the auto-injection.
+# AGENT_BROWSER_ARGS=--no-sandbox
+
+# Camofox local anti-detection browser (Camoufox-based Firefox).
+# Set CAMOFOX_URL to route the browser tools through a local Camofox server
+# instead of agent-browser/Browserbase. See docs/user-guide/features/browser.md.
+# CAMOFOX_URL=http://localhost:9377
+
+# Externally managed Camofox sessions — when another app owns the visible
+# Camofox browser, set these so Hermes shares the same userId/profile instead
+# of creating its own isolated session.
+# CAMOFOX_USER_ID=
+# CAMOFOX_SESSION_KEY=
+# Set to true to reuse an already-open Camofox tab for this identity before
+# creating a new one (useful for gateway restarts).
+# CAMOFOX_ADOPT_EXISTING_TAB=false
+
+# =============================================================================
+# SESSION LOGGING
+# =============================================================================
+# Session trajectories are automatically saved to logs/ directory
+# Format: logs/session_YYYYMMDD_HHMMSS_UUID.json
+# Contains full conversation history in trajectory format for debugging/replay
+
+# =============================================================================
+# VOICE TRANSCRIPTION & OPENAI TTS
+# =============================================================================
+# Required for voice message transcription (Whisper) and OpenAI TTS voices.
+# Uses OpenAI's API directly (not via OpenRouter).
+# Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter.
+# Get at: https://platform.openai.com/api-keys
+# VOICE_TOOLS_OPENAI_KEY=
+
+# =============================================================================
+# SLACK INTEGRATION
+# =============================================================================
+# Slack Bot Token - From Slack App settings (OAuth & Permissions)
+# Get at: https://api.slack.com/apps
+# SLACK_BOT_TOKEN=xoxb-...
+
+# Slack App Token - For Socket Mode (App-Level Tokens in Slack App settings)
+# SLACK_APP_TOKEN=xapp-...
+
+# Slack allowed users (comma-separated Slack user IDs)
+# SLACK_ALLOWED_USERS=
+
+# =============================================================================
+# TELEGRAM INTEGRATION
+# =============================================================================
+# Telegram Bot Token - From @BotFather (https://t.me/BotFather)
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_ALLOWED_USERS=                  # Comma-separated user IDs
+# TELEGRAM_HOME_CHANNEL=                   # Default chat for cron delivery
+# TELEGRAM_HOME_CHANNEL_NAME=              # Display name for home channel
+
+# Webhook mode (optional — for cloud deployments like Fly.io/Railway)
+# Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode.
+# TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
+# TELEGRAM_WEBHOOK_PORT=8443
+# TELEGRAM_WEBHOOK_SECRET=                 # Recommended for production
+
+# WhatsApp (built-in Baileys bridge — run `hermes whatsapp` to pair)
+# WHATSAPP_ENABLED=false
+# WHATSAPP_ALLOWED_USERS=15551234567
+
+# Email (IMAP/SMTP — send and receive emails as Hermes)
+# For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords
+# EMAIL_ADDRESS=hermes@gmail.com
+# EMAIL_PASSWORD=xxxx xxxx xxxx xxxx
+# EMAIL_IMAP_HOST=imap.gmail.com
+# EMAIL_IMAP_PORT=993
+# EMAIL_SMTP_HOST=smtp.gmail.com
+# EMAIL_SMTP_PORT=587
+# EMAIL_POLL_INTERVAL=15
+# EMAIL_ALLOWED_USERS=your@email.com
+# EMAIL_HOME_ADDRESS=your@email.com
+
+# Gateway-wide: allow ALL users without an allowlist (default: false = deny)
+# Only set to true if you intentionally want open access.
+# GATEWAY_ALLOW_ALL_USERS=false
+
+# =============================================================================
+# RESPONSE PACING
+# =============================================================================
+# Human-like delays between message chunks on messaging platforms.
+# Makes the bot feel less robotic.
+# HERMES_HUMAN_DELAY_MODE=off     # off | natural | custom
+# HERMES_HUMAN_DELAY_MIN_MS=800   # Min delay in ms (custom mode)
+# HERMES_HUMAN_DELAY_MAX_MS=2500  # Max delay in ms (custom mode)
+
+# =============================================================================
+# DEBUG OPTIONS
+# =============================================================================
+WEB_TOOLS_DEBUG=false
+VISION_TOOLS_DEBUG=false
+MOA_TOOLS_DEBUG=false
+IMAGE_TOOLS_DEBUG=false
+
+# =============================================================================
+# CONTEXT COMPRESSION (Auto-shrinks long conversations)
+# =============================================================================
+# When conversation approaches model's context limit, middle turns are
+# automatically summarized to free up space.
+#
+# Context compression is configured in ~/.hermes/config.yaml under compression:
+# CONTEXT_COMPRESSION_ENABLED=true        # Enable auto-compression (default: true)
+# CONTEXT_COMPRESSION_THRESHOLD=0.85      # Compress at 85% of context limit
+# Model is set via compression.summary_model in config.yaml (default: google/gemini-3-flash-preview)
+
+# =============================================================================
+# SKILLS HUB (GitHub integration for skill search/install/publish)
+# =============================================================================
+
+# GitHub Personal Access Token — for higher API rate limits on skill search/install
+# Get at: https://github.com/settings/tokens (Fine-grained recommended)
+# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+
+# GitHub App credentials (optional — for bot identity on PRs)
+# GITHUB_APP_ID=
+# GITHUB_APP_PRIVATE_KEY_PATH=
+# GITHUB_APP_INSTALLATION_ID=
+
+# Groq API key (free tier — used for Whisper STT in voice mode)
+# GROQ_API_KEY=
+
+# =============================================================================
+# STT PROVIDER SELECTION
+# =============================================================================
+# Default STT provider is "local" (faster-whisper) — runs on your machine, no API key needed.
+# Install with: pip install faster-whisper
+# Model downloads automatically on first use (~150 MB for "base").
+# To use cloud providers instead, set GROQ_API_KEY or VOICE_TOOLS_OPENAI_KEY above.
+# Provider priority: local > groq > openai
+# Configure in config.yaml: stt.provider: local | groq | openai
+
+# =============================================================================
+# STT ADVANCED OVERRIDES (optional)
+# =============================================================================
+# Override default STT models per provider (normally set via stt.model in config.yaml)
+# STT_GROQ_MODEL=whisper-large-v3-turbo
+# STT_OPENAI_MODEL=whisper-1
+
+# Override STT provider endpoints (for proxies or self-hosted instances)
+# GROQ_BASE_URL=https://api.groq.com/openai/v1
+# STT_OPENAI_BASE_URL=https://api.openai.com/v1
+
+# =============================================================================
+# MICROSOFT TEAMS INTEGRATION
+# =============================================================================
+# Register a Bot in Azure: https://dev.botframework.com/ → "Register a bot"
+# Or use Azure Portal: Azure Active Directory → App registrations → New registration
+# Then add the bot to Teams via the Bot Framework or App Studio.
+#
+# TEAMS_CLIENT_ID=                     # Azure AD App (client) ID
+# TEAMS_CLIENT_SECRET=                 # Azure AD client secret value
+# TEAMS_TENANT_ID=                     # Azure AD tenant ID (or "common" for multi-tenant)
+# TEAMS_ALLOWED_USERS=                 # Comma-separated AAD object IDs or UPNs
+# TEAMS_ALLOW_ALL_USERS=false          # Set true to skip the allowlist
+# TEAMS_HOME_CHANNEL=                  # Default channel/chat ID for cron delivery
+# TEAMS_HOME_CHANNEL_NAME=             # Display name for the home channel
+# TEAMS_PORT=3978                      # Webhook listen port (Bot Framework default)
+
+# =============================================================================
+# GOOGLE CHAT INTEGRATION
+# =============================================================================
+# Connects via Cloud Pub/Sub pull subscription (no public URL required).
+# Setup walkthrough: website/docs/user-guide/messaging/google_chat.md.
+# 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub.
+# 2. Create a Service Account with roles/pubsub.subscriber on the
+#    subscription (NOT project-wide); download the JSON key.
+# 3. Configure your Chat app at console.cloud.google.com/apis/credentials
+#    → Google Chat API → Configuration → Cloud Pub/Sub topic.
+# 4. (Optional, for native attachment delivery) Each user runs
+#    `/setup-files` once in their own DM after Pub/Sub is wired up.
+#
+# GOOGLE_CHAT_PROJECT_ID=                       # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT)
+# GOOGLE_CHAT_SUBSCRIPTION_NAME=                # Full path: projects/<id>/subscriptions/<name>
+# GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=             # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS)
+# GOOGLE_CHAT_ALLOWED_USERS=                    # Comma-separated emails allowed to talk to the bot
+# GOOGLE_CHAT_ALLOW_ALL_USERS=false             # Set true to skip the allowlist
+# GOOGLE_CHAT_HOME_CHANNEL=                     # Default space (spaces/XXXX) for cron delivery
+# GOOGLE_CHAT_HOME_CHANNEL_NAME=                # Display name for the home channel

reference/hermes-agent-2026.5.16/.envrc

@@ -0,0 +1,5 @@
+watch_file pyproject.toml uv.lock
+watch_file ui-tui/package-lock.json ui-tui/package.json
+watch_file flake.nix flake.lock nix/devShell.nix nix/tui.nix nix/package.nix nix/python.nix
+
+use flake

reference/hermes-agent-2026.5.16/.gitattributes

@@ -0,0 +1,2 @@
+# Auto-generated files — collapse diffs and exclude from language stats
+web/package-lock.json linguist-generated=true

reference/hermes-agent-2026.5.16/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,162 @@
+name: "🐛 Bug Report"
+description: Report a bug — something that's broken, crashes, or behaves incorrectly.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the sections below so we can reproduce and fix it quickly.
+
+        **Before submitting**, please:
+        - [ ] Search [existing issues](https://github.com/NousResearch/hermes-agent/issues) to avoid duplicates
+        - [ ] Update to the latest version (`hermes update`) and confirm the bug still exists
+        - [ ] Run `hermes debug share` and paste the links below (see Debug Report section)
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of what's broken. Include error messages, tracebacks, or screenshots if relevant.
+      placeholder: |
+        What happened? What did you expect to happen instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal steps to trigger the bug. The more specific, the faster we can fix it.
+      placeholder: |
+        1. Run `hermes chat`
+        2. Send the message "..."
+        3. Agent calls tool X
+        4. Error appears: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include full error output if available.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Affected Component
+      description: Which part of Hermes is affected?
+      multiple: true
+      options:
+        - CLI (interactive chat)
+        - Gateway (Telegram/Discord/Slack/WhatsApp)
+        - Setup / Installation
+        - Tools (terminal, file ops, web, code execution, etc.)
+        - Skills (skill loading, skill hub, skill guard)
+        - Agent Core (conversation loop, context compression, memory)
+        - Configuration (config.yaml, .env, hermes setup)
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Messaging Platform (if gateway-related)
+      description: Which platform adapter is affected?
+      multiple: true
+      options:
+        - N/A (CLI only)
+        - Telegram
+        - Discord
+        - Slack
+        - WhatsApp
+
+  - type: textarea
+    id: debug-report
+    attributes:
+      label: Debug Report
+      description: |
+        Run `hermes debug share` from your terminal and paste the links it prints here.
+        This uploads your system info, config, and recent logs to a paste service automatically.
+
+        If you're in an interactive chat session, you can also use the `/debug` slash command — it does the same thing.
+
+        If the upload fails, run `hermes debug share --local` and paste the output directly.
+      placeholder: |
+        Report   https://paste.rs/abc123
+        agent.log   https://paste.rs/def456
+        gateway.log   https://paste.rs/ghi789
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: e.g. Ubuntu 24.04, macOS 15.2, Windows 11
+      placeholder: Ubuntu 24.04
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Output of `python --version`
+      placeholder: "3.11.9"
+
+  - type: input
+    id: hermes-version
+    attributes:
+      label: Hermes Version
+      description: Output of `hermes version`
+      placeholder: "2.1.0"
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Additional Logs / Traceback (optional)
+      description: |
+        The debug report above covers most logs. Use this field for any extra error output, 
+        tracebacks, or screenshots not captured by `hermes debug share`.
+      render: shell
+
+  - type: textarea
+    id: root-cause
+    attributes:
+      label: Root Cause Analysis (optional)
+      description: |
+        If you've dug into the code and identified the root cause, share it here.
+        Include file paths, line numbers, and code snippets if possible. This massively speeds up fixes.
+      placeholder: |
+        The bug is in `gateway/run.py` line 949. `len(history)` counts session_meta entries
+        but `agent_messages` was built from filtered history...
+
+  - type: textarea
+    id: proposed-fix
+    attributes:
+      label: Proposed Fix (optional)
+      description: If you have a fix in mind (or a PR ready), describe it here.
+      placeholder: |
+        Replace `.get()` with `.pop()` on line 289 of `gateway/platforms/base.py`
+        to actually clear the pending message after retrieval.
+
+  - type: checkboxes
+    id: pr-ready
+    attributes:
+      label: Are you willing to submit a PR for this?
+      options:
+        - label: I'd like to fix this myself and submit a PR

reference/hermes-agent-2026.5.16/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 💬 Nous Research Discord
+    url: https://discord.gg/NousResearch
+    about: For quick questions, showcasing projects, sharing skills, and community chat.
+  - name: 📖 Documentation
+    url: https://github.com/NousResearch/hermes-agent/blob/main/README.md
+    about: Check the README and docs before opening an issue.
+  - name: 🤝 Contributing Guide
+    url: https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md
+    about: Read this before submitting a PR.

reference/hermes-agent-2026.5.16/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,85 @@
+name: "✨ Feature Request"
+description: Suggest a new feature or improvement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion! Before submitting, please consider:
+
+        - **Is this a new skill?** Most capabilities should be [skills, not tools](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#should-it-be-a-skill-or-a-tool). If it's a specialized integration (crypto, NFT, niche SaaS), it belongs on the Skills Hub, not bundled.
+        - **Search [existing issues](https://github.com/NousResearch/hermes-agent/issues)** — someone may have already proposed this.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or Use Case
+      description: What problem does this solve? What are you trying to do that you can't today?
+      placeholder: |
+        I'm trying to use Hermes with [provider/platform/workflow] but currently
+        there's no way to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How do you think this should work? Be as specific as you can — CLI flags, config options, UI behavior.
+      placeholder: |
+        Add a `--foo` flag to `hermes chat` that enables...
+        Or: Add a config key `bar.baz` that controls...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What other approaches did you consider? Why is the proposed solution better?
+
+  - type: dropdown
+    id: type
+    attributes:
+      label: Feature Type
+      options:
+        - New tool
+        - New bundled skill
+        - CLI improvement
+        - Gateway / messaging improvement
+        - Configuration option
+        - Performance / reliability
+        - Developer experience (tests, docs, CI)
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: How big is this change?
+      options:
+        - Small (single file, < 50 lines)
+        - Medium (few files, < 300 lines)
+        - Large (new module or significant refactor)
+
+  - type: checkboxes
+    id: pr-ready
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd like to implement this myself and submit a PR
+
+  - type: textarea
+    id: debug-report
+    attributes:
+      label: Debug Report (optional)
+      description: |
+        If this feature request is related to a problem you're experiencing, run `hermes debug share` and paste the links here.
+        In an interactive chat session, you can use `/debug` instead.
+        This helps us understand your environment and any related logs.
+      placeholder: |
+        Report   https://paste.rs/abc123
+      render: shell

reference/hermes-agent-2026.5.16/.github/ISSUE_TEMPLATE/setup_help.yml

@@ -0,0 +1,112 @@
+name: "🔧 Setup / Installation Help"
+description: Having trouble installing or configuring Hermes? Ask here.
+title: "[Setup]: "
+labels: ["setup"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Sorry you're having trouble! Please fill out the details below so we can help.
+
+        **Quick checks first:**
+        - Run `hermes debug share` and paste the links in the Debug Report section below
+        - If you're in a chat session, you can use `/debug` instead — it does the same thing
+        - Try `hermes update` to get the latest version
+        - Check the [README troubleshooting section](https://github.com/NousResearch/hermes-agent#troubleshooting)
+        - For general questions, consider the [Nous Research Discord](https://discord.gg/NousResearch) for faster help
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What's Going Wrong?
+      description: Describe what you're trying to do and where it fails.
+      placeholder: |
+        I ran `hermes setup` and selected Nous Portal, but when I try to
+        start the gateway I get...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps Taken
+      description: What did you do? Include the exact commands you ran.
+      placeholder: |
+        1. Ran the install script: `curl -fsSL ... | bash`
+        2. Ran `hermes setup` and chose "Quick setup"
+        3. Selected OpenRouter, entered API key
+        4. Ran `hermes chat` and got error...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation Method
+      options:
+        - Install script (curl | bash)
+        - Manual clone + pip/uv install
+        - PowerShell installer (Windows)
+        - Docker
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: Ubuntu 24.04 / macOS 15.2 / Windows 11
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Output of `python --version` (or `python3 --version`)
+      placeholder: "3.11.9"
+
+  - type: input
+    id: hermes-version
+    attributes:
+      label: Hermes Version
+      description: Output of `hermes version` (if install got that far)
+      placeholder: "2.1.0"
+
+  - type: textarea
+    id: debug-report
+    attributes:
+      label: Debug Report
+      description: |
+        Run `hermes debug share` from your terminal and paste the links it prints here.
+        This uploads your system info, config, and recent logs to a paste service automatically.
+
+        If you're in an interactive chat session, you can also use the `/debug` slash command — it does the same thing.
+
+        If the upload fails or install didn't get that far, run `hermes debug share --local` and paste the output directly.
+        If even that doesn't work, run `hermes doctor` and paste that output instead.
+      placeholder: |
+        Report   https://paste.rs/abc123
+        agent.log   https://paste.rs/def456
+        gateway.log   https://paste.rs/ghi789
+      render: shell
+
+  - type: textarea
+    id: error-output
+    attributes:
+      label: Full Error Output
+      description: Paste the complete error message or traceback. This will be auto-formatted.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: tried
+    attributes:
+      label: What I've Already Tried
+      description: List any fixes or workarounds you've already attempted.
+      placeholder: |
+        - Ran `hermes update`
+        - Tried reinstalling with `pip install -e ".[all]"`
+        - Checked that OPENROUTER_API_KEY is set in ~/.hermes/.env

reference/hermes-agent-2026.5.16/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,75 @@
+## What does this PR do?
+
+<!-- Describe the change clearly. What problem does it solve? Why is this approach the right one? -->
+
+
+
+## Related Issue
+
+<!-- Link the issue this PR addresses. If no issue exists, consider creating one first. -->
+
+Fixes #
+
+## Type of Change
+
+<!-- Check the one that applies. -->
+
+- [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] 🔒 Security fix
+- [ ] 📝 Documentation update
+- [ ] ✅ Tests (adding or improving test coverage)
+- [ ] ♻️ Refactor (no behavior change)
+- [ ] 🎯 New skill (bundled or hub)
+
+## Changes Made
+
+<!-- List the specific changes. Include file paths for code changes. -->
+
+- 
+
+## How to Test
+
+<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->
+
+1. 
+2. 
+3. 
+
+## Checklist
+
+<!-- Complete these before requesting review. -->
+
+### Code
+
+- [ ] I've read the [Contributing Guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md)
+- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`fix(scope):`, `feat(scope):`, etc.)
+- [ ] I searched for [existing PRs](https://github.com/NousResearch/hermes-agent/pulls) to make sure this isn't a duplicate
+- [ ] My PR contains **only** changes related to this fix/feature (no unrelated commits)
+- [ ] I've run `pytest tests/ -q` and all tests pass
+- [ ] I've added tests for my changes (required for bug fixes, strongly encouraged for features)
+- [ ] I've tested on my platform: <!-- e.g. Ubuntu 24.04, macOS 15.2, Windows 11 -->
+
+### Documentation & Housekeeping
+
+<!-- Check all that apply. It's OK to check "N/A" if a category doesn't apply to your change. -->
+
+- [ ] I've updated relevant documentation (README, `docs/`, docstrings) — or N/A
+- [ ] I've updated `cli-config.yaml.example` if I added/changed config keys — or N/A
+- [ ] I've updated `CONTRIBUTING.md` or `AGENTS.md` if I changed architecture or workflows — or N/A
+- [ ] I've considered cross-platform impact (Windows, macOS) per the [compatibility guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#cross-platform-compatibility) — or N/A
+- [ ] I've updated tool descriptions/schemas if I changed tool behavior — or N/A
+
+## For New Skills
+
+<!-- Only fill this out if you're adding a skill. Delete this section otherwise. -->
+
+- [ ] This skill is **broadly useful** to most users (if bundled) — see [Contributing Guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#should-the-skill-be-bundled)
+- [ ] SKILL.md follows the [standard format](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#skillmd-format) (frontmatter, trigger conditions, steps, pitfalls)
+- [ ] No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
+- [ ] I've tested the skill end-to-end: `hermes --toolsets skills -q "Use the X skill to do Y"`
+
+## Screenshots / Logs
+
+<!-- If applicable, add screenshots or log output showing the fix/feature in action. -->
+

reference/hermes-agent-2026.5.16/.github/actions/hermes-smoke-test/action.yml

@@ -0,0 +1,47 @@
+name: Hermes smoke test
+description: >
+  Run the image's built-in entrypoint against `--help` and `dashboard --help`
+  to catch basic runtime regressions before publishing.  Requires the image
+  to already be loaded into the local Docker daemon under `image`.
+
+  Works identically on amd64 and arm64 runners.
+
+inputs:
+  image:
+    description: Fully-qualified image tag (e.g. nousresearch/hermes-agent:test)
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Ensure /tmp/hermes-test is hermes-writable
+      shell: bash
+      run: |
+        # The image runs as the hermes user (UID 10000).  GitHub Actions
+        # creates /tmp/hermes-test root-owned by default, which hermes
+        # can't write to — chown it to match the in-container UID before
+        # bind-mounting.  Real users doing `docker run -v ~/.hermes:...`
+        # with their own UID hit the same issue and have their own
+        # remediations (HERMES_UID env var, or chown locally).
+        mkdir -p /tmp/hermes-test
+        sudo chown -R 10000:10000 /tmp/hermes-test
+
+    - name: hermes --help
+      shell: bash
+      run: |
+        docker run --rm \
+          -v /tmp/hermes-test:/opt/data \
+          --entrypoint /opt/hermes/docker/entrypoint.sh \
+          "${{ inputs.image }}" --help
+
+    - name: hermes dashboard --help
+      shell: bash
+      run: |
+        # Regression guard for #9153: dashboard was present in source but
+        # missing from the published image.  If this fails, something in
+        # the Dockerfile is excluding the dashboard subcommand from the
+        # installed package.
+        docker run --rm \
+          -v /tmp/hermes-test:/opt/data \
+          --entrypoint /opt/hermes/docker/entrypoint.sh \
+          "${{ inputs.image }}" dashboard --help

reference/hermes-agent-2026.5.16/.github/actions/nix-setup/action.yml

@@ -0,0 +1,18 @@
+name: 'Setup Nix'
+description: 'Install Nix and configure Cachix binary cache'
+
+inputs:
+  cachix-auth-token:
+    description: 'Cachix auth token (enables push). Omit for read-only.'
+    required: false
+    default: ''
+
+runs:
+  using: composite
+  steps:
+    - uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+    - uses: cachix/cachix-action@1eb2ef646ac0255473d23a5907ad7b04ce94065c # v17
+      with:
+        name: hermes-agent
+        authToken: ${{ inputs.cachix-auth-token }}
+      continue-on-error: true

reference/hermes-agent-2026.5.16/.github/dependabot.yml

@@ -0,0 +1,44 @@
+# Dependabot configuration for hermes-agent.
+#
+# Deliberately scoped to github-actions only.
+#
+# We do NOT enable Dependabot for pip / npm / any source-dependency ecosystem
+# because we pin source dependencies exactly (uv.lock, package-lock.json) as
+# part of our supply-chain posture. Automatic version-bump PRs against those
+# pins would undermine the strategy — pins are moved deliberately, after
+# review, not on a schedule.
+#
+# github-actions is the exception: action pins (we use full commit SHAs per
+# supply-chain policy) must be updated when upstream actions publish
+# patches — usually themselves security fixes. Dependabot opens a PR with
+# the new SHA and release notes; we review and merge like any other PR.
+#
+# Security-update PRs for source dependencies (opened ONLY when a CVE is
+# published affecting a currently-pinned version) are enabled separately
+# via the repo's Dependabot security updates setting
+# (Settings → Code security → Dependabot → Dependabot security updates).
+# Those are CVE-only, not schedule-driven, and do not conflict with our
+# pinning strategy — they fire when a pinned version becomes known-bad,
+# which is exactly when we want to move the pin.
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(actions)"
+      include: "scope"
+    groups:
+      # Batch routine action bumps into one PR per week to reduce noise.
+      # Security updates still open individually and bypass grouping.
+      actions-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"

reference/hermes-agent-2026.5.16/.github/workflows/contributor-check.yml

@@ -0,0 +1,73 @@
+name: Contributor Attribution Check
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      # Only run when code files change (not docs-only PRs)
+      - '*.py'
+      - '**/*.py'
+      - '.github/workflows/contributor-check.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  check-attribution:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0  # Full history needed for git log
+
+      - name: Check for unmapped contributor emails
+        run: |
+          # Get the merge base between this PR and main
+          MERGE_BASE=$(git merge-base origin/main HEAD)
+
+          # Find any new author emails in this PR's commits
+          NEW_EMAILS=$(git log ${MERGE_BASE}..HEAD --format='%ae' --no-merges | sort -u)
+
+          if [ -z "$NEW_EMAILS" ]; then
+            echo "No new commits to check."
+            exit 0
+          fi
+
+          # Check each email against AUTHOR_MAP in release.py
+          MISSING=""
+          while IFS= read -r email; do
+            # Skip teknium and bot emails
+            case "$email" in
+              *teknium*|*noreply@github.com*|*dependabot*|*github-actions*|*anthropic.com*|*cursor.com*)
+                continue ;;
+            esac
+
+            # Check if email is in AUTHOR_MAP (either as a key or matches noreply pattern)
+            if echo "$email" | grep -qP '\+.*@users\.noreply\.github\.com'; then
+              continue  # GitHub noreply emails auto-resolve
+            fi
+
+            if ! grep -qF "\"${email}\"" scripts/release.py 2>/dev/null; then
+              AUTHOR=$(git log --author="$email" --format='%an' -1)
+              MISSING="${MISSING}\n  ${email} (${AUTHOR})"
+            fi
+          done <<< "$NEW_EMAILS"
+
+          if [ -n "$MISSING" ]; then
+            echo ""
+            echo "⚠️  New contributor email(s) not in AUTHOR_MAP:"
+            echo -e "$MISSING"
+            echo ""
+            echo "Please add mappings to scripts/release.py AUTHOR_MAP:"
+            echo -e "$MISSING" | while read -r line; do
+              email=$(echo "$line" | sed 's/^ *//' | cut -d' ' -f1)
+              [ -z "$email" ] && continue
+              echo "    \"${email}\": \"<github-username>\","
+            done
+            echo ""
+            echo "To find the GitHub username for an email:"
+            echo "  gh api 'search/users?q=EMAIL+in:email' --jq '.items[0].login'"
+            exit 1
+          else
+            echo "✅ All contributor emails are mapped in AUTHOR_MAP."
+          fi

reference/hermes-agent-2026.5.16/.github/workflows/deploy-site.yml

@@ -0,0 +1,97 @@
+name: Deploy Site
+
+on:
+  release:
+    types: [published]
+  push:
+    branches: [main]
+    paths:
+      - 'website/**'
+      - 'skills/**'
+      - 'optional-skills/**'
+      - '.github/workflows/deploy-site.yml'
+  workflow_dispatch:
+
+permissions:
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy-vercel:
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Vercel Deploy
+        run: curl -X POST "${{ secrets.VERCEL_DEPLOY_HOOK }}"
+
+  deploy-docs:
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.11'
+
+      - name: Install PyYAML for skill extraction
+        run: pip install pyyaml==6.0.2 httpx==0.28.1
+
+      - name: Extract skill metadata for dashboard
+        run: python3 website/scripts/extract-skills.py
+
+      - name: Regenerate per-skill docs pages + catalogs
+        run: python3 website/scripts/generate-skill-docs.py
+
+      - name: Build skills index (if not already present)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if [ ! -f website/static/api/skills-index.json ]; then
+            python3 scripts/build_skills_index.py || echo "Skills index build failed (non-fatal)"
+          fi
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: website
+
+      - name: Build Docusaurus
+        run: npm run build
+        working-directory: website
+
+      - name: Stage deployment
+        run: |
+          mkdir -p _site/docs
+          cp -r website/build/* _site/docs/
+          # llms.txt / llms-full.txt are also published at the site root
+          # (https://hermes-agent.nousresearch.com/llms.txt) because some
+          # agents and IDE plugins probe the classic root-level path rather
+          # than /docs/llms.txt. Same file, two URLs, one source of truth.
+          if [ -f website/build/llms.txt ]; then
+            cp website/build/llms.txt _site/llms.txt
+          fi
+          if [ -f website/build/llms-full.txt ]; then
+            cp website/build/llms-full.txt _site/llms-full.txt
+          fi
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa  # v3
+        with:
+          path: _site
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4

reference/hermes-agent-2026.5.16/.github/workflows/docker-publish.yml

@@ -0,0 +1,534 @@
+name: Docker Build and Publish
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**/*.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'Dockerfile'
+      - 'docker/**'
+      - '.github/workflows/docker-publish.yml'
+      - '.github/actions/hermes-smoke-test/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - '**/*.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'Dockerfile'
+      - 'docker/**'
+      - '.github/workflows/docker-publish.yml'
+      - '.github/actions/hermes-smoke-test/**'
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+# Concurrency: push/release runs are NEVER cancelled so every merge gets its
+# own SHA-tagged image; :main and :latest are guarded separately by the
+# move-main and move-latest jobs.  PR runs reuse a PR-scoped group with
+# cancel-in-progress: true so rapid pushes to the same PR collapse to the
+# latest commit.
+concurrency:
+  group: docker-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  IMAGE_NAME: nousresearch/hermes-agent
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Build amd64 natively.  This job also runs the smoke tests (basic --help
+  # and the dashboard subcommand regression guard from #9153), because amd64
+  # is the only arch we can `load` into the local daemon on an amd64 runner.
+  # ---------------------------------------------------------------------------
+  build-amd64:
+    # Only run on the upstream repository, not on forks
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    outputs:
+      digest: ${{ steps.push.outputs.digest }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          submodules: recursive
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+
+      # Build once, load into the local daemon for smoke testing.  Cached
+      # to gha with a per-arch scope; the push step below reuses every
+      # layer from this build.
+      - name: Build image (amd64, smoke test)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+        with:
+          context: .
+          file: Dockerfile
+          load: true
+          platforms: linux/amd64
+          tags: ${{ env.IMAGE_NAME }}:test
+          cache-from: type=gha,scope=docker-amd64
+          cache-to: type=gha,mode=max,scope=docker-amd64
+
+      - name: Smoke test image
+        uses: ./.github/actions/hermes-smoke-test
+        with:
+          image: ${{ env.IMAGE_NAME }}:test
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Push amd64 by digest only (no tag).  The merge job assembles the
+      # tagged manifest list.  `push-by-digest=true` is docker's recommended
+      # pattern for multi-runner multi-platform builds.
+      #
+      # We apply the OCI revision label here (and again on arm64) because
+      # the move-main / move-latest jobs read it off the linux/amd64
+      # sub-manifest config of the floating tag to decide whether it's safe
+      # to advance.  The label must be on each per-arch image — manifest
+      # lists themselves don't carry image config labels.
+      - name: Push amd64 by digest
+        id: push
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+        with:
+          context: .
+          file: Dockerfile
+          platforms: linux/amd64
+          labels: |
+            org.opencontainers.image.revision=${{ github.sha }}
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=docker-amd64
+          cache-to: type=gha,mode=max,scope=docker-amd64
+
+      # Write the digest to a file and upload it as an artifact so the
+      # merge job can stitch both per-arch digests into a manifest list.
+      - name: Export digest
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.push.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: digest-amd64
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  # ---------------------------------------------------------------------------
+  # Build arm64 natively on GitHub's free arm64 runner.  This replaces the
+  # previous QEMU-emulated arm64 build, which was ~5-10x slower and shared
+  # a cache scope with amd64.  Matches the amd64 job's shape: build+load,
+  # smoke test, then on push/release push by digest.
+  # ---------------------------------------------------------------------------
+  build-arm64:
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 45
+    outputs:
+      digest: ${{ steps.push.outputs.digest }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          submodules: recursive
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+
+      # Build once, load into the local daemon for smoke testing.  Cached
+      # to gha with a per-arch scope; the push step below reuses every
+      # layer from this build.
+      - name: Build image (arm64, smoke test)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+        with:
+          context: .
+          file: Dockerfile
+          load: true
+          platforms: linux/arm64
+          tags: ${{ env.IMAGE_NAME }}:test
+          cache-from: type=gha,scope=docker-arm64
+          cache-to: type=gha,mode=max,scope=docker-arm64
+
+      - name: Smoke test image
+        uses: ./.github/actions/hermes-smoke-test
+        with:
+          image: ${{ env.IMAGE_NAME }}:test
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Push arm64 by digest
+        id: push
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+        with:
+          context: .
+          file: Dockerfile
+          platforms: linux/arm64
+          labels: |
+            org.opencontainers.image.revision=${{ github.sha }}
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=docker-arm64
+          cache-to: type=gha,mode=max,scope=docker-arm64
+
+      - name: Export digest
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.push.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: digest-arm64
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  # ---------------------------------------------------------------------------
+  # Stitch both per-arch digests into a single tagged multi-arch manifest.
+  # This is a registry-side operation — no building, no layer re-push —
+  # so it runs in ~30 seconds.  On main pushes it produces :sha-<sha>.
+  # On releases it produces :<release_tag_name>.
+  # ---------------------------------------------------------------------------
+  merge:
+    if: github.repository == 'NousResearch/hermes-agent' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release')
+    runs-on: ubuntu-latest
+    needs: [build-amd64, build-arm64]
+    timeout-minutes: 10
+    outputs:
+      pushed_sha_tag: ${{ steps.mark_pushed.outputs.pushed }}
+      pushed_release_tag: ${{ steps.mark_release_pushed.outputs.pushed }}
+      release_tag: ${{ steps.tag.outputs.tag }}
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          path: /tmp/digests
+          pattern: digest-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Compute the tag for this run.  Main pushes use sha-<sha> (so every
+      # commit gets its own immutable tag); releases use the release tag name.
+      - name: Compute tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            echo "tag=${{ github.event.release.tag_name }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=sha-${{ github.sha }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          set -euo pipefail
+          # Build the arg array from each digest file (filename = the digest
+          # hex, with no sha256: prefix; empty file content, only the name
+          # matters).  Using an array avoids shellcheck SC2046 and keeps
+          # every digest a single argv token even under pathological names.
+          args=()
+          for digest_file in *; do
+            args+=("${IMAGE_NAME}@sha256:${digest_file}")
+          done
+          docker buildx imagetools create \
+            -t "${IMAGE_NAME}:${TAG}" \
+            "${args[@]}"
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          TAG: ${{ steps.tag.outputs.tag }}
+
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect "${IMAGE_NAME}:${TAG}"
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          TAG: ${{ steps.tag.outputs.tag }}
+
+      # Signal to move-main that the SHA tag is live.  Only on main pushes;
+      # releases set pushed_release_tag instead.
+      - name: Mark SHA tag pushed
+        id: mark_pushed
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: echo "pushed=true" >> "$GITHUB_OUTPUT"
+
+      # Signal to move-latest that the release tag is live.
+      - name: Mark release tag pushed
+        id: mark_release_pushed
+        if: github.event_name == 'release'
+        run: echo "pushed=true" >> "$GITHUB_OUTPUT"
+
+  # ---------------------------------------------------------------------------
+  # Move :main to point at the SHA tag the merge job pushed.
+  #
+  # :main is the floating tag that tracks the tip of the main branch.  Every
+  # merge to main retags :main forward.  Users who want "latest dev build"
+  # pull :main; users who want stable releases pull :latest.
+  #
+  # The real serialization guarantee comes from the top-level concurrency
+  # group (`docker-${{ github.ref }}` with `cancel-in-progress: false`),
+  # which ensures at most one workflow run for this ref executes at a time.
+  # That means two move-main steps for the same ref cannot overlap.
+  #
+  # This job has its own concurrency group as defense-in-depth: if the
+  # top-level group is ever loosened, queued move-mains will run serially
+  # in arrival order, each one running the ancestor check below and either
+  # advancing :main or skipping.  `cancel-in-progress: false` matches the
+  # top-level setting — we don't want rapid pushes to cancel a queued
+  # move-main, because the ancestor check is the real safety mechanism
+  # and queueing is cheap (move-main is a ~30s registry op).
+  #
+  # Combined with the ancestor check, this means :main only ever moves
+  # forward in git history.
+  # ---------------------------------------------------------------------------
+  move-main:
+    if: |
+      github.repository == 'NousResearch/hermes-agent'
+      && github.event_name == 'push'
+      && github.ref == 'refs/heads/main'
+      && needs.merge.outputs.pushed_sha_tag == 'true'
+    needs: merge
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: docker-move-main-${{ github.ref }}
+      cancel-in-progress: false
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 1000
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Read the git revision label off the current :main manifest, then
+      # use `git merge-base --is-ancestor` to check whether our commit is a
+      # descendant of it.  If :main doesn't exist yet, or its label is
+      # missing, we treat that as "safe to publish".  If another run already
+      # advanced :main past us (or diverged), we skip and leave it alone.
+      - name: Decide whether to move :main
+        id: main_check
+        run: |
+          set -euo pipefail
+          image=nousresearch/hermes-agent
+
+          # Pull the JSON for the linux/amd64 sub-manifest's config and extract
+          # the OCI revision label with jq — Go template field access can't
+          # handle dots in map keys, so using json+jq is the robust route.
+          image_json=$(
+            docker buildx imagetools inspect "${image}:main" \
+              --format '{{ json (index .Image "linux/amd64") }}' \
+              2>/dev/null || true
+          )
+
+          if [ -z "${image_json}" ]; then
+            echo "No existing :main (or inspect failed) — safe to publish."
+            echo "push_main=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          current_sha=$(
+            printf '%s' "${image_json}" \
+              | jq -r '.config.Labels."org.opencontainers.image.revision" // ""'
+          )
+
+          if [ -z "${current_sha}" ]; then
+            echo "Registry :main has no revision label — safe to publish."
+            echo "push_main=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "Registry :main is at ${current_sha}"
+          echo "This run is at      ${GITHUB_SHA}"
+
+          if [ "${current_sha}" = "${GITHUB_SHA}" ]; then
+            echo ":main already points at our SHA — nothing to do."
+            echo "push_main=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Make sure we have the :main commit locally for merge-base.
+          if ! git cat-file -e "${current_sha}^{commit}" 2>/dev/null; then
+            git fetch --no-tags --prune origin \
+              "+refs/heads/main:refs/remotes/origin/main" \
+              || true
+          fi
+
+          if ! git cat-file -e "${current_sha}^{commit}" 2>/dev/null; then
+            echo "Registry :main points at an unknown commit (${current_sha}); refusing to overwrite."
+            echo "push_main=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Our SHA must be a descendant of the current :main to be safe.
+          if git merge-base --is-ancestor "${current_sha}" "${GITHUB_SHA}"; then
+            echo "Our commit is a descendant of :main — safe to advance."
+            echo "push_main=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Another run advanced :main past us (or diverged) — leaving it alone."
+            echo "push_main=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Retag the already-pushed SHA manifest as :main.  This is a registry-
+      # side operation — no rebuild, no layer re-push — so it's quick and
+      # atomic per-tag.  The ancestor check above plus the cancel-in-progress
+      # concurrency on this job together guarantee we only ever move :main
+      # forward in git history.
+      - name: Move :main to this SHA
+        if: steps.main_check.outputs.push_main == 'true'
+        run: |
+          set -euo pipefail
+          image=nousresearch/hermes-agent
+          docker buildx imagetools create \
+            --tag "${image}:main" \
+            "${image}:sha-${GITHUB_SHA}"
+
+  # ---------------------------------------------------------------------------
+  # Move :latest to point at the release tag the merge job pushed.
+  #
+  # :latest is the floating tag that tracks the most recent stable release.
+  # Only `release: published` events advance it — never main pushes.
+  #
+  # We still run an ancestor check against the existing :latest so that a
+  # backport release on an older branch (e.g. patching v1.1.5 after v1.2.3
+  # is out) doesn't drag :latest backwards.  The check is the same shape as
+  # move-main: read the OCI revision label off the current :latest, look up
+  # that commit in git, and only advance if our release commit is a strict
+  # descendant.
+  # ---------------------------------------------------------------------------
+  move-latest:
+    if: |
+      github.repository == 'NousResearch/hermes-agent'
+      && github.event_name == 'release'
+      && needs.merge.outputs.pushed_release_tag == 'true'
+    needs: merge
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: docker-move-latest
+      cancel-in-progress: false
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 1000
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Decide whether to move :latest
+        id: latest_check
+        run: |
+          set -euo pipefail
+          image=nousresearch/hermes-agent
+
+          image_json=$(
+            docker buildx imagetools inspect "${image}:latest" \
+              --format '{{ json (index .Image "linux/amd64") }}' \
+              2>/dev/null || true
+          )
+
+          if [ -z "${image_json}" ]; then
+            echo "No existing :latest (or inspect failed) — safe to publish."
+            echo "push_latest=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          current_sha=$(
+            printf '%s' "${image_json}" \
+              | jq -r '.config.Labels."org.opencontainers.image.revision" // ""'
+          )
+
+          if [ -z "${current_sha}" ]; then
+            echo "Registry :latest has no revision label — safe to publish."
+            echo "push_latest=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "Registry :latest is at ${current_sha}"
+          echo "This release is at  ${GITHUB_SHA}"
+
+          if [ "${current_sha}" = "${GITHUB_SHA}" ]; then
+            echo ":latest already points at our SHA — nothing to do."
+            echo "push_latest=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Make sure we have the :latest commit locally for merge-base.
+          # Releases can be cut from any branch, so fetch broadly.
+          if ! git cat-file -e "${current_sha}^{commit}" 2>/dev/null; then
+            git fetch --no-tags --prune origin \
+              "+refs/heads/main:refs/remotes/origin/main" \
+              || true
+          fi
+
+          if ! git cat-file -e "${current_sha}^{commit}" 2>/dev/null; then
+            echo "Registry :latest points at an unknown commit (${current_sha}); refusing to overwrite."
+            echo "push_latest=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Our release SHA must be a descendant of the current :latest.
+          # Backport releases on older branches won't satisfy this and will
+          # be left alone — :latest stays on the newer release.
+          if git merge-base --is-ancestor "${current_sha}" "${GITHUB_SHA}"; then
+            echo "Our release commit is a descendant of :latest — safe to advance."
+            echo "push_latest=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Existing :latest is newer than this release (likely a backport) — leaving it alone."
+            echo "push_latest=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Retag the already-pushed release manifest as :latest.
+      - name: Move :latest to this release tag
+        if: steps.latest_check.outputs.push_latest == 'true'
+        env:
+          RELEASE_TAG: ${{ needs.merge.outputs.release_tag }}
+        run: |
+          set -euo pipefail
+          image=nousresearch/hermes-agent
+          docker buildx imagetools create \
+            --tag "${image}:latest" \
+            "${image}:${RELEASE_TAG}"

reference/hermes-agent-2026.5.16/.github/workflows/docs-site-checks.yml

@@ -0,0 +1,48 @@
+name: Docs Site Checks
+
+on:
+  pull_request:
+    paths:
+      - 'website/**'
+      - '.github/workflows/docs-site-checks.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs-site-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install website dependencies
+        run: npm ci
+        working-directory: website
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.11'
+
+      - name: Install ascii-guard
+        run: python -m pip install ascii-guard==2.3.0 pyyaml==6.0.3
+
+      - name: Extract skill metadata for dashboard
+        run: python3 website/scripts/extract-skills.py
+
+      - name: Regenerate per-skill docs pages + catalogs
+        run: python3 website/scripts/generate-skill-docs.py
+
+      - name: Lint docs diagrams
+        run: npm run lint:diagrams
+        working-directory: website
+
+      - name: Build Docusaurus
+        run: npm run build
+        working-directory: website

reference/hermes-agent-2026.5.16/.github/workflows/history-check.yml

@@ -0,0 +1,58 @@
+name: History Check
+
+# Rejects PRs whose branch has no common ancestor with main.
+#
+# In May 2026 PR #25045 was merged from a branch that had been disconnected
+# from main's history (likely an accidental `git checkout --orphan` or
+# `.git/` re-init).  GitHub's merge UI does not refuse merges of unrelated
+# histories, so the PR landed cleanly with the intended one-file change —
+# but its parent-less root commit (413990c94) got grafted into main as a
+# second root, and ~1500 files' worth of `git blame` history collapsed
+# onto that single commit.
+#
+# This check catches the failure mode by requiring `git merge-base` between
+# the PR head and main to be non-empty.
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check-common-ancestor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0  # full history both sides for merge-base
+
+      - name: Reject PRs with no common ancestor on main
+        run: |
+          # `git merge-base` exits non-zero AND prints nothing when the two
+          # commits share no ancestor.  We check both conditions explicitly
+          # so the failure message is clear regardless of which signal fires
+          # first.
+          if ! BASE=$(git merge-base origin/main HEAD 2>/dev/null) || [ -z "$BASE" ]; then
+            echo ""
+            echo "::error::This PR has no common ancestor with main."
+            echo ""
+            echo "Your branch's history is disconnected from main.  Common causes:"
+            echo "  - the branch was created with 'git checkout --orphan'"
+            echo "  - '.git/' was re-initialized at some point during the work"
+            echo "  - the branch was force-pushed from an unrelated repository"
+            echo ""
+            echo "Merging an unrelated-history PR grafts a parent-less root commit"
+            echo "into main and collapses git blame for every file in that snapshot."
+            echo "Reference: PR #25045 caused this and re-rooted blame on ~1500"
+            echo "files to a single orphan commit."
+            echo ""
+            echo "To fix, rebase your changes onto current main:"
+            echo "  git fetch origin main"
+            echo "  git checkout -b fix-branch origin/main"
+            echo "  # re-apply your changes (cherry-pick, copy files, etc.)"
+            echo "  git push -f origin fix-branch"
+            exit 1
+          fi
+          echo "::notice::Common ancestor with main: $BASE"

reference/hermes-agent-2026.5.16/.github/workflows/lint.yml

@@ -0,0 +1,202 @@
+name: Lint (ruff + ty)
+
+# Two things here:
+#   1. Advisory diff — ruff + ty diagnostics as a diff vs the target branch.
+#      Posts a Markdown summary and a PR comment. Exit zero always.
+#   2. Blocking ``ruff check .`` — enforces the explicit rules in
+#      ``[tool.ruff.lint.select]`` (currently PLW1514). Failure blocks merge.
+#      Separate job so the advisory diff still runs and posts even when
+#      enforcement fails.
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "**/*.md"
+      - "docs/**"
+      - "website/**"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "**/*.md"
+      - "docs/**"
+      - "website/**"
+
+permissions:
+  contents: read
+  pull-requests: write # needed to post/update PR comments
+
+concurrency:
+  group: lint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-diff:
+    name: ruff + ty diff
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0 # need full history for merge-base + worktree
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+
+      - name: Install ruff + ty
+        run: |
+          uv tool install ruff
+          uv tool install ty
+
+      - name: Determine base ref
+        id: base
+        run: |
+          # For PRs, diff against the merge base with the target branch.
+          # For pushes to main, diff against the previous commit on main.
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE_SHA=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
+            BASE_REF="origin/${{ github.base_ref }}"
+          else
+            BASE_SHA=$(git rev-parse HEAD~1 2>/dev/null || git rev-parse HEAD)
+            BASE_REF="HEAD~1"
+          fi
+          echo "sha=${BASE_SHA}" >> "$GITHUB_OUTPUT"
+          echo "ref=${BASE_REF}" >> "$GITHUB_OUTPUT"
+          echo "Base SHA: ${BASE_SHA}"
+          echo "Base ref: ${BASE_REF}"
+
+      - name: Run ruff + ty on HEAD
+        run: |
+          mkdir -p .lint-reports/head
+          ruff check --output-format json --exit-zero \
+            > .lint-reports/head/ruff.json || true
+          ty check --output-format gitlab --exit-zero \
+            > .lint-reports/head/ty.json || true
+          echo "HEAD ruff: $(wc -c < .lint-reports/head/ruff.json) bytes"
+          echo "HEAD ty:   $(wc -c < .lint-reports/head/ty.json) bytes"
+
+      - name: Run ruff + ty on base (via git worktree)
+        run: |
+          mkdir -p .lint-reports/base
+          # Use a worktree so we don't clobber the main checkout. If the basex
+          # SHA is identical to HEAD (e.g. first commit), skip and leave the
+          # base reports empty — the diff script handles missing files.
+          HEAD_SHA=$(git rev-parse HEAD)
+          BASE_SHA="${{ steps.base.outputs.sha }}"
+          if [ "$BASE_SHA" = "$HEAD_SHA" ]; then
+            echo "Base SHA == HEAD SHA, skipping base scan."
+            echo '[]' > .lint-reports/base/ruff.json
+            echo '[]' > .lint-reports/base/ty.json
+          else
+            git worktree add --detach /tmp/lint-base "$BASE_SHA"
+            (
+              cd /tmp/lint-base
+              ruff check --output-format json --exit-zero \
+                > "$GITHUB_WORKSPACE/.lint-reports/base/ruff.json" || true
+              ty check --output-format gitlab --exit-zero \
+                > "$GITHUB_WORKSPACE/.lint-reports/base/ty.json" || true
+            )
+            git worktree remove --force /tmp/lint-base
+          fi
+          echo "base ruff: $(wc -c < .lint-reports/base/ruff.json) bytes"
+          echo "base ty:   $(wc -c < .lint-reports/base/ty.json) bytes"
+
+      - name: Generate diff summary
+        run: |
+          python scripts/lint_diff.py \
+            --base-ruff .lint-reports/base/ruff.json \
+            --head-ruff .lint-reports/head/ruff.json \
+            --base-ty   .lint-reports/base/ty.json \
+            --head-ty   .lint-reports/head/ty.json \
+            --base-ref  "${{ steps.base.outputs.ref }}" \
+            --head-ref  "${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}" \
+            --output    .lint-reports/summary.md
+          cat .lint-reports/summary.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload reports as artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: lint-reports
+          path: .lint-reports/
+          retention-days: 14
+
+      - name: Post / update PR comment
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        continue-on-error: true
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        with:
+          script: |
+            const fs = require('fs');
+            const body = fs.readFileSync('.lint-reports/summary.md', 'utf8');
+            const marker = '<!-- lint-diff-summary -->';
+            const fullBody = marker + '\n' + body;
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo:  context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body && c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo:  context.repo.repo,
+                comment_id: existing.id,
+                body: fullBody,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo:  context.repo.repo,
+                issue_number: context.issue.number,
+                body: fullBody,
+              });
+            }
+
+
+  ruff-blocking:
+    # Enforce the rules in pyproject.toml [tool.ruff.lint.select]. Currently
+    # PLW1514 (unspecified-encoding) — catches bare ``open()`` /
+    # ``read_text()`` / ``write_text()`` calls that default to locale
+    # encoding on Windows. Failure here blocks merge; the advisory
+    # ``lint-diff`` job above runs independently so reviewers still get
+    # the diff comment even when enforcement fails.
+    name: ruff enforcement (blocking)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+
+      - name: Install ruff
+        run: uv tool install ruff
+
+      - name: ruff check .
+        # No --exit-zero, no || true. Exit code propagates to the job,
+        # which propagates to the required-check gate.
+        run: |
+          ruff check .
+
+  windows-footguns:
+    # Static guardrails on Windows-unsafe Python primitives — os.kill(pid, 0),
+    # os.killpg, os.setsid, signal.SIGKILL without getattr fallback,
+    # shebang scripts via subprocess, bare open() without encoding=, etc.
+    # See scripts/check-windows-footguns.py for the full rule list.
+    name: Windows footguns (blocking)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up Python
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5
+        with:
+          python-version: "3.11"
+
+      - name: Run footgun checker
+        run: python scripts/check-windows-footguns.py --all

reference/hermes-agent-2026.5.16/.github/workflows/nix-lockfile-fix.yml

@@ -0,0 +1,254 @@
+name: Nix Lockfile Fix
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'ui-tui/package-lock.json'
+      - 'ui-tui/package.json'
+      - 'web/package-lock.json'
+      - 'web/package.json'
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to fix (leave empty to run on the selected branch)'
+        required: false
+        type: string
+  issue_comment:
+    types: [edited]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: nix-lockfile-fix-${{ github.event.issue.number || github.event.inputs.pr_number || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # ── Auto-fix on main ───────────────────────────────────────────────
+  # Fires when a push to main touches package.json or package-lock.json
+  # in ui-tui/ or web/. Runs fix-lockfiles and pushes the hash
+  # update commit directly to main so Nix builds never stay broken.
+  #
+  # Safety invariants:
+  #   1. The fix commit only touches nix/*.nix files, which are NOT in
+  #      the paths filter above, so this cannot re-trigger itself.
+  #   2. An explicit file-whitelist check before commit aborts if
+  #      fix-lockfiles ever modifies unexpected files.
+  #   3. Job-level concurrency with cancel-in-progress: true ensures
+  #      back-to-back pushes collapse to the newest; ref: main checkout
+  #      always operates on the latest branch state.
+  #   4. Uses a GitHub App token (not GITHUB_TOKEN) so the fix commit
+  #      triggers downstream nix.yml verification.
+  auto-fix-main:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    concurrency:
+      group: auto-fix-main
+      cancel-in-progress: true
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@7bfa3a4717ef143a604ee0a99d859b8886a96d00  # v1.9.3
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: main
+          token: ${{ steps.app-token.outputs.token }}
+
+      - uses: ./.github/actions/nix-setup
+        with:
+          cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
+
+      - name: Apply lockfile hashes
+        id: apply
+        run: nix run .#fix-lockfiles -- --apply
+
+      - name: Commit & push
+        if: steps.apply.outputs.changed == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          # Ensure only nix files were modified — prevents accidental
+          # self-triggering if fix-lockfiles ever touches package files.
+          unexpected="$(git diff --name-only | grep -Ev '^nix/(tui|web)\.nix$' || true)"
+          if [ -n "$unexpected" ]; then
+            echo "::error::Unexpected modified files: $unexpected"
+            exit 1
+          fi
+
+          # Record the base SHA before committing — used to detect package
+          # file changes if we need to rebase after a non-fast-forward push.
+          BASE_SHA="$(git rev-parse HEAD)"
+
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add nix/tui.nix nix/web.nix
+          git commit -m "fix(nix): auto-refresh npm lockfile hashes" \
+            -m "Source: $GITHUB_SHA" \
+            -m "Run: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+
+          # Retry push with rebase in case main advanced with an unrelated
+          # commit during the nix build. Without this, a non-fast-forward
+          # rejection silently loses the fix. If package files changed during
+          # the rebase, abort — a fresh auto-fix run will handle the new state.
+          for attempt in 1 2 3; do
+            if git push origin HEAD:main; then
+              exit 0
+            fi
+            echo "::warning::Push attempt $attempt failed (non-fast-forward?), rebasing…"
+            git fetch origin main
+
+            # If package files changed between our base and the new main,
+            # our computed hashes are stale. Abort and let the next triggered
+            # run recompute from the correct package-lock state.
+            pkg_changed="$(git diff --name-only "$BASE_SHA"..origin/main -- \
+              'ui-tui/package-lock.json' 'ui-tui/package.json' \
+              'web/package-lock.json' 'web/package.json' || true)"
+            if [ -n "$pkg_changed" ]; then
+              echo "::warning::Package files changed since hash computation — aborting; a fresh run will recompute"
+              exit 0
+            fi
+
+            git rebase origin/main
+          done
+          echo "::error::Failed to push after 3 rebase attempts"
+          exit 1
+
+  # ── PR fix (manual / checkbox) ─────────────────────────────────────
+  # Existing behavior: run on manual dispatch OR when a task-list
+  # checkbox in the sticky lockfile-check comment flips from [ ] to [x].
+  fix:
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'issue_comment'
+       && github.event.issue.pull_request != null
+       && contains(github.event.comment.body, '[x] **Apply lockfile fix**')
+       && !contains(github.event.changes.body.from, '[x] **Apply lockfile fix**'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - name: Authorize & resolve PR
+        id: resolve
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea  # v7.0.1
+        with:
+          script: |
+            // 1. Verify the actor has write access — applies to both checkbox
+            //    clicks and manual dispatch.
+            const { data: perm } =
+              await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                username: context.actor,
+              });
+            if (!['admin', 'write', 'maintain'].includes(perm.permission)) {
+              core.setFailed(
+                `${context.actor} lacks write access (has: ${perm.permission})`
+              );
+              return;
+            }
+
+            // 2. Resolve which ref to check out.
+            let prNumber = '';
+            if (context.eventName === 'issue_comment') {
+              prNumber = String(context.payload.issue.number);
+            } else if (context.eventName === 'workflow_dispatch') {
+              prNumber = context.payload.inputs.pr_number || '';
+            }
+
+            if (!prNumber) {
+              core.setOutput('ref', context.ref.replace(/^refs\/heads\//, ''));
+              core.setOutput('repo', context.repo.repo);
+              core.setOutput('owner', context.repo.owner);
+              core.setOutput('pr', '');
+              return;
+            }
+
+            const { data: pr } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: Number(prNumber),
+            });
+            core.setOutput('ref', pr.head.ref);
+            core.setOutput('repo', pr.head.repo.name);
+            core.setOutput('owner', pr.head.repo.owner.login);
+            core.setOutput('pr', String(pr.number));
+
+      # Wipe the sticky lockfile-check comment to a "running" state as soon
+      # as the job is authorized, so the user sees their click was picked up
+      # before the ~minute of nix build work.
+      - name: Mark sticky as running
+        if: steps.resolve.outputs.pr != ''
+        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728  # v2.9.1
+        with:
+          header: nix-lockfile-check
+          number: ${{ steps.resolve.outputs.pr }}
+          message: |
+            ### 🔄 Applying lockfile fix…
+
+            Triggered by @${{ github.actor }} — [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).
+
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          repository: ${{ steps.resolve.outputs.owner }}/${{ steps.resolve.outputs.repo }}
+          ref: ${{ steps.resolve.outputs.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - uses: ./.github/actions/nix-setup
+        with:
+          cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
+
+      - name: Apply lockfile hashes
+        id: apply
+        run: nix run .#fix-lockfiles
+
+      - name: Commit & push
+        if: steps.apply.outputs.changed == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add nix/tui.nix nix/web.nix
+          git commit -m "fix(nix): refresh npm lockfile hashes"
+          git push
+
+      - name: Update sticky (applied)
+        if: steps.apply.outputs.changed == 'true' && steps.resolve.outputs.pr != ''
+        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728  # v2.9.1
+        with:
+          header: nix-lockfile-check
+          number: ${{ steps.resolve.outputs.pr }}
+          message: |
+            ### ✅ Lockfile fix applied
+
+            Pushed a commit refreshing the npm lockfile hashes — [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).
+
+      - name: Update sticky (already current)
+        if: steps.apply.outputs.changed == 'false' && steps.resolve.outputs.pr != ''
+        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728  # v2.9.1
+        with:
+          header: nix-lockfile-check
+          number: ${{ steps.resolve.outputs.pr }}
+          message: |
+            ### ✅ Lockfile hashes already current
+
+            Nothing to commit — [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).
+
+      - name: Update sticky (failed)
+        if: failure() && steps.resolve.outputs.pr != ''
+        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728  # v2.9.1
+        with:
+          header: nix-lockfile-check
+          number: ${{ steps.resolve.outputs.pr }}
+          message: |
+            ### ❌ Lockfile fix failed
+
+            See the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for logs.

reference/hermes-agent-2026.5.16/.github/workflows/nix.yml

@@ -0,0 +1,117 @@
+name: Nix
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: nix-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  nix:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/nix-setup
+        with:
+          cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
+
+      - name: Resolve head SHA
+        if: github.event_name == 'pull_request'
+        id: sha
+        shell: bash
+        run: |
+          FULL="${{ github.event.pull_request.head.sha || github.sha }}"
+          echo "full=$FULL" >> "$GITHUB_OUTPUT"
+          echo "short=${FULL:0:7}" >> "$GITHUB_OUTPUT"
+
+      - name: Check flake
+        id: flake
+        if: runner.os == 'Linux'
+        continue-on-error: true
+        run: nix flake check --print-build-logs
+
+      - 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' || steps.build.outcome == 'failure') && runner.os == 'Linux'
+        continue-on-error: true
+        env:
+          LINK_SHA: ${{ steps.sha.outputs.full }}
+        run: nix run .#fix-lockfiles -- --check
+
+      # If fix-lockfiles itself crashes (infrastructure blip, cache throttle,
+      # etc.) it won't set stale=true/false.  Treat that as a distinct failure
+      # mode rather than silently ignoring it.
+      - name: Fail if hash check crashed without reporting
+        if: steps.hash_check.outcome == 'failure' && steps.hash_check.outputs.stale != 'true' && steps.hash_check.outputs.stale != 'false'
+        run: |
+          echo "::error::fix-lockfiles exited without reporting stale status — likely an infrastructure or script failure"
+          exit 1
+
+      - name: Post sticky PR comment (stale hashes)
+        if: steps.hash_check.outputs.stale == 'true' && github.event_name == 'pull_request'
+        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728  # v2.9.1
+        with:
+          header: nix-lockfile-check
+          message: |
+            ### ⚠️ npm lockfile hash out of date
+
+            Checked against commit [`${{ steps.sha.outputs.short }}`](${{ github.server_url }}/${{ github.repository }}/commit/${{ steps.sha.outputs.full }}) (PR head at check time).
+
+            The `hash = "sha256-..."` line in these nix files no longer matches the committed `package-lock.json`:
+
+            ${{ steps.hash_check.outputs.report }}
+
+            #### Apply the fix
+
+            - [ ] **Apply lockfile fix** — tick to push a commit with the correct hashes to this PR branch
+            - 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 build passed outright (no
+      # hash check needed) or the hash check explicitly returned stale=false
+      # (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.build.outcome == 'success'))
+        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728  # v2.9.1
+        with:
+          header: nix-lockfile-check
+          delete: true
+
+      - 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 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

reference/hermes-agent-2026.5.16/.github/workflows/osv-scanner.yml

@@ -0,0 +1,67 @@
+name: OSV-Scanner
+
+# Scans lockfiles (uv.lock, package-lock.json) against the OSV vulnerability
+# database. Runs on every PR that touches a lockfile and on a weekly schedule
+# against main.
+#
+# This is detection-only — OSV-Scanner does NOT open PRs or modify pins.
+# It reports known CVEs in currently-pinned dependency versions so we can
+# decide when and how to patch on our own schedule. Our pinning strategy
+# (full SHA / exact version) is preserved; only the notification signal
+# is added.
+#
+# Complements the existing supply-chain-audit.yml workflow (which scans
+# for malicious code patterns in PR diffs) by covering the orthogonal
+# "currently-pinned dep became known-vulnerable" case.
+#
+# Uses Google's officially-recommended reusable workflow, pinned by SHA.
+# Findings land in the repo's Security tab (Code Scanning > OSV-Scanner).
+# fail-on-vuln is disabled so the job does not block merges on pre-existing
+# vulnerabilities in pinned deps that we may need to patch deliberately.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'uv.lock'
+      - 'pyproject.toml'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'ui-tui/package.json'
+      - 'ui-tui/package-lock.json'
+      - 'website/package.json'
+      - 'website/package-lock.json'
+      - '.github/workflows/osv-scanner.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'uv.lock'
+      - 'pyproject.toml'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'ui-tui/package-lock.json'
+      - 'website/package-lock.json'
+  schedule:
+    # Weekly scan against main — catches CVEs published after merge for
+    # deps that haven't changed since.
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+
+permissions:
+  # Required by the reusable workflow to upload SARIF to the Security tab.
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    name: Scan lockfiles
+    uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@c51854704019a247608d928f370c98740469d4b5  # v2.3.5
+    with:
+      # Scan explicit lockfiles rather than recursing, so we only look at
+      # the three sources of truth and skip vendored / test / worktree dirs.
+      scan-args: |-
+        --lockfile=uv.lock
+        --lockfile=ui-tui/package-lock.json
+        --lockfile=website/package-lock.json
+      fail-on-vuln: false

reference/hermes-agent-2026.5.16/.github/workflows/skills-index.yml

@@ -0,0 +1,101 @@
+name: Build Skills Index
+
+on:
+  schedule:
+    # Run twice daily: 6 AM and 6 PM UTC
+    - cron: '0 6,18 * * *'
+  workflow_dispatch:  # Manual trigger
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/build_skills_index.py'
+      - '.github/workflows/skills-index.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  build-index:
+    # Only run on the upstream repository, not on forks
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install httpx==0.28.1 pyyaml==6.0.2
+
+      - name: Build skills index
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python scripts/build_skills_index.py
+
+      - name: Upload index artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: skills-index
+          path: website/static/api/skills-index.json
+          retention-days: 7
+
+  deploy-with-index:
+    needs: build-index
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    # Only deploy on schedule or manual trigger (not on every push to the script)
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: skills-index
+          path: website/static/api/
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.11'
+
+      - name: Install PyYAML for skill extraction
+        run: pip install pyyaml==6.0.2
+
+      - name: Extract skill metadata for dashboard
+        run: python3 website/scripts/extract-skills.py
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: website
+
+      - name: Build Docusaurus
+        run: npm run build
+        working-directory: website
+
+      - name: Stage deployment
+        run: |
+          mkdir -p _site/docs
+          cp -r landingpage/* _site/
+          cp -r website/build/* _site/docs/
+          echo "hermes-agent.nousresearch.com" > _site/CNAME
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa  # v3
+        with:
+          path: _site
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4

reference/hermes-agent-2026.5.16/.github/workflows/supply-chain-audit.yml

@@ -0,0 +1,205 @@
+name: Supply Chain Audit
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - '**/*.py'
+      - '**/*.pth'
+      - '**/setup.py'
+      - '**/setup.cfg'
+      - '**/sitecustomize.py'
+      - '**/usercustomize.py'
+      - '**/__init__.pth'
+      - 'pyproject.toml'
+
+permissions:
+  pull-requests: write
+  contents: read
+
+# Narrow, high-signal scanner. Only fires on critical indicators of supply
+# chain attacks (e.g. the litellm-style payloads). Low-signal heuristics
+# (plain base64, plain exec/eval, dependency/Dockerfile/workflow edits,
+# Actions version unpinning, outbound POST/PUT) were intentionally
+# removed — they fired on nearly every PR and trained reviewers to ignore
+# the scanner. Keep this file's checks ruthlessly narrow: if you find
+# yourself adding WARNING-tier patterns here again, make a separate
+# advisory-only workflow instead.
+
+jobs:
+  scan:
+    name: Scan PR for critical supply chain risks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0
+
+      - name: Scan diff for critical patterns
+        id: scan
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+
+          # Added lines only, excluding lockfiles.
+          DIFF=$(git diff "$BASE".."$HEAD" -- . ':!uv.lock' ':!*.lock' ':!package-lock.json' ':!yarn.lock' || true)
+
+          FINDINGS=""
+
+          # --- .pth files (auto-execute on Python startup) ---
+          # The exact mechanism used in the litellm supply chain attack:
+          # https://github.com/BerriAI/litellm/issues/24512
+          PTH_FILES=$(git diff --name-only "$BASE".."$HEAD" | grep '\.pth$' || true)
+          if [ -n "$PTH_FILES" ]; then
+            FINDINGS="${FINDINGS}
+          ### 🚨 CRITICAL: .pth file added or modified
+          Python \`.pth\` files in \`site-packages/\` execute automatically when the interpreter starts — no import required.
+
+          **Files:**
+          \`\`\`
+          ${PTH_FILES}
+          \`\`\`
+          "
+          fi
+
+          # --- base64 decode + exec/eval on the same line (the litellm attack pattern) ---
+          B64_EXEC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -iE 'base64\.(b64decode|decodebytes|urlsafe_b64decode)' | grep -iE 'exec\(|eval\(' | head -10 || true)
+          if [ -n "$B64_EXEC_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### 🚨 CRITICAL: base64 decode + exec/eval combo
+          Base64-decoded strings passed directly to exec/eval — the signature of hidden credential-stealing payloads.
+
+          **Matches:**
+          \`\`\`
+          ${B64_EXEC_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- subprocess with encoded/obfuscated command argument ---
+          PROC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -E 'subprocess\.(Popen|call|run)\s*\(' | grep -iE 'base64|\\x[0-9a-f]{2}|chr\(' | head -10 || true)
+          if [ -n "$PROC_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### 🚨 CRITICAL: subprocess with encoded/obfuscated command
+          Subprocess calls whose command strings are base64- or hex-encoded are a strong indicator of payload execution.
+
+          **Matches:**
+          \`\`\`
+          ${PROC_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- Install-hook files (setup.py/sitecustomize/usercustomize/__init__.pth) ---
+          # These execute during pip install or interpreter startup.
+          SETUP_HITS=$(git diff --name-only "$BASE".."$HEAD" | grep -E '(^|/)(setup\.py|setup\.cfg|sitecustomize\.py|usercustomize\.py|__init__\.pth)$' || true)
+          if [ -n "$SETUP_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### 🚨 CRITICAL: Install-hook file added or modified
+          These files can execute code during package installation or interpreter startup.
+
+          **Files:**
+          \`\`\`
+          ${SETUP_HITS}
+          \`\`\`
+          "
+          fi
+
+          if [ -n "$FINDINGS" ]; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+            echo "$FINDINGS" > /tmp/findings.md
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Post critical finding comment
+        if: steps.scan.outputs.found == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BODY="## 🚨 CRITICAL Supply Chain Risk Detected
+
+          This PR contains a pattern that has been used in real supply chain attacks. A maintainer must review the flagged code carefully before merging.
+
+          $(cat /tmp/findings.md)
+
+          ---
+          *Scanner only fires on high-signal indicators: .pth files, base64+exec/eval combos, subprocess with encoded commands, or install-hook files. Low-signal warnings were removed intentionally — if you're seeing this comment, the finding is worth inspecting.*"
+
+          gh pr comment "${{ github.event.pull_request.number }}" --body "$BODY" || echo "::warning::Could not post PR comment (expected for fork PRs — GITHUB_TOKEN is read-only)"
+
+      - name: Fail on critical findings
+        if: steps.scan.outputs.found == 'true'
+        run: |
+          echo "::error::CRITICAL supply chain risk patterns detected in this PR. See the PR comment for details."
+          exit 1
+
+  dep-bounds:
+    name: Check PyPI dependency upper bounds
+    runs-on: ubuntu-latest
+    if: contains(github.event.pull_request.changed_files_url, 'pyproject.toml') || true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for unbounded PyPI deps
+        id: bounds
+        run: |
+          set -euo pipefail
+
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+
+          # Only check added lines in pyproject.toml
+          ADDED=$(git diff "$BASE".."$HEAD" -- pyproject.toml | grep '^+' | grep -v '^+++' || true)
+
+          if [ -z "$ADDED" ]; then
+            echo "found=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Match PyPI dep specs that have >= but no < ceiling.
+          # Pattern: "package>=version" without a following ",<" bound.
+          # Excludes git+ URLs (which use commit SHAs) and comments.
+          UNBOUNDED=$(echo "$ADDED" | grep -oE '"[a-zA-Z0-9_-]+(\[[^\]]*\])?>=[ 0-9.]+"' | grep -v ',<' || true)
+
+          if [ -n "$UNBOUNDED" ]; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+            echo "$UNBOUNDED" > /tmp/unbounded.txt
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Post unbounded dep warning
+        if: steps.bounds.outputs.found == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BODY="## ⚠️ Unbounded PyPI Dependency Detected
+
+          This PR adds PyPI dependencies without a \`<next_major\` upper bound. Per our [supply chain policy](../blob/main/CONTRIBUTING.md#dependency-pinning-policy-supply-chain-hardening), all PyPI deps must be pinned as \`>=floor,<next_major\`.
+
+          **Unbounded specs found:**
+          \`\`\`
+          $(cat /tmp/unbounded.txt)
+          \`\`\`
+
+          **Fix:** Add an upper bound, e.g. \`\"package>=1.2.0,<2\"\`
+
+          ---
+          *See PR #2810 and CONTRIBUTING.md for the full policy rationale.*"
+
+          gh pr comment "${{ github.event.pull_request.number }}" --body "$BODY" || echo "::warning::Could not post PR comment (expected for fork PRs)"
+
+      - name: Fail on unbounded deps
+        if: steps.bounds.outputs.found == 'true'
+        run: |
+          echo "::error::PyPI dependencies without upper bounds detected. Add <next_major ceiling per CONTRIBUTING.md policy."
+          exit 1

reference/hermes-agent-2026.5.16/.github/workflows/tests.yml

@@ -0,0 +1,85 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+
+permissions:
+  contents: read
+
+# Cancel in-progress runs for the same PR/branch
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: |
+          uv venv .venv --python 3.11
+          source .venv/bin/activate
+          uv pip install -e ".[all,dev]"
+
+      - name: Run tests
+        run: |
+          source .venv/bin/activate
+          python -m pytest tests/ -q --ignore=tests/integration --ignore=tests/e2e --tb=short -n auto
+        env:
+          # Ensure tests don't accidentally call real APIs
+          OPENROUTER_API_KEY: ""
+          OPENAI_API_KEY: ""
+          NOUS_API_KEY: ""
+
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: |
+          uv venv .venv --python 3.11
+          source .venv/bin/activate
+          uv pip install -e ".[all,dev]"
+
+      - name: Run e2e tests
+        run: |
+          source .venv/bin/activate
+          python -m pytest tests/e2e/ -v --tb=short
+        env:
+          OPENROUTER_API_KEY: ""
+          OPENAI_API_KEY: ""
+          NOUS_API_KEY: ""

reference/hermes-agent-2026.5.16/.github/workflows/upload_to_pypi.yml

@@ -0,0 +1,163 @@
+name: Publish to PyPI
+
+# Triggered by CalVer tag pushes from scripts/release.py (e.g. v2026.5.15)
+# Can also be triggered manually from the Actions tab as an escape hatch.
+on:
+  push:
+    tags:
+      - 'v20*'  # CalVer tags: v2026.5.15, v2026.5.15.2, etc.
+  workflow_dispatch:
+    inputs:
+      confirm_tag:
+        description: 'Tag to publish (e.g. v2026.5.15). Must already exist.'
+        required: true
+        type: string
+
+# Restrict default token to read-only; each job escalates as needed.
+permissions:
+  contents: read
+
+# Prevent overlapping publishes (e.g. two same-day tags pushed quickly).
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          persist-credentials: false
+          # On workflow_dispatch, check out the confirmed tag.
+          ref: ${{ inputs.confirm_tag || github.ref }}
+          fetch-tags: true
+
+      - name: Validate tag exists
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if ! git tag -l "${{ inputs.confirm_tag }}" | grep -q .; then
+            echo "::error::Tag '${{ inputs.confirm_tag }}' does not exist in the repo"
+            exit 1
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+        with:
+          node-version: '22'
+
+      - name: Build web dashboard
+        run: cd web && npm ci && npm run build
+
+      - name: Build TUI bundle
+        run: cd ui-tui && npm ci && npm run build
+
+      - name: Bundle TUI into hermes_cli
+        run: |
+          mkdir -p hermes_cli/tui_dist
+          cp ui-tui/dist/entry.js hermes_cli/tui_dist/entry.js
+
+      - name: Verify frontend assets exist
+        run: |
+          test -f hermes_cli/web_dist/index.html || { echo "ERROR: web_dist not built"; exit 1; }
+          test -f hermes_cli/tui_dist/entry.js || { echo "ERROR: tui_dist not built"; exit 1; }
+
+      - name: Bundle install.sh into wheel
+        run: |
+          mkdir -p hermes_cli/scripts
+          cp scripts/install.sh hermes_cli/scripts/install.sh
+
+      - name: Build wheel and sdist
+        run: uv build --sdist --wheel
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hermes-agent
+    permissions:
+      id-token: write  # OIDC trusted publishing
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        with:
+          skip-existing: true
+
+  sign:
+    name: Sign and attach to GitHub Release
+    # Only runs on tag pushes — release.py creates the GitHub Release,
+    # and workflow_dispatch won't have a matching release to attach to.
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # attach assets to the existing release
+      id-token: write   # sigstore signing
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Wait for GitHub Release to exist
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        # release.py creates the GitHub Release after pushing the tag,
+        # but this workflow starts from the tag push — wait for it.
+        run: |
+          for i in $(seq 1 30); do
+            if gh release view "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+              echo "Release $GITHUB_REF_NAME found"
+              exit 0
+            fi
+            echo "Waiting for release... ($i/30)"
+            sleep 10
+          done
+          echo "::warning::Release $GITHUB_REF_NAME not found after 5 minutes — skipping signature upload"
+          echo "skip_sign=true" >> "$GITHUB_ENV"
+
+      - name: Sign with Sigstore
+        if: env.skip_sign != 'true'
+        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46  # v3.0.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+
+      - name: Attach signed artifacts to GitHub Release
+        if: env.skip_sign != 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        # release.py already created the GitHub Release — just upload
+        # the Sigstore signatures alongside the existing assets.
+        run: >-
+          gh release upload
+          "$GITHUB_REF_NAME" dist/*.sigstore.json
+          --repo "$GITHUB_REPOSITORY"
+          --clobber

reference/hermes-agent-2026.5.16/.github/workflows/uv-lockfile-check.yml

@@ -0,0 +1,119 @@
+name: uv.lock check
+
+# Verify uv.lock is in sync with pyproject.toml.  Blocking check — PRs
+# that modify pyproject.toml without regenerating uv.lock (or vice versa)
+# must not merge, because the Docker build's `uv sync --frozen` step will
+# fail on a stale lockfile and we'd rather catch it here than in the
+# docker-publish workflow on main.
+#
+# ─────────────────────────────────────────────────────────────────────────
+# IMPORTANT: this check runs against the MERGED state, not just your branch
+# ─────────────────────────────────────────────────────────────────────────
+#
+# For `pull_request` events, GitHub checks out `refs/pull/<N>/merge` by
+# default — a synthetic commit that merges your PR branch into the CURRENT
+# state of `main`.  That means the pyproject.toml evaluated here is
+# `main's pyproject.toml + your PR's changes to pyproject.toml`, not just
+# what's on your branch.
+#
+# Failure mode this creates: if `main` has advanced since you branched
+# (e.g. someone merged a PR that added a dep to pyproject.toml + its
+# corresponding uv.lock entries), your branch's uv.lock is missing those
+# new entries.  `uv lock --check` resolves against the merged pyproject
+# and sees a lockfile that doesn't cover all the current deps → fails
+# with "The lockfile at uv.lock needs to be updated."
+#
+# This can be confusing: `uv lock --check` passes locally (your branch
+# is internally consistent) but fails in CI (merged state isn't).
+#
+# Fix is to sync your branch with main and regenerate the lockfile:
+#
+#     git fetch origin main
+#     git rebase origin/main      # or merge, whatever the repo prefers
+#     uv lock                     # regenerates uv.lock against new pyproject.toml
+#     git add uv.lock
+#     git commit -m "chore: refresh uv.lock after rebase onto main"
+#     git push --force-with-lease # if you rebased
+#
+# If you also changed pyproject.toml in your PR, `uv lock` handles that
+# at the same time — one regeneration covers both your changes and the
+# drift from main.
+#
+# This is the correct behavior!  The check is protecting main's Docker
+# build: a post-merge build would see the same merged state and fail
+# the same way.  Better to catch it here than after merge.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/uv-lockfile-check.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/uv-lockfile-check.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: uv-lockfile-check-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  check:
+    name: uv lock --check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
+
+      # `uv lock --check` re-resolves the project from pyproject.toml and
+      # compares the result to uv.lock, exiting non-zero if they disagree.
+      # No network writes, no file modifications.
+      #
+      # On PRs this runs against the merge commit (see comment at the top
+      # of this file) — failures often mean "your branch is behind main,
+      # rebase and regenerate uv.lock."
+      - name: Verify uv.lock is up-to-date
+        run: |
+          if ! uv lock --check; then
+            cat <<'EOF' >> "$GITHUB_STEP_SUMMARY"
+          ## ❌ uv.lock is out of sync with pyproject.toml
+
+          **If this is a PR:** this check runs against the merged state
+          (your branch + current `main`), not just your branch.  If
+          `uv lock --check` passes locally, your branch is likely behind
+          `main` — recent changes to `pyproject.toml` on `main` aren't
+          reflected in your branch's `uv.lock` yet.
+
+          To fix, sync with main and regenerate the lockfile:
+
+          ```bash
+          git fetch origin main
+          git rebase origin/main   # or `git merge origin/main`
+          uv lock                  # regenerate against new pyproject.toml
+          git add uv.lock
+          git commit -m "chore: refresh uv.lock after syncing with main"
+          git push --force-with-lease  # drop --force-with-lease if you merged
+          ```
+
+          **If you only changed pyproject.toml:** run `uv lock` locally
+          and commit the result.
+
+          This check is blocking because the Docker image build uses
+          `uv sync --frozen --extra all`, which rejects stale lockfiles
+          — catching it here avoids a ~15 min failed docker-publish run
+          on `main` post-merge.
+          EOF
+            echo "::error title=uv.lock out of sync::Run \`uv lock\` locally and commit the result. If on a PR, sync with main first."
+            exit 1
+          fi

reference/hermes-agent-2026.5.16/.gitignore

@@ -0,0 +1,75 @@
+.DS_Store
+/venv/
+/_pycache/
+*.pyc*
+__pycache__/
+.venv/
+.vscode/
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env.development
+.env.test
+export*
+__pycache__/model_tools.cpython-310.pyc
+__pycache__/web_tools.cpython-310.pyc
+logs/
+data/
+.pytest_cache/
+tmp/
+temp_vision_images/
+hermes-*/*
+examples/
+tests/quick_test_dataset.jsonl
+tests/sample_dataset.jsonl
+run_datagen_kimik2-thinking.sh
+run_datagen_megascience_glm4-6.sh
+run_datagen_sonnet.sh
+source-data/*
+run_datagen_megascience_glm4-6.sh
+data/*
+node_modules/
+browser-use/
+agent-browser/
+# Private keys
+*.ppk
+*.pem
+privvy*
+images/
+__pycache__/
+hermes_agent.egg-info/
+wandb/
+testlogs
+
+# CLI config (may contain sensitive SSH paths)
+cli-config.yaml
+
+# Skills Hub state (lives in ~/.hermes/skills/.hub/ at runtime, but just in case)
+skills/.hub/
+ignored/
+.worktrees/
+environments/benchmarks/evals/
+
+# Web UI build output
+hermes_cli/web_dist/
+
+# Web UI assets — synced from @nous-research/ui at build time via
+# `npm run sync-assets` (see web/package.json).
+web/public/fonts/
+web/public/ds-assets/
+
+# Release script temp files
+.release_notes.md
+mini-swe-agent/
+
+# Nix
+.direnv/
+.nix-stamps/
+result
+website/static/api/skills-index.json
+models-dev-upstream/
+hermes_cli/tui_dist/*
+hermes_cli/scripts/
+docs/superpowers/*

reference/hermes-agent-2026.5.16/.mailmap

@@ -0,0 +1,108 @@
+# .mailmap — canonical author mapping for git shortlog / git log / GitHub
+# Format: Canonical Name <canonical@email> <commit@email>
+# See: https://git-scm.com/docs/gitmailmap
+#
+# This maps commit emails to GitHub noreply addresses so that:
+# 1. `git shortlog -sn` shows deduplicated contributor counts
+# 2. GitHub's contributor graph can attribute commits correctly
+# 3. Contributors with personal/work emails get proper credit
+#
+# When adding entries: use the contributor's GitHub noreply email as canonical
+# so GitHub can link commits to their profile.
+
+# === Teknium (multiple emails) ===
+Teknium <127238744+teknium1@users.noreply.github.com> <teknium1@gmail.com>
+Teknium <127238744+teknium1@users.noreply.github.com> <teknium@nousresearch.com>
+
+# === Contributors — personal/work emails mapped to GitHub noreply ===
+# Format: Canonical Name <GH-noreply> <commit-email>
+
+# Verified via GH API email search
+luyao618 <364939526@qq.com> <364939526@qq.com>
+ethernet8023 <arilotter@gmail.com> <arilotter@gmail.com>
+nicoloboschi <boschi1997@gmail.com> <boschi1997@gmail.com>
+cherifya <chef.ya@gmail.com> <chef.ya@gmail.com>
+BongSuCHOI <chlqhdtn98@gmail.com> <chlqhdtn98@gmail.com>
+dsocolobsky <dsocolobsky@gmail.com> <dsocolobsky@gmail.com>
+pefontana <fontana.pedro93@gmail.com> <fontana.pedro93@gmail.com>
+Helmi <frank@helmschrott.de> <frank@helmschrott.de>
+hata1234 <hata1234@gmail.com> <hata1234@gmail.com>
+
+# Verified via PR investigation / salvage PR bodies
+DeployFaith <agents@kylefrench.dev> <agents@kylefrench.dev>
+flobo3 <floptopbot33@gmail.com> <floptopbot33@gmail.com>
+gaixianggeng <gaixg94@gmail.com> <gaixg94@gmail.com>
+KUSH42 <xush@xush.org> <xush@xush.org>
+konsisumer <der@konsi.org> <der@konsi.org>
+WorldInnovationsDepartment <vorvul.danylo@gmail.com> <vorvul.danylo@gmail.com>
+m0n5t3r <iacobs@m0n5t3r.info> <iacobs@m0n5t3r.info>
+sprmn24 <oncuevtv@gmail.com> <oncuevtv@gmail.com>
+fancydirty <fancydirty@gmail.com> <fancydirty@gmail.com>
+fxfitz <francis.x.fitzpatrick@gmail.com> <francis.x.fitzpatrick@gmail.com>
+limars874 <limars874@gmail.com> <limars874@gmail.com>
+AaronWong1999 <aaronwong1999@icloud.com> <aaronwong1999@icloud.com>
+dippwho <dipp.who@gmail.com> <dipp.who@gmail.com>
+duerzy <duerzy@gmail.com> <duerzy@gmail.com>
+geoffwellman <geoff.wellman@gmail.com> <geoff.wellman@gmail.com>
+hcshen0111 <shenhaocheng19990111@gmail.com> <shenhaocheng19990111@gmail.com>
+jamesarch <han.shan@live.cn> <han.shan@live.cn>
+stephenschoettler <stephenschoettler@gmail.com> <stephenschoettler@gmail.com>
+Tranquil-Flow <tranquil_flow@protonmail.com> <tranquil_flow@protonmail.com>
+Dusk1e <yusufalweshdemir@gmail.com> <yusufalweshdemir@gmail.com>
+Awsh1 <ysfalweshcan@gmail.com> <ysfalweshcan@gmail.com>
+WAXLYY <ysfwaxlycan@gmail.com> <ysfwaxlycan@gmail.com>
+donrhmexe <don.rhm@gmail.com> <don.rhm@gmail.com>
+hqhq1025 <1506751656@qq.com> <1506751656@qq.com>
+BlackishGreen33 <s5460703@gmail.com> <s5460703@gmail.com>
+tomqiaozc <zqiao@microsoft.com> <zqiao@microsoft.com>
+MagicRay1217 <mingjwan@microsoft.com> <mingjwan@microsoft.com>
+aaronagent <1115117931@qq.com> <1115117931@qq.com>
+YoungYang963 <young@YoungdeMacBook-Pro.local> <young@YoungdeMacBook-Pro.local>
+LongOddCode <haolong@microsoft.com> <haolong@microsoft.com>
+Cafexss <coffeemjj@gmail.com> <coffeemjj@gmail.com>
+Cygra <sjtuwbh@gmail.com> <sjtuwbh@gmail.com>
+DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
+
+# Duplicate email mapping (same person, multiple emails)
+Sertug17 <104278804+Sertug17@users.noreply.github.com> <srhtsrht17@gmail.com>
+yyovil <birdiegyal@gmail.com> <tanishq231003@gmail.com>
+DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
+dsocolobsky <dsocolobsky@gmail.com> <dylan.socolobsky@lambdaclass.com>
+olafthiele <programming@olafthiele.com> <olafthiele@gmail.com>
+
+# Verified via git display name matching GH contributor username
+cokemine <aptx4561@gmail.com> <aptx4561@gmail.com>
+dalianmao000 <dalianmao0107@gmail.com> <dalianmao0107@gmail.com>
+emozilla <emozilla@nousresearch.com> <emozilla@nousresearch.com>
+jjovalle99 <juan.ovalle@mistral.ai> <juan.ovalle@mistral.ai>
+kagura-agent <kagura.chen28@gmail.com> <kagura.chen28@gmail.com>
+spniyant <niyant@spicefi.xyz> <niyant@spicefi.xyz>
+olafthiele <programming@olafthiele.com> <programming@olafthiele.com>
+r266-tech <r2668940489@gmail.com> <r2668940489@gmail.com>
+xingkongliang <tianliangjay@gmail.com> <tianliangjay@gmail.com>
+win4r <win4r@outlook.com> <win4r@outlook.com>
+zhouboli <zhouboli@gmail.com> <zhouboli@gmail.com>
+yongtenglei <yongtenglei@gmail.com> <yongtenglei@gmail.com>
+
+# Nous Research team
+benbarclay <ben@nousresearch.com> <ben@nousresearch.com>
+jquesnelle <jonny@nousresearch.com> <jonny@nousresearch.com>
+
+# GH contributor list verified
+spideystreet <dhicham.pro@gmail.com> <dhicham.pro@gmail.com>
+dorukardahan <dorukardahan@hotmail.com> <dorukardahan@hotmail.com>
+MustafaKara7 <karamusti912@gmail.com> <karamusti912@gmail.com>
+Hmbown <hmbown@gmail.com> <hmbown@gmail.com>
+kamil-gwozdz <kamil@gwozdz.me> <kamil@gwozdz.me>
+kira-ariaki <kira@ariaki.me> <kira@ariaki.me>
+knopki <knopki@duck.com> <knopki@duck.com>
+Unayung <unayung@gmail.com> <unayung@gmail.com>
+SeeYangZhi <yangzhi.see@gmail.com> <yangzhi.see@gmail.com>
+Julientalbot <julien.talbot@ergonomia.re> <julien.talbot@ergonomia.re>
+lesterli <lisicheng168@gmail.com> <lisicheng168@gmail.com>
+JiayuuWang <jiayuw794@gmail.com> <jiayuw794@gmail.com>
+tesseracttars-creator <tesseracttars@gmail.com> <tesseracttars@gmail.com>
+xinbenlv <zzn+pa@zzn.im> <zzn+pa@zzn.im>
+SaulJWu <saul.jj.wu@gmail.com> <saul.jj.wu@gmail.com>
+angelos <angelos@oikos.lan.home.malaiwah.com> <angelos@oikos.lan.home.malaiwah.com>
+MestreY0d4-Uninter <241404605+MestreY0d4-Uninter@users.noreply.github.com> <MestreY0d4-Uninter@users.noreply.github.com>

reference/hermes-agent-2026.5.16/.plans/openai-api-server.md

@@ -0,0 +1,291 @@
+# OpenAI-Compatible API Server for Hermes Agent
+
+## Motivation
+
+Every major chat frontend (Open WebUI 126k★, LobeChat 73k★, LibreChat 34k★,
+AnythingLLM 56k★, NextChat 87k★, ChatBox 39k★, Jan 26k★, HF Chat-UI 8k★,
+big-AGI 7k★) connects to backends via the OpenAI-compatible REST API with
+SSE streaming. By exposing this endpoint, hermes-agent becomes instantly
+usable as a backend for all of them — no custom adapters needed.
+
+## What It Enables
+
+```
+┌──────────────────┐
+│  Open WebUI      │──┐
+│  LobeChat        │  │    POST /v1/chat/completions
+│  LibreChat       │  ├──► Authorization: Bearer <key>     ┌─────────────────┐
+│  AnythingLLM     │  │    {"messages": [...]}             │  hermes-agent   │
+│  NextChat        │  │                                    │  gateway        │
+│  Any OAI client  │──┘    ◄── SSE streaming response      │  (API server)   │
+└──────────────────┘                                        └─────────────────┘
+```
+
+A user would:
+1. Set `API_SERVER_ENABLED=true` in `~/.hermes/.env`
+2. Run `hermes gateway` (API server starts alongside Telegram/Discord/etc.)
+3. Point Open WebUI (or any frontend) at `http://localhost:8642/v1`
+4. Chat with hermes-agent through any OpenAI-compatible UI
+
+## Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| POST | `/v1/chat/completions` | Chat with the agent (streaming + non-streaming) |
+| GET | `/v1/models` | List available "models" (returns hermes-agent as a model) |
+| GET | `/health` | Health check |
+
+## Architecture
+
+### Option A: Gateway Platform Adapter (recommended)
+
+Create `gateway/platforms/api_server.py` as a new platform adapter that
+extends `BasePlatformAdapter`. This is the cleanest approach because:
+
+- Reuses all gateway infrastructure (session management, auth, context building)
+- Runs in the same async loop as other adapters
+- Gets message handling, interrupt support, and session persistence for free
+- Follows the established pattern (like Telegram, Discord, etc.)
+- Uses `aiohttp.web` (already a dependency) for the HTTP server
+
+The adapter would start an `aiohttp.web.Application` server in `connect()`
+and route incoming HTTP requests through the standard `handle_message()` pipeline.
+
+### Option B: Standalone Component
+
+A separate HTTP server class in `gateway/api_server.py` that creates its own
+AIAgent instances directly. Simpler but duplicates session/auth logic.
+
+**Recommendation: Option A** — fits the existing architecture, less code to
+maintain, gets all gateway features for free.
+
+## Request/Response Format
+
+### Chat Completions (non-streaming)
+
+```
+POST /v1/chat/completions
+Authorization: Bearer hermes-api-key-here
+Content-Type: application/json
+
+{
+  "model": "hermes-agent",
+  "messages": [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "What files are in the current directory?"}
+  ],
+  "stream": false,
+  "temperature": 0.7
+}
+```
+
+Response:
+```json
+{
+  "id": "chatcmpl-abc123",
+  "object": "chat.completion",
+  "created": 1710000000,
+  "model": "hermes-agent",
+  "choices": [{
+    "index": 0,
+    "message": {
+      "role": "assistant",
+      "content": "Here are the files in the current directory:\n..."
+    },
+    "finish_reason": "stop"
+  }],
+  "usage": {
+    "prompt_tokens": 50,
+    "completion_tokens": 200,
+    "total_tokens": 250
+  }
+}
+```
+
+### Chat Completions (streaming)
+
+Same request with `"stream": true`. Response is SSE:
+
+```
+data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Here "},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"are "},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
+
+data: [DONE]
+```
+
+### Models List
+
+```
+GET /v1/models
+Authorization: Bearer hermes-api-key-here
+```
+
+Response:
+```json
+{
+  "object": "list",
+  "data": [{
+    "id": "hermes-agent",
+    "object": "model",
+    "created": 1710000000,
+    "owned_by": "hermes-agent"
+  }]
+}
+```
+
+## Key Design Decisions
+
+### 1. Session Management
+
+The OpenAI API is stateless — each request includes the full conversation.
+But hermes-agent sessions have persistent state (memory, skills, tool context).
+
+**Approach: Hybrid**
+- Default: Stateless. Each request is independent. The `messages` array IS
+  the conversation. No session persistence between requests.
+- Opt-in persistent sessions via `X-Session-ID` header. When provided, the
+  server maintains session state across requests (conversation history,
+  memory context, tool state). This enables richer agent behavior.
+- The session ID also enables interrupt support — a subsequent request with
+  the same session ID while one is running triggers an interrupt.
+
+### 2. Streaming
+
+The agent's `run_conversation()` is synchronous and returns the full response.
+For real SSE streaming, we need to emit chunks as they're generated.
+
+**Phase 1 (MVP):** Run agent in a thread, return the complete response as
+a single SSE chunk + `[DONE]`. This works with all frontends — they just see
+a fast single-chunk response. Not true streaming but functional.
+
+**Phase 2:** Add a response callback to AIAgent that emits text chunks as the
+LLM generates them. The API server captures these via a queue and streams them
+as SSE events. This gives real token-by-token streaming.
+
+**Phase 3:** Stream tool execution progress too — emit tool call/result events
+as the agent works, giving frontends visibility into what the agent is doing.
+
+### 3. Tool Transparency
+
+Two modes:
+- **Opaque (default):** Frontends see only the final response. Tool calls
+  happen server-side and are invisible. Best for general-purpose UIs.
+- **Transparent (opt-in via header):** Tool calls are emitted as OpenAI-format
+  tool_call/tool_result messages in the stream. Useful for agent-aware frontends.
+
+### 4. Authentication
+
+- Bearer token via `Authorization: Bearer <key>` header
+- Token configured via `API_SERVER_KEY` env var
+- Optional: allow unauthenticated local-only access (127.0.0.1 bind)
+- Follows the same pattern as other platform adapters
+
+### 5. Model Mapping
+
+Frontends send `"model": "hermes-agent"` (or whatever). The actual LLM model
+used is configured server-side in config.yaml. The API server maps any
+requested model name to the configured hermes-agent model.
+
+Optionally, allow model passthrough: if the frontend sends
+`"model": "anthropic/claude-sonnet-4"`, the agent uses that model. Controlled
+by a config flag.
+
+## Configuration
+
+```yaml
+# In config.yaml
+api_server:
+  enabled: true
+  port: 8642
+  host: "127.0.0.1"        # localhost only by default
+  key: "your-secret-key"   # or via API_SERVER_KEY env var
+  allow_model_override: false  # let clients choose the model
+  max_concurrent: 5         # max simultaneous requests
+```
+
+Environment variables:
+```bash
+API_SERVER_ENABLED=true
+API_SERVER_PORT=8642
+API_SERVER_HOST=127.0.0.1
+API_SERVER_KEY=your-secret-key
+```
+
+## Implementation Plan
+
+### Phase 1: MVP (non-streaming) — PR
+
+1. `gateway/platforms/api_server.py` — new adapter
+   - aiohttp.web server with endpoints:
+     - `POST /v1/chat/completions` — Chat Completions API (universal compat)
+     - `POST /v1/responses` — Responses API (server-side state, tool preservation)
+     - `GET /v1/models` — list available models
+     - `GET /health` — health check
+   - Bearer token auth middleware
+   - Non-streaming responses (run agent, return full result)
+   - Chat Completions: stateless, messages array is the conversation
+   - Responses API: server-side conversation storage via previous_response_id
+     - Store full internal conversation (including tool calls) keyed by response ID
+     - On subsequent requests, reconstruct full context from stored chain
+   - Frontend system prompt layered on top of hermes-agent's core prompt
+
+2. `gateway/config.py` — add `Platform.API_SERVER` enum + config
+
+3. `gateway/run.py` — register adapter in `_create_adapter()`
+
+4. Tests in `tests/gateway/test_api_server.py`
+
+### Phase 2: SSE Streaming
+
+1. Add response streaming to both endpoints
+   - Chat Completions: `choices[0].delta.content` SSE format
+   - Responses API: semantic events (response.output_text.delta, etc.)
+   - Run agent in thread, collect output via callback queue
+   - Handle client disconnect (cancel agent)
+
+2. Add `stream_callback` parameter to `AIAgent.run_conversation()`
+
+### Phase 3: Enhanced Features
+
+1. Tool call transparency mode (opt-in)
+2. Model passthrough/override
+3. Concurrent request limiting
+4. Usage tracking / rate limiting
+5. CORS headers for browser-based frontends
+6. GET /v1/responses/{id} — retrieve stored response
+7. DELETE /v1/responses/{id} — delete stored response
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `gateway/platforms/api_server.py` | NEW — main adapter (~300 lines) |
+| `gateway/config.py` | Add Platform.API_SERVER + config (~20 lines) |
+| `gateway/run.py` | Register adapter in _create_adapter() (~10 lines) |
+| `tests/gateway/test_api_server.py` | NEW — tests (~200 lines) |
+| `cli-config.yaml.example` | Add api_server section |
+| `README.md` | Mention API server in platform list |
+
+## Compatibility Matrix
+
+Once implemented, hermes-agent works as a drop-in backend for:
+
+| Frontend | Stars | How to Connect |
+|----------|-------|---------------|
+| Open WebUI | 126k | Settings → Connections → Add OpenAI API, URL: `http://localhost:8642/v1` |
+| NextChat | 87k | BASE_URL env var |
+| LobeChat | 73k | Custom provider endpoint |
+| AnythingLLM | 56k | LLM Provider → Generic OpenAI |
+| Oobabooga | 42k | Already a backend, not a frontend |
+| ChatBox | 39k | API Host setting |
+| LibreChat | 34k | librechat.yaml custom endpoint |
+| Chatbot UI | 29k | Custom API endpoint |
+| Jan | 26k | Remote model config |
+| AionUI | 18k | Custom API endpoint |
+| HF Chat-UI | 8k | OPENAI_BASE_URL env var |
+| big-AGI | 7k | Custom endpoint |

reference/hermes-agent-2026.5.16/.plans/streaming-support.md

@@ -0,0 +1,705 @@
+# Streaming LLM Response Support for Hermes Agent
+
+## Overview
+
+Add token-by-token streaming of LLM responses across all platforms. When enabled,
+users see the response typing out live instead of waiting for the full generation.
+Streaming is opt-in via config, defaults to off, and all existing non-streaming
+code paths remain intact as the default.
+
+## Design Principles
+
+1. **Feature-flagged**: `streaming.enabled: true` in config.yaml. Off by default.
+   When off, all existing code paths are unchanged — zero risk to current behavior.
+2. **Callback-based**: A simple `stream_callback(text_delta: str)` function injected
+   into AIAgent. The agent doesn't know or care what the consumer does with tokens.
+3. **Graceful degradation**: If the provider doesn't support streaming, or streaming
+   fails for any reason, silently fall back to the non-streaming path.
+4. **Platform-agnostic core**: The streaming mechanism in AIAgent works the same
+   regardless of whether the consumer is CLI, Telegram, Discord, or the API server.
+
+---
+
+## Architecture
+
+```
+                              stream_callback(delta)
+                                    │
+  ┌─────────────┐    ┌─────────────▼──────────────┐
+  │  LLM API    │    │      queue.Queue()          │
+  │  (stream)   │───►│  thread-safe bridge between │
+  │             │    │  agent thread & consumer    │
+  └─────────────┘    └─────────────┬──────────────┘
+                                   │
+                    ┌──────────────┼──────────────┐
+                    │              │              │
+              ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
+              │    CLI     │ │  Gateway  │ │ API Server│
+              │ print to   │ │ edit msg  │ │ SSE event │
+              │ terminal   │ │ on Tg/Dc  │ │ to client │
+              └───────────┘ └───────────┘ └───────────┘
+```
+
+The agent runs in a thread. The callback puts tokens into a thread-safe queue.
+Each consumer reads the queue in its own context (async task, main thread, etc.).
+
+---
+
+## Configuration
+
+### config.yaml
+
+```yaml
+streaming:
+  enabled: false          # Master switch. Default off.
+  # Per-platform overrides (optional):
+  # cli: true             # Override for CLI only
+  # telegram: true        # Override for Telegram only
+  # discord: false        # Keep Discord non-streaming
+  # api_server: true      # Override for API server
+```
+
+### Environment variables
+
+```
+HERMES_STREAMING_ENABLED=true    # Master switch via env
+```
+
+### How the flag is read
+
+- **CLI**: `load_cli_config()` reads `streaming.enabled`, sets env var. AIAgent
+  checks at init time.
+- **Gateway**: `_run_agent()` reads config, decides whether to pass
+  `stream_callback` to the AIAgent constructor.
+- **API server**: For Chat Completions `stream=true` requests, always uses streaming
+  regardless of config (the client is explicitly requesting it). For non-stream
+  requests, uses config.
+
+### Precedence
+
+1. API server: client's `stream` field overrides everything
+2. Per-platform config override (e.g., `streaming.telegram: true`)
+3. Master `streaming.enabled` flag
+4. Default: off
+
+---
+
+## Implementation Plan
+
+### Phase 1: Core streaming infrastructure in AIAgent
+
+**File: run_agent.py**
+
+#### 1a. Add stream_callback parameter to __init__ (~5 lines)
+
+```python
+def __init__(self, ..., stream_callback: callable = None, ...):
+    self.stream_callback = stream_callback
+```
+
+No other init changes. The callback is optional — when None, everything
+works exactly as before.
+
+#### 1b. Add _run_streaming_chat_completion() method (~65 lines)
+
+New method for Chat Completions API streaming:
+
+```python
+def _run_streaming_chat_completion(self, api_kwargs: dict):
+    """Stream a chat completion, emitting text tokens via stream_callback.
+    
+    Returns a fake response object compatible with the non-streaming code path.
+    Falls back to non-streaming on any error.
+    """
+    stream_kwargs = dict(api_kwargs)
+    stream_kwargs["stream"] = True
+    stream_kwargs["stream_options"] = {"include_usage": True}
+    
+    accumulated_content = []
+    accumulated_tool_calls = {}  # index -> {id, name, arguments}
+    final_usage = None
+    
+    try:
+        stream = self.client.chat.completions.create(**stream_kwargs)
+        
+        for chunk in stream:
+            if not chunk.choices:
+                # Usage-only chunk (final)
+                if chunk.usage:
+                    final_usage = chunk.usage
+                continue
+            
+            delta = chunk.choices[0].delta
+            
+            # Text content — emit via callback
+            if delta.content:
+                accumulated_content.append(delta.content)
+                if self.stream_callback:
+                    try:
+                        self.stream_callback(delta.content)
+                    except Exception:
+                        pass
+            
+            # Tool call deltas — accumulate silently
+            if delta.tool_calls:
+                for tc_delta in delta.tool_calls:
+                    idx = tc_delta.index
+                    if idx not in accumulated_tool_calls:
+                        accumulated_tool_calls[idx] = {
+                            "id": tc_delta.id or "",
+                            "name": "", "arguments": ""
+                        }
+                    if tc_delta.function:
+                        if tc_delta.function.name:
+                            accumulated_tool_calls[idx]["name"] = tc_delta.function.name
+                        if tc_delta.function.arguments:
+                            accumulated_tool_calls[idx]["arguments"] += tc_delta.function.arguments
+        
+        # Build fake response compatible with existing code
+        tool_calls = []
+        for idx in sorted(accumulated_tool_calls):
+            tc = accumulated_tool_calls[idx]
+            if tc["name"]:
+                tool_calls.append(SimpleNamespace(
+                    id=tc["id"], type="function",
+                    function=SimpleNamespace(name=tc["name"], arguments=tc["arguments"]),
+                ))
+        
+        return SimpleNamespace(
+            choices=[SimpleNamespace(
+                message=SimpleNamespace(
+                    content="".join(accumulated_content) or "",
+                    tool_calls=tool_calls or None,
+                    role="assistant",
+                ),
+                finish_reason="tool_calls" if tool_calls else "stop",
+            )],
+            usage=final_usage,
+            model=self.model,
+        )
+    
+    except Exception as e:
+        logger.debug("Streaming failed, falling back to non-streaming: %s", e)
+        return self.client.chat.completions.create(**api_kwargs)
+```
+
+#### 1c. Modify _run_codex_stream() for Responses API (~10 lines)
+
+The method already iterates the stream. Add callback emission:
+
+```python
+def _run_codex_stream(self, api_kwargs: dict):
+    with self.client.responses.stream(**api_kwargs) as stream:
+        for event in stream:
+            # Emit text deltas if streaming callback is set
+            if self.stream_callback and hasattr(event, 'type'):
+                if event.type == 'response.output_text.delta':
+                    try:
+                        self.stream_callback(event.delta)
+                    except Exception:
+                        pass
+        return stream.get_final_response()
+```
+
+#### 1d. Modify _interruptible_api_call() (~5 lines)
+
+Add the streaming branch:
+
+```python
+def _call():
+    try:
+        if self.api_mode == "codex_responses":
+            result["response"] = self._run_codex_stream(api_kwargs)
+        elif self.stream_callback is not None:
+            result["response"] = self._run_streaming_chat_completion(api_kwargs)
+        else:
+            result["response"] = self.client.chat.completions.create(**api_kwargs)
+    except Exception as e:
+        result["error"] = e
+```
+
+#### 1e. Signal end-of-stream to consumers (~5 lines)
+
+After the API call returns, signal the callback that streaming is done
+so consumers can finalize (remove cursor, close SSE, etc.):
+
+```python
+# In run_conversation(), after _interruptible_api_call returns:
+if self.stream_callback:
+    try:
+        self.stream_callback(None)  # None = end of stream signal
+    except Exception:
+        pass
+```
+
+Consumers check: `if delta is None: finalize()`
+
+**Tests for Phase 1:** (~150 lines)
+- Test _run_streaming_chat_completion with mocked stream
+- Test fallback to non-streaming on error
+- Test tool_call accumulation during streaming
+- Test stream_callback receives correct deltas
+- Test None signal at end of stream
+- Test streaming disabled when callback is None
+
+---
+
+### Phase 2: Gateway consumers (Telegram, Discord, etc.)
+
+**File: gateway/run.py**
+
+#### 2a. Read streaming config (~15 lines)
+
+In `_run_agent()`, before creating the AIAgent:
+
+```python
+# Read streaming config
+_streaming_enabled = False
+try:
+    # Check per-platform override first
+    platform_key = source.platform.value if source.platform else ""
+    _stream_cfg = {}  # loaded from config.yaml streaming section
+    if _stream_cfg.get(platform_key) is not None:
+        _streaming_enabled = bool(_stream_cfg[platform_key])
+    else:
+        _streaming_enabled = bool(_stream_cfg.get("enabled", False))
+except Exception:
+    pass
+# Env var override
+if os.getenv("HERMES_STREAMING_ENABLED", "").lower() in ("true", "1", "yes"):
+    _streaming_enabled = True
+```
+
+#### 2b. Set up queue + callback (~15 lines)
+
+```python
+_stream_q = None
+_stream_done = None
+_stream_msg_id = [None]  # mutable ref for the async task
+
+if _streaming_enabled:
+    import queue as _q
+    _stream_q = _q.Queue()
+    _stream_done = threading.Event()
+    
+    def _on_token(delta):
+        if delta is None:
+            _stream_done.set()
+        else:
+            _stream_q.put(delta)
+```
+
+Pass `stream_callback=_on_token` to the AIAgent constructor.
+
+#### 2c. Telegram/Discord stream preview task (~50 lines)
+
+```python
+async def stream_preview():
+    """Progressively edit a message with streaming tokens."""
+    if not _stream_q:
+        return
+    adapter = self.adapters.get(source.platform)
+    if not adapter:
+        return
+    
+    accumulated = []
+    token_count = 0
+    last_edit = 0.0
+    MIN_TOKENS = 20          # Don't show until enough context
+    EDIT_INTERVAL = 1.5      # Respect Telegram rate limits
+    
+    try:
+        while not _stream_done.is_set():
+            try:
+                chunk = _stream_q.get(timeout=0.1)
+                accumulated.append(chunk)
+                token_count += 1
+            except queue.Empty:
+                continue
+            
+            now = time.monotonic()
+            if token_count >= MIN_TOKENS and (now - last_edit) >= EDIT_INTERVAL:
+                preview = "".join(accumulated) + " ▌"
+                if _stream_msg_id[0] is None:
+                    r = await adapter.send(
+                        chat_id=source.chat_id,
+                        content=preview,
+                        metadata=_thread_metadata,
+                    )
+                    if r.success and r.message_id:
+                        _stream_msg_id[0] = r.message_id
+                else:
+                    await adapter.edit_message(
+                        chat_id=source.chat_id,
+                        message_id=_stream_msg_id[0],
+                        content=preview,
+                    )
+                last_edit = now
+        
+        # Drain remaining tokens
+        while not _stream_q.empty():
+            accumulated.append(_stream_q.get_nowait())
+        
+        # Final edit — remove cursor, show complete text
+        if _stream_msg_id[0] and accumulated:
+            await adapter.edit_message(
+                chat_id=source.chat_id,
+                message_id=_stream_msg_id[0],
+                content="".join(accumulated),
+            )
+    
+    except asyncio.CancelledError:
+        # Clean up on cancel
+        if _stream_msg_id[0] and accumulated:
+            try:
+                await adapter.edit_message(
+                    chat_id=source.chat_id,
+                    message_id=_stream_msg_id[0],
+                    content="".join(accumulated),
+                )
+            except Exception:
+                pass
+    except Exception as e:
+        logger.debug("stream_preview error: %s", e)
+```
+
+#### 2d. Skip final send if already streamed (~10 lines)
+
+In `_process_message_background()` (base.py), after getting the response,
+if streaming was active and `_stream_msg_id[0]` is set, the final response
+was already delivered via progressive edits. Skip the normal `self.send()`
+call to avoid duplicating the message.
+
+This is the most delicate integration point — we need to communicate from
+the gateway's `_run_agent` back to the base adapter's response sender that
+the response was already delivered. Options:
+
+- **Option A**: Return a special marker in the result dict:
+  `result["_streamed_msg_id"] = _stream_msg_id[0]`
+  The base adapter checks this and skips `send()`.
+  
+- **Option B**: Edit the already-sent message with the final response
+  (which may differ slightly from accumulated tokens due to think-block
+  stripping, etc.) and don't send a new one.
+
+- **Option C**: The stream preview task handles the FULL final response
+  (including any post-processing), and the handler returns None to skip
+  the normal send path.
+
+Recommended: **Option A** — cleanest separation. The result dict already
+carries metadata; adding one more field is low-risk.
+
+**Platform-specific considerations:**
+
+| Platform | Edit support | Rate limits | Streaming approach |
+|----------|-------------|-------------|-------------------|
+| Telegram | ✅ edit_message_text | ~20 edits/min | Edit every 1.5s |
+| Discord | ✅ message.edit | 5 edits/5s per message | Edit every 1.2s |
+| Slack | ✅ chat.update | Tier 3 (~50/min) | Edit every 1.5s |
+| WhatsApp | ❌ no edit support | N/A | Skip streaming, use normal path |
+| HomeAssistant | ❌ no edit | N/A | Skip streaming |
+| API Server | ✅ SSE native | No limit | Real SSE events |
+
+WhatsApp and HomeAssistant fall back to non-streaming automatically because
+they don't support message editing.
+
+**Tests for Phase 2:** (~100 lines)
+- Test stream_preview sends/edits correctly
+- Test skip-final-send when streaming delivered
+- Test WhatsApp/HA graceful fallback
+- Test streaming disabled per-platform config
+- Test thread_id metadata forwarded in stream messages
+
+---
+
+### Phase 3: CLI streaming
+
+**File: cli.py**
+
+#### 3a. Set up callback in the CLI chat loop (~20 lines)
+
+In `_chat_once()` or wherever the agent is invoked:
+
+```python
+if streaming_enabled:
+    _stream_q = queue.Queue()
+    _stream_done = threading.Event()
+    
+    def _cli_stream_callback(delta):
+        if delta is None:
+            _stream_done.set()
+        else:
+            _stream_q.put(delta)
+    
+    agent.stream_callback = _cli_stream_callback
+```
+
+#### 3b. Token display thread/task (~30 lines)
+
+Start a thread that reads the queue and prints tokens:
+
+```python
+def _stream_display():
+    """Print tokens to terminal as they arrive."""
+    first_token = True
+    while not _stream_done.is_set():
+        try:
+            delta = _stream_q.get(timeout=0.1)
+        except queue.Empty:
+            continue
+        if first_token:
+            # Print response box top border
+            _cprint(f"\n{top}")
+            first_token = False
+        sys.stdout.write(delta)
+        sys.stdout.flush()
+    # Drain remaining
+    while not _stream_q.empty():
+        sys.stdout.write(_stream_q.get_nowait())
+    sys.stdout.flush()
+    # Print bottom border
+    _cprint(f"\n\n{bot}")
+```
+
+**Integration challenge: prompt_toolkit**
+
+The CLI uses prompt_toolkit which controls the terminal. Writing directly
+to stdout while prompt_toolkit is active can cause display corruption.
+The existing KawaiiSpinner already solves this by using prompt_toolkit's
+`patch_stdout` context. The streaming display would need to do the same.
+
+Alternative: use `_cprint()` for each token chunk (routes through
+prompt_toolkit's renderer). But this might be slow for individual tokens.
+
+Recommended approach: accumulate tokens in small batches (e.g., every 50ms)
+and `_cprint()` the batch. This balances display responsiveness with
+prompt_toolkit compatibility.
+
+**Tests for Phase 3:** (~50 lines)
+- Test CLI streaming callback setup
+- Test response box borders with streaming
+- Test fallback when streaming disabled
+
+---
+
+### Phase 4: API Server real streaming
+
+**File: gateway/platforms/api_server.py**
+
+Replace the pseudo-streaming `_write_sse_chat_completion()` with real
+token-by-token SSE when the agent supports it.
+
+#### 4a. Wire streaming callback for stream=true requests (~20 lines)
+
+```python
+if stream:
+    _stream_q = queue.Queue()
+    
+    def _api_stream_callback(delta):
+        _stream_q.put(delta)  # None = done
+    
+    # Pass callback to _run_agent
+    result, usage = await self._run_agent(
+        ..., stream_callback=_api_stream_callback,
+    )
+```
+
+#### 4b. Real SSE writer (~40 lines)
+
+```python
+async def _write_real_sse(self, request, completion_id, model, stream_q):
+    response = web.StreamResponse(
+        headers={"Content-Type": "text/event-stream", "Cache-Control": "no-cache"},
+    )
+    await response.prepare(request)
+    
+    # Role chunk
+    await response.write(...)
+    
+    # Stream content chunks as they arrive
+    while True:
+        try:
+            delta = await asyncio.get_event_loop().run_in_executor(
+                None, lambda: stream_q.get(timeout=0.1)
+            )
+        except queue.Empty:
+            continue
+        
+        if delta is None:  # End of stream
+            break
+        
+        chunk = {"id": completion_id, "object": "chat.completion.chunk", ...
+                 "choices": [{"delta": {"content": delta}, ...}]}
+        await response.write(f"data: {json.dumps(chunk)}\n\n".encode())
+    
+    # Finish + [DONE]
+    await response.write(...)
+    await response.write(b"data: [DONE]\n\n")
+    return response
+```
+
+**Challenge: concurrent execution**
+
+The agent runs in a thread executor. SSE writing happens in the async event
+loop. The queue bridges them. But `_run_agent()` currently awaits the full
+result before returning. For real streaming, we need to start the agent in
+the background and stream tokens while it runs:
+
+```python
+# Start agent in background
+agent_task = asyncio.create_task(self._run_agent_async(...))
+
+# Stream tokens while agent runs
+await self._write_real_sse(request, ..., stream_q)
+
+# Agent is done by now (stream_q received None)
+result, usage = await agent_task
+```
+
+This requires splitting `_run_agent` into an async version that doesn't
+block waiting for the result, or running it in a separate task.
+
+**Responses API SSE format:**
+
+For `/v1/responses` with `stream=true`, the SSE events are different:
+
+```
+event: response.output_text.delta
+data: {"type":"response.output_text.delta","delta":"Hello"}
+
+event: response.completed  
+data: {"type":"response.completed","response":{...}}
+```
+
+This needs a separate SSE writer that emits Responses API format events.
+
+**Tests for Phase 4:** (~80 lines)
+- Test real SSE streaming with mocked agent
+- Test SSE event format (Chat Completions vs Responses)
+- Test client disconnect during streaming
+- Test fallback to pseudo-streaming when callback not available
+
+---
+
+## Integration Issues & Edge Cases
+
+### 1. Tool calls during streaming
+
+When the model returns tool calls instead of text, no text tokens are emitted.
+The stream_callback is simply never called with text. After tools execute, the
+next API call may produce the final text response — streaming picks up again.
+
+The stream preview task needs to handle this: if no tokens arrive during a
+tool-call round, don't send/edit any message. The tool progress messages
+continue working as before.
+
+### 2. Duplicate messages
+
+The biggest risk: the agent sends the final response normally (via the
+existing send path) AND the stream preview already showed it. The user
+sees the response twice.
+
+Prevention: when streaming is active and tokens were delivered, the final
+response send must be suppressed. The `result["_streamed_msg_id"]` marker
+tells the base adapter to skip its normal send.
+
+### 3. Response post-processing
+
+The final response may differ from the accumulated streamed tokens:
+- Think block stripping (`<think>...</think>` removed)
+- Trailing whitespace cleanup
+- Tool result media tag appending
+
+The stream preview shows raw tokens. The final edit should use the
+post-processed version. This means the final edit (removing the cursor)
+should use the post-processed `final_response`, not just the accumulated
+stream text.
+
+### 4. Context compression during streaming
+
+If the agent triggers context compression mid-conversation, the streaming
+tokens from BEFORE compression are from a different context than those
+after. This isn't a problem in practice — compression happens between
+API calls, not during streaming.
+
+### 5. Interrupt during streaming
+
+User sends a new message while streaming → interrupt. The stream is killed
+(HTTP connection closed), accumulated tokens are shown as-is (no cursor),
+and the interrupt message is processed normally. This is already handled by
+`_interruptible_api_call` closing the client.
+
+### 6. Multi-model / fallback
+
+If the primary model fails and the agent falls back to a different model,
+streaming state resets. The fallback call may or may not support streaming.
+The graceful fallback in `_run_streaming_chat_completion` handles this.
+
+### 7. Rate limiting on edits
+
+Telegram: ~20 edits/minute (~1 every 3 seconds to be safe)
+Discord: 5 edits per 5 seconds per message
+Slack: ~50 API calls/minute
+
+The 1.5s edit interval is conservative enough for all platforms. If we get
+429 rate limit errors on edits, just skip that edit cycle and try next time.
+
+---
+
+## Files Changed Summary
+
+| File | Phase | Changes |
+|------|-------|---------|
+| `run_agent.py` | 1 | +stream_callback param, +_run_streaming_chat_completion(), modify _run_codex_stream(), modify _interruptible_api_call() |
+| `gateway/run.py` | 2 | +streaming config reader, +queue/callback setup, +stream_preview task, +skip-final-send logic |
+| `gateway/platforms/base.py` | 2 | +check for _streamed_msg_id in response handler |
+| `cli.py` | 3 | +streaming setup, +token display, +response box integration |
+| `gateway/platforms/api_server.py` | 4 | +real SSE writer, +streaming callback wiring |
+| `hermes_cli/config.py` | 1 | +streaming config defaults |
+| `cli-config.yaml.example` | 1 | +streaming section |
+| `tests/test_streaming.py` | 1-4 | NEW — ~380 lines of tests |
+
+**Total new code**: ~500 lines across all phases
+**Total test code**: ~380 lines
+
+---
+
+## Rollout Plan
+
+1. **Phase 1** (core): Merge to main. Streaming disabled by default.
+   Zero impact on existing behavior. Can be tested with env var.
+
+2. **Phase 2** (gateway): Merge to main. Test on Telegram manually.
+   Enable per-platform: `streaming.telegram: true` in config.
+
+3. **Phase 3** (CLI): Merge to main. Test in terminal.
+   Enable: `streaming.cli: true` or `streaming.enabled: true`.
+
+4. **Phase 4** (API server): Merge to main. Test with Open WebUI.
+   Auto-enabled when client sends `stream: true`.
+
+Each phase is independently mergeable and testable. Streaming stays
+off by default throughout. Once all phases are stable, consider
+changing the default to enabled.
+
+---
+
+## Config Reference (final state)
+
+```yaml
+# config.yaml
+streaming:
+  enabled: false          # Master switch (default: off)
+  cli: true               # Per-platform override
+  telegram: true
+  discord: true
+  slack: true
+  api_server: true        # API server always streams when client requests it
+  edit_interval: 1.5      # Seconds between message edits (default: 1.5)
+  min_tokens: 20          # Tokens before first display (default: 20)
+```
+
+```bash
+# Environment variable override
+HERMES_STREAMING_ENABLED=true
+```

reference/openai-codex/.bazelignore

@@ -0,0 +1,4 @@
+# Without this, Bazel will consider BUILD.bazel files in
+# .git/sl/origbackups (which can be populated by Sapling SCM).
+.git
+codex-rs/target

reference/openai-codex/.bazelrc

@@ -0,0 +1,202 @@
+common --repo_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1
+common --repo_env=BAZEL_NO_APPLE_CPP_TOOLCHAIN=1
+# Dummy xcode config so we don't need to build xcode_locator in repo rule.
+common --xcode_version_config=//:disable_xcode
+
+common --disk_cache=~/.cache/bazel-disk-cache
+common --repo_contents_cache=~/.cache/bazel-repo-contents-cache
+common --repository_cache=~/.cache/bazel-repo-cache
+common --remote_cache_compression
+startup --experimental_remote_repo_contents_cache
+
+common --experimental_platform_in_output_dir
+
+# Runfiles strategy rationale: codex-rs/utils/cargo-bin/README.md
+common --noenable_runfiles
+
+common --enable_platform_specific_config
+common:linux --host_platform=//:local_linux
+common:windows --host_platform=//:local_windows
+common --@rules_cc//cc/toolchains/args/archiver_flags:use_libtool_on_macos=False
+common --@llvm//config:experimental_stub_libgcc_s
+
+# TODO(zbarsky): rules_rust doesn't implement this flag properly with remote exec...
+# common --@rules_rust//rust/settings:pipelined_compilation
+
+common --incompatible_strict_action_env
+# Not ideal, but We need to allow dotslash to be found
+common:linux --test_env=PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+common:macos --test_env=PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+
+# Pass through some env vars Windows needs to use powershell?
+common:windows --test_env=SYSTEMROOT
+common:windows --test_env=COMSPEC
+common:windows --test_env=WINDIR
+# Rust's libtest harness runs test bodies on std-spawned threads. The default
+# 2 MiB stack can be too small for large async test futures on Windows CI; see
+# https://github.com/openai/codex/pull/19067 for the motivating failure.
+common --test_env=RUST_MIN_STACK=8388608 # 8 MiB
+
+common --test_output=errors
+common --bes_results_url=https://app.buildbuddy.io/invocation/
+common --bes_backend=grpcs://remote.buildbuddy.io
+common --remote_cache=grpcs://remote.buildbuddy.io
+common --remote_download_toplevel
+common --nobuild_runfile_links
+common --remote_timeout=3600
+common --noexperimental_throttle_remote_action_building
+common --experimental_remote_execution_keepalive
+common --grpc_keepalive_time=30s
+common --experimental_remote_downloader=grpcs://remote.buildbuddy.io
+
+# This limits both in-flight executions and concurrent downloads. Even with high number
+# of jobs execution will still be limited by CPU cores, so this just pays a bit of
+# memory in exchange for higher download concurrency.
+common --jobs=30
+
+common:remote --extra_execution_platforms=//:rbe
+common:remote --remote_executor=grpcs://remote.buildbuddy.io
+common:remote --jobs=800
+# TODO(team): Evaluate if this actually helps, zbarsky is not sure, everything seems bottlenecked on `core` either way.
+# Enable pipelined compilation since we are not bound by local CPU count.
+#common:remote --@rules_rust//rust/settings:pipelined_compilation
+
+# GitHub Actions CI configs.
+common:ci --remote_download_minimal
+common:ci --keep_going
+common:ci --verbose_failures
+common:ci --build_metadata=REPO_URL=https://github.com/openai/codex.git
+common:ci --build_metadata=ROLE=CI
+common:ci --build_metadata=VISIBILITY=PUBLIC
+# rules_rust derives debug level from Bazel toolchain/compilation-mode settings,
+# not Cargo profiles. Keep CI Rust actions explicit and lean.
+common:ci --@rules_rust//rust/settings:extra_rustc_flag=-Cdebuginfo=0
+common:ci --@rules_rust//rust/settings:extra_exec_rustc_flag=-Cdebuginfo=0
+
+# Disable disk cache in CI since we have a remote one and aren't using persistent workers.
+common:ci --disk_cache=
+
+# Shared config for the main Bazel CI workflow.
+common:ci-bazel --config=ci
+common:ci-bazel --build_metadata=TAG_workflow=bazel
+# Bazel CI cross-compiles in several legs, and the V8-backed code-mode tests
+# are not stable in that setup yet. Keep running the rest of the Rust
+# integration suites through the workspace-root launcher.
+common:ci-bazel --test_env=CODEX_BAZEL_TEST_SKIP_FILTERS=suite::code_mode::
+
+# Shared config for Bazel-backed Rust linting.
+build:clippy --aspects=@rules_rust//rust:defs.bzl%rust_clippy_aspect
+build:clippy --output_groups=+clippy_checks
+build:clippy --@rules_rust//rust/settings:clippy.toml=//codex-rs:clippy.toml
+# Keep this deny-list in sync with `codex-rs/Cargo.toml` `[workspace.lints.clippy]`.
+# Cargo applies those lint levels to member crates that opt into `[lints] workspace = true`
+# in their own `Cargo.toml`, but `rules_rust` Bazel clippy does not read Cargo lint levels.
+# `clippy.toml` can configure lint behavior, but it cannot set allow/warn/deny/forbid levels.
+build:clippy --@rules_rust//rust/settings:clippy_flag=-Dwarnings
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::await_holding_invalid_type
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::await_holding_lock
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::expect_used
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::identity_op
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_clamp
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_filter
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_find
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_flatten
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_map
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_memcpy
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_non_exhaustive
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_ok_or
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_range_contains
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_retain
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_strip
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_try_fold
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::manual_unwrap_or
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::needless_borrow
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::needless_borrowed_reference
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::needless_collect
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::needless_late_init
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::needless_option_as_deref
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::needless_question_mark
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::needless_update
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::redundant_clone
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::redundant_closure
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::redundant_closure_for_method_calls
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::redundant_static_lifetimes
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::trivially_copy_pass_by_ref
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::uninlined_format_args
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::unnecessary_filter_map
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::unnecessary_lazy_evaluations
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::unnecessary_sort_by
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::unnecessary_to_owned
+build:clippy --@rules_rust//rust/settings:clippy_flag=--deny=clippy::unwrap_used
+
+# Shared config for Bazel-backed argument-comment-lint.
+build:argument-comment-lint --aspects=//tools/argument-comment-lint:lint_aspect.bzl%rust_argument_comment_lint_aspect
+build:argument-comment-lint --output_groups=argument_comment_lint_checks
+build:argument-comment-lint --@rules_rust//rust/toolchain/channel=nightly
+
+# Rearrange caches on Windows so they're on the same volume as the checkout.
+common:ci-windows --config=ci-bazel
+common:ci-windows --build_metadata=TAG_os=windows
+common:ci-windows --repo_contents_cache=D:/a/.cache/bazel-repo-contents-cache
+
+# We prefer to run the build actions entirely remotely so we can dial up the concurrency.
+# We have platform-specific tests, so we want to execute the tests on all platforms using the strongest sandboxing available on each platform.
+
+# On linux, we can do a full remote build/test, by targeting the right (x86/arm) runners, so we have coverage of both.
+# Linux crossbuilds don't work until we untangle the libc constraint mess.
+common:ci-linux --config=ci-bazel
+common:ci-linux --build_metadata=TAG_os=linux
+common:ci-linux --config=remote
+common:ci-linux --strategy=remote
+common:ci-linux --platforms=//:rbe
+
+# On mac, we can run all the build actions remotely but test actions locally.
+common:ci-macos --config=ci-bazel
+common:ci-macos --build_metadata=TAG_os=macos
+common:ci-macos --config=remote
+common:ci-macos --strategy=remote
+common:ci-macos --strategy=TestRunner=darwin-sandbox,local
+
+# On Windows, use Linux remote execution for build actions but keep test actions
+# on the Windows runner so Bazel's normal test sharding and flaky-test retries
+# still run against Windows binaries.
+common:ci-windows-cross --config=ci-windows
+common:ci-windows-cross --build_metadata=TAG_windows_cross_compile=true
+common:ci-windows-cross --config=remote
+common:ci-windows-cross --host_platform=//:rbe
+common:ci-windows-cross --strategy=remote
+common:ci-windows-cross --strategy=TestRunner=local
+common:ci-windows-cross --local_test_jobs=4
+common:ci-windows-cross --test_env=RUST_TEST_THREADS=1
+# Native Windows CI still covers the PowerShell tests. The cross-built gnullvm
+# binaries currently hang in PowerShell AST parser tests when those binaries are
+# run on the Windows runner.
+common:ci-windows-cross --test_env=CODEX_BAZEL_TEST_SKIP_FILTERS=suite::code_mode::,powershell
+common:ci-windows-cross --platforms=//:windows_x86_64_gnullvm
+common:ci-windows-cross --extra_execution_platforms=//:rbe,//:windows_x86_64_msvc
+common:ci-windows-cross --extra_toolchains=//:windows_gnullvm_tests_on_msvc_host_toolchain
+
+# Linux-only V8 CI config.
+common:ci-v8 --config=ci
+common:ci-v8 --build_metadata=TAG_workflow=v8
+common:ci-v8 --build_metadata=TAG_os=linux
+common:ci-v8 --config=remote
+common:ci-v8 --strategy=remote
+
+# Source-built Bazel V8 artifacts use the in-process sandbox by default. This
+# does not affect Cargo's default prebuilt rusty_v8 path.
+common --@v8//:v8_enable_pointer_compression=True
+common --@v8//:v8_enable_sandbox=True
+
+# Keep currently published rusty_v8 release artifacts non-sandboxed until the
+# artifact migration ships matching Rust feature selection for Cargo consumers.
+common:v8-release-compat --@v8//:v8_enable_pointer_compression=False
+common:v8-release-compat --@v8//:v8_enable_sandbox=False
+
+# Match rusty_v8's upstream GN release contract for published artifacts: every
+# target object uses Chromium's custom libc++ headers and the archive folds in
+# the matching runtime objects.
+common:rusty-v8-upstream-libcxx --@v8//:v8_use_rusty_v8_custom_libcxx=True
+
+# Optional per-user local overrides.
+try-import %workspace%/user.bazelrc

reference/openai-codex/.bazelversion

@@ -0,0 +1 @@
+9.0.0

reference/openai-codex/.codespellignore

@@ -0,0 +1,6 @@
+iTerm
+iTerm2
+psuedo
+SOM
+te
+TE

reference/openai-codex/.codespellrc

@@ -0,0 +1,6 @@
+[codespell]
+# Ref: https://github.com/codespell-project/codespell#using-a-config-file
+skip = .git*,vendor,*-lock.yaml,*.lock,.codespellrc,*test.ts,*.jsonl,frame*.txt,*.snap,*.snap.new
+check-hidden = true
+ignore-regex = ^\s*"image/\S+": ".*|\b(afterAll)\b
+ignore-words-list = ratatui,ser,iTerm,iterm2,iterm,te,TE,PASE,SEH

reference/openai-codex/.codex/environments/environment.toml

@@ -0,0 +1,11 @@
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "codex"
+
+[setup]
+script = ""
+
+[[actions]]
+name = "Run"
+icon = "run"
+command = "cargo +1.93.0 run --manifest-path=codex-rs/Cargo.toml --bin codex -- -c mcp_oauth_credentials_store=file"

reference/openai-codex/.codex/skills/babysit-pr/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: babysit-pr
+description: Babysit a GitHub pull request after creation by continuously polling review comments, CI checks/workflow runs, and mergeability state until the PR is merged/closed or user help is required. Diagnose failures, retry likely flaky failures up to 3 times, auto-fix/push branch-related issues when appropriate, and keep watching open PRs so fresh review feedback is surfaced promptly. Use when the user asks Codex to monitor a PR, watch CI, handle review comments, or keep an eye on failures and feedback on an open PR.
+---
+
+# PR Babysitter
+
+## Objective
+Babysit a PR persistently until one of these terminal outcomes occurs:
+
+- The PR is merged or closed.
+- A situation requires user help (for example CI infrastructure issues, repeated flaky failures after retry budget is exhausted, permission problems, or ambiguity that cannot be resolved safely).
+- Optional handoff milestone: the PR is currently green + mergeable + review-clean. Treat this as a progress state, not a watcher stop, so late-arriving review comments are still surfaced promptly while the PR remains open.
+
+Do not stop merely because a single snapshot returns `idle` while checks are still pending.
+
+## Inputs
+Accept any of the following:
+
+- No PR argument: infer the PR from the current branch (`--pr auto`)
+- PR number
+- PR URL
+
+## Core Workflow
+
+1. When the user asks to "monitor"/"watch"/"babysit" a PR, start with the watcher's continuous mode (`--watch`) unless you are intentionally doing a one-shot diagnostic snapshot.
+2. Run the watcher script to snapshot PR/review/CI state (or consume each streamed snapshot from `--watch`).
+3. Inspect the `actions` list in the JSON response.
+4. If `diagnose_ci_failure` is present, inspect failed run logs and classify the failure.
+5. If the failure is likely caused by the current branch, patch code locally, commit, and push. Do not patch random flaky tests, CI infrastructure, dependency outages, runner issues, or other failures that are unrelated to the branch.
+6. If `process_review_comment` is present, inspect surfaced review items and decide whether to address them.
+7. If a review item is actionable and correct, patch code locally, commit, push, and then mark the associated review thread/comment as resolved once the fix is on GitHub.
+8. Do not post replies to human-authored review comments/threads unless the user explicitly confirms the exact response. If a human review item is non-actionable, already addressed, or not valid, surface the item and recommended response to the user instead of replying on GitHub.
+9. If the failure is likely flaky/unrelated and `retry_failed_checks` is present, rerun failed jobs with `--retry-failed-now`.
+10. If both actionable review feedback and `retry_failed_checks` are present, prioritize review feedback first; a new commit will retrigger CI, so avoid rerunning flaky checks on the old SHA unless you intentionally defer the review change.
+11. On every loop, look for newly surfaced review feedback before acting on CI failures or mergeability state, then verify mergeability / merge-conflict status (for example via `gh pr view`) alongside CI.
+12. After any push or rerun action, immediately return to step 1 and continue polling on the updated SHA/state.
+13. If you had been using `--watch` before pausing to patch/commit/push, relaunch `--watch` yourself in the same turn immediately after the push (do not wait for the user to re-invoke the skill).
+14. Repeat polling until `stop_pr_closed` appears or a user-help-required blocker is reached. A green + review-clean + mergeable PR is a progress milestone, not a reason to stop the watcher while the PR is still open.
+15. Maintain terminal/session ownership: while babysitting is active, keep consuming watcher output in the same turn; do not leave a detached `--watch` process running and then end the turn as if monitoring were complete.
+
+## Commands
+
+### One-shot snapshot
+
+```bash
+python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --once
+```
+
+### Continuous watch (JSONL)
+
+```bash
+python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --watch
+```
+
+### Trigger flaky retry cycle (only when watcher indicates)
+
+```bash
+python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --retry-failed-now
+```
+
+### Explicit PR target
+
+```bash
+python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr <number-or-url> --once
+```
+
+## CI Failure Classification
+Use `gh` commands to inspect failed runs before deciding to rerun.
+
+- `gh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha`
+- `gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs -X GET -f per_page=100`
+- `gh api repos/<owner>/<repo>/actions/jobs/<job-id>/logs > /tmp/codex-gh-job-<job-id>-logs.zip`
+- `gh run view <run-id> --log-failed` as a fallback after the overall workflow run is complete
+
+`gh run view --log-failed` is workflow-run scoped and may not expose failed-job logs until the overall run finishes. For faster diagnosis, poll the run's jobs first and, as soon as a specific job has failed, fetch that job's logs directly from the Actions job logs endpoint. The watcher includes a `failed_jobs` list with each failed job's `job_id` and `logs_endpoint` when GitHub exposes one.
+
+Prefer treating failures as branch-related when failed-job logs point to changed code (compile/test/lint/typecheck/snapshots/static analysis in touched areas).
+
+Prefer treating failures as flaky/unrelated when logs show transient infra/external issues (timeouts, runner provisioning failures, registry/network outages, GitHub Actions infra errors).
+
+Do not attempt to fix flaky/unrelated failures by changing tests, build scripts, CI configuration, dependency pins, or infrastructure-adjacent code unless the logs clearly connect the failure to the PR branch. For flaky/unrelated failures, rerun only when the watcher recommends `retry_failed_checks`; otherwise wait or stop for user help.
+
+If classification is ambiguous, perform one manual diagnosis attempt before choosing rerun.
+
+Read `.codex/skills/babysit-pr/references/heuristics.md` for a concise checklist.
+
+## Review Comment Handling
+The watcher surfaces review items from:
+
+- PR issue comments
+- Inline review comments
+- Review submissions (COMMENT / APPROVED / CHANGES_REQUESTED)
+
+It intentionally surfaces Codex reviewer bot feedback (for example comments/reviews from `chatgpt-codex-connector[bot]`) in addition to human reviewer feedback. Most unrelated bot noise should still be ignored.
+For safety, the watcher only auto-surfaces trusted human review authors (for example repo OWNER/MEMBER/COLLABORATOR, plus the authenticated operator) and approved review bots such as Codex.
+On a fresh watcher state file, existing pending review feedback may be surfaced immediately (not only comments that arrive after monitoring starts). This is intentional so already-open review comments are not missed.
+
+When you agree with a comment and it is actionable:
+
+1. Patch code locally.
+2. Commit with `codex: address PR review feedback (#<n>)`.
+3. Push to the PR head branch.
+4. After the push succeeds, mark the associated GitHub review thread/comment as resolved.
+5. Resume watching on the new SHA immediately (do not stop after reporting the push).
+6. If monitoring was running in `--watch` mode, restart `--watch` immediately after the push in the same turn; do not wait for the user to ask again.
+
+Do not post replies to human-authored GitHub review comments/threads automatically. If you disagree with a human comment, believe it is non-actionable/already addressed, or need to answer a question, report the item to the user with a suggested response and wait for explicit confirmation before posting anything on GitHub. If the user approves a response, prefix it with `[codex]` so it is clear the response is automated and not from the human user.
+If the watcher later surfaces your own approved reply because the authenticated operator is treated as a trusted review author, treat that self-authored item as already handled and do not reply again.
+If a code review comment/thread is already marked as resolved in GitHub, treat it as non-actionable and safely ignore it unless new unresolved follow-up feedback appears.
+
+## Git Safety Rules
+
+- Work only on the PR head branch.
+- Avoid destructive git commands.
+- Do not switch branches unless necessary to recover context.
+- Before editing, check for unrelated uncommitted changes. If present, stop and ask the user.
+- After each successful fix, commit and `git push`, then re-run the watcher.
+- If you interrupted a live `--watch` session to make the fix, restart `--watch` immediately after the push in the same turn.
+- Do not run multiple concurrent `--watch` processes for the same PR/state file; keep one watcher session active and reuse it until it stops or you intentionally restart it.
+- A push is not a terminal outcome; continue the monitoring loop unless a strict stop condition is met.
+
+Commit message defaults:
+
+- `codex: fix CI failure on PR #<n>`
+- `codex: address PR review feedback (#<n>)`
+
+## Monitoring Loop Pattern
+Use this loop in a live Codex session:
+
+1. Run `--once`.
+2. Read `actions`.
+3. First check whether the PR is now merged or otherwise closed; if so, report that terminal state and stop polling immediately.
+4. Check CI summary, new review items, and mergeability/conflict status.
+5. Diagnose CI failures and classify branch-related vs flaky/unrelated. If the overall run is still pending but `failed_jobs` already includes a failed job, fetch that job's logs and diagnose immediately instead of waiting for the whole workflow run to finish. Patch only when the failure is branch-related.
+6. For each surfaced review item from another author, patch/commit/push and then resolve it if it is actionable. If it is non-actionable, already addressed, or requires a written answer, surface it to the user with a suggested response instead of posting automatically. If a later snapshot surfaces your own approved reply, treat it as informational and continue without responding again.
+7. Process actionable review comments before flaky reruns when both are present; if a review fix requires a commit, push it and skip rerunning failed checks on the old SHA.
+8. Retry failed checks only when `retry_failed_checks` is present and you are not about to replace the current SHA with a review/CI fix commit. Do not make code changes for unrelated flakes or infrastructure failures just to get CI green.
+9. If you pushed a commit, resolved a review thread, or triggered a rerun, report the action briefly and continue polling (do not stop). If a human review comment needs a written GitHub response, stop and ask for confirmation before posting.
+10. After a review-fix push, proactively restart continuous monitoring (`--watch`) in the same turn unless a strict stop condition has already been reached.
+11. If everything is passing, mergeable, not blocked on required review approval, and there are no unaddressed review items, report that the PR is currently ready to merge but keep the watcher running so new review comments are surfaced quickly while the PR remains open.
+12. If blocked on a user-help-required issue (infra outage, exhausted flaky retries, unclear reviewer request, permissions), report the blocker and stop.
+13. Otherwise sleep according to the polling cadence below and repeat.
+
+When the user explicitly asks to monitor/watch/babysit a PR, prefer `--watch` so polling continues autonomously in one command. Use repeated `--once` snapshots only for debugging, local testing, or when the user explicitly asks for a one-shot check.
+Do not stop to ask the user whether to continue polling; continue autonomously until a strict stop condition is met or the user explicitly interrupts.
+Do not hand control back to the user after a review-fix push just because a new SHA was created; restarting the watcher and re-entering the poll loop is part of the same babysitting task.
+If a `--watch` process is still running and no strict stop condition has been reached, the babysitting task is still in progress; keep streaming/consuming watcher output instead of ending the turn.
+
+## Polling Cadence
+Keep review polling aggressive and continue monitoring even after CI turns green:
+
+- While CI is not green (pending/running/queued or failing): poll every 1 minute.
+- After CI turns green: keep polling at the base cadence while the PR remains open so newly posted review comments are surfaced promptly instead of waiting on a long green-state backoff.
+- Reset the cadence immediately whenever anything changes (new commit/SHA, check status changes, new review comments, mergeability changes, review decision changes).
+- If CI stops being green again (new commit, rerun, or regression): stay on the base polling cadence.
+- If any poll shows the PR is merged or otherwise closed: stop polling immediately and report the terminal state.
+
+## Stop Conditions (Strict)
+Stop only when one of the following is true:
+
+- PR merged or closed (stop as soon as a poll/snapshot confirms this).
+- User intervention is required and Codex cannot safely proceed alone.
+
+Keep polling when:
+
+- `actions` contains only `idle` but checks are still pending.
+- CI is still running/queued.
+- Review state is quiet but CI is not terminal.
+- CI is green but mergeability is unknown/pending.
+- CI is green and mergeable, but the PR is still open and you are waiting for possible new review comments or merge-conflict changes.
+- The PR is green but blocked on review approval (`REVIEW_REQUIRED` / similar); continue polling at the base cadence and surface any new review comments without asking for confirmation to keep watching.
+
+## Output Expectations
+Provide concise progress updates while monitoring and a final summary that includes:
+
+- During long unchanged monitoring periods, avoid emitting a full update on every poll; summarize only status changes plus occasional heartbeat updates.
+- Treat push confirmations, intermediate CI snapshots, ready-to-merge snapshots, and review-action updates as progress updates only; do not emit the final summary or end the babysitting session unless a strict stop condition is met.
+- A user request to "monitor" is not satisfied by a couple of sample polls; remain in the loop until a strict stop condition or an explicit user interruption.
+- A review-fix commit + push is not a completion event; immediately resume live monitoring (`--watch`) in the same turn and continue reporting progress updates.
+- When CI first transitions to all green for the current SHA, emit a one-time celebratory progress update (do not repeat it on every green poll). Preferred style: `🚀 CI is all green! 33/33 passed. Still on watch for review approval.`
+- Do not send the final summary while a watcher terminal is still running unless the watcher has emitted/confirmed a strict stop condition; otherwise continue with progress updates.
+
+- Final PR SHA
+- CI status summary
+- Mergeability / conflict status
+- Fixes pushed
+- Flaky retry cycles used
+- Remaining unresolved failures or review comments
+
+## References
+
+- Heuristics and decision tree: `.codex/skills/babysit-pr/references/heuristics.md`
+- GitHub CLI/API details used by the watcher: `.codex/skills/babysit-pr/references/github-api-notes.md`

reference/openai-codex/.codex/skills/babysit-pr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PR Babysitter"
+  short_description: "Watch PR review comments, CI, and merge conflicts"
+  default_prompt: "Babysit the current PR: monitor reviewer comments, CI, and merge-conflict status (prefer the watcher’s --watch mode for live monitoring); surface new review feedback before acting on CI or mergeability work, fix valid issues, push updates, and rerun flaky failures up to 3 times. Do not post replies to human-authored review comments unless the user explicitly confirms the exact response. Do not patch unrelated flaky tests, CI infrastructure, dependency outages, runner issues, or other failures that are not caused by the branch. Keep exactly one watcher session active for the PR (do not leave duplicate --watch terminals running). If you pause monitoring to patch review/CI feedback, restart --watch yourself immediately after the push in the same turn. If a watcher is still running and no strict stop condition has been reached, the task is still in progress: keep consuming watcher output and sending progress updates instead of ending the turn. Do not treat a green + mergeable PR as a terminal stop while it is still open; continue polling autonomously after any push/rerun so newly posted review comments are surfaced until a strict terminal stop condition is reached or the user interrupts."

reference/openai-codex/.codex/skills/babysit-pr/references/github-api-notes.md

@@ -0,0 +1,82 @@
+# GitHub CLI / API Notes For `babysit-pr`
+
+## Primary commands used
+
+### PR metadata
+
+- `gh pr view --json number,url,state,mergedAt,closedAt,headRefName,headRefOid,headRepository,headRepositoryOwner`
+
+Used to resolve PR number, URL, branch, head SHA, and closed/merged state.
+
+### PR checks summary
+
+- `gh pr checks --json name,state,bucket,link,workflow,event,startedAt,completedAt`
+
+Used to compute pending/failed/passed counts and whether the current CI round is terminal.
+
+### Workflow runs for head SHA
+
+- `gh api repos/{owner}/{repo}/actions/runs -X GET -f head_sha=<sha> -f per_page=100`
+
+Used to discover failed workflow runs and rerunnable run IDs.
+
+### Failed log inspection
+
+- `gh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha`
+- `gh api repos/{owner}/{repo}/actions/runs/{run_id}/jobs -X GET -f per_page=100`
+- `gh api repos/{owner}/{repo}/actions/jobs/{job_id}/logs > /tmp/codex-gh-job-{job_id}-logs.zip`
+- `gh run view <run-id> --log-failed`
+
+Used by Codex to classify branch-related vs flaky/unrelated failures. Prefer the direct job log endpoint as soon as a job has failed because `gh run view --log-failed` may not produce failed-job logs until the overall workflow run completes.
+
+### Retry failed jobs only
+
+- `gh run rerun <run-id> --failed`
+
+Reruns only failed jobs (and dependencies) for a workflow run.
+
+## Review-related endpoints
+
+- Issue comments on PR:
+  - `gh api repos/{owner}/{repo}/issues/<pr_number>/comments?per_page=100`
+- Inline PR review comments:
+  - `gh api repos/{owner}/{repo}/pulls/<pr_number>/comments?per_page=100`
+- Review submissions:
+  - `gh api repos/{owner}/{repo}/pulls/<pr_number>/reviews?per_page=100`
+
+## JSON fields consumed by the watcher
+
+### `gh pr view`
+
+- `number`
+- `url`
+- `state`
+- `mergedAt`
+- `closedAt`
+- `headRefName`
+- `headRefOid`
+
+### `gh pr checks`
+
+- `bucket` (`pass`, `fail`, `pending`, `skipping`)
+- `state`
+- `name`
+- `workflow`
+- `link`
+
+### Actions runs API (`workflow_runs[]`)
+
+- `id`
+- `name`
+- `status`
+- `conclusion`
+- `html_url`
+- `head_sha`
+
+### Actions run jobs API (`jobs[]`)
+
+- `id`
+- `name`
+- `status`
+- `conclusion`
+- `html_url`

reference/openai-codex/.codex/skills/babysit-pr/references/heuristics.md

@@ -0,0 +1,66 @@
+# CI / Review Heuristics
+
+## CI classification checklist
+
+Treat as **branch-related** when logs clearly indicate a regression caused by the PR branch:
+
+- Compile/typecheck/lint failures in files or modules touched by the branch
+- Deterministic unit/integration test failures in changed areas
+- Snapshot output changes caused by UI/text changes in the branch
+- Static analysis violations introduced by the latest push
+- Build script/config changes in the PR causing a deterministic failure
+
+Treat as **likely flaky or unrelated** when evidence points to transient or external issues:
+
+- DNS/network/registry timeout errors while fetching dependencies
+- Runner image provisioning or startup failures
+- GitHub Actions infrastructure/service outages
+- Cloud/service rate limits or transient API outages
+- Non-deterministic failures in unrelated integration tests with known flake patterns
+
+Do not patch likely flaky/unrelated failures. Use the retry budget for rerunnable failures, wait for pending jobs, or stop and report the blocker when the failure is persistent or infrastructure-owned.
+
+If uncertain, inspect failed logs once before choosing rerun.
+
+## Decision tree (fix vs rerun vs stop)
+
+1. If PR is merged/closed: stop.
+2. If there are failed checks:
+   - Diagnose first.
+   - If checks are still pending but an individual job has already failed: fetch that job's logs and diagnose now.
+   - If branch-related: fix locally, commit, push.
+   - If likely flaky/unrelated and all checks for the current SHA are terminal: rerun failed jobs.
+   - If likely flaky/unrelated and not safely rerunnable: stop and report the blocker; do not edit unrelated tests, build scripts, CI configuration, dependency pins, or infrastructure code.
+   - If checks are still pending and no failed job is available yet: wait.
+3. If flaky reruns for the same SHA reach the configured limit (default 3): stop and report persistent failure.
+4. Independently, process any new human review comments.
+
+## Review comment agreement criteria
+
+Address the comment when:
+
+- The comment is technically correct.
+- The change is actionable in the current branch.
+- The requested change does not conflict with the user’s intent or recent guidance.
+- The change can be made safely without unrelated refactors.
+
+Fix valid human review feedback in code when possible, but do not post a GitHub reply to a human-authored comment/thread unless the user explicitly confirms the exact response.
+
+Do not auto-fix when:
+
+- The comment is ambiguous and needs clarification.
+- The request conflicts with explicit user instructions.
+- The proposed change requires product/design decisions the user has not made.
+- The codebase is in a dirty/unrelated state that makes safe editing uncertain.
+- The comment only needs a written answer or disagreement response; propose the reply to the user instead of posting it automatically.
+
+## Stop-and-ask conditions
+
+Stop and ask the user instead of continuing automatically when:
+
+- The local worktree has unrelated uncommitted changes.
+- `gh` auth/permissions fail.
+- The PR branch cannot be pushed.
+- CI failures persist after the flaky retry budget.
+- Reviewer feedback requires a product decision or cross-team coordination.
+- A human review comment requires a written GitHub reply instead of a code change.