@zalom/plastic 2.0.0-alpha.27 → 2.0.0-alpha.29

package/scripts/lib/cli/table.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Plastic::CLI::TABLE (intent 363) - the whole command line in one frozen hash:
+# a command name mapped to the file that holds it, the class inside
+# Plastic::CLI::Commands, and the one line `plastic help` prints beside it.
+#
+# Adding a command is one row here plus one file. `plastic help` reads this
+# hash and loads nothing, so listing the commands costs no command file.
+# test/cli/table_test.rb walks every row, so a half-wired command cannot ship.
+module Plastic
+  class CLI
+    TABLE = {
+      "auto brief" => ["commands/auto_brief", "AutoBrief", "Print an intent's spawn preamble, and the advisor shapes for --role advisor"],
+      "auto lock" => ["commands/auto_lock", "AutoLock", "Inspect, repair, or release an intent's delivery lock"],
+      "auto report" => ["commands/auto_report", "AutoReport", "Print an intent's completion report, then the review-by-risk rules"],
+      "auto take" => ["commands/auto_take", "AutoTake", "Arm an intent's delivery lock for this session"],
+      "auto" => ["commands/auto", "Auto", "List the auto subcommands"],
+      "backup" => ["commands/backup", "Backup", "Write one archive of the three databases and the config"],
+      "checkout" => ["commands/checkout", "Checkout", "Restore missing store files from the databases"],
+      "continue" => ["commands/continue", "Continue", "Show where one project stands and what runs next"],
+      "doctor" => ["commands/doctor", "Doctor", "Diagnose Plastic installation health"],
+      "feedback" => ["commands/feedback", "Feedback", "File a feedback report, body on standard input"],
+      "help" => ["commands/help", "Help", "List the commands and help topics, or show one usage"],
+      "hook" => ["commands/hook", "Hook", "Run one harness hook event through its launcher"],
+      "index" => ["commands/index", "Index", "Rebuild the search index from every markdown file in the stores"],
+      "install" => ["commands/install", "Install", "Install Plastic into this machine's agents"],
+      "intent" => ["commands/intent", "Intent", "List the intent subcommands"],
+      "intent answer" => ["commands/intent_answer", "IntentAnswer", "Answer an intent's needs_decision node"],
+      "intent end" => ["commands/intent_end", "IntentEnd", "Close an intent as delivered or abandoned"],
+      "intent new" => ["commands/intent_new", "IntentNew", "Create a new intent"],
+      "intent note" => ["commands/intent_note", "IntentNote", "Append a savepoint note to an intent"],
+      "intent rule" => ["commands/intent_rule", "IntentRule", "Record a ruling in an intent's Insights"],
+      "intent show" => ["commands/intent_show", "IntentShow", "Print an intent's state screen"],
+      "intent spec" => ["commands/intent_spec", "IntentSpec", "Print an intent's state screen, then the speccing rules"],
+      "intent step" => ["commands/intent_step", "IntentStep", "Run the next ready step of an intent's graph"],
+      "intent verify" => ["commands/intent_verify", "IntentVerify", "Run an intent's merge-gate checks"],
+      "migrate" => ["commands/migrate", "Migrate", "List the migrate subcommands"],
+      "migrate stores" => ["commands/migrate_stores", "MigrateStores", "Move the stores under stores/, behind a full copy of the home"],
+      "next" => ["commands/next", "Next", "Print the next action in one line"],
+      "project" => ["commands/project", "Project", "List the project subcommands"],
+      "project links" => ["commands/project_links", "ProjectLinks", "Project every store's Links sections from frontmatter"],
+      "project list" => ["commands/project_list", "ProjectList", "List every store this machine holds"],
+      "project new" => ["commands/project_new", "ProjectNew", "Register, provision and validate a new project"],
+      "query" => ["commands/query", "Query", "Run one read-only SQL statement on the index"],
+      "render" => ["commands/render", "Render", "Print one markdown file as an HTML page"],
+      "roadmap" => ["commands/roadmap", "Roadmap", "List the roadmap subcommands"],
+      "roadmap check" => ["commands/roadmap_check", "RoadmapCheck", "Check a roadmap's graph for cycles and dangling ids"],
+      "roadmap log" => ["commands/roadmap_log", "RoadmapLog", "Append a savepoint line to a roadmap's ledger"],
+      "roadmap next" => ["commands/roadmap_next", "RoadmapNext", "Name the roadmap most worth continuing"],
+      "roadmap show" => ["commands/roadmap_show", "RoadmapShow", "Print a roadmap's state screen"],
+      "rollback" => ["commands/rollback", "Rollback", "Move to a Plastic version this machine has run before"],
+      "search" => ["commands/search", "Search", "Find text in the stores, ranked, with one excerpt each"],
+      "session commit" => ["commands/session_commit", "SessionCommit", "Commit one verified checklist item"],
+      "session handoff" => ["commands/session_handoff", "SessionHandoff", "Write this session's hand-off into the day ledger"],
+      "session summary" => ["commands/session_summary", "SessionSummary", "Print the day ledger's open items and recent activity"],
+      "session" => ["commands/session", "Session", "List the session subcommands"],
+      "status" => ["commands/status", "Status", "Show active work in every store"],
+      "sync" => ["commands/sync", "Sync", "Bring the store files and the three databases level"],
+      "uninstall" => ["commands/uninstall", "Uninstall", "Remove Plastic from this machine's agents"],
+      "update" => ["commands/update", "Update", "Move Plastic to the next version on its channel"],
+      "version" => ["commands/version", "Version", "Print the installed Plastic version"]
+    }.freeze
+  end
+end

