Skip to content

docs(cli): document lib file placement map#3189

Merged
cv merged 6 commits into
mainfrom
refactor/lib-placement-map
May 7, 2026
Merged

docs(cli): document lib file placement map#3189
cv merged 6 commits into
mainfrom
refactor/lib-placement-map

Conversation

@cv

@cv cv commented May 7, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Collaborator

Summary

Documents the intended src/lib placement map before moving more legacy TypeScript files. This gives the follow-up reorg PRs a shared vocabulary for commands, actions, domain helpers, adapters, state, core utilities, and transitional feature folders.

Related Issue

Closes #3164

Changes

  • Add src/lib/README.md with the target layer rules and migration sequence.
  • Add orientation READMEs for src/lib/core, src/lib/inference, src/lib/onboard, src/lib/sandbox, and src/lib/security.
  • Call out high-import files that should move later or keep compatibility re-export paths.

Type of Change

  • Code change (feature, bug fix, or refactor)
  • Code change with doc updates
  • Doc only (prose changes, no code sample modifications)
  • Doc only (includes code sample changes)

Verification

  • npx prek run --all-files passes
  • npm test passes
  • Tests added or updated for new or changed behavior
  • No secrets, API keys, or credentials committed
  • Docs updated for user-facing behavior changes
  • make docs builds without warnings (doc changes only)
  • Doc pages follow the style guide (doc changes only)
  • New doc pages include SPDX header and frontmatter (new pages only)

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

  • Documentation
    • Added comprehensive README files documenting the internal structure, scope, and organization guidelines for multiple module directories.
    • Establishes clear architectural boundaries, layering rules, and file placement guidance to improve code organization and maintainability.
    • Documents the intended purpose and constraints for each module area to support future development.

@cv cv self-assigned this May 7, 2026
@coderabbitai

coderabbitai Bot commented May 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review Change Stack
No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 1609699e-9dd1-4b6e-8a61-867fd4bb8765

📥 Commits

Reviewing files that changed from the base of the PR and between edb85f0 and afaf906.

📒 Files selected for processing (6)
  • src/lib/README.md
  • src/lib/core/README.md
  • src/lib/inference/README.md
  • src/lib/onboard/README.md
  • src/lib/sandbox/README.md
  • src/lib/security/README.md
📝 Walkthrough

Walkthrough

This PR introduces comprehensive architectural documentation for src/lib, defining primary layers (commands, actions, domain, adapters, state, cli, core) and transitional feature folders (onboard, inference, sandbox, security, credentials). Five new README files specify module responsibilities, import safety rules, and migration guidance without changing any code behavior.

Changes

src/lib Architecture Documentation

Layer / File(s) Summary
Main Architecture Overview
src/lib/README.md		 Documents the primary layer-to-directory mapping (commands, actions, domain, adapters, state, cli, core), defines layering rules and responsibilities, lists transitional feature folders, and provides step-by-step migration guidance with safe follow-up clusters.
Core Primitives
src/lib/core/README.md		 Specifies src/lib/core as home for tiny cross-cutting primitives with minimal dependencies (e.g., version.ts, ports.ts, json-types.ts, errno.ts, wait.ts, url-utils.ts, shell-quote.ts) and sets constraint to keep product/workflow logic out.
Feature Module Specifications
src/lib/inference/README.md, src/lib/onboard/README.md, src/lib/sandbox/README.md, src/lib/security/README.md		 Details the scope and suggested file homes for transitional feature folders: inference (model config, health checks, local runtime, catalogs), onboard (onboarding flow, providers, probes), sandbox (configuration, build context, streams, channels), and security (redaction, secret-patterns, credential filters), with constraints on where related logic should reside.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

📚 A rabbit hops through structured shelves,
Where core holds primitives, neat and small,
And domain thinks while adapters delve
Through process bounds—now organized by all! 🐰

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes the primary change: adding documentation for the lib file placement map.
Linked Issues check ✅ Passed The PR comprehensively fulfills issue #3164 requirements: documents target layout rules, creates orientation READMEs for core/inference/onboard/sandbox/security, identifies transitional folders, and lists safe/high-risk files.
Out of Scope Changes check ✅ Passed All changes are documentation-only (five new README files) and directly address the placement map and migration guidance objectives from issue #3164.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch refactor/lib-placement-map

Comment @coderabbitai help to get the list of available commands and usage tips.

@cv cv added the v0.0.37 label May 7, 2026
@cv cv marked this pull request as draft May 7, 2026 16:56
@copy-pr-bot

copy-pr-bot Bot commented May 7, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@cv cv marked this pull request as ready for review May 7, 2026 18:09
@cv cv requested review from cjagwani, jyaunches and prekshivyas May 7, 2026 18:10
@cv cv changed the base branch from refactor/reorg-migrated-workflows to main May 7, 2026 18:10
prekshivyas
prekshivyas approved these changes May 7, 2026
View reviewed changes

