Merge branch 'main' into dependabot/npm_and_yarn/examples/next-app/next-16.1.5

Author: roodboi

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

@@ -1,25 +1,88 @@
 ---
 name: hack-cli
 description: >
-  Use the hack CLI for local dev environments (docker compose, logs, run commands) and agent integration setup.
-  Trigger when asked to start/stop services, open project URLs, inspect logs, run commands in services, manage
-  branch instances, or configure agent integrations (Cursor/Claude/Codex/MCP). Prefer CLI over MCP when shell
-  access is available.
+  Use the hack CLI for local runtime orchestration (compose, DNS/TLS, logs, sessions, tickets) and agent setup.
+  Trigger when asked to run/start/stop services, inspect logs, manage lifecycle/session workflows, or update
+  agent integrations. Prefer CLI over MCP when shell access is available.
 ---
 
 # hack CLI
 
-Use hack CLI as the primary interface for local dev.
+Use `hack` as the primary interface for local development.
+
+## Operating Rules
+
+- Prefer `hack` over raw `docker` / `docker compose`.
+- Do not start/stop project services from Docker Desktop UI for `hack`-managed repos.
+- Treat `.hack/.internal` and `.hack/.branch` as hack-managed artifacts; avoid hand-editing generated files.
+- Use MCP only when shell access is unavailable.
+- Run `hack doctor` (and `hack doctor --fix`) before manual runtime/network repair.
+
+## Config + Schema
+
+- Project config: `.hack/hack.config.json`
+- Global config: `~/.hack/hack.config.json`
+- Schema URL: `https://schemas.hack/hack.config.schema.json`
+- Prefer CLI config edits via `hack config get/set`.
+
+## Hostname Routing
+
+- Primary host is `dev_host` (default: `<project>.hack`).
+- Subdomains use `<sub>.<dev_host>` (for example: `api.myapp.hack`).
+- OAuth alias can add `<dev_host>.<tld>` and `<sub>.<dev_host>.<tld>` (default: `gy`).
+- Only HTTP services with Caddy labels and `hack-dev` network attachment are routable.
+- Required labels: `caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`.
+- Quick checks: `hack open`, `hack open <sub>`, `hack open --json`.
+
+## TLS + OAuth Host Rules
+
+- Caddy internal PKI provides HTTPS for routed hosts; trust CA with `hack global trust`.
+- `.hack` is local-first and not a public suffix.
+- Use alias hosts like `*.hack.gy` when provider callback validation rejects non-public-suffix hosts.
+- Alias hosts are local routes unless you explicitly add remote ingress/tunnel plumbing.
+
+## Managed Files
+
+- Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.json`.
+- Local-only files: `.hack/.env` and `.hack/.internal/` (gitignored; machine-specific state).
+- Generated by hack: `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Managed via CLI: `.hack/.internal/extra-hosts.json` using `hack internal extra-hosts ...` commands.
+- Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
+
+## Advanced Networking
+
+- Static host mappings: set `internal.extra_hosts` in `.hack/hack.config.json`.
+- Dynamic mappings for local proxies/tunnels: `hack internal extra-hosts set <hostname> <target>`.
+- List/remove mappings: `hack internal extra-hosts list` / `hack internal extra-hosts unset <hostname>`.
+- Prefer `host-gateway` for host-local proxy targets when possible.
+- Apply changes with `hack restart`; verify with `hack doctor`.
 
 ## Quick Start
 
+- Bootstrap project config: `hack init`
 - Start services: `hack up --detach`
+- Alternate shorthand: `hack up -d`
+- Restart services: `hack restart`
 - Open app: `hack open --json`
-- Tail logs: `hack logs --pretty`
+- Tail logs (compose): `hack logs --pretty`
+- Per-service logs: `hack logs <service>`
 - Snapshot logs: `hack logs --json --no-follow`
+- Loki history/query: `hack logs --loki --since 2h --pretty`
 - Run commands: `hack run <service> <cmd...>`
 - Stop services: `hack down`
 
+## Global Infra
+
+- Install once: `hack global install`
+- Start/stop/status: `hack global up`, `hack global down`, `hack global status`
+- Global logs: `hack global logs <service> --no-follow --tail 200`
+
+## Lifecycle + Startup
+
+- Put host setup in `.hack/hack.config.json` under `startup` / `lifecycle`.
+- Use lifecycle processes for long-running host tasks, not ad-hoc terminals.
+- Inspect via `hack projects --details` and `hack logs <service-or-process>`.
+
 ## Branch Instances
 
 Use branch instances to run parallel environments:
@@ -29,28 +92,42 @@ Use branch instances to run parallel environments:
 - `hack logs --branch <name>`
 - `hack down --branch <name>`
 
-## Logs
+## Sessions
+
+- Picker: `hack session`
+- Start/attach: `hack session start <project>`
+- Isolated agent session: `hack session start <project> --new --name agent-1`
+- Exec: `hack session exec <session> "<command>"`
+- Stop: `hack session stop <session>`
+
+## Tickets
 
-- Loki history: `hack logs --loki --since 2h --pretty`
-- Filter services: `hack logs --loki --services api,web`
-- Force compose logs: `hack logs --compose`
+- Create: `hack tickets create --title "..." --body-stdin`
+- List/show: `hack tickets list`, `hack tickets show T-00001`
+- Status/sync: `hack tickets status T-00001 in_progress`, `hack tickets sync`
 
 ## Project Targeting
 
 - Run from repo root when possible.
 - Otherwise use `--project <name>` or `--path <repo-root>`.
 - List projects: `hack projects --json`.
 
-## Daemon (optional)
+## Agent Maintenance
 
-- Start for faster JSON status/ps: `hack daemon start`
-- Check status: `hack daemon status`
+- Project-level hack commands auto-check integration drift and attempt auto-sync.
+- Set `HACK_SETUP_SYNC_MODE=warn` to warn-only, or `HACK_SETUP_SYNC_MODE=off` to disable.
+- Refresh project + global integrations: `hack setup sync --all-scopes`
+- Check generated integrations: `hack setup sync --all-scopes --check`
+- Remove generated integrations: `hack setup sync --all-scopes --remove`
+- After self-update: `hack update` then `hack setup sync --all-scopes`
 
 ## Agent Setup
 
 - Cursor rules: `hack setup cursor`
 - Claude hooks: `hack setup claude`
 - Codex skill: `hack setup codex`
+- Tickets skill: `hack setup tickets`
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
 - Init patterns: `hack agent patterns`
 - MCP (no shell only): `hack setup mcp`
+- MCP install (explicit): `hack mcp install --all --scope project`

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

@@ -9,12 +9,14 @@ description: >
 # hack tickets
 
 This repo uses the hack tickets extension (`dance.hack.tickets`).
+Prefer `hack tickets ...` (alias) or `hack x tickets ...` over manual edits in `.hack/tickets/`.
 
 ## Enable
 
 Enable globally:
 
 - `hack config set --global 'controlPlane.extensions["dance.hack.tickets"].enabled' true`
+- `hack setup sync --all-scopes` (refresh generated agent instructions + skills + MCP config)
 
 Or per-project by adding `.hack/hack.config.json`:
 
@@ -61,3 +63,5 @@ Tip: use `--body-stdin` for multi-line markdown.
 - Keep ticket titles short; put detail in `--body`.
 - Use `--json` for agent workflows and piping.
 - Run `hack x tickets sync` before opening PRs if you want tickets to travel with the repo.
+- Update status continuously (`open` -> `in_progress` -> `blocked`/`done`) so handoffs are explicit.
+- Use `--depends-on` / `--blocks` links to model execution order for parallel agent work.