@zalom/plastic 1.0.0-beta.33 → 1.0.0-beta.35

package/skills/install/SKILL.md

@@ -1,24 +1,31 @@
 ---
 name: plastic-install
-description: Use when initializing Plastic globally (~/.plastic/) or locally in a project, or to re-install/repair a broken installation. Accepts channel flags (--alpha, --beta, --latest) to select release channel. Default is --latest (stable). Global install is recommended — creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
+description: Use when initializing Plastic globally (~/.plastic/) or locally in a project, or to re-install/repair a broken installation. Accepts channel flags (--alpha, --beta, --latest) to select release channel. First install defaults to --beta; reinstalls match the already-installed channel. Global install is recommended: it creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
 ---
 
 # Install Plastic
 
-> **Recommended path:** for a first install, run `npx @zalom/plastic@latest install --claude`
-> in your shell (or `bunx @zalom/plastic@latest --claude` if you use Bun). This skill
+> **Recommended path:** for a first install, run `npx -y @zalom/plastic@beta install --claude`
+> in your shell (or `bunx -y @zalom/plastic@beta install --claude` if you use Bun). This skill
 > exists to **re-install or repair** an existing setup from inside the agent, and to
 > drive interactive global configuration. Whenever this skill performs an install or
 > re-install, it **runs `/plastic-doctor` afterward** and reports the result.
 
+## Channel rule
+
+If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
+`-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed
+(first install), default to `@beta`. The user can always override with
+`--alpha` / `--beta` / `--latest`.
+
 ## Re-install / repair
 
 If Plastic is already installed but something is broken (skills missing, hooks not
-firing, leftover legacy plugin), re-run the installer — it is idempotent, prunes
+firing, leftover legacy plugin), re-run the installer, it is idempotent, prunes
 files that no longer ship, and removes any legacy plugin/marketplace layout:
 
 ```bash
-npx @zalom/plastic@latest install --reinstall --claude   # or @beta / @alpha to match your channel
+npx -y @zalom/plastic@<channel> install --reinstall --claude
 ```
 
 Then **run `/plastic-doctor`** and report what it found.
@@ -27,22 +34,22 @@ Then **run `/plastic-doctor`** and report what it found.
 
 | Flag | Behavior |
 |------|----------|
-| `--latest` | Install from stable channel (default) |
-| `--beta` | Install from beta channel |
-| `--alpha` | Install from alpha channel |
+| `--latest` | Install from the stable channel |
+| `--beta` | Install from the beta channel (default on a first install) |
+| `--alpha` | Install from the alpha channel |
 
 When invoked from within Claude Code (re-install or channel switch), the skill
 runs the appropriate npx command:
 
 ```bash
-# Stable (default)
-npx @zalom/plastic install --claude
+# Stable
+npx -y @zalom/plastic@latest install --claude
 
-# Beta
-npx @zalom/plastic@beta install --claude
+# Beta (default on a first install)
+npx -y @zalom/plastic@beta install --claude
 
 # Alpha
-npx @zalom/plastic@alpha install --claude
+npx -y @zalom/plastic@alpha install --claude
 ```
 
 The installed version and channel are recorded in `~/.plastic/VERSION`.
@@ -55,105 +62,80 @@ Run `/plastic-install` with no arguments.
 
 #### Procedure
 
-**Step 1: Check for existing installation**
-
-Check if `~/.plastic/INDEX.md` exists.
-- If yes: announce "Plastic is already installed at ~/.plastic/. Run `/plastic-update` to sync core files."
-- If no: proceed with fresh install.
+**Step 1: Run the installer**
 
-**Step 2: Create ~/.plastic/ as a git repo**
+Check if `~/.plastic/VERSION` exists.
+- If yes: announce "Plastic is already installed at ~/.plastic/. Run `/plastic-update` to
+  sync core files, or use the re-install command above to repair in place."
+- If no: run the fresh install command (default `@beta`, or the channel the user named):
 
 ```bash
