@przeprogramowani/10x-cli 1.20.0 → 1.22.0

package/README.md

@@ -21,42 +21,145 @@ 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
-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 |
 |---------|-------------|
 | `10x auth` | Magic-link login with your Circle-registered email |
+| `10x auth --method circle` | No email received? Get the approval link as a Circle message instead |
 | `10x list` | Browse modules and lessons in your course |
 | `10x get <ref>` | Fetch a lesson and apply artifacts to your workspace |
 | `10x sync` | Bulk-download / refresh lessons and report what changed upstream |
@@ -73,8 +176,8 @@ Once installed, just tell your agent to **set up 10x-cli** and it will pick up t
 | `--type <type>` | Filter by artifact type: `skills`, `prompts`, `rules`, `configs` |
 | `--name <name>` | Filter by artifact name (requires `--type`) |
 | `--dry-run` | Show what would be written without touching the filesystem |
-| `--course <slug>` | Override the course slug (default: `10xdevs3`) |
-| `--no-course-rules` | Skip the course rules block in your rules file (`CLAUDE.md`/`AGENTS.md`); strips an existing one. Use `--course-rules` to re-enable. |
+| `--course <slug>` | Select an entitled course ID or slug; default is the project edition or API recommendation |
+| `--no-course-rules` | Skip the course rules block in your rules file (`CLAUDE.md`/`AGENTS.md`); removes an unchanged block whose ownership and baseline are known. Use `--course-rules` to re-enable. |
 
 #### Examples
 
@@ -96,7 +199,7 @@ Once installed, just tell your agent to **set up 10x-cli** and it will pick up t
 10x get m1l1 --tool cursor
 
 # Skip the course rules block (use only your rules). Persisted across runs;
-# a previously-applied block is stripped. Re-enable later with --course-rules.
+# an unchanged block with a known baseline is removed. Re-enable later with --course-rules.
 10x get m1l1 --no-course-rules
 10x get m1l2 --course-rules
 
@@ -117,17 +220,17 @@ already downloaded; `--all` pulls every unlocked lesson at once.
 
 Unchanged lessons are skipped **without a download** — the catalog advertises a
 per-lesson `contentHash` that the CLI compares against what it last applied, so the
-common "nothing changed" case is a single catalog request.
+common "nothing changed" case avoids lesson downloads. Skipping also requires the same language/tool/rules representation and intact tracked local files; missing files are repaired and local edits still surface as conflicts.
 
 | Flag | Description |
 |------|-------------|
 | `--all` | Sync every unlocked lesson, not just the ones you've downloaded |
 | `--module <m>` | Limit to one module (e.g. `m2` or `2`) |
 | `--dry-run` | Preview what would change without writing anything |
-| `--force` | Ignore the cheap-skip digest and overwrite local edits with upstream |
+| `--force` | Fetch again and overwrite local skill/prompt edits; protected rules and config templates remain guarded |
 | `--tool <tool>` | AI coding tool (same set as `get`) |
 | `--lang <lang>` | Content language: `en` (default) or `pl` |
-| `--course <slug>` | Override the course slug (default: `10xdevs3`) |
+| `--course <slug>` | Select an entitled course ID or slug; default is the project edition or API recommendation |
 | `--no-course-rules` | Skip the course rules block (same semantics as `get`) |
 
 ```bash
@@ -158,9 +261,7 @@ m2l3 — conflicts (1 skipped)
 ```
 
 Run that `10x get …` to take a single update, or `10x sync --force` to take them
-all. **Change visibility covers skills and prompts** — configs are create-only
-(never overwritten) and rules are sentinel-managed, so they aren't part of the
-"what changed" report.
+all for skills and prompts. Config templates are create-only. Course rules retain a separate upstream baseline: local edits or a missing baseline require explicit resolution, including when `--force` or `--no-course-rules` is used. Text outside the managed markers is preserved.
 
 **Exit code is worst-outcome:** `0` when everything is clean/unchanged (a skipped
 conflict is reported, not a failure), `1` if any lesson failed to fetch. The full
