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

package/{skills/tutorial/references → docs/help}/track-1-guided.md

@@ -9,7 +9,7 @@ end to end: a piece of work moved through What, Why, How, and Exec, with a finis
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+Run `plastic update` first, so the commands below match what is
 actually installed.
 
 Work in a sandbox: this track always creates a global-store intent; the throwaway repo below
@@ -22,7 +22,7 @@ directory instead (see station 6). Either way, nothing in this track touches a r
 
 ### 1. Create the intent
 
-Type `/plastic-intent-creating` and describe the work in plain words, for example "add a
+Run `plastic intent new` and describe the work in plain words, for example "add a
 short Usage section to this project's README."
 
 Artifact: a new intent directory, `{id}--slug.md`, plus the sentinel placeholder lifecycle
@@ -35,7 +35,7 @@ tool, never written by hand.
 
 ### 2. Board the intent
 
-Type `/plastic-intent-continuing` and name the intent.
+Run `plastic continue` and name the intent.
 
 Artifact: a delivery lock (a `delivery.lock` file in the intent directory) naming this
 session as the one owner, and a line in `savepoint.md` recording the stage. The agent then
@@ -46,13 +46,13 @@ sessions from editing the same intent at the same time.
 
 ### 3. Why, rulings one at a time
 
-Type `/plastic-intent-speccing` (say "grill me" for a harder, interview-style pass over
+Run `plastic intent spec` (say "grill me" for a harder, interview-style pass over
 the same ground). It asks conversational prose questions, one at a
 time, never a multiple-choice menu, and answers them one at a time in return.
 
 Artifact: `## Context` and `### Decisions` in the intent file fill in as each answer lands, and
 each ruling also lands as its own `## Insights` entry the moment it is made, never batched for
-later. This station's product is the enriched Why; it hands off to `/plastic-intent-speccing`
+later. This station's product is the enriched Why; it hands off to `plastic intent spec`
 next, it does not write `spec.md` itself.
 
 Checkpoint: after two or three answers, look at the intent file. Every ruling given out loud
@@ -60,7 +60,7 @@ is already sitting in `### Decisions` and in `## Insights`, in writing.
 
 ### 4. How, write the graph
 
-Ask the same conversation (`/plastic-intent-speccing`) to turn the rulings into the graph.
+Ask the same conversation (`plastic intent spec`) to turn the rulings into the graph.
 
 Artifact: `graph.md` (nodes, edges, dispatch policy) and one `nodes/N.md` file per node this
 small delivery needs. A delivery this size is one node; many independent tasks instead get
@@ -70,7 +70,7 @@ Checkpoint: open `graph.md` and point at the one node this worked example needs.
 
 ### 5. Exec, drive the runner loop
 
-Type `/plastic-intent-executing`.
+Run `plastic intent step`.
 
 Teach the loop: `ruby scripts/runner step <intent_dir>` computes which nodes are ready and
 prints a spawn block to dispatch, `ruby scripts/runner status <intent_dir>` reads the
@@ -87,7 +87,7 @@ moving to station 6.
 
 ### 6. End
 
-Type `/plastic-intent-ending`.
+Run `plastic intent end`.
 
 Artifact: a real `outcome.md` (Summary, Delivered, Verification, Follow-ups) generated by
 `scripts/outcome-report` from `graph.md` and the ledger, the intent moved from `## Active`

package/{skills/tutorial/references → docs/help}/track-2-auto.md

@@ -9,7 +9,7 @@ agent end to end, and pausing and resuming that delivery will feel familiar.
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+Run `plastic update` first, so the commands below match what is
 actually installed.
 
 Work in a sandbox: a throwaway git repository, or a global-store intent. Nothing in this
@@ -19,8 +19,8 @@ track touches a real project.
 
 ### 1. Board a small intent and choose auto
 
-Start from an active intent (create one first with `/plastic-intent-creating` if none
-exists, the same way as track 1 station 1). Type `/plastic-auto`.
+Start from an active intent (create one first with `plastic intent new` if none
+exists, the same way as track 1 station 1). Run `plastic auto take ID`.
 
 Artifact: the delivery lock arms, and the agent announces it is taking over the intent for
 autonomous delivery.
@@ -45,7 +45,7 @@ can review how it checked, not just what it found.
 The user keeps two things: the rulings made along the way, and the review points, moments
 auto is built to pause for, such as confirming a project path or stopping before a
 destructive action with no safe way back. When auto tells you to run a command yourself
-("run /plastic-intent-speccing"), that is an instruction for you to type; it is a different
+("run plastic intent spec"), that is an instruction for you to type; it is a different
 thing from the prompts auto hands to its own dispatched subagents, and the two are never
 mixed up in what it tells you.
 
@@ -74,7 +74,7 @@ line.
 
 ### 5. Continue and where-was-I after time away
 
-Type `/plastic-intent-continuing`.
+Run `plastic continue`.
 
 Artifact: the current state, presented and then the session stops. If a specific intent is
 named, the agent reads its stage and savepoint and resumes exactly there, rather than

package/{skills/tutorial/references → docs/help}/track-3-projects-and-roadmaps.md

@@ -9,7 +9,7 @@ will exist with more than one intent inside it and a roadmap file describing the
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+Run `plastic update` first, so the commands below match what is
 actually installed.
 
 Work in a sandbox: this whole track is a walked example. It creates a real project directory
@@ -20,11 +20,11 @@ one this tutorial keeps or ships.
 
 ### 1. Start from a founding implementation intent
 
-Create and board an intent the same way as track 1, stations 1 and 2: `/plastic-intent-creating`,
-then `/plastic-intent-continuing`. Describe something meant to grow into a small real project,
+Create and board an intent the same way as track 1, stations 1 and 2: `plastic intent new`,
+then `plastic continue`. Describe something meant to grow into a small real project,
 for example "build a personal todo app."
 
-Then type `/plastic-intent-speccing` and record a couple of real rulings on this founding
+Then type `plastic intent spec` and record a couple of real rulings on this founding
 intent, for example the language or how tasks get stored. Keep it short: this intent only
 needs enough decisions for the new project to inherit, not a full design.
 
@@ -33,17 +33,21 @@ into a whole new project.
 
 ### 2. Grow it into a project
 
-Type `/plastic-project-creating`.
+Make the project directory yourself and write its `AGENTS.md`, carrying forward at least one
+decision from the founding intent. Plastic does not create the directory or fill that file;
+that is ordinary agent work, done once, before the project exists. Once the directory exists,
+run `plastic project new SLUG --path PATH` to register it in `projects.yml` and provision and
+validate its store.
 
-Artifact: a new project directory, an `AGENTS.md` file carrying the founding intent's
-decisions, the project's own intent store, and a new entry in `projects.yml` registering it.
+Artifact: a new project directory with its `AGENTS.md`, the project's own intent store, and a
+new entry in `projects.yml` registering it.
 
 Checkpoint: open `AGENTS.md` and find at least one line that traces back to a decision
 recorded in the founding intent back in station 1.
 
 ### 3. Add more intents inside the project
 
-Type `/plastic-intent-creating` at least twice, from inside the project, describing two
+Run `plastic intent new` at least twice, from inside the project, describing two
 pieces of real work, for example "add a task list model" and "add a due date field."
 
 Artifact: two or more intent directories inside the project's own store, separate from the
@@ -54,13 +58,16 @@ in the global store.
 
 ### 4. Plan a delivery batch
 
-Type `/plastic-roadmap`.
+Copy `templates/roadmap.md` to `roadmaps/<slug>.md`, next to the project's `INDEX.md`, and fill
+it by hand: a title and short meta header, a `## Goal` section in prose describing what "done"
+looks like for the whole batch, a `## Batches` section (an ordered list of groups of intents;
+intents inside one batch are safe to run in parallel, batches themselves run one after another),
+and an append-only, dated `## Log`. `INDEX.md` stays the single source of truth for each
+intent's status; the roadmap only mirrors it. List the two or more intents from station 3
+across one or more batches.
 
-Teach the roadmap file shape exactly: a title and short meta header, a `## Goal` section in
-prose describing what "done" looks like for the whole batch, a `## Batches` section (an
-ordered list of groups of intents; intents inside one batch are safe to run in parallel,
-batches themselves run one after another), and an append-only, dated `## Log`. `INDEX.md`
-stays the single source of truth for each intent's status; the roadmap only mirrors it.
+Run `plastic roadmap check <slug>` to confirm the file parses, then `plastic roadmap show
+<slug>` to see it rendered as a report.
 
 Artifact: a new `roadmaps/<slug>.md` file, sitting next to the project's `INDEX.md`, listing
 the two or more intents from station 3 across one or more batches.
@@ -93,8 +100,8 @@ sections you turned into the condition above.
 
 No command run here; describe the step instead. Each delivered intent's code merges to main
 as it lands. When the batch (or a meaningful slice of it) is ready to ship, cutting a release
-runs through `/plastic-releasing`, which merges, bumps the version, tags, and completes the
-intents it collects.
+is a push to `alpha`, `beta`, or `main`: the version files are bumped in that push, and CI
+tags, publishes, and completes the intents it collects.
 
 Releases and any npm publish step are described here, not run: this walkthrough stays in a
 sandbox and never touches a real package registry.
@@ -108,4 +115,4 @@ This is the same What, Why, How, Exec cycle from tracks 1 and 2, repeated across
 and gathered by a roadmap. Read
 [`using-plastic-with-claude-code.md`](https://github.com/zalom/plastic/blob/main/docs/guides/using-plastic-with-claude-code.md) for roadmap-driven delivery in more depth,
 including a real worked roadmap. For the exact roadmap file format beyond what this
-walkthrough covers, the `plastic-roadmap` skill itself is the reference.
+walkthrough covers, [`docs/help/roadmaps.md`](roadmaps.md) is the reference.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.27",
+  "version": "2.0.0-alpha.28",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {
-    "plastic": "bin/plastic.js"
+    "plastic": "bin/plastic"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -34,6 +34,7 @@
     "bin/",
     "scripts/",
     "skills/",
+    "docs/help/",
     "hooks/",
     "agents/",
     "templates/",

package/scripts/append-ledger

@@ -30,6 +30,7 @@
 #   2 - usage error, or promote/tick found nothing to address (no write happens)
 #   3 - promote/tick could not take an exclusive lock (filesystem without flock support)
 
+require_relative "lib/store_layout"
 require_relative "lib/session_ledger"
 require_relative "lib/handoff"
 
@@ -162,7 +163,7 @@ def main(argv)
   usage_abort("verb must be one of #{VERBS.join(", ")}, got #{opts[:verb].inspect}") unless VERBS.include?(opts[:verb])
 
   plastic_home = expand(ENV.fetch("PLASTIC_HOME", "~/.plastic"))
-  store = opts[:store] ? expand(opts[:store]) : File.join(plastic_home, "store")
+  store = opts[:store] ? expand(opts[:store]) : Plastic::StoreLayout.global_store(plastic_home)
   templates = opts[:templates] ? expand(opts[:templates]) : default_templates_dir
   usage_abort("templates dir not found: #{templates}") unless Dir.exist?(templates)
   opts[:templates] = templates

package/scripts/dashboard.rb

@@ -21,6 +21,7 @@
 #
 # Read-only. Never modifies files.
 
+require_relative "lib/store_layout"
 require "json"
 require "yaml"
 require "date"
@@ -143,13 +144,13 @@ def completion_dates(index_path)
 end
 
 # All stores: global + every registered project. -> [{scope, store, index}]
-def stores
+def stores(home = PLASTIC_HOME)
   list = []
-  global = File.join(PLASTIC_HOME, "store")
-  list << { scope: "global", store: global, index: File.join(PLASTIC_HOME, "INDEX.md") } if File.directory?(global)
-  projects_root = File.join(PLASTIC_HOME, "projects")
+  global = Plastic::StoreLayout.global_store(home)
+  list << { scope: "global", store: global, index: File.join(Plastic::StoreLayout.global_root(home), "INDEX.md") } if File.directory?(global)
+  projects_root = Plastic::StoreLayout.projects_root(home)
   if File.directory?(projects_root)
-    Dir.children(projects_root).sort.each do |proj|
+    Plastic::StoreLayout.project_slugs(home).each do |proj|
       store = File.join(projects_root, proj, "store")
       next unless File.directory?(store)
       list << { scope: "project:#{proj}", store: store, index: File.join(projects_root, proj, "INDEX.md") }
@@ -592,7 +593,7 @@ def render_continue(records)
   out.concat(matrix(open, scope_tag: true))
   out << ""
   out << LEGEND
-  out << "ask    for the <slug> project board  ·  plastic-auto  (works the dispatchable queue)"
+  out << "ask    for the <slug> project board  ·  plastic auto take ID  (works the dispatchable queue)"
   out.join("\n") + "\n"
 end
 
@@ -855,7 +856,7 @@ end
 def short_description(scope)
   return "" unless scope.start_with?("project:")
   slug = scope.sub("project:", "")
-  agents = File.join(PLASTIC_HOME, "projects", slug, "AGENTS.md")
+  agents = File.join(Plastic::StoreLayout.project_root(PLASTIC_HOME, slug), "AGENTS.md")
   if File.exist?(agents)
     File.readlines(agents).each do |l|
       t = l.strip
@@ -1022,7 +1023,7 @@ end
 # directly under PLASTIC_HOME, with no intervening "store" segment.
 def screen_tier_root(plastic_home, scope)
   return plastic_home if scope == "global"
-  File.join(plastic_home, "projects", screen_scope_slug(scope))
+  Plastic::StoreLayout.project_root(plastic_home, screen_scope_slug(scope))
 end
 
 # "global" spans every store (the same aggregate render_continue and --json's
@@ -1085,7 +1086,7 @@ end
 # PLASTIC_HOME/store tmp root, and `session: nil` (A6) so the calling
 # session's own live heartbeat counts rather than being excluded as "self".
 def screen_sessions_count(plastic_home, now:)
-  store = File.join(plastic_home, "store")
+  store = Plastic::StoreLayout.global_store(plastic_home)
   DaySummary.active_sessions(store, nil, now: now, ttl: DaySummary::HEARTBEAT_TTL).size
 end
 

package/scripts/day-summary

@@ -14,6 +14,7 @@
 #
 # Exit codes: 0 done; 2 usage error.
 
+require_relative "lib/store_layout"
 require_relative "lib/session_ledger"
 require_relative "lib/day_summary"
 
@@ -43,7 +44,7 @@ end
 
 opts = parse_args(ARGV)
 home = opts[:home] ? expand(opts[:home]) : expand(ENV.fetch("PLASTIC_HOME", "~/.plastic"))
-store = opts[:store] ? expand(opts[:store]) : File.join(home, "store")
+store = opts[:store] ? expand(opts[:store]) : Plastic::StoreLayout.global_store(home)
 day = opts[:day] || SessionLedger.day_id
 usage_abort("--day must be eight digits parsing as a real date, got #{day.inspect}") unless SessionLedger.valid_day_id?(day)
 session = SessionLedger.short_session_id(opts[:session], ENV["CLAUDE_CODE_SESSION_ID"])

package/scripts/doctor.rb

@@ -9,6 +9,7 @@
 # Exit codes: 0 (all pass), 1 (warnings only), 2 (failures present)
 # Read-only — never modifies files.
 
+require_relative "lib/store_layout"
 require "date"
 require "open3"
 require "timeout"
@@ -40,6 +41,7 @@ require_relative "lib/preflight"
 require_relative "lib/ruby_probe"
 require_relative "lib/doctor_session_ledger"
 require_relative "lib/intent_screen"
+require_relative "lib/store_sync"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -216,7 +218,7 @@ class Doctor
   def check_global_store
     checks = []
 
-    index_path = File.join(plastic_home, "INDEX.md")
+    index_path = File.join(Plastic::StoreLayout.global_root(plastic_home), "INDEX.md")
 
     # index_exists
     if File.exist?(index_path)
@@ -252,7 +254,7 @@ class Doctor
     end
 
     # orphaned_intents — directories in store/ not referenced in INDEX.md
-    store_dir = File.join(plastic_home, "store")
+    store_dir = Plastic::StoreLayout.global_store(plastic_home)
     if File.directory?(store_dir)
       intent_dirs = store_intent_dirs(store_dir)
       orphans = intent_dirs.reject { |d| content.include?("store/#{d}") }
@@ -278,7 +280,7 @@ class Doctor
     store_paths = content.scan(%r{store/\S+}).map { |ref| ref.gsub(/[)\]>].*/, "").chomp("/") }.uniq
 
     ghosts = store_paths.select do |ref|
-      full_path = File.join(plastic_home, ref)
+      full_path = File.join(Plastic::StoreLayout.global_root(plastic_home), ref)
       !File.exist?(full_path) && !File.directory?(full_path)
     end
 
@@ -330,7 +332,7 @@ class Doctor
           category: "core_files", name: name, status: "warn",
           message: "#{config[:name]}'s 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"
         )
       else
         agent_version = File.read(agent_version_path).strip
