npm - @przeprogramowani/10x-cli - Versions diffs - 1.20.0 → 1.22.0 - Mend

@przeprogramowani/10x-cli 1.20.0 → 1.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +170 -26
package/dist/index.mjs +2964 -1118
package/package.json +3 -2
package/skills/10x-cli-guide/SKILL.md +227 -202
package/skills/10x-cli-guide/references/compatibility.md +310 -0
package/skills/10x-cli-setup/SKILL.md +119 -39
package/skills/10x-cli-setup/references/compatibility.md +310 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@przeprogramowani/10x-cli",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Open-source CLI for 10xDevs course content",
   "repository": {
     "type": "git",
@@ -27,7 +27,8 @@
     "generate-types": "bun run scripts/generate-types.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "lint": "bun run --bun node_modules/oxlint/bin/oxlint ."
+    "lint": "bun run --bun node_modules/oxlint/bin/oxlint .",
+    "validate:cli-skills": "node scripts/validate-cli-skills.mjs"
   },
   "dependencies": {
     "@clack/prompts": "0.9.1",

package/skills/10x-cli-guide/SKILL.md CHANGED Viewed

@@ -1,237 +1,262 @@
 ---
 name: 10x-cli-guide
-description: "Invoke this skill when the user asks how to USE the 10x-cli day-to-day — fetching lessons, listing modules, switching AI tools, troubleshooting errors, understanding where artifacts land, checking the 10xBench model leaderboard, or working on a specific OS (Windows, Linux, macOS). Covers commands (get, list, doctor, auth --status/--logout, bench), tool profiles, artifact locations, common errors, and platform-specific tips. Excludes: first-time installation and onboarding (use 10x-cli-setup instead), developing or contributing to 10x-cli source code, and general programming help."
+description: "Use when the user wants to download, use or update 10xDevs CLI skills, choose a helper installation channel, inspect course content, switch tool profiles or troubleshoot CLI/auth/content conflicts. Guides filtered get → an actual agent task → sync while preserving local work and course/tool/language context. For first installation or authentication preparation, use an available 10x-cli-setup copy. Does not implement CLI runtime or grant course access."
 ---
-# 10x-cli Daily Usage Guide
+# 10x-cli: download, use, update
-This skill helps users work with `@przeprogramowani/10x-cli` after it is already installed and authenticated. If the user has not installed or authenticated yet, hand off to the **10x-cli-setup** skill instead.
+Read the bundled [compatibility and channel reference](references/compatibility.md)
+before issuing commands. It contains the pinned runner setup, version checks, both
+helper channels and ownership safeguards. Commands use the released lesson-scoped
+skill filter; verify the actual selected package and content before using it. A local
+build or source membership is not proof that a feature has shipped.
-## Step 1: Detect the user's environment
+The next CLI release also provides project-only bundled installation through
+`10x helpers install --tool <chosen-profile>`. This command is **unreleased** and
+absent from the 1.21.0/1.22.0 master baselines: check the actual runner's
+`helpers --help` first. Follow **Bundled public copies** in the local reference
+for complete files, explicit targets and conflict handling; keep the existing
+pinned public route when the runner does not support it.
-Before giving any guidance, gather context silently — run these checks and remember the results. Do not print raw output to the user.
+## Environment
-### Operating system
+Reuse the setup handoff: project root, course, tool, language, runner/version,
+auth/access status, update method and helper channel/path. If anything is absent,
+inspect only that item. A working installed CLI needs no reinstall. If setup is
+needed, locate its actual SKILL.md and references or install that helper through
+the public channel; do not invoke a missing sibling by name.
-```bash
-echo "$OSTYPE" 2>/dev/null || echo "win32"
-```
-Use the result to tailor path separators, shell syntax, and clipboard commands throughout your answers:
+The guided acceptance context is macOS/zsh, Claude Code, 10xdevs4 and Polish.
+Determine the actual OS and shell from the environment, not a POSIX command that
+labels every failure Windows. Select the intended project root before any write.
+For v4, retain an existing v3 project and use a separate directory; ordinary get,
+sync and profile changes do not migrate editions. Preserve `.10x-cli.json` and
+all manifests if their versions/courses conflict.
-| OS | Shell | Home var | Clipboard | Temp dir |
-|----|-------|----------|-----------|----------|
-| macOS (`darwin*`) | zsh / bash | `$HOME` | `pbcopy` | `$TMPDIR` |
-| Linux (`linux-gnu*`) | bash / zsh | `$HOME` | `xclip -selection clipboard` or `xsel --clipboard` | `/tmp` |
-| Windows (`win32` / MSYS / Git Bash) | PowerShell / cmd | `%USERPROFILE%` | `clip.exe` | `%TEMP%` |
-### Active AI tool
+Use the verified `10x_cli` runner defined in the reference, or the user's exact
+verified global/standalone executable:
 ```bash
-10x doctor --json 2>/dev/null | head -1
+10x_cli --version
+10x_cli get --help
+10x_cli sync --help
+10x_cli auth --status
+10x_cli list --course 10xdevs4
 ```
-Also check which tool profile is configured:
+Check source/release evidence for lesson reference, skill filter and lesson-scoped sync, then use the
+filtered preview below to check the endpoint. Do not treat a successful help exit as
+capability proof. Keep unsupported CLI syntax, unpublished/missing content, locked
+module, membership denial and network failure distinct. Missing final release
+evidence need not block preparing the public helpers or the exercise files.
-```bash
-cat ~/.config/10x-cli/config.json 2>/dev/null || cat "$APPDATA/10x-cli/config.json" 2>/dev/null || echo "{}"
-```
+Read only needed nonsecret preferences from `config.json`. On macOS/Linux its
+base is nonempty `$XDG_CONFIG_HOME`, otherwise `~/.config`; on Windows it is
+`%APPDATA%`, otherwise the user's `AppData/Roaming`. Append `10x-cli/config.json`.
+Do not print `auth.json`, discard stderr, truncate doctor JSON or erase config to
+repair an unknown problem. An explicit course/tool/language in this journey takes
+precedence over saved defaults for that command.
-If the config contains a `"tool"` key, that is the active profile. If not, the default is `claude-code`.
+## Session management
-### CLI version
+When login is needed, let the user choose the delivery channel and complete it:
 ```bash
-10x --version
+10x_cli auth                  # Interactive: choose email or Circle
+10x_cli auth --method email   # Email magic link; default for piped/JSON output
+10x_cli auth --method circle  # One-time approval link delivered in Circle
+10x_cli auth --status
+10x_cli auth --logout
 ```
-## Step 2: Answer the user's question using the reference below
-Use the environment context from Step 1 to personalize every answer. Always use the OS-appropriate shell syntax, paths, and commands. Never show macOS-specific commands to a Windows user or vice versa.
----
-## Command Reference
+Circle is useful when the email does not arrive. The approval link expires after
+15 minutes; the CLI does not resend it automatically. In non-interactive mode,
+provide the user's email with `--email` and choose `--method circle` explicitly.
+Do not send a login message until the user requests authentication. Sessions
+refresh transparently; re-login is needed only when refresh cannot recover them.
-### `10x get <ref>` — Fetch and apply lesson artifacts
+## Download
-The primary daily command. Fetches a lesson bundle from the API and writes skills, prompts, rules, and config templates to the project directory.
+The launch exercise follows lesson 1, “Od pomysłu do PRD”, using its existing
+10xCards example. `10x-plan` is not part of this launch demonstration.
+After checking each name's capability and availability, download three separate
+complete selected skill trees. Inspect each dry-run before its corresponding write:
 ```bash
-10x get m1l1              # Fetch module 1, lesson 1
-10x get m2l3              # Fetch module 2, lesson 3
-10x get m1l1 --dry-run    # Preview what would be written
-10x get m1l1 --tool cursor  # Use a different AI tool profile
-10x get m1l1 --lang pl    # Fetch Polish content
+10x_cli get m1l1 --type skills --name 10x-init --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli get m1l1 --type skills --name 10x-init --course 10xdevs4 --tool claude-code --lang pl
+10x_cli get m1l1 --type skills --name 10x-shape --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli get m1l1 --type skills --name 10x-shape --course 10xdevs4 --tool claude-code --lang pl
+10x_cli get m1l1 --type skills --name 10x-prd --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli get m1l1 --type skills --name 10x-prd --course 10xdevs4 --tool claude-code --lang pl
 ```
-**Filtering artifacts:**
+Inspect each report and the complete supporting tree, not just SKILL.md. In the
+chosen macOS/zsh exercise directory, each of these checks must succeed before use
+(stop on any failure; do not infer success from the last check alone):
 ```bash
-10x get m1l1 --type skills                     # Only skills
-10x get m1l1 --type skills --name code-review  # One specific skill
-10x get m1l1 --print --type skills --name code-review  # Print to stdout
+test -s .claude/skills/10x-init/SKILL.md
+test -s .claude/skills/10x-shape/SKILL.md
+test -s .claude/skills/10x-shape/references/prd-schema.md
+test -s .claude/skills/10x-prd/SKILL.md
+test -s .claude/skills/10x-prd/../10x-shape/references/prd-schema.md
 ```
-**Where artifacts land** (depends on the active tool profile):
-| Tool | Skills | Prompts | Rules file | Config templates |
-|------|--------|---------|------------|------------------|
-| Claude Code | `.claude/skills/<name>/SKILL.md` | `.claude/prompts/<name>.md` | `CLAUDE.md` | `.claude/config-templates/<name>` |
-| Cursor | `.cursor/skills/<name>/SKILL.md` | `.cursor/prompts/<name>.md` | `.cursor/rules/10x-course.mdc` | `.cursor/config-templates/<name>` |
-| GitHub Copilot | `.github/skills/<name>/SKILL.md` | `.github/prompts/<name>.md` | `.github/copilot-instructions.md` | `.github/config-templates/<name>` |
-| Codex CLI | `.agents/skills/<name>/SKILL.md` | `.agents/prompts/<name>.md` | `AGENTS.md` | `.agents/config-templates/<name>` |
-| Devin Desktop | `.devin/skills/<name>/SKILL.md` | `.devin/prompts/<name>.md` | `AGENTS.md` | `.devin/config-templates/<name>` |
-| Generic | `.ai/skills/<name>/SKILL.md` | `.ai/prompts/<name>.md` | `AGENTS.md` | `.ai/config-templates/<name>` |
-**Re-applying a lesson** overwrites skills and prompts if content changed, updates the rules sentinel block, but never overwrites config templates (they may contain user edits).
-**Switching lessons** cleans up artifacts from the previous lesson that are not in the new one, keeps shared artifacts, and adds new ones.
-### `10x list [module]` — Browse available content
-```bash
-10x list       # Show all modules with lock state
-10x list m1    # Show lessons in module 1
-```
-Locked modules show their unlock date. Use this to see what is available before fetching.
-### `10x doctor` — Diagnose problems
-Runs 5 checks: Auth status, API connectivity, Config directory, CLI version, and tool directory presence.
+The PRD entrypoint resolves `../10x-shape/references/prd-schema.md` relative to its
+own directory. A standalone PRD tree is insufficient. Read all installed
+entrypoints and every reference they require; the paths above are the known
+source minimum, not permission to discard extra files from a published bundle.
+Also inspect `.claude/.10x-cli-manifest.json`: `lessons.m1l1.skills` must include
+all three names, with file hashes in `files.skills`. These are lesson-owned
+partial downloads, not independent owners. Inspect `.10x-cli.json` for the course
+binding; partial downloads do not establish a complete lesson release identity.
+CLI 1.21.0 is published with v4 and filtered skill downloads; production m1l1 EN/PL
+contains init/shape/prd and their references. These revised helpers are a separate
+source change, not proof that their course copies have been published.
+Verify all three names against the actual selected release. If any name, schema,
+owner or release is missing/mismatched, preserve the precise error and stop the
+exercise; never silently substitute a whole lesson, another course or filtered get.
+`CLAUDE-m1l1` is a separate lesson rule, not delivered by these filtered skill gets.
+The inspected init/shape/prd sources do not require that rule to run this chain.
+This does not establish that every step of the full lesson works without it.
+Use the learner's existing lesson 1 inputs and instructions: if they require the
+rule, inspect the existing project rule and its provenance. If absent, report the
+missing prerequisite and obtain the supported route from the lesson/release owner
+before that step. Do not invent a rule command or download a full lesson to bypass
+it. Do not overwrite an existing project rule.
+For browsing use `10x_cli list m1 --course 10xdevs4`. The commands above filter
+one lesson by skill name; `get 10x-init` is not supported. `--print` is inspection:
+TTY Markdown can contain only SKILL.md; non-TTY output is a JSON envelope. Never
+redirect print output into SKILL.md as a package installation.
+## Use: 10xCards, from idea to PRD
+Downloading the trees is only preparation. Use the existing 10xCards example and
+the learner's actual answers from lesson 1. If those inputs are absent, ask for
+them; do not invent product requirements, a replacement task.md or a ready-made
+plan. Keep private lesson text out of public fixtures and transcripts.
+Do not assume native slash/$ discovery or automatic activation from npm install.
+Give the agent explicit local paths and work through these steps separately:
+1. Read `.claude/skills/10x-init/SKILL.md` and follow it in the chosen project.
+   Inspect the create-if-absent context/changes, context/archive and
+   context/foundation directories and their READMEs. Preserve existing files.
+2. Read `.claude/skills/10x-shape/SKILL.md` and
+   `.claude/skills/10x-shape/references/prd-schema.md`. Follow the skill's discovery
+   with the learner's 10xCards inputs. Let the learner answer and approve the
+   checkpoint; do not answer for them. Inspect
+   `context/foundation/shape-notes.md` against those answers before proceeding.
+3. Read `.claude/skills/10x-prd/SKILL.md` and its sibling schema, then generate the
+   draft from the actual `context/foundation/shape-notes.md`. Inspect
+   `context/foundation/prd.md` against that input and the installed schema;
+   unresolved domain choices stay open. Respect the skill's existing-file
+   collision choice (a versioned file may be the appropriate result).
+Success requires the learner's notes and a schema-conformant PRD, with gaps
+explicit and original project work preserved. A transcript of downloads alone
+is insufficient. Stop after reviewing the PRD; do not chain into stack selection,
+bootstrap or implementation. If a different global/local skill copy was read,
+correct the path before accepting the result. Record the actual agent, profile,
+language, output paths and checks; use a fresh isolated exercise directory for the
+two canonical output filenames instead of forcing an overwrite.
+## Update
+Use the same runner, directory, course, tool and language. Sync updates entire
+downloaded lessons, including m1l1 after these filtered gets. Its preview may
+include other skills, prompts, configs and course rules. Inspect that expanded
+scope and apply only when the user accepts it; to update only one skill, repeat
+its filtered preview/get instead. Do not use sync as a hidden rule prerequisite
+workaround:
 ```bash
-10x doctor          # Human-readable output
-10x doctor --json   # Machine-readable for scripting
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl
 ```
-Exit code 78 means at least one check failed.
-### `10x auth` — Session management
-```bash
-10x auth             # Start magic-link login
-10x auth --status    # Check current session
-10x auth --logout    # Clear credentials
-```
-Sessions refresh transparently — if a token is near expiry, the next command refreshes it automatically. You only need to re-auth manually if the session has fully expired.
-### `10x bench` — 10xBench model leaderboard
-```bash
-10x bench             # Top 10 AI models with color-coded score bars
-10x bench --limit 5   # Just the top 5
-10x bench --json      # Machine-readable envelope (also when piped)
-```
-Shows the live leaderboard from [10xbench.ai](https://10xbench.ai) — AI models
-benchmarked on vibe-coding the Przeprogramowani.pl website. Each row has the
-average score, number of runs, cost per run where measured, and the agent
-harness used. **No authentication needed** — this works before `10x auth`.
-Data updates when new benchmark results are published; superseded model
-versions are already filtered out upstream. If it reports the leaderboard as
-unavailable, the site may be mid-deploy — retry in a few minutes.
----
-## Switching Tools
-To change your AI tool (e.g., from Claude Code to Cursor):
-```bash
-10x get m1l1 --tool cursor
-```
-The CLI will detect that artifacts from the old tool exist and offer two options:
-1. **Migrate** (default) — move all artifacts to the new tool's directories, remove the sentinel block from the old rules file.
-2. **Delete** — remove only 10x-managed artifacts from the old tool's directories. Your own files (e.g., `.github/workflows/`) are never touched.
-The tool choice is saved in the config file (`~/.config/10x-cli/config.json` on macOS/Linux, `%APPDATA%/10x-cli/config.json` on Windows). Future `get` commands will use the new tool without needing `--tool` again.
----
-## Platform-Specific Tips
-### Windows
-- **Use PowerShell** (not cmd.exe). The CLI outputs ANSI colors and Unicode symbols that render correctly in Windows Terminal + PowerShell but may garble in legacy cmd.
-- **npx works fine**: `npx @przeprogramowani/10x-cli get m1l1` — no global install needed. Node 20+ is the only prerequisite.
-- **Clipboard**: Skills that copy to clipboard use `clip.exe` on Windows. If a skill outputs a clipboard command, it will fall back silently if `clip.exe` is unavailable.
-- **Config location**: `%APPDATA%\10x-cli\config.json` and `%APPDATA%\10x-cli\auth.json`. The CLI creates these automatically.
-- **Path separators**: The CLI uses Node's `path.join()` internally, so forward slashes in command output (like `.claude/skills/code-review/SKILL.md`) work fine on Windows — no need to convert them.
-### Linux
-- **Clipboard**: Skills use `xclip -selection clipboard` or `xsel --clipboard`. If neither is installed, clipboard operations fail silently. Install with `sudo apt install xclip` (Debian/Ubuntu) or `sudo dnf install xclip` (Fedora).
-- **Config location**: `~/.config/10x-cli/` (respects `$XDG_CONFIG_HOME` if set).
-### macOS
-- **Clipboard**: Skills use `pbcopy` — works out of the box.
-- **Config location**: `~/.config/10x-cli/`.
----
-## Troubleshooting
-When the user reports a problem, follow this sequence:
-### 1. Run doctor first
-```bash
-10x doctor
-```
-This catches the most common issues. Read the output and address each failing check.
-### 2. Common problems and fixes
-| Symptom | Likely cause | Fix |
-|---------|-------------|-----|
-| "You're not signed in" | No auth or expired session | `10x auth` |
-| "Session expired" | Token past expiry and auto-refresh failed | `10x auth` (re-login) |
-| API unreachable / timeout | Network issue or API outage | Check internet; retry in a few minutes |
-| "Module is locked" | Content not yet released | `10x list` to see unlock date |
-| `.claude/` not found (doctor fail) | Running from wrong directory or wrong tool profile | `cd` to project root; check `10x doctor --json` for which tool is configured |
-| "403 Forbidden" on `10x get` | Module locked or no membership | Check `10x list` for module state; verify enrollment |
-| Orphaned artifact prompt on `get` | Switching tools mid-lesson | Choose "migrate" to move files, or "delete" to clean up |
-| Permission denied writing files | Directory not writable | Check directory permissions; on POSIX: `chmod u+w <dir>` |
-### 3. Verbose mode for deeper debugging
-```bash
-10x get m1l1 --verbose
-10x doctor --verbose
-```
-This prints request/response diagnostics to stderr, useful for diagnosing API or network issues.
-### 4. Nuclear reset
-If config is corrupted:
-On macOS/Linux:
-```bash
-rm -rf ~/.config/10x-cli
-10x auth
-```
-On Windows (PowerShell):
-```powershell
-Remove-Item -Recurse -Force "$env:APPDATA\10x-cli"
-10x auth
-```
-This clears auth and tool preference. The next `10x auth` recreates everything.
----
-## Important Principles
-- **Answer with the user's OS and tool in mind.** Never show `pbcopy` to a Windows user. Never show `%APPDATA%` to a macOS user.
-- **Run `10x doctor` before speculating.** It catches 80% of issues.
-- **Don't guess command syntax from memory.** If unsure about a flag or behavior, fetch the latest README: `https://raw.githubusercontent.com/przeprogramowani/10x-cli/refs/heads/master/README.md`
-- **Distinguish tool profile issues from CLI issues.** If artifacts land in the wrong directory, it is a tool profile question. If the command itself fails, it is a CLI/auth/network question.
+Normal sync refreshes the full lessons recorded in the manifest, not just the
+three selected skills. `--all` broadens scope to unlocked lessons and is not needed
+for this exercise. Missing managed files should be repaired; local edits should
+remain visible as conflicts or preserved files. Read all report outcomes and
+resource counts even if exit is 0: skipped conflicts alone are not process errors.
+Do not equate an unchanged remote digest with intact local files.
+For one conflicting skill, inspect the diff and back up local work before retrying
+its filtered get in an interactive terminal with the same course/tool/lang. Preserve
+the user's resolution choice. If a CLI hint omits context, restore these flags in
+your proposed command. Never run automatic `--force`; it can overwrite local
+skill/prompt edits and does not bypass protected rules or safe removal. Config
+templates remain create-only. Cleanup preserves modified/untracked files and
+files owned elsewhere; do not manually sweep a skill directory after sync.
+Three updates are independent: changing the npm/binary version updates the CLI;
+repeating pinned public `skills add` with a deliberately chosen new retained SHA
+updates a public helper; CLI sync updates CLI-owned course skills. It does not
+update the executable or public installer-owned helper copies.
+## Channels: both helpers are available through two routes
+The public on-demand route works before CLI/auth and installs one project helper
+at a selected source SHA. The CLI route uses authenticated filtered get once helper
+content is published and m1l1 is accessible. Follow the exact commands and guards
+in the reference for `10x-cli-setup` and `10x-cli-guide`; install only what is needed.
+Both routes deliver each helper's own `references/compatibility.md`.
+Use one owner per installed copy. Inspect destination paths/symlinks, CLI manifest
+and the public installer's project registration before writing. If a helper is
+already CLI-owned, use that copy and sync. For a public→CLI takeover, back up the
+whole helper and metadata outside managed trees, unregister only that helper using
+the original pinned installer's project/agent remove flow, verify registration and
+destination are absent, then filtered get. Merge local edits consciously from backup.
+If either owner remains, stop the takeover. CLI→public has no verified per-skill
+unregister contract: use a new isolated project instead of hand-editing manifests.
+## Profiles and troubleshooting
+Full skill trees land under the selected profile's `skills/<canonical-name>/`:
+| Profile | Tool directory | Rules file for full lesson delivery |
+|---|---|---|
+| claude-code | `.claude/` | `CLAUDE.md` |
+| cursor | `.cursor/` | `.cursor/rules/10x-course.mdc` |
+| copilot | `.github/` | `.github/copilot-instructions.md` |
+| codex | `.agents/` | `AGENTS.md` |
+| devin-desktop | `.devin/` | `AGENTS.md` |
+| gemini | `.gemini/` | `GEMINI.md` |
+| generic | `.ai/` | `AGENTS.md` |
+Profile changes may offer migrate, delete eligible managed files, or keep both;
+none means deleting arbitrary user content or switching the course edition.
+Legacy windsurf aliases and orphan handling should follow the selected version's
+help/output. These path mappings are not evidence of a completed Windows or
+other-agent walkthrough. Translate shell syntax to the user's actual shell.
+Run `10x_cli doctor --json` when diagnosis is useful; inspect its complete
+`data.overall` and `data.checks` as well as exit status. It checks the configured
+profile, not a `--tool` or `--course` argument. Before first get, a missing tool
+directory can be expected; explain only that failure and keep other failures
+visible. Doctor exit 78 can coexist with outer JSON `status: "ok"`.
+| Symptom | Next step |
+|---|---|
+| Missing/expired auth | Inspect auth status and live-access result; let the user complete login through setup. Login may send email. |
+| No email received | Offer `10x_cli auth --method circle`; let the user request the message. |
+| `circle_login_disabled` | Circle is unavailable; use `10x_cli auth --method email`. |
+| `dm_rejected` | Enable Circle direct messages or use email login. |
+| `circle_login_expired` | Ask for a fresh Circle login or use email; never auto-resend. |
+| Denied course access | Confirm selected course and membership; changing tool/reinstalling does not grant access. |
+| Locked or unpublished v4 | Inspect module availability/release evidence; do not bypass the gate or fall back to v3. |
+| Unsupported name/missing index | Verify exact CLI package and content release; preserve the error for the release owner. |
+| Network/API failure | Keep diagnostics, retry the same context when service returns; no config reset. |
+| Wrong directory/profile | Recheck cwd and explicit flags; a fresh project may legitimately have no tool directory. |
+| Signature/release mismatch | Preserve failure and source identity; do not disable verification or reuse unrelated bytes. |
+| Edition/manifest conflict | Preserve binding and manifests for repair; use a separate v4 project rather than deleting them. |
+| File conflict or permission failure | Inspect affected paths and local edits, retain backup and resolve the specific issue. No broad chmod/reset/force. |
+Use `--verbose` only when needed, and redact credentials before sharing diagnostics.
+For unrelated day-to-day commands such as `bench`, inspect this runner's matching
+help; do not fetch arbitrary master README as an authority for an older binary.