@zalom/plastic 1.0.0-alpha.25 → 1.0.0-alpha.27

package/PLASTIC.md

@@ -184,6 +184,6 @@ Detailed conventions live inside the skills that use them, not in this file.
 | Projects, hubs | `plastic-creating-project` | hubs, project stores |
 | Index maintenance | `plastic-managing-index` | — |
 | Releases, deprecations | `plastic-releasing` | deprecation process |
-| Health diagnostics | `plastic-doctor` | gate enforcement, stuck detection |
+| Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
 | Writing agent instructions | `plastic-writing-instructions` | agentskills.io spec |
 | Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |

package/README.md

@@ -114,6 +114,11 @@ Or say "auto" to let the agent handle the full lifecycle autonomously.
 
 All conventions live in `AGENTS.md`, distributed to `~/.plastic/AGENTS.md`
 during installation. Run `plastic-doctor` to check installation health.
+`plastic-doctor --core` runs a binary install-integrity check (compares files
+against the install manifests; pass or error). `plastic-doctor --store` checks
+store state (intents, INDEX sections, conventions) and can be scoped to
+`global` or a project slug. The full `plastic-doctor` runs all checks and is
+run automatically after every update.
 
 ## License
 

package/package.json

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

package/scripts/dashboard.rb

@@ -22,6 +22,7 @@
 require "json"
 require "yaml"
 require "date"
+require_relative "doctor"
 
 PLASTIC_HOME = ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") }
 
@@ -449,6 +450,34 @@ def render_all(records)
   out.join("\n") + "\n"
 end
 
+# ---------------------------------------------------------------------------
+# Store health — runs doctor's scoped store check on dashboard load.
+#
+# Each board load runs `doctor --store <scope>` (global board -> :global,
+# project board -> the slug) and surfaces a compact store-health line in the
+# payload. Invoked IN-PROCESS (Doctor.new + run_store_checks) rather than
+# shelling out: it is hermetic for tests (same PLASTIC_HOME), faster (no second
+# Ruby boot), and avoids parsing a subprocess's JSON. Non-fatal by contract: a
+# warn/fail result is data only and never crashes the board or changes its exit.
+# ---------------------------------------------------------------------------
+
+def store_health(scope)
+  result = Doctor.new(plastic_home: PLASTIC_HOME).run_store_checks(scope)
+  failing = (result[:checks] || []).reject { |c| c[:status] == "pass" }
+                                   .map { |c| c[:name] }
+  {
+    scope: scope.is_a?(Symbol) ? scope.to_s : scope,
+    status: result[:status],
+    summary: result[:summary],
+    failing_checks: failing,
+  }
+rescue StandardError => e
+  # Never let a store-health probe take down the dashboard.
+  { scope: scope.is_a?(Symbol) ? scope.to_s : scope,
+    status: "warn", summary: { pass: 0, warn: 1, fail: 0, total: 1 },
+    failing_checks: ["store_health_probe_error"], error: e.message }
+end
+
 # ---------------------------------------------------------------------------
 # Markdown-board data payload (intent 37) — heavy side; the skill fills a
 # Markdown template from this and presents it. Deterministic, golden-tested.
