natureco-cli 5.18.2 → 5.19.0

package/skills/running-claude-code-via-litellm-copilot/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: running-claude-code-via-litellm-copilot
+description: Use when routing Claude Code through a local LiteLLM proxy to GitHub Copilot, reducing direct Anthropic spend, configuring ANTHROPIC_BASE_URL or ANTHROPIC_MODEL overrides, or troubleshooting Copilot proxy setup failures such as model-not-found, no localhost traffic, or GitHub 401/403 auth errors.
+---
+
+## Overview
+
+Use this skill for the specific workaround where Claude Code keeps its Anthropic-shaped client behavior, but the actual backend traffic is sent to a local LiteLLM proxy and then forwarded to GitHub Copilot.
+
+Treat this as an advanced workaround, not an officially guaranteed GitHub workflow. Help the user succeed technically, but do not promise GitHub support, policy approval, or long-term compatibility.
+
+This skill is guidance-first but execution-aware:
+
+- If the user wants explanation only, provide the smallest correct set of files, commands, and checks.
+- If the user wants real setup work on the current machine, inspect first and adapt commands to the active shell and OS.
+- Pause before persistent edits such as `~/.claude/settings.json` or shell profile files.
+
+Read [`references/doc-verified-notes.md`](./references/doc-verified-notes.md) before answering if you need to justify which parts come from the article and which parts were tightened against current LiteLLM docs.
+
+## When To Use
+
+Use this skill when the user wants any of the following:
+
+- Claude Code to run against GitHub Copilot through LiteLLM
+- lower direct Anthropic API spending while keeping the Claude Code workflow
+- a local `config.yaml` for LiteLLM's GitHub Copilot provider
+- `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`, or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` setup
+- help understanding GitHub device authorization during LiteLLM startup
+- help with model mismatch, 404-like errors, no requests reaching LiteLLM, or GitHub 401/403 failures
+
+Do not use this skill for:
+
+- deciding whether the workaround is allowed by GitHub terms
+- general LiteLLM architecture unrelated to Claude Code plus Copilot
+- direct Anthropic API setup with no Copilot or LiteLLM component
+
+## Core Rules
+
+1. Lead with a short compliance caveat.
+   Explain that this is a workaround based on a local proxy path, not a GitHub-promoted workflow, and the user must evaluate the latest Copilot terms and limits for themselves.
+2. Prefer the minimum viable path first.
+   Start with temporary environment variables and a local `config.yaml` unless the user explicitly wants a persistent setup.
+3. Keep `ANTHROPIC_MODEL` and LiteLLM `model_name` identical.
+   Exact string match matters more than clever explanation.
+4. Treat `ANTHROPIC_AUTH_TOKEN` as a local placeholder.
+   Claude Code expects a non-empty value locally, but it is not the GitHub Copilot credential and should not be presented as a reusable secret.
+5. Never overwrite `~/.claude/settings.json` wholesale.
+   Merge only the needed `env` keys and preserve unrelated settings.
+
+## Workflow
+
+### 1. Preflight
+
+Check these first when the user wants real setup work:
+
+- `claude --help` succeeds
+- `uv --version` or `pip --version` succeeds
+- the user has GitHub Copilot access
+- the intended LiteLLM port is available, usually `4000`
+
+If the user only wants instructions, state the prerequisites instead of running them.
+
+### 2. Choose Temporary vs Persistent Setup
+
+Use this rule:
+
+- Temporary setup: preferred default for first-time setup, debugging, and low-risk trials
+- Persistent setup: only when the user explicitly wants the proxy path to apply every time Claude Code starts
+
+For persistent setup, confirm the target file and then merge keys into `~/.claude/settings.json`. Do not replace the file contents.
+
+### 3. Create LiteLLM `config.yaml`
+
+Start from the article's flow, but keep the provider naming aligned with LiteLLM docs:
+
+```yaml
+model_list:
+  - model_name: claude-opus-4.5
+    litellm_params:
+      model: github_copilot/claude-opus-4.5
+      drop_params: true
+```
+
+Explain the fields:
+
+- `model_name`: the logical name Claude Code will request
+- `model`: the LiteLLM provider route, using `github_copilot/<model>`
+- `drop_params: true`: strips unsupported Anthropic-specific fields before forwarding to Copilot
+
+If the user wants a different Copilot-backed model, keep the same pattern:
+
+```yaml
+model_list:
+  - model_name: <logical-name>
+    litellm_params:
+      model: github_copilot/<copilot-model>
+      drop_params: true
+```
+
+Do not hardcode extra headers into the default path unless the user already hit a rejection that suggests header overrides are needed.
+
+### 4. Install and Start LiteLLM
+
+Preferred install:
+
+```bash
+uv tool install "litellm[proxy]"
+```
+
+Fallback:
+
+```bash
+pip install "litellm[proxy]"
+```
+
+Start the proxy from the directory containing `config.yaml`:
+
+```bash
+litellm --config config.yaml --port 4000
+```
+
+Tell the user to keep that terminal open because the logs are the fastest truth source during verification.
+
+### 5. Explain GitHub Device Authorization
+
+On the first successful request to the GitHub Copilot provider, LiteLLM may open a device authorization flow:
+
+1. LiteLLM prints a verification URL and device code
+2. the user opens the URL and approves the request
+3. LiteLLM stores the resulting credential locally for future use
+
+Optional token-location overrides exist:
+
+- `GITHUB_COPILOT_TOKEN_DIR`
+- `GITHUB_COPILOT_ACCESS_TOKEN_FILE`
+
+Only mention these when the user needs custom token storage, shared environments, or troubleshooting around expired or misplaced credentials.
+
+### 6. Configure Claude Code
+
+For a temporary PowerShell session:
+
+```powershell
+$env:ANTHROPIC_AUTH_TOKEN = "sk-any-string"
+$env:ANTHROPIC_BASE_URL = "http://localhost:4000"
+$env:ANTHROPIC_MODEL = "claude-opus-4.5"
+$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
+claude
+```
+
+For a temporary Bash or Zsh session:
+
+```bash
+export ANTHROPIC_AUTH_TOKEN="sk-any-string"
+export ANTHROPIC_BASE_URL="http://localhost:4000"
+export ANTHROPIC_MODEL="claude-opus-4.5"
+export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+claude
+```
+
+For persistent configuration, merge these keys into `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "sk-any-string",
+    "ANTHROPIC_BASE_URL": "http://localhost:4000",
+    "ANTHROPIC_MODEL": "claude-opus-4.5",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
+  }
+}
+```
+
+Merge-safe behavior:
+
+- if the file does not exist, create it
+- if it exists, preserve all unrelated top-level keys
+- preserve existing `env` entries that are unrelated to this workflow
+- update only the four keys above
+- if the JSON is malformed, stop and report the parse problem instead of overwriting the file
+
+### 7. Verify The Request Chain
+
+Use two terminals when possible:
+
+- Terminal A runs LiteLLM
+- Terminal B runs `claude`
+
+Ask for one small prompt such as a short script or code review request, then verify:
+
+- Claude Code starts normally
+- LiteLLM logs show an inbound request
+- LiteLLM logs indicate the GitHub Copilot model route, typically `github_copilot/<model>`
+
+The healthy path is:
+
+```text
+Claude Code -> LiteLLM -> GitHub Copilot -> LiteLLM -> Claude Code
+```
+
+### 8. Troubleshooting
+
+If Claude Code reports model-not-found, 404-like failures, or LiteLLM says the model does not exist:
+
+- compare `ANTHROPIC_MODEL` to `model_name` exactly
+- check case, punctuation, and hyphens
+
+If LiteLLM never receives a request:
+
+- confirm `ANTHROPIC_BASE_URL` points to <http://localhost:4000>
+- confirm LiteLLM is still running on that port
+- confirm the environment variables were set in the same shell session that launched `claude`
+- check local firewall or port conflicts if the URL is correct but still silent
+
+If LiteLLM reaches GitHub Copilot but gets 401 or 403 responses:
+
+- repeat the device authorization flow by restarting LiteLLM and retrying
+- confirm the GitHub account still has Copilot access
+- if custom token-directory variables are set, verify they point to the intended files
+
+## Advanced Fallback: Header Overrides
+
+The article uses explicit Copilot-style headers. Current LiteLLM docs expose GitHub Copilot as a provider and also document header override support.
+
+Only reach for explicit `extra_headers` when:
+
+- the basic provider flow reaches Copilot but still needs client-shape overrides
+- the user already has evidence that a specific environment behaves better with editor-style headers
+
+Example fallback:
+
+```yaml
+model_list:
+  - model_name: claude-opus-4.5
+    litellm_params:
+      model: github_copilot/claude-opus-4.5
+      drop_params: true
+      extra_headers:
+        editor-version: "vscode/1.85.1"
+        editor-plugin-version: "copilot/1.155.0"
+        Copilot-Integration-Id: "vscode-chat"
+        user-agent: "GithubCopilot/1.155.0"
+```
+
+Present this as an advanced fallback, not the universal default.
+
+## Output Checklist
+
+When answering a real user request with this skill, include:
+
+- the brief compliance caveat
+- the exact `config.yaml` or the delta to apply
+- shell-appropriate commands
+- whether the setup is temporary or persistent
+- the verification path
+- the smallest relevant troubleshooting section if something failed
+
+## Safety Reminders
+
+- Do not state that GitHub officially supports this workaround.
+- Do not imply that a dummy `ANTHROPIC_AUTH_TOKEN` is a real Copilot credential.
+- Do not recommend replacing `~/.claude/settings.json` wholesale.
+- Do not present stale model names as guaranteed current availability; if the user asks for a specific model, keep the `github_copilot/<model>` pattern and note that Copilot-exposed model availability may change.

package/skills/scaffold-exercises/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: scaffold-exercises
+description: Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
+---
+
+# Scaffold Exercises
+
+Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`, then commit with `git commit`.
+
+## Directory naming
+
+- **Sections**: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
+- **Exercises**: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
+- Section number = `XX`, exercise number = `XX.YY`
+- Names are dash-case (lowercase, hyphens)
+
+## Exercise variants
+
+Each exercise needs at least one of these subfolders:
+
+- `problem/` - student workspace with TODOs
+- `solution/` - reference implementation
+- `explainer/` - conceptual material, no TODOs
+
+When stubbing, default to `explainer/` unless the plan specifies otherwise.
+
+## Required files
+
+Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
+
+- Is **not empty** (must have real content, even a single title line works)
+- Has no broken links
+
+When stubbing, create a minimal readme with a title and a description:
+
+```md
+# Exercise Title
+
+Description here
+```
+
+If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
+
+## Workflow
+
+1. **Parse the plan** - extract section names, exercise names, and variant types
+2. **Create directories** - `mkdir -p` for each path
+3. **Create stub readmes** - one `readme.md` per variant folder with a title
+4. **Run lint** - `pnpm ai-hero-cli internal lint` to validate
+5. **Fix any errors** - iterate until lint passes
+
+## Lint rules summary
+
+The linter (`pnpm ai-hero-cli internal lint`) checks:
+
+- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
+- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
+- `readme.md` exists and is non-empty in the primary subfolder
+- No `.gitkeep` files
+- No `speaker-notes.md` files
+- No broken links in readmes
+- No `pnpm run exercise` commands in readmes
+- `main.ts` required per subfolder unless it's readme-only
+
+## Moving/renaming exercises
+
+When renumbering or moving exercises:
+
+1. Use `git mv` (not `mv`) to rename directories - preserves git history
+2. Update the numeric prefix to maintain order
+3. Re-run lint after moves
+
+Example:
+
+```bash
+git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
+```
+
+## Example: stubbing from a plan
+
+Given a plan like:
+
+```
+Section 05: Memory Skill Building
+- 05.01 Introduction to Memory
+- 05.02 Short-term Memory (explainer + problem + solution)
+- 05.03 Long-term Memory
+```
+
+Create:
+
+```bash
+mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
+mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
+mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
+```
+
+Then create readme stubs:
+
+```
+exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
+```

