[pull] main from NVIDIA:main

.agents/skills/build-from-issue/SKILL.md

@@ -177,7 +177,7 @@ In the prompt, instruct the reviewer to:
    - **Medium**: Multiple files/components, some design decisions, but well-scoped
    - **High**: Cross-cutting changes, architectural decisions needed, significant unknowns
 8. Call out risks, unknowns, and decisions that need stakeholder input.
-9. Assess **gateway config documentation impact** — if the change adds, removes, renames, or changes defaults for gateway TOML keys or driver-specific config options, the plan must include an update to `docs/reference/gateway-config.mdx`. If the change is surfaced through Helm or a compute-driver overview, also include `docs/reference/sandbox-compute-drivers.mdx` or the relevant deployment docs.
+9. Assess **gateway config documentation impact** — if the change adds, removes, renames, or changes defaults for gateway TOML keys or driver-specific config options, the plan must include an update to `docs/how-it-works/gateways/configuration.mdx`. If the change is surfaced through Helm or a compute-driver overview, also include `docs/how-it-works/sandboxes/runtimes.mdx` or the relevant deployment docs.
 10. Assess **LSM compatibility** — if the change touches process identity, `/proc` filesystem access, binary execution, or inter-process visibility, flag whether it will behave differently on hosts running SELinux (enforcing) or AppArmor. In particular, tests that fork+exec into system binaries will fail on SELinux-enforcing hosts due to cross-label `/proc/<pid>/exe` access restrictions.
 
 Perform this investigation against the current branch and current product behavior. If the issue contains earlier diagnostics, verify them rather than relying on them.
@@ -474,9 +474,9 @@ behavior or subsystem that changed.
 
 If the implementation changes gateway TOML parsing, `[openshell.gateway]`
 fields, `[openshell.drivers.<name>]` fields, driver config defaults, or Helm
-rendering of `gateway.toml`, update `docs/reference/gateway-config.mdx` in the
+rendering of `gateway.toml`, update `docs/how-it-works/gateways/configuration.mdx` in the
 same branch. If the change affects user-facing compute-driver setup, also
-update `docs/reference/sandbox-compute-drivers.mdx` or the relevant deployment
+update `docs/how-it-works/sandboxes/runtimes.mdx` or the relevant deployment
 page.
 
 Use the `sync-agent-infra` skill's maintenance map to identify related skill updates when the implementation changes behavior, commands, or development workflows. Run its full consistency check when the implementation adds, removes, or renames skills or crates; changes workflow relationships or skill coverage; modifies issue or PR templates; or changes agent cross-references. Fix any drift before committing.

.agents/skills/create-github-pr/SKILL.md

@@ -21,9 +21,9 @@ Create pull requests on GitHub using the `gh` CLI.
 
 If the branch changes gateway TOML parsing, `[openshell.gateway]` fields,
 `[openshell.drivers.<name>]` fields, driver config defaults, or Helm rendering
-of `gateway.toml`, verify that `docs/reference/gateway-config.mdx` is updated
+of `gateway.toml`, verify that `docs/how-it-works/gateways/configuration.mdx` is updated
 in the same branch. If the change affects user-facing compute-driver setup,
-also update `docs/reference/sandbox-compute-drivers.mdx` or the relevant
+also update `docs/how-it-works/sandboxes/runtimes.mdx` or the relevant
 deployment docs.
 
 ### Check Agent Infrastructure

.agents/skills/create-spike/SKILL.md

@@ -93,7 +93,7 @@ The prompt to the reviewer **must** instruct it to:
 
 9. **Check architecture docs** in the `architecture/` directory for relevant documentation about the affected subsystems.
 