package/scripts/lib/cli.rb

@@ -0,0 +1,94 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "did_you_mean"
+require_relative "cli/table"
+require_relative "cli/command"
+require_relative "cli/output"
+
+# Plastic::CLI (intent 363) - the dispatcher behind bin/plastic. It reads the
+# command table, matches the longest command name the arguments begin with,
+# requires that one file, and calls it. Nothing else is loaded, which is what
+# keeps a call at about 20 milliseconds with RubyGems off.
+#
+# No arguments, or --help, print the command list. --version prints the
+# version. A command's own --help prints that command's usage line, read from
+# the class without building it. An unknown name exits 2 and names the closest
+# command, so a typo never becomes a stack trace.
+module Plastic
+  class CLI
+    FLAGS = {"--version" => "version", "-v" => "version",
+             "--help" => "help", "-h" => "help"}.freeze
+
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(argv, out: $stdout, err: $stderr, env: ENV, home: Dir.home,
+      directory: Dir.pwd, table: TABLE)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @env = env
+      @home = home
+      @directory = directory
+      @table = table
+    end
+
+    def call
+      matched = match(expanded)
+      return unknown(expanded.first) unless matched
+
+      name, rest = matched
+      return usage(name, rest) if help?(rest)
+
+      command(name).call(rest, out: @out, err: @err, env: @env, home: @home,
+        directory: @directory)
+    end
+
+    def match(argv)
+      [2, 1].each do |width|
+        name = argv.first(width).join(" ")
+        return [name, argv.drop(width)] if @table.key?(name)
+      end
+      nil
+    end
+
+    private
+
+    def expanded
+      return ["help"] if @argv.empty?
+
+      [FLAGS.fetch(@argv.first, @argv.first)] + @argv.drop(1)
+    end
+
+    def help?(rest)
+      rest.any? { |argument| FLAGS[argument] == "help" }
+    end
+
+    def usage(name, rest)
+      Output.new(out: @out, err: @err)
+        .row("usage", command(name)::USAGE_LINE)
+        .flush(json: rest.include?("--json"))
+      Command::OK
+    end
+
+    def command(name)
+      file, const, = @table.fetch(name)
+      require_relative "cli/#{file}"
+      Commands.const_get(const)
+    end
+
+    def unknown(name)
+      suggestions = closest(name)
+      @err.puts "plastic: no command named #{name.inspect}"
+      @err.puts "Closest: #{suggestions.join(", ")}" unless suggestions.empty?
+      @err.puts "Run `plastic help` for the command list."
+      Command::USAGE
+    end
+
+    def closest(name)
+      DidYouMean::SpellChecker.new(dictionary: @table.keys).correct(name)
+    end
+  end
+end

