@hamedb89/localghost 0.1.9 → 0.1.12

package/README.md

@@ -9,46 +9,20 @@ Buh. Friendly local hostnames for app repos.
 [![CI](https://github.com/hamedb89/localghost/actions/workflows/ci.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/ci.yml)
 [![GitHub Pages](https://github.com/hamedb89/localghost/actions/workflows/pages.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/pages.yml)
 [![Publish npm](https://github.com/hamedb89/localghost/actions/workflows/publish-npm.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/publish-npm.yml)
-[![npm version](https://img.shields.io/badge/npm-v0.1.9-CB3837?logo=npm)](https://www.npmjs.com/package/@hamedb89/localghost)
+[![npm version](https://img.shields.io/badge/npm-v0.1.12-CB3837?logo=npm)](https://www.npmjs.com/package/@hamedb89/localghost)
 
-Localghost is a tiny Node.js CLI for friendly local domains in app repos. Add it as a dev dependency, run `yarn dev`, and use `http://app.localhost/` instead of remembering which localhost port belongs to which process.
+Localghost is a tiny Node.js CLI for clean local app domains. Add it as a dev dependency, keep running the command your team already knows, and use `http://app.localhost/` instead of remembering which port belongs to which process.
 
-[Website](https://hamedb89.github.io/localghost/) · [npm](https://www.npmjs.com/package/@hamedb89/localghost) · [GitHub](https://github.com/hamedb89/localghost)
+[Website](https://hamedb89.github.io/localghost/) · [Docs](https://hamedb89.github.io/localghost/docs/) · [npm](https://www.npmjs.com/package/@hamedb89/localghost) · [GitHub](https://github.com/hamedb89/localghost)
 
-## What It Does
+## Quick Start
 
-- Creates and reads `.localghost` in your app repo.
-- Lets repos choose explicit config files or filename patterns when `.localghost` is not enough.
-- Updates only a managed Localghost block in `/etc/hosts` during explicit setup.
-- Generates `ops/local/Caddyfile` for local reverse proxying. HTTP is the default; HTTPS is explicit with `--https` or `--ssl`.
-- Checks whether Caddy is installed, but does not run Homebrew for you.
-- Provides a Vite plugin that sets explicit `server.allowedHosts` entries.
-- Defaults Vite dev to the configured Localghost domain and no-ops during production/build.
-- Prints parsed config and project-local state as JSON for scripts, Codex, agents, and future MCP tools.
-- Checks npm for newer Localghost releases at most once per day, with an explicit opt-out.
-
-## Trust
-
-- CI runs typecheck, build, site build, and npm package dry-run on Node 20 and 22.
-- GitHub Pages is deployed by Actions from the checked-in `site/` and `assets/` sources.
-- Preview the exact Pages artifact locally with `npm run site:serve`, then open `http://127.0.0.1:4173/`.
-- npm publish is guarded by `prepublishOnly` and the release workflow publishes with npm provenance.
-- Runtime dependencies are intentionally small: `commander` for the CLI and `execa` for process execution. Vite is an optional peer dependency for the Vite plugin.
-- No postinstall scripts, hidden Homebrew installs, or broad hosts-file rewrites.
-- Update checks are best-effort, cached for 24 hours, and can be disabled with `LOCALGHOST_NO_UPDATE_CHECK=1` or `--no-update-check`.
-
-<p align="center">
-  <img src="./assets/localghost-app-icon.png" alt="Localghost app icon" width="180">
-</p>
-
-## Start Here
+Install it as a dev dependency:
 
 ```sh
 yarn add -D @hamedb89/localghost
 ```
 
-That is the entrypoint you are optimizing for: install the dev dependency, keep using the dev command your team already knows, and let Localghost handle the local-domain setup around it.
-
 For Vite apps, add the plugin once:
 
 ```ts
@@ -60,15 +34,13 @@ export default defineConfig({
 });
 ```
 
-Now your daily command is just:
+Then keep using the command your repo already expects:
 
 ```sh
 yarn dev
 ```
 
-And you are ready.
-
-On the first interactive `yarn dev`, Localghost can create `.localghost`, explain the `/etc/hosts` change, write the local Caddyfile, and then print the browser-facing URL:
+On the first interactive run, Localghost can create `.localghost`, explain the `/etc/hosts` change, write `ops/local/Caddyfile`, and print the browser-facing URL:
 
 ```txt
 localghost
@@ -77,7 +49,7 @@ also:   http://www.app.localhost/
 target: http://127.0.0.1:5173/
 ```
 
-If your project does not use Vite, or you want one command that starts Caddy and then your app process, wrap your raw dev script:
+For non-Vite apps, wrap your raw dev command:
 
 ```json
 {
@@ -88,109 +60,139 @@ If your project does not use Vite, or you want one command that starts Caddy and
 }
 ```
 
-Then the daily command stays the same:
+## The Simple Stuff
+
+Start the detected development server with Localghost:
 
 ```sh
-yarn dev
+npm exec localghost
 ```
 
-## Configuration
+Localghost detects the package manager, prefers a non-recursive `dev:raw` script, falls back to `dev`, repairs stale setup when needed, then starts Caddy and the server. Preview the decision without starting anything:
+
+```sh
+npm exec localghost -- --dry-run
+```
 
-Most apps only need a `.localghost` file when they want explicit hostnames or multiple services:
+Create the repo-local hostname contract:
 
-```txt
-# Buh. Friendly names for local services.
-# Format: <host> <port>
-app.localhost 5173
-www.app.localhost 5173
-api.app.localhost 8787
+```sh
+localghost init --write-scripts
 ```
 
-If `.localghost` is missing, the Vite plugin can prompt to create it during `yarn dev`. You can also create it directly:
+Check whether the machine is ready:
 
 ```sh
-yarn localghost init
+localghost doctor
 ```
 
-Check the machine:
+Prepare `/etc/hosts` and the local Caddyfile:
 
 ```sh
-yarn localghost doctor
+localghost setup
 ```
 
-If Caddy is missing, Localghost prints:
+Check setup readiness:
 
-```txt
-Caddy: missing
-Run: brew install caddy
-Localghost will not install it for you. No surprise spells.
+```sh
+localghost status --ready
 ```
 
-Prepare or repair the machine setup directly:
+Repair stale hosts, Caddy configuration, or setup state:
 
 ```sh
-yarn localghost setup
+localghost repair
 ```
 
-Check that the hosts block and Caddyfile are ready:
+Run only the local proxy:
 
 ```sh
-yarn localghost status --ready
+localghost dev
 ```
 
-Run only the proxy when your app server is started separately:
+Wrap an app server:
 
 ```sh
-yarn localghost dev
+localghost run -- vite
 ```
 
-Use HTTPS only when you explicitly want Caddy local certificates:
+See the domain layer:
 
 ```sh
-yarn localghost dev --https
+localghost routes
 ```
 
-Trust Caddy's local HTTPS CA when you want browsers to stop showing local certificate warnings:
+```txt
+localghost routes
+  http://app.localhost/ -> http://127.0.0.1:5173
+  http://api.app.localhost/ -> http://127.0.0.1:8787
+```
+
+See active Localghost sessions:
 
 ```sh
-yarn localghost trust
+localghost ps
+localghost ps --json
 ```
 
-Reset generated setup without deleting `.localghost`:
+Check for updates:
 
 ```sh
-yarn localghost reset
-yarn localghost setup
+localghost update
 ```
 
 Prefer `.localhost` names. `.local` is supported, but Localghost warns because `.local` can collide with mDNS/Bonjour.
 
-## Config Files
+## What It Changes
 
-By default, Localghost reads `.localghost` from the project root. Repos that need another name can be explicit:
+Localghost is intentionally small and explicit:
 
-```sh
-localghost print --config .localghost.preview
-localghost setup --config .localghost.preview
+- Reads `.localghost` from your app repo and turns hostnames into local routes.
+- Updates only a managed Localghost block in `/etc/hosts` during explicit setup.
+- Generates `ops/local/Caddyfile` for local reverse proxying.
+- Records setup state in `ops/local/localghost-state.json`.
+- Keeps HTTP as the default; HTTPS is explicit with `--https`, `--ssl`, or config.
+- Checks whether Caddy is installed, but never installs Homebrew packages for you.
+- Gives Vite explicit `server.allowedHosts` entries without using `allowedHosts: true`.
+- Never opens browser tabs by default.
+
+`setup`, `dev`, and `teardown` refuse to run in production-like environments such as `NODE_ENV=production`, `VERCEL_ENV=production`, or `LOCALGHOST_ENV=production`.
+
+## Configuration By Use Case
+
+### One App Domain
+
+Use a `.localghost` file when you want one stable local domain:
+
+```txt
+# .localghost
+app.localhost 5173
 ```
 
-You can pass `--config` more than once. Localghost uses the first file that exists:
+Then run:
 
 ```sh
-localghost print --config .localghost.private --config .localghost
+localghost setup
+localghost run -- vite
 ```
 
-You can also search project-root filenames with a regular expression:
+### Multiple Local Services
 
-```sh
-localghost print --config-pattern '^\.localghost\.(private|preview)$'
+Map each browser-facing host to the upstream port:
+
+```txt
+# .localghost
+app.localhost 5173
+www.app.localhost 5173
+api.app.localhost 8787
+admin.app.localhost 5174
 ```
 
-The Vite plugin accepts the same shape through `fileName`, `configFiles`, or `configPattern`. If you run `localghost init --config .localghost.preview --write-scripts`, generated package scripts include the matching `--config` flag.
+`localghost routes` prints the same `domain -> upstream` map that `setup` and `dev` use.
 
-## Package Scripts
+### Add Package Scripts
 
-`localghost init --write-scripts` adds these scripts when they are missing:
+`localghost init --write-scripts` adds missing scripts without replacing your existing ones:
 
 ```json
 {
@@ -200,6 +202,7 @@ The Vite plugin accepts the same shape through `fileName`, `configFiles`, or `co
     "localghost:proxy:https": "localghost dev --https",
     "localghost:run": "localghost run --",
     "localghost:ready": "localghost status --ready",
+    "localghost:repair": "localghost repair",
     "localghost:trust": "localghost trust",
     "localghost:ps": "localghost ps",
     "localghost:print": "localghost print",
@@ -215,7 +218,9 @@ The Vite plugin accepts the same shape through `fileName`, `configFiles`, or `co
 }
 ```
 
-A full app might compose them with its own servers:
+### Keep `yarn dev` As The Daily Command
+
+Wrap the raw app server so teammates keep typing the normal command:
 
 ```json
 {
@@ -226,7 +231,7 @@ A full app might compose them with its own servers:
 }
 ```
 
-In Turborepo, let Localghost wrap the dev runner and keep dev uncached:
+For Turborepo, wrap the dev runner and keep dev uncached:
 
 ```json
 {
@@ -237,8 +242,6 @@ In Turborepo, let Localghost wrap the dev runner and keep dev uncached:
 }
 ```
 
-Then keep persistent dev tasks uncached:
-
 ```json
 {
   "tasks": {
@@ -247,263 +250,350 @@ Then keep persistent dev tasks uncached:
 }
 ```
 
-`localghost run` resolves one shared Localghost context, starts Caddy, handles the optional HTTPS trust prompt, then starts the child command. That keeps Localghost setup/proxy output before Vite's ready log. It passes the selected port to the child command through `LOCALGHOST_PORT` and `VITE_PORT`, and stops Caddy when the child exits. Dynamic ports are on by default: Localghost starts at the configured port, checks `127.0.0.1:<port>`, and walks upward until it finds a free port. Use `--dynamic-port=no` when you want strict fixed-port behavior.
+`localghost run` starts Caddy, handles optional HTTPS trust, starts the child command, passes `LOCALGHOST_PORT` and `VITE_PORT`, and stops Caddy when the child exits.
 
-Most repos do not need `localghost.config.mjs`. Localghost derives `project` from `package.json`, defaults to port `5173`, keeps HTTPS off by default, enables dynamic ports by default, and adds `www.` aliases by default. Add `localghost.config.mjs` only when you want to override those defaults:
+### Vite Plugin
 
-```js
-import { defineLocalghostConfig } from "@hamedb89/localghost";
+Use the plugin when you want Vite to bind to `127.0.0.1`, use the selected Localghost port, set strict `allowedHosts`, and print the browser-facing domain:
 
-export default defineLocalghostConfig({
-  https: true
+```ts
+import { defineConfig } from "vite";
+import { localGhostPlugin } from "@hamedb89/localghost/vite";
+
+export default defineConfig({
+  plugins: [
+    localGhostPlugin({
+      port: 5173,
+      configFiles: [".localghost.private", ".localghost"]
+    })
+  ]
 });
 ```
 
-Then the daily script can stay small:
+The plugin runs only during local `vite serve`; production/build mode does not configure Vite dev-server hosting. If `ghostTunnel` is configured, the build hook can still print the production URL shape for visibility.
 
-```json
-{
-  "scripts": {
-    "dev": "localghost run -- yarn dev:raw",
-    "dev:raw": "vite"
-  }
-}
+### Custom Config Files
+
+By default, Localghost reads `.localghost`. Repos that need another file name can be explicit:
+
+```sh
+localghost print --config .localghost.preview
+localghost setup --config .localghost.preview
+```
+
+You can pass `--config` more than once. Localghost uses the first file that exists:
+
+```sh
+localghost print --config .localghost.private --config .localghost
+```
+
+You can also search project-root filenames with a regular expression:
+
+```sh
+localghost print --config-pattern '^\.localghost\.(private|preview)$'
 ```
 
-`www.` aliases are enabled by default. A `.localghost` entry like `app.localhost 5173` also sets up `www.app.localhost` unless `wwwAlias: false` is set in `localghost.config.mjs`.
+The Vite plugin accepts the same idea through `fileName`, `configFiles`, or `configPattern`.
+
+### Shared Project Defaults
 
-`ghostTunnel` is the production opt-in for a wildcard product entrypoint on top of your deployed Vite app. The default namespace is `<route>-<project>-<owner>.ghost.<domain>`, and omitted domains are shown as `*` in logs:
+Most repos do not need `localghost.config.mjs`. Add it when you want shared defaults for CLI and Vite:
 
 ```js
 import { defineLocalghostConfig } from "@hamedb89/localghost";
 
 export default defineLocalghostConfig({
-  ghostTunnel: {
-    domains: "socialworkouts.app",
-    mode: "manual"
-  }
+  project: "app",
+  port: 5173,
+  dynamicPort: true,
+  autoRepair: true,
+  command: ["pnpm", "dev"],
+  wwwAlias: true
 });
 ```
 
-With `ghostTunnel: { domains }`, local route and Vite startup logs use local defaults for `route`, `project`, and `owner`, then fill the configured domain:
+Localghost derives `project` from `package.json`, defaults to port `5173`, keeps HTTP as the default, enables dynamic ports and setup repair by default, and adds `www.` aliases by default. `run`, `dev`, and the Vite plugin perform a read-only readiness check first and repair only when the managed hosts block or setup state is stale.
 
-```txt
-localghost ghost tunnel
-  mode: manual
-  expected: https://app-decision-layer-hamed.ghost.socialworkouts.app/
-```
-
-Without `domains`, the expected URL stays wildcarded:
+With no subcommand, `command` takes precedence. Otherwise Localghost detects npm, pnpm, Yarn, or Bun and runs `dev:raw` or `dev`. Scripts that invoke Localghost are skipped to prevent recursion.
 
-```txt
-localghost ghost tunnel
-  mode: manual
-  expected: https://app-decision-layer-hamed.ghost.*/
-```
+### Multiple Apps
 
-`ghostTunnel: "manual"` and `ghostTunnel: "public"` are shorthand modes. `manual` is the default; use `enabled: false` to keep domains/config in the file without exposing the tunnel surface.
+For a monorepo where one root command already starts every app, keep using `command` and list the routes in `.localghost`.
 
-Use object form to override defaults or provide a concrete preview URL:
+When Localghost should own each process, configure explicit services:
 
 ```js
 export default defineLocalghostConfig({
-  ghostTunnel: {
-    domains: "socialworkouts.app",
-    preview: {
-      route: "plan",
-      project: "summer-base",
-      owner: "hamed"
+  services: [
+    {
+      name: "web",
+      cwd: "apps/web",
+      host: "xyz.localhost",
+      port: 5173,
+      command: ["pnpm", "dev"]
+    },
+    {
+      name: "api",
+      cwd: "apps/api",
+      host: "api.xyz.localhost",
+      port: 8787,
+      command: ["pnpm", "dev"]
     }
-  }
+  ]
 });
 ```
 
-Production apps can read that flag without requiring the local `.localghost` file, then construct and validate tunnel URLs:
+Then bare `localghost` starts one Caddy instance and both services. Each command runs in its own `cwd` and receives its own `LOCALGHOST_PORT`, `VITE_PORT`, and `LOCALGHOST_SERVICE`. Dynamic-port selection and setup repair apply to every service. When Caddy or any service exits, Localghost stops the remaining processes.
 
-```ts
-import {
-  assertSecureGhostTunnelRequest,
-  constructGhostTunnelUrl,
-  readLocalghostProjectConfig
-} from "@hamedb89/localghost";
+Omit a service `command` to detect `dev:raw` or `dev` from that service directory. Service directories must stay inside the project root, and names and hosts must be unique.
 
-const { config } = await readLocalghostProjectConfig();
-const url = constructGhostTunnelUrl({
-  domain: "socialworkouts.app",
-  route: "plan",
-  project: "summer-base",
-  owner: "hamed",
-  ghostTunnel: config.ghostTunnel
-});
+Caddy startup and validation logs are quiet after success; configuration errors remain visible. Set `LOCALGHOST_CADDY_VERBOSE=1` when debugging Caddy itself. Once all service ports are listening, Localghost prints the final hostname-to-upstream map beneath the service startup logs.
 
-const route = assertSecureGhostTunnelRequest({
-  host: request.headers.get("host") ?? "",
-  domain: "socialworkouts.app",
-  protocol: "https",
-  authenticated: Boolean(session),
-  ghostTunnel: config.ghostTunnel
-});
+Try the runnable Node example in [`examples/multi-service`](./examples/multi-service).
+
+Disable automatic repair when you want strict failure behavior:
+
+```sh
+localghost run --auto-repair=no -- vite
 ```
 
-That constructs `https://plan-summer-base-hamed.ghost.socialworkouts.app/`, validates the same host shape, requires HTTPS by default, and requires the app to confirm auth by default. See [Ghost Tunnel](./docs/ghost-tunnel.md) for the production DNS and routing flow.
+Or set `autoRepair: false` in `localghost.config.mjs`. HTTPS certificate trust remains explicit.
 
-When `ghostTunnel.preview` is configured, local route and Vite startup logs include the concrete URL as `expected: https://plan-summer-base-hamed.ghost.socialworkouts.app/`. In an interactive Vite terminal, press `g` to show the Ghost Tunnel configuration and open a numbered concrete URL. Wildcard `*` URLs are shown for clarity, but the menu only opens configured concrete domains.
+### Fixed Ports
 
-Relay guardrails are private-by-default: public requests never choose the local target, route registration requires a matching local-agent bearer token, signed route claims are exact/scoped/expiring, and default targets are limited to `localhost`, `127.0.0.1`, and `::1` with dangerous ports blocked. The package exports relay helpers for registration, target validation, header stripping, log redaction, limits, and safe offline responses.
+Dynamic ports are on by default. Localghost starts at the configured port, checks `127.0.0.1:<port>`, and walks upward until it finds a free port.
 
-Local security checks:
+Use strict fixed-port behavior when you want startup to fail instead:
 
 ```sh
-npm test
-npm run test:cli
-npm run test:coverage
+localghost run --dynamic-port=no -- vite
 ```
 
-`localghost dev` and `localghost run` also register their active sessions in a user-local activity file. Use `localghost ps` to see the Localghost apps currently running on the machine:
-
-```txt
-localghost ps
+Or in config:
 
-app  run: vite
-  cwd: /Users/you/Projects/app
-  pid: 12345, caddy: 12346, child: 12347
-  started: 2026-07-05T12:00:00.000Z
-  app.localhost -> 127.0.0.1:5173 (listening)
+```js
+export default defineLocalghostConfig({
+  dynamicPort: false
+});
 ```
 
-Pass `--json` when another helper, such as a menu bar app, needs to poll the same state.
+### Local HTTPS
 
-## macOS Widget
+HTTP is the default. Use HTTPS only when you explicitly want Caddy local certificates:
 
-Localghost includes a tiny native macOS widget in `apps/macos-widget`. One widget tracks all active Localghost sessions across the machine. It shows `LG n` in the top bar and opens a small floating desktop panel with the Localghost route list, target ports, and listening state.
+```sh
+localghost setup --https
+localghost dev --https
+```
 
-Build it from source:
+Trust Caddy's local HTTPS CA when you want browsers to stop showing local certificate warnings:
 
 ```sh
-npm run build
-npm run macos:widget:build
+localghost trust
+localghost run --trust -- vite
 ```
 
-The app bundle is written to `dist/LocalghostWidget.app`. See [docs/macos-widget.md](./docs/macos-widget.md) for local development notes.
+macOS may ask for your password so Caddy can add its local CA to Keychain. Localghost records the trust result in `ops/local/localghost-state.json`.
 
-## Vite
+You can also make HTTPS the repo default:
 
-```ts
-import { defineConfig } from "vite";
-import { localGhostPlugin } from "@hamedb89/localghost/vite";
+```js
+export default defineLocalghostConfig({
+  https: true
+});
+```
 
-export default defineConfig({
-  plugins: [
-    localGhostPlugin({
-      port: 5173,
-      configFiles: [".localghost.private", ".localghost"]
-    })
-  ]
+### Disable `www.` Aliases
+
+By default, `app.localhost 5173` also creates `www.app.localhost`.
+
+Disable that when the repo wants only exact hosts:
+
+```js
+export default defineLocalghostConfig({
+  wwwAlias: false
 });
 ```
 
-The plugin binds Vite to `127.0.0.1` by default, prints the selected Localghost domain, generates an explicit `server.allowedHosts` list from the selected config file, and does not set `allowedHosts: true`. It runs only during local `vite serve`; production/build mode no-ops. Dynamic ports are enabled by default, so the plugin uses the configured port when available and otherwise moves to the next free port before Vite starts. Set `dynamicPort: false` when strict fixed-port behavior matters.
+### Public Ghost Tunnel
+
+`ghostTunnel` is an opt-in production URL shape for deployed wildcard endpoints. It does not change local Caddy or `/etc/hosts` setup.
+
+Use public mode when the deployed app should react to whatever route arrives:
 
-If `.localghost` is missing and Vite is running in an interactive terminal, the plugin asks whether to create one, prompts for the primary domain and optional extra domains, and then asks whether to run setup. Before touching `/etc/hosts`, it explains why macOS may ask for your password and confirms that only Localghost's managed block is changed.
+```js
+import { defineLocalghostConfig } from "@hamedb89/localghost";
+
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    mode: "public",
+    domains: "copper-comet.example"
+  }
+});
+```
 
-When Vite starts, Localghost prints the browser-facing URLs:
+Build output stays flexible instead of filling slots from the build machine:
 
 ```txt
-localghost
-local:  http://app.localhost/
-also:   http://www.app.localhost/
-target: http://127.0.0.1:5173/
+localghost ghost tunnel
+  mode: public
+  configured: https://<route>-<project>-<owner>.ghost.copper-comet.example/
 ```
 
-`https: true` means the browser-facing URL is expected to go through Caddy on HTTPS, while Vite still runs behind it on `127.0.0.1:<port>`. The plugin uses that to set Vite websocket/HMR proxy settings and to print `https://...` local host URLs. Localghost never opens browser tabs by default.
+Production code can parse and validate the incoming wildcard host:
 
-Set `log: false` if you want to keep Vite's default terminal output only.
+```ts
+import {
+  assertSecureGhostTunnelRequest,
+  readLocalghostProjectConfig
+} from "@hamedb89/localghost";
 
-## CLI
+const { config } = await readLocalghostProjectConfig();
 
-```sh
-localghost init
-localghost init --write-scripts
-localghost doctor
-localghost setup
-localghost setup --project app
-localghost setup --config .localghost.preview
-localghost setup --https
-localghost trust
-localghost status
-localghost status --ready
-localghost ps
-localghost ps --json
-localghost reset
-localghost teardown
-localghost teardown --remove-caddyfile
-localghost update
-localghost --no-update-check doctor
-localghost run -- vite
-localghost run --trust -- vite
-localghost run --dynamic-port=no -- vite
-localghost dev --config-pattern '^\.localghost\.'
-localghost dev --https
-localghost print
+const route = assertSecureGhostTunnelRequest({
+  host: request.headers.get("host") ?? "",
+  domain: "copper-comet.example",
+  protocol: "https",
+  authenticated: Boolean(session),
+  ghostTunnel: config.ghostTunnel
+});
 ```
 
-Localghost checks npm for newer releases after successful commands. The check has a short timeout, is cached for 24 hours, and never fails the command. Disable it with `LOCALGHOST_NO_UPDATE_CHECK=1` or `--no-update-check`. Run `localghost update` when you want an explicit update check.
+By default, secure requests require HTTPS and app-authenticated access.
 
-`setup`, `dev`, and `teardown` refuse to run in production-like environments such as `NODE_ENV=production`, `VERCEL_ENV=production`, or `LOCALGHOST_ENV=production`.
+### Concrete Ghost Tunnel Preview
 
-When HTTPS is enabled, `localghost dev` and `localghost run` ask once whether to trust Caddy's local HTTPS CA. If you accept, macOS may ask for your password so Caddy can add its local CA to Keychain. Localghost records the result in `ops/local/localghost-state.json`; use `localghost trust` or `localghost run --trust -- ...` when you want to rerun the trust step intentionally.
+Use `preview` only when you want one concrete URL in logs or menus:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    mode: "public",
+    domains: "copper-comet.example",
+    preview: {
+      route: "decisionlayer",
+      project: "decision-layer",
+      owner: "hamedbahrami"
+    }
+  }
+});
+```
 
-`setup` writes only a managed block in the system hosts file:
+That prints:
 
 ```txt
-# localghost:start app
-127.0.0.1 app.localhost
-# localghost:end app
+localghost ghost tunnel
+  mode: public
+  configured: https://decisionlayer-decision-layer-hamedbahrami.ghost.copper-comet.example/
+```
+
+### Manual Ghost Tunnel
+
+Manual mode is the default. It is useful for private or operator-mediated sharing flows:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    mode: "manual",
+    domains: "moonlit-otter.example"
+  }
+});
 ```
 
-Localghost does not rewrite the whole hosts file. It replaces only its own managed block for the selected project.
+Manual relay helpers are private by default: registration requires a local-agent bearer token plus an exact signed route claim, targets must be explicit local host/port objects, dangerous ports are blocked, sensitive headers/logs are redacted, and offline agents get a safe 503 page.
 
-## Teardown And State
+### Script And Agent Output
 
-`setup` writes a project-local state file at `ops/local/localghost-state.json`. It records the last Localghost action, selected config path, generated Caddyfile path, hosts file path, proxy mode, and the host entries that were applied. This is durable enough for project tooling and avoids relying on OS temp folders for tracking. Most apps should treat it as generated local state and ignore it in git.
+Use JSON when scripts, menu bar tools, or agents need stable output:
 
 ```sh
-localghost status
-localghost status --ready
+localghost print
 localghost status --json
+localghost ps --json
+localghost update --json
 ```
 
-`localghost dev` requires setup to be ready before it starts Caddy. If setup is missing or stale, it prints the exact `localghost setup` command instead of silently running `sudo`. Use `localghost dev --setup` only when you explicitly want the dev command to perform setup first.
+`print` parses the selected config file. `status` reports the project-local setup state. `ps` reports active sessions across projects and whether each upstream port is listening.
 
-When a project no longer needs Localghost, teardown removes only the managed hosts block for the selected project:
+### Reset Or Remove Localghost
+
+Reconcile the managed hosts block, regenerate and validate the Caddyfile, and refresh setup state:
 
 ```sh
-localghost teardown
+localghost repair
 ```
 
-When you want to retest setup without deleting `.localghost`, use reset:
+For HTTPS certificate trust problems, explicitly re-run Caddy's trust step:
+
+```sh
+localghost repair --https --trust
+```
+
+If a running Caddy process exits, `localghost run` exits with it; starting the normal development command again launches a fresh Caddy process.
+
+Retest setup without deleting `.localghost`:
 
 ```sh
 localghost reset
 localghost setup
 ```
 
-The generated Caddyfile is left in place by default. Remove it explicitly when you want a fuller cleanup:
+Remove only the managed hosts block for this project:
+
+```sh
+localghost teardown
+```
+
+Remove the generated Caddyfile too:
 
 ```sh
 localghost teardown --remove-caddyfile
 ```
 
-Localghost still uses a short-lived OS temp file while copying `/etc/hosts` with `sudo`, but that temp file is not the source of truth.
+### macOS Widget
+
+Localghost includes a tiny native macOS widget under `apps/macos-widget`. It reads the shared activity file and shows known setup/running instances.
+
+Build it from source:
+
+```sh
+npm run build
+npm run macos:widget:build
+```
+
+The app bundle is written to `dist/LocalghostWidget.app`.
+
+## CLI Reference
+
+```sh
+localghost [--cwd path] [--dry-run]
+localghost init [--write-scripts] [--config file] [--host host] [--port port]
+localghost doctor
+localghost setup [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
+localghost repair [--project name] [--config file] [--config-pattern regex] [--https|--ssl] [--trust]
+localghost trust [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
+localghost reset [--project name]
+localghost teardown [--project name] [--remove-caddyfile]
+localghost status [--ready] [--json]
+localghost ps [--json]
+localghost update [--json]
+localghost dev [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust]
+localghost run [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust] [--dynamic-port] -- command
+localghost routes [--https|--ssl]
+localghost print [--config file] [--config-pattern regex]
+```
 
 ## API
 
 ```ts
 import {
+  assertSecureGhostTunnelRequest,
+  constructGhostTunnelUrl,
   getConfigFileCandidates,
   initLocalghost,
   readDevHosts,
   readLocalghostState,
+  readLocalghostProjectConfig,
   removeSystemHosts,
   renderCaddyfile,
   renderHostsBlock,
@@ -511,34 +601,30 @@ import {
   updateSystemHosts
 } from "@hamedb89/localghost";
 
-readDevHosts({ configFiles: [".localghost.private", ".localghost"] });
-readDevHosts({ configPattern: /^\.localghost\.(private|preview)$/ });
+import { localGhostPlugin } from "@hamedb89/localghost/vite";
 ```
 
-Vite helper:
+`localHostsPlugin` is also exported as a compatibility alias for the Vite helper.
 
-```ts
-import { localGhostPlugin } from "@hamedb89/localghost/vite";
-```
+## Trust
 
-`localHostsPlugin` is also exported as a compatibility alias.
+- CI runs typecheck, build, site build, and npm package dry-run on Node 20 and 22.
+- GitHub Pages is deployed by Actions from the checked-in `site/`, `docs/`, and `assets/` sources.
+- Preview the exact Pages artifact locally with `npm run site:serve`, then open `http://127.0.0.1:4173/`.
+- npm publish is guarded by `prepublishOnly` and the release workflow publishes with npm provenance.
+- Runtime dependencies are intentionally small: `commander` and `execa`. Vite is an optional peer dependency.
+- No postinstall scripts, hidden Homebrew installs, surprise browser tabs, or broad hosts-file rewrites.
+- Update checks are best-effort, cached for 24 hours, and can be disabled with `LOCALGHOST_NO_UPDATE_CHECK=1` or `--no-update-check`.
 
 ## More Docs
 
-Localghost copy can be mysterious, goofy, magical, funny, and a little absurd. The product behavior should stay boring in the best way: explicit commands, exact paths, clear errors, and no hidden installs.
-
 - [Website](https://hamedb89.github.io/localghost/)
-- [Brand guidelines](./docs/brand.md)
-- [Job-to-be-done flows](./docs/flows.md)
+- [Rendered docs](https://hamedb89.github.io/localghost/docs/)
+- [User flows](./docs/flows.md)
 - [CLI reference](./docs/localghost.1.md)
-
-## Assets
-
-<p align="center">
-  <img src="./assets/localghost-mascot.png" alt="Localghost mascot" width="180">
-  <br>
-  <img src="./assets/localghost-wordmark.png" alt="Localghost wordmark" width="420">
-</p>
+- [Ghost Tunnel guide](./docs/ghost-tunnel.md)
+- [macOS widget notes](./docs/macos-widget.md)
+- [Brand guidelines](./docs/brand.md)
 
 ## License