@oriro/orirocli 0.1.0

package/skills/finance/finance-tax-planning/SKILL.md

@@ -0,0 +1,89 @@
+---
+watermark: ORIRO
+disable-model-invocation: true
+name: finance-tax-planning
+provider: ORIRO.ai
+copyright: Copyright (c) 2026 ORIRO.ai
+description: >
+  Advanced tax planning — tax minimization strategies, business tax structure,
+  estate planning, international tax, and proactive tax management. Activate
+  for questions about minimizing taxes, business tax strategy, tax-efficient
+  investing, estate tax, or strategic tax planning. Sources: IRS publications,
+  CPA Journal, tax planning principles. Consult a CPA or tax attorney for
+  implementation.
+---
+
+# Tax Planning
+
+## Core tax minimization principles
+
+**Defer:** Push income to future years (lower tax today).
+**Shift:** Move income to lower-bracket family members (within rules) or entities.
+**Convert:** Change character of income (ordinary → capital gains, personal → business).
+**Deduct:** Find all allowable deductions. Bunch deductible expenses into higher-income years.
+**Exclude:** Use accounts and structures that eliminate tax entirely (Roth IRA, HSA, municipal bonds).
+
+## Business structure for tax efficiency
+
+### S-Corp saves self-employment tax
+
+Above ~$50K net profit, operating as S-Corp vs. sole proprietor saves significant SE tax.
+**How it works:** Pay yourself "reasonable salary" → remainder taken as distribution.
+SE tax (15.3%) applies to salary only, not distributions.
+**Example:** $200K profit. Reasonable salary = $80K.
+Sole proprietor: SE tax on $200K = $18,370 (approximate).
+S-Corp: SE tax on $80K salary only = ~$12,240 + some employer costs.
+Net savings: $4,000-6,000+/year. Worth the added complexity above ~$50K.
+
+### Qualified Business Income (QBI) Deduction — Section 199A
+
+Pass-through businesses (sole props, S-Corps, partnerships, LLCs) can deduct up to 20% of QBI.
+**Limitations for service businesses:** Phases out for income above $182,050 single / $364,200 MFJ (2024).
+Above phase-out: Architects, engineers, real estate, financial advisors still qualify. Most professional services (lawyers, doctors, consultants) do not.
+Optimize: Keep taxable income below phase-out threshold.
+
+## Timing strategies
+
+### Accelerate deductions, defer income
+
+**Deductions:** Pay Q4 expenses in December not January. Pre-pay deductible expenses.
+**Income:** Delay December invoicing to January if possible (calendar-year taxpayer).
+**Bonus:** Structure business income to qualify for year-end deduction strategies.
+
+### Capital gains management
+
+**Long-term vs. short-term:** Hold assets 1+ year for preferential rates.
+**Tax loss harvesting:** Sell losing positions to offset gains. Wash sale rule: Don't buy back the same or "substantially identical" security within 30 days.
+**0% capital gains bracket:** In 2024, long-term capital gains taxed at 0% for single filers below $47,025 ($94,050 MFJ). Rebalance or harvest gains in low-income years.
+**Opportunity Zones:** Invest realized gains in Opportunity Zone funds → deferral and potential exclusion of gains.
+
+## Retirement plan strategies
+
+### Maximize deductions
+
+**SEP-IRA (self-employed):** Up to 25% of compensation, max $69,000 (2024). Deadline: tax filing + extensions.
+**Solo 401(k):** Employee elective deferral ($23,000) + employer profit sharing (25% of compensation) = up to $69,000. Best for self-employed with high income.
+**Defined Benefit Plan:** For very high earners. Can shelter $275,000+ per year. Complex, costly, worth it above ~$400K profit.
+**Backdoor Roth IRA:** Contribute to non-deductible IRA → immediately convert to Roth. Legal for any income level. No pro-rata problem if no other traditional IRA.
+**Mega backdoor Roth:** If 401(k) plan allows after-tax contributions + in-service withdrawal → convert to Roth IRA. Additional $43,000+/year in Roth contributions.
+
+## Business deductions often missed
+
+**Home office:** Dedicated space used regularly and exclusively for business.
+Simplified method: $5/sq ft, max 300 sq ft = $1,500 max.
+Regular method: Proportional share of home expenses (mortgage interest, rent, utilities, insurance, repairs).
+**Vehicle:** Actual expense method vs. standard mileage ($0.67/mile in 2024 for business).
+**Section 179:** Deduct full cost of qualifying equipment in year purchased (up to $1,160,000 in 2024).
+**Bonus depreciation:** 60% bonus depreciation in 2024 (phases down). For property not qualifying for Section 179.
+**Health insurance (self-employed):** 100% deductible above-the-line (reduces AGI).
+**Retirement plan contributions:** All contributions deductible.
+
+## Estate planning tax basics
+
+**Federal estate tax exemption (2024):** $13.61M per person ($27.22M married). Sunsets to ~$7M in 2026 absent Congressional action.
+**Annual gift exclusion:** $18,000/person/year (2024). No gift tax, no estate inclusion.
+**529 superfunding:** Front-load 5 years of annual exclusion gifts into 529 ($90,000 single, $180,000 married). No gift tax, removed from estate.
+**Irrevocable life insurance trust (ILIT):** Life insurance proceeds excluded from estate.
+**Grantor trust strategies:** Shift appreciation out of estate while maintaining income tax payments (effectively additional tax-free gift to trust).
+
+Sources: IRS publications (irs.gov — free, especially Pub 334, 587, 946, 560), CPA Journal (free articles), Kitces.com (free financial planning content), Forbes Advisor tax planning guides

