feat: add PURL copy semantics

.changeset/calm-spoons-copy.md

@@ -0,0 +1,5 @@
+---
+'vlurp': minor
+---
+
+Add `vlurp SOURCE... DEST` copying with `pkg:github` PURL sources and glob selection inside `#subpath`. Copies now support familiar basename semantics, multiple remote sources, embedded refs, destination-relative lineage, vlurpfile pin/upgrade integration, and traversal-safe preflight planning. Repeatable `--glob` and case-insensitive `--iglob` patterns filter files beneath cp sources, and existing presets compose with the new interface. Repository shorthand, presets, and `--filter` remain fully supported.

README.md

@@ -17,42 +17,86 @@ npm install -g vlurp
 or run directly:
 
 ```sh
-npx vlurp <user>/<repo>
+npx vlurp mattpocock/skills --preset skills
 ```
 
 ## Quick start
 
-Fetch a repo's Claude config:
+The easy case is repository shorthand. Fetch the useful skill files from a repository with a maintained preset:
 
+```sh
+vlurp mattpocock/skills --preset skills
+```
+
+This writes the selected repository content beneath `./mattpocock/skills`. Pin it to a commit when you want a reproducible fetch:
+
+```sh
+vlurp mattpocock/skills --preset skills --ref 2ab9580
+```
+
+Use `-d` to choose an output root, `--as` to give the fetched directory a specific name, or `--filter` for repository-relative patterns:
+
+```sh
+vlurp mattpocock/skills -d ./vendor --preset skills
+vlurp mattpocock/skills -d ./skills --as writing --filter 'skills/in-progress/writing-*'
 ```
-$ vlurp eyaltoledano/claude-task-master -d ./vlurp
 
-  eyaltoledano/claude-task-master@HEAD
-  2 files
-  ./vlurp/eyaltoledano/claude-task-master/
+When you need exact remote sources and `cp` placement, use PURL operands. This copies matching directories directly into `./skills/`:
+
 ```
+$ vlurp 'pkg:github/mattpocock/skills#skills/in-progress/writing-*' ./skills/
 
-Fetch skill files pinned to a commit, flattened into a named directory:
+  ./skills/writing-beats/
+  ./skills/writing-fragments/
+  ./skills/writing-shape/
+```
 
+Embed the ref in the PURL to pin the same copy:
+
+```
+$ vlurp 'pkg:github/mattpocock/skills@2ab9580#skills/in-progress/writing-*' ./skills/
 ```
-$ vlurp obra/superpowers -d .claude/skills --preset skills --ref e4f5a6b
 
-  obra/superpowers@e4f5a6b
-  22 files (preset: skills)
-  .claude/skills/obra/superpowers/
+The command follows familiar `cp SOURCE... DEST` rules. A selected directory or file is copied by basename into an existing destination directory. If a single source is copied to a missing destination, that destination becomes the copy.
+
+Copy multiple exact sources:
+
+```sh
+vlurp \
+  'pkg:github/anthropics/skills@main#skills/pdf' \
+  'pkg:github/anthropics/skills@main#skills/slides' \
+  ./skills/
 ```
 
-Fetch a specific directory from deep inside a repo:
+## Presets
+
+Presets are a first-class way to fetch common repository structures without spelling out globs. They work with both repository shorthand and the cp-style interface:
 
+```sh
+vlurp obra/superpowers --preset skills -d ./.claude/skills --ref e4f5a6b
+vlurp eyaltoledano/claude-task-master --preset claude -d ./config
+vlurp 'pkg:github/obra/superpowers' ./.claude/skills --preset skills
 ```
-$ vlurp whilp/dotfiles -d .claude/skills \
-    --filter ".claude/skills/duckdb-json/**" --as duckdb
 
-  whilp/dotfiles@HEAD
-  3 files
-  .claude/skills/duckdb/
+| Preset | Selects |
+|--------|---------|
+| `claude` | `.claude/**`, `CLAUDE.md` |
+| `skills` | `skills/**`, `SKILL.md`, Markdown support files |
+| `agents` | `agents/**`, `commands/**`, Markdown support files |
+| `docs` | Markdown documentation excluding boilerplate |
+| `all-md` | All Markdown files |
+| `minimal` | Only `.claude/**` and `CLAUDE.md` |
+
+With cp-style operands, a preset filters the files beneath each selected source without changing where that source is placed. Add `--glob` or `--iglob` to refine a preset; explicit patterns are applied after the preset.
+
+```sh
+vlurp 'pkg:github/obra/superpowers#skills' ./skills \
+  --preset skills \
+  --glob '!**/experimental/**'
 ```
 