@@ -348,7 +350,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
       end
@@ -613,7 +615,7 @@ class Doctor
         fixable: true,
         fix_hint: "Relocate each unsanctioned section into the " \
                   "intent's revisions.md via move-and-record (a missing required section is restored " \
-                  "or reprojected instead); see plastic-conventions > references/maintenance-and-revisions.md"
+                  "or reprojected instead); see `plastic help maintenance-and-revisions`"
       )
     end
 
@@ -644,7 +646,7 @@ class Doctor
     # unpromoted_rules (intent 341, G8, C37): an Insights entry tagged
     # `rule:` (via `insight-append --rule`) is a promise the rule will make
     # it into project doctrine. Advisory only.
-    checks.concat(unpromoted_rules_checks(intent_dirs, home: Dir.home))
+    checks.concat(unpromoted_rules_checks(intent_dirs))
 
     # cross_store_resolution — RESOLVES (not just shape-checks) every cross-store
     # `store:id` ref against the FULL store family via the relocation map
@@ -705,14 +707,14 @@ class Doctor
     if scopes.nil? || scopes.include?("global")
       stores << {
         scope: "global",
-        index: File.join(plastic_home, "INDEX.md"),
-        store_dir: File.join(plastic_home, "store"),
+        index: File.join(Plastic::StoreLayout.global_root(plastic_home), "INDEX.md"),
+        store_dir: Plastic::StoreLayout.global_store(plastic_home),
       }
     end
 
