docs: expand with-watch documentation

Author: kdy1

apps/public-docs/README.md

@@ -23,3 +23,4 @@ pnpm --filter public-docs test
 - `nodeup.mdx`: Public project guide for `nodeup`.
 - `cargo-mono.mdx`: Public project guide for `cargo-mono`.
 - `derun.mdx`: Public project guide for `derun`.
+- `with-watch.mdx`: Public project guide for `with-watch`.

apps/public-docs/docs.json

@@ -46,6 +46,15 @@
           }
         ]
       },
+      {
+        "tab": "With Watch",
+        "groups": [
+          {
+            "group": "Command Rerun Watcher",
+            "pages": ["with-watch"]
+          }
+        ]
+      },
       {
         "tab": "DexDex",
         "groups": [

apps/public-docs/index.mdx

@@ -9,7 +9,7 @@ This site provides a curated, user-facing layer of documentation that complement
 - Read [Getting Started](getting-started) for local setup and editing workflow.
 - See [Projects Overview](projects-overview) for the current public project catalog.
 - Review [Documentation Lifecycle](documentation-lifecycle) for update rules between `docs/` and `apps/public-docs`.
-- Open [Nodeup](nodeup), [Cargo Mono](cargo-mono), and [Derun](derun) from the top navigation for dedicated project guides.
+- Open [Nodeup](nodeup), [Cargo Mono](cargo-mono), [Derun](derun), and [With Watch](with-watch) from the top navigation for dedicated project guides.
 
 ## Scope
 

apps/public-docs/projects-overview.mdx

@@ -7,6 +7,7 @@ This page provides a high-level public catalog of projects in the Delino OSS mon
 - [`cargo-mono`](cargo-mono): Cargo subcommand tooling for Rust monorepo workflows.
 - [`nodeup`](nodeup): Rust-based Node.js runtime manager.
 - [`derun`](derun): Terminal-fidelity run execution and MCP bridge tool.
+- [`with-watch`](with-watch): Command rerun watcher for inferred or explicit filesystem inputs.
 - [`dexdex`](dexdex): Connect RPC-first desktop + server orchestration platform.
 - `mpapp`: Expo React Native mobile app.
 - `devkit`: Next.js micro-app host platform.

apps/public-docs/with-watch.mdx

@@ -0,0 +1,89 @@
+# with-watch
+
+`with-watch` is a Rust-based command rerun watcher that repeats a delegated command when its inferred or explicit filesystem inputs change.
+
+## Why use with-watch
+
+- Keep familiar CLI tools such as `cat`, `cp`, `sed`, and `find`.
+- Let `with-watch` infer watched inputs for common file-oriented commands.
+- Declare explicit inputs with `exec --input` when you want fully predictable reruns.
+
+## Install
+
+Tag contract:
+
+- `with-watch@v<semver>`
+
+Package manager:
+
+- macOS/Linux: `brew install delinoio/tap/with-watch`
+
+Cargo:
+
+```bash
+cargo install with-watch
+```
+
+## Quick start
+
+Rerun a file reader when its input changes:
+
+```bash
+with-watch cat input.txt
+```
+
+Watch the current directory with a safe pathless default:
+
+```bash
+with-watch ls -l
+```
+
+Run a simple shell expression:
+
+```bash
+with-watch --shell 'cat input.txt | grep hello'
+```
+
+Provide explicit inputs for an arbitrary command:
+
+```bash
+with-watch exec --input 'src/**/*.rs' -- cargo test -p with-watch
+```
+
+## Input inference model
+
+- Passthrough mode and `--shell` use built-in command adapters first.
+- Known outputs, inline scripts, and output redirects are filtered out of the watch set.
+- Safe pathless defaults are intentionally narrow: `ls`, `dir`, `vdir`, `du`, and `find`.
+- If `with-watch` cannot infer safe filesystem inputs, it fails instead of guessing.
+
+## When exec --input is required
+
+Some commands do not expose meaningful filesystem inputs on their own. For example, `echo hello` has nothing safe to watch.
+
+In those cases, use `exec --input` to declare the watch set explicitly:
+
+```bash
+with-watch exec --input 'src/**/*.rs' -- cargo test -p with-watch
+```
+
+`with-watch` reruns the delegated command unchanged. It does not inject changed file paths into argv or environment variables.
+
+## Shell support boundaries
+
+- `--shell` supports command-line expressions with `&&`, `||`, and `|`.
+- Input redirects (`<`, `<>`) become watched inputs.
+- Output redirects (`>`, `>>`, `&>`, `&>>`, `>|`) are treated as outputs and filtered from watching.
+- Full shell control-flow is out of scope for v1.
+
+## Rerun behavior
+
+- Default rerun filtering uses content hashes.
+- `--no-hash` switches to metadata-only comparison.
+- Self-mutating commands such as `sed -i.bak -e 's/old/new/' config.txt` refresh their baseline after each run so they do not loop on their own writes.
+- Replace-style writers remain watchable because path inputs subscribe from the nearest existing directory anchor.
+
+## Related pages
+
+- [Projects Overview](projects-overview)
+- [Documentation Lifecycle](documentation-lifecycle)

crates/with-watch/README.md

@@ -2,16 +2,31 @@
 
 `with-watch` reruns a delegated command when its inferred or explicit filesystem inputs change.
 
+## Why use
+
+- Keep familiar POSIX/coreutils-style commands while adding automatic reruns.
+- Let `with-watch` infer watched inputs for common read/write utilities such as `cat`, `cp`, `sed`, and `find`.
+- Fall back to explicit `exec --input` globs when inference would be ambiguous or when the delegated command has no meaningful filesystem inputs.
+
 ## Install
 
 ```sh
 cargo install with-watch
 brew install delinoio/tap/with-watch
 ```
 
-## Examples
+## Command modes
+
+- Passthrough mode: `with-watch [--no-hash] <utility> [args...]`
+- Shell mode: `with-watch [--no-hash] --shell '<expr>'`
+- Explicit-input mode: `with-watch exec [--no-hash] --input <glob>... -- <command> [args...]`
+
+Use passthrough mode for a single delegated command, shell mode for simple command-line expressions that need `&&`, `||`, or `|`, and `exec --input` when you want to declare the watched files yourself.
+
+## Quick start
 
 ```sh
+with-watch cat input.txt
 with-watch cp src.txt dest.txt
 with-watch ls -l
 with-watch --shell 'cat src.txt | grep hello'
@@ -25,3 +40,37 @@ with-watch exec --input 'src/**/*.rs' -- cargo test -p with-watch
 - Known outputs, inline scripts, patterns, and shell output redirects are filtered out of the watch set.
 - Pathless defaults are intentionally narrow: only `ls`, `dir`, `vdir`, `du`, and `find` implicitly watch the current directory.
 - `exec --input` remains the explicit escape hatch when a delegated command has no meaningful filesystem inputs or when fallback inference would be ambiguous.
+
+## When to use exec --input
+
+Use `exec --input` when the delegated command does not read a stable filesystem input by itself, or when you want the watch set to be explicit.
+
+For example, commands like `echo hello` are intentionally rejected because there is nothing safe to watch:
+
+```sh
+with-watch exec --input 'src/**/*.rs' -- cargo test -p with-watch
+```
+
+`with-watch` reruns the delegated command exactly as provided. It does not inject changed paths into argv or environment variables.
+
+## Shell limitations
+
+- `--shell` is for command-line expressions, not shell scripts.
+- Supported operators are `&&`, `||`, and `|`.
+- Input redirects (`<`, `<>`) are treated as watched inputs.
+- Output redirects (`>`, `>>`, `&>`, `&>>`, `>|`) are filtered as outputs and are not watched.
+- Broader shell control-flow remains out of scope for v1.
+
+## Rerun behavior
+
+- The default rerun filter compares content hashes, which avoids reruns from metadata churn alone.
+- `--no-hash` switches the filter to metadata-only comparison.
+- Commands that write excluded outputs such as `cp src.txt dest.txt` should rerun when the source input changes, not when the output file changes.
+- Commands that mutate watched inputs directly, such as `sed -i.bak -e 's/old/new/' config.txt`, refresh their baseline after each run so they do not loop on their own writes.
+- Path-based inputs anchor the watcher at the nearest existing directory so replace-style writers keep producing later external change events.
+
+## Troubleshooting
+
+- `No watch inputs could be inferred from the delegated command`: switch to `with-watch exec --input ... -- <command>`.
+- `--shell cannot be combined with delegated argv or the exec subcommand`: choose exactly one command mode per invocation.
+- `--shell` works only for simple command-line expressions on Unix-like platforms.

docs/apps-public-docs-foundation.md

@@ -15,6 +15,8 @@
 ## Interfaces and Contracts
 - Navigation and page ID contracts in `apps/public-docs/docs.json` must remain stable.
 - Public-facing routes and content groupings must map to canonical docs contracts.
+- Top-level product page IDs currently include `nodeup`, `cargo-mono`, `derun`, `with-watch`, and `dexdex`.
+- The `With Watch` tab must route to the stable page ID `with-watch` and keep the `Command Rerun Watcher` grouping unless contracts are updated together.
 - Breaking navigation changes require explicit migration notes.
 
 ## Storage

docs/crates-with-watch-foundation.md

@@ -17,6 +17,10 @@
 - Root passthrough mode must remain `with-watch [--no-hash] <utility> [args...]`.
 - Shell mode must remain `with-watch [--no-hash] --shell '<expr>'`.
 - `exec` mode must remain `with-watch exec [--no-hash] --input <glob>... -- <command> [args...]`.
+- The CLI must continue to reject mixed modes and empty delegated-command requests with operator-facing guidance.
+- Passthrough and shell modes must infer watch inputs before the first run; if inference does not produce safe filesystem inputs, the command must fail with `exec --input` guidance instead of guessing.
+- `exec --input` must accept repeatable explicit glob/path values, keep the delegated command unchanged, and remain the canonical fallback for otherwise ambiguous or pathless commands.
+- `--no-hash` must remain a global flag that switches rerun filtering from content hashes to metadata-only comparison.
 - Public crate installation must remain `cargo install with-watch`.
 - Publish tag naming must remain `with-watch@v<version>`.
 - Stable internal enums must remain aligned with the current v1 contract:
@@ -36,6 +40,7 @@
 - `exec --input` remains the canonical explicit input contract when inference is insufficient, but command-side side-effect metadata may still be inferred for rerun suppression and logging.
 - Commands marked as `WritesWatchedInputs` must refresh the baseline snapshot after each run and suppress reruns caused only by their own writes while they were executing.
 - Path watch inputs must attach their OS watcher to the nearest existing directory so replace-style writers such as GNU `sed -i` do not orphan follow-up change detection on Linux.
+- Operator-facing documentation must explain the three command modes, the `exec --input` escape hatch, shell support boundaries, and why self-mutating commands do not loop on their own writes.
 - Homebrew installation must consume prebuilt GitHub release archives for `darwin/amd64`, `darwin/arm64`, and `linux/amd64`.
 
 ## Storage
@@ -56,6 +61,7 @@
 - Local validation: `cargo test -p with-watch`
 - Workspace validation baseline: `cargo test --workspace --all-targets`
 - Tests must cover CLI modes, shell parsing, adapter classification, fallback ambiguity handling, snapshot diffing, self-write suppression, and representative rerun flows.
+- Documentation changes should be checked against `cargo run -p with-watch -- --help` and the integration scenarios in `crates/with-watch/tests/cli.rs`.
 - Publishability validation: `cargo publish -p with-watch --dry-run`
 - Release contract checks should align with `.github/workflows/release-with-watch.yml`.
 - Release assets must include standalone binaries (`with-watch-<os>-<arch>[.exe]`) and compressed archives (`with-watch-<os>-<arch>.tar.gz|zip`) for the supported release matrix.

docs/project-public-docs.md

@@ -15,6 +15,7 @@ Provide the Mintlify-based public documentation site for user-facing product and
 ## Cross-Domain Invariants
 - Mintlify navigation IDs and docs structure must stay aligned with documented contracts.
 - User-facing content changes should be versioned alongside relevant contract updates.
+- Public project pages currently exposed in top-level navigation include `nodeup`, `cargo-mono`, `derun`, `with-watch`, and `dexdex`.
 
 ## Change Policy
 - Update this index and `docs/apps-public-docs-foundation.md` in the same change for navigation, runtime, or publishing workflow updates.

docs/project-with-watch.md

@@ -16,10 +16,13 @@ Provide a Rust-based CLI wrapper that reruns delegated shell utilities and arbit
 - Root passthrough mode must remain `with-watch [--no-hash] <utility> [args...]`.
 - Shell mode must remain `with-watch [--no-hash] --shell '<expr>'` and is the supported entrypoint for `&&`, `||`, and `|`.
 - Arbitrary command mode must remain `with-watch exec [--no-hash] --input <glob>... -- <command> [args...]`.
+- The public CLI surface must keep exactly one delegated-command entrypoint per invocation: passthrough argv, `--shell`, or `exec --input`.
 - Default change detection must prefer content hashing, while `--no-hash` must switch the rerun filter to metadata-only comparison.
 - `exec --input` reruns the delegated command unchanged and must not inject changed paths into argv or environment variables.
+- Commands without safe inferred filesystem inputs must fail clearly and direct operators to `with-watch exec --input ...`.
 - Passthrough and shell modes must use adapter-driven input inference that excludes known outputs, scripts, and pattern operands from the watch set.
 - Shell redirects must treat `<` and `<>` targets as watched inputs and `>`, `>>`, `&>`, `&>>`, and `>|` targets as filtered outputs.
+- Shell parsing support is limited to command-line expressions plus `&&`, `||`, and `|`; broader shell control-flow stays out of scope until documented otherwise.
 - Safe pathless default watch roots are limited to the built-in allowlist (`ls`, `dir`, `vdir`, `du`, and `find`).
 - Commands that mutate watched inputs directly must refresh the baseline snapshot after each run and suppress self-triggered reruns caused by their own writes.
 - Path-based watch inputs must anchor watcher subscriptions at the nearest existing directory so replace-style writers keep emitting later external changes.
@@ -29,7 +32,7 @@ Provide a Rust-based CLI wrapper that reruns delegated shell utilities and arbit
 - Homebrew installation must consume prebuilt `with-watch` release archives for `darwin/amd64`, `darwin/arm64`, and `linux/amd64`.
 
 ## Change Policy
-- Update this index and `docs/crates-with-watch-foundation.md` together when CLI shape, watch inference behavior, release automation, side-effect suppression, or storage/logging contracts change.
+- Update this index and `docs/crates-with-watch-foundation.md` together when CLI shape, watch inference behavior, operator guidance, release automation, side-effect suppression, or storage/logging contracts change.
 - Update root `Cargo.toml`, `.github/workflows/release-with-watch.yml`, `scripts/release/update-homebrew.sh`, and `packaging/homebrew/templates/with-watch.rb.tmpl` in the same change when with-watch release tags, artifact names, or package-manager distribution contracts change.
 - Keep root `AGENTS.md` and `crates/AGENTS.md` aligned with ownership and project-ID changes.