@zalom/plastic 1.0.0-beta.34 → 1.0.0-beta.36

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

@@ -85,14 +85,11 @@ git merge <branch-name> --no-ff -m "feat: merge intent [ID] - [description]"
 
 Always `--no-ff` to preserve branch history in the merge commit.
 
-**Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
-worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
-`plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
-feature branch. The merge-then-remove of that worktree is handled together with cleanup in
-step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the
-worktree. If you already merged here by hand, step 9 is a clean no-op merge ("Already up to
-date") and proceeds straight to removal. Do not delete the worktree before its branch is
-merged, or the work is lost.
+**Worktree-isolated intents (intent 73c3).** A worktree-delivered intent's code lives on
+`plastic/{id}--{slug}`, merged together with cleanup in step 9, not on a hand-made feature
+branch. Do not delete the worktree before its branch is merged, or the work is lost. For
+the full rationale and the already-merged-by-hand no-op case, read
+`references/promotion-and-tagging.md`.
 
 ### 4. Bump Version
 
@@ -231,12 +228,8 @@ A release IS a delivery. The active intent that drove this work must be complete
 
 ### 9. Clean Up the Intent's Worktrees (merge-then-remove)
 
-A release is the merge-then-remove path for the intent's worktrees (intent 73c3). This is the
-one place the merge-vs-remove policy lands on "merge": the intent's code branch
-(`plastic/{id}--{slug}`) is merged back into the repo's default branch BEFORE the worktree is
-removed, so the integrated work is never lost. (The disarm path in `plastic-auto`, by contrast,
-is a plain remove because no release is merging the branch.)
-
+A release is the merge-then-remove path for the intent's worktrees (intent 73c3): the
+intent's code branch is merged back into the default branch BEFORE the worktree is removed.
 Drive it through `Worktree.finish` with `merge: true`, which merges the code branch, then
 removes both worktrees (code + paired store), prunes both repos, and clears the worktree block
 from the bridge:
@@ -249,10 +242,10 @@ ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
 (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
-prune` in the affected repo if you hit a stale reference.
+Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree
+prune` in the affected repo if you hit a stale reference. For why this is the one place the
+merge-vs-remove policy lands on merge, and the fail-open/idempotent guarantees of `finish`,
+read `references/promotion-and-tagging.md`.
 
 ## Conventions
 
@@ -266,34 +259,9 @@ prune` in the affected repo if you hit a stale reference.
 - **Verify sync** - after pushing, confirm npm dist-tag, GitHub "Latest", and the git tag all show the new version
 - **Branch cleanup** - delete merged feature branches: `git branch -d <branch>`
 
-## Promotion
-
-To promote a release across channels, use `--promote`:
-
-```bash
-plastic-releasing --promote beta    # promotes current alpha → beta
-plastic-releasing --promote stable  # promotes current beta → stable
-```
-
-**Promotion rules:**
-- Linear only: alpha → beta → stable. Cannot skip channels.
-- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
-  to `-beta.1`, publishes with `--tag beta`.
-- `--promote stable`: reads version from `package.json`, strips pre-release suffix
-  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
-- Version files are bumped and committed as in a normal release.
-- An annotated tag is created for the promoted version.
-
-## Retroactive Tagging
-
-For repos without prior tags, tag historical releases:
-
-```bash
-git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
-```
-
-Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).
-
 ## References
 
+- When promoting a pre-release across channels (`--promote beta`/`--promote stable`) or
+  tagging a historical release retroactively, read `references/promotion-and-tagging.md`
+  for the exact commands and rules first
 - Read `references/deprecations.md` for the full deprecation process, severity levels, deprecations.yml schema, and dismissal rules when adding or managing deprecations

package/skills/releasing/references/promotion-and-tagging.md

@@ -0,0 +1,60 @@
+# Promotion, Retroactive Tagging, and Worktree Merge Rationale
+
+Occasional variant paths off the main release workflow: promoting a pre-release
+across channels, tagging historical releases retroactively, and the deep rationale
+for why the intent's worktree is merged before removal.
+
+## Table of Contents
+
+- [Worktree merge-then-remove rationale](#worktree-merge-then-remove-rationale)
+- [Promotion](#promotion)
+- [Retroactive Tagging](#retroactive-tagging)
+
+## Worktree merge-then-remove rationale
+
+**Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
+worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
+`plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
+feature branch. The merge-then-remove of that worktree is handled together with cleanup in
+Workflow step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the
+worktree. If you already merged here by hand, step 9 is a clean no-op merge ("Already up to
+date") and proceeds straight to removal. Do not delete the worktree before its branch is
+merged, or the work is lost.
+
+A release is the merge-then-remove path for the intent's worktrees. This is the one place
+the merge-vs-remove policy lands on "merge": the intent's code branch (`plastic/{id}--{slug}`)
+is merged back into the repo's default branch BEFORE the worktree is removed, so the
+integrated work is never lost. (The disarm path in `plastic-auto`, by contrast, is a plain
+remove because no release is merging the branch.)
+
+`Worktree.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.
+
+## Promotion
+
+To promote a release across channels, use `--promote`:
+
+```bash
+plastic-releasing --promote beta    # promotes current alpha → beta
+plastic-releasing --promote stable  # promotes current beta → stable
+```
+
+**Promotion rules:**
+- Linear only: alpha → beta → stable. Cannot skip channels.
+- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
+  to `-beta.1`, publishes with `--tag beta`.
+- `--promote stable`: reads version from `package.json`, strips pre-release suffix
+  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
+- Version files are bumped and committed as in a normal release.
+- An annotated tag is created for the promoted version.
+
+## Retroactive Tagging
+
+For repos without prior tags, tag historical releases:
+
+```bash
+git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
+```
+
+Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).

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