-    projects_root = File.join(plastic_home, "projects")
+    projects_root = Plastic::StoreLayout.projects_root(plastic_home)
     if File.directory?(projects_root)
-      Dir.children(projects_root).sort.each do |project|
+      Plastic::StoreLayout.project_slugs(plastic_home).each do |project|
         scope = "project:#{project}"
         next unless scopes.nil? || scopes.include?(scope)
 
@@ -1228,7 +1230,7 @@ end
       "project-links --intent <id> --apply` over running project-links directly: it detects " \
       "(never acquires) the target's delivery lock, requires a clean store working tree, and " \
       "commits the scoped change plus its revisions.md receipt as one merged operation " \
-      "(plastic-conventions > references/maintenance-and-revisions.md)."
+      "(`plastic help maintenance-and-revisions`)."
     )
   end
 
@@ -1692,7 +1694,7 @@ end
       "Every sources/chain id resolves to a real intent (I4)",
       "Record the dangling sources/chain edge as a " \
       "broken-source/broken-chain move-and-record entry in the intent's revisions.md (see " \
-      "plastic-conventions > references/maintenance-and-revisions.md), or restore the missing intent"
+      "`plastic help maintenance-and-revisions`), or restore the missing intent"
     )
     checks
   end
@@ -1865,31 +1867,25 @@ end
   #
   # `insight-append --rule` tags an entry "... - rule: <text>". A tag is a
   # promise the rule will make it into project doctrine; until the exact