-mkdir -p ~/.plastic/store ~/.plastic/projects
+npx -y @zalom/plastic@beta install --claude
 ```
 
-Copy templates from the plugin:
-- `config.yml` from `${CLAUDE_PLUGIN_ROOT}/templates/config.yml`
-- `projects.yml` from `${CLAUDE_PLUGIN_ROOT}/templates/projects.yml`
-- `INDEX.md` from `${CLAUDE_PLUGIN_ROOT}/templates/index.md`
-- `PLASTIC.md` from `${CLAUDE_PLUGIN_ROOT}/PLASTIC.md`
+This single command, via `install.rb` (`bootstrap` + `distribute`), creates `store/`,
+`projects/`, `config.yml`, `projects.yml`, `INDEX.md`, and `AGENTS.md` under `~/.plastic/`,
+and copies the utility scripts (`folgezettel-id`, `read-config`, and the rest of
+`scripts/`). This skill does none of that itself; it wraps the command with the
+interactive steps the CLI does not yet own, plus reporting and a doctor pass.
 
-Create `AGENTS.md` (user-editable, not overwritten on updates):
-```markdown
-# Plastic — Agent Instructions
+**Statusline**
 
-Read `PLASTIC.md` in this directory. It contains all Plastic conventions.
-Follow it exactly. Never modify it — it is overwritten on plugin updates.
+On install, if an existing statusline is already configured, Plastic asks whether to
+keep it or switch to Plastic's (interactive sessions only). The choice is honored via
+`--statusline keep` or `--statusline plastic`, which skips the prompt. Non-interactive
+sessions (no tty) default to keeping the user's line: nothing is silently overwritten.
+A fresh system with no statusline configured gets Plastic's line with no prompt.
 
