opencode-skills-collection 3.1.23 → 4.0.1

package/bundled-skills/git-pushing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-pushing
-description: "Stage all changes, create a conventional commit, and push to the remote branch. Use when explicitly asks to push changes (\"push this\", \"commit and push\"), mentions saving work to remote (\"save to github\", \"push to remote\"), or completes a feature and wants to share it."
+description: "Safely stage, commit, and push intended git changes with conventional commit messages. Use for ordinary non-release pushes when explicitly asked to push, save work remotely, or share a completed change."
 risk: critical
 source: community
 date_added: "2026-02-27"
@@ -8,7 +8,7 @@ date_added: "2026-02-27"
 
 # Git Push Workflow
 
-Stage all changes, create a conventional commit, and push to the remote branch.
+Stage only intended changes, create a conventional commit, and push to the remote branch.
 
 ## When to Use
 Automatically activate when the user:
@@ -18,9 +18,19 @@ Automatically activate when the user:
 - Completes a feature and wants to share it
 - Says phrases like "let's push this up" or "commit these changes"
 
+## Safety Gates
+
+Before staging, inspect `git status --short --branch`, confirm the intended files, and fetch the upstream branch when a concurrent push is plausible. Do not absorb unrelated dirty files.
+
+The helper requires an empty live index and a conventional commit message before it stages anything. It locks the live index, builds and validates the commit in an isolated temporary index, rejects `--` without paths, and atomically updates the branch only if its parent is unchanged.
+
+The helper honors `branch.<name>.pushRemote`, `remote.pushDefault`, and the branch's configured upstream, in that order. For a new branch without those settings, it requires `origin` and establishes `origin/<branch>`. It rejects detached HEAD and invalid remote configurations before staging.
+
+Do not use this skill for a versioned repository release, tag publication, or a repository with an explicit `release:prepare` / `release:publish` workflow. Use that repository's release flow instead; it owns version changes, generated files, tags, and publish verification.
+
 ## Workflow
 
-**ALWAYS use the script** - do NOT use manual git commands:
+Use the helper only after the safety gates pass. With no paths it stages all current changes, so use that form only when every dirty file belongs to the requested commit:
 
 ```bash
 bash skills/git-pushing/scripts/smart_commit.sh
@@ -32,9 +42,16 @@ With custom message:
 bash skills/git-pushing/scripts/smart_commit.sh "feat: add feature"
 ```
 
-Script handles: staging, conventional commit message, Claude footer, push with -u flag.
+To stage only named files, pass them after `--`:
+
+```bash
+bash skills/git-pushing/scripts/smart_commit.sh "fix: scope change" -- path/to/file
+```
+
+The helper handles isolated staging, commit creation, and push; it does not replace validation, release tooling, or a rebase required by an advanced upstream branch.
 
 ## Limitations
+- The helper currently requires Git's `files` ref backend; it rejects `reftable` repositories before creating a commit because their refs cannot use the filesystem lock protocol.
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/git-pushing/scripts/smart_commit.sh

@@ -1,19 +1,214 @@
 #!/bin/bash
-set -e
+set -euo pipefail
 
-# Default commit message if none provided
+# Always inspect and update the repository's real index. An inherited alternate
+# index could otherwise make the safety check observe different staged content.
+unset GIT_INDEX_FILE
+
+CONVENTIONAL_PATTERN='^(feat|fix|ref|refactor|perf|docs|test|build|ci|chore|style|meta|license|revert)(\([A-Za-z0-9._/-]+\))?(!)?: .+'
 MESSAGE="${1:-chore: update code}"