-  # rule text shows up in some skills/conventions/references/*.md chapter,
-  # it is only visible to a session that happens to read this one intent
-  # file, and the next session repeats the mistake the rule names. Advisory
-  # only (warn, never fail): a freshly tagged rule is not yet promoted by
-  # design, and nothing here can auto-promote it (that is an editorial call,
-  # not a mechanical one).
+  # rule text shows up in some docs/help/*.md chapter, it is only visible to
+  # a session that happens to read this one intent file, and the next
+  # session repeats the mistake the rule names. Advisory only (warn, never
+  # fail): a freshly tagged rule is not yet promoted by design, and nothing
+  # here can auto-promote it (that is an editorial call, not a mechanical
+  # one).
   RULE_ENTRY_RE = /—\s*rule:\s*(.+?)\s*\z/.freeze
 
-  def unpromoted_rules_checks(intent_dirs, package_root: PACKAGE_ROOT, home: nil)
-    # The installed doctor runs from ~/.plastic/scripts, so PACKAGE_ROOT
-    # (~/.plastic) has no skills/ directory: the conventions chapters install
-    # to the agent home layout instead. `home` is caller-injected (never an
-    # ENV read here) so this stays hermetic in tests; the real call site
-    # passes the process's actual home directory.
-    chapter_dirs = []
-    if home
-      chapter_dirs << File.join(home, ".claude", "skills", "plastic-conventions", "references")
-      chapter_dirs << File.join(home, ".agents", "skills", "plastic-conventions", "references")
-    end
-    chapter_dirs << File.join(package_root, "skills", "conventions", "references")
+  def unpromoted_rules_checks(intent_dirs, package_root: PACKAGE_ROOT)
+    # docs/help installs straight under PACKAGE_ROOT for every harness alike
+    # (~/.plastic/docs/help once installed, repo docs/help in a checkout), so
+    # a single path covers both the repo and the installed layout; unlike
+    # the old skills-based chapters, help topics are no longer agent-home
+    # specific, so this needs no `home:` split.
+    chapter_dir = File.join(package_root, "docs", "help")
 
