docs(dashboard): align v2.0.0 startup and release surfaces

Author: eblackrps

CHANGELOG.md

@@ -8,6 +8,24 @@ This changelog tracks published releases and the major implementation milestones
 
 - No unreleased changes yet.
 
+## [2.0.0] - 2026-04-11
+
+### Installation, Startup, And First Run
+- added `viaduct start`, `viaduct stop`, and `viaduct doctor` so the default local experience is now one WebUI-first runtime instead of a manual multi-step API bootstrap
+- taught `viaduct start` to generate the default local lab config automatically when `~/.viaduct/config.yaml` is missing and to point it at the shipped KVM fixtures
+- added recorded local runtime status reporting through `viaduct status --runtime`, including the WebUI URL, API URL, PID, and runtime log location
+- updated the Unix and Windows install scripts to copy bundled docs, examples, and configs together and to generate a starter config for the installed lab path
+
+### Dashboard, Site, And Product Surfaces
+- aligned the dashboard runtime auth flow with the built-in local single-user fallback so the default local lab path no longer requires pasted browser credentials
+- synchronized the dashboard, root docs, lab docs, troubleshooting guidance, deployment examples, public site, and release-facing screenshots around the new local startup model
+- refreshed the public website and social-card copy to emphasize installation, startup, workspace progression, and controlled operator workflows more clearly
+
+### Verification, Packaging, And Release Readiness
+- extended automated CLI coverage with tests around local runtime paths and starter-config generation
+- kept `make release-gate`, `make certification-test`, `make plugin-check`, `make contract-check`, and `make package-release-matrix` aligned with the same packaged product surface
+- added `v2.0.0` release notes and synchronized visible version markers, screenshot labels, and package metadata around the new release
+
 ## [1.9.0] - 2026-04-11
 
 ### Install, Packaging, And Startup Flow

INSTALL.md

@@ -1,6 +1,6 @@
 # Installation
 
-This is the top-level installation entrypoint for Viaduct. Use it together with [QUICKSTART.md](QUICKSTART.md) if you want the fastest evaluation path, or see [docs/getting-started/installation.md](docs/getting-started/installation.md) for the deeper walkthrough.
+This is the top-level installation entrypoint for Viaduct. Use it with [QUICKSTART.md](QUICKSTART.md) for the fastest browser-first path, or see [docs/getting-started/installation.md](docs/getting-started/installation.md) for the deeper walkthrough.
 
 ## Requirements
 
@@ -20,14 +20,15 @@ make web-build
 ./bin/viaduct version
 ```
 
-Start the packaged local operator surface:
+Start the local operator runtime:
 
 ```bash
-export VIADUCT_ADMIN_KEY=change-me
-./bin/viaduct serve-api --port 8080
+./bin/viaduct start
 ```
 
-Then open [http://localhost:8080](http://localhost:8080).
+On a fresh source checkout, `viaduct start` generates the default local lab config when `~/.viaduct/config.yaml` is missing, serves the built dashboard and API together, and prints the WebUI URL.
+
+The default local URL is [http://127.0.0.1:8080](http://127.0.0.1:8080).
 
 ## Install From A Release Bundle
 
@@ -44,31 +45,40 @@ Release bundles produced by `make package-release-matrix` include:
 On POSIX systems:
 
 ```bash
-PREFIX=/usr/local ./install.sh ./bin/viaduct ./web
+PREFIX=/usr/local ./install.sh ./bin/viaduct ./web ./configs ./examples ./docs
 ```
 
 On Windows PowerShell:
 
 ```powershell