-10. **Assess gateway config documentation impact.** If the change would add, remove, rename, or change defaults for gateway TOML keys or driver-specific config options, call out that `docs/reference/gateway-config.mdx` must be updated. If the change is surfaced through Helm or compute-driver setup docs, call out the relevant deployment or compute-driver docs too.
+10. **Assess gateway config documentation impact.** If the change would add, remove, rename, or change defaults for gateway TOML keys or driver-specific config options, call out that `docs/how-it-works/gateways/configuration.mdx` must be updated. If the change is surfaced through Helm or compute-driver setup docs, call out the relevant deployment or compute-driver docs too.
 
 11. **Assess Linux Security Module (LSM) impact.** If the change involves process identity, `/proc` filesystem access, file labeling, binary execution, or inter-process visibility, call out whether it will behave differently on hosts running SELinux (enforcing) or AppArmor. For example: reading `/proc/<pid>/exe` across an SELinux domain boundary returns ENOENT, not EACCES. Tests that fork+exec into system binaries (different SELinux label) will fail on enforcing hosts. Flag any LSM-sensitive code paths and recommend mitigations.
 

.agents/skills/update-docs/SKILL.md

@@ -50,20 +50,20 @@ For each relevant commit, determine which doc page(s) it affects. Use this mappi
 
 | Code area | Likely doc page(s) |
 |---|---|
-| `crates/openshell-cli/` (gateway commands) | `docs/sandboxes/manage-gateways.mdx` |
-| `crates/openshell-cli/` (sandbox commands) | `docs/sandboxes/manage-sandboxes.mdx` |
-| `crates/openshell-cli/` (provider commands) | `docs/sandboxes/manage-providers.mdx` |
+| `crates/openshell-cli/` (gateway commands) | `docs/how-it-works/gateways/overview.mdx` |
+| `crates/openshell-cli/` (sandbox commands) | `docs/how-it-works/sandboxes/overview.mdx` |
+| `crates/openshell-cli/` (provider commands) | `docs/how-it-works/providers/overview.mdx` |
 | `crates/openshell-cli/` (new top-level command) | May need a new page or `docs/reference/` entry |
-| `crates/openshell-server/src/config_file.rs` or gateway TOML parsing | `docs/reference/gateway-config.mdx` |
-| `crates/openshell-server/src/cli.rs` gateway config merge/default behavior | `docs/reference/gateway-config.mdx` |
-| `crates/openshell-driver-*/` config structs or driver defaults | `docs/reference/gateway-config.mdx`, `docs/reference/sandbox-compute-drivers.mdx` |
-| `deploy/helm/openshell/templates/gateway-config.yaml` | `docs/reference/gateway-config.mdx`, `docs/reference/sandbox-compute-drivers.mdx`, Helm docs if values change |
-| Proxy or policy code | `docs/sandboxes/policies.mdx`, `docs/reference/policy-schema.mdx` |
+| `crates/openshell-server/src/config_file.rs` or gateway TOML parsing | `docs/how-it-works/gateways/configuration.mdx` |
+| `crates/openshell-server/src/cli.rs` gateway config merge/default behavior | `docs/how-it-works/gateways/configuration.mdx` |
+| `crates/openshell-driver-*/` config structs or driver defaults | `docs/how-it-works/gateways/configuration.mdx`, `docs/how-it-works/sandboxes/runtimes.mdx` |
+| `deploy/helm/openshell/templates/gateway-config.yaml` | `docs/how-it-works/gateways/configuration.mdx`, `docs/how-it-works/sandboxes/runtimes.mdx`, Helm docs if values change |
+| Proxy or policy code | `docs/how-it-works/policies/overview.mdx`, `docs/how-it-works/policies/schema.mdx` |
 | Inference code | `docs/inference/configure.mdx` |
 | `python/` (SDK changes) | `docs/reference/` or `docs/get-started/quickstart.mdx` |
 | `proto/` (API changes) | `docs/reference/` |
