nerftools 0.3.2__tar.gz → 1.1.0__tar.gz

{nerftools-0.3.2 → nerftools-1.1.0}/.cspell.json

@@ -5,26 +5,22 @@
     "agentic",
     "Agentworks",
     "bunx",
+    "codegen",
+    "coreutils",
     "dataclass",
     "dataclasses",
-    "defanged",
-    "elif",
+    "errexit",
     "esac",
+    "footguns",
     "execdir",
     "exitcode",
-    "frontmatter",
-    "gwat",
-    "invokable",
     "metacharacter",
     "metacharacters",
     "myapp",
     "mypy",
     "mywi",
     "nerfctl",
-    "nerfed",
     "nerftools",
-    "noprofile",
-    "norc",
     "okdir",
     "oneline",
     "permissioning",
@@ -33,16 +29,13 @@
     "pnpx",
     "pyproject",
     "pytest",
-    "pytestmark",
     "rulesync",
     "Rulesync",
     "stdutils",
     "subshell",
-    "tmpl",
-    "upgen",
+    "TOCTOU",
+    "typer",
     "uppercased",
-    "usecases",
-    "variadics",
     "wiql",
     "WIQL"
   ],
@@ -52,6 +45,9 @@
   "ignorePaths": [
     "node_modules",
     "out/",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "**/*.yaml",
+    "**/*.yml",
+    "**/*.py"
   ]
 }

{nerftools-0.3.2 → nerftools-1.1.0}/.github/workflows/ci.yml

@@ -60,4 +60,4 @@ jobs:
       - name: cspell
         uses: streetsidesoftware/cspell-action@v8
         with:
-          files: "**/*.{md,py,yaml}"
+          files: "**/*.md"

{nerftools-0.3.2 → nerftools-1.1.0}/.github/workflows/release-please.yml

@@ -13,12 +13,11 @@ jobs:
       FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
     outputs:
       pr_branch: ${{ steps.extract.outputs.pr_branch }}
-      app_token: ${{ steps.app-token.outputs.token }}
     steps:
       # Use a GitHub App token so the release PR (and any subsequent pushes
       # to its branch) trigger CI workflows. The default GITHUB_TOKEN creates
       # events as github-actions[bot], which GitHub won't run workflows for.
-      - uses: actions/create-github-app-token@v2
+      - uses: actions/create-github-app-token@v3
         id: app-token
         with:
           app-id: ${{ vars.RELEASE_APP_ID }}
@@ -43,7 +42,7 @@ jobs:
     if: needs.release-please.outputs.pr_branch
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/create-github-app-token@v2
+      - uses: actions/create-github-app-token@v3
         id: app-token
         with:
           app-id: ${{ vars.RELEASE_APP_ID }}
@@ -59,19 +58,19 @@ jobs:
         with:
           enable-cache: true
 
-      - name: Install dependencies
-        run: uv sync --frozen
+      - name: Sync lockfile and install dependencies
+        run: uv sync
 
       - name: Regenerate Claude Code plugin
-        run: uv run nerf generate --target claude-plugin --plugin-config nerf-plugin.yaml --outdir ./out/claude-plugin
+        run: uv run nerf generate --target claude-plugin -c nerf.yaml --outdir ./out/claude-plugin
 
-      - name: Commit updated plugin
+      - name: Commit updated plugin and lockfile
         run: |
           git config user.name "nerftools-release[bot]"
           git config user.email "nerftools-release[bot]@users.noreply.github.com"
-          git add out/claude-plugin/
+          git add out/claude-plugin/ uv.lock
           if git diff --cached --quiet; then
-            echo "No changes to plugin output"
+            echo "No changes to plugin output or lockfile"
           else
             git commit -m "build: regenerate Claude Code plugin for release"
             git push

{nerftools-0.3.2 → nerftools-1.1.0}/.gitignore

@@ -40,3 +40,6 @@ Thumbs.db
 .pytest_cache/
 htmlcov/
 .coverage
+
+# tmuxinator config is personal
+.tmuxinator.yml

nerftools-1.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.1.0"
+}