-.\install.ps1 -SourceBin .\bin\viaduct.exe -SourceWeb .\web -Prefix "$env:LOCALAPPDATA\\Viaduct"
+.\install.ps1 -SourceBin .\bin\viaduct.exe -SourceWeb .\web -SourceConfigs .\configs -SourceExamples .\examples -SourceDocs .\docs -Prefix "$env:LOCALAPPDATA\\Viaduct"
 ```
 
-After install:
+Both install scripts copy the CLI, built dashboard assets, docs, configs, and examples into one predictable layout. They also create a starter config that points at the installed lab fixtures when no config already exists at the install location.
+
+After install, start Viaduct with the config path printed by the installer. For example:
 
 ```bash
-viaduct serve-api --port 8080
+viaduct start --config /usr/local/etc/viaduct/config.yaml
+```
+
+On Windows, the equivalent installed command is typically:
+
+```powershell
+viaduct.exe start --config "$env:LOCALAPPDATA\Viaduct\etc\viaduct\config.yaml"
 ```
 
-Then open [http://localhost:8080](http://localhost:8080).
+The default local URL remains [http://127.0.0.1:8080](http://127.0.0.1:8080).
 
 ## Verify The Install
 
 ```bash
 viaduct version
 viaduct --help
+viaduct doctor
 ```
 
-When built dashboard assets are present, the same `viaduct serve-api` process serves the dashboard shell at `/` and the API under `/api/v1/`.
+When built dashboard assets are present, Viaduct serves the dashboard shell at `/` and the API under `/api/v1/`.
 
 ## Recommended Next Step
 
@@ -81,3 +91,4 @@ For packaged or persistent evaluation environments:
 - set `VIADUCT_WEB_DIR` only when you keep built dashboard assets in a non-standard location
 - tune `VIADUCT_WORKSPACE_JOB_TIMEOUT` if discovery or planning jobs need a different server-side timeout budget
 - keep the Vite dev server out of any shared or internet-facing environment
+- use `viaduct serve-api` directly for service, container, or intentionally headless deployments

QUICKSTART.md

@@ -2,9 +2,7 @@
 
 This is the fastest source-based evaluation path for Viaduct. It uses the local lab so you can reach the workspace-to-report flow without a live hypervisor estate.
 
-## Maturity Note
-
-Viaduct is in active development. Start in the lab or a supervised pilot first.
+The default operator path is now browser-first: start the local runtime, open the WebUI, create a workspace, discover, inspect, simulate, save a plan, and export a report.
 
 ## 1. Build Viaduct
 
@@ -13,6 +11,7 @@ go mod tidy
 make build
 make web-build
 ./bin/viaduct version
+./bin/viaduct start
 ```
 
 On Windows PowerShell:
@@ -22,64 +21,20 @@ go mod tidy
 make build
 make web-build
 .\bin\viaduct.exe version