package/skills/secure-linux-web-hosting/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: secure-linux-web-hosting
+description: Use when setting up, hardening, or reviewing a cloud server for self-hosting, including DNS, SSH, firewalls, Nginx, static-site hosting, reverse-proxying an app, HTTPS with Let's Encrypt or ACME clients, safe HTTP-to-HTTPS redirects, or optional post-launch network tuning such as BBR.
+---
+
+## Overview
+
+Use this skill to turn a cloud server into a safely reachable web host
+without leaning on stale distro-specific memory or outdated Debian-10-era
+tutorials.
+
+This skill keeps the familiar teaching arc of a beginner-friendly server guide,
+but turns it into a reusable operator workflow:
+
+1. Intake and routing
+2. Prerequisites
+3. Secure access
+4. Firewall and exposure
+5. Web server setup
+6. Static site or app proxy
+7. HTTPS
+8. Validation
+9. Optional advanced tuning
+
+Before giving actionable commands, identify the distro family and verify the
+current package names, service units, config paths, and ACME-client guidance
+against official documentation for the user's distro and chosen tools.
+
+Open [`references/workflow-map.md`](./references/workflow-map.md) first for the
+phase sequence, then open the narrower reference file you need.
+
+## When to Use
+
+Use this skill when the user mentions any of the following:
+
+- a cloud server, VM, droplet, or other Linux host they want to use for hosting
+- connecting a domain or DNS A/AAAA record to a server
+- SSH login, SSH hardening, root login, keys, ports, or firewall setup
+- installing or configuring Nginx for a website
+- serving a simple static site from Linux
+- putting a small app behind Nginx as a reverse proxy
+- HTTPS, Let's Encrypt, Certbot, `acme.sh`, certificate renewal, or redirecting
+  HTTP to HTTPS
+- optional post-setup performance or network tuning such as BBR
+
+Do not use this skill for:
+
+- Kubernetes, PaaS, or full container-orchestrator deployment design
+- application-specific build or CI/CD questions where Linux hosting is not the
+  actual problem
+- Windows or macOS host administration
+- public multi-tenant production architecture reviews that need a broader SRE
+  or platform-design treatment
+
+## Workflow
+
+### 1. Intake and classify the current state
+
+Start by identifying:
+
+- distro family or image name
+- whether the user has root access, an admin user, or only one live SSH session
+- whether DNS already points at the host
+- whether the goal is a static site or an app reverse proxy
+- whether ports are already exposed
+- whether HTTPS is already partially configured
+
+If the distro is unknown, ask for it or have the user inspect `/etc/os-release`
+before giving concrete package or service commands.
+
+### 2. Verify current docs before actionable commands
+
+Use bundled references for routing, then verify details against live official
+docs before giving commands that depend on current distro behavior.
+
+Always verify:
+
+- package manager commands and package names
+- firewall tooling and service names
+- SSH service unit names and config include paths
+- Nginx package and config layout
+- the chosen ACME client's current instructions
+
+If you cannot verify a detail, say so and give high-level guidance instead of
+pretending the old Debian tutorial path is universal.
+
+### 3. Keep the phases in order
+
+Walk through the phases in this order unless the user is explicitly asking for
+review or remediation of an existing setup:
+
+1. prerequisites
+2. secure access
+3. firewall and exposure
+4. web server
+5. choose one hosting branch: static site or app proxy
+6. HTTPS
+7. validation
+8. optional advanced tuning
+
+Do not collapse the static-site branch and reverse-proxy branch into one
+default answer. Pick the branch that matches the user's goal.
+
+### 4. Enforce the safety gates
+
+Treat these as hard stop checks:
+
+- Do not recommend changing SSH port, disabling password auth, or disabling
+  root SSH login until key-based login works in a second SSH session.
+- Do not recommend certificate issuance until DNS resolves to the intended host
+  and the HTTP site or proxy path works as expected.
+- Do not force an HTTP-to-HTTPS redirect until HTTPS loads cleanly.
+- Do not suggest BBR or similar tuning until secure hosting is already working.
+
+Always distinguish:
+
+- local-machine actions: SSH, DNS checks, browser tests
+- server actions: package install, config edits, service reloads, firewall rules
+
+## Output Expectations
+
+For a fresh setup, provide:
+
+- a brief diagnosis of the current state
+- the current phase and why it comes next
+- local-machine steps separate from server steps
+- concrete commands or config snippets only after doc verification
+- a verification step after each risky change
+- a short "if this fails, check X" branch for the likely mistake at that phase
+
+For a hardening or troubleshooting review, provide:
+
+- the most likely risk or breakage first
+- a prioritized remediation sequence
+- the first safe verification step before the next config change
+
+## Common Mistakes
+
+- treating Debian-specific commands from an old article as Linux-universal
+- hardening SSH in the only active session and locking the user out
+- opening application ports directly instead of keeping the app on loopback
+- mixing static-file hosting guidance and reverse-proxy guidance in one config
+- attempting ACME issuance before DNS or HTTP is actually correct
+- forcing redirects before HTTPS is proven
+- treating BBR as part of the core setup instead of an optional later step
+- ignoring SELinux or AppArmor differences when Nginx can read files on one
+  distro but not another
+
+## Reference Usage
+
+Use [`references/workflow-map.md`](./references/workflow-map.md) for the phase map,
+branching logic, and validation order.
+
+Use [`references/distro-routing.md`](./references/distro-routing.md) when distro
+family, package manager, firewall tooling, or config layout matters.
+
+Use [`references/nginx-patterns.md`](./references/nginx-patterns.md) when the user
+needs the static-site branch or the reverse-proxy branch.
+
+Use [`references/security-and-tls.md`](./references/security-and-tls.md) for SSH
+hardening sequence, firewall posture, certificate issuance, renewal, and
+redirect timing.

