@protolabsai/proto 0.14.0

package/dist/bundled/qc-helper/docs/support/troubleshooting.md

@@ -0,0 +1,123 @@
+# Troubleshooting
+
+This guide provides solutions to common issues and debugging tips, including topics on:
+
+- Authentication or login errors
+- Frequently asked questions (FAQs)
+- Debugging tips
+- Existing GitHub Issues similar to yours or creating new Issues
+
+## Authentication or login errors
+
+- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, or `unable to get local issuer certificate`**
+  - **Cause:** You may be on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This often requires a custom root CA certificate to be trusted by Node.js.
+  - **Solution:** Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of your corporate root CA certificate file.
+    - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt`
+
+- **Error: `Device authorization flow failed: fetch failed`**
+  - **Cause:** Node.js could not reach Qwen OAuth endpoints (often a proxy or SSL/TLS trust issue). When available, Qwen Code will also print the underlying error cause (for example: `UNABLE_TO_VERIFY_LEAF_SIGNATURE`).
+  - **Solution:**
+    - Confirm you can access `https://chat.qwen.ai` from the same machine/network.
+    - If you are behind a proxy, set it via `qwen --proxy <url>` (or the `proxy` setting in `settings.json`).
+    - If your network uses a corporate TLS inspection CA, set `NODE_EXTRA_CA_CERTS` as described above.
+
+- **Issue: Unable to display UI after authentication failure**
+  - **Cause:** If authentication fails after selecting an authentication type, the `security.auth.selectedType` setting may be persisted in `settings.json`. On restart, the CLI may get stuck trying to authenticate with the failed auth type and fail to display the UI.
+  - **Solution:** Clear the `security.auth.selectedType` configuration item in your `settings.json` file:
+    - Open `~/.qwen/settings.json` (or `./.qwen/settings.json` for project-specific settings)
+    - Remove the `security.auth.selectedType` field
+    - Restart the CLI to allow it to prompt for authentication again
+
+## Frequently asked questions (FAQs)
+
+- **Q: How do I update Qwen Code to the latest version?**
+  - A: If you installed it globally via `npm`, update it using the command `npm install -g @qwen-code/qwen-code@latest`. If you compiled it from source, pull the latest changes from the repository, and then rebuild using the command `npm run build`.
+
+- **Q: Where are the Qwen Code configuration or settings files stored?**
+  - A: The Qwen Code configuration is stored in two `settings.json` files:
+    1. In your home directory: `~/.qwen/settings.json`.
+    2. In your project's root directory: `./.qwen/settings.json`.
+
+    Refer to [Qwen Code Configuration](../configuration/settings) for more details.
+
+- **Q: Why don't I see cached token counts in my stats output?**
+  - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Qwen API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Qwen Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command.
+
+## Common error messages and solutions
+
+- **Error: `EADDRINUSE` (Address already in use) when starting an MCP server.**
+  - **Cause:** Another process is already using the port that the MCP server is trying to bind to.
+  - **Solution:**
+    Either stop the other process that is using the port or configure the MCP server to use a different port.
+
+- **Error: Command not found (when attempting to run Qwen Code with `qwen`).**
+  - **Cause:** The CLI is not correctly installed or it is not in your system's `PATH`.
+  - **Solution:**
+    The update depends on how you installed Qwen Code:
+    - If you installed `qwen` globally, check that your `npm` global binary directory is in your `PATH`. You can update using the command `npm install -g @qwen-code/qwen-code@latest`.
+    - If you are running `qwen` from source, ensure you are using the correct command to invoke it (e.g. `node packages/cli/dist/index.js ...`). To update, pull the latest changes from the repository, and then rebuild using the command `npm run build`.
+
+- **Error: `MODULE_NOT_FOUND` or import errors.**
+  - **Cause:** Dependencies are not installed correctly, or the project hasn't been built.
+  - **Solution:**
+    1.  Run `npm install` to ensure all dependencies are present.
+    2.  Run `npm run build` to compile the project.
+    3.  Verify that the build completed successfully with `npm run start`.
+
+- **Error: "Operation not permitted", "Permission denied", or similar.**
+  - **Cause:** When sandboxing is enabled, Qwen Code may attempt operations that are restricted by your sandbox configuration, such as writing outside the project directory or system temp directory.
+  - **Solution:** Refer to the [Configuration: Sandboxing](../features/sandbox) documentation for more information, including how to customize your sandbox configuration.
+
+- **Qwen Code is not running in interactive mode in "CI" environments**
+  - **Issue:** Qwen Code does not enter interactive mode (no prompt appears) if an environment variable starting with `CI_` (e.g. `CI_TOKEN`) is set. This is because the `is-in-ci` package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment.
+  - **Cause:** The `is-in-ci` package checks for the presence of `CI`, `CONTINUOUS_INTEGRATION`, or any environment variable with a `CI_` prefix. When any of these are found, it signals that the environment is non-interactive, which prevents the CLI from starting in its interactive mode.
+  - **Solution:** If the `CI_` prefixed variable is not needed for the CLI to function, you can temporarily unset it for the command. e.g. `env -u CI_TOKEN qwen`
+
+- **DEBUG mode not working from project .env file**
+  - **Issue:** Setting `DEBUG=true` in a project's `.env` file doesn't enable debug mode for the CLI.
+  - **Cause:** The `DEBUG` and `DEBUG_MODE` variables are automatically excluded from project `.env` files to prevent interference with the CLI behavior.
+  - **Solution:** Use a `.qwen/.env` file instead, or configure the `advanced.excludedEnvVars` setting in your `settings.json` to exclude fewer variables.
+
+## IDE Companion not connecting
+
+- Ensure VS Code has a single workspace folder open.
+- Restart the integrated terminal after installing the extension so it inherits:
+  - `QWEN_CODE_IDE_WORKSPACE_PATH`
+  - `QWEN_CODE_IDE_SERVER_PORT`
+- If running in a container, verify `host.docker.internal` resolves. Otherwise, map the host appropriately.
+- Reinstall the companion with `/ide install` and use “Qwen Code: Run” in the Command Palette to verify it launches.
+
+## Exit Codes
+
+The Qwen Code uses specific exit codes to indicate the reason for termination. This is especially useful for scripting and automation.
+
+| Exit Code | Error Type                 | Description                                                                                         |
+| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
+| 41        | `FatalAuthenticationError` | An error occurred during the authentication process.                                                |
+| 42        | `FatalInputError`          | Invalid or missing input was provided to the CLI. (non-interactive mode only)                       |
+| 44        | `FatalSandboxError`        | An error occurred with the sandboxing environment (e.g. Docker, Podman, or Seatbelt).               |
+| 52        | `FatalConfigError`         | A configuration file (`settings.json`) is invalid or contains errors.                               |
+| 53        | `FatalTurnLimitedError`    | The maximum number of conversational turns for the session was reached. (non-interactive mode only) |
+
+## Debugging Tips
+
+- **CLI debugging:**
+  - Use the `--verbose` flag (if available) with CLI commands for more detailed output.
+  - Check the CLI logs, often found in a user-specific configuration or cache directory.
+
+- **Core debugging:**
+  - Check the server console output for error messages or stack traces.
+  - Increase log verbosity if configurable.
+  - Use Node.js debugging tools (e.g. `node --inspect`) if you need to step through server-side code.
+
+- **Tool issues:**
+  - If a specific tool is failing, try to isolate the issue by running the simplest possible version of the command or operation the tool performs.
+  - For `run_shell_command`, check that the command works directly in your shell first.
+  - For _file system tools_, verify that paths are correct and check the permissions.
+
+- **Pre-flight checks:**
+  - Always run `npm run preflight` before committing code. This can catch many common issues related to formatting, linting, and type errors.
+
+## Existing GitHub Issues similar to yours or creating new Issues
+
+If you encounter an issue that was not covered here in this _Troubleshooting guide_, consider searching the Qwen Code [Issue tracker on GitHub](https://github.com/QwenLM/qwen-code/issues). If you can't find an issue similar to yours, consider creating a new GitHub Issue with a detailed description. Pull requests are also welcome!

package/dist/bundled/receiving-code-review/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake                      | Fix                                 |
+| ---------------------------- | ----------------------------------- |
+| Performative agreement       | State requirement or just act       |
+| Blind implementation         | Verify against codebase first       |
+| Batch without testing        | One at a time, test each            |
+| Assuming reviewer is right   | Check if breaks things              |
+| Avoiding pushback            | Technical correctness > comfort     |
+| Partial implementation       | Clarify all items first             |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## GitHub Thread Replies
+
+When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.

package/dist/bundled/requesting-code-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+---
+
+# Requesting Code Review
+
+Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code-reviewer subagent:**
+
+Use the Agent tool with subagent_type: "deepcode", fill template at `code-reviewer.md`
+
+**Placeholders:**
+
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch superpowers:code-reviewer subagent]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: requesting-code-review/code-reviewer.md