+shift || true
+
+validate_message() {
+  local subject=$1
+  if [[ ! "$subject" =~ $CONVENTIONAL_PATTERN ]]; then
+    echo "Commit message must use the conventional '<type>(<scope>): <subject>' format." >&2
+    exit 1
+  fi
+}
+
+validate_message "$MESSAGE"
+
+PATH_MODE=false
+if [[ "${1:-}" == "--" ]]; then
+  PATH_MODE=true
+  shift
+elif [[ "$#" -gt 0 ]]; then
+  echo "Pass selected paths after an explicit -- separator." >&2
+  exit 1
+fi
+
+if [[ "$PATH_MODE" == true && "$#" -eq 0 ]]; then
+  echo "The -- separator requires at least one path." >&2
+  exit 1
+fi
+
+BRANCH=$(git symbolic-ref --quiet --short HEAD) || {
+  echo "Refusing to commit from a detached HEAD." >&2
+  exit 1
+}
+
+REF_FORMAT=$(git rev-parse --show-ref-format 2>/dev/null || true)
+if [[ -z "$REF_FORMAT" || "$REF_FORMAT" == "--show-ref-format" ]]; then
+  REF_FORMAT=$(git config --get extensions.refStorage || true)
+  REF_FORMAT=${REF_FORMAT:-files}
+fi
+if [[ "$REF_FORMAT" != files ]]; then
+  echo "Refusing to run with ref backend '$REF_FORMAT'; safe branch locking currently requires the files backend." >&2
+  exit 1
+fi
+
+PUSH_REMOTE=$(git config --get "branch.$BRANCH.pushRemote" || true)
+if [[ -z "$PUSH_REMOTE" ]]; then
+  PUSH_REMOTE=$(git config --get remote.pushDefault || true)
+fi
+FETCH_REMOTE=$(git config --get "branch.$BRANCH.remote" || true)
+MERGE_REF=$(git config --get "branch.$BRANCH.merge" || true)
+if [[ -z "$PUSH_REMOTE" ]]; then
+  PUSH_REMOTE=${FETCH_REMOTE:-origin}
+fi
+
+if [[ "$PUSH_REMOTE" == "." ]] || ! git remote get-url --push "$PUSH_REMOTE" >/dev/null 2>&1; then
+  echo "Configured push remote '$PUSH_REMOTE' does not exist or is not pushable." >&2
+  exit 1
+fi
+
+PUSH_BRANCH=$BRANCH
+if [[ "$PUSH_REMOTE" == "$FETCH_REMOTE" && -n "$MERGE_REF" ]]; then
+  if [[ "$MERGE_REF" != refs/heads/* ]]; then
+    echo "Configured upstream '$MERGE_REF' is not a pushable branch ref." >&2
+    exit 1
+  fi
+  PUSH_BRANCH=${MERGE_REF#refs/heads/}
+fi
+
+HAS_UPSTREAM=false
+if git rev-parse --verify --quiet '@{upstream}' >/dev/null; then
+  HAS_UPSTREAM=true
+fi
+SET_UPSTREAM=false
+if [[ "$HAS_UPSTREAM" == false && "$PUSH_REMOTE" == origin ]]; then
+  SET_UPSTREAM=true
+fi
+
+GIT_DIR=$(git rev-parse --absolute-git-dir)
+GIT_COMMON_DIR=$(git rev-parse --path-format=absolute --git-common-dir)
+LIVE_INDEX="$GIT_DIR/index"
+LIVE_INDEX_LOCK="$LIVE_INDEX.lock"
+BRANCH_REF="$GIT_COMMON_DIR/refs/heads/$BRANCH"
+BRANCH_REF_LOCK="$BRANCH_REF.lock"
+TEMP_DIR=$(mktemp -d "${TMPDIR:-/tmp}/smart-commit.XXXXXX")
+TEMP_INDEX="$TEMP_DIR/index"
+MESSAGE_FILE="$TEMP_DIR/COMMIT_EDITMSG"
+LOCK_HELD=false
+BRANCH_LOCK_HELD=false
+
+cleanup() {
+  rm -rf "$TEMP_DIR"
+  if [[ "$LOCK_HELD" == true ]]; then
+    rm -f "$LIVE_INDEX_LOCK"
+  fi
+  if [[ "$BRANCH_LOCK_HELD" == true ]]; then
+    rm -f "$BRANCH_REF_LOCK"
+  fi
+}
+trap cleanup EXIT
+
+if ! (set -o noclobber; : > "$LIVE_INDEX_LOCK") 2>/dev/null; then
+  echo "The Git index is busy; refusing to race another staging operation." >&2
+  exit 1
+fi
+LOCK_HELD=true
+
+if ! git diff --cached --quiet; then
+  echo "Refusing to commit because the index already contains staged changes." >&2
+  echo "Commit or unstage the existing index, then retry with the intended paths." >&2
+  exit 1
+fi
+
+PARENT=$(git rev-parse --verify HEAD)
+if [[ -f "$LIVE_INDEX" ]]; then
+  cp "$LIVE_INDEX" "$TEMP_INDEX"
+else
+  GIT_INDEX_FILE="$TEMP_INDEX" git read-tree "$PARENT"
+fi
+if [[ "$PATH_MODE" == true ]]; then
+  GIT_INDEX_FILE="$TEMP_INDEX" git add -- "$@"
+else
+  GIT_INDEX_FILE="$TEMP_INDEX" git add -A
+fi
+
+if GIT_INDEX_FILE="$TEMP_INDEX" git diff --cached --quiet; then
+  echo "No changes staged for commit." >&2
+  exit 1
+fi
+
+EXPECTED_TREE=$(GIT_INDEX_FILE="$TEMP_INDEX" git write-tree)
+printf '%s\n' "$MESSAGE" > "$MESSAGE_FILE"
+
+GIT_INDEX_FILE="$TEMP_INDEX" git hook run --ignore-missing pre-commit
+if [[ $(GIT_INDEX_FILE="$TEMP_INDEX" git write-tree) != "$EXPECTED_TREE" ]]; then
+  echo "Pre-commit hooks changed the isolated index; review those changes before retrying." >&2
+  exit 1
+fi
+
+GIT_INDEX_FILE="$TEMP_INDEX" git hook run --ignore-missing prepare-commit-msg -- "$MESSAGE_FILE" message
+GIT_INDEX_FILE="$TEMP_INDEX" git hook run --ignore-missing commit-msg -- "$MESSAGE_FILE"
+if [[ $(GIT_INDEX_FILE="$TEMP_INDEX" git write-tree) != "$EXPECTED_TREE" ]]; then
+  echo "Commit hooks changed the isolated index; review those changes before retrying." >&2
+  exit 1
+fi
+validate_message "$(head -n 1 "$MESSAGE_FILE")"
+
+if [[ $(git config --bool commit.gpgsign || true) == true ]]; then
+  CREATED_COMMIT=$(git commit-tree -S "$EXPECTED_TREE" -p "$PARENT" -F "$MESSAGE_FILE")
+else
+  CREATED_COMMIT=$(git commit-tree "$EXPECTED_TREE" -p "$PARENT" -F "$MESSAGE_FILE")
+fi
+
+if ! git update-ref "refs/heads/$BRANCH" "$CREATED_COMMIT" "$PARENT"; then
+  echo "The branch changed concurrently; refusing to replace or push it." >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$BRANCH_REF_LOCK")"
+if ! (set -o noclobber; : > "$BRANCH_REF_LOCK") 2>/dev/null; then
+  CURRENT_BRANCH_COMMIT=$(git rev-parse --verify "refs/heads/$BRANCH")
+  if [[ "$CURRENT_BRANCH_COMMIT" != "$CREATED_COMMIT" ]]; then
+    GIT_INDEX_FILE="$TEMP_INDEX" git read-tree "$CURRENT_BRANCH_COMMIT"
+  fi
+  cp "$TEMP_INDEX" "$LIVE_INDEX_LOCK"
+  mv -f "$LIVE_INDEX_LOCK" "$LIVE_INDEX"
+  LOCK_HELD=false
+  echo "The branch ref is busy after commit creation; refusing to continue to hooks or push." >&2
+  exit 1
+fi
+BRANCH_LOCK_HELD=true
+CURRENT_BRANCH_COMMIT=$(git rev-parse --verify "refs/heads/$BRANCH")
+if [[ "$CURRENT_BRANCH_COMMIT" != "$CREATED_COMMIT" ]]; then
+  GIT_INDEX_FILE="$TEMP_INDEX" git read-tree "$CURRENT_BRANCH_COMMIT"
+  cp "$TEMP_INDEX" "$LIVE_INDEX_LOCK"
+  mv -f "$LIVE_INDEX_LOCK" "$LIVE_INDEX"
+  LOCK_HELD=false
+  echo "The branch changed before its ref lock was acquired; refusing to push." >&2
+  exit 1
+fi
 
-# Add all changes
-git add .
+if ! GIT_INDEX_FILE="$TEMP_INDEX" git hook run --ignore-missing post-commit; then
+  echo "Warning: post-commit hook failed after the commit was created; continuing with a consistent index." >&2
+fi
+CURRENT_BRANCH_COMMIT=$(git rev-parse --verify "refs/heads/$BRANCH")
+if [[ "$CURRENT_BRANCH_COMMIT" != "$CREATED_COMMIT" ]]; then
+  GIT_INDEX_FILE="$TEMP_INDEX" git read-tree "$CURRENT_BRANCH_COMMIT"
+  cp "$TEMP_INDEX" "$LIVE_INDEX_LOCK"
+  mv -f "$LIVE_INDEX_LOCK" "$LIVE_INDEX"
+  LOCK_HELD=false
+  echo "The branch changed after commit creation; refusing to push another commit." >&2
+  exit 1
+fi
 
-# Commit with the provided message
-git commit -m "$MESSAGE"
+cp "$TEMP_INDEX" "$LIVE_INDEX_LOCK"
+mv -f "$LIVE_INDEX_LOCK" "$LIVE_INDEX"
+LOCK_HELD=false
 
-# Get current branch name
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
+PUSH_REFSPEC="$CREATED_COMMIT:refs/heads/$PUSH_BRANCH"
+git push "$PUSH_REMOTE" "$PUSH_REFSPEC"
+if [[ "$SET_UPSTREAM" == true ]]; then
+  git config "branch.$BRANCH.remote" "$PUSH_REMOTE"
+  git config "branch.$BRANCH.merge" "refs/heads/$PUSH_BRANCH"
+fi
 
-# Push to remote, setting upstream if needed
-git push -u origin "$BRANCH"
+rm -f "$BRANCH_REF_LOCK"
+BRANCH_LOCK_HELD=false
 
-echo "✅ Successfully pushed to $BRANCH"
+echo "✅ Successfully pushed $BRANCH to $PUSH_REMOTE/$PUSH_BRANCH"

package/bundled-skills/go-in-depth/scripts/workflow-script.js

@@ -89,7 +89,10 @@ const REPORT_SCHEMA = {
 
 // ─── Phase 0: Scope — decompose question into search angles ───
 phase("Scope")
-const QUESTION = (typeof args === "string" ? args.trim() : args?.query?.trim()) || ""
+const RAW_QUESTION = typeof args === "string"
+  ? args
+  : (typeof args === "object" && args !== null && !Array.isArray(args) ? args.query : "")
+const QUESTION = typeof RAW_QUESTION === "string" ? RAW_QUESTION.trim() : ""
 if (!QUESTION) {
   return { error: "No research question provided. Pass it as args: Workflow({name: 'go-in-depth', args: '<question>'})." }
 }

package/bundled-skills/grok-build/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: grok-build
+description: "Delegate well-specified implementation tasks to xAI's Grok Build CLI running headlessly while the orchestrating agent plans, writes task specs, reviews every diff, and owns the result."
+category: agent-orchestration
+risk: critical
+source: https://github.com/sanjay3290/ai-skills/tree/main/skills/grok-build
+source_repo: sanjay3290/ai-skills
+source_type: community
+date_added: "2026-07-09"
+author: sanjay3290
+tags: [grok, delegation, code-generation, xai]
+tools: [claude, cursor, gemini]
+license: "Apache-2.0"
+license_source: "https://github.com/sanjay3290/ai-skills/blob/main/LICENSE"
+---
+
+# Grok Build Orchestration
+
+## When to Use
+
+- Use when delegating a well-specified implementation task to xAI's Grok Build CLI running headlessly
+- Use when executing a Markdown implementation plan task-by-task with a diff review after each task
+- Use when the user says "use grok", "grok build", "have grok implement", or "send to grok"
+
+The coding assistant is the orchestrator: it plans, writes self-contained task specs,
+dispatches them to Grok Build headlessly, reviews every diff, and owns the final result.
+Grok is the fast, cheap executor. Full CLI details and verified behaviors: `references/cli.md`.
+
+## Safety Gate
+
+Before every dispatch, show the user the exact task specification that will be sent to xAI,
+the target worktree, and the permission mode. Obtain explicit approval to disclose that text
+and to let Grok edit the scoped worktree. Never include secrets, proprietary source, customer
+data, or credentials in a task specification. Do not run `grok update`, `--always-approve`,
+or a destructive recovery command without separate, explicit approval.
+
+## When to delegate vs keep with the orchestrator
+
+| Delegate to Grok | Keep with the orchestrator |
+|---|---|
+| Plan tasks with clear acceptance criteria | Ambiguous requirements, architecture decisions |
+| Boilerplate, scaffolding, CRUD | Deep cross-file debugging |
+| Mechanical refactors | Security-sensitive code |
+| Test writing from clear specs | Anything touching production infrastructure |
+| UI components from mockups/specs | Tasks where writing the spec ≈ doing the work |
+
+When in doubt, keep it with the orchestrator.
+
+## Session preflight (once, before the first dispatch)
+
+1. `grok update --check --json` — if `updateAvailable` is true, tell the user. Run
+   `grok update` only after explicit approval, then confirm with `grok --version`.
+2. `grok models` — if it errors or reports logged out, STOP and ask the user to run
+   `grok login`.
+
+## Per-task loop (sequential — the default)
+
+1. **Spec.** Write a self-contained task file (template below) to a temp directory
+   OUTSIDE the target repo — the harness scratchpad if one is available, else the OS
+   temp dir. Never write it inside the target repo. Grok has zero conversation context:
+   no one-liner prompts, ever.
+   - POSIX: `mkdir -p "${TMPDIR:-/tmp}/grok-specs"`, then write `task.md` there.
+   - Windows (PowerShell): `New-Item -ItemType Directory -Force "$env:TEMP\grok-specs"`,
+     then write `task.md` there.
+2. **Clean state.** No uncommitted *source* changes — commit or stash first, so the
+   post-run diff is exactly Grok's work. Ignore build artifacts (`__pycache__`, `dist/`,
+   etc.); if they show in `git status`, they're usually just un-gitignored, not your
+   concern. Never dispatch on a dirty source tree.
+3. **Dispatch.**
+
+   POSIX:
+
+   ```bash
+   grok --prompt-file <task-file> \
+     --output-format json \
+     --always-approve \
+     --max-turns 30 \
+     --cwd <repo>
+   ```
+
+   Windows (PowerShell) — backtick line-continuation:
+
+   ```powershell
+   grok --prompt-file <task-file> `
+     --output-format json `
+     --always-approve `
+     --max-turns 30 `
+     --cwd <repo>
+   ```
+
+   Parse the JSON output and save `sessionId`. (`--always-approve` is required for
+   headless runs — `--permission-mode acceptEdits` silently cancels edits with no
+   interactive approver. Use it only after the user explicitly approves Grok editing this
+   exact scoped worktree. See `references/cli.md`.) For a high-stakes task, add `--check`
+   so Grok self-verifies before you review; skip it otherwise (it ~doubles latency).
+4. **Review gate — non-negotiable.**
+   - Read the diff yourself (`git diff -- <files from the spec>` to skip artifact noise):
+     does it do the task, only the task, and match repo conventions?
+   - Run the acceptance commands from the spec.
+   - **Pass** → commit with a clear message following the repo's convention → next task.
+   - **Fail** → ask the user before a fix-up or any reset. Never run `git checkout -- .` or
+     `git clean -fd` automatically; preserve the diff for review and use a non-destructive
+     recovery plan unless the user explicitly authorizes otherwise.
+
+## Task spec template
+
+```markdown
+# Task: <one-line title>
+
+## Context
+- Repo: <path> — <one line on what the project is>
+- Conventions: <test runner, formatter, a good example file to imitate>
+
+## Files
+- Modify: <path>
+- Create: <path>
+
+## Task
+<precise description of the change>
+
+## Constraints
+- Do not modify any files other than those listed above.
+- <other constraints>
+
+## Acceptance criteria
+- `<exact command>` <expected result>
+```
+
+## Executing a Markdown implementation plan
+
+- One plan task per dispatch, in order.
+- Check off the plan's task checkboxes (`- [ ]` → `- [x]`) as each task lands and passes
+  the review gate.
+- If the plan explicitly marks tasks as independent, see Parallel dispatch below;
+  otherwise stay sequential.
+
+## Parallel dispatch (opt-in exception, not the default)
+
+Only when a plan explicitly marks tasks independent: dispatch each with
+`--worktree=<task-slug>`, run concurrently, then review and merge one worktree at a
+time through the same review gate. Merge conflicts usually eat the savings — prefer
+sequential.
+
+## Failure handling
+
+| Failure | Action |
+|---|---|
+| `stopReason: "Cancelled"`, empty text, no diff | Missing `--always-approve` — retry with it |
+| CLI error / timeout | Retry once; then do the task yourself and note the fallback |
+| Auth expired | Stop; ask the user to run `grok login` |
+| 2 fix-up rounds exhausted | Preserve the diff, ask the user for a recovery decision, then finish the task manually if authorized |
+| Dirty tree at dispatch | Refuse; commit/stash first |
+
+## Limitations
+
+- Grok receives the approved task specification; it is a third-party service and should not
+  receive secrets, proprietary material, personal data, or customer data.
+- `--always-approve` allows edits without an interactive approval prompt. It must be limited to
+  a clean, explicitly approved worktree and never substitutes for the orchestrator's review.
+- Model output can be incorrect, insecure, incomplete, or out of scope. Review the diff and
+  run the acceptance checks before accepting any change.
+- This skill does not authorize installations, updates, commits, pushes, deployments, or
+  destructive cleanup.
+
+## Models
+
+Default `grok-4.5`. Add `-m grok-composer-2.5-fast` only for trivial mechanical tasks.

package/bundled-skills/grok-build/references/cli.md

@@ -0,0 +1,99 @@
+# Grok Build CLI — headless reference
+
+Verified against `grok` 0.2.93 (stable channel), 2026-07-09. Re-verify with
+`grok --help` after major version bumps — flags mirror Claude Code's.
+
+## One-shot headless run
+
+```bash
+grok -p "prompt" --output-format json
+grok --prompt-file task.md --output-format json   # preferred: no shell-quoting issues
+```
+
+⚠️ `grok agent` is NOT a one-shot command — it runs the agent as a stdio/WebSocket
+server for SDK/ACP integrations. Always use top-level `grok -p` / `--prompt-file`.
+
+## JSON output shape (verified)
+
+```json
+{
+  "text": "final response text",
+  "stopReason": "EndTurn",
+  "sessionId": "019f470d-3e02-7601-b726-1133cc72ef76",
+  "requestId": "…",
+  "thought": "…"
+}
+```
+
+`sessionId` is the handle for fix-ups.
+
+- POSIX: `grok --prompt-file task.md --output-format json | python3 -c "import json,sys;print(json.load(sys.stdin)['sessionId'])"`
+- Windows (PowerShell): `grok --prompt-file task.md --output-format json | ConvertFrom-Json | Select-Object -ExpandProperty sessionId`
+
+`stopReason: "Cancelled"` with empty `text` means a tool call hit a permission gate and
+was auto-cancelled headlessly — you forgot `--always-approve` (see below).
+
+## Permissions — the headless gotcha
+
+**Use `--always-approve` for headless dispatch. Do NOT rely on
+`--permission-mode acceptEdits`.**
+
+Verified 2026-07-09: `--permission-mode acceptEdits` FAILS headlessly — the edit tool
+hits a permission gate with no interactive approver, and the run returns
+`stopReason: "Cancelled"` with no file change. `--always-approve` auto-approves BOTH
+edits AND shell commands in one flag (Grok ran the acceptance test itself in the same
+run). This is safe in the grok-build workflow because dispatch happens on a clean tree,
+the task spec constrains scope, and the orchestrator reviews the full diff before
+committing.
+
+Optional hardening: `--sandbox <profile>` (env `GROK_SANDBOX`) restricts filesystem and
+network access — layer it on for untrusted repos.
+
+## Resume / fix-up
+
+```bash
+grok --resume <sessionId> -p "specific feedback" --always-approve --output-format json
+```
+
+Verified: the resumed session retains full context — it knows the repo and files touched
+without re-explanation. Pass only the specific feedback, not the whole task again.
+
+## Self-verification (`--check`) — opt-in only
+
+`--check` appends a self-verification loop: Grok spawns a verifier subagent that emits a
+checklist, action trace, scope/edge-case evaluation, and its own `VERDICT: PASS`.
+
+Verified: correct but ~doubles wall-clock (a trivial task went from a few seconds to
+~48s) and adds token cost, undercutting Grok's speed/cost advantage. Skip it by default —
+the orchestrator's review gate is the authority. Add `--check` only for high-stakes tasks
+where you want Grok to self-correct before review.
+
+## Update check (session preflight)
+
+```bash
+grok update --check --json
+# → {"currentVersion":"0.2.93","latestVersion":"0.2.93","updateAvailable":false,"channel":"stable",…}
+grok update        # installs latest stable
+```
+
+## Key flags
+
+| Flag | Purpose |
+|---|---|
+| `--always-approve` | Auto-approve all tool executions (edits + shell). **Required for headless.** |
+| `--permission-mode <m>` | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` — but see gotcha above |
+| `--allow` / `--deny` | Fine-grained permission rules (Claude Code `--allowedTools` syntax) |
+| `--max-turns <N>` | Turn cap — always set for headless runs |
+| `--check` | Appends a self-verification loop (opt-in; see above) |
+| `--worktree[=name]` | Run in a fresh git worktree (parallel tasks) |
+| `--json-schema '<schema>'` | Constrain final output to a JSON Schema |
+| `-m <model>` | `grok-4.5` (default) or `grok-composer-2.5-fast` |
+| `--cwd <dir>` | Working directory for the run |
+| `--best-of-n <N>` | Run N ways in parallel, pick best (headless) |
+
+## Install & auth
+
+- Install / update: follow xAI's Grok CLI install docs for your OS; verify with
+  `grok --version`. Works on macOS, Linux, and Windows (PowerShell).
+- Auth: grok.com subscription OAuth (`grok login` / `grok logout`). Check with `grok models`.
+- Models available: `grok-4.5` (default), `grok-composer-2.5-fast`.

package/bundled-skills/huggingface-tool-builder/references/find_models_by_paper.sh

@@ -200,7 +200,7 @@ else
     echo "$MODELS_WITH_PAPERS" | while read -r model_data; do
         if [[ -n "$model_data" ]]; then
             # Decode base64 and show formatted
-            echo "$model_data" | base64 -d | jq -r '
+            echo "$model_data" | base64 -d | jq -r ' # security-allowlist: local JSON decoding for display
                 "📄 \(.id)
    arXiv: \(.arxiv_tags)
    Task: \(.task)