docs(cli): document lib file placement map

src/lib/README.md

@@ -0,0 +1,57 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# `src/lib` layout
+
+`src/lib` is organized by architectural role first, then by product area. Use this map when adding new code or when moving legacy flat modules into clearer homes.
+
+## Primary layers
+
+```text
+src/lib/commands/**  oclif adapter classes and parser glue
+src/lib/actions/**   workflow orchestration and user-facing command behavior
+src/lib/domain/**    pure decisions, policy, classification, and planning
+src/lib/adapters/**  host boundaries: process, fs, Docker, OpenShell, HTTP
+src/lib/state/**     persisted local state and state-file I/O
+src/lib/cli/**       CLI framework, metadata, routing, and help infrastructure
+src/lib/core/**      tiny cross-cutting primitives with minimal dependencies
+```
+
+Layering rules:
+
+- Command classes should parse argv and call actions; they should not own product logic.
+- Actions may compose domain helpers, adapters, state modules, and output.
+- Domain helpers should stay pure and avoid direct process, filesystem, Docker, OpenShell, or network calls.
+- Adapters isolate host-boundary calls so actions and tests can inject fakes.
+- State modules own persisted local files and registry/session I/O.
+
+## Transitional feature folders
+
+Some older modules are still too large or coupled to split directly into actions/domain/adapters. Use these feature folders as intermediate homes while preserving behavior:
+
+```text
+src/lib/agent/**        agent definition, agent-specific onboarding, runtime helpers
+src/lib/credentials/**  credential storage and credential command support
+src/lib/dashboard/**    dashboard contract, health, and recovery helpers
+src/lib/deploy/**       deploy/build-image support that is not yet action-shaped
+src/lib/diagnostics/**  debug collection and diagnostic report helpers
+src/lib/inference/**    inference config, health probes, local runtime helpers
+src/lib/messaging/**    channel/messaging policy and message filtering helpers
+src/lib/onboard/**      onboarding support modules around the large legacy flow
+src/lib/policy/**       policy preset loading and application support
+src/lib/runtime/**      sandbox/runtime recovery helpers
+src/lib/sandbox/**      sandbox config, build, stream, and version support
+src/lib/security/**     redaction, secret patterns, and credential filtering
+src/lib/shields/**      shields orchestration, timers, and audit helpers
+src/lib/tunnel/**       local service/tunnel command support
+```
+
+Prefer small mechanical PRs that move one cluster at a time. High-import legacy files such as `onboard.ts`, `runner.ts`, `policies.ts`, `nim.ts`, and `services.ts` should either move late or keep temporary compatibility re-export files at their old paths.
+
+## Suggested migration sequence
+
+1. Document the target map and conventions before moving more code.
+2. Move low-risk feature clusters such as `agent`, `dashboard`, `diagnostics`, and `shields`.
+3. Move security/credentials/core helpers.
+4. Move inference/model/local-runtime helpers.
+5. Move onboarding support files before considering the large `onboard.ts` flow.

src/lib/core/README.md

@@ -0,0 +1,20 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Core helpers
+
+`src/lib/core` is for tiny cross-cutting primitives with minimal dependencies. These helpers should be safe to import from actions, domain modules, adapters, and CLI infrastructure.
+
+Good candidates:
+
+```text
+version.ts
+ports.ts
+json-types.ts
+errno.ts
+wait.ts
+url-utils.ts
+shell-quote.ts
+```
+
+Keep product workflows out of this directory. If a helper starts depending on Docker, OpenShell, filesystem state, or a specific command workflow, move it to an adapter, action, domain area, or feature folder instead.

src/lib/inference/README.md

@@ -0,0 +1,25 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Inference
+
+`src/lib/inference` is for model/provider configuration, inference health checks, local runtime support, and model catalog helpers.
+
+Suggested homes:
+
+```text
+config.ts                 inference config parsing and normalization
+health.ts                 inference endpoint health checks
+local.ts                  local inference orchestration helpers
+provider-models.ts        provider model catalog support
+model-prompts.ts          prompt/model display helpers
+nim.ts                    NIM catalog and lifecycle support
+ollama/model-size.ts      Ollama model size parsing
+ollama/proxy.ts           Ollama auth proxy support
+ollama/windows.ts         Windows Ollama support
+vllm.ts                   vLLM support
+web-search.ts             web-search capability helpers
+onboard-probes.ts         onboarding-time inference validation probes
+```
+
+Longer term, pure inference decisions should move under `src/lib/domain/inference/**`, and HTTP/process boundaries should move under `src/lib/adapters/**`.

src/lib/onboard/README.md

@@ -0,0 +1,28 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Onboard support
+
+`src/lib/onboard` is the transitional home for onboarding support modules while the large legacy `src/lib/onboard.ts` flow is split over time.
+
+Good candidates:
+
+```text
+types.ts
+providers.ts
+preflight.ts
+usage-notice.ts
+legacy-command.ts
+```
+
+Related modules may live outside this folder when their ownership is clearer:
+
+```text
+src/lib/state/onboard-session.ts          persisted onboarding session state
+src/lib/inference/onboard-probes.ts       inference validation probes used by onboarding
+src/lib/inference/ollama/proxy.ts         Ollama proxy lifecycle helpers
+src/lib/inference/vllm.ts                 vLLM onboarding helpers
+src/lib/inference/ollama/windows.ts       Windows Ollama support
+```
+
+Do not move `src/lib/onboard.ts` casually. It is high-import and high-risk; if it moves, keep a compatibility re-export path or split it through focused behavior-preserving PRs.

src/lib/sandbox/README.md

@@ -0,0 +1,18 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Sandbox support
+
+`src/lib/sandbox` is for sandbox configuration, build context, create-stream, version, and channel support that is not already owned by an action/domain module.
+
+Suggested homes:
+
+```text
+config.ts                 sandbox config download/upload and mutation support
+build-context.ts          sandbox build context construction
+create-stream.ts          sandbox create progress parsing
+version.ts                sandbox/agent version helpers
+channels.ts               sandbox channel support, unless moved to messaging
+```
+
+Command workflows should continue to live under `src/lib/actions/sandbox/**`. Pure validation/classification helpers should live under `src/lib/domain/sandbox/**`.

src/lib/security/README.md

@@ -0,0 +1,17 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Security helpers
+
+`src/lib/security` is for reusable redaction, secret-pattern, credential-hash, and credential-filter helpers.
+
+Suggested homes:
+
+```text
+credential-filter.ts
+credential-hash.ts
+redact.ts
+secret-patterns.ts
+```
+
+Credential storage belongs under `src/lib/credentials/**`; security helpers should not own persistence or user prompts.