+`--glob` is case-sensitive and `--iglob` is case-insensitive. Both are repeatable. A leading `!` excludes matches. If any positive pattern is present, unmatched files are excluded; with exclusion-only patterns, unmatched files remain included.
+
 Check that nothing has been modified since you fetched:
 
 ```
@@ -109,17 +153,13 @@ Process multiple repos from a `.vlurpfile`:
 # .vlurpfile
 
 # Official Anthropic skills
-vlurp anthropics/skills -d ./vlurp --filter "skills/**" --filter "template/**"
+vlurp 'pkg:github/anthropics/skills@b7c8d9e#skills/*' ./skills/
 
 # obra/superpowers -- Core agent patterns
-vlurp obra/superpowers -d ./vlurp --filter "skills/**" --filter ".claude/**"
-
-# DuckDB skills from assorted dotfiles
-vlurp whilp/dotfiles -d ./vlurp --filter ".claude/skills/duckdb-json/**"
-vlurp PovertyAction/ipa-research-data-science-hub -d ./vlurp --filter ".claude/skills/duckdb/**"
+vlurp obra/superpowers --preset skills -d ./skills --ref e4f5a6b
 
 # Microsoft Amplifier -- multi-agent framework
-vlurp microsoft/amplifier -d ./vlurp --filter "**/*.md"
+vlurp 'pkg:github/microsoft/amplifier@4a5b6c7#**/*.md' ./docs/
 ```
 
 ```
@@ -129,7 +169,10 @@ $ vlurp batch .vlurpfile
 ## Commands
 
 ```
-vlurp <source>                       Fetch from a GitHub repo or gist
+vlurp REPOSITORY [options]           Fetch a repository using shorthand
+vlurp REPOSITORY --preset NAME       Fetch using a named selection preset
+vlurp SOURCE... DEST                 Copy precise PURL sources into local files
+vlurp SOURCE... DEST --preset NAME   Copy PURL sources using a preset
 vlurp batch <vlurpfile>              Process a .vlurpfile (batch fetch)
 vlurp verify <path>                  Check file integrity against lineage
 vlurp pin [source]                   Pin sources to current upstream HEAD
@@ -144,34 +187,27 @@ vlurp catalog-diff [old] [new]       Compare catalog snapshots
 ## Flags
 
 ```
--d <dir>              Root output directory
---ref <sha|tag>       Pin to a git ref (commit, tag, branch)
---as <name>           Flatten output into named directory
---preset <name>       Use a preset filter set
---filter <glob>       Glob pattern for file matching (repeatable)
---auto                Auto-detect repo structure
+-d <dir>              Root output directory for repository selection mode
+--ref <sha|tag>       Pin a repository-mode fetch to a Git ref
+--as <name>           Override its output directory name
+--preset <name>       Apply a maintained named selection preset
+--glob <pattern>      Apply a case-sensitive cp transfer pattern
+--iglob <pattern>     Apply a case-insensitive cp transfer pattern
+--filter <glob>       Add repository-mode selection patterns
+--auto                Detect a suitable repository preset
 --dry-run, -n         Preview without writing
 --force, -f           Overwrite without prompting
 --json                Machine-readable output (catalog-diff)
 --vlurpfile <path>    Explicit .vlurpfile path (upgrade)
 ```
 
-## Presets
-
-```
-claude      .claude/**, CLAUDE.md
-skills      skills/**, SKILL.md, **/*.md
-agents      agents/**, commands/**, **/*.md
-docs        **/*.md (excluding boilerplate)
-all-md      **/*.md
-minimal     .claude/**, CLAUDE.md only
-```
+PURL operands determine remote sources and local placement. `--preset`, `--glob`, and `--iglob` determine the files transferred beneath those sources. Repository shorthand with `--preset` or `--filter` remains supported.
 
 ## Feature guides
 
 | Guide | Covers |
 |-------|--------|
-| **[Fetching & Filtering](doc/fetch.md)** | Sources, globs, presets, `--ref`, `--as`, `--auto` |
+| **[Fetching and Copying](doc/fetch.md)** | Repository shorthand, presets, PURL sources, refs, and cp semantics |
 | **[The .vlurpfile](doc/vlurpfile.md)** | Batch processing, manifest format, intent vs reality |
 | **[Supply Chain Security](doc/supply-chain.md)** | Lineage, verify, pin, scan, threat model |
 | **[Upgrades & Change Detection](doc/upgrade.md)** | outdated, diff, upgrade, catalog, catalog-diff |