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

package/PLASTIC.md

@@ -213,12 +213,14 @@ run the main session on the best available thinking model (Fable, Opus, or whate
 them). This is advisory only: it changes no behavior and blocks nothing if ignored, and it
 concerns the human's main session, never a dispatched subagent.
 
-**`plastic-intent-discovery`.** The What-stage agent. It fires at intent activation, before the
-delivery lock is armed and Why begins: it reads the intent's `chain`/`sources` frontmatter,
-runs QMD-first discovery over completed predecessor work and related parked or future intents,
-and deposits findings to `resources/discovery--<slug>.md` in the intent directory ONLY. It
-never writes the intent file, `spec.md`, or any other lifecycle deliverable; the Why-stage
-`plastic-brainstorming` agent reads its deposit and enriches `## Context`.
+**`plastic-intent-discovery`.** The What-stage agent. It fires at intent activation, after the
+delivery lock is armed and before Why begins, running under that lock as the owner session (it
+does not acquire the lock itself and is not blocked by it): it reads the intent's
+`chain`/`sources` frontmatter, runs QMD-first discovery over completed predecessor work and
+related parked or future intents, and deposits findings to `resources/discovery--<slug>.md` in
+the intent directory ONLY. It never writes the intent file, `spec.md`, or any other lifecycle
+deliverable; the Why-stage `plastic-brainstorming` agent reads its deposit and enriches
+`## Context`.
 
 `savepoint.md` — a deterministic, append-only ledger of cycle-step milestones (one line per
 lifecycle boundary, newest at the bottom), written automatically by the gate hook. It is

package/agents/plastic-intent-discovery.md

@@ -7,13 +7,14 @@ description: |
   <example>Context: An intent is being moved from Future to Active.
   user: "Board this intent and gather what we already know"
   assistant: "I'll use the intent-discovery agent to run QMD discovery and deposit findings to resources/"
-  <commentary>What-stage discovery runs at activation, before the lock and Why.</commentary></example>
+  <commentary>What-stage discovery runs at activation, after the lock is armed, under it.</commentary></example>
 model: sonnet
 ---
 
 You are the Plastic Intent Discovery agent. You own the What stage: at intent
-activation, before the lock is armed and Why begins, you gather the context
-that already exists and deposit it for the Why stage to consume.
+activation, after the lock is armed and before Why begins, under the lock as
+the owner session, you gather the context that already exists and deposit it
+for the Why stage to consume.
 
 ## Responsibilities
 1. **Read the intent's links.** Load the activating intent file's `chain` and
@@ -32,6 +33,8 @@ that already exists and deposit it for the Why stage to consume.
 ## Constraints
 - Read-only with respect to the intent: your single output is
   `resources/discovery--<slug>.md`.
-- Never take the delivery lock; you run before it is armed.
+- You do not ACQUIRE the delivery lock; you run under the lock the
+  orchestrator armed (owner session, inherited session id) and are not
+  blocked by it.
 - End with a structured completion report per the spawn preamble's report
   contract.

package/bin/plastic.js

@@ -50,8 +50,12 @@ try {
   })
 } catch (err) {
   if (err.status) process.exit(err.status)
-  console.error('Error: Ruby is required to run Plastic.')
-  console.error('  macOS: Ruby is pre-installed')
-  console.error('  Linux: sudo apt install ruby / dnf install ruby')
+  // Ruby cannot run to print its own message when it is missing, so this
+  // mirrors scripts/lib/preflight.rb's FATAL block word for word.
+  console.error('Plastic needs Ruby 3.0.0 or newer to run its scripts (found not found).')
+  console.error('Install a pinned Ruby with mise:')
+  console.error('  curl https://mise.run | sh        # only if mise is not installed yet')
+  console.error('  mise use --global ruby@3.3')
+  console.error('Then re-run the Plastic installer.')
   process.exit(1)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.34",
+  "version": "1.0.0-beta.35",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/install.rb

@@ -14,6 +14,7 @@
 # so install.rb is the single file-syncer; the ledger action is contextual.
 
 require_relative "lib/installer_core"
+require_relative "lib/preflight"
 
 class Install < InstallerCore
   def cli(argv = ARGV)
@@ -22,6 +23,9 @@ class Install < InstallerCore
       return 0
     end
 
+    gate = preflight_gate
+    return gate unless gate.zero?
+
     force = argv.include?("--force")
     reinstall = argv.include?("--reinstall")
     ledger_action = flag_value(argv, "--ledger-action")
@@ -42,19 +46,19 @@ class Install < InstallerCore
       return 1
     end
 
-    run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action)
+    run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action, argv: argv)
     0
   end
 
   # Hermetic entrypoint (no prompting / no exit). Returns the per-agent results array.
