fix(pi): close release contract gaps

.agents/skills/nemoclaw-user-guide/SKILL.md

@@ -44,6 +44,7 @@ Use these pages first for common onboarding flows:
 - Deep Agents quickstart: `https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/get-started/quickstart.md`.
 - Pi home: `https://docs.nvidia.com/nemoclaw/latest/user-guide/pi/home.md`.
 - Pi quickstart: `https://docs.nvidia.com/nemoclaw/latest/user-guide/pi/get-started/quickstart.md`.
+- Pi model limits: `https://docs.nvidia.com/nemoclaw/latest/user-guide/pi/inference/configure-model-limits.md`.
 - Pi operations: `https://docs.nvidia.com/nemoclaw/latest/user-guide/pi/manage-sandboxes/run-pi.md`.
 - Pi support and security: `https://docs.nvidia.com/nemoclaw/latest/user-guide/pi/reference/pi-support.md`.
 - Pi command reference: `https://docs.nvidia.com/nemoclaw/latest/user-guide/pi/reference/commands.md`.

docs/get-started/quickstart-pi.mdx

@@ -18,7 +18,7 @@ agent-variants: ["pi"]
 Run the pinned Pi coding agent inside a NemoClaw-managed OpenShell sandbox.
 
 <Warning>
-Pi remains a qualified release candidate until the final activation change adds it to the supported agent inventory and managed-image release cohort. Normal installations reject `--agent pi` before that activation. The qualification controls are not a user setup path.
+Pi remains a release candidate until the final activation change adds it to the supported agent inventory and managed-image release cohort. Normal installations reject `--agent pi` before that activation. The qualification controls are not a user setup path.
 </Warning>
 
 ## Requirements
@@ -53,6 +53,19 @@ Choose a provider and model that use the OpenAI Chat Completions API. NemoClaw k
 
 Stock onboarding selects a Pi managed-image digest. It does not build the Pi Dockerfile on the host. The reviewed Dockerfile is a trusted CI image-build source, not a user onboarding mechanism. A missing, incomplete, mutable, or inconsistent image contract fails before sandbox creation.
 
+Set optional Pi model metadata before onboarding when the selected model needs an explicit context window, output limit, or reasoning declaration. Refer to [Configure Model Limits](../inference/configure-model-limits).
+
+## Resume Interrupted Onboarding
+
+Correct the reported condition, then continue the recorded Pi onboarding session.
+
+```bash
+nemoclaw onboard --resume
+```
+
+Resume reuses the recorded agent, provider, model, and sandbox name. Pi model-tuning environment values are not stored in an incomplete onboarding checkpoint, so re-export `NEMOCLAW_CONTEXT_WINDOW`, `NEMOCLAW_MAX_TOKENS`, and `NEMOCLAW_REASONING` before resuming when the original run supplied them. Resume does not change a completed sandbox.
+Use `nemoclaw onboard --agent pi --name my-pi --fresh` to discard an incomplete Pi session and start again. Add `--recreate-sandbox` when replacing an existing completed sandbox.
+
 ## Check the Sandbox
 
 Wait for onboarding to finish, then inspect the registered agent and runtime.
@@ -94,14 +107,18 @@ Use JSON mode when automation needs structured event evidence.
 
 ```bash
 nemoclaw my-pi exec --workdir /sandbox --no-tty -- \
-  pi --no-approve --mode json --print --tools read \
+  pi --no-approve --no-context-files --mode json --print --tools read \
     "Use the read tool to inspect README.md and report its title"
 ```
 
-`--no-approve` ignores project-local executable resources but does not disable context files; add `--no-context-files` when required. `--tools read` limits that invocation to Pi's read tool. JSON mode writes newline-delimited session events, including structured tool execution events and the final assistant message.
+`--no-approve` ignores project-local executable resources but does not disable context files.
+`--no-context-files` excludes `AGENTS.md` and `CLAUDE.md` from the prompt; omit it only when automation must accept project instructions.
+`--tools read` limits that invocation to Pi's read tool.
+JSON mode writes newline-delimited session events, including structured tool execution events and the final assistant message.
 
 ## Continue
 
 - [Run and Manage Pi](../manage-sandboxes/run-pi) covers lifecycle, state, backup, rebuild, recovery, and troubleshooting.
