@crvouga/personal 0.1.0 → 0.1.1

package/README.md

@@ -1,4 +1,45 @@
-# Personal developer command center
+# Personal CLI
+
+Use the installed `personal` executable for routine work. `npx @crvouga/personal`
+is the same CLI when it is not installed.
+
+```sh
+personal fleet-node-sync
+personal fleet-status
+personal fleet-discover
+```
+
+`fleet-node-sync` reconciles locked tools, installs the public launcher, removes
+owned legacy `ws` launchers, upserts the Codex proxy profile, and reconciles declared
+T3 provider instances. It applies by invocation; `--dry-run` previews. Run in the
+personal checkout or use `--workspace PATH`. Node ID defaults to hostname; `--id`
+overrides it. Revision defaults to checkout HEAD; `--revision FULL_SHA` pins it.
+
+```sh
+personal t3-plan --json
+personal t3-apply
+personal t3-status
+personal t3-cleanup --dry-run
+personal t3-import --instance EXISTING_ID
+```
+
+Tracked `packages/workstation/agents/t3.json` is desired state. Apply creates and
+updates declared instances and removes previously owned instances absent from the
+definition. Cleanup removes only owned instances. Import is explicit ownership of
+an existing instance. `--plan-hash HASH` rejects stale plans. Secrets and unrelated
+settings are omitted from reports and preserved in the configuration.
+
+All former workstation commands now use `personal workstation …`; there is no `ws`
+package executable. The source installer migrates recognized legacy launchers.
+Native Windows should use the npm executable; proxy adapter execution requires
+macOS/Linux/WSL. Pairing and provider authentication remain per-machine prerequisites.
+
+Read the [node/T3 reconciliation runbook](../workstation/agents/setup.md) for state,
+concurrency, recovery, rollout and precise ownership boundaries. The public package
+needs a local checkout and its shared toolchain for workstation operations; the T3
+reconciler itself runs on Node without Bun or access to live credentials.
+
+## Detailed command reference
 
 Public npm distribution: **`@crvouga/personal`**, executable **`personal`**.
 The source workspace `@pkgs/personal-cli` stays private; its build bundles the
@@ -10,7 +51,7 @@ Requires Node **22.13+ on the 22.x line, or 23.5+** with npm.
 npx --yes @crvouga/personal
 ```
 
-The terminal application has a searchable command palette, category submenus,
+The terminal application has a flat searchable command palette sorted A–Z with group prefixes,
 descriptions, target selection, progress indicators, result summaries, searchable
 node/status/check drill-downs, remedies, retry/back navigation, and an add-node
 wizard. It shows the equivalent noninteractive command before running anything.
@@ -40,9 +81,50 @@ global flags; `agent --json` documents the output/safety contract; `fleet schema
 exposes the roster schema. JSON error messages never contain raw subprocess
 output, environment variables, authentication responses or exception messages.
 
+## Check every Tailscale computer
+
+```sh
+npx --yes @crvouga/personal@latest fleet discover --json
+npx --yes @crvouga/personal@latest fleet health --json
+```
+
+`discover` reads the signed-in local Tailscale daemon, includes offline computers
+and excludes iOS, Android and tvOS devices. `health` checks every visible computer,
+including this controller. It pings online peers, checks registered computers over
+fresh verified SSH sessions, compares checkout/toolchain input hashes, checks each
+pinned tool version and Docker runtime, and runs the existing read-only `personal workstation doctor`
+for managed links, PATH and workstation configuration.
+
+Register remote computers with their existing SSH aliases and actual checkout paths.
+DNS names, Tailscale addresses and resolved SSH aliases are matched exactly. Missing,
+ambiguous, offline or no-longer-visible registrations produce explicit failures;
+the command never guesses a username/path or silently reduces the checked fleet.
+`fleet nodes` before registration shows an empty list and setup guidance.
+
+Authentication checks cover Codex, Claude Code, GitHub, Vault, T3, Railway, Vercel,
+Cloudflare, AWS's active profile and npm. Their status/identity commands run on each
+computer as its SSH user; browser login on another computer does not authenticate
+that session. Credential values and account responses are withheld. Codex/Claude
+status reports do not prove quotas, model access or a live billable request.
+Gemini, Copilot and OpenCode provider access are explicitly **unverified** until a
+supported noninteractive adapter can verify them; saved keys alone never count.
+
+Health uses strict coverage: warnings and skipped checks return exit **1**, as do
+failures. It cannot certify devices hidden by Tailscale ACLs, other accounts/tailnets,
+all-pairs connectivity, every application, or operator-only T3/VS Code connection
+flows. Those limits remain visible in the report. Per-node health probes default
+to five minutes, overridable with `--timeout`; concurrency is bounded to four.
+Commands only diagnose; they never log in, install tools, rewrite configuration,
+or repair machines automatically. Use `--workspace` to select the reference checkout.
+
+The palette lists all commands directly, for example **Fleet: Check all Tailscale
+computers**, **Fleet: Discover Tailscale computers** and **Session: Workspace / config**.
+Node lists and the first checks needing attention display immediately; detailed
+reports remain available without navigating category submenus.
+
 ## Register actual computers
 