-This file (`AGENTS.md`) is where project-specific rules live. Users and agents
-may add content below.
-
----
-```
+**Step 2: Initialize git (retained)**
 
-Add `.gitkeep` to `store/` and `projects/`.
+Only if `~/.plastic/.git` is absent (a fresh bootstrap does not init git):
 
-Initialize git:
 ```bash
 cd ~/.plastic && git init && git add . && git commit -m "chore: initialize Plastic global intent store"
 ```
 
-**Step 2b: Copy utility scripts**
+Retained here because the CLI does not git-init the store yet (follow-up).
 
-```bash
-mkdir -p ~/.plastic/scripts
-cp "${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" ~/.plastic/scripts/folgezettel-id
-cp "${CLAUDE_PLUGIN_ROOT}/scripts/read-config" ~/.plastic/scripts/read-config
-chmod +x ~/.plastic/scripts/folgezettel-id ~/.plastic/scripts/read-config
-```
-
-This ensures project agents can generate hashes via `~/.plastic/scripts/folgezettel-id` without depending on a specific agent's plugin cache path.
-
-**Step 2c: Detect agent type and set preferences**
+**Step 3: Personalize config (retained)**
 
 Detect which agent is running:
-- If `CLAUDE_CODE` env var is set or we're running inside Claude Code → `agent.type: claude-code`
-- If `HERMES_HOME` env var is set → `agent.type: hermes`
-- Otherwise → ask the user: "Which AI agent are you using? (claude-code / hermes / other)"
+- If `CLAUDE_CODE` env var is set or we're running inside Claude Code -> `agent.type: claude-code`
+- If `HERMES_HOME` env var is set -> `agent.type: hermes`
+- Otherwise -> ask the user: "Which AI agent are you using? (claude-code / hermes / other)"
 
 Ask the user:
-> "Enable Agent Teams? (experimental — parallel project work with teammates)"
-> - Yes → set `parallel_mode: agent-teams`
-> - No → set `parallel_mode: linear` (subagents only)
-
-Update `~/.plastic/config.yml` with detected/chosen values using `read-config --migrate` first to ensure v3 schema, then write the agent-specific values.
-
-Auto-commit the config change.
-
-**Step 2d: Configure GitHub and push preferences**
+> "Enable Agent Teams? (experimental: parallel project work with teammates)"
+> - Yes -> set `parallel_mode: agent-teams`
+> - No -> set `parallel_mode: linear` (subagents only)
 
 Inform the user:
-> "Plastic agents can create GitHub repositories for new projects.
-> By default, all agent-created repos are **private**. Your global
-> intent store (~/.plastic/) is never pushed — it stays local-only."
+> "Plastic agents can create GitHub repositories for new projects. By default, all
+> agent-created repos are **private**. Your global intent store (~/.plastic/) is never
+> pushed, it stays local-only."
 
 Ask the user:
 > "Default visibility for agent-created repos?"
-> - Private (recommended) → set `github.default_visibility: private`
-> - Public → set `github.default_visibility: public`
-
+> - Private (recommended) -> set `github.default_visibility: private`
+> - Public -> set `github.default_visibility: public`
+>
 > "Allow agents to push to GitHub without asking?"
-> - No (recommended) → set `github.auto_push: false`
-> - Yes → set `github.auto_push: true`
-
-Update `config.yml` with chosen values. Auto-commit.
-
-**Step 3: Configure project roots**
-
-Ask the user:
+> - No (recommended) -> set `github.auto_push: false`
+> - Yes -> set `github.auto_push: true`
+>
 > "Where do you keep your projects? Default: ~/.plastic/projects/"
 > "Add additional roots? (e.g., ~/apps/personal/, ~/apps/companies/)"
 
-Update `config.yml` with any additional roots.
-
-Auto-commit the config change.
+Write each answer via `read-config --migrate` first (ensures the v3 schema), then the
+chosen values; auto-commit each change. Retained here because the CLI writes only
+hardcoded defaults, so these interactive choices stay in the skill.
 
 **Step 4: Verify with doctor**
 
 Run `/plastic-doctor` and report the result. Resolve any fixable findings before
 announcing success.
 
-**Step 5: Register stores with QMD (optional)**
+**Step 5: Register stores with QMD (retained)**
 
 QMD is an optional search layer. If it is installed, register the Plastic stores so
 they are searchable:
@@ -165,19 +147,27 @@ ruby ~/.plastic/scripts/qmd-sync detect && ruby ~/.plastic/scripts/qmd-sync regi
 `qmd-sync` no-ops cleanly when QMD is absent, so this is safe to run unconditionally.
 It registers `plastic-global` and every project store from `projects.yml`, then indexes
 them. Report what was registered, or that QMD was not detected and the step was skipped.
+Retained here because the CLI does not register at install time (follow-up).
+
+**Step 6: Report + announce**
 
-**Step 6: Announce**
+```
+Plastic install (<channel>)
+Command:  npx -y @zalom/plastic@<channel> install --claude <flags>
+Version:  none -> <installed>
+Doctor:   <summary or "all clear">
+```
 
-> "Plastic installed globally at ~/.plastic/. Health check: [doctor summary].
-> Create your first intent with `/plastic-creating-intent`."
+Then: "Create your first intent with `/plastic-creating-intent`."
 
 ### Local Install (testing/legacy)
 
-Run `/plastic-install --local`.
+Run `/plastic-install --local`. `install.rb` has no `--local` verb, so this mode is
+genuinely skill-owned.
 
 #### Procedure
 
-**Step 1:** Check if `.plastic/` exists in CWD — if so, warn and exit.
+**Step 1:** Check if `.plastic/` exists in CWD, if so, warn and exit.
 
 **Step 2:** Create `.plastic/` in CWD:
 - `config.yml` from templates
@@ -192,4 +182,5 @@ Run `/plastic-install --local`.
 
 **Step 4:** Commit in project: `git add .plastic/ && git commit -m "chore: initialize Plastic local store"`
 
-**Step 5:** Announce: "Plastic initialized locally. This is a testing/legacy mode. Consider `/plastic-install` for global mode."
+**Step 5:** Announce: "Plastic initialized locally. This is a testing/legacy mode. Consider
+`/plastic-install` for global mode."

package/skills/intent-discovery/SKILL.md

@@ -4,22 +4,21 @@ description: >-
   What-stage context deposit at intent activation: run QMD discovery over the
   intent's chain/sources and related parked intents, and write findings to
   resources/discovery--<slug>.md for the Why stage to consume. Use when an intent
-  is activated (moved from Future to Active), before the lock is armed and Why
-  begins. Never writes the intent file itself.
+  is activated (moved from Future to Active), after the lock is armed, under it,
+  and before Why begins. Never writes the intent file itself.
 ---
 
 # Intent Discovery — What-stage context deposit
 
 Announce: "Discovering context for intent [ID] — [name]."
 
-Runs once, at intent activation, before the lock and Why. It gathers what is
+Runs once, at intent activation, after the lock is armed and before Why. It gathers what is
 already known so Why does not start cold, and deposits it as a resource the
 Why-stage brainstorming agent reads.
 
 ## When it fires
-Inside `plastic-intent-starting`, at the moment the intent moves from
-`## Future` to `## Active` (before the bridge is armed). Dispatched as the
-`plastic-intent-discovery` background agent.
+Inside `plastic-intent-starting`, right after the bridge is armed, under the
+lock. Dispatched as the `plastic-intent-discovery` background agent.
 
 ## What it does
 1. **Read the intent's links.** Load the activating intent file's `chain` and