+- [Configure Model Limits](../inference/configure-model-limits) covers Pi context-window, output-token, and reasoning metadata.
 - [NemoClaw for Pi CLI Commands Reference](../reference/commands) lists host and in-sandbox command forms.
 - [Pi Support and Security](../reference/pi-support) records the initial compatibility matrix, policy, credential, and qualification boundaries.

docs/index.yml

@@ -448,6 +448,13 @@ navigation:
               - page: "Quickstart with Pi"
                 path: get-started/quickstart-pi.mdx
                 slug: quickstart
+          - section: "Inference"
+            slug: inference
+            collapsed: open-by-default
+            contents:
+              - page: "Configure Model Limits"
+                path: _build/agent-variants/inference/configure-model-limits.pi.generated.mdx
+                slug: configure-model-limits
           - section: "Operate Pi"
             slug: manage-sandboxes
             collapsed: open-by-default

docs/inference/configure-model-limits.mdx

@@ -8,6 +8,7 @@ description-agent: "Explains which agent runtimes accept NemoClaw model-limit ov
 keywords: ["nemoclaw context window", "nemoclaw max tokens", "model limits"]
 content:
   type: "how_to"
+agent-variants: ["openclaw", "hermes", "deepagents", "pi"]
 ---
 <AgentOnly variant="openclaw,hermes">
 
@@ -16,6 +17,33 @@ Changing an explicit build-time model limit on an existing sandbox requires fres
 
 </AgentOnly>
 
+<AgentOnly variant="pi">
+
+## Set Pi Model Metadata
+
+Pi accepts an explicit context window, maximum output-token count, and reasoning flag.
+
+| Variable | Values | Default |
+|---|---|---|
+| `NEMOCLAW_CONTEXT_WINDOW` | Positive integer up to `4194304` tokens | Unset; Pi uses the model default |
+| `NEMOCLAW_MAX_TOKENS` | Integer from `1` to `1000000000` tokens | Unset; Pi uses the model default |
+| `NEMOCLAW_REASONING` | `true` or `false` | Unset; Pi uses the model default |
+
+Export the values before onboarding.
+
+```bash
+export NEMOCLAW_CONTEXT_WINDOW=65536
+export NEMOCLAW_MAX_TOKENS=8192
+export NEMOCLAW_REASONING=true
+nemoclaw onboard --agent pi --name <sandbox-name>
+```
+
+NemoClaw validates each supplied value and writes it to `/sandbox/.pi/agent/models.json` through the managed startup profile.
+An invalid value fails before Pi starts.
+Pi does not support `NEMOCLAW_REASONING_EFFORT`.
+
+</AgentOnly>
+
 <AgentOnly variant="deepagents">
 
 NemoClaw does not configure context-window or output-token limits for LangChain Deep Agents Code.
@@ -111,7 +139,36 @@ $$nemoclaw onboard --fresh --name <sandbox-name> --recreate-sandbox
 
 </AgentOnly>
 
+<AgentOnly variant="pi">
+
+## Recreate a Pi Sandbox
+
+A normal Pi rebuild replays the recorded context window, maximum output-token count, and reasoning flag.
+Changing those values requires a fresh replacement.
+Create a snapshot first when declared user state must survive, then export the new values and recreate the sandbox.
+
+```bash
+nemoclaw <sandbox-name> snapshot create --name before-model-change
+nemoclaw onboard --agent pi --name <sandbox-name> --fresh --recreate-sandbox
+```
+
+Pi has no runtime `inference set` configuration path.
+Use the same fresh replacement flow to change its provider or model.
+
+</AgentOnly>
+
 ## Related Topics
 
+<AgentOnly variant="openclaw,hermes,deepagents">
+
 - [Configure Inference Timeouts](configure-inference-timeouts) for request, validation, and readiness budgets.
 - [Switch Models](switch-models) to change the selected model.
+
+</AgentOnly>
+
+<AgentOnly variant="pi">
+
+- [Run and Manage Pi](../manage-sandboxes/run-pi) for rebuild and snapshot behaviour.
+- [Pi Support and Security](../reference/pi-support) for supported inference and credential boundaries.
+
+</AgentOnly>

