Claude/gracious liskov

.agents/skills/update-docs-from-commits/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: update-docs-from-commits
+description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift.
+---
+
+# Update Docs from Commits
+
+Scan recent git history for commits that affect user-facing behavior and draft documentation updates for each.
+
+## Prerequisites
+
+- You must be in the NemoClaw git repository (`NemoClaw`).
+- The `docs/` directory must exist with the current doc set.
+
+## When to Use
+
+- After a batch of features or fixes has landed and docs may be stale.
+- Before a release, to catch any doc gaps.
+- When a contributor asks "what docs need updating?"
+
+## Step 1: Identify Relevant Commits
+
+Determine the commit range. The user may provide one explicitly (e.g., "since v0.1.0" or "last 30 commits"). If not, default to commits since the head of the main branch.
+
+```bash
+# Commits since a tag
+git log v0.1.0..HEAD --oneline --no-merges
+
+# Or last 50 commits
+git log -50 --oneline --no-merges
+```
+
+Filter to commits that are likely to affect docs. Look for these signals:
+
+1. **Commit type**: `feat`, `fix`, `refactor`, `perf` commits often change behavior. `docs` commits are already doc changes. `chore`, `ci`, `test` commits rarely need doc updates.
+2. **Files changed**: Changes to `nemoclaw/src/`, `nemoclaw-blueprint/`, `bin/`, `scripts/`, or policy-related code are high-signal.
+3. **Ignore**: Changes limited to `test/`, `.github/`, or internal-only modules.
+
+```bash
+# Show files changed per commit to assess impact
+git log v0.1.0..HEAD --oneline --no-merges --name-only
+```
+
+## Step 2: Map Commits to Doc Pages
+
+For each relevant commit, determine which doc page(s) it affects. Use this mapping as a starting point:
+
+| Code area | Likely doc page(s) |
+|---|---|
+| `nemoclaw/src/commands/` (launch, connect, status, logs) | `docs/reference/commands.md` |
+| `nemoclaw/src/commands/` (new command) | May need a new page or entry in `docs/reference/commands.md` |
+| `nemoclaw/src/blueprint/` | `docs/about/architecture.md` |
+| `nemoclaw/src/cli.ts` or `nemoclaw/src/index.ts` | `docs/reference/commands.md`, `docs/get-started/quickstart.md` |
+| `nemoclaw-blueprint/orchestrator/` | `docs/about/architecture.md` |
+| `nemoclaw-blueprint/policies/` | `docs/reference/network-policies.md` |
+| `nemoclaw-blueprint/blueprint.yaml` | `docs/about/architecture.md`, `docs/reference/inference-profiles.md` |
+| `scripts/` (setup, start) | `docs/get-started/quickstart.md` |
+| `Dockerfile` | `docs/about/architecture.md` |
+| Inference-related changes | `docs/reference/inference-profiles.md` |
+
+If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.
+
+## Step 3: Read the Commit Details
+
+For each commit that needs a doc update, read the full diff to understand the change:
+
+```bash
+git show <commit-hash> --stat
+git show <commit-hash>
+```
+
+Extract:
+
+- What changed (new flag, renamed command, changed default, new feature).
+- Why it changed (from the commit message body, linked issue, or PR description).
+- Any breaking changes or migration steps.
+
+## Step 4: Read the Current Doc Page
+
+Before editing, read the full target doc page to understand its current content and structure.
+
+Identify where the new content should go. Follow the page's existing structure.
+
+## Step 5: Draft the Update
+
+Write the doc update following these conventions:
+
+- **Active voice, present tense, second person.**
+- **No unnecessary bold.** Reserve bold for UI labels and parameter names.
+- **No em dashes** unless used sparingly. Prefer commas or separate sentences.
+- **Start sections with an introductory sentence** that orients the reader.
+- **No superlatives.** Say what the feature does, not how great it is.
+- **Code examples use `console` language** with `$` prompt prefix.
+- **Include the SPDX header** if creating a new page.
+- **Match existing frontmatter format** if creating a new page.
+- **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia.
+- **Always capitalize NemoClaw correctly.** Wrong: nemoclaw (in prose), Nemoclaw.
+- **Always capitalize OpenShell correctly.** Wrong: openshell (in prose), Openshell, openShell.
+- **Do not number section titles.** Wrong: "Section 1: Configure Inference" or "Step 3: Verify." Use plain descriptive titles.
+- **No colons in titles.** Wrong: "Inference: Cloud and Local." Write "Cloud and Local Inference" instead.
+- **Use colons only to introduce a list.** Do not use colons as general-purpose punctuation between clauses.
+
+When updating an existing page:
+
+- Add content in the logical place within the existing structure.
+- Do not reorganize sections unless the change requires it.
+- Update any cross-references or "Next Steps" links if relevant.
+
+When creating a new page:
+
+- Follow the frontmatter template from existing pages in `docs/`.
+- Add the page to the appropriate `toctree` in `docs/index.md`.
+
+## Step 6: Present the Results
+
+After drafting all updates, present a summary to the user:
+
+```
+## Doc Updates from Commits
+
+### Updated pages
+- `docs/reference/commands.md`: Added `eject` command documentation (from commit abc1234).
+- `docs/reference/network-policies.md`: Updated policy schema for new egress rule (from commit def5678).
+
+### New pages needed
+- None (or list any new pages created).
+
+### Commits with no doc impact
+- `chore(deps): bump typescript` (abc1234) — internal dependency, no user-facing change.
+- `test: add launch command test` (def5678) — test-only change.
+```
+
+## Step 7: Build and Verify
+
+After making changes, build the docs locally:
+
+```bash
+make docs
+```
+
+Check for:
+
+- Build warnings or errors.
+- Broken cross-references.
+- Correct rendering of new content.
+
+## Tips
+
+- When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior.
+- Group related commits that touch the same doc page into a single update rather than making multiple small edits.
+- If a commit is a breaking change, add a note at the top of the relevant section using a `:::{warning}` admonition.
+- PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories.
+
+## Example Usage
+
+User says: "Catch up the docs for everything merged since v0.1.0."
+
+1. Run `git log v0.1.0..HEAD --oneline --no-merges --name-only`.
+2. Filter to `feat`, `fix`, `refactor`, `perf` commits touching user-facing code.
+3. Map each to a doc page.
+4. Read the commit diffs and current doc pages.
+5. Draft updates following the style guide.
+6. Present the summary.
+7. Build with `make docs` to verify.

