10x-cli-setup

The full skill.

Original instructions from the publisher’s SKILL.md

# 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 bare `list`: with no `--course` the CLI takes the
edition from the project's `.10x-cli.json` binding, or, in a directory that is not
bound yet, from the live API recommendation (the highest edition the account can
reach). Add `--course <slug>` only to inspect another entitled edition on purpose.
Distinguish no membership, unpublished course, locked module and network
failure. Reinstalling the CLI or selecting a different tool does not grant access.
Keep `--tool` and `--lang` explicit in subsequent download/sync commands and leave
`--course` out, so every download stays on the project's edition.

## 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. Its auth check also reports the resolved edition
and selection reason (`details.course`, `details.selectionReason`) — use that as
the self-check before the first download. A project is bound to one edition on its
first write; a later edition needs a new empty directory, because writing it into a
bound project fails with `course_mismatch`.

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.