package/skills/setup-pre-commit/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: setup-pre-commit
+description: Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
+---
+
+# Setup Pre-Commit Hooks
+
+## What This Sets Up
+
+- **Husky** pre-commit hook
+- **lint-staged** running Prettier on all staged files
+- **Prettier** config (if missing)
+- **typecheck** and **test** scripts in the pre-commit hook
+
+## Steps
+
+### 1. Detect package manager
+
+Check for `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `bun.lockb` (bun). Use whichever is present. Default to npm if unclear.
+
+### 2. Install dependencies
+
+Install as devDependencies:
+
+```
+husky lint-staged prettier
+```
+
+### 3. Initialize Husky
+
+```bash
+npx husky init
+```
+
+This creates `.husky/` dir and adds `prepare: "husky"` to package.json.
+
+### 4. Create `.husky/pre-commit`
+
+Write this file (no shebang needed for Husky v9+):
+
+```
+npx lint-staged
+npm run typecheck
+npm run test
+```
+
+**Adapt**: Replace `npm` with detected package manager. If repo has no `typecheck` or `test` script in package.json, omit those lines and tell the user.
+
+### 5. Create `.lintstagedrc`
+
+```json
+{
+  "*": "prettier --ignore-unknown --write"
+}
+```
+
+### 6. Create `.prettierrc` (if missing)
+
+Only create if no Prettier config exists. Use these defaults:
+
+```json
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "semi": true,
+  "arrowParens": "always"
+}
+```
+
+### 7. Verify
+
+- [ ] `.husky/pre-commit` exists and is executable
+- [ ] `.lintstagedrc` exists
+- [ ] `prepare` script in package.json is `"husky"`
+- [ ] `prettier` config exists
+- [ ] Run `npx lint-staged` to verify it works
+
+### 8. Commit
+
+Stage all changed/created files and commit with message: `Add pre-commit hooks (husky + lint-staged + prettier)`
+
+This will run through the new pre-commit hooks — a good smoke test that everything works.
+
+## Notes
+
+- Husky v9+ doesn't need shebangs in hook files
+- `prettier --ignore-unknown` skips files Prettier can't parse (images, etc.)
+- The pre-commit runs lint-staged first (fast, staged-only), then full typecheck and tests