@otto-assistant/otto 0.1.2 → 0.7.16

package/skills/otto-publish/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: otto-publish
+description: >
+  End-to-end Otto release workflow for @otto-assistant/otto: commit, push,
+  verify GitHub Actions npm publish, fix failures, then upgrade on host and
+  restart dependent processes. Use when user says "publish".
+---
+
+# Otto Publish Workflow
+
+Run this workflow whenever the user asks to publish Otto.
+
+## Required behavior
+
+1. Commit and push requested changes.
+2. Verify the GitHub workflow that builds and publishes `@otto-assistant/otto` (and the `@otto-assistant/bridge` deprecation shim).
+3. If workflow fails, fix issues and repeat until green.
+4. Upgrade npm package on the current host.
+5. Restart processes/services that depend on the updated package.
+6. Report final published version and verification evidence.
+
+## Release commands
+
+Use repository root unless noted.
+
+```bash
+git status --short --branch
+git diff
+git log -8 --oneline
+```
+
+```bash
+# stage only requested files
+git add <files>
+
+git commit -m "$(cat <<'EOF'
+<message>
+EOF
+)"
+
+git push origin HEAD
+```
+
+```bash
+# monitor publish workflow
+gh run list --workflow "publish-npm.yml" --limit 10
+gh run view <run-id> --log
+```
+
+```bash
+# update package on host
+pnpm add -g @otto-assistant/otto@latest
+```
+
+## Validation after host upgrade
+
+```bash
+otto --version
+```
+
+If bot process is running, restart it with SIGUSR2 so it reloads new code.

package/skills/playwriter/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: playwriter
+description: Control the user own Chrome browser via Playwriter extension with Playwright code snippets in a stateful local js sandbox via playwriter cli. Use this over other Playwright MCPs to automate the browser — it connects to the user's existing Chrome instead of launching a new one. Use this for JS-heavy websites (Instagram, Twitter, cookie/login walls, lazy-loaded UIs) instead of webfetch/curl. Run `playwriter skill` command to read the complete up to date skill
+---
+
+## REQUIRED: Read Full Documentation First
+
+**Before using playwriter, you MUST run this command:**
+
+```bash
+playwriter skill # IMPORTANT! do not use | head here. read in full!
+```
+
+This outputs the complete documentation including:
+
+- Session management and timeout configuration
+- Selector strategies (and which ones to AVOID)
+- Rules to prevent timeouts and failures
+- Best practices for slow pages and SPAs
+- Context variables, utility functions, and more
+
+**Do NOT skip this step.** The quick examples below will fail without understanding timeouts, selector rules, and common pitfalls from the full docs.
+
+**Read the ENTIRE output.** Do NOT pipe through `head`, `tail`, or any truncation command. The skill output must be read in its entirety — critical rules about timeouts, selectors, and common pitfalls are spread throughout the document, not just at the top.
+
+## Minimal Example (after reading full docs)
+
+```bash
+playwriter session new
+playwriter -s 1 -e 'await page.goto("https://example.com")'
+```
+
+**Always use single quotes** for the `-e` argument. Single quotes prevent bash from interpreting `$`, backticks, and backslashes inside your JS code. Use double quotes or backtick template literals for strings inside the JS.
+
+If `playwriter` is not found, use `npx playwriter@latest` or `bunx playwriter@latest`.

package/skills/profano/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: profano
+description: CLI tool to analyze V8 .cpuprofile files and print top functions by self-time or total-time in the terminal. ALWAYS load this skill when CPU profiling JavaScript or TypeScript programs (Node, Vitest, Bun, Chrome DevTools exports) — it shows how to generate .cpuprofile files and how to inspect them from the terminal without opening Chrome DevTools.
+---
+
+# profano
+
+`profano` reads V8 `.cpuprofile` files and prints the heaviest functions as a table sorted by self-time or total (inclusive) time.
+
+Every time you use profano, you MUST fetch the latest README and read it in full:
+
+```bash
+curl -s https://raw.githubusercontent.com/remorses/profano/main/README.md  # NEVER pipe to head/tail, read in full
+```
+
+The README covers generating `.cpuprofile` files (Node, Vitest, Bun, Chrome DevTools, browser pages via playwriter, React component profiling), all CLI options, and how to read the output columns.

