fix: Inline cli-install.md

.github/workflows/sync.yml

@@ -0,0 +1,32 @@
+name: Sync CLI install reference
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - skills/shared/cli-install.md
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - run: |
+          cp skills/shared/cli-install.md skills/dune/references/cli-install.md
+          cp skills/shared/cli-install.md skills/sim/references/cli-install.md
+
+      - run: |
+          git config user.name "$GITHUB_ACTOR"
+          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          git add skills/dune/references/cli-install.md skills/sim/references/cli-install.md
+
+          if git diff --staged --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "sync: copy cli-install.md to dune & sim references"
+            git push
+          fi

skills/dune/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Dune Analytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/dune/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: dune
 description: "Dune CLI for querying blockchain and on-chain data via DuneSQL, searching decoded contract tables, managing saved queries, and monitoring credit usage on Dune Analytics. Use when user asks about blockchain data, on-chain analytics, token transfers, DEX trades, smart contract events, wallet balances, Ethereum/EVM chain queries, DuneSQL, or says \"query Dune\", \"search Dune datasets\", or \"run a Dune query\"."
+license: MIT
 compatibility: Requires network access and the Dune CLI (auto-installed on first use). Works on macOS, Linux, and Windows.
 allowed-tools: Bash(dune:*) Bash(curl:*) Read
 metadata:

skills/dune/references/cli-install.md