-    chapters_text = chapter_dirs.select { |d| Dir.exist?(d) }
-                                .flat_map { |d| Dir.glob(File.join(d, "*.md")) }
-                                .map { |f| File.read(f) }
-                                .join("\n\n")
+    chapters_text = Dir.glob(File.join(chapter_dir, "*.md"))
+                        .map { |f| File.read(f) }
+                        .join("\n\n")
 
     unpromoted = []
     intent_dirs.each do |d|
@@ -1917,7 +1913,7 @@ end
         category: "conventions", name: "unpromoted_rules", status: "warn",
         message: "#{unpromoted.size} tagged rule(s) not yet carried by any conventions chapter",
         details: unpromoted, fixable: false,
-        fix_hint: "Promote the rule into the right skills/conventions/references/*.md chapter, " \
+        fix_hint: "Promote the rule into the right docs/help/*.md chapter, " \
                   "or drop the tag if the finding does not belong in doctrine"
       )]
     end
@@ -1934,8 +1930,7 @@ end
   # skill directory under agent_dir/skills that has NO corresponding entry in the
   # current install manifest is a stray (e.g. a leftover old-name copy the
   # install/update prune should have removed, or one it never saw because the
-  # manifest predates it). Complements flat_skills_check (which only confirms at
-  # least one skill exists). Defers to the manifest check when the manifest itself
+  # manifest predates it). Defers to the manifest check when the manifest itself
   # is missing or malformed, so the two checks never double-report the same gap.
 
   # Auto-mode role agents install as <dir>/agents/plastic-*.md. Pass if at least