package/skills/proxyman/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: proxyman
+description: >
+  Reverse-engineer HTTP APIs using Proxyman for macOS. Intercept, record, and export
+  network traffic from CLI tools and apps (Node.js, Python, Ruby, Go, curl).
+  Export as HAR (JSON) and analyze with jq. Use this skill when the user wants
+  to capture, inspect, or reverse-engineer HTTP traffic from macOS applications.
+---
+
+# proxyman — HTTP traffic capture and reverse-engineering
+
+Proxyman is a macOS proxy that intercepts HTTP/HTTPS traffic. Use it to
+reverse-engineer APIs: capture what an app sends, inspect headers and bodies,
+and build SDKs or integrations from the captured data.
+
+## Important
+
+**Always run `proxyman-cli --help` and `proxyman-cli <subcommand> --help`
+before using.** The help output is the source of truth for all commands and
+options. The CLI binary lives inside the app bundle:
+
+```
+/Applications/Proxyman.app/Contents/MacOS/proxyman-cli
+```
+
+**Proxyman GUI must be running** for the CLI to work. The CLI talks to the
+running app — it does not work standalone or headless.
+
+```bash
+open -a Proxyman
+```
+
+## Node.js, Python, Ruby, Go, curl do NOT use macOS system proxy
+
+This is critical. Even though Proxyman auto-configures macOS system proxy
+settings, **CLI tools and runtimes ignore them**. You must set env vars so
+traffic routes through Proxyman (default port 9090):
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:9090 \
+HTTP_PROXY=http://127.0.0.1:9090 \
+NODE_TLS_REJECT_UNAUTHORIZED=0 \
+  <your-command-here>
+```
+
+- `HTTPS_PROXY` / `HTTP_PROXY`: route traffic through Proxyman
+- `NODE_TLS_REJECT_UNAUTHORIZED=0`: accept Proxyman's SSL cert for Node.js apps
+- For Python: `REQUESTS_CA_BUNDLE` or `SSL_CERT_FILE` may be needed instead
+- For curl: use `--proxy http://127.0.0.1:9090 -k` or set the env vars
+
+Proxyman also has an "Automatic Setup" feature (Setup menu > Automatic Setup)
+that opens a pre-configured terminal with all env vars set. But for scripting
+and agent use, set the env vars explicitly as shown above.
+
+## CLI reference
+
+```
+proxyman-cli clear-session              Clear current captured traffic
+proxyman-cli export-log [options]       Export captured traffic to file
+proxyman-cli export [options]           Export debug tool rules (Map Local, etc)
+proxyman-cli import --input <file>      Import debug tool rules
+proxyman-cli proxy on|off               Toggle macOS system HTTP proxy
+proxyman-cli breakpoint enable|disable  Toggle Breakpoint tool
+proxyman-cli maplocal enable|disable    Toggle Map Local tool
+proxyman-cli scripting enable|disable   Toggle Scripting tool
+proxyman-cli install-root-cert <file>   Install custom root cert (requires sudo)
+```
+
+### export-log options
+
+```
+-m, --mode <mode>         all | domains (default: all)
+-o, --output <path>       Output file path (required)
+-d, --domains <domain>    Filter by domain (repeatable, only with -m domains)
+-f, --format <format>     proxymansession | har | raw (default: proxymansession)
+```
+
+**Always use `-f har`** for agent workflows. HAR is JSON and works with jq.
+
+### export-log timing bug
+
+The CLI can report "Exported Completed!" before the file is actually written.
+Add `sleep 3` after export-log before reading the file:
+
+```bash
+proxyman-cli export-log -m all -o capture.har -f har
+sleep 3
+jq '.log.entries | length' capture.har
+```
+
+## Reverse-engineering workflow
+
+This is the primary use case. Example: figuring out how Claude Code talks to
+the Anthropic API.
+
+```bash
+# 1. Make sure Proxyman is running
+open -a Proxyman
+
+# 2. Clear previous traffic
+proxyman-cli clear-session
+
+# 3. Run the target app through the proxy
+HTTPS_PROXY=http://127.0.0.1:9090 \
+HTTP_PROXY=http://127.0.0.1:9090 \
+NODE_TLS_REJECT_UNAUTHORIZED=0 \
+  claude -p "say hi" --max-turns 1
+
+# 4. Export captured traffic as HAR
+proxyman-cli export-log -m all -o capture.har -f har
+sleep 3
+
+# 5. Filter for the domain you care about
+jq '[.log.entries[] | select(.request.url | test("anthropic"))]' capture.har
+```
+
+## Analyzing HAR files with jq
+
+### List all domains and request counts
+
+```bash
+jq '[.log.entries[].request.url] | map(split("/")[2])
+  | group_by(.) | map({domain: .[0], count: length})
+  | sort_by(-.count)' capture.har
+```
+
+### Filter by domain
+
+```bash
+jq '.log.entries[] | select(.request.url | test("api.example.com"))' capture.har
+```
+
+### Request summary (method, url, status)
+
+```bash
+jq '[.log.entries[] | select(.request.url | test("api.example.com")) | {
+  method: .request.method,
+  url: .request.url,
+  status: .response.status
+}]' capture.har
+```
+
+### Full request details (headers + body)
+
+```bash
+jq '.log.entries[] | select(.request.url | test("v1/messages")) | {
+  url: .request.url,
+  method: .request.method,
+  status: .response.status,
+  request_headers: [.request.headers[] | {(.name): .value}] | add,
+  request_body: (.request.postData.text | fromjson? // .request.postData.text),
+  response_body: (.response.content.text | fromjson? // .response.content.text)
+}' capture.har
+```
+
+### Request body structure (without full content)
+
+Useful for large payloads — see the shape without the bulk:
+
+```bash
+jq '.log.entries[] | select(.request.url | test("v1/messages"))
+  | .request.postData.text | fromjson
+  | {model, max_tokens, stream,
+     system_count: (.system | length),
+     messages_count: (.messages | length),
+     tools_count: (.tools | length),
+     messages: [.messages[] | {role, content_type: (.content | type)}]
+  }' capture.har
+```
+
+### Extract specific headers
+
+```bash
+jq '.log.entries[] | select(.request.url | test("api.example.com"))
+  | {url: .request.url, auth: (.request.headers[] | select(.name == "authorization") | .value)}' capture.har
+```
+
+### Only failed requests
+
+```bash
+jq '[.log.entries[] | select(.response.status >= 400) | {
+  url: .request.url,
+  status: .response.status,
+  error: .response.content.text
+}]' capture.har
+```
+
+## Domain-filtered export
+
+If you only care about one domain, filter at export time to get a smaller file:
+
+```bash
+proxyman-cli export-log -m domains --domains 'api.anthropic.com' -o anthropic.har -f har
+```
+
+Multiple domains:
+
+```bash
+proxyman-cli export-log -m domains \
+  --domains 'api.anthropic.com' \
+  --domains 'mcp-proxy.anthropic.com' \
+  -o anthropic.har -f har
+```
+
+## SSL proxying
+
+Proxyman needs to decrypt HTTPS to see request/response bodies. For Node.js
+apps, `NODE_TLS_REJECT_UNAUTHORIZED=0` handles this. For system apps and
+browsers, install and trust the Proxyman root certificate:
+
+- Proxyman menu > Certificate > Install Certificate on this Mac
+- Or via CLI: `proxyman-cli install-root-cert <path-to-cert>`
+
+Without SSL proxying enabled for a domain, you'll see the connection but not
+the decrypted body content.

