Merge pull request #29 from link-foundation/issue-28-9a07df20ebbb

docs: Add PIPES.md with preferred pipe syntax for issue #28

Author: konard

.changeset/pipes-documentation.md

@@ -0,0 +1,12 @@
+---
+'start-command': patch
+---
+
+Add documentation for piping with `$` command
+
+- Created `docs/PIPES.md` with detailed guide on pipe usage
+- Preferred approach: `echo "hi" | $ agent` (pipe TO the $-wrapped command)
+- Alternative approach: `$ 'echo "hi" | agent'` (quoting)
+- Updated `docs/USAGE.md` with brief pipe reference
+- Updated `README.md` with piping examples
+- Updated case study for issue #28 with new recommended approach

README.md

@@ -21,6 +21,29 @@ $ npm test
 $ git status
 ```
 
+### Piping with `$`
+
+When piping data to a command wrapped with `$`, **put `$` on the receiving command**:
+
+```bash
+# Preferred - pipe TO the $-wrapped command
+echo "hi" | $ agent
+
+# Alternative - quote the entire pipeline (more verbose)
+$ 'echo "hi" | agent'
+```
+
+Both approaches work, but piping TO `$` is simpler and requires fewer quotes.
+
+```bash
+# More examples
+cat file.txt | $ processor
+git diff | $ reviewer
+echo "analyze this" | $ agent --verbose
+```
+
+See [docs/PIPES.md](docs/PIPES.md) for detailed guidance on piping, and [docs/USAGE.md](docs/USAGE.md) for general usage.
+
 ### Natural Language Commands (Aliases)
 
 You can also use natural language to execute common commands. The `$` command supports pattern-based substitutions defined in `substitutions.lino`:

docs/PIPES.md

@@ -0,0 +1,243 @@
+# Piping with start-command (`$`)
+
+This document explains how to use pipes with the `$` command effectively.
+
+## Table of Contents
+
+- [Quick Summary](#quick-summary)
+- [The Preferred Way: Pipe TO `$`](#the-preferred-way-pipe-to-)
+- [Alternative: Quoting](#alternative-quoting)
+- [Why This Matters](#why-this-matters)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Summary
+
+When piping data to a command wrapped with `$`, **put `$` on the receiving command**:
+
+```bash
+# Preferred - pipe TO the $-wrapped command
+echo "hi" | $ agent
+
+# Alternative - quote the entire pipeline (more verbose)
+$ 'echo "hi" | agent'
+```
+
+Both approaches work, but piping TO `$` is simpler and requires fewer quotes.
+
+## The Preferred Way: Pipe TO `$`
+
+The cleanest way to use pipes with `$` is to place `$` on the command that **receives** the piped input:
+
+```bash
+# Data flows: echo "hi" -> agent (wrapped with $)
+echo "hi" | $ agent
+```
+
+This works because:
+
+1. The shell creates a pipeline: `echo "hi"` piped to `$ agent`
+2. `$ agent` receives "hi" on stdin
+3. The `$` command wraps `agent`, which processes the input
+
+### Real-World Examples
+
+```bash
+# Pipe text to an AI agent
+echo "Explain this code" | $ agent
+
+# Pipe file contents to a processor
+cat file.txt | $ processor
+
+# Pipe command output to an analyzer
+ls -la | $ analyzer
+
+# Chain multiple commands, wrap the final one
+cat data.json | jq '.items[]' | $ handler
+```
+
+### When to Use This Approach
+
+Use `command | $ target` when:
+
+- You want to pipe data INTO a command that `$` wraps
+- You want the `$` logging and monitoring for the receiving command
+- You prefer minimal quoting
+
+## Alternative: Quoting
+
+You can also wrap the entire pipeline in quotes:
+
+```bash
+# Single quotes preserve the pipe literally
+$ 'echo "hi" | agent'
+
+# The $ command receives the whole pipeline as one argument
+$ 'cat file.txt | grep pattern | wc -l'
+```
+
+### When to Use Quoting
+
+Use quotes when:
+
+- You want `$` to wrap the ENTIRE pipeline (logging all commands)
+- You need the pipeline to run as a single tracked unit
+- You want a single log file for the whole operation
+
+### Quote Types
+
+| Quote Type | Behavior           | Example                |
+| ---------- | ------------------ | ---------------------- |
+| `'single'` | Everything literal | `$ 'echo $HOME \| wc'` |
+| `"double"` | Variables expand   | `$ "echo $HOME \| wc"` |
+
+## Why This Matters
+
+### Shell Parsing Order
+
+When you type a command, the shell parses it **before** any program runs:
+
+```
+Without quotes or positioning:
+    $ echo "hi" | agent
+    └───┬────┘   └──┬──┘
+        │           │
+   Command 1    Command 2
+   ($ echo "hi")   (agent)
+
+   Result: agent receives $ output, not "hi"
+```
+
+The pipe `|` is a shell operator, so the shell splits the command at that point.
+
+### Solution Comparison
+
+```
+Preferred - Pipe TO $:
+    echo "hi" | $ agent
+    └───┬────┘   └──┬──┘
+        │           │
+   Command 1    Command 2
+   (echo "hi")    ($ agent)
+
+   Result: $ agent receives "hi" - correct!
+
+Alternative - Quoting:
+    $ 'echo "hi" | agent'
+    └─────────┬──────────┘
+              │
+        Single command
+        (pipeline runs inside $)
+
+   Result: agent receives "hi" - correct!
+```
+
+## Examples
+
+### Basic Piping
+
+```bash
+# Pipe text to a command
+echo "hello world" | $ processor
+
+# Pipe file contents
+cat config.json | $ validator
+
+# Pipe command output
+git diff | $ reviewer
+```
+
+### Multiple Pipes
+
+```bash
+# $ wraps only the final command
+cat file.txt | grep "error" | $ reporter
+
+# $ wraps the entire pipeline (quoted)
+$ 'cat file.txt | grep "error" | wc -l'
+```
+
+### With Variables
+
+```bash
+# Variable expands before piping (shell handles it)
+echo "$HOME" | $ agent
+
+# Variable preserved literally (single quotes)
+$ 'echo $HOME | wc -c'
+```
+
+### Complex Commands
+
+```bash
+# Process JSON and pipe to handler
+curl -s https://api.example.com/data | jq '.items' | $ handler
+
+# Pipe to a command with arguments
+echo "analyze this" | $ agent --verbose --format json
+```
+
+## Troubleshooting
+
+### Problem: Output goes to wrong place
+
+**Symptom:** Running `$ cmd1 | cmd2` and cmd2 receives unexpected output.
+
+**Cause:** Shell parses `|` before `$` runs, so cmd2 gets `$` output.
+
+**Solutions:**
+
+1. Pipe TO $: `cmd1 | $ cmd2`
+2. Quote: `$ 'cmd1 | cmd2'`
+
+### Problem: Command not receiving stdin
+
+**Symptom:** `echo "data" | $ cmd` but cmd doesn't see the data.
+
+**Check:** Does `cmd` read from stdin? Not all commands do.
+
+**Test:** Try `echo "data" | cmd` without `$` first.
+
+### Problem: Quotes inside quotes
+
+**Symptom:** `$ 'echo "hello 'world'"'` causes errors.
+
+**Solutions:**
+
+```bash
+# Use double quotes with escaping
+$ "echo \"hello 'world'\""
+
+# Or mix quote styles
+echo "hello 'world'" | $ processor
+```
+
+### Problem: Variables not expanding
+
+**Symptom:** `$ 'echo $HOME'` prints literal "$HOME".
+
+**Cause:** Single quotes prevent expansion.
+
+**Solutions:**
+
+```bash
+# Use double quotes (escape the pipe)
+$ "echo $HOME | wc -c"
+
+# Or pipe TO $ (variable expands in source command)
+echo "$HOME" | $ wc -c
+```
+
+## Summary
+
+| Approach  | Syntax             | Best For                    |
+| --------- | ------------------ | --------------------------- |
+| Pipe TO $ | `cmd1 \| $ cmd2`   | Simple piping, less quoting |
+| Quoted    | `$ 'cmd1 \| cmd2'` | Logging entire pipeline     |
+
+The preferred approach is **piping TO `$`** - it's simpler and avoids quote complexity.
+
+## See Also
+
+- [USAGE.md](USAGE.md) - General usage guide
+- [Case Study: Issue #28](case-studies/issue-28/README.md) - Detailed analysis