@przeprogramowani/10x-cli 1.21.0 → 1.22.0

package/README.md

@@ -21,37 +21,139 @@ npm install -g @przeprogramowani/10x-cli
 # https://github.com/przeprogramowani/10x-cli/releases
 ```
 
+## Install the bundled CLI helpers (unreleased)
+
+`10x helpers install` is implemented on this branch for the next CLI release;
+it is **not available in 1.21.0 or the 1.22.0 master baseline**. A checkout build
+may still print 1.22.0 until the release process assigns a version. Check
+`10x helpers --help` on your actual executable before using this command; do not
+assume that installing today's npm version includes it.
+
+Once your release includes it, run from the intended project directory:
+
+```bash
+10x helpers install --tool copilot --dry-run
+10x helpers install --tool copilot
+```
+
+This installs **both** `10x-cli-setup` and `10x-cli-guide`, each with its complete
+`SKILL.md` and `references/compatibility.md`, into `.github/skills/`. Use
+`--tool claude-code`, `cursor`, `codex`, `devin-desktop`, `gemini`, or `generic`
+when that is your intended tool. The target must be explicit; installation is
+project-only. There is no `--global`, automatic agent detection, `skills`/npx
+subprocess, authentication, or network access. The helper bytes come from the
+same CLI build, including the standalone binary; fetching the npm CLI itself
+still requires npm/network in the usual way.
+
+Identical existing files are unchanged; missing files are created. If any existing
+helper file differs, neither helper is written and the command exits 1. Keep the
+existing copy or back up your changes outside managed skill directories before
+replacing it deliberately. Files managed by course `10x get`/`sync` remain under
+that channel; this command does not register or take over a course manifest.
+It never deletes extra local files. A filesystem failure also exits 1; any files
+already created remain, and rerunning safely checks them again. `--dry-run`
+performs the same path/conflict checks without writes. Invalid/missing targets or
+unsupported flags exit 2 in both human and JSON use.
+
+For Copilot CLI, run `/skills reload`, then `/skills info 10x-cli-setup` and
+`/skills info 10x-cli-guide` in the same project. Installing helpers does not
+execute them or authenticate the course CLI. VS Code Copilot also reads project
+`.github/skills`; open the same project there.
+
+To try the **unreleased source checkout** without changing a global installation:
+run `bun run /absolute/path/to/10x-cli/src/index.ts helpers install --tool copilot`
+from a disposable project, with dependencies already installed in the checkout.
+The public `skills` route below remains available for older CLI releases. Its
+Copilot agent ID is `github-copilot`, whereas this CLI uses `--tool copilot`.
+
 ## Agentic Installation
 
-Let your AI coding agent handle the setup. This repo ships a [`10x-cli-setup`](skills/10x-cli-setup/SKILL.md) skill that walks your agent through installing, authenticating, and configuring the CLI — all driven by the latest README.
+The [`10x-cli-setup`](skills/10x-cli-setup/SKILL.md) helper prepares the CLI and
+passes project context to [`10x-cli-guide`](skills/10x-cli-guide/SKILL.md), which
+leads through download → an actual agent task → sync. Each ships its own
+[compatibility reference](skills/10x-cli-guide/references/compatibility.md).
+Installing the npm CLI does not activate these helpers in your agent.
 
-Install the skill with [skills.sh](https://skills.sh):
+For public installation on demand, choose a full retained public CLI master SHA
+containing the helper version you want. From your project root (macOS/zsh):
 
 ```bash