@@ -42,5 +41,7 @@ executor, Done: intent-curator).
 
 ## Boundaries
 - Single output: `resources/discovery--<slug>.md`.
-- Never takes the delivery lock (it runs before the lock is armed).
+- Does not ACQUIRE the delivery lock itself; it runs under the lock the
+  orchestrator armed, as the owner session (inherited session id), and is not
+  blocked by it.
 - Advisory input to Why, not a gate.

package/skills/intent-starting/SKILL.md

@@ -34,14 +34,6 @@ enforces it: without a held lock, mutating writes to this active intent's dir ar
 1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
    (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
    brand-new What intent is activated here, then locked.
-1a. **Dispatch What-stage discovery (before the lock).** Right after activation and before
-   arming the bridge, dispatch the `plastic-intent-discovery` agent (see the
-   `plastic-intent-discovery` skill). Resolve its model explicitly and pass it at dispatch
-   time (belt-and-braces): `read-config agents.models.plastic-intent-discovery --project
-   <repo>`. The agent runs QMD discovery over the intent's `chain`/`sources` and deposits
-   findings to `resources/discovery--<slug>.md` only; it never writes the intent file, so the
-   lock-owner-only rule is untouched. This is advisory context for Why, not a gate: if
-   discovery yields nothing, proceed to the lock normally.
 2. **Self-heal the lock state first.** Run:
    `ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <STORE>/<dir>`
    This is the one repair function (same one /plastic-lock exposes): it removes
@@ -61,6 +53,17 @@ enforces it: without a held lock, mutating writes to this active intent's dir ar
    ```
    Replace `<ID>`, `<STORE>` (`~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
    `<dir>` (the `ID--slug` directory), and `<name>`.
+4. **Dispatch What-stage discovery (under the lock).** Right after arming, when the intent
+   was just activated in step 1 (on a resume that already has
+   `resources/discovery--<slug>.md`, skip: discovery runs once per intent, at activation
+   only), dispatch the `plastic-intent-discovery` agent (see the `plastic-intent-discovery`
+   skill), now that this session owns the lock, deposit authorized as the owner session. Resolve its
+   model explicitly and pass it at dispatch time (belt-and-braces): `read-config
+   agents.models.plastic-intent-discovery --project <repo>`. The agent runs QMD discovery
+   over the intent's `chain`/`sources` and deposits findings to
+   `resources/discovery--<slug>.md` only; it never writes the intent file, so the
+   lock-owner-only rule is untouched. This is advisory context for Why, not a gate: if
+   discovery yields nothing, proceed to Why normally.
 
 **Session id resolution (verbatim from `plastic-auto`).** The first argument is the session
 id the bridge is keyed by: pass the hook stdin `session_id` when you have it, otherwise

package/skills/releasing/SKILL.md

@@ -243,9 +243,12 @@ from the bridge:
 
 ```bash
 ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
-  'b = Bridge.read(ENV["CLAUDE_CODE_SESSION_ID"]); Worktree.finish(b, merge: true) if b'
+  'b = Bridge.discover_bridge(session: ENV["CLAUDE_CODE_SESSION_ID"], cwd: Dir.pwd); Worktree.finish(b, merge: true) if b'
 ```
 
+(Uses `discover_bridge`, not a bare session-keyed `Bridge.read`, because a session can own more
+than one live bridge now — intent 131 — and `discover_bridge` resolves the right one for this cwd.)
+
 `finish` is fail-open and idempotent: a conflicting merge is aborted and logged (the worktree
 is still removed rather than stranded), and a second call with the block already cleared is a
 no-op. Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree

package/skills/uninstall/SKILL.md

@@ -9,15 +9,21 @@ The installer tracks every file it writes in a manifest, so uninstall is exact a
 leaves no orphans. Prefer running it through the CLI; this skill wraps the same
 underlying uninstaller and adds reporting + verification.
 
+## Channel rule
+
+If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
+`-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed,
+default to `@beta`. The user can always override with `--alpha` / `--beta` / `--latest`.
+
 ## Procedure
 
 ### Step 1: Run the uninstaller
 
 ```bash
-npx @zalom/plastic@latest uninstall --claude
+npx -y @zalom/plastic@<channel> uninstall --claude
 ```
 
-(Use `--codex` / `--hermes` / `--all` to target other agents. `bunx` works too.)
+(Use `--codex` / `--hermes` / `--all` to target other agents. `bunx -y @zalom/plastic@<channel> uninstall --claude` works too.)
 
 This removes, for the targeted agent:
 - all `~/.claude/skills/plastic-*/` skills
@@ -29,8 +35,8 @@ This removes, for the targeted agent:
 
 ### Step 2: Report removed vs left
 
-Relay the uninstaller's output to the user — what was **removed** and what was
-**left in place**:
+Relay the uninstaller's output to the user: what was **removed** and what was
+**left in place**.
 - **Left:** `~/.plastic/` (intent store, history, projects) and any non-Plastic
   settings.json entries.
 
@@ -39,21 +45,33 @@ Relay the uninstaller's output to the user — what was **removed** and what was
 Tell the user to confirm:
 
 ```bash
-ls ~/.claude/skills | grep '^plastic-'    # → no output
-ls ~/.claude/hooks  | grep '^plastic-'    # → no output
-grep -n plastic ~/.claude/settings.json   # → no plastic hook/plugin refs
+ls ~/.claude/skills | grep '^plastic-'    # -> no output
+ls ~/.claude/hooks  | grep '^plastic-'    # -> no output
+grep -n plastic ~/.claude/settings.json   # -> no plastic hook/plugin refs
+```
+
+### Step 4: Report + offer the data decision
+
+Emit the reporting block, using the Step 3 checks for the verification line:
+
+```
+Plastic uninstall (<channel>)
+Command:  npx -y @zalom/plastic@<channel> uninstall --claude <flags>
+Version:  removed
+Verification: <Step 3 results, or "clean">
 ```
 
-### Step 4: Offer the data decision
+Then:
 
 ```
 Plastic is uninstalled from [agent].
 Your intent store at ~/.plastic/ is untouched.
 
 Delete it too?
-  a) Keep everything (recommended) — re-install anytime with npx
-  b) Delete everything now — removes ~/.plastic/ entirely (irreversible)
+  a) Keep everything (recommended): re-install anytime with npx
+  b) Delete everything now: removes ~/.plastic/ entirely (irreversible)
 ```
 
-- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with `npx @zalom/plastic@latest install --claude`."
+- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with
+  `npx -y @zalom/plastic@beta install --claude` (or your channel)."
 - **Delete:** run `rm -rf ~/.plastic/` and confirm.

package/skills/update/SKILL.md

@@ -13,58 +13,69 @@ description: Use when updating Plastic. Runs the `update` verb, which reads the
 ## What it does
 
 `update` is a single deterministic command. It reads `~/.plastic/VERSION`, derives the
-channel from the version string (`-alpha`/`-beta`/none → stable), queries `npm` dist-tags,
+channel from the version string (`-alpha`/`-beta`/none -> stable), queries `npm` dist-tags,
 and advances to the **next version on the current channel**. "Already up to date" is a
-clean no-op. You do not compute the target yourself — the script does.
+clean no-op. You do not compute the target yourself, the script does.
+
+## Channel rule
+
+If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
+`-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed
+(first install), default to `@beta`. The user can always override with
+`--alpha` / `--beta` / `--latest`.
 
 ## Flags
 
 | Flag | Behaviour |
 |------|-----------|
 | (none) | Advance to the next version on the **current** channel |
