docs: add native management flow reconstruction

platform-services/NODE.md

@@ -28,6 +28,7 @@ Relevant leaves:
 - **[usage-analytics-and-migrations.md](usage-analytics-and-migrations.md)** — Telemetry, quotas, updates, and local evolution over time.
 - **[claude-ai-limits-and-extra-usage-state.md](claude-ai-limits-and-extra-usage-state.md)** — The shared Claude.ai quota state machine, warning and recovery surfaces, `/usage`, `/extra-usage`, and the extra-usage couplings that affect fast mode, prompt caching, and 1M model access.
 - **[doctor-command-and-health-diagnostics.md](doctor-command-and-health-diagnostics.md)** — How `/doctor`, `claude doctor`, shared install health checks, and persistent diagnostics aggregate warnings across settings, sandboxing, plugins, MCP, and context.
+- **[native-install-update-and-setup-token-cli-flows.md](native-install-update-and-setup-token-cli-flows.md)** — How `claude install`, `claude update`, and `claude setup-token` build on shared health checks while still owning their launcher, repair, and limited-scope OAuth handoff behavior.
 - **[startup-service-sequencing-and-capability-gates.md](startup-service-sequencing-and-capability-gates.md)** — How startup creates governance waiters, launches managed settings/policy/sync work, and keeps interactive, headless, and bare readiness distinct.
 - **[bootstrap-and-service-failures.md](bootstrap-and-service-failures.md)** — How late or failed startup services degrade, reconcile, and still preserve explicit capability denials when required.
 - **[interactive-startup-and-project-activation.md](interactive-startup-and-project-activation.md)** — How import-time prewarm, cwd-sensitive setup, trust gating, post-trust activation, and deferred prefetch divide the local startup pipeline.

platform-services/auth-login-logout-and-token-lifecycle.md

@@ -24,6 +24,7 @@ It intentionally does not re-document:
 - the full auth-source precedence and provider-selection rules already summarized in [auth-config-and-policy.md](auth-config-and-policy.md)
 - the remote managed settings and policy service internals already covered in [policy-and-managed-settings-lifecycle.md](policy-and-managed-settings-lifecycle.md)
 - the full bridge or remote-session transport model beyond the auth handoff points already named in [remote-and-bridge-flows.md](../collaboration-and-agents/remote-and-bridge-flows.md)
+- the standalone launcher and setup-token command wrappers beyond the limited-scope auth semantics captured in [native-install-update-and-setup-token-cli-flows.md](native-install-update-and-setup-token-cli-flows.md)
 
 ## Shared lifecycle rule
 

platform-services/native-install-update-and-setup-token-cli-flows.md

