@aefree/pi-plastic 0.4.0 → 0.5.1

package/skills/_shared/references/conventional-commits.md

@@ -1,198 +1,198 @@
-# Conventional Commits
-
-This reference file documents the conventional commit format used across the project.
-
----
-
-## Format
-
-```
-<type>(<scope>): <subject>
-
-[optional body]
-
-[optional footer]
-```
-
----
-
-## Types
-
-| Type | Description | Example |
-|------|-------------|---------|
-| **feat** | New feature | `feat(auth): add OAuth login` |
-| **fix** | Bug fix | `fix(cart): calculate tax correctly` |
-| **refactor** | Code restructuring (no behavior change) | `refactor(api): extract service layer` |
-| **perf** | Performance improvement | `perf(query): optimize user lookup` |
-| **test** | Adding or updating tests | `test(auth): add login edge cases` |
-| **docs** | Documentation changes | `docs(readme): update installation steps` |
-| **style** | Code style changes (formatting, etc.) | `style(lint): fix indentation` |
-| **chore** | Build process or auxiliary tool changes | `chore(deps): update to Rails 7.1` |
-| **ci** | CI/CD configuration changes | `ci(github): add test workflow` |
-
----
-
-## Scope
-
-The scope is optional but recommended. It specifies which part of the codebase was affected:
-
-**Examples:**
-- `feat(player): add dash mechanic`
-- `fix(inventory): prevent negative quantities`
-- `refactor(ui): simplify menu navigation`
-- `perf(rendering): batch sprite draws`
-
-**Guidelines:**
-- Use lowercase
-- Be specific but concise
-- Match your module/component names
-- Omit if change is global
-
----
-
-## Subject
-
-The subject contains a succinct description of the change:
-
-- **Use imperative mood:** "add" not "added" or "adds"
-- **Don't capitalize first letter:** "add feature" not "Add feature"
-- **No period at the end:** "fix bug" not "fix bug."
-- **Limit to 50 characters**
-
-**Good examples:**
-- `feat(auth): add password reset flow`
-- `fix(api): handle null responses`
-- `refactor(utils): extract string helpers`
-
-**Bad examples:**
-- `feat(auth): Added password reset flow` (not imperative)
-- `feat(auth): Add Password Reset Flow` (capitalized)
-- `feat(auth): add password reset flow.` (period at end)
-
----
-
-## Body (Optional)
-
-Use the body to explain **what** and **why**, not **how**:
-
-```
-feat(player): add dash mechanic
-
-Adds a dash ability to the player character for enhanced mobility.
-Dash has 1-second cooldown and consumes 10 stamina.
-
-Closes #42
-```
-
-**Guidelines:**
-- Wrap at 72 characters
-- Separate from subject with blank line
-- Focus on context and reasoning
-- Link to issues if applicable
-
----
-
-## Footer (Optional)
-
-Use footer for metadata:
-
-**Breaking changes:**
-```
-feat(api)!: change authentication endpoint
-
-BREAKING CHANGE: /api/login now requires email instead of username
-```
-
-**Issue references:**
-```
-fix(cart): calculate tax correctly
-
-Fixes #123
-Closes #124
-Related to #125
-```
-
-**Attribution:**
-```
-feat(dashboard): add analytics widget
-
-Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
-```
-
----
-
-## Attribution Footer
-
-Add a simple attribution line in the footer when needed:
-
-```
-feat(feature): implement new capability
-
-[Body explaining the change]
-
-Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
-```
-
----
-
-## Examples
-
-### Simple Feature
-```
-feat(player): add jump mechanic
-```
-
-### Bug Fix with Context
-```
-fix(inventory): prevent item duplication
-
-Items were duplicating when rapidly clicking the pickup button.
-Added debounce logic to prevent double-processing.
-
-Fixes #156
-```
-
-### Refactor with Explanation
-```
-refactor(rendering): extract camera controller
-
-Moved camera logic from PlayerController to dedicated CameraController
-for better separation of concerns and reusability.
-```
-
-### Performance Improvement
-```
-perf(physics): optimize collision detection
-
-Changed from O(n²) all-pairs check to spatial hashing.
-Reduces frame time by ~15ms with 100+ objects.
-```
-
-### Attribution Example
-```
-feat(multiplayer): add lobby system
-
-Implements matchmaking lobby with room creation, joining, and ready-up.
-Uses WebSocket for real-time updates.
-
-Closes #89
-
-Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
-```
-
----
-
-## Usage in Skills
-
-**Reference this file when:**
-- Creating commits (Git or Plastic)
-- Generating commit messages
-- Validating commit format
-- Writing PR/code review descriptions
-
-**Load this file:**
-```markdown
-Load conventional commit format from ../../_shared/references/conventional-commits.md
-```
-
-Then format all commits according to this standard.
+# Conventional Commits
+
+This reference file documents the conventional commit format used across the project.
+
+---
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+---
+
+## Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **feat** | New feature | `feat(auth): add OAuth login` |
+| **fix** | Bug fix | `fix(cart): calculate tax correctly` |
+| **refactor** | Code restructuring (no behavior change) | `refactor(api): extract service layer` |
+| **perf** | Performance improvement | `perf(query): optimize user lookup` |
+| **test** | Adding or updating tests | `test(auth): add login edge cases` |
+| **docs** | Documentation changes | `docs(readme): update installation steps` |
+| **style** | Code style changes (formatting, etc.) | `style(lint): fix indentation` |
+| **chore** | Build process or auxiliary tool changes | `chore(deps): update to Rails 7.1` |
+| **ci** | CI/CD configuration changes | `ci(github): add test workflow` |
+
+---
+
+## Scope
+
+The scope is optional but recommended. It specifies which part of the codebase was affected:
+
+**Examples:**
+- `feat(player): add dash mechanic`
+- `fix(inventory): prevent negative quantities`
+- `refactor(ui): simplify menu navigation`
+- `perf(rendering): batch sprite draws`
+
+**Guidelines:**
+- Use lowercase
+- Be specific but concise
+- Match your module/component names
+- Omit if change is global
+
+---
+
+## Subject
+
+The subject contains a succinct description of the change:
+
+- **Use imperative mood:** "add" not "added" or "adds"
+- **Don't capitalize first letter:** "add feature" not "Add feature"
+- **No period at the end:** "fix bug" not "fix bug."
+- **Limit to 50 characters**
+
+**Good examples:**
+- `feat(auth): add password reset flow`
+- `fix(api): handle null responses`
+- `refactor(utils): extract string helpers`
+
+**Bad examples:**
+- `feat(auth): Added password reset flow` (not imperative)
+- `feat(auth): Add Password Reset Flow` (capitalized)
+- `feat(auth): add password reset flow.` (period at end)
+
+---
+
+## Body (Optional)
+
+Use the body to explain **what** and **why**, not **how**:
+
+```
+feat(player): add dash mechanic
+
+Adds a dash ability to the player character for enhanced mobility.
+Dash has 1-second cooldown and consumes 10 stamina.
+
+Closes #42
+```
+
+**Guidelines:**
+- Wrap at 72 characters
+- Separate from subject with blank line
+- Focus on context and reasoning
+- Link to issues if applicable
+
+---
+
+## Footer (Optional)
+
+Use footer for metadata:
+
+**Breaking changes:**
+```
+feat(api)!: change authentication endpoint
+
+BREAKING CHANGE: /api/login now requires email instead of username
+```
+
+**Issue references:**
+```
+fix(cart): calculate tax correctly
+
+Fixes #123
+Closes #124
+Related to #125
+```
+
+**Attribution:**
+```
+feat(dashboard): add analytics widget
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Attribution Footer
+
+Add a simple attribution line in the footer when needed:
+
+```
+feat(feature): implement new capability
+
+[Body explaining the change]
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Examples
+
+### Simple Feature
+```
+feat(player): add jump mechanic
+```
+
+### Bug Fix with Context
+```
+fix(inventory): prevent item duplication
+
+Items were duplicating when rapidly clicking the pickup button.
+Added debounce logic to prevent double-processing.
+
+Fixes #156
+```
+
+### Refactor with Explanation
+```
+refactor(rendering): extract camera controller
+
+Moved camera logic from PlayerController to dedicated CameraController
+for better separation of concerns and reusability.
+```
+
+### Performance Improvement
+```
+perf(physics): optimize collision detection
+
+Changed from O(n²) all-pairs check to spatial hashing.
+Reduces frame time by ~15ms with 100+ objects.
+```
+
+### Attribution Example
+```
+feat(multiplayer): add lobby system
+
+Implements matchmaking lobby with room creation, joining, and ready-up.
+Uses WebSocket for real-time updates.
+
+Closes #89
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Usage in Skills
+
+**Reference this file when:**
+- Creating commits (Git or Plastic)
+- Generating commit messages
+- Validating commit format
+- Writing PR/code review descriptions
+
+**Load this file:**
+```markdown
+Load conventional commit format from ../../_shared/references/conventional-commits.md
+```
+
+Then format all commits according to this standard.

package/skills/using-plastic/SKILL.md

@@ -16,13 +16,13 @@ Treat `plastic_merge` success as provisional until `plastic_status` confirms the
 
 For the common closeout flow of merging a finished source branch into its parent branch, prefer `plastic_mergeToBranch` when available. When `target` is omitted, it resolves the source branch's Plastic parent branch instead of assuming `/dev`. It switches to the target, optionally updates, runs the safe merge, checks merge state, and checks in the merge result. Pass `target` only when the user explicitly wants a different integration branch.
 
-`plastic_diff` is intentionally disabled. For the common workspace change, use `plastic_diffFile(path="<workspace-path>")` with no revision; it materializes the Plastic base internally and returns a bounded portable text diff. Use a revision only when needed: a changeset number/`cs:<number>`, `br:/<branch>`, `lb:<label>`, file-qualified spec, or global `revid:`/`rev:` spec. `base`, `head`, and `cs:head` are intentionally rejected rather than guessed. Use `plastic_diffRevisions` only for two explicit file-qualified revisions. Binary content is reported rather than decoded as text.
+`plastic_diff` is intentionally disabled. Route changed-path listing to `plastic_status()`, one intentional workspace-file comparison to `plastic_diffFile(path="<workspace-path>")`, an explicitly scoped pending review to `plastic_workspaceDiff(paths=[...])`, and an explicit historical pair to `plastic_diffRevisions`. Do not use diffs as routine post-edit validation or checkin preflight. Prefer focused tests, `plastic_status` for pending scope, and direct reads for current file content; diff only when change-boundary evidence is needed. `plastic_diffFile` uses machine-readable status: added and explicitly selected private/new files compare against an empty base; changed, moved, and deleted items use their reported base revision when available. A `--nodata` base failure means Plastic cannot provide historical bytes; refresh/update the workspace or use two known file-qualified revisions. Explicit `revision` behavior remains a separate historical request. Binary content is reported rather than decoded as text.
 
-Use `plastic_status()` for “what changed?” and changed-path/status listing; do not use `cm diff` formatting for that purpose. Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. It uses `PI_PLASTIC_DIFF_EXECUTABLE` when set, otherwise portable `diff` on PATH; pass `toolPath` only for an intentional one-call override. For a large patch, pass an intentional new `output` path because Plastic will not overwrite it.
+`plastic_workspaceDiff` requires selected paths or explicit `allPending=true`, runs status once, has small default file/per-file/combined-output bounds, and returns per-file outcomes without aborting when one file is unavailable. Selected private paths are included; whole-workspace private review additionally requires `includePrivate=true`. Keep `maxChars` small unless more output is intentional. Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. It uses `PI_PLASTIC_DIFF_EXECUTABLE` when set, otherwise GNU/POSIX `diff` on PATH; paths containing spaces are supported, but Pi does not discover Git Bash paths automatically. Pass `toolPath` only for an intentional one-call override. For a large patch, pass an intentional new `output` path because Plastic will not overwrite it.
 
 Prefer runtime `plastic_*` tools first. Keep `cm` shell commands as manual fallback.
 
-Directly invoked mutating `plastic_*` tools run without package-owned approval tokens or UI confirmation. Inspect exact targets, use available preflight modes, and rely on the tools' command, workspace, path-containment, and non-interactive process guards. A command process is attempted once without implicit retry; after an ambiguous failure, inspect Plastic status before deciding whether to retry manually.
+Directly invoked mutating `plastic_*` tools run without package-owned approval tokens or UI confirmation. Inspect exact targets and rely on the tools' command, workspace, path-containment, and non-interactive process guards. Do not call preflight and then the same operation as routine ceremony. Use preflight when mutation scope is ambiguous or broad, moved/deleted paths may need rewriting, a compound operation needs preview, or the user explicitly asks for one. A command process is attempted once without implicit retry; after an ambiguous failure, inspect Plastic status before deciding whether to retry manually.
 
 Create normal work branches beneath an intended parent: use `<parent-branch>/<new-branch>`, not `/<new-branch>`. The parent does not need to be the branch loaded in the workspace. Prefer `plastic_branchCreate(branch="<new-branch>", parent="<parent-branch>")`; omitting `parent` uses the current branch only as a convenience. Rare top-level branch creation requires the explicit `allowRootBranch=true` override.
 

package/skills/using-plastic/references/changeset-operations.md

@@ -53,7 +53,7 @@ cm status --all
 
 Safe checklist:
 - Confirm deleted items appear in status output before checkin.
-- Prefer `plastic_checkin(preflight=true, paths=[...])` so the tool can rewrite unstable file scopes (moved/deleted) to stable parent scopes.
+- For path-scoped checkins containing moved/deleted items, use `plastic_checkin(preflight=true, paths=[...])` so the tool can preview rewriting unstable file scopes to stable parent scopes. Do not preflight ordinary exact-scope checkins routinely.
 - `plastic_checkin` now inspects `cm status --machinereadable` and auto-enables `--applychanged` when moved/deleted items are in scope.
 - Re-run `cm status --all` after add/scope changes, then checkin.
 
@@ -71,13 +71,13 @@ cm checkin -c="<commit-message>"
 
 ## Safe Diff Usage
 
-Never run `cm diff` in Pi.
-
-Use one of these safe alternatives:
+Never run `cm diff` in Pi. Do not replace it with a routine safe-diff call: use `plastic_status` for pending scope, focused tests for behavior, and direct reads for current content. Request diff output only when change-boundary evidence is needed.
 
 ```text
 plastic_status(machineReadable=true) # list pending paths/statuses
