@hamedb89/localghost 0.1.13 → 0.2.0

package/README.md

@@ -79,6 +79,8 @@ Localghost detects the package manager, prefers a non-recursive `dev:raw` script
 npm exec localghost -- --dry-run
 ```
 
+Supported runtime flags such as `--https`, `--clean-caddy`, `--auto-repair`, and `--dynamic-port` are forwarded by the bare command to the underlying run lifecycle.
+
 Create the repo-local hostname contract:
 
 ```sh
@@ -91,6 +93,8 @@ Check whether the machine is ready:
 localghost doctor
 ```
 
+Doctor also reports occupied configured ports, stale registry leases, and port allocations shared by multiple Localghost instances. Use `--json` for agent-readable output.
+
 Prepare `/etc/hosts` and the local Caddyfile:
 
 ```sh
@@ -109,6 +113,14 @@ Repair stale hosts, Caddy configuration, or setup state:
 localghost repair
 ```
 
+If an existing project port is occupied or was allocated incorrectly, ask Localghost to choose and remember the next available port:
+
+```sh
+localghost repair --reallocate-port
+```
+
+This does not edit `.localghost`; it records a stable runtime allocation in `~/.localghost` and regenerates the managed hosts and Caddy state from that allocation. To remove expired or dead leases as part of the repair, add `--prune-registry`.
+
 Run only the local proxy:
 
 ```sh
@@ -140,6 +152,15 @@ localghost ps
 localghost ps --json
 ```
 
+Give coding agents the supported workflow and repository conventions:
+
+```sh
+localghost guide --agent
+localghost guide --agent --json
+```
+
+Localghost remembers project and instance port assignments in user-level state under `~/.localghost`. The registry is used only for Localghost-managed processes; the operating-system port check remains authoritative for unrelated processes.
+
 Check for updates:
 
 ```sh
@@ -417,7 +438,10 @@ export default defineLocalghostConfig({
 });
 ```
 
-### Public Ghost Tunnel
+### Public Ghost Tunnel (Experimental)
+
+> [!WARNING]
+> Ghost Tunnel is experimental. Its configuration, transport protocol, and public APIs may change between releases. Do not rely on it for production-critical access, and review its authentication and network exposure before sharing a tunnel.
 
 `ghostTunnel` is an opt-in production URL shape for deployed wildcard endpoints. It does not change local Caddy or `/etc/hosts` setup.
 
@@ -570,15 +594,16 @@ The app bundle is written to `dist/LocalghostWidget.app`.
 ```sh
 localghost [--cwd path] [--dry-run]
 localghost init [--write-scripts] [--config file] [--host host] [--port port]
-localghost doctor
+localghost doctor [--cwd path] [--config file] [--config-pattern regex] [--json]
 localghost setup [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
-localghost repair [--project name] [--config file] [--config-pattern regex] [--https|--ssl] [--trust]
+localghost repair [--project name] [--config file] [--config-pattern regex] [--https|--ssl] [--trust] [--reallocate-port] [--prune-registry]
 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 release <patch|minor|major>
 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]
@@ -614,6 +639,7 @@ import { localGhostPlugin } from "@hamedb89/localghost/vite";
 - 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.
+- To release the CLI, run `localghost release patch`, `localghost release minor`, or `localghost release major`. The command dispatches the **Release** workflow from `main`; it synchronizes version metadata, verifies the package and runtime matrix, commits and tags the bump, publishes npm, and creates a GitHub Release with generated notes. GitHub CLI must be installed and authenticated.
 - 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`.
@@ -624,7 +650,7 @@ import { localGhostPlugin } from "@hamedb89/localghost/vite";
 - [Rendered docs](https://hamedb89.github.io/localghost/docs/)
 - [User flows](./docs/flows.md)
 - [CLI reference](./docs/localghost.1.md)
-- [Ghost Tunnel guide](./docs/ghost-tunnel.md)
+- [Ghost Tunnel guide (experimental)](./docs/ghost-tunnel.md)
 - [macOS widget notes](./docs/macos-widget.md)
 - [Brand guidelines](./docs/brand.md)