feat(open): prefer OAuth alias URLs

.codex/skills/hack-cli/SKILL.md

@@ -12,11 +12,11 @@ Use `hack` as the primary interface for local-first development.
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.3.6; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `64098e5ae1ea` (version alone is not a freshness guarantee).
+- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -52,6 +52,7 @@ Use `hack` as the primary interface for local-first development.
 - Primary host comes from `dev_host` (default: `<project>.hack`).
 - Subdomain pattern is `<sub>.<dev_host>` (for example: `api.myapp.hack`).
 - OAuth alias (when enabled) also routes `<dev_host>.<tld>` and `<sub>.<dev_host>.<tld>` (default tld: `gy`).
+- Browser launches automatically prefer a routed OAuth alias when enabled; custom development hosts outside `.hack` stay on the primary host. Set `open.prefer` or pass `hack open --prefer <auto|alias|dev>` to override.
 - Not every compose service is routable: only services with Caddy labels and on `hack-dev` are exposed.
 - Required labels for HTTP services: `caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`.
 - Quick checks: `hack open`, `hack open <sub>`, `hack open --json`.
@@ -70,7 +71,7 @@ Use `hack` as the primary interface for local-first development.
 - Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
 - Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
 - Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
-- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.internal/compose.runtime.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.branch/compose.<branch>.runtime.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
 - Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
@@ -104,7 +105,7 @@ Use `hack` as the primary interface for local-first development.
 - Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
 - Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
 - Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
-- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+- Browser/host URL: use `hack open <service> --json` (OAuth aliases are preferred when enabled). Container-to-container traffic should use Compose DNS.
 
 ## Logs (default is compose)
 

.cursor/rules/hack.mdc

@@ -7,11 +7,11 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.3.6; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `64098e5ae1ea` (version alone is not a freshness guarantee).
+- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -34,7 +34,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
 - Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
 - Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
-- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.internal/compose.runtime.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.branch/compose.<branch>.runtime.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
 - Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
@@ -61,7 +61,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
 - Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
 - Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
-- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+- Browser/host URL: use `hack open <service> --json` (OAuth aliases are preferred when enabled). Container-to-container traffic should use Compose DNS.
 
 ## Lifecycle + startup
 

AGENTS.md

@@ -210,11 +210,11 @@ Most formatting and common issues are automatically fixed by Biome. Run `bun x u
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.3.6; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `64098e5ae1ea` (version alone is not a freshness guarantee).
+- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -245,6 +245,7 @@ Hostname routing + Caddy labels:
 - Primary host comes from `dev_host` (default: `<project>.hack`).
 - Subdomain pattern is `<sub>.<dev_host>` (for example: `api.myapp.hack`).
 - OAuth alias (when enabled) also routes `<dev_host>.<tld>` and `<sub>.<dev_host>.<tld>` (default tld: `gy`).
+- Browser launches automatically prefer a routed OAuth alias when enabled; custom development hosts outside `.hack` stay on the primary host. Set `open.prefer` or pass `hack open --prefer <auto|alias|dev>` to override.
 - Not every compose service is routable: only services with Caddy labels and on `hack-dev` are exposed.
 - Required labels for HTTP services: `caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`.
 - Quick checks: `hack open`, `hack open <sub>`, `hack open --json`.
@@ -261,7 +262,7 @@ Project files (managed vs generated):
 - Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
 - Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
 - Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
-- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.internal/compose.runtime.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.branch/compose.<branch>.runtime.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
 - Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
@@ -291,7 +292,7 @@ Running things (decision guide):
 - Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
 - Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
 - Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
-- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+- Browser/host URL: use `hack open <service> --json` (OAuth aliases are preferred when enabled). Container-to-container traffic should use Compose DNS.
 
 Logs (default is compose):
 - Fast tail: `hack logs --pretty`

CLAUDE.md

@@ -80,11 +80,11 @@ This project uses Obsidian for project context, specs, research, and progress tr
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.3.6; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `64098e5ae1ea` (version alone is not a freshness guarantee).
+- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -115,6 +115,7 @@ Hostname routing + Caddy labels:
 - Primary host comes from `dev_host` (default: `<project>.hack`).
 - Subdomain pattern is `<sub>.<dev_host>` (for example: `api.myapp.hack`).
 - OAuth alias (when enabled) also routes `<dev_host>.<tld>` and `<sub>.<dev_host>.<tld>` (default tld: `gy`).
+- Browser launches automatically prefer a routed OAuth alias when enabled; custom development hosts outside `.hack` stay on the primary host. Set `open.prefer` or pass `hack open --prefer <auto|alias|dev>` to override.
 - Not every compose service is routable: only services with Caddy labels and on `hack-dev` are exposed.
 - Required labels for HTTP services: `caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`.
 - Quick checks: `hack open`, `hack open <sub>`, `hack open --json`.
@@ -131,7 +132,7 @@ Project files (managed vs generated):
 - Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
 - Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
 - Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
-- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.internal/compose.runtime.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.branch/compose.<branch>.runtime.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
 - Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
@@ -161,7 +162,7 @@ Running things (decision guide):
 - Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
 - Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
 - Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
-- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+- Browser/host URL: use `hack open <service> --json` (OAuth aliases are preferred when enabled). Container-to-container traffic should use Compose DNS.
 
 Logs (default is compose):
 - Fast tail: `hack logs --pretty`

docs/architecture.md

@@ -62,7 +62,8 @@ graph LR
 
 - Project scope (`.hack`)
   - `docker-compose.yml` defines services + Caddy labels
-  - `hack.config.json` stores project name, dev host, log preferences, OAuth alias
+  - `hack.config.json` stores project name, dev host, log preferences, OAuth alias, and browser
+    launch preference (`open.prefer`)
   - `controlPlane.gateway.enabled` marks the project as gateway-capable
   - Optional overrides:
     - `.internal/compose.override.yml` (generated internal DNS/TLS injection)
@@ -321,9 +322,11 @@ one, or set `worktree.auto_branch=false` to opt into the base instance explicitl
   - `.env` (optional, only when explicitly materialized)
   - `.internal/compose.override.yml`
   - `.internal/compose.env.override.yml`
+  - `.internal/compose.runtime.override.yml`
   - `.internal/extra-hosts.json`
   - `.internal/lifecycle/state.json` and `.internal/lifecycle/*.log`
   - `.branch/compose.<branch>.override.yml`
+  - `.branch/compose.<branch>.runtime.override.yml`
 
 ## Key design choices