@@ -2301,7 +2296,7 @@ end
   # 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_dir = Plastic::StoreLayout.project_root(plastic_home, slug)
 
     # project_dir_exists
     if File.directory?(project_dir)
@@ -2351,7 +2346,7 @@ end
     end
 
     # project_yml_exists
-    project_yml_path = File.join(plastic_home, "projects", slug, "project.yml")
+    project_yml_path = File.join(Plastic::StoreLayout.project_root(plastic_home, slug), "project.yml")
     project_yml_data = nil
 
     if File.exist?(project_yml_path)
@@ -2398,7 +2393,7 @@ end
     return checks unless parent_id
 
     # Find the intent directory for the parent ID
-    store_dir = File.join(plastic_home, "store")
+    store_dir = Plastic::StoreLayout.global_store(plastic_home)
     parent_dir = nil
     if File.directory?(store_dir)
       parent_dir = Dir.children(store_dir).find { |d| d.start_with?("#{parent_id}--") }
@@ -2555,7 +2550,7 @@ end
   # A config-asks warn in that tier would flip every post-update doctor to
   # "fail" on an otherwise healthy install until the question is answered,
   # re-noising the post-update surface intent 126 deliberately quieted. The
-  # recoverable-later path for a pending question is a full `/plastic-doctor`
+  # recoverable-later path for a pending question is a full `plastic doctor`
   # run, the declared maintenance front door; the moment-it-happens path is
   # update.rb#announce_pending_config_asks, which already runs on every hop.
   #
@@ -3019,6 +3014,16 @@ end
     end
   end
 
+  def check_graph_links
+    return [] unless File.exist?(Plastic::WorkGraph.path(plastic_home))
+
+    orphans = Plastic::StoreSync.orphans(plastic_home)
+    return [check(category: "graph_links", name: "graph_links", status: "pass", message: "every stored file belongs to an intent in work_graph.db")] if orphans.empty?
+
+    [check(category: "graph_links", name: "graph_links", status: "warn", details: orphans, fixable: false,
+      message: "#{orphans.size} intent id(s) hold files and have no row in work_graph.db")]
+  end
+
   # --- Run all checks ---
 
   def run_checks(agent_key)
@@ -3037,6 +3042,7 @@ end
     all_checks += check_session_ledger(scopes: ["global"])
     all_checks += check_skill_lint
     all_checks += check_install_integrity
+    all_checks += check_graph_links
     all_checks += check_display_registration(agent_key)
     all_checks += check_display_paints(agent_key)
     all_checks += check_display_not_defeated(agent_key)