@prekshivyas prekshivyas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pure documentation, 165+/0- across 6 READMEs establishing the architectural vocabulary for the ongoing src/lib/ reorg work. Closes #3164.

The layering rules in src/lib/README.md accurately reflect the patterns that emerged through the recent extraction PRs (#3080, #3083, #3088, #3090, #3107, #3108) — commands parse argv, actions own workflow, domain stays pure, adapters isolate boundaries, state owns persistence, cli for framework, core for cross-cutting primitives. The 14 transitional feature folders (agent/credentials/dashboard/deploy/diagnostics/inference/messaging/onboard/policy/runtime/sandbox/security/shields/tunnel) are sensible intermediate homes for clusters too large to split directly into the primary layers yet.

Specific things that read well:

  • High-import legacy files (onboard.ts, runner.ts, policies.ts, nim.ts, services.ts) explicitly called out as either move-late or keep-compatibility-re-export. Matches the pattern actually used in #3098/#3101 (e.g. resolveSandboxOclifDispatch alias).
  • core/README.md includes a scope-creep guard: "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."
  • inference/README.md documents the longer-term destination (src/lib/domain/inference/** for pure decisions, src/lib/adapters/** for HTTP/process boundaries) without forcing the split now.
  • onboard/README.md warns: "Do not move src/lib/onboard.ts casually. It is high-import and high-risk." Good — that file has been friction throughout the stack.
  • security/README.md correctly carves persistence (credentials) out of security helpers (redaction/patterns/filtering).
  • Migration sequence step (1) is this PR; steps 2-5 sequence low-risk clusters first (agent, dashboard, diagnostics, shields), then security/credentials/core, then inference/model, then onboarding support modules before tackling onboard.ts itself. Right priority order.

CI: pr.yaml rollup checks pass (commit-lint, dco, layer-boundary, check-hash, changes, get-pr-info, markdown-links, CodeRabbit). checks / macos-e2e / build-sandbox-images and current self-hosted run still in progress at approval time.

@jyaunches jyaunches self-assigned this May 7, 2026
@cv cv enabled auto-merge (squash) May 7, 2026 18:15
@cv cv merged commit 131f511 into main May 7, 2026
16 checks passed
This was referenced May 7, 2026
Merged
Merged
@miyoungc miyoungc mentioned this pull request May 7, 2026
Merged
jyaunches pushed a commit that referenced this pull request May 8, 2026
@miyoungc @cursoragent
docs: prepare 0.0.37 release docs (#3215)
37050a6 
## Summary
- Bump the docs release metadata to `0.0.37`.
- Document release-prep updates for messaging policy presets, sandbox
runtime utilities, and the GPU CDI troubleshooting path.
- Refresh generated `nemoclaw-user-*` skills from the updated docs.

## Source summary
- #3159 -> `docs/reference/troubleshooting.md`: Documents the GPU CDI
preflight warning and remediation for `nvidia.com/gpu=all` gateway start
failures.
- #2415 -> `docs/reference/network-policies.md`,
`docs/manage-sandboxes/messaging-channels.md`,
`docs/network-policy/customize-network-policy.md`: Clarifies that
Telegram, Discord, and Slack egress comes from opt-in messaging presets,
not the baseline policy.
- #3091 -> `docs/deployment/sandbox-hardening.md`,
`docs/network-policy/customize-network-policy.md`: Documents the
retained sandbox utilities `vi`, `jq`, and `dos2unix` while keeping
host-side policy files as the durable source of truth.

## Test plan
- `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix
nemoclaw-user`
- `make docs`
- `npm run build:cli`
- `npm run typecheck:cli`
- Commit and pre-push hooks: markdownlint, docs-to-skills verification,
gitleaks, commitlint, CLI typecheck

## Skipped
- #3193 and #3191 matched `docs/.docs-skip` entries for experimental
shields/config paths.
- #3200 and #3183 were test-only fixes.
- #3189 and #3163 were internal documentation/refactor changes with no
public docs impact.

Made with [Cursor](https://cursor.com)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Clarified which utilities remain in the sandbox runtime for
lightweight inspection and cleanup
* Noted that messaging endpoints (Discord, Slack, Telegram) are not in
the baseline policy and that channel presets are applied during
onboarding
  * Added GPU passthrough troubleshooting for gateway startup
* Updated release/version bump and release-prep workflow guidance,
including Discord preset description updates
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
@cv cv deleted the refactor/lib-placement-map branch May 27, 2026 21:17
@wscurran wscurran added area: docs Documentation, examples, guides, or docs build chore Build, CI, dependency, or tooling maintenance and removed documentation labels Jun 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@prekshivyas prekshivyas prekshivyas approved these changes

@jyaunches jyaunches Awaiting requested review from jyaunches

@cjagwani cjagwani Awaiting requested review from cjagwani

Assignees

@cv cv

@jyaunches jyaunches

Labels

area: docs Documentation, examples, guides, or docs build chore Build, CI, dependency, or tooling maintenance

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Reorg src/lib

4 participants

@cv @prekshivyas @jyaunches @wscurran