+.\bin\viaduct.exe start
 ```
 
-## 2. Seed The Local Config
-
-```bash
-mkdir -p ~/.viaduct
-cp examples/lab/config.yaml ~/.viaduct/config.yaml
-```
-
-The lab config uses the local KVM fixture set. For any persistent non-demo environment, configure `state_store_dsn` and use PostgreSQL.
-
-## 3. Start The API
-
-```bash
-export VIADUCT_ADMIN_KEY=lab-admin
-./bin/viaduct serve-api --port 8080
-```
-
-On Windows PowerShell:
-
-```powershell
-$env:VIADUCT_ADMIN_KEY = "lab-admin"
-.\bin\viaduct.exe serve-api --port 8080
-```
-
-When built dashboard assets are present, the same process serves the WebUI at [http://localhost:8080](http://localhost:8080). If you serve the dashboard from a different origin, set `VIADUCT_ALLOWED_ORIGINS` before starting the API.
-
-## 4. Seed The Lab Tenant And Service Account
+On a fresh source checkout, `viaduct start` writes `~/.viaduct/config.yaml` automatically if it does not exist and points it at the shipped `examples/lab/kvm` fixtures.
 
-```bash
-curl -X POST \
-  -H "X-Admin-Key: lab-admin" \
-  -H "Content-Type: application/json" \
-  --data @examples/lab/tenant-create.json \
-  http://localhost:8080/api/v1/admin/tenants
-
-curl -X POST \
-  -H "X-API-Key: lab-tenant-key" \
-  -H "Content-Type: application/json" \
-  --data @examples/lab/service-account-create.json \
-  http://localhost:8080/api/v1/service-accounts
-```
+For any persistent non-demo environment, configure `state_store_dsn` and use PostgreSQL instead of the in-memory store.
 
-This creates:
-- tenant key: `lab-tenant-key`
-- service-account key: `lab-operator-key`
+## 2. Open The WebUI
 
-Use the service-account key for the normal operator flow. Keep the tenant key for bootstrap or break-glass admin work.
+Open [http://127.0.0.1:8080](http://127.0.0.1:8080). The same local runtime serves the WebUI at `/` and the API at `/api/v1/`.
 
-## 5. Open The Dashboard
+For the default local lab path, the dashboard can use the built-in single-user fallback and does not require a pasted browser key.
 
-Open [http://localhost:8080](http://localhost:8080). The dashboard starts on the pilot workspace route and asks for a runtime key.
-
-Authenticate with:
-- preferred: `lab-operator-key`
-- bootstrap only: `lab-tenant-key`
-
-The dashboard stores the runtime key in session storage by default. Use the "Remember this browser" option only when you intentionally want the browser to keep a local copy across restarts on a trusted workstation.
+If you intentionally configure tenant keys or service-account keys, the runtime bootstrap screen remains available. The browser stores runtime credentials in session storage by default and offers an explicit remember option for trusted workstations.
 
 If you want the Vite development server instead of the packaged local shell:
 
@@ -89,9 +44,9 @@ npm ci
 npm run dev
 ```
 
-Use that only for frontend development. The default operator path is the same-origin dashboard served by `viaduct serve-api`.
+Use that only for frontend development. The default operator path is the same-origin dashboard served by `viaduct start`.
 
-## 6. Run The Workspace-First Flow
+## 3. Run The Workspace-First Flow
 
 In the dashboard:
 
@@ -104,7 +59,20 @@ In the dashboard:
 
 The matching seeded request body for API-driven creation is in [examples/lab/pilot-workspace-create.json](examples/lab/pilot-workspace-create.json).
 
-## 7. Optional CLI Corroboration
+## 4. Check The Local Runtime
+
+```bash
+./bin/viaduct status --runtime
+./bin/viaduct doctor
+```
+
+Stop the local runtime when you are finished:
+
+```bash
+./bin/viaduct stop
+```
+
+## 5. Optional CLI Corroboration
 
 ```bash
 ./bin/viaduct discover --type kvm --source examples/lab/kvm --save

README.md

@@ -1,29 +1,28 @@
 # Viaduct
-> Open-source control plane for mixed virtualization discovery, planning, and supervised migration operations.
+> Open-source control plane for virtualization migration assessment, planning, and controlled operator execution.
 
 [![CI](https://github.com/eblackrps/Viaduct/actions/workflows/ci.yml/badge.svg)](https://github.com/eblackrps/Viaduct/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/eblackrps/Viaduct)](https://github.com/eblackrps/Viaduct/blob/main/LICENSE)
 
-Viaduct helps operators understand mixed virtualization estates before they commit to a migration path. The repository combines a Go backend, REST API, CLI, React dashboard, and a standalone public site around one shared model for discovery, dependency-aware planning, migration readiness, saved pilot workspaces, and exported operator evidence.
+Viaduct helps operators discover mixed virtualization estates, map dependencies, build migration plans, and manage controlled migration work from one shared backend model. The repository combines a Go backend, REST API, CLI, React dashboard, and standalone public site around the same persisted inventory, workspace, planning, and reporting surfaces.
 
-## Current Status
+## Current Focus
 
-Viaduct is in active development. The strongest current story is:
-- mixed-estate discovery
-- dependency-aware assessment
-- readiness and simulation
-- supervised pilot planning
-- operator-visible reporting and export
+Viaduct is built for operators who need:
+- mixed-estate discovery and inventory normalization
+- dependency-aware migration assessment
+- readiness and planning discipline before cutover work starts
+- controlled, reviewable operator workflows with exported evidence
 
-The default first-run experience is the pilot workspace flow: create workspace, discover, inspect, simulate, save plan, and export report. Start in the local lab or a supervised pilot environment first. Do not assume unattended migration breadth across every connector pair.
+The default first-run experience is the WebUI-first workspace flow: start Viaduct, create a workspace, discover, inspect, simulate, save a plan, and export a report. The local lab remains the fastest path from fresh clone to a working dashboard and API.
 
 ## Why Viaduct
 
 Many teams do not need more abstract migration talk. They need to know what exists, what depends on what, what should move first, and what evidence is good enough to approve a pilot. Viaduct is aimed at that planning and handoff gap.
 
 It is strongest when operators need:
 - one normalized inventory across mixed platforms
-- dependency context before planning a first wave
+- dependency context before sequencing migration work
 - a persisted assessment record instead of disconnected notes and screenshots
 - a CLI, API, and dashboard that reflect the same state
 
@@ -53,39 +52,31 @@ It is strongest when operators need:
 The cleanest path is the local lab in [examples/lab](examples/lab).
 
 ```bash