@@ -243,7 +344,7 @@ On first run, the CLI prompts you to choose your AI coding tool. Artifacts are w
 | Gemini CLI | `.gemini/` | `GEMINI.md` |
 | Generic | `.ai/` | `AGENTS.md` |
 
-Override anytime with `--tool <name>`. Your choice is saved in `~/.config/10x-cli/config.json`.
+Override with `--tool <name>`. Validated writing commands save your choice in `~/.config/10x-cli/config.json`. Previews leave it unchanged.
 The former `windsurf` ID remains accepted as an alias and is upgraded to
 `devin-desktop`; existing `.windsurf/` artifacts can be migrated by the normal
 tool-switch prompt.
@@ -272,3 +373,46 @@ CI runs lint, typecheck, tests, and build checks on every PR. Releases are autom
 ## License
 
 MIT
+
+## Course selection and project edition
+
+`get`, `list`, and `sync` select the explicit `--course` first, then the project's edition, then the live API recommendation. A new project with only v3 access selects v3, with only v4 selects v4, and with both selects published, available v4. An unpublished v4 can leave v3 as the recommendation; network or backend failures are reported instead of falling back. Output includes the course and selection reason.
+
+The first validated write records `{ "version": 1, "course": "10xdevs4" }` (or `10xdevs3`) in the root `.10x-cli.json`, shared across AI tool profiles. Existing supported v2/v3 manifests preserve their recorded edition. All profiles, including legacy Windsurf, must agree. Corrupt, unknown-version, or conflicting manifests block writes and must be preserved for repair. Artifact names never infer an edition.
+
+Ordinary `get` and `sync` cannot change a bound project's edition. Start v4 in a separate directory while retaining the v3 project. Read-only inspection of another entitled edition is allowed with `--course`. Do not delete the binding or manifests to bypass an edition conflict. Course edition and manifest schema version are separate concepts.
+
+`list`, `get --print`, `get --dry-run`, `sync --dry-run`, and `doctor` preserve project files and tool/language preferences, including interactive tool choices. Auth token rotation may update only the credential store. Failed download, signature, course, or path validation leaves a new project unbound. Once writing starts, its binding remains even if an I/O operation fails, so retry stays on the same edition. `auth --status` and `doctor` distinguish token expiry from live course access.
+
+
+## Candidate verification and v4 release
+
+Using v4 requires a CLI version with course discovery and project edition binding.
+Existing v3 projects remain usable without a new flag or an edition migration.
+Start v4 in a separate project directory; this release includes no edition migration
+command. Support files inside each skill directory are downloaded together with
+`SKILL.md`, including selector and stack-assessment references.
+
+Before publication, CI tests the exact CLI and Toolkit candidate commits together
+on Linux and Windows using real local auth callback, polling and token refresh.
+It also exercises the actual released npm 1.20.0 CLI against the candidate API and
+this candidate against existing v2/v3-manifest projects. Automated fixtures send no
+emails. npm latest or a different branch cannot stand in for the candidate binary.
+
+The private Toolkit release runbook `docs/how-to/release-10xdevs4-cli.md` documents
+the required full candidate SHA pair, vetted v3 fixture artifact, exact v4 stage
+and secured preparation Worker/content revisions. Publication depends on the
+coordinated gate plus normal Linux/Windows tests, builds and smoke checks. The
+operator must still verify secured production access and final v4 content before
+npm publication; passing a local test does not execute that rollout.
+
+For deterministic contract checks, export `/openapi.json` from the exact local
+candidate Worker, then run:
+
+```bash
+OPENAPI_SPEC_PATH=/absolute/candidate-openapi.json bun run generate-types --check
+```
+
+Check mode reads that file and compares the generated result without changing
+`src/generated/api-types.ts`. To regenerate, omit `--check` while keeping the same
+source file. Do not regenerate candidate contracts from the production API.