docs: add Strands Shell SDK documentation section

[agent-of-mkmeral]

Description

Adds a dedicated Strands Shell SDK documentation section to the docs site, modeled on the existing Strands Evals SDK section: its own sidebar group with an overview, quickstart, and supporting reference pages.

Strands Shell is the in-process virtual shell sandbox for agents. It had a README but no presence on the docs site. This section gives it a proper home.

Pages added

All under site/src/content/docs/user-guide/shell-sdk/:

Page	Type	Covers
index.mdx (Overview)	explanation	What it is, why a virtual shell, how the Kernel mediates, what it is not
quickstart.mdx	tutorial	Install + first sandboxed command via MCP, Python, and Node.js
configuration.mdx	how-to	Binds, credential injection, network allowlist, limits, and the TOML format
commands.mdx	reference	Full command inventory, flags, and divergences from GNU/BSD coreutils
mcp-server.mdx	reference/how-to	The four MCP tools, their schemas, nested MCP-as-Lua
security.mdx	explanation	Kernel boundary, SSRF guard, credential handling, threat model, when to add OS isolation

Navigation entry added in src/config/navigation.yml as a new "Strands Shell SDK" group, placed after "Strands Evals SDK".

Design decisions

• Modeled on the Evals SDK section, not the user-guide concepts. Strands Shell is a separate product with its own install and API surface, so it gets a sibling top-level group rather than living under Tools or Concepts.
• Inline Python + JavaScript, no .ts snippet files. The docs site type-checks every .ts snippet under content/docs/ against @strands-agents/sdk (via test-snippets/). @strands-agents/shell is not a dependency there, so adding .ts snippets would break typecheck:snippets. The Evals SDK section sets the precedent of inline Python; I followed it and used inline JavaScript for the Node tab, matching how the shell README presents Node usage.
• Code verified against source. Every API example was checked against the shell repo: the Python Shell/Bind/Cred/Limits constructor in python/strands_shell/__init__.py, the Node Shell.create surface in index.d.ts, the MCP tool schemas in src/mcp.rs, and the TOML schema in src/vfs_config.rs.

Accuracy note worth a reviewer's eye

The shell README states there is "no per-command timeout by default," but the config-driven constructors my docs cover default timeout to 30 seconds: the Node index.d.ts says "Default 30," and the Rust ShellBuilder::default() sets Some(30s). The README's "no default" describes the lower-level Rust builder path. I documented the 30s default consistently since that is what Python Shell(...) and Node Shell.create(...) users actually get. Flagging in case the shell README should be reconciled separately.

Related Issues

Requested by @mkmeral.

Documentation PR

This PR is documentation only. All changes live under site/.

Type of Change

Documentation update

Testing

• Full npm run build runs clean: 689 pages built, astro-broken-links-checker (with throwError: true) reports no broken links. (The full static build needs a larger heap: NODE_OPTIONS="--max-old-space-size=7168" npm run build.)
• prettier --check passes on all six new pages.
• navigation.yml parses as valid YAML; the new group resolves to existing content files.
• Frontmatter on all six pages has title and a 140-160 char description.
• Style pass: no em-dashes, no emoji, no banned hype/AI-tell phrases; the reference page (commands.mdx) avoids contractions per the voice guide.
• Internal .md links and anchor targets checked against page headings.

Pre-Open Review Loop Summary

This PR went through the task-pr-gate Mode A fresh-context pre-open review chain before being marked ready. Each iteration ran as a separate GitHub Actions process with fresh model state, re-deriving every claim against the strands-agents/shell source of truth rather than trusting the prior reviewer.

Iteration	Actor	Findings	Action
0	author	Initial draft: 6 pages + nav, code verified against shell source, inline-Python/JS decision	Opened draft PR #2849
1	fresh reviewer	1 must-fix: build-breaking mailto: link in security.mdx rewritten to a bogus relative path by PageLink.astro (isRelativeLink() does not exempt the mailto scheme), failing astro-broken-links-checker (throwError: true)	Fixed: render email as inline code, HackerOne stays the linked channel. Build verified clean (689 pages).
2	fresh reviewer	Zero new must-fix. Independently re-verified: full build clean (689 pages, no broken links); prettier clean; 30s timeout default confirmed in src/shell.rs ShellBuilder::default(); Limits defaults, TOML schema (copy default, deny_unknown_fields), cred schema, SSRF list, MCP tool schemas (timeout_ms 30000 / offset 1 / limit 2000), Python/Node API surfaces, version requirements, SECURITY.md channel all match source; no style violations; nav wiring correct. 1 nice-to-have filed as inline comment.	Converged. Marked ready for review.

Convergence reached at iteration 2 of 3 (clean findings, 100% overlap with iteration 1's verification).

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Changed pages:

• user-guide/shell-sdk/commands
• user-guide/shell-sdk/configuration
• user-guide/shell-sdk
• user-guide/shell-sdk/mcp-server
• user-guide/shell-sdk/quickstart
• user-guide/shell-sdk/security

Updated at: 2026-06-17T11:08:59.881Z

[github-actions]

Assessment: Comment (approve once the bind-default note is addressed or consciously deferred)

Strong documentation PR. I verified every API surface against strands-agents/shell source: the Python Shell/Bind/Cred/Limits constructors, the Node Shell.create types, the four MCP tool schemas, the TOML cred/bind/limits tables, and the error hierarchies all match. Structure mirrors the Evals SDK section cleanly, and the style pass holds (no em-dashes, no emoji, .md link convention consistent with the rest of the docs).

The timeout-default question you flagged in the description checks out: ShellBuilder::default() sets Some(30s), the Python constructor only overrides when timeout is passed, and the Node type documents Default 30. Documenting 30s consistently for the config-driven path is correct. The README's "no default" describes the lower-level Rust builder, so a separate README reconciliation is the right call, not a change here.

Review detail

• Accuracy (one item): The "copy is the safe default" framing is true for TOML but not for the programmatic constructors, which default mode to direct. See the inline comment on configuration.mdx. This is the only substantive issue I found.
• API verification: All signatures, defaults (Limits, MCP timeout_ms/offset/limit), Node version >= 18, Python 3.10+, and the Cred exactly-one-of rule confirmed against source.
• Scope/size: Six new pages plus a nav entry, all under site/. Appropriately scoped for a docs section; no test changes needed.

Nicely researched, and flagging the timeout discrepancy proactively in the description made verification much faster.

[github-actions]

Issue: The docs consistently frame copy as the safe default (security.mdx: "the safe choice is the default at every turn"; configuration.mdx line 163: "bind mode defaults to copy when omitted, which is the safe choice"). That is accurate for the TOML parser (default_mode() returns BindMode::Copy), but the programmatic constructors default to direct:

• Python Bind dataclass: mode: Literal["direct", "copy"] = "direct"
• Node BindConfig: mode?: 'direct' | 'copy' documented as 'direct' passthrough (default)

So a reader who writes strands_shell.Bind("/host", "/dest") and omits mode= gets a live host-passthrough mount, the exact behavior the :::caution below warns against. Every example here passes mode explicitly, which hides the asymmetry.

Suggestion: Call out that the constructor default is direct (so omitting mode is not the safe choice in code, even though it is in TOML), or note the inconsistency for upstream to reconcile. A one-line note in the Binds section would prevent a reader from assuming the in-code default matches the TOML default.