-mkdir -p ~/.viaduct
-cp examples/lab/config.yaml ~/.viaduct/config.yaml
 make build
 make web-build
 ./bin/viaduct version
-
-export VIADUCT_ADMIN_KEY=lab-admin
-./bin/viaduct serve-api --port 8080
+./bin/viaduct start
 ```
 
-In another terminal:
+On a fresh source checkout, `viaduct start`:
+- creates `~/.viaduct/config.yaml` automatically when it is missing
+- points that config at the shipped `examples/lab/kvm` fixtures
+- serves the built dashboard and API together at [http://127.0.0.1:8080](http://127.0.0.1:8080)
+- opens the WebUI automatically on interactive local runs when practical
 
-```bash
-curl -X POST \
-  -H "X-Admin-Key: lab-admin" \
-  -H "Content-Type: application/json" \
-  --data @examples/lab/tenant-create.json \
-  http://localhost:8080/api/v1/admin/tenants
-
-curl -X POST \
-  -H "X-API-Key: lab-tenant-key" \
-  -H "Content-Type: application/json" \
-  --data @examples/lab/service-account-create.json \
-  http://localhost:8080/api/v1/service-accounts
-```
+For the default local lab path, the dashboard can use the built-in single-user fallback and does not require a pasted browser key. Tenant keys and service-account keys remain supported for multi-tenant, packaged, and pilot environments.
 
-Then open [http://localhost:8080](http://localhost:8080), sign in with `lab-operator-key`, and run the workspace-first flow.
+Use these companion commands when you need them:
 
-`viaduct serve-api` now serves the built dashboard automatically when assets are present in `web/dist`, a packaged `web/` directory, or an installed `share/viaduct/web` layout. If you prefer the Vite development server while changing frontend code, that flow still lives in [web/README.md](web/README.md).
+```bash
+./bin/viaduct status --runtime
+./bin/viaduct doctor
+./bin/viaduct stop
+```
 
-The runtime bootstrap stores keys in the browser session by default. Use the optional remember toggle only on a trusted workstation.
+`viaduct serve-api` remains the lower-level API command for container, service, and intentionally headless deployments. It still serves the built dashboard automatically when assets are present in `web/dist`, a packaged `web/` directory, or an installed `share/viaduct/web` layout. If you prefer the Vite development server while changing frontend code, that flow still lives in [web/README.md](web/README.md).
 
-If you serve the dashboard from a non-default origin, configure `VIADUCT_ALLOWED_ORIGINS` on the API so the browser can reach tenant-protected routes. The same-origin packaged and local built path on `http://localhost:8080` does not need that override.
+If you serve the dashboard from a different browser origin, configure `VIADUCT_ALLOWED_ORIGINS` on the API so tenant-protected routes can be reached safely. The default same-origin local path on `http://127.0.0.1:8080` does not need that override.
 
 Use these entrypoints next:
 - Quickstart: [QUICKSTART.md](QUICKSTART.md)