package/scripts/end-intent

@@ -68,6 +68,7 @@
 #   7  hollow delivered report refused (317a D7) - intent 308's one deliberate
 #      exception to report-and-proceed; --allow-hollow-report overrides.
 
+require_relative "lib/store_layout"
 require "fileutils"
 require "date"
 require "open3"
@@ -170,14 +171,7 @@ end
 # "projects" (the StoreDiscovery convention, scripts/lib/store_discovery.rb), never by
 # hardcoding ".plastic" as a name.
 def resolve_plastic_home_and_scope(store)
-  parent = File.dirname(store)
-  grandparent = File.dirname(parent)
-  if File.basename(grandparent) == "projects"
-    slug = File.basename(parent)
-    [File.dirname(grandparent), "project:#{slug}"]
-  else
-    [parent, "global"]
-  end
+  Plastic::StoreLayout.home_and_scope(store)
 end
 
 # --- outcome generation, before the backfill (intent 339, G6, spec D10) -----

package/scripts/file-session-intent

@@ -14,6 +14,7 @@
 # and on any filing error (reported on stderr; the next boot tries again), 2 on
 # a usage error.
 
+require_relative "lib/store_layout"
 require_relative "lib/session_ledger"
 require_relative "lib/session_backfill"
 
@@ -48,7 +49,7 @@ if opts[:carry_to] && !SessionLedger.valid_day_id?(opts[:carry_to])
   usage_abort("--carry-to must be a real calendar date, YYYYMMDD")
 end
 
-store = opts[:store] || File.join(File.expand_path(ENV.fetch("PLASTIC_HOME", "~/.plastic")), "store")
+store = opts[:store] || Plastic::StoreLayout.global_store(File.expand_path(ENV.fetch("PLASTIC_HOME", "~/.plastic")))
 templates = opts[:templates] || File.expand_path("../templates", __dir__)
 
 begin

package/scripts/hook-capture

@@ -9,6 +9,7 @@
 # runs in its own rescue and the hook always exits 0 (spec D2). Intent 345
 # (D7, 323) removed the per-prompt Future-intent hint step entirely.
 
+require_relative "lib/store_layout"
 require "json"
 require "open3"
 require "time"
@@ -38,7 +39,7 @@ cwd = payload["cwd"].to_s
 cwd = Dir.pwd if cwd.empty?
 
 plastic_home = File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
-store = File.join(plastic_home, "store")
+store = Plastic::StoreLayout.global_store(plastic_home)
 templates = File.expand_path("../templates", __dir__)
 sid = SessionLedger.short_session_id(nil, session_id)
 today = SessionLedger.day_id
@@ -108,7 +109,7 @@ begin
       cockpit, _err, status = Open3.capture3({ "RUBYOPT" => nil }, "ruby", dashboard, "continue")
       if status.success? && !cockpit.strip.empty?
         context_parts << (cockpit.rstrip +
-          "\n\nFollow the plastic-intent-continuing skill workflow to resume: " \
+          "\n\nRun `plastic continue` to resume: " \
           "if active intents exist, read their state and resume; otherwise surface the " \
           "most-valuable next work and any stale or triage intents from the board above.")
 
@@ -135,7 +136,7 @@ begin
   auto_triggers = ["take it from here", "deliver this", "/plastic-auto", "auto mode"].freeze
   triggered = auto_triggers.any? { |p| message_lower.include?(p) } || message_lower.match?(/\bauto\b/)
   if triggered
-    context_parts << "Auto-mode request detected. Invoke the plastic-auto skill to deliver the " \
+    context_parts << "Auto-mode request detected. Run `plastic auto take ID` to deliver the " \
                       "active intent autonomously - it takes the intent under a lock and a worktree " \
                       "and points this session at it."
   end

package/scripts/hook-close

@@ -8,6 +8,7 @@
 #
 # Usage: hook-close <plastic_home>   (stdin: the hook JSON)
 
+require_relative "lib/store_layout"
 require "json"
 require_relative "lib/session_ledger"
 require_relative "lib/session_close"
@@ -23,7 +24,7 @@ payload =
     {}
   end
 
-store = File.join(File.expand_path(plastic_home), "store")
+store = Plastic::StoreLayout.global_store(File.expand_path(plastic_home))
 filer = File.expand_path("file-session-intent", __dir__)
 templates = File.expand_path("../templates", __dir__)
 begin