From: Thomas Walker Lynch <eknp9n@reasoningtechnology.com>
Date: Tue, 13 Oct 2026 04:04:40 +0000 (+0000)
Subject: skeleton update
X-Git-Url: https://git.reasoningtechnology.com/USER_NAME.png?a=commitdiff_plain;h=4fa9b24df8f6ec39815d70cda618e6c6beab691d;p=RT-Style

skeleton update
---

diff --git a/administrator/document/how-to_add-project-dependency.html b/administrator/document/how-to_add-project-dependency.html
new file mode 100644
index 0000000..327a28c
--- /dev/null
+++ b/administrator/document/how-to_add-project-dependency.html
@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>How to add a project dependency</title>
+    <script>
+      {
+        let dirpr_library = null;
+        try{ dirpr_library = localStorage.getItem("RT.dirpr_library"); }catch(e){}
+        window.RT = window.RT || {};
+        RT.dirpr_library = RT.dirpr_library || dirpr_library || "https://style.ReasoningTechnology.com/Manuscript";
+        document.write('<script src="' + RT.dirpr_library + '/Core/RT-Manuscript_make.js"><\/script>');
+      }
+    </script>
+    <script>
+      window.RT.theme_preference('inverse_wheat');
+      window.RT.load('Layout/paginate');
+      window.RT.load('Layout/article_tech_ref');
+      window.RT.load('Element/theme_selector');
+    </script>
+  </head>
+  <body>
+    <RT·theme-selector></RT·theme-selector>
+    <RT·article>
+      <RT·title
+        author="Thomas Walker Lynch"
+        date="2026-10-09"
+        title="How to add a project dependency">
+      </RT·title>
+
+      <RT·TOC level="1"></RT·TOC>
+
+      <h1>Project dependencies</h1>
+
+      <p>
+        A <RT·term>project dependency</RT·term> is software the project uses but did not author: a language toolchain, a library, a tool, or another project. A dependency is installed outside the project, as a sibling directory of it, and is linked into the project under <RT·code>shared/project-dependency</RT·code>.
+      </p>
+
+      <p>
+        Getting an arbitrary piece of software working is different every time, so the administrator is free to do whatever a dependency needs inside <RT·code>shared/project-dependency</RT·code>. The skeleton relies on only the few conventions given in the next section.
+      </p>
+
+      <h1>What the skeleton relies on</h1>
+
+      <ul>
+        <li><RT·code>project</RT·code> : A link to <RT·code>../../../</RT·code>, the directory that holds this project and its siblings. It comes with the skeleton. Links to dependencies are made through it, so they are relative and stay correct in every clone.</li>
+        <li><RT·code>&lt;name&gt;.init</RT·code> : A bash script that every role setup sources, for every role, each time a person takes on a role. It puts the dependency into the environment, typically by adding to <RT·code>PATH</RT·code> or exporting variables.</li>
+        <li><RT·code>&lt;name&gt;.org</RT·code> or <RT·code>&lt;name&gt;.html</RT·code> : Notes on how the dependency was installed, so that each team member can repeat the installation after cloning. Short notes may instead be comments at the top of <RT·code>&lt;name&gt;.init</RT·code>.</li>
+        <li><RT·code>&lt;name&gt;.install</RT·code> : Optional. A script that carries out the installation, where it can be automated. A person runs it; setup never does.</li>
+        <li><RT·code>.gitignore</RT·code> : Belongs to the administrator. It decides which of the files in the directory are tracked.</li>
+      </ul>
+
+      <p>
+        Files for one dependency share a base name, so that <RT·code>Python.init</RT·code>, <RT·code>Python.org</RT·code>, and the link they describe sit together in a listing.
+      </p>
+
+      <h1>Steps</h1>
+
+      <h2>Install the dependency beside the project</h2>
+      <p>
+        Download, clone, or extract the dependency into the directory that holds the project, so that it sits as a sibling of the project directory. Build it there if it needs building.
+      </p>
+
+      <h2>Link it</h2>
+      <p>
+        Make the link through the <RT·code>project</RT·code> link. The word <RT·code>project</RT·code> in the link target is literal.
+      </p>
+      <RT·code>
+        > cd $REPO_HOME/shared/project-dependency
+        > ln -s project/&lt;dependency directory&gt; &lt;name&gt;
+      </RT·code>
+
+      <h2>Write the init file</h2>
+      <p>
+        Write <RT·code>&lt;name&gt;.init</RT·code> in the same directory. Because it runs on every setup for every role, keep it to setting the environment:
+      </p>
+      <ul>
+        <li>Make it quick, and safe to run any number of times.</li>
+        <li>Do not install, build, or download anything from it.</li>
+        <li>Test that the dependency is present before using it, so that a clone without the dependency still sets up.</li>
+        <li>Print nothing in normal use. A notice for the administrator role, when the dependency is missing, is fine.</li>
+      </ul>
+      <p>
+        <RT·code>Python.init</RT·code>, which comes with the skeleton, is an example:
+      </p>
+      <RT·code>
+        if [[ -d "$REPO_HOME/shared/project-dependency/Python-3.12.3/bin" ]]; then
+          PATH="$REPO_HOME/shared/project-dependency/Python-3.12.3/bin:$PATH"
+        else
+          if [[ "$ROLE" == "administrator" ]]; then
+             echo "Notice: Local Python-3.12.3 bin not found. Using system Python."
+          fi
+        fi
+      </RT·code>
+
+      <h2>Write the installation notes</h2>
+      <p>
+        Record what was installed, where it came from, and the commands used, in <RT·code>&lt;name&gt;.org</RT·code>, <RT·code>&lt;name&gt;.html</RT·code>, or comments in the init file. A team member who has cloned the project follows these notes to install the dependency, and then recreates the link if it is not tracked.
+      </p>
+
+      <h2>Decide what is tracked</h2>
+      <p>
+        The skeleton's <RT·code>.gitignore</RT·code> tracks itself, the <RT·code>project</RT·code> link, and files ending in <RT·code>.init</RT·code>, <RT·code>.install</RT·code>, <RT·code>.org</RT·code>, and <RT·code>.html</RT·code>. Everything else in the directory is ignored. To track a dependency's link, so that it arrives with every clone, add a line naming it:
+      </p>
+      <RT·code>
+        !&lt;name&gt;
+      </RT·code>
+      <p>
+        A tracked link points at nothing until the dependency is installed beside the project, which is why init files test for the dependency before using it.
+      </p>
+
+      <h2>Commit</h2>
+      <p>
+        Add the init file, the notes, the <RT·code>.gitignore</RT·code> change, and any tracked link, then commit.
+      </p>
+
+    </RT·article>
+  </body>
+</html>
diff --git a/administrator/tool/RT-Style_header_v5_to_v6 b/administrator/tool/RT-Style_header_v5_to_v6
new file mode 100755
index 0000000..3ca4169
--- /dev/null
+++ b/administrator/tool/RT-Style_header_v5_to_v6
@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+# -*- mode: python; coding: utf-8; python-indent-offset: 2; indent-tabs-mode: nil -*-
+
+"""
+RT-Style_header_v5_to_v6
+
+Converts RT-Style version 5 document headers to version 6.
+
+A version 5 document loads the engine through a locator file beside it:
+
+    <script src="RT-Manuscript_locator.js"></script>
+
+A version 6 document carries an inline header block instead. The block takes
+the library from the record made by opening a Manuscript directory's
+setup.html, and falls back to the Reasoning Technology server.
+
+For each version 5 .html file found, the tool replaces the locator line in
+<head> with the version 6 block, keeping its indentation. It then deletes
+RT-Manuscript_locator.js from that file's directory, unless another version 5
+document there, not converted in this run, still uses it. Any other mention of
+RT-Manuscript_locator in the file (an escaped example, prose) is logged for a
+person to edit.
+
+Usage: RT-Style_header_v5_to_v6 <command> [file ...]
+       RT-Style_header_v5_to_v6 preview <command> [file ...]
+
+  help | -h | --help   print this message (also printed when given no arguments)
+  project              walk the directory tree rooted at $REPO_HOME
+  tree                 walk the directory tree rooted at the current directory
+  local                only the current directory, no subdirectories
+  file <name> ...      only the named .html files
+  preview <command>    print the log of what <command> would do, change nothing
+
+Every directory is walked, whatever its name. Symbolic links to directories
+are not followed, so a link back up the tree cannot cause a loop or reach
+outside it.
+"""
+
+import sys ,os ,re
+from pathlib import Path
+
+LOCATOR_FILE = "RT-Manuscript_locator.js"
+V6_MARK = 'localStorage.getItem("RT.dirpr_library")'
+
+V6_BLOCK = [
+  '<script>'
+  ,'  {'
+  ,'    let dirpr_library = null;'
+  ,'    try{ dirpr_library = localStorage.getItem("RT.dirpr_library"); }catch(e){}'
+  ,'    window.RT = window.RT || {};'
+  ,'    RT.dirpr_library = RT.dirpr_library || dirpr_library || "https://style.ReasoningTechnology.com/Manuscript";'
+  ,'    document.write(\'<script src="\' + RT.dirpr_library + \'/Core/RT-Manuscript_make.js"><\\/script>\');'
+  ,'  }'
+  ,'</script>'
+]
+
+LOCATOR_LINE = re.compile(
+  r'^(?P<indent>[ \t]*)<script\s+src\s*=\s*["\'](?:[^"\']*/)?RT-Manuscript_locator\.js["\']\s*>\s*</script>\s*$'
+  ,re.IGNORECASE
+)
+HEAD_END = re.compile(r'</head\s*>' ,re.IGNORECASE)
+
+
+# ---------------------------------------------------------------- log
+
+class Log:
+  def __init__(self ,preview: bool ,base: Path):
+    self.preview = preview
+    self.base = base
+    self.count = {"converted": 0 ,"deleted": 0 ,"already": 0 ,"hand": 0
+                  ,"untouched": 0 ,"stray": 0 ,"error": 0}
+
+  def rel(self ,p: Path) -> str:
+    try: return str(p.resolve().relative_to(self.base))
+    except ValueError: return str(p)
+
+  def line(self ,tag: str ,text: str):
+    print(f"  {tag:<15} {text}")
+
+  def act(self ,done: str ,would: str ,p: Path ,key: str):
+    self.line(would if self.preview else done ,self.rel(p))
+    self.count[key] += 1
+
+  def summary(self):
+    c = self.count
+    v = "would be " if self.preview else ""
+    print()
+    print("summary:")
+    print(f"  {c['converted']:>4}  .html files {v}converted to version 6")
+    print(f"  {c['deleted']:>4}  {LOCATOR_FILE} files {v}deleted")
+    print(f"  {c['already']:>4}  .html files already version 6")
+    print(f"  {c['hand']:>4}  .html files with mentions to edit by hand")
+    print(f"  {c['untouched']:>4}  other .html files left alone")
+    if c['stray']:
+      print(f"  {c['stray']:>4}  {LOCATOR_FILE} files kept (see 'kept' lines)")
+    if c['error']:
+      print(f"  {c['error']:>4}  errors")
+    if self.preview:
+      print("preview only: nothing was changed")
+
+
+# ---------------------------------------------------------------- finding files
+
+def walk(root: Path ,recursive: bool):
+  """Yields (directory ,[.html files] ,has_locator) for each directory."""
+  if not recursive:
+    entries = sorted(root.iterdir())
+    yield root ,[e for e in entries if e.is_file() and e.suffix == ".html"] ,(root / LOCATOR_FILE).is_file()
+    return
+  for d ,dirs ,files in os.walk(root):
+    dirs.sort()
+    files = sorted(files)
+    yield Path(d) ,[Path(d) / f for f in files if f.endswith(".html")] ,LOCATOR_FILE in files
+
+
+# ---------------------------------------------------------------- conversion
+
+def convert(text: str):
+  """Returns (new_text ,replaced_count ,leftover). leftover lists
+  (line_number ,line) for locator mentions that were not replaced."""
+  lines = text.split("\n")
+  out = []
+  replaced = 0
+  leftover = []
+  in_head = True
+  for n ,line in enumerate(lines ,1):
+    m = LOCATOR_LINE.match(line) if in_head else None
+    if m:
+      eol = "\r" if line.endswith("\r") else ""
+      out.extend(m.group("indent") + b + eol for b in V6_BLOCK)
+      replaced += 1
+    else:
+      out.append(line)
+      if LOCATOR_FILE.removesuffix(".js") in line:
+        leftover.append((n ,line.strip()))
+    if in_head and HEAD_END.search(line):
+      in_head = False
+  return "\n".join(out) ,replaced ,leftover
+
+def do_file(f: Path ,log: Log) -> bool:
+  """Converts one .html file. Returns True when it was version 5."""
+  try:
+    text = f.read_text(encoding="utf-8")
+  except Exception as e:
+    log.line("error" ,f"{log.rel(f)}: cannot read: {e}")
+    log.count["error"] += 1
+    return False
+
+  if V6_MARK in text and LOCATOR_FILE.removesuffix(".js") not in text:
+    log.line("already v6" ,log.rel(f))
+    log.count["already"] += 1
+    return False
+
+  new_text ,replaced ,leftover = convert(text)
+
+  if replaced:
+    if not log.preview:
+      try:
+        mode = f.stat().st_mode
+        f.write_text(new_text ,encoding="utf-8")
+        os.chmod(f ,mode)
+      except Exception as e:
+        log.line("error" ,f"{log.rel(f)}: cannot write: {e}")
+        log.count["error"] += 1
+        return False
+    log.act("converted" ,"would convert" ,f ,"converted")
+    if replaced > 1:
+      log.line("note" ,f"{log.rel(f)}: {replaced} locator lines in <head>, all replaced")
+  elif not leftover:
+    log.count["untouched"] += 1
+
+  if leftover:
+    log.count["hand"] += 1
+    for n ,line in leftover:
+      log.line("edit by hand" ,f"{log.rel(f)}:{n}: {line[:100]}")
+
+  return replaced > 0
+
+def uses_locator(f: Path) -> bool:
+  """True when f still loads the engine through a locator line in <head>."""
+  try:
+    text = f.read_text(encoding="utf-8")
+  except Exception:
+    return False
+  for line in text.split("\n"):
+    if LOCATOR_LINE.match(line): return True
+    if HEAD_END.search(line): return False
+  return False
+
+def do_locator(d: Path ,converted: set ,log: Log):
+  """Deletes d's locator unless a version 5 document not converted in this
+  run still uses it."""
+  loc = d / LOCATOR_FILE
+  users = sorted(f.name for f in d.iterdir()
+                 if f.is_file() and f.suffix == ".html"
+                 and f.resolve() not in converted and uses_locator(f))
+  if users:
+    shown = ", ".join(users[:3]) + (" ..." if len(users) > 3 else "")
+    log.line("kept" ,f"{log.rel(loc)}  (still used by {shown})")
+    log.count["stray"] += 1
+    return
+  if not log.preview:
+    try:
+      loc.unlink()
+    except Exception as e:
+      log.line("error" ,f"{log.rel(loc)}: cannot delete: {e}")
+      log.count["error"] += 1
+      return
+  log.act("deleted" ,"would delete" ,loc ,"deleted")
+
+def run_dirs(root: Path ,recursive: bool ,log: Log):
+  for d ,html ,has_locator in walk(root ,recursive):
+    converted = set()
+    for f in html:
+      if do_file(f ,log): converted.add(f.resolve())
+    if has_locator:
+      if converted:
+        do_locator(d ,converted ,log)
+      else:
+        log.line("kept" ,f"{log.rel(d / LOCATOR_FILE)}  (no version 5 document beside it)")
+        log.count["stray"] += 1
+
+def run_files(files: list[Path] ,log: Log):
+  converted = set()
+  dirs = []
+  for f in files:
+    if do_file(f ,log):
+      converted.add(f.resolve())
+      d = f.parent.resolve()
+      if d not in dirs: dirs.append(d)
+  for d in dirs:
+    if (d / LOCATOR_FILE).is_file():
+      do_locator(d ,converted ,log)
+
+
+# ---------------------------------------------------------------- command line
+
+def print_help() -> int:
+  print(__doc__.strip())
+  return 0
+
+def CLI(argv=None) -> int:
+  if argv is None:
+    argv = sys.argv[1:]
+  if not argv or argv[0] in ("help" ,"-h" ,"--help"):
+    return print_help()
+
+  preview = False
+  if argv[0] == "preview":
+    preview = True
+    argv = argv[1:]
+    if not argv:
+      print("Error: 'preview' needs a command after it.\n" ,file=sys.stderr)
+      print_help()
+      return 1
+
+  command ,rest = argv[0] ,argv[1:]
+
+  if command == "file":
+    if not rest:
+      print("Error: 'file' needs at least one file name." ,file=sys.stderr)
+      return 1
+    files = [Path(a) for a in rest]
+    for f in files:
+      if not f.is_file():
+        print(f"Error: {f} is not a file." ,file=sys.stderr)
+        return 1
+    base = Path.cwd().resolve()
+    log = Log(preview ,base)
+    print(f"RT-Style_header_v5_to_v6 {'preview ' if preview else ''}file   in {base}")
+    run_files(files ,log)
+    log.summary()
+    return 1 if log.count["error"] else 0
+
+  if rest:
+    print(f"Error: '{command}' takes no arguments." ,file=sys.stderr)
+    return 1
+
+  if command == "project":
+    repo_home = os.environ.get("REPO_HOME")
+    if not repo_home:
+      print("Error: 'project' needs REPO_HOME to be set." ,file=sys.stderr)
+      return 1
+    root ,recursive = Path(repo_home) ,True
+  elif command == "tree":
+    root ,recursive = Path.cwd() ,True
+  elif command == "local":
+    root ,recursive = Path.cwd() ,False
+  else:
+    print(f"Error: unknown command '{command}'.\n" ,file=sys.stderr)
+    print_help()
+    return 1
+
+  if not root.is_dir():
+    print(f"Error: {root} is not a directory." ,file=sys.stderr)
+    return 1
+
+  base = root.resolve()
+  log = Log(preview ,base)
+  print(f"RT-Style_header_v5_to_v6 {'preview ' if preview else ''}{command}   in {base}")
+  run_dirs(base ,recursive ,log)
+  log.summary()
+  return 1 if log.count["error"] else 0
+
+if __name__ == "__main__":
+  sys.exit(CLI())
diff --git a/administrator/tool/new-project b/administrator/tool/new-project
index 5394bed..c949ddb 100755
--- a/administrator/tool/new-project
+++ b/administrator/tool/new-project
@@ -9,12 +9,15 @@ the Harmony skeleton architecture.
 
 The script executes the following sequential lifecycle:
   1. Validates the execution environment (requires an active role session).