package/dist/bundled/review/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: review
+description: Review changed code for correctness, security, code quality, and performance. Use when the user asks to review code changes, a PR, or specific files. Invoke with `/review`, `/review <pr-number>`, or `/review <file-path>`.
+allowedTools:
+  - task
+  - run_shell_command
+  - grep_search
+  - read_file
+  - glob
+---
+
+# Code Review
+
+You are an expert code reviewer. Your job is to review code changes and provide actionable feedback.
+
+## Step 1: Determine what to review
+
+Your goal here is to understand the scope of changes so you can dispatch agents effectively in Step 2. Based on the arguments provided:
+
+- **No arguments**: Review local uncommitted changes
+  - Run `git diff` and `git diff --staged` to get all changes
+  - If both diffs are empty, inform the user there are no changes to review and stop here — do not proceed to the review agents
+
+- **PR number or URL** (e.g., `123` or `https://github.com/.../pull/123`):
+  - Save the current branch name, stash any local changes (`git stash --include-untracked`), then `gh pr checkout <number>`
+  - Run `gh pr view <number>` and save the output (title, description, base branch, etc.) to a temp file (e.g., `/tmp/pr-review-context.md`) so agents can read it without you repeating it in each prompt
+  - Note the base branch (e.g., `main`) — agents will use `git diff <base>...HEAD` to get the diff and can read files directly
+
+- **File path** (e.g., `src/foo.ts`):
+  - Run `git diff HEAD -- <file>` to get recent changes
+  - If no diff, read the file and review its current state
+
+## Step 2: Parallel multi-dimensional review
+
+Launch **four parallel review agents** to analyze the changes from different angles. Each agent should focus exclusively on its dimension.
+
+**IMPORTANT**: Do NOT paste the full diff into each agent's prompt — this duplicates it 4x. Instead, give each agent the command to obtain the diff, a concise summary of what the changes are about, and its review focus. Each agent can read files and search the codebase on its own.
+
+### Agent 1: Correctness & Security
+
+Focus areas:
+
+- Logic errors and edge cases
+- Null/undefined handling
+- Race conditions and concurrency issues
+- Security vulnerabilities (injection, XSS, SSRF, path traversal, etc.)
+- Type safety issues
+- Error handling gaps
+
+### Agent 2: Code Quality
+
+Focus areas:
+
+- Code style consistency with the surrounding codebase
+- Naming conventions (variables, functions, classes)
+- Code duplication and opportunities for reuse
+- Over-engineering or unnecessary abstraction
+- Missing or misleading comments
+- Dead code
+
+### Agent 3: Performance & Efficiency
+
+Focus areas:
+
+- Performance bottlenecks (N+1 queries, unnecessary loops, etc.)
+- Memory leaks or excessive memory usage
+- Unnecessary re-renders (for UI code)
+- Inefficient algorithms or data structures
+- Missing caching opportunities
+- Bundle size impact
+
+### Agent 4: Undirected Audit
+
+No preset dimension. Review the code with a completely fresh perspective to catch issues the other three agents may miss.
+Focus areas:
+
+- Business logic soundness and correctness of assumptions
+- Boundary interactions between modules or services
+- Implicit assumptions that may break under different conditions
+- Unexpected side effects or hidden coupling
+- Anything else that looks off — trust your instincts
+
+## Step 3: Restore environment and present findings
+
+If you checked out a PR branch in Step 1, restore the original state first: check out the original branch, `git stash pop` if changes were stashed, and remove the temp file.
+
+Then combine results from all four agents into a single, well-organized review. Use this format:
+
+### Summary
+
+A 1-2 sentence overview of the changes and overall assessment.
+
+### Findings
+
+Use severity levels:
+
+- **Critical** — Must fix before merging. Bugs, security issues, data loss risks.
+- **Suggestion** — Recommended improvement. Better patterns, clearer code, potential issues.
+- **Nice to have** — Optional optimization. Minor style tweaks, small performance gains.
+
+For each finding, include:
+
+1. **File and line reference** (e.g., `src/foo.ts:42`)
+2. **What's wrong** — Clear description of the issue
+3. **Why it matters** — Impact if not addressed
+4. **Suggested fix** — Concrete code suggestion when possible
+
+### Verdict
+
+One of:
+
+- **Approve** — No critical issues, good to merge
+- **Request changes** — Has critical issues that need fixing
+- **Comment** — Has suggestions but no blockers
+
+## Guidelines
+
+- Be specific and actionable. Avoid vague feedback like "could be improved."
+- Reference the existing codebase conventions — don't impose external style preferences.
+- Focus on the diff, not pre-existing issues in unchanged code.
+- Keep the review concise. Don't repeat the same point for every occurrence.
+- When suggesting a fix, show the actual code change.
+- Flag any exposed secrets, credentials, API keys, or tokens in the diff as **Critical**.