package/skills/finance/finance-trading/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ORIRO.ai
+
+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.

package/skills/finance/finance-trading/SKILL.md

@@ -0,0 +1,112 @@
+---
+watermark: ORIRO
+disable-model-invocation: true
+name: finance-trading
+provider: ORIRO.ai
+copyright: Copyright (c) 2026 ORIRO.ai
+description: >
+  Financial markets and trading — market structure, order types, technical
+  analysis, risk management, trading psychology. Activate for questions about
+  how markets work, order types, reading charts, trading strategies, risk
+  management, or understanding market mechanics. Sources: SEC investor education,
+  CME Group educational content, FINRA investor education.
+  Trading involves substantial risk. This is education, not trading advice.
+---
+
+# Financial Markets and Trading
+
+## Market structure
+
+### Order types
+
+**Market order:** Execute immediately at best available price. Guaranteed fill, not guaranteed price.
+**Limit order:** Execute at specified price or better. Guaranteed price if filled; not guaranteed to fill.
+**Stop order:** Becomes market order when stop price reached. Used to limit losses or protect profits.
+**Stop-limit:** Becomes limit order when stop triggered. May not fill if market gaps past limit.
+
+### Bid-ask spread
+
+Bid: highest price buyers will pay. Ask: lowest price sellers will accept.
+Spread = ask - bid = cost of immediate entry and exit.
+Liquid markets (S&P 500 ETFs): very tight spreads. Illiquid markets (small stocks): wide spreads.
+
+### Market participants
+
+Market makers: Provide liquidity by quoting both bid and ask. Profit from spread.
+Institutional traders: Mutual funds, hedge funds, pension funds. Move markets.
+Algorithmic traders: Computerized execution. Dominant in modern markets.
+Retail traders: Individual investors. Typically price takers.
+
+## Technical analysis
+
+Study of price and volume to identify patterns and trends.
+**Trend identification:**
+Uptrend: higher highs and higher lows.
+Downtrend: lower highs and lower lows.
+Range/consolidation: no clear directional pattern.
+
+**Moving averages:**
+Simple MA (SMA): Average of closing prices over N periods.
+Exponential MA (EMA): Gives more weight to recent prices.
+**Golden cross:** Short MA crosses above long MA — bullish signal (e.g., 50-day above 200-day).
+**Death cross:** Short MA crosses below long MA — bearish signal.
+
+**Support and resistance:**
+Support: price level where buying has historically stepped in.
+Resistance: price level where selling has historically stepped in.
+Broken resistance becomes support (and vice versa).
+
+**Volume:** Confirms price movements. Volume should increase in the direction of the trend.
+
+**RSI (Relative Strength Index):** Momentum oscillator 0-100.
+
+> 70: overbought (potential reversal). <30: oversold (potential reversal).
+> More reliable as divergence signal than absolute levels.
+
+**MACD (Moving Average Convergence Divergence):**
+Difference between 12-period and 26-period EMA.
+Signal line: 9-period EMA of MACD.
+Crossovers and divergences as signals.
+
+## Risk management — the most critical component
+
+**Position sizing:**
+Risk per trade: 1-2% of capital maximum (risking $100-200 per $10,000).
+Position size = (Account risk in $) / (Entry price - Stop price)
+Example: $10,000 account, 1% risk = $100 risk. Entry $50, stop $48 ($2 risk per share). Position = 50 shares.
+
+**Risk/reward ratio:**
+Minimum 1:2 risk/reward before entering a trade.
+If risking $100, target minimum $200 profit.
+At 50% win rate with 1:2 R/R = profitable over time.
+
+**Stop losses:** Pre-defined exit if trade moves against you. Set BEFORE entering the trade. Never move stops against your position.
+
+**Drawdown management:**
+Maximum drawdown: largest peak-to-trough decline.
+At 20% loss, need 25% gain to break even.
+At 50% loss, need 100% gain to break even.
+Protect capital above all else.
+
+## Trading psychology
+
+**The three enemies:** Fear, greed, hope (when applied to losing positions).
+**FOMO (Fear of Missing Out):** Enters trades late, chases price. Fix: Define criteria before markets open.
+**Revenge trading:** Increasing size after loss to recover quickly. Fix: Daily loss limits.
+**Overtrading:** Taking low-quality setups out of boredom. Fix: Define minimum criteria; if not met, don't trade.
+
+**Process over outcome:** Good process can lead to bad outcomes (bad luck). Bad process can lead to good outcomes (good luck). Evaluate yourself on process, not individual trade outcomes.
+
+## Futures basics (relevant to commodities and index trading)
+
+Futures: Agreement to buy/sell an asset at a future date at a price agreed today.
+Standardized contracts traded on exchanges (CME, ICE).
+Leverage: Control large notional value with small margin deposit.
+Mark-to-market: Daily settlement of gains and losses.
+Margin call: If account equity falls below maintenance margin, must add funds or close positions.
+
+**Contango:** Future price > spot price (most common — storage costs, time value).
+**Backwardation:** Future price < spot price (indicates tight supply or high demand for immediate delivery).
+
+Sources: SEC investor education (sec.gov/investor), CME Group education (cmegroup.com/education),
+FINRA investor education, Investopedia technical analysis content, Jack Schwager "Market Wizards" principles