-  def run(selected:, force: false, reinstall: false, ledger_action: nil)
+  def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin)
     fresh = !installed?
     mode = fresh ? :install : :update # :update here means "re-sync, skip bootstrap"
 
     distribute(mode)
     bootstrap if fresh
 
-    results = selected.map { |key| install_for_agent(key, force) }
+    results = selected.map { |key| install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall) }
 
     action = ledger_action || (fresh ? "install" : "reinstall")
     ledger_append(version, action)
@@ -72,8 +76,37 @@ class Install < InstallerCore
     File.exist?(path) ? File.read(path).strip : nil
   end
 
+  # Injectable pre-flight gate: real probes as default args, printing to an
+  # injectable `out:` IO so this is hermetically testable via StringIO. Returns
+  # 1 (stop the install) when Ruby is missing/too-old, else 0.
+  def preflight_gate(ruby_version: RUBY_VERSION, node_version: node_probe, git_present: git_probe,
+                      mise_present: mise_probe, out: $stderr)
+    result = Preflight.check(ruby_version: ruby_version, node_version: node_version,
+                              git_present: git_present, mise_present: mise_present)
+    result[:messages].each { |message| out.puts(message) }
+    result[:fatal] ? 1 : 0
+  end
+
   private
 
+  def node_probe
+    `node --version`.strip
+  rescue StandardError
+    ""
+  end
+
+  def git_probe
+    !`command -v git`.strip.empty?
+  rescue StandardError
+    false
+  end
+
+  def mise_probe
+    !`command -v mise`.strip.empty?
+  rescue StandardError
+    false
+  end
+
   def flag_value(argv, name)
     i = argv.index(name)
     return nil unless i && argv[i + 1]
@@ -119,9 +152,12 @@ class Install < InstallerCore
         --alpha       Alpha channel
 
       Other options:
-        --reinstall   Re-sync core files for the installed version (repair). Store untouched.
-        --force       Overwrite existing files without prompting
-        -h, --help    Show this help
+        --reinstall          Re-sync core files for the installed version (repair). Store untouched.
+        --force              Overwrite existing files without prompting
+        --statusline VALUE   keep or plastic. If an existing statusline is found, this
+                             skips the interactive prompt. Interactive sessions ask by
+                             default; non-interactive sessions default to keep.
+        -h, --help           Show this help
 
       Notes:
         Install is one-shot. If Plastic is already installed, use `update` to upgrade or

package/scripts/lib/bridge.rb

@@ -1173,7 +1173,11 @@ module Bridge
       c = line[i]
       case state
       when :single
-        out << " "
+        if c == "'" || c == "<" || c == ">"
+          out << " "
+        else
+          out << c
+        end
         state = :normal if c == "'"
         i += 1
       when :double
@@ -1181,7 +1185,11 @@ module Bridge
           out << "  "
           i += 2
         else
-          out << " "
+          if c == '"' || c == "<" || c == ">"
+            out << " "
+          else
+            out << c
+          end
           state = :normal if c == '"'
           i += 1
         end
@@ -1191,7 +1199,7 @@ module Bridge
         elsif c == '"'
           out << " "; state = :double; i += 1
         elsif c == "<" && line[i + 1] == "<"