package/scripts/lib/compact_instructions.rb

@@ -28,7 +28,15 @@ module CompactInstructions
   # as stale, so the block states the shipped numbers and names the two keys as the
   # override instead. It names the hand-off in words and never by path, so it reads
   # correctly whether or not the hand-off writer is installed.
+  # The `@` line is a Claude Code import: the harness reads the named file into the
+  # session. It is the whole of ruling D43, that PLASTIC.md is the only instruction text
+  # Plastic carries. It names the installed copy under the Plastic home, because a bare
+  # `@PLASTIC.md` would resolve against ~/.claude, where no such file exists.
   BODY = <<~MD.freeze
+    Plastic runs from one command, `plastic`. Its instructions are one page, imported here:
+
+    @~/.plastic/PLASTIC.md
+
     Plastic watches this session's context. When the harness reports how much of the
     window is used:
 

package/scripts/lib/day_summary.rb

@@ -8,6 +8,7 @@
 # heartbeat. Never the raw ledger (296 D36). No environment reads; every
 # path is injected.
 
+require_relative "store_layout"
 require "time"
 require_relative "session_ledger"
 require_relative "handoff"
@@ -82,10 +83,10 @@ module DaySummary
   # The global store plus every projects/<slug>/store, each with its INDEX
   # one level up, the way doctor enumerates them.
   def stores(home)
-    list = [[File.join(home, "INDEX.md"), File.join(home, "store")]]
-    projects_root = File.join(home, "projects")
+    list = [[File.join(Plastic::StoreLayout.global_root(home), "INDEX.md"), Plastic::StoreLayout.global_store(home)]]
+    projects_root = Plastic::StoreLayout.projects_root(home)
     if File.directory?(projects_root)
-      Dir.children(projects_root).sort.each do |slug|
+      Plastic::StoreLayout.project_slugs(home).each do |slug|
         list << [File.join(projects_root, slug, "INDEX.md"), File.join(projects_root, slug, "store")]
       end
     end

package/scripts/lib/doctor_core.rb

@@ -8,12 +8,13 @@
 # the store, conventions, intent and CLI halves, so Doctor stays one class with
 # one public surface and one definition of which checks are core (intent 36a).
 
+require_relative "store_layout"
 require "json"
 require "yaml"
 require "time"
 require "digest"
-require "rubygems"
 
+require_relative "version_number"
 require_relative "hook_registry"
 require_relative "compact_instructions"
 
@@ -301,7 +302,7 @@ class Doctor
       return checks
     end
 
-    index_path = File.join(plastic_home, "INDEX.md")
+    index_path = File.join(Plastic::StoreLayout.global_root(plastic_home), "INDEX.md")
     if File.exist?(index_path)
       checks << check(
         category: "global_store", name: "global_index_reachable", status: "pass",
@@ -517,9 +518,6 @@ class Doctor
       checks << hooks_entries_owned_check(settings)
     end
 
-    # skills_exist — flat, hyphen-namespaced personal skills (plastic-<name>/)
-    checks << flat_skills_check(agent_dir, "--claude")
-
     # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
     # e.g. an old-name copy after a rename; intent 158a AC15)
     checks << stray_skills_check(agent_dir, "--claude", File.join(agent_dir, "plastic", "manifest.json"))
@@ -630,24 +628,6 @@ class Doctor
     )
   end
 