-plastic_diffFile(path="<workspace-path>") # common workspace-base diff
+plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped review
+plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
 plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```

package/skills/using-plastic/references/code-review-creation.md

@@ -1,30 +1,30 @@
-# Code Review Creation
-
-## CLI (Preferred)
-
-```bash
-branch=$(cm status | head -1 | cut -d@ -f1 | xargs)
-review_id=$(cm codereview "br:${branch}" "Feature: Brief description" --format="{id}")
-
-# Assign reviewer immediately after creating the review
-cm codereview -e "$review_id" --reviewer="reviewer-name"
-
-# List reviews for this branch
-cm find review "where target='br:${branch}'" --format="{id} {status} {title}"
-```
-
-Agent preference: use runtime `plastic_*` methods first for status/branch lookup; keep shell commands as manual fallback.
-
-Reviewer assignment is required in the workflow. If your server uses different reviewer flags, run `cm codereview --help` and use the server-specific reviewer option right after review creation.
-
-Tool-first flow (preferred):
-
-```text
-plastic_status()
-# Then use cm codereview ... as fallback for review create/assign
-```
-
-## CLI Not Available
-
-- Document branch and changeset in plan/issue tracker.
-- Or create review via Plastic GUI and assign a reviewer before sharing the review link.
+# Code Review Creation
+
+## CLI (Preferred)
+
+```bash
+branch=$(cm status | head -1 | cut -d@ -f1 | xargs)
+review_id=$(cm codereview "br:${branch}" "Feature: Brief description" --format="{id}")
+
+# Assign reviewer immediately after creating the review
+cm codereview -e "$review_id" --reviewer="reviewer-name"
+
+# List reviews for this branch
+cm find review "where target='br:${branch}'" --format="{id} {status} {title}"
+```
+
+Agent preference: use runtime `plastic_*` methods first for status/branch lookup; keep shell commands as manual fallback.
+
+Reviewer assignment is required in the workflow. If your server uses different reviewer flags, run `cm codereview --help` and use the server-specific reviewer option right after review creation.
+
+Tool-first flow (preferred):
+
+```text
+plastic_status()
+# Then use cm codereview ... as fallback for review create/assign
+```
+
+## CLI Not Available
+
+- Document branch and changeset in plan/issue tracker.
+- Or create review via Plastic GUI and assign a reviewer before sharing the review link.

package/skills/using-plastic/references/integration.md

@@ -4,7 +4,7 @@
 
 - Create feature branch following detected conventions.
 - Use incremental checkins.
-- Never use `cm diff`; use text-only diff tools.
+- Never use `cm diff`. Do not diff routinely; use a text-only diff tool only when review needs change-boundary evidence.
 - Use `plastic_merge` (or `cm merge ... --nointeractiveresolution --mergetype=try`) for autonomous merges.
 
 ## Autonomous Merge Workflow
@@ -34,10 +34,12 @@ plastic_patch(source="<branch-spec>", integration=true)
 plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")
 ```
 
