# World-Class Onboarding Friction Ledger

Append install, upgrade, /init, and first-session friction findings here.

## 2026-04-29 - stale global launcher finding

Hypothesis: Fresh install checks can be misleading when a stale global launcher shadows npm latest.
Baseline: npm latest was 8.8.107 while a local global launcher could return stale 8.8.106.
Change: Record stale launcher as a P0 upgrade-path trust issue.
Commands: Fresh npx check from /tmp returned 8.8.107 (Clavue), as recorded in the upgrade plan.
Result: Fresh npx path was correct, local global launcher path remained a separate risk.
Decision: retry
Reason: Users need exact detection and repair guidance for current binary path, current binary version, npm latest, install manager, and stale launcher state.
Follow-up: Add upgrade-path doctor/preflight checks and record evidence here.

## 2026-04-30 - stale PATH launcher diagnostic

Hypothesis: Doctor/update can close the stale global launcher gap by warning on older PATH launchers while leaving normal update execution unblocked.
Baseline: The 2026-04-29 finding showed npm latest at 8.8.107 while a local global launcher could still report 8.8.106.
Change: Doctor diagnostics now compare the resolved PATH `clavue` launcher against the current runtime paths, execute that launcher with `--version`, and add a warning only when it reports an older version than the current runtime. Update reuses the same diagnostic warning surface.
Commands: `node --test tests/product-truth-surfaces.test.mjs`; spec/code-quality subagent review; `npm run rebuild:dist`; `node scripts/verify-dist.mjs`; `node --test tests/product-truth-surfaces.test.mjs tests/release-pipeline.test.mjs`.
Result: Focused product-truth tests passed 34/34; combined product-truth and release pipeline tests passed 55/55; dist rebuilt and verified.
Decision: keep
Reason: Users get direct repair guidance for stale npm/global launchers without changing install-manager semantics or blocking update.
Follow-up: Keep the release-preflight local launcher advisory as the broader live-environment check.

## 2026-04-30 - malformed package manifest visibility

Hypothesis: `/init` should make malformed root manifests visible in generated guidance instead of silently treating them as generic project facts.
Baseline: Invalid `package.json` content was swallowed and recorded as `Node package manifest`, which could mislead users during first-run setup.
Change: Malformed `package.json` now appears as `Malformed JSON package manifest` in `clavue.md` while `/init` still creates guidance successfully.
Commands: `node --test tests/init-command.test.mjs` red baseline failed 9/10 on the malformed manifest assertion; `npm run rebuild:dist && node --test tests/init-command.test.mjs`; `node scripts/verify-dist.mjs`.
Result: Focused init command tests passed 10/10 after the fix; dist rebuilt and verified.
Decision: keep
Reason: New users get a clear repair signal for broken project metadata without an avoidable first-run failure.
Follow-up: Add an unwritable-target regression that proves onboarding state is not marked complete after failed writes.

## 2026-04-30 - default-path offline smoke

| step | status | command | evidence | next action |
| --- | --- | --- | --- | --- |
| install-run | pass | node dist/cli.js --version | Shipped CLI entrypoint is the default executable surface and reports a version before loading the full app. | Keep dist entrypoint in release smoke coverage. |
| provider-profile-adoption | pass | clavue provider adopt --profile default-compatible | Provider setup is represented as profile adoption so compatible routes can start without editing environment variables by hand. | Use online provider validation before release credentials are available. |
| init-guidance | pass | clavue -p /init --permission-mode bypassPermissions --output-format text | /init creates or refreshes project guidance and records detected project commands. | Keep failure-state tests for unwritable and ambiguous workspace targets. |
| read | pass | clavue read package.json | Default path includes repository inspection before editing. | Preserve read-before-edit workflow in onboarding copy. |
| edit | pass | clavue edit sample.test.mjs | Default path includes a reversible local edit in a temp repository. | Keep edits constrained to temp smoke fixtures. |
| test | pass | node --test | Default path verifies the temp repository after the edit. | Expand online smoke only after deterministic offline coverage is stable. |
| continuation | pass | clavue --continue | Default path records continuation as a first-class long-session recovery step. | Pair with realistic long-session smoke in P2. |
| doctor-upgrade-diagnostics | pass | clavue doctor && clavue update --check | Default path ends with diagnostics for provider, install, and upgrade readiness. | Keep doctor and upgrade diagnostics visible in release reports. |