.c8rc.json

@@ -0,0 +1,25 @@
+{
+  "all": true,
+  "src": ["bin", "test"],
+  "exclude": [
+    "**/*.test.js",
+    "node_modules/**",
+    "nemoclaw/node_modules/**",
+    "nemoclaw/dist/**",
+    "nemoclaw-blueprint/**",
+    "docs/**",
+    ".devcontainer/**",
+    ".github/**",
+    "scripts/**",
+    "coverage/**",
+    ".jscpd/**"
+  ],
+  "reporter": ["text", "lcov", "html"],
+  "reports-dir": "coverage",
+  "check-coverage": true,
+  "lines": 30,
+  "functions": 40,
+  "branches": 65,
+  "statements": 30,
+  "per-file": false
+}

.devcontainer/README.md

@@ -0,0 +1,171 @@
+# NemoClaw Dev Container
+
+This directory contains the VS Code Dev Container configuration for NemoClaw development.
+
+## What is a Dev Container?
+
+A development container (devcontainer) is a fully configured development environment running in a Docker container. It provides a consistent, reproducible environment for all contributors, whether human developers or autonomous AI agents.
+
+## Features
+
+This devcontainer includes:
+
+### Base Environment
+- **Node.js 22** (Debian Bookworm base image)
+- **Python 3.11** with pip, uv, and development tools
+- **Docker-in-Docker** for testing containerized workflows
+- **Git** with LFS support
+
+### VS Code Extensions
+
+**TypeScript/JavaScript:**
+- ESLint - Linting and code quality
+- Prettier - Code formatting
+- TypeScript Next - Latest TypeScript language features
+
+**Python:**
+- Python extension - IntelliSense, debugging, testing
+- Pylance - Fast type checking
+- Ruff - Fast Python linter and formatter
+
+**Git:**
+- GitLens - Git supercharged (blame, history, etc.)
+- GitHub Pull Requests - Review and manage PRs from VS Code
+
+**Documentation:**
+- Markdown All in One - Markdown authoring
+- markdownlint - Markdown linting
+
+**General:**
+- EditorConfig - Consistent coding styles
+- Code Spell Checker - Catch typos
+
+### Pre-Configured Settings
+
+- **TypeScript**: Auto-format on save with Prettier, ESLint auto-fix
+- **Python**: Auto-format on save with Ruff, import organization
+- **Editor**: 100-character ruler, 2-space tabs, trim whitespace
+- **Git**: Auto-fetch enabled, safe directory configured
+
+### Automatic Setup
+
+The `postCreate.sh` script runs after container creation:
+1. Installs Python dependencies (uv sync)
+2. Installs TypeScript dependencies (npm install)
+3. Installs root dependencies (test runner, code quality tools)
+4. Installs pre-commit hooks
+5. Builds TypeScript plugin
+6. Displays quick start guide
+
+## Using the Dev Container
+
+### First Time Setup
+
+1. **Install Prerequisites:**
+   - [Visual Studio Code](https://code.visualstudio.com/)
+   - [Docker Desktop](https://www.docker.com/products/docker-desktop)
+   - [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+2. **Open in Container:**
+   - Clone the repository
+   - Open the folder in VS Code
+   - Click "Reopen in Container" when prompted
+   - Or use Command Palette (F1): `Dev Containers: Reopen in Container`
+
+3. **Wait for Initialization:**
+   - First build takes ~2-3 minutes
+   - Subsequent starts are much faster (~30 seconds)
+   - Watch the progress in the terminal
+
+4. **Start Developing:**
+   - All dependencies are installed
+   - Pre-commit hooks are configured
+   - TypeScript is built and ready
+   - You can immediately run `npm test`, `make check`, etc.
+
+### Rebuilding the Container
+
+If you modify `.devcontainer/devcontainer.json` or `postCreate.sh`:
+
+1. Command Palette (F1): `Dev Containers: Rebuild Container`
+2. Or: `Dev Containers: Rebuild Without Cache` for a clean rebuild
+
+### SSH Keys and Git
+
+The devcontainer mounts your local `~/.ssh` directory (read-only) so you can use your SSH keys for Git operations without copying them into the container.
+
+## For Autonomous Agents
+
+The devcontainer provides a fully configured environment for autonomous AI agents:
+
+**Benefits:**
+- Consistent environment across all agents
+- No "works on my machine" issues
+- All tools pre-installed and configured
+- Editor settings enforce code quality
+- Pre-commit hooks automatically configured
+
+**Agent Workflow:**
+1. Open repository in devcontainer
+2. Environment is ready - no setup needed
+3. Make changes with all tools available
+4. Pre-commit hooks run automatically on commit
+5. All linters, formatters, type checkers work out of the box
+
+**Testing Agent Changes:**
+```bash
+# All these commands work immediately in the devcontainer:
+npm test                    # Run unit tests
+cd nemoclaw && npm run check  # TypeScript checks
+cd nemoclaw-blueprint && make check  # Python checks
+make complexity             # Complexity analysis
+make dead-code              # Dead code detection
+make duplicates             # Duplicate code detection
+make tech-debt              # Technical debt tracking
+```
+
+## Troubleshooting
+
+### Container Won't Build
+- Check Docker is running: `docker ps`
+- Check disk space: `docker system df`
+- Try rebuild without cache
+
+### Slow Performance
+- Allocate more resources to Docker (Settings → Resources)
+- Use Docker volumes for node_modules (already configured)
+
+### Extensions Not Working
+- Reload window: `Developer: Reload Window`
+- Reinstall extension inside container
+
+### Post-Create Script Failed
+- Check terminal output for specific error
+- Run manually: `.devcontainer/postCreate.sh`
+- Report issue with error message
+
+## Configuration Files
+
+- **devcontainer.json**: Main configuration (image, features, extensions, settings)
+- **postCreate.sh**: Initialization script (dependencies, hooks, build)
+- **README.md**: This file (documentation)
+
+## Customization
+
+To customize for your workflow:
+
+1. **Add Extensions:** Edit `customizations.vscode.extensions` in devcontainer.json
+2. **Change Settings:** Edit `customizations.vscode.settings` in devcontainer.json
+3. **Add Tools:** Edit `postCreate.sh` to install additional tools
+4. **Change Base Image:** Edit `image` in devcontainer.json (requires rebuild)
+
+## References
+
+- [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers)
+- [devcontainer.json reference](https://containers.dev/implementors/json_reference/)
+- [Dev Container Features](https://containers.dev/features)
+- [NemoClaw AGENTS.md](../AGENTS.md) - Full development guide
+
+---
+
+**Questions?** See [CONTRIBUTING.md](../CONTRIBUTING.md) or ask in GitHub Discussions.