docs: add a short v5 start-here path (HACK-2195)

AGENTS.md

@@ -71,6 +71,7 @@ when testing Hack behavior. Keep host-native virtualization, routing/trust, and
 resource benchmarks on the host they qualify. Container checks do not replace them.
 
 For a behavior change, add or update the closest regression test and affected docs.
+A PR that changes user-visible behavior updates the affected short page in the v5 start-here path in the same PR.
 Run focused checks first, then required CI gates. Documentation-only changes need
 link, generation, and contract checks rather than artificial unit tests.
 After applicable checks pass, broaden or repeat them only for a new change, failure,

docs/cli.md

@@ -66,8 +66,8 @@ or opened, because it is the right URL; text output adds one warning, and `--jso
 Either is the usual sign of a machine set up by an earlier version that only resolves the
 older suffix: run `hack global install`, or give the project a host under a suffix that
 already resolves with `hack config set dev_host <name>.<suffix>`. A lookup that fails or
-times out is never reported as unresolved, and hosts outside Hack's own suffixes are left
-alone.
+times out is never reported as unresolved. The macOS `unconfigured` hint applies only
+to Hack-managed suffixes; an unknown result for another host is left alone.
 
 Saved native origins retain their own routing behavior: opening them does not invoke
 the Compose proxy's system resolver, Docker inspections or CA-pinned TLS probe.

docs/guides/native-candidate.md

@@ -1,9 +1,9 @@
 # Native backend reference
 
 This is the detailed reference for the native backend (beta). It is long and
-precise. For a short introduction, read the [overview](../native/README.md),
-[try it](../native/try-it.md) and
-[what works and known limits](../native/limits.md). The
+precise. For the first run, use [Try native on Apple Silicon](https://hack.foo/docs/v5/native/start).
+The [overview](../native/README.md) and
+[known limits](../native/limits.md) explain its scope. The
 [reference map](../native/reference.md) lists this page's sections by topic.
 
 The native backend is beta. `hack-native` is an opt-in Apple Silicon macOS executor installed alongside
@@ -108,40 +108,17 @@ for this stable home; `channel` reports `installed-candidate`. State remains und
 child processes bind to its identity. Moving an executable is supported; moving
 an active home or adopting another installation's state is not.
 
-Run the normal project CLI through the bundle's `hack-v5` entrypoint:
-
-```sh
-export HACK_NATIVE_HOME=/absolute/private/candidate-home
-/absolute/copied/hack-native-bundle/hack-v5 ps --path /absolute/project
-```
-
-Keep the bundle together and invoke this entrypoint by its full path (do not copy
-or symlink only the script). With `HACK_RUNTIME_BACKEND` unset (or `native`) it
-selects the native backend and the adjacent executor, even if an inherited
-`HACK_NATIVE_BINARY` selects another binary. An explicit
-`HACK_RUNTIME_BACKEND=compose` runs the same bundled CLI on the Compose backend
-with your own Hack home and existing global routing services. It needs no
-`HACK_NATIVE_HOME` and removes the native selectors. Other values refuse with exit
-code 64. The [candidate installer guide](https://github.com/hack-dance/hack/blob/next/docs/guides/candidate-install.md#test-both-backends)
-describes Compose testing and its shared-state limits: run stable `hack global up`,
-then any stable `hack doctor` or `hack doctor --fix`, then stable `hack daemon stop`,
-confirm `pgrep -fl "hack daemon start"` prints nothing, and run no stable `hack`
-command while the candidate uses your Hack home. Stable `hack global up` (v4.2.0)
-starts a stopped `hackd` again, and so does stable `hack doctor --fix` (it asks
-first only in a terminal). If the check lists a process, the guide gives the
-launchd remedy. The entrypoint turns off daemon autostart in newer builds, so the
-candidate does not start the stable `hackd` on its own: a candidate
-`hack doctor --fix` skips its `hackd` repair without asking and prints the
-command to run yourself, which runs the stable CLI. Do not commit the
-project's generated `.hack/.internal/` directory; newer generators rewrite files
-such as `compose.override.yml`. The entrypoint preserves arguments, exit codes and
-signals through `exec`, and never replaces the installed `hack`. Project-specific
-native adaptation, dependency and routing selections remain explicit; this entrypoint
-does not prepare a provider or migrate existing projects. An unversioned local
-build reports the repository package version. A versioned prerelease build reports
-its explicit candidate version and includes source provenance. The `hack-v5`
-entrypoint alone does not identify a published release. Unsupported native workflows still
-report their existing refusal rather than falling back to Docker.
+For normal project commands, follow the short
+[native start page](https://hack.foo/docs/v5/native/start). Manual bundle users
+use the adjacent `hack-v5` entrypoint with an explicit `HACK_NATIVE_HOME`;
+keep the bundle together. The [candidate installer guide](candidate-install.md#test-both-backends)
+defines backend selectors, private versus shared homes, stable-daemon quiescence
+and returning to Compose. Neither entrypoint prepares the provider, migrates a
+project or falls back to Docker for an unsupported native command. An unversioned
+local build reports its repository version; only a versioned bundle includes
+candidate version provenance. The entrypoint alone does not identify a release.
+`hack-v5` passes arguments, exit codes and signals through `exec`; it never replaces
+the installed stable executable.
 
 Native `up` accepts an explicit branch or the branch inferred from a linked Git
 worktree when its exact source root can be shared with a fresh or matching pool.
@@ -934,20 +911,16 @@ compatibility. V4 and candidate homes remain separate; this procedure does not
 migrate V4 data into the candidate or replace the installed `hack`. DNS, trust and
 client configuration are outside this bundle-selection procedure.
 
-Provider setup is separate and explicit. Prepare the native runtime with:
-
-```sh
-./hack-native --candidate-root /absolute/private/candidate-home runtime setup
-```
-
-`runtime setup` lists the pinned SmolVM, Docker engine and four Alpine guest
-packages with their exact compressed byte lengths, source hosts, SHA-256 hashes, private cache and
-install destination, then asks once when preparation is needed. `--no-interactive` (or
+For ordinary setup and consent, use the short
+[native start page](https://hack.foo/docs/v5/native/start#prepare-the-runtime).
+The remainder describes the setup and recovery contract. `--no-interactive` (or
 truthy `HACK_NO_INTERACTIVE` values `1`, `true`, `yes` or `on`, ignoring case and
 surrounding whitespace) refuses with `E_INTERACTIVE_REQUIRED` unless
 `--accept-downloads` explicitly consents. No provider download happens from `up`,
 the installer, the probe or any other implicit path. The optional BuildKit client
 is still prepared separately below.
+Setup lists the pinned SmolVM, Docker engine and four Alpine guest packages,
+including exact compressed sizes, hosts, hashes, private cache and destinations.
 
 The executable embeds `provider-pins.json` and checks its hashes against the
 manual preparation pins. HTTPS redirects may use only the original host and the

docs/versions/v5/getting-started.md

@@ -1,47 +1,100 @@
-# Getting started
+# First project on Compose
 
-Complete [Install](install.md) first. These steps use the default Docker Compose
-backend. For the native backend (beta), read
-[Try the native backend](native/try-it.md) after this page.
+Start here: [1. Install](install.md) → **2. First project** →
+[3. Upgrade from v4](upgrade.md) or [4. Try native](native/start.md).
 
-## Initialize one project
+Use the terminal from Install: `hack` selects v5 and
+`HACK_RUNTIME_BACKEND=compose` is exported. Docker must be running.
+An existing v4 project should follow the upgrade page before these steps.
 
-From a repository you own:
+```mermaid
+---
+title: First Compose run
+---
+sequenceDiagram
+  autonumber
+  participant You
+  participant Hack
+  participant Compose
+  You->>Hack: init
+  Hack-->>You: Review .hack files
+  You->>Hack: up
+  Hack->>Compose: Start services
+  You->>Hack: open and logs
+  Hack-->>You: URL and output
+  You->>Hack: down
+  Hack->>Compose: Stop project
+```
+
+## Set up your repository
+
+From the repository you want to run:
 
 ```sh
 cd your-project
 hack init
 ```
 
-Review the generated `.hack/` files before starting anything. Keep configuration in
-git and keep the secret key and local state out of it. For an existing Compose
-project, custom domains or agent-assisted setup, follow
-[Project setup](guides/init-project.md).
+Follow the service and domain prompts. Discovery suggests services from the app's
+packages; review the images and commands it proposes. To adopt an existing Compose
+app, use `hack init --manual` for a scaffold, then put the needed service definitions
+in `.hack/docker-compose.yml`. Adjust relative build and mount paths for that
+file's location; keep the original Compose file until the app checks pass.
+This is the Compose setup path; `hack config adopt` is a separate native configuration path.
+If `.hack/` already exists, review that setup instead of replacing it.
+
+Check `.hack/docker-compose.yml`: its images, commands, ports and mounts should
+match your app. Check the local URL in the service's routing labels. Commit shared
+configuration, but never the project key `.hack.secret.key` or local env layers.
+[Project setup](guides/init-project.md) explains discovery and custom domains.
 
-## Start, inspect and stop
+For noninteractive setup, `hack init --auto` uses discovery defaults. In builds
+containing merged #791, intended for next.17, it warns **“No runnable service was
+found”** when discovery wrote a placeholder `app` service (a Bun image running
+`bun run dev`). Set that service's image and command to how your app really starts
+before `up`. The notice does not appear for a discovered service or when you
+explicitly chose `--manual` or `--no-discovery`.
+
+## Start and open
 
 ```sh
 hack up --detach