package/skills/gemini/SKILL.md

@@ -0,0 +1,51 @@
+---
+provider: ORIRO.ai
+copyright: Copyright (c) 2026 ORIRO.ai
+watermark: ORIRO
+disable-model-invocation: true
+name: gemini
+description: "Gemini CLI one-shot prompts, summaries, generation, skills, hooks, MCP, or Gemma routing."
+homepage: https://ai.google.dev/
+metadata:
+  {
+    "oriro":
+      {
+        "emoji": "✨",
+        "requires": { "bins": ["gemini"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gemini-cli",
+              "bins": ["gemini"],
+              "label": "Install Gemini CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Gemini CLI
+
+Use Gemini in headless one-shot mode. Positional text starts interactive mode; use `-p/--prompt`.
+
+Quick start
+
+- `gemini -p "Answer this question..."`
+- `gemini -m <model> -p "Prompt..."`
+- `gemini -p "Return JSON" --output-format json`
+- stdin appends to `-p`: `cat notes.md | gemini -p "Summarize"`
+
+Extensions
+
+- List: `gemini --list-extensions`
+- Manage: `gemini extensions <command>`
+- Skills: `gemini skills <command>`
+- Hooks: `gemini hooks <command>`
+- MCP: `gemini mcp <command>`
+
+Notes
+
+- If auth is required, run `gemini` once interactively and follow the login flow.
+- Avoid `--yolo` for safety.

package/skills/gh-issues/SKILL.md

@@ -0,0 +1,216 @@
+---
+provider: ORIRO.ai
+copyright: Copyright (c) 2026 ORIRO.ai
+watermark: ORIRO
+name: gh-issues
+description: "Fetch GitHub issues, select candidates, spawn background fix agents, open PRs, and optionally process PR review comments."
+user-invocable: true
+metadata:
+  {
+    "oriro":
+      {
+        "requires": { "bins": ["git", "gh"] },
+        "primaryEnv": "GH_TOKEN",
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# gh-issues
+
+Use for issue-to-PR automation. Prefer `gh` CLI; fall back to `gh api` only when a high-level command lacks the needed field.
+
+## Arguments
+
+- positional `owner/repo`: optional; else infer from `git remote get-url origin`.
+- `--label <label>`: filter.
+- `--limit <n>`: default 10.
+- `--milestone <title>`: filter.
+- `--assignee <login|@me>`: filter.
+- `--state open|closed|all`: default open.
+- `--fork <owner/repo>`: push branches to fork, PR to source.
+- `--watch`: poll issues + reviews.
+- `--interval <minutes>`: default 5.
+- `--dry-run`: list only.
+- `--yes`: no confirmation.
+- `--reviews-only`: skip issue fixing; handle PR reviews.
+- `--cron`: spawn and exit; implies `--yes`.
+- `--model <id>`: pass to workers when supported.
+- `--notify-channel <id>`: optional final notification target.
+
+## Phase 1: resolve repo
+
+```bash
+git remote get-url origin
+if [ -z "${GH_TOKEN:-}" ]; then
+  CONFIG_PATH="${ORIRO_CONFIG_PATH:-${ORIRO_STATE_DIR:-$HOME/.oriro}/oriro.json}"
+  GH_TOKEN=$(jq -r '.skills.entries["gh-issues"].apiKey // empty' "$CONFIG_PATH" 2>/dev/null || true)
+  if [ -n "$GH_TOKEN" ]; then export GH_TOKEN; fi
+fi
+gh auth status
+gh repo view OWNER/REPO --json nameWithOwner,defaultBranchRef
+```
+
+If `gh auth status` fails and `GH_TOKEN` is missing, stop and ask for GitHub auth/config.
+
+Derived:
+
+- `SOURCE_REPO`: issue repo.
+- `PUSH_REPO`: fork if set, else source.
+- `BASE_BRANCH`: source default branch unless user says otherwise.
+- `PUSH_REMOTE`: `fork` in fork mode, else `origin`.
+
+Stop on dirty worktree unless user confirms that workers should ignore uncommitted changes.
+
+In fork mode, do not mutate remotes before confirmation or during `--dry-run`.
+
+Verify auth/read access only:
+
+```bash
+gh auth token >/dev/null || test -n "${GH_TOKEN:-}"
+gh repo view "$PUSH_REPO" --json nameWithOwner
+git ls-remote --exit-code origin HEAD
+```
+
+## Phase 2: fetch issues
+
+Build filters and fetch:
+
+```bash
+gh issue list --repo "$SOURCE_REPO" --state open --limit 10 --json number,title,labels,url,body,assignees,milestone
+```
+
+Add `--label`, `--milestone`, `--assignee`, `--state`, `--limit` as requested. `gh issue list` already excludes PRs.
+
+If none found: report no matches. If `--dry-run`: show compact list and stop.
+
+## Phase 3: avoid duplicate work
+
+For each candidate:
+
+```bash
+gh pr list --repo "$SOURCE_REPO" --search "$SOURCE_REPO#<n>" --state open --json number,url,title,headRefName
+gh pr list --repo "$SOURCE_REPO" --head "fix/issue-<n>" --state open --json number,url
+gh api "repos/$PUSH_REPO/branches/fix/issue-<n>" >/dev/null
+```
+
+Skip candidates with an open PR, existing branch, or active local claim.
+
+Claim file:
+
+```text
+${ORIRO_STATE_DIR:-$HOME/.oriro}/gh-issues-<owner>-<repo>.json
+```
+
+Expire claims older than 2 hours.
+Create the parent directory before writing.
+
+## Phase 4: confirm
+
+Unless `--yes` or `--cron`, ask user to choose:
+
+- `all`
+- comma-separated issue numbers
+- `cancel`
+
+After confirmation, in fork mode, configure the push remote before handing work to agents:
+
+```bash
+gh auth setup-git
+git remote get-url fork || git remote add fork "https://github.com/$PUSH_REPO.git"
+git remote set-url fork "https://github.com/$PUSH_REPO.git"
+git ls-remote --exit-code fork HEAD
+```
+
+## Phase 5: spawn workers
+
+Launch up to 8 background workers. Do not block on each worker when `--cron`.
+
+Before each spawn, write a claim for `SOURCE_REPO#<n>` with the current ISO timestamp. After a worker reports PR/failure, remove or update the claim. This prevents watch/cron overlap before a branch or PR exists.
+
+Worker prompt must include:
+
+- issue URL, title, body, labels.
+- `SOURCE_REPO`, `PUSH_REPO`, `BASE_BRANCH`, `PUSH_REMOTE`, fork mode.
+- target branch `fix/issue-<n>`.
+- required proof and PR body.
+- notification route.
+
+Worker instructions:
+
+```text
+Use gh and git. Do not handwave.
+Checkout/create fix/issue-<n> from BASE_BRANCH.
+Implement minimal fix.
+Run relevant tests.
+Commit with conventional message.
+Push to PUSH_REMOTE.
+Open PR against SOURCE_REPO BASE_BRANCH.
+PR body: What Problem This Solves + Why This Change Was Made + User Impact + Evidence + visible Fixes SOURCE_REPO#<n>.
+Report PR URL or failure reason.
+Send completion/failure with oriro message send if route provided.
+```
+
+Use `coding-agent` launch rules when available.
+
+## Phase 6: collect
+
+Poll workers with `process` or task registry. Report:
+
+- issue number + title.
+- status: PR opened, skipped, failed, timed out.
+- PR URL or reason.
+
+Notify channel only with final compact summary.
+
+## Reviews-only / watch reviews
+
+Discover open PRs:
+
+```bash
+gh pr list --repo "$SOURCE_REPO" --state open --json number,title,url,headRefName,reviewDecision \
+  --jq '[.[] | select(.headRefName | startswith("fix/issue-"))]'
+```
+
+Fetch review threads/comments:
+
+```bash
+gh pr view <n> --repo "$SOURCE_REPO" --json url,headRefName,comments,reviews
+gh api "repos/$SOURCE_REPO/pulls/<n>/comments"
+gh api "repos/$SOURCE_REPO/issues/<n>/comments"
+```
+
+Only process `fix/issue-*` PRs created by this workflow unless the user explicitly named PR numbers. Group actionable comments by PR. Ignore praise, status, duplicates, and already-addressed comments. Spawn one worker per selected/scoped PR, same background rules.
+
+Review worker instructions:
+
+```text
+Checkout PR branch.
+Read all actionable review comments.
+Patch minimal changes.
+Run relevant tests.
+Commit and push normally; do not force-push unless explicitly told.
+Reply to addressed comments with fix + commit/file reference.
+Report comments addressed/skipped and proof.
+```
+
+## Watch mode
+
+Loop:
+
+1. Fetch issues.
+2. Spawn eligible issue workers.
+3. Process actionable PR reviews.
+4. Sleep `--interval`.
+5. Stop when user says stop.
+
+Keep cumulative summary small.

package/skills/gifgrep/SKILL.md

@@ -0,0 +1,89 @@
+---
+provider: ORIRO.ai
+copyright: Copyright (c) 2026 ORIRO.ai
+watermark: ORIRO
+disable-model-invocation: true
+name: gifgrep
+description: "Search GIF providers with CLI/TUI, download results, and extract stills/sheets."
+homepage: https://gifgrep.com
+metadata:
+  {
+    "oriro":
+      {
+        "emoji": "🧲",
+        "requires": { "bins": ["gifgrep"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "oriro/tap/gifgrep",
+              "bins": ["gifgrep"],
+              "label": "Install gifgrep (brew)",
+            },
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/oriro/gifgrep/cmd/gifgrep@latest",
+              "bins": ["gifgrep"],
+              "label": "Install gifgrep (go)",
+            },
+          ],
+      },
+  }
+---
+
+# gifgrep
+
+Use `gifgrep` to search GIF providers (Tenor/Giphy), browse in a TUI, download results, and extract stills or sheets.
+
+GIF-Grab (gifgrep workflow)
+
+- Search -> preview -> download -> extract (still/sheet) for fast review and sharing.
+
+Quick start
+
+- `gifgrep cats --max 5`
+- `gifgrep cats --format url | head -n 5`
+- `gifgrep search --json cats | jq '.[0].url'`
+- `gifgrep tui "office handshake"`
+- `gifgrep cats --download --max 1 --format url`
+
+TUI + previews
+
+- TUI: `gifgrep tui "query"`
+- CLI still previews: `--thumbs` (Kitty/Ghostty only; still frame)
+
+Download + reveal
+
+- `--download` saves to `~/Downloads`
+- `--reveal` shows the last download in Finder
+
+Stills + sheets
+
+- `gifgrep still ./clip.gif --at 1.5s -o still.png`
+- `gifgrep sheet ./clip.gif --frames 9 --cols 3 -o sheet.png`
+- Sheets = single PNG grid of sampled frames (great for quick review, docs, PRs, chat).
+- Tune: `--frames` (count), `--cols` (grid width), `--padding` (spacing).
+
+Providers
+
+- `--source auto|tenor|giphy`
+- `GIPHY_API_KEY` required for `--source giphy`
+- `TENOR_API_KEY` optional (Tenor demo key used if unset)
+
+Output
+
+- `--json` prints an array of results (`id`, `title`, `url`, `preview_url`, `tags`, `width`, `height`)
+- `--format` for pipe-friendly fields (e.g., `url`)
+
+GIF asset hygiene
+
+- Before recommending or using an animated GIF URL, verify it resolves successfully, has `Content-Type: image/gif`, and is actually animated (multiple frames or loop metadata; e.g. inspect with `file`, `identify`, or a small script).
+- Record attribution/license/source URL alongside the asset.
+- Do not hotlink when a local asset is needed: download/copy it into the project and reference the local file.
+
+Environment tweaks
+
+- `GIFGREP_SOFTWARE_ANIM=1` to force software animation
+- `GIFGREP_CELL_ASPECT=0.5` to tweak preview geometry

package/skills/github/SKILL.md

@@ -0,0 +1,87 @@
+---
+provider: ORIRO.ai
+copyright: Copyright (c) 2026 ORIRO.ai
+watermark: ORIRO
+name: github
+description: "GitHub CLI for issues, PRs, CI/check logs, comments, reviews, releases, repos, and gh api queries."
+metadata:
+  {
+    "oriro":
+      {
+        "emoji": "🐙",
+        "requires": { "bins": ["gh"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (brew)",
+            },
+            {
+              "id": "apt",
+              "kind": "apt",
+              "package": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (apt)",
+            },
+          ],
+      },
+  }
+---
+
+# GitHub
+
+Use `gh` for GitHub. Use `git` for local commits/branches/push/pull. Use code-reading tools for deep reviews.
+
+## Auth
+
+```bash
+gh auth status
+gh auth login
+```
+
+Gateway HOME can differ from operator HOME. If `gh` auth exists elsewhere, set `GH_CONFIG_DIR` in the gateway service env and restart.
+
+## PRs
+
+```bash
+gh pr list --repo owner/repo --json number,title,state,author,url
+gh pr view 55 --repo owner/repo --json title,body,author,files,commits,reviews,reviewDecision
+gh pr checks 55 --repo owner/repo
+gh pr diff 55 --repo owner/repo
+gh pr create --repo owner/repo --title "feat: title" --body-file /tmp/pr.md
+gh pr merge 55 --repo owner/repo --squash
+```
+
+URLs work directly: `gh pr view https://github.com/owner/repo/pull/55`.
+
+## Issues
+
+```bash
+gh issue list --repo owner/repo --state open --json number,title,labels,url
+gh issue view 42 --repo owner/repo --json title,body,comments,labels,state
+gh issue create --repo owner/repo --title "Bug: ..." --body-file /tmp/issue.md
+gh issue comment 42 --repo owner/repo --body-file /tmp/comment.md
+gh issue close 42 --repo owner/repo --comment "Fixed in ..."
+```
+
+## CI/runs
+
+```bash
+gh run list --repo owner/repo --limit 10
+gh run view <run-id> --repo owner/repo --json status,conclusion,headSha,url
+gh run view <run-id> --repo owner/repo --log-failed
+gh run rerun <run-id> --repo owner/repo --failed
+```
+
+## API
+
+```bash
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+gh api repos/owner/repo/labels --jq '.[].name'
+gh api --cache 1h repos/owner/repo --jq '{stars: .stargazers_count, forks: .forks_count}'
+```
+
+Use `--json` + `--jq` for structured output. Use `--body-file` for comments/bodies containing backticks, shell snippets, env names, or user text.