diff --git a/docs/console-and-the-flow.md b/docs/console-and-the-flow.md
index 666a5fc8..d5541ddf 100644
--- a/docs/console-and-the-flow.md
+++ b/docs/console-and-the-flow.md
@@ -23,7 +23,7 @@ destination under it is the signed-in user's.
 | Group     | Destinations                                                     | Route                                                                                              | What the user does there                               | RBAC family                                    |
 | --------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------- |
 | Observe   | Search, Saved Searches, Chart Explorer, Dashboards, Hunt Results | `/observe/search`, `/observe/search/list`, `/observe/chart`, `/observe/dashboards`, `/observe/hunt-results` | look at the data                                       | `dashboard_read`                               |
-| Data flow | Sources, Meta Schemas, Library                                   | `/sources`, `/schemas`, `/library`                                                                 | define what comes in, how it is shaped, where it lands | `source_*`, `schema_*`, `library_*`            |
+| Data flow | Sources, Meta Schemas, Library                                   | `/sources`, `/schemas`, `/library`                                                                 | define what comes in, its fields, where it lands       | `source_*`, `schema_*`, `library_*`            |
 | Detect    | Rules, Hunts                                                     | `/rules`, `/hunts`                                                                                 | define what to look for                                | `rule_*`, `hunt_*`                             |
 | Stack     | Components, Admin Tools                                          | `/components`, `/admin-tools`                                                                      | see and tune what is running                           | `deployment_read`, `helmvars_read`, `helmvars_write`, `deployment_admin_links_read` |
 
@@ -83,7 +83,7 @@ Both live on the source form's first tab, beside the name:
 - **Archive** -- keep the raw record as it arrived. The archiver reads the
   landing topic, so this needs the bus.
 
-## Reading an app's shape rather than naming it
+## Reading an app's manifest rather than naming it
 
 The Stack destinations render from `GET /api/v1/apps`, whose entries come from
 the app manifest. Nothing in the console is keyed to an app's name:
diff --git a/docs/create-schema-form.md b/docs/create-schema-form.md
index 30f7d306..9fd85680 100644
--- a/docs/create-schema-form.md
+++ b/docs/create-schema-form.md
@@ -44,7 +44,7 @@ Implications:
 
 ### Full-form Zod validation per field rule
 
-`useAntdZodResolver` implements each `Form.Item` rule by calling `schema.safeParseAsync(getFieldsValue())` — i.e. it parses the **entire** form shape for **every** validated control path that uses `formValidation`.
+`useAntdZodResolver` implements each `Form.Item` rule by calling `schema.safeParseAsync(getFieldsValue())` — i.e. it parses the **entire** form value for **every** validated control path that uses `formValidation`.
 
 With large `uploadedColumns` / `schemaColumns` lists, **each** triggered validation can mean a **full** parse of the combined schema. Many cells × many validations scales poorly even when the table paginates visible rows.
 
diff --git a/docs/local-development.md b/docs/local-development.md
index 1ab3162b..760f21c4 100644
--- a/docs/local-development.md
+++ b/docs/local-development.md
@@ -72,7 +72,7 @@ The fork iframe is optional for console work. Wiring it up is covered in
 | `INTERNAL_API_URL`                 | runtime            | engine base URL for server-side fetches (middleware, NextAuth)                             |
 | `NEXTAUTH_URL` / `NEXTAUTH_SECRET` | runtime            | NextAuth session config -- any non-empty secret works for dev                              |
 | `DFE_COOKIE_DOMAIN`                | runtime            | parent domain for the `dfe_token` cookie -- leave unset locally                            |
-| `HYPERDX_URL` / `HYPERDX_PORT`     | runtime            | the embed pair, either shape -- see [observe-embed.md](observe-embed.md)                   |
+| `HYPERDX_URL` / `HYPERDX_PORT`     | runtime            | the embed pair, either variable -- see [observe-embed.md](observe-embed.md)                |
 | `LOG_LEVEL`                        | runtime            | server log threshold, `DEBUG` to `ERROR`, default `INFO`                                   |
 | `LOG_FORMAT`                       | runtime            | `json` or `text`. Unset writes JSON in production or with an OTLP endpoint, text otherwise |
 
diff --git a/docs/observe-embed.md b/docs/observe-embed.md
index a2c7bdb1..bfad5204 100644
--- a/docs/observe-embed.md
+++ b/docs/observe-embed.md
@@ -13,11 +13,11 @@ flowchart LR
 
 ## How it is configured
 
-One runtime mechanism, two deployment shapes. The `(auth)` layout reads both
+One runtime mechanism, two ways to reach dfe-hyperdx. The `(auth)` layout reads both
 values per request and hands them to `HyperdxContext`; `useHyperdxUrl()` is
 the single source the iframe URL and the sidebar gating read.
 
-| Variable       | Shape                                                                                                                        |
+| Variable       | Points at                                                                                                                    |
 | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `HYPERDX_URL`  | dfe-hyperdx on its own hostname (k8s gateway: `https://hyperdx.{domain}`). Wins when set.                                        |
 | `HYPERDX_PORT` | Same host, different port (docker compose). Host comes from `window.location`, so it is correct for localhost and LAN alike. |