@przeprogramowani/10x-cli 1.19.1 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@przeprogramowani/10x-cli",
-  "version": "1.19.1",
+  "version": "1.21.0",
   "description": "Open-source CLI for 10xDevs course content",
   "repository": {
     "type": "git",

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

@@ -81,11 +81,12 @@ The primary daily command. Fetches a lesson bundle from the API and writes skill
 | 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).
+**Re-applying a lesson** updates clean managed files and preserves local edits unless explicitly resolved. Config templates are create-only. Course rules with local edits or an unknown baseline require explicit resolution, even with `--force` or when opting out. Text outside the managed markers stays intact.
 
-**Switching lessons** cleans up artifacts from the previous lesson that are not in the new one, keeps shared artifacts, and adds new ones.
+**Switching lessons** accumulates downloaded artifacts. Cleanup is scoped to the lesson being updated and removes only unchanged files with known hashes and no remaining owner. User files, modified files and files without a baseline are preserved.
 
 ### `10x list [module]` — Browse available content
 
@@ -110,11 +111,15 @@ 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
+10x auth                    # Interactive: choose email magic link or Circle message
+10x auth --method email     # Magic-link login (default when piped / --json)
+10x auth --method circle    # Approval link sent as a Circle message — use when no email arrives
+10x auth --status           # Check current session (shows the login method when known)
+10x auth --logout           # Clear credentials
 ```
 
+`--method circle` sends a direct message in Circle with a one-time approval link; open it in Circle on any device and the terminal signs in within a few seconds. The link expires after 15 minutes and the CLI never resends it by itself — run the command again for a fresh message, or fall back to `--method email`. In non-interactive mode (`--json` or piped output) pass `--email` and an explicit `--method circle`; the CLI never prompts there.
+
 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
@@ -143,10 +148,13 @@ To change your AI tool (e.g., from Claude Code to Cursor):
 10x get m1l1 --tool cursor
 ```
 
-The CLI will detect that artifacts from the old tool exist and offer two options:
+The CLI will detect that artifacts from the old tool exist and offer three options:
+
+1. **Migrate** (default) — transfer eligible managed files to the new profile, preserving modified or conflicting source files and their ownership.
+2. **Delete** — remove only unchanged managed files with known hashes and no other owner; preserve user files and edits.
+3. **Keep both** — retain the existing profile and dismiss its repeated orphan prompt.
 
-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.
+Tool switching cannot change a project's course edition. If profiles disagree about the course or a manifest is corrupt, preserve the files and resolve that conflict before writing.
 
 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.
 
@@ -192,6 +200,10 @@ This catches the most common issues. Read the output and address each failing ch
 |---------|-------------|-----|
 | "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) |
+| No email received after `10x auth` | Magic link filtered or delayed | `10x auth --method circle` — approval link arrives as a Circle message |
+| "Circle login is currently unavailable" (`circle_login_disabled`) | Circle channel switched off server-side | `10x auth --method email` |
+| "Circle refused to deliver the login message" (`dm_rejected`) | Direct messages disabled in Circle settings | Enable DMs in Circle, or `10x auth --method email` |
+| "The Circle login expired" (`circle_login_expired`) | Approval link not opened within 15 minutes | `10x auth --method circle` again, or `10x auth --method email` |
 | 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 |
@@ -234,3 +246,28 @@ This clears auth and tool preference. The next `10x auth` recreates everything.
 - **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.
+
+## 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.
+
+
+## v3 compatibility and v4 rollout
+
+Upgrade the CLI to use v4 capabilities. Existing v3 users can continue `auth`,
+`list`, `get` and `sync` without compulsory course flags or project migration.
+A new v4 purchase does not switch a bound v3 project; create a separate directory
+for v4. Complete skill directories are installed, including references and scripts;
+`--print` in human mode shows only `SKILL.md` and explains how to download the rest.
+
+The first v4 delivery release does not include a course-edition migration command.
+Do not recommend deleting a binding or manifest to force another edition. Warnings
+about using old binaries on edition-migrated projects belong to the later migration
+release. If v4 is unavailable, distinguish its publication/unlock state from course
+membership; do not claim that reinstalling or changing a tool grants access.