-hack open
 hack ps
-hack logs --no-follow --tail 50
+hack open
 ```
 
-Expected: the declared services start, `open` prints or opens the instance URL,
-and `ps` shows service state. Visit the app and run its own health check. A URL or
-a running container alone does not prove the app works. If startup fails, read the
-error and run `hack doctor` before trying again.
+Expect the declared services in `ps` and the app's local URL from `open`.
+If a project has several URLs, choose the app's route. A worker-only project may
+have no URL. Sign in or load a page that reads data to check the app itself.
+
+With #791, Compose `open` warns when the host's DNS looks wrong; the URL is still
+printed or opened. `open --json` adds `dns: "unresolved"` for a confirmed missing
+address, or `dns: "unconfigured"` on a Mac whose Hack DNS suffix is not set up and
+whose lookup did not answer in time. A machine upgraded from v4 may resolve only
+the older suffix. Follow the hint: use the same Compose-selected v5 CLI to run
+`hack global install`, or choose a host under a working suffix with
+`hack config set dev_host <name>.<suffix>`. Review host-change prompts.
+See [the DNS troubleshooting row](troubleshooting.md).
+
+A failed startup prints a reason. Read it before retrying; use
+[troubleshooting](troubleshooting.md) and `hack doctor` for setup problems.
+
+## Read logs and stop
 
 ```sh