-| `deploy/` (Dockerfile, Helm) | `docs/sandboxes/manage-gateways.mdx`, `docs/about/architecture.mdx` |
-| Sandbox image behavior | `docs/sandboxes/manage-sandboxes.mdx` |
+| `deploy/` (Dockerfile, Helm) | `docs/how-it-works/gateways/overview.mdx`, `docs/about/architecture.mdx` |
+| Sandbox image behavior | `docs/how-it-works/sandboxes/overview.mdx` |
 
 If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.
 
@@ -135,8 +135,8 @@ After drafting all updates, present a summary to the user:
 ## Doc Updates from Commits
 
 ### Updated pages
-- `docs/sandboxes/manage-gateways.mdx`: Added `--gpu` flag documentation (from commit abc1234).
-- `docs/reference/policy-schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678).
+- `docs/how-it-works/gateways/overview.mdx`: Added `--gpu` flag documentation (from commit abc1234).
+- `docs/how-it-works/policies/schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678).
 
 ### New pages needed
 - None (or list any new pages created).

AGENTS.md

@@ -266,7 +266,7 @@ When behavior, commands, or development workflows change, review the related age
 
 - When making changes, update the relevant documentation in the `architecture/` directory.
 - When changes affect user-facing behavior, update the relevant published docs pages under `docs/` and navigation in `docs/index.yml`.
-- When changing gateway TOML fields, driver-specific config options, config defaults, or Helm rendering of `gateway.toml`, update `docs/reference/gateway-config.mdx` in the same branch.
+- When changing gateway TOML fields, driver-specific config options, config defaults, or Helm rendering of `gateway.toml`, update `docs/how-it-works/gateways/configuration.mdx` in the same branch.
 - `fern/` contains the Fern site config, components, preview workflow inputs, publish settings, and publishing documentation in `fern/README.md`.
 - Follow the docs style guide in [docs/CONTRIBUTING.mdx](docs/CONTRIBUTING.mdx): active voice, minimal formatting, no filler introductions, `shell` fences for copyable commands, and no duplicate body H1.
 - Fern PR previews run through `.github/workflows/branch-docs.yml`. Release Dev publishes `dev`, and Release Tag publishes an immutable stable version plus `latest`. Both production paths call `.github/workflows/sync-docs.yml` once.

CI.md

