[clubanderson]

Docs companion to #17741 (code). Part of #17695; sibling of the OpenShell docs PR #17647.

• ADR-0026: status line notes phase 2; new Implementation notes (phase 2: Agent Substrate) section — contract mapping, deviations from Substrate's reference model (no go.ate.dev/substrate import, per-kick actor, copied workspace via bridge, digest-pinned image, HIVE_POLICY_PROFILE, suspend instead of delete), cluster prerequisites (podcert feature gates, cgroup v2 / /dev/kvm, worker capabilities) and which hive clusters qualify, and when to choose it over OpenShell; consequences + refs updated.
• sandbox-isolation.md: new Running sandboxed kicks in a Substrate actor section (config example, lifecycle, egress policy, what hive checks, limitations); remaining-gaps bullet updated.
• integrations.md: Agent Substrate row (CNCF Sandbox).
• deploy/substrate.md (new): prerequisites table, cluster survey (hive-oke OL9/UEK8 6.12 k8s 1.34.10; lke648397 6.12; vllm-d/a-ks-wec2 RHCOS 5.14 — Substrate needs gVisor/microVM support + podcert gates, not a kernel floor), ate-setup install, WorkerPool/SandboxConfig, projected identity files, verification commands, upgrades. deploy/README.md pointer.
• changelog fragment changed-substrate-runtime-docs.md.

Credential brokering stays hive's: agents in the actor use the hive MITM proxy; Substrate's zero-credential injection is documented as complementary and unused.

[clubanderson]

/lgtm
/approve

[kubestellar-prow]

@clubanderson: you cannot LGTM your own PR.

Details

In response to this:

/lgtm
/approve

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: clubanderson

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [clubanderson]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

No conflicting open PRs or same-file overlaps were found.

[hivecommons-hive]

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

• relative links and anchors resolve

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

• scanner (2026-11-11 20:15 UTC): CI: relative links and anchors resolve fails with one broken link:

  src/docs/sandbox-isolation.md: adr/0002-github-proxy.md does not exist. The ADR file on v5 is src/docs/adr/0002-mitm-proxy-network-enforcement.md.

  Suggested one-line fix in the egress policy paragraph of src/docs/sandbox-isolation.md:

  ([ADR-0002](adr/0002-mitm-proxy-network-enforcement.md))
  

  i.e. replace adr/0002-github-proxy.md with adr/0002-mitm-proxy-network-enforcement.md. All other checks on this PR are green; this is the only blocker.

  — hive: agent=scanner

hive/awaiting-ci: `relative links and anchors resolve` is red on a31fbab and the cause is PR-local (one broken link in the diff, not a baseline failure).

`src/docs/sandbox-isolation.md` links `ADR-0002`, but the file on `v5` is `src/docs/adr/0002-mitm-proxy-network-enforcement.md`. Suggested fix:

```diff
-(ADR-0002)
+(ADR-0002)
```

Not pushing to a human-authored branch; once this lands the link check should go green.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

dc70922

ℹ️ Sentinel notice — informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @clubanderson, head dc709229d978) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation — a maintainer should confirm the change is intended before it merges.

• sensitive_path — changes 2 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
  • src/deploy/README.md
  • src/deploy/substrate.md

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

[hivecommons-hive]

The red relative links and anchors resolve check is a single broken link, and the fix is one path.

Job log (run 43092130861):

1 broken link(s):
  src/docs/sandbox-isolation.md: broken link 'adr/0002-github-proxy.md' -> src/docs/adr/0002-github-proxy.md does not exist

The link is in the new Running sandboxed kicks in a Substrate actor section, in the paragraph starting The egress policy. ([ADR-0002](adr/0002-github-proxy.md)). The ADR directory at this head has no file by that name; ADR-0002 is src/docs/adr/0002-mitm-proxy-network-enforcement.md, so the link should be [ADR-0002](adr/0002-mitm-proxy-network-enforcement.md).

Nothing else in the diff is flagged by the checker; once that path is corrected the docs side should go green. I've only reviewed the link failure here, not the substance of the Substrate contract mapping against #17741's code.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88