-| `--latest` | Switch to / advance the **stable** channel (toward stability — frictionless) |
+| `--latest` | Switch to / advance the **stable** channel (toward stability, frictionless) |
 | `--beta` | Switch to / advance the **beta** channel |
-| `--alpha` | Switch to / advance the **alpha** channel (bleeding edge — confirmed if moving down in stability) |
+| `--alpha` | Switch to / advance the **alpha** channel (bleeding edge, confirmed if moving down in stability) |
 
 Switching toward a more stable channel is frictionless; switching toward bleeding edge is
 confirmed. To roll **back** to a previously-installed version, use `plastic-versions`.
 
 ## Prerequisites
 
-Plastic must be installed (`~/.plastic/VERSION` present). If not, run
-`npx @zalom/plastic install --claude` first.
+Plastic must be installed (`~/.plastic/VERSION` present). If not, run `plastic-install`
+first (or `npx -y @zalom/plastic@beta install --claude` directly).
 
 ## Procedure
 
 ### Step 1: Run the update
 
 ```bash
-npx @zalom/plastic update            # next version on the current channel
-# or: npx @zalom/plastic update --beta   /   --latest   /   --alpha
+npx -y @zalom/plastic@<channel> update --claude
+# channel switch: append --beta / --latest / --alpha
+# other agents: append --codex / --hermes / --all
 ```
 