@@ -549,6 +578,7 @@ def render_data_global(records)
   matrix_pool = global.select { |r| actionable?(r) && r[:status] != "active" }
   projs = project_summaries(records)
   { mode: "global", date: today.to_s,
+    store_health: store_health(:global),
     recently_worked: recently_worked(records),
     matrix: matrix_data(matrix_pool),
     counts: counts_of(global),
@@ -564,6 +594,7 @@ def render_data_project(records, slug)
   scoped = records.select { |r| r[:scope] == scope }
   matrix_pool = scoped.select { |r| r[:status] == "future" }
   { mode: "project", date: today.to_s, slug: slug,
+    store_health: store_health(slug),
     description: short_description(scope),
     recently_worked: recently_worked(records, project_scope: scope),
     matrix: matrix_data(matrix_pool),
@@ -619,7 +650,14 @@ def main(argv)
   if json
     subset = mode == "project" ? records.select { |r| r[:scope] == "project:#{slug}" } : records
     label = mode == "project" ? "project:#{slug}" : "all"
-    puts JSON.pretty_generate(render_json(subset, label))
+    payload = render_json(subset, label)
+    # Run the scoped store check on load, mirroring the --data board path:
+    # project board -> the slug; global/continue board -> :global. The `all`
+    # manifest spans every store, so its store-health probe is left to the
+    # per-scope boards (keeping the all-scopes auto-mode contract stable).
+    payload[:store_health] = store_health(slug) if mode == "project"
+    payload[:store_health] = store_health(:global) if mode == "continue"
+    puts JSON.pretty_generate(payload)
     return 0
   end
 

package/scripts/doctor.rb

@@ -13,6 +13,9 @@ require "json"
 require "yaml"
 require "time"
 require "date"
+require "digest"
+
+require_relative "lib/qmd_sync"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -63,6 +66,12 @@ class Doctor
     agent = "claude"
     help = false
     core = false
+    # store flag representation:
+    #   nil        — --store not given
+    #   :all       — --store with no value (check every store)
+    #   :global    — --store global
+    #   "<slug>"   — --store <slug> (a single project)
+    store = nil
 
     i = 0
     while i < argv.length
@@ -78,6 +87,15 @@ class Doctor
       when "--core"
         core = true
         i += 1
+      when "--store"
+        nxt = argv[i + 1]
+        if nxt && !nxt.start_with?("-")
+          store = (nxt == "global") ? :global : nxt
+          i += 2
+        else
+          store = :all
+          i += 1
+        end
       when "--help", "-h"
         help = true
         i += 1
@@ -86,7 +104,7 @@ class Doctor
       end
     end
 
-    { agent: agent, help: help, core: core }
+    { agent: agent, help: help, core: core, store: store }
   end
 
   def show_help
@@ -99,8 +117,12 @@ class Doctor
 
       Options:
         --agent NAME    Agent to check: claude (default), codex, hermes
-        --core          Fast runtime-liveness check only (hooks, scripts, core files);
-                        skips the slow store/conventions/project inventory walks.
+        --core          Binary core sync check: verifies agent registration, core
+                        files, and that every manifest-tracked file matches its
+                        recorded SHA256. Exits 0 (pass) or 2 (fail); never warn.
+        --store [WHICH] Run only the store/conventions checks. WHICH may be:
+                        global (global store only), a project slug (that project
+                        only), or omitted (all stores). 3-state pass/warn/fail.
         -h, --help      Show this help
 
       Output:
@@ -301,10 +323,14 @@ class Doctor
 
   # --- Check category 2: Conventions ---
 
-  def check_conventions
+  # When `scopes` is a non-nil Array of scope strings (e.g. ["global"] or
+  # ["project:plastic"]), only intents whose :scope is in that list are checked.
+  # When nil (the default, used by the full run), every intent is checked.
+  def check_conventions(scopes: nil)
     checks = []
 
     intent_dirs = all_intent_dirs
+    intent_dirs = intent_dirs.select { |d| scopes.include?(d[:scope]) } unless scopes.nil?
     dirname_pattern = /^\w+--[\w-]+$/
 
     # intent_dirname
@@ -639,6 +665,84 @@ class Doctor
     checks
   end
 
+  # --- Check category: manifest sync (binary core integrity) ---
+
+  # Verify, for BOTH the global manifest and the agent-side manifest, that every
+  # file listed exists and its current SHA256 matches the recorded hash.
+  #   - GLOBAL manifest:    <plastic_home>/manifest.json
+  #   - AGENT-side manifest: claude -> <dir>/plastic/manifest.json
+  #                          other  -> <dir>/plastic-manifest.json
+  # Manifest format: { "version", "created", "files": { abs_path => sha256 } }.
+  # A missing manifest is a fail; any missing/mismatched listed file is a fail;
+  # otherwise a single pass per manifest.
+  def check_manifest_sync(agent_key)
+    checks = []
+
+    global_manifest = File.join(plastic_home, "manifest.json")
+    checks << verify_manifest(global_manifest, "global")
+
+    agent_dir = agents[agent_key][:dir]
+    agent_manifest = if agent_key == "claude"
+                       File.join(agent_dir, "plastic", "manifest.json")
+                     else
+                       File.join(agent_dir, "plastic-manifest.json")
+                     end
+    checks << verify_manifest(agent_manifest, "agent")
+
+    checks
+  end
+
+  # Check one manifest file. Returns a single check (pass or fail).
+  def verify_manifest(manifest_path, label)
+    unless File.exist?(manifest_path)
+      return check(
+        category: "manifest_sync", name: "#{label}_manifest", status: "fail",
+        message: "#{label} core manifest missing — re-run the Plastic installer",
+        details: [tilde(manifest_path)],
+        fixable: true, fix_hint: "Re-run the Plastic installer"
+      )
+    end
+
+    data = read_json_safe(manifest_path)
+    files = data.is_a?(Hash) ? data["files"] : nil
+    unless files.is_a?(Hash)
+      return check(
+        category: "manifest_sync", name: "#{label}_manifest", status: "fail",
+        message: "#{label} core manifest unreadable or malformed — re-run the Plastic installer",
+        details: [tilde(manifest_path)],
+        fixable: true, fix_hint: "Re-run the Plastic installer"
+      )
+    end
+
+    missing = []
+    mismatched = []
+    files.each do |path, recorded|
+      unless File.exist?(path)
+        missing << tilde(path)
+        next
+      end
+      actual = Digest::SHA256.file(path).hexdigest
+      mismatched << tilde(path) if actual != recorded
+    end
+
+    if missing.empty? && mismatched.empty?
+      check(
+        category: "manifest_sync", name: "#{label}_manifest", status: "pass",
+        message: "#{label} manifest: all #{files.size} tracked file(s) present and matching"
+      )
+    else
+      details = []
+      details += missing.map { |p| "missing: #{p}" }
+      details += mismatched.map { |p| "modified: #{p}" }
+      check(
+        category: "manifest_sync", name: "#{label}_manifest", status: "fail",
+        message: "#{label} manifest out of sync: #{missing.size} missing, #{mismatched.size} modified",
+        details: details,
+        fixable: true, fix_hint: "Re-run the Plastic installer to restore tracked files"
+      )
+    end
+  end
+
   # --- Check category 5: Project stores ---
 
   def check_project_stores
@@ -666,135 +770,140 @@ class Doctor
       return checks
     end
 
-    # Load INDEX.md content for cross-reference checks
-    index_path = File.join(plastic_home, "INDEX.md")
-    index_content = File.exist?(index_path) ? File.read(index_path) : ""
-
     projects.each do |slug, project_info|
-      project_dir = File.join(plastic_home, "projects", slug)
+      checks += check_project_store(slug, project_info)
+    end
 
-      # project_dir_exists
-      if File.directory?(project_dir)
-        checks << check(
-          category: "project_stores", name: "project_dir_exists", status: "pass",
-          message: "Project directory exists for '#{slug}'"
-        )
-      else
-        checks << check(
-          category: "project_stores", name: "project_dir_exists", status: "warn",
-          message: "Project directory missing for '#{slug}'",
-          details: [tilde(project_dir)],
-          fixable: true, fix_hint: "Create the project store directory: mkdir -p #{tilde(project_dir)}"
-        )
-      end
+    checks
+  end
 
-      # project_index
-      project_index = File.join(project_dir, "INDEX.md")
-      if File.exist?(project_index)
-        checks << check(
-          category: "project_stores", name: "project_index", status: "pass",
-          message: "INDEX.md exists for project '#{slug}'"
-        )
-      else
-        checks << check(
-          category: "project_stores", name: "project_index", status: "warn",
-          message: "INDEX.md missing for project '#{slug}'",
-          details: [tilde(project_index)],
-          fixable: true, fix_hint: "Create INDEX.md in the project store directory"
-        )
-      end
+  # Per-project validation extracted from check_project_stores so a single
+  # project can be checked in isolation (used by `--store <slug>`).
+  def check_project_store(slug, project_info)
+    checks = []
+    project_dir = File.join(plastic_home, "projects", slug)
 
-      # project_yml_exists
-      project_yml_path = File.join(plastic_home, "projects", slug, "project.yml")
-      project_yml_data = nil
+    # project_dir_exists
+    if File.directory?(project_dir)
+      checks << check(
+        category: "project_stores", name: "project_dir_exists", status: "pass",
+        message: "Project directory exists for '#{slug}'"
+      )
+    else
+      checks << check(
+        category: "project_stores", name: "project_dir_exists", status: "warn",
+        message: "Project directory missing for '#{slug}'",
+        details: [tilde(project_dir)],
+        fixable: true, fix_hint: "Create the project store directory: mkdir -p #{tilde(project_dir)}"
+      )
+    end
 
-      if File.exist?(project_yml_path)
-        checks << check(
-          category: "project_stores", name: "project_yml_exists", status: "pass",
-          message: "project.yml exists for project '#{slug}'"
-        )
-        project_yml_data = load_yaml_safe(project_yml_path)
-      else
-        checks << check(
-          category: "project_stores", name: "project_yml_exists", status: "warn",
-          message: "project.yml missing for project '#{slug}'",
-          fixable: true, fix_hint: "Create project.yml from template — see plastic-creating-project"
-        )
-      end
+    # project_index
+    project_index = File.join(project_dir, "INDEX.md")
+    if File.exist?(project_index)
+      checks << check(
+        category: "project_stores", name: "project_index", status: "pass",
+        message: "INDEX.md exists for project '#{slug}'"
+      )
+    else
+      checks << check(
+        category: "project_stores", name: "project_index", status: "warn",
+        message: "INDEX.md missing for project '#{slug}'",
+        details: [tilde(project_index)],
+        fixable: true, fix_hint: "Create INDEX.md in the project store directory"
+      )
+    end
+
+    # project_yml_exists
+    project_yml_path = File.join(plastic_home, "projects", slug, "project.yml")
+    project_yml_data = nil
+
+    if File.exist?(project_yml_path)
+      checks << check(
+        category: "project_stores", name: "project_yml_exists", status: "pass",
+        message: "project.yml exists for project '#{slug}'"
+      )
+      project_yml_data = load_yaml_safe(project_yml_path)
+    else
+      checks << check(
+        category: "project_stores", name: "project_yml_exists", status: "warn",
+        message: "project.yml missing for project '#{slug}'",
+        fixable: true, fix_hint: "Create project.yml from template — see plastic-creating-project"
+      )
+    end
 
-      # governing_docs_exist
-      if project_yml_data.is_a?(Hash) && project_yml_data["governing_docs"].is_a?(Array) && !project_yml_data["governing_docs"].empty?
-        project_path = project_info.is_a?(Hash) ? project_info["path"] : nil
-
-        if project_path
-          missing_docs = project_yml_data["governing_docs"].reject do |doc_path|
-            File.exist?(File.join(project_path, doc_path))
-          end
-
-          if missing_docs.empty?
-            checks << check(
-              category: "project_stores", name: "governing_docs_exist", status: "pass",
-              message: "All governing docs exist for project '#{slug}'"
-            )
-          else
-            checks << check(
-              category: "project_stores", name: "governing_docs_exist", status: "warn",
-              message: "#{missing_docs.size} governing doc(s) missing for project '#{slug}'",
-              details: missing_docs,
-              fixable: false
-            )
-          end
+    # governing_docs_exist
+    if project_yml_data.is_a?(Hash) && project_yml_data["governing_docs"].is_a?(Array) && !project_yml_data["governing_docs"].empty?
+      project_path = project_info.is_a?(Hash) ? project_info["path"] : nil
+
+      if project_path
+        missing_docs = project_yml_data["governing_docs"].reject do |doc_path|
+          File.exist?(File.join(project_path, doc_path))
+        end
+
+        if missing_docs.empty?
+          checks << check(
+            category: "project_stores", name: "governing_docs_exist", status: "pass",
+            message: "All governing docs exist for project '#{slug}'"
+          )
+        else
+          checks << check(
+            category: "project_stores", name: "governing_docs_exist", status: "warn",
+            message: "#{missing_docs.size} governing doc(s) missing for project '#{slug}'",
+            details: missing_docs,
+            fixable: false
+          )
         end
       end
+    end
 
-      # cross_references — if project has `parent` field, check global store intent tags
-      parent_id = project_info.is_a?(Hash) ? project_info["parent"] : nil
-      next unless parent_id
+    # cross_references — if project has `parent` field, check global store intent tags
+    parent_id = project_info.is_a?(Hash) ? project_info["parent"] : nil
+    return checks unless parent_id
 
-      # Find the intent directory for the parent ID
-      store_dir = File.join(plastic_home, "store")
-      parent_dir = nil
-      if File.directory?(store_dir)
-        parent_dir = Dir.children(store_dir).find { |d| d.start_with?("#{parent_id}--") }
-      end
+    # Find the intent directory for the parent ID
+    store_dir = File.join(plastic_home, "store")
+    parent_dir = nil
+    if File.directory?(store_dir)
+      parent_dir = Dir.children(store_dir).find { |d| d.start_with?("#{parent_id}--") }
+    end
 
-      if parent_dir.nil?
-        checks << check(
-          category: "project_stores", name: "cross_references", status: "warn",
-          message: "Parent intent '#{parent_id}' for project '#{slug}' not found in global store",
-          fixable: false
-        )
-        next
-      end
+    if parent_dir.nil?
+      checks << check(
+        category: "project_stores", name: "cross_references", status: "warn",
+        message: "Parent intent '#{parent_id}' for project '#{slug}' not found in global store",
+        fixable: false
+      )
+      return checks
+    end
 
-      intent_md = File.join(store_dir, parent_dir, "#{parent_dir}.md")
-      fm = parse_frontmatter(intent_md)
+    intent_md = File.join(store_dir, parent_dir, "#{parent_dir}.md")
+    fm = parse_frontmatter(intent_md)
 
-      if fm.nil?
-        checks << check(
-          category: "project_stores", name: "cross_references", status: "warn",
-          message: "Cannot read frontmatter of parent intent '#{parent_id}' for project '#{slug}'",
-          fixable: false
-        )
-        next
-      end
+    if fm.nil?
+      checks << check(
+        category: "project_stores", name: "cross_references", status: "warn",
+        message: "Cannot read frontmatter of parent intent '#{parent_id}' for project '#{slug}'",
+        fixable: false
+      )
+      return checks
+    end
 
-      tags = fm["tags"]
-      expected_tag = "project-#{slug}"
+    tags = fm["tags"]
+    expected_tag = "project-#{slug}"
 
-      if tags.is_a?(Array) && tags.include?(expected_tag)
-        checks << check(
-          category: "project_stores", name: "cross_references", status: "pass",
-          message: "Parent intent '#{parent_id}' has '#{expected_tag}' tag for project '#{slug}'"
-        )
-      else
-        checks << check(
-          category: "project_stores", name: "cross_references", status: "warn",
-          message: "Parent intent '#{parent_id}' missing '#{expected_tag}' tag",
-          details: ["Intent: store/#{parent_dir}", "Expected tag: #{expected_tag}", "Current tags: #{(tags || []).inspect}"],
-          fixable: false
-        )
-      end
+    if tags.is_a?(Array) && tags.include?(expected_tag)
+      checks << check(
+        category: "project_stores", name: "cross_references", status: "pass",
+        message: "Parent intent '#{parent_id}' has '#{expected_tag}' tag for project '#{slug}'"
+      )
+    else
+      checks << check(
+        category: "project_stores", name: "cross_references", status: "warn",
+        message: "Parent intent '#{parent_id}' missing '#{expected_tag}' tag",
+        details: ["Intent: store/#{parent_dir}", "Expected tag: #{expected_tag}", "Current tags: #{(tags || []).inspect}"],
+        fixable: false
+      )
     end
 
     checks
@@ -898,6 +1007,48 @@ class Doctor
     a_pre <=> b_pre
   end
 
+  # --- Check category: QMD integration (read-only, optional) ---
+  #
+  # QMD is an optional integration. When `qmd` is not on PATH we emit a single
+  # passing check and never fail — its absence is not a Plastic health problem.
+  # When present, we report whether every Plastic store is registered as a QMD
+  # collection. Everything here is read-only; we never invoke a mutating qmd
+  # subcommand. detector/runner are injectable so tests stay hermetic.
+  def check_qmd(detector: QmdSync.method(:detect), runner: QmdSync.default_runner)
+    return [absent_qmd_check] unless detector.call
+
+    checks = [check(
+      category: "qmd", name: "present", status: "pass",
+      message: "QMD installed"
+    )]
+
+    status = QmdSync.status(plastic_home: plastic_home, runner: runner, detector: detector)
+    missing = status[:missing] || []
+
+    if status[:all_registered]
+      checks << check(
+        category: "qmd", name: "collections", status: "pass",
+        message: "All #{status[:expected].size} Plastic store(s) registered as QMD collections"
+      )
+    else
+      checks << check(
+        category: "qmd", name: "collections", status: "warn",
+        message: "#{missing.size} Plastic store(s) not registered as QMD collections",
+        details: missing,
+        fixable: true, fix_hint: "Run: qmd-sync register --all"
+      )
+    end
+
+    checks
+  end
+
+  def absent_qmd_check
+    check(
+      category: "qmd", name: "present", status: "pass",
+      message: "QMD not installed (optional integration)"
+    )
+  end
+
   # --- Run all checks ---
 
   def run_checks(agent_key)
@@ -908,28 +1059,72 @@ class Doctor
     all_checks += check_core_files(agent_key)
     all_checks += check_project_stores
     all_checks += check_deprecations
+    all_checks += check_qmd
 
     summarize(all_checks, agent_key)
   end
 
-  # Fast runtime-liveness check: only the plumbing that proves Plastic can
-  # operate (hooks, skills, scripts, core files). Skips the slow inventory
-  # walks (global store refs, per-intent conventions, project stores,
-  # deprecations) so it returns near-instantly. Used by `doctor.rb --core`.
+  # Binary core sync check: agent registration + core files + manifest sync,
+  # rolled up with binary: true so ANY warn or fail makes the overall status
+  # "fail" (and "warn" is never emitted). Used by `doctor.rb --core`.
   def run_core_checks(agent_key)
     all_checks = []
     all_checks += check_agent_registration(agent_key)
     all_checks += check_core_files(agent_key)
+    all_checks += check_manifest_sync(agent_key)
 
-    summarize(all_checks, agent_key)
+    summarize(all_checks, agent_key, binary: true)
+  end
+
+  # Store-scoped checks for `doctor.rb --store [global|<slug>]`.
+  #   :all     -> global store + all project stores + all conventions
+  #   :global  -> global store + conventions scoped to ["global"]
+  #   "<slug>" -> that project only + conventions scoped to ["project:<slug>"]
+  #               (fail if the slug is not registered in projects.yml)
+  # 3-state roll-up (pass/warn/fail), like the full run.
+  def run_store_checks(store)
+    all_checks =
+      case store
+      when :all
+        check_global_store + check_project_stores + check_conventions
+      when :global
+        check_global_store + check_conventions(scopes: ["global"])
+      else
+        all_checks_for_project_slug(store)
+      end
+
+    summarize(all_checks, "claude", binary: false)
+  end
+
+  # Build the checks for a single project slug, or a lone fail check when the
+  # slug is unknown.
+  def all_checks_for_project_slug(slug)
+    projects_data = load_yaml_safe(File.join(plastic_home, "projects.yml"))
+    projects = projects_data.is_a?(Hash) ? projects_data["projects"] : nil
+
+    unless projects.is_a?(Hash) && projects.key?(slug)
+      return [check(
+        category: "project_stores", name: "unknown_project", status: "fail",
+        message: "unknown project '#{slug}'",
+        fixable: false
+      )]
+    end
+
+    check_project_store(slug, projects[slug]) +
+      check_conventions(scopes: ["project:#{slug}"])
   end
 
   # Roll a list of checks up into the standard result envelope.
-  def summarize(all_checks, agent_key)
+  # When binary: true, the overall status is "pass" only if there are zero warn
+  # AND zero fail; any warn or fail yields "fail" (never "warn"). When false
+  # (the default) the classic 3-state pass/warn/fail roll-up is used.
+  def summarize(all_checks, agent_key, binary: false)
     summary = { pass: 0, warn: 0, fail: 0, total: all_checks.size }
     all_checks.each { |c| summary[c[:status].to_sym] += 1 }
 
-    overall = if summary[:fail] > 0
+    overall = if binary
+                (summary[:fail] > 0 || summary[:warn] > 0) ? "fail" : "pass"
+              elsif summary[:fail] > 0
                 "fail"
               elsif summary[:warn] > 0
                 "warn"
@@ -957,10 +1152,19 @@ class Doctor
       exit 0
     end
 
-    result = flags[:core] ? run_core_checks(flags[:agent]) : run_checks(flags[:agent])
+    result =
+      if !flags[:store].nil?
+        run_store_checks(flags[:store])
+      elsif flags[:core]
+        run_core_checks(flags[:agent])
+      else
+        run_checks(flags[:agent])
+      end
 
     puts JSON.pretty_generate(result)
 
+    # --core is binary: status is only ever pass|fail, so this maps to 0|2.
+    # --store and the full run keep the 3-state 0/1/2 mapping.
     case result[:status]
     when "fail" then exit 2
     when "warn" then exit 1

package/scripts/hook-session-start

@@ -8,6 +8,7 @@ require "date"
 require "yaml"
 require_relative "lib/bridge"
 require_relative "lib/boot_banner"
+require_relative "lib/qmd_sync"
 require_relative "doctor"
 
 index_path, store_root, mode, plugin_root = ARGV
@@ -204,6 +205,25 @@ parts = []
 parts << core_banner
 parts << ""
 
+# --- QMD search status (intent 45a, READ-ONLY) ---
+# Report-only line for the model (additionalContext), never systemMessage and
+# never the exit code. QmdSync.status shells out to `qmd collection list`, so the
+# whole block is guarded: a 2s timeout caps any hang, and rescue-all guarantees a
+# slow/broken/missing qmd appends nothing and the hook continues cleanly.
+begin
+  require "timeout"
+  qmd_status = Timeout.timeout(2) { QmdSync.status(plastic_home: store_root) }
+  if qmd_status[:present]
+    if qmd_status[:all_registered]
+      parts << "QMD: #{qmd_status[:registered].size} Plastic collections indexed (search with the qmd skill)."
+    else
+      parts << "QMD detected — run `qmd-sync register --all` to index your Plastic stores for search."
+    end
+  end
+rescue Exception
+  # Any failure (timeout, missing binary, parse error) — stay silent, never crash.
+end
+
 if plastic_md
   # Conventions always loaded first
   parts << plastic_md

package/scripts/lib/boot_banner.rb

@@ -13,24 +13,16 @@ module BootBanner
   # health: the Hash returned by Doctor#run_core_checks, or nil if the check
   #         itself raised (degraded to an error banner).
   # version: the installed Plastic version string, or nil.
+  #
+  # Returns one of two binary lines:
+  #   "Plastic Core loaded — v{VER} | doctor --core run: success"
+  #   "Plastic Core loaded — v{VER} | doctor --core run: error — run /plastic-doctor"
   def render(health:, version:)
-    return "Plastic Core: health check error — run /plastic-doctor" if health.nil?
-
-    if health[:status] == "pass"
-      "Plastic Core loaded — v#{version || "unknown"}"
+    ver = version || "unknown"
+    if !health.nil? && health[:status] == "pass"
+      "Plastic Core loaded — v#{ver} | doctor --core run: success"
     else
-      bad = first_problem(health[:checks])
-      if bad
-        "Plastic Core loaded with issues — #{bad[:name]}: #{bad[:message]} — run /plastic-doctor"
-      else
-        "Plastic Core loaded with issues — run /plastic-doctor"
-      end
+      "Plastic Core loaded — v#{ver} | doctor --core run: error — run /plastic-doctor"
     end
   end
-
-  # First failing check, else first warning, else nil.
-  def first_problem(checks)
-    checks = checks || []
-    checks.find { |c| c[:status] == "fail" } || checks.find { |c| c[:status] == "warn" }
-  end
 end

package/scripts/lib/installer_core.rb

@@ -177,6 +177,11 @@ class InstallerCore
 
     Dir.glob(File.join(plastic_home, "scripts", "*")).each { |f| FileUtils.chmod(0o755, f) if File.file?(f) }
 
+    global_files = core_files.values.map { |d| File.join(plastic_home, d) }
+    global_files << File.join(plastic_home, "VERSION")
+    global_files = global_files.select { |p| File.exist?(p) }
+    write_manifest(global_files, File.join(plastic_home, "manifest.json"))
+
     puts "  \u{2705} Core files synced (v#{version})"
   end
 
@@ -199,6 +204,8 @@ class InstallerCore
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
+      "scripts/lib/qmd_sync.rb" => "scripts/lib/qmd_sync.rb",
+      "scripts/qmd-sync" => "scripts/qmd-sync",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",
       "scripts/install.rb" => "scripts/install.rb",
       "scripts/update.rb" => "scripts/update.rb",

package/scripts/lib/qmd_sync.rb

@@ -0,0 +1,160 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+
+# QmdSync — the single place Plastic talks to QMD (intent 45a).
+#
+# Plastic computes only the Plastic-specific inputs (which store directory maps to
+# which `plastic-`prefixed collection, derived from projects.yml, plus a short
+# context description). The actual indexing is delegated to the `qmd` CLI; this
+# module never reimplements QMD's logic. QMD is optional: every public entry
+# no-ops cleanly when `qmd` is not on PATH.
+#
+# Pure and dependency-injected: all shelling-out goes through an injected
+# `runner` callable, so the whole module is unit-testable with no real binary,
+# no network, and no model downloads. The default runner shells out to `qmd`.
+module QmdSync
+  module_function
+
+  CONTEXT_DESCRIPTION =
+    "Plastic intent store: intents, specs, plans, checklists, outcomes, and insights " \
+    "for the What/Why/How/Exec lifecycle. Search here for past decisions and work."
+
+  # A runner is `->(args_array) { [stdout_string, success_boolean] }`.
+  # The default invokes the real `qmd` binary.
+  def default_runner
+    lambda do |args|
+      require "open3"
+      out, _err, status = Open3.capture3("qmd", *args)
+      [out, status.success?]
+    end
+  end
+
+  # True when `qmd` is resolvable on PATH. The probe is injectable so tests do
+  # not depend on the host having qmd installed.
+  def detect(path_probe: method(:which_qmd))
+    !!path_probe.call
+  end
+
+  def which_qmd
+    ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+      candidate = File.join(dir, "qmd")
+      File.file?(candidate) && File.executable?(candidate)
+    end
+  end
+
+  # Collection name for a store directory.
+  #   global store (<plastic_home>/store)        -> "plastic-global"
+  #   project store (<.../projects/<slug>/store) -> "plastic-<slug>"
+  # Slug is resolved from projects.yml by matching the project path; falls back
+  # to the directory's parent name when no registry match exists.
+  def collection_name(store_dir, plastic_home:)
+    store_dir = File.expand_path(store_dir)
+    global_store = File.expand_path(File.join(plastic_home, "store"))
+    return "plastic-global" if store_dir == global_store
+
+    slug = slug_for_store(store_dir, plastic_home: plastic_home)
+    "plastic-#{slug}"
+  end
+
+  # Every store Plastic knows about: the global store plus each registered
+  # project store. Returns [{collection:, dir:}, ...].
+  def enumerate_stores(plastic_home:)
+    stores = [{
+      collection: "plastic-global",
+      dir: File.expand_path(File.join(plastic_home, "store")),
+    }]
+
+    projects = load_projects(plastic_home)
+    projects.each do |slug, info|
+      path = info.is_a?(Hash) ? info["path"] : nil
+      next unless path
+      project_store = File.join(File.expand_path(path), "store")
+      # Project stores live under ~/.plastic/projects/<slug>/store as the mirror;
+      # registry `path` is the project code dir, so the tactical store is the
+      # plastic_home projects mirror.
+      mirror_store = File.expand_path(File.join(plastic_home, "projects", slug.to_s, "store"))
+      dir = Dir.exist?(mirror_store) ? mirror_store : project_store
+      stores << { collection: "plastic-#{slug}", dir: dir }
+    end
+    stores
+  end
+
+  # Register a store directory as a collection and attach the Plastic context
+  # description. Idempotent: re-running is safe. No-op when qmd is absent.
+  def register(collection:, dir:, runner: default_runner, context: CONTEXT_DESCRIPTION, detector: method(:detect))
+    return skip_result unless detector.call
+    out1, ok1 = runner.call(["collection", "add", dir, "--name", collection])
+    _out2, ok2 = runner.call(["context", "add", collection, context])
+    { ran: true, ok: (ok1 && ok2), output: out1.to_s.strip }
+  end
+
+  # Re-index a single collection: refresh the corpus then its embeddings.
+  # Scoped embed (-c) keeps delivery-time reindex fast. No-op when qmd absent.
+  def reindex(collection:, runner: default_runner, detector: method(:detect))
+    return skip_result unless detector.call
+    _o1, ok1 = runner.call(["update"])
+    _o2, ok2 = runner.call(["embed", "-c", collection])
+    { ran: true, ok: (ok1 && ok2) }
+  end
+
+  # Read-only status used by doctor and the session-start report line.
+  # Returns a structured hash; never mutates the index.
+  def status(plastic_home:, runner: default_runner, detector: method(:detect))
+    return { present: false } unless detector.call
+
+    expected = enumerate_stores(plastic_home: plastic_home).map { |s| s[:collection] }
+    listed = list_collections(runner)
+    missing = expected - listed
+
+    { present: true, expected: expected, registered: listed,
+      missing: missing, all_registered: missing.empty? }
+  end
+
+  # --- internals ---
+
+  def skip_result
+    { ran: false, ok: true, skipped: true }
+  end
+
+  def list_collections(runner)
+    out, ok = runner.call(["collection", "list"])
+    return [] unless ok && out
+    # qmd prints lines like "plastic-global (qmd://plastic-global/)"; pull the
+    # leading collection token off each non-indented line.
+    out.lines.filter_map do |line|
+      next if line.start_with?(" ", "\t")
+      m = line.strip.match(/\A([A-Za-z0-9][\w.-]*)\b/)
+      m && m[1]
+    end.reject { |t| %w[Collections No].include?(t) }
+  end
+
+  def load_projects(plastic_home)
+    path = File.join(plastic_home, "projects.yml")
+    return {} unless File.exist?(path)
+    data = begin
+      YAML.safe_load(File.read(path)) || {}
+    rescue StandardError
+      {}
+    end
+    projects = data.is_a?(Hash) ? data["projects"] : nil
+    projects.is_a?(Hash) ? projects : {}
+  end
+
+  def slug_for_store(store_dir, plastic_home:)
+    projects = load_projects(plastic_home)
+    projects.each do |slug, info|
+      path = info.is_a?(Hash) ? info["path"] : nil
+      next unless path
+      project_root = File.expand_path(path)
+      mirror = File.expand_path(File.join(plastic_home, "projects", slug.to_s, "store"))
+      return slug.to_s if store_dir == File.join(project_root, "store") || store_dir == mirror
+    end
+    # Fallback: <...>/projects/<slug>/store -> slug, else parent dir name.
+    parts = store_dir.split(File::SEPARATOR)
+    idx = parts.rindex("projects")
+    return parts[idx + 1] if idx && parts[idx + 1] && parts[idx + 2] == "store"
+    File.basename(File.dirname(store_dir))
+  end
+end

package/scripts/qmd-sync

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# qmd-sync — deterministic CLI over QmdSync (intent 45a).
+#
+# Plastic skills and hooks call these verbs instead of assembling `qmd` commands
+# themselves. QMD is optional: when `qmd` is absent every verb exits 0 and prints
+# a skip notice, so callers can invoke unconditionally.
+#
+# Usage:
+#   qmd-sync detect                     # exit 0 if qmd present, 1 if absent
+#   qmd-sync register --store <dir>     # register one store as a collection
+#   qmd-sync register --all             # register the global store + all projects
+#   qmd-sync reindex --store <dir>      # update + embed that store's collection
+#   qmd-sync status [--format json]     # read-only status
+#
+# --home <path> overrides the Plastic home (default: ~/.plastic).
+
+require "json"
+require_relative "lib/qmd_sync"
+
+def plastic_home(args)
+  if (i = args.index("--home")) && args[i + 1]
+    File.expand_path(args[i + 1])
+  else
+    File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
+  end
+end
+
+def opt(args, name)
+  (i = args.index(name)) && args[i + 1]
+end
+
+verb = ARGV.shift
+home = plastic_home(ARGV)
+
+unless QmdSync.detect
+  case verb
+  when "detect"
+    warn "QMD not detected on PATH."
+    exit 1
+  else
+    puts "QMD not detected; skipped (#{verb})."
+    exit 0
+  end
+end
+
+case verb
+when "detect"
+  puts "QMD detected."
+  exit 0
+
+when "register"
+  stores =
+    if ARGV.include?("--all")
+      QmdSync.enumerate_stores(plastic_home: home)
+    elsif (dir = opt(ARGV, "--store"))
+      [{ collection: QmdSync.collection_name(dir, plastic_home: home), dir: File.expand_path(dir) }]
+    else
+      warn "register: pass --store <dir> or --all"
+      exit 2
+    end
+  stores.each do |s|
+    next unless Dir.exist?(s[:dir])
+    res = QmdSync.register(collection: s[:collection], dir: s[:dir])
+    puts "registered #{s[:collection]} -> #{s[:dir]} (#{res[:ok] ? "ok" : "warn"})"
+  end
+  exit 0
+
+when "reindex"
+  dir = opt(ARGV, "--store") or (warn("reindex: pass --store <dir>"); exit 2)
+  collection = QmdSync.collection_name(dir, plastic_home: home)
+  res = QmdSync.reindex(collection: collection)
+  puts "reindexed #{collection} (#{res[:ok] ? "ok" : "warn"})"
+  exit 0
+
+when "status"
+  st = QmdSync.status(plastic_home: home)
+  if opt(ARGV, "--format") == "json"
+    puts JSON.generate(st)
+  else
+    puts "QMD present: #{st[:present]}"
+    puts "registered: #{Array(st[:registered]).join(", ")}"
+    puts "missing: #{Array(st[:missing]).join(", ")}" unless Array(st[:missing]).empty?
+  end
+  exit 0
+
+else
+  warn "qmd-sync: unknown verb #{verb.inspect}. Use detect|register|reindex|status."
+  exit 2
+end

package/scripts/update.rb

@@ -13,6 +13,7 @@
 # `install --reinstall --ledger-action update` for the chosen version via npx.
 
 require_relative "lib/installer_core"
+require_relative "doctor"
 
 class Update < InstallerCore
   PKG = "@zalom/plastic"
@@ -51,10 +52,31 @@ class Update < InstallerCore
         return 1
       end
       puts "\u{2b06}\u{fe0f}  Updating Plastic #{iv} \u{2192} #{res[:target]}"
-      perform_switch(res[:target], agent_args(argv))
+      exit_code = perform_switch(res[:target], agent_args(argv))
+      run_post_update_doctor if exit_code == 0
+      exit_code
     end
   end
 
+  # Run the full doctor after a successful update and print a human-readable
+  # summary. Informational only: does not raise and does not affect the update's
+  # exit code. Accepts injected `doctor` and `out` for hermetic unit tests.
+  def run_post_update_doctor(doctor: nil, out: $stdout)
+    doctor ||= Doctor.new
+    out.puts "\nRunning full doctor after update..."
+    result = doctor.run_checks("claude")
+    s = result[:summary]
+    out.puts "  Doctor status: #{result[:status]} " \
+             "(pass: #{s[:pass]}, warn: #{s[:warn]}, fail: #{s[:fail]}, total: #{s[:total]})"
+    out.puts "  Run /plastic-doctor for details." unless result[:status] == "pass"
+    result
+  rescue StandardError => e
+    # Non-blocking: a crash here (e.g. malformed file in the real store) must not
+    # undo or fail an update that already succeeded. Report and move on.
+    out.puts "  doctor could not run: #{e.message} — run /plastic-doctor"
+    nil
+  end
+
   # Pure decision logic (hermetically testable). Returns a status hash.
   def compute_target(installed_version:, dist_tags:, requested_channel: nil)
     installed_ch = channel_for(installed_version)

package/skills/auto/SKILL.md

@@ -161,11 +161,17 @@ During initial project creation, all decisions are non-destructive by definition
    - Update `chain` in the current intent's frontmatter
 6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
-8. Disarm the lifecycle gate (auto delivery is finished):
+8. Refresh the QMD search index for this store (optional, no-op when QMD is absent):
+   ```bash
+   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>
+   ```
+   Delivery is the lifecycle event that keeps the search index fresh. `<store-root>` is the
+   store that holds this intent (the global store or the project store).
+9. Disarm the lifecycle gate (auto delivery is finished):
    ```bash
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_SESSION_ID"])'
    ```
-9. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
+10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
 
 ## Error Handling
 

package/skills/continuing/SKILL.md

@@ -40,6 +40,11 @@ here — run the data payload and fill + present the matching template:
 Fill the matching template from this skill's `templates/` and **present the filled Markdown
 in your reply** (every time). See `plastic-dashboard` for the fill rules and entry flow.
 
+The board load runs the scoped store check on every load (`doctor --store <scope>`): the
+global board runs `--store global` and a project board runs `--store <slug>`. The result
+arrives in the payload as `store_health`; surface it as a one-line store-health note. It is
+non-fatal (a warn or fail is shown as data, it does not block continuing).
+
 ### Then stop
 Present "here is the state, what next?" and wait. Offer active intents first, then future
 intents. Do not start executing work. The branches below are the only follow-ups:

package/skills/creating-project/SKILL.md

@@ -157,7 +157,18 @@ cd ~/.plastic && git add . && git commit -m "feat: spawn project <slug> from int
 cd <project> && git add . && git commit -m "feat: initialize project from intent <ID>"
 ```
 
-### 10. Announce
+### 10. Register the project store with QMD (optional)
+
+If QMD is installed, register the new project's store as a search collection:
+
+```bash
+ruby ~/.plastic/scripts/qmd-sync register --store ~/.plastic/projects/<slug>/store
+```
+
+`qmd-sync` no-ops when QMD is absent, so run it unconditionally. This adds the
+`plastic-<slug>` collection and indexes it.
+
+### 11. Announce
 
 Log in `## Insights` of each founding intent:
 > "Project `<slug>` created at `<path>`. Tactical mirror: `project-<slug>:1` (autonomous)"

package/skills/dashboard/SKILL.md

@@ -32,10 +32,17 @@ ruby ~/.plastic/scripts/dashboard.rb [continue|project <slug>] --data
 - `continue` (default) → the **global** board payload (`mode: "global"`).
 - `project <slug>` → that **project** board payload (`mode: "project"`).
 
-The payload is read-only JSON. Global-board fields: `date`, `recently_worked`, `matrix`
-(`quick_win`/`next_big`/`defer`/`triage`/`research`, each a list of `{line, bullet, ...}`),
-`counts`, `projects`, `project_totals`. Project-board fields: `slug`, `description`,
-`recently_worked`, `matrix`, `counts`, `active`, `future`.
+The payload is read-only JSON. Global-board fields: `date`, `store_health`, `recently_worked`,
+`matrix` (`quick_win`/`next_big`/`defer`/`triage`/`research`, each a list of `{line, bullet, ...}`),
+`counts`, `projects`, `project_totals`. Project-board fields: `slug`, `store_health`,
+`description`, `recently_worked`, `matrix`, `counts`, `active`, `future`.
+
+Each board load runs the scoped store check (`doctor --store <scope>`): the global board runs
+`--store global` and a project board runs `--store <slug>`. The result rides in the payload as
+`store_health` (`{scope, status, summary, failing_checks}`). Surface it as a one-line
+store-health note on the board (for example `store health: pass (3/3)` or
+`store health: warn (orphaned_intents)`). It is non-fatal: a warn or fail is shown as data and
+never blocks the board.
 
 ### Step 2 — Fill the matching template
 

package/skills/doctor/SKILL.md

@@ -5,10 +5,51 @@ description: Use when diagnosing Plastic installation health, after updates, or
 
 # Doctor — Plastic Health Check
 
+## Scopes
+
+Doctor has three scopes. Pick the right one for the situation:
+
+| Scope | Flag | When it runs | States |
+|-------|------|--------------|--------|
+| Core check | `--core` | SessionStart hook (automatic), also available on demand | Binary: pass or error |
+| Store check | `--store [global\|<slug>]` | Dashboard load, `plastic-continuing` | Three-state: pass / warn / fail |
+| Full check | (no flag) | After every update (automatic), or `/plastic-doctor` | Three-state: pass / warn / fail |
+
+### `--core` (binary, manifest-backed)
+
+Verifies that every core file is present and content-matches what the installed
+version shipped. It checks two install manifests:
+
+- `~/.plastic/manifest.json` (global manifest, covers PLASTIC.md and global scripts)
+- `~/.claude/plastic/manifest.json` (agent-side manifest, covers agent scripts and hooks)
+
+Each manifest maps a file path to its SHA256. The core check also confirms hooks
+are registered, scripts are present and executable, and the installed version
+matches. Result is binary: exit 0 on pass, non-zero on error. It never produces
+warnings.
+
+### `--store [global|<slug>]`
+
+Checks store state: intents are well-formed, INDEX sections are present, conventions
+are followed, and links are valid. Scope options:
+
+- No argument: checks all stores (global and all projects)
+- `global`: checks only the global store
+- A project slug (e.g. `--store plastic`): checks only that project's store
+
+Produces three-state results (pass / warn / fail) and is run per-scope at dashboard
+load time: the global board uses `--store global`, a project board uses `--store <slug>`.
+
+### Full doctor (no flag)
+
+Runs core plus all store checks plus deprecation checks. This is what `/plastic-doctor`
+invokes. It also runs automatically after every `plastic-update` (informational,
+does not block or revert the update).
+
 ## When to Use
 
-- User invokes `/plastic-doctor`
-- After `plastic-update` completes (automatically)
+- User invokes `/plastic-doctor` (full check)
+- After `plastic-update` completes (automatically, full check)
 - When hooks aren't firing, skills aren't loading, or something seems broken
 - When the user says "check plastic", "diagnose", "what's wrong with plastic"
 

package/skills/doctor/report.md

@@ -7,6 +7,10 @@
   2. Replace every {{placeholder}} below with the corresponding JSON value.
   3. For the category sections: the template shows ONE example section.
      Repeat that pattern for each unique category in the checks array.
+     The scope determines which categories appear:
+       --core scope:      agent_registration, core_files (binary pass/error only)
+       --store scope:     global_store, conventions, project_stores
+       full (no flag):    all six categories below
      The six known categories and their display names are:
        global_store       -> "Global Store"
        conventions        -> "Conventions"

package/skills/executing-plan/SKILL.md

@@ -75,6 +75,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately — do not leave it for later.
 
@@ -100,6 +101,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** Complete the intent immediately when work is done.
 

package/skills/install/SKILL.md

@@ -153,7 +153,20 @@ Auto-commit the config change.
 Run `/plastic-doctor` and report the result. Resolve any fixable findings before
 announcing success.
 
-**Step 5: Announce**
+**Step 5: Register stores with QMD (optional)**
+
+QMD is an optional search layer. If it is installed, register the Plastic stores so
+they are searchable:
+
+```bash
+ruby ~/.plastic/scripts/qmd-sync detect && ruby ~/.plastic/scripts/qmd-sync register --all
+```
+
+`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.
+
+**Step 6: Announce**
 
 > "Plastic installed globally at ~/.plastic/. Health check: [doctor summary].
 > Create your first intent with `/plastic-creating-intent`."