Ephemeral exposures: short-lived site and port or hostname with a TTL, for shark expose

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

README.md

@@ -259,6 +259,19 @@ Blacktip redirects an unauthenticated visitor to Hammerhead's login page. Hammer
 token with a per-edge key and sends the visitor back; Blacktip verifies it and sets a cookie. The same
 decision function runs in both proxy modes.
 
+## Ephemeral exposures (`shark expose`)
+
+A short-lived port or website for development, created and removed by an API key. [shark-expose](https://git.veillax.com/Veillax/shark-expose) is the command-line client; the API is plain JSON, with an API key (**Access**) as the bearer token. `-` can stand for the key's own organization in the path.
+
+| Call | Does |
+|---|---|
+| `POST /api/orgs/-/expose` | `{proto: "http"\|"https"\|"tcp", targetPort, targetHost?, name?, ttlSeconds?, port?, hostname?, edgeId?, auth?: {password?, pin?, sso?}}`. Makes a site and a port on an online edge, and returns the public address plus `siteToken`, the token Bamboo dials in with. |
+| `POST /api/orgs/-/expose/{id}/renew` | Pushes the deadline out by `ttlSeconds` (default 300) from now. |
+| `GET /api/orgs/-/expose[/{id}]` | Lists exposures, with whether the edge reports the port listening. |
+| `DELETE /api/orgs/-/expose/{id}` | Removes it now. Stopping twice is fine. |
+
+TCP gets a free port from 20000-29999. A website gets `<name>-<random>.<one of your domains>` (so a wildcard DNS record for that domain should point at the edge) on port 80/443, or on `port`. An exposure that isn't renewed within its TTL (30 seconds to 24 hours) is removed, along with its site and any login secrets. The dashboard shows them with the `ephemeral` tag; the deadlines live in memory, so a Hammerhead restart removes any that are still there. An organization can have 20 at a time.
+
 ## Design
 
 The dashboard follows the Lightwell design language: warm neutrals, one teal accent, system fonts, status badges with text, and dialogs that name what they affect. See [docs/design.md](docs/design.md). `node scripts/lint-design.mjs` checks the rules that a machine can check.