-  2. Safely extracts a clean copy of all Git-tracked files using an archive stream.
-  3. Renames the boilerplate 0pus_Harmony anchor file to reflect the new project.
-  4. Injects an initial version tracking entry into the shared configuration space.
-  5. Initializes a fresh Git repository bound to the core-developer_branch.
-  6. Stages and commits the pristine skeleton infrastructure as a baseline.
-  7. Maps any upstream remote network targets passed via CLI parameters.
+  2. Checks the git status of the skeleton. The new project is made from the
+     last commit, so uncommitted changes and untracked files would be left
+     out. When there are any, lists them and asks whether to continue.
+  3. Safely extracts a clean copy of all Git-tracked files using an archive stream.
+  4. Renames the boilerplate 0pus_Harmony anchor file to reflect the new project.
+  5. Injects an initial version tracking entry into the shared configuration space.
+  6. Initializes a fresh Git repository bound to the core-developer_branch.
+  7. Stages and commits the pristine skeleton infrastructure as a baseline.
+  8. Maps any upstream remote network targets passed via CLI parameters.
 """
 
 import sys ,os ,subprocess
@@ -28,14 +31,31 @@ def get_Z_date() -> str:
   except Exception:
     return "1970-01-01"
 
-def work(project_name: str ,remotes: list[str]) -> int:
-  """Orchestrates the assembly of the new skeleton instance."""
-  repo_home = os.environ.get("REPO_HOME")
-  if not repo_home:
-    print("Error: REPO_HOME is not set. A person must run this from within a sourced role environment." ,file=sys.stderr)
-    return 1
+def uncommitted(repo_path: Path) -> list[str] | None:
+  """Returns the lines of 'git status --porcelain' for the skeleton: one per
+  file with uncommitted changes or untracked. None when git cannot report."""
+  try:
+    res = subprocess.run(
+      ["git" ,"status" ,"--porcelain" ,"--untracked-files=normal"]
+      ,cwd=str(repo_path) ,capture_output=True ,text=True ,check=True
+    )
+  except Exception:
+    return None
+  return [line for line in res.stdout.splitlines() if line.strip()]
+
+def confirm(question: str) -> bool:
+  """Asks a yes or no question at the terminal. Without a terminal to ask
+  at, the answer is no."""
+  if not sys.stdin.isatty():
+    return False
+  try:
+    answer = input(question + " [y/N] ")
+  except EOFError:
+    return False
+  return answer.strip().lower() in ("y" ,"yes")
 
-  repo_path = Path(repo_home).resolve()
+def work(repo_path: Path ,project_name: str ,remotes: list[str]) -> int:
+  """Orchestrates the assembly of the new skeleton instance."""
   
   # Resolve destination relative to the parent space of the current repository
   dest_path = Path(project_name)
@@ -129,7 +149,29 @@ def CLI(argv=None) -> int:
     print("Error: project name is required." ,file=sys.stderr)
     return 1
 
-  return work(project_name ,remotes)
+  repo_home = os.environ.get("REPO_HOME")
+  if not repo_home:
+    print("Error: REPO_HOME is not set. A person must run this from within a sourced role environment." ,file=sys.stderr)
+    return 1
+  repo_path = Path(repo_home).resolve()
+
+  status = uncommitted(repo_path)
+  if status is None:
+    print(f"Error: could not read the git status of {repo_path}." ,file=sys.stderr)
+    return 1
+  if status:
+    shown = status[:20]
+    print(f"Warning: {repo_path} has {len(status)} uncommitted or untracked file(s):")
+    for line in shown:
+      print("  " + line)
+    if len(status) > len(shown):
+      print(f"  ... and {len(status) - len(shown)} more (see 'git status')")
+    print("The new project is made from the last commit, so these will not be in it.")
+    if not confirm("Continue anyway?"):
+      print("Stopped. Nothing was made. Commit or stash the changes, then run new-project again.")
+      return 1
+
+  return work(repo_path ,project_name ,remotes)
 
 if __name__ == "__main__":
   sys.exit(CLI())
diff --git a/developer/tool/build_component/copy b/developer/tool/build_component/copy
index 2939ef3..0a1998c 100755
--- a/developer/tool/build_component/copy
+++ b/developer/tool/build_component/copy
@@ -10,8 +10,8 @@ sys.path.insert(0, os.path.join(os.path.abspath("tool"), "build_component"))
 import sync_engine
 
 HELP = """usage: copy {all|clean|help}
