Transcript Lake

Documentation / CLI

transcript-lake onboarding

Walk the first-use journey and optionally adopt one discovered source through the canonical ingestion boundary.

Invocation#

sh
transcript-lake [--data-dir <path>] onboarding [--source <runtime> --root <discovered-root>] [--skip-source] [--reset] [--yes] [--json]

Purpose#

Present the published first-use journey screen by screen, and on its source step either adopt one discovered root through the same masking, cursor and Oko boundary as adopt, or leave an empty usable Lake. First success is recorded only when a source was really adopted; a walkthrough viewed, or a source step skipped, records no first-success fact. The journey itself is on the Onboarding page.

Inputs and options#

  • --source <runtime> and --root <discovered-root> name the one source to adopt; they travel together. Without them the source step reports the exact adopt command to run and stops there.
  • --skip-source leaves an empty usable Lake and does not claim first success; it cannot be combined with --source.
  • --reset discards the recorded attempt and replays the journey from its entry screen.
  • --yes answers the Enter prompts; --json emits the whole walk as one object and never prompts, because machine output has no reader to press Enter.
  • Global --data-dir <path> selects the Lake root for this invocation.

Output and state effect#

Writes the journey's progress as it advances, so a later run resumes rather than restarts; a journey already completed is reported as such and nothing more is written. Progress belongs to the operator on this machine, not to a Lake root: it is kept in $XDG_STATE_HOME/transcript-lake/onboarding.json (~/.local/state when XDG_STATE_HOME is unset or empty), keyed by USER and the machine name, so a second --data-dir is still the same first use. Adopting a source writes exactly what adopt writes and persists the selected native identity in sources.json. Human output prints each screen with its title, body and command; JSON emits one object holding every screen shown, the notes and the evidence recorded.

Exact refusals#

  • onboarding requires --source and --root together when only one of the pair is given.
  • use either --source/--root or --skip-source when both are given.
  • A positional argument is refused as onboarding accepts flags only; an unrecognized flag as unknown onboarding flag: --wat; a repeated one as onboarding received duplicate <flag>.
  • onboarding progress is recorded per operator, and USER names none: <cause> when the environment sets no USER: progress belongs to one operator on one machine, so without one there is nobody to record it for.
  • The adoption refusals of adopt when the named source cannot be ingested; source adoption returned without a persisted selection and an adopted source does not satisfy the published journey when it was ingested but the journey's evidence was not met.
  • published first-success evidence was not satisfied, published journey has no eligible next screen, published onboarding screen has no kind, onboarding state has no current screen, onboarding state is not an object — a journey definition or a recorded state that does not match the published journey.

All long flags are exact and single-use. A value flag never consumes another --flag. Global --data-dir may appear anywhere in the invocation, must appear once, and selects an absolute root.

Back to the complete CLI command tree.