-  def flat_skills_check(agent_dir, installer_flag)
-    skills_root = File.join(agent_dir, "skills")
-    found = Dir.glob(File.join(skills_root, "plastic-*", "SKILL.md"))
-
-    if !found.empty?
-      check(
-        category: "agent_registration", name: "skills_exist", status: "pass",
-        message: "#{found.size} plastic-* skill(s) installed in #{tilde(skills_root)}"
-      )
-    else
-      check(
-        category: "agent_registration", name: "skills_exist", status: "fail",
-        message: "No plastic-* skills found in #{tilde(skills_root)}",
-        fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest #{installer_flag}"
-      )
-    end
-  end
-
   # Manifest-diff stray-skill check (intent 158a), extended (intent 276) to
   # never vanish on a missing manifest and to name the reserved-prefix rule.
   def stray_skills_check(agent_dir, installer_flag, manifest_path)
@@ -707,9 +687,6 @@ class Doctor
   def check_flat_skills_and_stray(agent_key, agent_dir)
     checks = []
 
-    # For codex/hermes: just check skills exist (no settings.json hooks)
-    checks << flat_skills_check(agent_dir, "--#{agent_key}")
-
     # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
     # e.g. an old-name copy after a rename; intent 158a AC15)
     checks << stray_skills_check(agent_dir, "--#{agent_key}", File.join(agent_dir, "plastic", "manifest.json"))
@@ -1061,9 +1038,7 @@ class Doctor
   end
 
   def safe_version(str)
-    Gem::Version.new(str.to_s)
-  rescue ArgumentError
-    nil
+    VersionNumber.parse(str)
   end
 
   def check_core_files(agent_key, include_drift: true)
@@ -1167,7 +1142,7 @@ class Doctor
               "#{tilde(agent_version_path)}: #{agent_version}",
             ],
             fixable: true,
-            fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+            fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or `plastic rollback` to a prior version"
           )
         end
       else
@@ -1175,7 +1150,7 @@ class Doctor
           category: "core_files", name: "version_match", status: "warn",
           message: "Agent-side VERSION file not found at #{tilde(agent_version_path)}",
           fixable: true,
-          fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+          fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or `plastic rollback` to a prior version"
         )
       end
     end
@@ -1280,7 +1255,7 @@ class Doctor
 
   DISPLAY_HOOK_FIX_HINT = "Re-run the Plastic installer to repair the hook registration: " \
                           "npx @zalom/plastic@<channel> install --reinstall --claude " \
-                          "(plastic-install --repair)".freeze
+                          "(plastic install --reinstall)".freeze
 
   # display_hook_registered (intent 331e, D1, category "display"): the Claude
   # settings carry the plastic-message-display command, on-disk, executable.

package/scripts/lib/doctor_session_ledger.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "time"
 require_relative "session_ledger"
 
@@ -38,7 +39,7 @@ module DoctorSessionLedger
   def check_session_ledger(scopes: nil, now: Time.now)
     return [] unless scopes.nil? || scopes.include?("global")
 
-    store_dir = File.join(plastic_home, "store")
+    store_dir = Plastic::StoreLayout.global_store(plastic_home)
     orphans = orphaned_session_dirs(store_dir, now)
     shape = day_ledger_shape_problems(store_dir)
 

package/scripts/lib/feedback_report.rb

@@ -18,7 +18,7 @@ require "fileutils"
 # Trust model: this class never sends anything anywhere. `compose` returns a
 # Result carrying a local file path and a browser URL; only the human, in
 # their own authenticated browser, submits it. There is no send method here
-# and there must never be one (see skills/feedback/references/transport-and-privacy.md).
+# and there must never be one (see SECURITY.md).
 class FeedbackReport
   GITHUB_REPO = "zalom/plastic"
   CAP_BYTES = 7500