-Use the interactive **Fleet setup / add node** action, or preview first:
+Use the interactive **Fleet: Register a developer computer** action, or preview first:
 
 ```sh
 personal fleet add --id dev-linux --ssh dev-linux --path /home/dev/workspace --json
@@ -103,3 +185,54 @@ bun run personal:build
 
 See [releasing.md](releasing.md) for automatic CI releases, credential sources,
 first-publish bootstrap, packed-consumer verification and recovery.
+
+## Preview and apply repairs
+
+```sh
+personal fleet repairs --json
+personal fleet repair --json                        # all visible Tailscale computers
+personal fleet repair --local --json                # this computer only
+personal fleet repair --node dev-linux --json       # selected registered computer
+personal fleet repair --local --repair workspace --json
+# Copy planHash from the reviewed preview; it rejects changed plans:
+personal fleet repair --local --repair workspace --plan-hash REVIEWED_SHA256 --apply --yes --json
+personal fleet repair --local --repair providers --apply --yes --json
+personal fleet repair --local --script              # emit a POSIX script; never execute it here
+```
+
+The flat palette includes **Fleet: Explore repairs and login commands** and
+**Fleet: Repair tools and configuration**. Applying from the palette carries the
+reviewed plan hash. Plan previews exit 0 even when `healthOk` is false: a valid
+plan is not a healthy computer. `--repair` selects from `workspace`, `workstation`
+and `providers`; omitted selection includes the eligible owner actions identified
+by the failed checks. Explicit selection also supports rerunning an owner action.
+
+`workspace` uses existing mise/shared setup and frozen dependencies. `workstation`
+uses `personal:install --yes` and can update launcher/PATH, managed links, notifications
+and provider configuration. `providers` uses the existing strict Vault-backed
+workstation provider sync. Each computer uses its own Vault authorization; the
+controller never transfers credential files, tokens, SSH agents or keychains.
+Native login recipes are operator steps and are commented in generated scripts.
+Use an intended Vault project/config for runtime access, for example
+`vault run --config dev -- personal fleet health --json`, only when those secrets
+are needed by that process.
+
+Only registered, successfully probed remote machines are eligible for automatic
+repairs. SSH host trust, unavailable computers, conflicting Git changes, native
+account approvals, service permissions and manual end-to-end tests stay explicit
+operator work. Unknown future checks also receive an operator step rather than
+being omitted. A successful repair command is followed by fresh checks; remaining
+failures, warnings or skips return exit 1. Reports separate `executionOk`,
+`healthOk`, completed owner commands, and remaining steps. Actions run serially;
+a failure stops later actions on that computer. Partial changes are possible.
+
+Generated scripts require a POSIX shell and are for review in the operator's own
+terminal. They use existing checkout tooling; they do not require a globally
+installed `personal` on remote machines. They are point-in-time scripts without
+CLI plan-hash enforcement. Prefer the guarded CLI apply path and obtain a fresh
+whole-tailnet health report afterward.
+
+See [fleet access and repair research](../fleet/docs/access-and-repair-research.md)
+for the comparison of mise, OpenBao, Bitwarden, 1Password, Tailscale SSH, chezmoi,
+Teleport, Ansible and Syncthing, plus existing password-manager onboarding and
+the distinction between shared service secrets and per-machine logins.