-- Inspect specific file content changes with the common workspace-base path first:
+- When change-boundary evidence is needed, inspect specific files first and opt into multi-file output explicitly:
 
 ```text
-plastic_diffFile(path="<workspace-path>")
+plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped pending review
+plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
 plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```

package/skills/using-plastic/references/quick-reference.md

@@ -18,7 +18,8 @@ Note: command examples target current `cm` 11.x CLI syntax; legacy aliases may d
 | Shelve | `plastic_shelvesetCreate(comment="description")` | `cm shelveset create -c="description"` | Save work temporarily |
 | Patch for review | `plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")` | `cm patch <branch-spec> --clean --integration --output=<patch-file>` | Focused branch-review patch; inspect before sharing |
 | Changed-file listing | `plastic_status(machineReadable=true)` | `cm status --all` | Lists changed, added, moved, deleted, and private items without GUI diff |
-| Diff (workspace vs Plastic base) | `plastic_diffFile(path="<workspace-path>")` | None recommended | Bounded portable text diff; no guessed revision needed |
+| Diff (one workspace file) | `plastic_diffFile(path="<workspace-path>", maxChars=4000)` | None recommended | Intentional focused comparison only; not routine validation |
+| Diff (pending review) | `plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000)` | None recommended | Requires selected paths or explicit `allPending=true`; use status for changed-path listing |
 | Diff (workspace vs supported revision) | `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` | None recommended | Also accepts a branch, label, file-qualified, or global revision spec |
 | Diff (revision vs revision) | `plastic_diffRevisions(leftRevision="<left-revspec>", rightRevision="<right-revspec>")` | None recommended | Requires two file-qualified revisions; avoids GUI and package temp-file recipes |
 

