Start with your existing Probierz project.

First use, CLI, and Desktop#

Run `probierz onboarding --source /path/to/existing-probierz`, or use `probierz project adopt --source /path/to/existing-probierz` at any time. In Probierz Desktop, choose **Choose project** on first use or open **Workspace → Adopt existing project**. **Skip** keeps an empty, usable destination.

Desktop starts Probierz's local `serve` process on `127.0.0.1` with an ephemeral port and calls its project-adoption API. The CLI, onboarding, and GUI therefore use one core parser and transaction.

probierz project adopt --source /absolute/path/existing-probierz
probierz project adoptions

Accepted repository shape#

The selected path must be a Git repository with one or more validated `apps/<appId>/probierz.yaml` manifests. Every surface's declared spec must exist beneath that surface's established Probierz package directory.

• Application definitions: every regular, non-symlink file beneath `apps/`.
• Journey specs and their helpers: regular files beneath `packages/<surface>/test/specs`, `packages/<surface>/tests`, or `packages/<surface>/specs` for supported packages.
• The source repository's own `apps/.adoptions.json` is reported as skipped local history; it is never nested into the destination.
• Malformed manifests, app-directory ID mismatches, missing declared specs, symlinks, and special filesystem entries reject the selection before mutation.

Duplicates, conflicts, and replacement#

Probierz identifies a source by its canonical path and a SHA-256 digest over ordered definition paths, modes, and bytes. Repeating the same source and content is `unchanged`. The destination preserves existing files by default.

Any differing destination is returned in the complete conflict list and no file changes. After review, `--replace` or **Replace these reviewed definitions** may replace unmanaged files and same-source files that still match their retained content and mode. A path owned by another source is always a conflict. Locally changed adopted content or modes are retained and refused, including files that disappeared upstream.

Retained state and execution boundary#

Accepted adoption writes `apps/.adoptions.json` with the canonical source path, content digest, timestamp, application IDs, and every retained file digest. Definitions are staged and moved as one rollback-capable transaction, so an invalid or conflicting selection leaves no partial import.

Results report imported, unchanged, removed, conflicting, and rejected counts without printing definition or credential contents. Adoption never runs a spec, creates evidence, installs a browser or driver, opens an app, or touches the source repository. Execution remains the separate `probierz run` operation.