docs(site): tighten evaluation-ready public surfaces

Author: eblackrps

CHANGELOG.md

@@ -21,7 +21,7 @@ This changelog tracks published releases and the major implementation milestones
 ### Lab, Contract, And Release Surface
 - added a deterministic `examples/lab` end-to-end smoke flow for workspace creation through report export
 - updated the published OpenAPI contract, quickstart flow, lab assets, configuration guidance, and operator docs to match the new workspace APIs and runtime auth flow
-- added v1.6.0 release-note draft material and release-facing screenshot assets for the workspace-first operator application
+- added v1.6.0 release-note material and release-facing screenshot assets for the workspace-first operator application
 
 ## [1.5.0] - 2026-04-08
 
@@ -31,7 +31,7 @@ This changelog tracks published releases and the major implementation milestones
 
 ### API And Dashboard Trust Surfaces
 - hardened the API contract with structured JSON error responses, stabilized migration command acknowledgements, and updated OpenAPI coverage for the operator-facing routes
-- improved dashboard-side error handling so settings and report workflows preserve request correlation and support-grade failure detail instead of flattening backend errors into generic strings
+- improved dashboard-side error handling so settings and report workflows preserve request correlation and operator-facing failure detail instead of flattening backend errors into generic strings
 
 ### Documentation And Operator Readiness
 - added presenter-ready demo assets, real-user validation templates, and commercialization decision guidance to support design-partner conversations and pilot packaging
@@ -98,7 +98,7 @@ This changelog tracks published releases and the major implementation milestones
 
 ## [1.1.0] - 2026-04-05
 
-### Current Stable Surface
+### Current Tagged Feature Set
 - multi-platform discovery for VMware, Proxmox, Hyper-V, KVM, Nutanix, and Veeam-related backup inventory
 - dependency graph construction across workload, network, storage, and backup metadata
 - declarative cold and warm migration orchestration with preflight checks, execution windows, approval gates, checkpoints, resume support, verification, and rollback

CONTRIBUTING.md

@@ -1,60 +1,71 @@
 # Contributing
 
-## How To Report Bugs
-Open a GitHub issue with a clear summary, the environment you were using, reproduction steps, expected behavior, and the actual behavior you observed. If logs or screenshots help clarify the problem, include them with any secrets removed. Use the bug-report template when possible so maintainers get the minimum triage context up front.
+## Before You Start
 
-## How To Request Features
-Open a GitHub issue describing the problem you are trying to solve, why existing behavior is not enough, and what a successful outcome would look like. Feature requests with operational context are easier to prioritize than solution-only requests.
+Viaduct's public-facing materials are part of the product surface. If your change affects operator behavior, update the relevant docs, examples, and release-facing assets in the same change.
+
+## Reporting Bugs
+
+Open a GitHub issue with:
+- a clear summary
+- your environment
+- reproduction steps
+- expected behavior
+- actual behavior
+
+If logs or screenshots help, include them with secrets removed.
+
+## Requesting Features
+
+Open a GitHub issue that explains the operator or contributor problem first. Narrow, workflow-grounded requests are easier to evaluate than solution-only requests.
 
 ## Development Setup
+
 - Go 1.24 or newer
-- Node.js 20 or newer for the dashboard
-- `make` (preferred, optional on Windows if you run the underlying commands directly)
+- Node.js 20.19 or newer for the dashboard
+- `make` for the standard workflow
 - `golangci-lint`
 
-Clone the repository, install dependencies with `go mod tidy`, and use the Make targets for the standard workflow. The quickest release-candidate validation path is:
+Typical setup:
 
 ```bash
 go mod tidy
+make build
+```
+
+For a fuller local check:
+
+```bash
 make release-gate
 ```
 
-If you use Codex for repo tasks, the bootstrap script in `.codex/setup.sh` installs the expected linter version in supported environments.
+## Workflow Expectations
 
-## Workflow
 1. Fork the repository.
-2. Create a feature branch for your work.
-3. Make your changes with focused commits and update docs, examples, and sample configs when public behavior changes.
-4. Run `go test ./... -v -race`, `go vet ./...`, `make build`, and `cd web && npm run build` for the surfaces you touched.
-5. Run `make release-gate` before asking for review when your change affects release, packaging, dashboard, migrations, tenant behavior, plugins, or docs.
-6. Submit a pull request with context about the problem, solution, compatibility impact, and verification.
+2. Create a focused branch.
+3. Make the smallest coherent set of changes.
+4. Update docs, examples, sample configs, and public assets when operator-visible behavior changes.
+5. Run the verification commands for the surfaces you touched.
+6. Submit a pull request with scope, rationale, compatibility impact, and validation notes.
+
+## Verification Expectations
+
+- Run `go test ./... -v -race`, `go vet ./...`, `make build`, and `cd web && npm run build` for the relevant surfaces.
+- Run `make release-gate` before asking for review when the change affects release, packaging, dashboard, migrations, tenants, plugins, docs, or public assets.
+- Add regression coverage for bug fixes.
+
+## Compatibility And Scope
 