-          m = line[i..].match(/\A<<(-?)\s*("|')?([A-Za-z_][A-Za-z0-9_]*)\2?/)
+          m = line[i..].match(/\A<<(-?)\s*("|')?([A-Za-z0-9_][A-Za-z0-9_]*)\2?/)
           if m
             openers << { word: m[3], dash: m[1] == "-" }
             out << (" " * m[0].length)

package/scripts/lib/installer_core.rb

@@ -161,6 +161,37 @@ class InstallerCore
     nums.select { |n| n >= 1 && n <= agents.size }.map { |n| agents[n - 1][:key] }
   end
 
+  # Resolve whether install should keep the user's existing statusline or switch it
+  # to Plastic's. Pure function of (settings file, argv, input, reinstall): no writes,
+  # so it stays fully unit-testable apart from merge_claude_hooks.
+  def statusline_choice(settings_path, argv: [], input: $stdin, reinstall: false)
+    existing_command = read_json_safe(settings_path)&.dig("statusLine", "command").to_s
+    return :plastic if existing_command.empty?
+    return :plastic if existing_command.include?("plastic-")
+
+    idx = argv.index("--statusline")
+    flag = idx && argv[idx + 1]
+    return flag.to_sym if %w[keep plastic].include?(flag)
+
+    return :keep if reinstall
+    return prompt_statusline(input: input) if input.tty?
+
+    :keep
+  end
+
+  def prompt_statusline(input: $stdin)
+    return :keep unless input.tty?
+
+    puts "An existing statusline was found in your settings.\n\n"
+    puts "  1. Keep my statusline (Plastic will not change it)"
+    puts "  2. Switch to Plastic's statusline"
+    puts
+    print "Select (1 or 2, Enter to keep): "
+    answer = input.gets&.strip
+
+    answer == "2" ? :plastic : :keep
+  end
+
   # --- Distribution phase ---
 
   def distribute(mode)
@@ -249,6 +280,7 @@ class InstallerCore
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",
+      "scripts/lib/preflight.rb" => "scripts/lib/preflight.rb",
       "scripts/install.rb" => "scripts/install.rb",
       "scripts/update.rb" => "scripts/update.rb",
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
@@ -321,7 +353,7 @@ class InstallerCore
     (data["files"] || {}).keys
   end
 
-  def install_for_agent(key, force)
+  def install_for_agent(key, force, argv: [], input: $stdin, reinstall: false)
     config = agent_config(key)
     return { agent: config[:name], success: false, reason: "Unknown agent" } unless config
 
@@ -334,7 +366,7 @@ class InstallerCore
     old_files = manifest_files(manifest_path_for(key, config))
 
     result = case key
-             when "claude" then install_claude(config, force)
+             when "claude" then install_claude(config, force, argv: argv, input: input, reinstall: reinstall)
              when "codex" then install_codex(config, force)
              when "hermes" then install_hermes(config, force)
              end
@@ -363,7 +395,7 @@ class InstallerCore
     removed
   end
 
-  def install_claude(config, force)
+  def install_claude(config, force, argv: [], input: $stdin, reinstall: false)
     hooks_dir = File.join(config[:dir], "hooks")
     skills_root = File.join(config[:dir], "skills")
     plastic_dir = File.join(config[:dir], "plastic")
@@ -406,7 +438,8 @@ class InstallerCore
 
     # Merge hooks + statusline into settings.json (no plugin registration)
     settings_path = File.join(config[:dir], "settings.json")
-    merge_claude_hooks(settings_path)
+    choice = statusline_choice(settings_path, argv: argv, input: input, reinstall: reinstall)
+    merge_claude_hooks(settings_path, choice: choice)
 
     # Write manifest
     manifest_path = File.join(plastic_dir, "manifest.json")
@@ -572,7 +605,7 @@ class InstallerCore
 
   # --- settings.json merge (read-modify-write, never clobber) ---
 
-  def merge_claude_hooks(settings_path)
+  def merge_claude_hooks(settings_path, choice: :plastic)
     settings = read_json_safe(settings_path) || {}
     return if settings.nil?
 
@@ -614,7 +647,7 @@ class InstallerCore
       File.write(File.join(cache_dir, "original-statusline.json"), JSON.pretty_generate(existing_status))
     end
 
-    settings["statusLine"] = { "type" => "command", "command" => "#{hook_dir}/plastic-statusline" }
+    settings["statusLine"] = { "type" => "command", "command" => "#{hook_dir}/plastic-statusline" } if choice == :plastic
 
     # No plugin/marketplace registration: skills are flat personal skills
     # (plastic-<name>/) discovered directly from ~/.claude/skills.

package/scripts/lib/preflight.rb

@@ -0,0 +1,79 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "rubygems"
+
+# Pure, dependency-injected pre-flight checks for Plastic's runtime dependencies
+# (intent 38). Takes injected probes (ruby version, node version, git presence,
+# mise presence) and returns a plain decision: ok / fatal plus branded messages.
+#
+# No I/O, no shelling out, no ENV reads here. Callers (scripts/install.rb,
+# bin/plastic.js) own the impure probing and the printing, so this module stays
+# hermetically testable. Voice matches boot_banner.rb (understated, "Plastic ..."
+# prefix); no em-dash, no en-dash in any message.
+module Preflight
+  module_function
+
+  RUBY_FLOOR = "3.0.0"
+  NODE_FLOOR = 18
+  RUBY_PIN = "3.3"
+
+  def check(ruby_version:, node_version:, git_present:, mise_present:)
+    messages = []
+
+    ruby_message = ruby_issue(ruby_version, mise_present)
+    fatal = !ruby_message.nil?
+    messages << ruby_message if ruby_message
+
+    node_message = node_issue(node_version)
+    messages << node_message if node_message
+
+    git_message = git_issue(git_present)
+    messages << git_message if git_message
+
+    { ok: messages.empty?, fatal: fatal, messages: messages }
+  end
+
+  def ruby_issue(ruby_version, mise_present)
+    parsed = safe_version(ruby_version)
+    return nil if parsed && parsed >= safe_version(RUBY_FLOOR)
+
+    lines = []
+    lines << "Plastic needs Ruby #{RUBY_FLOOR} or newer to run its scripts (found #{found(ruby_version)})."
+    lines << "Install a pinned Ruby with mise:"
+    lines << "  curl https://mise.run | sh        # only if mise is not installed yet" unless mise_present
+    lines << "  mise use --global ruby@#{RUBY_PIN}"
+    lines << "Then re-run the Plastic installer."
+    lines.join("\n")
+  end
+
+  def node_issue(node_version)
+    parsed = safe_version(strip_leading_v(node_version))
+    return nil if parsed && parsed >= safe_version(NODE_FLOOR.to_s)
+
+    "Plastic works best on Node #{NODE_FLOOR} or newer (found #{found(node_version)}). " \
+      "Pin it with mise: mise use --global node@25"
+  end
+
+  def git_issue(git_present)
+    return nil if git_present
+
+    "Plastic uses git for its store and worktrees (git was not found). " \
+      "Install git, e.g. macOS: xcode-select --install"
+  end
+
+  def safe_version(str)
+    Gem::Version.new(str.to_s)
+  rescue ArgumentError
+    nil
+  end
+
+  def strip_leading_v(str)
+    str.to_s.strip.sub(/\Av/, "")
+  end
+
+  def found(value)
+    text = value.to_s.strip
+    text.empty? ? "not found" : text
+  end
+end

package/skills/doctor/SKILL.md

@@ -3,7 +3,7 @@ name: plastic-doctor
 description: Use when diagnosing Plastic installation health, after updates, or when something seems broken. Runs checks and reports findings with fix options.
 ---
 
-# Doctor — Plastic Health Check
+# Doctor: Plastic Health Check
 
 ## Scopes
 
@@ -67,9 +67,9 @@ Parse the JSON output from stdout. The script is read-only and never modifies
 files. Errors go to stderr.
 
 Exit codes indicate check results, not script failure:
-- `0` — all checks passed
-- `1` — warnings found
-- `2` — failures found
+- `0`: all checks passed
+- `1`: warnings found
+- `2`: failures found
 
 All three exit codes mean the script ran successfully. Do not treat non-zero
 as an error.
@@ -118,7 +118,7 @@ Use the `fix_hint` value to determine the correct action:
 | "Remove stale references from INDEX.md" | Edit INDEX.md to remove ghost references |
 | "Inject the missing required frontmatter field(s)" | Edit the intent's `{ID}--{slug}.md` frontmatter to add the missing key (e.g. `chain: []`) without touching other keys |
 | "Run: provision-project-store {slug}" | Run `provision-project-store <slug>` (or invoke the `plastic-add-project-store` skill) to create the missing store |
-| "Re-run installer" | Run `npx @zalom/plastic@latest --agent` |
+| "Re-run installer" | Run `npx -y @zalom/plastic@<channel> install --agent <agent>` (channel: -alpha->@alpha, -beta->@beta, else @latest) |
 | "Dispatch plastic-intent-curator ... revisions.md ..." | Invoke the `plastic-intent-curator` (or the agent) to relocate the flagged section or ref into the intent's `revisions.md` via move-and-record (one dated, `[rule: <tag>]`-tagged entry per item), per PLASTIC.md > Structural maintenance and revisions.md. For a missing required section, restore or reproject it instead. |
 
 For fixes the agent cannot handle automatically, explain what the user needs
@@ -144,7 +144,7 @@ Show the updated results.
 When invoked from `plastic-update` (not directly by the user):
 
 1. Run the diagnostic script as in Step 1.
-2. If all checks pass: show a single line — **"Health check: all clear."**
+2. If all checks pass, show a single line: **"Health check: all clear."**
 3. If issues are found: show the full report (Steps 3-6).
 
 This keeps the update flow clean when nothing is wrong.

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/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.