nerftools-1.1.0/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+## [1.1.0](https://github.com/WayfarerLabs/nerftools/compare/v1.0.0...v1.1.0) (2026-05-04)
+
+
+### Features
+
+* **az-devops:** new package with az-devops-set-default-project tool ([0fb4a15](https://github.com/WayfarerLabs/nerftools/commit/0fb4a15347edd279481f51a85506e3ad254a7479))
+* **azdo:** --project everywhere, new pipelines/repos tools, area listing ([a42f7e7](https://github.com/WayfarerLabs/nerftools/commit/a42f7e71eab7e3d5dcc04de50377ef504c7fefaa))
+* **azdo:** --project everywhere, new tools, set-default-project ([2dab02d](https://github.com/WayfarerLabs/nerftools/commit/2dab02df9d885d6636e37bfe718b57a3617dbded))
+* **gh:** differentiate the four PR comment surfaces ([567b64d](https://github.com/WayfarerLabs/nerftools/commit/567b64dc18444ff3df17e2f0ee04e67d24469dfc))
+* **gh:** differentiate the four PR comment surfaces; add reviews tool ([ca9ab91](https://github.com/WayfarerLabs/nerftools/commit/ca9ab910ebd7e426b4704b47994cbdc1b4518232))
+* **manifest:** add path_tests for filesystem-typed parameters ([e035eac](https://github.com/WayfarerLabs/nerftools/commit/e035eac70eabf84a6b02ef508b7995fe943708ec))
+* **manifest:** add path_tests for filesystem-typed parameters ([fdb64cd](https://github.com/WayfarerLabs/nerftools/commit/fdb64cde6201f3d567cdfb04ff8e1c955c08d0a7))
+* massive add of az-related default tools ([818fe04](https://github.com/WayfarerLabs/nerftools/commit/818fe04326be536924de4e7450e202db759df362))
+
+
+### Bug Fixes
+
+* address PR review feedback on az and kubectl tools ([4395484](https://github.com/WayfarerLabs/nerftools/commit/4395484f4388f99ee760a774ae7be406d40d586b))
+* address two minor PR review nits ([adad61d](https://github.com/WayfarerLabs/nerftools/commit/adad61d071fc325325e12148b8e58104def93b0e))
+* **az-aks:** split admin credential fetch, mark command-invoke admin, fix variadic ([f152896](https://github.com/WayfarerLabs/nerftools/commit/f152896f4af595b235be0d3af1d5d1e1b7e1cd91))
+* **az-keyvault:** drop secret fingerprint and tighten masked output ([242f8d7](https://github.com/WayfarerLabs/nerftools/commit/242f8d79e4c9a3d3a34a59dd6ab58d12476409b5))
+* **az-monitor:** dry-run honors validation; --interval allows P1D and FULL ([c246266](https://github.com/WayfarerLabs/nerftools/commit/c2462661def1d26d9556925b359ef79d2fa43b88))
+* **builder:** add hint lines to path_tests errors; doc symlink semantics ([a1e602b](https://github.com/WayfarerLabs/nerftools/commit/a1e602b691091c1b08f5017074467d397f3bb382))
+* **builder:** preserve shell quoting in dry-run output via printf %q ([5ef4816](https://github.com/WayfarerLabs/nerftools/commit/5ef4816f086833445310674d4f9d157c609ad91d))
+* **builder:** reject --nerf-dry-run tokens inside variadic+allow_flags args ([854519c](https://github.com/WayfarerLabs/nerftools/commit/854519c4070a35592b0f5358e223e270d812ad3d))
+* **builder:** reject trailing tokens after declared positionals ([9580f8b](https://github.com/WayfarerLabs/nerftools/commit/9580f8b32dcc41332caca08d7bbebffd2a643409))
+* **builder:** revert ineffective set -e in _nerf_pre, document the limitation ([7e6787a](https://github.com/WayfarerLabs/nerftools/commit/7e6787a788a58b37ae63bd5486c068af2238ea17))
+* **builder:** under_cwd accepts paths under root when cwd is "/" ([3b05ccd](https://github.com/WayfarerLabs/nerftools/commit/3b05ccd02c0ffa8e91cefcad6a3112228b281d0a))
+* cross-platform date in az-monitor, drop None aggregation, simplify timeout msg ([616385d](https://github.com/WayfarerLabs/nerftools/commit/616385d7f411cfc091c6c8ef81ecbcd94b33ca45))
+* **gh-pr-reviews:** use --paginate; fix Changes-requested wording ([97e5f41](https://github.com/WayfarerLabs/nerftools/commit/97e5f412d9d37378e366b25b8044b2cd8274ec10))
+* **gh:** add --slurp so paginated jq aggregates across pages ([8ebd3eb](https://github.com/WayfarerLabs/nerftools/commit/8ebd3eb00bcb3b7687306fdcdde5263599b8dac5))
+* high-impact security and correctness from second-pass review ([022af82](https://github.com/WayfarerLabs/nerftools/commit/022af82533d88258680c7ca02b9d9b95302e35e1))
+* **kubectl:** convert read-only tools from passthrough to template ([782b3a7](https://github.com/WayfarerLabs/nerftools/commit/782b3a7c0f97fd9feda09d6c363c66c0d93c2768))
+* **kubectl:** kubectl-config-use-context is admin-threat, tighten pattern ([f1265ce](https://github.com/WayfarerLabs/nerftools/commit/f1265ce1b67f5396829879a3c39d75f23f389edf))
+* more PR review feedback (rename misleading tool, guard external deps) ([6c101a4](https://github.com/WayfarerLabs/nerftools/commit/6c101a48b08560acc44342dc0c3d763ce2e72a20))
+* paginate the remaining gh read tools; tighten cross-refs and doc ([8d48ed5](https://github.com/WayfarerLabs/nerftools/commit/8d48ed5d8c11abb5c72c73aee032ac1d23ef1a82))
+* require 3+ word tool descriptions to catch trivial placeholders ([3433ffd](https://github.com/WayfarerLabs/nerftools/commit/3433ffd6a79c92a91743968639311be9b199a6a9))
+* smaller hardening from second-pass review ([5079b21](https://github.com/WayfarerLabs/nerftools/commit/5079b21039265787dfc63721a47c6b3cf358c089))
+* stop appending "." to descriptions; require terminal punctuation in manifest ([2ce0f11](https://github.com/WayfarerLabs/nerftools/commit/2ce0f11f514e57e4e0a029a786686cb5b54cdd04))
+
+
+### Documentation
+
+* address review feedback on coverage gap and template paragraph ([dec48de](https://github.com/WayfarerLabs/nerftools/commit/dec48def42011233452ed7b85d0e85697c78431a))
+* **az-account:** document --subscription scope boundary ([b105f2b](https://github.com/WayfarerLabs/nerftools/commit/b105f2b008cafe9d548a743885c5fa93b2cf02b8))
+* correct --nerf-dry-run position claim and warn against local in pre ([9231598](https://github.com/WayfarerLabs/nerftools/commit/923159816725486aa12c3f9f26442b75da5f04cb))
+* document passthrough security limitations around alternative flag syntax ([44031d5](https://github.com/WayfarerLabs/nerftools/commit/44031d5a71864313a6dbc1362d547ac6ddb6ccca))
+
+## [1.0.0](https://github.com/WayfarerLabs/nerftools/compare/v0.3.2...v1.0.0) (2026-04-19)
+
+
+### ⚠ BREAKING CHANGES
+
+* `--plugin-config` and `--prefix` flags are removed. Use `-c <path>` to pass a config file. `--prefix` is now configured via `defaults.prefix` in the config file.
+
+### Features
+
+* introduce optional config file, drop --plugin-config and install script ([f6a1ab9](https://github.com/WayfarerLabs/nerftools/commit/f6a1ab95f7f1e22fc84d6fea111390db38ef6ebb))
+
+
+### Bug Fixes
+
+* address review feedback from Copilot ([60f4bc5](https://github.com/WayfarerLabs/nerftools/commit/60f4bc53ca87607b40873554a48ba7984a7b6c9e))
+* **ci:** sync uv.lock during release to prevent version drift ([6eef9b8](https://github.com/WayfarerLabs/nerftools/commit/6eef9b8d6dfd2ccc0646cca71bdcc95fff779f48))
+
+
+### Documentation
+
+* **sdd:** capture the refactor sdd as it defined the fundamental structure ([5c7cad4](https://github.com/WayfarerLabs/nerftools/commit/5c7cad4248c3320cd7d67848d4963376dd8f24ee))
+
+## [0.3.2](https://github.com/WayfarerLabs/nerftools/compare/v0.3.1...v0.3.2) (2026-04-14)
+
+
+### Documentation
+
+* clean up pypi description ([d2b5f7f](https://github.com/WayfarerLabs/nerftools/commit/d2b5f7fef31e4ac0048a0a35059b2d24ea3e07ac))
+* clean up pypi description ([d2ab29d](https://github.com/WayfarerLabs/nerftools/commit/d2ab29d03366f92e1e6660ba99745b7d2a0469f5))
+
+## [0.3.1](https://github.com/WayfarerLabs/nerftools/compare/v0.3.0...v0.3.1) (2026-04-14)
+
+
+### Bug Fixes
+
+* use app token for regenerate-dist pushes so CI triggers on release PRs ([e78ae87](https://github.com/WayfarerLabs/nerftools/commit/e78ae875208a100d77cde6cb0881186e61b83e60))
+
+## [0.3.0](https://github.com/WayfarerLabs/nerftools/compare/v0.2.0...v0.3.0) (2026-04-14)
+
+
+### Features
+
+* add --embed-marketplace option for standalone plugin deployment ([d00ae28](https://github.com/WayfarerLabs/nerftools/commit/d00ae28170857702a29141f24bec15c62e034c8b))
+* initial nerftools repo with Python package and pre-built Claude Code plugin ([55eee79](https://github.com/WayfarerLabs/nerftools/commit/55eee79eb462dfb996568d42e05b86fe3a11ce3a))
+* templatize plugin metadata via nerf-plugin.yaml config ([05086d6](https://github.com/WayfarerLabs/nerftools/commit/05086d63214351f2f9cef21fd4b6dc0679a52bd4))
+
+
+### Bug Fixes
+
+* doc update as fix to trigger release pipeline ([79ede3c](https://github.com/WayfarerLabs/nerftools/commit/79ede3c0f7fad1446e960bef3f943c5ca83e1a08))
+* drop component prefix from release-please tags to match release … ([ac70693](https://github.com/WayfarerLabs/nerftools/commit/ac70693efa1e418348e5b7f10b964ebed82258db))
+* drop component prefix from release-please tags to match release workflow ([6f92386](https://github.com/WayfarerLabs/nerftools/commit/6f92386f6fdc3dab9b63cc12ad9fcfead327382b))
+
+
+### Documentation
+
+* additional readme tweaks ([4f7267f](https://github.com/WayfarerLabs/nerftools/commit/4f7267f8112c215ffc0fd50d0cdd2a9d6430ea87))
+* document the release process in CONTRIBUTING.md ([cfd29c8](https://github.com/WayfarerLabs/nerftools/commit/cfd29c8b144d17d58232c6b8677451c427627d8a))
+* fix manifest spec link and split threat model content between README and spec ([60493c8](https://github.com/WayfarerLabs/nerftools/commit/60493c846bb9fbffde8875a576a4698e4ae2e461))
+* move manifest guide and ref from readme ([6392c0b](https://github.com/WayfarerLabs/nerftools/commit/6392c0b716892080137b133487f3a536650590b3))
+* polish README intro and update quick start with --plugin-config ([6cd3dde](https://github.com/WayfarerLabs/nerftools/commit/6cd3dde8c3b98dc8be7c57b1d0a3de84429bd9d0))
+* update readme with additional context ([a93632d](https://github.com/WayfarerLabs/nerftools/commit/a93632dd217d5dad44ee4df3c86a31c282640636))
+
+## [0.2.0](https://github.com/WayfarerLabs/nerftools/compare/nerftools-v0.1.0...nerftools-v0.2.0) (2026-04-14)
+
+
+### Features
+
+* add --embed-marketplace option for standalone plugin deployment ([d00ae28](https://github.com/WayfarerLabs/nerftools/commit/d00ae28170857702a29141f24bec15c62e034c8b))
+* initial nerftools repo with Python package and pre-built Claude Code plugin ([55eee79](https://github.com/WayfarerLabs/nerftools/commit/55eee79eb462dfb996568d42e05b86fe3a11ce3a))
+* templatize plugin metadata via nerf-plugin.yaml config ([05086d6](https://github.com/WayfarerLabs/nerftools/commit/05086d63214351f2f9cef21fd4b6dc0679a52bd4))
+
+
+### Bug Fixes
+
+* doc update as fix to trigger release pipeline ([79ede3c](https://github.com/WayfarerLabs/nerftools/commit/79ede3c0f7fad1446e960bef3f943c5ca83e1a08))
+
+
+### Documentation
+
+* additional readme tweaks ([4f7267f](https://github.com/WayfarerLabs/nerftools/commit/4f7267f8112c215ffc0fd50d0cdd2a9d6430ea87))
+* document the release process in CONTRIBUTING.md ([cfd29c8](https://github.com/WayfarerLabs/nerftools/commit/cfd29c8b144d17d58232c6b8677451c427627d8a))
+* fix manifest spec link and split threat model content between README and spec ([60493c8](https://github.com/WayfarerLabs/nerftools/commit/60493c846bb9fbffde8875a576a4698e4ae2e461))
+* move manifest guide and ref from readme ([6392c0b](https://github.com/WayfarerLabs/nerftools/commit/6392c0b716892080137b133487f3a536650590b3))
+* polish README intro and update quick start with --plugin-config ([6cd3dde](https://github.com/WayfarerLabs/nerftools/commit/6cd3dde8c3b98dc8be7c57b1d0a3de84429bd9d0))
+* update readme with additional context ([a93632d](https://github.com/WayfarerLabs/nerftools/commit/a93632dd217d5dad44ee4df3c86a31c282640636))

{nerftools-0.3.2 → nerftools-1.1.0}/CONTRIBUTING.md

@@ -38,7 +38,7 @@ After changing manifests or plugin generation code, you can rebuild the pre-buil
 to preview the output:
 
 ```bash
-uv run nerf generate --target claude-plugin --plugin-config nerf-plugin.yaml --outdir ./out/claude-plugin
+uv run nerf generate --target claude-plugin -c nerf.yaml --outdir ./out/claude-plugin
 ```
 
 You don't need to commit the regenerated `out/` -- CI regenerates it as part of the release PR.
@@ -55,7 +55,7 @@ and conventional commits. No one manually bumps versions or creates tags.
 2. The `release-please` workflow keeps an open PR titled `chore(main): release X.Y.Z` that
    accumulates changes. On each push to `main` it:
    - Computes the next version from the conventional commits since the last release.
-   - Updates the version in `pyproject.toml`, `nerf-plugin.yaml`, and `.release-please-manifest.json`.
+   - Updates the version in `pyproject.toml`, `nerf.yaml`, and `.release-please-manifest.json`.
    - Updates `CHANGELOG.md`.
    - Regenerates `out/claude-plugin/` with the new version baked into `plugin.json`.
 3. When you're ready to release, merge the release PR.
@@ -75,7 +75,7 @@ and conventional commits. No one manually bumps versions or creates tags.
 - Don't create tags by hand. `release-please` creates tags on merge of the release PR.
 - Don't edit `CHANGELOG.md` by hand. It's regenerated from commit messages.
 - Don't edit `out/claude-plugin/` by hand. Edit the source (`nerftools/`, manifests, or
-  `nerf-plugin.yaml`) and the release PR will regenerate it.
+  `nerf.yaml`) and the release PR will regenerate it.
 
 ### Breaking changes
 

{nerftools-0.3.2 → nerftools-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nerftools
-Version: 0.3.2
+Version: 1.1.0
 Summary: Define and generate nerf tools: limited-scope wrappers for common CLI utilities that allow for fine-grained control over agent execution
 Project-URL: Homepage, https://github.com/WayfarerLabs/nerftools
 Project-URL: Repository, https://github.com/WayfarerLabs/nerftools

{nerftools-0.3.2 → nerftools-1.1.0}/README.md

@@ -100,14 +100,23 @@ uv run nerf generate --target bin --outdir ./bin
 # Generate rulesync skills
 uv run nerf generate --target skills --outdir ./skills
 
-# Generate a Claude Code plugin (requires a plugin metadata config)
-uv run nerf generate --target claude-plugin \
-  --plugin-config nerf-plugin.yaml \
-  --outdir ./claude-plugin
+# Generate a Claude Code plugin (uses built-in defaults if no config)
+uv run nerf generate --target claude-plugin --outdir ./claude-plugin
+
+# Generate a Claude Code plugin with custom identity
+uv run nerf generate --target claude-plugin -c nerf.yaml --outdir ./claude-plugin
 ```
 
-Plugin metadata is sourced from an external file to make it easy for teams to personalize the output
-plugin for their needs. See [nerf-plugin.yaml](nerf-plugin.yaml) for the plugin metadata format.
+Package identity and per-target settings live in an optional config file passed via `-c <path>`.
+When omitted, sensible defaults produce an installable plugin. See [nerf.yaml](nerf.yaml) for an
+example.
+
+To install the generated plugin:
+
+```bash
+claude plugin marketplace add <plugin-dir>
+claude plugin install <plugin-name>@<marketplace-name>
+```
 
 ## Default Manifests/Packages
 
@@ -183,6 +192,7 @@ nerftools/             Python package
   rendering.py         Shared display helpers (maps-to, usage tokens)
   skill.py             Rulesync skill generation
   formats.py           Claude Code plugin builder
+  config.py            Config loader, plugin metadata, defaults resolution
   cli.py               CLI (validate + generate)
   nerfctl/claude/      Grant management shell scripts
   default_manifests/   Default tool package manifests (YAML)

{nerftools-0.3.2 → nerftools-1.1.0}/docs/nerf-manifest.md

@@ -235,6 +235,18 @@ Rules:
 - A variadic argument's `{{kind.name}}` must be the last element of `command`.
 - The generated script ends with `exec`, replacing the process.
 
+**Literal command tokens are passed unquoted to bash.** Placeholder substitutions
+(`{{switches.x}}`, `{{options.x}}`, `{{arguments.x}}`) emit shell-quoted variable references and
+are always safe -- a value like `*.md` passed via `{{arguments.target}}` reaches the wrapped tool
+verbatim, with no glob expansion. The unquoted-token concern applies *only* to the static literal
+strings you put in `template.command`. The codegen lays each literal token down unquoted in the
+generated `exec` line, so bash sees them raw. This works for simple words, flags, and
+comma-separated lists (e.g. `--json title,body,state`), which covers the vast majority of cases.
+It does *not* work for literal tokens containing shell-special characters -- braces, parens,
+brackets, glob characters (`*`, `?`), tilde, redirects, pipes, dollar signs, backticks, quotes,
+whitespace, etc. If you need a literal token like that (a `jq` expression, etc.), or if you need
+any pipe / redirection / transformation logic, use `script` mode instead.
+
 Example:
 
 ```yaml
@@ -299,6 +311,33 @@ safe-find:
     prefix: [.]
 ```
 
+#### Known security limitations
+
+Passthrough deny operates on whole tokens, so it cannot enforce restrictions when the wrapped
+tool accepts alternative flag syntax:
+
+- **Short-flag stacking.** Tools that use POSIX-style or `pflag` short flags (notably `kubectl`,
+  many `getopt`-based utilities) allow combining boolean short flags into one token: `-Aw` is
+  parsed as `-A -w`. A deny entry of `-w` matches only the exact token `-w`, not `-Aw`, `-wA`,
+  `-Aow`, or any other stack containing `w`.
+- **Inline value forms.** For a flag that takes a value, the deny patterns `--watch` and `-w`
+  do not catch `--watch=true`, `-w=true`, or `-wtrue` (BSD-style short flag with concatenated
+  value). The first two can be partially mitigated with glob denies like `--watch=*` and
+  `-w=*`. The concatenated form `-wtrue` is syntactically indistinguishable from a short-flag
+  stack and cannot be reliably denied at the token level.
+
+**When this matters.** Use `template` mode when the wrapped tool is an agent-escape vector and
+supports either of the above syntaxes. Templates declare the entire surface up front, so any
+flag not declared in the manifest cannot reach the underlying command. Use passthrough only
+when the wrapped tool's flag surface is well-understood, or when an undeclared flag slipping
+through is purely an ergonomic issue rather than a safety one.
+
+**Future direction.** A future opt-in deny extension may recognize tokens matching
+`^-[a-zA-Z]{2,}$` and decompose them for deny matching, closing the short-flag-stacking gap.
+The concatenated-value form is likely to remain a passthrough limitation because it cannot be
+distinguished from a stack without per-tool flag knowledge. When in doubt, prefer template
+mode.
+
 ### script
 
 Run an inline bash script. Best for tools that need custom logic beyond wrapping a single command.
@@ -386,6 +425,8 @@ options:
     pattern: <string> # Regex the value must match (auto-anchored with ^...$)
     allow: [<string>, ...] # Exhaustive list of allowed values
     deny: [<string>, ...] # Values to reject
+    path_tests: [<test>, ...] # Mark as a filesystem path; see "Path tests" below
+    default: <string> # Default value seeded into the bash variable when the flag is omitted
 ```
 
 Rules:
@@ -396,6 +437,12 @@ Rules:
 - `pattern` is automatically anchored to a full match in the generated bash script.
 - When `repeatable: true`, the option can be passed multiple times. The generated script accumulates
   flag-value pairs in an array so `"${VAR[@]}"` expands to `--flag val1 --flag val2`.
+- `default` seeds the bash variable so inline placeholder substitutions like
+  `"{{options.x}}/foo"` see the value even when the agent omits the flag. `default` is
+  validated at manifest-load time: it must satisfy `pattern` / `allow` / `deny`, and is
+  mutually exclusive with `required: true`, `repeatable: true`, and `path_tests`
+  (path tests only evaluate against runtime cwd, so they cannot validate a load-time
+  default). `default` must be a string; YAML `null`, `true`, `0`, etc. are rejected.
 
 ### arguments
 
@@ -411,6 +458,7 @@ arguments:
     pattern: <string> # Regex the value must match (auto-anchored)
     allow: [<string>, ...] # Exhaustive list of allowed values
     deny: [<string>, ...] # Values to reject
+    path_tests: [<test>, ...] # Mark as a filesystem path; see "Path tests" below
 ```
 
 Rules:
@@ -421,6 +469,104 @@ Rules:
 - Variadic arguments become bash arrays; all others become scalar variables.
 - By default, variadic arguments reject tokens starting with `-` to prevent flag injection. Set
   `allow_flags: true` when forwarding to a tool that expects its own flags (e.g. pytest, ruff).
+- Arguments do not have a `default` field. Required positional arguments always receive a value;
+  optional positionals are exposed to the wrapped tool only when the agent supplies one.
+
+## Path tests
+
+Mark an option or argument as a filesystem path by setting `path_tests` to a non-empty list of
+test names. The generated script applies a baseline check (control characters rejected,
+canonicalization succeeds) plus the listed tests in a deterministic order.
+
+```yaml
+options:
+  directory:
+    description: Directory to run in
+    flag: -C
+    path_tests: [under_cwd, dir]
+arguments:
+  target:
+    description: File to format
+    required: true
+    path_tests: [under_cwd, file]
+```
+
+### Test catalog
+
+| Test | Meaning | Bash primitive |
+| ------------- | --------------------------------------------------------------- | -------------- |
+| `under_cwd`   | Canonicalized path is `$PWD` itself or under it (symlink-aware) | `realpath -m`  |
+| `exists`      | Path exists                                                     | `[[ -e ]]`     |
+| `not_exists`  | Path does not exist (e.g. for new-file targets)                 | `[[ ! -e ]]`   |
+| `file`        | Exists and is a regular file (implies `exists`)                 | `[[ -f ]]`     |
+| `dir`         | Exists and is a directory (implies `exists`)                    | `[[ -d ]]`     |
+| `readable`    | Readable by the current user (implies `exists`)                 | `[[ -r ]]`     |
+| `writable`    | Writable by the current user (implies `exists`)                 | `[[ -w ]]`     |
+| `executable`  | Executable by the current user (implies `exists`)               | `[[ -x ]]`     |
+| `symlink`     | Path is a symlink                                               | `[[ -L ]]`     |
+| `not_symlink` | Path is not a symlink                                           | `! [[ -L ]]`   |
+
+**Symlinks behave differently across tests.** `under_cwd` follows symlinks via `realpath -m`,
+so a symlink whose target is outside the workspace fails the boundary check even if the link
+itself is inside. The `exists`/`file`/`dir`/`readable`/`writable`/`executable` tests also follow
+symlinks (they check the target, not the link). Only `symlink` and `not_symlink` test the path
+itself without following the link. Combine them deliberately if you mean both, e.g.
+`[under_cwd, file]` requires the resolved target to be a regular file inside the workspace,
+while `[under_cwd, not_symlink, file]` additionally rejects symlinks even when their targets
+would qualify.
+
+### Evaluation order
+
+For each path-typed parameter, the helper runs:
+
+1. **Baseline** -- reject `\n` / `\r` / `\t` in the input, canonicalize `$PWD` and the input.
+2. **Boundary** -- `under_cwd`.
+3. **Existence** -- `exists`, `not_exists`.
+4. **Type** -- `file`, `dir`, `symlink`, `not_symlink`.
+5. **Access** -- `readable`, `writable`, `executable`.
+
+The helper short-circuits on the first failure and reports the failed test name.
+
+### Rules
+
+- `path_tests` only applies to `options` and `arguments`, not `switches`.
+- An empty list is rejected at validation time. Omit the field entirely if you do not want path
+  validation.
+- Mutually exclusive: `exists` and `not_exists`; `file` and `dir`; `symlink` and `not_symlink`.
+- `not_exists` cannot be combined with `file`, `dir`, `readable`, `writable`, `executable`, or
+  `symlink` -- those tests require the path to exist.
+- Unknown test names are rejected at validation time.
+- For variadic arguments the helper runs once per element.
+- Optional parameters are skipped when unset; required parameters are checked after the
+  required-value check.
+
+### Threat-scope implication
+
+A parameter with `path_tests: [under_cwd, ...]` is constrained to the workspace, so the tool can
+credibly claim `read: workspace` or `write: workspace` rather than `read: machine` or
+`write: machine` for that filesystem-touching surface.
+
+### Don't duplicate the wrapped tool's own checks
+
+`path_tests` exists to enforce *boundaries* (workspace containment, control characters, basic
+canonicalization). It is not a place to recreate validation that the wrapped tool already does.
+For most cases, `[under_cwd]` alone is the right answer: it locks the path to the workspace and
+delegates type, existence, and content checks to the tool you're calling.
+
+For example, `git -C <dir>` already produces a clear `fatal: cannot change to '...': Not a
+directory` if the path is wrong. Adding `dir` to `path_tests` would only duplicate that check
+and produce a less informative error than git's. Reach for the longer test lists only when the
+wrapped tool's behavior on the failure mode is genuinely worse than failing at the boundary
+(e.g. silently no-oping, hanging, or modifying state).
+
+### Caveats
+
+- Symlink resolution uses `realpath -m`, which follows symlinks. A symlink inside `$PWD` whose
+  target is outside `$PWD` fails `under_cwd`. This is intentional.
+- The check is not a security boundary against an adversarial filesystem actor (TOCTOU between
+  validation and use is possible).
+- `realpath` is required and is part of GNU coreutils on Linux and modern macOS coreutils. Pure
+  BSD environments are not supported.
 
 ## Lifecycle
 
@@ -462,7 +608,14 @@ The pre script is wrapped in a shell function (`_nerf_pre`). Key points:
 - **Print your own error messages.** The fallback message is generic. Write `echo "error: ..." >&2`
   before `return 1`.
 - **Shell variables set in pre are visible to main.** Functions execute in the caller's scope.
+  Do **not** use `local` -- a `local` declaration limits scope to the function body and the
+  variable will be empty when main runs.
 - **`{{kind.name}}` placeholders work.** Parameters are parsed before pre runs.
+- **`set -e` does NOT abort pre on bare command failure.** Bash suppresses errexit inside any
+  function whose return code is being tested by the caller, and the wrapper invokes pre via
+  `_nerf_pre || _nerf_pre_rc=$?`. Even adding `set -e` inside the function body has no effect
+  per POSIX/bash semantics. **Always check command results explicitly with `if`/`||` and
+  `return 1`.**
 
 Example:
 
@@ -543,7 +696,8 @@ error: nerf-safe-find: token '-exec' is not allowed (matched deny pattern '-exec
 
 ## Dry-run mode
 
-Every generated tool supports `--nerf-dry-run`. When passed as the first argument, the tool runs all
+Every generated tool supports `--nerf-dry-run`. When passed in the flag region (before any
+positional argument), the tool runs all
 validation, guards, pre-hooks, and deny scans as normal, but instead of executing the final command
 it prints what would be run and exits.
 
@@ -565,8 +719,12 @@ $ nerf-find-cwd --nerf-dry-run -exec echo {} \;
 error: nerf-find-cwd: token '-exec' is not allowed (matched deny pattern '-exec')
 ```
 
-`--nerf-dry-run` must be the first token because the parser stops consuming flags at the first
-unrecognized argument.
+`--nerf-dry-run` may appear anywhere in the flag region (before the first positional argument);
+like other declared flags it is recognized in any order. The parser stops consuming flags at the
+first non-flag token, so `--nerf-dry-run` placed after a positional argument is captured into
+that argument (or rejected as an extra) and does not enable dry-run. For tools with
+variadic+allow_flags arguments, the codegen rejects `--nerf-dry-run` tokens inside the variadic
+explicitly to prevent silent dry-run bypass.
 
 ## Generated documentation
 
@@ -606,3 +764,9 @@ Generated skill files follow the same structure formatted as markdown for AI ass
 | `pattern` is a valid regex                                           | options, arguments    |
 | `env` keys match `[A-Z_][A-Z0-9_]*`                                  | env                   |
 | Guard has exactly one of `command` or `script`                       | guards                |
+| `path_tests` is non-empty if present                                 | options, arguments    |
+| `path_tests` entries are known names                                 | options, arguments    |
+| `path_tests` mutual exclusions enforced                              | options, arguments    |
+| `default` must be a string                                           | options               |
+| `default` mutually exclusive with `required`, `repeatable`, `path_tests` | options           |
+| `default` must satisfy `pattern` / `allow` / `deny` if present       | options               |