package/skills/security-review/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: security-review
+description: >
+  Complete a security review of the pending changes on the current branch.
+  Performs a focused, high-confidence security audit with detailed false-positive
+  filtering. Use when the user wants a security review of their PR or branch changes.
+allowed-tools:
+  - Bash(git diff:*)
+  - Bash(git status:*)
+  - Bash(git log:*)
+  - Bash(git show:*)
+  - Bash(git remote show:*)
+  - Read
+  - Glob
+  - Grep
+  - LS
+  - Task
+source-path: cli.js (line 4337, embedded SKILL.md in variable Azz)
+source-package: "@anthropic-ai/claude-code@2.1.63"
+source-date: 2026-02-28
+---
+
+You are a senior security engineer conducting a focused security review of the changes on this branch.
+
+GIT STATUS:
+
+```
+!`git status`
+```
+
+FILES MODIFIED:
+
+```
+!`git diff --name-only origin/HEAD...`
+```
+
+COMMITS:
+
+```
+!`git log --no-decorate origin/HEAD...`
+```
+
+DIFF CONTENT:
+
+```
+!`git diff --merge-base origin/HEAD`
+```
+
+Review the complete diff above. This contains all code changes in the PR.
+
+
+OBJECTIVE:
+Perform a security-focused code review to identify HIGH-CONFIDENCE security vulnerabilities that could have real exploitation potential. This is not a general code review - focus ONLY on security implications newly added by this PR. Do not comment on existing security concerns.
+
+CRITICAL INSTRUCTIONS:
+1. MINIMIZE FALSE POSITIVES: Only flag issues where you're >80% confident of actual exploitability
+2. AVOID NOISE: Skip theoretical issues, style concerns, or low-impact findings
+3. FOCUS ON IMPACT: Prioritize vulnerabilities that could lead to unauthorized access, data breaches, or system compromise
+4. EXCLUSIONS: Do NOT report the following issue types:
+   - Denial of Service (DOS) vulnerabilities, even if they allow service disruption
+   - Secrets or sensitive data stored on disk (these are handled by other processes)
+   - Rate limiting or resource exhaustion issues
+
+SECURITY CATEGORIES TO EXAMINE:
+
+**Input Validation Vulnerabilities:**
+- SQL injection via unsanitized user input
+- Command injection in system calls or subprocesses
+- XXE injection in XML parsing
+- Template injection in templating engines
+- NoSQL injection in database queries
+- Path traversal in file operations
+
+**Authentication & Authorization Issues:**
+- Authentication bypass logic
+- Privilege escalation paths
+- Session management flaws
+- JWT token vulnerabilities
+- Authorization logic bypasses
+
+**Crypto & Secrets Management:**
+- Hardcoded API keys, passwords, or tokens
+- Weak cryptographic algorithms or implementations
+- Improper key storage or management
+- Cryptographic randomness issues
+- Certificate validation bypasses
+
+**Injection & Code Execution:**
+- Remote code execution via deseralization
+- Pickle injection in Python
+- YAML deserialization vulnerabilities
+- Eval injection in dynamic code execution
+- XSS vulnerabilities in web applications (reflected, stored, DOM-based)
+
+**Data Exposure:**
+- Sensitive data logging or storage
+- PII handling violations
+- API endpoint data leakage
+- Debug information exposure
+
+Additional notes:
+- Even if something is only exploitable from the local network, it can still be a HIGH severity issue
+
+ANALYSIS METHODOLOGY:
+
+Phase 1 - Repository Context Research (Use file search tools):
+- Identify existing security frameworks and libraries in use
+- Look for established secure coding patterns in the codebase
+- Examine existing sanitization and validation patterns
+- Understand the project's security model and threat model
+
+Phase 2 - Comparative Analysis:
+- Compare new code changes against existing security patterns
+- Identify deviations from established secure practices
+- Look for inconsistent security implementations
+- Flag code that introduces new attack surfaces
+
+Phase 3 - Vulnerability Assessment:
+- Examine each modified file for security implications
+- Trace data flow from user inputs to sensitive operations
+- Look for privilege boundaries being crossed unsafely
+- Identify injection points and unsafe deserialization
+
+REQUIRED OUTPUT FORMAT:
+
+You MUST output your findings in markdown. The markdown output should contain the file, line number, severity, category (e.g. `sql_injection` or `xss`), description, exploit scenario, and fix recommendation.
+
+For example:
+
+# Vuln 1: XSS: `foo.py:42`
+
+* Severity: High
+* Description: User input from `username` parameter is directly interpolated into HTML without escaping, allowing reflected XSS attacks
+* Exploit Scenario: Attacker crafts URL like /bar?q=<script>alert(document.cookie)</script> to execute JavaScript in victim's browser, enabling session hijacking or data theft
+* Recommendation: Use Flask's escape() function or Jinja2 templates with auto-escaping enabled for all user inputs rendered in HTML
+
+SEVERITY GUIDELINES:
+- **HIGH**: Directly exploitable vulnerabilities leading to RCE, data breach, or authentication bypass
+- **MEDIUM**: Vulnerabilities requiring specific conditions but with significant impact
+- **LOW**: Defense-in-depth issues or lower-impact vulnerabilities
+
+CONFIDENCE SCORING:
+- 0.9-1.0: Certain exploit path identified, tested if possible
+- 0.8-0.9: Clear vulnerability pattern with known exploitation methods
+- 0.7-0.8: Suspicious pattern requiring specific conditions to exploit
+- Below 0.7: Don't report (too speculative)
+
+FINAL REMINDER:
+Focus on HIGH and MEDIUM findings only. Better to miss some theoretical issues than flood the report with false positives. Each finding should be something a security engineer would confidently raise in a PR review.
+
+FALSE POSITIVE FILTERING:
+
+> You do not need to run commands to reproduce the vulnerability, just read the code to determine if it is a real vulnerability. Do not use the bash tool or write to any files.
+>
+> HARD EXCLUSIONS - Automatically exclude findings matching these patterns:
+> 1. Denial of Service (DOS) vulnerabilities or resource exhaustion attacks.
+> 2. Secrets or credentials stored on disk if they are otherwise secured.
+> 3. Rate limiting concerns or service overload scenarios.
+> 4. Memory consumption or CPU exhaustion issues.
+> 5. Lack of input validation on non-security-critical fields without proven security impact.
+> 6. Input sanitization concerns for GitHub Action workflows unless they are clearly triggerable via untrusted input.
+> 7. A lack of hardening measures. Code is not expected to implement all security best practices, only flag concrete vulnerabilities.
+> 8. Race conditions or timing attacks that are theoretical rather than practical issues. Only report a race condition if it is concretely problematic.
+> 9. Vulnerabilities related to outdated third-party libraries. These are managed separately and should not be reported here.
+> 10. Memory safety issues such as buffer overflows or use-after-free-vulnerabilities are impossible in rust. Do not report memory safety issues in rust or any other memory safe languages.
+> 11. Files that are only unit tests or only used as part of running tests.
+> 12. Log spoofing concerns. Outputting un-sanitized user input to logs is not a vulnerability.
+> 13. SSRF vulnerabilities that only control the path. SSRF is only a concern if it can control the host or protocol.
+> 14. Including user-controlled content in AI system prompts is not a vulnerability.
+> 15. Regex injection. Injecting untrusted content into a regex is not a vulnerability.
+> 16. Regex DOS concerns.
+> 16. Insecure documentation. Do not report any findings in documentation files such as markdown files.
+> 17. A lack of audit logs is not a vulnerability.
+>
+> PRECEDENTS -
+> 1. Logging high value secrets in plaintext is a vulnerability. Logging URLs is assumed to be safe.
+> 2. UUIDs can be assumed to be unguessable and do not need to be validated.
+> 3. Environment variables and CLI flags are trusted values. Attackers are generally not able to modify them in a secure environment. Any attack that relies on controlling an environment variable is invalid.
+> 4. Resource management issues such as memory or file descriptor leaks are not valid.
+> 5. Subtle or low impact web vulnerabilities such as tabnabbing, XS-Leaks, prototype pollution, and open redirects should not be reported unless they are extremely high confidence.
+> 6. React and Angular are generally secure against XSS. These frameworks do not need to sanitize or escape user input unless it is using dangerouslySetInnerHTML, bypassSecurityTrustHtml, or similar methods. Do not report XSS vulnerabilities in React or Angular components or tsx files unless they are using unsafe methods.
+> 7. Most vulnerabilities in github action workflows are not exploitable in practice. Before validating a github action workflow vulnerability ensure it is concrete and has a very specific attack path.
+> 8. A lack of permission checking or authentication in client-side JS/TS code is not a vulnerability. Client-side code is not trusted and does not need to implement these checks, they are handled on the server-side. The same applies to all flows that send untrusted data to the backend, the backend is responsible for validating and sanitizing all inputs.
+> 9. Only include MEDIUM findings if they are obvious and concrete issues.
+> 10. Most vulnerabilities in ipython notebooks (*.ipynb files) are not exploitable in practice. Before validating a notebook vulnerability ensure it is concrete and has a very specific attack path where untrusted input can trigger the vulnerability.
+> 11. Logging non-PII data is not a vulnerability even if the data may be sensitive. Only report logging vulnerabilities if they expose sensitive information such as secrets, passwords, or personally identifiable information (PII).
+> 12. Command injection vulnerabilities in shell scripts are generally not exploitable in practice since shell scripts generally do not run with untrusted user input. Only report command injection vulnerabilities in shell scripts if they are concrete and have a very specific attack path for untrusted input.
+>
+> SIGNAL QUALITY CRITERIA - For remaining findings, assess:
+> 1. Is there a concrete, exploitable vulnerability with a clear attack path?
+> 2. Does this represent a real security risk vs theoretical best practice?
+> 3. Are there specific code locations and reproduction steps?
+> 4. Would this finding be actionable for a security team?
+>
+> For each finding, assign a confidence score from 1-10:
+> - 1-3: Low confidence, likely false positive or noise
+> - 4-6: Medium confidence, needs investigation
+> - 7-10: High confidence, likely true vulnerability
+
+START ANALYSIS:
+
+Begin your analysis now. Do this in 3 steps:
+
+1. Use a sub-task to identify vulnerabilities. Use the repository exploration tools to understand the codebase context, then analyze the PR changes for security implications. In the prompt for this sub-task, include all of the above.
+2. Then for each vulnerability identified by the above sub-task, create a new sub-task to filter out false-positives. Launch these sub-tasks as parallel sub-tasks. In the prompt for these sub-tasks, include everything in the "FALSE POSITIVE FILTERING" instructions.
+3. Filter out any vulnerabilities where the sub-task reported a confidence less than 8.
+
+Your final reply must contain the markdown report and nothing else.