@@ -50,8 +50,8 @@ Manually dispatch `Integration Tests` on the candidate branch with an
 [{"environment":"ubuntu-docker-rootful","installer":"binaries","testsuite":"policy-advisor"}]
 ```
 
-This runs the `mechanistic-proposal` and `policy-local` conformance tests in the
-installed-artifact suite. The artifact run must contain the candidate CLI and
+This runs the `mechanistic-proposal`, `new-hostname-proposal`, and
+`policy-local` conformance tests in the installed-artifact suite. The artifact run must contain the candidate CLI and
 gateway binaries and runtime images. This manual run does not replace the
 required PR E2E gate.
 

README.md

@@ -280,11 +280,11 @@ Agent implementation is human-directed: a user may request a phase directly, or
 
 - [Full Documentation](https://docs.nvidia.com/openshell/latest/index.html) — overview, architecture, tutorials, and reference
 - [Run Your First Agent](https://docs.nvidia.com/openshell/latest/about/run-an-agent) — prepare an image, attach providers, and launch an agent
-- [GitHub Sandbox Tutorial](https://docs.nvidia.com/openshell/latest/get-started/tutorials/github-sandbox) — end-to-end scoped GitHub repo access
+- [GitHub Sandbox Tutorial](https://docs.nvidia.com/openshell/latest/tutorials/github-sandbox) — end-to-end scoped GitHub repo access
 - [Architecture](https://github.com/NVIDIA/OpenShell/tree/main/architecture) — detailed architecture docs and design decisions
 - [Roadmap](https://github.com/orgs/NVIDIA/projects/233) — planned work and project priorities
 - [RFC Board](https://github.com/orgs/NVIDIA/projects/233/views/6) — RFC proposals tracked on the OpenShell Roadmap with the `rfc` label
-- [Support Matrix](https://docs.nvidia.com/openshell/latest/reference/support-matrix) — platforms, versions, and kernel requirements
+- [Support Matrix](https://docs.nvidia.com/openshell/latest/about/support-matrix) — platforms, versions, and kernel requirements
 - [Brev Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg) — try OpenShell on cloud compute without local setup
 - [Agent Instructions](AGENTS.md) — system prompt and workflow documentation for agent contributors
 

architecture/gateway.md

@@ -1217,7 +1217,7 @@ Gateway CLI flag  >  gateway OPENSHELL_* env var  >  TOML file  >  built-in defa
 The TOML file is opt-in via `--config <PATH>` / `OPENSHELL_GATEWAY_CONFIG`.
 Driver implementation settings live exclusively in TOML driver tables. The
 selector is the singular `[openshell.gateway] compute_driver`; legacy
-`compute_drivers` lists are rejected. See `docs/reference/gateway-config.mdx`
+`compute_drivers` lists are rejected. See `docs/how-it-works/gateways/configuration.mdx`
 for worked per-driver examples and RFC 0003 for the full schema.
 
 Each installation has an operator-assigned gateway name. Configure it with

architecture/sandbox.md

@@ -269,8 +269,9 @@ Input mediation, DNS/TCP authorization, and outer-fence enforcement are
 identical in both modes. The selected mode is emitted in the sandbox
 qualification output (`seccomp_listener_mode`).
 
-DNS uses an exact sandbox-local resolver at `127.0.0.53:53`. The driver sets the
-nameserver and permits an unprivileged bind to port 53. UDP and TCP DNS requests
+DNS uses an exact sandbox-local resolver at `127.0.0.53:53`. The driver sets that
+nameserver without search domains, so names reach policy DNS as the workload
+wrote them, and permits an unprivileged bind to port 53. UDP and TCP DNS requests
 are forwarded through the supervisor, which applies hostname-based DNS policy.
 The Podman driver supplies that resolver configuration as a driver-owned,
 read-only secret mounted at `/etc/resolv.conf`; the workload remains on
@@ -323,10 +324,12 @@ preserves this lifetime rule; persistent responses remain eligible for reuse.
 An explicit `protocol: tcp` endpoint with a valid DNS hostname opts into native
 DNS and transparent TCP when the selected runtime advertises that substrate.
 Hostless `allowed_ips` and literal-IP selectors remain available only to the
-legacy explicit-proxy path when `protocol` is omitted. The shared supervisor
-answers only eligible DNS names, returns an epoch-scoped synthetic address, and
+legacy explicit-proxy path when `protocol` is omitted. For an eligible DNS
+name, the shared supervisor returns an epoch-scoped synthetic address and
 publishes the expiring name, endpoint, ports, policy generation, and validated
-real addresses as one correlation. A connection to that synthetic address is
+real addresses as one correlation. A name absent from policy receives at most a
+contract-free observation address for policy advisor proposals; see
+[Security Policy](security-policy.md). A connection to that synthetic address is
 captured before the bypass fence, mapped back to its workload process, authorized
 through the same egress pipeline, and dialed only through the pinned addresses.
 Omitted protocol endpoints retain explicit-proxy behavior.

architecture/security-policy.md

@@ -6,7 +6,7 @@ policy proxy. The gateway stores and delivers policy, but it does not make
 per-request egress decisions.
 
 For the field-by-field YAML reference, use
-[Policy Schema Reference](../docs/reference/policy-schema.mdx).
+[Policy Schema Reference](../docs/how-it-works/policies/schema.mdx).
 
 ## Policy Areas
 
@@ -282,6 +282,19 @@ because it changes the effective access model for every sandbox on the gateway.
 The policy advisor pipeline turns observed denials into draft policy
 recommendations. There are two proposers (sandbox-side mechanistic mapper,
 agent-authored via `policy.local`); the gateway is the single referee.
+For a new DNS name absent from policy, the supervisor can
+publish a bounded, short-lived synthetic observation mapping without querying
+an upstream resolver. It carries only the name to the subsequent TCP mediation
+step, which supplies the destination port and verified process identity for a
+denial summary. Observation mappings have no endpoint contracts or real pinned
+addresses, cannot authorize a relay, and become stale on policy generation
+change. Transparent TCP re-acquires the mapping at the generation that
+authorized the connection, so a reload between DNS and authorization fails
+closed instead of resolving the name again. Every unknown name still produces a
+DNS denial event. Reserved names, fail-closed quarantine, and an exhausted
+observation budget (a quarter of each address family's synthetic pool) keep the
+plain DNS refusal. This mechanistic observation path does not depend on the
+agent-authored proposal setting.
 When enabled, L7 `policy_denied` responses include both structured
 `next_steps` and a short `agent_guidance` string so generic agents can continue
 through the proposal loop instead of treating the denial as terminal.
@@ -421,7 +434,7 @@ reported modeled domains. See the `openshell-prover` crate README for the
 supported construction and matching patterns.
 
 This containment operation is separate from the proposal-risk queries below.
-See the [standalone policy prover documentation](../docs/reference/policy-prover.mdx)
+See the [standalone policy prover documentation](../docs/how-it-works/policies/prover.mdx)
 for installation, command behavior, model limitations, evidence, and exit codes.
 
 ## What the proposal prover decides

crates/openshell-cli/src/commands/common.rs

@@ -22,7 +22,8 @@ use std::io::IsTerminal;
 use std::process::Command;
 use std::time::{Duration, Instant};
 
-const DOCS_PROVIDERS_URL: &str = "https://docs.nvidia.com/openshell/latest/sandboxes/providers-v2";
+const DOCS_PROVIDERS_URL: &str =
+    "https://docs.nvidia.com/openshell/latest/how-it-works/providers/overview";
 
 // ---------------------------------------------------------------------------
 // View types

crates/openshell-conformance/src/lib.rs

@@ -24,8 +24,8 @@ use tokio::time::sleep;
 use self::executor::{CliExecutionError, CliExecutor, ProcessCli};
 
 pub use scenarios::{
-    MECHANISTIC_PROPOSAL_SCENARIO, POLICY_LOCAL_SCENARIO, SANDBOX_LIFECYCLE_SCENARIO,
-    SMOKE_SCENARIO,
+    MECHANISTIC_PROPOSAL_SCENARIO, NEW_HOSTNAME_PROPOSAL_SCENARIO, POLICY_LOCAL_SCENARIO,
+    SANDBOX_LIFECYCLE_SCENARIO, SMOKE_SCENARIO,
 };
 
 /// An installed conformance scenario.
@@ -48,6 +48,7 @@ const SCENARIOS: &[Scenario] = &[
     SMOKE_SCENARIO,
     SANDBOX_LIFECYCLE_SCENARIO,
     MECHANISTIC_PROPOSAL_SCENARIO,
+    NEW_HOSTNAME_PROPOSAL_SCENARIO,
     POLICY_LOCAL_SCENARIO,
 ];
 

crates/openshell-conformance/src/scenarios/mod.rs

@@ -7,6 +7,8 @@ mod policy_behavior;
 mod sandbox_lifecycle;
 mod smoke;
 
-pub use policy_behavior::{MECHANISTIC_PROPOSAL_SCENARIO, POLICY_LOCAL_SCENARIO};
+pub use policy_behavior::{
+    MECHANISTIC_PROPOSAL_SCENARIO, NEW_HOSTNAME_PROPOSAL_SCENARIO, POLICY_LOCAL_SCENARIO,
+};
 pub use sandbox_lifecycle::SANDBOX_LIFECYCLE_SCENARIO;
 pub use smoke::SMOKE_SCENARIO;