package/skills/using-plastic/references/resources.md

@@ -1,7 +1,7 @@
-# Resources
-
-- CLI Reference: https://docs.unity.com/en-us/unity-version-control/uvcs-cli
-- Branch Management: https://docs.unity.com/en-us/unity-version-control/branches
-- Code Reviews: https://docs.unity.com/en-us/unity-version-control/code-reviews
-
-Minimum version: PlasticSCM 11.0+
+# Resources
+
+- CLI Reference: https://docs.unity.com/en-us/unity-version-control/uvcs-cli
+- Branch Management: https://docs.unity.com/en-us/unity-version-control/branches
+- Code Reviews: https://docs.unity.com/en-us/unity-version-control/code-reviews
+
+Minimum version: PlasticSCM 11.0+

package/skills/using-plastic/references/reviewing-changes.md

@@ -21,16 +21,18 @@ plastic_patch(source="<branch-spec>", toolPath="<path-to-diff-tool>")
 
 ## Text-Only Diff Options
 
-Prefer tool-first:
+Do not use diffs as routine post-edit validation or checkin preflight. Prefer focused tests, `plastic_status` for pending scope, and direct reads for current content. Use a diff only when change-boundary evidence is needed, such as reviewing unfamiliar changes or confirming a specific risky hunk.
 
 ```text
 plastic_status(machineReadable=true) # “what changed?” / changed-path listing
-plastic_diffFile(path="<workspace-path>") # common workspace vs Plastic-base comparison
-plastic_diffFile(path="<workspace-path>", revision="cs:<number>") # explicit advanced comparison
+plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped pending review
+plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
+plastic_diffFile(path="<workspace-path>", revision="cs:<number>") # explicit historical comparison
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```
 