package/skills/sigillo/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: sigillo
+description: >
+  Sigillo is a self-hostable open-source alternative to Doppler. Use when
+  working with sigillo run, sigillo setup, sigillo login, managing secrets,
+  projects, or environments. Also load when integrating Sigillo into CI,
+  Cloudflare Workers, Docker, Vercel, or any other deployment target.
+---
+
+# sigillo
+
+Every time you work with sigillo, you MUST fetch the latest README:
+
+```bash
+curl -s https://raw.githubusercontent.com/remorses/sigillo/main/README.md
+```
+
+**Never pipe through `head`, `tail`, `sed -n`, or any truncating command.** Read the full output.
+
+## Rules for agents
+
+### Never read `.env` files directly
+
+If a `.env` file exists, **do not source it or read its contents**. Use `sigillo run` instead so secrets are injected without being read by the agent:
+
+```bash
+# BAD — exposes secrets to the agent context window
+source .env && next dev
+cat .env
+
+# GOOD — secrets injected, never visible
+sigillo run -- next dev
+```
+
+### Non-interactive auth
+
+`sigillo login` opens a browser. In agent sessions, use a token instead:
+
+```bash
+# Option A: env var (preferred in CI / agent sessions)
+export SIGILLO_TOKEN="sig_xxx"
+
+# Option B: save token scoped to the current directory
+sigillo login --token sig_xxx --scope .
+```
+
+Token is stored in `~/.sigillo/config.json`. Subsequent commands in that directory pick it up without `--token`.
+
+### Directory scoping
+
+`sigillo setup` binds the current directory to a project and environment. The CLI resolves config by **longest matching scope**.
+
+```bash
+# Non-interactive — use in agent sessions
+sigillo setup --project proj_abc --env production
+```
+
+After this, `sigillo run` in any subdirectory uses that project + environment automatically.
+
+### Verify what is injected
+
+```bash
+# List injected variable names (values are redacted)
+sigillo run -- printenv
+
+# Get a single value
+sigillo secrets get DATABASE_URL
+```
+
+### Redaction details
+
+`sigillo run` replaces secret values in stdout/stderr with `*`. Threshold: **Shannon entropy ≥ 3.5 bits/char AND length ≥ 16 chars** — short or low-entropy values like `true`, `1`, `development` are not redacted. Use `--disable-redaction` only when explicitly verifying values.
+
+### Mount secrets to a file for tools that require it
+
+Some tools (wrangler, docker) read from files, not env vars:
+
+```bash
+# Write secrets to a temp file, deleted after the process exits
+sigillo run --mount .env.prod --mount-format env -- wrangler secret bulk .env.prod
+
+# Mount as JSON for config loaders
+sigillo run --mount config/secrets.json --mount-format json -- node server.js
+```
+
+The mounted file is **deleted** once the child process exits.
+
+### CI environment variables
+
+```yaml
+- name: Run with secrets
+  env:
+    SIGILLO_TOKEN: ${{ secrets.SIGILLO_TOKEN }}
+    SIGILLO_PROJECT: ${{ vars.SIGILLO_PROJECT }}
+    SIGILLO_ENVIRONMENT: production
+  run: npx sigillo run -- pnpm build
+```
+
+### Prefer `sigillo run` over downloading secrets
+
+Avoid `sigillo secrets download` unless a specific tool requires a file format. Prefer injecting directly via `sigillo run --` so values never touch the filesystem.