-# Add the skill to your current project (symlinked)
-npx skills add przeprogramowani/10x-cli
+: "${CLI_SKILLS_REF:?Set the full public CLI master SHA containing the helpers}"
+npx --yes skills@1.5.26 add "https://github.com/przeprogramowani/10x-cli/tree/$CLI_SKILLS_REF/skills" --skill 10x-cli-setup --agent claude-code --copy
+# Install guide when needed using the same channel:
+npx --yes skills@1.5.26 add "https://github.com/przeprogramowani/10x-cli/tree/$CLI_SKILLS_REF/skills" --skill 10x-cli-guide --agent claude-code --copy
+```
+
+These are project copies. Installer prompts remain enabled; `npx --yes` only
+accepts running the pinned tool. Inspect the actual installed paths and ask the
+agent to read that SKILL.md and its references. No automatic discovery is assumed.
 
-# Or install globally so it's available in every project
-npx skills add przeprogramowani/10x-cli -g
+Both helpers can also be downloaded through the CLI once filtered get is supported
+by your verified release and v4 m1l1 content is published and accessible. In a
+separate project from public copies, after setup/auth:
 
-# Target a specific agent
-npx skills add przeprogramowani/10x-cli -a claude-code
-npx skills add przeprogramowani/10x-cli -a cursor
+```bash
+: "${CLI_VERSION:?Set the actual verified published CLI version}"
+10x_cli() { npx --yes "@przeprogramowani/10x-cli@$CLI_VERSION" "$@"; }
+10x_cli --version
+10x_cli get --help
+10x_cli get m1l1 --type skills --name 10x-cli-setup --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli get m1l1 --type skills --name 10x-cli-setup --course 10xdevs4 --tool claude-code --lang pl
+10x_cli get m1l1 --type skills --name 10x-cli-guide --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli get m1l1 --type skills --name 10x-cli-guide --course 10xdevs4 --tool claude-code --lang pl
 ```
 
-Once installed, just tell your agent to **set up 10x-cli** and it will pick up the skill automatically.
+Source membership does not prove publication. Confirm skill-filter support and direct
+sync against the actual package and content; do not infer it from a version label
+or silently replace the name with a full lesson. CLI-owned copies update through
+sync; public copies update through a deliberate new source SHA and pinned add.
+The CLI executable has its own npm/binary update procedure.
+
+Keep one updater per copy. Before either route, inspect destination paths/symlinks
+and CLI/installer ownership. For public→CLI takeover, back up the whole helper
+outside managed trees, unregister only that helper through the original installer,
+verify its destination and registration are gone, then filtered get. Preserve local
+edits for conscious merging. For CLI→public use a new project; no verified CLI
+per-skill unregister is promised. See the compatibility reference for details.
 
 ## Quick Start
 
+Use an existing verified global/standalone `10x`, or the pinned `10x_cli` runner
+above. Retain your v3 project and use a separate v4 exercise directory. After
+checking skill-filter capability and content availability. Sync later refreshes
+whole downloaded lessons, so inspect its preview and accept any additional
+artifacts/rules before applying; repeat a skill filter for a narrow update:
+
 ```bash
-10x auth        # Authenticate with your email (magic link or Circle message)
-10x list        # Browse available modules and lessons
-10x get m1l1    # Fetch and apply lesson artifacts
-10x sync        # Update everything you've downloaded; show what changed
-10x doctor      # Check everything is working
-10x bench       # Show the 10xBench top-10 model leaderboard
+10x_cli auth --status
+# If login is needed: 10x_cli auth (email or Circle); see auth commands below.
+10x_cli list --course 10xdevs4
+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
+# Follow the guide: read each installed SKILL.md and references, then
+# init → shape with the learner’s 10xCards inputs → PRD from approved notes.
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl
+10x_cli doctor
 ```
 
+The guide uses lesson 1's existing 10xCards example and produces
+`context/foundation/shape-notes.md`, then `context/foundation/prd.md`.
+Read all three installed skill trees; PRD requires the sibling
+`.claude/skills/10x-shape/references/prd-schema.md`. Preserve existing outputs and
+follow the skills' collision choices. `CLAUDE-m1l1` is a separate lesson rule;
+see the guide for prerequisite checks without a full-get fallback. `10x-plan`
+is not available for this launch demonstration. CLI 1.21.0 and v4 m1 EN/PL are
+published; these revised helpers remain a separate source change. Verify each
+filtered preview and complete PL references before the walkthrough. A download alone is not successful skill use.
+Inspect sync conflicts even on exit 0; never apply automatic `--force`. A missing
+tool directory before first get can explain that doctor check; other failures
+remain visible. Full lesson downloads and other commands remain available below.
+
 ## Commands
 
 | Command | Description |