RELEASE.md

@@ -17,7 +17,7 @@ On Windows, `make release-gate` still builds `bin/viaduct.exe`, but it validates
 2. Run `make release-gate`.
 3. Inspect the generated bundles in `dist/`.
 4. Verify `release-manifest.json`, `dependency-manifest.json`, and `SHA256SUMS.txt`.
-5. Smoke-test the packaged binary with `viaduct version`, `viaduct --help`, and `viaduct serve-api --port 8080` against the bundled dashboard assets when they are present.
+5. Smoke-test the packaged binary with `viaduct version`, `viaduct --help`, `viaduct doctor`, and the canonical local start flow (`viaduct start --config <installed-config> --detach --open-browser=false`) against the bundled dashboard assets when they are present.
 6. Confirm install docs, upgrade docs, rollback docs, deployment examples, and the pilot workspace guide still match the artifact layout.
 7. Confirm the release notes entry, changelog entry, and screenshot assets are present and aligned with the shipped workflow.
 8. Verify the plugin manifest check and OpenAPI contract check remain green.
@@ -40,7 +40,7 @@ The standalone public site under [`site/`](site/README.md) is published through
 - summarize operator-visible changes
 - document compatibility, migration, or upgrade concerns
 - call out any connector-specific caveats
-- include the workspace-first operator flow and runtime-auth bootstrap changes when they are part of the release
+- include the workspace-first operator flow, runtime-auth behavior, and local startup changes when they are part of the release
 - include current screenshot assets when the dashboard experience changed materially
 - use absolute GitHub URLs in the published GitHub release body when relative asset links would be ambiguous
 - update [CHANGELOG.md](CHANGELOG.md) with notable release information

SUPPORT.md

@@ -7,6 +7,7 @@ Viaduct is maintained as an open-source project with best-effort community suppo
 - Project overview and status: [README.md](README.md)
 - Install and first run: [INSTALL.md](INSTALL.md), [QUICKSTART.md](QUICKSTART.md)
 - Full docs map: [docs/README.md](docs/README.md)
+- Local runtime health: `viaduct status --runtime`, `viaduct doctor`
 - Troubleshooting: [docs/reference/troubleshooting.md](docs/reference/troubleshooting.md)
 - Support matrix: [docs/reference/support-matrix.md](docs/reference/support-matrix.md)
 

UPGRADE.md

@@ -18,6 +18,7 @@ This is the top-level upgrade entrypoint. Use it with [docs/operations/upgrade.m
 - Validate `/api/v1/about` after startup so the reported store backend and schema version match the expected deployment state.
 - If active migrations exist, finish or intentionally pause them before upgrading.
 - If you rely on packaged web assets, redeploy the matching dashboard bundle together with the binary.
+- If you use the standard local operator path, prefer `viaduct start` after upgrade. Keep `viaduct serve-api` for service, container, or intentionally headless deployments.
 
 ## Rollback
 

docs/README.md

@@ -7,6 +7,8 @@ This directory holds the deeper Viaduct documentation set. The repo-root docs ar
 - [Installation](getting-started/installation.md)
 - [Quickstart](getting-started/quickstart.md)
 
+The default local path now starts with `viaduct start`, opens the WebUI at `http://127.0.0.1:8080`, and uses the shipped lab fixtures when no local config exists yet.
+
 ## Operator Workflows
 
 - [Pilot Workspace Flow](operations/pilot-workspace-flow.md)