-Append the agent flag(s) if not just Claude (`--codex`, `--hermes`, `--all`).
-The command prints the transition (`vX → vY`) or "already up to date", and records the
-move in the append-only `~/.plastic/versions.json` ledger.
+`bunx -y @zalom/plastic@<channel> update --claude` works as a fallback if `npx` is
+unavailable. The command prints the transition (`vX -> vY`) or "already up to date", runs
+a post-update doctor summary, and records the move in the append-only
+`~/.plastic/versions.json` ledger.
 
-### Step 2: Announce key changes
+### Step 2: Relay the result, announce convention changes
 
-After it completes, read `~/.plastic/PLASTIC.md` and announce convention changes that
-affect the current session:
+Relay what `update` printed, do not recompute the version transition or the doctor
+summary:
 
 ```
-Plastic updated to vX.Y.Z (channel).
-
-Key changes:
-- [notable convention changes, if any]
-
-Recommendation: run /clear for a clean session with all new conventions loaded.
+Plastic update (<channel>)
+Command:  npx -y @zalom/plastic@<channel> update --claude <flags>
+Version:  <before> -> <after>
+Doctor:   <relayed summary, or "all clear">
 ```
 
-### Step 3: Health check
+Then read `~/.plastic/PLASTIC.md` and announce convention changes that affect the
+current session, and recommend `/clear` for a clean session with all new conventions
+loaded.
+
+### Step 3: Health check only on a relayed failure
 
-Invoke `plastic-doctor`. If all checks pass: **"Health check: all clear."** Otherwise show
-the report and offer to fix.
+If the relayed doctor summary shows a failure, invoke `plastic-doctor` for the full
+report and offer to fix. If it already reads clean, do not re-run doctor.
 
 ### Step 4: Commit + clear update cache
 