-## Compatibility Expectations
 - Preserve API, state-store, and plugin compatibility where possible.
-- Document any migration requirement or operator-facing behavior change in the PR and relevant docs.
-- Keep tenant boundaries strict and explicit in tests and implementation.
-- Add regression coverage for every bug fix.
-
-## Documentation And Examples
-- Top-level docs such as `README.md`, `INSTALL.md`, `QUICKSTART.md`, `UPGRADE.md`, `RELEASE.md`, `SUPPORT.md`, and `SECURITY.md` are part of the public product surface.
-- Keep detailed docs under `docs/` aligned with the public entrypoint docs at the repo root.
-- Historical phase documents under `docs/roadmaps/` are archives. Update them only to clarify shipped outcomes, not to describe current active work.
-- Example configs and lab assets should remain runnable and parseable. Prefer realistic examples over pseudo-configuration.
-
-## Testing Expectations
-- Table-driven Go tests are the default.
-- Integration tests live under `tests/integration/`.
-- Release and packaging changes should include validation for examples, install flows, or generated artifacts where practical.
-- If you touch dashboard code, run `cd web && npm run build`.
-
-## Codebase Orientation
+- Keep tenant boundaries strict and explicit.
+- Prefer extending existing packages over introducing parallel abstractions.
+- Keep the public maturity language honest. Use evaluation-ready or more cautious wording unless stronger proof exists.
+
+## Helpful References
+
 - Architecture overview: [docs/architecture.md](docs/architecture.md)
 - Codebase map: [docs/reference/codebase-map.md](docs/reference/codebase-map.md)
 - Configuration guide: [docs/reference/configuration.md](docs/reference/configuration.md)
 - Plugin author guide: [docs/reference/plugin-author-guide.md](docs/reference/plugin-author-guide.md)
-
-## Support
-For usage questions, evaluation help, or contribution process questions, start with [SUPPORT.md](SUPPORT.md).
-
-## Security
-If you believe you have found a security issue, follow the process in [SECURITY.md](SECURITY.md) instead of opening a public bug report.
+- Support and contributor help: [SUPPORT.md](SUPPORT.md)
+- Security process: [SECURITY.md](SECURITY.md)

INSTALL.md

@@ -1,8 +1,9 @@
 # Installation
 
-This document is the top-level installation entrypoint for Viaduct. For a deeper walkthrough, see [docs/getting-started/installation.md](docs/getting-started/installation.md).
+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.
 
 ## Requirements
+
 - Go 1.24 or newer
 - Node.js 20.19 or newer if you want to build the dashboard
 - `make` for the standard workflow
@@ -29,7 +30,7 @@ npm run build
 ## Install From A Release Bundle
 
 Release bundles produced by `make package-release-matrix` include:
-- the CLI binary
+- CLI binary
 - built web assets
 - docs and sample configs
 - install scripts
@@ -55,6 +56,11 @@ viaduct version
 viaduct --help
 ```
 
-The fastest no-infrastructure evaluation path is the local KVM lab in [examples/lab](examples/lab). Continue with [QUICKSTART.md](QUICKSTART.md).
+## Recommended Next Step
+
+The cleanest evaluation path is still the local lab in [examples/lab](examples/lab). Continue with [QUICKSTART.md](QUICKSTART.md).
 
-Reference deployment assets for Docker Compose, systemd, and Kubernetes live in [examples/deploy](examples/deploy). Start with [examples/deploy/README.md](examples/deploy/README.md) and use the Kubernetes notes in [examples/deploy/kubernetes/README.md](examples/deploy/kubernetes/README.md) if you want a pilot-style in-cluster evaluation.
+For packaged or persistent evaluation environments:
+- use PostgreSQL instead of the in-memory store
+- prefer service-account keys for normal operator access
+- keep the Vite dev server out of any shared or internet-facing environment

QUICKSTART.md

@@ -1,13 +1,10 @@
 # Quickstart
 
-This is the fastest way to evaluate Viaduct from source without a live hypervisor.
+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.
 
-The default first-run path is now the workspace-first operator flow:
+## Maturity Note
 
-1. bootstrap the local lab tenant and service account
-2. sign into the dashboard with a runtime key
-3. create a pilot workspace
-4. discover, inspect, simulate, save a plan, and export a report
+Viaduct is evaluation-ready. Start in the lab or a supervised pilot first.
 
 ## 1. Build The CLI
 
@@ -17,16 +14,24 @@ make build
 ./bin/viaduct version
 ```
 