-hack down
+hack logs --no-follow --tail 50
+hack logs --follow
 ```
 
-Stop releases project-owned runtime processes. It does not delete application
-data or prune shared caches. [Run and inspect](guides/run-project.md) covers
-selected services and log history.
+The first command prints a snapshot. The second keeps watching. Ctrl-C stops
+watching the logs; it does not stop the project. Logs may contain secret values.
+Do not paste raw logs into a public issue.
 
-## Next
+```sh
+hack down
+```
 
-- [Core concepts](../core.md) explains projects, services and instances.
-- [Work on another branch](guides/parallel-work.md) runs a second instance beside the first.
-- [Agent handoff](agent-handoff.md) gives a coding agent the same documentation.
+This stops the project. It does not delete its named volumes or stop shared
+routing services. See [Run and inspect](guides/run-project.md) for service selection,
+log history and restarts. When this Compose run works, try native only on a
+[disposable project](native/start.md).

docs/versions/v5/guides/init-project.md

@@ -11,12 +11,17 @@ cd your-project
 hack init
 ```
 
-`hack init` detects an existing `docker-compose.yml`, asks about services and
-domains, and writes `.hack/`: the Compose file Hack manages, `hack.config.json`,
+`hack init` discovers app packages, asks about services and domains, and writes
+`.hack/`: the Compose file Hack manages, `hack.config.json`,
 the default env YAML and a `.gitignore` for machine-local state. Review the files
 and commit them. To hand setup to an agent instead, run
 `hack init --with claude` or `hack init --with codex`.
 
+It does not automatically adopt an existing Compose file. Use `hack init --manual`
+for a scaffold, then copy the needed service definitions into
+`.hack/docker-compose.yml`. Review relative build and mount paths, env delivery
+and Hack routing labels before starting; keep the old file until the app works.
+
 For an existing project, `hack agent onboard` prints an onboarding prompt that
 describes the services, env and routing a Hack setup should cover. See
 [Explicit agent setup](agent-first-setup.md).

docs/versions/v5/index.md

@@ -11,7 +11,14 @@ macOS) is opt-in and ships only through the `hack-next` channel, not in the stab
 archives or the Homebrew formula. Read [Upgrade from v4](upgrade.md) for what
 changed and what was retired.
 
-Start with [Install](install.md), then [Getting started](getting-started.md).
+## Start here
+
+1. [Install v5](install.md): choose a channel and set up Compose routing.
+2. [First project on Compose](getting-started.md): set up, start, open, read logs and stop.
+3. [Upgrade from v4](upgrade.md): back up first, try one project and roll back.
+4. [Try native on Apple Silicon](native/start.md): prepare, check, start and return to Compose.
+
+[Troubleshooting](troubleshooting.md) maps common Doctor findings to their fixes.
 [What's new in 5.0](../guides/v5-release-notes.md) summarizes the release.
 v5 prerelease bundles are Apple Silicon macOS only; see
 [Install](install.md#prerequisites) for platform support.