-The diff tools materialize historical bytes and remove their temporary files internally. They use a bounded portable text diff, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review.
+The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; changed, moved, and deleted records use their status revision ID when available. A `--nodata` item cannot supply historical/base bytes: refresh the workspace or use two known file-qualified revisions. `plastic_workspaceDiff` requires selected paths or `allPending=true` and returns per-file unavailable outcomes instead of aborting the batch. All tools use bounded GNU/POSIX text diff, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review.
 
 ## Metadata Listing (No GUI Diff)
 
@@ -49,9 +51,9 @@ Use the Read tool for full context instead of GUI diffs.
 Use the common no-revision path first; `base`, `head`, and `cs:head` are rejected rather than guessed:
 
 ```text
-plastic_diffFile(path="<workspace-path>")
-plastic_diffFile(path="<workspace-path>", revision="br:/<branch>")
-plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
+plastic_diffFile(path="<workspace-path>", maxChars=4000)
+plastic_diffFile(path="<workspace-path>", revision="br:/<branch>", maxChars=4000)
+plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>", maxChars=4000)
 ```
 
 ## Pending Changes

package/skills/using-plastic/references/shelving.md

@@ -1,25 +1,25 @@
-# Shelving
-
-## Save Work
-
-```bash
-cm shelveset create -c="Working on feature X"
-```
-
-## List Shelves
-
-```bash
-cm find shelve "where owner='me'" --format="{shelveid} {date} {comment}"
-```
-
-## Restore Work
-
-```bash
-cm shelveset apply sh:5
-```
-
-## Delete Shelve
-
-```bash
-cm shelveset delete sh:5
-```
+# Shelving
+
+## Save Work
+
+```bash
+cm shelveset create -c="Working on feature X"
+```
+
+## List Shelves
+
+```bash
+cm find shelve "where owner='me'" --format="{shelveid} {date} {comment}"
+```
+
+## Restore Work
+
+```bash
+cm shelveset apply sh:5
+```
+
+## Delete Shelve
+
+```bash
+cm shelveset delete sh:5
+```