Result: 8/8 default-path steps passed in deterministic offline mode.
Decision: keep

## 2026-04-30 - /init failure-state and mixed-monorepo coverage

Hypothesis: `/init` should not mark onboarding complete after a failed guidance write, and ambiguous nested mixed-language workspaces should receive explicit monorepo guidance.
Baseline: Focused init tests failed 11/12 before the mixed-monorepo diagnostic was added; stdout only listed nested project candidates without the explicit mixed-monorepo signal.
Change: Added regression coverage for failed writes and mixed nested project types, and added a mixed-monorepo diagnostic when multiple nested project candidates exist without root project signals.
Commands: `node --test tests/init-command.test.mjs` red baseline failed 11/12 on `Mixed monorepo candidates detected`; `npm run rebuild:dist`; `node --test tests/init-command.test.mjs`.
Result: Focused init command tests passed 12/12 after the fix.
Decision: keep
Reason: First-run guidance now distinguishes workspace-container ambiguity from a concrete single project, and failed writes do not produce a completed onboarding state.
Follow-up: Keep `/init` diagnostics covered by the world-class eval runner.

## 2026-04-30 - default-path offline smoke

| step | status | command | evidence | next action |
| --- | --- | --- | --- | --- |
| install-run | pass | node dist/cli.js --version | Shipped CLI entrypoint is the default executable surface and reports a version before loading the full app. | Keep dist entrypoint in release smoke coverage. |
| provider-profile-adoption | pass | clavue provider adopt --profile default-compatible | Provider setup is represented as profile adoption so compatible routes can start without editing environment variables by hand. | Use online provider validation before release credentials are available. |
| init-guidance | pass | clavue -p /init --permission-mode bypassPermissions --output-format text | /init creates or refreshes project guidance and records detected project commands. | Keep failure-state tests for unwritable and ambiguous workspace targets. |
| read | pass | clavue read package.json | Default path includes repository inspection before editing. | Preserve read-before-edit workflow in onboarding copy. |
| edit | pass | clavue edit sample.test.mjs | Default path includes a reversible local edit in a temp repository. | Keep edits constrained to temp smoke fixtures. |
| test | pass | node --test | Default path verifies the temp repository after the edit. | Expand online smoke only after deterministic offline coverage is stable. |
| continuation | pass | clavue --continue | Default path records continuation as a first-class long-session recovery step. | Pair with realistic long-session smoke in P2. |
| doctor-upgrade-diagnostics | pass | clavue doctor && clavue update --check | Default path ends with diagnostics for provider, install, and upgrade readiness. | Keep doctor and upgrade diagnostics visible in release reports. |

Result: 8/8 default-path steps passed in deterministic offline mode.
Decision: keep

## 2026-05-01 - default-path offline-contract smoke

Evidence mode: offline-contract

| step | status | evidence mode | command | evidence | next action |
| --- | --- | --- | --- | --- | --- |
| install-run | pass | offline-contract | node dist/cli.js --version | Shipped CLI entrypoint is the default executable surface and reports a version before loading the full app. | Keep dist entrypoint in release smoke coverage. |
| provider-profile-adoption | pass | offline-contract | clavue provider adopt --profile default-compatible | Provider setup is represented as profile adoption so compatible routes can start without editing environment variables by hand. | Use online provider validation before release credentials are available. |
| init-guidance | pass | offline-contract | clavue -p /init --permission-mode bypassPermissions --output-format text | /init creates or refreshes project guidance and records detected project commands. | Keep failure-state tests for unwritable and ambiguous workspace targets. |
| read | pass | offline-contract | clavue read package.json | Default path includes repository inspection before editing. | Preserve read-before-edit workflow in onboarding copy. |
| edit | pass | offline-contract | clavue edit sample.test.mjs | Default path includes a reversible local edit in a temp repository. | Keep edits constrained to temp smoke fixtures. |
| test | pass | offline-contract | node --test | Default path verifies the temp repository after the edit. | Expand online smoke only after deterministic offline coverage is stable. |
| continuation | pass | offline-contract | clavue --continue | Default path records continuation as a first-class long-session recovery step. | Pair with realistic long-session smoke in P2. |
| doctor-upgrade-diagnostics | pass | offline-contract | clavue doctor && clavue update --check | Default path ends with diagnostics for provider, install, and upgrade readiness. | Keep doctor and upgrade diagnostics visible in release reports. |