@@ -0,0 +1,141 @@
+---
+title: "Native Install, Update, and Setup-Token CLI Flows"
+owners: []
+soft_links: [/platform-services/doctor-command-and-health-diagnostics.md, /platform-services/auth-login-logout-and-token-lifecycle.md, /platform-services/deep-link-protocol-trampoline-and-origin-banner.md]
+---
+
+# Native Install, Update, and Setup-Token CLI Flows
+
+Claude Code's standalone management commands are not just thin wrappers around
+one config file. `claude install`, `claude update`, and `claude setup-token`
+share installation-health logic with `claude doctor`, but each also adds its
+own launch, repair, and user-handoff behavior. A faithful rebuild needs those
+CLI-specific flows rather than only the lower-level auth or diagnostics
+backends.
+
+## Scope boundary
+
+This leaf covers:
+
+- the standalone `claude install` native-launcher flow
+- the standalone `claude update` flow and its shared health checks
+- the standalone `claude setup-token` limited-scope OAuth flow
+- the TTY and browser-handoff expectations that matter for these commands
+
+It intentionally does not re-document:
+
+- the full diagnostics aggregation model already covered in
+  [doctor-command-and-health-diagnostics.md](doctor-command-and-health-diagnostics.md)
+- the broader auth lifecycle already covered in
+  [auth-login-logout-and-token-lifecycle.md](auth-login-logout-and-token-lifecycle.md)
+- the deep-link or terminal-launch trampoline beyond how launcher paths are
+  surfaced to users
+
+## Shared management-command posture
+
+Equivalent behavior should preserve:
+
+- one shared installation-health backend reused by `doctor`, `install`, and
+  `update`
+- top-level commands printing compact terminal rows rather than opening the full
+  REPL
+- raw-mode-dependent flows failing early outside a TTY instead of degrading into
+  partially interactive nonsense
+- install/update warnings being phrased as issue-plus-fix text, not only as
+  opaque status codes
+
+## `claude install` is a native-launcher flow
+
+Equivalent behavior should preserve:
+
+- `claude install` opening with `Checking installation status...`
+- the default target being the current native release channel rather than a
+  project-local development install
+- explicit targets such as `stable`, `latest`, or a concrete version string
+  resolving before the launcher is rewritten
+- native install creating or updating the user-facing launcher path and then
+  surfacing shell-integration guidance
+- PATH remediation being shown immediately when the user-level native bin
+  directory is not available from the current shell
+- success output including a version line, launcher location, and a simple "next
+  step" handoff
+
+The important reconstruction lesson is that install is not just "copy a
+binary." It also repairs the runnable launcher surface and teaches the user how
+that launcher becomes reachable.
+
+## `claude update` reuses health checks before attempting mutation
+
+Equivalent behavior should preserve:
+
+- `claude update` opening with the current version and the release channel it is
+  checking
+- the same PATH and install-method mismatch warnings that `doctor` would have
+  surfaced
+- install-method mismatch repair happening inline before the updater proceeds,
+  instead of forcing the user to run a second command manually
+- repair not short-circuiting the rest of the update flow when a newer native
+  version is still available
+- up-to-date states being explicit, while available updates end in a concrete
+  success summary such as `Successfully updated from X to version Y`
+
+The rebuild target is not merely "check if a version differs." It is a
+diagnostics-aware updater that can repair known launcher metadata drift and then
+continue.
+
+## Launcher and install metadata stay user-visible
+
+Equivalent behavior should preserve:
+
+- the currently running native version being distinguishable from the latest
+  available version
+- launcher-path metadata being available to both install/update summaries and
+  doctor diagnostics
+- persisted install-method state being repairable when the launcher on disk and
+  the saved install metadata drift apart
+- versioned native-install records remaining inspectable enough that later
+  health commands can explain what is supposed to be running
+
+## `claude setup-token` is a limited-scope OAuth helper, not a full login
+
+Equivalent behavior should preserve:
+
+- the command being a top-level CLI entry point rather than an alias for full
+  account login
+- a TTY/raw-mode requirement because the flow expects interactive browser or
+  manual-code handoff
+- a welcome banner before browser launch
+- a warning when another auth source is already configured, clarifying that this
+  flow will create an additional OAuth token rather than replacing the main
+  session
+- browser-open first, followed by a manual fallback URL and pasted-code prompt
+  if the browser does not complete the flow quickly
+- the resulting token being treated as limited-scope material, not as a signal
+  to tear down and replace the current logged-in identity
+
+This flow lives on the auth stack, but it must not reuse the destructive
+logout-before-install path that a real account switch uses.
+
+## Delayed manual fallback is part of the UX contract
+
+Equivalent behavior should preserve:
+
+- an initial optimistic browser-open step instead of requiring manual code entry
+  every time
+- a delayed terminal fallback that prints the authorization URL in a copyable
+  form when browser launch does not complete
+- a pasted-code prompt that keeps the user inside the same CLI flow instead of
+  forcing them to restart the command
+
+## Failure modes
+
+- **launcher drift**: install/update reports success but leaves the runnable
+  launcher pointing at an older or unrelated binary
+- **repair dead-end**: `update` notices install-method drift but stops after
+  rewriting metadata instead of continuing to the available update
+- **PATH invisibility**: native install succeeds on disk but never explains why
+  `claude` is still not found from the user's shell
+- **destructive token helper**: `setup-token` accidentally replaces the main
+  logged-in identity instead of creating limited-scope OAuth material
+- **browser dead-end**: browser launch fails and the CLI never prints the
+  fallback URL or pasted-code prompt