@@ -0,0 +1,82 @@
+# CLI Installation & Version Compatibility
+
+Shared reference for all Dune CLI skills. This covers installing the `dune` binary and handling version mismatches. For authentication-specific recovery, see the install-and-recovery reference.
+
+---
+
+## CLI Not Found Recovery
+
+If a `dune` command fails because `dune` is not found on PATH (e.g. "command not found"), install it. **Always try Option A (automated) first.** Only fall back to Option B if Option A fails.
+
+### Option A -- Automated install (no user interaction)
+
+The default installer writes to `/usr/local/bin`, which requires `sudo` and fails in non-interactive terminals. Instead, install to a user-writable directory.
+
+**Choosing the install directory:**
+
+Before running any commands, read the `PATH` environment variable yourself (do NOT run PATH-scanning scripts in the user's terminal). Look for an existing directory under the user's home that is already on PATH. Common ones:
+
+- `$HOME/.local/bin`, `$HOME/bin`, `$HOME/go/bin`, `$HOME/.cargo/bin`
+- On Windows: directories under `%USERPROFILE%` (e.g. `AppData\Local\Microsoft\WindowsApps`, scoop shims)
+
+Pick the first one that exists on PATH. If none is found, fall back to `$HOME/.local/bin` (or `%USERPROFILE%\.local\bin` on Windows).
+
+**macOS / Linux -- run each step as a separate command:**
+
+1. Only if the chosen directory doesn't exist yet (i.e. using the fallback):
+   ```bash
+   mkdir -p "$HOME/.local/bin"
+   ```
+
+2. Download the installer:
+   ```bash
+   curl -sSfL -o /tmp/dune_install.sh https://github.com/duneanalytics/cli/raw/main/install.sh
+   ```
+
+3. Run the installer into the chosen directory (`INSTALL_DIR` must be on the same line -- it is **not** picked up when piping curl to bash):
+   ```bash
+   INSTALL_DIR="<chosen-dir>" bash /tmp/dune_install.sh
+   ```
+
+4. Add to PATH for the current session:
+   ```bash
+   export PATH="<chosen-dir>:$PATH"
+   ```
+
+5. Only if the fallback was used, persist to shell profile (skip if `<chosen-dir>` was already on PATH):
+   ```bash
+   grep -q '.local/bin' ~/.zshrc 2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+   ```
+   (Use `~/.bashrc` instead if the user's shell is bash.)
+
+6. Verify:
+   ```bash
+   dune --help
+   ```
+
+### Option B -- User-assisted install (fallback)
+
+If Option A fails, ask the user to run the install command themselves in a separate terminal. They can provide `sudo` if needed:
+
+**macOS / Linux:**
+```bash
+curl -sSfL https://github.com/duneanalytics/cli/raw/main/install.sh | bash
+```
+
+---
+
+## Version Compatibility
+
+Skills are written for the Dune CLI version specified by `cli_version` in each skill's frontmatter. Patch versions don't matter -- only major and minor.
+
+**Do NOT check the version proactively.** Only run `dune --version` when a command fails and the error looks like a skill/CLI incompatibility, for example:
+
+- Unknown subcommand or flag (e.g. "unknown command", "unknown flag")
+- Unexpected output format (e.g. JSON fields the skill references are missing)
+- A command documented in the skill doesn't exist
+
+When you see such an error, run `dune --version`, parse the major.minor, and compare to the skill's `cli_version`:
+
+- **Major version mismatch**: **Stop.** Tell the user the CLI version is incompatible and they must upgrade (or downgrade). Point them to re-run the install steps from Option A above.
+- **Minor version mismatch**: **Warn** the user that versions differ and recommend upgrading the CLI or the skill. Continue attempting the task -- minor differences are usually non-breaking.
+- **Versions match**: Not a version problem. Debug the error normally.

skills/dune/references/install-and-recovery.md

@@ -8,7 +8,7 @@ This reference covers CLI installation, authentication failure recovery, and ver
 
 ## CLI Not Found Recovery
 
-If the command fails because `dune` is not found on PATH (e.g. "command not found"), follow the installation steps in the [shared CLI install reference](../../shared/cli-install.md#cli-not-found-recovery).
+If the command fails because `dune` is not found on PATH (e.g. "command not found"), follow the installation steps in the [shared CLI install reference](cli-install.md#cli-not-found-recovery).
 
 ---
 
@@ -28,7 +28,7 @@ Do **not** attempt to handle the API key yourself -- the user must authenticate
 
 ## Version Compatibility
 
-See the [shared CLI version compatibility reference](../../shared/cli-install.md#version-compatibility).
+See the [shared CLI version compatibility reference](cli-install.md#version-compatibility).
 
 ---
 

skills/shared/cli-install.md

@@ -1,6 +1,6 @@
 # CLI Installation & Version Compatibility
 
-Shared reference for all Dune CLI skills. This covers installing the `dune` binary and handling version mismatches. For authentication-specific recovery, see the install-and-recovery reference in each skill.
+Shared reference for all Dune CLI skills. This covers installing the `dune` binary and handling version mismatches. For authentication-specific recovery, see the install-and-recovery reference.
 
 ---
 
@@ -54,33 +54,6 @@ Pick the first one that exists on PATH. If none is found, fall back to `$HOME/.l
    dune --help
    ```
 
-**Windows (PowerShell) -- run each step as a separate command:**
-
-1. Only if the chosen directory doesn't exist yet (i.e. using the fallback):
-   ```powershell
-   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.local\bin"
-   ```
-
-2. Run the installer:
-   ```powershell
-   $env:INSTALL_DIR = "<chosen-dir>"; irm https://github.com/duneanalytics/cli/raw/main/install.ps1 | iex
-   ```
-
-3. Add to PATH for the current session:
-   ```powershell
-   $env:Path = "<chosen-dir>;$env:Path"
-   ```
-
-4. Only if the fallback was used, persist to user PATH:
-   ```powershell
-   [Environment]::SetEnvironmentVariable("Path", "<chosen-dir>;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")
-   ```
-
-5. Verify:
-   ```powershell
-   dune --help
-   ```
-
 ### Option B -- User-assisted install (fallback)
 
 If Option A fails, ask the user to run the install command themselves in a separate terminal. They can provide `sudo` if needed:
@@ -90,15 +63,6 @@ If Option A fails, ask the user to run the install command themselves in a separ
 curl -sSfL https://github.com/duneanalytics/cli/raw/main/install.sh | bash
 ```
 
-**Windows (PowerShell):**
-```powershell
-irm https://github.com/duneanalytics/cli/raw/main/install.ps1 | iex
-```
-
-> **Security note:** Option B pipes a remote script directly into the shell. This is convenient but means the script is executed without inspection. Option A (downloading first, then running) is safer. If the user has concerns, recommend they download and inspect the script before running it.
-
-Tell the user to come back once the install is complete, then re-check with `command -v dune` (or `Get-Command dune` on Windows).
-
 ---
 
 ## Version Compatibility

skills/sim/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Dune Analytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/sim/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: sim
 description: "Dune Sim API for real-time blockchain wallet and token lookups across EVM and SVM chains. Use when user asks about wallet balances, token prices, NFT holdings, DeFi positions, transaction history, wallet activity, token holders, stablecoins, or any real-time on-chain data for a specific address. Triggers: 'check wallet', 'token balance', 'NFT holdings', 'DeFi positions', 'transaction history', 'token holders', 'token price', 'stablecoin balance', 'wallet activity', or any request involving a blockchain address (0x... or Solana base58)."
+license: MIT
 compatibility: Requires network access and the Dune CLI (auto-installed on first use). Works on macOS, Linux, and Windows.
 allowed-tools: Bash(dune:*) Bash(curl:*) Read
 metadata:

skills/sim/references/cli-install.md

@@ -0,0 +1,82 @@
+# CLI Installation & Version Compatibility
+
+Shared reference for all Dune CLI skills. This covers installing the `dune` binary and handling version mismatches. For authentication-specific recovery, see the install-and-recovery reference.
+
+---
+
+## CLI Not Found Recovery
+
+If a `dune` command fails because `dune` is not found on PATH (e.g. "command not found"), install it. **Always try Option A (automated) first.** Only fall back to Option B if Option A fails.
+
+### Option A -- Automated install (no user interaction)
+
+The default installer writes to `/usr/local/bin`, which requires `sudo` and fails in non-interactive terminals. Instead, install to a user-writable directory.
+
+**Choosing the install directory:**
+
+Before running any commands, read the `PATH` environment variable yourself (do NOT run PATH-scanning scripts in the user's terminal). Look for an existing directory under the user's home that is already on PATH. Common ones:
+
+- `$HOME/.local/bin`, `$HOME/bin`, `$HOME/go/bin`, `$HOME/.cargo/bin`
+- On Windows: directories under `%USERPROFILE%` (e.g. `AppData\Local\Microsoft\WindowsApps`, scoop shims)
+
+Pick the first one that exists on PATH. If none is found, fall back to `$HOME/.local/bin` (or `%USERPROFILE%\.local\bin` on Windows).
+
+**macOS / Linux -- run each step as a separate command:**
+
+1. Only if the chosen directory doesn't exist yet (i.e. using the fallback):
+   ```bash
+   mkdir -p "$HOME/.local/bin"
+   ```
+
+2. Download the installer:
+   ```bash
+   curl -sSfL -o /tmp/dune_install.sh https://github.com/duneanalytics/cli/raw/main/install.sh
+   ```
+
+3. Run the installer into the chosen directory (`INSTALL_DIR` must be on the same line -- it is **not** picked up when piping curl to bash):
+   ```bash
+   INSTALL_DIR="<chosen-dir>" bash /tmp/dune_install.sh
+   ```
+
+4. Add to PATH for the current session:
+   ```bash
+   export PATH="<chosen-dir>:$PATH"
+   ```
+
+5. Only if the fallback was used, persist to shell profile (skip if `<chosen-dir>` was already on PATH):
+   ```bash
+   grep -q '.local/bin' ~/.zshrc 2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+   ```
+   (Use `~/.bashrc` instead if the user's shell is bash.)
+
+6. Verify:
+   ```bash
+   dune --help
+   ```
+
+### Option B -- User-assisted install (fallback)
+
+If Option A fails, ask the user to run the install command themselves in a separate terminal. They can provide `sudo` if needed:
+
+**macOS / Linux:**
+```bash
+curl -sSfL https://github.com/duneanalytics/cli/raw/main/install.sh | bash
+```
+
+---
+
+## Version Compatibility
+
+Skills are written for the Dune CLI version specified by `cli_version` in each skill's frontmatter. Patch versions don't matter -- only major and minor.
+
+**Do NOT check the version proactively.** Only run `dune --version` when a command fails and the error looks like a skill/CLI incompatibility, for example:
+
+- Unknown subcommand or flag (e.g. "unknown command", "unknown flag")
+- Unexpected output format (e.g. JSON fields the skill references are missing)
+- A command documented in the skill doesn't exist
+
+When you see such an error, run `dune --version`, parse the major.minor, and compare to the skill's `cli_version`:
+
+- **Major version mismatch**: **Stop.** Tell the user the CLI version is incompatible and they must upgrade (or downgrade). Point them to re-run the install steps from Option A above.
+- **Minor version mismatch**: **Warn** the user that versions differ and recommend upgrading the CLI or the skill. Continue attempting the task -- minor differences are usually non-breaking.
+- **Versions match**: Not a version problem. Debug the error normally.

skills/sim/references/install-and-recovery.md

@@ -8,7 +8,7 @@ This reference covers CLI installation, Sim API authentication failure recovery,
 
 ## CLI Not Found Recovery
 
-If the command fails because `dune` is not found on PATH (e.g. "command not found"), follow the installation steps in the [shared CLI install reference](../../shared/cli-install.md#cli-not-found-recovery).
+If the command fails because `dune` is not found on PATH (e.g. "command not found"), follow the installation steps in the [shared CLI install reference](cli-install.md#cli-not-found-recovery).
 
 ---
 
@@ -51,7 +51,7 @@ Do **not** attempt to handle the API key yourself -- the user must authenticate
 
 ## Version Compatibility
 
-See the [shared CLI version compatibility reference](../../shared/cli-install.md#version-compatibility).
+See the [shared CLI version compatibility reference](cli-install.md#version-compatibility).
 
 ---