Result: 8/8 default-path offline-contract steps passed in deterministic offline mode.
Decision: keep

## 2026-05-01 - default-path offline-contract smoke

Evidence mode: offline-contract

| step | status | evidence mode | command | evidence | next action |
| --- | --- | --- | --- | --- | --- |
| install-run | pass | offline-contract | node dist/cli.js --version | Shipped CLI entrypoint is the default executable surface and reports a version before loading the full app. | Keep dist entrypoint in release smoke coverage. |
| provider-profile-adoption | pass | offline-contract | clavue provider adopt --profile default-compatible | Provider setup is represented as profile adoption so compatible routes can start without editing environment variables by hand. | Use online provider validation before release credentials are available. |
| init-guidance | pass | offline-contract | clavue -p /init --permission-mode bypassPermissions --output-format text | /init creates or refreshes project guidance and records detected project commands. | Keep failure-state tests for unwritable and ambiguous workspace targets. |
| read | pass | offline-contract | clavue read package.json | Default path includes repository inspection before editing. | Preserve read-before-edit workflow in onboarding copy. |
| edit | pass | offline-contract | clavue edit sample.test.mjs | Default path includes a reversible local edit in a temp repository. | Keep edits constrained to temp smoke fixtures. |
| test | pass | offline-contract | node --test | Default path verifies the temp repository after the edit. | Expand online smoke only after deterministic offline coverage is stable. |
| continuation | pass | offline-contract | clavue --continue | Default path records continuation as a first-class long-session recovery step. | Pair with realistic long-session smoke in P2. |
| doctor-upgrade-diagnostics | pass | offline-contract | clavue doctor && clavue update --check | Default path ends with diagnostics for provider, install, and upgrade readiness. | Keep doctor and upgrade diagnostics visible in release reports. |

Result: 8/8 default-path offline-contract steps passed in deterministic offline mode.
Decision: keep

## 2026-05-06 - default-path offline-contract smoke

Evidence mode: offline-contract

| step | status | evidence mode | command | evidence | next action |
| --- | --- | --- | --- | --- | --- |
| install-run | pass | offline-contract | node dist/cli.js --version | Shipped CLI entrypoint is the default executable surface and reports a version before loading the full app. | Keep dist entrypoint in release smoke coverage. |
| provider-profile-adoption | pass | offline-contract | clavue provider adopt --profile default-compatible | Provider setup is represented as profile adoption so compatible routes can start without editing environment variables by hand. | Use online provider validation before release credentials are available. |
| init-guidance | pass | offline-contract | clavue -p /init --permission-mode bypassPermissions --output-format text | /init creates or refreshes project guidance and records detected project commands. | Keep failure-state tests for unwritable and ambiguous workspace targets. |
| read | pass | offline-contract | clavue read package.json | Default path includes repository inspection before editing. | Preserve read-before-edit workflow in onboarding copy. |
| edit | pass | offline-contract | clavue edit sample.test.mjs | Default path includes a reversible local edit in a temp repository. | Keep edits constrained to temp smoke fixtures. |
| test | pass | offline-contract | node --test | Default path verifies the temp repository after the edit. | Expand online smoke only after deterministic offline coverage is stable. |
| continuation | pass | offline-contract | clavue --continue | Default path records continuation as a first-class long-session recovery step. | Pair with realistic long-session smoke in P2. |
| doctor-upgrade-diagnostics | pass | offline-contract | clavue doctor && clavue update --check | Default path ends with diagnostics for provider, install, and upgrade readiness. | Keep doctor and upgrade diagnostics visible in release reports. |

Result: 8/8 default-path offline-contract steps passed in deterministic offline mode.
Decision: keep
