@juicesharp/rpiv-args 2.0.0 → 2.2.0

package/README.md

@@ -1,247 +1,123 @@
-# rpiv-args
+# @juicesharp/rpiv-args
+
+[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-args.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-args)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 <div align="center">
   <a href="https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-args">
-    <picture>
-      <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-args/docs/cover.png" alt="rpiv-args cover" width="50%">
-    </picture>
+    <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-args/docs/cover.png" alt="Two panels: /skill:deploy api production filling $1 and $2 in a skill body, and a /skill:commit body whose !`git status -s` runs and pastes real git output into the prompt" width="50%">
   </a>
 </div>
 
-Pass arguments to your skills like a shell command. `rpiv-args` adds `$1`, `$ARGUMENTS`, `$@`, `${@:N}`, and `${@:N:L}` placeholders to [Pi Agent](https://github.com/badlogic/pi-mono) skills - write `/skill:deploy api production` and your skill body sees `$1` = `api`, `$2` = `production`. Skills without placeholders are untouched, so installing `rpiv-args` is safe for any existing skill collection.
+Pass arguments to a skill the way you pass them to a shell command.
+`rpiv-args` adds `$1`, `$2`, `$ARGUMENTS` and friends to
+[Pi Agent](https://github.com/badlogic/pi-mono) skill bodies, and runs
+`` !`cmd` `` and ```` ```! ```` blocks so real command output is in the prompt
+before the model reads it. It is for anyone who writes Pi skills and wants to
+parameterize them instead of keeping one hard-coded copy per case.
 
 ## Install
 
-```bash
+```sh
 pi install npm:@juicesharp/rpiv-args
 ```
 
-Or run `/rpiv-setup` if you have `@juicesharp/rpiv-pi` installed.
-
-## Placeholders
-
-| Placeholder | Replaced with | Example |
-|---|---|---|
-| `$1`, `$2`, … | Positional argument (1-indexed) | `/skill:foo a b c` → `$1` = `a`, `$2` = `b` |
-| `$ARGUMENTS` | All arguments as a single string | `/skill:foo a b c` → `a b c` |
-| `$@` | Same as `$ARGUMENTS` | `/skill:foo a b c` → `a b c` |
-| `${@:N}` | Arguments from position N onward | `/skill:foo a b c` → `${@:2}` = `b c` |
-| `${@:N:L}` | L arguments starting at position N | `/skill:foo a b c d` → `${@:2:2}` = `b c` |
-
-**Indexing is 1-based** - `$1` is the first argument, `$2` is the second.
-Out-of-range positions resolve to an empty string. For `${@:N[:L]}`, `N` is
-clamped to `≥ 1` and out-of-range slices yield an empty string.
-
-Multi-word values use shell-style quoting:
-
-```
-/skill:deploy "staging server" --force
-```
-
-→ `$1` = `staging server`, `$2` = `--force`, `$ARGUMENTS` = `staging server --force`
-
-## How it works
-
-rpiv-args intercepts the `input` event (fires before Pi's built-in skill
-expansion). When a skill body contains at least one placeholder, the extension:
-
-1. Parses arguments using shell-style quoting
-2. Substitutes all placeholders in the body
-3. Wraps the result in a `<skill>` block byte-identical to Pi's native format
-4. Appends the raw arguments after the block - matches Pi's standard output so any tool that parses `<skill>` blocks continues to work unchanged
-
-When no placeholders are found in the skill body, the output is byte-identical
-to Pi's built-in expansion - zero behavioral change.
-
-## Writing skills with arguments
-
-### `$ARGUMENTS` vs `$1` - which to use
-
-Use **`$ARGUMENTS`** (or `$@`) when the input is freeform text the LLM should
-interpret naturally:
-
-```yaml
----
-name: fix-issue
-description: Fix a GitHub issue by number or description
----
-
-Fix the following issue: $ARGUMENTS
-```
-
-```
-/skill:fix-issue login page crashes on mobile
-```
-
-→ `Fix the following issue: login page crashes on mobile`
-
-Use **`$1`, `$2`** only for skills with a fixed, structured invocation pattern:
-
-```yaml
----
-name: migrate-component
-description: Migrate a component between frameworks
----
-
-Migrate the $1 component from $2 to $3.
-Preserve all existing behavior and tests.
-```
-
-```
-/skill:migrate-component SearchBar React Vue
-```
-
-→ `Migrate the SearchBar component from React to Vue.`
-
-### Why this matters
-
-If a positional skill receives natural language input:
-
-```
-/skill:migrate-component can you migrate the search bar please
-```
-
-→ `Migrate the can component from you to migrate.` - **broken**.
-
-The LLM is good at interpreting `$ARGUMENTS` as a whole, but positional
-placeholders blindly split on spaces. Use `$ARGUMENTS` unless your skill has
-a strict arg structure.
-
-### `argument-hint` frontmatter
-
-Add an `argument-hint` to document what the skill expects:
-
-```yaml
----
-name: fix-issue
-description: Fix a GitHub issue
-argument-hint: [issue-number-or-description]
----
-```
-
-```yaml
----
-name: migrate-component
-description: Migrate a component between frameworks
-argument-hint: [component] [from] [to]
----
-```
-
-rpiv-args ignores this field - substitution is triggered by placeholders in the body, not the hint.
-
-**Note**: Pi currently surfaces `argument-hint` in autocomplete for prompt
-templates (`commands/*.md`) but **not** for skills (`/skill:<name>`). The
-field is read by Pi but not displayed in the `/skill:` autocomplete UI at
-present - treat it as documentation metadata until upstream Pi exposes it.
+Restart your Pi session.
 
-### Full example
+## Quick start
 
-<details>
-<summary>Deploy skill - SKILL.md, invocation, and the exact text the LLM sees</summary>
+Create `.pi/skills/deploy/SKILL.md` in your project (or
+`~/.pi/agent/skills/deploy/SKILL.md` for a personal skill) and put a
+placeholder in the body:
 
 ```yaml
 ---
 name: deploy
 description: Deploy a service to an environment
-argument-hint: [service] [environment]
 ---
 
 Deploy service $1 to $2.
-
-## Steps
-1. Run the test suite for $1
-2. Build the Docker image
-3. Push to the $2 registry
-4. Verify the deployment
+Current branch: !`git branch --show-current`
 ```
 
+Invoke it with arguments:
+
 ```
 /skill:deploy api production
 ```
 
-→ The LLM receives:
-
-```xml
-<skill name="deploy" location="...">
-Deploy service api to production.
-
-## Steps
-1. Run the test suite for api
-2. Build the Docker image
-3. Push to the production registry
-4. Verify the deployment
-</skill>
-
-api production
-```
-
-Note: the raw arguments (`api production`) are also appended after the
-`</skill>` block - this is Pi's standard behavior and is preserved for
-backward compatibility.
-
-</details>
-
-## Backward compatibility
-
-- Skills **without** placeholders → output is byte-identical to Pi's built-in expansion
-- Skills **with** placeholders → body gets substitution, raw args still appended after block
-- The `argument-hint` frontmatter field is read but not enforced in v1
-
-## Variables and shell execution
-
-Skills can reference runtime context and inline shell command output. These run on **every** invocation, regardless of whether the skill body uses `$N` / `$ARGUMENTS` tokens.
-
-| Syntax | Replaced with |
-|---|---|
-| `${SKILL_DIR}` | Absolute path to the skill's source directory (forward-slash normalized on Windows) |
-| `${SESSION_ID}` | The current Pi session id |
-| `` !`command` `` | Single-line shell command output (no newline crossing) |
-| ` ```!\n…\n``` ` | Multi-line shell program output (newlines preserved) |
-
-### Shell execution semantics
-
-- **Working directory**: every shell command runs in `process.cwd()` (the Pi session's working directory).
-- **Sequential**: commands within one body run one at a time, in source order. `` !`mkdir x` `` then `` !`ls x` `` is safe.
-- **Output truncation**: combined stdout + stderr capped at 50 KB / 2000 lines (tail-truncated — failures at the end of the output survive).
-- **Errors are inlined** (the rest of the body still reaches the LLM):
-  - Timeout → `[Shell error: timed out after Ns]`
-  - Non-zero exit → `[Shell error: exit code N]\n<stderr>`
-- **`shell-timeout` frontmatter** (seconds, default 120 s):
-
-| Value | Effect |
-|---|---|
-| absent | 120 s (default) |
-| positive number (e.g. `5`, `0.5`) | converted to ms |
-| `0` | timer disabled (no timeout) |
-| any non-finite or negative value (string, `NaN`, `.inf`, `-1`, `true`) | silent fallback to default 120 s |
-
-### Cross-platform skill authoring
-
-On Windows, rpiv-args runs each command via `powershell.exe -Command` (PowerShell 5.1+ ships with every supported Windows version). On macOS / Linux it uses `sh -c`. Most POSIX utilities work on both platforms because PowerShell exposes them as aliases:
-
-| POSIX command | Works on Windows via PowerShell alias |
-|---|---|
-| `ls`, `cat`, `pwd`, `cp`, `mv`, `rm`, `mkdir` | ✅ (aliases of `Get-ChildItem`, `Get-Content`, etc.) |
-| `git`, `npm`, `node`, `python` | ✅ (external binaries on PATH) |
-| `grep`, `sed`, `awk`, `find`, `xargs` | ❌ (not aliased — use PowerShell equivalents like `Select-String`) |
-
-> **POSIX flags are NOT translated.** Aliases match command NAMES only. `` !`rm -rf x` `` will FAIL under PowerShell because `Remove-Item` takes `-Recurse -Force`, not `-rf`. For destructive or flag-heavy commands, prefer external binaries (`git`, `npm`, `node`) or write a portable PowerShell-flavored block (`` ```! ``` ``) instead.
-
-**PowerShell cmdlet exit-code quirk**: external commands propagate their exit code via `$LASTEXITCODE`, which PowerShell reflects in its own exit code (so `` !`git status` `` reports failure correctly). However, **cmdlet errors return exit 0 by default**. If a skill relies on a cmdlet's failure to be visible, prepend `$ErrorActionPreference = "Stop"; ` or use `-ErrorAction Stop` per cmdlet. For maximum portability, prefer external commands (`git`, `npm`) over cmdlets where you care about exit codes.
-
-## Limitations
-
-| Limitation | Detail |
-|---|---|
-| **No type validation** | `$1` expecting a file path receives whatever the user types |
-| **No flag parsing** | `--env=prod` is a single positional token, not a parsed flag |
-| **Literal substitution** | Placeholders are replaced even inside code blocks and inline code |
-| **`steer()`/`followUp()` paths** | `session.steer()` / `session.followUp()` bypass the `input` event (see `agent-session.js:861-887`); placeholders are **not** resolved on those paths. Use the primary prompt path for argument-substituted skills. |
-| **No recursive substitution** | A `$ARGUMENTS` value containing `$1` is not re-expanded |
+The model receives the body with `$1` as `api`, `$2` as `production`, the real
+branch name in place of the `git` command, and a trailing
+`Skill input: api production` line marking your raw input.
+
+## What you get
+
+- **Skills take arguments like shell commands** — positionals, `$ARGUMENTS`
+  and `${@:N:L}` slices, split with shell-style quoting, so
+  `/skill:deploy "staging server" --force` puts `staging server` in `$1`.
+- **Command output lands in the prompt, not in a tool call** — inline
+  `` !`git status -s` `` and ```` ```! ```` blocks execute first and the model
+  reads the evidence instead of deciding to go fetch it.
+- **Installing it is a no-op for existing skills** — a body with no
+  placeholder and no shell syntax emits text byte-identical to Pi's built-in
+  expansion, pinned by a regression test.
+- **The model stops reading your argument as a new instruction** — arguments
+  are emitted under an explicit `Skill input:` label and a skill-invocation
+  protocol is prepended to the system prompt every turn.
+- **Runaway commands can't hang the turn or flood the context** — every
+  command is capped at 120 s by default and output is tail-truncated to
+  50 KB / 2000 lines; errors are inlined so the rest of the body still gets
+  through.
+- **Commands run in the order you wrote them** — strictly sequential, never
+  parallel, so `` !`mkdir x` `` then `` !`ls x` `` behaves.
+- **Skill-relative paths keep working** — `${SKILL_DIR}` always resolves to
+  the skill file's own directory, however the skill was installed;
+  `${SESSION_ID}` gives the current session id.
+
+## Configuration
+
+`rpiv-args` reads no config file and no environment variables. The one knob is
+per-skill frontmatter, in the skill's own `SKILL.md`:
+
+| Key | What it does | Default |
+| --- | --- | --- |
+| `shell-timeout` | Ceiling in **seconds** for each `` !`cmd` `` / ```` ```! ```` command in that skill. `0` disables the timer. | `120` |
+
+Shell commands always run in the Pi session's working directory, not the skill
+directory.
+
+## Reference
+
+- [Placeholders and variables](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-args/docs/placeholders.md)
+  — every placeholder and runtime variable, indexing and slicing rules,
+  quoting, and what substitution deliberately does not do.
+- [Authoring skills](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-args/docs/authoring-skills.md)
+  — choosing `$ARGUMENTS` over positionals, empty-argument behaviour,
+  frontmatter, and a worked example with the exact text the model receives.
+- [Shell substitution](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-args/docs/shell-substitution.md)
+  — shell syntax, execution order, timeouts, error strings, output budgets,
+  and Windows / PowerShell authoring.
+- [How it works](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-args/docs/how-it-works.md)
+  — the three event hooks, the transformation pipeline, both emit paths, the
+  skill index, and the paths that are not covered.
+
+## Requirements
+
+- A Pi Agent host. No API key, no model selection, no native modules —
+  nothing here calls a model.
+- **A POSIX shell or PowerShell** for `` !`cmd` `` / ```` ```! ```` blocks.
+  Commands run through `sh -c` on macOS and Linux and `powershell.exe -Command`
+  on Windows, where POSIX-only tools such as `grep`, `sed` and `awk` are not
+  aliased — see
+  [Shell substitution](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-args/docs/shell-substitution.md).
+
+## Related
+
+- [@juicesharp/rpiv-pi](https://www.npmjs.com/package/@juicesharp/rpiv-pi) —
+  the umbrella package. Its `/rpiv-setup` command installs `rpiv-args` along
+  with the rest of the family, and its lane transcript hides the
+  `Skill input:` line from the displayed conversation.
 
 ## License
 
-[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-args.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-args)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-MIT
+MIT — see [LICENSE](LICENSE).

package/docs/authoring-skills.md

@@ -0,0 +1,135 @@
+# Writing skills that take arguments
+
+How to choose between freeform and positional arguments, what the model
+actually receives, and the frontmatter that affects it.
+
+## `$ARGUMENTS` vs `$1` — which to use
+
+Use **`$ARGUMENTS`** (or `$@`) when the input is freeform text the model
+should interpret as a whole:
+
+```yaml
+---
+name: fix-issue
+description: Fix a GitHub issue by number or description
+---
+
+Fix the following issue: $ARGUMENTS
+```
+
+```
+/skill:fix-issue login page crashes on mobile
+```
+
+→ `Fix the following issue: login page crashes on mobile`
+
+Use **`$1`, `$2`** only when the skill has a fixed, structured invocation:
+
+```yaml
+---
+name: migrate-component
+description: Migrate a component between frameworks
+---
+
+Migrate the $1 component from $2 to $3.
+Preserve all existing behavior and tests.
+```
+
+```
+/skill:migrate-component SearchBar React Vue
+```
+
+→ `Migrate the SearchBar component from React to Vue.`
+
+### Why the choice matters
+
+Positional placeholders split blindly on whitespace. If a positional skill
+receives natural language:
+
+```
+/skill:migrate-component can you migrate the search bar please
+```
+
+→ `Migrate the can component from you to migrate.` — broken.
+
+Prefer `$ARGUMENTS` unless the invocation really is structured. When you do
+use positionals, document the shape in `description` and expect users to quote
+multi-word values (`/skill:deploy "staging server" production`).
+
+## Empty arguments
+
+When a skill is invoked with no arguments, the emitted text ends at
+`</skill>` — no trailing argument text and no `Skill input:` line at all. A
+skill that has an "if no input was given" branch can rely on that absence.
+
+## Worked example
+
+```yaml
+---
+name: deploy
+description: Deploy a service to an environment
+---
+
+Deploy service $1 to $2.
+
+## Steps
+1. Run the test suite for $1
+2. Build the Docker image
+3. Push to the $2 registry
+4. Verify the deployment
+```
+
+```
+/skill:deploy api production
+```
+
+The model receives:
+
+```
+<skill name="deploy" location="/path/to/deploy/SKILL.md">
+References are relative to /path/to/deploy.
+
+Deploy service api to production.
+
+## Steps
+1. Run the test suite for api
+2. Build the Docker image
+3. Push to the production registry
+4. Verify the deployment
+</skill>
+
+Skill input: api production
+```
+
+The `Skill input:` trailer carries the **raw**, un-substituted argument string.
+It appears only when the body contains argument placeholders; a body with no
+placeholders gets the bare argument string after the block instead, exactly as
+Pi's built-in expansion emits it.
+
+## Frontmatter
+
+| Key | Effect |
+| --- | --- |
+| `shell-timeout` | Per-skill ceiling in seconds for `` !`cmd` `` / ```` ```! ```` execution. See [shell-substitution.md](shell-substitution.md). |
+| `argument-hint` | Not read by `rpiv-args`. Substitution is triggered by placeholders in the body, never by a hint. Treat it as documentation for readers of your skill. |
+
+There is no `arguments:` key and no required-argument enforcement: a skill
+cannot declare that `$1` is mandatory, and nothing fails when it is missing —
+the placeholder simply resolves to an empty string.
+
+## Skill-relative assets
+
+Use `${SKILL_DIR}` to point at files shipped next to the skill:
+
+```md
+Follow the checklist in ${SKILL_DIR}/checklist.md before editing anything.
+```
+
+`${SKILL_DIR}` resolves to the directory of the skill file itself, so the same
+skill works whether it was loaded from a skills directory, a plugin, or
+another extension's `pi.skills` manifest.
+
+## New skills are picked up on reload
+
+The skill index is built once per session and cached. After adding or renaming
+a skill file, run `/reload` (or start a new session) so the index is rebuilt.

package/docs/how-it-works.md

@@ -0,0 +1,97 @@
+# How rpiv-args works
+
+The internals: which Pi events the extension hooks, how a `/skill:` message is
+transformed, what exactly it emits, and which paths it does not cover.
+
+## Surface
+
+`rpiv-args` registers no slash commands, no tools and no keybindings. Its
+entire surface is three Pi event hooks.
+
+| Hook | What it does |
+| --- | --- |
+| `input` | Intercepts `/skill:<name> <args>` before Pi's built-in expander, runs the pipeline, and returns transformed text |
+| `before_agent_start` | Prepends a `## Skill invocation protocol (CRITICAL)` section to the system prompt, every turn |
+| `session_start` | Rebuilds the skill index when the session reason is `reload` or `startup` |
+
+## Input dispatch
+
+The `input` handler takes one of four branches:
+
+1. Text already starts with `<skill ` → passed through untouched. This is the
+   re-entrancy guard: text transformed by this or any other extension is not
+   reprocessed.
+2. Text does not start with `/skill:` → passed through untouched.
+3. The skill name is unknown, or the skill file cannot be read → passed
+   through, so Pi emits its own handling or error.
+4. Known skill → transformed.
+
+## Pipeline
+
+For a known skill, in this order:
+
+1. Read the skill file and split frontmatter from body.
+2. Record whether the body contains any argument placeholder — this flag is
+   captured **before** substitution and decides the emit path.
+3. If it does, tokenise the argument string shell-style and substitute
+   `$N` / `${@:N[:L]}` / `$ARGUMENTS` / `$@`.
+4. Substitute `${SKILL_DIR}` and `${SESSION_ID}` — always, on both paths.
+5. Execute `` !`cmd` `` and ```` ```! ```` blocks — always, on both paths.
+6. Wrap the result in a `<skill name="…" location="…">` block byte-identical
+   to Pi's native format, and append the trailer.
+
+## Emit paths
+
+| Body | Emitted after `</skill>` |
+| --- | --- |
+| No argument placeholders | Blank line, then the raw argument string — the suffix is byte-identical to Pi's built-in expansion |
+| Has argument placeholders | Blank line, then `Skill input: <raw args>` |
+| Either, invoked with no arguments | Nothing; the text ends at `</skill>` |
+
+A body with no argument placeholders, no `${…}` variables and no shell syntax
+emits bytes identical to Pi's built-in expansion; that is pinned by a
+regression test, and it is what makes installing the extension a no-op for
+existing skill collections. Bodies that do use variables or shell syntax still
+get steps 4 and 5 on this path — `hadTokens` governs the trailer only, not the
+substitution pipeline.
+
+The trailer always carries the **raw**, un-substituted argument string. If a
+user types `${SKILL_DIR}` as an argument, the occurrence woven into the body
+is substituted while the trailer keeps the literal text.
+
+## The `Skill input:` trailer and the protocol block
+
+Bare trailing text after `</skill>` reads to a model like a second, separate
+instruction — especially when the argument is phrased as an imperative
+("delete the old migrations"). Two things fix that together:
+
+- the labelled `Skill input:` trailer on the placeholder path, and
+- the `## Skill invocation protocol (CRITICAL)` section prepended to the
+  system prompt on every turn, which tells the model that text after
+  `</skill>` is argument input to the skill, never a separate command, and
+  that the same value may also appear substituted inside the body.
+
+The label string is a cross-package contract: `@juicesharp/rpiv-pi`'s lane
+transcript and `@juicesharp/rpiv-warp`'s toast summariser both strip
+`Skill input:` for display using a literal regex. Changing the label requires
+changing them too.
+
+## Skill index
+
+The name → file-path index is built lazily from Pi's command registry the
+first time a `/skill:` message arrives, then memoised for the session. It is
+sourced from the registry rather than from a filesystem walk, so it also
+recognises skills declared by another extension's `pi.skills` manifest.
+
+That also means `sendUserMessage("/skill:… ")` calls made programmatically by
+other extensions are expanded: those bypass Pi's built-in expander, leaving
+`rpiv-args` as the only expander on that path.
+
+The index is invalidated on `session_start` with reason `reload` or `startup`.
+Other reasons — resuming a session, for example — keep the cached index.
+
+## Paths not covered
+
+`session.steer()` and `session.followUp()` do not go through the `input`
+event, so placeholders are not resolved on those paths. Use the primary
+prompt path for argument-substituted skills.

package/docs/placeholders.md

@@ -0,0 +1,86 @@
+# Placeholders and variables
+
+Complete reference for every token `rpiv-args` substitutes into a skill body:
+the positional argument family, the slice forms, and the always-on runtime
+variables.
+
+## Argument placeholders
+
+Substitution runs only when the skill body contains at least one of these
+tokens. A body with none of them is passed through untouched.
+
+| Placeholder | Replaced with | Example (`/skill:foo a b c d`) |
+| --- | --- | --- |
+| `$1`, `$2`, … `$N` | The Nth argument, 1-indexed | `$2` → `b` |
+| `$ARGUMENTS` | All arguments joined by a single space | `a b c d` |
+| `$@` | Identical to `$ARGUMENTS` | `a b c d` |
+| `${@:N}` | Arguments from position N onward | `${@:2}` → `b c d` |
+| `${@:N:L}` | L arguments starting at position N | `${@:2:2}` → `b c` |
+
+### Indexing rules
+
+- Indexing is **1-based**: `$1` is the first argument.
+- An out-of-range position resolves to an **empty string**, not to a literal
+  `$3`. `/skill:foo a` leaves `$2` as `""`.
+- Digits are matched greedily: `$11` is the eleventh argument, never `$1`
+  followed by a literal `1`.
+- In `${@:N}` and `${@:N:L}`, `N` is clamped to `≥ 1`, so `${@:0}` returns the
+  whole argument list. A slice that starts past the end of the list produces
+  an empty slice, which joins to an empty string.
+
+### Substitution order
+
+Replacements are applied in a fixed order: `$N` first, then `${@:N[:L]}`, then
+`$ARGUMENTS`, then `$@`.
+
+The order is load-bearing. Because `$N` runs first, an argument value that
+itself contains `$1` is **not** re-expanded when it lands in the body via
+`$ARGUMENTS` or a slice. There is no recursive substitution.
+
+## Argument tokenisation
+
+The argument string after `/skill:<name> ` is split shell-style:
+
+- Splits on spaces **and** tabs; runs of whitespace collapse.
+- Both `"` and `'` quote a multi-word value.
+- Quote styles can mix inside one token: `"a b"c` produces the single
+  argument `a bc`.
+- An unmatched quote flushes what it has instead of raising an error.
+
+```
+/skill:deploy "staging server" --force
+```
+
+→ `$1` = `staging server`, `$2` = `--force`, `$ARGUMENTS` = `staging server --force`
+
+Arguments are always plain strings. There is no type validation and no flag
+parsing — `--env=prod` is one positional token, not a parsed option.
+
+## Runtime variables
+
+These are substituted on **every** invocation, whether or not the body uses
+argument placeholders.
+
+| Variable | Replaced with |
+| --- | --- |
+| `${SKILL_DIR}` | Absolute path of the directory containing the skill file |
+| `${SESSION_ID}` | The current Pi session id |
+
+`${SKILL_DIR}` is always `dirname()` of the skill file itself, so a skill can
+reference a sibling asset (`${SKILL_DIR}/template.md`) regardless of how the
+skill was installed — filesystem skill directory, plugin, or a skill declared
+by another extension's `pi.skills` manifest. On Windows the value is
+normalised to forward slashes; on POSIX the path is preserved byte for byte,
+including literal backslashes.
+
+Unknown `${FOO}` placeholders are left in the body untouched.
+
+## What substitution does not do
+
+| Limit | Detail |
+| --- | --- |
+| No type validation | `$1` receives whatever the user typed; a skill expecting a path can get a sentence |
+| No flag parsing | `--force` is a positional token like any other |
+| Literal substitution | Placeholders are replaced inside fenced code blocks and inline code too — there is no fence awareness |
+| No recursive substitution | A value containing `$1` is never re-expanded |
+| Body-token trigger only | There is no `arguments:` frontmatter key; substitution keys off tokens present in the body |

package/docs/shell-substitution.md

@@ -0,0 +1,105 @@
+# Shell substitution
+
+Complete reference for `` !`command` `` and ```` ```! ```` blocks in skill
+bodies: syntax, execution order, timeouts, error text, output budgets, and
+cross-platform authoring.
+
+## Syntax
+
+| Form | Behaviour |
+| --- | --- |
+| `` !`command` `` | Inline. Single line only — the pattern never crosses a newline. Requires at least one character between the backticks, so a literal empty `` !`` `` in prose is left verbatim and never executed. |
+| ```` ```!\n…\n``` ```` | Block. Multi-line; newlines are preserved and the whole block is handed to the shell as one program. |
+
+Both forms run on **every** invocation of the skill, whether or not the body
+uses `$N` / `$ARGUMENTS` placeholders. The command's output replaces the
+`` !`…` `` or fence in the body before the model sees anything.
+
+## Execution semantics
+
+- **Working directory** — every command runs in `process.cwd()`, the Pi
+  session's working directory. Not the skill directory. Use `${SKILL_DIR}` if
+  you need a skill-relative path.
+- **Sequential** — commands in one body run one at a time, in source order,
+  never in parallel. `` !`mkdir x` `` followed by `` !`ls x` `` is safe.
+- **Blocks before inlines** — fenced blocks execute first and their output is
+  masked while the inline pass runs, so block stdout that happens to contain
+  `` !`something` `` is never re-executed.
+- **Shell** — `sh -c` on macOS and Linux, `powershell.exe -Command` on
+  Windows.
+
+## Timeouts
+
+`shell-timeout` in the skill's own frontmatter sets the ceiling, in **seconds**,
+for every command in that skill.
+
+```yaml
+---
+name: commit
+description: Draft a commit message from the working tree
+shell-timeout: 30
+---
+```
+
+| Value | Effect |
+| --- | --- |
+| absent | 120 s (the default) |
+| positive number (`5`, `0.5`) | Converted to milliseconds; sub-second values are honoured |
+| `0` | Timer disabled — no timeout |
+| negative, string, `true`, `.nan`, `.inf` | Silent fallback to 120 s |
+
+A timed-out command is reported as `[Shell error: timed out after Ns]`. The
+displayed seconds value is floored at `1`, so a `shell-timeout: 0.5` timeout
+still reads `after 1s`.
+
+## Errors and output budget
+
+Errors are inlined into the body, so the rest of the skill still reaches the
+model:
+
+| Situation | Text substituted into the body |
+| --- | --- |
+| Timeout | `[Shell error: timed out after Ns]` |
+| Non-zero exit | `[Shell error: exit code N]` followed by the command's stderr |
+| Success with stderr output | stdout, then `[stderr]` on its own line, then stderr |
+
+Timeout wins over exit code: a killed command reports the timeout message even
+if it also produced a non-zero code.
+
+Output is capped at **50 KB / 2000 lines**, tail-truncated — the *end* of the
+output survives, which is where failures usually appear. When truncation
+happens a footer is appended: `[truncated: hit 2000 lines]` or
+`[truncated: hit 50.0KB]`. The cap applies to the non-zero-exit path too, so
+a multi-megabyte stderr from a failed `` !`npm test` `` cannot blow past the
+budget.
+
+## Trust model
+
+Substitution order is arguments → variables → shell. An argument that contains
+`` !`echo hi` `` and lands in the body through `$ARGUMENTS` will therefore be
+executed. This is deliberate: skill bodies and the local user are trusted, and
+a skill author who interpolates arguments is interpolating into a program.
+Treat `/skill:` invocations with the same trust you give your own shell.
+
+## Cross-platform authoring
+
+On Windows each command runs through `powershell.exe -Command`; on macOS and
+Linux through `sh -c`. Many POSIX utilities work on both because PowerShell
+exposes them as aliases:
+
+| POSIX command | On Windows |
+| --- | --- |
+| `ls`, `cat`, `pwd`, `cp`, `mv`, `rm`, `mkdir` | Works — PowerShell aliases of `Get-ChildItem`, `Get-Content`, etc. |
+| `git`, `npm`, `node`, `python` | Works — external binaries on `PATH` |
+| `grep`, `sed`, `awk`, `find`, `xargs` | Not aliased — use PowerShell equivalents such as `Select-String` |
+
+**POSIX flags are not translated.** Aliases match command *names* only.
+`` !`rm -rf x` `` fails under PowerShell, which expects `-Recurse -Force`. For
+flag-heavy or destructive commands prefer external binaries (`git`, `npm`,
+`node`) or write a PowerShell-flavoured ```` ```! ```` block.
+
+**Exit-code quirk.** External commands propagate their exit code, so
+`` !`git status` `` reports failure correctly. PowerShell *cmdlet* errors
+return exit 0 by default. If a skill depends on a cmdlet failure being
+visible, prepend `$ErrorActionPreference = "Stop"; ` or pass
+`-ErrorAction Stop` per cmdlet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-args",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Pi extension. Shell-style $1 / $ARGUMENTS placeholders and !`cmd` / ```! shell substitution, expanded into your Pi skills at invocation.",
   "keywords": [
     "pi-package",
@@ -34,6 +34,10 @@
   "files": [
     "index.ts",
     "args.ts",
+    "docs/",
+    "!docs/*.png",
+    "!docs/*.jpg",
+    "!docs/*.svg",
     "README.md",
     "LICENSE"
   ],