skryba onboarding

Show the first-use walkthrough: three screens that say what the commands are, where the human boundary lies, and how to import a first draft; the walkthrough completes on its own once skryba draft import has retained a document.

Invocation

skryba onboarding [--reset]

Inputs and options

• --reset discards the recorded progress and evidence and starts from the first screen again.
• The global --text flag is accepted and changes nothing here: the walkthrough is prose for a person.

Behaviour

The journey is first-use, compiled into the binary from src/app/onboarding_first_use.json. Progress is kept in $XDG_STATE_HOME/skryba/onboarding.json, or $HOME/.local/state/skryba/onboarding.json when XDG_STATE_HOME is absent or empty, as skryba.onboarding-state.v1 with the current screen, a status of in_progress or completed, and the facts observed so far. If neither variable supplies a nonempty value, the command refuses instead of choosing the working directory.

Each run prints the current screen as == <title> == followed by its body. An explanation screen waits for Enter (Press Enter to continue.) and moves to the next screen, saving the state after every step, so the walkthrough can be left and resumed. The last screen is the first success: it asks for one skryba draft import <file>. When that import has not happened yet the command prints Run the command from this step, then run \skryba onboarding` again.and exits 0;draft importrecords the factdraft_importedinto the state (and says so on stderr:Onboarding first success recorded: draft_imported), and the next skryba onboardingprintsFirst success observed; onboarding is complete.` and marks the journey completed.

A completed journey prints Onboarding is complete. Use \skryba onboarding --reset` to show it again.and exits 0.--resetprintsOnboarding progress and evidence reset.and shows the first screen. A state file written by an older journey version is replaced by a fresh one without--reset`.

Refusals

• HOME is unavailable; set HOME or XDG_STATE_HOME to keep onboarding progress: neither location variable supplies a nonempty value.
• check onboarding state <path>: …: filesystem inspection failed; this is not treated as absent progress.
• stored onboarding state identity mismatch; use --reset to replace it: the state file names another product or journey.
• read onboarding state <path>: … / parse onboarding state: the state file cannot be read or is not JSON.
• onboarding journey identity mismatch, onboarding screen is unavailable: <id>, onboarding screen has no next screen: the compiled journey is inconsistent, which a release does not ship.

Refusals exit 1; nothing else is written when one occurs.

State-location qualification

cargo test --test onboarding-home invokes the real CLI with isolated HOME, XDG_STATE_HOME and working directories. It covers an empty state-home refusal without HOME, recovery through a declared HOME, explicit state-home selection and byte-preserving resume from another working directory. It retains the committed source revision, binary digest, actual commands, statuses and output in .build/onboarding-home-*/report.json; only its owned workspace is removed. This does not exercise draft import, model services or the desktop UI.