-  all     Stages files from authored to scratchpad.
-  clean   Removes the specified namespace from scratchpad.
+  all     Stages files from authored to scratchpad/made/<namespace>.
+  clean   Removes scratchpad/made/<namespace>.
   help    Shows this message.
 """
 
@@ -24,7 +24,7 @@ def cmd_all():
     sys.exit(1)
 
   src_root = os.path.join("authored", namespace_dir)
-  dst_root = os.path.join("scratchpad", namespace)
+  dst_root = os.path.join("scratchpad", "made", namespace)
 
   sync_engine.execute_sync(src_root, dst_root, prefix="copy", apply_modes=False)
 
@@ -34,7 +34,7 @@ def cmd_clean():
     print("copy: error: NAMESPACE environment variable must be set.", file=sys.stderr)
     sys.exit(1)
 
-  dst_root = os.path.join("scratchpad", namespace)
+  dst_root = os.path.join("scratchpad", "made", namespace)
   if os.path.exists(dst_root):
     shutil.rmtree(dst_root)
   print(f"copy: Cleaned {dst_root}")
diff --git a/document/introduction_Harmony.html b/document/introduction_Harmony.html
index 4271b0b..432c63b 100644
--- a/document/introduction_Harmony.html
+++ b/document/introduction_Harmony.html
@@ -22,9 +22,9 @@
   <body>
     <RT·theme-selector></RT·theme-selector>
     <RT·article>
-      <RT·title 
-        author="Thomas Walker Lynch" 
-        date="2026-06-23" 
+      <RT·title
+        author="Thomas Walker Lynch"
+        date="2026-10-09"
         title="Introduction to Harmony">
       </RT·title>
 
@@ -32,333 +32,217 @@
 
       <h1>Purpose</h1>
       <p>
-        Harmony provides a language-agnostic project directory structure and maintenance tools for long-lived, multi-person team software development. The structure exists to enforce:
+        Harmony is a project skeleton: a language-agnostic directory structure and a set of maintenance tools, kept in a git repository, from which new projects are made. It is designed for long-lived software developed by a team, and serves equally well for one person, who takes on each role in turn. The structure exists to give:
       </p>
       <ol>
         <li>Clarity about where things live.
           <ul>
             <li>Role-based work areas.</li>
-            <li>Separation of skeleton, team member authored, machine-made, and third-party installed software.</li>
+            <li>Separation of skeleton, team member authored, machine-made, and depended-upon software.</li>
           </ul>
         </li>
         <li>A safe, predictable build and promotion workflow.</li>
       </ol>
 
+      <h1>Making a project</h1>
       <p>
-        Harmony is a project skeleton, a set of tools and directories that have been checked into a git repository. To create a Harmony-based project, the project administrator performs these steps:
+        A project administrator makes a new project from a clone of Harmony, by taking on the administrator role and running <RT·code>new-project</RT·code> with the name of the new project:
+      </p>
+      <RT·code>
+        > cd Harmony
+        > ./setup administrator
+        > new-project &lt;name&gt;
+      </RT·code>
+      <p>
+        <RT·code>new-project</RT·code> makes the new project as a sibling directory of Harmony, then:
       </p>
       <ol>
-        <li>Clone the Harmony project to a local directory.</li>
-        <li>Remove the <RT·code>.git</RT·code> tree.</li>
-        <li>Rename the Harmony directory to the name of the new project.</li>
-        <li>Rename the <RT·code>0pus_Harmony</RT·code> file to reflect the name of the new project.</li>
-        <li>Add a line to the <RT·code>shared/tool/version</RT·code> file for the new project.</li>
-        <li><RT·code>git init -b core_developer_branch</RT·code></li>
+        <li>Copies the files of Harmony's last commit, leaving out Harmony's git history, untracked files, and uncommitted changes.</li>
+        <li>Renames <RT·code>0pus_Harmony</RT·code> to <RT·code>0pus_&lt;name&gt;</RT·code>.</li>
+        <li>Adds a line for the new project to <RT·code>shared/tool/version</RT·code>.</li>
+        <li>Initializes a git repository on the <RT·code>core-developer_branch</RT·code> branch, and commits the copied skeleton.</li>
+        <li>Adds any remote repositories given as <RT·code>-remote &lt;url&gt;</RT·code>.</li>
       </ol>
-
       <p>
-        The order is important so as to protect the Harmony skeleton project from accidental check-ins from users.
+        Because the new project starts with its own git history, work done in it cannot be checked in to the Harmony skeleton by accident.
       </p>
       <p>
-        Leave the Harmony skeleton version in the version file, so that project administrators can understand what has changed in the skeleton over time.
+        Leave the Harmony line in the version file. It records which skeleton the project was made from, so that an administrator can later see what has changed in the skeleton since, and bring the project up to date. The administrator tool <RT·code>skeleton_diff</RT·code> compares a project with a Harmony checkout for this purpose.
       </p>
+
+      <h1>Taking on a role</h1>
       <p>
-        The <RT·code>core_developer_branch</RT·code> is the branch that the core development team works on. Project releases are moved to release branches.
+        A person works in a project by taking on a <RT·term>role</RT·term>. The roles are <RT·code>administrator</RT·code>, <RT·code>developer</RT·code>, <RT·code>tester</RT·code>, and <RT·code>consumer</RT·code>. From the top directory of the project, run <RT·code>setup</RT·code> with the role:
       </p>
-
-      <h1>Environment setup</h1>
+      <RT·code>
+        > ./setup developer
+      </RT·code>
       <p>
-        Python programmers who use virtual environments will be familiar with an analogous process. The term 'virtual environment' does not invoke any hardware virtualization features; rather, it is a local environment setup. To avoid confusion, a Harmony user refers instead to the 'project setup'. The command to establish the environment is called 'setup' instead of 'activate'. Also note that in Harmony, unlike in Python, there are multiple setups available, each tailored to the specific role a person takes on.
+        <RT·code>setup</RT·code> starts a new bash shell configured for the role, and leaves the person in the role's directory. The prompt shows the project and the role. <RT·code>exit</RT·code> leaves the role and returns to the shell <RT·code>setup</RT·code> was run from. It is common to have several terminal windows or Emacs shells open, each in a different role.
       </p>
       <p>
-        As of the time of this writing, the defined roles are: <strong>administrator</strong>, <strong>consumer</strong>, <strong>developer</strong>, and <strong>tester</strong>. A person takes on a role by sourcing the top-level <RT·code>setup</RT·code> script and giving the target role as an argument. For example, in a bash shell with <RT·code>></RT·code> as the prompt, the command is:
+        Python programmers will recognize this as similar to a virtual environment. Harmony calls it the project setup, and the command is <RT·code>setup</RT·code> rather than <RT·code>activate</RT·code>. Unlike a Python virtual environment, there is one setup for each role.
       </p>
-
-      <RT·code>
-        > . setup &lt;role&gt;
-      </RT·code>
-
       <p>
-        Specifically for the developer role:
+        In the new shell, the setup:
       </p>
-        
-      <RT·code>
-        > . setup developer
-      </RT·code>
-
+      <ul>
+        <li>Sets <RT·code>ROLE</RT·code>, <RT·code>ROLE_HOME</RT·code> and <RT·code>SETUP</RT·code>, and puts <RT·code>&lt;role&gt;/tool</RT·code> on the <RT·code>PATH</RT·code>.</li>
+        <li>Sources the project-wide <RT·code>shared/tool/setup</RT·code>, which sets <RT·code>REPO_HOME</RT·code> and <RT·code>PROJECT</RT·code>, puts <RT·code>shared/tool</RT·code> and <RT·code>shared/authored</RT·code> on the <RT·code>PATH</RT·code>, and sources each project dependency's <RT·code>.init</RT·code> file.</li>
+        <li>Sources <RT·code>shared/authored/setup</RT·code>, when the project has one, for project-specific additions to every role.</li>
+        <li>Changes into the role's directory and sources <RT·code>&lt;role&gt;/tool/setup</RT·code>, the setup customized for that role in this project.</li>
+        <li>When running inside Emacs, copies the environment to Emacs with <RT·code>env_to_emacs</RT·code>.</li>
+      </ul>
       <p>
-        For the administrator role:
+        Tools rely on this environment. Absolute paths are formed from <RT·code>REPO_HOME</RT·code>, and some tools, such as <RT·code>build</RT·code> and <RT·code>promote</RT·code>, refuse to run outside the role they belong to.
       </p>
-        
-      <RT·code>
-        > . setup administrator
-      </RT·code>
 
+      <h1>Roles and their directories</h1>
       <p>
-        Instead of starting with a period, the <RT·code>source</RT·code> command can be spelled out explicitly, for example:
+        Each role has a directory at the top of the project. The <RT·code>shared</RT·code> directory holds what all roles use.
       </p>
-      
-      <RT·code>
-        > source setup tester
-      </RT·code>
 
+      <h2>Administrator</h2>
       <p>
-        Behind the scenes, the <RT·code>setup</RT·code> script performs the following actions:
+        The administrator keeps the project in step with the Harmony skeleton, maintains the role environments, installs project dependencies, and makes releases. <RT·code>administrator/tool</RT·code> holds the tools for this, among them <RT·code>new-project</RT·code>, <RT·code>skeleton_diff</RT·code>, and <RT·code>archive</RT·code>, which writes an archive of the repository to the scratchpad.
       </p>
 
+      <h2>Developer</h2>
+      <p>
+        The developer writes the project's source and builds it.
+      </p>
       <ul>
-        <li>Sources the project-wide setup (<RT·code>shared/tool/setup</RT·code>) to establish the core environment variables (e.g., <RT·code>REPO_HOME</RT·code> and <RT·code>PROJECT</RT·code>).</li>
-        <li>Conditionally sources <RT·code>shared/authored/setup</RT·code> (if present) to apply administrator-injected, project-specific tool configurations.</li>
-        <li>Dynamically sources all <RT·code>.init</RT·code> files found in the <RT·code>shared/linked-project/</RT·code> directory.</li>
-        <li>Configures the <RT·code>PATH</RT·code> to include shared tools, library environments, and the specific <RT·code>&lt;role&gt;/tool</RT·code> directory.</li>
-        <li>Changes the working directory into the specified role's workspace.</li>
-        <li>Sources the <RT·code>&lt;role&gt;/tool/setup</RT·code> script. While the earlier steps apply the standard Harmony skeleton setup, this final step applies the role setup that is customized for this specific project.</li>
+        <li><RT·code>authored/</RT·code> : Source written by the team. Tracked.</li>
+        <li><RT·code>document/</RT·code> : Documents for developers, such as coding and naming conventions.</li>
+        <li><RT·code>experiment/</RT·code> : Informal, short-lived trials.</li>
+        <li><RT·code>scratchpad/</RT·code> : Untracked. Intermediate build files and the staged products of a build.</li>
+        <li><RT·code>tool/</RT·code> : The developer's tools, including <RT·code>build</RT·code> and <RT·code>promote</RT·code>.</li>
       </ul>
 
-      <h1>After git clone</h1>
+      <h2>Tester</h2>
       <p>
-        Because git does not track certain artifact directories (such as <RT·code>consumer/</RT·code> outputs), a freshly cloned repository lacks external dependencies and consumable products. Team members must perform a few steps to populate these areas.
+        The tester holds the formal tests, including regression suites, and runs them against the work product in <RT·code>consumer/</RT·code>. A developer may keep informal tests in <RT·code>developer/experiment</RT·code>. A test that is to be kept is moved to <RT·code>tester/</RT·code>, which keeps writing code and validating it apart.
       </p>
 
-      <h2>Third-party tools</h2>
-      <p>
-        Harmony is language agnostic. When a project makes use of project-specific C, Python, NodeJS, Java, or other tools, the project administrator configures the project to expect these tools in the <RT·code>shared/linked-project</RT·code> directory via the `.init` plugin system.
-      </p>
+      <h2>Consumer</h2>
       <p>
-        Because multiple team members will have to repeat the third-party install process after cloning a project, the administrator should carefully document the installation steps and place the resulting documents in the <RT·code>administrator/document</RT·code> directory. The standard installation method is to clone the external tool into the parent directory alongside the project, create a symlink to it under <RT·code>shared/linked-project/</RT·code> using the <RT·code>project/</RT·code> parent link, and supply an <RT·code>.init</RT·code> script to manage the local environment variables.
+        <RT·code>consumer/</RT·code> receives the work product when a developer promotes it. It is untracked, apart from its <RT·code>.gitignore</RT·code>, and is treated as a deployment target: files arrive there only through <RT·code>promote</RT·code>, and nothing is built in it. The consumer role uses the work product as its end users would.
       </p>
 
-      <h2>Consumer build</h2>
+      <h2>Shared</h2>
+      <ul>
+        <li><RT·code>shared/tool/</RT·code> : Tools for all roles, and the project-wide setup. The <RT·code>version</RT·code> command prints the version lines.</li>
+        <li><RT·code>shared/authored/</RT·code> : Project-specific additions for all roles. It is on every role's <RT·code>PATH</RT·code>, and may hold a <RT·code>setup</RT·code> that every role sources.</li>
+        <li><RT·code>shared/project-dependency/</RT·code> : Software the project uses but did not author. See "Project dependencies" below.</li>
+      </ul>
+
+      <h1>Building and promoting</h1>
       <p>
-        In this section we use the term 'consumer' to mean any team member that wants to make use of the project work product. The tester will want to test it, and the consumer role will want to deploy it, etc.
+        Building and promotion are separate steps. In the developer role, <RT·code>build</RT·code> makes the work product from <RT·code>developer/authored</RT·code> and stages it on the developer's scratchpad. <RT·code>promote write</RT·code> then copies what changed to <RT·code>consumer/</RT·code>. The result is a <RT·term>promotion candidate</RT·term>, which stays as it is until the next promotion.
       </p>
       <p>
-        Because compiled binaries and final layouts are not tracked in the repository, the current version of Harmony requires a work product consumer to run a local build after cloning the project. The results of the build will appear directly in the <RT·code>consumer/</RT·code> directory.
+        Source in <RT·code>developer/authored</RT·code> is grouped into directories named <RT·code>&lt;Namespace&gt;.&lt;Tool&gt;</RT·code>. The suffix names the build component in <RT·code>developer/tool/build_component</RT·code> that builds that directory, such as <RT·code>make</RT·code> for C, or <RT·code>copy</RT·code> for files used as they are. Given no arguments, <RT·code>build</RT·code> prints its usage and the namespaces it found. <RT·code>promote</RT·code> given no arguments prints its commands, among them <RT·code>dry write</RT·code>, which shows what <RT·code>write</RT·code> would copy.
       </p>
       <p>
-        To facilitate this, the developer must explicitly document the project's build and promote procedure, saving this guide as <RT·code>developer/document/build.html</RT·code>. The consumer must then read this document and execute the described steps to locally populate their <RT·code>consumer/</RT·code> directory.
+        The tester runs tests against the promotion candidate. Tests read from <RT·code>consumer/</RT·code> and never write to it, though a tester may copy files elsewhere to experiment with them. A developer often has a second window open in the tester role, and cycles through edit, build, promote and test.
       </p>
 
+      <h2>After cloning a project</h2>
       <p>
-        Because the build and promotion tools are strictly isolated within the developer workspace, the consumer must temporarily put on the developer hat to perform the build. Typically the consumer build procedure will be a variation of the following:
+        Built products are not tracked, so a fresh clone has an empty <RT·code>consumer/</RT·code>. A team member who needs the work product builds it, taking on the developer role to do so:
       </p>
-
-      <ol>
-        <li><RT·code>> bash</RT·code></li>
-        <li><RT·code>> cd &lt;project&gt;</RT·code></li>
-        <li><RT·code>> . setup developer</RT·code></li>
-        <li><RT·code>> build &lt;namespace&gt;</RT·code></li>
-        <li><RT·code>> promote write</RT·code></li>
-        <li><RT·code>> exit</RT·code></li>
-        <li><RT·code>> bash</RT·code></li>
-        <li><RT·code>> cd &lt;project&gt;</RT·code></li>
-        <li><RT·code>> . setup &lt;role&gt;</RT·code></li>
-      </ol>
-
+      <RT·code>
+        > ./setup developer
+        > build &lt;namespace&gt;
+        > promote write
+        > exit
+        > ./setup &lt;role&gt;
+      </RT·code>
       <p>
-        This sequence opens a bash shell, assumes the developer role to orchestrate the build, makes the work product, then promotes it to the consumer's workspace. The <RT·code>exit</RT·code> command drops the developer role. The last two lines put the person into the &lt;role&gt; workspace, typically for testing or deploying.
+        The developer documents any project-specific build steps in <RT·code>developer/document/build.html</RT·code>. A fresh clone also lacks the project's dependencies, which each team member installs as described beside each dependency in <RT·code>shared/project-dependency</RT·code>.
       </p>
 
-
-      <h1>Directory semantic properties</h1>
+      <h1>Project dependencies</h1>
       <p>
-        This section discusses our thinking in naming the files and directories found in the Harmony skeleton.
+        Harmony is language agnostic. When a project uses C, Python, NodeJS, Java, or other software it did not author, the administrator installs that software as a sibling directory of the project and links it in under <RT·code>shared/project-dependency</RT·code>, with an <RT·code>.init</RT·code> file that every role's setup sources to put the dependency into the environment. Installation notes for each dependency sit beside its <RT·code>.init</RT·code> file, so that each team member can repeat the installation after cloning.
       </p>
       <p>
-        A directory name is considered to be a <RT·term>property</RT·term> given to each file contained in the directory. A full path then forms a semantic sentence describing each file.
+        The directory comes with a <RT·code>project</RT·code> link to the directory holding the project and its siblings, through which dependencies are linked, and with Python as an example dependency. The steps are given in <RT·code>administrator/document/how-to_add-project-dependency.html</RT·code>.
       </p>
+
+      <h1>Directory names</h1>
       <p>
-        Because a directory name represents a property, it is rarely plural. For example, when each and every file in a directory is a test, the directory is named <RT·code>test</RT·code>.
+        A directory name is a <RT·term>property</RT·term> of each file in the directory, so a full path reads as a description of the file. Because a name states a property of each file, it is rarely plural: when every file in a directory is a test, the directory is named <RT·code>test</RT·code>.
       </p>
       <p>
-        We run into limitations when using a conventional file system as though it were a property based file system. One limitation is that we are forced to choose a single directory name for each file. When a set of files in a directory all share the same multiple properties, we can use a compound directory name with the properties separated by an underscore, but it is impractical to specify overlapping directory groupings, i.e. we can't arbitrarily define any number of properties for a file in this manner.
+        A conventional file system can only approximate a property-based one. Each file sits in one directory, so it receives one property per level of the path. Files sharing several properties can be given a compound name with the properties separated by an underscore, but overlapping groupings cannot be expressed.
       </p>
       <p>
-        The following list presents each property type in order of preference when naming directories:
+        When choosing a directory name, prefer properties in this order:
       </p>
       <ul>
-        <li><strong>Role Association</strong> (<RT·code>administrator</RT·code>, <RT·code>developer</RT·code>, <RT·code>tester</RT·code>, <RT·code>consumer</RT·code>): Identifies the persona, whether human or AI, intended to interact with the files.</li>
-        <li><strong>Provenance</strong> (<RT·code>authored</RT·code>, <RT·code>made</RT·code>): Indicates whether the file was created by an intellect or mechanically produced by a tool.</li>
-        <li><strong>Capability</strong> (<RT·code>tool</RT·code>, <RT·code>document</RT·code>, <RT·code>experiment</RT·code>): Describes the primary function or structural nature of the file.</li>
-        <li><strong>Lifecycle State</strong> (<RT·code>scratchpad</RT·code>, <RT·code>stage</RT·code>): Denotes the persistence, volatility, or promotion status of the file.</li>
-        <li><strong>Tracking Status</strong> (<RT·code>tracked</RT·code>, <RT·code>untracked</RT·code>): Specifies the version control expectations for the artifacts.</li>
+        <li><strong>Role</strong> (<RT·code>administrator</RT·code>, <RT·code>developer</RT·code>, <RT·code>tester</RT·code>, <RT·code>consumer</RT·code>): the role, human or AI, that works with the files.</li>
+        <li><strong>Provenance</strong> (<RT·code>authored</RT·code>, <RT·code>made</RT·code>): whether a person wrote the file or a tool produced it.</li>
+        <li><strong>Capability</strong> (<RT·code>tool</RT·code>, <RT·code>document</RT·code>, <RT·code>experiment</RT·code>): what the file is for.</li>
+        <li><strong>Lifecycle</strong> (<RT·code>scratchpad</RT·code>, <RT·code>stage</RT·code>): how long the file is expected to last, or where it is in promotion.</li>
+        <li><strong>Tracking</strong> (<RT·code>tracked</RT·code>, <RT·code>untracked</RT·code>): what version control does with it.</li>
       </ul>
 
       <h2>Authored, made, scratchpad, inherited</h2>
       <p>
-        Files found in a directory named <RT·code>authored</RT·code> were written by project team members. They did not come with the Harmony skeleton, nor with the installation of other software. Project build tools treat <RT·code>authored</RT·code> directories as strictly read-only. Typically these files constitute the intellectual property of a project.
-      </p>
-      <p>
-        All source code that gets built into a promotion or project release must be placed in the developers' <RT·code>authored</RT·code> directory. The story is not as clean for build tools and other files. New documents go into document directories, and new tools go into the tool directories, etc. As a specific example, the developer will almost certainly edit the <RT·code>developer/tool/build</RT·code> file.
-      </p>
-      <p>
-        When the Harmony version line in the <RT·code>shared/tool/version</RT·code> file is left in place, it is straightforward for a project administrator to determine which Harmony skeleton files have been edited in a project, and which new files have been added.
-      </p>
-      <p>
-        Files found in a directory named <RT·code>scratchpad</RT·code> are not tracked. Hence, a <RT·code>git clone</RT·code> will always return empty <RT·code>scratchpad</RT·code> directories. It is common for tools to place intermediate files on a scratchpad. It is also common for files to be staged on a scratchpad. Tools play nice and use subdirectories on the pad, so a person who is aware of those subdirectory names can use a scratchpad as a temporary directory. There is a scratchpad maintenance tool that comes with the Harmony, called unimaginatively, <RT·code>scratchpad</RT·code>. Pay attention as one of its commands is <RT·code>clear</RT·code>, and that deletes everything on the current directory's scratchpad.
-      </p>
-      <p>
-        Third party software is installed under <RT·code>shared/linked-project</RT·code>. Other files are said to be <RT·term>inherited</RT·term>, or to be <RT·term>customizations</RT·term>.
+        Files in a directory named <RT·code>authored</RT·code> were written by the project's team. They did not come with the skeleton, nor with the installation of other software, and they typically constitute the project's intellectual property. Build tools treat <RT·code>authored</RT·code> directories as read-only. All source that is built into a promotion or a release is placed in <RT·code>developer/authored</RT·code>.
       </p>
-
-      <h1>Top-level repository layout</h1>
       <p>
-        A team member will source the project setup file to take on a role. As of this writing, the supported roles are: <RT·code>administrator</RT·code>, <RT·code>developer</RT·code>, <RT·code>tester</RT·code>, and <RT·code>consumer</RT·code>.
+        Files that came with the skeleton are <RT·term>inherited</RT·term>. When the team edits one, such as <RT·code>developer/tool/build</RT·code>, it becomes a <RT·term>customization</RT·term>. New documents go in document directories and new tools in tool directories. Because the Harmony line stays in the version file, an administrator can tell which skeleton files a project has customized and which it has added.
       </p>
-
-      <ul>
-        <li><RT·code>administrator/</RT·code> : Project-local tools and skeleton maintenance.</li>
-        <li><RT·code>developer/</RT·code> : Primary workspace for developers.</li>
-        <li><RT·code>tester/</RT·code> : Regression and validation workspace for testers.</li>
-        <li><RT·code>consumer/</RT·code> : Consumption workspace acting as the final artifact sink.</li>
-        <li><RT·code>shared/</RT·code> : Shared ecosystem tools and global environments.</li>
-      </ul>
-
-      <h2>The administrator work area</h2>
       <p>
-        This directory holds the tools and documentation used to manage the project as a whole. It includes the HTML documentation for the project ontology and workflow, as well as project-local tools utilized by the administrator to maintain the Harmony skeleton.
+        Files in a directory named <RT·code>scratchpad</RT·code> are untracked, so a clone always has empty scratchpads. Tools place intermediate and staged files there, each in its own subdirectory, so a person who knows those names can also use a scratchpad as a temporary directory. The <RT·code>scratchpad</RT·code> tool maintains the scratchpad of the current directory. Note that its <RT·code>clear</RT·code> command deletes everything on that scratchpad.
       </p>
 
-      <h2>The developer work area</h2>
+      <h1>Documents</h1>
       <p>
-        This directory is entered by first going to the top-level directory of the project, then sourcing <RT·code>. setup developer</RT·code>.
+        Each directory named <RT·code>document</RT·code> holds documents for the role, or the scope, of its parent:
       </p>
       <ul>
-        <li><RT·code>authored/</RT·code> : Human-written source. Tracked by Git.</li>
-        <li><RT·code>made/</RT·code> : Tracked artifacts generated by tools (e.g., links to CLI entry points).</li>
-        <li><RT·code>experiment/</RT·code> : Try-it-here code. Short-lived spot testing.</li>
-        <li><RT·code>scratchpad/</RT·code> : Git-ignored directory. Holds all intermediate build outputs, including the staged namespace directories for promotions.</li>
-        <li><RT·code>tool/</RT·code> : Developer-specific tools (like the promote and build scripts).</li>
+        <li><RT·code>document/</RT·code> : The project as a whole, such as this introduction.</li>
+        <li><RT·code>administrator/document/</RT·code> : Maintaining the project skeleton, adding dependencies, and making releases.</li>
+        <li><RT·code>developer/document/</RT·code> : Coding standards, conventions, and the build.</li>
+        <li><RT·code>tester/document/</RT·code> : Test plans and testing tools.</li>
+        <li><RT·code>consumer/&lt;namespace&gt;/document/</RT·code> : Documents released with the work product, such as manuals and API references.</li>
       </ul>
-
-      <h2>The tester work area</h2>
       <p>
-        This directory is dedicated to formal testing, including regression suites. While a developer can run and keep informal spot tests in their <RT·code>experiment/</RT·code> directory, any experiment promoted to a formal test is moved here. This enforces the boundary between writing code and validating it.
+        Documents are written in HTML with the RT semantic tags, and formatted by RT-Style, a separate project at <RT·code>https://github.com/Thomas-Walker-Lynch/RT-Style</RT·code>. A document loads RT-Style through a short script block at the top of its head. To write a new document, copy an existing one, keep that block as it is, and type over the contents.
       </p>
-
-      <h2>The shared tree</h2>
       <p>
-        This directory contains ecosystem tools and global environments available to all roles. This includes the shared tool directory, as well as third-party symlinks and <RT·code>.init</RT·code> scripts required by the project. To assist in project specific modifications to the Harmony skeleton, Harmony comes with an empty <RT·code>shared/authored</RT·code> directory that is listed earlier in the executable search path than <RT·code>shared/tool</RT·code>.
+        Documents are read in Chrome. With nothing set up, a document loads RT-Style from <RT·code>style.ReasoningTechnology.com</RT·code>. To read without a network connection, or against a local copy of RT-Style, open that copy's <RT·code>Manuscript/setup.html</RT·code> once in Chrome. Chrome then loads RT-Style from it for every local document.
       </p>
-
-      <h2>The consumer tree</h2>
       <p>
-        The <RT·code>consumer/</RT·code> tree is where developers put work product that is ready to be consumed. The entire directory is git-ignored and treated as a transient deployment target. Artifacts arrive in the <RT·code>consumer/</RT·code> tree <em>only</em> when the promote script is invoked, which performs a flat-copy from the developer's <RT·code>scratchpad/made</RT·code> directory.
+        <RT·code>document/writing_tool-script.html</RT·code> gives the conventions for writing tools.
       </p>
 
-      <h2>Document directories</h2>
+      <h1>What git tracks</h1>
       <p>
-        There is a directory for documents that talks about the project as a whole, one for each role, one for tools that are shared among the roles, and the released work product probably comes with a document directory of its own.
+        Everything is tracked except:
       </p>
       <ul>
-        <li><RT·code>document/</RT·code> : Top-level onboarding, project-wide structure, such as this document.</li>
-        <li><RT·code>consumer/&lt;namespace&gt;/document/</RT·code> : Documentation for end-users of made code (e.g., man pages, application manuals, library API references).</li>
-        <li><RT·code>administrator/document/</RT·code> : Documentation for maintaining the project skeleton and global tools.</li>
-        <li><RT·code>developer/document/</RT·code> : Documentation for developers, including coding standards and internal API guides.</li>
-        <li><RT·code>tester/document/</RT·code> : Documentation for testers detailing test plans and tools.</li>
-        <li><RT·code>shared/document/</RT·code> : Documentation on installing and configuring shared tools.</li>
+        <li><RT·code>consumer/</RT·code>, apart from its <RT·code>.gitignore</RT·code>.</li>
+        <li>Every <RT·code>scratchpad/</RT·code>, apart from its <RT·code>.gitignore</RT·code>.</li>
+        <li>In <RT·code>shared/project-dependency/</RT·code>, whatever its <RT·code>.gitignore</RT·code> does not list as tracked.</li>
+        <li>Archives, editor backups, and compiled files, as listed in the top-level <RT·code>.gitignore</RT·code>.</li>
       </ul>
 
+      <h1>Workflow and releases</h1>
       <p>
-        Currently, our developers write documents directly in HTML using the RT semantic tags. See the <RT·code>RT·Style</RT·code> project and the documentation there. A common approach is to copy another document and the <RT·code>setup.js</RT·code> file, then to type over the top of that other document.
-      </p>
-
-      <h2>Untracked directories</h2>
-      <ol>
-        <li><RT·code>consumer/</RT·code> (Excluding the base <RT·code>.gitignore</RT·code>)</li>
-        <li><RT·code>shared/linked-project/</RT·code> (Excluding <RT·code>.init</RT·code> and <RT·code>.gitignore</RT·code> files)</li>
-        <li><RT·code>**/scratchpad/</RT·code></li>
-      </ol>
-
-      <h1>Workflow</h1>
-      <p> See the document "Product Development Roles and Workflow" for more details.</p>
-
-      <h1>Developer promotion and project releases</h1>
-      <p>
-        As a first step, a developer creates a <RT·term>promotion candidate</RT·term> inside of the <RT·code>consumer/</RT·code> directory. This is typically done by running <RT·code>build</RT·code> to stage the artifacts into <RT·code>scratchpad/made</RT·code>, followed by running <RT·code>promote write</RT·code>. The developer will often modify the versions of one or both of those tools that come with the Harmony skeleton. The promotion candidate remains stable until the next <RT·term>promotion</RT·term>.
-      </p>
-      <p>
-        Then the tester runs tests on the promotion candidate. Tests must only read from the <RT·code>consumer/</RT·code> directory, though local copies can be made and edited as experiments.
+        The project moves forward through a cycle: the developer promotes a candidate, the tester tests it and files issues, and the developer fixes them and promotes again. The <RT·code>core-developer_branch</RT·code> is the branch the core development team works on. When the product manager judges the work product reliable and complete enough, the administrator makes a <RT·term>project release</RT·term> on a branch named <RT·code>release_v&lt;major&gt;</RT·code>, and tags it.
       </p>
       <p>
-        It is common for a developer to open a second window on his desktop, and then enter the project as a tester in that second window. The developer can then make a promotion candidate, run the tests, edit source code, and perhaps tests, and then quickly spin through the test-debug-fix-promote cycle repeatedly.
+        These documents give the details:
       </p>
-      <p>
-        When the product manager determines the work product to be sufficiently reliable and feature rich, the administrator will make a <RT·term>project release</RT·term>. He will do this by creating a branch called <RT·code>release_v&lt;major&gt;</RT·code> and tagging it. The major release numbers go up incrementally.
-      </p>
-
-      <h1>The Harmony directory tree</h1>
-
-      <RT·code>
-      2026-06-23 13:41:45 Z [Harmony:administrator] Thomas_developer@StanleyPark
-      §/home/Thomas/subu_data/developer/project§
-      > tree Harmony
-      Harmony
-      ├── 0pus_Harmony
-      ├── administrator
-      │ ├── authored
-      │ ├── document
-      │ │ └── setup.js
-      │ └── tool
-      │   ├── archive
-      │   └── setup
-      ├── consumer
-      │ └── .gitignore
-      ├── developer
-      │ ├── authored
-      │ │ └── hello.CLI.c
-      │ ├── document
-      │ │ ├── 02_RT_Code_Format.html
-      │ │ ├── 03_Naming_and_Directory_Conventions.html
-      │ │ ├── 04_Language_Addenda.html
-      │ │ └── setup.js
-      │ ├── experiment
-      │ ├── made
-      │ ├── scratchpad
-      │ └── tool
-      │   ├── do_all
-      │   ├── build
-      │   ├── makefile
-      │   ├── promote
-      │   └── setup
-      ├── document
-      │ ├── introduction_Harmony.html
-      │ ├── role-and-workflow_product-development.html
-      │ └── setup.js
-      ├── LICENSE
-      ├── README.md
-      ├── scratchpad
-      ├── setup
-      ├── shared
-      │ ├── authored
-      │ ├── document
-      │ │ ├── install_generic.org
-      │ │ ├── install_Python.org
-      │ │ └── setup.js
-      │ ├── made
-      │ ├── dictionary_style-directory.js
-      │ ├── linked-project
-      │ │ ├── project -> ../../../
-      │ │ ├── Python-3.12.3 -> project/Python-3.12.3
-      │ │ ├── Python.init
-      │ │ ├── RT·Style -> project/RT·Style/consumer
-      │ │ └── RT·Style.init
-      │ └── tool
-      │   ├── scratchpad
-      │   ├── setup
-      │   ├── style
-      │   └── version
-      └── tester
-          ├── authored
-          │ └── test_routine.sh
-          ├── RT_Format
-          │ ├── RT_Format
-          │ ├── RT·formatter.el
-          │ ├── data_test-0.c
-          │ └── data_test-1.py
-          └── tool
-              └── setup
-      </RT·code>
+      <ul>
+        <li><RT·code>document/role-and-workflow_product-development.html</RT·code> : The roles, and how their work interacts.</li>
+        <li><RT·code>document/role-and-workflow_product-maintenance.html</RT·code> : Issues, triage, and patching releases.</li>
+        <li><RT·code>administrator/document/how-to_release.html</RT·code> : Making a release.</li>
+      </ul>
 
     </RT·article>
   </body>
diff --git a/document/writing_tool-script.html b/document/writing_tool-script.html
new file mode 100644
index 0000000..5942d3f
--- /dev/null
+++ b/document/writing_tool-script.html
@@ -0,0 +1,287 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Writing a tool script</title>
+    <script>
+      {
+        let dirpr_library = null;
+        try{ dirpr_library = localStorage.getItem("RT.dirpr_library"); }catch(e){}
+        window.RT = window.RT || {};
+        RT.dirpr_library = RT.dirpr_library || dirpr_library || "https://style.ReasoningTechnology.com/Manuscript";
+        document.write('<script src="' + RT.dirpr_library + '/Core/RT-Manuscript_make.js"><\/script>');
+      }
+    </script>
+    <script>
+      window.RT.theme_preference('inverse_wheat');
+      window.RT.load('Layout/paginate');
+      window.RT.load('Layout/article_tech_ref');
+      window.RT.load('Element/theme_selector');
+    </script>
+  </head>
+  <body>
+    <RT·theme-selector></RT·theme-selector>
+    <RT·article>
+      <RT·title
+        author="RT"
+        date="2026-10-09"
+        title="Writing a tool script">
+      </RT·title>
+
+      <RT·TOC level="1"></RT·TOC>
+
+      <h1>Purpose</h1>
+
+      <p>
+        A tool is a script a person runs from a role setup to do work on files. This document gives the conventions for how an RT tool presents itself on the command line, reports what it does, and changes files safely. It complements <RT·code>RT-code-format.html</RT·code>, which covers identifier names, layout, and the separation of the <RT·code>CLI()</RT·code> function from the work functions. Those rules apply here and are not repeated.
+      </p>
+
+      <p>
+        The conventions serve three needs of the person at the keyboard. They must be able to see what a tool will do before it does it, read afterward what it did, and run it again without harm.
+      </p>
+
+      <p>
+        Examples are taken from <RT·code>RT-Style_header_v5_to_v6</RT·code>, the administrator tool that converts RT-Style version 5 document headers to version 6.
+      </p>
+
+      <h1>The command line</h1>
+
+      <h2>No arguments prints the help</h2>
+
+      <p>
+        A tool given no arguments prints its help message and exits with status 0. A person who types the bare name of a tool is asking what it does. Nothing on the file system changes.
+      </p>
+
+      <h2>The first argument is a command</h2>
+
+      <p>
+        The first argument names a command, written as a word, not a flag. The words <RT·code>help</RT·code>, <RT·code>-h</RT·code> and <RT·code>--help</RT·code> all print the help message. Further arguments, when a command accepts any, follow the command. A command that accepts no further arguments rejects them with an error.
+      </p>
+
+      <p>
+        An unknown command prints an error naming it, then the help message, and exits with a nonzero status.
+      </p>
+
+      <h2>The help message is the module docstring</h2>
+
+      <p>
+        In Python the help message is the module docstring, printed by <RT·code>print(__doc__.strip())</RT·code>. The documentation at the top of the file and the message the person sees are then the same text, and cannot drift apart. The docstring opens with the tool name, a paragraph on what the tool does, then the usage and one line per command:
+      </p>
+
+      <RT·code>
+        Usage: RT-Style_header_v5_to_v6 &lt;command&gt; [file ...]
+               RT-Style_header_v5_to_v6 preview &lt;command&gt; [file ...]
+
+          help | -h | --help   print this message (also printed when given no arguments)
+          project              walk the directory tree rooted at $REPO_HOME
+          tree                 walk the directory tree rooted at the current directory
+          local                only the current directory, no subdirectories
+          file &lt;name&gt; ...      only the named .html files
+          preview &lt;command&gt;    print the log of what &lt;command&gt; would do, change nothing
+      </RT·code>
+
+      <h2>Scope commands</h2>
+
+      <p>
+        A tool that acts on files found in a directory tree offers the same four commands for choosing which files:
+      </p>
+      <ul>
+        <li><RT·code>project</RT·code> walks the tree rooted at <RT·code>$REPO_HOME</RT·code>. When <RT·code>REPO_HOME</RT·code> is not set, the command is an error. Otherwise it behaves as <RT·code>tree</RT·code> run from <RT·code>$REPO_HOME</RT·code>, from whatever directory the person is in.</li>
+        <li><RT·code>tree</RT·code> walks the tree rooted at the current directory.</li>
+        <li><RT·code>local</RT·code> acts on the current directory only, without descending.</li>
+        <li><RT·code>file</RT·code> acts on the files named after it.</li>
+      </ul>
+
+      <p>
+        Only <RT·code>project</RT·code> depends on a Harmony project. The others work anywhere, because the files a tool serves are not always in a project. RT-Style documents, for example, appear in projects and outside them.
+      </p>
+
+      <h2>Preview</h2>
+
+      <p>
+        A tool that changes files offers <RT·code>preview</RT·code>, placed before any other command. <RT·code>preview tree</RT·code> prints the log that <RT·code>tree</RT·code> would print and changes nothing. The person reads it, decides, then runs the command without <RT·code>preview</RT·code>.
+      </p>
+
+      <p>
+        Preview is not a separate code path. The work functions are given a <RT·code>preview</RT·code> flag and test it only at the point of each action, immediately before writing or deleting. Everything else, finding files, deciding what to do, and logging, runs the same in both modes. A preview log that came from different code could not be trusted to describe the real run.
+      </p>
+
+      <h1>The log</h1>
+
+      <p>
+        A tool that acts on files prints a log of each thing it did. The log is for a person reading a terminal, and for that same person reading it again in a scrollback or a saved file later. This is the log of converting the Harmony skeleton documents, with the path on the first line shortened to fit the page:
+      </p>
+
+      <RT·code>
+        RT-Style_header_v5_to_v6 project   in /home/Thomas/.../project/Harmony
+          converted       administrator/document/how-to_release.html
+          converted       developer/document/naming_file-and-directory.html
+          converted       developer/document/single-file_C-module-and-namespace.html
+          converted       document/introduction_Harmony.html
+          converted       document/role-and-workflow_product-development.html
+          converted       document/role-and-workflow_product-maintenance.html
+
+        summary:
+             6  .html files converted to version 6
+             0  RT-Manuscript_locator.js files deleted
+             0  .html files already version 6
+             0  .html files with mentions to edit by hand
+             0  other .html files left alone
+      </RT·code>
+
+      <ul>
+        <li>The first line names the tool, the command, and the absolute directory the work is rooted in, so a saved log says where it came from.</li>
+        <li>Each action is one line. A fixed-width tag in the past tense says what happened, followed by the path relative to the root. Relative paths keep lines short and make logs from different machines comparable.</li>
+        <li>In a preview the tags read <RT·code>would convert</RT·code>, <RT·code>would delete</RT·code>, and the summary ends with <RT·code>preview only: nothing was changed</RT·code>.</li>
+        <li>A decision not to act is logged too, with the reason in parentheses, as in <RT·code>kept  shared/document/RT-Manuscript_locator.js  (no version 5 document beside it)</RT·code>. A file the tool left alone on purpose must be distinguishable from one it missed.</li>
+        <li>Work the tool cannot do safely is logged with the tag <RT·code>edit by hand</RT·code>, the file, the line number and the line, as in <RT·code>edit by hand  .../Document/user.html:83: &amp;lt;script src=...</RT·code>, so a person can go straight to it.</li>
+        <li>A summary of counts ends the log. A count line that would always be zero for a run, such as errors, may be left out when it is zero.</li>
+        <li>Walk directories and files in sorted order, so two runs over the same tree produce the same log.</li>
+      </ul>
+
+      <p>
+        Errors are logged on their own lines with the tag <RT·code>error</RT·code>, the tool carries on with the remaining files, and the exit status is nonzero when any error occurred. Errors in the command line itself are printed to standard error before any work starts.
+      </p>
+
+      <h1>Walking directories</h1>
+
+      <p>
+        A tool walks every directory in its scope, whatever the directory is named. It does not skip directories by name, since a name that means nothing to the tool's author may hold files that matter to its user.
+      </p>
+
+      <p>
+        A tool does not follow symbolic links to directories. A Harmony project has <RT·code>shared/project-dependency/project</RT·code> pointing to <RT·code>../../../</RT·code>, the directory holding all the projects. Following it would send the walk into every neighboring project and around the loop back into this one. In Python, <RT·code>os.walk</RT·code> does not follow such links unless given <RT·code>followlinks=True</RT·code>, so leave that argument out.
+      </p>
+
+      <h1>Paths</h1>
+
+      <p>
+        A tool forms an absolute path only by starting from an environment variable that the role setup provides, such as <RT·code>$REPO_HOME</RT·code>. Paths the tool writes into files, and symbolic links it creates, are relative.
+      </p>
+
+      <p>
+        An absolute path written into a file is correct for only one view of the file system. Under the subu arrangement, the master user reaches a sub-user's files through a mapped mount at a different absolute path from the one the sub-user sees. A path recorded by one of them is then unreadable, or points somewhere else, for the other. A relative path is resolved from wherever the file is reached, so it is correct in every view.
+      </p>
+
+      <h1>Changing files safely</h1>
+
+      <h2>Checkpoint first</h2>
+
+      <p>
+        A tool edits files in place and does not make backup copies. The person checkpoints the project with git before running it, and reviews the result with <RT·code>git diff</RT·code>. Run <RT·code>preview</RT·code> first.
+      </p>
+
+      <h2>Change only what is recognized exactly</h2>
+
+      <p>
+        Match the precise form the tool was written to change, in the precise place it occurs. <RT·code>RT-Style_header_v5_to_v6</RT·code> replaces a locator script line only when it stands alone on a line inside <RT·code>&lt;head&gt;</RT·code>. A mention of the locator anywhere else, such as an escaped example in a manual, is not touched. It is logged for a person to edit.
+      </p>
+
+      <h2>Keep everything not being changed</h2>
+
+      <p>
+        Carry over what the edit is not about: the indentation of a replaced line, line endings, file permissions, and every other line of the file byte for byte. After a run, <RT·code>git diff</RT·code> should show the intended change and nothing else.
+      </p>
+
+      <h2>Running twice does no harm</h2>
+
+      <p>
+        A second run of the same command finds nothing left to do, changes nothing, and says so in its summary. A tool achieves this by recognizing work already done. The header converter counts a file holding the version 6 block as <RT·code>already version 6</RT·code> and leaves it alone. A person can therefore rerun a tool to confirm a job is complete, or to finish one that stopped part way.
+      </p>
+
+      <h2>Before deleting, check nothing still uses it</h2>
+
+      <p>
+        A tool deletes a file only when nothing remaining depends on it. In testing, the header converter run with <RT·code>file</RT·code> on two of six test documents in a directory deleted the shared locator file while the other four still needed it. The rule now is that a locator is deleted only when no unconverted version 5 document beside it still loads it. Otherwise it is kept, and the log names the documents still using it.
+      </p>
+
+      <h2>Leave alone what the tool cannot identify as its own</h2>
+
+      <p>
+        A file with the right name in an unexpected place is not evidence that the tool should remove it. The converter keeps a locator file that has no version 5 document beside it, and logs it as <RT·code>kept</RT·code>, leaving the decision to a person.
+      </p>
+
+      <h1>Testing a tool</h1>
+
+      <p>
+        Test a new tool on a copy of real material before it runs on the original. An archive of the project, extracted into a scratch directory, gives realistic files that can be discarded.
+      </p>
+      <ol>
+        <li>Run with no arguments, an unknown command, and each command's error cases, such as <RT·code>project</RT·code> with <RT·code>REPO_HOME</RT·code> unset or <RT·code>file</RT·code> naming a file that does not exist.</li>
+        <li>Run <RT·code>preview</RT·code> and confirm that nothing changed, for example with <RT·code>diff -r</RT·code> against an untouched copy.</li>
+        <li>Run each scope command from more than one directory, including from outside any project.</li>
+        <li>Run each command twice. The second run must report nothing left to do.</li>
+        <li>Run on part of a job, such as <RT·code>file</RT·code> on some of the documents in a directory, and confirm the rest still work.</li>
+        <li>Read the diff of a changed file in full.</li>
+      </ol>
+
+      <h1>A skeleton</h1>
+
+      <p>
+        A Python tool laid out to these conventions begins with <RT·code>#!/usr/bin/env python3</RT·code>, then the Emacs mode line the Harmony tools carry, which sets two-space indentation and no tabs. The rest of the skeleton follows:
+      </p>
+
+      <RT·code>
+        """
+        tool_name
+
+        What the tool does, in a paragraph.
+
+        Usage: tool_name &lt;command&gt; [file ...]
+               tool_name preview &lt;command&gt; [file ...]
+
+          help | -h | --help   print this message, also printed given no arguments
+          project              walk the tree rooted at $REPO_HOME
+          tree                 walk the tree rooted at the current directory
+          local                only the current directory
+          file &lt;name&gt; ...      only the named files
+          preview &lt;command&gt;    print the log of &lt;command&gt;, change nothing
+        """
+
+        import sys ,os
+        from pathlib import Path
+
+        def work(dirpa_root ,recursive ,preview):
+          ...
+
+        def print_help():
+          print(__doc__.strip())
+          return 0
+
+        def CLI(argv=None):
+          if argv is None: argv = sys.argv[1:]
+          if not argv or argv[0] in ("help" ,"-h" ,"--help"): return print_help()
+
+          preview = argv[0] == "preview"
+          if preview: argv = argv[1:]
+          if not argv:
+            print("Error: 'preview' needs a command after it." ,file=sys.stderr)
+            return 1
+
+          command ,rest = argv[0] ,argv[1:]
+          ...
+
+        if __name__ == "__main__":
+          sys.exit(CLI())
+      </RT·code>
+
+      <h1>Exercises</h1>
+
+      <h2>Exercise 1: The bare tool</h2>
+      <p>
+        A tool named <RT·code>tidy</RT·code> deletes editor backup files ending in <RT·code>~</RT·code>. When run with no arguments it deletes them from the current directory. List what is wrong with that behavior under these conventions, and give the command line it should have instead.
+      </p>
+
+      <h2>Exercise 2: A log line</h2>
+      <p>
+        A tool prints <RT·code>Processing /home/Thomas/subu/developer/project/Two/document/a.html ... done</RT·code> for every file it looks at, whether or not it changed it. Rewrite the log for a run in which one of three files was changed, one was already correct, and one could not be read.
+      </p>
+
+      <h2>Exercise 3: A safe delete</h2>
+      <p>
+        A tool replaces each <RT·code>include.css</RT·code> link in an HTML document with an inline style block, then deletes <RT·code>include.css</RT·code> from the directory. Describe the run in which this breaks a document, and the check that prevents it.
+      </p>
+
+    </RT·article>
+  </body>
+</html>
diff --git a/setup b/setup
index f750f1d..8ab56c8 100755
--- a/setup
+++ b/setup
@@ -30,11 +30,6 @@ def main():
 
     print(f"ROLE_HOME {role_home}")
 
-    # Python-domain logic: PATH injection
-    path_parts = env.get("PATH", "").split(os.pathsep)
-    if tool_dir not in path_parts:
-        env["PATH"] = f"{tool_dir}{os.pathsep}{env.get('PATH', '')}"
-
     # Python-domain logic: Directory validation
     if not os.path.isdir(role):
         print(f"setup: failed to locate directory for role '{role}'")
@@ -47,6 +42,8 @@ def main():
         'if [[ -f ~/.bashrc ]]; then source ~/.bashrc; fi',
         'if [[ -f "shared/tool/setup" ]]; then source "shared/tool/setup"; fi',
         'if [[ -f "shared/authored/setup" ]]; then source "shared/authored/setup"; fi',
+        '# the role tool directory is searched before everything the shared setup added',
+        f'PATH="{tool_dir}:$PATH"; export PATH',
         f'cd "{role}"',
         'if [[ -f "tool/setup" ]]; then',
         '    source "tool/setup"',
diff --git a/shared/project-dependency/.gitignore b/shared/project-dependency/.gitignore
new file mode 100644
index 0000000..a033c31
--- /dev/null
+++ b/shared/project-dependency/.gitignore
@@ -0,0 +1,11 @@
+# shared/project-dependency/.gitignore
+# Tracks the skeleton's parts. Add a ! line for anything else to track,
+# such as a dependency's link.
+*
+!.gitignore
+!project
+!*.init
+!*.install
+!*.org
+!*.html
+!Python-3.12.3
diff --git a/shared/project-dependency/Python.init b/shared/project-dependency/Python.init
new file mode 100644
index 0000000..eddbaad
--- /dev/null
+++ b/shared/project-dependency/Python.init
@@ -0,0 +1,16 @@
+# -*- mode: sh; sh-shell: bash; -*-
+# init files are bash script
+
+# Python.init
+# --------------------------------------------------------------------------------
+# Ensure the local Python build is prioritized in the PATH.
+# The user must establish the Python-3.12.3 symlink for this to activate.
+
+if [[ -d "$REPO_HOME/shared/project-dependency/Python-3.12.3/bin" ]]; then
+  PATH="$REPO_HOME/shared/project-dependency/Python-3.12.3/bin:$PATH"
+else
+  # Optional: Issue a quiet warning for the administrator role
+  if [[ "$ROLE" == "administrator" ]]; then
+     echo "Notice: Local Python-3.12.3 bin not found. Using system Python."
+  fi
+fi
diff --git a/shared/project-dependency/Python.org b/shared/project-dependency/Python.org
new file mode 100644
index 0000000..a5ba50c
--- /dev/null
+++ b/shared/project-dependency/Python.org
@@ -0,0 +1,38 @@
+#+TITLE: Python Installation Guide
+#+AUTHOR: Project Administrator
+
+This project requires a dedicated Python environment. The configuration plugin (`shared/project-dependency/Python.init`) was written targeting Python 3.12.3, though the architecture does not rely on any known version-dependent features. 
+
+* 1. Download and Extract
+Download the Python source code and extract it as a sibling to the main project directory. Assuming you are at the top level of your project workspace:
+
+#+begin_src bash
+cd ../
+wget https://www.python.org/ftp/python/3.12.3/Python-3.12.3.tgz
+tar -xzf Python-3.12.3.tgz
+cd Python-3.12.3
+#+end_src
+
+* 2. Build the Environment
+Compile the Python binaries in place. Setting the installation prefix to the current directory isolates the build, and enabling shared libraries ensures compatibility with C extensions.
+
+#+begin_src bash
+./configure --prefix="$(pwd)" --enable-optimizations --enable-shared
+make -j8
+make install
+#+end_src
+
+* 3. Link the Project
+
+Python-3.12.3 is linked to a Harmony derived project by default.  
+
+See administrator/document/how-to_add-project-dependency.html for details about linking a project, if you want to check the setup.
+
+If you are installing a different version, then at least the Python-3.12.3 version project linking is there as a good example.
+
+Project linking is not difficult, make a sym link to `project/<dependency>`, and then add an init file, as described in administrator/document/how-to_add-project-dependency.html. The 'project' in the link is literal.
+
+
+
+
+
diff --git a/shared/tool/setup b/shared/tool/setup
index d5e3d76..a7a66aa 100644
--- a/shared/tool/setup
+++ b/shared/tool/setup
@@ -57,25 +57,28 @@ umask 0077
 
 # --------------------------------------------------------------------------------
 # PATH & Plugin Sourcing
-#   precedence: last defined, first discovered
-  
-  PATH="$REPO_HOME/shared/authored:$PATH"
-  PATH="$REPO_HOME/shared/made:$PATH"
+#   Each addition goes to the front, so the last added is searched first.
+#   Resulting search order, most specific first:
+#     shared/authored, shared/made, shared/tool, project dependencies, the rest.
+#   The top-level setup then puts the role's tool directory in front of these.
+
+  # Project dependencies: source each .init file. Each prepends its own entries.
+  for init_file in "$REPO_HOME/shared/project-dependency/"*.init; do
+    if [[ -f "$init_file" ]]; then
+      source "$init_file"
+    fi
+  done
+
   PATH="$REPO_HOME/shared/tool:$PATH"
+  PATH="$REPO_HOME/shared/made:$PATH"
+  PATH="$REPO_HOME/shared/authored:$PATH"
 
-  # Remove duplicates
+  # Remove duplicates, keeping the first occurrence
   clean_path() {
     PATH=$(echo ":$PATH" | awk -v RS=: -v ORS=: '!seen[$0]++' | sed 's/^://; s/:$//')
   }
   clean_path
 
-  # Plugin Sourcing: Dynamically load all the linked project configurations
-  for init_file in "$REPO_HOME/shared/linked-project/"*.init; do
-    if [[ -f "$init_file" ]]; then
-      source "$init_file"
-    fi
-  done
-
   export PATH
 
 # --------------------------------------------------------------------------------
diff --git a/tester/.gitkeep b/tester/.gitkeep
new file mode 100644
index 0000000..e69de29