package/scripts/lib/graph_measure_models.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "json"
 require "tmpdir"
 require_relative "node_ledger"
@@ -112,7 +113,8 @@ module GraphMeasureModels
   # purpose - two different silences over the same store, agreeing with
   # each other only by accident.
   def project_config_path(store_dir)
-    File.join(File.dirname(store_dir.to_s), "config.yml")
+    home, slug = Plastic::StoreLayout.locate(store_dir.to_s)
+    File.join((slug == Plastic::StoreLayout::GLOBAL) ? home : File.dirname(store_dir.to_s), "config.yml")
   end
 
   # --- rendering ---------------------------------------------------------------

package/scripts/lib/index_entry.rb

@@ -10,6 +10,8 @@
 # plain hyphen as the id/title separator on READ; every WRITE still emits the
 # real em dash (D10). The separator is built from the codepoint, not a
 # literal byte, so this file stays em-dash free.
+require_relative "atomic_write"
+
 module IndexEntry
   module_function
 
@@ -22,6 +24,13 @@ module IndexEntry
     line.to_s.match(ENTRY_RE)
   end
 
+  def add_active(index_path, dir_name:, title:)
+    id = dir_name.split("--").first
+    line = "- [#{id} #{EM_DASH} #{title}](store/#{dir_name}/#{dir_name}.md)\n"
+    text = File.read(index_path, encoding: "UTF-8")
+    AtomicWrite.write(index_path, text.sub(/^## Active\n/) { |heading| heading + line })
+  end
+
   # True iff the intent is Active in its store's INDEX.md, which lives at the
   # PARENT of the store/ dir. Non-raising: any failure (missing or unreadable
   # INDEX, bad arg) returns false. `index_active_ids` is a pure-data test

package/scripts/lib/installer_core.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "json"
 require "yaml"
 require "fileutils"
@@ -12,6 +13,7 @@ require_relative "agent_models"
 require_relative "harness_text"
 require_relative "compact_instructions"
 require_relative "engine_permissions"
+require_relative "qmd_sync"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/rollback) and their tests can run
@@ -45,23 +47,21 @@ class InstallerCore
   CLAUDE_SECTION_END = "<!-- END PLASTIC COMPACT -->"
   CLAUDE_SECTION_RE = /^<!-- BEGIN PLASTIC COMPACT.*?-->\n.*?\n<!-- END PLASTIC COMPACT -->\n?/m
 
-  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the plastic-conventions
-  # skill, injected into ~/.codex/AGENTS.md. Not a slice of PLASTIC.md itself: AGENTS.md is
-  # a shared file Codex merges from multiple sources, so this block stays a small,
-  # hand-curated pointer rather than embedding the core wholesale, and it never drifts
-  # because it only ever points, never duplicates.
+  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the help topics
+  # `plastic help TOPIC` prints, injected into ~/.codex/AGENTS.md. Not a slice of
+  # PLASTIC.md itself: AGENTS.md is a shared file Codex merges from multiple sources,
+  # so this block stays a small, hand-curated pointer rather than embedding the core
+  # wholesale, and it never drifts because it only ever points, never duplicates.
   CODEX_AGENTS_MD_BODY = <<~MD.freeze
     Plastic is installed for this agent. Plastic is intent-driven state management: work runs
     in one of three modes, direct, thinking, or auto (a team drives the runner loop:
     `runner step`, `status`, `answer`). Do not jump straight to code.
 
     Standing rules:
-    - Core conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly. For
-      depth, read a chapter from ~/.agents/skills/plastic-conventions/references/ on demand.
-      Both are generated and overwritten on Plastic updates, so never edit them.
-    - Operational procedures are installed as skills under ~/.agents/skills/ (each
-      plastic-<name>/SKILL.md). Invoke one explicitly as $plastic-<name> (for example
-      $plastic-doctor), or let Codex pick one implicitly by matching its description.
+    - The command line is ~/.plastic/PLASTIC.md. Read it and follow it exactly. The
+      conventions are chapters `plastic help TOPIC` prints on demand. Both are
+      generated and overwritten on Plastic updates, so never edit them.
+    - Operational procedures are the `plastic` command line itself, run directly.
     - Intents, specs, plans, checklists, and outcomes live under ~/.plastic/, never in
       the project tree.
 
@@ -352,12 +352,36 @@ class InstallerCore
     end
   end
 
+  # The command line (intent 363). Glob-derived for the reason screen_files is:
+  # a command is one row in scripts/lib/cli/table.rb plus one file, and a
+  # hand-written manifest would make it two files and a diff. The launcher
+  # bin/plastic requires scripts/lib/cli.rb by a relative path, so the whole
+  # subtree travels together or an installed copy LoadErrors on the first call.
+  def cli_files
+    Dir.glob(File.join(package_root, "scripts", "lib", "{cli,rlm}", "**", "*.rb")).each_with_object({}) do |path, acc|
+      rel = path.sub("#{package_root}/", "")
+      acc[rel] = rel
+    end
+  end
+
+  # `plastic help TOPIC` (intent 372, family 4) reads docs/help/TOPIC.md from
+  # package_root the same way it reads a command's file, so the chapter has to
+  # ship the same way a template does: glob-derived, one file added and it
+  # installs with no diff here.
+  def help_files
+    Dir.glob(File.join(package_root, "docs", "help", "*.md")).each_with_object({}) do |path, acc|
+      rel = File.join("docs", "help", File.basename(path))
+      acc[rel] = rel
+    end
+  end
+
   # Files copied into ~/.plastic on install/update. Every verb script + the shared lib
   # must be here so the installed ~/.plastic/scripts copy is self-complete (sync-guarded
   # by install_sync_test). The templates and screen-kind halves are glob-derived
   # (template_files, screen_files above); the rest stays a hand-written literal.
   def core_files
-    hand_registered_files.merge(template_files).merge(hook_files).merge(screen_files)
+    hand_registered_files.merge(template_files).merge(hook_files).merge(screen_files).merge(cli_files)
+      .merge(help_files)
   end
 
   def hand_registered_files
@@ -391,6 +415,9 @@ class InstallerCore
       "scripts/plastic-lock" => "scripts/plastic-lock",
       "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
       "scripts/lib/compact_instructions.rb" => "scripts/lib/compact_instructions.rb",
+      "scripts/lib/version_number.rb" => "scripts/lib/version_number.rb",
+      "scripts/lib/cli.rb" => "scripts/lib/cli.rb",
+      "bin/plastic" => "bin/plastic",
       "scripts/agent-report" => "scripts/agent-report",
       "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
       "scripts/insight-append" => "scripts/insight-append",
@@ -406,6 +433,14 @@ class InstallerCore
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
       "scripts/lib/graph_rebuild.rb" => "scripts/lib/graph_rebuild.rb",
       "scripts/lib/store_discovery.rb" => "scripts/lib/store_discovery.rb",
+      "scripts/lib/store_layout.rb" => "scripts/lib/store_layout.rb",
+      "scripts/lib/stores_move.rb" => "scripts/lib/stores_move.rb",
+      "scripts/lib/sqlite.rb" => "scripts/lib/sqlite.rb",
+      "scripts/lib/search_index.rb" => "scripts/lib/search_index.rb",
+      "scripts/lib/store_sync.rb" => "scripts/lib/store_sync.rb",
+      "scripts/lib/work_graph.rb" => "scripts/lib/work_graph.rb",
+      "scripts/lib/reference_archive.rb" => "scripts/lib/reference_archive.rb",
+      "scripts/lib/backup.rb" => "scripts/lib/backup.rb",
       "scripts/lib/frontmatter_writer.rb" => "scripts/lib/frontmatter_writer.rb",
       "scripts/lib/links_projection.rb" => "scripts/lib/links_projection.rb",
       "scripts/lib/links_section.rb" => "scripts/lib/links_section.rb",
@@ -624,7 +659,7 @@ class InstallerCore
   def bootstrap
     puts "  \u{1f331} First install \u{2014} bootstrapping store..."
 
-    FileUtils.mkdir_p(File.join(plastic_home, "store"))
+    FileUtils.mkdir_p(Plastic::StoreLayout.global_store(plastic_home))
     FileUtils.mkdir_p(File.join(plastic_home, "projects"))
 
     write_if_missing(File.join(plastic_home, "config.yml"), <<~YAML)
@@ -643,7 +678,7 @@ class InstallerCore
 
     write_if_missing(File.join(plastic_home, "projects.yml"), "---\nprojects: {}\n")
 
-    write_if_missing(File.join(plastic_home, "INDEX.md"), <<~MD)
+    write_if_missing(File.join(Plastic::StoreLayout.global_root(plastic_home), "INDEX.md"), <<~MD)
       # Index
 
       ## Active
@@ -661,7 +696,7 @@ class InstallerCore
       # Plastic: Agent Instructions
 
       Read `PLASTIC.md` in this directory for the core conventions; deeper doctrine lives
-      in the `plastic-conventions` skill's chapters. Follow it exactly. Never modify it:
+      in the chapters `plastic help TOPIC` prints. Follow it exactly. Never modify it:
       it is overwritten on plugin updates.
 
       This file (`AGENTS.md`) is where project-specific rules live.
@@ -672,6 +707,25 @@ class InstallerCore
     puts "  \u{2705} Store bootstrapped"
   end
 
+  # Intent 372 (former install skill, lines 119-127): `~/.plastic` becomes its own
+  # git repository the first time it exists, so `update` can later commit the core
+  # files it re-syncs. Leaves an existing repository alone.
+  def git_init_if_absent(runner: ->(cmd) { system(*cmd) })
+    FileUtils.mkdir_p(plastic_home)
+    return if File.directory?(File.join(plastic_home, ".git"))
+    runner.call(["git", "-C", plastic_home, "init", "-q"])
+  end
+
+  # Intent 372 (former install skill, lines 167-179): register every Plastic store as
+  # a QMD collection. QmdSync.register already no-ops per store when QMD is absent;
+  # the detector is injected too so a run stays hermetic on a machine that happens to
+  # have the real `qmd` binary on PATH.
+  def register_with_qmd(runner: QmdSync.default_runner, detector: QmdSync.method(:detect))
+    QmdSync.enumerate_stores(plastic_home: plastic_home).each do |store|
+      QmdSync.register(collection: store[:collection], dir: store[:dir], runner: runner, detector: detector)
+    end
+  end
+
   # --- Agent adapters ---
 
   # Uniform per-agent install record dir: <agent-dir>/plastic/ holds VERSION and
@@ -943,9 +997,9 @@ class InstallerCore
   # Every store root (the global store, plus each project store) whose real
   # path is reached with no symlink between it and plastic_home.
   def real_store_roots(plastic_home)
-    roots = [File.join(plastic_home, "store")] +
-            Dir.glob(File.join(plastic_home, "projects", "*", "store"))
-    roots.select { |root| real_store_root?(plastic_home, root) }
+    roots = [Plastic::StoreLayout.global_store(plastic_home)] +
+            Dir.glob(File.join(Plastic::StoreLayout.projects_root(plastic_home), "*", "store"))
+    roots.uniq.select { |root| real_store_root?(plastic_home, root) }
   end
 
   def real_store_root?(plastic_home, store_root)
@@ -1020,7 +1074,7 @@ class InstallerCore
   # fails milder than the bug it prevents, independent of what any caller's `root:` is or
   # what a hand-edited manifest claims.
   def store_roots
-    [File.join(plastic_home, "store"), File.join(plastic_home, "projects")].map { |p| File.expand_path(p) }
+    %w[store projects stores].map { |name| File.expand_path(File.join(plastic_home, name)) }
   end
 
   # `install_skills_flat` relocates any top-level underscore-prefixed markdown

package/scripts/lib/intent_screen.rb

@@ -1,4 +1,5 @@
 # encoding: UTF-8
+require_relative "store_layout"
 # frozen_string_literal: true
 # IntentScreen (intent 316) - fills templates/intent-screen.md from one intent's
 # record: the intent file, the tier's INDEX.md, savepoint.md and checklist.md.
@@ -101,9 +102,8 @@ module IntentScreen
   # --- store ---------------------------------------------------------------------
 
   def self.store_fields(store_root)
-    parent = File.basename(File.dirname(store_root))
-    if parent == "projects"
-      slug = File.basename(store_root)
+    slug = Plastic::StoreLayout.locate(File.join(store_root, "store")).last
+    if slug != Plastic::StoreLayout::GLOBAL
       { "store" => "project:#{slug}", "store.note" => "the #{slug} project store" }
     else
       { "store" => "global", "store.note" => "the global store" }

package/scripts/lib/lock.rb

@@ -368,8 +368,8 @@ module Lock
   # file is inert: nothing reads it, it stays zero bytes, and
   # scripts/end-intent:558 keys its exit contract on Lock.path alone. This is
   # a requirement, not a guarantee the code enforces: the curator stray-file
-  # rule (skills/conventions/references/maintenance-and-revisions.md:155)
-  # has no *.lock carve-out today, so a wrongful delete there degrades one
+  # rule (docs/help/maintenance-and-revisions.md:155) has no *.lock
+  # carve-out today, so a wrongful delete there degrades one
   # write window to the pre-fix (unguarded) behavior, not a hard failure.
   def with_write_guard(intent_dir, type: "delivery",
                        guard_timeout: WRITE_GUARD_TIMEOUT_SECONDS,

package/scripts/lib/node_input.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "yaml"
 require "date"
 require "digest"
@@ -70,7 +71,7 @@ module NodeInput
     status.success? ? truncate_landed_commits(out) : nil
   end
 
-  PROJECT_LAYOUT_RE = %r{\A(.*)/projects/([^/]+)/store/[^/]+\z}.freeze
+  PROJECT_LAYOUT_RE = %r{\A(.*)/(?:projects|stores)/([^/]+)/store/[^/]+\z}.freeze
 
   # --- paths ---------------------------------------------------------------
 
@@ -399,7 +400,7 @@ module NodeInput
     return nil unless m
 
     home, slug = m[1], m[2]
-    path = File.join(home, "projects", slug, "project.yml")
+    path = File.join(Plastic::StoreLayout.project_root(home, slug), "project.yml")
     return nil unless File.exist?(path)
 
     # `permitted_classes` (post-execution review finding B3): the same bug

package/scripts/lib/preflight.rb

@@ -1,7 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-require "rubygems"
+require_relative "version_number"
 
 # Pure, dependency-injected pre-flight checks for Plastic's runtime dependencies
 # (intent 38). Takes injected probes (ruby version, node version, git presence,
@@ -14,9 +14,9 @@ require "rubygems"
 module Preflight
   module_function
 
-  RUBY_FLOOR = "3.0.0"
+  RUBY_FLOOR = "4.0.0"
   NODE_FLOOR = 18
-  RUBY_PIN = "3.3"
+  RUBY_PIN = "4.0"
 
   def check(ruby_version:, node_version:, git_present:, mise_present:)
     messages = []
@@ -63,9 +63,7 @@ module Preflight
   end
 
   def safe_version(str)
-    Gem::Version.new(str.to_s)
-  rescue ArgumentError
-    nil
+    VersionNumber.parse(str)
   end
 
   def strip_leading_v(str)