From 5916ba5f3c5f156f9de5ea57030f026177da03a0 Mon Sep 17 00:00:00 2001
From: Hernan Alvarez <hernan@skybook.tailb6cc3.ts.net>
Date: Sat, 17 Oct 2026 20:04:31 -0700
Subject: [PATCH 1/2] Docs: say host, not machine, for the enrolled computer

Vocabulary pass per Positioning Fundamentals v6.6, Section 10. Defines host
once on the overview and on Connect a host; headings and anchors follow
(connect-a-host, disconnect-a-host, long-lived-headless-hosts). Where the
mint output still prints gateway, the docs keep the literal and flag it
(#2720).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/CLI.md                  | 10 ++++-----
 docs/CLIENTS.md              |  2 +-
 docs/CLI_REFERENCE.md        | 32 ++++++++++++++-------------
 docs/CONFIGURATION.md        |  4 ++--
 docs/MCP.md                  |  2 +-
 docs/MCP_REFERENCE.md        |  2 +-
 docs/PRIVACY.md              | 42 ++++++++++++++++++------------------
 docs/QUERYING.md             |  8 +++----
 docs/README.md               |  4 ++--
 docs/TEAM_SETUP.md           | 39 +++++++++++++++++----------------
 docs/TROUBLESHOOTING.md      |  6 +++---
 scripts/gen-mcp-reference.js |  2 +-
 12 files changed, 78 insertions(+), 75 deletions(-)

diff --git a/docs/CLI.md b/docs/CLI.md
index 3880ae892..ba3593fda 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -24,8 +24,8 @@ hyp setup
 ```
 
 Select **Sync to the cloud** to store your recordings on HypAware Cloud or
-choose **Local only** to keep recordings on your machine. To change this later,
-see [connect a machine](TEAM_SETUP.md#connect-a-machine).
+choose **Local only** to keep recordings on your host. To change this later,
+see [connect a host](TEAM_SETUP.md#connect-a-host).
 
 Setup then asks which AI clients to record, installs the background service,
 connects the clients you selected, and imports their supported session history.
@@ -85,7 +85,7 @@ attention, with guidance to help resolve problems. For capture checks, see
 The daemon keeps capture and scheduled sync running after you close the terminal.
 Setup installs it as a per-user service. On macOS, its LaunchAgent runs while
 you are logged in. On Linux, its systemd user service requires user-session
-support; see [headless deployment](TEAM_SETUP.md#long-lived-headless-machines)
+support; see [headless deployment](TEAM_SETUP.md#long-lived-headless-hosts)
 for hosts that must keep running after logout.
 
 ```sh
@@ -105,7 +105,7 @@ hyp setup
 ```
 
 Select **Reconfigure** in the menu. HypAware preserves a centrally managed
-configuration layer and changes only the choices this machine owns.
+configuration layer and changes only the choices this host owns.
 
 For unattended replacements and configuration files, see
 [repeatable configuration](CONFIGURATION.md#make-a-repeatable-setup).
@@ -163,7 +163,7 @@ detached, replacing `<client>` with its name, such as `claude` or `codex`.
 ## Uninstall
 
 ```sh
-hyp leave                  # if this machine is enrolled in Cloud
+hyp leave                  # if this host is enrolled in Cloud
 hyp daemon uninstall
 npm uninstall -g hypaware
 ```
diff --git a/docs/CLIENTS.md b/docs/CLIENTS.md
index 2d762ae89..937325a51 100644
--- a/docs/CLIENTS.md
+++ b/docs/CLIENTS.md
@@ -158,7 +158,7 @@ hyp client status ollama
 
 To add Ollama on an existing installation while preserving its export choice,
 run `hyp setup --source ollama` without `--export`. An explicit `--export` changes
-that choice. Other clients are preserved; check `hyp status` to see your sinks. Recorded local inference can leave the machine through configured sinks.
+that choice. Other clients are preserved; check `hyp status` to see your sinks. Recorded local inference can leave the host through configured sinks.
 Setup checks the service and model inventory without starting Ollama, downloading
 or loading a model, or sending inference. Missing executable, unavailable service
 and empty model inventory are separate results. SDK use does not need the CLI
diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md
index 7a77c73ba..bf2382dd6 100644
--- a/docs/CLI_REFERENCE.md
+++ b/docs/CLI_REFERENCE.md
@@ -70,7 +70,7 @@ clients with scheduled recovery still import history. Neither flag applies to
 a preset.
 
 With no arguments and no output terminal, setup prints an agent guide on
-stdout and exits `0` without configuring the machine. It lists detected
+stdout and exits `0` without configuring the host. It lists detected
 sources, recording disclosures, choices and commands, browser sign-in
 handoffs, and verification. An agent asks the person before selecting sources
 or enabling cloud sync, then runs explicit unattended flags. `hyp setup
@@ -497,9 +497,9 @@ hyp report list [--local] [--kind <kind>] [--period <period>] [--limit <n>] [--b
 ```
 
 Lists the newest reports visible to the selected organization, then this
-machine's saved reports (`$HYP_HOME/reports`, as `hyp report save` leaves
+host's saved reports (`$HYP_HOME/reports`, as `hyp report save` leaves
 them) in their own section, newest first by `report.md` mtime, at most 100
-with the rest counted. A machine with nothing saved prints no section.
+with the rest counted. A host with nothing saved prints no section.
 `--local` prints the saved section alone, with no remote read, and takes none
 of the remote's selectors or filters. When nothing selects or filters the
 remote and it cannot be read, the saved reports are still listed under a
@@ -727,7 +727,7 @@ hyp sync [instance] [--history <client>] [--yes] [--dry-run]
 
 Prints a destination and exclusion plan, confirms it, then forces the selected
 sink or every configured sink to export. `--dry-run` sends nothing. On a newly
-enrolled machine, an interactive all-destination sync can release the
+enrolled host, an interactive all-destination sync can release the
 first-sync review hold early. A single-instance sync can't release that hold.
 
 `--history <client>` is a separate mode: it previews and, after its own
@@ -1352,7 +1352,7 @@ hyp privacy show . --json
 hyp privacy set <path> sync|local-only|ignore
 ```
 
-Upserts an exact machine-local path marking. It doesn't write a dotfile or
+Upserts an exact host-local path marking. It doesn't write a dotfile or
 delete rows. An `ignore` marking prints a line naming
 `hyp privacy purge --ignored`, which deletes what was already recorded in
 every ignored folder.
@@ -1367,7 +1367,7 @@ hyp privacy set ./private-research local-only
 hyp privacy unset <path> [sync|local-only|ignore]
 ```
 
-Removes machine-local entries governing the path. Add a class to remove only
+Removes host-local entries governing the path. Add a class to remove only
 entries of that class. The operation is idempotent and doesn't delete rows.
 
 ```sh
@@ -1380,7 +1380,7 @@ hyp privacy unset ./private-research local-only
 hyp privacy list [--json]
 ```
 
-Lists machine-local path and client policy plus the new-folder prompt
+Lists host-local path and client policy plus the new-folder prompt
 preference. It can't globally enumerate `.hypignore` files; use
 `hyp privacy show PATH` for a specific path.
 
@@ -1397,7 +1397,7 @@ hyp privacy ignore [path]
 Writes a shareable `.hypignore` file in an existing directory at the explicit
 path. With no path, uses
 the repository root, or the current directory when outside a repository.
-Use `hyp privacy set <path> sync|local-only|ignore` for machine-local markings
+Use `hyp privacy set <path> sync|local-only|ignore` for host-local markings
 and `hyp privacy show [path]` to report without writing. The receipt names
 `hyp privacy purge --ignored` to delete what was already recorded in ignored
 folders.
@@ -1413,7 +1413,7 @@ hyp privacy unignore [path]
 ```
 
 Removes the nearest governing `.hypignore`. Use `hyp privacy unset <path>`
-to remove machine-local markings. It does not remove cached rows.
+to remove host-local markings. It does not remove cached rows.
 
 ```sh
 hyp privacy unignore ./customer-data
@@ -1455,7 +1455,7 @@ hyp privacy purge <path> | --session <id> [--remote <target> | --local-only] | -
 ```
 
 **Warning:** This operation permanently deletes matching rows from this
-machine's local cache. Select exactly one target. Every form also sweeps the
+host's local cache. Select exactly one target. Every form also sweeps the
 Claude raw-body spool so pending bodies can't recreate deleted rows. A terminal
 prompts for confirmation; a non-interactive call requires `--yes`.
 
@@ -1543,7 +1543,7 @@ Installs the persistent launchd or systemd user service. When invoked from an
 ephemeral `npx` path, it installs a durable global package before it writes the
 service. `--force` allows the existing CLI path if that global installation
 fails; removing that directory later can break capture. `--dry-run` renders
-the exact service definition without changing the machine; add `--json` for
+the exact service definition without changing the host; add `--json` for
 structured plan output.
 
 ```sh
@@ -1931,13 +1931,13 @@ hyp remote login [name] [--token-file <path>] [--org <org>] [--host <label>] [--
 Signs in through a browser by default, or reads a static token from
 `--token-file` or standard input. It stores the credential with mode `0600`.
 Omit `name` to sign in to the default target. Unless you set `--no-forward`,
-login can enroll this machine, set up sync, and install the daemon.
+login can enroll this host, set up sync, and install the daemon.
 
 - `--org <org>` selects an organization.
 - `--browser` forces browser sign-in when stdin is piped, unless an explicit
   `--token-file` is supplied.
 - `--no-browser` prints the sign-in URL instead of opening a browser.
-- `--host <label>` overrides the host label this machine syncs under, which defaults to the
+- `--host <label>` overrides the host label this host syncs under, which defaults to the
   hostname.
 - `--no-forward` signs in for queries only, with no organization enrollment.
 - `--no-daemon` sets up sync without installing the service.
@@ -1957,9 +1957,11 @@ hyp remote mint [name] [--scope query] [--label <label>] [--expires-days <n>]
 Mints a long-lived CI enrollment token from your logged-in session and prints
 it once, for pasting into CI secrets. It requires a session stored by
 `hyp remote login`. Omit `name` to mint against the default target.
-`--label` names the gateway the token is bound to, and `--expires-days`
+`--label` names the host the token is bound to, and `--expires-days`
 overrides the 365-day default. Every CI run that joins with the token shares
-that one gateway, and the token itself never rotates.
+that one host record, and the token itself never rotates. Mint prints its
+id on standard error, shown as gateway in the current CLI output; this is the
+host record.
 
 ```sh
 hyp remote mint team --label repo-ci --expires-days 90
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 823bc9df2..22ec52186 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -20,7 +20,7 @@ To disable automatic updates, set `"auto_update": false` and restart the daemon.
 Organization policy may control this setting. Each plugin owns its own `config` block. Use
 `hyp plugin info PLUGIN` to inspect an installed plugin's manifest.
 
-On an enrolled machine, a separate central layer under `config-control/` is
+On an enrolled host, a separate central layer under `config-control/` is
 authoritative. Local settings are additive and cannot override central locks.
 `hyp status --verbose` identifies each layer and any rejected local entries.
 Joining does not replace your local configuration; leaving removes central
@@ -85,7 +85,7 @@ from that cache, not a prerequisite for querying it.
 
 These `--export` flags select unattended setup; they are not extra choices
 inside the guided walkthrough. New guided setups default to local Parquet
-exports; interactive reconfiguration preserves the existing export choice. An enrolled machine may also have a
+exports; interactive reconfiguration preserves the existing export choice. An enrolled host may also have a
 centrally managed sync sink regardless of its local export choice.
 
 For previewing destinations and sending recordings now, see
diff --git a/docs/MCP.md b/docs/MCP.md
index 06326b25a..01012adac 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -9,7 +9,7 @@ ways to connect:
   `hyp` installed and uses your own sign-in. No token is involved.
 - **Remote:** the client connects over HTTPS to your team's server at
   `/v1/mcp` and sends an agent token. Use it for cloud agents, CI jobs, and
-  any client that has no `hyp` on its machine.
+  any client that has no `hyp` on its host.
 
 > **Tip:** At your own computer, use the local setup, even to reach your
 > team's history: `hyp mcp serve --remote` uses the session you already
diff --git a/docs/MCP_REFERENCE.md b/docs/MCP_REFERENCE.md
index 646f353d3..552fb3143 100644
--- a/docs/MCP_REFERENCE.md
+++ b/docs/MCP_REFERENCE.md
@@ -4,7 +4,7 @@
 
 HypAware serves MCP in two places:
 
-- `hyp mcp serve`, over stdio, for an agent on your machine. It lists the tools core and your active plugins register.
+- `hyp mcp serve`, over stdio, for an agent on your host. It lists the tools core and your active plugins register.
 - hypaware-server's `/v1/mcp`, over HTTP, for an agent with a member session or an agent token. What it lists depends on the credential.
 
 Every tool below has a CLI command that does the same thing. Each tool's `tools/list` entry carries its title, description, input schema and hints, as shown here.
diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md
index 2fa0dcaf6..ed8bfee45 100644
--- a/docs/PRIVACY.md
+++ b/docs/PRIVACY.md
@@ -1,6 +1,6 @@
 # What HypAware records, and how to control it
 
-HypAware records AI activity on your machine. This page explains what is
+HypAware records AI activity on your host. This page explains what is
 captured, where it goes, and how to control it. If your team is rolling
 HypAware out, read this page before you enroll.
 
@@ -43,7 +43,7 @@ transcripts under `~/.claude/projects`.
 
 Spool cleanup works as follows:
 
-- A session you ignored, by `.hypignore`, by a machine-local marking, or with
+- A session you ignored, by `.hypignore`, by a host-local marking, or with
   `hyp session ignore`, has its bodies **deleted unread**, not skipped.
 - The default cap is 512 MB, configured as `telemetry.spool_max_bytes` in
   the `@hypaware/claude` plugin's config. The listener and Claude hooks enforce
@@ -101,7 +101,7 @@ organization unless you saved a preference. It is separate from session recordin
 
 Every directory subtree resolves to one class. Starting at the session's
 working directory, HypAware uses the nearest ancestor `.hypignore` file and
-the most-specific matching machine-local marking. It then takes the most
+the most-specific matching host-local marking. It then takes the most
 restrictive result across those sources: `ignore`, then `local-only`, then
 `sync`. This is not a merge of every ancestor file.
 
@@ -111,7 +111,7 @@ restrictive result across those sources: `ignore`, then `local-only`, then
 | `local-only` | yes              | never                        |
 | `ignore`     | never            | never                        |
 
-`local-only` rows stay fully queryable on your own machine; they are
+`local-only` rows stay fully queryable on your own host; they are
 withheld at the export seam, so no sink or remote query can see them.
 
 ## Marking directories
@@ -129,8 +129,8 @@ There are two authoring surfaces for the same classes:
 
   An empty or comment-only `.hypignore` also means `ignore`.
 
-- **A machine-local store** (`hyp privacy`) records the class privately on
-  this machine, never as a file in the repo. Use it when the marking itself
+- **A host-local store** (`hyp privacy`) records the class privately on
+  this host, never as a file in the repo. Use it when the marking itself
   is sensitive (a dotfile in a hidden directory is a breadcrumb pointing at
   exactly the thing you are hiding), or when the path is not a repo:
 
@@ -139,11 +139,11 @@ There are two authoring surfaces for the same classes:
   hyp privacy set <path> local-only    # recorded, never synced
   hyp privacy set <path> sync          # explicitly synced (not asked again)
   hyp privacy show [path]              # which class governs, and why
-  hyp privacy list                     # every machine-local entry
+  hyp privacy list                     # every host-local entry
   hyp privacy unset <path> [class]     # back to the implicit default
   ```
 
-On a machine connected to HypAware Cloud, folders you have not marked sync
+On a host connected to HypAware Cloud, folders you have not marked sync
 without asking. You can instead be asked, once per new folder, how to
 handle it, at the moment you open a session there:
 
@@ -155,9 +155,9 @@ hyp privacy folders        # report which is in force
 
 This gates the question only. In either setting, folders you already
 marked keep their class, `.hypignore` files are unaffected, and nothing
-already local-only or ignored starts syncing. The setting is machine-local
+already local-only or ignored starts syncing. The setting is host-local
 and reversible, `hyp setup` asks for it in its own step, and `hyp status`
-names it on an enrolled machine.
+names it on an enrolled host.
 
 Three caveats apply to both surfaces:
 
@@ -186,7 +186,7 @@ for them.
 
 ## Control a whole client's sharing
 
-Keep a locally configured client's recordings on this machine:
+Keep a locally configured client's recordings on this host:
 
 ```sh
 hyp privacy client codex local-only
@@ -237,7 +237,7 @@ to delete previously captured rows.
 
 ## Deleting what was already recorded
 
-`hyp privacy purge` permanently deletes rows from this machine's local cache:
+`hyp privacy purge` permanently deletes rows from this host's local cache:
 
 ```sh
 hyp privacy purge <path>          # rows whose cwd is at or under the path
@@ -248,14 +248,14 @@ hyp privacy purge --all           # everything, wholesale
 
 It prompts on a TTY; pass `--yes` for non-interactive use.
 
-> **Caution:** A session purge is the only form that reaches beyond this machine. It also
+> **Caution:** A session purge is the only form that reaches beyond this host. It also
 > deletes that session's rows from every configured or signed-in remote and
 > every enrolled server, and keeps the session from being recorded again. The
 > confirmation prompt names the servers it will contact:
 
 ```sh
-hyp privacy purge --session <id> --remote <target>  # this machine and one server
-hyp privacy purge --session <id> --local-only       # this machine only
+hyp privacy purge --session <id> --remote <target>  # this host and one server
+hyp privacy purge --session <id> --local-only       # this host only
 ```
 
 Deleting on a server uses your login, and needs you to be the session's owner
@@ -275,13 +275,13 @@ next batch write back rows you just deleted.
 ## Review before the first Cloud sync
 
 Before sharing recordings, review captured directories with the
-`hypaware-privacy` skill in Claude Code or Codex. It checks this machine's local
+`hypaware-privacy` skill in Claude Code or Codex. It checks this host's local
 cache, samples recordings, and proposes directory markings and deletions for
 your confirmation. A review cannot guarantee it will find every secret, and it
 does not automatically redact all recorded content. You can run it at any time,
 even without Cloud enrollment.
 
-<!-- agent: Run the hypaware-privacy skill: review what this machine has recorded, sample it, and propose which folders to mark local-only or ignore before anything syncs. Do not delete anything without asking me. -->
+<!-- agent: Run the hypaware-privacy skill: review what this host has recorded, sample it, and propose which folders to mark local-only or ignore before anything syncs. Do not delete anything without asking me. -->
 ```sh
 hyp privacy show
 hyp privacy list
@@ -290,8 +290,8 @@ hyp privacy list
 For the enrollment hold, deadline, and unattended behavior, see
 [the first-sync review](TEAM_SETUP.md#review-before-the-first-upload).
 
-For disconnecting a machine while retaining its local recordings, see
-[Cloud and teams](TEAM_SETUP.md#disconnect-a-machine).
+For disconnecting a host while retaining its local recordings, see
+[Cloud and teams](TEAM_SETUP.md#disconnect-a-host).
 
 ## The daemon's own telemetry
 
@@ -311,7 +311,7 @@ separate; see [data paths](CONFIGURATION.md#know-where-data-lives).
 
 Product telemetry reports how HypAware itself is running. It is enabled for an
 enrolled organization unless you saved an `off` or `local` preference. An
-already-enrolled machine starts reporting on its next CLI run or daemon start
+already-enrolled host starts reporting on its next CLI run or daemon start
 after an upgrade, without a new prompt. Standalone installations default to off.
 Check the effective state and destination:
 
@@ -320,7 +320,7 @@ Check the effective state and destination:
 hyp telemetry status
 ```
 
-Organization telemetry goes to the HypAware server this machine is enrolled
+Organization telemetry goes to the HypAware server this host is enrolled
 with, using its existing enrollment. The CLI does not send telemetry anywhere
 else. The server also copies the HypAware version, OS family, and configured
 client names to PostHog for product analytics, where they are kept until
diff --git a/docs/QUERYING.md b/docs/QUERYING.md
index bcd0521a9..9bfc053c3 100644
--- a/docs/QUERYING.md
+++ b/docs/QUERYING.md
@@ -5,8 +5,8 @@ start a question with `hyp ask` or ask the client you already have open to use
 HypAware. Search and SQL commands are also available below. To generate or share
 a report, see [reports](REPORTS.md).
 
-Queries use this machine's recordings by default. To search recordings in
-HypAware Cloud, including other machines and your team, tell your agent to use
+Queries use this host's recordings by default. To search recordings in
+HypAware Cloud, including other hosts and your team, tell your agent to use
 `--remote` on its query commands. This uses your default remote target;
 `--remote <target>` selects another. See [remote access](TEAM_SETUP.md#manage-remote-access)
 to configure a target and sign in.
@@ -43,7 +43,7 @@ which one to use.
 
 ## See what is available
 
-<!-- agent: Use HypAware to tell me what is recorded on this machine: which datasets, how fresh, and a summary of models, tokens, and tools. Over MCP, read the datasets with query_sql. -->
+<!-- agent: Use HypAware to tell me what is recorded on this host: which datasets, how fresh, and a summary of models, tokens, and tools. Over MCP, read the datasets with query_sql. -->
 ```sh
 hyp cache status
 hyp query overview
@@ -265,7 +265,7 @@ leads, not proof of what was decided. Check incomplete results and later
 relevant sessions before concluding whether a decision still stands.
 
 Team retrieval needs no replicated graph or additional client plugin. The
-server maintains the graph. This machine's own capture graph remains available
+server maintains the graph. This host's own capture graph remains available
 for local activity questions. If remote graph data is unavailable, use remote
 message searches and disclose that coverage limit.
 
diff --git a/docs/README.md b/docs/README.md
index 18da16223..b137427d0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,7 +1,7 @@
 # HypAware documentation
 
 HypAware records sessions from your AI clients locally so you can search and
-query them on your machine. You can sync your recordings to HypAware Cloud so
+query them on your host. A host is any machine the collector runs on: a laptop, a build box, a remote agent's box. You can sync your recordings to HypAware Cloud so
 your team can search and query them.
 
 ## Quickstart
@@ -14,7 +14,7 @@ hyp setup
 ```
 
 Select **Sync to the cloud** to sync your recordings to HypAware Cloud, or
-choose **Local only** to keep recordings on your machine. Then ask your agent
+choose **Local only** to keep recordings on your host. Then ask your agent
 about your recordings:
 
 ```sh
diff --git a/docs/TEAM_SETUP.md b/docs/TEAM_SETUP.md
index 1af5e6f7f..de7f32d0c 100644
--- a/docs/TEAM_SETUP.md
+++ b/docs/TEAM_SETUP.md
@@ -1,17 +1,17 @@
 # Connect to HypAware Cloud and your team
 
-Get an organization in HypAware Cloud, then set up each machine to join it.
+Get an organization in HypAware Cloud, then set up each host to join it. A host is any machine the collector runs on: a laptop, a build box, a remote agent's box.
 
 ## Get an organization
 
-You can sign in to HypAware Cloud and sync your own machines without setting
+You can sign in to HypAware Cloud and sync your own hosts without setting
 up a team.
 
 For a team, [contact us](https://hypaware.ai/contact?utm_medium=docs) to set up
 an organization for your email domain. Teammates join automatically when they
 sign in with a verified email address from that domain.
 
-## Connect a machine
+## Connect a host
 
 [Install HypAware](CLI.md#install-hypaware), then select **Sync to the cloud**
 in `hyp setup`. If you already configured local capture, either run `hyp setup`
@@ -85,8 +85,8 @@ hyp status
 ```
 
 This reports whether recording is active, what is shared with your team
-versus kept on your machine, and any pending first-sync deadline. To disconnect
-from Cloud while retaining local capture, use [disconnect a machine](#disconnect-a-machine).
+versus kept on your host, and any pending first-sync deadline. To disconnect
+from Cloud while retaining local capture, use [disconnect a host](#disconnect-a-host).
 
 ## Send recordings now
 
@@ -126,13 +126,13 @@ hyp remote list
 hyp remote login <target> --no-forward
 ```
 
-`--no-forward` grants query access without enrolling this machine for sync.
+`--no-forward` grants query access without enrolling this host for sync.
 Use `hyp remote add` to configure
 another target; see the [remote reference](CLI_REFERENCE.md#manage-remote-query-targets)
 for its URL and credential options. For remote searches and SQL, see
 [queries](QUERYING.md#query-a-remote-target).
 
-## Disconnect a machine
+## Disconnect a host
 
 ```sh
 hyp leave
@@ -148,12 +148,12 @@ sign-in. For deletion, see
 
 ## CI and headless deployment
 
-Capture AI client sessions on a machine with no browser and no interactive user:
+Capture AI client sessions on a host with no browser and no interactive user:
 a CI runner, a container, or a long-lived server. Enrollment happens with a
-token minted ahead of time on your own machine, so the headless machine never
+token minted ahead of time on your own host, so the headless host never
 signs in.
 
-Two things make headless different from a laptop install:
+Two things make headless different from an interactive install:
 
 - **No browser sign-in.** Enrollment uses a pre-minted token with
   `hyp join` instead of `hyp remote login`.
@@ -162,7 +162,7 @@ Two things make headless different from a laptop install:
   or supervisor backgrounds, via `hyp join --no-daemon` plus
   `hyp daemon run`.
 
-Every run that joins with one token lands under **one shared gateway** in
+Every run that joins with one token lands under **one shared host** in
 HypAware Cloud, so a pipeline's runs stay grouped together. A token-based join
 syncs immediately: there is no first-sync review hold, because whoever
 minted the token chose enrollment deliberately. See
@@ -170,7 +170,7 @@ minted the token chose enrollment deliberately. See
 
 ## One-time: mint a token
 
-On your own machine, where you are signed in (`hyp remote login`):
+On your own host, where you are signed in (`hyp remote login`):
 
 ```sh
 hyp remote mint
@@ -180,14 +180,15 @@ This prints the token **once**; store it in your CI secret store immediately
 (the examples below call it `HYP_CI_TOKEN`). Only the token goes to standard
 output, so `hyp remote mint > ci.token` captures exactly the secret. Options:
 
-- `--label <label>` names the gateway the token is bound to, for example the
+- `--label <label>` names the host the token is bound to, for example the
   pipeline name.
 - `--expires-days <n>` overrides the 365-day default expiry.
 
 The token never rotates. When it nears expiry, mint a new one and swap the CI
-secret. Minting binds a **new gateway row** at mint time (the id is printed on
+secret. Minting binds a **new host record** at mint time (the id is printed on
 standard error next to the token), so runs before and after the swap group
-under different gateways, and the old row stays in place in HypAware Cloud.
+under different hosts, and the old record stays in place in HypAware Cloud.
+The id is shown as gateway in the current CLI output; this is the host record.
 
 ## Each run: join, capture, flush
 
@@ -258,7 +259,7 @@ jobs:
 > **Tip:** `if: always()` runs the flush even when the agent step fails, which is often
 > the run you most want recorded. HypAware requires **Node 22.12 or newer**.
 
-## Long-lived headless machines
+## Long-lived headless hosts
 
 A server or VM that outlives one job uses the same join, but lets the daemon
 install as a real service where one is available:
@@ -275,13 +276,13 @@ is a LaunchAgent, which needs a logged-in user session. In a container image or
 service manager, keep `--no-daemon` and run `hyp daemon run` as
 the entrypoint or under your own supervisor, and relaunch it when it exits
 with code 75. No teardown flush is needed on a
-machine that keeps running; the scheduled exports drain it. Flush with
-`hyp sync --yes` before deliberately retiring the machine.
+host that keeps running; the scheduled exports drain it. Flush with
+`hyp sync --yes` before deliberately retiring the host.
 
 ### Headless troubleshooting
 
 - `hyp status` on the runner reports whether recording is active, and what is
-  shared with your team versus kept on the machine.
+  shared with your team versus kept on the host.
 - `hyp remote mint` failing with HTTP 404 can mean the server does not support
   token minting or the target points at the wrong server. Mint uses the target's
   origin, so check the scheme and hostname as well as server support.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index cffaf4f9c..4d539a830 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -198,13 +198,13 @@ them ([issue 2225](https://github.com/hyparam/hypaware/issues/2225)). v1.42.0
 stops new skips once the daemon restarts on it; `hyp daemon restart` makes
 sure. Nothing finds the rows already skipped, so recovery is a manual step for
 each destination. It reaches only rows the local cache still holds: rows that
-retention has removed are gone from this machine.
+retention has removed are gone from this host.
 
 <!-- @ref LLP 0345#central: central drops a replayed row it already has, by part id -->
 For HypAware Cloud, `hyp sync --history <client>` resends one client's
 retained `ai_gateway_messages` and leaves normal export progress alone. The
 server drops rows it already has, so a rerun is safe. Run it for each client
-that records on this machine, and read the preview first: the client must be
+that records on this host, and read the preview first: the client must be
 syncing, and the replay also sends rows it held back while it was local-only.
 Folders marked local-only stay withheld. Other datasets, such as traces and
 logs, have no Cloud replay.
@@ -243,7 +243,7 @@ back.
 
 ## A command is missing or rejects an option
 
-<!-- agent: A hyp command or flag from the docs is missing on this machine. Run hyp version and hyp plugin list and tell me whether it is an inactive plugin or an old version. -->
+<!-- agent: A hyp command or flag from the docs is missing on this host. Run hyp version and hyp plugin list and tell me whether it is an inactive plugin or an old version. -->
 ```sh
 hyp version
 hyp --help
diff --git a/scripts/gen-mcp-reference.js b/scripts/gen-mcp-reference.js
index c18c765ae..62375dc04 100644
--- a/scripts/gen-mcp-reference.js
+++ b/scripts/gen-mcp-reference.js
@@ -281,7 +281,7 @@ export async function renderMcpReference() {
     '',
     'HypAware serves MCP in two places:',
     '',
-    '- `hyp mcp serve`, over stdio, for an agent on your machine. It lists the tools core and your active plugins register.',
+    '- `hyp mcp serve`, over stdio, for an agent on your host. It lists the tools core and your active plugins register.',
     '- hypaware-server\'s `/v1/mcp`, over HTTP, for an agent with a member session or an agent token. What it lists depends on the credential.',
     '',
     'Every tool below has a CLI command that does the same thing. Each tool\'s `tools/list` entry carries its title, description, input schema and hints, as shown here.',

From fff451ceb0ae2d959589931b06a1a7b01c4fe80d Mon Sep 17 00:00:00 2001
From: Hernan Alvarez <hernan@skybook.tailb6cc3.ts.net>
Date: Sat, 17 Oct 2026 20:29:12 -0700
Subject: [PATCH 2/2] Docs: say AI provider hosts in the proxy note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/PRIVACY.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md
index ed8bfee45..e7a4966a5 100644
--- a/docs/PRIVACY.md
+++ b/docs/PRIVACY.md
@@ -56,8 +56,8 @@ Spool cleanup works as follows:
 ### Proxy mode and certificate cleanup
 
 Claude Code uses OTEL capture by default. An explicitly configured proxy routes
-HTTPS through the local gateway. The gateway decrypts hosts named by the
-configured capture adapters; other hosts are tunneled without decryption.
+HTTPS through the local gateway. The gateway decrypts AI provider hosts named
+by the configured capture adapters; other hosts are tunneled without decryption.
 Only supported provider API requests are recorded.
 
 The proxy's local certificate authority (CA) is stored under