docs/manage-sandboxes/run-pi.mdx

@@ -18,7 +18,8 @@ agent-variants: ["pi"]
 Use NemoClaw for host-side lifecycle operations and Pi for work inside the sandbox.
 
 <Note>
-Pi remains unavailable to normal installations until final release activation. These commands describe the accepted runtime once the installed release lists `pi` as a supported agent.
+Pi remains unavailable to normal installations until final release activation.
+Candidate qualification uses these lifecycle commands; internal qualification settings are not a user setup path.
 </Note>
 
 ## Connect and Run Pi
@@ -44,10 +45,11 @@ nemoclaw <sandbox-name> exec --workdir /sandbox --no-tty -- \
 ```
 
 For automation, select JSON mode and an explicit tool set.
+Use `--no-context-files` when project instructions must not enter the prompt.
 
 ```bash
 nemoclaw <sandbox-name> exec --workdir /sandbox --no-tty -- \
-  pi --no-approve --mode json --print --tools read,grep,find,ls \
+  pi --no-approve --no-context-files --mode json --print --tools read,grep,find,ls \
     "Find the configuration entry that selects the default model"
 ```
 
@@ -95,7 +97,8 @@ nemoclaw <sandbox-name> snapshot restore <version-or-name-or-timestamp>
 
 ## Rebuild and Recover
 
-Rebuild validates the recorded workload authority, resolves the current release's Pi image, and preserves declared Pi state.
+Rebuild validates the recorded workload authority and selects the immutable Pi image authorised by the protected qualification receipt.
+It preserves declared Pi state and replays the recorded context window, maximum output-token count, and reasoning flag.
 
 ```bash
 nemoclaw <sandbox-name> rebuild --yes
@@ -108,7 +111,31 @@ nemoclaw <sandbox-name> recover
 nemoclaw <sandbox-name> status
 ```
 
-After a NemoClaw update, rebuild the sandbox to consume a newer reviewed Pi package and image. Each Pi update requires a new package integrity, dependency review, image digest, and qualification result.
+Pi has no long-running agent gateway or host forward. `recover` re-enters the shared sandbox readiness path; it does not restart a Pi process. Rebuild when the Pi entrypoint, managed configuration, or image is inconsistent.
+
+Pi has no runtime `inference set` path. To change the provider, model, context window, output limit, or reasoning flag, create a snapshot, set the new selection, and run a fresh replacement.
+
+```bash
+nemoclaw <sandbox-name> snapshot create --name before-model-change
+nemoclaw onboard --agent pi --name <sandbox-name> --fresh --recreate-sandbox
+```
+
+Refer to [Configure Model Limits](../inference/configure-model-limits) for the supported environment variables.
+
+## Update NemoClaw and Pi
+
+After a NemoClaw update, inspect registered sandboxes before rebuilding Pi.
+
+```bash
+nemoclaw update --yes
+nemoclaw upgrade-sandboxes --check
+nemoclaw <sandbox-name> rebuild --yes
+```
+
+A host update alone does not select a newer Pi image.
+While Pi remains a candidate, rebuild uses the protected qualification receipt rather than the installed release catalogue.
+Each Pi update requires a reviewed package version and integrity value, an immutable image digest, and a qualification result.
+Pi runtime self-update and package auto-update remain unsupported.
 
 ## Stop, Start, and Destroy
 
@@ -136,6 +163,10 @@ The selected build cannot prove an accepted immutable Pi image. Do not replace t
 
 Pi v1 accepts `openai-completions`. Select a Chat Completions-compatible provider or re-onboard with a supported provider and model.
 
+### Fix a Runtime Startup Security Refusal
+
+Pi requires exact soft and hard limits of `nproc=512` and `nofile=65536`. It refuses to start when its protected shell initialization, privilege drop, or either limit cannot be applied. Correct the reported container-runtime constraint before rebuilding from the accepted image, then check status. Do not bypass the failed control or replace the managed entrypoint.
+
 ### Diagnose an Inference Failure
 
 Run `nemoclaw <sandbox-name> status` and `nemoclaw <sandbox-name> doctor`. Confirm that the host credential remains registered with OpenShell and that the selected model supports streaming and structured tool calls.

docs/reference/pi-commands.mdx

@@ -26,11 +26,13 @@ Pi remains a release candidate. Ordinary installations reject `--agent pi` until
 | Command | Purpose |
 |---|---|
 | `nemoclaw onboard --agent pi --name <name>` | Create a Pi sandbox after activation |
+| `nemoclaw onboard --resume` | Continue an incomplete recorded onboarding session |
+| `nemoclaw onboard --agent pi --name <name> --fresh --recreate-sandbox` | Replace a completed Pi sandbox with new startup selections |
 | `nemoclaw list` | List registered sandboxes and agents |
 | `nemoclaw <name> status` | Check Pi, inference, policy, and runtime state |
 | `nemoclaw <name> logs` | Read bounded sandbox logs |
 | `nemoclaw <name> doctor` | Diagnose Pi sandbox state; this command does not recover Pi |
-| `nemoclaw <name> recover` | Repair a stopped Pi gateway and its host forwards |
+| `nemoclaw <name> recover` | Re-enter sandbox readiness checks; Pi has no agent gateway or host forward |
 
 ## Run Pi
 
@@ -39,18 +41,33 @@ Pi remains a release candidate. Ordinary installations reject `--agent pi` until
 | `nemoclaw launch <name>` | Run launch preflight and open interactive Pi |
 | `nemoclaw <name> connect` | Open a shell in the sandbox |
 | `nemoclaw <name> exec --workdir /sandbox --no-tty -- pi --no-approve --print "<task>"` | Run one headless task from the host |
-| `nemoclaw <name> exec --workdir /sandbox --no-tty -- pi --no-approve --mode json --print "<task>"` | Emit newline-delimited JSON task events |
+| `nemoclaw <name> exec --workdir /sandbox --no-tty -- pi --no-approve --no-context-files --mode json --print "<task>"` | Emit newline-delimited JSON task events |
 
 Inside a connected sandbox:
 
 ```bash
 pi
 pi --no-approve --print "Review the current changes"
