@przeprogramowani/10x-cli 1.21.0 → 1.22.1

package/dist/index.mjs

@@ -3183,7 +3183,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "@przeprogramowani/10x-cli",
-  version: "1.21.0",
+  version: "1.22.1",
   description: "Open-source CLI for 10xDevs course content",
   repository: {
     type: "git",
@@ -3210,7 +3210,8 @@ var package_default = {
     "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",
@@ -7438,6 +7439,1130 @@ function renderGetResult(ctx, bundle, writeResult, dryRun, profile, langMeta = {
 `), undefined);
 }
 
+// src/commands/helpers.ts
+import { existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname6, join as join11, resolve as resolve3 } from "node:path";
+
+// skills/10x-cli-setup/SKILL.md
+var SKILL_default = `---
+name: 10x-cli-setup
+description: "Set up or troubleshoot @przeprogramowani/10x-cli for a 10xDevs learner: reuse or install a compatible CLI, check authentication and course access, choose the project and AI tool, and hand off to 10x-cli-guide. Use for installation, updates, npm permissions and onboarding. Excludes CLI source development and everyday download/use/sync guidance once setup is ready."
+---
+
+# 10x-cli Setup
+
+Prepare the user's CLI and project, then pass the working context to guide. Read
+[the compatibility reference](references/compatibility.md) before choosing a
+version, installing a helper, or running a course command. Use the actual runner's
+help and its matching published source; a moving master README does not establish
+what the installed CLI supports.
+
+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.
+
+## 1. Establish the project and existing installation
+
+Use the user's request and existing session context. Identify the intended project
+directory, shell and AI tool before writing files. For the guided 10xDevs4 exercise
+the context is macOS/zsh, \`10xdevs4\`, \`claude-code\`, \`pl\`; do not silently apply it
+to a v3 project or a user who selected another profile.
+
+In a POSIX shell, inspect the runner without hiding failures:
+
+\`\`\`bash
+pwd
+command -v 10x
+\`\`\`
+
+If found, run \`10x --version\` and its \`--help\`, \`get --help\`, \`sync --help\` and
+\`auth --help\`. Record the executable path and installation method. An existing
+working installation needs no reinstall or fresh login. If an executable exists
+but fails, preserve the error and diagnose its runtime/PATH/permissions; this is
+different from a missing command. On other systems use their shell's executable
+lookup, not a POSIX detection snippet.
+
+Inspect the project's \`.10x-cli.json\` and existing profile manifests as local
+metadata, without editing them. The course binding is shared across profiles;
+changing \`--tool\` cannot switch v3 to v4. For a v4 exercise with a bound v3 project,
+use a separate directory and retain the v3 project. Preserve corrupt, unknown or
+conflicting bindings/manifests for diagnosis; do not delete them to force access.
+
+## 2. Select a compatible runner, then install only if needed
+
+Follow **Version and capability check** in the local reference. Record the actual
+package version, source revision and supported syntax. The released syntax is
+\`get m1l1 --type skills --name NAME\`; the positional argument is a lesson reference,
+not a skill name. Verify the corresponding lesson and skill in the content.
+Neither a local build nor a higher version number proves both. If skill-filter support
+is unavailable, continue preparing the project and public helpers, and report the
+specific pending capability before download. Do not substitute a full lesson or
+another course without the user's choice.
+
+For npm/npx verify Node against that package's \`engines\` (the inspected baseline
+requires Node 20+). When there is no suitable global CLI, the pinned npx runner in
+the reference avoids a global install. Respect a user's requested global or
+standalone method; use its matching install/update procedure. Carry forward
+existing authorization for installation. A permissions error is not a reason for
+automatic \`sudo\`, a global config reset or deleting credentials.
+
+Re-run version/help after an install or update. Keep one exact runner throughout
+setup and guide so an older \`10x\` on PATH cannot replace the verified npx version.
+With no network, inspect available local version/help and matching packaged
+documentation; leave publication, access and download checks unverified. Do not
+claim setup is complete from an offline version check.
+
+## 3. Check authentication separately from course availability
+
+Run the selected runner's \`auth --status\`. It can contact the course API but does
+not request a login email. Inspect both session validity and live access status:
+a valid token or successful exit does not prove \`access_checked\` or v4 access.
+Keep the error when access could not be checked.
+
+Only when login is required, have the user run the verified \`auth\` command in an
+interactive terminal and complete its displayed flow. The inspected version uses
+a magic link sent by email or a Circle message (\`--method email\` /
+\`--method circle\`); follow the selected release's help. Do not request email, open magic links or perform login
+on the user's behalf without their authorization. Never read out \`auth.json\`,
+tokens, magic-link URLs or email contents. Summarize only session/access state.
+
+Then use the selected runner's \`list --course 10xdevs4\` (or the user's explicit
+course). Distinguish no membership, unpublished course, locked module and network
+failure. Reinstalling the CLI or selecting a different tool does not grant access.
+Keep \`--course\`, \`--tool\` and \`--lang\` explicit in subsequent download/sync commands.
+
+## 4. Diagnose readiness without manufacturing a tool directory
+
+Run the selected runner's \`doctor --json\`; read all of \`data.checks\` and
+\`data.overall\`, plus the exit status. The outer \`status: "ok"\` is an output envelope,
+not a promise that every check passed. Doctor uses the configured profile (or its
+default), so compare the reported tool with the intended one; it has no \`--tool\`
+flag in the inspected baseline.
+
+In a new project before the first download, a missing \`.claude/\` (or the reported
+profile directory) can be expected. If that is the only failure and this is the
+correct writable project, explain that the first successful download creates it.
+Do not create a dummy directory just to turn the check green. Preserve and address
+any auth, access, API, binding or write-permission failure separately. An update
+lookup skipped offline does not establish that the CLI is current.
+
+## 5. Hand off to the actual guide copy
+
+Locate the project's installed \`10x-cli-guide/SKILL.md\` and its own
+\`references/compatibility.md\`. Check its installation channel/owner using the
+reference before adding or updating it. If absent, install guide through the
+chosen public on-demand or compatible CLI channel; verify the resulting files.
+Installing the npm CLI alone does not activate either helper in an agent. Do not
+claim that an absent guide is available or rely on unverified slash-command
+discovery. Tell the agent to read the exact materialized guide path and its local
+reference.
+
+Pass this compact context in the conversation, without secrets:
+
+\`\`\`text
+Project: absolute cwd; course binding or unbound
+Course / tool / requested language: 10xdevs4 / claude-code / pl (or user's choice)
+Runner: exact executable or pinned npx command; observed version and source ref
+CLI install/update method: npx pin / npm global / standalone asset
+Auth: valid / login required / unknown; live course access and module state
+Setup helper: actual path, public or CLI owner, observed source ref if known
+Guide helper: actual path, owner and source ref if known; full reference present
+Readiness: verified checks; remaining release/network/access issues, if any
+Next task: guide's lesson setup (idea-check/init/shape/prd) → use → sync journey, or the user's narrower request
+\`\`\`
+
+For lesson 1 setup, carry forward all four skills in the handoff:
+\`10x-idea-check\`, \`10x-init\`, \`10x-shape\` and \`10x-prd\`, with their references.
+Idea assessment is optional to run, not a reason to omit its files during lesson
+setup. A request for one specific skill remains a narrower download. Verify
+materialized files separately from native slash-command discovery.
+
+Once ready, continue in guide without rerunning installation or asking the user
+to repeat choices already supplied. Report remaining blockers precisely if the
+download cannot yet run; do not present preparation as a completed real journey.
+`;
+
+// skills/10x-cli-setup/references/compatibility.md
+var compatibility_default = `# CLI compatibility, channels and command context
+
+This reference is packaged inside each helper. Both copies must have identical
+bytes in the authoring repository. It defines the guided filtered-download contract;
+verify the selected published CLI and live content before executing that path.
+
+## Version and capability check
+
+Record four independent identities: CLI runner/version, CLI package source,
+public helper source revision, and the course content release. Updating one does
+not automatically update the others.
+
+| Evidence | What it establishes | What it does not establish |
+|---|---|---|
+| Actual executable \`--version\`, command help | The runner and syntax in use | Working API, entitlement or a published helper revision |
+| npm version, \`dist.integrity\`, \`gitHead\`, matching packaged README/source | Origin of that published package | Publication of changes on a development branch |
+| Full helper commit retained on public CLI master | Reproducible public helper source | Installation in this project or course publication |
+| Successful named download and complete local tree/manifest | Actual package/API/content behavior for this context | A successful agent task or another profile/language |
+
+The earlier planning shorthand \`get SKILL_NAME\` was incorrect. Released CLI
+uses a lesson reference plus \`--type skills --name NAME\`; there is no standalone
+skill-name positional command or independent skill-owner sync contract. On 2026-09-14, CLI \`1.21.0\` was published with v4, filtered skill downloads
+and Circle login; production m1 EN/PL and sync were verified. Its npm \`gitHead\`
+is \`2cc510fe690ba820937602d702564985087ded46\`. These revised helpers have their
+own source/content identity and are not implied by installing CLI 1.21.0. A local
+source build can carry an old version label; do not identify features from that
+label alone.
+
+For a known installed version, read its npm metadata (replace the shell variable
+with the observed version) and use the matching source revision for documentation:
+
+\`\`\`bash
+: "\${CLI_VERSION:?Set the actual published CLI version}"
+npm view "@przeprogramowani/10x-cli@$CLI_VERSION" version engines gitHead dist.integrity dist.tarball --json
+\`\`\`
+
+Use that exact package's README or
+\`https://raw.githubusercontent.com/przeprogramowani/10x-cli/<gitHead>/README.md\`,
+with the real \`gitHead\` substituted. For a standalone binary, use its actual
+release tag/asset, published verification information and matching source. Do not
+invent a source SHA if metadata is absent. The installed help wins for supported
+flags; a help/README mismatch must remain visible and be checked against matching
+source, not resolved by fetching arbitrary master instructions.
+
+Before the filtered-download journey, verify \`get --help\` and matching source/release evidence
+for \`get m1l1 --type skills --name NAME\` and lesson-scoped sync. A successful \`--help\` exit alone does
+not prove skill-filter support. If support or release evidence is missing, prepare the
+public helpers and handoff, but pause filtered commands with a precise explanation.
+Once supported, a filtered dry-run verifies the actual API/content selection before
+writing. Report unsupported reference, missing skill/index, locked module, denied
+access and network errors separately; do not silently use a lesson or v3 instead.
+
+## Keep one runner and one project context
+
+The examples below use a pinned npx runner in macOS/zsh or another POSIX shell.
+Set \`CLI_VERSION\` from verified release evidence, then use this function in that
+shell session. If the user's existing verified global/standalone \`10x\` works,
+substitute its exact executable for \`10x_cli\`; no reinstall is required.
+
+\`\`\`bash
+: "\${CLI_VERSION:?Set the actual published CLI version}"
+10x_cli() { npx --yes "@przeprogramowani/10x-cli@$CLI_VERSION" "$@"; }
+10x_cli --version
+10x_cli --help
+10x_cli get --help
+10x_cli sync --help
+10x_cli auth --help
+10x_cli auth --status
+10x_cli list --course 10xdevs4
+\`\`\`
+
+Run commands from the intended project root. The target guided context is
+\`--course 10xdevs4 --tool claude-code --lang pl\`; preserve it in downloads,
+previews, updates and recovery. \`list\` takes \`--course\`, not tool/lang flags.
+Use another context only when the user chose it. Record any language fallback
+reported by the CLI rather than calling English output Polish.
+
+The project edition is stored in \`.10x-cli.json\` after a validated write and shared
+across profiles; existing supported manifests also carry edition information.
+Course selection is explicit flag → project edition → live API recommendation.
+An explicit course does not authorize changing a bound project's edition. Retain
+the v3 project and start a separate v4 directory for this journey. Preserve unknown,
+corrupt or conflicting manifests; never delete a binding to force migration.
+
+Verified releases with the project-binding safeguards preserve project files and
+tool/language preferences during \`list\`, \`get --print\`, \`get --dry-run\`,
+\`sync --dry-run\` and \`doctor\`. Auth token refresh can still update the credential
+store. Verify the selected release's contract before describing a preview as
+read-only; do not generalize older source bugs to the target release.
+
+## Two helper channels, one owner per installed copy
+
+The public authoring source is \`przeprogramowani/10x-cli\`, under
+\`skills/10x-cli-setup/\` and \`skills/10x-cli-guide/\`. Toolkit distributes controlled
+copies through course content. Each helper includes \`SKILL.md\` and its own
+\`references/compatibility.md\`; neither may rely on an installed sibling helper.
+
+Before either installer writes, inspect the destination directory, its path
+components/symlink targets, the tool's \`.10x-cli-manifest.json\`, and the skills
+installer's project registration/lock. Do not infer ownership solely from a
+directory name. If ownership is mixed or unknown, preserve local files and
+resolve it before writing; use a separate project to try the other channel.
+
+### Bundled public copies (unreleased command)
+
+The next CLI release adds \`10x helpers install --tool copilot\` (use the user's
+chosen profile). This command is absent from the 1.21.0 and 1.22.0 master
+baselines. Verify \`10x helpers --help\` on the actual runner; a source build may
+still report the baseline version. Do not claim npm availability from this text.
+
+When supported, run from the intended project:
+
+\`\`\`bash
+10x helpers install --tool copilot --dry-run
+10x helpers install --tool copilot
+\`\`\`
+
+Both helpers and their own compatibility references are embedded in the same npm
+bundle/standalone executable. No auth, network, external skills installer or
+global installation is involved. \`--tool\` is required; Copilot writes to
+\`.github/skills/\`, Claude Code to \`.claude/skills/\`, and other profiles follow the
+CLI profile table. Do not carry \`--agent github-copilot\` from the external
+installer into this command.
+
+Existing identical files are unchanged; missing files are created. Any differing
+helper file blocks the entire preflight with exit 1, preserving both helpers and
+local extras. Never remove a user's files merely to make a retry pass. Keep an
+existing copy, or let the user deliberately back it up outside managed trees
+before replacement. Course-owned copies stay with get/sync; this command writes
+no course manifest or binding. Filesystem errors also exit 1 and report that
+already created files remain; unsupported options/targets exit 2. Preview uses
+the same checks without writes. This is a public bundled snapshot, not an
+automatic updater; another CLI version may contain different helper bytes and
+will preserve differing installed files as conflicts. Neither npm installation
+alone nor running this command activates the helpers in the agent.
+
+For older CLI releases use the pinned public installer below with an explicit
+agent and Project scope. For Copilot that is \`--agent github-copilot --copy\`,
+which \`skills@1.5.26\` places in project \`.agents/skills/\`. Do not add \`-g\` or
+\`--all\`. Confirm the complete tree and the actual source selected by Copilot.
+
+### Public on-demand channel
+
+This channel can bootstrap before CLI installation or course authentication.
+Select a full, retained public CLI master commit containing these helper trees;
+record it as \`CLI_SKILLS_REF\`. Do not use an unmerged branch SHA as the permanent
+reference. The installer is separately pinned to the inspected \`skills@1.5.26\`.
+
+\`\`\`bash
+: "\${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
+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
+\`\`\`
+
+Run only the needed helper's command, from the project root. Project scope is the
+default; do not add \`--global\`/\`-g\`. \`--copy\` requests a project copy instead of a
+symlink. \`npx --yes\` accepts running the pinned npm tool; there is deliberately no
+\`--yes\` argument to \`skills add\`, so its own prompts are retained. Confirm the
+installer's actual paths and complete references after installation. A helper
+already managed by CLI should be used/updated through CLI, not overwritten here.
+
+### CLI channel
+
+Use this channel after setup/auth and only with verified skill-filter support and
+available v4 content. These helpers and the lesson skills \`10x-idea-check\`, \`10x-init\`, \`10x-shape\`, \`10x-prd\` belong to m1l1
+and inherit course membership and module availability. Their source membership
+does not prove that the content has been published or unlocked.
+
+In a separate project from the public copies, or after the explicit takeover
+below, use the same verified \`10x_cli\` runner:
+
+\`\`\`bash
+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
+\`\`\`
+
+Each successful filtered skill download should materialize
+\`.claude/skills/<canonical-name>/SKILL.md\` and
+\`.claude/skills/<canonical-name>/references/compatibility.md\`, under lesson ownership
+\`lessons.m1l1.skills\` in \`.claude/.10x-cli-manifest.json\`, with hashes in
+\`files.skills\`. Confirm that complete tree and owner from actual output/files.
+This filter writes only the selected skill, not course rules or the whole lesson.
+
+### Changing the owner deliberately
+
+To move a public copy to CLI, inventory and back up that entire helper outside the
+managed skill trees, including local changes and installer metadata needed for
+recovery. Use the original pinned installer's \`remove --help\` and \`remove\` flow to
+unregister only the selected helper at project scope for the selected agent.
+Verify that both its registration and destination path/symlink are gone. If
+anything remains or another owner is present, stop the takeover and preserve it.
+Then use a filtered skill download and inspect its complete tree and lesson ownership. Merge
+desired local edits consciously from the backup; do not automatically force them
+over the downloaded copy. Reopen/read the installed helper after replacement.
+
+The reverse move has no verified CLI per-skill unregister command in this contract.
+Use a new isolated project for a public copy; do not hand-edit the CLI manifest or
+place two updaters over the same files. Normal use does not require any takeover.
+
+## Download, use, update
+
+Prepare lesson 1's four skills, including \`10x-idea-check\` with its references.
+The launch example remains the existing 10xCards: init → shape → PRD.
+Idea assessment is optional to run before that chain; install its tree during
+lesson setup so the learner can use it. Retain a narrower scope when the user
+explicitly requested only a specific skill.
+\`10x-plan\` is not available for the launch demonstration. After capability and
+content checks for each name, inspect each preview before its corresponding write:
+
+\`\`\`bash
+10x_cli get m1l1 --type skills --name 10x-idea-check --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli get m1l1 --type skills --name 10x-idea-check --course 10xdevs4 --tool claude-code --lang pl
+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
+\`\`\`
+
+Require the complete four trees and inspect each installed entrypoint/reference.
+All checks below must succeed before use; stop on any failure:
+
+\`\`\`bash
+test -s .claude/skills/10x-idea-check/SKILL.md
+test -s .claude/skills/10x-idea-check/references/examples.md
+test -s .claude/skills/10x-idea-check/references/assessment-guide.md
+test -s .claude/skills/10x-idea-check/references/10xdevs-4-dates.md
+test -s .claude/skills/10x-idea-check/references/10xdevs-4-certification.md
+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
+\`\`\`
+
+PRD reads \`../10x-shape/references/prd-schema.md\` relative to its SKILL.md;
+isolated PRD download is insufficient. These are the source minimum: preserve
+additional supporting files in the selected release. Inspect all four names in
+\`lessons.m1l1.skills\`, their hashes in \`files.skills\`, and the project edition
+binding. Partial downloads do not establish complete lesson freshness/release identity.
+Membership in source is candidate evidence; actual filtered availability, full PL
+references and release identity still need verification for all four names.
+
+\`CLAUDE-m1l1\` is a separate lesson rule and is not included in these filtered gets.
+The inspected three skill sources do not require it for the chain. This is not
+proof that the entire lesson needs no rule: if the learner's lesson instructions
+require it, inspect an existing rule's provenance, or report the missing
+prerequisite and ask the lesson/release owner for a supported route before that
+step. Never invent a command, overwrite a rule or fall back to full lesson get.
+
+If the learner wants to assess their idea before shaping, have the agent read
+\`.claude/skills/10x-idea-check/SKILL.md\` and its references and follow that skill.
+A learner ready to shape can skip assessment. Then read the chain's entrypoints
+and references in order: init preserves/scaffolds context directories; shape conducts the actual
+10xCards discovery with the learner and writes
+\`context/foundation/shape-notes.md\`; after the learner approves those notes, PRD
+uses them and the sibling schema to produce \`context/foundation/prd.md\`.
+Ask for missing lesson inputs; do not manufacture a task.md, product decisions or
+a finished plan. Respect existing-file collision choices and report actual output
+paths. Inspect the notes, schema compliance, open questions and preserved local
+work. Stop at PRD, without stack selection or implementation. Download alone is
+not use; native slash/$ discovery needs separate agent evidence. Keep private
+lesson text out of public fixtures. The guide supplies the detailed agent steps.
+
+Sync below refreshes entire recorded lessons, not only the four skill filters.
+Preview may include other skills, prompts, configs and course rules; apply only
+when the user accepts that scope. For a narrow update, repeat the selected skill
+filter instead. Never use sync to silently bypass a missing lesson-rule prerequisite.
+
+\`\`\`bash
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl
+\`\`\`
+
+Normal sync refreshes downloaded owners, including the full lessons that own previously downloaded skills. Avoid \`--all\` for this small journey. Inspect updated,
+unchanged, conflict/preserved and error outcomes even when exit is 0. Preserve
+local edits; do not use automatic \`--force\`. Recovery commands must retain the
+same runner/course/tool/lang, even if an older report omits that context.
+
+Filtered lesson get (\`m1l1 --type skills --name ...\`) is the supported command
+used throughout this guide. It preserves other previously downloaded artifacts
+through partial writes; normal sync later operates at lesson scope. \`--print\` is an
+inspection surface, not installation: human TTY output can show only SKILL.md,
+while non-TTY output is JSON. Never redirect it into SKILL.md as a full package.
+
+| Item to update | Correct channel |
+|---|---|
+| npx CLI | Choose and verify a new published version, update the runner pin |
+| Global npm CLI | \`npm install -g "@przeprogramowani/10x-cli@$CLI_VERSION"\` after selecting/verifying the version |
+| Standalone CLI | Replace through its verified release asset procedure, then check the actual executable |
+| Public helper copy | Inspect local changes/ownership; rerun its selected \`skills add\` command with a deliberate new full source SHA |
+| CLI-owned helper or exercise skill | Repeat its filtered get for a narrow update; \`sync\` refreshes full recorded lessons after preview |
+
+\`skills update\` is not a substitute for proving an exact selected helper revision;
+it may follow a different ref/latest. npm install includes helper source files in
+the package but does not install them into an agent. CLI sync cannot update the
+CLI executable or a public installer-owned helper.
+
+## Diagnostics and evidence boundaries
+
+Doctor performs auth/access, API, config, version and configured-tool checks.
+It can return 78 with an outer JSON \`status: "ok"\`; inspect \`data.overall\` and all
+\`data.checks\`. A missing tool directory before first get can be expected. Explain
+only that failure as pre-download state; do not ignore auth/network/permissions.
+The inspected doctor has no \`--tool\` or \`--course\` flags and may report a different
+configured profile/course from this journey's explicit command context.
+
+Configuration is under \`$XDG_CONFIG_HOME/10x-cli\` on macOS/Linux when nonempty,
+otherwise \`~/.config/10x-cli\`. Windows uses \`%APPDATA%/10x-cli\`, falling back to
+the user's \`AppData/Roaming/10x-cli\`. Inspect only needed nonsecret preferences;
+do not dump credentials or reset the entire config directory. Auth validity and
+live course access are distinct: inspect \`access_checked\`/access errors, not only
+the status exit. Login is user-operated and may send email.
+
+Full acceptance needs real package/version/integrity/source and endpoint/content
+release evidence, both helper channels, complete support files, and an actual
+agent task transcript for macOS/zsh/Claude Code/PL. Local builds and fixtures can
+check structure/conflicts but cannot prove publication, course unlock or this
+user's entitlement. Other platforms/profiles and EN/PL transformed content need
+their own evidence; do not imply a Windows or translated-content walkthrough ran.
+`;
+
+// skills/10x-cli-guide/SKILL.md
+var SKILL_default2 = `---
+name: 10x-cli-guide
+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: download, use, update
+
+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.
+
+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.
+
+## Environment
+
+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.
+
+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.
+
+Use the verified \`10x_cli\` runner defined in the reference, or the user's exact
+verified global/standalone executable:
+
+\`\`\`bash
+10x_cli --version
+10x_cli get --help
+10x_cli sync --help
+10x_cli auth --status
+10x_cli list --course 10xdevs4
+\`\`\`
+
+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.
+
+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.
+
+## Session management
+
+When login is needed, let the user choose the delivery channel and complete it:
+
+\`\`\`bash
+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
+\`\`\`
+
+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.
+
+## Download
+
+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.
+Prepare all four lesson skills: \`10x-idea-check\`, \`10x-init\`, \`10x-shape\` and
+\`10x-prd\`. Idea assessment is optional to run; its files should still be available
+when preparing lesson 1. If the user requested only a specific skill, retain that
+narrower scope. After checking each name's capability and availability, download
+four separate complete selected skill trees. Inspect each dry-run before its corresponding write:
+
+\`\`\`bash
+10x_cli get m1l1 --type skills --name 10x-idea-check --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli get m1l1 --type skills --name 10x-idea-check --course 10xdevs4 --tool claude-code --lang pl
+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
+\`\`\`
+
+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
+test -s .claude/skills/10x-idea-check/SKILL.md
+test -s .claude/skills/10x-idea-check/references/examples.md
+test -s .claude/skills/10x-idea-check/references/assessment-guide.md
+test -s .claude/skills/10x-idea-check/references/10xdevs-4-dates.md
+test -s .claude/skills/10x-idea-check/references/10xdevs-4-certification.md
+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
+\`\`\`
+
+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 four 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 idea-check/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 four 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. If the learner wants to assess whether an
+idea fits their experience, time and course goals, first read
+\`.claude/skills/10x-idea-check/SKILL.md\` and its references and follow that skill.
+Do not make assessment a prerequisite when the learner is ready to shape.
+Then 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_cli sync --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl
+\`\`\`
+
+Normal sync refreshes the full lessons recorded in the manifest, not just the
+four 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. |
+| Missing \`10x-idea-check\` after setup | Older helper journeys selected only init/shape/prd. Check the actual commands, selected profile path and manifest; use the idea-check preview/get above to add its complete tree. If the files already exist, read that exact SKILL.md and check the agent's discovery/reload behavior before reinstalling. An absent slash command alone does not prove missing files. |
+| 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.
+`;
+
+// skills/10x-cli-guide/references/compatibility.md
+var compatibility_default2 = `# CLI compatibility, channels and command context
+
+This reference is packaged inside each helper. Both copies must have identical
+bytes in the authoring repository. It defines the guided filtered-download contract;
+verify the selected published CLI and live content before executing that path.
+
+## Version and capability check
+
+Record four independent identities: CLI runner/version, CLI package source,
+public helper source revision, and the course content release. Updating one does
+not automatically update the others.
+
+| Evidence | What it establishes | What it does not establish |
+|---|---|---|
+| Actual executable \`--version\`, command help | The runner and syntax in use | Working API, entitlement or a published helper revision |
+| npm version, \`dist.integrity\`, \`gitHead\`, matching packaged README/source | Origin of that published package | Publication of changes on a development branch |
+| Full helper commit retained on public CLI master | Reproducible public helper source | Installation in this project or course publication |
+| Successful named download and complete local tree/manifest | Actual package/API/content behavior for this context | A successful agent task or another profile/language |
+
+The earlier planning shorthand \`get SKILL_NAME\` was incorrect. Released CLI
+uses a lesson reference plus \`--type skills --name NAME\`; there is no standalone
+skill-name positional command or independent skill-owner sync contract. On 2026-09-14, CLI \`1.21.0\` was published with v4, filtered skill downloads
+and Circle login; production m1 EN/PL and sync were verified. Its npm \`gitHead\`
+is \`2cc510fe690ba820937602d702564985087ded46\`. These revised helpers have their
+own source/content identity and are not implied by installing CLI 1.21.0. A local
+source build can carry an old version label; do not identify features from that
+label alone.
+
+For a known installed version, read its npm metadata (replace the shell variable
+with the observed version) and use the matching source revision for documentation:
+
+\`\`\`bash
+: "\${CLI_VERSION:?Set the actual published CLI version}"
+npm view "@przeprogramowani/10x-cli@$CLI_VERSION" version engines gitHead dist.integrity dist.tarball --json
+\`\`\`
+
+Use that exact package's README or
+\`https://raw.githubusercontent.com/przeprogramowani/10x-cli/<gitHead>/README.md\`,
+with the real \`gitHead\` substituted. For a standalone binary, use its actual
+release tag/asset, published verification information and matching source. Do not
+invent a source SHA if metadata is absent. The installed help wins for supported
+flags; a help/README mismatch must remain visible and be checked against matching
+source, not resolved by fetching arbitrary master instructions.
+
+Before the filtered-download journey, verify \`get --help\` and matching source/release evidence
+for \`get m1l1 --type skills --name NAME\` and lesson-scoped sync. A successful \`--help\` exit alone does
+not prove skill-filter support. If support or release evidence is missing, prepare the
+public helpers and handoff, but pause filtered commands with a precise explanation.
+Once supported, a filtered dry-run verifies the actual API/content selection before
+writing. Report unsupported reference, missing skill/index, locked module, denied
+access and network errors separately; do not silently use a lesson or v3 instead.
+
+## Keep one runner and one project context
+
+The examples below use a pinned npx runner in macOS/zsh or another POSIX shell.
+Set \`CLI_VERSION\` from verified release evidence, then use this function in that
+shell session. If the user's existing verified global/standalone \`10x\` works,
+substitute its exact executable for \`10x_cli\`; no reinstall is required.
+
+\`\`\`bash
+: "\${CLI_VERSION:?Set the actual published CLI version}"
+10x_cli() { npx --yes "@przeprogramowani/10x-cli@$CLI_VERSION" "$@"; }
+10x_cli --version
+10x_cli --help
+10x_cli get --help
+10x_cli sync --help
+10x_cli auth --help
+10x_cli auth --status
+10x_cli list --course 10xdevs4
+\`\`\`
+
+Run commands from the intended project root. The target guided context is
+\`--course 10xdevs4 --tool claude-code --lang pl\`; preserve it in downloads,
+previews, updates and recovery. \`list\` takes \`--course\`, not tool/lang flags.
+Use another context only when the user chose it. Record any language fallback
+reported by the CLI rather than calling English output Polish.
+
+The project edition is stored in \`.10x-cli.json\` after a validated write and shared
+across profiles; existing supported manifests also carry edition information.
+Course selection is explicit flag → project edition → live API recommendation.
+An explicit course does not authorize changing a bound project's edition. Retain
+the v3 project and start a separate v4 directory for this journey. Preserve unknown,
+corrupt or conflicting manifests; never delete a binding to force migration.
+
+Verified releases with the project-binding safeguards preserve project files and
+tool/language preferences during \`list\`, \`get --print\`, \`get --dry-run\`,
+\`sync --dry-run\` and \`doctor\`. Auth token refresh can still update the credential
+store. Verify the selected release's contract before describing a preview as
+read-only; do not generalize older source bugs to the target release.
+
+## Two helper channels, one owner per installed copy
+
+The public authoring source is \`przeprogramowani/10x-cli\`, under
+\`skills/10x-cli-setup/\` and \`skills/10x-cli-guide/\`. Toolkit distributes controlled
+copies through course content. Each helper includes \`SKILL.md\` and its own
+\`references/compatibility.md\`; neither may rely on an installed sibling helper.
+
+Before either installer writes, inspect the destination directory, its path
+components/symlink targets, the tool's \`.10x-cli-manifest.json\`, and the skills
+installer's project registration/lock. Do not infer ownership solely from a
+directory name. If ownership is mixed or unknown, preserve local files and
+resolve it before writing; use a separate project to try the other channel.
+
+### Bundled public copies (unreleased command)
+
+The next CLI release adds \`10x helpers install --tool copilot\` (use the user's
+chosen profile). This command is absent from the 1.21.0 and 1.22.0 master
+baselines. Verify \`10x helpers --help\` on the actual runner; a source build may
+still report the baseline version. Do not claim npm availability from this text.
+
+When supported, run from the intended project:
+
+\`\`\`bash
+10x helpers install --tool copilot --dry-run
+10x helpers install --tool copilot
+\`\`\`
+
+Both helpers and their own compatibility references are embedded in the same npm
+bundle/standalone executable. No auth, network, external skills installer or
+global installation is involved. \`--tool\` is required; Copilot writes to
+\`.github/skills/\`, Claude Code to \`.claude/skills/\`, and other profiles follow the
+CLI profile table. Do not carry \`--agent github-copilot\` from the external
+installer into this command.
+
+Existing identical files are unchanged; missing files are created. Any differing
+helper file blocks the entire preflight with exit 1, preserving both helpers and
+local extras. Never remove a user's files merely to make a retry pass. Keep an
+existing copy, or let the user deliberately back it up outside managed trees
+before replacement. Course-owned copies stay with get/sync; this command writes
+no course manifest or binding. Filesystem errors also exit 1 and report that
+already created files remain; unsupported options/targets exit 2. Preview uses
+the same checks without writes. This is a public bundled snapshot, not an
+automatic updater; another CLI version may contain different helper bytes and
+will preserve differing installed files as conflicts. Neither npm installation
+alone nor running this command activates the helpers in the agent.
+
+For older CLI releases use the pinned public installer below with an explicit
+agent and Project scope. For Copilot that is \`--agent github-copilot --copy\`,
+which \`skills@1.5.26\` places in project \`.agents/skills/\`. Do not add \`-g\` or
+\`--all\`. Confirm the complete tree and the actual source selected by Copilot.
+
+### Public on-demand channel
+
+This channel can bootstrap before CLI installation or course authentication.
+Select a full, retained public CLI master commit containing these helper trees;
+record it as \`CLI_SKILLS_REF\`. Do not use an unmerged branch SHA as the permanent
+reference. The installer is separately pinned to the inspected \`skills@1.5.26\`.
+
+\`\`\`bash
+: "\${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
+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
+\`\`\`
+
+Run only the needed helper's command, from the project root. Project scope is the
+default; do not add \`--global\`/\`-g\`. \`--copy\` requests a project copy instead of a
+symlink. \`npx --yes\` accepts running the pinned npm tool; there is deliberately no
+\`--yes\` argument to \`skills add\`, so its own prompts are retained. Confirm the
+installer's actual paths and complete references after installation. A helper
+already managed by CLI should be used/updated through CLI, not overwritten here.
+
+### CLI channel
+
+Use this channel after setup/auth and only with verified skill-filter support and
+available v4 content. These helpers and the lesson skills \`10x-idea-check\`, \`10x-init\`, \`10x-shape\`, \`10x-prd\` belong to m1l1
+and inherit course membership and module availability. Their source membership
+does not prove that the content has been published or unlocked.
+
+In a separate project from the public copies, or after the explicit takeover
+below, use the same verified \`10x_cli\` runner:
+
+\`\`\`bash
+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
+\`\`\`
+
+Each successful filtered skill download should materialize
+\`.claude/skills/<canonical-name>/SKILL.md\` and
+\`.claude/skills/<canonical-name>/references/compatibility.md\`, under lesson ownership
+\`lessons.m1l1.skills\` in \`.claude/.10x-cli-manifest.json\`, with hashes in
+\`files.skills\`. Confirm that complete tree and owner from actual output/files.
+This filter writes only the selected skill, not course rules or the whole lesson.
+
+### Changing the owner deliberately
+
+To move a public copy to CLI, inventory and back up that entire helper outside the
+managed skill trees, including local changes and installer metadata needed for
+recovery. Use the original pinned installer's \`remove --help\` and \`remove\` flow to
+unregister only the selected helper at project scope for the selected agent.
+Verify that both its registration and destination path/symlink are gone. If
+anything remains or another owner is present, stop the takeover and preserve it.
+Then use a filtered skill download and inspect its complete tree and lesson ownership. Merge
+desired local edits consciously from the backup; do not automatically force them
+over the downloaded copy. Reopen/read the installed helper after replacement.
+
+The reverse move has no verified CLI per-skill unregister command in this contract.
+Use a new isolated project for a public copy; do not hand-edit the CLI manifest or
+place two updaters over the same files. Normal use does not require any takeover.
+
+## Download, use, update
+
+Prepare lesson 1's four skills, including \`10x-idea-check\` with its references.
+The launch example remains the existing 10xCards: init → shape → PRD.
+Idea assessment is optional to run before that chain; install its tree during
+lesson setup so the learner can use it. Retain a narrower scope when the user
+explicitly requested only a specific skill.
+\`10x-plan\` is not available for the launch demonstration. After capability and
+content checks for each name, inspect each preview before its corresponding write:
+
+\`\`\`bash
+10x_cli get m1l1 --type skills --name 10x-idea-check --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli get m1l1 --type skills --name 10x-idea-check --course 10xdevs4 --tool claude-code --lang pl
+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
+\`\`\`
+
+Require the complete four trees and inspect each installed entrypoint/reference.
+All checks below must succeed before use; stop on any failure:
+
+\`\`\`bash
+test -s .claude/skills/10x-idea-check/SKILL.md
+test -s .claude/skills/10x-idea-check/references/examples.md
+test -s .claude/skills/10x-idea-check/references/assessment-guide.md
+test -s .claude/skills/10x-idea-check/references/10xdevs-4-dates.md
+test -s .claude/skills/10x-idea-check/references/10xdevs-4-certification.md
+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
+\`\`\`
+
+PRD reads \`../10x-shape/references/prd-schema.md\` relative to its SKILL.md;
+isolated PRD download is insufficient. These are the source minimum: preserve
+additional supporting files in the selected release. Inspect all four names in
+\`lessons.m1l1.skills\`, their hashes in \`files.skills\`, and the project edition
+binding. Partial downloads do not establish complete lesson freshness/release identity.
+Membership in source is candidate evidence; actual filtered availability, full PL
+references and release identity still need verification for all four names.
+
+\`CLAUDE-m1l1\` is a separate lesson rule and is not included in these filtered gets.
+The inspected three skill sources do not require it for the chain. This is not
+proof that the entire lesson needs no rule: if the learner's lesson instructions
+require it, inspect an existing rule's provenance, or report the missing
+prerequisite and ask the lesson/release owner for a supported route before that
+step. Never invent a command, overwrite a rule or fall back to full lesson get.
+
+If the learner wants to assess their idea before shaping, have the agent read
+\`.claude/skills/10x-idea-check/SKILL.md\` and its references and follow that skill.
+A learner ready to shape can skip assessment. Then read the chain's entrypoints
+and references in order: init preserves/scaffolds context directories; shape conducts the actual
+10xCards discovery with the learner and writes
+\`context/foundation/shape-notes.md\`; after the learner approves those notes, PRD
+uses them and the sibling schema to produce \`context/foundation/prd.md\`.
+Ask for missing lesson inputs; do not manufacture a task.md, product decisions or
+a finished plan. Respect existing-file collision choices and report actual output
+paths. Inspect the notes, schema compliance, open questions and preserved local
+work. Stop at PRD, without stack selection or implementation. Download alone is
+not use; native slash/$ discovery needs separate agent evidence. Keep private
+lesson text out of public fixtures. The guide supplies the detailed agent steps.
+
+Sync below refreshes entire recorded lessons, not only the four skill filters.
+Preview may include other skills, prompts, configs and course rules; apply only
+when the user accepts that scope. For a narrow update, repeat the selected skill
+filter instead. Never use sync to silently bypass a missing lesson-rule prerequisite.
+
+\`\`\`bash
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl --dry-run
+10x_cli sync --course 10xdevs4 --tool claude-code --lang pl
+\`\`\`
+
+Normal sync refreshes downloaded owners, including the full lessons that own previously downloaded skills. Avoid \`--all\` for this small journey. Inspect updated,
+unchanged, conflict/preserved and error outcomes even when exit is 0. Preserve
+local edits; do not use automatic \`--force\`. Recovery commands must retain the
+same runner/course/tool/lang, even if an older report omits that context.
+
+Filtered lesson get (\`m1l1 --type skills --name ...\`) is the supported command
+used throughout this guide. It preserves other previously downloaded artifacts
+through partial writes; normal sync later operates at lesson scope. \`--print\` is an
+inspection surface, not installation: human TTY output can show only SKILL.md,
+while non-TTY output is JSON. Never redirect it into SKILL.md as a full package.
+
+| Item to update | Correct channel |
+|---|---|
+| npx CLI | Choose and verify a new published version, update the runner pin |
+| Global npm CLI | \`npm install -g "@przeprogramowani/10x-cli@$CLI_VERSION"\` after selecting/verifying the version |
+| Standalone CLI | Replace through its verified release asset procedure, then check the actual executable |
+| Public helper copy | Inspect local changes/ownership; rerun its selected \`skills add\` command with a deliberate new full source SHA |
+| CLI-owned helper or exercise skill | Repeat its filtered get for a narrow update; \`sync\` refreshes full recorded lessons after preview |
+
+\`skills update\` is not a substitute for proving an exact selected helper revision;
+it may follow a different ref/latest. npm install includes helper source files in
+the package but does not install them into an agent. CLI sync cannot update the
+CLI executable or a public installer-owned helper.
+
+## Diagnostics and evidence boundaries
+
+Doctor performs auth/access, API, config, version and configured-tool checks.
+It can return 78 with an outer JSON \`status: "ok"\`; inspect \`data.overall\` and all
+\`data.checks\`. A missing tool directory before first get can be expected. Explain
+only that failure as pre-download state; do not ignore auth/network/permissions.
+The inspected doctor has no \`--tool\` or \`--course\` flags and may report a different
+configured profile/course from this journey's explicit command context.
+
+Configuration is under \`$XDG_CONFIG_HOME/10x-cli\` on macOS/Linux when nonempty,
+otherwise \`~/.config/10x-cli\`. Windows uses \`%APPDATA%/10x-cli\`, falling back to
+the user's \`AppData/Roaming/10x-cli\`. Inspect only needed nonsecret preferences;
+do not dump credentials or reset the entire config directory. Auth validity and
+live course access are distinct: inspect \`access_checked\`/access errors, not only
+the status exit. Login is user-operated and may send email.
+
+Full acceptance needs real package/version/integrity/source and endpoint/content
+release evidence, both helper channels, complete support files, and an actual
+agent task transcript for macOS/zsh/Claude Code/PL. Local builds and fixtures can
+check structure/conflicts but cannot prove publication, course unlock or this
+user's entitlement. Other platforms/profiles and EN/PL transformed content need
+their own evidence; do not imply a Windows or translated-content walkthrough ran.
+`;
+
+// src/lib/bundled-helpers.ts
+var BUNDLED_HELPERS = {
+  "10x-cli-setup": { "SKILL.md": SKILL_default, "references/compatibility.md": compatibility_default },
+  "10x-cli-guide": { "SKILL.md": SKILL_default2, "references/compatibility.md": compatibility_default2 }
+};
+
+// src/commands/helpers.ts
+function registerHelpersCommand(cli) {
+  cli.command("helpers <action>", "Install both bundled public CLI helpers into this project (action: install)").option("--tool <tool>", `Choose the target explicitly: ${Object.keys(PROFILES).join(", ")}`).option("--dry-run", "Check paths and conflicts without writing files").action((action, flags) => {
+    const ctx = resolveContext(flags);
+    const profile = typeof flags.tool === "string" ? getToolProfile(flags.tool) : undefined;
+    if (action !== "install" || !profile || typeof profile.toolId !== "string") {
+      outputError(ctx, "usage", "Choose install and a supported target tool explicitly.", ExitCodes.USAGE, "Run '10x helpers install --tool copilot' from your project, or choose another tool from '10x helpers --help'.");
+    }
+    const root = process.cwd();
+    try {
+      const files = Object.entries(BUNDLED_HELPERS).flatMap(([name, tree]) => Object.entries(tree).map(([file, content]) => {
+        const path = join11(profile.skillDir(name), file);
+        const absolute = resolve3(root, path);
+        assertProjectFilePath(root, absolute);
+        const state = !existsSync10(absolute) ? "missing" : readFileSync9(absolute).equals(Buffer.from(content)) ? "unchanged" : "conflict";
+        return { path, absolute, content, state };
+      }));
+      const conflicts = files.filter((file) => file.state === "conflict");
+      if (conflicts.length) {
+        outputError(ctx, "helper_conflict", `Existing helper files differ: ${conflicts.map((f2) => f2.path).join(", ")}. No files were written.`, ExitCodes.ERROR, "Keep your existing helpers, or back them up outside the skill directories before retrying '10x helpers install --tool " + profile.toolId + "'.");
+      }
+      const results = [];
+      for (const file of files) {
+        if (file.state === "missing" && !flags.dryRun) {
+          assertProjectFilePath(root, file.absolute);
+          mkdirSync6(dirname6(file.absolute), { recursive: true });
+          assertProjectFilePath(root, file.absolute);
+          writeFileSync6(file.absolute, file.content, { flag: "wx" });
+        }
+        results.push({ path: file.path, action: file.state === "unchanged" ? "unchanged" : flags.dryRun ? "would_create" : "created" });
+      }
+      output(ctx, `${flags.dryRun ? "Helper preview" : "Helpers ready"} for ${profile.displayName} in this project.
+${results.map((f2) => `${f2.action}: ${f2.path}`).join(`
+`)}`, { version: package_default.version, scope: "project", tool: profile.toolId, dryRun: !!flags.dryRun, files: results });
+    } catch (error) {
+      outputError(ctx, "helper_install_failed", `Could not complete helper installation: ${error instanceof Error ? error.message : String(error)}.`, ExitCodes.ERROR, "Inspect the reported path and preserve existing files; any files already created remain available when you retry '10x helpers install --tool " + profile.toolId + "'.");
+    }
+  });
+}
+
 // src/commands/list.ts
 function registerListCommand(cli) {
   cli.command("list [module]", "Browse available modules and lessons").option("--course <course>", "Select course ID or slug (default: project edition or API recommendation)").action(async (moduleArg, options) => {
@@ -7588,11 +8713,11 @@ function renderModuleDetail(ctx, module, course, reason) {
 }
 
 // src/commands/sync.ts
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 
 // src/lib/sync-freshness.ts
-import { existsSync as existsSync10, readFileSync as readFileSync9 } from "node:fs";
-import { join as join11 } from "node:path";
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "node:fs";
+import { join as join12 } from "node:path";
 function isLessonFresh(root, manifest, id, profile, lang, courseRules) {
   const lesson = manifest?.lessons?.[id];
   const representation = lesson?.representation;
@@ -7600,25 +8725,25 @@ function isLessonFresh(root, manifest, id, profile, lang, courseRules) {
     return false;
   const matches = (path, hash) => {
     assertProjectFilePath(root, path);
-    return !!hash && existsSync10(path) && contentHash(readFileSync9(path)) === hash;
+    return !!hash && existsSync11(path) && contentHash(readFileSync10(path)) === hash;
   };
   try {
     for (const [name, skill] of Object.entries(lesson.skills)) {
       if (!isSafeName(name))
         return false;
       for (const file of skill.files)
-        if (!isSafeSkillFilePath(file) || !matches(join11(root, profile.skillDir(name), file), manifest.files.skills[name]?.contentHashes?.[file]))
+        if (!isSafeSkillFilePath(file) || !matches(join12(root, profile.skillDir(name), file), manifest.files.skills[name]?.contentHashes?.[file]))
           return false;
     }
     for (const name of lesson.prompts)
-      if (!isSafeName(name) || !matches(join11(root, profile.promptPath(name.replace(/\.md$/, ""))), manifest.files.promptHashes?.[name]))
+      if (!isSafeName(name) || !matches(join12(root, profile.promptPath(name.replace(/\.md$/, ""))), manifest.files.promptHashes?.[name]))
         return false;
     for (const name of lesson.configs)
-      if (!isSafeName(name) || !matches(join11(root, profile.configPath(name)), manifest.files.configHashes?.[name]))
+      if (!isSafeName(name) || !matches(join12(root, profile.configPath(name)), manifest.files.configHashes?.[name]))
         return false;
-    const rulesPath = join11(root, profile.rulesFile);
+    const rulesPath = join12(root, profile.rulesFile);
     assertProjectFilePath(root, rulesPath);
-    const existing = existsSync10(rulesPath) ? readFileSync9(rulesPath, "utf8") : "";
+    const existing = existsSync11(rulesPath) ? readFileSync10(rulesPath, "utf8") : "";
     const block = inspectRulesBlock(existing, profile.sentinelBegin, profile.sentinelEnd);
     if (representation.rules) {
       const rules = manifest.managedRules;
@@ -7677,7 +8802,7 @@ async function runSync(ctx, options) {
     }
     return true;
   });
-  const manifest = readManifest(join12(process.cwd(), profile.manifestDir));
+  const manifest = readManifest(join13(process.cwd(), profile.manifestDir));
   const manifestLessonIds = new Set(manifest?.lessons ? Object.keys(manifest.lessons) : manifest ? [manifest.lessonId] : []);
   let targets = unlocked;
   if (moduleFilter !== undefined)
@@ -7735,7 +8860,7 @@ async function runSync(ctx, options) {
   }
 }
 async function syncLesson(ctx, lesson, opts) {
-  const currentManifest = readManifest(join12(process.cwd(), opts.profile.manifestDir));
+  const currentManifest = readManifest(join13(process.cwd(), opts.profile.manifestDir));
   const stored = currentManifest?.lessons?.[lesson.lessonId]?.catalogContentHash;
   if (!opts.force && lesson.contentHash !== undefined && stored !== undefined && lesson.contentHash === stored && isLessonFresh(process.cwd(), currentManifest, lesson.lessonId, opts.profile, opts.lang, opts.applyCourseRules)) {
     verbose(ctx, `${lesson.lessonId}: upstream unchanged (digest match) — skipping fetch`);
@@ -8080,6 +9205,7 @@ cli.option("--json", "Output as JSON (auto-detected when piped)");
 cli.option("--verbose", "Show detailed output on stderr");
 registerAuthCommand(cli);
 registerGetCommand(cli);
+registerHelpersCommand(cli);
 registerListCommand(cli);
 registerSyncCommand(cli);
 registerDoctorCommand(cli);