-## 2. Seed A Local Config
+On Windows PowerShell:
+
+```powershell
+go mod tidy
+make build
+.\bin\viaduct.exe version
+```
+
+## 2. Seed The Local Config
 
 ```bash
 mkdir -p ~/.viaduct
 cp examples/lab/config.yaml ~/.viaduct/config.yaml
 ```
 
-The lab config points the KVM source at the local fixture set. For any non-demo environment, configure `state_store_dsn` and use PostgreSQL for persistence.
+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 With An Admin Bootstrap Key
+## 3. Start The API
 
 ```bash
 export VIADUCT_ADMIN_KEY=lab-admin
@@ -40,83 +45,66 @@ $env:VIADUCT_ADMIN_KEY = "lab-admin"
 .\bin\viaduct.exe serve-api --port 8080
 ```
 
-## 4. Create The Lab Tenant
+## 4. Seed The Lab Tenant And Service Account
 
 ```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
-```
-
-This seeds the deterministic tenant key `lab-tenant-key`.
 
-## 5. Create The Lab Service Account
-
-```bash
 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
 ```
 
-This seeds the deterministic service-account key `lab-operator-key`.
+This creates:
+- tenant key: `lab-tenant-key`
+- service-account key: `lab-operator-key`
 
-## 6. Start The Dashboard
+Use the service-account key for the normal operator flow. Keep the tenant key for bootstrap or break-glass admin work.
+
+## 5. Start The Dashboard
 
 ```bash
 cd web
 npm ci
 npm run dev
 ```
 
-The dashboard expects the API at `/api` and opens on the pilot workspace route. The first screen is a runtime auth bootstrap flow.
+Open the Vite URL shown in the terminal. The dashboard starts on the pilot workspace route and asks for a runtime key.
 
 Authenticate with:
-- `Service account`: `lab-operator-key`
-- `Tenant key`: `lab-tenant-key`
-
-For normal dashboard and pilot use, prefer `VITE_VIADUCT_SERVICE_ACCOUNT_KEY`. Keep `VITE_VIADUCT_API_KEY` for tenant bootstrap or break-glass admin access.
-
-If you create additional tenants or service accounts, verify the active identity with:
-
-```bash
-curl -H "X-Service-Account-Key: <service-account-key>" http://localhost:8080/api/v1/tenants/current
-```
+- preferred: `lab-operator-key`
+- bootstrap only: `lab-tenant-key`
 
-Use the tenant key only when you are bootstrapping the tenant or intentionally using tenant-admin access:
-
-```bash
-curl -H "X-API-Key: <tenant-key>" http://localhost:8080/api/v1/tenants/current
-```
-
-## 7. Run The Workspace-First Flow
+## 6. Run The Workspace-First Flow
 
 In the dashboard:
 
 1. Create the first pilot workspace from the prefilled lab defaults.
 2. Run discovery.
-3. Inspect the discovered workloads and dependency graph.
-4. Run simulation.
+3. Inspect the workload and graph state.
+4. Run readiness simulation.
 5. Save the plan.
 6. Export the pilot report.
 
-The seeded API equivalent for workspace creation lives in [examples/lab/pilot-workspace-create.json](examples/lab/pilot-workspace-create.json).
+The matching seeded request body for API-driven creation is in [examples/lab/pilot-workspace-create.json](examples/lab/pilot-workspace-create.json).
 
-## 8. Optional CLI Corroboration
+## 7. Optional CLI Corroboration
 
 ```bash
 ./bin/viaduct discover --type kvm --source examples/lab/kvm --save
 ./bin/viaduct plan --spec examples/lab/migration-window.yaml
 ```
 
 ## Next Steps
-- Review [docs/operations/pilot-workspace-flow.md](docs/operations/pilot-workspace-flow.md) for the full workspace-first operator guide.
-- Review [docs/operations/migration-operations.md](docs/operations/migration-operations.md) for execution and rollback workflows.
-- Review [docs/operations/backup-portability.md](docs/operations/backup-portability.md) for Veeam portability guidance.
-- Review [docs/operations/multi-tenancy.md](docs/operations/multi-tenancy.md) before enabling shared-tenant operation.
-- Review [docs/operations/auth-role-audit-model.md](docs/operations/auth-role-audit-model.md) for the early-product trust model and attribution boundaries.
-- Review [examples/deploy/README.md](examples/deploy/README.md) if you want to move from local evaluation into a packaged pilot environment.
-- Review [examples/plugin-example/README.md](examples/plugin-example/README.md) if you want to validate plugin-backed connector loading.
+
+- Detailed quickstart: [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)
+- Pilot workspace guide: [docs/operations/pilot-workspace-flow.md](docs/operations/pilot-workspace-flow.md)
+- Installation guide: [INSTALL.md](INSTALL.md)
+- Configuration reference: [docs/reference/configuration.md](docs/reference/configuration.md)
+- Deployment examples: [examples/deploy/README.md](examples/deploy/README.md)