-pi --no-approve --mode json --print --tools read "Read README.md"
+pi --no-approve --no-context-files --mode json --print --tools read "Read README.md"
 pi --no-context-files
 ```
 
-`--no-approve` ignores project-local executable resources. It does not disable `AGENTS.md` or `CLAUDE.md`; use `--no-context-files` for that boundary.
+`--no-approve` ignores project-local executable resources.
+It does not disable `AGENTS.md` or `CLAUDE.md`.
+Use `--no-context-files` when project instructions must not enter the prompt.
+
+## Configure Model Metadata
+
+Set supported Pi model metadata before onboarding or a fresh replacement.
+
+```bash
+export NEMOCLAW_CONTEXT_WINDOW=65536
+export NEMOCLAW_MAX_TOKENS=8192
+export NEMOCLAW_REASONING=true
+nemoclaw onboard --agent pi --name <name>
+```
+
+Pi supports a positive `NEMOCLAW_CONTEXT_WINDOW` no larger than `4194304`, a `NEMOCLAW_MAX_TOKENS` value from `1` to `1000000000`, and `true` or `false` for `NEMOCLAW_REASONING`. It does not support `NEMOCLAW_REASONING_EFFORT` or the runtime `inference set` command. A normal rebuild replays the recorded values.
 
 ## Preserve and Replace State
 
@@ -67,13 +84,26 @@ Review the selected version, name, or timestamp before restore replaces sandbox
 nemoclaw <name> snapshot restore <version-or-name-or-timestamp>
 ```
 
-Rebuild validates recorded authority and resolves the current release's Pi image.
+Rebuild validates recorded authority and selects the immutable Pi image authorised by the protected qualification receipt.
 
 ```bash
 nemoclaw <name> rebuild --yes
 nemoclaw <name> recover
 ```
 
+## Update the Host and Sandbox
+
+After updating NemoClaw, inspect registered sandboxes before rebuilding Pi.
+
+```bash
+nemoclaw update --yes
+nemoclaw upgrade-sandboxes --check
+nemoclaw <name> rebuild --yes
+```
+
+The host update does not self-update Pi inside a running sandbox.
+While Pi remains a candidate, rebuild uses the protected qualification receipt rather than the installed release catalogue.
+
 ## Stop or Remove the Sandbox
 
 ```bash