package/skills/versions/SKILL.md

@@ -3,7 +3,7 @@ name: plastic-versions
 description: Use when the user wants to see their Plastic version history or roll back to a previously-installed version after a bad release. Manages the local, append-only versions.json ledger and steps between versions the user has actually run. For moving to a brand-new release, use plastic-update instead.
 ---
 
-# Plastic Versions — local version time-machine
+# Plastic Versions: local version time-machine
 
 ## When to Use
 - "show plastic versions", "version history", "what versions have I run"
@@ -11,11 +11,18 @@ description: Use when the user wants to see their Plastic version history or rol
 - A new version broke something and the user wants their last known-good build
 
 For upgrading to a **new** release, use `plastic-update`. This skill only navigates
-versions you have **already installed** — the ones recorded in the ledger.
+versions you have **already installed**, the ones recorded in the ledger.
+
+## Channel rule
+
+`versions` restores whichever build you pick from the ledger, it does not take a channel
+flag for the target. The pinned `<channel>` below is only the npx invocation itself:
+derive it from `~/.plastic/VERSION` the same way as the other lifecycle skills,
+`-alpha` -> `@alpha`, `-beta` -> `@beta`, otherwise `@latest`.
 
 ## The ledger
 
-`~/.plastic/versions.json` is an **append-only JSONL** ledger — one line per version
+`~/.plastic/versions.json` is an **append-only JSONL** ledger, one line per version
 change, never modified or deleted:
 
 ```json
@@ -23,15 +30,16 @@ change, never modified or deleted:
 {"version":"1.0.0-alpha.18","action":"update","at":"..."}
 ```
 
-`action` ∈ `install | reinstall | update | downgrade` (derived from version direction; the
-channel is derived from the version string, never stored). It is a troubleshooting record.
+`action` is one of `install`, `reinstall`, `update`, `downgrade` (derived from version
+direction; the channel is derived from the version string, never stored). It is a
+troubleshooting record.
 
 ## Procedure
 
 ### Show history
 
 ```bash
-npx @zalom/plastic versions
+npx -y @zalom/plastic@<channel> versions
 ```
 
 Prints the table with the currently-installed version marked. If the most recent action was
@@ -40,8 +48,8 @@ a `downgrade`, it asks whether to keep rolling back.
 ### Roll back
 
 ```bash
-npx @zalom/plastic versions --downgrade                    # one step back
-npx @zalom/plastic versions --downgrade --version 1.0.0-alpha.15   # to a specific run
+npx -y @zalom/plastic@<channel> versions --downgrade                    # one step back
+npx -y @zalom/plastic@<channel> versions --downgrade --version 1.0.0-alpha.15   # to a specific run
 ```
 
 Rollback targets are restricted to versions in the ledger (only builds you have actually
@@ -51,15 +59,22 @@ re-fetched from npm and re-synced; your intent store, config, and the ledger are
 ### Step forward (after a rollback)
 
 ```bash
-npx @zalom/plastic versions --upgrade                      # one step forward in your history
+npx -y @zalom/plastic@<channel> versions --upgrade                      # one step forward in your history
 ```
 
 ### After any change
 
-Run `plastic-doctor` to confirm health, and suggest `/clear` so the session picks up the
-swapped conventions.
+Run `plastic-doctor` to confirm health, then emit the reporting block and suggest
+`/clear` so the session picks up the swapped conventions:
+
+```
+Plastic versions (<channel>)
+Command:  npx -y @zalom/plastic@<channel> versions <flags>
+Version:  <before> -> <after>
+Doctor:   <summary or "all clear">
+```
 
 ## Notes
-- The ledger is **never** edited or pruned — it is the audit trail.
+- The ledger is **never** edited or pruned, it is the audit trail.
 - Downgrades cannot un-migrate a store-format change; if a warning appears, surface it to
   the user rather than forcing the rollback.