diff --git a/.agents/factory/bin/_fsm.py b/.agents/factory/bin/_fsm.py
index 1a10faca..e000bf38 100644
--- a/.agents/factory/bin/_fsm.py
+++ b/.agents/factory/bin/_fsm.py
@@ -8,11 +8,14 @@
 ``.agents/factory/methodology.md``).
 
 Requires PyYAML, which is a declared project dependency (``requirements.txt``)
-and lives in the project virtual environment — NOT the system interpreter. Run
-these scripts with the project env active, e.g. from the repo root::
+and lives in the uv-synced project virtualenv (``.venv``) — NOT the system
+interpreter. Run these scripts via the venv Python from the repo root::
 
-    source .venv/bin/activate        # or: conda activate rcac-docs
-    python3 .agents/factory/bin/<script>.py ...
+    .venv/bin/python .agents/factory/bin/<script>.py ...
+
+Bootstrap the env first if it is missing (see AGENTS.md "Setup")::
+
+    uv venv && uv pip install -r requirements.txt --python .venv/bin/python
 
 Adapted from the HyperShell software factory (`.agents/factory/bin`).
 """
@@ -27,9 +30,10 @@
     import yaml
 except ModuleNotFoundError as exc:  # pragma: no cover - environment guard
     raise SystemExit(
-        "PyYAML is required but was not found. Activate the project environment "
-        "first (e.g. `source .venv/bin/activate` or `conda activate rcac-docs`), "
-        "then run `python3 .agents/factory/bin/<script>.py` from the repo root."
+        "PyYAML is required but was not found. Run this via the uv-synced venv from "
+        "the repo root: `.venv/bin/python .agents/factory/bin/<script>.py`. Bootstrap "
+        "it first if missing: `uv venv && uv pip install -r requirements.txt "
+        "--python .venv/bin/python`."
     ) from exc
 
 
diff --git a/.agents/factory/bin/meta_status.py b/.agents/factory/bin/meta_status.py
new file mode 100644
index 00000000..73b79013
--- /dev/null
+++ b/.agents/factory/bin/meta_status.py
@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Enumerate the findings in a spec's META.md as JSON.
+
+META.md is the per-job harness-retrospective log (see
+``.agents/factory/templates/META.md``). Each finding is a markdown section::
+
+    ## F3 — verify gate passes on build ERRORs
+    `origin=docs-plan severity=high category=tooling status=open target=path/to/file`
+    - **What happened:** ...
+    - **Recommended fix:** ...
+
+This reader is stdlib-only (no PyYAML, no mkdocs), so it cannot break on a missing
+dependency — but invoke it via ``.venv/bin/python`` like every other factory script
+(the project convention; see AGENTS.md "Setup"). `/docs-harness` and `/docs-publish`
+use it to enumerate/count findings instead of hand-parsing markdown (the same "scripts
+own the fragile parsing" principle as ``next_phase.py``). It never mutates the file.
+
+Usage (from the repo root)::
+
+    .venv/bin/python .agents/factory/bin/meta_status.py spec/<slug>/META.md
+    .venv/bin/python .agents/factory/bin/meta_status.py spec/<slug>/META.md --status open
+    .venv/bin/python .agents/factory/bin/meta_status.py spec/<slug>/META.md --status open --severity high
+    .venv/bin/python .agents/factory/bin/meta_status.py spec/<slug>/META.md F1 F3   # only these ids
+
+Exit codes: 0 ok (even with zero findings) · 2 usage / I/O error.
+A missing META.md is NOT an error — it means "no findings" (prints an empty set).
+"""
+from __future__ import annotations
+
+# Standard libs
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# Public interface
+__all__ = ["main", "parse_findings"]
+
+# A finding starts at a "## F<n> — <title>" heading. Accept "—", "-", or ":" as the separator.
+_HEADING_RE = re.compile(r"^##\s+(?P<id>F\d+)\s*[—:-]\s*(?P<title>.*\S)\s*$", re.MULTILINE)
+# key=value tokens on the attributes line. Values are non-whitespace but exclude backticks, so a
+# code-span-wrapped attributes line (`origin=… target=path`) does not glue the closing ` onto target.
+_KV_RE = re.compile(r"(?P<key>\w+)=(?P<val>[^\s`]+)")
+_ATTR_KEYS = ("origin", "severity", "category", "status", "target")
+
+
+def parse_findings(text: str) -> list[dict]:
+    """Parse META.md text into a list of finding dicts (in document order).
+
+    Example/commented-out findings inside HTML comments (``<!-- ... -->``) are
+    ignored, so the template's illustrative F1 never counts as real.
+    """
+    # Strip HTML comments first so the template's example block is not parsed.
+    text = re.sub(r"<!--.*?-->", "", text, flags=re.DOTALL)
+
+    findings: list[dict] = []
+    matches = list(_HEADING_RE.finditer(text))
+    for i, m in enumerate(matches):
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        body = text[start:end]
+
+        attrs: dict[str, str] = {}
+        for line in body.splitlines():
+            if "status=" in line or "origin=" in line:
+                attrs = {kv.group("key"): kv.group("val") for kv in _KV_RE.finditer(line)}
+                break
+
+        finding = {"id": m.group("id"), "title": m.group("title").strip()}
+        for key in _ATTR_KEYS:
+            finding[key] = attrs.get(key, "")
+        findings.append(finding)
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description="Enumerate findings in a spec's META.md as JSON.")
+    ap.add_argument("path", help="path to spec/<slug>/META.md")
+    ap.add_argument("ids", nargs="*", help="only these finding ids (e.g. F1 F3)")
+    ap.add_argument("--status", help="filter by status (e.g. open)")
+    ap.add_argument("--severity", help="filter by severity (e.g. high)")
+    args = ap.parse_args(argv)
+
+    path = Path(args.path)
+    if not path.exists():
+        # A missing META.md means "no findings recorded" — a normal, clean outcome.
+        print(json.dumps({"path": str(path), "exists": False, "count": 0, "findings": []}, indent=2))
+        return 0
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"cannot read {path}: {exc}", file=sys.stderr)
+        return 2
+
+    findings = parse_findings(text)
+    wanted = set(args.ids)
+    selected = [
+        f for f in findings
+        if (not wanted or f["id"] in wanted)
+        and (not args.status or f["status"] == args.status)
+        and (not args.severity or f["severity"] == args.severity)
+    ]
+    open_high = [f for f in findings if f["status"] == "open" and f["severity"] == "high"]
+    report = {
+        "path": str(path),
+        "exists": True,
+        "count": len(selected),
+        "total": len(findings),
+        "open": len([f for f in findings if f["status"] == "open"]),
+        "open_high": [f["id"] for f in open_high],
+        "findings": selected,
+    }
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/.agents/factory/bin/next_phase.py b/.agents/factory/bin/next_phase.py
index 72fd38bc..db01afd8 100755
--- a/.agents/factory/bin/next_phase.py
+++ b/.agents/factory/bin/next_phase.py
@@ -6,7 +6,7 @@
 "what do I do next"; the model executes, the script computes the transition.
 
 Usage (run from the repo root, with the project env active):
-    python3 .agents/factory/bin/next_phase.py spec/<slug>/TECH.md
+    .venv/bin/python .agents/factory/bin/next_phase.py spec/<slug>/TECH.md
 
 Exit codes: 0 ok · 2 parse/validation error (message on stderr).
 """
diff --git a/.agents/factory/bin/set_phase.py b/.agents/factory/bin/set_phase.py
index 8d932138..47335517 100755
--- a/.agents/factory/bin/set_phase.py
+++ b/.agents/factory/bin/set_phase.py
@@ -9,19 +9,19 @@
 
 Usage examples (run from the repo root, with the project env active):
     # mark a phase done and advance the pointer, stamping today's date
-    python3 .agents/factory/bin/set_phase.py spec/<slug>/TECH.md \
+    .venv/bin/python .agents/factory/bin/set_phase.py spec/<slug>/TECH.md \
         --phase P2 --phase-status done --current P3 --touch
 
     # set an in_progress phase, update the hill honesty signal
-    python3 .agents/factory/bin/set_phase.py spec/<slug>/TECH.md \
+    .venv/bin/python .agents/factory/bin/set_phase.py spec/<slug>/TECH.md \
         --phase P3 --phase-status in_progress --hill uphill --touch
 
     # record a blocked state from a failed review
-    python3 .agents/factory/bin/set_phase.py spec/<slug>/TECH.md \
+    .venv/bin/python .agents/factory/bin/set_phase.py spec/<slug>/TECH.md \
         --top-status blocked --blocked-reason "review: R2 gap" --touch
 
     # record a review verdict
-    python3 .agents/factory/bin/set_phase.py spec/<slug>/TECH.md \
+    .venv/bin/python .agents/factory/bin/set_phase.py spec/<slug>/TECH.md \
         --verdict approved --reviewed-commit abc1234 --touch
 
 Exit codes: 0 ok · 2 parse/validation error · 3 unknown --phase id.
diff --git a/.agents/factory/bin/strict_check.py b/.agents/factory/bin/strict_check.py
index 2b2ffb71..34268177 100755
--- a/.agents/factory/bin/strict_check.py
+++ b/.agents/factory/bin/strict_check.py
@@ -9,16 +9,23 @@
 introduced. Pre-existing warnings are known debt tracked in the baseline file.
 
 Usage (run from the repo root, with the project env active):
-    .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    .venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py
     # or from a captured log:
-    python3 .agents/factory/bin/strict_check.py build.log
+    .venv/bin/python .agents/factory/bin/strict_check.py build.log
 
 Options:
     --baseline PATH   baseline file (default: .agents/factory/strict-baseline.txt)
 
+A `mkdocs build --strict` can also fail *hard* — a macro/Jinja `UndefinedError`, a config
+error, a plugin crash — which surfaces as an `ERROR` line and/or a Python traceback, NOT a
+`WARNING`. Those are never acceptable debt, so this gate fails on any `ERROR`/traceback
+regardless of the baseline. (We deliberately do NOT rely on the pipeline exit code / `pipefail`:
+under `--strict` mkdocs aborts non-zero on *any* warning, including the tolerated baseline ones,
+so this script — not the exit code — must be the arbiter.)
+
 Exit codes:
-    0  no new warnings beyond the baseline (PASS)
-    1  new warning(s) attributable to this change (STOP)
+    0  no ERRORs and no new warnings beyond the baseline (PASS)
+    1  a build ERROR/traceback, or new warning(s) attributable to this change (STOP)
     2  usage / I/O error (e.g. missing baseline file)
 """
 from __future__ import annotations
@@ -30,10 +37,12 @@
 from pathlib import Path
 
 # Public interface
-__all__ = ["main", "extract_warnings", "load_baseline"]
+__all__ = ["main", "extract_warnings", "extract_errors", "load_baseline"]
 
 # A mkdocs strict warning line looks like: "WARNING -  <message>".
 _WARNING_RE = re.compile(r"^WARNING\s*-\s*(?P<msg>.*\S)\s*$")
+# A hard failure looks like "ERROR    -  <message>" (macros/Jinja error, config error, …).
+_ERROR_RE = re.compile(r"^ERROR\s*-\s*(?P<msg>.*\S)\s*$")
 
 
 def extract_warnings(text: str) -> set[str]:
@@ -46,6 +55,22 @@ def extract_warnings(text: str) -> set[str]:
     return out
 
 
+def extract_errors(text: str) -> set[str]:
+    """Return hard-failure signals (ERROR lines + a crash traceback) in a build log.
+
+    These indicate the build did not succeed (e.g. an unescaped ``{{ }}`` in published
+    config raising a macros ``UndefinedError``). They are never baseline debt.
+    """
+    out: set[str] = set()
+    for line in text.splitlines():
+        m = _ERROR_RE.match(line)
+        if m:
+            out.add(m.group("msg").strip())
+    if "Traceback (most recent call last):" in text:
+        out.add("Python traceback in build output (the build crashed)")
+    return out
+
+
 def load_baseline(path: Path) -> set[str]:
     """Return the set of baseline warning messages (ignoring '#' and blanks)."""
     out: set[str] = set()
@@ -78,9 +103,22 @@ def main(argv: list[str]) -> int:
         return 2
 
     found = extract_warnings(text)
+    errors = sorted(extract_errors(text))
     new = sorted(found - baseline)
     fixed = sorted(baseline - found)
 
+    if errors:
+        print(f"FAIL: {len(errors)} build ERROR(s) — the build did not succeed cleanly:")
+        for msg in errors:
+            print(f"  ! {msg}")
+        print(
+            "\nERRORs are never baseline debt. Fix the build — a common cause here is an "
+            "unescaped '{{' / '{%' in published content hitting the macros/Jinja pass "
+            "(publish verbatim config via a '--8<--' include instead), a bad config, or a "
+            "plugin crash."
+        )
+        return 1
+
     if new:
         print(f"FAIL: {len(new)} new mkdocs --strict warning(s) introduced by this change:")
         for msg in new:
diff --git a/.agents/factory/getting-started.html b/.agents/factory/getting-started.html
index 8eae7013..2bade51e 100644
--- a/.agents/factory/getting-started.html
+++ b/.agents/factory/getting-started.html
@@ -277,7 +277,10 @@ <h2>Why this, why now <a class="anchor" href="#exec">#</a></h2>
     <em>Shape Up</em>) map cleanly onto agent work. This site packages that method as a small,
     transparent toolkit in <code><a href="../">.agents/</a></code>: five skills and a set of reference
     documents that carry a change from a shaped goal, through a researched plan, through authoring,
-    through an adversarial review, to a pull request — with a durable, committed record at every step.</p>
+    through an adversarial review, to a pull request — with a durable, committed record at every step.
+    The same toolkit also watches <em>itself</em>: it records where its own instructions cause friction
+    and lets a human feed those lessons back in — a <a href="#factory">self-improvement loop</a> that
+    sharpens the factory over time without ever loosening its guardrails.</p>
 
   <h3>What changes for the docs team <a class="anchor" href="#exec">#</a></h3>
   <p>The level of abstraction rises. People spend less time on boilerplate scaffolding, nav wiring, and
@@ -569,7 +572,7 @@ <h3>TECH.md is a finite-state machine <a class="anchor" href="#factory">#</a></h
     <span class="v">hammerable</span>: <span class="n">false</span>          <span class="c"># HPC accuracy — review may not cut this</span>
     <span class="v">hill</span>: downhill            <span class="c"># uphill=figuring out · downhill=writing</span>
     <span class="v">status</span>: done
-    <span class="v">verify</span>: <span class="s">".venv/bin/mkdocs build --strict 2>&amp;1 | python3 .agents/factory/bin/strict_check.py"</span></code></pre>
+    <span class="v">verify</span>: <span class="s">".venv/bin/mkdocs build --strict 2>&amp;1 | .venv/bin/python .agents/factory/bin/strict_check.py"</span></code></pre>
   <p>A pair of small helper scripts (<code><a href="bin/next_phase.py">next_phase.py</a></code> /
     <code><a href="bin/set_phase.py">set_phase.py</a></code>) read and update this block, so the agent
     never hand-edits fragile YAML.</p>
@@ -588,6 +591,38 @@ <h3>Build in the open <a class="anchor" href="#factory">#</a></h3>
     to the repository. The methodology is not a hidden prompt; it is version-controlled, reviewable, and
     improvable like any other part of the site. The full rationale lives in
     <code><a href="methodology.md">methodology.md</a></code>.</p>
+
+  <h3>The factory improves itself <a class="anchor" href="#factory">#</a></h3>
+  <p>The five lifecycle skills don't just run the process — they <em>watch it for friction</em>. Each
+    skill ends with a silent-by-default <strong>meta-note</strong> step: when a concrete problem in the
+    <em>skillset itself</em> — a misleading instruction, a wrong command, a gap in guidance — costs
+    something during a job, the skill records a terse finding in that job's
+    <code>spec/&lt;slug&gt;/META.md</code>, gated by a single test: <em>"was this the instructions'
+    fault, not mine or the task's?"</em> A merely hard task is not a finding. These <code>F#</code>
+    findings run <em>orthogonal</em> to the <code>GOAL → REVIEW</code> content spine, and are
+    deliberately <strong>hidden from the blind reviewer</strong> (they can leak author intent).</p>
+
+  <p>The loop is <strong>asymmetric by design — cheap to observe, deliberate to act</strong> — so it can
+    never become a token-sink or quietly loosen a guardrail:</p>
+
+  <div class="flow" aria-label="The self-improvement loop">
+    <div class="step"><div class="n">observe</div><div class="t">meta-note</div><div class="d">skills log friction to META.md (F#)</div></div>
+    <div class="arrow">→</div>
+    <div class="step"><div class="n">surface</div><div class="t">/docs-publish</div><div class="d">open findings → a PR "🔧 Harness feedback" block</div></div>
+    <div class="arrow">→</div>
+    <div class="step"><div class="n">act</div><div class="t">/docs-harness</div><div class="d">human-gated fix to .agents/</div></div>
+  </div>
+
+  <p>A sixth skill, <code>/docs-harness</code>, stands <em>outside</em> the lifecycle and is the only one
+    that edits the factory itself. Pointed at a finished job's <code>META.md</code>, it previews the
+    recommended fix for each finding and — <strong>only with human approval</strong> — applies them to
+    <code>.agents/</code> as atomic <code>[harness]</code> commits, recording every decision in a
+    cross-job ledger, <code><a href="harness-log.md">harness-log.md</a></code>. It is bound by four rules
+    it cannot break: the observer is never the fixer; it <strong>never auto-weakens a
+    <code>hammerable:false</code> gate</strong>; fixes must generalize (no overfitting to one job); and
+    it writes no findings of its own (no meta-on-meta). Because edits to <code>.agents/**</code> are
+    excluded from the production deploy, the blast radius is the <em>next</em> job's authoring — never
+    the live site.</p>
 </section>
 
 <!-- =================== 5. SKILLS =================== -->
@@ -649,6 +684,18 @@ <h2>Hands-on: the five skills <a class="anchor" href="#skills">#</a></h2>
       <b>skill</b> <a href="../skills/docs-publish/SKILL.md">docs-publish/SKILL.md</a></div>
   </div>
 
+  <div class="skill" style="border-left-color:var(--muted)">
+    <div class="cmd" style="color:var(--text-2)">/docs-harness <span style="color:var(--muted);font-weight:400">— the self-improvement skill (not part of the lifecycle)</span></div>
+    <p>Stands apart from the five above: it changes the <strong>factory</strong>, not any page. Pointed at
+      a finished job's <code>META.md</code>, it previews and — <strong>only with your approval</strong> —
+      applies each recorded process fix to <code>.agents/</code> as an atomic <code>[harness]</code>
+      commit, logging every decision. It never fires on its own
+      (<code>disable-model-invocation</code>), never auto-weakens a safety gate, and writes no findings
+      itself. See <a href="#factory">The factory improves itself</a> for the loop it closes.</p>
+    <div class="io"><b>reads</b> spec/&lt;slug&gt;/META.md + harness-log.md · <b>writes</b> .agents/ fixes, harness-log.md ·
+      <b>skill</b> <a href="../skills/docs-harness/SKILL.md">docs-harness/SKILL.md</a></div>
+  </div>
+
   <h3>A day in the life <a class="anchor" href="#skills">#</a></h3>
   <div class="term-title">a new user-guide page, start to finish</div>
   <pre><code><span class="k">/docs-feature</span> add a Python examples page to the Gautschi user guide
@@ -735,6 +782,29 @@ <h3>Workforce <a class="anchor" href="#leadership">#</a></h3>
   <p>These are exactly the skills experienced writers and RSEs already have. The change is that they
     spend more of their day exercising them and less on boilerplate. It is a force multiplier for a
     small docs team, not a substitute for one.</p>
+
+  <h3>A factory that improves itself <a class="anchor" href="#leadership">#</a></h3>
+  <p>The factory is instrumented to get <em>better with use</em> — without ever putting its own
+    guardrails up for negotiation. As each job runs, the skills quietly record process friction (a
+    misleading instruction, a wrong command, a gap in guidance) as findings in that job's
+    <code>META.md</code>; a human then decides, through the <code>/docs-harness</code> skill, which of
+    those fixes to fold back into the toolchain. Three properties make this safe to leave running:</p>
+  <ul>
+    <li><strong>Human-gated and non-self-weakening.</strong> No fix is ever auto-applied, and the skill
+      is constitutionally forbidden from loosening a <code>hammerable:false</code> gate (HPC accuracy,
+      accessibility, build integrity) without an explicit human override. The mechanism that sharpens
+      the process cannot be turned against its own quality bar.</li>
+    <li><strong>Isolated blast radius.</strong> These changes touch only the <code>.agents/</code>
+      toolchain, which is excluded from the production deploy — so a factory tweak can never itself reach
+      the live site. It changes how the <em>next</em> page is authored, not any published page.</li>
+    <li><strong>Fully audited.</strong> Every applied or rejected fix is logged, with its rationale, in a
+      cross-job ledger (<code>harness-log.md</code>) — the same "answer it from the repository alone"
+      standard the content trail meets, and an anti-thrash memory so rejected ideas don't keep
+      returning.</li>
+  </ul>
+  <p>The takeaway for leadership is <strong>compounding return</strong>: the team's accumulated lessons
+    about <em>how</em> to author well become durable, reviewable changes to the shared toolchain rather
+    than living only in one person's head — and every one of those changes passes through a human hand.</p>
 </section>
 
 <!-- =================== 6. REFERENCE =================== -->
@@ -757,7 +827,7 @@ <h3>The constitution <a class="anchor" href="#reference">#</a></h3>
   </table>
   </div>
 
-  <h3>The five skills <a class="anchor" href="#reference">#</a></h3>
+  <h3>The skills — five lifecycle, one meta <a class="anchor" href="#reference">#</a></h3>
   <div class="tablewrap">
   <table>
     <thead><tr><th>Skill</th><th>Role</th></tr></thead>
@@ -767,6 +837,9 @@ <h3>The five skills <a class="anchor" href="#reference">#</a></h3>
       <tr><td><code><a href="../skills/docs-draft/SKILL.md">docs-draft</a></code></td><td>Author the roadmap, one verified phase at a time.</td></tr>
       <tr><td><code><a href="../skills/docs-review/SKILL.md">docs-review</a></code></td><td>Independent, blind, evidence-based QA.</td></tr>
       <tr><td><code><a href="../skills/docs-publish/SKILL.md">docs-publish</a></code></td><td>Open the pull request to <code>main</code> (or merge locally).</td></tr>
+      <tr><td><code><a href="../skills/docs-harness/SKILL.md">docs-harness</a></code> <span style="color:var(--muted)">(meta)</span></td>
+          <td>Apply a job's <code>META.md</code> self-improvement findings to the factory, human-gated.
+              <em>Not part of the content lifecycle</em> — it changes the toolchain, not any page.</td></tr>
     </tbody>
   </table>
   </div>
@@ -777,8 +850,8 @@ <h3>Reference documents <a class="anchor" href="#reference">#</a></h3>
     <thead><tr><th>Document</th><th>What it is / how it's used</th></tr></thead>
     <tbody>
       <tr><td><code><a href="methodology.md">methodology.md</a></code></td>
-          <td>The full lifecycle rationale — the "why" behind the skills, and the Shape Up mapping.
-              Read this to understand the flow.</td></tr>
+          <td>The full lifecycle rationale — the "why" behind the skills, the Shape Up mapping, and the
+              self-improvement loop. Read this to understand the flow.</td></tr>
       <tr><td><code><a href="invariants.md">invariants.md</a></code></td>
           <td>The curated checklist of load-bearing rules, drawn from <code>AGENTS.md</code>. Used as
               the planning gate and the review footgun list.</td></tr>
@@ -804,11 +877,14 @@ <h3>Templates &amp; state scripts <a class="anchor" href="#reference">#</a></h3>
       <tr><td><code><a href="templates/PLAN.md">templates/PLAN.md</a></code></td><td>Skeleton for the design.</td></tr>
       <tr><td><code><a href="templates/TECH.md">templates/TECH.md</a></code></td><td>Skeleton for the phased FSM roadmap (with the field reference).</td></tr>
       <tr><td><code><a href="templates/REVIEW.md">templates/REVIEW.md</a></code></td><td>Skeleton for the review report.</td></tr>
+      <tr><td><code><a href="templates/META.md">templates/META.md</a></code></td><td>Skeleton for the per-job harness-retrospective log — the <code>F#</code> finding format and the bar for recording one.</td></tr>
       <tr><td><code><a href="bin/next_phase.py">bin/next_phase.py</a></code></td><td>Reads &amp; validates a TECH.md; prints the next actionable phase as JSON.</td></tr>
       <tr><td><code><a href="bin/set_phase.py">bin/set_phase.py</a></code></td><td>Advances FSM state by regenerating the front-matter (no fragile hand-edits).</td></tr>
       <tr><td><code><a href="bin/strict_check.py">bin/strict_check.py</a></code></td><td>Gates a <code>mkdocs --strict</code> log against the warning baseline (fails only on regressions).</td></tr>
+      <tr><td><code><a href="bin/meta_status.py">bin/meta_status.py</a></code></td><td>Enumerates a <code>META.md</code>'s findings as JSON (by status / severity / id), so <code>/docs-publish</code> and <code>/docs-harness</code> never hand-parse the log.</td></tr>
       <tr><td><code><a href="bin/_fsm.py">bin/_fsm.py</a></code></td><td>Shared parse / validate / serialize helpers for the scripts above.</td></tr>
       <tr><td><code><a href="strict-baseline.txt">strict-baseline.txt</a></code></td><td>The known pre-existing <code>--strict</code> warnings the build gate ignores.</td></tr>
+      <tr><td><code><a href="harness-log.md">harness-log.md</a></code></td><td>The cross-job ledger of applied / rejected self-improvement fixes — anti-thrash memory, read before applying a finding.</td></tr>
     </tbody>
   </table>
   </div>
diff --git a/.agents/factory/harness-log.md b/.agents/factory/harness-log.md
new file mode 100644
index 00000000..39146f2d
--- /dev/null
+++ b/.agents/factory/harness-log.md
@@ -0,0 +1,13 @@
+# Harness change log — the factory improving itself
+
+Cross-job institutional memory for the self-improvement loop. `/docs-harness` appends a row here for
+every finding it **applies** or **rejects**, so fixes don't thrash and rejected findings don't keep
+coming back. Humans may annotate freely. **Newest first.**
+
+- Per-job *raw observations* live in each `spec/{slug}/META.md` (written by the skills' meta-note step).
+- This file is the *decisions* ledger across jobs — read it before applying a finding, to catch a
+  proposed fix that would **revert** a recent deliberate change or repeat a **rejected** one.
+
+| date | finding | job (META) | action | target | note |
+|------|---------|-----------|--------|--------|------|
+| 2026-07-15 | initial hardening pass (build-gate ERRORs, uv/.venv standardization, weaker/non-Claude robustness, verbatim-include pattern) | agentic-ai-docs (test-drive) | applied (manual, pre-loop) | `.agents/**`, `AGENTS.md` | Applied by hand during the factory test-drive before `/docs-harness` existed; recorded for provenance. Commits `58f49733`..`804f0bd3`. |
diff --git a/.agents/factory/invariants.md b/.agents/factory/invariants.md
index 9c3bd982..a0ab6abb 100644
--- a/.agents/factory/invariants.md
+++ b/.agents/factory/invariants.md
@@ -93,11 +93,19 @@ the build breaks.
 
 ## §8 — Build integrity (hammerable: false)
 
-`mkdocs build --strict` must introduce **no new warnings** versus `strict-baseline.txt`.
-CI builds with `--verbose`, not `--strict`, so broken links and nav orphans would
-otherwise ship silently. Gate with:
-`.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py`.
-This is a correctness gate, not a nicety — do not scope-hammer it.
+`mkdocs build --strict` must introduce **no new warnings** versus `strict-baseline.txt`,
+**and must not fail** (no build `ERROR`s or tracebacks). CI builds with `--verbose`, not
+`--strict`, so broken links and nav orphans would otherwise ship silently. Gate with:
+`.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py`
+— the checker fails on new warnings **and** on any `ERROR`/traceback (e.g. an unescaped
+`{{`/`{%` in published content hitting the macros pass). Do **not** add `pipefail`: under
+`--strict` mkdocs aborts non-zero on *any* warning, including the tolerated baseline ones, so
+`strict_check.py` — not the exit code — is the arbiter.
+
+**`--strict` does not catch everything.** A mistyped `pymdownx.snippets` include
+(`--8<-- "…"`) fails **silently** (`check_paths: false` → an empty block, no warning). When a
+page embeds a verbatim file, also **eyeball the render** or grep the built `site/` for a known
+token. This is a correctness gate, not a nicety — do not scope-hammer it.
 
 ## §9 — Content-level accessibility, WCAG 2.1 (hammerable: false)
 
diff --git a/.agents/factory/methodology.md b/.agents/factory/methodology.md
index f0c5c128..71f18c9a 100644
--- a/.agents/factory/methodology.md
+++ b/.agents/factory/methodology.md
@@ -135,13 +135,17 @@ links resolve, that front-matter matches the archetype, and that images have alt
 ```
 .agents/
   skills/docs-{feature,plan,draft,review,publish}/SKILL.md   # the five lifecycle skills
+  skills/docs-harness/SKILL.md      # meta/maintenance: applies META.md findings to the factory
   factory/
     methodology.md   invariants.md   ears.md   style-guide.md   review-rubric.md
     getting-started.html            # human onboarding
     strict-baseline.txt             # known pre-existing --strict warnings
-    templates/                      # GOAL.md PLAN.md TECH.md REVIEW.md skeletons
-    bin/                            # next_phase.py, set_phase.py, strict_check.py, _fsm.py
+    harness-log.md                  # cross-job ledger of applied/rejected self-improvement fixes
+    templates/                      # GOAL.md PLAN.md TECH.md REVIEW.md META.md skeletons
+    bin/                            # next_phase.py, set_phase.py, strict_check.py, meta_status.py, _fsm.py
 spec/{slug}/                        # per-job artifacts (committed, retained on merge)
+  GOAL/PLAN/TECH/REVIEW.md          # the content spine (R-IDs)
+  META.md                           # orthogonal: harness-retrospective findings (F-IDs) — the toolmaker's notes
 AGENTS.md                           # the constitution (CLAUDE.md is a symlink to it)
 ```
 
@@ -154,3 +158,30 @@ commits → `REVIEW.md` requirement→evidence matrix → PR body. Because a mer
 per-commit history, the committed `spec/{slug}/` folder *is* the retained trace.
 Provenance lives in that chain and in the commit/PR — **never** embed feature-scoped
 `R#`/`P#` IDs in page content (they restart per job and collide across branches).
+
+## The self-improvement loop (META.md + `/docs-harness`)
+
+The factory watches its own friction and — human-gated — fixes itself. The loop is deliberately
+**asymmetric: cheap to observe, deliberate to act**, so it can't become a token-sink or quietly
+loosen its own guardrails.
+
+- **Observe (every lifecycle skill, silence by default).** Each `docs-*` skill ends with a
+  **meta-note step** that appends a finding to `spec/{slug}/META.md` **only** when a concrete problem
+  in the *skillset itself* cost something — gated by one test: *"the instructions' fault, not mine or
+  the task's?"* A merely hard task, a self-inflicted error, or a one-off content issue is **not** a
+  finding. `META.md` is orthogonal to the `GOAL→…→REVIEW` content spine: it uses `F#` ids, is about
+  the *toolchain*, and is **kept out of the blind reviewer's context** (it can leak author intent).
+- **Surface.** `/docs-publish` reads open findings (`meta_status.py`) and adds a terse, labelled
+  "🔧 Harness feedback" block to the PR body, so a human sees process friction alongside the content.
+- **Act (`/docs-harness`, human-gated).** Points at a job's `META.md`, previews the recommended fix
+  for each finding, and — defaulting to all but scopable to specific ids (`F1 F3`) — applies them to
+  `.agents/` as atomic `[harness]` commits, recording each in the cross-job `harness-log.md`.
+
+The safety of the loop rests on four rules, enforced in `/docs-harness`: **observer ≠ fixer**
+(recording is cheap and low-stakes; the fix is authored later with fresh eyes + human review);
+**never auto-weaken a `hammerable:false` gate** without an explicit human override; **fixes must
+generalize** (reject overfit-to-one-job); and **no meta-on-meta** (`/docs-harness` writes no
+findings). `harness-log.md` is the anti-thrash memory: a proposed fix that reverts a recent change or
+repeats a rejected one is flagged, not silently re-applied. `.agents/**` edits don't trigger the prod
+deploy (CI path filter), so the blast radius is the *next* job's authoring, not the live site — which
+is exactly why the human gate matters.
diff --git a/.agents/factory/review-rubric.md b/.agents/factory/review-rubric.md
index c60e6038..6a8b0e71 100644
--- a/.agents/factory/review-rubric.md
+++ b/.agents/factory/review-rubric.md
@@ -40,7 +40,7 @@ clean diff is a valid, valuable result.**
 
 1. **Reproduce it.** Run the command or render the page that would reveal it:
    - build/nav/link/front-matter/`--strict` →
-     `.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py`
+     `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py`
      and inspect the log for the specific file;
    - rendering/a11y-structure → `mkdocs serve` and view the page (or inspect the built
      HTML under `site/`);
diff --git a/.agents/factory/strict-baseline.txt b/.agents/factory/strict-baseline.txt
index 34d5155e..353e98e5 100644
--- a/.agents/factory/strict-baseline.txt
+++ b/.agents/factory/strict-baseline.txt
@@ -3,29 +3,27 @@
 # WHAT THIS IS
 #   `mkdocs build --strict` promotes build WARNINGs (broken internal links,
 #   missing targets, nav orphans) to hard errors. CI builds with `--verbose`,
-#   NOT `--strict`, so these warnings currently ship to production silently.
-#   The factory's build-integrity gate runs `--strict` and blocks only on
-#   warnings that are NOT already in this baseline — i.e. regressions your
-#   change introduced. Pre-existing warnings (below) are known debt.
+#   NOT `--strict`, so such warnings would otherwise ship to production silently.
+#   The factory's build-integrity gate runs `--strict` and blocks on any warning
+#   that is NOT already listed below — i.e. a regression your change introduced.
 #
 # HOW IT IS USED
-#   .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+#   .venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py
 #   Exit 0 = you introduced no new warnings (PASS).
 #   Exit 1 = new warning(s) attributable to your change (STOP; fix or justify).
 #   Lines starting with '#' and blank lines are ignored by the checker.
 #
-# MAINTENANCE
-#   These are real, pre-existing broken links (a great first `fix/` job for the
-#   factory). Entries #1-2 live in tool-generated catalog files
-#   (software/ngc_catalog.md, software/rocm_catalog.md) and must be fixed at the
-#   generator (tools/), not by hand. When a baseline warning is genuinely fixed,
-#   delete its line here in the same change so the debt count only shrinks.
-#   Last captured: 2026-07-14 (mkdocs 1.6.1, mkdocs-material 9.6.16).
+# CURRENT STATE: EMPTY (zero tolerated warnings — the gate is at its strictest).
+#   The seven pre-existing broken-link warnings captured on 2026-07-14 were all
+#   fixed upstream on `main` (commit 4f3e3574, "Fix warnings for --strict
+#   building") and deleted here on 2026-07-15 in the same spirit the MAINTENANCE
+#   note prescribes — a clean `--strict` build now emits no warnings at all.
+#   With an empty baseline, ANY warning fails the gate.
 #
-Doc file 'software/ngc_catalog.md' contains a link '../../assets/images/nvidia_logo.png', but the target '../assets/images/nvidia_logo.png' is not found among documentation files. Did you mean '../assets/images/nvidia_logo.png'?
-Doc file 'software/rocm_catalog.md' contains a link '../../assets/images/rocm_logo.png', but the target '../assets/images/rocm_logo.png' is not found among documentation files. Did you mean '../assets/images/rocm_logo.png'?
-Doc file 'userguides/gilbreth/run_jobs/learning/customml.md' contains a link 'index.md', but the target 'userguides/gilbreth/run_jobs/learning/index.md' is not found among documentation files.
-Doc file 'userguides/gilbreth/run_jobs/learning/ml_batch.md' contains a link 'index.md', but the target 'userguides/gilbreth/run_jobs/learning/index.md' is not found among documentation files.
-Doc file 'userguides/negishi/run_jobs/biocontainers.md' contains a link '../../../../assets/images/userguides/examples/biocontainers.png', but the target '../assets/images/userguides/examples/biocontainers.png' is not found among documentation files. Did you mean '../../../assets/images/userguides/examples/biocontainers.png'?
-Doc file 'userguides/negishi/run_jobs/windows/launcher.md' contains a link '../../../../../assets/images/userguides/examples/windows.png', but the target '../assets/images/userguides/examples/windows.png' is not found among documentation files. Did you mean '../../../../assets/images/userguides/examples/windows.png'?
-Doc file 'userguides/scholar/run_jobs/r_example.md' contains a link '../../userguides/gautschi/run_jobs/examples/example_r_profile_setup.md', but the target 'userguides/userguides/gautschi/run_jobs/examples/example_r_profile_setup.md' is not found among documentation files.
+# MAINTENANCE
+#   Keep the debt count shrinking. If a build legitimately surfaces a
+#   pre-existing warning you cannot fix within your change, add its exact message
+#   on its own line below with a comment justifying it; when a listed warning is
+#   genuinely fixed, delete its line in the same change. Tool-generated catalog
+#   files (software/*_catalog.md) must be fixed at the generator (tools/), never
+#   by hand.
diff --git a/.agents/factory/style-guide.md b/.agents/factory/style-guide.md
index 3399f46e..5428f3af 100644
--- a/.agents/factory/style-guide.md
+++ b/.agents/factory/style-guide.md
@@ -107,6 +107,25 @@ content. Available macros live in `main.py` (`ssh_keys_snippet`, `ssh_x11_snippe
 `scratch_space`, `compile_gpu_snippet`, `htar_snippet`, `hsi_snippet`, … — read `main.py`
 for the current list and signatures).
 
+**Publishing a file verbatim (config, rules, `agents.d/*`) — the Jinja-safe pattern.** To show a
+real file byte-exact (a `settings.json`, a `config.toml`, a context `*.md`), keep it as an actual
+file under `docs/snippets/…` and `--8<--` it **inside a fenced code block** — do *not* paste the body
+into the page:
+
+````markdown
+```json title="~/.claude/settings.json"
+--8<-- "docs/snippets/agentic-ai/claude/settings.json"
+```
+````
+
+The macros/Jinja pass runs on the page's own source **before** Markdown parsing; `--8<--` splices the
+file in **after** — so literal `{{ … }}` / `{% … %}` in the included file is **never** evaluated and
+cannot break the build (pasting the same body directly would need `{% raw %}…{% endraw %}` and
+duplicates the content). One on-disk file = one source of truth, syntax-highlighted, copyable.
+**Footgun:** `pymdownx.snippets` runs with `check_paths: false`, so a **mistyped include path fails
+silently** — an empty code block, and `--strict` does *not* warn. Always eyeball the render (or grep
+the built `site/` for a known token) after adding one.
+
 **Code blocks** — always tag the language; show interactive prompts with `$`. Extras:
 ` ```python title="test.py" `, line highlight ` ```py hl_lines="2 3" `, `linenums="1"`,
 inline `` `#!python range()` ``. Job scripts conventionally open with `# FILENAME: myjob.sub`.
diff --git a/.agents/factory/templates/META.md b/.agents/factory/templates/META.md
new file mode 100644
index 00000000..d22647ff
--- /dev/null
+++ b/.agents/factory/templates/META.md
@@ -0,0 +1,39 @@
+# META — harness retrospective for {slug}
+
+> **Notes to the toolmaker, not to the reader.** Process/skillset feedback captured *while building
+> this job* — orthogonal to `GOAL/PLAN/TECH/REVIEW` (which are about the doc). Each `docs-*` skill's
+> **meta-note step** appends a finding here **only** when a concrete instruction/steering/tooling
+> problem in the *skillset itself* cost something during that step; otherwise it stays silent.
+> `/docs-harness` reads this file to propose fixes (human-gated). **This file is kept out of the
+> blind reviewer's context** (it can reveal author intent). None below == the skills worked.
+
+<!--
+Append one finding per real problem, as a "## F<n> — <title>" section (n = next integer).
+Line 2 of each section is the machine-readable attributes line (parsed by meta_status.py) — keep the
+`key=value` tokens space-separated, values with NO spaces (paths are fine):
+
+    origin   = which skill/step raised it (docs-feature | docs-plan | docs-draft:P3 | docs-review)
+    severity = high | medium | low        (high = a safety/gate/correctness gap)
+    category = instruction | steering | tooling | template | missing-guidance
+    status   = open | applied | rejected | deferred   (skills write `open`; /docs-harness updates it)
+    target   = best-guess file the fix touches (a path, no line number)
+
+THE BAR (write only if YES): "Was this the *instructions'* fault — not mine, not the task's?"
+Qualifies: hand-fixed a command the skill gave (wrong flag/path/unquoted YAML); a genuinely
+ambiguous instruction; a [NEEDS CLARIFICATION] better guidance could have pre-empted; an
+allowed-tools/step mismatch; a gate that passed/failed misleadingly.
+Stay silent: the task was just hard; you erred against a clear instruction; a one-off *content*
+issue (that belongs in REVIEW/GOAL); a vague preference with no measured cost.
+Cap ≤3 findings/invocation, terse. If an equivalent finding exists, append "· seen again" to its
+attributes line instead of duplicating. A fix that would weaken a `hammerable:false` gate is
+`severity=high` and must say so explicitly.
+-->
+
+<!-- EXAMPLE (delete when you add a real one):
+## F1 — verify gate passes on build ERRORs
+`origin=docs-plan severity=high category=tooling status=open target=.agents/factory/bin/strict_check.py`
+- **What happened:** the verify recipe only caught new WARNINGs; a macros/Jinja error would PASS.
+- **Skill cause (not mine):** the template's `verify:` had the hole.
+- **Recommended fix:** fail the gate on ERROR/traceback lines too.
+- **Confidence:** high · **Effort:** small
+-->
diff --git a/.agents/factory/templates/PLAN.md b/.agents/factory/templates/PLAN.md
index b523ff1a..41eb3b59 100644
--- a/.agents/factory/templates/PLAN.md
+++ b/.agents/factory/templates/PLAN.md
@@ -68,10 +68,13 @@ name / Slurm flag / module?) or "how does the existing site handle X".
 
 How we will *prove* the pages are correct — this seeds each phase's `verify:` in `TECH.md`:
 
-- **Build integrity:** `.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py`
-  (no new warnings vs baseline).
+- **Build integrity:** `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py`
+  (no new warnings **and no build ERRORs/tracebacks** vs baseline).
 - **Nav:** the new page(s) appear in `mkdocs.yml` and resolve (no "not in nav" warning).
-- **Render:** `mkdocs serve` and view the page(s) — layout, tabs, admonitions, macros expand.
+- **Silent-failure guard:** a mistyped `--8<--` include renders an **empty** block with no
+  `--strict` warning (`check_paths: false`). For any page that embeds a verbatim file, add a
+  `grep -rq <sentinel-token> site/<path>/` to the phase `verify:` and eyeball the render.
+- **Render:** `.venv/bin/mkdocs serve` and view the page(s) — layout, tabs, admonitions, macros expand.
 - **Front-matter:** matches the archetype (blog `<!-- more -->` + allowed category + known author, etc.).
 - **Accessibility:** images have alt text; headings descend logically.
 - **HPC accuracy:** which authoritative source or gold-standard page each factual claim was checked against.
diff --git a/.agents/factory/templates/REVIEW.md b/.agents/factory/templates/REVIEW.md
index e5132fba..65f02136 100644
--- a/.agents/factory/templates/REVIEW.md
+++ b/.agents/factory/templates/REVIEW.md
@@ -13,8 +13,8 @@
 
 Commands actually executed / pages actually rendered, and their outcomes (the spine of the review):
 
-- `.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py` → <result>
-- `mkdocs serve` + viewed <page(s)> → <what rendered: tabs, admonitions, macros, layout>
+- `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py` → <result>
+- `.venv/bin/mkdocs serve` + viewed <page(s)> → <what rendered: tabs, admonitions, macros, layout>
 - nav check: <new page(s) present in `mkdocs.yml` / resolve without "not in nav" warning>
 - front-matter / a11y spot-check → <observed>
 
diff --git a/.agents/factory/templates/TECH.md b/.agents/factory/templates/TECH.md
index e7d0e374..ac5175f2 100644
--- a/.agents/factory/templates/TECH.md
+++ b/.agents/factory/templates/TECH.md
@@ -17,7 +17,7 @@ phases:
     parallel: false
     hammerable: false
     hill: uphill
-    verify: ".venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py"
+    verify: ".venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py"
   - id: P2
     name: "Draft the Running Jobs article"
     status: pending
@@ -26,7 +26,7 @@ phases:
     parallel: true
     hammerable: false
     hill: uphill
-    verify: ".venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py && grep -q 'run_jobs' mkdocs.yml"
+    verify: ".venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py && grep -q 'run_jobs' mkdocs.yml"
 review:
   last_reviewed_commit: ""
   verdict: none
@@ -37,9 +37,9 @@ review:
 
 The **context engine and finite-state machine** for authoring this job. The YAML frontmatter
 above is the resume ground-truth (read it with
-`python3 .agents/factory/bin/next_phase.py spec/{slug}/TECH.md`); the per-phase checklists
+`.venv/bin/python .agents/factory/bin/next_phase.py spec/{slug}/TECH.md`); the per-phase checklists
 below are the work. `docs-draft` executes the next actionable phase, runs its `verify:`
-command, updates state via `python3 .agents/factory/bin/set_phase.py …`, and makes one atomic
+command, updates state via `.venv/bin/python .agents/factory/bin/set_phase.py …`, and makes one atomic
 content+state commit. Run from the repo root with the project env active.
 
 - **Vision / requirements (locked):** [`GOAL.md`](GOAL.md) — R-IDs are the contract.
@@ -64,7 +64,12 @@ content+state commit. Run from the repo root with the project env active.
 - `hill`: `uphill` (still figuring it out) → `crest` (unknowns resolved) → `downhill` (just
   writing). A phase stuck `uphill` across drafts is a raised hand → escalate to the human.
 - `verify`: the exact command that proves the phase — prefer the `--strict` gate plus a nav/
-  front-matter check; add a `mkdocs serve` render check in the phase steps when layout matters.
+  front-matter check; add a `.venv/bin/mkdocs serve` render check in the phase steps when layout matters.
+  The gate (`strict_check.py`) fails on new warnings **and** build ERRORs/tracebacks. `--strict`
+  does **not** catch a mistyped `--8<--` include (silent empty block), so for pages that embed a
+  verbatim file, chain a `grep -rq <sentinel> site/<path>/`. **Quote the whole `verify:` string**
+  (it contains pipes/colons); keep single-quotes *inside* it. Example gate + include check:
+  `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py && grep -q '<page>.md' mkdocs.yml && grep -rq '<sentinel>' site/<path>/`
 
 ## Conventions (apply to every phase)
 
@@ -89,8 +94,8 @@ content+state commit. Run from the repo root with the project env active.
 
 - [ ] Create `docs/userguides/<cluster>/index.md` and `overview.md` from the userguide archetype.
 - [ ] Add the section + pages to `mkdocs.yml` `nav:`.
-- [ ] `python tools/generate_breadcrumbs.py`.
-- **Verify:** `.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py`
+- [ ] `.venv/bin/python tools/generate_breadcrumbs.py`.
+- **Verify:** `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py`
 - **Touches:** `docs/userguides/<cluster>/index.md`, `overview.md`, `mkdocs.yml`.
 
 ## Phase P2 — Draft the Running Jobs article
@@ -99,8 +104,8 @@ content+state commit. Run from the repo root with the project env active.
 
 - [ ] Write `run_jobs/index.md` (prose + `bash` batch example + admonitions + macros/snippets).
 - [ ] Add it to `nav:`; add cross-links and a back-link to the hub.
-- [ ] `mkdocs serve` and eyeball the rendered page (tabs, admonitions, macro expansion).
-- **Verify:** `.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py && grep -q 'run_jobs' mkdocs.yml`
+- [ ] `.venv/bin/mkdocs serve` and eyeball the rendered page (tabs, admonitions, macro expansion).
+- **Verify:** `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py && grep -q 'run_jobs' mkdocs.yml`
 - **Touches:** `docs/userguides/<cluster>/run_jobs/index.md`, `mkdocs.yml`.
 
 ---
@@ -109,8 +114,8 @@ content+state commit. Run from the repo root with the project env active.
 
 1. `next_phase.py` prints the next actionable phase (statuses are authoritative; the
    `current_phase` pointer is reconciled against them).
-2. Pre-flight: clean tree, on `branch`, `base` (`main`) reachable, project env active
-   (`python3 -c "import yaml, mkdocs"`).
+2. Pre-flight: clean tree, on `branch`, `base` (`main`) reachable, the uv-synced `.venv` present
+   (`.venv/bin/python -c "import yaml, mkdocs"`; bootstrap per AGENTS.md "Setup" if not).
 3. Execute every `[ ]` in the phase (consult `PLAN.md` / `research/` / `style-guide.md` for detail).
 4. Run the phase's `verify:` command — never advance on a checkbox alone.
 5. Amend this file freely if reality diverges (regenerate frontmatter with `set_phase.py`; note the
diff --git a/.agents/settings.json b/.agents/settings.json
index 182186b6..f8c71a4b 100644
--- a/.agents/settings.json
+++ b/.agents/settings.json
@@ -2,12 +2,16 @@
   "$comment": "Shared, version-controlled permission allowlist for the RCAC-Docs documentation factory. These are safe, read-only-or-idempotent commands the docs-* skills run repeatedly; pre-approving them reduces interactive prompts. Personal overrides go in .agents/settings.local.json (gitignored). Keep this least-privilege — do not add broad wildcards.",
   "permissions": {
     "allow": [
-      "Bash(mkdocs build:*)",
+      "Bash(uv venv:*)",
+      "Bash(uv pip:*)",
       "Bash(.venv/bin/mkdocs build:*)",
-      "Bash(python3 .agents/factory/bin/next_phase.py:*)",
-      "Bash(python3 .agents/factory/bin/strict_check.py:*)",
-      "Bash(python3 -c \"import yaml, mkdocs\":*)",
-      "Bash(python tools/generate_breadcrumbs.py:*)",
+      "Bash(.venv/bin/mkdocs serve:*)",
+      "Bash(.venv/bin/python .agents/factory/bin/next_phase.py:*)",
+      "Bash(.venv/bin/python .agents/factory/bin/set_phase.py:*)",
+      "Bash(.venv/bin/python .agents/factory/bin/strict_check.py:*)",
+      "Bash(.venv/bin/python .agents/factory/bin/meta_status.py:*)",
+      "Bash(.venv/bin/python tools/generate_breadcrumbs.py:*)",
+      "Bash(.venv/bin/python -c \"import yaml, mkdocs\":*)",
       "Bash(git status:*)",
       "Bash(git diff:*)",
       "Bash(git log:*)",
diff --git a/.agents/skills/docs-draft/SKILL.md b/.agents/skills/docs-draft/SKILL.md
index c97dcb26..fb42f0f6 100644
--- a/.agents/skills/docs-draft/SKILL.md
+++ b/.agents/skills/docs-draft/SKILL.md
@@ -9,7 +9,7 @@ description: >-
   documentation factory (see .agents/factory/methodology.md).
 disable-model-invocation: true
 argument-hint: "[status | dry run | phase P3 | through P5 | next 2 | skip review]"
-allowed-tools: Read, Write, Edit, Grep, Glob, Bash(git status *), Bash(git branch *), Bash(git rev-parse *), Bash(git log *), Bash(git diff *), Bash(git add *), Bash(git commit *), Bash(python3 .agents/factory/bin/*), Bash(python3 -c *), Bash(.venv/bin/mkdocs *), Bash(mkdocs *), Bash(python tools/generate_breadcrumbs.py), Bash(grep *)
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(git status *), Bash(git branch *), Bash(git rev-parse *), Bash(git log *), Bash(git diff *), Bash(git add *), Bash(git commit *), Bash(uv *), Bash(.venv/bin/python *), Bash(.venv/bin/mkdocs *), Bash(.venv/bin/python .agents/factory/bin/*), Bash(python3 -c *), Bash(grep *)
 ---
 
 # docs-draft — execute the roadmap
@@ -19,14 +19,22 @@ ground-truth; you never hand-edit its YAML — `next_phase.py` reads it and `set
 
 ## Step 0 — status / dry-run (when requested)
 
-Print the FSM state (`next_phase.py`) and what the next phase would do. No edits, no commits.
+Print the FSM state (`.venv/bin/python .agents/factory/bin/next_phase.py …`) and what the next phase
+would do. No edits, no commits.
 
 ## Step 1 — Pre-flight
 
-- Clean tree on a `feature/`|`fix/`|`refactor/` branch; resolve `{slug}`.
-- Assert the environment: `python3 -c "import yaml, mkdocs"` (activate `.venv`/conda if it fails).
-- `python3 .agents/factory/bin/next_phase.py spec/{slug}/TECH.md`. If it warns of pointer drift,
-  reconcile with `set_phase.py --current <id>` before acting.
+- Clean tree on a `feature/`|`fix/`|`refactor/` branch; resolve `{slug}`. ("Clean" = no uncommitted
+  changes; ahead of / diverged from `origin` is fine — never `reset`/rebase onto `origin` to fix it.)
+- **Ensure the toolchain env** — a `uv`-synced `.venv` (see AGENTS.md "Setup"); run everything via
+  `.venv/bin/…`, never system Python. Idempotent bootstrap:
+  ```bash
+  [ -x .venv/bin/python ] || uv venv
+  uv pip install -q -r requirements.txt --python .venv/bin/python
+  # fallback without uv: [ -x .venv/bin/python ] || python3 -m venv .venv; .venv/bin/python -m pip install -q -r requirements.txt
+  ```
+- `.venv/bin/python .agents/factory/bin/next_phase.py spec/{slug}/TECH.md`. If it warns of pointer
+  drift, reconcile with `.venv/bin/python .agents/factory/bin/set_phase.py --current <id>` before acting.
 - **Remediation mode:** if `top_status: blocked` or `review.verdict: changes-requested`, read
   `spec/{slug}/REVIEW.md`, reopen the phase(s) covering the failing R-IDs with
   `set_phase.py --phase P<n> --phase-status in_progress` and `--top-status in_progress`.
@@ -45,25 +53,33 @@ Execute every `[ ]` step to the archetype conventions (`style-guide.md`) and the
 - Reuse `main.py` macros / `docs/snippets/` includes for cluster-variable content; escape literal
   `{{`/`{%` with `{% raw %}`.
 - **Add every new page to `mkdocs.yml` `nav:` in this same phase** (else it is orphaned), and when
-  nav changes run `python tools/generate_breadcrumbs.py`.
+  nav changes run `.venv/bin/python tools/generate_breadcrumbs.py`.
 - Never hand-edit generated files (catalogs, breadcrumbs beyond the generator) — regenerate via `tools/`.
 - Content images need meaningful `alt`; verify HPC specifics against an authoritative source.
 
 ## Step 4 — Verify gate
 
 Run the phase's `verify:` command — at minimum
-`.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py`
-plus any nav/front-matter check. When layout matters, also `mkdocs serve` and eyeball the rendered
-page. **A non-zero verify (a new `--strict` warning, a failed check) is a STOP condition — do not
-advance the phase.**
+`.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py`
+plus any nav/front-matter check. When layout matters, also `.venv/bin/mkdocs serve` and eyeball the
+rendered page. **A non-zero verify (a new `--strict` warning, a build ERROR, or a failed check) is a
+STOP condition — do not advance the phase.**
 
 ## Step 5 — Update the FSM
 
 Check off the `[ ]` items in the body; advance state via
-`set_phase.py spec/{slug}/TECH.md --phase {id} --phase-status done --current {next_id_or_done} --touch`
+`.venv/bin/python .agents/factory/bin/set_phase.py spec/{slug}/TECH.md --phase {id} --phase-status done --current {next_id_or_done} --touch`
 (regenerate — never hand-edit YAML). Update `--hill` when the honesty signal changes. When all phases
 are done, also `--top-status in_review`.
 
+**Meta-note (self-improvement; usually skip).** If *this phase* hit a problem in the *skillset
+itself* — the bar is **"instructions' fault, not mine or the task's"** (a wrong/ambiguous
+instruction, a `verify:` recipe you had to hand-fix, an allowed-tools gap, a gate that mis-fired) —
+append one terse finding to `spec/{slug}/META.md` (from `.agents/factory/templates/META.md` if
+absent), `origin=docs-draft:{id}`. It rides Step 6's `git add -A`. Silence by default; ≤1–2 per phase;
+add "· seen again" rather than duplicating; a fix that would weaken a `hammerable:false` gate is
+`severity=high`. **Recording only** — `/docs-harness` applies fixes later, human-reviewed.
+
 ## Step 6 — Commit (atomic content + state)
 
 `git add -A` → `git commit -m "[{kind}] Draft {slug} {id}: {phase name}"` (no `WIP:` prefix, no
diff --git a/.agents/skills/docs-feature/SKILL.md b/.agents/skills/docs-feature/SKILL.md
index ff226b66..dbec8df2 100644
--- a/.agents/skills/docs-feature/SKILL.md
+++ b/.agents/skills/docs-feature/SKILL.md
@@ -19,14 +19,25 @@ first step of the factory (see `.agents/factory/methodology.md`). Produce exactl
 and stop for the human's sign-off before the more expensive `/docs-plan`.
 
 **Never guess.** Where intent is ambiguous — which cluster, which audience, an HPC spec you can't
-confirm — emit a literal `[NEEDS CLARIFICATION: …]` marker and ask (`AskUserQuestion`). Wrong or
-invented documentation harms real users.
+confirm — emit a literal `[NEEDS CLARIFICATION: …]` marker and ask the human. Wrong or invented
+documentation harms real users. **Shaping is not research:** answer from a quick local
+`Read`/`Grep` (the prompt, the files it references, the nav) or from the human — do **not** open a
+research rabbit hole here. Anything needing external verification (an HPC spec, a repo, a vendor
+doc) is marked `[NEEDS CLARIFICATION]` and deferred to `/docs-plan`.
+
+> **Harness portability (smaller models / non-Claude harnesses).** Degrade gracefully, don't fail:
+> gather clarifications with `AskUserQuestion` **if your harness has it, otherwise ask the questions
+> in plain text and STOP** for the human. The `allowed-tools` / `disable-model-invocation`
+> front-matter keys are Claude-Code-specific and are harmlessly ignored elsewhere.
 
 ## Step 1 — Pre-flight
 
-- Confirm you are on `main` with an otherwise-clean tree. The only permitted pending change is an
-  untracked `spec/{slug}/GOAL.md` you are about to adopt. If not on `main`, STOP and tell the human.
-- `git fetch origin || true` (best-effort freshness).
+- Confirm you are on `main`. **"Clean" tree = no *uncommitted* changes** (an untracked
+  `spec/{slug}/GOAL.md` you are about to adopt is fine). **Being ahead of / diverged from
+  `origin/main` is normal and is NOT a blocker** — the `.agents/` factory may exist only on local
+  `main`. If not on `main`, STOP and tell the human.
+- `git fetch origin || true` (best-effort freshness). **Do not** `reset`/rebase onto `origin` to
+  reconcile divergence — you branch off **local** `main` (HEAD) in Step 3.
 
 ## Step 2 — Resolve slug / kind / appetite
 
@@ -39,9 +50,14 @@ invented documentation harms real users.
 - **Collision check:** `git rev-parse --verify {branch}` must fail (branch absent) and
   `spec/{slug}/` must not already be tracked. If either exists, pick a new slug or STOP.
 
+> **Substitute the placeholders — never emit a literal `{slug}`/`{branch}`.** Worked example: slug
+> `gautschi-python-guide` → branch `feature/gautschi-python-guide` → artifact
+> `spec/gautschi-python-guide/GOAL.md`.
+
 ## Step 3 — Create the branch
 
-`git switch -c {branch} main`
+`git switch -c {branch} main`  — off **local** `main` (HEAD), never `origin/main` (which may lack
+the `.agents/` factory).
 
 ## Step 4 — Write / refine GOAL.md
 
@@ -62,6 +78,11 @@ If adopting a hand-written untracked `GOAL.md`, refine it in place rather than o
 Bounded to the appetite · no unresolved `[NEEDS CLARIFICATION]` left silently · every criterion is
 testable (renderable/checkable) · the archetype is implied or stated.
 
+**Size circuit-breaker.** If the job needs more than ~8–10 acceptance criteria, or spans several
+distinct deliverable types / "pillars," it is probably too big for one job. Surface this to the
+human and offer to split into a **pilot + follow-ups** (record the deferrals in Non-goals) rather
+than shaping a mega-GOAL that a downstream draft can't land cleanly.
+
 ## Step 6 — Commit
 
 `git add spec/{slug}/GOAL.md` → `git commit -m "[{kind}] Shape {slug} goal"`
@@ -71,3 +92,22 @@ testable (renderable/checkable) · the archetype is implied or stated.
 
 Summarize the slug, kind, appetite, and the R-IDs; note any `[NEEDS CLARIFICATION]` awaiting the
 human. Recommend `/docs-plan` once the GOAL is approved.
+
+**GOAL is the locked contract — but not frozen forever.** It MAY be amended later (during
+`/docs-plan`, or after review feedback) **only with explicit human direction**, recorded in a dated
+Clarifications sub-block with the affected R-IDs re-confirmed. It must never drift *silently* during
+drafting.
+
+## Step 8 — Meta-note (self-improvement; usually a no-op)
+
+**Silence is the default.** Append a finding to `spec/{slug}/META.md` (create it from
+`.agents/factory/templates/META.md` if absent) **only** when a concrete problem in the *skillset
+itself* cost you something this run. **The bar:** *was this the instructions' fault — not mine, not
+the task's?* Qualifies: you hand-fixed a command the skill gave (wrong flag/path, unquoted YAML); a
+genuinely ambiguous instruction; a `[NEEDS CLARIFICATION]` better guidance could have pre-empted; an
+allowed-tools/step mismatch; a gate that passed/failed misleadingly. Stay silent for a merely hard
+task, an error you made against clear guidance, a one-off *content* issue (→ GOAL), or a vague
+preference. Cap ≤3, terse; add "· seen again" to an existing finding rather than duplicating; a fix
+that would weaken a `hammerable:false` gate is `severity=high`. **This step only records** — fixes
+are applied later by `/docs-harness`, human-reviewed. If you wrote one, commit it:
+`git add spec/{slug}/META.md && git commit -m "[harness] Meta-note: {slug} (docs-feature)"`.
diff --git a/.agents/skills/docs-harness/SKILL.md b/.agents/skills/docs-harness/SKILL.md
new file mode 100644
index 00000000..f5973b77
--- /dev/null
+++ b/.agents/skills/docs-harness/SKILL.md
@@ -0,0 +1,106 @@
+---
+name: docs-harness
+description: >-
+  Apply the documentation factory's self-improvement findings. Reads a job's spec/{slug}/META.md
+  (the harness-retrospective log the docs-* skills append to), proposes the recommended skillset
+  fixes, and — human-gated, defaulting to all but scopable to specific finding ids — applies them to
+  the .agents/ factory, one atomic [harness] commit each, recording every decision in
+  .agents/factory/harness-log.md. A META/maintenance skill: it changes the TOOLCHAIN, not any
+  documentation. Not part of the content lifecycle; it never writes META.md (no meta-on-meta).
+disable-model-invocation: true
+argument-hint: "<slug | spec/<slug>/META.md | --all> [F1 F3 …] [--severity high] [--dry-run]"
+allowed-tools: Read, Write, Edit, Grep, Glob, AskUserQuestion, Bash(git status *), Bash(git branch *), Bash(git switch *), Bash(git checkout *), Bash(git rev-parse *), Bash(git log *), Bash(git diff *), Bash(git add *), Bash(git commit *), Bash(git push *), Bash(gh pr *), Bash(uv *), Bash(.venv/bin/python *), Bash(.venv/bin/python .agents/factory/bin/*), Bash(grep *)
+---
+
+# docs-harness — apply the factory's self-improvement findings
+
+The **act** side of the self-improvement loop. The `docs-*` skills *observe* friction and append
+findings to `spec/{slug}/META.md`; this skill *reads* those findings and, **with human review**,
+edits the `.agents/` factory to fix them. It touches the toolchain only — never documentation, never
+`GOAL/PLAN/TECH/REVIEW`, and **never `META.md` findings' text** (it only flips their `status`).
+
+> **This skill can degrade the factory if misused — so it is human-gated by construction.** It never
+> auto-applies; it previews every edit; and it refuses to weaken a safety gate without an explicit
+> typed override (see Step 3). `.agents/**` changes do **not** trigger the production deploy (the CI
+> path filter skips factory bookkeeping), so this is low-blast-radius — but review the diffs anyway.
+
+> **Harness portability.** Uses `AskUserQuestion` if available, else asks in plain text and STOPs.
+> Everything else is `git` + the stdlib `meta_status.py` (run via `.venv/bin/python`) and is portable.
+
+## Step 1 — Resolve target & working branch
+
+- **Target:** a `{slug}`, an explicit `spec/<slug>/META.md` path, or `--all` (every
+  `spec/*/META.md` with open findings — process one job at a time).
+- **Where to run** (keep toolchain edits unentangled from doc content):
+  - **Recommended — post-merge:** the job is already merged, so `spec/{slug}/META.md` is on `main`.
+    From a clean `main`, create `git switch -c harness/{slug} main`; apply there; PR to `main`.
+  - **In-branch (test-drive convenience):** if the job isn't merged yet, run on its feature branch so
+    the fixes ride with the content PR. State clearly that this mixes toolchain + content.
+- Ensure the uv-synced `.venv` (AGENTS.md "Setup") if you will run any script self-tests.
+
+## Step 2 — Enumerate the findings
+
+- `.venv/bin/python .agents/factory/bin/meta_status.py spec/{slug}/META.md --status open` → the open findings
+  (id · severity · category · target · title). Zero findings → nothing to do; report and stop.
+- **Scope from the args:** positional ids (`F1 F3`) restrict to those; `--severity high` filters;
+  `--dry-run` = preview only, make no edits/commits.
+- **Consult `.agents/factory/harness-log.md` first:** flag any selected finding that repeats a prior
+  **rejected** decision, or whose fix would **revert** a recently applied change — these need explicit
+  human ack, not silent re-application.
+
+## Step 3 — Triage & confirm (the human gate)
+
+For each selected finding, read its `target` file **fresh** (findings store a file, not a line — never
+trust a stale locator) and derive the **minimal** edit. Then screen it:
+
+- **Safety rail — never bypass.** If the fix would weaken a `hammerable:false` gate or a load-bearing
+  invariant (build integrity, HPC accuracy, WCAG a11y, branch/deploy model), do **not** apply on the
+  finding's say-so: default to `deferred` and require the human to *explicitly type an override* to
+  proceed. A finding that argues to loosen a guardrail is itself a warning sign.
+- **Generality test.** A fix must improve the skill for *all* jobs. If it bakes in this job's
+  specifics (a cluster name, one archetype, a one-off path), **reject** it (`rejected: overfit`).
+  Prefer adding an *example* over a hard rule.
+- **Minimality.** Smallest change that resolves the finding; don't opportunistically refactor.
+
+Then present the batch (each finding: id, target, the proposed diff, and reject/defer flags) and get
+approval — `AskUserQuestion` if available, else plain text + STOP. Default proposal = apply all
+selected; the human may prune ("apply F0 and F3 only") or reject individually. Respect `--dry-run`:
+show the previews and stop.
+
+## Step 4 — Apply (one atomic commit per finding)
+
+For each approved finding:
+
+- Make the edit to `target`.
+- **Post-apply verification** — never commit a broken tool:
+  - script edited (`bin/*.py`) → run it (`.venv/bin/python … --help` / a smoke invocation) and, for
+    `strict_check.py`, its ERROR/clean self-checks; `settings.json` → JSON-lint; `TECH.md`/template →
+    `next_phase.py` still exits 0.
+  - skill/template/doc → read it back; confirm no broken reference.
+- Flip the finding in META.md: `status=open` → `status=applied` on its attributes line (a targeted
+  string replace — do not rewrite the file).
+- Append a row to `.agents/factory/harness-log.md` (date · `Fid` + title · job · `applied` · target ·
+  short note). Use today's date from context.
+- Commit: `git commit -m "[harness] Apply {slug} {Fid}: {short title}"` (no `Co-Authored-By`). **One
+  finding per commit** so any single fix is independently revertable.
+
+## Step 5 — Rejections, deferrals & pruning
+
+- Declined finding → flip `status=rejected` (or `deferred`) and append `· <status>: <reason>` to its
+  attributes line; log it in `harness-log.md` so it does not recur.
+- Stale/unapplicable finding (target moved, already fixed) → `status=rejected` with `stale`.
+- Commit these META/log updates together: `[harness] Triage {slug} META findings`.
+
+## Step 6 — Report & (optional) PR
+
+- Summary: applied / deferred / rejected counts, each finding's outcome, and the commits.
+- On a `harness/{slug}` branch: offer to `git push` + `gh pr create --base main` (human-confirmed).
+  Note the deploy CI skips `.agents/**`, so this PR does not roll production — but it still changes how
+  every future job is built, so it deserves a real review.
+
+## Guardrails recap (do not violate)
+
+- **Never** auto-apply; **never** weaken a safety/`hammerable:false` gate without an explicit human
+  override; **never** apply an overfit fix; **never** write or invent META findings; **never** recurse
+  (`/docs-harness` produces no META). Cap ~8 applied findings per run without re-confirmation. When in
+  doubt, `defer` and ask.
diff --git a/.agents/skills/docs-plan/SKILL.md b/.agents/skills/docs-plan/SKILL.md
index 2449538d..3870af8b 100644
--- a/.agents/skills/docs-plan/SKILL.md
+++ b/.agents/skills/docs-plan/SKILL.md
@@ -8,7 +8,7 @@ description: >-
   (see .agents/factory/methodology.md).
 disable-model-invocation: true
 argument-hint: "[appetite small|big] [skip research] [status]"
-allowed-tools: Read, Write, Edit, Grep, Glob, Agent, AskUserQuestion, WebSearch, WebFetch, Bash(git status *), Bash(git branch *), Bash(git rev-parse *), Bash(git log *), Bash(git add *), Bash(git commit *), Bash(python3 .agents/factory/bin/*), Bash(python3 -c *)
+allowed-tools: Read, Write, Edit, Grep, Glob, Agent, AskUserQuestion, WebSearch, WebFetch, Bash(git status *), Bash(git branch *), Bash(git rev-parse *), Bash(git log *), Bash(git add *), Bash(git commit *), Bash(uv *), Bash(.venv/bin/python *), Bash(.venv/bin/mkdocs *), Bash(.venv/bin/python .agents/factory/bin/*), Bash(python3 -c *)
 ---
 
 # docs-plan — research → PLAN → TECH
@@ -16,13 +16,33 @@ allowed-tools: Read, Write, Edit, Grep, Glob, Agent, AskUserQuestion, WebSearch,
 Design the change and generate the phased FSM the drafting step resumes from. Two invariant gates
 bracket the design so it can't drift from the constitution.
 
+> **Harness portability (smaller models / non-Claude harnesses).** This skill leans on two
+> Claude-Code conveniences — degrade gracefully rather than fail. **Subagent fan-out** (`Agent`,
+> Step 3): if unavailable, do the research **sequentially yourself**, writing the same
+> `research/NN-*.md` files. **Interactive questions** (`AskUserQuestion`): if unavailable, ask in
+> plain text and STOP. The `allowed-tools` / `disable-model-invocation` front-matter keys are
+> Claude-specific and are harmlessly ignored elsewhere. Everything else (git, `uv`/`.venv`, the FSM
+> scripts) is plain shell and portable.
+
 ## Step 1 — Pre-flight & load
 
 - Confirm a `feature/`|`fix/`|`refactor/` branch with a clean tree; resolve `{slug}` from the branch.
-- Assert the environment: `python3 -c "import yaml, mkdocs"` (activate `.venv`/conda if it fails).
+  ("Clean" = no uncommitted changes; being ahead of / diverged from `origin` is fine and is **not**
+  a blocker — never `reset`/rebase onto `origin` to "fix" it.)
+- **Ensure the toolchain env** — a `uv`-synced `.venv` (see AGENTS.md "Setup"), then run everything
+  via `.venv/bin/…` (never system Python, which lacks the pinned deps). Idempotent bootstrap:
+  ```bash
+  [ -x .venv/bin/python ] || uv venv
+  uv pip install -q -r requirements.txt --python .venv/bin/python
+  # fallback without uv: [ -x .venv/bin/python ] || python3 -m venv .venv; .venv/bin/python -m pip install -q -r requirements.txt
+  ```
+  Confirm it works: `.venv/bin/python -c "import yaml, mkdocs"`.
 - Read `spec/{slug}/GOAL.md`, `.agents/factory/invariants.md`, `.agents/factory/style-guide.md`,
   and `AGENTS.md`. GOAL.md must be committed with **no unresolved `[NEEDS CLARIFICATION]`** — if any
   remain, STOP and return to `/docs-feature`.
+- **Amending the GOAL:** if research/design reveals that a *requirement itself* must change, amend
+  `spec/{slug}/GOAL.md` **only with explicit human sign-off** — in a dated Clarifications sub-block,
+  with the affected R-IDs re-confirmed. Never silently drift requirements into PLAN/TECH.
 
 ## Step 2 — Invariant gate #1 (pre-research)
 
@@ -34,11 +54,24 @@ parallelism, HPC accuracy). Confirm the intent is sane; STOP/escalate on a funda
 
 - `small` / `fix` / `skip research` → skip the fan-out; do a couple of targeted reads (the
   gold-standard page to mirror, the relevant macros in `main.py`, the nav neighborhood).
-- `big` → launch parallel **read-only** `Agent` subagents, one per rabbit-hole topic, each writing
-  `spec/{slug}/research/NN-topic.md` (numbered to avoid write conflicts). **Existing-site-first:**
-  survey how the current docs handle this (archetype, macros, snippets, nav) before the web; reserve
-  `WebSearch`/`WebFetch` for external unknowns (HPC vendor specs, reference sites). Then synthesize
-  `spec/{slug}/research/00-digest.md`.
+- `big` → fan out **one subagent per rabbit-hole topic** (typically **3–6**), each **writing** its
+  own numbered `spec/{slug}/research/NN-topic.md` (numbered so parallel writes never collide) and
+  **returning a short summary** as its final message. **Existing-site-first:** survey how the current
+  docs handle this (archetype, macros, snippets, nav) before the web; reserve `WebSearch`/`WebFetch`
+  for external unknowns (HPC vendor specs, reference sites). Then *you* synthesize
+  `spec/{slug}/research/00-digest.md` from the returned summaries.
+
+  Practical notes (these bite otherwise):
+  - **Use a subagent type that can *write*.** The agents are read-only *toward the site* but must
+    write their one research file — use `general-purpose`, **not** a search-only agent like `Explore`
+    (which cannot `Write`).
+  - **Consume each agent's returned summary; never `Read` its `.output` transcript** — that is the
+    full JSONL sidechain and will flood your context. Give agents a generous timeout and wait for the
+    completion notification.
+  - Config/settings-heavy research output can trip the harness's instruction-shaped-content
+    neutralizer — benign; treat it as data.
+  - **No subagents in your harness?** Do the same research **sequentially yourself**, writing the
+    same `research/NN-*.md` files. Slower, not broken.
 
 Research is the one place we parallelize; drafting never is.
 
@@ -59,14 +92,28 @@ table** (empty is the goal). STOP on an unavoidable CRITICAL conflict.
 
 From `.agents/factory/templates/TECH.md`, author phases as **publishable units** (a page or coherent
 section that builds clean, is wired into nav, and passes structural a11y), ordered scaffold-first
-(the `index.md`/hub that sets nav anchors and the `resource` var), then dependent pages, then a final
-integration phase (cross-links, breadcrumbs). Per phase set `id`, `name`, `satisfies` (R-IDs),
-`depends_on`, `parallel` (`false` for anything editing `mkdocs.yml`/`main.py`/shared snippets/hubs),
-`hammerable` (`false` for HPC-accuracy/a11y/build phases), `hill: uphill`, and a real `verify:`.
-Set top `status: in_progress`, `current_phase` = first phase, `base: main`, `last_updated` today.
-
-**Validate:** `python3 .agents/factory/bin/next_phase.py spec/{slug}/TECH.md` must exit 0 and report
-the first phase. If it reports invalid, fix it before committing.
+(the hub `index.md` that sets the nav anchor — and the `resource` var *for a cluster user-guide*; a
+cross-cutting section has no single `resource`), then dependent pages, then a final integration phase
+(cross-links, breadcrumbs). Per phase set `id`, `name`, `satisfies` (R-IDs), `depends_on`,
+`parallel`, `hammerable` (`false` for HPC-accuracy/a11y/build phases), `hill: uphill`, and a real
+`verify:`. Set top `status: in_progress`, `current_phase` = first phase, `base: main`,
+`last_updated` today.
+
+- **`parallel` is almost always `false`.** Any phase touching shared surface — `mkdocs.yml` nav,
+  `main.py`, a shared snippet, a hub — is `false`, and nearly every content phase edits nav. Only
+  `true` for genuinely independent sibling pages that touch no shared surface. When unsure, `false`.
+- **`verify:` is hand-written YAML — the #1 FSM-corruption risk.** Quote the whole value and keep
+  single-quotes *inside* it (it contains pipes/colons). Vetted recipe:
+  `".venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py && grep -q '<page>.md' mkdocs.yml"`
+  — for a page embedding a verbatim `--8<--` file, append `&& grep -rq '<sentinel>' site/<path>/`
+  (the gate cannot see a silently-empty include).
+- **Phase-count circuit-breaker:** more than ~8 phases usually means the GOAL is too big — flag it to
+  the human and consider splitting (see `docs-feature` Step 5) rather than committing a sprawling FSM.
+
+**Validate — before writing any phase prose, and fix until it passes:**
+`.venv/bin/python .agents/factory/bin/next_phase.py spec/{slug}/TECH.md` must exit 0 and report the
+first phase. Common failures: an unquoted `verify:`, a `depends_on` naming an unknown phase id, a
+`current_phase` typo, or a `status` outside the allowed enum.
 
 ## Step 7 — Commit
 
@@ -77,3 +124,17 @@ the first phase. If it reports invalid, fix it before committing.
 
 Summarize the design, the phase list, and any risks/open questions for the human. Recommend
 `/docs-draft` to begin executing the roadmap.
+
+## Step 9 — Meta-note (self-improvement; usually a no-op)
+
+**Silence is the default.** Append a finding to `spec/{slug}/META.md` (create it from
+`.agents/factory/templates/META.md` if absent) **only** when a concrete problem in the *skillset
+itself* cost you something this run. **The bar:** *was this the instructions' fault — not mine, not
+the task's?* Qualifies: you hand-fixed a command the skill gave (wrong flag/path, unquoted `verify:`
+YAML); a genuinely ambiguous instruction; a research/agent-orchestration snag the guidance should
+have pre-empted; an allowed-tools/step mismatch; a validator that passed/failed misleadingly. Stay
+silent for a merely hard task, an error against clear guidance, a one-off *content* issue (→
+GOAL/PLAN), or a vague preference. Cap ≤3, terse; add "· seen again" to an existing finding rather
+than duplicating; a fix that would weaken a `hammerable:false` gate is `severity=high`. **This step
+only records** — fixes are applied later by `/docs-harness`, human-reviewed. If you wrote one, commit
+it: `git add spec/{slug}/META.md && git commit -m "[harness] Meta-note: {slug} (docs-plan)"`.
diff --git a/.agents/skills/docs-publish/SKILL.md b/.agents/skills/docs-publish/SKILL.md
index b18b0d30..9f03e6b1 100644
--- a/.agents/skills/docs-publish/SKILL.md
+++ b/.agents/skills/docs-publish/SKILL.md
@@ -8,7 +8,7 @@ description: >-
   this is the one irreversible, outward step. Final step of the documentation factory.
 disable-model-invocation: true
 argument-hint: "[pr (default) | local] [merge]"
-allowed-tools: Read, Grep, Glob, AskUserQuestion, Bash(git status *), Bash(git branch *), Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git fetch *), Bash(git push *), Bash(git switch *), Bash(git checkout *), Bash(git merge *), Bash(git add *), Bash(git commit *), Bash(gh pr *), Bash(gh repo *)
+allowed-tools: Read, Grep, Glob, AskUserQuestion, Bash(git status *), Bash(git branch *), Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git fetch *), Bash(git push *), Bash(git switch *), Bash(git checkout *), Bash(git merge *), Bash(git add *), Bash(git commit *), Bash(gh pr *), Bash(gh repo *), Bash(.venv/bin/python .agents/factory/bin/meta_status.py *)
 ---
 
 # docs-publish — ship the branch to main
@@ -39,6 +39,12 @@ Report the review verdict, commits vs `main`, and any existing PR (`gh pr status
   - **Research** → `spec/{slug}/research/*.md` (if present)
   - **Phases completed** → from the `TECH.md` FSM (id · name · satisfies R-IDs)
   - **Verification** → from `spec/{slug}/REVIEW.md` (build/render/link/nav/a11y results, verdict)
+  - **🔧 Harness feedback** *(only if
+    `.venv/bin/python .agents/factory/bin/meta_status.py spec/{slug}/META.md --status open` reports `open > 0`)*
+    → a short, collapsed section listing each open finding (`id · severity · title`), then label the
+    PR: `gh pr edit --add-label harness-feedback`. Keep it terse (link to `META.md` for detail) so it
+    doesn't dominate the PR; route them later with `/docs-harness`. Do **not** write or resolve
+    findings here.
   - `Closes #NN` (this auto-closes the issue — `main` is the default branch)
   - trailing line: `🤖 Generated with [Claude Code](https://claude.com/claude-code)`
 
diff --git a/.agents/skills/docs-review/SKILL.md b/.agents/skills/docs-review/SKILL.md
index 1c6d8a11..778e756f 100644
--- a/.agents/skills/docs-review/SKILL.md
+++ b/.agents/skills/docs-review/SKILL.md
@@ -10,7 +10,7 @@ description: >-
   documentation factory (see .agents/factory/review-rubric.md).
 disable-model-invocation: true
 argument-hint: "[debate] [completeness] [status]"
-allowed-tools: Read, Grep, Glob, Write, Agent, ReportFindings, AskUserQuestion, Bash(git status *), Bash(git branch *), Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git add *), Bash(git commit *), Bash(python3 .agents/factory/bin/set_phase.py *)
+allowed-tools: Read, Grep, Glob, Write, Agent, ReportFindings, AskUserQuestion, Bash(git status *), Bash(git branch *), Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git add *), Bash(git commit *), Bash(.venv/bin/python .agents/factory/bin/set_phase.py *)
 ---
 
 # docs-review — blind adversarial QA
@@ -34,9 +34,10 @@ Spawn a fresh `Agent` (general-purpose) given **inline, ONLY**:
 - the full text of `.agents/factory/invariants.md`, `.agents/factory/review-rubric.md`,
   `.agents/factory/style-guide.md`, and `.agents/factory/strict-baseline.txt`;
 - instructions to work in the runnable repo (project env active) and **verify by executing**:
-  `.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py`, `mkdocs serve`
+  `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py`, `mkdocs serve`
   + view changed pages, nav/front-matter/a11y checks;
-- an explicit instruction to **NOT read `PLAN.md`, `TECH.md`, or `research/`**.
+- an explicit instruction to **NOT read `PLAN.md`, `TECH.md`, `research/`, or `META.md`** (the last
+  can leak author intent and would break blindness).
 
 Required return: structured findings — each with severity, **CONFIRMED** (reproduced by
 command/render/diff) vs **PLAUSIBLE** (HPC accuracy or prose a11y that isn't machine-checkable →
@@ -53,9 +54,9 @@ manufacture findings.
 
 ## Step 4 — Set verdict & route
 
-- **Clean pass:** `set_phase.py spec/{slug}/TECH.md --verdict approved --reviewed-commit {sha} --touch`
+- **Clean pass:** `.venv/bin/python .agents/factory/bin/set_phase.py spec/{slug}/TECH.md --verdict approved --reviewed-commit {sha} --touch`
   → recommend `/docs-publish`.
-- **CONFIRMED findings:** `set_phase.py … --top-status blocked --verdict changes-requested
+- **CONFIRMED findings:** `.venv/bin/python .agents/factory/bin/set_phase.py … --top-status blocked --verdict changes-requested
   --reviewed-commit {sha} --blocked-reason "<short>" --touch` → recommend `/docs-draft`. If any
   CONFIRMED finding touches a **high-impact file** (see review-rubric) → STOP and require human sign-off.
 - **PLAUSIBLE only:** surface to the human for triage; do not auto-block.
@@ -67,6 +68,16 @@ manufacture findings.
 A separate fresh subagent that *may* read `TECH.md`: did every planned phase ship? did scope balloon
 past appetite? Append its notes to `REVIEW.md`.
 
+## Step 6 — Meta-note (process only; usually a no-op)
+
+**You (the orchestrator), not the blind reviewer, write this — after `REVIEW.md` exists.** Append a
+finding to `spec/{slug}/META.md` **only** if the *rubric or the review skill itself* was unclear or
+mis-steered the pass (e.g. an invariant that was ambiguous to apply, a verify step that didn't catch
+what it should). **Content findings do NOT go here — they go in `REVIEW.md`.** The bar is the same:
+*the instructions' fault, not the task's.* `origin=docs-review`, terse, ≤2, silence by default; a
+fix that would weaken a `hammerable:false` gate is `severity=high`. Commit it with the review. This
+records only — `/docs-harness` applies fixes later.
+
 ## Final report
 
 Verdict, finding counts (CONFIRMED vs PLAUSIBLE), human-gate status, R-ID coverage, and the next
diff --git a/.github/workflows/rebuild_agent_context.yml b/.github/workflows/rebuild_agent_context.yml
new file mode 100644
index 00000000..fa36e4b4
--- /dev/null
+++ b/.github/workflows/rebuild_agent_context.yml
@@ -0,0 +1,69 @@
+name: Rebuild agentic-AI context on data-model change (GitHub App)
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+    paths:
+      - 'tools/agent_context/**'
+      - 'tools/generate_agent_context.py'
+
+permissions:
+  contents: write
+
+jobs:
+  rebuild-agent-context:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Generate GitHub App installation token
+        id: app-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ secrets.PURDUERCAC_DOCS_BOT_APP_ID }}
+          private_key: ${{ secrets.PURDUERCAC_DOCS_BOT_PRIVATE_KEY }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install jinja2 pyyaml
+
+      - name: Configure git identity
+        run: |
+          git config user.name "purduercac-docs-bot"
+          git config user.email "purduercac-docs-bot@users.noreply.github.com"
+          git pull
+
+      - name: Regenerate agentic-AI context
+        run: python tools/generate_agent_context.py
+
+      - name: Commit and push regenerated context (using App token)
+        env:
+          GITHUB_APP_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          # Stage the regenerated tree before pulling
+          git add docs/snippets/agentic-ai || true
+
+          # Sync with branch to avoid rebase errors
+          git pull origin ${{ github.ref_name }} --rebase || git pull origin ${{ github.ref_name }}
+
+          # Re-stage in case of merge/rebase updates
+          git add docs/snippets/agentic-ai || true
+
+          # Skip commit if no changes
+          git diff --cached --quiet && echo "No changes to commit" && exit 0
+
+          git commit -m "Auto-regenerate agentic-AI context after data-model change"
+          git push https://x-access-token:${GITHUB_APP_TOKEN}@github.com/${{ github.repository }} HEAD:${{ github.ref_name }}
diff --git a/AGENTS.md b/AGENTS.md
index 857ac888..528731b8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,16 +27,23 @@ blog articles, and workshop/training material for RCAC's HPC clusters and storag
 
 ## Environment & working rules
 
-- **Setup:** create a Python environment and install pinned deps.
+- **Setup — one supported way: a `uv`-managed virtualenv synced from `requirements.txt`.** Do
+  **not** run `mkdocs` or the factory scripts against the system Python (it lacks the pinned deps).
+  This bootstrap is idempotent — safe to re-run to resync:
   ```bash
-  python -m venv .venv && source .venv/bin/activate   # or: conda create -n rcac-docs python && conda activate rcac-docs
-  python -m pip install -r requirements.txt
+  # uv-first (recommended):
+  [ -x .venv/bin/python ] || uv venv                       # create ./.venv if missing
+  uv pip install -r requirements.txt --python .venv/bin/python   # sync pinned deps into it
+  # fallback if uv is unavailable:
+  #   [ -x .venv/bin/python ] || python3 -m venv .venv
+  #   .venv/bin/python -m pip install -r requirements.txt
   ```
-  (The local `.venv` may be uv-created and lacks `pip`; `uv pip install -r requirements.txt`
-  syncs it. The project itself is pip/`requirements.txt`-managed — there is no `pyproject.toml`
-  and no `uv.lock`.)
-- **Always run tooling from the repo root.** The macros module (`main.py`) and the factory
-  scripts resolve paths relative to the current directory.
+  Then **invoke every tool through `.venv/bin/…` — no `activate` needed** (this explicit form is
+  unambiguous and is what the factory scripts and `verify:` gates assume): `.venv/bin/mkdocs …`,
+  `.venv/bin/python …`. The project is `requirements.txt`-managed — there is no `pyproject.toml`
+  and no `uv.lock`.
+- **Always run tooling from the repo root** (and via `.venv/bin/`). The macros module (`main.py`)
+  and the factory scripts resolve paths relative to the current directory.
 - **Commit only when explicitly asked.** When you do: branch off **`main`** (never commit
   straight to `main`; never touch `dev` outside an a11y rollout — see Branch & deploy model).
   Commit subjects follow `[category] Imperative summary` — categories include `feature`, `fix`,
@@ -50,13 +57,14 @@ blog articles, and workshop/training material for RCAC's HPC clusters and storag
 ## Commands
 
 ```bash
-mkdocs serve                       # local preview at http://localhost:8000
-mkdocs serve -a localhost:8080     # custom port
-mkdocs build                       # build the static site into ./site (gitignored)
-mkdocs build --strict              # promote link/nav warnings to errors — USE THIS to verify (CI does not)
+# All tooling runs through the uv-synced .venv (see Setup) — no activation needed.
+.venv/bin/mkdocs serve                     # local preview at http://localhost:8000
+.venv/bin/mkdocs serve -a localhost:8080   # custom port
+.venv/bin/mkdocs build                     # build the static site into ./site (gitignored)
+.venv/bin/mkdocs build --strict            # promote link/nav warnings to errors — USE THIS to verify (CI does not)
 
-cd tools && make                   # regenerate the software & dataset catalogs (see Automation)
-python tools/generate_breadcrumbs.py   # regenerate docs/assets/data/breadcrumbs.json after a nav change
+cd tools && make                           # regenerate the software & dataset catalogs (see Automation)
+.venv/bin/python tools/generate_breadcrumbs.py   # regenerate docs/assets/data/breadcrumbs.json after a nav change
 
 # Optional: build the production image locally
 docker build -f Dockerfile.geddes-prod -t rcac-docs-prod:local . && docker run --rm -p 8080:80 rcac-docs-prod:local
@@ -87,8 +95,8 @@ the prod image · pinned in `requirements.txt`. Plugins: `search`, `blog`, `tags
 | `hooks/` | MkDocs hooks (`socialmedia.py`, currently disabled in `mkdocs.yml`). |
 | `Dockerfile.geddes-prod`, `k8s/geddes-prod/` | Production image (builder → nginx) and Kubernetes manifests. |
 | `.github/workflows/` | CI/CD (deploy, catalog rebuild, breadcrumbs, branch sync/guard). |
-| **`.agents/`** | The spec-driven **documentation factory** (`docs-*` skills + `factory/` methodology, invariants, style guide, EARS, review rubric, templates, and `bin/` FSM scripts). `.claude` symlinks here. |
-| **`spec/{slug}/`** | The committed, dated per-job design records (`GOAL/PLAN/TECH/REVIEW.md`) the factory produces and retains on merge. Outside `docs/`, so not published. |
+| **`.agents/`** | The spec-driven **documentation factory** (`docs-*` lifecycle skills + the `docs-harness` self-improvement skill + `factory/` methodology, invariants, style guide, EARS, review rubric, templates, `harness-log.md`, and `bin/` FSM scripts). `.claude` symlinks here. |
+| **`spec/{slug}/`** | The committed, dated per-job records the factory produces and retains on merge: `GOAL/PLAN/TECH/REVIEW.md` (the content spine) plus `META.md` (orthogonal harness-retrospective findings). Outside `docs/`, so not published. |
 
 ## Content conventions & archetypes
 
@@ -121,8 +129,8 @@ review). The headlines:
 5. **Links relative, assets absolute.**
 6. **Front-matter per archetype** (blog `categories` from the allowed set; `<!-- more -->`).
 7. **Macros/snippets + Jinja escaping.**
-8. **Build integrity** — `mkdocs build --strict` introduces no new warnings vs the baseline
-   (`hammerable: false`).
+8. **Build integrity** — `mkdocs build --strict` introduces no new warnings **and no build
+   errors** vs the baseline (`hammerable: false`).
 9. **Content-level WCAG 2.1 accessibility** (`hammerable: false`).
 10. **Per-cluster parallelism** — keep the shared chapter set/order.
 11. **HPC technical accuracy** — commands, flags, partitions, paths, specs must be correct
@@ -183,10 +191,17 @@ review). The headlines:
   `feature/`|`fix/`|`refactor/` branch with artifacts committed under `spec/{slug}/`.
   `.agents/factory/methodology.md` is the *why*; `getting-started.html` is the onboarding.
   **Ceremony scales to appetite** — a one-sentence fix may skip the lifecycle entirely.
+- **The factory improves itself (self-improvement loop).** Each lifecycle skill ends with a
+  silence-by-default **meta-note** step that logs skillset friction — only when *the instructions'
+  fault, not the task's* — to `spec/{slug}/META.md` (`F#` findings, orthogonal to the content spine,
+  kept out of the blind reviewer's context). `/docs-publish` surfaces open findings in the PR body;
+  the human-gated **`/docs-harness`** skill then applies the recommended fixes to `.agents/` (atomic
+  `[harness]` commits, logged in `factory/harness-log.md`). It never auto-weakens a `hammerable:false`
+  gate and never writes findings itself. See methodology.md → "The self-improvement loop".
 - **Verify by rendering, not asserting.** After a change, run
-  `mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py` (no new warnings),
-  confirm the page is in `nav:`, and `mkdocs serve` to eyeball the render — the concurrency and
-  link/nav behavior are where documentation bugs hide.
+  `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py` (no new
+  warnings **and no build errors**), confirm the page is in `nav:`, and `.venv/bin/mkdocs serve` to
+  eyeball the render — the concurrency and link/nav behavior are where documentation bugs hide.
 - **Put content where it belongs:** new pages under `docs/…` + a `nav:` entry; cluster-variable
   content via `main.py` macros (extend the macro, don't fork the prose); generated catalogs via
   `tools/`, never by hand.
diff --git a/docs/agentic-ai/acceptable_use.md b/docs/agentic-ai/acceptable_use.md
new file mode 100644
index 00000000..4e027656
--- /dev/null
+++ b/docs/agentic-ai/acceptable_use.md
@@ -0,0 +1,87 @@
+---
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# Acceptable Use & Etiquette
+
+{% set resource = "gautschi" %}
+
+Running an agentic coding tool on RCAC's systems does not change the rules — it
+raises the stakes. An agent can issue commands faster than you can read them, so
+the same acceptable-use and good-citizen expectations that apply to *you* apply
+to any agent acting on your behalf. **You are accountable for everything your
+agent does under your account**, exactly as if you had typed it yourself. The
+rules below are the etiquette for using these tools responsibly on shared HPC
+resources; they are consistent with RCAC's existing Acceptable Use policy, quoted
+at the bottom of this page.
+
+## No heavy compute on the login nodes
+
+Login (front-end) nodes are shared by every user for editing, compiling, and
+submitting work — not for running it. An agent that compiles a large project,
+launches a parallel run, or spins up a long-lived process on a login node
+degrades the system for everyone. Keep agent activity on the front ends light,
+and push real work to the scheduler. This mirrors RCAC's Running Jobs
+guidance:
+
+!!! important
+
+    Do NOT run large, long, multi-threaded, parallel, or CPU-intensive jobs on a
+    front-end login host. All users share the front-end hosts, and running
+    anything but the smallest test job will negatively impact everyone's ability
+    to use the cluster. Always use SLURM to submit your work as a job.
+
+## Run real work through Slurm, with time limits
+
+Any nontrivial computation an agent performs SHALL go through the Slurm
+scheduler, not run interactively on a login node. Instruct your agent to submit
+batch or interactive jobs (`sbatch`, `sinteractive`) with an explicit
+`--time` limit and a correct account, partition, and QOS. A bounded time limit
+protects both your allocation and the shared queue from a runaway job an agent
+started and then lost track of.
+
+## Keep sensitive data out of world-readable locations
+
+Do not let an agent place sensitive or restricted data in world-readable paths
+(for example, a group- or world-readable scratch directory). Agents readily
+create scratch files, logs, and intermediate outputs; make sure those land in
+appropriately-permissioned locations. If your work involves regulated or
+export-controlled data, confirm it is handled on an approved system before an
+agent ever touches it.
+
+## Never expose secrets or credentials
+
+Do not paste passwords, SSH private keys, API tokens, or other credentials into
+an agent's prompt or context, and do not point an agent at files that contain
+them. Whatever an agent can read, it may echo back, log, or transmit to a
+model provider. Treat the agent's context window as potentially observable, and
+keep secrets out of it.
+
+## Confirm destructive and irreversible actions
+
+Require your agent to pause for your confirmation before any destructive or
+hard-to-undo operation — deleting files (`rm`), overwriting data, cancelling
+other users' jobs, or changing permissions on shared paths. Configure your
+harness so these actions prompt rather than run automatically; the
+[per-harness settings](shared_context/settings.md) we publish deny the most dangerous
+operations outright as a starting point.
+
+## Be a good citizen
+
+You share these systems with thousands of other researchers. The same courtesy
+you extend as a human user extends to your agent: do not stress the filesystem
+with runaway metadata operations, do not leave orphaned processes on login
+nodes, and do not consume shared resources you are not actually using. If an
+agent's behavior is affecting the system or other users, RCAC staff may stop it
+without prior notice, exactly as they would any other disruptive workload.
+
+## Acceptable Purdue IT Research Resource Use
+
+{{ resource_use(resource) }}
+
+---
+
+Back to [Agentic AI](index.md).
diff --git a/docs/agentic-ai/best_practices.md b/docs/agentic-ai/best_practices.md
new file mode 100644
index 00000000..f0d8f03f
--- /dev/null
+++ b/docs/agentic-ai/best_practices.md
@@ -0,0 +1,134 @@
+---
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# Best Practices & Limitations
+
+Agentic coding tools are genuinely useful on HPC — they draft submission scripts,
+untangle build errors, and automate the tedious parts of managing a workflow. They
+are also prone to confident, plausible mistakes, and getting good results is less
+about the model than about *how you use it*. This page collects the practices that
+separate a productive session from a frustrating — or costly — one.
+
+## Know when you're doing research versus operations
+
+Draw a line between the two very different jobs you might ask an agent to do:
+
+- **Research** — writing analysis code, exploring a dataset, prototyping a model,
+  drafting and debugging a submission script. Mistakes here are usually cheap and
+  self-correcting: the code doesn't compile, the plot looks wrong, the job fails
+  fast. This is where agents shine, and where you can let them iterate freely.
+- **Operations** — moving or deleting data, managing quota, cancelling jobs,
+  changing permissions, installing software, editing shared files. Mistakes here
+  are expensive and sometimes irreversible: a deleted directory, an exhausted
+  allocation, a corrupted shared environment. Slow down. Review each command before
+  it runs, and keep destructive operations behind an explicit confirmation.
+
+The same agent is trustworthy for the first and needs a short leash for the second.
+Configure your harness accordingly — the
+[per-harness settings](shared_context/settings.md) we publish deny the most dangerous
+operations by default as a starting point.
+
+## Engineer the context
+
+An agent is only as good as the context it operates in. Vague requests get vague —
+often wrong — answers; specific ones get useful results. The canonical illustration
+is Picard ordering from the replicator: not "a drink," but "Tea, Earl Grey, hot."
+Bring the same specificity to your prompts:
+
+- Name the cluster, the partition, the account, and the software versions you
+  actually intend to use, rather than letting the agent guess.
+- Point the agent at the authoritative source. RCAC injects cluster-specific
+  context into agents automatically (see [MCP Servers](mcp_servers.md) and the shared
+  [context files](shared_context/context_files.md)), so an agent connected to our
+  tooling already knows the cluster runs Slurm, uses Lmod, and which partitions it
+  has — it does not have to infer it from general knowledge.
+- Give the agent the error message, the job ID, the exact file — not a paraphrase.
+
+Good context supplied up front prevents the single most common failure mode on HPC:
+a plausible, well-formatted answer written for a system we don't run.
+
+## Verify: augmented, not outsourced
+
+Use an agent to accelerate your own understanding, not to replace it. The goal is to
+be **augmented, not outsourced**.
+
+- **Ask *why*, not just *what*.** When an agent proposes an `#SBATCH` line or a
+  `module load`, ask it to explain the choice. You learn something, and the
+  explanation often exposes a wrong assumption.
+- **Verification isn't optional — it's the core competency.** Read the generated
+  script before you submit it. Confirm the partition exists, the account is one you
+  can charge, the paths are real. An agent will state a nonexistent module or an
+  invalid partition with total confidence.
+- **Mind the expertise paradox.** These tools are most dangerous precisely where you
+  know the least, because that is exactly where you cannot catch the error. If you
+  can't yet evaluate the output, treat it as a draft to learn from, not an answer to
+  run.
+
+## Let the agent ground itself first
+
+Counterintuitively, the safest agents are the ones that look before they leap.
+Encourage — and permit — your agent to run **read-only sanity checks** eagerly,
+before it acts, so its plan is grounded in the real state of the cluster rather than
+an assumption:
+
+- `myquota` — how much home and scratch space you actually have left.
+- `slist` — which accounts you can charge, and their balances.
+- `sfeatures` — the real node/GPU features available.
+- `module avail` / `module list` — what software exists and what is currently
+  loaded.
+
+The per-harness [settings we publish](shared_context/settings.md) allow-list these
+commands so the agent runs them without stopping to ask. An agent that checks `slist`
+before writing
+`--account=` will not invent an account name; one that runs `module avail` before a
+`module load` will not hallucinate a version.
+
+## Understand the blast radius
+
+Agents don't introduce new *kinds* of risk on a well-run cluster so much as they
+**accelerate the pace** at which an ordinary mistake can happen. The confinement that
+already protects our systems — cgroups, quotas, health checks, root-squash,
+per-user permissions — still applies to an agent acting as you. But existing
+hardening has to be *respected*, not bypassed. Keep these failure modes in mind:
+
+- **Destructive commands.** An agent can `rm -rf` a project directory in the time it
+  takes to read the confirmation prompt. Require confirmation for deletes, mass
+  moves, and permission changes; never run in a fully-autonomous "do not ask" mode on
+  shared systems.
+- **Allocation exhaustion.** A retry loop that resubmits a failing GPU job can burn
+  through an allocation in hours. Always set a `--time` limit, watch `slist`, and
+  don't let an agent submit jobs unattended.
+- **Credential and secret leakage.** Whatever an agent reads can end up in its
+  context window, its logs, or a request to a model provider. Never point it at
+  private keys, tokens, or `.env` files, and never paste credentials into a prompt.
+
+## Containers offer limited protection — this is not Docker
+
+A common assumption is that running an agent "in a container" sandboxes it. On RCAC
+clusters that assumption is wrong in an important way:
+
+!!! warning "Apptainer is not a sandbox for agents"
+
+    RCAC uses **Apptainer** (not Docker) for containers, and RCAC's Apptainer
+    configuration **automatically bind-mounts `/home`, `/depot`, and `/scratch`**
+    into the container for convenience. Those mounts are **writable**, so an agent
+    running inside a container can still edit — or delete — your real files on those
+    filesystems. The most likely failure is not a container escape; it is an agent
+    quietly *modifying files* on a mount you forgot was there.
+
+    If you need stronger isolation, invoke Apptainer explicitly with the bind-mounts
+    disabled, and still keep the permission guardrails in place. Do not rely on the
+    container alone.
+
+The harnesses' own OS-level sandboxes (Codex's `bubblewrap`, Gemini's Docker/Podman
+mode, Claude Code's namespace isolation) are frequently **unavailable on shared login
+nodes** as well. Treat the **permission and approval layer as your primary control**,
+point writable work at `$RCAC_SCRATCH`, and deny `rm -rf`/`sudo` outright.
+
+---
+
+Back to [Agentic AI](index.md).
diff --git a/docs/agentic-ai/index.md b/docs/agentic-ai/index.md
new file mode 100644
index 00000000..7732f983
--- /dev/null
+++ b/docs/agentic-ai/index.md
@@ -0,0 +1,95 @@
+---
+title: Agentic AI
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# Agentic AI at RCAC
+
+Researchers on RCAC's clusters are already using agentic coding tools — Claude
+Code, OpenAI Codex, Gemini CLI, opencode, and Warp — to write Slurm scripts,
+debug failing jobs, move data, and explore software. RCAC's stance is
+**proactive engagement, not prohibition**. Rather than forbidding these tools,
+we shape the context in which you use them so their output is more likely to be
+correct for *our* systems, and we give you what you need to **verify** that
+output rather than simply trust it.
+
+These tools are genuinely useful, but they are also capable of producing
+confident, plausible, and wrong answers: a Slurm script for a scheduler we don't
+run, a module name that doesn't exist, a path on the wrong filesystem. The aim of
+this section is to make the tools work *well* on RCAC by giving them accurate,
+cluster-specific context, and to give you the judgment to check what they produce.
+Treat an agent as **augmenting your expertise, not outsourcing it** — ask *why*,
+not just *what*.
+
+!!! note "Early and evolving"
+
+    This is new, actively-developed work. The MCP servers, the shared context
+    files, and the per-harness settings documented here are prototypes that will
+    change over time. We publish them openly and invite your feedback — see the
+    shared-context pages for how to send corrections.
+
+## In this section
+
+<div class="grid cards" markdown>
+
+-   :material-scale-balance:{ .lg .middle } __Acceptable Use & Etiquette__
+
+    ---
+
+    The rules for running agents on RCAC systems, consistent with Purdue's
+    Acceptable Use Policy.
+
+    [:octicons-arrow-right-24: Acceptable Use & Etiquette](acceptable_use.md)
+
+-   :material-lightbulb-on:{ .lg .middle } __Best Practices & Limitations__
+
+    ---
+
+    Using an agent *for research* versus *for operations*; context engineering;
+    verifying output; and the caution/blast-radius risks.
+
+    [:octicons-arrow-right-24: Best Practices & Limitations](best_practices.md)
+
+-   :material-connection:{ .lg .middle } __MCP Servers__
+
+    ---
+
+    RCAC's MCP servers (`rcac-mcp`, `globus-mcp`, `rcac-docs-mcp`) and how they give
+    an agent context that knows our clusters.
+
+    [:octicons-arrow-right-24: MCP Servers](mcp_servers.md)
+
+-   :material-robot:{ .lg .middle } __Running Agents__
+
+    ---
+
+    Set up your harness on the cluster (login nodes) or locally, targeting the
+    cluster over SSH — for all five harnesses.
+
+    [:octicons-arrow-right-24: Running Agents](running_agents/index.md)
+
+-   :material-file-cog:{ .lg .middle } __Shared Context & Settings__
+
+    ---
+
+    The actual context files and per-harness settings each cluster deploys, published
+    verbatim as the canonical source of truth — plus how to send feedback.
+
+    [:octicons-arrow-right-24: Shared Context & Settings](shared_context/index.md)
+
+</div>
+
+For cluster-specific setup pointers, see the **Using AI Agents** chapter in each
+cluster's user guide — for example
+[Gautschi](../userguides/gautschi/using_ai_agents.md),
+[Negishi](../userguides/negishi/using_ai_agents.md), or
+[Gilbreth](../userguides/gilbreth/using_ai_agents.md).
+
+---
+
+*RCAC's approach to agentic computing is described in the PEARC'26 paper "Hello
+Computer: HPC in the Agentic Era" (Lentner & Ashish, 2026) — see the
+[replication package](https://github.com/glentner/pearc26-hello-computer).*
diff --git a/docs/agentic-ai/mcp_servers.md b/docs/agentic-ai/mcp_servers.md
new file mode 100644
index 00000000..37c9cd43
--- /dev/null
+++ b/docs/agentic-ai/mcp_servers.md
@@ -0,0 +1,189 @@
+---
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# RCAC MCP Servers
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open
+standard that lets an agent call external tools and read external context through a
+uniform interface. RCAC builds and maintains MCP servers so that an agent working on
+your behalf has **context that knows our clusters** — it can check your real quota,
+list your actual Slurm accounts, submit and monitor jobs, search the authoritative
+documentation, and move data, instead of guessing from general knowledge.
+
+This is the fix for the failure mode at the heart of agentic HPC: an agent that
+confidently writes a submission script for a scheduler we don't run. Connected to
+these servers, the agent grounds its answers in the live state of the system.
+
+!!! note "Prototypes under active development"
+
+    All three servers below are **working prototypes under active development**. They
+    are open source and usable today, but their tool sets, names, and interfaces
+    **will change over time**. Treat what follows as the current state, not a frozen
+    contract, and see the feedback note at the end of this page.
+
+RCAC currently publishes three servers:
+
+| Server | What it does | Transport |
+|--------|--------------|-----------|
+| `rcac-mcp` | HPC cluster & storage operations | local stdio, over your SSH |
+| `globus-mcp` | Data transfers and remote compute (Globus) | local stdio, your Globus login |
+| `rcac-docs-mcp` | Full-text search of this documentation site | hosted HTTP, or local stdio |
+
+## `rcac-mcp` — HPC operations
+
+**Repository:** <https://github.com/PurdueRCAC/rcac-mcp>
+
+`rcac-mcp` enables agentic development with RCAC's HPC clusters and storage services.
+It gives an agent tools to run shell commands, read and write files, inspect storage
+quota, and drive Slurm — all executed **on the cluster over your existing SSH
+connection**.
+
+The default mode is **local-first**: the server runs as a `stdio` subprocess on your
+own machine and executes everything on the cluster over your existing `~/.ssh/config`
+and keys. It introduces **no new service and no new credential** — the security
+boundary is the SSH connection you already have. If you can SSH to the cluster, your
+agent can too, and only with the access you already hold.
+
+The agent works entirely through **tool calls** — it asks the server to run a command,
+submit a job, or read a file, and the server carries that out over the SSH connection,
+which stays a background transport. The agent is not driving an interactive terminal.
+(This differs from a terminal-based harness like Warp, where you open the SSH session
+yourself and the agent rides along in it — see [Running Agents](running_agents/local.md).)
+
+Add it to an MCP-capable harness with the server's canonical configuration block,
+pointing `--ssh-host` at your cluster login node (the example below uses
+`gautschi.rcac.purdue.edu` — use your cluster's host):
+
+```json
+{
+  "mcpServers": {
+    "rcac": {
+      "command": "uvx",
+      "args": ["git+https://github.com/purduercac/rcac-mcp", "--ssh-host", "gautschi.rcac.purdue.edu"]
+    }
+  }
+}
+```
+
+`uvx` fetches, builds, and runs the server in one step, so there is no separate
+install. (You may instead set `RCAC_SSH_HOST` in the environment and omit
+`--ssh-host`.) Per-harness registration details are on the
+[Running Agents](running_agents/local.md) pages.
+
+### Tools it exposes
+
+The server groups its tools by area (names may evolve):
+
+- **Shell & files:** `run_command`, `list_directory`, `read_file`, `write_file`,
+  `upload_file`, `download_file`.
+- **Cluster & storage:** `myquota`, `storage_paths`, `jobinfo`, `jobscript`,
+  `showpartitions`, `average_wait`.
+- **Slurm:** `sbatch`, `squeue`, `scancel`, `sacct`, `sinfo`, `scontrol_show_job`,
+  `scontrol_show_node`, plus RCAC-specific `slist` (your accounts and balances) and
+  `sfeatures` (node hardware features).
+
+### It injects the cluster's shared context
+
+`rcac-mcp` also reads the cluster's **shared context files** and hands them to the
+agent. Over the same SSH connection, it collects the markdown files in
+`/etc/agents.d/` on the host (a configurable location), concatenates them, and
+exposes the result to the agent as a read-only resource named `rcac://context`.
+
+This is how the [context files](shared_context/context_files.md) RCAC publishes reach a
+locally-run agent without you installing anything: the cluster maintains them, and the
+server injects them at connect time. See
+[Shared Context & Settings](shared_context/index.md) for what those files contain.
+
+!!! info "A planned direction, not a shipped fact"
+
+    RCAC intends to **refocus `rcac-mcp` on HPC operations only** and re-architect it
+    around a **generalized plugin model** — for example
+    `cluster-mcp[slurm,lmod,…]`, where scheduler, module-system, and other
+    capabilities become installable extensions. This is a **stated direction for the
+    project, not something that has shipped**: today's public `rcac-mcp` is the
+    single prototype described above (it still bundles the documentation-search tools
+    that now also live in `rcac-docs-mcp`). Expect the name and structure to change;
+    follow the repository for the current state.
+
+## `globus-mcp` — data transfers
+
+**Repository:** <https://github.com/PurdueRCAC/globus-mcp>
+
+`globus-mcp` gives an agent federated data transfer and remote code execution across
+research storage systems, by wrapping the Globus CLI and the Globus Compute SDK. An
+agent can search endpoints, browse remote filesystems, run asynchronous transfers,
+and submit Python functions to Compute endpoints.
+
+!!! warning "Beta software"
+
+    `globus-mcp` is **beta**: its APIs, tool signatures, and behavior may change
+    without notice. Use it with caution in production workflows.
+
+Like `rcac-mcp`, it runs as a local `stdio` subprocess and uses **your own Globus
+identity** — on first use its `globus_login()` and `compute_login()` tools walk you
+through browser-based OAuth. No new RCAC-hosted credential is introduced.
+
+```json
+{
+  "mcpServers": {
+    "globus": {
+      "command": "uvx",
+      "args": ["git+https://github.com/purduercac/globus-mcp"]
+    }
+  }
+}
+```
+
+Its tools cover identity (`whoami`, `globus_login`), endpoints (`endpoint_search`,
+`endpoint_show`), filesystem operations (`ls`, `stat`, `mkdir`, `rename`, `rm`,
+`delete`), transfers (`transfer`, `transfer_batch`, `task_*`), and remote Compute
+(`compute_submit`, `compute_status`, `compute_result`).
+
+## `rcac-docs-mcp` — documentation search
+
+**Repository:** <https://github.com/PurdueRCAC/rcac-docs-mcp>
+
+`rcac-docs-mcp` is a single-purpose server that exposes **this documentation site**
+to an agent through full-text search, so the agent grounds its advice in current,
+authoritative RCAC docs rather than general knowledge. It indexes the user guides,
+software catalog, datasets, blog posts, and workshops and exposes exactly two tools:
+
+- `doc_search(query, category=None)` — full-text search returning ranked results with
+  path, title, heading, and a matching snippet. `category` filters by section
+  (`userguides`, `software`, `datasets`, `blog`, `workshops`).
+- `doc_load(path)` — return the full markdown of one document by its path.
+
+The easiest way to use it is the **hosted instance at
+`https://docs.rcac.purdue.edu/mcp`** — a shared, no-authentication HTTP endpoint.
+Point any HTTP-capable MCP client at that URL; no token or credentials are required.
+Unlike the other two servers, this one does not SSH anywhere and needs no user
+credentials — it only reads a search index — which is why it can be safely public.
+
+You can also run it locally as a `stdio` subprocess (it builds a local index first):
+
+```json
+{
+  "mcpServers": {
+    "rcac-docs": {
+      "command": "uvx",
+      "args": ["git+https://github.com/PurdueRCAC/rcac-docs-mcp"]
+    }
+  }
+}
+```
+
+## Status and feedback
+
+These servers are early, evolving work, and we publish them openly precisely so the
+community can shape them. All three are MIT-licensed; issues and pull requests are
+welcome on their repositories, and you can reach the team at
+[rcac-help@purdue.edu](mailto:rcac-help@purdue.edu) or on
+[Discord](https://discord.gg/RmtKZmaQW9).
+
+---
+
+Back to [Agentic AI](index.md).
diff --git a/docs/agentic-ai/running_agents/index.md b/docs/agentic-ai/running_agents/index.md
new file mode 100644
index 00000000..9839b7b6
--- /dev/null
+++ b/docs/agentic-ai/running_agents/index.md
@@ -0,0 +1,54 @@
+---
+title: Running Agents
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# Running Agents
+
+There are two ways to run an agentic coding tool against an RCAC cluster, and this
+section is organized around that choice. Both are legitimate; which one fits depends
+on your harness and how you like to work.
+
+- **On the cluster (login nodes).** You SSH into a cluster login node and run a
+  command-line harness (Claude Code, Codex, Gemini CLI, or opencode) *there*. The
+  agent lives on the front end alongside your shell, so it sees the real filesystem,
+  modules, and scheduler directly — but it is bound by the same login-node etiquette
+  you are.
+- **Locally, targeting the cluster.** The harness runs in your own environment — your
+  laptop or workstation — and reaches the cluster over your existing SSH access. Two
+  mechanisms fit here: most harnesses (Claude Code, Codex, Gemini CLI,
+  opencode) connect through the RCAC [MCP servers](../mcp_servers.md), which bridge to
+  the cluster over SSH so the agent works through *tool calls*; **Warp** is a desktop
+  terminal in which you SSH into the cluster yourself and its Agent Mode rides your live
+  session. Either way, nothing new is installed on the cluster and no new credentials
+  are created.
+
+<div class="grid cards" markdown>
+
+-   :material-console:{ .lg .middle } __On the Cluster (Login Nodes)__
+
+    ---
+
+    Run a CLI harness directly on a cluster front end. Covers install, the
+    login-node compute rules, and where agents may write.
+
+    [:octicons-arrow-right-24: On the Cluster](on_cluster.md)
+
+-   :material-laptop:{ .lg .middle } __Local (over SSH)__
+
+    ---
+
+    Run the harness on your own machine and reach the cluster over SSH — no new
+    credentials, no hosted infrastructure. The recommended setup, and the only way to
+    use Warp.
+
+    [:octicons-arrow-right-24: Local, Targeting the Cluster](local.md)
+
+</div>
+
+---
+
+Back to [Agentic AI](../index.md).
diff --git a/docs/agentic-ai/running_agents/local.md b/docs/agentic-ai/running_agents/local.md
new file mode 100644
index 00000000..e12523de
--- /dev/null
+++ b/docs/agentic-ai/running_agents/local.md
@@ -0,0 +1,142 @@
+---
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# Local, Targeting the Cluster
+
+In this mode the agent runs where *you* are — on your laptop or workstation — and
+reaches the cluster over the SSH access you already have. It is the recommended setup for
+most users. Two mechanisms fit here, and they work differently:
+
+- **Through the MCP servers** (Claude Code, Codex, Gemini CLI, opencode). The RCAC
+  [`rcac-mcp`](../mcp_servers.md) server runs alongside your harness and bridges to the
+  cluster over SSH. The agent works purely through **tool calls** — it never drives a
+  terminal itself.
+- **Through the Warp terminal** (Warp). Warp is a desktop terminal in which *you* SSH
+  into the cluster, and its Agent Mode observes and acts within that live session. Warp
+  does **not** use the cluster MCP server.
+
+Either way, nothing new is installed on the cluster and no new credentials are created.
+
+## The MCP-bridge architecture
+
+For the four CLI harnesses, the `rcac-mcp` server runs as a subprocess of your harness
+on your own machine and executes commands on the cluster over your existing
+`~/.ssh/config` and keys. That design has three consequences worth stating plainly:
+
+- **No new credentials.** The server adds no authentication layer of its own. It acts
+  as you, over your SSH connection — the security boundary is the SSH session itself.
+- **No hosted infrastructure.** Nothing is installed or left running on the cluster.
+  The tooling lives on your machine; the cluster sees ordinary SSH commands.
+- **Only the access you already have.** An agent connected this way can do exactly
+  what you can do over SSH — no more. **If you can SSH to the cluster, your agent
+  can too**, within the same permissions.
+
+The agent also gets cluster-aware context automatically: `rcac-mcp` reads the host's
+`/etc/agents.d/` files over SSH and injects them, so the agent knows the cluster's
+partitions, filesystems, and policies without you installing anything.
+
+### Connect `rcac-mcp` to your harness
+
+The canonical `rcac-mcp` configuration points `--ssh-host` at your login node (the
+examples below use `gautschi.rcac.purdue.edu` — substitute your cluster's host). Add it
+to your harness in that harness's native format:
+
+=== "Claude Code / Gemini CLI"
+
+    These read an `mcpServers` JSON block (Claude Code in `.mcp.json`, Gemini CLI in
+    `~/.gemini/settings.json`):
+
+    ```json
+    {
+      "mcpServers": {
+        "rcac": {
+          "command": "uvx",
+          "args": ["git+https://github.com/purduercac/rcac-mcp", "--ssh-host", "gautschi.rcac.purdue.edu"]
+        }
+      }
+    }
+    ```
+
+=== "Codex"
+
+    Add a block to `~/.codex/config.toml`:
+
+    ```toml
+    [mcp_servers.rcac]
+    command = "uvx"
+    args = ["git+https://github.com/purduercac/rcac-mcp", "--ssh-host", "gautschi.rcac.purdue.edu"]
+    ```
+
+=== "opencode"
+
+    Add a local server to `~/.config/opencode/opencode.json`:
+
+    ```json
+    {
+      "mcp": {
+        "rcac": {
+          "type": "local",
+          "command": ["uvx", "git+https://github.com/purduercac/rcac-mcp", "--ssh-host", "gautschi.rcac.purdue.edu"],
+          "enabled": true
+        }
+      }
+    }
+    ```
+
+`uvx` fetches and runs the server on demand, so there is no separate install step. The
+full [settings and permission files](../shared_context/settings.md) for each harness —
+including the shared context and starting-point deny/allow policy — are published in the
+Shared Context & Settings pages of this section.
+
+### The other two servers
+
+- **`globus-mcp`** (data transfers) registers the same way, with
+  `uvx git+https://github.com/purduercac/globus-mcp` as the command and no
+  `--ssh-host` (it uses your browser-based Globus login on first use).
+- **`rcac-docs-mcp`** (documentation search) is easiest as the hosted endpoint: point
+  an HTTP-capable MCP client at `https://docs.rcac.purdue.edu/mcp` — no credentials
+  required.
+
+## Warp: the recommended workflow
+
+Warp is RCAC's recommended harness for most users. It is a desktop terminal
+application, so you run it on your workstation and SSH into the cluster *inside it*; its
+Agent Mode then rides your live SSH session — reading `stdout`/`stderr` and issuing
+commands in the session you opened. Because you are already SSH'd into the cluster,
+Warp does **not** use the `rcac-mcp` bridge; the two are alternative ways to reach the
+same cluster, not layers you combine.
+
+Recommended workflow:
+
+1. **Install Warp** on your workstation (macOS, Windows, or Linux) and sign in.
+2. **SSH into the cluster** in a Warp terminal.
+3. **Wire in the shared context.** Once you are on the cluster, RCAC's context lives at
+   `/etc/agents.d/` (concatenated into an `AGENTS.md`). You can give it to Warp's agent
+   by having the agent read those files at the start of a session, or by keeping the
+   assembled `AGENTS.md` in the directory you work from. See
+   [Shared Context & Settings](../shared_context/index.md).
+4. **Keep the guardrails on.** Warp's built-in Agent Profile denylist already requires
+   approval for `rm`, `curl`, `wget`, and `eval`; RCAC's recommended profile is on the
+   [settings page](../shared_context/settings.md).
+
+!!! warning "Run-until-completion bypasses the denylist"
+
+    Warp's *Run-until-completion* mode **ignores the denylist entirely** — a real hazard
+    on a cluster session. Avoid it on shared systems, and review commands before they
+    run.
+
+## Prior art: external tools over SSH
+
+Reaching into the cluster from a locally-run tool is a well-worn path at RCAC. The
+[VS Code on RCAC](../../lifesciences/guides/vscode.md) guide documents the same shape
+for a different tool — Remote-SSH and ProxyJump from a local editor into a login or
+compute node — and is a useful companion for setting up your SSH config cleanly before
+you point an agent at it.
+
+---
+
+Back to [Running Agents](index.md).
diff --git a/docs/agentic-ai/running_agents/on_cluster.md b/docs/agentic-ai/running_agents/on_cluster.md
new file mode 100644
index 00000000..4abddc75
--- /dev/null
+++ b/docs/agentic-ai/running_agents/on_cluster.md
@@ -0,0 +1,118 @@
+---
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# On the Cluster (Login Nodes)
+
+In this mode you SSH into a cluster login node and run a command-line harness right
+there. The four CLI harnesses — **Claude Code**, **Codex**, **Gemini CLI**, and
+**opencode** — install and run headlessly on Linux, so they work over SSH. **Warp**
+does not run here; it is a desktop application (see [Warp](#warp) below).
+
+## The login-node rule applies to your agent
+
+A login (front-end) node is a shared, multi-tenant machine meant for editing,
+compiling, submitting jobs, and light pre- and post-processing — not for running
+computation. Launching a harness there is fine: the agent process itself is
+lightweight (mostly network calls). But **anything heavy the agent then wants to do
+must go through Slurm**, exactly as if you were doing it by hand.
+
+!!! important
+
+    Do NOT run large, long, multi-threaded, parallel, or CPU-intensive jobs on a
+    front-end login host. All users share the front-end hosts, and running anything
+    but the smallest test job will negatively impact everyone's ability to use
+    the cluster. Always use SLURM to submit your work as a job.
+
+In practice: instruct your agent to compile modestly, test on tiny inputs, and submit
+real runs with `sbatch` or `sinteractive` — with a correct account (`-A`, discovered
+via `slist`), partition (`-p`), QOS (`-q`), and an explicit `--time` limit. The shared
+[context files](../shared_context/context_files.md) RCAC publishes already tell an agent
+this, and the [per-harness settings](../shared_context/settings.md) deny the most
+dangerous operations, but the responsibility is ultimately yours.
+
+## Where agents may write
+
+Point an agent's working files at your **scratch** space, not your home directory.
+Scratch is the large, high-performance filesystem intended for job I/O; find it with
+`findscratch` or the `$RCAC_SCRATCH` environment variable. Keep in mind scratch is
+**not backed up and is purged after a period of inactivity** (the window varies by
+cluster), so move anything you want to keep to durable storage.
+
+!!! warning "Sandboxes are weak on shared nodes — don't rely on them"
+
+    The harnesses ship OS-level sandboxes (Codex uses `bubblewrap`, Gemini uses
+    Docker/Podman, Claude Code uses Linux namespaces). These are frequently
+    **unavailable or disabled on shared login nodes**, so do not count on them.
+    Containers are not a safety net either: RCAC uses **Apptainer** (not Docker), and
+    its configuration **auto bind-mounts `/home`, `/depot`, and `/scratch`** into the
+    container — those mounts stay writable, so an agent in a container can still edit
+    your real files. Treat the harness's **permission/approval rules as your primary
+    control**: keep destructive operations (`rm -rf`, `sudo`) denied and set writable
+    roots to `$RCAC_SCRATCH`.
+
+## Install and run each harness
+
+Each CLI installs into your user space (home directory) — no elevated privileges
+needed. Run these on a cluster login node after you SSH in.
+
+=== "Claude Code"
+
+    ```bash
+    # native installer (or: npm install -g @anthropic-ai/claude-code)
+    curl -fsSL https://claude.ai/install.sh | bash
+
+    claude                 # interactive
+    claude -p "…"          # headless / non-interactive
+    ```
+
+=== "Codex"
+
+    ```bash
+    # shell installer (or: npm install -g @openai/codex)
+    curl -fsSL https://chatgpt.com/codex/install.sh | sh
+
+    codex                  # interactive
+    codex exec "…"         # headless / non-interactive
+    ```
+
+=== "Gemini CLI"
+
+    ```bash
+    npm install -g @google/gemini-cli
+
+    gemini                 # interactive
+    gemini -p "…"          # headless (avoid --yolo on shared nodes)
+    ```
+
+=== "opencode"
+
+    ```bash
+    # install script (or: npm install -g opencode-ai)
+    curl -fsSL https://opencode.ai/install | bash
+
+    opencode               # interactive TUI
+    opencode run "…"       # non-interactive
+    ```
+
+To connect these harnesses to the RCAC [MCP servers](../mcp_servers.md) and wire in the
+shared context and permission policy, see
+[Shared Context & Settings](../shared_context/index.md).
+
+## Warp
+
+Warp is **RCAC's recommended harness for most users** — but it is a **desktop
+application**, not a headless CLI, and **cannot be installed on a login node**. There
+is no login-node path for Warp, and you should not try to fabricate one.
+
+Instead, run Warp on your own workstation and SSH into the cluster from there; its Agent
+Mode then rides your live SSH session — reading output and issuing commands in the
+session you opened — while the app stays local. That is the recommended setup for Warp;
+see [Local, Targeting the Cluster](local.md).
+
+---
+
+Back to [Running Agents](index.md).
diff --git a/docs/agentic-ai/shared_context/context_files.md b/docs/agentic-ai/shared_context/context_files.md
new file mode 100644
index 00000000..da95f752
--- /dev/null
+++ b/docs/agentic-ai/shared_context/context_files.md
@@ -0,0 +1,69 @@
+---
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# Context Files (`/etc/agents.d`)
+
+Every RCAC cluster ships a small set of **shared-context files** under `/etc/agents.d/` —
+plain Markdown deployed to the cluster and injected into agents by `rcac-mcp`. Each is
+written for the agent, in the shape *fact → correct command/path → "do not…" →
+rationale*. They are **generated per cluster** from a single data model, so the
+partitions, GPUs, filesystems, and toolchain are correct for the machine the agent is
+on.
+
+The files below are **Gautschi's**, shown as the worked example. Each cluster publishes
+its own set under *Using AI Agents* in its user guide — for example
+[Negishi](../../userguides/negishi/using_ai_agents.md) and
+[Gilbreth](../../userguides/gilbreth/using_ai_agents.md).
+
+Volatile numbers (quotas, balances) are deliberately **not hardcoded**: the files tell
+the agent to run `myquota` and `slist` and read the real values instead.
+
+## `unix.md`
+
+```markdown title="/etc/agents.d/unix.md"
+--8<-- "docs/snippets/agentic-ai/gautschi/agents.d/unix.md"
+```
+
+## `filesystems.md`
+
+```markdown title="/etc/agents.d/filesystems.md"
+--8<-- "docs/snippets/agentic-ai/gautschi/agents.d/filesystems.md"
+```
+
+## `lmod.md`
+
+```markdown title="/etc/agents.d/lmod.md"
+--8<-- "docs/snippets/agentic-ai/gautschi/agents.d/lmod.md"
+```
+
+## `slurm.md`
+
+```markdown title="/etc/agents.d/slurm.md"
+--8<-- "docs/snippets/agentic-ai/gautschi/agents.d/slurm.md"
+```
+
+## `policies.md`
+
+```markdown title="/etc/agents.d/policies.md"
+--8<-- "docs/snippets/agentic-ai/gautschi/agents.d/policies.md"
+```
+
+## The assembled `AGENTS.md`
+
+On the cluster, the files above are concatenated into a single `AGENTS.md` and
+symlinked to each harness's context filename. This is the exact assembled file an
+on-cluster agent reads:
+
+??? note "Show the concatenated `AGENTS.md`"
+
+    ```markdown title="AGENTS.md (assembled)"
+    --8<-- "docs/snippets/agentic-ai/gautschi/agents.d/AGENTS.md"
+    ```
+
+---
+
+Back to [Shared Context & Settings](index.md).
diff --git a/docs/agentic-ai/shared_context/index.md b/docs/agentic-ai/shared_context/index.md
new file mode 100644
index 00000000..006480a1
--- /dev/null
+++ b/docs/agentic-ai/shared_context/index.md
@@ -0,0 +1,80 @@
+---
+title: Shared Context & Settings
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# Shared Context & Settings
+
+To make agents reliable on our systems, RCAC gives them two things up front: **shared
+context** that describes the cluster, and **per-harness settings** that encode a
+sensible permission policy. This section publishes both, verbatim, as the canonical
+source of truth — so you can see exactly what your agent is told and how it is
+constrained, and so you can help improve it.
+
+## What `/etc/agents.d` is
+
+`/etc/agents.d/` is a directory of Markdown files on each cluster that describe that cluster
+*to an agent*: the operating environment, the filesystems, the module system, the
+scheduler, and the policies. Agentic tools already look for context files in
+well-known locations; `/etc/agents.d` is how RCAC supplies cluster-specific facts and
+prohibitions so the agent "absorbs the cluster's rules before you ask your first
+question."
+
+Each file follows the same shape: **a fact → the correct command or path → an explicit
+"do not…" → the rationale.** They are written to the agent, not to you.
+
+## Canonical source of truth
+
+The files published here are the **single source of truth**. They reach a running agent
+two ways, depending on how you work:
+
+- **On the cluster.** Cluster configuration management (Puppet) copies these files out
+  to `/etc/agents.d/` on the cluster's hosts, where they are concatenated into a single
+  `AGENTS.md` and symlinked to the other well-known context filenames (`CLAUDE.md`,
+  `GEMINI.md`, …) that each harness reads.
+- **Locally.** The `rcac-mcp` server reads `/etc/agents.d/` over your SSH connection
+  and injects the concatenated context to your agent as a read-only resource — so a
+  locally-run agent gets the same guidance without you installing anything.
+
+Because this repository is canonical, editing the files here is how the deployed
+context changes.
+
+## How to contribute feedback
+
+This is early, evolving work, and the context and settings improve fastest with input
+from the people using them. If a fact is wrong, a prohibition is missing, or a setting
+is too strict or too loose:
+
+- Open an issue or pull request on the
+  [RCAC-Docs repository](https://github.com/PurdueRCAC/RCAC-Docs).
+- Email [rcac-help@purdue.edu](mailto:rcac-help@purdue.edu).
+- Reach the team on [Discord](https://discord.gg/RmtKZmaQW9).
+
+<div class="grid cards" markdown>
+
+-   :material-file-document-multiple:{ .lg .middle } __Context Files (`/etc/agents.d`)__
+
+    ---
+
+    The five context files — `unix`, `filesystems`, `lmod`, `slurm`, and
+    `policies` — published verbatim (Gautschi shown as the example).
+
+    [:octicons-arrow-right-24: Context Files](context_files.md)
+
+-   :material-cog:{ .lg .middle } __Harness Settings & Permissions__
+
+    ---
+
+    A starting-point settings file for each of the five harnesses: allow-list the
+    sanity commands, deny destructive operations.
+
+    [:octicons-arrow-right-24: Harness Settings & Permissions](settings.md)
+
+</div>
+
+---
+
+Back to [Agentic AI](../index.md).
diff --git a/docs/agentic-ai/shared_context/settings.md b/docs/agentic-ai/shared_context/settings.md
new file mode 100644
index 00000000..e52e6f1d
--- /dev/null
+++ b/docs/agentic-ai/shared_context/settings.md
@@ -0,0 +1,150 @@
+---
+tags:
+  - Agentic AI
+authors:
+  - glentner
+---
+
+# Harness Settings & Permissions
+
+Alongside the shared [context files](context_files.md), RCAC configures a
+starting-point permission policy for each of the five harnesses. **These are the
+cluster-side settings** — what RCAC applies for an agent running **on the cluster
+nodes**. Wherever a harness supports it, RCAC deploys them to the system-managed
+location and **enforces** them; they are already in effect, and you do not install them
+yourself. We publish them here for **transparency**: so you can see exactly what your
+agent is and is not allowed to do.
+
+These files are **generated per cluster** and differ only in the cluster-specific
+scratch path; the examples below are **Gautschi's**. See each cluster's *Using AI
+Agents* chapter (for example [Negishi](../../userguides/negishi/using_ai_agents.md) or
+[Gilbreth](../../userguides/gilbreth/using_ai_agents.md)) for its own.
+
+Every policy does two things: it **allow-lists the read-only sanity commands**
+(`myquota`, `slist`, `sfeatures`, `module list`, `module avail`) so the agent runs them
+eagerly without stopping to ask, and it **denies the most dangerous operations**
+(`rm -rf`, `sudo`).
+
+!!! info "Cluster-side vs. local-side — which MCP server goes where"
+
+    These settings are for an agent running **on the cluster**, so they do **not**
+    register the `rcac-mcp` server. `rcac-mcp` is a **local-side** tool: it bridges an
+    agent running on *your own machine* to the cluster over SSH, and it launches via
+    `uvx`, which is not on the nodes' default `PATH`. An agent already on the cluster
+    has direct shell and Slurm access and does not need that bridge. If you instead run
+    a CLI harness on your laptop, register `rcac-mcp` as shown on the
+    [Local page](../running_agents/local.md).
+
+    What the cluster-side settings *do* wire in is the **documentation MCP server** —
+    the hosted, no-authentication endpoint `https://docs.rcac.purdue.edu/mcp`
+    (`doc_search` / `doc_load`), reached over plain HTTP with **no local tooling**. That
+    lets an on-cluster agent consult the authoritative docs on top of the
+    `/etc/agents.d` context it already has.
+
+!!! note "A v0 starting point — please push back"
+
+    This is a **deliberate first draft**, not a finished policy. Permissions do not
+    port across harnesses — each format is different — so these are parallel
+    translations of one intent. If a rule is too strict, too loose, or wrong for your
+    work, tell us (see [how to contribute](index.md)).
+
+!!! warning "Where enforcement lives — and where it can't"
+
+    Cluster-wide enforcement requires a system-managed configuration path. **Claude
+    Code, Gemini CLI, and opencode have one**, so RCAC deploys the policy there and a
+    user cannot override it. **Codex has no system-managed path**, so its settings are a
+    recommended default you adopt yourself. **Warp has no settings file at all** — its
+    policy is a team-managed Agent Profile (below). Note also that the harnesses'
+    OS-level sandboxes are frequently **unavailable on shared login nodes**, so the
+    permission/approval rules — not the sandbox — are the real control, with writable
+    roots pointed at `$RCAC_SCRATCH`.
+
+## Claude Code
+
+RCAC deploys this to the managed **`/etc/claude-code/managed-settings.json`**, where it
+is enforced: Claude Code evaluates `permissions` in the order **deny → ask → allow**,
+and a deny at the managed scope cannot be overridden. The shared context is bridged by
+importing `@AGENTS.md` from a managed `CLAUDE.md` (Claude Code does not read `AGENTS.md`
+natively).
+
+```json title="/etc/claude-code/managed-settings.json"
+--8<-- "docs/snippets/agentic-ai/gautschi/claude/settings.json"
+```
+
+Claude Code keeps MCP servers in `.mcp.json` rather than `settings.json`. The cluster-
+side docs server is the hosted HTTP endpoint — no local command needed:
+
+```json title=".mcp.json (documentation server)"
+{
+  "mcpServers": {
+    "rcac-docs": { "type": "http", "url": "https://docs.rcac.purdue.edu/mcp" }
+  }
+}
+```
+
+(To run a harness *locally* and reach the cluster, register `rcac-mcp` instead — see
+the [Local page](../running_agents/local.md).)
+
+## Codex
+
+Codex has **no system-managed configuration path**, so RCAC cannot enforce this
+centrally the way it can for Claude Code and Gemini. Instead this is the **recommended
+user config** — adopt it as `~/.codex/config.toml`. Codex also has no per-command
+allow/deny list; its safety comes from the `approval_policy` and `sandbox_mode`. On
+nodes without `bubblewrap`, the OS sandbox will not engage — fall back to
+`approval_policy = "untrusted"` and `sandbox_mode = "read-only"`. Codex reads
+`AGENTS.md` natively for the shared context, and the only MCP server is the hosted docs
+endpoint over HTTP.
+
+```toml title="~/.codex/config.toml (recommended)"
+--8<-- "docs/snippets/agentic-ai/gautschi/codex/config.toml"
+```
+
+## Gemini CLI
+
+RCAC deploys this to the system path **`/etc/gemini-cli/settings.json`**, which has the
+final say over user and project settings. Gemini controls the shell tool with
+prefix-matched allow (`tools.core`) and deny (`tools.exclude`) lists; the exclude list
+wins, and chained commands are split so any disallowed part blocks the whole line.
+`context.fileName` is set to read `AGENTS.md`, and `mcpServers` registers the docs
+endpoint over HTTP (`httpUrl`).
+
+```json title="/etc/gemini-cli/settings.json"
+--8<-- "docs/snippets/agentic-ai/gautschi/gemini/settings.json"
+```
+
+## opencode
+
+RCAC deploys this to the system location **`/etc/opencode/`**. opencode matches bash
+patterns with **last-match-wins**, so the catch-all `"*": "ask"` must come **first**,
+followed by the specific allow and deny rules. opencode reads `AGENTS.md` natively, and
+its `mcp` block registers the docs endpoint as a remote HTTP server.
+
+```json title="/etc/opencode/opencode.json"
+--8<-- "docs/snippets/agentic-ai/gautschi/opencode/opencode.json"
+```
+
+## Warp
+
+Warp has **no server-side settings file** to deploy. Its permission policy is an
+**Agent Profile**, configured in the app and shareable as a team-managed profile; RCAC's
+recommended profile mirrors the same intent as the files above:
+
+- **Allow** (auto-run, no confirmation): `myquota`, `slist`, `sfeatures`, and
+  `module\s+(list|avail).*`.
+- **Deny** (always require approval): `rm\s+-rf.*` and `sudo.*`. Warp's built-in
+  denylist already covers `rm`, `curl`, `wget`, and `eval`; the denylist beats both the
+  allowlist and "Agent decides."
+
+Because you SSH into the cluster yourself in Warp (see the
+[Local page](../running_agents/local.md)), Warp does not use `rcac-mcp`. To give it the
+shared context, wire in the cluster's `/etc/agents.d` files once you are on the host.
+
+!!! warning "Run-until-completion bypasses the denylist"
+
+    Warp's *Run-until-completion* mode ignores the denylist entirely — avoid it on
+    shared cluster sessions.
+
+---
+
+Back to [Shared Context & Settings](index.md).
diff --git a/docs/assets/data/breadcrumbs.json b/docs/assets/data/breadcrumbs.json
index e44354c6..96554a30 100644
--- a/docs/assets/data/breadcrumbs.json
+++ b/docs/assets/data/breadcrumbs.json
@@ -209,6 +209,11 @@
     "Gautschi User Guide",
     "Compiling Source Code"
   ],
+  "/userguides/gautschi/using_ai_agents/": [
+    "Home",
+    "Gautschi User Guide",
+    "Using AI Agents"
+  ],
   "/userguides/gautschi/faqs/": [
     "Home",
     "Gautschi User Guide",
@@ -258,6 +263,11 @@
     "Gilbreth User Guide",
     "Compiling Source Code"
   ],
+  "/userguides/gilbreth/using_ai_agents/": [
+    "Home",
+    "Gilbreth User Guide",
+    "Using AI Agents"
+  ],
   "/userguides/gilbreth/faqs/": [
     "Home",
     "Gilbreth User Guide",
@@ -307,6 +317,11 @@
     "Negishi User Guide",
     "Compiling Source Code"
   ],
+  "/userguides/negishi/using_ai_agents/": [
+    "Home",
+    "Negishi User Guide",
+    "Using AI Agents"
+  ],
   "/userguides/negishi/faqs/": [
     "Home",
     "Negishi User Guide",
@@ -1178,6 +1193,59 @@
     "Life Sciences",
     "Juicer"
   ],
+  "/agentic-ai/": [
+    "Home",
+    "Agentic AI"
+  ],
+  "/agentic-ai/acceptable_use/": [
+    "Home",
+    "Agentic AI",
+    "Acceptable Use & Etiquette"
+  ],
+  "/agentic-ai/best_practices/": [
+    "Home",
+    "Agentic AI",
+    "Best Practices & Limitations"
+  ],
+  "/agentic-ai/mcp_servers/": [
+    "Home",
+    "Agentic AI",
+    "MCP Servers"
+  ],
+  "/agentic-ai/running_agents/": [
+    "Home",
+    "Agentic AI",
+    "Running Agents"
+  ],
+  "/agentic-ai/running_agents/on_cluster/": [
+    "Home",
+    "Agentic AI",
+    "Running Agents",
+    "On the Cluster (Login Nodes)"
+  ],
+  "/agentic-ai/running_agents/local/": [
+    "Home",
+    "Agentic AI",
+    "Running Agents",
+    "Local (over SSH)"
+  ],
+  "/agentic-ai/shared_context/": [
+    "Home",
+    "Agentic AI",
+    "Shared Context & Settings"
+  ],
+  "/agentic-ai/shared_context/context_files/": [
+    "Home",
+    "Agentic AI",
+    "Shared Context & Settings",
+    "Context Files (/etc/agents.d)"
+  ],
+  "/agentic-ai/shared_context/settings/": [
+    "Home",
+    "Agentic AI",
+    "Shared Context & Settings",
+    "Harness Settings & Permissions"
+  ],
   "/contact/": [
     "Home",
     "Contact us"
diff --git a/docs/snippets/agentic-ai/GENERATED.md b/docs/snippets/agentic-ai/GENERATED.md
new file mode 100644
index 00000000..b4b3f4b6
--- /dev/null
+++ b/docs/snippets/agentic-ai/GENERATED.md
@@ -0,0 +1,25 @@
+<!-- This directory is generated. Do not hand-edit. -->
+# Generated: agentic-AI per-cluster context
+
+Everything under `docs/snippets/agentic-ai/<cluster>/` is **generated** by
+`tools/generate_agent_context.py` from the per-cluster data model in
+`tools/agent_context/clusters/<cluster>.yml` and the shared templates in
+`tools/agent_context/templates/`.
+
+**Do not edit the generated files** — the `agents.d/*.md`, the assembled `AGENTS.md`, and
+the `claude/`, `codex/`, `gemini/`, `opencode/` settings — directly; your changes will be
+overwritten on the next run. Edit the cluster YAML (facts) or a template (shared prose)
+and regenerate:
+
+```bash
+.venv/bin/python tools/generate_agent_context.py
+```
+
+The Markdown and TOML files each carry an inline `<!-- ... -->` / `# ...` marker naming
+the generator. JSON has no comment syntax, so this file is the marker for the `*.json`
+settings.
+
+To add a cluster: create `tools/agent_context/clusters/<cluster>.yml`, regenerate, add a
+`using_ai_agents.md` chapter under `docs/userguides/<cluster>/`, and wire it into
+`mkdocs.yml` `nav:`. Encode only facts the cluster's own user guide confirms; leave
+uncertain values `null` (the templates emit a "verify live" note) rather than guessing.
diff --git a/docs/snippets/agentic-ai/gautschi/agents.d/AGENTS.md b/docs/snippets/agentic-ai/gautschi/agents.d/AGENTS.md
new file mode 100644
index 00000000..b1faff2a
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/agents.d/AGENTS.md
@@ -0,0 +1,234 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gautschi.yml. Manual changes will be lost! -->
+# Gautschi Agent Context
+
+This file is the assembled agent context for Purdue RCAC's **Gautschi**
+cluster, concatenated from the topic files in `/etc/agents.d/`. It is the
+canonical guidance an agent should follow when operating on Gautschi. Read it
+before acting.
+
+<!-- Source: unix.md -->
+
+# Unix Environment (Gautschi)
+
+Gautschi runs **Rocky Linux 9** with a standard GNU/bash userland. You are acting as a
+specific user, over that user's existing SSH access — you have exactly their
+privileges and nothing more.
+
+## The login (front-end) nodes are shared
+
+Connecting to `gautschi.rcac.purdue.edu` places you on one of several shared front-end
+nodes, used simultaneously by many people. They are for **editing, compiling,
+submitting jobs, and light pre- and post-processing only**.
+
+- **Do NOT run large, long, multi-threaded, parallel, or CPU-intensive work on a
+  login node.** Submit it to Slurm instead (see `slurm.md`). Heavy work on a front end
+  degrades the system for everyone and may be killed by administrators.
+- **Do NOT start unbounded background processes or retry loops.** Clean up stray
+  processes, and watch for your own retry storms.
+
+## No elevated privileges
+
+- **Do NOT use `sudo` or attempt to gain root.** You cannot install system packages.
+- Install software into user space, or preferably use the environment modules system
+  (see `lmod.md`).
+
+## Ground yourself before acting
+
+Prefer checking the real state of the system over assuming it. These commands are
+read-only, cheap, and safe — run them eagerly before you plan or act:
+
+- `myquota` — home and scratch usage and limits.
+- `slist` — the accounts you can charge and their balances.
+- `sfeatures` — node and GPU hardware features.
+- `module avail` / `module list` — available and currently-loaded software.
+
+Grounding your plan in real output prevents the most common failure mode: confidently
+acting on an assumption that is wrong for this cluster.
+
+<!-- Source: filesystems.md -->
+
+# Filesystems (Gautschi)
+
+Gautschi mounts several filesystems, each with a different purpose, technology, and
+durability. Put data in the right place, and never assume a path is durable without
+checking.
+
+## Home — `/home/$USER` (`$HOME`)
+
+- **Technology:** ZFS, with automatic snapshots (recoverable).
+- **Use for:** source code, scripts, configuration, small files. It is
+  medium-performance and space-limited.
+- **Do NOT** stage large datasets or run heavy parallel job I/O here.
+
+## Scratch — `/scratch/gautschi/$USER` (`$RCAC_SCRATCH`)
+
+- **Technology:** Lustre, a high-performance parallel filesystem.
+- **Use for:** active job input/output and large working data. Point writable working
+  files here (`$RCAC_SCRATCH`), not at home. Find the path with `findscratch`.
+- **Not backed up, and purged after 60 days of inactivity** (by last access and
+  content-modification time; touching metadata does not protect a file). Use
+  `purgelist` to see files scheduled for purge.
+- **Do NOT** treat scratch as durable storage — move anything you want to keep to Data
+  Depot or Fortress.
+
+## Node-local — `/tmp`
+
+- Ephemeral, per-node storage that exists only while your job runs on that node; not
+  backed up, not recoverable.
+
+## Long-term — Data Depot and Fortress
+
+- **Data Depot** is group project space on **GPFS** (typically under `/depot`), for
+  active research data you need to keep.
+- **Fortress** is the HPSS archive for long-term/cold storage; move data with `hsi`
+  and `htar`.
+
+## Check before you write
+
+- Run **`myquota`** to read home and scratch usage and limits before writing large
+  amounts of data. **Do NOT assume specific quota numbers** — they differ per user and
+  change over time; read them from `myquota`.
+- Reference paths with environment variables (`$HOME`, `$RCAC_SCRATCH`), not
+  hard-coded strings, since paths can change.
+
+## Prohibitions
+
+- **Do NOT** store secrets, credentials, or sensitive/regulated data in world-readable
+  paths.
+- **Do NOT** perform bulk or recursive deletes (`rm -rf`) without confirming with the
+  user first.
+
+<!-- Source: lmod.md -->
+
+# Software Modules — Lmod (Gautschi)
+
+Software on Gautschi is provided through **environment modules** (Lmod), not the
+system package manager.
+
+## Finding and loading software
+
+- `module avail` — list available modules.
+- `module spider <name>` — search for a package and see its versions and
+  prerequisites.
+- `module load <name>/<version>` — load a specific version; `(D)` marks the default.
+- `module list` — show what is currently loaded; `module purge` clears everything.
+
+Load the same modules inside your job scripts that you used interactively, so batch
+jobs run in the environment you tested.
+
+## Recommended toolchain
+
+The recommended compiler and MPI stack is **GCC 14.1.0 with OpenMPI**. Check
+`module avail` for the exact versions available.
+
+## Prohibitions
+
+- **Do NOT** install software with `apt`, `yum`, `dnf`, or `sudo` — you do not have
+  root, and system package managers are not the mechanism here. Use modules, or install
+  into user space.
+- **Do NOT invent module names or versions.** Verify a package and version exist with
+  `module spider` (or `module avail`) before claiming it is available or writing it
+  into a job script.
+- For Python, prefer the `anaconda` modules and user environments rather than modifying
+  a base installation.
+
+<!-- Source: slurm.md -->
+
+# Slurm Scheduler (Gautschi)
+
+All real computation on Gautschi runs as **Slurm** jobs. Never run compute on a login
+node (see `unix.md`) — submit it here.
+
+## Every Gautschi job needs four things
+
+A job request must specify **resources**, an **account**, a **QOS**, and a
+**partition**. On Gautschi you MUST explicitly set **both the account
+(`-A`/`--account=`) and the partition (`-p`/`--partition=`)**; also set the QOS
+(`-q`/`--qos=`) and always a time limit (`--time`).
+
+- Discover the accounts you can charge (and their balances) with **`slist`** — do not
+  guess an account name.
+- Set a realistic `--time`; memory is allocated in proportion to the cores you request.
+
+## Partitions
+
+| Partition | For | Notes |
+|-----------|-----|-------|
+| `cpu` | CPU jobs (192-core nodes) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `ai` | GPU jobs (8× H100 per node) | QOS `normal` or `preemptible`; up to 2 weeks |
+| `smallgpu` | Small GPU jobs (2× L40S per node) | up to 24 h |
+| `highmem` | Large-memory jobs (1.5 TB nodes) | up to 24 h; job must use more than 48 cores |
+| `profiling` | Hardware performance profiling | whole-node; up to 24 h |
+
+## QOS and charging
+
+- **`normal`** — the default; normal priority, charged against your account.
+- **`standby`** — access to idle resources at low priority, **not charged**, max 4
+  hours. Request it with **`-q standby`** (it is a QOS, **not** an account).
+- **`preemptible`** — `ai` partition only; cheaper GPU-hours, but jobs can be preempted
+  (killed) to make room for `normal` jobs — checkpoint your work.
+
+## Common commands
+
+`sbatch` (submit a batch script), `squeue -u $USER` (your jobs), `scontrol show job
+<id>` (job detail), `scontrol hold`/`release`, `scancel <id>` (cancel), `sinteractive`
+(interactive job), `srun` (launch tasks).
+
+## Prohibitions
+
+- **Do NOT** use `--partition=a10` — it is not a Gautschi partition. The valid GPU partitions are `ai` and `smallgpu`.
+- **Do NOT** write `-A standby` or `#SBATCH -A standby` — `standby` is a QOS
+  (`-q standby`), not an account.
+- **Do NOT** emit flags for other schedulers (PBS/Torque `#PBS`, LSF `#BSUB`) — this is
+  Slurm.
+- **Do NOT** invent partition or QOS names; the valid sets are listed above.
+- **Do NOT** submit jobs without a `--time` limit, and **do NOT** `scancel` jobs you do
+  not own or run bulk cancellations without confirming with the user.
+
+<!-- Source: policies.md -->
+
+# Policies and Safety (Gautschi)
+
+You are acting as a specific user on shared, audited research infrastructure.
+Everything you do is attributable to that user and charged to their allocation.
+
+## Acceptable use
+
+- Use of Gautschi is bound by Purdue IT's Acceptable Use Policy and RCAC's resource
+  policies. Stay within the user's approved allocations and project scope.
+
+## Data handling
+
+- **Do NOT** place sensitive, regulated, or export-controlled data on the cluster
+  without prior approval, and **do NOT** store any sensitive data in world-readable
+  locations.
+
+## Secrets and credentials
+
+- **Do NOT** read, print, or transmit private keys, API tokens, or passwords, and
+  **do NOT** write them into files, prompts, or your own context. Treat anything under
+  `~/.ssh` and any `.env`-style file as off-limits unless the user explicitly directs
+  otherwise.
+
+## Resource stewardship
+
+- No heavy compute on login nodes; submit through Slurm with time limits (see
+  `slurm.md`). Watch allocation balances with `slist` — a runaway resubmission loop can
+  exhaust an allocation quickly.
+
+## Destructive operations require confirmation
+
+- **Confirm with the user before any destructive or irreversible action:** `rm -rf`,
+  mass file moves, permission changes on shared paths, or bulk `scancel`.
+
+## Containers are not a sandbox here
+
+- Gautschi uses **Apptainer** (not Docker). RCAC's Apptainer configuration
+  **auto-mounts `/home`, `/depot`, and `/scratch`** into containers, and those mounts
+  are writable — running inside a container does **not** protect the user's real files
+  from being edited or deleted. Do not assume container isolation.
+
+## Getting help
+
+- Verify AI-generated commands before running them. Report incorrect or harmful AI
+  output to **rcac-help@purdue.edu**.
diff --git a/docs/snippets/agentic-ai/gautschi/agents.d/filesystems.md b/docs/snippets/agentic-ai/gautschi/agents.d/filesystems.md
new file mode 100644
index 00000000..49a3fbe6
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/agents.d/filesystems.md
@@ -0,0 +1,51 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gautschi.yml. Manual changes will be lost! -->
+# Filesystems (Gautschi)
+
+Gautschi mounts several filesystems, each with a different purpose, technology, and
+durability. Put data in the right place, and never assume a path is durable without
+checking.
+
+## Home — `/home/$USER` (`$HOME`)
+
+- **Technology:** ZFS, with automatic snapshots (recoverable).
+- **Use for:** source code, scripts, configuration, small files. It is
+  medium-performance and space-limited.
+- **Do NOT** stage large datasets or run heavy parallel job I/O here.
+
+## Scratch — `/scratch/gautschi/$USER` (`$RCAC_SCRATCH`)
+
+- **Technology:** Lustre, a high-performance parallel filesystem.
+- **Use for:** active job input/output and large working data. Point writable working
+  files here (`$RCAC_SCRATCH`), not at home. Find the path with `findscratch`.
+- **Not backed up, and purged after 60 days of inactivity** (by last access and
+  content-modification time; touching metadata does not protect a file). Use
+  `purgelist` to see files scheduled for purge.
+- **Do NOT** treat scratch as durable storage — move anything you want to keep to Data
+  Depot or Fortress.
+
+## Node-local — `/tmp`
+
+- Ephemeral, per-node storage that exists only while your job runs on that node; not
+  backed up, not recoverable.
+
+## Long-term — Data Depot and Fortress
+
+- **Data Depot** is group project space on **GPFS** (typically under `/depot`), for
+  active research data you need to keep.
+- **Fortress** is the HPSS archive for long-term/cold storage; move data with `hsi`
+  and `htar`.
+
+## Check before you write
+
+- Run **`myquota`** to read home and scratch usage and limits before writing large
+  amounts of data. **Do NOT assume specific quota numbers** — they differ per user and
+  change over time; read them from `myquota`.
+- Reference paths with environment variables (`$HOME`, `$RCAC_SCRATCH`), not
+  hard-coded strings, since paths can change.
+
+## Prohibitions
+
+- **Do NOT** store secrets, credentials, or sensitive/regulated data in world-readable
+  paths.
+- **Do NOT** perform bulk or recursive deletes (`rm -rf`) without confirming with the
+  user first.
diff --git a/docs/snippets/agentic-ai/gautschi/agents.d/lmod.md b/docs/snippets/agentic-ai/gautschi/agents.d/lmod.md
new file mode 100644
index 00000000..2f469281
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/agents.d/lmod.md
@@ -0,0 +1,32 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gautschi.yml. Manual changes will be lost! -->
+# Software Modules — Lmod (Gautschi)
+
+Software on Gautschi is provided through **environment modules** (Lmod), not the
+system package manager.
+
+## Finding and loading software
+
+- `module avail` — list available modules.
+- `module spider <name>` — search for a package and see its versions and
+  prerequisites.
+- `module load <name>/<version>` — load a specific version; `(D)` marks the default.
+- `module list` — show what is currently loaded; `module purge` clears everything.
+
+Load the same modules inside your job scripts that you used interactively, so batch
+jobs run in the environment you tested.
+
+## Recommended toolchain
+
+The recommended compiler and MPI stack is **GCC 14.1.0 with OpenMPI**. Check
+`module avail` for the exact versions available.
+
+## Prohibitions
+
+- **Do NOT** install software with `apt`, `yum`, `dnf`, or `sudo` — you do not have
+  root, and system package managers are not the mechanism here. Use modules, or install
+  into user space.
+- **Do NOT invent module names or versions.** Verify a package and version exist with
+  `module spider` (or `module avail`) before claiming it is available or writing it
+  into a job script.
+- For Python, prefer the `anaconda` modules and user environments rather than modifying
+  a base installation.
diff --git a/docs/snippets/agentic-ai/gautschi/agents.d/policies.md b/docs/snippets/agentic-ai/gautschi/agents.d/policies.md
new file mode 100644
index 00000000..9ee74545
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/agents.d/policies.md
@@ -0,0 +1,46 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gautschi.yml. Manual changes will be lost! -->
+# Policies and Safety (Gautschi)
+
+You are acting as a specific user on shared, audited research infrastructure.
+Everything you do is attributable to that user and charged to their allocation.
+
+## Acceptable use
+
+- Use of Gautschi is bound by Purdue IT's Acceptable Use Policy and RCAC's resource
+  policies. Stay within the user's approved allocations and project scope.
+
+## Data handling
+
+- **Do NOT** place sensitive, regulated, or export-controlled data on the cluster
+  without prior approval, and **do NOT** store any sensitive data in world-readable
+  locations.
+
+## Secrets and credentials
+
+- **Do NOT** read, print, or transmit private keys, API tokens, or passwords, and
+  **do NOT** write them into files, prompts, or your own context. Treat anything under
+  `~/.ssh` and any `.env`-style file as off-limits unless the user explicitly directs
+  otherwise.
+
+## Resource stewardship
+
+- No heavy compute on login nodes; submit through Slurm with time limits (see
+  `slurm.md`). Watch allocation balances with `slist` — a runaway resubmission loop can
+  exhaust an allocation quickly.
+
+## Destructive operations require confirmation
+
+- **Confirm with the user before any destructive or irreversible action:** `rm -rf`,
+  mass file moves, permission changes on shared paths, or bulk `scancel`.
+
+## Containers are not a sandbox here
+
+- Gautschi uses **Apptainer** (not Docker). RCAC's Apptainer configuration
+  **auto-mounts `/home`, `/depot`, and `/scratch`** into containers, and those mounts
+  are writable — running inside a container does **not** protect the user's real files
+  from being edited or deleted. Do not assume container isolation.
+
+## Getting help
+
+- Verify AI-generated commands before running them. Report incorrect or harmful AI
+  output to **rcac-help@purdue.edu**.
diff --git a/docs/snippets/agentic-ai/gautschi/agents.d/slurm.md b/docs/snippets/agentic-ai/gautschi/agents.d/slurm.md
new file mode 100644
index 00000000..4baf7a3b
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/agents.d/slurm.md
@@ -0,0 +1,51 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gautschi.yml. Manual changes will be lost! -->
+# Slurm Scheduler (Gautschi)
+
+All real computation on Gautschi runs as **Slurm** jobs. Never run compute on a login
+node (see `unix.md`) — submit it here.
+
+## Every Gautschi job needs four things
+
+A job request must specify **resources**, an **account**, a **QOS**, and a
+**partition**. On Gautschi you MUST explicitly set **both the account
+(`-A`/`--account=`) and the partition (`-p`/`--partition=`)**; also set the QOS
+(`-q`/`--qos=`) and always a time limit (`--time`).
+
+- Discover the accounts you can charge (and their balances) with **`slist`** — do not
+  guess an account name.
+- Set a realistic `--time`; memory is allocated in proportion to the cores you request.
+
+## Partitions
+
+| Partition | For | Notes |
+|-----------|-----|-------|
+| `cpu` | CPU jobs (192-core nodes) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `ai` | GPU jobs (8× H100 per node) | QOS `normal` or `preemptible`; up to 2 weeks |
+| `smallgpu` | Small GPU jobs (2× L40S per node) | up to 24 h |
+| `highmem` | Large-memory jobs (1.5 TB nodes) | up to 24 h; job must use more than 48 cores |
+| `profiling` | Hardware performance profiling | whole-node; up to 24 h |
+
+## QOS and charging
+
+- **`normal`** — the default; normal priority, charged against your account.
+- **`standby`** — access to idle resources at low priority, **not charged**, max 4
+  hours. Request it with **`-q standby`** (it is a QOS, **not** an account).
+- **`preemptible`** — `ai` partition only; cheaper GPU-hours, but jobs can be preempted
+  (killed) to make room for `normal` jobs — checkpoint your work.
+
+## Common commands
+
+`sbatch` (submit a batch script), `squeue -u $USER` (your jobs), `scontrol show job
+<id>` (job detail), `scontrol hold`/`release`, `scancel <id>` (cancel), `sinteractive`
+(interactive job), `srun` (launch tasks).
+
+## Prohibitions
+
+- **Do NOT** use `--partition=a10` — it is not a Gautschi partition. The valid GPU partitions are `ai` and `smallgpu`.
+- **Do NOT** write `-A standby` or `#SBATCH -A standby` — `standby` is a QOS
+  (`-q standby`), not an account.
+- **Do NOT** emit flags for other schedulers (PBS/Torque `#PBS`, LSF `#BSUB`) — this is
+  Slurm.
+- **Do NOT** invent partition or QOS names; the valid sets are listed above.
+- **Do NOT** submit jobs without a `--time` limit, and **do NOT** `scancel` jobs you do
+  not own or run bulk cancellations without confirming with the user.
diff --git a/docs/snippets/agentic-ai/gautschi/agents.d/unix.md b/docs/snippets/agentic-ai/gautschi/agents.d/unix.md
new file mode 100644
index 00000000..6a5f6ff8
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/agents.d/unix.md
@@ -0,0 +1,37 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gautschi.yml. Manual changes will be lost! -->
+# Unix Environment (Gautschi)
+
+Gautschi runs **Rocky Linux 9** with a standard GNU/bash userland. You are acting as a
+specific user, over that user's existing SSH access — you have exactly their
+privileges and nothing more.
+
+## The login (front-end) nodes are shared
+
+Connecting to `gautschi.rcac.purdue.edu` places you on one of several shared front-end
+nodes, used simultaneously by many people. They are for **editing, compiling,
+submitting jobs, and light pre- and post-processing only**.
+
+- **Do NOT run large, long, multi-threaded, parallel, or CPU-intensive work on a
+  login node.** Submit it to Slurm instead (see `slurm.md`). Heavy work on a front end
+  degrades the system for everyone and may be killed by administrators.
+- **Do NOT start unbounded background processes or retry loops.** Clean up stray
+  processes, and watch for your own retry storms.
+
+## No elevated privileges
+
+- **Do NOT use `sudo` or attempt to gain root.** You cannot install system packages.
+- Install software into user space, or preferably use the environment modules system
+  (see `lmod.md`).
+
+## Ground yourself before acting
+
+Prefer checking the real state of the system over assuming it. These commands are
+read-only, cheap, and safe — run them eagerly before you plan or act:
+
+- `myquota` — home and scratch usage and limits.
+- `slist` — the accounts you can charge and their balances.
+- `sfeatures` — node and GPU hardware features.
+- `module avail` / `module list` — available and currently-loaded software.
+
+Grounding your plan in real output prevents the most common failure mode: confidently
+acting on an assumption that is wrong for this cluster.
diff --git a/docs/snippets/agentic-ai/gautschi/claude/settings.json b/docs/snippets/agentic-ai/gautschi/claude/settings.json
new file mode 100644
index 00000000..d9653118
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/claude/settings.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Bash(myquota:*)",
+      "Bash(slist:*)",
+      "Bash(sfeatures:*)",
+      "Bash(module list:*)",
+      "Bash(module avail:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(sudo:*)",
+      "Read(./.env)",
+      "Read(~/.ssh/**)"
+    ],
+    "additionalDirectories": ["/scratch/gautschi"]
+  },
+  "disableBypassPermissionsMode": "disable"
+}
diff --git a/docs/snippets/agentic-ai/gautschi/codex/config.toml b/docs/snippets/agentic-ai/gautschi/codex/config.toml
new file mode 100644
index 00000000..dc598b52
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/codex/config.toml
@@ -0,0 +1,22 @@
+# Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gautschi.yml. Manual changes will be lost!
+# ~/.codex/config.toml — recommended cluster-side config for Codex on Gautschi.
+#
+# Codex has no per-command allow/deny list; safety comes from the approval policy and
+# the sandbox mode. On shared login nodes where bubblewrap is unavailable, prefer
+# approval_policy = "untrusted" and sandbox_mode = "read-only" so nothing runs without
+# an explicit approval. Codex reads AGENTS.md natively for the shared context.
+#
+# The only MCP server configured here is the hosted documentation server over plain
+# HTTP (no local tooling / no uvx). An agent running on the cluster already has direct
+# shell and Slurm access, so it does NOT need the rcac-mcp SSH bridge — that server is
+# for running an agent locally (see the Local page).
+
+approval_policy = "on-request"
+sandbox_mode    = "workspace-write"
+
+[sandbox_workspace_write]
+writable_roots = ["/scratch/gautschi"]
+network_access = false
+
+[mcp_servers.rcac_docs]
+url = "https://docs.rcac.purdue.edu/mcp"
diff --git a/docs/snippets/agentic-ai/gautschi/gemini/settings.json b/docs/snippets/agentic-ai/gautschi/gemini/settings.json
new file mode 100644
index 00000000..5c0559ac
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/gemini/settings.json
@@ -0,0 +1,25 @@
+{
+  "tools": {
+    "core": [
+      "run_shell_command(myquota)",
+      "run_shell_command(slist)",
+      "run_shell_command(sfeatures)",
+      "run_shell_command(module)"
+    ],
+    "exclude": [
+      "run_shell_command(rm)",
+      "run_shell_command(sudo)"
+    ]
+  },
+  "security": {
+    "disableYoloMode": true
+  },
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"]
+  },
+  "mcpServers": {
+    "rcac-docs": {
+      "httpUrl": "https://docs.rcac.purdue.edu/mcp"
+    }
+  }
+}
diff --git a/docs/snippets/agentic-ai/gautschi/opencode/opencode.json b/docs/snippets/agentic-ai/gautschi/opencode/opencode.json
new file mode 100644
index 00000000..3b0c6a15
--- /dev/null
+++ b/docs/snippets/agentic-ai/gautschi/opencode/opencode.json
@@ -0,0 +1,22 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "myquota": "allow",
+      "slist": "allow",
+      "sfeatures": "allow",
+      "module list": "allow",
+      "module avail *": "allow",
+      "rm -rf *": "deny",
+      "sudo *": "deny"
+    }
+  },
+  "mcp": {
+    "rcac-docs": {
+      "type": "remote",
+      "url": "https://docs.rcac.purdue.edu/mcp",
+      "enabled": true
+    }
+  }
+}
diff --git a/docs/snippets/agentic-ai/gilbreth/agents.d/AGENTS.md b/docs/snippets/agentic-ai/gilbreth/agents.d/AGENTS.md
new file mode 100644
index 00000000..72550e66
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/agents.d/AGENTS.md
@@ -0,0 +1,235 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gilbreth.yml. Manual changes will be lost! -->
+# Gilbreth Agent Context
+
+This file is the assembled agent context for Purdue RCAC's **Gilbreth**
+cluster, concatenated from the topic files in `/etc/agents.d/`. It is the
+canonical guidance an agent should follow when operating on Gilbreth. Read it
+before acting.
+
+<!-- Source: unix.md -->
+
+# Unix Environment (Gilbreth)
+
+Gilbreth runs **Rocky 9** with a standard GNU/bash userland. You are acting as a
+specific user, over that user's existing SSH access — you have exactly their
+privileges and nothing more.
+
+## The login (front-end) nodes are shared
+
+Connecting to `gilbreth.rcac.purdue.edu` places you on one of several shared front-end
+nodes, used simultaneously by many people. They are for **editing, compiling,
+submitting jobs, and light pre- and post-processing only**.
+
+- **Do NOT run large, long, multi-threaded, parallel, or CPU-intensive work on a
+  login node.** Submit it to Slurm instead (see `slurm.md`). Heavy work on a front end
+  degrades the system for everyone and may be killed by administrators.
+- **Do NOT start unbounded background processes or retry loops.** Clean up stray
+  processes, and watch for your own retry storms.
+
+## No elevated privileges
+
+- **Do NOT use `sudo` or attempt to gain root.** You cannot install system packages.
+- Install software into user space, or preferably use the environment modules system
+  (see `lmod.md`).
+
+## Ground yourself before acting
+
+Prefer checking the real state of the system over assuming it. These commands are
+read-only, cheap, and safe — run them eagerly before you plan or act:
+
+- `myquota` — home and scratch usage and limits.
+- `slist` — the accounts you can charge and their balances.
+- `sfeatures` — node and GPU hardware features.
+- `module avail` / `module list` — available and currently-loaded software.
+
+Grounding your plan in real output prevents the most common failure mode: confidently
+acting on an assumption that is wrong for this cluster.
+
+<!-- Source: filesystems.md -->
+
+# Filesystems (Gilbreth)
+
+Gilbreth mounts several filesystems, each with a different purpose, technology, and
+durability. Put data in the right place, and never assume a path is durable without
+checking.
+
+## Home — `/home/$USER` (`$HOME`)
+
+- **Technology:** GPFS, with nightly snapshots kept for 7 days, weekly for 4 weeks, and monthly for 3 months (recoverable).
+- **Use for:** source code, scripts, configuration, small files. It is
+  medium-performance and space-limited.
+- **Do NOT** stage large datasets or run heavy parallel job I/O here.
+
+## Scratch — `/scratch/gilbreth/$USER` (`$RCAC_SCRATCH`)
+
+- **Technology:** a high-performance, large-capacity parallel filesystem.
+- **Use for:** active job input/output and large working data. Point writable working
+  files here (`$RCAC_SCRATCH`), not at home. Find the path with `findscratch`.
+- **Not backed up, and purged after 60 days of inactivity** (by last access and
+  content-modification time; touching metadata does not protect a file). Use
+  `purgelist` to see files scheduled for purge.
+- **Do NOT** treat scratch as durable storage — move anything you want to keep to Data
+  Depot or Fortress.
+
+## Node-local — `/tmp`
+
+- Ephemeral, per-node storage that exists only while your job runs on that node; not
+  backed up, not recoverable.
+
+## Long-term — Data Depot and Fortress
+
+- **Data Depot** is group project space on **GPFS** (typically under `/depot`), for
+  active research data you need to keep.
+- **Fortress** is the HPSS archive for long-term/cold storage; move data with `hsi`
+  and `htar`.
+
+## Check before you write
+
+- Run **`myquota`** to read home and scratch usage and limits before writing large
+  amounts of data. **Do NOT assume specific quota numbers** — they differ per user and
+  change over time; read them from `myquota`.
+- Reference paths with environment variables (`$HOME`, `$RCAC_SCRATCH`), not
+  hard-coded strings, since paths can change.
+
+## Prohibitions
+
+- **Do NOT** store secrets, credentials, or sensitive/regulated data in world-readable
+  paths.
+- **Do NOT** perform bulk or recursive deletes (`rm -rf`) without confirming with the
+  user first.
+
+<!-- Source: lmod.md -->
+
+# Software Modules — Lmod (Gilbreth)
+
+Software on Gilbreth is provided through **environment modules** (Lmod), not the
+system package manager.
+
+## Finding and loading software
+
+- `module avail` — list available modules.
+- `module spider <name>` — search for a package and see its versions and
+  prerequisites.
+- `module load <name>/<version>` — load a specific version; `(D)` marks the default.
+- `module list` — show what is currently loaded; `module purge` clears everything.
+
+Load the same modules inside your job scripts that you used interactively, so batch
+jobs run in the environment you tested.
+
+## Recommended toolchain
+
+Do not assume a default compiler or MPI version. Check `module avail` (and, where
+provided, `module load rcac`) for the recommended stack, and verify with `module list`.
+
+## Prohibitions
+
+- **Do NOT** install software with `apt`, `yum`, `dnf`, or `sudo` — you do not have
+  root, and system package managers are not the mechanism here. Use modules, or install
+  into user space.
+- **Do NOT invent module names or versions.** Verify a package and version exist with
+  `module spider` (or `module avail`) before claiming it is available or writing it
+  into a job script.
+- For Python, prefer the `anaconda` modules and user environments rather than modifying
+  a base installation.
+
+<!-- Source: slurm.md -->
+
+# Slurm Scheduler (Gilbreth)
+
+All real computation on Gilbreth runs as **Slurm** jobs. Never run compute on a login
+node (see `unix.md`) — submit it here.
+
+## Every Gilbreth job needs four things
+
+A job request must specify **resources**, an **account**, a **QOS**, and a
+**partition**. On Gilbreth you MUST explicitly set **both the account
+(`-A`/`--account=`) and the partition (`-p`/`--partition=`)**; also set the QOS
+(`-q`/`--qos=`) and always a time limit (`--time`).
+
+- Discover the accounts you can charge (and their balances) with **`slist`** — do not
+  guess an account name.
+- Set a realistic `--time`; memory is allocated in proportion to the cores you request.
+
+## Partitions
+
+| Partition | For | Notes |
+|-----------|-----|-------|
+| `a10` | A10 GPU jobs (3× A10 24 GB per node) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `a30` | A30 GPU jobs (3× A30 24 GB per node) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `a100-40gb` | A100-40GB GPU jobs (2–4× A100 40 GB per node) | QOS `normal` or `standby`; up to 2 weeks; NVLink nodes need `--constraint=nvlink` |
+| `a100-80gb` | A100-80GB GPU jobs (2× A100 80 GB per node) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `training` | Shared multi-GPU training pool (4 GPUs/node; V100/A100/H100) | QOS `training` only; up to 24 h; for demonstrated >2-GPU workflows |
+
+## QOS and charging
+
+- **`normal`** — the default; normal priority, charged against your account.
+- **`standby`** — access to idle resources at low priority, **not charged**, max 4
+  hours. Request it with **`-q standby`** (it is a QOS, **not** an account).
+- **`training`** — required for the `training` partition (`-q training`); low priority,
+  **not charged**, max 24 hours.
+
+## Common commands
+
+`sbatch` (submit a batch script), `squeue -u $USER` (your jobs), `scontrol show job
+<id>` (job detail), `scontrol hold`/`release`, `scancel <id>` (cancel), `sinteractive`
+(interactive job), `srun` (launch tasks).
+
+## Prohibitions
+
+- **Do NOT** assume a `preemptible` QOS — Gilbreth has none; the low-priority QOS is `standby`, and the shared multi-GPU pool uses `-q training`.
+- **Do NOT** pick a GPU type with a `--gres` type string — on Gilbreth the GPU type is chosen by **partition** (`a10`/`a30`/`a100-40gb`/`a100-80gb`); request a count with `--gpus-per-node=N`.
+- **Do NOT** write `-A standby` or `#SBATCH -A standby` — `standby` is a QOS
+  (`-q standby`), not an account.
+- **Do NOT** emit flags for other schedulers (PBS/Torque `#PBS`, LSF `#BSUB`) — this is
+  Slurm.
+- **Do NOT** invent partition or QOS names; the valid sets are listed above.
+- **Do NOT** submit jobs without a `--time` limit, and **do NOT** `scancel` jobs you do
+  not own or run bulk cancellations without confirming with the user.
+
+<!-- Source: policies.md -->
+
+# Policies and Safety (Gilbreth)
+
+You are acting as a specific user on shared, audited research infrastructure.
+Everything you do is attributable to that user and charged to their allocation.
+
+## Acceptable use
+
+- Use of Gilbreth is bound by Purdue IT's Acceptable Use Policy and RCAC's resource
+  policies. Stay within the user's approved allocations and project scope.
+
+## Data handling
+
+- **Do NOT** place sensitive, regulated, or export-controlled data on the cluster
+  without prior approval, and **do NOT** store any sensitive data in world-readable
+  locations.
+
+## Secrets and credentials
+
+- **Do NOT** read, print, or transmit private keys, API tokens, or passwords, and
+  **do NOT** write them into files, prompts, or your own context. Treat anything under
+  `~/.ssh` and any `.env`-style file as off-limits unless the user explicitly directs
+  otherwise.
+
+## Resource stewardship
+
+- No heavy compute on login nodes; submit through Slurm with time limits (see
+  `slurm.md`). Watch allocation balances with `slist` — a runaway resubmission loop can
+  exhaust an allocation quickly.
+
+## Destructive operations require confirmation
+
+- **Confirm with the user before any destructive or irreversible action:** `rm -rf`,
+  mass file moves, permission changes on shared paths, or bulk `scancel`.
+
+## Containers are not a sandbox here
+
+- Gilbreth uses **Apptainer** (not Docker). RCAC's Apptainer configuration
+  **auto-mounts `/home`, `/depot`, and `/scratch`** into containers, and those mounts
+  are writable — running inside a container does **not** protect the user's real files
+  from being edited or deleted. Do not assume container isolation.
+
+## Getting help
+
+- Verify AI-generated commands before running them. Report incorrect or harmful AI
+  output to **rcac-help@purdue.edu**.
diff --git a/docs/snippets/agentic-ai/gilbreth/agents.d/filesystems.md b/docs/snippets/agentic-ai/gilbreth/agents.d/filesystems.md
new file mode 100644
index 00000000..6b25ddfc
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/agents.d/filesystems.md
@@ -0,0 +1,51 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gilbreth.yml. Manual changes will be lost! -->
+# Filesystems (Gilbreth)
+
+Gilbreth mounts several filesystems, each with a different purpose, technology, and
+durability. Put data in the right place, and never assume a path is durable without
+checking.
+
+## Home — `/home/$USER` (`$HOME`)
+
+- **Technology:** GPFS, with nightly snapshots kept for 7 days, weekly for 4 weeks, and monthly for 3 months (recoverable).
+- **Use for:** source code, scripts, configuration, small files. It is
+  medium-performance and space-limited.
+- **Do NOT** stage large datasets or run heavy parallel job I/O here.
+
+## Scratch — `/scratch/gilbreth/$USER` (`$RCAC_SCRATCH`)
+
+- **Technology:** a high-performance, large-capacity parallel filesystem.
+- **Use for:** active job input/output and large working data. Point writable working
+  files here (`$RCAC_SCRATCH`), not at home. Find the path with `findscratch`.
+- **Not backed up, and purged after 60 days of inactivity** (by last access and
+  content-modification time; touching metadata does not protect a file). Use
+  `purgelist` to see files scheduled for purge.
+- **Do NOT** treat scratch as durable storage — move anything you want to keep to Data
+  Depot or Fortress.
+
+## Node-local — `/tmp`
+
+- Ephemeral, per-node storage that exists only while your job runs on that node; not
+  backed up, not recoverable.
+
+## Long-term — Data Depot and Fortress
+
+- **Data Depot** is group project space on **GPFS** (typically under `/depot`), for
+  active research data you need to keep.
+- **Fortress** is the HPSS archive for long-term/cold storage; move data with `hsi`
+  and `htar`.
+
+## Check before you write
+
+- Run **`myquota`** to read home and scratch usage and limits before writing large
+  amounts of data. **Do NOT assume specific quota numbers** — they differ per user and
+  change over time; read them from `myquota`.
+- Reference paths with environment variables (`$HOME`, `$RCAC_SCRATCH`), not
+  hard-coded strings, since paths can change.
+
+## Prohibitions
+
+- **Do NOT** store secrets, credentials, or sensitive/regulated data in world-readable
+  paths.
+- **Do NOT** perform bulk or recursive deletes (`rm -rf`) without confirming with the
+  user first.
diff --git a/docs/snippets/agentic-ai/gilbreth/agents.d/lmod.md b/docs/snippets/agentic-ai/gilbreth/agents.d/lmod.md
new file mode 100644
index 00000000..cd3d7d7a
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/agents.d/lmod.md
@@ -0,0 +1,32 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gilbreth.yml. Manual changes will be lost! -->
+# Software Modules — Lmod (Gilbreth)
+
+Software on Gilbreth is provided through **environment modules** (Lmod), not the
+system package manager.
+
+## Finding and loading software
+
+- `module avail` — list available modules.
+- `module spider <name>` — search for a package and see its versions and
+  prerequisites.
+- `module load <name>/<version>` — load a specific version; `(D)` marks the default.
+- `module list` — show what is currently loaded; `module purge` clears everything.
+
+Load the same modules inside your job scripts that you used interactively, so batch
+jobs run in the environment you tested.
+
+## Recommended toolchain
+
+Do not assume a default compiler or MPI version. Check `module avail` (and, where
+provided, `module load rcac`) for the recommended stack, and verify with `module list`.
+
+## Prohibitions
+
+- **Do NOT** install software with `apt`, `yum`, `dnf`, or `sudo` — you do not have
+  root, and system package managers are not the mechanism here. Use modules, or install
+  into user space.
+- **Do NOT invent module names or versions.** Verify a package and version exist with
+  `module spider` (or `module avail`) before claiming it is available or writing it
+  into a job script.
+- For Python, prefer the `anaconda` modules and user environments rather than modifying
+  a base installation.
diff --git a/docs/snippets/agentic-ai/gilbreth/agents.d/policies.md b/docs/snippets/agentic-ai/gilbreth/agents.d/policies.md
new file mode 100644
index 00000000..1bc3e90b
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/agents.d/policies.md
@@ -0,0 +1,46 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gilbreth.yml. Manual changes will be lost! -->
+# Policies and Safety (Gilbreth)
+
+You are acting as a specific user on shared, audited research infrastructure.
+Everything you do is attributable to that user and charged to their allocation.
+
+## Acceptable use
+
+- Use of Gilbreth is bound by Purdue IT's Acceptable Use Policy and RCAC's resource
+  policies. Stay within the user's approved allocations and project scope.
+
+## Data handling
+
+- **Do NOT** place sensitive, regulated, or export-controlled data on the cluster
+  without prior approval, and **do NOT** store any sensitive data in world-readable
+  locations.
+
+## Secrets and credentials
+
+- **Do NOT** read, print, or transmit private keys, API tokens, or passwords, and
+  **do NOT** write them into files, prompts, or your own context. Treat anything under
+  `~/.ssh` and any `.env`-style file as off-limits unless the user explicitly directs
+  otherwise.
+
+## Resource stewardship
+
+- No heavy compute on login nodes; submit through Slurm with time limits (see
+  `slurm.md`). Watch allocation balances with `slist` — a runaway resubmission loop can
+  exhaust an allocation quickly.
+
+## Destructive operations require confirmation
+
+- **Confirm with the user before any destructive or irreversible action:** `rm -rf`,
+  mass file moves, permission changes on shared paths, or bulk `scancel`.
+
+## Containers are not a sandbox here
+
+- Gilbreth uses **Apptainer** (not Docker). RCAC's Apptainer configuration
+  **auto-mounts `/home`, `/depot`, and `/scratch`** into containers, and those mounts
+  are writable — running inside a container does **not** protect the user's real files
+  from being edited or deleted. Do not assume container isolation.
+
+## Getting help
+
+- Verify AI-generated commands before running them. Report incorrect or harmful AI
+  output to **rcac-help@purdue.edu**.
diff --git a/docs/snippets/agentic-ai/gilbreth/agents.d/slurm.md b/docs/snippets/agentic-ai/gilbreth/agents.d/slurm.md
new file mode 100644
index 00000000..181e89d7
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/agents.d/slurm.md
@@ -0,0 +1,52 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gilbreth.yml. Manual changes will be lost! -->
+# Slurm Scheduler (Gilbreth)
+
+All real computation on Gilbreth runs as **Slurm** jobs. Never run compute on a login
+node (see `unix.md`) — submit it here.
+
+## Every Gilbreth job needs four things
+
+A job request must specify **resources**, an **account**, a **QOS**, and a
+**partition**. On Gilbreth you MUST explicitly set **both the account
+(`-A`/`--account=`) and the partition (`-p`/`--partition=`)**; also set the QOS
+(`-q`/`--qos=`) and always a time limit (`--time`).
+
+- Discover the accounts you can charge (and their balances) with **`slist`** — do not
+  guess an account name.
+- Set a realistic `--time`; memory is allocated in proportion to the cores you request.
+
+## Partitions
+
+| Partition | For | Notes |
+|-----------|-----|-------|
+| `a10` | A10 GPU jobs (3× A10 24 GB per node) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `a30` | A30 GPU jobs (3× A30 24 GB per node) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `a100-40gb` | A100-40GB GPU jobs (2–4× A100 40 GB per node) | QOS `normal` or `standby`; up to 2 weeks; NVLink nodes need `--constraint=nvlink` |
+| `a100-80gb` | A100-80GB GPU jobs (2× A100 80 GB per node) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `training` | Shared multi-GPU training pool (4 GPUs/node; V100/A100/H100) | QOS `training` only; up to 24 h; for demonstrated >2-GPU workflows |
+
+## QOS and charging
+
+- **`normal`** — the default; normal priority, charged against your account.
+- **`standby`** — access to idle resources at low priority, **not charged**, max 4
+  hours. Request it with **`-q standby`** (it is a QOS, **not** an account).
+- **`training`** — required for the `training` partition (`-q training`); low priority,
+  **not charged**, max 24 hours.
+
+## Common commands
+
+`sbatch` (submit a batch script), `squeue -u $USER` (your jobs), `scontrol show job
+<id>` (job detail), `scontrol hold`/`release`, `scancel <id>` (cancel), `sinteractive`
+(interactive job), `srun` (launch tasks).
+
+## Prohibitions
+
+- **Do NOT** assume a `preemptible` QOS — Gilbreth has none; the low-priority QOS is `standby`, and the shared multi-GPU pool uses `-q training`.
+- **Do NOT** pick a GPU type with a `--gres` type string — on Gilbreth the GPU type is chosen by **partition** (`a10`/`a30`/`a100-40gb`/`a100-80gb`); request a count with `--gpus-per-node=N`.
+- **Do NOT** write `-A standby` or `#SBATCH -A standby` — `standby` is a QOS
+  (`-q standby`), not an account.
+- **Do NOT** emit flags for other schedulers (PBS/Torque `#PBS`, LSF `#BSUB`) — this is
+  Slurm.
+- **Do NOT** invent partition or QOS names; the valid sets are listed above.
+- **Do NOT** submit jobs without a `--time` limit, and **do NOT** `scancel` jobs you do
+  not own or run bulk cancellations without confirming with the user.
diff --git a/docs/snippets/agentic-ai/gilbreth/agents.d/unix.md b/docs/snippets/agentic-ai/gilbreth/agents.d/unix.md
new file mode 100644
index 00000000..c6cc8046
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/agents.d/unix.md
@@ -0,0 +1,37 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gilbreth.yml. Manual changes will be lost! -->
+# Unix Environment (Gilbreth)
+
+Gilbreth runs **Rocky 9** with a standard GNU/bash userland. You are acting as a
+specific user, over that user's existing SSH access — you have exactly their
+privileges and nothing more.
+
+## The login (front-end) nodes are shared
+
+Connecting to `gilbreth.rcac.purdue.edu` places you on one of several shared front-end
+nodes, used simultaneously by many people. They are for **editing, compiling,
+submitting jobs, and light pre- and post-processing only**.
+
+- **Do NOT run large, long, multi-threaded, parallel, or CPU-intensive work on a
+  login node.** Submit it to Slurm instead (see `slurm.md`). Heavy work on a front end
+  degrades the system for everyone and may be killed by administrators.
+- **Do NOT start unbounded background processes or retry loops.** Clean up stray
+  processes, and watch for your own retry storms.
+
+## No elevated privileges
+
+- **Do NOT use `sudo` or attempt to gain root.** You cannot install system packages.
+- Install software into user space, or preferably use the environment modules system
+  (see `lmod.md`).
+
+## Ground yourself before acting
+
+Prefer checking the real state of the system over assuming it. These commands are
+read-only, cheap, and safe — run them eagerly before you plan or act:
+
+- `myquota` — home and scratch usage and limits.
+- `slist` — the accounts you can charge and their balances.
+- `sfeatures` — node and GPU hardware features.
+- `module avail` / `module list` — available and currently-loaded software.
+
+Grounding your plan in real output prevents the most common failure mode: confidently
+acting on an assumption that is wrong for this cluster.
diff --git a/docs/snippets/agentic-ai/gilbreth/claude/settings.json b/docs/snippets/agentic-ai/gilbreth/claude/settings.json
new file mode 100644
index 00000000..aeb89f2f
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/claude/settings.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Bash(myquota:*)",
+      "Bash(slist:*)",
+      "Bash(sfeatures:*)",
+      "Bash(module list:*)",
+      "Bash(module avail:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(sudo:*)",
+      "Read(./.env)",
+      "Read(~/.ssh/**)"
+    ],
+    "additionalDirectories": ["/scratch/gilbreth"]
+  },
+  "disableBypassPermissionsMode": "disable"
+}
diff --git a/docs/snippets/agentic-ai/gilbreth/codex/config.toml b/docs/snippets/agentic-ai/gilbreth/codex/config.toml
new file mode 100644
index 00000000..436ebc28
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/codex/config.toml
@@ -0,0 +1,22 @@
+# Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gilbreth.yml. Manual changes will be lost!
+# ~/.codex/config.toml — recommended cluster-side config for Codex on Gilbreth.
+#
+# Codex has no per-command allow/deny list; safety comes from the approval policy and
+# the sandbox mode. On shared login nodes where bubblewrap is unavailable, prefer
+# approval_policy = "untrusted" and sandbox_mode = "read-only" so nothing runs without
+# an explicit approval. Codex reads AGENTS.md natively for the shared context.
+#
+# The only MCP server configured here is the hosted documentation server over plain
+# HTTP (no local tooling / no uvx). An agent running on the cluster already has direct
+# shell and Slurm access, so it does NOT need the rcac-mcp SSH bridge — that server is
+# for running an agent locally (see the Local page).
+
+approval_policy = "on-request"
+sandbox_mode    = "workspace-write"
+
+[sandbox_workspace_write]
+writable_roots = ["/scratch/gilbreth"]
+network_access = false
+
+[mcp_servers.rcac_docs]
+url = "https://docs.rcac.purdue.edu/mcp"
diff --git a/docs/snippets/agentic-ai/gilbreth/gemini/settings.json b/docs/snippets/agentic-ai/gilbreth/gemini/settings.json
new file mode 100644
index 00000000..5c0559ac
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/gemini/settings.json
@@ -0,0 +1,25 @@
+{
+  "tools": {
+    "core": [
+      "run_shell_command(myquota)",
+      "run_shell_command(slist)",
+      "run_shell_command(sfeatures)",
+      "run_shell_command(module)"
+    ],
+    "exclude": [
+      "run_shell_command(rm)",
+      "run_shell_command(sudo)"
+    ]
+  },
+  "security": {
+    "disableYoloMode": true
+  },
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"]
+  },
+  "mcpServers": {
+    "rcac-docs": {
+      "httpUrl": "https://docs.rcac.purdue.edu/mcp"
+    }
+  }
+}
diff --git a/docs/snippets/agentic-ai/gilbreth/opencode/opencode.json b/docs/snippets/agentic-ai/gilbreth/opencode/opencode.json
new file mode 100644
index 00000000..3b0c6a15
--- /dev/null
+++ b/docs/snippets/agentic-ai/gilbreth/opencode/opencode.json
@@ -0,0 +1,22 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "myquota": "allow",
+      "slist": "allow",
+      "sfeatures": "allow",
+      "module list": "allow",
+      "module avail *": "allow",
+      "rm -rf *": "deny",
+      "sudo *": "deny"
+    }
+  },
+  "mcp": {
+    "rcac-docs": {
+      "type": "remote",
+      "url": "https://docs.rcac.purdue.edu/mcp",
+      "enabled": true
+    }
+  }
+}
diff --git a/docs/snippets/agentic-ai/negishi/agents.d/AGENTS.md b/docs/snippets/agentic-ai/negishi/agents.d/AGENTS.md
new file mode 100644
index 00000000..c69f399a
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/agents.d/AGENTS.md
@@ -0,0 +1,231 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/negishi.yml. Manual changes will be lost! -->
+# Negishi Agent Context
+
+This file is the assembled agent context for Purdue RCAC's **Negishi**
+cluster, concatenated from the topic files in `/etc/agents.d/`. It is the
+canonical guidance an agent should follow when operating on Negishi. Read it
+before acting.
+
+<!-- Source: unix.md -->
+
+# Unix Environment (Negishi)
+
+Negishi runs **Rocky Linux 8** with a standard GNU/bash userland. You are acting as a
+specific user, over that user's existing SSH access — you have exactly their
+privileges and nothing more.
+
+## The login (front-end) nodes are shared
+
+Connecting to `negishi.rcac.purdue.edu` places you on one of several shared front-end
+nodes, used simultaneously by many people. They are for **editing, compiling,
+submitting jobs, and light pre- and post-processing only**.
+
+- **Do NOT run large, long, multi-threaded, parallel, or CPU-intensive work on a
+  login node.** Submit it to Slurm instead (see `slurm.md`). Heavy work on a front end
+  degrades the system for everyone and may be killed by administrators.
+- **Do NOT start unbounded background processes or retry loops.** Clean up stray
+  processes, and watch for your own retry storms.
+
+## No elevated privileges
+
+- **Do NOT use `sudo` or attempt to gain root.** You cannot install system packages.
+- Install software into user space, or preferably use the environment modules system
+  (see `lmod.md`).
+
+## Ground yourself before acting
+
+Prefer checking the real state of the system over assuming it. These commands are
+read-only, cheap, and safe — run them eagerly before you plan or act:
+
+- `myquota` — home and scratch usage and limits.
+- `slist` — the accounts you can charge and their balances.
+- `sfeatures` — node and GPU hardware features.
+- `module avail` / `module list` — available and currently-loaded software.
+
+Grounding your plan in real output prevents the most common failure mode: confidently
+acting on an assumption that is wrong for this cluster.
+
+<!-- Source: filesystems.md -->
+
+# Filesystems (Negishi)
+
+Negishi mounts several filesystems, each with a different purpose, technology, and
+durability. Put data in the right place, and never assume a path is durable without
+checking.
+
+## Home — `/home/$USER` (`$HOME`)
+
+- **Technology:** GPFS, with nightly snapshots kept for 7 days, weekly for 4 weeks, and monthly for 3 months (recoverable).
+- **Use for:** source code, scripts, configuration, small files. It is
+  medium-performance and space-limited.
+- **Do NOT** stage large datasets or run heavy parallel job I/O here.
+
+## Scratch — `/scratch/negishi/$USER` (`$RCAC_SCRATCH`)
+
+- **Technology:** a high-performance, large-capacity parallel filesystem.
+- **Use for:** active job input/output and large working data. Point writable working
+  files here (`$RCAC_SCRATCH`), not at home. Find the path with `findscratch`.
+- **Not backed up, and purged after 60 days of inactivity** (by last access and
+  content-modification time; touching metadata does not protect a file). Use
+  `purgelist` to see files scheduled for purge.
+- **Do NOT** treat scratch as durable storage — move anything you want to keep to Data
+  Depot or Fortress.
+
+## Node-local — `/tmp`
+
+- Ephemeral, per-node storage that exists only while your job runs on that node; not
+  backed up, not recoverable.
+
+## Long-term — Data Depot and Fortress
+
+- **Data Depot** is group project space on **GPFS** (typically under `/depot`), for
+  active research data you need to keep.
+- **Fortress** is the HPSS archive for long-term/cold storage; move data with `hsi`
+  and `htar`.
+
+## Check before you write
+
+- Run **`myquota`** to read home and scratch usage and limits before writing large
+  amounts of data. **Do NOT assume specific quota numbers** — they differ per user and
+  change over time; read them from `myquota`.
+- Reference paths with environment variables (`$HOME`, `$RCAC_SCRATCH`), not
+  hard-coded strings, since paths can change.
+
+## Prohibitions
+
+- **Do NOT** store secrets, credentials, or sensitive/regulated data in world-readable
+  paths.
+- **Do NOT** perform bulk or recursive deletes (`rm -rf`) without confirming with the
+  user first.
+
+<!-- Source: lmod.md -->
+
+# Software Modules — Lmod (Negishi)
+
+Software on Negishi is provided through **environment modules** (Lmod), not the
+system package manager.
+
+## Finding and loading software
+
+- `module avail` — list available modules.
+- `module spider <name>` — search for a package and see its versions and
+  prerequisites.
+- `module load <name>/<version>` — load a specific version; `(D)` marks the default.
+- `module list` — show what is currently loaded; `module purge` clears everything.
+
+Load the same modules inside your job scripts that you used interactively, so batch
+jobs run in the environment you tested.
+
+## Recommended toolchain
+
+The recommended compiler and MPI stack is **GCC 12.2.0 with OpenMPI**. Check
+`module avail` for the exact versions available.
+
+## Prohibitions
+
+- **Do NOT** install software with `apt`, `yum`, `dnf`, or `sudo` — you do not have
+  root, and system package managers are not the mechanism here. Use modules, or install
+  into user space.
+- **Do NOT invent module names or versions.** Verify a package and version exist with
+  `module spider` (or `module avail`) before claiming it is available or writing it
+  into a job script.
+- For Python, prefer the `anaconda` modules and user environments rather than modifying
+  a base installation.
+
+<!-- Source: slurm.md -->
+
+# Slurm Scheduler (Negishi)
+
+All real computation on Negishi runs as **Slurm** jobs. Never run compute on a login
+node (see `unix.md`) — submit it here.
+
+## Every Negishi job needs four things
+
+A job request must specify **resources**, an **account**, a **QOS**, and a
+**partition**. On Negishi you MUST explicitly set **both the account
+(`-A`/`--account=`) and the partition (`-p`/`--partition=`)**; also set the QOS
+(`-q`/`--qos=`) and always a time limit (`--time`).
+
+- Discover the accounts you can charge (and their balances) with **`slist`** — do not
+  guess an account name.
+- Set a realistic `--time`; memory is allocated in proportion to the cores you request.
+
+## Partitions
+
+| Partition | For | Notes |
+|-----------|-----|-------|
+| `cpu` | CPU jobs (128-core nodes, 256 GB) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `highmem` | Large-memory jobs (1 TB nodes) | QOS `normal`; up to 24 h; job must use more than 64 of 128 cores |
+| `gpu` | GPU jobs (3× AMD MI210 per node) | QOS `normal`; up to 24 h; request cores proportional to GPUs used |
+
+## QOS and charging
+
+- **`normal`** — the default; normal priority, charged against your account.
+- **`standby`** — access to idle resources at low priority, **not charged**, max 4
+  hours. Request it with **`-q standby`** (it is a QOS, **not** an account).
+
+## Common commands
+
+`sbatch` (submit a batch script), `squeue -u $USER` (your jobs), `scontrol show job
+<id>` (job detail), `scontrol hold`/`release`, `scancel <id>` (cancel), `sinteractive`
+(interactive job), `srun` (launch tasks).
+
+## Prohibitions
+
+- **Do NOT** assume `ai`/`smallgpu` partitions or a `preemptible` QOS — those are from other RCAC clusters. Negishi's GPU partition is `gpu` (AMD MI210), and the low-priority QOS is `standby`.
+- **Do NOT** request unlimited memory with `--mem=0`; set an explicit value (use `--exclusive` for a whole node).
+- **Do NOT** write `-A standby` or `#SBATCH -A standby` — `standby` is a QOS
+  (`-q standby`), not an account.
+- **Do NOT** emit flags for other schedulers (PBS/Torque `#PBS`, LSF `#BSUB`) — this is
+  Slurm.
+- **Do NOT** invent partition or QOS names; the valid sets are listed above.
+- **Do NOT** submit jobs without a `--time` limit, and **do NOT** `scancel` jobs you do
+  not own or run bulk cancellations without confirming with the user.
+
+<!-- Source: policies.md -->
+
+# Policies and Safety (Negishi)
+
+You are acting as a specific user on shared, audited research infrastructure.
+Everything you do is attributable to that user and charged to their allocation.
+
+## Acceptable use
+
+- Use of Negishi is bound by Purdue IT's Acceptable Use Policy and RCAC's resource
+  policies. Stay within the user's approved allocations and project scope.
+
+## Data handling
+
+- **Do NOT** place sensitive, regulated, or export-controlled data on the cluster
+  without prior approval, and **do NOT** store any sensitive data in world-readable
+  locations.
+
+## Secrets and credentials
+
+- **Do NOT** read, print, or transmit private keys, API tokens, or passwords, and
+  **do NOT** write them into files, prompts, or your own context. Treat anything under
+  `~/.ssh` and any `.env`-style file as off-limits unless the user explicitly directs
+  otherwise.
+
+## Resource stewardship
+
+- No heavy compute on login nodes; submit through Slurm with time limits (see
+  `slurm.md`). Watch allocation balances with `slist` — a runaway resubmission loop can
+  exhaust an allocation quickly.
+
+## Destructive operations require confirmation
+
+- **Confirm with the user before any destructive or irreversible action:** `rm -rf`,
+  mass file moves, permission changes on shared paths, or bulk `scancel`.
+
+## Containers are not a sandbox here
+
+- Negishi uses **Apptainer** (not Docker). RCAC's Apptainer configuration
+  **auto-mounts `/home`, `/depot`, and `/scratch`** into containers, and those mounts
+  are writable — running inside a container does **not** protect the user's real files
+  from being edited or deleted. Do not assume container isolation.
+
+## Getting help
+
+- Verify AI-generated commands before running them. Report incorrect or harmful AI
+  output to **rcac-help@purdue.edu**.
diff --git a/docs/snippets/agentic-ai/negishi/agents.d/filesystems.md b/docs/snippets/agentic-ai/negishi/agents.d/filesystems.md
new file mode 100644
index 00000000..ab880d5a
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/agents.d/filesystems.md
@@ -0,0 +1,51 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/negishi.yml. Manual changes will be lost! -->
+# Filesystems (Negishi)
+
+Negishi mounts several filesystems, each with a different purpose, technology, and
+durability. Put data in the right place, and never assume a path is durable without
+checking.
+
+## Home — `/home/$USER` (`$HOME`)
+
+- **Technology:** GPFS, with nightly snapshots kept for 7 days, weekly for 4 weeks, and monthly for 3 months (recoverable).
+- **Use for:** source code, scripts, configuration, small files. It is
+  medium-performance and space-limited.
+- **Do NOT** stage large datasets or run heavy parallel job I/O here.
+
+## Scratch — `/scratch/negishi/$USER` (`$RCAC_SCRATCH`)
+
+- **Technology:** a high-performance, large-capacity parallel filesystem.
+- **Use for:** active job input/output and large working data. Point writable working
+  files here (`$RCAC_SCRATCH`), not at home. Find the path with `findscratch`.
+- **Not backed up, and purged after 60 days of inactivity** (by last access and
+  content-modification time; touching metadata does not protect a file). Use
+  `purgelist` to see files scheduled for purge.
+- **Do NOT** treat scratch as durable storage — move anything you want to keep to Data
+  Depot or Fortress.
+
+## Node-local — `/tmp`
+
+- Ephemeral, per-node storage that exists only while your job runs on that node; not
+  backed up, not recoverable.
+
+## Long-term — Data Depot and Fortress
+
+- **Data Depot** is group project space on **GPFS** (typically under `/depot`), for
+  active research data you need to keep.
+- **Fortress** is the HPSS archive for long-term/cold storage; move data with `hsi`
+  and `htar`.
+
+## Check before you write
+
+- Run **`myquota`** to read home and scratch usage and limits before writing large
+  amounts of data. **Do NOT assume specific quota numbers** — they differ per user and
+  change over time; read them from `myquota`.
+- Reference paths with environment variables (`$HOME`, `$RCAC_SCRATCH`), not
+  hard-coded strings, since paths can change.
+
+## Prohibitions
+
+- **Do NOT** store secrets, credentials, or sensitive/regulated data in world-readable
+  paths.
+- **Do NOT** perform bulk or recursive deletes (`rm -rf`) without confirming with the
+  user first.
diff --git a/docs/snippets/agentic-ai/negishi/agents.d/lmod.md b/docs/snippets/agentic-ai/negishi/agents.d/lmod.md
new file mode 100644
index 00000000..f667cee5
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/agents.d/lmod.md
@@ -0,0 +1,32 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/negishi.yml. Manual changes will be lost! -->
+# Software Modules — Lmod (Negishi)
+
+Software on Negishi is provided through **environment modules** (Lmod), not the
+system package manager.
+
+## Finding and loading software
+
+- `module avail` — list available modules.
+- `module spider <name>` — search for a package and see its versions and
+  prerequisites.
+- `module load <name>/<version>` — load a specific version; `(D)` marks the default.
+- `module list` — show what is currently loaded; `module purge` clears everything.
+
+Load the same modules inside your job scripts that you used interactively, so batch
+jobs run in the environment you tested.
+
+## Recommended toolchain
+
+The recommended compiler and MPI stack is **GCC 12.2.0 with OpenMPI**. Check
+`module avail` for the exact versions available.
+
+## Prohibitions
+
+- **Do NOT** install software with `apt`, `yum`, `dnf`, or `sudo` — you do not have
+  root, and system package managers are not the mechanism here. Use modules, or install
+  into user space.
+- **Do NOT invent module names or versions.** Verify a package and version exist with
+  `module spider` (or `module avail`) before claiming it is available or writing it
+  into a job script.
+- For Python, prefer the `anaconda` modules and user environments rather than modifying
+  a base installation.
diff --git a/docs/snippets/agentic-ai/negishi/agents.d/policies.md b/docs/snippets/agentic-ai/negishi/agents.d/policies.md
new file mode 100644
index 00000000..68947706
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/agents.d/policies.md
@@ -0,0 +1,46 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/negishi.yml. Manual changes will be lost! -->
+# Policies and Safety (Negishi)
+
+You are acting as a specific user on shared, audited research infrastructure.
+Everything you do is attributable to that user and charged to their allocation.
+
+## Acceptable use
+
+- Use of Negishi is bound by Purdue IT's Acceptable Use Policy and RCAC's resource
+  policies. Stay within the user's approved allocations and project scope.
+
+## Data handling
+
+- **Do NOT** place sensitive, regulated, or export-controlled data on the cluster
+  without prior approval, and **do NOT** store any sensitive data in world-readable
+  locations.
+
+## Secrets and credentials
+
+- **Do NOT** read, print, or transmit private keys, API tokens, or passwords, and
+  **do NOT** write them into files, prompts, or your own context. Treat anything under
+  `~/.ssh` and any `.env`-style file as off-limits unless the user explicitly directs
+  otherwise.
+
+## Resource stewardship
+
+- No heavy compute on login nodes; submit through Slurm with time limits (see
+  `slurm.md`). Watch allocation balances with `slist` — a runaway resubmission loop can
+  exhaust an allocation quickly.
+
+## Destructive operations require confirmation
+
+- **Confirm with the user before any destructive or irreversible action:** `rm -rf`,
+  mass file moves, permission changes on shared paths, or bulk `scancel`.
+
+## Containers are not a sandbox here
+
+- Negishi uses **Apptainer** (not Docker). RCAC's Apptainer configuration
+  **auto-mounts `/home`, `/depot`, and `/scratch`** into containers, and those mounts
+  are writable — running inside a container does **not** protect the user's real files
+  from being edited or deleted. Do not assume container isolation.
+
+## Getting help
+
+- Verify AI-generated commands before running them. Report incorrect or harmful AI
+  output to **rcac-help@purdue.edu**.
diff --git a/docs/snippets/agentic-ai/negishi/agents.d/slurm.md b/docs/snippets/agentic-ai/negishi/agents.d/slurm.md
new file mode 100644
index 00000000..64730f6b
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/agents.d/slurm.md
@@ -0,0 +1,48 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/negishi.yml. Manual changes will be lost! -->
+# Slurm Scheduler (Negishi)
+
+All real computation on Negishi runs as **Slurm** jobs. Never run compute on a login
+node (see `unix.md`) — submit it here.
+
+## Every Negishi job needs four things
+
+A job request must specify **resources**, an **account**, a **QOS**, and a
+**partition**. On Negishi you MUST explicitly set **both the account
+(`-A`/`--account=`) and the partition (`-p`/`--partition=`)**; also set the QOS
+(`-q`/`--qos=`) and always a time limit (`--time`).
+
+- Discover the accounts you can charge (and their balances) with **`slist`** — do not
+  guess an account name.
+- Set a realistic `--time`; memory is allocated in proportion to the cores you request.
+
+## Partitions
+
+| Partition | For | Notes |
+|-----------|-----|-------|
+| `cpu` | CPU jobs (128-core nodes, 256 GB) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
+| `highmem` | Large-memory jobs (1 TB nodes) | QOS `normal`; up to 24 h; job must use more than 64 of 128 cores |
+| `gpu` | GPU jobs (3× AMD MI210 per node) | QOS `normal`; up to 24 h; request cores proportional to GPUs used |
+
+## QOS and charging
+
+- **`normal`** — the default; normal priority, charged against your account.
+- **`standby`** — access to idle resources at low priority, **not charged**, max 4
+  hours. Request it with **`-q standby`** (it is a QOS, **not** an account).
+
+## Common commands
+
+`sbatch` (submit a batch script), `squeue -u $USER` (your jobs), `scontrol show job
+<id>` (job detail), `scontrol hold`/`release`, `scancel <id>` (cancel), `sinteractive`
+(interactive job), `srun` (launch tasks).
+
+## Prohibitions
+
+- **Do NOT** assume `ai`/`smallgpu` partitions or a `preemptible` QOS — those are from other RCAC clusters. Negishi's GPU partition is `gpu` (AMD MI210), and the low-priority QOS is `standby`.
+- **Do NOT** request unlimited memory with `--mem=0`; set an explicit value (use `--exclusive` for a whole node).
+- **Do NOT** write `-A standby` or `#SBATCH -A standby` — `standby` is a QOS
+  (`-q standby`), not an account.
+- **Do NOT** emit flags for other schedulers (PBS/Torque `#PBS`, LSF `#BSUB`) — this is
+  Slurm.
+- **Do NOT** invent partition or QOS names; the valid sets are listed above.
+- **Do NOT** submit jobs without a `--time` limit, and **do NOT** `scancel` jobs you do
+  not own or run bulk cancellations without confirming with the user.
diff --git a/docs/snippets/agentic-ai/negishi/agents.d/unix.md b/docs/snippets/agentic-ai/negishi/agents.d/unix.md
new file mode 100644
index 00000000..a56cf236
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/agents.d/unix.md
@@ -0,0 +1,37 @@
+<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/negishi.yml. Manual changes will be lost! -->
+# Unix Environment (Negishi)
+
+Negishi runs **Rocky Linux 8** with a standard GNU/bash userland. You are acting as a
+specific user, over that user's existing SSH access — you have exactly their
+privileges and nothing more.
+
+## The login (front-end) nodes are shared
+
+Connecting to `negishi.rcac.purdue.edu` places you on one of several shared front-end
+nodes, used simultaneously by many people. They are for **editing, compiling,
+submitting jobs, and light pre- and post-processing only**.
+
+- **Do NOT run large, long, multi-threaded, parallel, or CPU-intensive work on a
+  login node.** Submit it to Slurm instead (see `slurm.md`). Heavy work on a front end
+  degrades the system for everyone and may be killed by administrators.
+- **Do NOT start unbounded background processes or retry loops.** Clean up stray
+  processes, and watch for your own retry storms.
+
+## No elevated privileges
+
+- **Do NOT use `sudo` or attempt to gain root.** You cannot install system packages.
+- Install software into user space, or preferably use the environment modules system
+  (see `lmod.md`).
+
+## Ground yourself before acting
+
+Prefer checking the real state of the system over assuming it. These commands are
+read-only, cheap, and safe — run them eagerly before you plan or act:
+
+- `myquota` — home and scratch usage and limits.
+- `slist` — the accounts you can charge and their balances.
+- `sfeatures` — node and GPU hardware features.
+- `module avail` / `module list` — available and currently-loaded software.
+
+Grounding your plan in real output prevents the most common failure mode: confidently
+acting on an assumption that is wrong for this cluster.
diff --git a/docs/snippets/agentic-ai/negishi/claude/settings.json b/docs/snippets/agentic-ai/negishi/claude/settings.json
new file mode 100644
index 00000000..bbb15a0b
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/claude/settings.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Bash(myquota:*)",
+      "Bash(slist:*)",
+      "Bash(sfeatures:*)",
+      "Bash(module list:*)",
+      "Bash(module avail:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(sudo:*)",
+      "Read(./.env)",
+      "Read(~/.ssh/**)"
+    ],
+    "additionalDirectories": ["/scratch/negishi"]
+  },
+  "disableBypassPermissionsMode": "disable"
+}
diff --git a/docs/snippets/agentic-ai/negishi/codex/config.toml b/docs/snippets/agentic-ai/negishi/codex/config.toml
new file mode 100644
index 00000000..6c724b38
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/codex/config.toml
@@ -0,0 +1,22 @@
+# Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/negishi.yml. Manual changes will be lost!
+# ~/.codex/config.toml — recommended cluster-side config for Codex on Negishi.
+#
+# Codex has no per-command allow/deny list; safety comes from the approval policy and
+# the sandbox mode. On shared login nodes where bubblewrap is unavailable, prefer
+# approval_policy = "untrusted" and sandbox_mode = "read-only" so nothing runs without
+# an explicit approval. Codex reads AGENTS.md natively for the shared context.
+#
+# The only MCP server configured here is the hosted documentation server over plain
+# HTTP (no local tooling / no uvx). An agent running on the cluster already has direct
+# shell and Slurm access, so it does NOT need the rcac-mcp SSH bridge — that server is
+# for running an agent locally (see the Local page).
+
+approval_policy = "on-request"
+sandbox_mode    = "workspace-write"
+
+[sandbox_workspace_write]
+writable_roots = ["/scratch/negishi"]
+network_access = false
+
+[mcp_servers.rcac_docs]
+url = "https://docs.rcac.purdue.edu/mcp"
diff --git a/docs/snippets/agentic-ai/negishi/gemini/settings.json b/docs/snippets/agentic-ai/negishi/gemini/settings.json
new file mode 100644
index 00000000..5c0559ac
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/gemini/settings.json
@@ -0,0 +1,25 @@
+{
+  "tools": {
+    "core": [
+      "run_shell_command(myquota)",
+      "run_shell_command(slist)",
+      "run_shell_command(sfeatures)",
+      "run_shell_command(module)"
+    ],
+    "exclude": [
+      "run_shell_command(rm)",
+      "run_shell_command(sudo)"
+    ]
+  },
+  "security": {
+    "disableYoloMode": true
+  },
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"]
+  },
+  "mcpServers": {
+    "rcac-docs": {
+      "httpUrl": "https://docs.rcac.purdue.edu/mcp"
+    }
+  }
+}
diff --git a/docs/snippets/agentic-ai/negishi/opencode/opencode.json b/docs/snippets/agentic-ai/negishi/opencode/opencode.json
new file mode 100644
index 00000000..3b0c6a15
--- /dev/null
+++ b/docs/snippets/agentic-ai/negishi/opencode/opencode.json
@@ -0,0 +1,22 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "myquota": "allow",
+      "slist": "allow",
+      "sfeatures": "allow",
+      "module list": "allow",
+      "module avail *": "allow",
+      "rm -rf *": "deny",
+      "sudo *": "deny"
+    }
+  },
+  "mcp": {
+    "rcac-docs": {
+      "type": "remote",
+      "url": "https://docs.rcac.purdue.edu/mcp",
+      "enabled": true
+    }
+  }
+}
diff --git a/docs/userguides/gautschi/index.md b/docs/userguides/gautschi/index.md
index c61d4d31..937fda8c 100644
--- a/docs/userguides/gautschi/index.md
+++ b/docs/userguides/gautschi/index.md
@@ -30,4 +30,5 @@ Gautschi is a Community Cluster optimized for communities running traditional, t
 - [**File Storage and Transfer**](storage.md)
 - [**Gateway (Open OnDemand)**](gateway.md)
 - [**Compiling Source Code**](compile.md)
+- [**Using AI Agents**](using_ai_agents.md)
 - [**Frequently Asked Questions**](faqs.md)
\ No newline at end of file
diff --git a/docs/userguides/gautschi/using_ai_agents.md b/docs/userguides/gautschi/using_ai_agents.md
new file mode 100644
index 00000000..c77b53ed
--- /dev/null
+++ b/docs/userguides/gautschi/using_ai_agents.md
@@ -0,0 +1,73 @@
+---
+tags:
+  - Gautschi
+authors:
+  - glentner
+resource: Gautschi
+search:
+  boost: 2
+---
+
+# Using AI Agents on {{ resource }}
+
+Agentic coding tools — Claude Code, Codex, Gemini CLI, opencode, and Warp — work well
+on {{ resource }} when they are set up with accurate, cluster-specific context. This
+chapter is the {{ resource }}-specific quick-start; the concepts, policy, MCP servers,
+and shared-context model live in the top-level
+[Agentic AI](../../agentic-ai/index.md) section, and everything there applies here.
+
+RCAC's stance is **proactive engagement, not prohibition**: we shape the context so an
+agent's output is more likely to be correct for {{ resource }}, and we help you
+**verify** it rather than forbidding the tools. Start with
+[Acceptable Use & Etiquette](../../agentic-ai/acceptable_use.md) and
+[Best Practices & Limitations](../../agentic-ai/best_practices.md).
+
+## Choose how you run the agent
+
+The [Running Agents](../../agentic-ai/running_agents/index.md) pages cover both
+deployment modes for all five harnesses:
+
+- **[On the cluster](../../agentic-ai/running_agents/on_cluster.md)** — install a CLI
+  harness (Claude Code, Codex, Gemini CLI, or opencode) on a {{ resource }} login node
+  and run it there.
+- **[Locally, targeting the cluster](../../agentic-ai/running_agents/local.md)** — run
+  the harness on your own machine and reach {{ resource }} over SSH (host
+  `{{ resource | lower }}.rcac.purdue.edu`) through the RCAC MCP servers. This is the
+  recommended path, and the only way to use **Warp** (a desktop app that cannot run on a
+  login node).
+
+## {{ resource }}'s shared context
+
+RCAC deploys a set of context files to `/etc/agents.d/` on {{ resource }} — the
+partitions, GPUs, filesystems, and toolchain that general-purpose models most often get
+wrong — and `rcac-mcp` injects them into an agent. They are **generated from
+{{ resource }}'s verified facts**, so an agent that reads them targets the right
+partitions and writes to the right filesystems. See
+[Context Files](../../agentic-ai/shared_context/context_files.md) for how the files are
+structured and [Harness Settings & Permissions](../../agentic-ai/shared_context/settings.md)
+for the per-harness permission policy.
+
+This is the exact assembled context an on-cluster agent reads on {{ resource }}:
+
+??? note "Show {{ resource }}'s assembled `AGENTS.md`"
+
+    ```markdown title="AGENTS.md ({{ resource }})"
+    --8<-- "docs/snippets/agentic-ai/gautschi/agents.d/AGENTS.md"
+    ```
+
+The cluster-side permission policy for Claude Code allow-lists `slist`/`myquota`, denies
+`rm -rf`/`sudo`, and points writable scope at {{ resource }}'s scratch:
+
+```json title="/etc/claude-code/managed-settings.json"
+--8<-- "docs/snippets/agentic-ai/gautschi/claude/settings.json"
+```
+
+!!! important
+
+    Do NOT run large, long, multi-threaded, parallel, or CPU-intensive jobs on a
+    front-end login host. Always use Slurm to submit your work as a job — this applies
+    to anything heavy an agent does on your behalf, exactly as it does to you.
+
+---
+
+Back to the [Gautschi User Guide](index.md).
diff --git a/docs/userguides/gilbreth/index.md b/docs/userguides/gilbreth/index.md
index 90857984..ae024cf3 100644
--- a/docs/userguides/gilbreth/index.md
+++ b/docs/userguides/gilbreth/index.md
@@ -30,4 +30,5 @@ Gilbreth is a Community Cluster optimized for communities running GPU intensive
 - [**File Storage and Transfer**](storage.md)
 - [**Gateway (Open OnDemand)**](gateway.md)
 - [**Compiling Source Code**](compile.md)
+- [**Using AI Agents**](using_ai_agents.md)
 - [**Frequently Asked Questions**](faqs.md)
diff --git a/docs/userguides/gilbreth/using_ai_agents.md b/docs/userguides/gilbreth/using_ai_agents.md
new file mode 100644
index 00000000..52403e25
--- /dev/null
+++ b/docs/userguides/gilbreth/using_ai_agents.md
@@ -0,0 +1,75 @@
+---
+tags:
+  - Gilbreth
+authors:
+  - glentner
+resource: Gilbreth
+search:
+  boost: 2
+---
+
+# Using AI Agents on {{ resource }}
+
+Agentic coding tools — Claude Code, Codex, Gemini CLI, opencode, and Warp — work well
+on {{ resource }} when they are set up with accurate, cluster-specific context. This
+chapter is the {{ resource }}-specific quick-start; the concepts, policy, MCP servers,
+and shared-context model live in the top-level
+[Agentic AI](../../agentic-ai/index.md) section, and everything there applies here.
+
+RCAC's stance is **proactive engagement, not prohibition**: we shape the context so an
+agent's output is more likely to be correct for {{ resource }}, and we help you
+**verify** it rather than forbidding the tools. Start with
+[Acceptable Use & Etiquette](../../agentic-ai/acceptable_use.md) and
+[Best Practices & Limitations](../../agentic-ai/best_practices.md).
+
+## Choose how you run the agent
+
+The [Running Agents](../../agentic-ai/running_agents/index.md) pages cover both
+deployment modes for all five harnesses:
+
+- **[On the cluster](../../agentic-ai/running_agents/on_cluster.md)** — install a CLI
+  harness (Claude Code, Codex, Gemini CLI, or opencode) on a {{ resource }} login node
+  and run it there.
+- **[Locally, targeting the cluster](../../agentic-ai/running_agents/local.md)** — run
+  the harness on your own machine and reach {{ resource }} over SSH (host
+  `{{ resource | lower }}.rcac.purdue.edu`) through the RCAC MCP servers. This is the
+  recommended path, and the only way to use **Warp** (a desktop app that cannot run on a
+  login node).
+
+## {{ resource }}'s shared context
+
+RCAC deploys a set of context files to `/etc/agents.d/` on {{ resource }} — the
+partitions, GPUs, filesystems, and toolchain that general-purpose models most often get
+wrong — and `rcac-mcp` injects them into an agent. They are **generated from
+{{ resource }}'s verified facts** (its GPU-purchase partitions
+`a10`/`a30`/`a100-40gb`/`a100-80gb`/`training`, where the GPU type is chosen by
+partition), so an agent that reads them targets the right partitions and writes to the
+right filesystems. See
+[Context Files](../../agentic-ai/shared_context/context_files.md) for how the files are
+structured and [Harness Settings & Permissions](../../agentic-ai/shared_context/settings.md)
+for the per-harness permission policy.
+
+This is the exact assembled context an on-cluster agent reads on {{ resource }}:
+
+??? note "Show {{ resource }}'s assembled `AGENTS.md`"
+
+    ```markdown title="AGENTS.md ({{ resource }})"
+    --8<-- "docs/snippets/agentic-ai/gilbreth/agents.d/AGENTS.md"
+    ```
+
+The cluster-side permission policy for Claude Code allow-lists `slist`/`myquota`, denies
+`rm -rf`/`sudo`, and points writable scope at {{ resource }}'s scratch:
+
+```json title="/etc/claude-code/managed-settings.json"
+--8<-- "docs/snippets/agentic-ai/gilbreth/claude/settings.json"
+```
+
+!!! important
+
+    Do NOT run large, long, multi-threaded, parallel, or CPU-intensive jobs on a
+    front-end login host. Always use Slurm to submit your work as a job — this applies
+    to anything heavy an agent does on your behalf, exactly as it does to you.
+
+---
+
+Back to the [Gilbreth User Guide](index.md).
diff --git a/docs/userguides/negishi/index.md b/docs/userguides/negishi/index.md
index 878446cd..225654b8 100644
--- a/docs/userguides/negishi/index.md
+++ b/docs/userguides/negishi/index.md
@@ -31,6 +31,7 @@ Negishi is a Community Cluster optimized for communities running traditional, ti
 - [**File Storage and Transfer**](storage.md)
 - [**Gateway (Open OnDemand)**](gateway.md)
 - [**Compiling Source Code**](compile.md)
+- [**Using AI Agents**](using_ai_agents.md)
 - [**Frequently Asked Questions**](faqs.md)
 
 
diff --git a/docs/userguides/negishi/using_ai_agents.md b/docs/userguides/negishi/using_ai_agents.md
new file mode 100644
index 00000000..002556d5
--- /dev/null
+++ b/docs/userguides/negishi/using_ai_agents.md
@@ -0,0 +1,74 @@
+---
+tags:
+  - Negishi
+authors:
+  - glentner
+resource: Negishi
+search:
+  boost: 2
+---
+
+# Using AI Agents on {{ resource }}
+
+Agentic coding tools — Claude Code, Codex, Gemini CLI, opencode, and Warp — work well
+on {{ resource }} when they are set up with accurate, cluster-specific context. This
+chapter is the {{ resource }}-specific quick-start; the concepts, policy, MCP servers,
+and shared-context model live in the top-level
+[Agentic AI](../../agentic-ai/index.md) section, and everything there applies here.
+
+RCAC's stance is **proactive engagement, not prohibition**: we shape the context so an
+agent's output is more likely to be correct for {{ resource }}, and we help you
+**verify** it rather than forbidding the tools. Start with
+[Acceptable Use & Etiquette](../../agentic-ai/acceptable_use.md) and
+[Best Practices & Limitations](../../agentic-ai/best_practices.md).
+
+## Choose how you run the agent
+
+The [Running Agents](../../agentic-ai/running_agents/index.md) pages cover both
+deployment modes for all five harnesses:
+
+- **[On the cluster](../../agentic-ai/running_agents/on_cluster.md)** — install a CLI
+  harness (Claude Code, Codex, Gemini CLI, or opencode) on a {{ resource }} login node
+  and run it there.
+- **[Locally, targeting the cluster](../../agentic-ai/running_agents/local.md)** — run
+  the harness on your own machine and reach {{ resource }} over SSH (host
+  `{{ resource | lower }}.rcac.purdue.edu`) through the RCAC MCP servers. This is the
+  recommended path, and the only way to use **Warp** (a desktop app that cannot run on a
+  login node).
+
+## {{ resource }}'s shared context
+
+RCAC deploys a set of context files to `/etc/agents.d/` on {{ resource }} — the
+partitions, GPUs, filesystems, and toolchain that general-purpose models most often get
+wrong — and `rcac-mcp` injects them into an agent. They are **generated from
+{{ resource }}'s verified facts** (its `cpu`/`highmem`/`gpu` partitions, AMD MI210 GPUs,
+and GPFS home), so an agent that reads them targets the right partitions and writes to
+the right filesystems. See
+[Context Files](../../agentic-ai/shared_context/context_files.md) for how the files are
+structured and [Harness Settings & Permissions](../../agentic-ai/shared_context/settings.md)
+for the per-harness permission policy.
+
+This is the exact assembled context an on-cluster agent reads on {{ resource }}:
+
+??? note "Show {{ resource }}'s assembled `AGENTS.md`"
+
+    ```markdown title="AGENTS.md ({{ resource }})"
+    --8<-- "docs/snippets/agentic-ai/negishi/agents.d/AGENTS.md"
+    ```
+
+The cluster-side permission policy for Claude Code allow-lists `slist`/`myquota`, denies
+`rm -rf`/`sudo`, and points writable scope at {{ resource }}'s scratch:
+
+```json title="/etc/claude-code/managed-settings.json"
+--8<-- "docs/snippets/agentic-ai/negishi/claude/settings.json"
+```
+
+!!! important
+
+    Do NOT run large, long, multi-threaded, parallel, or CPU-intensive jobs on a
+    front-end login host. Always use Slurm to submit your work as a job — this applies
+    to anything heavy an agent does on your behalf, exactly as it does to you.
+
+---
+
+Back to the [Negishi User Guide](index.md).
diff --git a/mkdocs.yml b/mkdocs.yml
index 617b2b79..095c3457 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -142,6 +142,7 @@ nav:
       - File Storage and Transfer: userguides/gautschi/storage.md
       - Gateway (Open OnDemand): userguides/gautschi/gateway.md
       - Compiling Source Code: userguides/gautschi/compile.md
+      - Using AI Agents: userguides/gautschi/using_ai_agents.md
       - Frequently Asked Questions: userguides/gautschi/faqs.md
     - Gilbreth:
       - userguides/gilbreth/index.md
@@ -153,6 +154,7 @@ nav:
       - File Storage and Transfer: userguides/gilbreth/storage.md
       - Gateway (Open OnDemand): userguides/gilbreth/gateway.md
       - Compiling Source Code: userguides/gilbreth/compile.md
+      - Using AI Agents: userguides/gilbreth/using_ai_agents.md
       - Frequently Asked Questions: userguides/gilbreth/faqs.md
     - Negishi:
       - userguides/negishi/index.md
@@ -164,6 +166,7 @@ nav:
       - File Storage and Transfer: userguides/negishi/storage.md
       - Gateway (Open OnDemand): userguides/negishi/gateway.md
       - Compiling Source Code: userguides/negishi/compile.md
+      - Using AI Agents: userguides/negishi/using_ai_agents.md
       - Frequently Asked Questions: userguides/negishi/faqs.md
     - Scholar: 
       - userguides/scholar/index.md
@@ -358,6 +361,19 @@ nav:
         - Mitochondrial Genomes (MitoHiFi): lifesciences/tutorials/mitohifi.md
       - Hi-C Analysis:
         - Juicer: lifesciences/tutorials/juicer.md
+  - Agentic AI:
+    - agentic-ai/index.md
+    - Acceptable Use & Etiquette: agentic-ai/acceptable_use.md
+    - Best Practices & Limitations: agentic-ai/best_practices.md
+    - MCP Servers: agentic-ai/mcp_servers.md
+    - Running Agents:
+      - agentic-ai/running_agents/index.md
+      - On the Cluster (Login Nodes): agentic-ai/running_agents/on_cluster.md
+      - Local (over SSH): agentic-ai/running_agents/local.md
+    - Shared Context & Settings:
+      - agentic-ai/shared_context/index.md
+      - Context Files (/etc/agents.d): agentic-ai/shared_context/context_files.md
+      - Harness Settings & Permissions: agentic-ai/shared_context/settings.md
   # - Tags: tags.md
   - Contact us: contact.md
   - FAQs: faqs.md
diff --git a/spec/agentic-ai-docs/GOAL.md b/spec/agentic-ai-docs/GOAL.md
new file mode 100644
index 00000000..b7685a13
--- /dev/null
+++ b/spec/agentic-ai-docs/GOAL.md
@@ -0,0 +1,280 @@
+# GOAL — Agentic AI on RCAC: guidance, MCP tooling, and shared context
+
+> **Origin spec.** The *what* and *why* — the locked contract `docs-review` grades against.
+> The *how* lives in [`PLAN.md`](PLAN.md) and [`TECH.md`](TECH.md) (written by `docs-plan`).
+
+- **slug:** agentic-ai-docs
+- **kind:** feature
+- **appetite:** big  ·  *multi-pillar new section; expect `docs-plan` to split into several phases and
+  to scope-hammer nice-to-haves against this contract.*
+
+## Problem
+
+Researchers on RCAC's clusters are already using agentic coding tools — Claude Code, OpenAI
+Codex, Gemini CLI, opencode, Warp — with or without our endorsement, both directly on login
+nodes and from their laptops targeting the cluster over SSH. Today the RCAC documentation site
+has **zero** public guidance on this: no acceptable-use rules, no setup instructions, no mention
+of our MCP servers, and no published account of the shared context we inject into agents. The
+result is the failure mode described in our PEARC'26 paper *Hello Computer: HPC in the Agentic
+Era* — users arrive at the help desk with confident, plausible, and wrong AI output (a Slurm
+script for a scheduler we don't run), and the cluster is exposed to preventable mistakes because
+nobody shaped the context in which the interaction happened.
+
+RCAC's chosen strategy is **proactive engagement, not prohibition**: system-wide `/etc/agents.d`
+context files, purpose-built MCP servers, and honest documentation that helps users *verify*
+rather than *forbidding* the tools. Two of those three pillars exist in prototype (the MCP
+servers); the documentation pillar does not exist at all, and the shared context/settings
+artifacts the other pillars are meant to consume have not yet been authored. This feature builds
+the documentation pillar **and**, as a shared exercise, constructs the first real version of the
+shared context and per-harness settings — starting with the Gautschi cluster.
+
+## Outcome / vision
+
+A new top-level **Agentic AI** section on `docs.rcac.purdue.edu`, plus a cross-linked **Using AI
+Agents** chapter in the Gautschi user guide. After reading, a researcher can:
+
+- Understand RCAC's stance and what is expected of them: acceptable use, etiquette, the real
+  limitations, and best practices (using an agent *for research* vs *for operations*; verifying
+  output; augmenting rather than outsourcing their own expertise; the safety "don't cross the
+  streams" cautions).
+- **Set up their chosen harness** (any of the five) correctly for Gautschi, in whichever mode
+  they work — running the agent *on the cluster* (login nodes) or *locally, targeting the
+  cluster* over MCP + SSH.
+- Learn what our **MCP servers** are, why they matter, and how to connect them: the HPC
+  operations server (`rcac-mcp`, generalizing toward a plugin architecture), the docs-search
+  server (`rcac-docs-mcp`, hosted at `docs.rcac.purdue.edu/mcp`), and `globus-mcp` for transfers.
+- **See exactly what context and permissions RCAC gives their agents** — the actual Gautschi
+  `/etc/agents.d` context files (`unix.md`, `filesystems.md`, `lmod.md`, `slurm.md`,
+  `policies.md`) and the per-harness settings files, published verbatim — and know how to send
+  feedback and corrections.
+
+The published context/settings files are the **canonical single source of truth**: cluster
+config management (Puppet) copies them out to `/etc/agents.d` on the hosts, and the HPC MCP
+server reads them over SSH and injects them as agent context. This is early, evolving work; the
+docs say so.
+
+## Acceptance criteria (the contract)
+
+Reader-facing, observable outcomes. Stable IDs survive squash-merge.
+
+**Section & stance**
+
+- **R1** — A top-level **Agentic AI** section SHALL appear in `mkdocs.yml` `nav:` with an
+  `index.md` hub that states RCAC's stance (proactive engagement, not prohibition; verify, don't
+  forbid) and links to every subpage; it SHALL resolve without a `--strict` nav/link warning.
+
+**Acceptable use, etiquette, limitations, best practices**
+
+- **R2** — WHEN a reader opens the acceptable-use/etiquette page, it SHALL state the rules for
+  running agents on RCAC systems (no heavy compute on login nodes; jobs go through Slurm with
+  time limits; no sensitive data in world-readable locations; destructive actions require
+  confirmation) consistently with RCAC's existing Acceptable Use policy, and link to the Purdue
+  IT policy of record.
+- **R3** — A best-practices/limitations page SHALL distinguish using an agent *for research* from
+  using one *for operations*, and SHALL cover context engineering, verification of output
+  ("augmented, not outsourced"; ask *why*, not just *what*), and the caution/blast-radius risks
+  (destructive commands, allocation exhaustion, credential/secret leakage).
+
+**Running agents (organized by deployment mode; all five harnesses)**
+
+- **R4** — The "Running agents" material SHALL be organized primarily by deployment mode —
+  (a) *on the cluster* (login nodes) and (b) *locally, targeting the cluster* via MCP + SSH — and
+  each mode SHALL cover Claude Code, Codex, Gemini CLI, opencode, and Warp.
+- **R5** — The on-cluster guidance SHALL state the login-node constraints that apply to agents
+  (no heavy/parallel/long compute on front-ends; submit work via Slurm), consistent with the
+  Gautschi Running Jobs guidance.
+- **R6** — The local (MCP + SSH) guidance SHALL explain the local-first architecture: the agent
+  runs in the user's own environment and executes remotely through their existing SSH access — no
+  new credentials and no hosted infrastructure required.
+
+**MCP servers**
+
+- **R7** — An MCP page SHALL document RCAC's MCP servers with their current focus and link each to
+  its public GitHub repository: the HPC operations server (`rcac-mcp`, generalizing toward a
+  plugin architecture, e.g. `cluster-mcp[slurm,lmod,…]`); the docs-search server
+  (`rcac-docs-mcp`, hosted at `docs.rcac.purdue.edu/mcp`); and `globus-mcp` (data transfers). It
+  SHALL explain *why* MCP matters (context that knows our clusters), present all three as **working
+  prototypes under active development**, and explicitly **call out the planned rename /
+  re-architecture of `rcac-mcp`** toward the HPC-only plugin model.
+- **R8** — The MCP page SHALL explain that the HPC MCP server reads the host's `/etc/agents.d`
+  markdown context (a configurable location) over SSH and injects it into the agent's context.
+- **R9** — Any install/connection commands or tool names shown for the MCP servers SHALL be
+  verified against the live public repositories at draft time — never invented.
+
+**Shared context & settings (build + publish the canonical source of truth)**
+
+- **R10** — The section SHALL publish the actual Gautschi shared-context files verbatim
+  (`unix.md`, `filesystems.md`, `lmod.md`, `slurm.md`, `policies.md`); their content SHALL be
+  HPC-accurate for Gautschi (Rocky Linux 9; Lmod; partitions `cpu`/`ai`/`highmem`/`smallgpu`/
+  `profiling`; QOS `normal`/`standby`/`preemptible`; correct filesystem paths and technologies —
+  `/home` ZFS, `/depot` GPFS, `/scratch` Lustre — deferring volatile quota numbers to
+  `myquota`/`slist` rather than hardcoding them).
+- **R11** — The section SHALL publish per-harness settings/permission files for all five harnesses
+  (Claude Code, Codex, Gemini CLI, opencode, Warp), each in that harness's native settings
+  format, wiring in the shared context and encoding a starting-point permission policy that both
+  (a) **denies** destructive/dangerous operations (e.g. `rm -rf`, `sudo`) and login-node heavy
+  compute, and (b) **allow-lists common read-only sanity commands** (`myquota`, `slist`,
+  `sfeatures`, `module list`, `module avail`, …) so the agent runs them eagerly without prompting.
+- **R12** — A page SHALL explain how `/etc/agents.d` context and the harness settings fit together
+  (context injected; permissions enforced), state that these files are the canonical source of
+  truth copied into cluster config management, and tell readers how to contribute feedback and
+  corrections.
+
+**Gautschi integration**
+
+- **R13** — A **Using AI Agents** chapter SHALL be added to the Gautschi user guide (in the
+  Gautschi `nav:` sub-tree) and be cross-linked with the top-level Agentic AI section, giving
+  Gautschi-specific setup pointers.
+
+**Build, accessibility, accuracy (hammerable: false — never trimmed to fit appetite)**
+
+- **R14** — Every new page SHALL be included in `mkdocs.yml` `nav:`, and `mkdocs build --strict`
+  SHALL introduce no new warnings versus `strict-baseline.txt`.
+- **R15** — Page-to-page links SHALL be relative and static assets absolute; every content image
+  SHALL carry meaningful `alt` text; headings SHALL descend without skipping; tables SHALL use
+  header rows (content-level WCAG 2.1).
+- **R16** — All HPC specifics on the new pages (partitions, QOS, modules, filesystem paths, SSH
+  hostnames, commands) SHALL be correct for Gautschi, verified against gold-standard Gautschi
+  pages or authoritative sources; no invented flags or paths.
+
+## Non-goals (no-gos)
+
+- **Other clusters.** Gautschi only. Anvil, Bell, Gilbreth, Negishi, Scholar, Geddes, Hammer, and
+  the storage services are an explicit follow-up feature (per-cluster parallelism handled then).
+- **Building the MCP servers.** We document and link `rcac-mcp` / `globus-mcp` / `rcac-docs-mcp`;
+  their source code lives in their own repos and is not shipped or vendored here.
+- **The config-management (Puppet) deployment pipeline.** We author the canonical `/etc/agents.d`
+  and settings files; wiring them into Puppet and onto the hosts is out of scope for this feature.
+- **A security audit / formal threat model** of MCP or agentic tooling — practical caution only,
+  mirroring the paper's non-goal (confinement discussed, not proven).
+- **Model or vendor benchmarking / endorsement.** Guidance is vendor-neutral across the five
+  harnesses; no performance claims.
+- **Theme / CSS / JS or accessibility-*theme*-layer changes.** Content-level a11y only; the theme
+  a11y layer is a `dev`-branch concern (invariants §2).
+- **Generated content.** No hand-edits to catalogs, the software/dataset generators, or
+  breadcrumbs (breadcrumbs regenerate from the nav change via the normal workflow).
+- **A companion announcement blog post** — deferred to a possible follow-up so it doesn't expand
+  this already-large feature.
+
+## Clarifications
+
+Resolved with the human during shaping on 2026-07-14.
+
+- **Q:** Where should the material live, and how prominent? — **A:** Hybrid: a new **top-level
+  "Agentic AI" section** for the general/conceptual/MCP/context material, **plus** a cross-linked
+  **"Using AI Agents"** chapter in the Gautschi user guide.
+- **Q:** How should the built context files and harness settings be surfaced? — **A:** Publish
+  them **verbatim** in this repo as the **canonical single source of truth**. Puppet copies them
+  out to `/etc/agents.d` on the cluster hosts, and the HPC MCP server injects them over SSH; users
+  do **not** hand-install them. (A downloadable copy is a nice-to-have, not required.)
+- **Q:** Which harnesses get authored settings/permission files? — **A:** **All five** (Claude
+  Code, Codex, Gemini CLI, opencode, Warp). All five also get usage guidance.
+- **Q:** Primary organizing axis for the run-agents guidance? — **A:** **By deployment mode**
+  (on-cluster login nodes vs. local via MCP + SSH), with harnesses covered within each.
+- **Q (architecture, from the human):** MCP servers are being re-architected — record the current
+  intent. — **A:** `rcac-mcp` is refocusing on **HPC-only operations** with a **generalized
+  plugin architecture** (e.g. `cluster-mcp[slurm,lmod,…]`); `rcac-docs-mcp` is a **standalone**
+  service hosted at **`docs.rcac.purdue.edu/mcp`** (full-text search/load over this site);
+  `globus-mcp` handles data transfers. The HPC server, over SSH, reads `/etc/agents.d` (a
+  configurable path) on the host and injects those markdown files as MCP context. Docs present all
+  of this as **prototype/evolving** ("likely to change over time").
+- **Q:** What enforced-permission policy do the settings encode? — **A:** This is a deliberate
+  **shared construction exercise**; author a reasonable **starting-point** deny/allow policy
+  derived from the paper (no login-node heavy compute; require Slurm time limits; no secrets in
+  world-readable paths; confirm destructive operations) and iterate later. Not a blocker.
+- **Voice/stance (adopted from the paper, recorded):** proactive engagement not prohibition;
+  "mostly harmless"; verify don't forbid; augmented not outsourced; "don't cross the streams"
+  caution. Professional, instructional, second person (house style).
+
+### Resolved during planning review (2026-07-15)
+
+Refinements from the human after reviewing `PLAN.md`/`TECH.md`:
+
+- **MCP framing (confirmed).** All three servers (`rcac-mcp`, `globus-mcp`, `rcac-docs-mcp`) are
+  **working prototypes under active development**. Docs SHALL explicitly **call out the planned
+  rename / re-architecture of `rcac-mcp`** toward the HPC-only plugin model (`cluster-mcp[slurm,
+  lmod,…]`) — as a stated direction, not a shipped fact. (Refines R7.)
+- **Warp is first-class and recommended.** Warp is the **recommended harness for most users**; the
+  docs SHALL tell the story of using it *well* — run locally on the user's workstation, targeting the
+  cluster over SSH (Warp is a desktop app and does not run on login nodes). Give it prominent,
+  first-class treatment in the local (MCP + SSH) guidance, not a footnote.
+- **Container model is Apptainer, not Docker.** These clusters use **Apptainer**. RCAC's Apptainer
+  configuration **auto bind-mounts `/home`, `/depot`, and `/scratch`** into containers for
+  convenience, so containers offer **limited protection** — the most likely failure mode is an agent
+  *editing files* on those (still-writable) mounts; users can disable the bind-mounts by invoking
+  Apptainer explicitly. Best-practices/caution and the context files SHALL reflect this (do not imply
+  Docker or strong container sandboxing on the nodes).
+- **Filesystem technologies (authoritative, human-corrected).** `/home` is **ZFS**, `/depot` is
+  **GPFS**, `/scratch` is **Lustre** — this corrects the generic snippet that implied `/home` on
+  GPFS. `filesystems.md` SHALL state these correctly. (Refines R10.)
+- **Eager read-only sanity checks + allow-list.** Guidance and context SHALL instruct agents to
+  **eagerly run read-only sanity commands** — `myquota`, `slist`, `sfeatures`, `module list`,
+  `module avail`, and similar — and the per-harness settings SHALL **allow-list** them so the agent
+  does not stop to ask. (Refines R11.)
+
+*No unresolved `[NEEDS CLARIFICATION]` markers remain; the GOAL is ready for `docs-plan`.*
+
+### Resolved during human review (2026-07-15)
+
+Refinements from the human after reading the fully-drafted section on a local build.
+These **refine the recorded voice/interpretation**; the acceptance criteria (R-IDs) are
+unchanged.
+
+- **Paper reference, not front-and-center (refines the voice note & R3).** The PEARC'26
+  paper *Hello Computer: HPC in the Agentic Era* SHALL be cited as a **reference (a
+  footer note)** linking its GitHub replication package
+  (<https://github.com/glentner/pearc26-hello-computer>), **not** as the lead content of
+  the hub. (A DOI will be added once the paper is on the ACM Digital Library — deferred.)
+- **Measured tone; drop the pop-culture framing (supersedes the earlier voice note).**
+  The published docs SHALL use a **direct, measured, professional tone**. The literal
+  phrase **"mostly harmless" SHALL NOT appear**, and other pop-culture references
+  (e.g. "don't cross the streams", "I Know Kung Fu") SHALL be dropped. **One exception:**
+  the **"Tea, Earl Grey, hot"** illustration may appear **once** — it is conceptually
+  load-bearing for the point about prompt specificity. (The stance itself — proactive
+  engagement, verify-don't-forbid, augmented-not-outsourced — is unchanged and correct.)
+- **Warp is distinct from the MCP bridge (refines R4/R6).** Two different local
+  mechanisms SHALL be distinguished: (a) the cluster MCP (`rcac-mcp`) uses SSH as a
+  **background bridge** so the agent works through **pure tool calls** — this is the model
+  for the CLI harnesses (Claude Code, Codex, Gemini CLI, opencode); (b) **Warp** is a
+  desktop terminal in which the **user SSHs into the cluster directly** and the agent
+  **rides that live SSH session**. Warp SHALL NOT be documented as using the cluster MCP;
+  instead the docs SHALL explain how a user can **wire in the `/etc/agents.d` shared
+  context once they have SSH'd to the cluster**.
+- **Settings are RCAC-deployed & enforced, not user-installed (refines R11/R12).** The
+  per-harness settings SHALL be presented as **what RCAC deploys to the system-managed
+  location and enforces** (published for transparency), not as files the user must copy
+  in. Where a harness has a system-managed path (Claude Code
+  `/etc/claude-code/managed-settings.json`, Gemini `/etc/gemini-cli/settings.json`,
+  opencode `/etc/opencode/`) this SHALL be stated as the enforced location; **Codex** has
+  no managed path (a recommended user default — stated honestly); **Warp** has no settings
+  file (a team-managed **Agent Profile**, documented inline — no `AGENTS.md`-style file).
+- **Cluster-side settings carry the docs MCP, not `rcac-mcp` (follow-up, 2026-07-15).**
+  The published settings are **cluster-side** (for an agent running *on the nodes*) and
+  SHALL NOT register `rcac-mcp` — that is a **local-side** SSH bridge that launches via
+  `uvx` (absent from the nodes' default PATH), and an on-cluster agent already has direct
+  shell/Slurm access. The cluster-side settings SHALL instead wire in the hosted, no-auth
+  **documentation** MCP (`https://docs.rcac.purdue.edu/mcp`, `doc_search`/`doc_load`) over
+  plain HTTP, so the agent consults authoritative docs on top of `/etc/agents.d`.
+  `rcac-mcp` remains the **local-side** registration on the Running Agents → Local page.
+
+## Related materials
+
+- **PEARC'26 paper** (the motivating source, three pillars, and Discussion framing to mirror for
+  voice): <https://github.com/glentner/pearc26-hello-computer> — *Hello Computer: HPC in the
+  Agentic Era* (Lentner & Ashish, 2026).
+- **MCP repositories:** <https://github.com/PurdueRCAC/rcac-mcp> ·
+  <https://github.com/PurdueRCAC/globus-mcp> · <https://github.com/PurdueRCAC/rcac-docs-mcp>
+  (hosted at `docs.rcac.purdue.edu/mcp`).
+- **Gold-standard pages to mirror / reuse:**
+  - Hub archetype: `docs/lifesciences/index.md` (tagged hub + grid cards).
+  - Policy archetype: `docs/userguides/anvil/policies.md` + `docs/snippets/resourceuse.md`
+    (`resource_use` macro) — Gautschi currently has **no** `policies.md`.
+  - External-tool → cluster prior art: `docs/lifesciences/guides/vscode.md` (Remote-SSH /
+    ProxyJump into a compute node).
+  - Gautschi facts: `docs/userguides/gautschi/{overview,software,storage}.md`,
+    `run_jobs/{index,queues,directives}.md`.
+  - Reusable macros (`main.py`): `ssh_keys_snippet`, `module_system`, `slurm_general_jobs`,
+    `storage_quota`, `scratch_space`, `resource_use`.
+- **Reference sites** (same MkDocs-Material lineage): docs.tacc.utexas.edu, docs.alcf.anl.gov,
+  docs.ncsa.illinois.edu.
+- Issue: *(none yet — create and back-link if desired).*
diff --git a/spec/agentic-ai-docs/META.md b/spec/agentic-ai-docs/META.md
new file mode 100644
index 00000000..475c58de
--- /dev/null
+++ b/spec/agentic-ai-docs/META.md
@@ -0,0 +1,25 @@
+# META — harness retrospective for agentic-ai-docs
+
+> **Notes to the toolmaker, not to the reader.** Process/skillset feedback captured *while building
+> this job* — orthogonal to `GOAL/PLAN/TECH/REVIEW` (which are about the doc). Each `docs-*` skill's
+> **meta-note step** appends a finding here **only** when a concrete instruction/steering/tooling
+> problem in the *skillset itself* cost something during that step; otherwise it stays silent.
+> `/docs-harness` reads this file to propose fixes (human-gated). **This file is kept out of the
+> blind reviewer's context** (it can reveal author intent). None below == the skills worked.
+
+## F1 — scope/branch-hygiene check is optional, so bundled non-content commits nearly slipped past review
+`origin=docs-review severity=low category=missing-guidance status=open target=.agents/skills/docs-review/SKILL.md`
+- **What happened:** the branch carried nine `[harness]` commits (`.agents/**` + `AGENTS.md`, ~1k
+  lines) alongside the content work. The **blind correctness pass** (Step 2) is scoped to content vs
+  `GOAL.md` and only listed them as "unmapped changes" — it did not surface the real consequence
+  (a squash-merge folds `[harness]` tooling into a content-titled commit on the production trunk).
+  That consequence was caught only because the orchestrator chose to run the **optional** Step 5
+  completeness sub-pass, which can see the appetite and reason about the squash-PR.
+- **Skill cause (not mine):** `docs-review` has no *mandatory* step that checks branch hygiene —
+  whether the diff mixes commit `[category]`s foreign to the feature (e.g. `[harness]` on a content
+  branch) and what a squash merge would do to them. It's left to an optional pass, so by default a
+  material publish-time concern is missed.
+- **Recommended fix:** add a cheap mandatory pre-flight check (Step 1) or correctness-pass item —
+  `git log --oneline main..HEAD`, flag any commit whose `[category]` differs from `{kind}`, and note
+  the squash-fold implication for `docs-publish`. Does **not** weaken any `hammerable:false` gate.
+- **Confidence:** medium · **Effort:** small
diff --git a/spec/agentic-ai-docs/PLAN.md b/spec/agentic-ai-docs/PLAN.md
new file mode 100644
index 00000000..8c7ade5a
--- /dev/null
+++ b/spec/agentic-ai-docs/PLAN.md
@@ -0,0 +1,316 @@
+# PLAN — Agentic AI on RCAC: guidance, MCP tooling, and shared context
+
+> **Status:** Draft for review · **Last updated:** 2026-07-15
+> **Authoritative design.** The *how*. Vision/contract is [`GOAL.md`](GOAL.md); the phased
+> executable roadmap is [`TECH.md`](TECH.md). Backing detail is in [`research/`](research/).
+> Every design element traces to a GOAL R-ID.
+
+## 1. Summary
+
+Build a net-new top-level **Agentic AI** section (hub + guidance + MCP + a mode-organized
+"Running Agents" area + a "Shared Context & Settings" subdir) plus a cross-linked **Using AI
+Agents** chapter in the Gautschi user guide. As a shared exercise, we also *construct* the first
+real Gautschi `/etc/agents.d` context files and per-harness settings, storing them as byte-exact
+canonical files under `docs/snippets/agentic-ai/` and publishing them verbatim via `--8<--` fenced
+includes (proven Jinja-safe). Ten publishable phases, scaffold → content → integration; HPC
+accuracy, accessibility, and build integrity are `hammerable: false`.
+
+## 2. Design
+
+### Archetypes
+
+Three archetypes are in play (see [`style-guide.md`](../../.agents/factory/style-guide.md)):
+
+- **Reference / hub / landing** — `docs/agentic-ai/index.md` and the two subdir `index.md`s.
+  Front-matter: `title` + `tags: [Agentic AI]` (mirror `docs/lifesciences/index.md`); grid-cards
+  body. (Hubs may add `hide: [toc]` if they end up card-only.)
+- **Cluster user-guide article** — the Gautschi `using_ai_agents.md` chapter. Front-matter:
+  `tags: [Gautschi]`, `authors: […]`, and `{% set resource = "gautschi" %}` where it reuses
+  cluster macros.
+- **Policy page** (a lighter variant, mirrored from `docs/userguides/anvil/policies.md`) — the
+  acceptable-use page: `tags` + `authors`, one H1, hand-written sections + `{{ resource_use(…) }}`.
+
+A **novel publishing pattern** (not a new archetype, but new to this repo) carries the verbatim
+context/settings artifacts — see *Reuse* below.
+
+### Page structure (files to create)
+
+**New content pages** under `docs/agentic-ai/`:
+
+| File | H1 / purpose | R-IDs |
+|------|--------------|-------|
+| `index.md` | *Agentic AI at RCAC* — stance (proactive engagement, not prohibition; verify, don't forbid), grid-card nav to subpages | R1 |
+| `acceptable_use.md` | *Acceptable Use & Etiquette* — rules for agents on RCAC systems; reuse `{{ resource_use(resource) }}`; link Purdue IT AUP | R2 |
+| `best_practices.md` | *Best Practices & Limitations* — agent *for research* vs *for operations*; context engineering; verification ("augmented, not outsourced"); caution/blast-radius | R3 |
+| `mcp_servers.md` | *RCAC MCP Servers* — why MCP; the three **actively-developed prototypes** with verified connect commands; `/etc/agents.d` injection; **call out the `rcac-mcp` rename/re-architecture** | R7, R8, R9, R16 |
+| `running_agents/index.md` | *Running Agents* — the two deployment modes explained; card links | R4 |
+| `running_agents/on_cluster.md` | *On the Cluster (Login Nodes)* — five harnesses on login nodes; login-node constraints; Warp = local-only note | R4, R5, R16 |
+| `running_agents/local.md` | *Local, Targeting the Cluster* — two local mechanisms (the `rcac-mcp` SSH bridge for CLI harnesses; Warp's interactive terminal session); **feature Warp prominently (RCAC's recommended harness)** | R4, R6 |
+| `shared_context/index.md` | *Shared Context & Settings* — how `/etc/agents.d` + settings fit; canonical source-of-truth → Puppet + MCP injection; **how to contribute feedback** | R12 |
+| `shared_context/context_files.md` | *Context Files (`/etc/agents.d`)* — the five Gautschi context files, published verbatim | R10, R16 |
+| `shared_context/settings.md` | *Harness Settings & Permissions* — the five per-harness settings, published verbatim; **deny destructive ops + allow-list read-only sanity commands** | R11 |
+
+**New Gautschi chapter:** `docs/userguides/gautschi/using_ai_agents.md` (R13, R16).
+
+**New canonical artifact files** (byte-exact source of truth; under `docs/snippets/agentic-ai/`,
+excluded from nav by `exclude_docs: snippets/`, `--8<--`-included — never nav pages):
+
+```
+docs/snippets/agentic-ai/
+  agents.d/unix.md          agents.d/filesystems.md   agents.d/lmod.md
+  agents.d/slurm.md         agents.d/policies.md
+  agents.d/AGENTS.md        # concatenated canonical context (the assembled file harnesses read)
+  claude/settings.json      codex/config.toml         gemini/settings.json
+  opencode/opencode.json
+```
+
+> **Human-review amendment (2026-07-15):** Warp has **no settings file** — its policy is
+> a team-managed **Agent Profile** documented *inline* on the settings page (the earlier
+> `warp/AGENTS.md` artifact was removed as misleading). See the amendments note in §5.
+
+### Navigation placement (exact)
+
+Insert a **top-level section after Life Sciences** (`mkdocs.yml:361`, before the commented Tags line):
+
+```yaml
+  - Agentic AI:
+    - agentic-ai/index.md
+    - Acceptable Use & Etiquette: agentic-ai/acceptable_use.md
+    - Best Practices & Limitations: agentic-ai/best_practices.md
+    - MCP Servers: agentic-ai/mcp_servers.md
+    - Running Agents:
+      - agentic-ai/running_agents/index.md
+      - On the Cluster (Login Nodes): agentic-ai/running_agents/on_cluster.md
+      - Local (over SSH): agentic-ai/running_agents/local.md
+    - Shared Context & Settings:
+      - agentic-ai/shared_context/index.md
+      - Context Files (/etc/agents.d): agentic-ai/shared_context/context_files.md
+      - Harness Settings & Permissions: agentic-ai/shared_context/settings.md
+```
+
+Insert the Gautschi chapter **between Compiling Source Code (`mkdocs.yml:144`) and FAQs (`:145`)**:
+
+```yaml
+      - Using AI Agents: userguides/gautschi/using_ai_agents.md
+```
+
+**Nav is added incrementally, in lockstep with page creation** (a nav line pointing at a missing
+file, or a page absent from nav, both fail `--strict`). Reading/nav order == phase order. Breadcrumbs
+regenerate at the integration phase (`.venv/bin/python tools/generate_breadcrumbs.py`).
+
+### Reuse (macros, snippets, gold-standard pages)
+
+- **Verbatim-publishing pattern** (research 02, proven): each artifact is a real file under
+  `docs/snippets/agentic-ai/…`, embedded in a fenced block:
+  ````markdown
+  ```json title="~/.claude/settings.json"
+  --8<-- "docs/snippets/agentic-ai/claude/settings.json"
+  ```
+  ````
+  `--8<--` content is spliced **after** the Jinja pass, so literal `{{`/`{%` never breaks the build.
+  Single source of truth, syntax-highlighted. Fence languages: `json` (Claude/Gemini/opencode),
+  `toml` (Codex), `markdown` (agents.d/*). *(Warp has no published settings file — see §5
+  amendment; its policy is an inline Agent Profile.)*
+- **Macros for background prose** (call, don't hardcode): `{{ resource_use(resource) }}` (AUP block,
+  acceptable-use page), `{{ module_system(resource) }}`, `{{ slurm_general_overview(resource) }}`,
+  `{{ ssh_keys_snippet(resource) }}`, `{{ storage_quota(resource) }}`, `{{ scratch_purge(resource) }}`
+  — chiefly on the Gautschi chapter and where HPC background is summarized. **Do not** source the
+  *context files* from these macros (they emit generic RCAC text; the context files must be authored
+  from verified Gautschi facts — research 03).
+- **Gold-standard pages to mirror:** `docs/lifesciences/index.md` (hub + grid cards);
+  `docs/userguides/anvil/policies.md` (policy page); `docs/lifesciences/guides/vscode.md`
+  (external-tool → login → compute prior art, for the local mode).
+
+### Assets
+
+None required for a first cut (text + code blocks + admonitions + grid cards). If an architecture
+diagram is added later for the local-first MCP+SSH flow, it goes under
+`docs/assets/images/agentic-ai/` with an absolute path and descriptive alt text (deferred; not a
+GOAL requirement).
+
+### Cross-links & tags
+
+- Tag new pages `Agentic AI`; the Gautschi chapter `Gautschi`.
+- Hub grid-cards → each subpage; each subpage ends with a back-link to its hub.
+- Cross-links: `running_agents/local.md` ↔ `mcp_servers.md`; `mcp_servers.md` ↔
+  `shared_context/context_files.md` (the `/etc/agents.d` injection); `shared_context/settings.md` ↔
+  `running_agents/*` (where to install each config); Gautschi chapter ↔ the top-level section.
+  **Sibling cross-links are added in the integration phase** (P10) so every intermediate build is
+  `--strict`-clean; each content phase only back-links to an already-existing hub.
+
+### Accessibility plan (R15)
+
+One `#` H1 per page; headings descend without skipping; grid-card links use descriptive text (not
+"click here"); every table has a header row; no meaning by color alone; any future image gets
+meaningful alt text. Code blocks carry a `title=` label. This is content-level a11y (owned on
+`main`); no theme/CSS/`overrides` changes (invariants §2).
+
+### Requirement → design map
+
+| R-ID | Design element(s) that satisfy it |
+|------|-----------------------------------|
+| R1 | `docs/agentic-ai/index.md` hub + top-level `Agentic AI` nav section |
+| R2 | `agentic-ai/acceptable_use.md` (policy archetype + `{{ resource_use }}` + Purdue AUP link) |
+| R3 | `agentic-ai/best_practices.md` (research-vs-ops, context engineering, verification, caution) |
+| R4 | `running_agents/{index,on_cluster,local}.md` organized by deployment mode, five harnesses each |
+| R5 | `running_agents/on_cluster.md` login-node constraints (mirrors Gautschi Running Jobs) |
+| R6 | `running_agents/local.md` local-first architecture (no new credentials/hosted infra) |
+| R7 | `mcp_servers.md` — three servers, focus + repo links, "why MCP" |
+| R8 | `mcp_servers.md` — HPC server reads `/etc/agents.d` over SSH, injects as context |
+| R9 | `mcp_servers.md` — install/connect commands verified against the live repos (research 04) |
+| R10 | `docs/snippets/agentic-ai/agents.d/*.md` (Gautschi-accurate; `/home` ZFS · `/depot` GPFS · `/scratch` Lustre; quotas via `myquota`) + `shared_context/context_files.md` |
+| R11 | `docs/snippets/agentic-ai/{claude,codex,gemini,opencode}/…` (deny destructive ops + **allow-list read-only sanity commands**) + `shared_context/settings.md`; Warp = inline Agent-Profile policy (no file). Presented as **cluster-side, RCAC-deployed/enforced** at the system-managed paths (transparency), not user-installed. Cluster-side settings wire in the **docs HTTP MCP** (`docs.rcac.purdue.edu/mcp`), **not** `rcac-mcp` (which is local-side, on the Local page) — see §5 amendments 4–5 |
+| R12 | `shared_context/index.md` — how it fits, source-of-truth → Puppet + MCP, feedback channels |
+| R13 | `docs/userguides/gautschi/using_ai_agents.md` + Gautschi nav entry + cross-links |
+| R14 | Every phase adds its nav line; every `verify:` runs `mkdocs build --strict` |
+| R15 | a11y plan above; final sweep in P10 |
+| R16 | context files/MCP commands/Gautschi facts authored from research 03/04; verified P4/P7/P9/P10 |
+
+## 3. Invariant gate (constitution check)
+
+Checked against [`invariants.md`](../../.agents/factory/invariants.md) before research and again
+after this design. Touched sections and how the design honors each:
+
+- **§1 branch/deploy** — all work on `feature/agentic-ai-docs`; squash PR to `main` at publish. No
+  direct `main`/`dev` edits.
+- **§2 dev-only a11y layer** — **untouched.** No edits to `docs/stylesheets/`, `overrides/`,
+  `a11y.js`, or any force-preserved path. Content-level a11y only.
+- **§3 generated-content firewall** — no hand-edits to catalogs or `breadcrumbs.json`; breadcrumbs
+  are **regenerated** via `tools/generate_breadcrumbs.py` after the nav change. `docs/snippets/
+  agentic-ai/*` are hand-authored source, not generated outputs.
+- **§4 nav-is-manual** — every new page gets a `mkdocs.yml` `nav:` entry in the same phase; snippet
+  files are correctly *not* in nav (excluded, `--8<--`-only).
+- **§5 links relative / assets absolute** — page-to-page links relative; any asset absolute.
+- **§6 front-matter per archetype** — hub (`title`+`tags`), policy page (`tags`+`authors`),
+  userguide chapter (`tags`+`authors`+`{% set resource %}`).
+- **§7 macros / Jinja escaping** — verbatim config is `--8<--`-included (post-Jinja, immune);
+  background prose reuses macros. No literal `{{`/`{%` pasted into page source unescaped.
+- **§8 build integrity** — each phase gates on `mkdocs build --strict | strict_check.py` (zero new
+  warnings vs the 7-line baseline).
+- **§9 content WCAG** — a11y plan above; finalized P10.
+- **§10 per-cluster parallelism** — a Gautschi-only "Using AI Agents" chapter creates deliberate
+  per-cluster asymmetry; **explicitly scoped** as a pilot in GOAL non-goals (other clusters follow).
+  See deviation table.
+- **§11 HPC accuracy** — context files/MCP/Gautschi facts authored strictly from verified research;
+  the two known Gautschi doc-errors (`--partition=a10`, `-A standby`) are excluded by design;
+  volatile numbers (quotas) are deferred to `myquota`/`slist` rather than hardcoded.
+- **§12 commit/PR** — `[feature] …` subjects, no `Co-Authored-By`; squash PR; `Closes #NN` if an
+  issue is filed.
+
+### Deviation justifications
+
+| Deviation | Why needed | Simpler alternative rejected because |
+|-----------|-----------|--------------------------------------|
+| Gautschi-only `Using AI Agents` chapter (per-cluster asymmetry, §10) | GOAL scopes this feature to Gautschi as the pilot; the cross-cluster home is the top-level section | Adding the chapter to all 8 clusters now blows the appetite and would duplicate not-yet-verified per-cluster facts; scoped as a follow-up in GOAL non-goals |
+| New verbatim-config publishing pattern (`--8<--` fenced includes from `docs/snippets/agentic-ai/`) | R10/R11 require publishing real, byte-exact config as the single source of truth | Hand-pasting config into pages needs `{% raw %}` and duplicates content (drift); this pattern is proven `--strict`-safe (research 02) and stays within §7 (snippets are a sanctioned mechanism) |
+
+## 4. Rabbit holes (resolved)
+
+- **Will publishing verbatim config with literal `{{`/`{%` break the macros build?** → No.
+  `--8<--` splices files *after* the Jinja pass; proven with an isolated `mkdocs build --strict`
+  (exit 0) ([`research/02-macros-and-jinja.md`](research/02-macros-and-jinja.md)).
+- **What are the *real* Gautschi partitions/QOS/paths/commands?** → Extracted with citations, plus
+  an `[UNCONFIRMED]` list and two doc-errors to avoid
+  ([`research/03-gautschi-facts.md`](research/03-gautschi-facts.md)).
+- **Do the MCP servers exist, and what are the real connect commands/tools?** → Yes; all three
+  public, `uvx`-installed, verified configs + tool lists
+  ([`research/04-mcp-servers.md`](research/04-mcp-servers.md)).
+- **What is each harness's settings/permissions/MCP/context-file contract?** → Full per-harness
+  table, incl. system/managed enforcement points and Warp's GUI-only caveat
+  ([`research/05-harness-configs.md`](research/05-harness-configs.md)).
+- **What should the `/etc/agents.d` files contain, and how do they reach each harness?** → Per-file
+  outlines + the concatenate-to-`AGENTS.md` mapping
+  ([`research/06-context-and-conventions.md`](research/06-context-and-conventions.md)).
+- **Where exactly does this live in the site?** → Top-level after Life Sciences + Gautschi chapter;
+  exact nav lines ([`research/01-site-architecture.md`](research/01-site-architecture.md)).
+
+## 5. Risks & open questions
+
+- **`cluster-mcp` / HPC-only refocus is [UNVERIFIED] publicly** (research 04): the public
+  `rcac-mcp` is a prototype that still bundles docs tools; the plugin architecture
+  (`cluster-mcp[slurm,lmod,…]`) has no public trace. **Human confirmed the framing (2026-07-15):**
+  treat all three servers as **actively-developed working prototypes** and **explicitly call out the
+  planned rename/re-architecture of `rcac-mcp`** — as a stated direction, not shipped fact. No longer
+  a blocker; keep the "planned/evolving" labeling.
+- **Gautschi `[UNCONFIRMED]` facts** — exact home/scratch quotas (illustrative only), Depot mount
+  path, OpenMPI version, default shell, availability of `sinfo`/`sacct`/`jobinfo`, a Purdue AUP
+  direct URL. **Mitigation:** context files tell the agent to run `myquota`/`findscratch`/`slist`
+  instead of hardcoding; state only verified facts; use the AUP block from `resource_use` / link
+  Purdue IT Policy V.4.1 (from `resourceuse.md`). **Filesystem tech now confirmed** (human): `/home`
+  ZFS · `/depot` GPFS · `/scratch` Lustre.
+- **Warp is a local desktop GUI, not a headless CLI** — cannot be installed on a login node
+  (research 05) — **but it is RCAC's *recommended* harness for most users** (human, 2026-07-15).
+  **Mitigation:** give Warp **first-class, prominent** treatment in the **local (over-SSH)** guidance
+  — tell the story of using it well ("run on your workstation, SSH in"). **Superseded by the §5
+  human-review amendment (2026-07-15):** Warp does **not** use the cluster MCP and has **no settings
+  file** — represent its policy as an **inline, team-managed Agent Profile** (the `warp/AGENTS.md`
+  artifact was removed), with shared context wired in from `/etc/agents.d` once SSH'd; still note the
+  Run-until-completion denylist bypass.
+- **Enforced-permissions policy is a v0 starting point** (GOAL clarification) — label it as such and
+  invite feedback. It must both **deny** destructive ops (`rm -rf`, `sudo`) **and allow-list common
+  read-only sanity commands** (`myquota`, `slist`, `sfeatures`, `module list`, `module avail`, …) so
+  agents run them eagerly without prompting (human, 2026-07-15). **Container model is Apptainer, not
+  Docker:** RCAC's Apptainer config **auto bind-mounts `/home`, `/depot`, `/scratch`** → limited
+  protection (editing files is the real risk; bind-mounts disable-able on explicit invocation) — the
+  caution/best-practices content must reflect this, not imply Docker sandboxing. The real
+  config-management enforcement points are Claude `/etc/claude-code/managed-settings.json` and Gemini
+  `/etc/gemini-cli/settings.json`.
+- **`check_paths:false`** — a mistyped `--8<--` path fails **silently** (empty block, no `--strict`
+  error). **Mitigation:** each context/settings phase greps the built `site/` for a sentinel token.
+- **Feedback channel** for context corrections — default to the RCAC-Docs GitHub issues +
+  rcac-help@purdue.edu + Discord (from AGENTS.md contact); confirm at draft.
+
+### Human-review amendments (2026-07-15)
+
+Applied after the human read the fully-drafted section (see GOAL.md → "Resolved during
+human review"). Acceptance criteria unchanged; these adjust *how* the design is realized:
+
+1. **Paper as reference, not lead.** The hub no longer opens with the paper / "mostly
+   harmless"; the paper is a measured **footer reference** linking the GitHub replication
+   package. DOI deferred until the paper is on the ACM DL.
+2. **Measured tone.** "mostly harmless" and other pop-culture framings removed
+   throughout; the single **"Tea, Earl Grey, hot"** prompting illustration is retained.
+3. **Warp ≠ MCP bridge (refines R6).** The *local* mode has **two mechanisms**: (a)
+   `rcac-mcp` as a background SSH bridge with pure tool-calling (Claude Code, Codex,
+   Gemini CLI, opencode); (b) **Warp**, a desktop terminal where the user SSHs in and the
+   agent rides the live session. Warp does **not** register `rcac-mcp`; shared context is
+   wired in from `/etc/agents.d` once SSH'd. `mcp_servers.md`, `running_agents/index.md`,
+   `running_agents/on_cluster.md`, and `running_agents/local.md` all reworked to reflect
+   this.
+4. **Settings framed as enforced, not user-installed (refines R11/R12).**
+   `shared_context/settings.md` now presents the policy as **RCAC-deployed to the
+   system-managed path and enforced** (Claude `/etc/claude-code/managed-settings.json`,
+   Gemini `/etc/gemini-cli/settings.json`, opencode `/etc/opencode/`), with honest
+   caveats: **Codex** has no managed path (recommended user default), **Warp** has no
+   settings file (inline team-managed Agent Profile). The `warp/AGENTS.md` snippet was
+   deleted.
+5. **Cluster-side settings ≠ local-side MCP (follow-up, 2026-07-15).** The published
+   settings are **cluster-side** and no longer register `rcac-mcp` (a local-side SSH
+   bridge needing `uvx`, which is not on the nodes' PATH, and pointless for an agent
+   already on the cluster). They instead wire in the hosted, no-auth **documentation**
+   MCP `https://docs.rcac.purdue.edu/mcp` over HTTP (Gemini `httpUrl`, Codex `url`,
+   opencode `type:"remote"`, Claude via `.mcp.json` `type:"http"`). `rcac-mcp` stays on
+   the Local page as the local-side registration. `settings.md` now states the
+   cluster-side/local-side split explicitly.
+
+## 6. Verification strategy
+
+Seeds each phase's `verify:` in `TECH.md`:
+
+- **Build integrity:** `.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py`
+  (no new warnings vs `strict-baseline.txt`) — every phase.
+- **Nav:** `grep` the phase's page path in `mkdocs.yml` (no "not in nav"/"missing file" warning).
+- **Verbatim includes (P4/P7/P8):** `grep -rq <sentinel> site/agentic-ai/…` to defeat the
+  `check_paths:false` silent-empty footgun (e.g. `RCAC_SCRATCH`, `mcpServers`).
+- **Render:** `mkdocs serve` and eyeball layout (grid cards, tabs, admonitions, macro expansion,
+  code blocks non-empty) — in the phase steps where layout matters.
+- **Front-matter:** matches the archetype (hub `title`+`tags`; policy/userguide `tags`+`authors`).
+- **Accessibility:** images (if any) have alt text; headings descend; tables have header rows;
+  descriptive link text — final sweep P10.
+- **HPC accuracy:** every factual claim checked against a gold-standard Gautschi page or
+  `research/03`; MCP commands against `research/04`; **no `--partition=a10`, no `-A standby`**;
+  volatile numbers deferred to runtime commands.
+
+---
+
+*Backing research: [`research/00-digest.md`](research/00-digest.md).*
diff --git a/spec/agentic-ai-docs/REVIEW.md b/spec/agentic-ai-docs/REVIEW.md
new file mode 100644
index 00000000..22a1b328
--- /dev/null
+++ b/spec/agentic-ai-docs/REVIEW.md
@@ -0,0 +1,159 @@
+# REVIEW — Agentic AI on RCAC: guidance, MCP tooling, and shared context
+
+> Adversarial QA by `docs-review`, run in an isolated/clean context. The correctness pass grades the
+> branch diff against [`GOAL.md`](GOAL.md) + the invariants + the style guide **only** — it does not
+> see `PLAN.md`/`TECH.md` (avoids grading-its-own-homework / plan-sycophancy). Every finding cites
+> **evidence** — a build/render/link result or a direct read of the diff — not an assertion.
+
+- **Reviewed commit:** d7465e42  ·  **Base:** main  ·  **Date:** 2026-07-15
+- **Verdict:** approved
+- **Cycle:** 1 of ≤3 (escalate to human on non-convergence)
+
+## Verification run
+
+Commands actually executed / pages actually rendered, and their outcomes (the spine of the review):
+
+- `.venv/bin/mkdocs build --strict 2>&1 | .venv/bin/python .agents/factory/bin/strict_check.py`
+  → **PASS: no new --strict warnings (7 present, all in baseline of 7). EXIT_STATUS=0.** Independently
+  re-run by the orchestrator with the identical result. `strict-baseline.txt` diff is a comment-only
+  `python3`→`.venv/bin/python` edit — no warning entries added/removed; the gate was not weakened.
+- `.venv/bin/mkdocs serve` + built-`site/` inspection of the new pages → snippet `--8<--` includes
+  expanded verbatim (`grep "Rocky Linux 9" site/…/context_files/index.html` → 2 hits), macros
+  rendered (no leaked raw `{{`/`{%`), admonitions/tables/code blocks intact, partition table has a
+  header row.
+- nav check: all **11** new pages present in `mkdocs.yml` `nav:` — 10 under `docs/agentic-ai/**`
+  (`mkdocs.yml:363-375`) + `docs/userguides/gautschi/using_ai_agents.md` (`mkdocs.yml:145`); none
+  orphaned; `--strict` raises no "not included in nav" warning.
+- front-matter / a11y spot-check → hub/landing pages carry `hide:`; no content images (alt vacuously
+  satisfied); no absolute `](/…)` page-to-page links; one H1 per page; headings descend without skips.
+
+## Requirement → evidence matrix
+
+Bidirectional traceability. Every R-ID R1–R16 has an implementing change and was verified by an
+executed command or a direct render/diff read.
+
+| R-ID | Implemented by (file) | Verified how | Status |
+|------|------------------------|--------------|--------|
+| R1 | `agentic-ai/index.md:11-15,34-81`; `mkdocs.yml:363-375` | render + nav grep; stance present, cards link every subpage | ✅ |
+| R2 | `agentic-ai/acceptable_use.md:21-71` | render; login-node / Slurm `--time` / world-readable / destructive-confirm rules + Purdue IT-16 link (via `resource_use`) | ✅ |
+| R3 | `agentic-ai/best_practices.md:17-107` | render; research-vs-ops, context-eng, augmented-not-outsourced, blast-radius | ✅ |
+| R4 | `running_agents/index.md:9-25`; `on_cluster.md`; `local.md` | render; two modes, all five harnesses in each | ✅ |
+| R5 | `running_agents/on_cluster.md:23-35` | diff vs gold-standard `run_jobs/queues.md` login-node guidance | ✅ |
+| R6 | `running_agents/local.md:25-37` | render; own-env / existing-SSH / no-new-creds / no-hosted-infra | ✅ |
+| R7 | `mcp_servers.md:10-19,21-26,38/113/147,100-109` | render; 3 repos, why-MCP, prototype admonition, `cluster-mcp[…]` rename call-out | ✅ |
+| R8 | `mcp_servers.md:89-98` | render; `/etc/agents.d`, "configurable location", injected over SSH | ✅ |
+| R9 | `mcp_servers.md:80-86,140-143,154-158` + `uvx` blocks | **PLAUSIBLE** — private repos unreachable at review time; nothing looks fabricated (see F1) | ⚠️ |
+| R10 | `snippets/agentic-ai/agents.d/{unix,filesystems,lmod,slurm,policies}.md` | render verbatim; HPC facts cross-checked vs gold-standard; filesystem-tech labels PLAUSIBLE (F2) | ✅ (tech labels ⚠️) |
+| R11 | `snippets/agentic-ai/{claude,codex,gemini,opencode}/*` + Warp inline in `settings.md` | read; deny `rm -rf`/`sudo`, allow-list `myquota`/`slist`/`sfeatures`/`module list`/`avail`; Codex caveat (F3) | ✅ |
+| R12 | `shared_context/index.md:9-52` | render; injected/enforced, canonical SoT copied to `/etc/agents.d`, feedback path | ✅ |
+| R13 | `userguides/gautschi/using_ai_agents.md`; `mkdocs.yml:145` | render + nav; cross-linked up/down with the section | ✅ |
+| R14 | `mkdocs.yml`; strict gate | **CONFIRMED** — 11/11 in nav, gate exit 0, no new warnings | ✅ |
+| R15 | all new pages | render; relative links / absolute assets / heading descent / table headers | ✅ |
+| R16 | new pages + context files | partitions/QOS/host/modules CONFIRMED vs gold-standard; tech-labels + MCP tool-names PLAUSIBLE tail | ✅ (tail ⚠️) |
+
+**Key refinements (part of the contract):** all verified SATISFIED — "mostly harmless"/"cross the
+streams"/"kung fu" = 0 hits; "Tea, Earl Grey, hot" = exactly 1 (`best_practices.md:39`); PEARC'26
+paper is a footer note (`index.md:89-91`), not the lead; Warp documented as riding a live user SSH
+session, **not** the `rcac-mcp` bridge (`local.md:103-110`); CLI harnesses use the `rcac-mcp` SSH
+bridge for local mode; settings framed as RCAC-deployed/enforced with correct managed paths (Codex
+honestly has none; Warp is an inline Agent Profile); cluster-side settings register only the hosted
+docs MCP (`docs.rcac.purdue.edu/mcp`), never `rcac-mcp`; Apptainer-not-Docker with auto-bind-mount
+limited-protection caveat present.
+
+Unmapped changes (possible scope creep): the `.agents/**` + `AGENTS.md` `[harness]` commits — see
+**Completeness sub-pass** and **Human-gate triggers** below. No `docs/**` content scope-creep; no
+non-goal leakage (Gautschi-only; no theme/CSS/JS; no catalog hand-edits; `breadcrumbs.json`
+regenerated as expected; no blog post; no MCP-server code).
+
+## Findings
+
+No **CONFIRMED** defects. All items below are **PLAUSIBLE** (human triage) or minor notes — none
+auto-loops to `docs-draft`.
+
+### [LOW/PLAUSIBLE] F1 — MCP tool names & install commands not verifiable against live repos
+- **Where:** `docs/agentic-ai/mcp_servers.md:80-86` (rcac-mcp tools), `140-143` (globus-mcp tools),
+  `154-158` (`doc_search`/`doc_load`), and the `uvx git+https://…` / `--ssh-host` / `RCAC_SSH_HOST`
+  blocks.
+- **Concern:** the review sandbox cannot reach `github.com/PurdueRCAC/{rcac-mcp,globus-mcp,rcac-docs-mcp}`.
+  Nothing looks fabricated and the commands are internally consistent, but R9 requires verification
+  against the live repos. Minor org-case cosmetics: prose links use `PurdueRCAC/…`, `uvx` args use
+  `purduercac/…` (GitHub redirects both — not a defect).
+- **Authoritative source to check:** the three public repos (a maintainer with access confirms the
+  tool lists and the `--ssh-host`/`RCAC_SSH_HOST` flags match the shipped servers).
+
+### [LOW/PLAUSIBLE] F2 — filesystem *technology* labels not on the gold-standard Gautschi storage page
+- **Where:** `docs/snippets/agentic-ai/agents.d/filesystems.md` — asserts `/home`=ZFS, `/scratch`=Lustre,
+  `/depot`=GPFS.
+- **Concern:** `docs/userguides/gautschi/storage.md` does not state these technologies; corroborated
+  only indirectly (`docs/snippets/home_directory.md` mentions ZFS; Anvil pages mention GPFS/Lustre).
+- **Note (mitigates):** these exact labels are the **human-corrected authoritative facts recorded in
+  `GOAL.md`** ("Filesystem technologies (authoritative, human-corrected): `/home` is ZFS, `/depot` is
+  GPFS, `/scratch` is Lustre") — i.e. already confirmed by the human during shaping. Residual risk is
+  low; a confirming nod at publish is sufficient.
+
+### [LOW] F3 — Codex permission encoding is coarser than the other harnesses (honest, defensible)
+- **Where:** `docs/snippets/agentic-ai/codex/config.toml`.
+- **Note:** Codex has no per-command allow/deny list, so the file relies on `approval_policy` /
+  `sandbox_mode` and states this honestly — inventing allow/deny syntax would violate R9. "Deny
+  login-node heavy compute" is carried by the context files, not the permission JSON. Defensible;
+  recorded for transparency, not a defect.
+
+## Human-gate triggers
+
+No CONFIRMED finding touches a high-impact file, so no **mandatory** human sign-off gate is triggered
+by a *defect*. Two advisory triggers apply:
+
+1. **Advisory (rubric §"Mandatory human sign-off gate"):** two **PLAUSIBLE HPC/accuracy** items
+   (F1 MCP tool-names/commands; F2 filesystem-tech labels) remain on what will be a **new,
+   high-traffic section that auto-deploys to production within ~5 minutes with no staging gate**. A
+   brief human eyeball of those two specifics before `docs-publish` is advisable. Nothing blocks.
+2. **Publish-time scope decision (from the completeness sub-pass):** nine `[harness]` commits touch
+   the high-impact-adjacent factory tooling (`.agents/**`) and `AGENTS.md`. They do **not** touch the
+   published site, but a squash-merge would fold them into a single content-titled commit on `main`.
+   This is a human decision at `/docs-publish` (split into a separate PR / use a merge commit /
+   accept the fold) — see below.
+
+## Optional completeness sub-pass (separate reviewer; saw `TECH.md`)
+
+- **All 10 content phases (P1–P10) shipped**; each phase marked `done` has its deliverable present in
+  the diff (no done-but-absent red flags). Every R-ID R1–R16 maps to ≥1 shipped phase.
+- **One planned file deliberately trimmed:** `docs/snippets/agentic-ai/warp/AGENTS.md` was dropped
+  during the human-review pass because Warp has no settings file; R11's "all five harnesses" is
+  satisfied for Warp inline (documented, justified trim — commit `66642d3f`, not a silent drop).
+- **Scope-creep — `.agents/**` + `AGENTS.md` (`~1k lines / 24 files`, 9 `[harness]` commits):**
+  legitimate self-improvement-loop harness work (added `docs-harness`, `META.md`/`meta_status.py`/
+  `harness-log.md`, standardized on `.venv`, hardened the build gate on ERRORs), correctly
+  `[harness]`-categorized — but **outside this feature's content appetite** and co-developed on the
+  content branch. **Squash-PR implication:** `docs-publish` squashes to `main`, collapsing all 26
+  commits into one content-titled commit and losing the `[harness]` categorization / mixing tooling
+  with published content. Recommend a human decision at publish: split the harness work into its own
+  PR (merged first), or use a non-squash merge — but AGENTS.md mandates a squash PR, so this needs a
+  human call.
+- **Non-goal leakage:** none on the content side.
+- **Completeness verdict:** content **COMPLETE**; overall **SCOPE-CONCERN** due to the bundled
+  harness commits.
+
+## Post-rebase integration & re-verification (2026-07-15)
+
+The review (cycle 1) was conducted while local `main` was fast-forwarded to the unmerged PR #273
+factory branch. After PR #273 was merged to `origin/main` (merge commit `74ff3f54`, preserving the
+8 factory SHAs), this branch was reintegrated onto the true trunk:
+
+- **Rebase:** `git rebase origin/main` replayed our **26** commits and **auto-dropped** the 8 PR #273
+  factory commits (now ancestors of `origin/main`). **Zero conflicts** — the only two overlap files,
+  `mkdocs.yml` (Agentic AI nav vs origin's Negishi nav edits) and the generated `breadcrumbs.json`,
+  merged cleanly. `tools/generate_breadcrumbs.py` re-run afterward produced **no diff**, confirming
+  the merged breadcrumbs match the final nav. The reviewed content is byte-identical post-rebase; the
+  cycle-1 findings all still hold. Pre-rebase HEAD preserved at branch `backup/agentic-ai-docs-prerebase`.
+- **Build re-verified on the true base:** `.venv/bin/mkdocs build --strict | strict_check.py` →
+  **PASS, 0 warnings present.** Origin's `4f3e3574 "Fix warnings for --strict building"` fixed all 7
+  pre-existing baseline warnings, so `.agents/factory/strict-baseline.txt` was trimmed to **empty**
+  (commit `b8c6a6c3`) — a gate-*strengthening* change (any warning now fails), per the file's own
+  MAINTENANCE note. This resolves the "unmapped `.agents/**` changes" note above by one more entry
+  and does not weaken any `hammerable:false` gate.
+- **`last_reviewed_commit`** advanced to `b8c6a6c3` (the last content/harness commit; this REVIEW/TECH
+  bookkeeping commit sits on top as the tip, matching the factory's established pattern).
+- **Scope note still stands for `/docs-publish`:** the branch is now cleanly our 26 commits on
+  `origin/main`, but it still bundles the 9 in-feature `[harness]` improvements with the content — the
+  squash-vs-merge-commit decision (preserve `[harness]`/`[content]`/`[feature]` categories, or fold)
+  remains a human call at publish. The 8 PR #273 factory commits are no longer part of this diff.
diff --git a/spec/agentic-ai-docs/TECH.md b/spec/agentic-ai-docs/TECH.md
new file mode 100644
index 00000000..0f693250
--- /dev/null
+++ b/spec/agentic-ai-docs/TECH.md
@@ -0,0 +1,434 @@
+---
+slug: agentic-ai-docs
+title: 'Agentic AI on RCAC: guidance, MCP tooling, and shared context'
+kind: feature
+appetite: big
+status: in_review
+branch: feature/agentic-ai-docs
+base: main
+current_phase: done
+last_updated: '2026-07-15'
+phases:
+- id: P1
+  name: 'Scaffold: section hub + top-level nav anchor'
+  status: done
+  satisfies:
+  - R1
+  depends_on: []
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'agentic-ai/index.md' mkdocs.yml
+- id: P2
+  name: Acceptable Use & Etiquette page
+  status: done
+  satisfies:
+  - R2
+  depends_on:
+  - P1
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'acceptable_use.md' mkdocs.yml
+- id: P3
+  name: Best Practices & Limitations page
+  status: done
+  satisfies:
+  - R3
+  depends_on:
+  - P1
+  parallel: false
+  hammerable: true
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'best_practices.md' mkdocs.yml
+- id: P4
+  name: MCP Servers page (rcac-mcp / globus-mcp / rcac-docs-mcp)
+  status: done
+  satisfies:
+  - R7
+  - R8
+  - R9
+  - R16
+  depends_on:
+  - P1
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'mcp_servers.md' mkdocs.yml
+- id: P5
+  name: 'Running Agents: overview + on-cluster (login nodes)'
+  status: done
+  satisfies:
+  - R4
+  - R5
+  depends_on:
+  - P1
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'running_agents/on_cluster.md' mkdocs.yml
+- id: P6
+  name: 'Running Agents: local, targeting the cluster (MCP + SSH)'
+  status: done
+  satisfies:
+  - R4
+  - R6
+  depends_on:
+  - P1
+  - P5
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'running_agents/local.md' mkdocs.yml
+- id: P7
+  name: 'Shared context: hub + build/publish the 5 /etc/agents.d files'
+  status: done
+  satisfies:
+  - R10
+  - R12
+  - R16
+  depends_on:
+  - P1
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'shared_context/context_files.md' mkdocs.yml && grep -rq RCAC_SCRATCH
+    site/agentic-ai/shared_context/
+- id: P8
+  name: Build/publish per-harness settings & permissions (all five)
+  status: done
+  satisfies:
+  - R11
+  - R12
+  depends_on:
+  - P1
+  - P7
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'shared_context/settings.md' mkdocs.yml && grep -rq mcpServers site/agentic-ai/shared_context/
+- id: P9
+  name: Gautschi 'Using AI Agents' chapter
+  status: done
+  satisfies:
+  - R13
+  - R16
+  depends_on:
+  - P1
+  - P4
+  - P5
+  - P6
+  - P7
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && grep -q 'using_ai_agents.md' mkdocs.yml
+- id: P10
+  name: 'Integration: hub cards, cross-links, breadcrumbs, a11y + accuracy sweep'
+  status: done
+  satisfies:
+  - R14
+  - R15
+  - R16
+  depends_on:
+  - P1
+  - P2
+  - P3
+  - P4
+  - P5
+  - P6
+  - P7
+  - P8
+  - P9
+  parallel: false
+  hammerable: false
+  hill: uphill
+  verify: .venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+    && .venv/bin/python tools/generate_breadcrumbs.py && grep -q 'Agentic AI' mkdocs.yml
+review:
+  last_reviewed_commit: b8c6a6c3
+  verdict: approved
+  blocked_reason: ''
+---
+# TECH.md — Agentic AI on RCAC
+
+The **context engine and finite-state machine** for authoring this job. The YAML frontmatter above
+is the resume ground-truth (read it with
+`python3 .agents/factory/bin/next_phase.py spec/agentic-ai-docs/TECH.md`); the per-phase checklists
+below are the work. `docs-draft` executes the next actionable phase, runs its `verify:`, updates
+state via `set_phase.py`, and makes one atomic content+state commit. Run from the repo root with the
+project env active.
+
+- **Vision / requirements (locked):** [`GOAL.md`](GOAL.md) — R-IDs are the contract.
+- **Authoritative design:** [`PLAN.md`](PLAN.md).
+- **Backing research:** [`research/00-digest.md`](research/00-digest.md) + the six briefs.
+
+## Conventions (apply to every phase)
+
+- Voice/archetype/load-bearing rules from [`../../AGENTS.md`](../../AGENTS.md),
+  [`style-guide.md`](../../.agents/factory/style-guide.md), and
+  [`invariants.md`](../../.agents/factory/invariants.md).
+- One phase per `docs-draft` invocation; one atomic commit with **both** content and the `TECH.md`
+  state change. Subjects: `[feature] Draft agentic-ai-docs P<n>: …`. **No `Co-Authored-By`.**
+- **Adding a page updates `mkdocs.yml` `nav:` in the same commit** (else orphaned / missing-file
+  `--strict` failure). Add nav lines in reading order (see PLAN §2). Regenerate breadcrumbs at P10
+  (`.venv/bin/python tools/generate_breadcrumbs.py`).
+- **Verbatim artifacts** (`docs/agentic-ai` pages that show config) use the proven pattern: a real
+  file under `docs/snippets/agentic-ai/…` embedded in a fenced block via `--8<--` (post-Jinja, so
+  literal `{{`/`{%` is safe). `check_paths:false` fails silently → each such phase greps the built
+  `site/` for a sentinel and eyeballs `mkdocs serve`.
+- **HPC accuracy (hammerable:false):** author from [`research/03-gautschi-facts.md`](research/03-gautschi-facts.md)
+  and [`research/04-mcp-servers.md`](research/04-mcp-servers.md). **Never** emit `--partition=a10` or
+  `#SBATCH -A standby`. Defer volatile numbers (quotas) to `myquota`/`slist`; don't invent
+  `[UNCONFIRMED]` specifics.
+- Never hand-edit generated files (catalogs, breadcrumbs) — regenerate via `tools/`.
+- Each content page ends with a back-link to its hub; **sibling cross-links are deferred to P10** so
+  intermediate builds stay `--strict`-clean.
+
+## Human-review amendments (2026-07-15)
+
+After all ten phases were drafted, the human reviewed the rendered section and requested four
+refinements (recorded in [`GOAL.md`](GOAL.md) → "Resolved during human review" and
+[`PLAN.md`](PLAN.md) §5). These were applied across the already-`done` phases as a single
+remediation pass — the acceptance criteria (R-IDs) are unchanged:
+
+1. **Paper as a footer reference, not the hub lead** (P1 `index.md`; also P3): removed the
+   paper-forward opening; added a measured footer citation linking the GitHub replication package.
+2. **Measured tone — no "mostly harmless" / pop-culture** (P1, P3): struck the phrase everywhere;
+   kept the single load-bearing "Tea, Earl Grey, hot" prompting illustration.
+3. **Warp ≠ the MCP bridge** (P4 `mcp_servers.md`, P5 `on_cluster.md`, P6 `running_agents/index.md`
+   + `local.md`): distinguished `rcac-mcp` (background SSH bridge, pure tool-calling; CLI harnesses)
+   from Warp (desktop terminal, user SSHs in, agent rides the live session; **does not use the
+   cluster MCP**; wire in `/etc/agents.d` context once SSH'd).
+4. **Settings are RCAC-deployed & enforced, not user-installed** (P8 `settings.md`): reframed to the
+   system-managed enforcement paths (Claude/Gemini/opencode), with honest caveats for Codex (no
+   managed path — recommended default) and Warp (no file — inline team-managed Agent Profile); the
+   `warp/AGENTS.md` snippet was deleted.
+5. **Cluster-side settings carry the docs MCP, not `rcac-mcp`** (P8 `settings.md` + the codex/gemini/
+   opencode snippets; follow-up 2026-07-15): the cluster-side files no longer register the local-side
+   `rcac-mcp` SSH bridge (needs `uvx`, absent on the nodes; pointless on-cluster). They wire in the
+   hosted no-auth **docs** MCP `https://docs.rcac.purdue.edu/mcp` over HTTP instead; `settings.md`
+   states the cluster-side/local-side split, and `rcac-mcp` stays on `running_agents/local.md`.
+
+Verified: `--strict` clean, no "mostly harmless", exactly one Star Trek reference, `mcpServers`
+sentinel intact, no dangling `--8<--` includes, HPC accuracy preserved.
+
+---
+
+## Phase P1 — Scaffold: section hub + nav anchor
+**Satisfies:** R1 · **Depends on:** — · **hammerable:** false
+**Goal:** the top-level `Agentic AI` section exists with a hub `index.md` stating RCAC's stance, is
+wired into nav, and builds clean.
+
+- [x] Create `docs/agentic-ai/index.md` (hub archetype, mirror `docs/lifesciences/index.md`):
+      `title: Agentic AI`, `tags: [Agentic AI]`; one H1; a stance intro (proactive engagement, not
+      prohibition; "mostly harmless"; verify, don't forbid — from GOAL/paper). Grid-card links are
+      **deferred to P10** (children don't exist yet) — for now a short "in this section" prose list
+      with **no dead links**, or cards pointing only to pages that exist.
+- [x] Insert the top-level `Agentic AI` nav block after Life Sciences (`mkdocs.yml:361`), initially
+      containing only `- agentic-ai/index.md`.
+- **Verify:** `.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py && grep -q 'agentic-ai/index.md' mkdocs.yml`
+- **Touches:** `docs/agentic-ai/index.md`, `mkdocs.yml`.
+
+## Phase P2 — Acceptable Use & Etiquette
+**Satisfies:** R2 · **Depends on:** P1 · **hammerable:** false
+**Goal:** a page stating the rules for running agents on RCAC systems, consistent with the existing
+AUP, with a link to the Purdue IT policy of record.
+
+- [x] Create `docs/agentic-ai/acceptable_use.md` (policy archetype, mirror
+      `docs/userguides/anvil/policies.md`): `tags`+`authors`; one H1; hand-written sections — no
+      heavy compute on login nodes (quote/echo the Gautschi Running-Jobs rule), jobs via Slurm with
+      `--time`, no sensitive data in world-readable paths, no secrets/credentials in context,
+      destructive actions require confirmation, agent output is the user's responsibility.
+- [x] Reuse the canonical AUP block: `{% set resource = "gautschi" %}` then
+      `{{ resource_use(resource) }}` (or link Purdue IT Acceptable Use Policy V.4.1 directly if a
+      single-cluster `resource` reads oddly for cross-cluster policy — see research 02).
+- [x] Add nav line under the section; back-link to the hub.
+- **Verify:** `… strict_check.py && grep -q 'acceptable_use.md' mkdocs.yml`
+- **Touches:** `docs/agentic-ai/acceptable_use.md`, `mkdocs.yml`.
+
+## Phase P3 — Best Practices & Limitations
+**Satisfies:** R3 · **Depends on:** P1 · **hammerable:** true
+**Goal:** a page distinguishing agents *for research* vs *for operations*, covering context
+engineering, verification, and caution/blast-radius.
+
+- [x] Create `docs/agentic-ai/best_practices.md`: research-vs-operations distinction; context
+      engineering ("Tea, Earl Grey, hot" — specificity); verification ("augmented, not outsourced";
+      ask *why* not just *what*; the expertise paradox); **let agents run read-only sanity checks
+      eagerly** (`myquota`, `slist`, `sfeatures`, `module list`, `module avail`) to ground themselves
+      before acting; caution/blast-radius (destructive commands, allocation exhaustion,
+      credential/secret leakage; existing HPC confinement contains blast radius). **Container note:
+      RCAC uses Apptainer (not Docker), and its config auto bind-mounts `/home`, `/depot`, `/scratch`
+      — so containers give limited protection and the likeliest failure is an agent *editing files*;
+      don't imply Docker-style sandboxing.** Frame from the paper's Discussion; professional voice.
+- [x] Add nav line; back-link to hub.
+- **Verify:** `… strict_check.py && grep -q 'best_practices.md' mkdocs.yml`
+- **Touches:** `docs/agentic-ai/best_practices.md`, `mkdocs.yml`.
+
+## Phase P4 — MCP Servers
+**Satisfies:** R7, R8, R9, R16 · **Depends on:** P1 · **hammerable:** false
+**Goal:** document the three RCAC MCP servers accurately (why MCP; current focus; verified connect
+commands; the `/etc/agents.d` injection), presenting the tooling as prototype/evolving.
+
+- [x] Create `docs/agentic-ai/mcp_servers.md`: "why MCP" (context that knows our clusters); present
+      **all three as actively-developed working prototypes**; a per-server section for **rcac-mcp**
+      (HPC ops, stdio via `uvx`, runs over the user's existing SSH, tool list, `rcac://context`),
+      **globus-mcp** (transfers, beta, user's Globus OAuth), **rcac-docs-mcp** (hosted HTTP at
+      `docs.rcac.purdue.edu/mcp`, `doc_search`/`doc_load`). Link each public repo. Use the
+      **verified** connect blocks from research 04 (inline fenced JSON/TOML — short, no Jinja triggers).
+- [x] State that the HPC server reads the host's `/etc/agents.d` markdown over SSH and injects it as
+      context (R8).
+- [x] **Explicitly call out the planned rename / re-architecture of `rcac-mcp`** toward the HPC-only
+      plugin model (`cluster-mcp[slurm,lmod,…]`) — framed as a **stated direction / planned&evolving**,
+      NOT shipped fact (human-confirmed framing 2026-07-15; research 04 marks it `[UNVERIFIED]`).
+- [x] Add nav line; back-link to hub.
+- **Verify:** `… strict_check.py && grep -q 'mcp_servers.md' mkdocs.yml`
+- **Touches:** `docs/agentic-ai/mcp_servers.md`, `mkdocs.yml`.
+
+## Phase P5 — Running Agents: overview + on-cluster
+**Satisfies:** R4, R5 · **Depends on:** P1 · **hammerable:** false
+**Goal:** the `Running Agents` area exists (mode overview) plus the on-cluster (login-node) page
+covering all five harnesses with the login-node constraints.
+
+- [x] Create `docs/agentic-ai/running_agents/index.md` (subdir hub): explain the two deployment
+      modes (on-cluster vs local MCP+SSH); card/links to the two mode pages (local link deferred to
+      P10 if `local.md` not yet created — or ordered so on_cluster exists here and local added P6).
+- [x] Create `docs/agentic-ai/running_agents/on_cluster.md`: install/run each of Claude Code, Codex,
+      Gemini CLI, opencode on a login node (Linux); the login-node compute constraint (mirror the
+      Gautschi Running-Jobs rule); point writable work at `$RCAC_SCRATCH`; note OS sandboxes are
+      often unavailable on shared nodes (RCAC uses **Apptainer**, which auto bind-mounts
+      `/home`/`/depot`/`/scratch` → limited protection). **Warp:** state honestly it is a local
+      desktop GUI and **cannot** run on a login node — but it is **RCAC's recommended harness for most
+      users**; run it on your workstation and SSH in (point to the local page for the recommended
+      workflow).
+- [x] Add the `Running Agents` nav sub-section (index + On the Cluster); back-links to hub.
+- **Verify:** `… strict_check.py && grep -q 'running_agents/on_cluster.md' mkdocs.yml`
+- **Touches:** `docs/agentic-ai/running_agents/{index,on_cluster}.md`, `mkdocs.yml`.
+
+## Phase P6 — Running Agents: local (MCP + SSH)
+**Satisfies:** R4, R6 · **Depends on:** P1, P5 · **hammerable:** false
+**Goal:** the local-mode page — agent runs in the user's own environment, executes remotely over
+existing SSH via the MCP servers.
+
+- [x] Create `docs/agentic-ai/running_agents/local.md`: the local-first architecture (no new
+      credentials, no hosted infra — "if you can SSH to the cluster, your agent can too"); how to
+      register `rcac-mcp` (and globus-mcp / rcac-docs-mcp) in each harness (reference research 05
+      MCP-config forms); cite `docs/lifesciences/guides/vscode.md` as prior art for external-tool →
+      cluster tunneling. **Feature Warp first-class and up front — it is RCAC's recommended harness
+      for most users: tell the story of using it *well* locally (Agent Mode on the workstation,
+      targeting Gautschi over SSH, with `rcac-mcp` connected).** Back-link to hub; forward links to
+      `mcp_servers.md` deferred to P10.
+- [x] Add the `Local (MCP + SSH)` nav line under Running Agents.
+- **Verify:** `… strict_check.py && grep -q 'running_agents/local.md' mkdocs.yml`
+- **Touches:** `docs/agentic-ai/running_agents/local.md`, `mkdocs.yml`.
+
+## Phase P7 — Shared context: hub + build/publish the 5 context files
+**Satisfies:** R10, R12, R16 · **Depends on:** P1 · **hammerable:** false
+**Goal:** author the five Gautschi `/etc/agents.d` context files (byte-exact, HPC-accurate) and
+publish them verbatim; the shared-context hub explains the model + how to give feedback.
+
+- [x] Author canonical files under `docs/snippets/agentic-ai/agents.d/`: `unix.md`, `filesystems.md`,
+      `lmod.md`, `slurm.md`, `policies.md` — each *fact → correct command/path → "do not…" →
+      rationale* (outlines in research 06), grounded in verified Gautschi facts (research 03). Also
+      write `agents.d/AGENTS.md` (the concatenated canonical context harnesses read). Instruct the
+      agent to **eagerly run read-only sanity checks** (`myquota`, `slist`, `sfeatures`,
+      `module list`, `module avail`) before acting. **Accuracy gate:** partitions
+      cpu/ai/highmem/smallgpu/profiling; QOS normal/standby/preemptible; `-A` (via `slist`) + `-q` +
+      `-p` mandatory; filesystems **`/home` ZFS · `/depot` GPFS · `/scratch` (`$RCAC_SCRATCH`) Lustre,
+      60-day purge**, `myquota`/`findscratch`; GCC 14.1.0 + OpenMPI; **Apptainer (not Docker), config
+      auto bind-mounts `/home`/`/depot`/`/scratch` → limited protection**; **no `--partition=a10`,
+      no `-A standby`**; defer quota numbers to `myquota`.
+- [x] Create `docs/agentic-ai/shared_context/index.md` (subdir hub): what `/etc/agents.d` is, that
+      these files are the **canonical single source of truth** copied into cluster config management
+      (Puppet) and injected by the MCP server over SSH, and **how to contribute feedback/corrections**
+      (RCAC-Docs GitHub issues + rcac-help@purdue.edu + Discord).
+- [x] Create `docs/agentic-ai/shared_context/context_files.md`: publish each context file verbatim
+      via `--8<--` fenced `markdown` blocks with `title=` labels.
+- [x] Add the `Shared Context & Settings` nav sub-section (index + Context Files); back-links to hub.
+- [x] `mkdocs serve` — confirm the included blocks render non-empty (check_paths footgun).
+- **Verify:** `… strict_check.py && grep -q 'shared_context/context_files.md' mkdocs.yml && grep -rq RCAC_SCRATCH site/agentic-ai/shared_context/`
+- **Touches:** `docs/snippets/agentic-ai/agents.d/*.md`, `docs/agentic-ai/shared_context/{index,context_files}.md`, `mkdocs.yml`.
+
+## Phase P8 — Build/publish per-harness settings & permissions
+**Satisfies:** R11, R12 · **Depends on:** P1, P7 · **hammerable:** false
+**Goal:** author and publish verbatim the per-harness settings/permission files for all five
+harnesses, wiring in the shared context and encoding a starting-point enforced-permission policy.
+
+- [x] Author canonical files under `docs/snippets/agentic-ai/`. Every file must both **allow-list
+      read-only sanity commands** (`myquota`, `slist`, `sfeatures`, `module list`, `module avail`) so
+      they run without prompting, **and deny** destructive/dangerous ops (`rm -rf`, `sudo`):
+      `claude/settings.json` (`permissions.allow` for the sanity commands + `permissions.deny` for
+      `rm -rf`/`sudo`; note managed `/etc/claude-code/managed-settings.json` as the enforcement point;
+      `mcpServers` for rcac-mcp; CLAUDE.md→AGENTS.md bridge), `codex/config.toml`
+      (`approval_policy`/`sandbox_mode`; `[mcp_servers.rcac]`; AGENTS.md native — note Codex has no
+      per-command allowlist, so rely on approval/sandbox mode), `gemini/settings.json` (`tools.core`
+      allow-list `run_shell_command(myquota)`/`(slist)`/`(module)`… + `tools.exclude`
+      `run_shell_command(rm)`/`(sudo)`; note system `/etc/gemini-cli/settings.json` as the enforcement
+      point; `mcpServers`), `opencode/opencode.json` (`permission` bash-pattern map — allow the sanity
+      commands, deny `rm -rf *`/`sudo *`, **catch-all first**; `mcp` local), `warp/AGENTS.md` (Warp has
+      no server-side settings file — represent it as the repo AGENTS.md + a documented Agent-Profile
+      allow/deny list; note Run-until-completion bypasses the denylist). Use research 05 for exact
+      schema; mark any `[UNVERIFIED]` key honestly.
+- [x] Create `docs/agentic-ai/shared_context/settings.md`: publish each settings file verbatim via
+      `--8<--` fenced blocks (json/toml/markdown); explain each harness's permission model briefly,
+      that this is a **v0 starting point** inviting feedback, and where config-management enforcement
+      lives (managed/system files). Note OS-sandbox weakness on shared nodes.
+- [x] Add the `Harness Settings & Permissions` nav line; back-link to hub.
+- [x] `mkdocs serve` — confirm blocks render non-empty.
+- **Verify:** `… strict_check.py && grep -q 'shared_context/settings.md' mkdocs.yml && grep -rq mcpServers site/agentic-ai/shared_context/`
+- **Touches:** `docs/snippets/agentic-ai/{claude,codex,gemini,opencode,warp}/…`, `docs/agentic-ai/shared_context/settings.md`, `mkdocs.yml`.
+
+## Phase P9 — Gautschi "Using AI Agents" chapter
+**Satisfies:** R13, R16 · **Depends on:** P1, P4, P5, P6, P7 · **hammerable:** false
+**Goal:** a Gautschi user-guide chapter giving cluster-specific setup pointers, cross-linked with the
+top-level section.
+
+- [x] Create `docs/userguides/gautschi/using_ai_agents.md` (userguide archetype): `tags: [Gautschi]`,
+      `authors`, `{% set resource = "gautschi" %}`; Gautschi-specific quick-start (login host
+      `gautschi.rcac.purdue.edu`, `slist`/`myquota`, partitions/QOS reminders), and links into the
+      top-level Agentic AI pages (MCP servers, running-agents, shared context). Reuse macros for
+      SSH/module/Slurm background where helpful.
+- [x] Insert the `Using AI Agents` nav line between Compiling Source Code (`mkdocs.yml:144`) and FAQs.
+- **Verify:** `… strict_check.py && grep -q 'using_ai_agents.md' mkdocs.yml`
+- **Touches:** `docs/userguides/gautschi/using_ai_agents.md`, `mkdocs.yml`.
+
+## Phase P10 — Integration: cards, cross-links, breadcrumbs, sweep
+**Satisfies:** R14, R15, R16 · **Depends on:** P1–P9 · **hammerable:** false
+**Goal:** the section reads as one coherent whole; every internal link resolves; breadcrumbs are
+current; a11y and HPC accuracy pass a final review.
+
+- [x] Populate the hub grid-cards (`agentic-ai/index.md`) linking every subpage; add the
+      Running-Agents index card to `local.md`; add sibling cross-links (running-agents ↔ mcp_servers
+      ↔ shared_context ↔ Gautschi chapter).
+- [x] `.venv/bin/python tools/generate_breadcrumbs.py` (nav changed).
+- [x] a11y sweep: one H1/page, descending headings, header rows on tables, descriptive link text,
+      alt text on any image.
+- [x] HPC-accuracy final pass against research 03/04: partitions, QOS, paths, commands, MCP connect
+      strings; confirm **no `--partition=a10` / `-A standby`** anywhere in the new pages/snippets.
+- [x] Full `mkdocs serve` eyeball of the whole section.
+- **Verify:** `… strict_check.py && .venv/bin/python tools/generate_breadcrumbs.py && grep -q 'Agentic AI' mkdocs.yml`
+- **Touches:** `docs/agentic-ai/**`, `docs/userguides/gautschi/using_ai_agents.md`, `docs/assets/data/breadcrumbs.json`, `mkdocs.yml`.
+
+---
+
+## How `docs-draft` drives this
+
+1. `next_phase.py spec/agentic-ai-docs/TECH.md` prints the next actionable phase (statuses are
+   authoritative).
+2. Pre-flight: clean tree, on `feature/agentic-ai-docs`, `main` reachable, env active
+   (`.venv/bin/python -c "import yaml, mkdocs"`).
+3. Execute every `[ ]` in the phase (consult `PLAN.md` / `research/` / `style-guide.md`).
+4. Run the phase's `verify:` — never advance on a checkbox alone.
+5. Amend this file if reality diverges (`set_phase.py`; note in the commit body). STOP and escalate
+   only on a **`GOAL.md` contradiction** or a phase stuck `uphill` across drafts (raised hand — esp.
+   the `cluster-mcp` framing and any newly-surfaced `[UNCONFIRMED]` HPC spec).
+6. Mark the phase `done`, advance `current_phase`, `--touch`; one `[feature]` commit; stop & report.
diff --git a/spec/agentic-ai-docs/research/00-digest.md b/spec/agentic-ai-docs/research/00-digest.md
new file mode 100644
index 00000000..30ccdb13
--- /dev/null
+++ b/spec/agentic-ai-docs/research/00-digest.md
@@ -0,0 +1,189 @@
+# Research digest — agentic-ai-docs
+
+Synthesis of the six research briefs in this directory. Cited detail lives in each brief; this is
+the decision-ready summary that `PLAN.md`/`TECH.md` build on.
+
+- [`01-site-architecture.md`](01-site-architecture.md) — IA, nav insertion, hub archetype, breadcrumbs.
+- [`02-macros-and-jinja.md`](02-macros-and-jinja.md) — the verbatim-publishing pattern (the #1 risk), macros to reuse, policy archetype.
+- [`03-gautschi-facts.md`](03-gautschi-facts.md) — citable Gautschi facts + `[UNCONFIRMED]` list + two doc-errors to avoid.
+- [`04-mcp-servers.md`](04-mcp-servers.md) — the three public MCP servers, verified connect commands, tool lists.
+- [`05-harness-configs.md`](05-harness-configs.md) — per-harness config/permission/MCP/context-file reference.
+- [`06-context-and-conventions.md`](06-context-and-conventions.md) — `/etc/agents.d` content design, context→harness mapping, peer prior art.
+
+## 1. Information architecture (settled)
+
+- New **top-level `Agentic AI`** nav section, inserted **after Life Sciences** (`mkdocs.yml:361`),
+  before the commented Tags line. Life Sciences is the exact structural precedent (a domain hub
+  with its own `index.md`). Contact/FAQs stay last.
+- New **Gautschi chapter** `Using AI Agents`, inserted **between Compiling Source Code
+  (`mkdocs.yml:144`) and FAQs (`:145`)** so FAQs stays last per cluster convention.
+- Hub archetype = `docs/lifesciences/index.md`: `title`+`tags` front-matter, `<div class="grid
+  cards" markdown>` blocks, `## :material-…:` headers. A section subdir needs a bare `index.md`
+  first child (`navigation.indexes` enabled, `mkdocs.yml:18`).
+- Breadcrumbs regenerate from nav (`python tools/generate_breadcrumbs.py`; CI also runs on
+  `mkdocs.yml` change). Only 7 pre-existing `--strict` warnings in `strict-baseline.txt`, none in
+  our files → the bar is **zero new warnings**.
+- **No existing agentic-AI docs** — net-new. Closest analogs: `docs/userguides/anvil/anvilgpt.md`
+  (a hosted chatbot, not a coding agent) and `docs/lifesciences/guides/vscode.md` (external
+  tool → login → compute via ProxyJump; useful structural precedent for the local mode).
+
+## 2. The verbatim-config pattern (the #1 technical risk — SOLVED)
+
+The `mkdocs-macros` plugin evaluates Jinja on every page's own source **before** Markdown parsing;
+`pymdownx.snippets` (`--8<--`) splices files in **during** parsing, **after** Jinja. **Therefore
+`--8<--`-included content is never Jinja-evaluated** — literal `{{`/`{%` passes through untouched
+(proven empirically, `mkdocs build --strict` exit 0).
+
+**Pattern:** keep each context/settings artifact as a real byte-exact file under
+`docs/snippets/agentic-ai/…` (excluded from nav by `exclude_docs: snippets/`, still `--8<--`-includable
+and present in the prod build) and embed it in a fenced code block:
+
+````markdown
+```json title="~/.claude/settings.json"
+--8<-- "docs/snippets/agentic-ai/claude/settings.json"
+```
+````
+
+Single source of truth, syntax-highlighted, zero escaping, page keeps `{{ macro() }}` access.
+**Footgun:** `check_paths:false` — a mistyped include path yields a silent **empty** block (no
+`--strict` error). Mitigate by grepping the built `site/` for a sentinel token in each phase's
+`verify:` and eyeballing the render.
+
+**Macros to reuse** (call, don't hardcode; `{% set resource = "gautschi" %}` then `{{ macro(resource) }}`):
+`resource_use` (Purdue AUP block), `module_system`, `slurm_general_overview`, `slurm_general_jobs`,
+`ssh_keys_snippet`, `storage_quota`, `scratch_space`, `scratch_purge`, `environment_variables`,
+`accounts_md_snippet`. **Caveat:** Gautschi's own pages do *not* invoke `module_system`/
+`slurm_general_jobs` (they emit generic RCAC text) — fine for background prose, but the **context
+files must be authored from the verified Gautschi facts (§4), not from these generic macros.**
+
+**Policy archetype** = `docs/userguides/anvil/policies.md` (Gautschi has none): `tags`+`authors`
+front-matter, one H1, `{% set resource %}`, hand-written sections + `{{ resource_use(resource) }}` /
+`{{ scratch_purge(resource) }}`.
+
+## 3. MCP servers (verified against the public repos)
+
+All three are public, MIT, Python/FastMCP, installed for the desktop path via `uvx git+https://…`.
+
+- **`rcac-mcp`** (PurdueRCAC/rcac-mcp, **prototype**) — HPC cluster+storage tools. Local **stdio**
+  subprocess; runs commands on the cluster over the user's **existing SSH** (`~/.ssh/config`), no
+  new credential. Verified config:
+  ```json
+  {"mcpServers":{"rcac":{"command":"uvx","args":["git+https://github.com/purduercac/rcac-mcp","--ssh-host","cluster.rcac.purdue.edu"]}}}
+  ```
+  Tools: `run_command`, `list_directory`, `read_file`/`write_file`, `upload_file`/`download_file`,
+  `myquota`, `storage_paths`, `jobinfo`/`jobcmd`/`jobenv`/`jobscript`, `showpartitions`,
+  `average_wait`, `sbatch`/`squeue`/`scancel`/`sacct`/`sinfo`, `scontrol_show_job`/`_node`, `slist`,
+  `sfeatures`, `doc_search`, `doc_load`. **Confirmed:** reads `/etc/agents.d/*.md` over SSH and
+  exposes it as resource `rcac://context`. Optional hosted HTTP with JWT/OIDC delegation.
+- **`globus-mcp`** (**BETA**, banner-warned) — wraps Globus CLI + Compute SDK; user's own Globus
+  OAuth (browser login). stdio via `uvx git+…`. Tools: `whoami`, `endpoint_search/show`, `ls/stat/
+  mkdir/rename/rm/delete`, `transfer/transfer_batch`, `task_*`, `compute_*`.
+- **`rcac-docs-mcp`** — hosted **no-auth HTTP at `docs.rcac.purdue.edu/mcp`** (add as a remote HTTP
+  MCP server; exact client JSON `[UNVERIFIED]`), or local stdio via `uvx git+…`. Two tools:
+  `doc_search(query, category=None)`, `doc_load(path)` over an FTS5/BM25 index.
+
+**⚠ [UNVERIFIED]:** the "HPC-only refocus / `cluster-mcp[slurm,lmod,…]` plugin architecture" (from
+GOAL R7) has **zero public mentions** — the public `rcac-mcp` still bundles docs tools. **Docs must
+present `rcac-mcp` as the current prototype and frame the plugin direction as planned/evolving,
+clearly labeled — not as shipped fact. Confirm with the human before publish.** Also noted: private
+`agentbase` (internal-KB agentic search) — out of scope.
+
+## 4. Gautschi facts (safety-critical — see brief 03 for citations)
+
+- **System:** Rocky Linux 9; login `gautschi.rcac.purdue.edu`; 8 front-ends (192-core EPYC 9654,
+  768 GB); auth = SSH keys or Purdue Login MFA (**not** "BoilerKey" — that term is absent).
+- **Slurm:** every job needs 4 parts and must pass **both `-A/--account=` and `-p/--partition=`**
+  (+ optional `-q/--qos=`). Partitions: `cpu` (192c, ~2 GB/core, normal+standby, 2wk/4h),
+  `ai` (112c, 8× H100 80 GB, normal+preemptible, 2wk), `highmem` (192c, 1.5 TB, 24h, >48-core rule),
+  `profiling` (whole-node, 24h), `smallgpu` (128c, 2× L40S, 24h). QOS: `normal` (default, charged),
+  `standby` (idle, free, 4h max), `preemptible` (ai only, 0.25 GPU-hr, killable). List accounts with
+  **`slist`**. Verified commands: `sbatch`, `squeue -u`, `scontrol show/hold/release`, `scancel`,
+  `sinteractive`, `srun`, `slist`, `sfeatures`, `myquota`, `findscratch`, `purgelist`.
+- **Filesystems (tech corrected by the human, authoritative 2026-07-15):** home `/home/$USER`
+  (`$HOME`) is **ZFS** (snapshotted); **`/depot` is GPFS**; scratch `/scratch/gautschi/$USER` via
+  **`$RCAC_SCRATCH`** (NOT `$CLUSTER_SCRATCH`) is **Lustre**, **60-day** purge, not backed up;
+  Fortress (HPSS) for archive; check with **`myquota`** / `findscratch`. *(This corrects research 03,
+  which read `/home` as GPFS from a generic snippet.)* **Quotas (25 GB home / 100 TB scratch) are
+  illustrative `myquota` output, not official — context files must tell the agent to RUN `myquota`,
+  not hardcode numbers.**
+- **Modules:** environment modules (Lmod — implied by `module spider`); `module avail/spider/load`;
+  recommended GCC 14.1.0 + OpenMPI (exact OpenMPI version unstated).
+- **Login-node rule (quote):** "Do NOT run large, long, multi-threaded, parallel, or CPU-intensive
+  jobs on a front-end login host… Always use SLURM to submit your work as a job."
+  (`run_jobs/index.md:16-17`).
+- **🚫 Two doc-errors to NOT propagate:** `--partition=a10` (invalid — use `ai`/`smallgpu`) and
+  `#SBATCH -A standby` (standby is a QOS `-q standby`, not an account).
+- **`[UNCONFIRMED]`** (do not invent; run-command or omit): exact quotas, Depot mount path, OpenMPI
+  version, default login shell, `sinfo`/`sacct`/`jobinfo` on Gautschi, a Purdue AUP direct URL,
+  data-classification policy.
+
+## 5. The five harnesses (see brief 05 for the full table)
+
+| harness | config path(s) | format | permission mechanism | MCP | context file |
+|---|---|---|---|---|---|
+| **Claude Code** | `~/.claude/settings.json`; project `.claude/settings.json`; **managed `/etc/claude-code/managed-settings.json`** | JSON | `permissions.allow/deny/ask` + `defaultMode` + OS sandbox | `claude mcp add` / `.mcp.json` (stdio+http/sse) | `CLAUDE.md` (no native AGENTS.md — bridge via `@import`/symlink) |
+| **Codex CLI** | `~/.codex/config.toml`; `.codex/config.toml` | TOML | `approval_policy` + `sandbox_mode` (no per-cmd list; Linux sandbox needs **bubblewrap**) | `[mcp_servers.NAME]` / `codex mcp add` (stdio+HTTP) | `AGENTS.md` (native) |
+| **Gemini CLI** | **`/etc/gemini-cli/settings.json` (system, final say)**; `~/.gemini/settings.json`; `.gemini/settings.json` | JSON | `tools.core` (allow) / `tools.exclude` (deny) `run_shell_command(<prefix>)`; blocklist wins; chains split | `mcpServers` (stdio+SSE+HTTP) | `GEMINI.md`; configurable `context.fileName` (can add AGENTS.md) |
+| **opencode** | `~/.config/opencode/opencode.json`; project `opencode.json`; `/etc/opencode/` | JSON | `permission` per-bash-pattern map (**last-match-wins → catch-all first**); no OS sandbox | `mcp` `type:"local"`/`"remote"` | `AGENTS.md` (native) + `instructions` |
+| **Warp** | **Desktop-app UI** (Settings > Agents); MCP JSON; Warp Drive rules | UI/JSON | Agent-Profile autonomy + regex allow/deny (Run-until-completion **ignores denylist**) | Settings > Agents > MCP (stdio+remote) | `AGENTS.md` (ALL-CAPS; `WARP.md` legacy) |
+
+**Cross-cutting HPC realities:** the harnesses' own OS sandboxes (Codex `bubblewrap`, Gemini
+Docker/Podman, Linux namespaces) are frequently **unavailable on shared nodes** → treat the
+**permission/approval layer as primary**, point writable roots at `$RCAC_SCRATCH`, deny
+`rm -rf`/`sudo`. **Container model on these clusters is Apptainer, not Docker** (human, 2026-07-15):
+RCAC's Apptainer config **auto bind-mounts `/home`, `/depot`, `/scratch`** into containers for
+convenience, so containers give **limited protection** — the likeliest failure mode is an agent
+*editing files* on those still-writable mounts (bind-mounts can be disabled if the user invokes
+Apptainer explicitly). The **enforcement points** for config management are the *system/managed*
+files: Claude `/etc/claude-code/managed-settings.json`, Gemini `/etc/gemini-cli/settings.json`.
+**Read-only sanity commands should be *allow-listed*** so the agent runs `myquota`, `slist`,
+`sfeatures`, `module list`, `module avail`, … eagerly without prompting (human, 2026-07-15).
+**Warp is a local desktop GUI, cannot be installed on a login node — but it is RCAC's *recommended*
+harness for most users**, so give it first-class treatment in the **local (MCP + SSH)** guidance:
+"run it on your workstation and SSH in" (don't fabricate a login-node path).
+
+## 6. Context-file design + mapping + prior art
+
+- **`/etc/agents.d/*.md` = the DRY source of truth.** Shape per file: *fact → correct command/path
+  → "do not…" list → rationale* (mirrors the paper's own `rules/`+`tips/`). Per-file outlines:
+  - **unix.md** — Rocky 9 / bash; shared front-ends for edit/compile/submit only; no heavy compute
+    on login nodes; no sudo; SSH-inherited access; process hygiene.
+  - **filesystems.md** — home vs `$RCAC_SCRATCH` (not backed up, ~60-day purge) vs `/tmp` vs
+    Depot/Fortress; `myquota`/`findscratch`; no secrets in world-readable paths; confirm bulk deletes.
+  - **lmod.md** — software via environment modules, not apt/yum; `module avail/spider/load`; GCC
+    14.1.0+OpenMPI; never invent module names.
+  - **slurm.md** — job needs resources + `-A` (via `slist`) + `-q` + `-p` (mandatory); partitions
+    cpu/ai/highmem/smallgpu/profiling; QOS normal/standby/preemptible; always set `--time`; no
+    PBS/LSF flags; **never** `--partition=a10` or `-A standby`.
+  - **policies.md** — Purdue AUP; sensitive-data & credential bans; resource stewardship;
+    destructive-op confirmation; report to rcac-help@purdue.edu.
+- **Mapping context → harnesses:** concatenate `/etc/agents.d/*.md` into one canonical **`AGENTS.md`**;
+  symlink/bridge `CLAUDE.md` (Claude has no native AGENTS.md); Codex/opencode/Warp/Gemini read
+  `AGENTS.md` (Gemini via `context.fileName`). **Local mode:** `rcac-mcp` injects the files over SSH
+  (`rcac://context`). **Permissions are NOT portable** — hand-translate one policy into each harness's
+  native settings format.
+- **Prior-art verdict — early but not empty:** NERSC has a full [AI Coding Tools page](https://docs.nersc.gov/development/coding-agents/)
+  ("verification is the whole game"; login-node + secrets rules) — the closest analog; TACC has
+  [AI Tools on TACC Resources](https://docs.tacc.utexas.edu/basics/conduct/#ai) (compute-nodes-only,
+  user-accountable). ALCF/NCSA — nothing agent-facing found. **No peer publishes an MCP/Slurm server
+  or `/etc/agents.d` context** → RCAC's genuine white space. (A broad community "slurm-mcp" sweep was
+  org-policy-blocked mid-research; not required for this feature.)
+
+## 7. Net implications for the plan
+
+1. One top-level `docs/agentic-ai/` section (hub + guidance + MCP + running-agents + shared-context
+   subdir) + one Gautschi chapter; canonical artifacts under `docs/snippets/agentic-ai/`.
+2. Publish verbatim via `--8<--` fenced includes; verify by grepping built `site/` (check_paths
+   footgun).
+3. Author context files from verified Gautschi facts (incl. `/home` ZFS · `/depot` GPFS ·
+   `/scratch` Lustre); instruct agents to run `myquota`/`slist`/`sfeatures`/`module list` rather than
+   hardcoding volatile numbers; never emit the two doc-errors.
+4. Present all three MCP servers as **actively-developed working prototypes** (human-confirmed
+   framing); **explicitly call out the planned rename/re-architecture of `rcac-mcp`** toward the
+   plugin model — stated direction, not shipped fact.
+5. **Warp is first-class and RCAC's recommended harness for most users** — tell the story of using it
+   *well* locally over SSH (it can't run on a login node). Enforcement lives in the system/managed
+   settings files (Claude `/etc/claude-code/`, Gemini `/etc/gemini-cli/`).
+6. Settings **allow-list read-only sanity commands** (run eagerly, no prompt) and **deny**
+   destructive ops; caution content reflects the **Apptainer** model (auto bind-mounts /home,/depot,
+   /scratch → limited protection; editing files is the real risk), not Docker sandboxing.
diff --git a/spec/agentic-ai-docs/research/01-site-architecture.md b/spec/agentic-ai-docs/research/01-site-architecture.md
new file mode 100644
index 00000000..b1f150af
--- /dev/null
+++ b/spec/agentic-ai-docs/research/01-site-architecture.md
@@ -0,0 +1,438 @@
+# Research 01 — Site Architecture & Navigation Mechanics
+
+Scope: how to add (a) a new top-level **Agentic AI** nav section and (b) a **Using AI Agents**
+chapter inside the Gautschi user guide. All citations are to files under the repo root
+`/Users/geoffrey/Software/github.com/purduercac/RCAC-Docs`. Read-only investigation; no site
+files were modified.
+
+---
+
+## 1. `mkdocs.yml` nav — top-level sections and exact insertion points
+
+The `nav:` block is `mkdocs.yml:96-364`. The **top-level sections, in order**, are:
+
+1. `HPC User Guides:` — `mkdocs.yml:97`
+2. `Storage User Guides:` — `mkdocs.yml:206`
+3. `RCAC Resources:` — `mkdocs.yml:245`
+4. `Life Sciences:` — `mkdocs.yml:332`
+5. `# - Tags: tags.md` (commented out) — `mkdocs.yml:362`
+6. `- Contact us: contact.md` — `mkdocs.yml:363`
+7. `- FAQs: faqs.md` — `mkdocs.yml:364`
+
+`Life Sciences` is the closest structural precedent for `Agentic AI`: it is a top-level
+*domain hub* (its own `index.md` + `Getting Started` / `Guides` / `Tutorials` subsections),
+not a cluster or storage guide. See `mkdocs.yml:332-361`:
+
+```yaml
+  - Life Sciences:
+    - lifesciences/index.md
+    - Getting Started:
+      - HPC Orientation for Biologists: lifesciences/guides/hpc-orientation.md
+      ...
+    - Tutorials:
+      - Gene Prediction:
+        - BRAKER3: lifesciences/tutorials/braker.md
+        ...
+        - Juicer: lifesciences/tutorials/juicer.md
+  # - Tags: tags.md
+  - Contact us: contact.md
+  - FAQs: faqs.md
+```
+
+### RECOMMENDED insertion point for top-level "Agentic AI"
+
+**Insert immediately after the `Life Sciences` section ends (after `mkdocs.yml:361`) and
+before the commented `# - Tags` line (`mkdocs.yml:362`).** This groups the two domain hubs
+(Life Sciences, Agentic AI) together and keeps the utility items (`Contact us`, `FAQs`) last —
+consistent with the current layout. (Alternative acceptable slot: after `Storage User Guides`
+ends at `mkdocs.yml:244`, before `RCAC Resources`. The Life-Sciences-adjacent slot is
+preferred for domain-hub parallelism.)
+
+The last two lines of the Life Sciences block to anchor against are `mkdocs.yml:360-361`:
+
+```yaml
+      - Hi-C Analysis:
+        - Juicer: lifesciences/tutorials/juicer.md
+```
+
+**PASTE-READY snippet** (new lines to add directly below `mkdocs.yml:361`, at the same
+2-space indent as `- Life Sciences:`). A section that owns a direct `index.md` child gets a
+breadcrumb parent (see §4), so include one:
+
+```yaml
+  - Agentic AI:
+    - agentic-ai/index.md
+    - Overview: agentic-ai/overview.md
+    - Using AI Agents on RCAC: agentic-ai/using-ai-agents.md
+    # ...additional pages, each also created under docs/agentic-ai/ + linked from the hub
+```
+
+Notes for the drafter:
+- The exact content dir/filenames above are a proposal; whatever paths you use must exist
+  under `docs/` and each must appear here or the page is orphaned (invariant §4;
+  `.agents/factory/style-guide.md:153`).
+- `docs_dir` is unset, so it defaults to `docs/` (see §5) — paths are relative to `docs/`.
+- `Agentic AI` is **not** in `BREADCRUMB_TITLE_OVERRIDES`
+  (`tools/generate_breadcrumbs.py:39-55`), so it renders verbatim as "Agentic AI" in
+  breadcrumbs. Add an override there only if you want a longer label.
+
+### Gautschi sub-tree block
+
+The Gautschi cluster block is `mkdocs.yml:135-145` (nested under `HPC User Guides` →
+2nd-level, 4-space indent for the `- Gautschi:` key, 6-space for its children):
+
+```yaml
+    - Gautschi:
+      - userguides/gautschi/index.md
+      - Gautschi Overview: userguides/gautschi/overview.md
+      - Biography of Gautschi: userguides/gautschi/biography.md
+      - Accounts: userguides/gautschi/accounts.md
+      - Software: userguides/gautschi/software.md
+      - Running Jobs: userguides/gautschi/run_jobs/index.md
+      - File Storage and Transfer: userguides/gautschi/storage.md
+      - Gateway (Open OnDemand): userguides/gautschi/gateway.md
+      - Compiling Source Code: userguides/gautschi/compile.md
+      - Frequently Asked Questions: userguides/gautschi/faqs.md
+```
+
+### RECOMMENDED insertion point for the Gautschi "Using AI Agents" chapter
+
+**Insert between `Compiling Source Code` (`mkdocs.yml:144`) and `Frequently Asked Questions`
+(`mkdocs.yml:145`).** Across every cluster, `Frequently Asked Questions` is the last chapter;
+keeping FAQs last preserves that convention. So the new line becomes the second-to-last child.
+
+PASTE-READY — the Gautschi block after the edit (new line marked; single flat page):
+
+```yaml
+    - Gautschi:
+      - userguides/gautschi/index.md
+      - Gautschi Overview: userguides/gautschi/overview.md
+      - Biography of Gautschi: userguides/gautschi/biography.md
+      - Accounts: userguides/gautschi/accounts.md
+      - Software: userguides/gautschi/software.md
+      - Running Jobs: userguides/gautschi/run_jobs/index.md
+      - File Storage and Transfer: userguides/gautschi/storage.md
+      - Gateway (Open OnDemand): userguides/gautschi/gateway.md
+      - Compiling Source Code: userguides/gautschi/compile.md
+      - Using AI Agents: userguides/gautschi/using_ai_agents.md      # <-- NEW
+      - Frequently Asked Questions: userguides/gautschi/faqs.md
+```
+
+If the chapter needs sub-pages, use a nested section with its own `index.md` (this also earns
+a breadcrumb parent):
+
+```yaml
+      - Using AI Agents:
+        - userguides/gautschi/using_ai_agents/index.md
+        - Getting Started: userguides/gautschi/using_ai_agents/getting-started.md
+      - Frequently Asked Questions: userguides/gautschi/faqs.md
+```
+
+Also add a matching bullet to the Gautschi hub list in
+`docs/userguides/gautschi/index.md` (the hub ends at the "Frequently Asked Questions"
+bullet) so the hub page and the nav stay in sync — the hub currently lists each chapter as a
+markdown bullet (`docs/userguides/gautschi/index.md`, the `- [**...**](...)` list).
+
+> Caveat — invariant §10 (per-cluster parallelism, `.agents/factory/invariants.md`; AGENTS.md
+> "Invariants" §10): the cluster chapter set is deliberately identical across clusters. A
+> Gautschi-only "Using AI Agents" chapter intentionally breaks that symmetry. It is what the
+> task asks for; just flag it in REVIEW so it is a conscious exception, not an accident.
+
+Naming: use lowercase `snake_case` (`using_ai_agents.md`), per
+`.agents/factory/style-guide.md:149`.
+
+---
+
+## 2. Hub / landing archetype (grid cards, front-matter, section headers)
+
+### `docs/lifesciences/index.md` (a clean section-hub example)
+
+Front-matter (`docs/lifesciences/index.md:1-5`):
+
+```yaml
+---
+title: Life Sciences
+tags:
+  - Life Sciences
+---
+```
+
+Then a single `#` H1, a one-paragraph intro, and one `grid cards` block. The card grid
+(`docs/lifesciences/index.md:11-45`) is the canonical pattern:
+
+```markdown
+<div class="grid cards" markdown>
+
+-   :material-rocket-launch:{ .lg .middle } __Start Here__
+
+    ---
+
+    New to HPC for bioinformatics? Begin with the orientation guide.
+
+    [:octicons-arrow-right-24: HPC Orientation for Biologists](guides/hpc-orientation.md)
+
+-   :material-file-document:{ .lg .middle } __Guides__
+
+    ---
+
+    Step-by-step guides for common bioinformatics tasks: Nextflow, R, SRA downloads, QC, and more.
+
+    [:octicons-arrow-right-24: Running Bioinformatics on RCAC](guides/running-bioinformatics.md)
+
+</div>
+```
+
+Anatomy of one card: `-   :material-ICON:{ .lg .middle } __Bold title__` → blank line →
+`    ---` (horizontal rule = card header divider) → blank line → description prose → blank
+line → an arrow link `[:octicons-arrow-right-24: label](relative/path.md)`. Indentation
+inside a card is 4 spaces. Links are **relative** page-to-page (invariant §5).
+
+### `docs/index.md` (the site home page — richer variant)
+
+Front-matter (`docs/index.md:1-9`) uses `hide:` and a wrapping div:
+
+```yaml
+---
+hide:
+  - footer
+  - toc
+#   - navigation
+meta:
+  - name: google-site-verification
+    content: HQsOhuVVa11DY0qIrxXPW6GUR9jk4EnFfQgUzCgKNbw
+---
+```
+
+Body is wrapped in `<div class="home-page" markdown>` … `</div>`
+(`docs/index.md:11` and `:291`). It uses **section headers with an inline icon**, e.g.
+`docs/index.md:43`, `:99`, `:215`, `:253`:
+
+```markdown
+## :material-rocket-launch: New to RCAC?
+## :material-server-network: HPC User Guides
+## :material-bookshelf: RCAC Resources
+## :material-lifebuoy: Need Help?
+```
+
+Each header is followed by its own `<div class="grid cards" markdown>` block. Cards can carry
+a **bold spec line** (`docs/index.md:109`, `:129`) and **multiple arrow links separated by
+`&nbsp;`** (`docs/index.md:55`):
+
+```markdown
+    **128 cores/node | 256GB-1TB RAM | A100/H100 GPUs**
+
+    [:octicons-arrow-right-24: Purdue account](https://www.rcac.purdue.edu/account/request) &nbsp;&nbsp; [:octicons-arrow-right-24: ACCESS account](userguides/anvil/access/)
+```
+
+### `.md-button` / quick-launcher patterns
+
+- `.md-button` is documented in `.agents/factory/style-guide.md:129` (`[text](url){ .md-button }`)
+  and `:68` (`[Back to index](index.md){ .md-button }`) — used for back/prev-next nav on
+  lessons, not seen on the two hub pages above.
+- The Gautschi hub uses a bespoke **quick-launcher** widget instead of grid cards
+  (`docs/userguides/gautschi/index.md`): a `<div class="quick-launcher">` containing
+  `quick-launcher-card` blocks with `<a … class="launcher-btn">` — styled from
+  `docs/stylesheets/extra.css`. This is the cluster-hub convention (index.md + a bullet list
+  of chapters), distinct from the domain-hub grid-cards convention.
+
+### Copyable skeleton for a new "Agentic AI" section hub (`docs/agentic-ai/index.md`)
+
+```markdown
+---
+title: Agentic AI
+tags:
+  - Agentic AI
+---
+
+# Agentic AI
+
+One or two sentences describing agentic AI on RCAC systems and who this section is for.
+
+<div class="grid cards" markdown>
+
+-   :material-robot:{ .lg .middle } __Start Here__
+
+    ---
+
+    New to running AI agents on RCAC? Begin with the overview.
+
+    [:octicons-arrow-right-24: Overview](overview.md)
+
+-   :material-cog:{ .lg .middle } __Using AI Agents__
+
+    ---
+
+    Configure and run agentic AI tools on RCAC clusters.
+
+    [:octicons-arrow-right-24: Using AI Agents on RCAC](using-ai-agents.md)
+
+</div>
+```
+
+Add each card's target page under `docs/agentic-ai/` and register it in `nav:` (§1). If you
+want the home-page `## :material-...:` section-header style, that is only needed on
+`docs/index.md`; a section hub typically leads with its `#` H1 + one grid.
+
+---
+
+## 3. `navigation.indexes` and the hub front-matter contract
+
+`theme.features` (`mkdocs.yml:17-28`) enables, among others:
+
+```yaml
+  features:
+    - navigation.indexes      # mkdocs.yml:18
+    - navigation.sections     # mkdocs.yml:21
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+```
+
+`navigation.indexes` is what lets a section's `index.md` become the clickable landing page
+for that section header (rather than a separate "Index" child). That is why every section in
+`nav:` lists a **bare `index.md` string as its first child** (e.g. `mkdocs.yml:99`
+`- userguides/anvil/index.md`; `mkdocs.yml:136` `- userguides/gautschi/index.md`;
+`mkdocs.yml:333` `- lifesciences/index.md`). To make `Agentic AI` (or a nested `Using AI
+Agents`) behave as a landing hub, its **first child must be the bare `…/index.md` string**.
+
+The style guide confirms the convention: "Every section directory has an `index.md` hub
+(`navigation.indexes`)" — `.agents/factory/style-guide.md:151`.
+
+Front-matter contract, cross-checked against `.agents/factory/style-guide.md`:
+
+- **Hub / landing page** (archetype E, `.agents/factory/style-guide.md:70-73`): "Front-matter
+  uses `hide: [footer]` (and often `toc`); minimal prose; grid-card or bulleted navigation."
+  The site home does exactly this (`docs/index.md:1-9`). A lighter domain hub may instead use
+  just `title` + `tags` (`docs/lifesciences/index.md:1-5`) — both are in use; pick per how
+  much chrome you want to hide.
+- **Normal cluster user-guide page** (archetype A, `.agents/factory/style-guide.md:13-26`):
+  `tags:` (cluster name) + `authors:` (RCAC handle) + `search: boost: 2`, plus `resource:`
+  only if the body uses `{{ resource }}`. The Gautschi index/overview confirm this exact set
+  (`docs/userguides/gautschi/index.md:1-8`, `docs/userguides/gautschi/overview.md:1-8`).
+
+So a **Gautschi "Using AI Agents"** page (living under `docs/userguides/gautschi/`) should
+carry the archetype-A front-matter (`tags: [Gautschi]`, `authors:`, `search: boost: 2`),
+**not** the hub front-matter — unless it becomes a nested section with its own index.md, in
+which case that index.md is the hub.
+
+---
+
+## 4. Breadcrumbs — trigger, output, whether the drafter must regenerate
+
+### Generator header (`tools/generate_breadcrumbs.py:1-13`)
+
+```
+Generate breadcrumbs.json from mkdocs.yml nav.
+ - Only include parent titles if that parent section contains an actual index.md
+ - Do NOT emit an entry for the root "/" (no breadcrumb for Home page)
+ - Writes output to docs/assets/data/breadcrumbs.json so MkDocs will serve it
+```
+
+Key mechanics for planning:
+- **Output path:** `docs/assets/data/breadcrumbs.json`
+  (`tools/generate_breadcrumbs.py:62`, `OUTPUT_JSON`). It is a **generated file** (invariant
+  §3 — do not hand-edit; regenerate).
+- **Parent inclusion rule:** a nav section contributes its title to a child's breadcrumb chain
+  **only if that section contains a direct `index.md` string child**
+  (`tools/generate_breadcrumbs.py:110-113`). This is the concrete reason the `Agentic AI`
+  section (and any nested `Using AI Agents` section) must include a bare `…/index.md` first
+  child if you want it to appear as a breadcrumb ancestor.
+- **Title overrides:** `BREADCRUMB_TITLE_OVERRIDES` (`tools/generate_breadcrumbs.py:39-55`)
+  maps e.g. `Gautschi` → `Gautschi User Guide`. So a Gautschi child page's breadcrumb will
+  read `Home / Gautschi User Guide / Using AI Agents`. `Agentic AI` has **no** override, so it
+  appears verbatim; add an entry there only if a different breadcrumb label is desired.
+
+### CI trigger (`.github/workflows/update_breadcrumbs.yml`)
+
+```yaml
+on:
+  push:
+    branches: [ main, dev ]        # lines 4-7
+    paths:
+      - 'mkdocs.yml'               # lines 8-9
+```
+
+The workflow runs only when **`mkdocs.yml` changes** on `main` or `dev`. It runs
+`python tools/generate_breadcrumbs.py` (`.yml:50`) and **bot-commits** the regenerated
+`docs/assets/data/breadcrumbs.json` as `purduercac-docs-bot` (`.yml:43-46, 52-69`).
+
+### Does the drafter need to run it manually?
+
+**Optional but recommended.** CI will regenerate and bot-commit it after the nav change lands
+on `main`/`dev`. However:
+- For local `mkdocs serve` / `mkdocs build --strict` verification of the new pages'
+  breadcrumbs, run it manually: `python tools/generate_breadcrumbs.py` (from repo root — it
+  resolves `mkdocs.yml` relative to its own location, `tools/generate_breadcrumbs.py:60-61`).
+- If you commit the regenerated JSON in the same PR, expect the bot to produce a no-op (or a
+  redundant) follow-up commit; committing it yourself keeps the PR self-consistent. Either
+  way it is a generated artifact — never hand-edit it.
+
+---
+
+## 5. `mkdocs.yml` — `docs_dir`, `exclude_docs`, `not_in_nav`, macros/snippets config
+
+- **`docs_dir`:** not set anywhere in `mkdocs.yml` → defaults to `docs/`. All nav paths and
+  content live under `docs/`.
+- **`exclude_docs`** (`mkdocs.yml:4-5`):
+
+  ```yaml
+  exclude_docs: |
+    snippets/
+  ```
+
+  Only `docs/snippets/` is excluded from the build (they are `--8<--` includes, not pages).
+- **`not_in_nav`:** **not present** in `mkdocs.yml`. There is no allow-list of intentionally
+  un-navigated pages, so any page under `docs/` that is not in `nav:` (and not excluded) is a
+  `--strict` orphan warning. → **Every new Agentic AI / Using AI Agents page must be added to
+  `nav:`** (invariant §4).
+- **`macros` plugin** (`mkdocs.yml:94`): declared as a bare `- macros` with **no config
+  block** (no `module_name`, no `include_dir`). The macros module is `main.py` at repo root
+  (the mkdocs-macros default `main`). Extend macros there, don't fork prose (invariant §7).
+- **Snippets:** there is **no `snippets` plugin**; snippet includes come from the markdown
+  extension `- pymdownx.snippets` (`mkdocs.yml:416`), also declared with **no config block**
+  (default base path = project root, so includes are written `--8<-- "docs/snippets/…"`).
+
+**Implication for "published verbatim config files":** if the Agentic AI docs need to show
+literal config files verbatim (e.g. an MCP/agent config), the clean options are (a) keep them
+as pages under `docs/agentic-ai/…` with fenced code blocks, or (b) store a canonical copy
+under `docs/snippets/` and pull it in with `--8<--` (snippets are build-excluded, so they
+won't orphan). A file placed under `docs/` that is neither in `nav:` nor under `snippets/`
+will trip the `--strict` orphan check. Also mind Jinja escaping: literal `{{`/`{%` in prose
+must be wrapped in `{% raw %}` because the `macros` plugin processes every page
+(invariant §7; `.agents/factory/style-guide.md:102-108`).
+
+---
+
+## 6. `--strict` baseline (known pre-existing warnings)
+
+Source: `.agents/factory/strict-baseline.txt`. Verify gate command
+(`.agents/factory/strict-baseline.txt:13`):
+
+```
+.venv/bin/mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py
+```
+
+Exit 0 = no *new* warnings vs baseline (PASS); exit 1 = a regression your change introduced.
+CI itself builds with `--verbose`, **not** `--strict`, so these ship silently today
+(`.agents/factory/strict-baseline.txt:5-9`). The **7 known pre-existing warnings**
+(`.agents/factory/strict-baseline.txt:25-31`), summarized:
+
+1. `software/ngc_catalog.md` — bad image link `../../assets/images/nvidia_logo.png` (should be
+   `../assets/...`). **Generated file — fix at `tools/`, not by hand.**
+2. `software/rocm_catalog.md` — bad image link `../../assets/images/rocm_logo.png`.
+   **Generated — fix at `tools/`.**
+3. `userguides/gilbreth/run_jobs/learning/customml.md` — broken `index.md` link (missing
+   `learning/index.md`).
+4. `userguides/gilbreth/run_jobs/learning/ml_batch.md` — same missing `learning/index.md`.
+5. `userguides/negishi/run_jobs/biocontainers.md` — wrong `../` depth on a biocontainers image.
+6. `userguides/negishi/run_jobs/windows/launcher.md` — wrong `../` depth on a windows image.
+7. `userguides/scholar/run_jobs/r_example.md` — broken cross-cluster link to a Gautschi
+   `example_r_profile_setup.md` (doubled `userguides/`).
+
+None touch `docs/index.md`, `docs/lifesciences/`, `docs/agentic-ai/`, or the Gautschi files
+being edited — so the drafter starts from a clean slate for the new work. The bar: introduce
+**zero** new `--strict` warnings. The #1 way to add one is getting relative-link `../` depth
+wrong (`.agents/factory/style-guide.md:138-140`), so count directory levels carefully on the
+new pages and hub links, and add every new page to `nav:` to avoid orphan warnings.
+Last baseline capture: 2026-07-14, mkdocs 1.6.1 / mkdocs-material 9.6.16
+(`.agents/factory/strict-baseline.txt:23`).
diff --git a/spec/agentic-ai-docs/research/02-macros-and-jinja.md b/spec/agentic-ai-docs/research/02-macros-and-jinja.md
new file mode 100644
index 00000000..c3c58522
--- /dev/null
+++ b/spec/agentic-ai-docs/research/02-macros-and-jinja.md
@@ -0,0 +1,321 @@
+# Research 02 — Macros, Jinja, and publishing verbatim config safely
+
+Scope: how the `mkdocs-macros` Jinja pass interacts with published content, the SAFEST way to
+publish verbatim harness config / `agents.d` context files (the #1 technical risk), the reusable
+macros we should call instead of hardcoding, and the policy-page archetype to mirror.
+
+All claims below are backed by file citations and by an isolated, empirical mkdocs build in
+`/tmp/macrotest` reproducing the exact stack (`mkdocs 1.6.1`, `mkdocs-macros-plugin 1.3.9`,
+`pymdown-extensions 10.16.1`) — versions from `requirements.txt:16-28`.
+
+---
+
+## 0. TL;DR — the recommended verbatim pattern
+
+**Keep each harness config / context file as a REAL file on disk (exact bytes) under
+`docs/snippets/agentic-ai/…`, and embed it in a docs page inside a fenced code block via
+`--8<--`.** Proven immune to Jinja regardless of file content, single source of truth, syntax
+highlighted, and the surrounding page can still use `{{ macros() }}` freely.
+
+```markdown
+```json title="settings.json"
+--8<-- "docs/snippets/agentic-ai/claude/settings.json"
+```
+```
+
+(That outer fence is just for display here; on the page it is a single ```` ```json ```` block
+whose only body line is the `--8<--` directive.)
+
+Why it is safe: **the macros/Jinja pass runs on a page's OWN source BEFORE Markdown parsing;
+`pymdownx.snippets` splices `--8<--` files in DURING Markdown parsing, AFTER Jinja. Included
+content is therefore never Jinja-evaluated** (proven in §3). Do NOT paste config bodies directly
+into a page unless you wrap them in `{% raw %}…{% endraw %}` or set `render_macros: false` in the
+page front matter.
+
+---
+
+## 1. `main.py` macros to REUSE (signatures + what each EMITS)
+
+`main.py` registers macros via `@env.macro` inside `define_env(env)`. Two flavors: **inline
+f-strings** (built from `resource`) and **snippet-file readers** (read a `docs/snippets/*.md`
+file and string-substitute `{CLUSTER}`→`resource.title()`, `{cluster}`→`resource.lower()`).
+
+The invocation idiom (used on every cluster page and documented in `docs/templates.md:70-89`):
+
+```markdown
+{% set resource = "gautschi" %}      <!-- Jinja var, set once at top of page -->
+{{ module_system(resource) }}        <!-- each macro emits a block of markdown -->
+```
+
+`{% set resource = "anvil" %}` is real Jinja executed by the macros plugin (see
+`docs/userguides/anvil/policies.md:10`). `resource.title()` → `Gautschi`, `resource.lower()` →
+`gautschi` (naming convention noted at `main.py:1-4`).
+
+| Macro (signature) | Kind | Emits | Citation |
+|---|---|---|---|
+| `resource_use(resource)` | snippet reader (special) | The standard **"Acceptable Purdue IT Research Resource Use"** block: queuing-system policy, links to Purdue IT Policy V.4.1 & Remote Access V.1.6, User Credential Standards, and the activity-logging notice. For `anvil` it deletes the credential-standards lines (`lines[4:6]`). | `main.py:742-748`; source text `docs/snippets/resourceuse.md` |
+| `module_system(resource)` | inline f-string | Full **Lmod / `module`** walkthrough for `{resource.title()}`: `module spider/avail/load/unload/purge/show`, hierarchical modules, auto default compiler/MPI, `$RCAC_APPNAME_ROOT/_VERSION`. | `main.py:540-632` |
+| `slurm_general_overview(resource)` | inline f-string | The **"## Overview / Slurm Basics"** section: what Slurm is, "SSH lands on a login node" note, "don't run jobs on login nodes" warning, the queue concept — for `{resource.title()}`. | `main.py:246-266` |
+| `slurm_general_jobs(resource)` | inline f-string | The large Slurm job tutorial: **Job Submission Script** (sample `#SBATCH`), env-var table, **Submitting a Job** (`sbatch`), multi-node, **Interactive jobs** (`sinteractive`), redirecting output, holding jobs — for `{resource.title()}`. | `main.py:268-430` |
+| `ssh_keys_snippet(resource)` | inline f-string | **"### SSH Keys general overview"** + Mac/Linux `ssh-keygen`/`ssh-copy-id` steps + Windows/PuTTY key-generation steps, all parameterized to `{resource}.rcac.purdue.edu`. | `main.py:27-129` |
+| `storage_quota(resource)` | snippet reader | The **storage-quota** section (`{CLUSTER}`/`{cluster}` substituted). | `main.py:688-692`; `docs/snippets/storage_quota.md` |
+| `scratch_space(resource)` | snippet reader | The **scratch-space** section. | `main.py:694-698`; `docs/snippets/scratch_space.md` |
+| `scratch_purge(resource)` | snippet reader (special) | The **scratch-purge policy**; per-cluster edits: `anvil`/`bell` → 60→30 days; `anvil` also strips the purge-warning-email + `purgelist` section and rewrites Depot/Fortress → "project space". | `main.py:750-795`; `docs/snippets/scratchpurge.md` |
+| `environment_variables(resource)` | snippet reader | The **environment-variables** section (only `{cluster}`→lower substituted). | `main.py:682-686`; `docs/snippets/environment_variables.md` |
+| `accounts_md_snippet(resource)` | inline f-string | The full **"# Accounts on {resource.title()}"** page body: obtaining an account, R4P note, and login methods (ThinLinc web / Gateway-OnDemand / SSH). | `main.py:488-532` |
+
+Other macros exist (SSH X11, ThinLinc, scp/sftp/globus/htar/hsi, apptainer/biocontainers/rocm,
+compile, recover_*) — same two patterns; read `main.py` before hardcoding anything (per CLAUDE.md).
+
+**Relevance to agentic-AI docs:** for HPC background sections (modules, Slurm, SSH, storage) prefer
+these macros over rewriting prose, e.g. `{{ module_system(resource) }}`, `{{ slurm_general_overview(resource) }}`.
+
+---
+
+## 2. `mkdocs.yml` — plugin & extension config that governs the risk
+
+**`macros` plugin** is registered with **NO options** (`mkdocs.yml:94`):
+
+```yaml
+plugins:
+  - search
+  - blog: …
+  - tags: …
+  - git-revision-date-localized: …
+  - rss: …
+  - macros            # <-- line 94, bare, so ALL defaults apply
+```
+
+Confirmed `mkdocs-macros-plugin 1.3.9` defaults (read from `MacrosPlugin.config_scheme`):
+
+| Option | Default | Consequence |
+|---|---|---|
+| `module_name` | `'main'` | `main.py` at repo root is auto-loaded (no override needed). |
+| `render_by_default` | `True` | **Every page is Jinja-rendered.** Opt out per page with `render_macros: false` in front matter. |
+| `on_undefined` | `'keep'` | A **bare** undefined variable `{{ FOO }}` is kept literally, no error. |
+| `on_error_fail` | `False` | A Jinja **error** does not fail a plain build — it logs and (in non-strict) deploys a broken page. |
+| `j2_variable_start_string` / `j2_block_start_string` | `''` (Jinja defaults `{{` / `{%`) | Triggers are the standard `{{`, `{%`, `{#`. |
+
+**`markdown_extensions`** (`mkdocs.yml:404-425`), relevant parts:
+
+```yaml
+markdown_extensions:
+  - toc: { permalink: true }
+  - tables
+  - attr_list
+  - md_in_html
+  - admonition
+  - pymdownx.details
+  - pymdownx.blocks.caption
+  - pymdownx.emoji: { … }
+  - pymdownx.snippets            # <-- line 416, bare, ALL defaults apply
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+      linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences         # <-- line 423, bare
+  - pymdownx.tabbed: { alternate_style: true }
+```
+
+**`pymdownx.snippets` is bare (`mkdocs.yml:416`)**, so its defaults apply (read from source):
+
+| Option | Default | Consequence |
+|---|---|---|
+| `base_path` | `['.']` | Include paths resolve from the dir mkdocs runs from = **repo root**. So `--8<-- "docs/snippets/…"` is correct (matches all existing includes). Prod confirms it: `Dockerfile.geddes-prod` does `WORKDIR /docs` → `COPY . .` → `mkdocs build`, i.e. runs from the repo-root copy (`Dockerfile.geddes-prod:4,9,13`). |
+| `restrict_base_path` | `True` | Cannot include files **outside** the repo tree → canonical files must live inside the repo. |
+| `check_paths` | **`False`** | **Footgun:** a mistyped/missing include path silently yields an **empty** code block — no error, even under `--strict`. Mitigate by eyeballing the render (verify gate) or, optionally, enabling `check_paths: true`. |
+| `url_download` | `False` | No remote includes; files must be local. |
+
+`pymdownx.highlight` gives `linenums: true` globally, so every fenced block gets line numbers —
+fine for showing config. `pymdownx.superfences` enables the fenced blocks / nesting we rely on.
+
+Note `exclude_docs: | snippets/` (`mkdocs.yml:4-5`) — anything under `docs/snippets/` is **not
+built as a standalone page**, so putting canonical files there does NOT create nav orphans
+(satisfies invariant #4) while remaining `--8<--`-includable.
+
+---
+
+## 3. The escaping solution — processing order, proven empirically
+
+### Processing order (the key fact)
+1. **mkdocs-macros runs Jinja on a page's OWN markdown source** (pre-page phase), with `main.py`
+   macros + `mkdocs.yml` `extra:` vars + front-matter `{% set %}` vars in scope.
+2. **Then Markdown conversion runs**; `pymdownx.snippets` (`--8<--`) splices file contents in as
+   raw text during the Markdown preprocessor phase — **after** Jinja.
+
+⇒ **Content pulled in by `--8<--` is never seen by Jinja.** Literal `{{`/`{%`/`{#` in an included
+file passes straight through.
+
+### Empirical proof (isolated `/tmp/macrotest`, exact stack, `mkdocs build --strict`, exit 0)
+- **Macros run on page source:** `{{ hello("A") }}` in a page → rendered `MACRO_EMITTED[A]`.
+- **`--8<--` includes are NOT Jinja-processed:** an included file containing
+  `"echo {{ THIS_WOULD_BREAK }}"` and `{% if x %}…{% endif %}` rendered **verbatim** (found in
+  HTML, no error). Had Jinja seen it, the function/undefined-tag would have errored.
+- **A raw `.json`/`.toml` file embedded INSIDE a fenced block works:** a real `settings.json`
+  containing `{{ this_is_not_jinja }}`, `${{ github.token }}`, and `{% raw %}…{% endraw %}`,
+  included via ```` ```json … --8<-- "…/settings.json" … ``` ````, rendered verbatim with syntax
+  highlighting, `--strict` exit 0 — **and** a `{{ hello("still-works") }}` macro on the same page
+  still evaluated. This is the recommended pattern.
+- **`{% raw %}…{% endraw %}` around a fenced block in a page's own source works:** a block with
+  `"{{ user }}"` and `"{% for f in files %}{{ f }}{% endfor %}"` rendered verbatim.
+- **`render_macros: false` front matter disables Jinja for the whole page:** a page with
+  `{{ BOOM }}` and `{% if x %}` in a code block rendered verbatim, `--strict` exit 0.
+
+### The risk, quantified (why this matters)
+- A **bare undefined variable** `{{ FOO }}` → kept (because `on_undefined: keep`), `--strict` exit 0.
+- **BUT** a function call / attribute / filter / unknown tag — e.g. `{{ nope_fn("z") }}`,
+  `{{ a.b }}`, `{% unknowntag %}` — raises `UndefinedError`/`TemplateSyntaxError`. Measured:
+  under `mkdocs build --strict` this **aborts (exit 1, "Aborted with 1 warnings in strict mode")**;
+  under plain `mkdocs build` (what CI/prod uses, per CLAUDE.md) it logs an ERROR but **exits 0 and
+  deploys a garbled page**. Only the factory's `--strict` verify gate catches it.
+- Harness config/context files WILL contain such triggers: Warp workflow YAML uses `{{arg}}`
+  placeholders; GitHub-Actions / Go-template / Jinja examples use `${{ … }}` and `{{ .Var }}`;
+  hooks and context markdown can contain `{%`. JSON single braces (`{ "a": 1 }`) are NOT triggers
+  (Jinja needs doubled `{{`/`{%`), and a lone `}}` is harmless — but you cannot safely hand-audit
+  every file. Make the mechanism immune instead.
+
+### Existing precedent in the repo
+- `docs/templates.md:70-83` documents the intended escape: to *show* macro syntax literally it
+  wraps `{% set resource = "gautschi" %}` and `{{ ssh_keys_snippet(resource) }}` in
+  `{% raw %} … {% endraw %}`.
+- Live proof that snippets bypass Jinja: `docs/snippets/examples/apps/mathematica.md:66` contains
+  a **lone `{% endraw %}`** (no opening `{% raw %}`). It is `--8<--`-included with **no** raw
+  wrapper by `docs/userguides/hammer/run_jobs/examples/apps/mathematica.md:11` and the bell
+  equivalent — and the site builds. A lone `{% endraw %}` would be a fatal `TemplateSyntaxError`
+  if snippets were Jinja-processed; it is not, confirming the ordering. (It does render as stray
+  literal text on those pages — a pre-existing cosmetic bug, not ours to fix here.)
+
+### Ranking of the three safe options
+1. **`--8<--` include of a real file inside a fenced block (RECOMMENDED)** — single source of
+   truth (the on-disk file is the exact, copyable, operationally-usable config), zero escaping,
+   syntax-highlighted, page keeps macro access. Only caveat: `check_paths:false` means a bad path
+   fails silently → verify by rendering.
+2. **`{% raw %}…{% endraw %}` around an inline fenced block** — good when the content is short and
+   you want it literally in the page file, but it **duplicates** the config (two copies to keep in
+   sync) — violates single-source-of-truth; use only for tiny snippets.
+3. **`render_macros: false` front matter** — bulletproof but all-or-nothing: the whole page loses
+   `{{ macro() }}` access. Use only for a page that is *entirely* verbatim config and needs no macros.
+
+---
+
+## 4. Policy-page archetype (`docs/userguides/anvil/policies.md`) + `resourceuse.md`
+
+**Gautschi has NO `policies.md`** — confirmed: `find docs -name policies.md` returns only
+`docs/userguides/anvil/policies.md`. The policy archetype currently exists for Anvil alone, so
+there is no per-cluster policy parallelism to maintain (invariant #10 doesn't bind here).
+
+**Structure to mirror** (`docs/userguides/anvil/policies.md`):
+```markdown
+---
+tags:
+  - Anvil            # cluster/topic tag(s)
+authors:
+  - dane             # from docs/blog/.authors.yml
+---
+
+# Anvil Policies      <!-- single H1 -->
+
+{% set resource = "anvil" %}     <!-- sets Jinja var so macros can be called -->
+
+## Software Installation Request Policy    <!-- prose section -->
+…
+## Helpful Tips                             <!-- bulleted etiquette / good-citizen -->
+…
+## Acceptable Purdue IT Research Resource Use
+{{ resource_use(resource) }}               <!-- reused standard AUP block -->
+
+## Scratch File Purging
+{{ scratch_purge(resource) }}
+```
+Notes: this page carries only `tags` + `authors` (no `resource:`/`search.boost:` — lighter than a
+cluster user-guide article). It opens with `{% set resource = … %}` then mixes hand-written
+sections with macro-emitted standard blocks.
+
+**`docs/snippets/resourceuse.md`** (rendered by `resource_use`) is the reusable acceptable-use
+text: 4 short paragraphs — (1) use the queuing system / specify cores accurately; (2) comply with
+**Purdue IT Acceptable Use Policy V.4.1** and **Remote Access Policy V.1.6** (linked); (3) refer
+to **User Credential Standards**; (4) activity is logged/archived/analyzed (modules, apps, perf
+counters, disk, job scripts). Line 1 is an HTML comment noting the `resource_use` macro mutates it
+per resource (drops the credential-standards line for Anvil).
+
+**For our agentic-AI acceptable-use page:** mirror this archetype — front matter (`tags` +
+`authors`), one H1, hand-written policy/etiquette sections, and reuse `{{ resource_use(resource) }}`
+if we want the canonical Purdue AUP block verbatim. Because agentic-AI policy is likely
+cross-cluster, either pick a representative `resource` for the AUP block or link Purdue Policy
+V.4.1 / V.1.6 directly rather than `{% set %}`-ing a single cluster.
+
+---
+
+## 5. Concrete recommendation (copyable)
+
+### (a) Where canonical files live
+Store the exact harness config + `agents.d` context files as **real files** under a new
+`docs/snippets/agentic-ai/` tree (excluded from page build by `exclude_docs: snippets/`, still
+`--8<--`-includable, resolves in prod). Suggested layout:
+
+```
+docs/snippets/agentic-ai/
+  claude/settings.json
+  codex/config.toml
+  gemini/settings.json
+  opencode/opencode.json
+  warp/warp.yaml
+  agents.d/unix.md
+  agents.d/filesystems.md
+  agents.d/lmod.md
+  agents.d/slurm.md
+  agents.d/policies.md
+```
+These files hold the byte-exact config/context (single source of truth). If they must also match
+files deployed to `/etc/agents.d`, keep them here and treat this as canonical (or symlink/copy in
+tooling) — but the files themselves stay inside the repo tree (`restrict_base_path: true`).
+
+### (b) How to render them (builds clean under `--strict`, single source of truth)
+On the published page (which lives under `docs/…` and IS in `nav:` per invariant #4), embed each
+file inside a fenced code block. No `{% raw %}` needed — the include is post-Jinja:
+
+````markdown
+## Claude Code — `settings.json`
+
+Drop this at `~/.claude/settings.json`:
+
+```json title="~/.claude/settings.json"
+--8<-- "docs/snippets/agentic-ai/claude/settings.json"
+```
+
+## `/etc/agents.d/slurm.md`
+
+```markdown title="/etc/agents.d/slurm.md"
+--8<-- "docs/snippets/agentic-ai/agents.d/slurm.md"
+```
+````
+
+The surrounding page can still freely use macros in its prose, e.g.
+`{% set resource = "gautschi" %}` … `{{ slurm_general_overview(resource) }}`.
+
+Choose the ```` ```<lang> ```` fence to match each file: `json` (Claude/Gemini/opencode), `toml`
+(Codex), `yaml` (Warp), `markdown` (agents.d/*). `title="…"` (an `attr_list`/superfences feature,
+already enabled) labels the block with the on-disk path.
+
+### Verification (per CLAUDE.md verify gate)
+```bash
+mkdocs build --strict 2>&1 | python3 .agents/factory/bin/strict_check.py   # no NEW warnings
+mkdocs serve   # eyeball: config renders verbatim, no empty blocks (check_paths:false is silent)
+```
+Confirm every new published page is added to `mkdocs.yml` `nav:` (snippet files are correctly NOT
+in nav). Because `check_paths` is off, a typo'd `--8<--` path fails silently — the visual render
+check is the safety net.
+
+---
+
+## Appendix — files cited
+- `main.py` (macros; lines cited per macro above)
+- `mkdocs.yml:4-5` (exclude_docs), `:94` (macros bare), `:404-425` (extensions), `:416/423` (snippets/superfences)
+- `docs/templates.md:32-89` (snippet + macro + `{% raw %}` precedent)
+- `docs/userguides/anvil/policies.md` (policy archetype)
+- `docs/snippets/resourceuse.md` (reusable AUP text)
+- `docs/snippets/examples/apps/mathematica.md:66` + `docs/userguides/hammer/run_jobs/examples/apps/mathematica.md:11` (lone `{% endraw %}` in an unwrapped include — live proof snippets bypass Jinja)
+- `Dockerfile.geddes-prod:4,9,13` (prod builds from repo root → snippet base_path resolves)
+- Empirical harness: `/tmp/macrotest` (mkdocs 1.6.1 / macros 1.3.9 / pymdownx 10.16.1)
diff --git a/spec/agentic-ai-docs/research/03-gautschi-facts.md b/spec/agentic-ai-docs/research/03-gautschi-facts.md
new file mode 100644
index 00000000..92096cbb
--- /dev/null
+++ b/spec/agentic-ai-docs/research/03-gautschi-facts.md
@@ -0,0 +1,323 @@
+# Gautschi Cluster Facts Sheet (citable)
+
+Purpose: exact, citable Gautschi facts for authoring the shared-context files `slurm.md`,
+`filesystems.md`, `lmod.md`, `unix.md`, `policies.md`. HPC accuracy is safety-critical —
+every fact below carries a `path:line` citation. Anything not verifiable in the source tree
+is marked `[UNCONFIRMED]`.
+
+All paths are relative to repo root
+`/Users/geoffrey/Software/github.com/purduercac/RCAC-Docs`.
+
+IMPORTANT META-NOTE ON WHERE TEXT LIVES: many Gautschi storage/account pages are thin
+wrappers that pull real text from `main.py` macros or `docs/snippets/*.md`. Citations below
+point at the actual source of the text (the macro/snippet), not just the wrapper page.
+
+---
+
+## 1. SYSTEM
+
+- **OS:** Rocky Linux 9. "Gautschi nodes run Rocky Linux 9 and use Slurm ... as the batch
+  scheduler." — `docs/userguides/gautschi/overview.md:40`. (Note: one apptainer example page
+  shows `CentOS Linux release 7.3.1611` inside a *container* image — that is container OS, not
+  the host — `docs/userguides/gautschi/run_jobs/apptainer_example.md:45`.)
+- **Scheduler:** Slurm — `overview.md:40`, `run_jobs/index.md:14`.
+- **CPU compute node (sub-cluster A):** Two AMD EPYC 9654 96-core "Genoa" CPUs @ 2.4 GHz =
+  **192 cores/node, 384 GB memory**; 400 Gbps NDR InfiniBand; 338 nodes; retires 2030.
+  — `overview.md:12`, `overview.md:22`, `overview.md:34`.
+- **High-memory node (sub-cluster B):** Two AMD EPYC 9654 96-core "Genoa" @ 2.4 GHz = 192
+  cores, **1.5 TB memory**; 6 nodes. — `overview.md:35`, `run_jobs/queues.md:98`.
+- **Small-GPU node (sub-cluster G):** Two AMD EPYC 9554 64-core "Genoa" @ 3.1 GHz = 128
+  cores, 384 GB memory, **Two NVIDIA L40S GPUs (48 GB each)**; 6 nodes.
+  — `overview.md:36`, `run_jobs/queues.md:131`.
+- **GPU/AI node (sub-cluster H):** Two Intel Xeon Platinum 8480+ 56-core CPUs @ 3.8 GHz = 112
+  cores, **1 TB CPU memory**, **Eight NVIDIA H100 GPUs (80 GB each)**, 8-way NVLinked; 20
+  nodes. — `overview.md:37`, `run_jobs/queues.md:75`. (`overview.md:22` says "1032 GB",
+  `overview.md:12` says "1031 GB", table `overview.md:37` says "1TB" — minor internal
+  inconsistency; treat as ~1 TB. `[UNCONFIRMED exact GB]`.)
+- **Interconnect:** 400 Gbps NDR InfiniBand on all compute nodes — `overview.md:12`,
+  `overview.md:22`.
+- **Front-end / login nodes:** **8 front-end nodes**, each Two AMD EPYC 9654 96-core "Genoa"
+  @ 2.4 GHz = 192 cores, **768 GB memory** — `overview.md:24-28`. (Observed login node
+  hostname `login02` in an scontrol example — `run_jobs/monitoring_job.md:44`.)
+- **Login hostname:** `gautschi.rcac.purdue.edu`. SSH form:
+  `ssh username@gautschi.rcac.purdue.edu` — `main.py:520`, `main.py:528`, `main.py:52`
+  (`ssh-copy-id ... username@{resource}.rcac.purdue.edu`, resource=gautschi via
+  `accounts.md:12`).
+- **Compute node naming:** `gautschi-a001.rcac.purdue.edu` style; short names `a166`,
+  `a[014-015]` — `run_jobs/simple_job.md:45`, `run_jobs/monitoring_job.md:46`,
+  `run_jobs/multiple_node.md:28`, `run_jobs/mpi_jobs.md:69`.
+- **Other access endpoints:** ThinLinc remote desktop `desktop.gautschi.rcac.purdue.edu`
+  (`main.py:181`, `main.py:190-191`, `index.md:19`); Open OnDemand "Gateway"
+  `gateway.gautschi.rcac.purdue.edu` (`main.py:509`, `index.md:15`).
+- **Authentication:** SSH public keys OR Purdue MFA (two-factor). "Gautschi supports either
+  Purdue's MFA two-factor authentication or SSH keys." — `main.py:515`. Password login:
+  "enter your Purdue career account password. Your MFA app will then receive a notification to
+  approve the login." — `main.py:531`; Gateway: "Career account username and Purdue Login MFA
+  client" — `docs/userguides/gautschi/gateway.md:20`. SSH-key setup is a 3-step
+  keygen/copy/test flow — `main.py:28-70`. **`[UNCONFIRMED]`: the term "BoilerKey" does not
+  appear anywhere in the Gautschi docs or `main.py`; the docs say "Purdue Login MFA" / "MFA".**
+- **Account eligibility:** must be in a research group that purchased access; external
+  collaborators need a valid Purdue career account (R4P if none) — `main.py:492-497`.
+
+## 2. SLURM
+
+### Account / allocation model
+- Every Gautschi job request has **four parts**: resources, **account** (`-A/--account=`),
+  **QOS** (`-q/--qos=`), and **partition** (`-p/--partition=`) — `run_jobs/queues.md:14-19`.
+- **You MUST explicitly specify BOTH the account and the partition.** "you must explicitly
+  define the account that you want to submit to using the '-A/--account=' option"
+  (`queues.md:27`); "instead of only needing to specify the account name in the job script,
+  the desired partition must also be specified." (`queues.md:47`).
+- Accounts = queues, named after the purchasing partner; behave like bank accounts of
+  purchased cores / GPU-hours. Use **`slist`** to list your accounts and their balances —
+  `queues.md:25`, `run_jobs/mpi_jobs.md:127`, `run_jobs/gpu_usage_monitoring.md:106`.
+- "standby"/"highmem"/"gpu" are **no longer accounts** on Gautschi (they were on older
+  clusters) — they are now QOS/partitions — `queues.md:27`, `queues.md:41`.
+
+### QOS model
+Two QOS classes: **Partition QOS** (auto-applied by the partition) and **Job QOS** (chosen
+with `-q/--qos=`) — `queues.md:31-36`. Job QOSes available to every user/account:
+- **`normal`** (default if no `-q` given): high priority, no extra limits — `queues.md:40`.
+- **`standby`** (opt-in `-q standby`/`--qos=standby`): access to idle resources, **low
+  priority, max 4 hours**, usage **NOT** charged against the account; replaces the old
+  `-A standby` style — `queues.md:41`.
+- **`preemptible`** (AI partition only, `-q preemptible`): low priority, charged **0.25
+  GPU-hour per GPU per hour** (4x cheaper), max 2 weeks, **can be cancelled/preempted** to make
+  room for `normal` jobs — "imperative to use checkpointing" — `queues.md:87-92`.
+
+### Partitions (authoritative list from queues.md)
+| Partition | Nodes | Node type | Cores/node | Memory model | GPUs | QOSes | Max walltime | Submit |
+|---|---|---|---|---|---|---|---|---|
+| **`cpu`** | 336 Gautschi-A | AMD EPYC 9654, 192c | 192 | ~2 GB/core requested | — | normal, standby | normal: **2 weeks**; standby: 4 h | `-p cpu` |
+| **`ai`** | 20 Gautschi-H | Intel Xeon 8480+, 112c | 112 | ~9 GB/core requested | 8× H100 80 GB/node (160 total) | normal, preemptible | **2 weeks** | `-p ai` |
+| **`highmem`** | 6 Gautschi-B | AMD EPYC 9654, 192c | 192 | ~8 GB/core; 1.5 TB/node | — | normal | **24 h** | `-p highmem` |
+| **`profiling`** | 2 Gautschi-A | AMD EPYC 9654 (perf counters) | 192 | whole-node only | — | normal | **24 h** | `-p profiling` |
+| **`smallgpu`** | 6 Gautschi-G | AMD EPYC 9554, 128c | 128 | ~3 GB/core | 2× L40S 48 GB/node | normal | **24 h** | `-p smallgpu` |
+
+Citations: cpu `queues.md:49-71`; ai `queues.md:73-94`; highmem `queues.md:96-110`; profiling
+`queues.md:112-127`; smallgpu `queues.md:129-142`.
+
+Partition-specific limits/notes:
+- **cpu:** memory ~2 GB per requested core; `normal` withdraws cores from account until job
+  ends; GPU-only groups may use `cpu` only via `standby` — `queues.md:51-69`.
+- **ai:** memory ~9 GB per requested core; `normal` charges **1 GPU-hour per GPU per hour**
+  (tracked by the minute) — `queues.md:75-85`.
+- **highmem:** ~8 GB/core; **no expectation of start time**; max **2 running / 8 submitted**
+  jobs; **your job must use more than 48 of the 192 cores** — `queues.md:102-108`.
+- **profiling:** hardware perf counters (e.g. AMD MicroProf); **whole-node only**; max 1
+  running job; monitored to prevent use as plain compute — `queues.md:114-125`.
+- **smallgpu:** ~3 GB/core; request cores proportional to GPUs used; up to **2 GPUs**; max 8
+  submitted jobs — `queues.md:131-140`.
+
+### Default limits
+- Access sold in units of 48 cores (quarter of a CPU node) or a 5-GPU-year package —
+  `overview.md:14`.
+- **`[UNCONFIRMED]`: no explicit default walltime or default node/core count is stated on any
+  Gautschi page.** (The generic `main.py` macro `slurm_general_jobs` states "time: 30 minutes,
+  nodes: 1" at `main.py:335-336`, but that macro is NOT invoked by any Gautschi page — see
+  §Modules note — so do not attribute it to Gautschi.)
+
+### Example real `#SBATCH` directives (gold-standard submit script)
+From `run_jobs/creating_the_submission_script.md:15-34` (cpu partition):
+```bash
+#!/bin/bash
+# FILENAME:  myjobsubmissionfile
+#SBATCH --account=myLabAccount
+#SBATCH --partition=cpu
+#SBATCH --qos=normal
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --time=1-00:00:00
+module load matlab
+cd $SLURM_SUBMIT_DIR
+matlab -nodisplay -singleCompThread -r myscript
+```
+Combined `-A ... -p ...` on one directive line — `run_jobs/directives.md:26-28`. Full
+command-line form: `sbatch -A myLabAccount -p cpu -q normal -N1 -n1 -t 1-00:00:00 file`
+— `run_jobs/submit_script.md:28`.
+
+### Slurm / cluster commands referenced in Gautschi docs (verified present)
+- **`sbatch`** — submit batch job — `submit_script.md:16`, `directives.md:16`.
+- **`squeue -u <user>`** — view your jobs — `monitoring_job.md:15,21`.
+- **`scontrol show job <id>`** — job detail — `monitoring_job.md:31`.
+- **`scontrol hold job <id>` / `scontrol release job <id>`** — hold/release —
+  `docs/snippets/holding_job.md` (included by `run_jobs/holding_job.md:11`).
+- **`scancel <jobid>`** — cancel job — `docs/snippets/cancelling_job.md:6` (included by
+  `run_jobs/cancelling_job.md:11`).
+- **`sinteractive -A <acct> -p <part> -N.. -n..`** — interactive job — `interactive_jobs.md:15-21`.
+- **`srun` / `mpiexec`** — launch MPI ranks; `srun --mpi=pmi2` for Intel MPI —
+  `mpi_jobs.md:35,44,47`, `monitoring_resources.md:53,62`.
+- **`slist`** — list accounts / balances (incl. GPU-hour balance) — `queues.md:25`,
+  `mpi_jobs.md:127`, `gpu_usage_monitoring.md:106`, `gateway/jobs.md:17`,
+  `gaussian_example.md:110`.
+- **`sfeatures`** — node/GPU feature detail — `gpu_jobs.md:92`.
+- **`myquota`** — home/scratch quota — `docs/snippets/storage_quota.md:8`.
+- **`findscratch`** — print scratch path — `docs/snippets/scratch_space.md:15`.
+- **`purgelist`** — files scheduled for scratch purge — `docs/snippets/scratchpurge.md:21-24`.
+- **`monitor`** (module) — resource telemetry — `monitoring_resources.md:21-25`.
+- **`[UNCONFIRMED]`: `sinfo`, `sacct`, `jobinfo`, `mybalance`, `showpartitions`, `wait_time`
+  do NOT appear anywhere under `docs/userguides/gautschi/`** (grep-verified). `mybalance`,
+  `showpartitions`, `wait_time`, and the `wholenode` partition appear only in the generic
+  `main.py` macro `slurm_general_jobs` (`main.py:301-391`), which Gautschi does not use — do
+  not present them as Gautschi commands.
+
+### KNOWN DOC ERRORS to NOT propagate (copy-paste leftovers from Gilbreth)
+- `run_jobs/gpu_jobs.md:41,49-51` and `run_jobs/mpi_jobs.md:32` use **`--partition=a10`**,
+  which is **not a Gautschi partition** (valid GPU partitions are `ai` and `smallgpu`).
+  Grep count: 7 uses of `--partition=a10` under gautschi. **Do not use `a10` in generated docs.**
+- `run_jobs/mpi_jobs.md:94` uses **`#SBATCH -A standby`** — invalid on Gautschi (standby is a
+  QOS `-q standby`, not an account). — contradicts `queues.md:41`.
+
+## 3. MODULES (Lmod)
+
+- Gautschi's `software.md` demonstrates module use directly with **`module avail`**,
+  **`module spider <name>`**, **`module load <name>/<version>`** — `software.md:23-56`.
+  (`module spider` is an Lmod-specific command, so the module system is **Lmod**; note the
+  word "Lmod" itself is only in the `module_system` macro, which Gautschi does **not** invoke —
+  see below. `[UNCONFIRMED that a Gautschi page literally names "Lmod"]`.)
+- **Default compiler + MPI (recommended):** **GCC 14.1.0** and **OpenMPI** —
+  `overview.md:42-45`. `[UNCONFIRMED: exact OpenMPI version not stated on any Gautschi page.]`
+- Example load lines: `module load hypershell/2.7.0` (`software.md:55`), `module load cuda`
+  (`gpu_jobs.md:26`), `module load matlab` (`creating_the_submission_script.md:27`),
+  `module load monitor` (`monitoring_resources.md:24`).
+- Core Applications sample (`module avail`) includes `amduprof/5.1.701`,
+  `anaconda/2024.10-py312`, `anaconda/2025.06-py313 (D)`, `hypershell/*`, `ngc/default`,
+  `oclfpga/2024.1.0`, `openblas/0.3.27` — `software.md:25-29`.
+- **Do NOT attribute the generic Lmod write-up to Gautschi:** the `module_system(resource)`
+  macro (`main.py:540-632`, describes hierarchy, `module unload/purge/show/help`,
+  `$RCAC_APPNAME_ROOT`, auto compiler/MPI/CUDA loading) is invoked by anvil/bell/gilbreth/
+  hammer/negishi software pages **but not by Gautschi** (grep-verified: `module_system` usage
+  is in `docs/userguides/{anvil,bell,gilbreth,hammer,negishi}` only). Those extra module
+  commands are RCAC-standard and almost certainly apply, but are `[UNCONFIRMED for Gautschi
+  specifically]` from the Gautschi page set. General module commands (`module unload`,
+  `module purge`, `module list`, `module show`) do appear in Gautschi job-script examples/prose
+  via `main.py:360-363` only if a Gautschi page calls that macro — it does not; however
+  `module purge`/`module list` appear as generic script comments. Verified in-Gautschi:
+  `module avail`, `module spider`, `module load` (software.md), `module avail openmpi`
+  (`mpi_jobs.md:18`).
+
+## 4. FILESYSTEMS
+
+Text lives in `main.py` macros / `docs/snippets/`; wrapper pages just include them.
+
+- **Home directory:** path **`/home/myusername`**, env var **`$HOME`**. On GPFS. Long-term,
+  medium-performance, **not** for heavy-I/O jobs. — `docs/snippets/home_directory.md:8-13,29-34`
+  (included via `storage/home_directory.md:11`). Snapshots: **nightly for 7 days, weekly for 4
+  weeks, monthly for 3 months** — `home_directory.md:27`.
+- **Home quota:** the `myquota` example shows a **25.0 GB** home limit
+  (`docs/snippets/storage_quota.md:14-15`), but this is illustrative example output in a shared
+  snippet, and home quota "cannot be increased beyond current level"
+  (`storage_quota.md:54`). **`[UNCONFIRMED: 25 GB is an example, not a Gautschi-stated
+  official quota.]`**
+- **Scratch:** path **`/scratch/gautschi/myusername`** (`{cluster}` = `gautschi`), env var
+  **`$RCAC_SCRATCH`** (NOT `$CLUSTER_SCRATCH`). Find it with **`findscratch`**. High-
+  performance parallel filesystem; not backed up; not recoverable. — `docs/snippets/
+  scratch_space.md:12-27` (via `storage/scratch_space.md:11`), `docs/snippets/
+  environment_variables.md:12,28,37`. **CORRECTION to task hypothesis: the variable is
+  `$RCAC_SCRATCH`, and there is no `$CLUSTER_SCRATCH` in these docs.**
+- **Scratch purge policy:** **files not accessed or content-modified in 60 days are purged**
+  (Gautschi uses the default 60-day threshold; only Anvil/Bell are rewritten to 30 days by
+  `main.py:755-757`). — `docs/snippets/scratch_space.md:10`, `docs/snippets/scratchpurge.md:10`,
+  `scratchpurge.md:67`. Purge is by last access + content-modification time; metadata changes
+  don't protect a file; no warning emails; use `purgelist` to see candidates —
+  `scratchpurge.md:8-19,21-33`.
+- **Scratch quota:** `myquota` example shows scratch **100.0 TB / 2,000k files**
+  (`storage_quota.md:15`) — illustrative example output, not a Gautschi-official figure.
+  **`[UNCONFIRMED exact Gautschi scratch quota.]`** Quota increases available on request
+  (`storage_quota.md:58`).
+- **/tmp:** node-local short-term storage on each front-end/compute node; data lives only
+  while the program runs; not backed up; not recoverable — `docs/snippets/tmp_directory.md:4-6`
+  (via `storage/tmp_directory.md:11`).
+- **Data Depot:** long-term storage for active research data (purchasable); listed as an
+  archival target for staging scratch data — `docs/snippets/scratchpurge.md:6,47,51`;
+  purchasable via `storage_quota.md:54`. `[UNCONFIRMED: no Gautschi page states the Depot mount
+  path or per-space quota; Depot path is typically `/depot/<group>` on RCAC but not cited here.]`
+- **Fortress (long-term / archive):** HPSS archival system, **>10 PB** capacity; use `hsi`/
+  `htar`. — `docs/snippets/long_term_storage.md:4-9` (via `storage/long_term_storage.md:11`),
+  `scratch_space.md:4`.
+- **Quota-check command:** **`myquota`** (reports home + scratch, size and file-count) —
+  `docs/snippets/storage_quota.md:8-16`.
+- **Storage environment variables:** `HOME` = `/home/myusername`; `PWD`; `RCAC_SCRATCH` =
+  `/scratch/gautschi/myusername` — `docs/snippets/environment_variables.md:10-12`.
+- **Slurm/runtime env vars documented for Gautschi:** `SLURM_SUBMIT_DIR` (used in gold
+  submit script, `creating_the_submission_script.md:30`), `SLURM_JOB_NODELIST`
+  (`multiple_node.md:20`), `CUDA_VISIBLE_DEVICES` (`gpu_jobs.md:30`). The fuller table
+  (`SLURM_SUBMIT_DIR`, `SLURM_JOBID`, `SLURM_JOB_NAME`, `SLURM_JOB_NODELIST`,
+  `SLURM_SUBMIT_HOST`, `SLURM_JOB_PARTITION`) exists in the generic macro `main.py:310-317`
+  but that macro is not used by Gautschi — the individual vars above ARE used in Gautschi pages.
+
+## 5. POLICIES
+
+- **Login-node "do not run compute" wording (quote it):**
+  > "Do NOT run large, long, multi-threaded, parallel, or CPU-intensive jobs on a front-end
+  > login host. All users share the front-end hosts, and running anything but the smallest
+  > test job will negatively impact everyone's ability to use Gautschi. Always use SLURM to
+  > submit your work as a job."
+  — `docs/userguides/gautschi/run_jobs/index.md:16-17` (an `!!! important` admonition).
+- **Front-end use policy (external link):** "The normal acceptable front-end use policy ...
+  applies" → <https://www.rcac.purdue.edu/policies/frontenduse> —
+  `docs/userguides/gautschi/gateway/cluster_tools.md:18`.
+- **Scratch purge policy (external link):**
+  <https://www.rcac.purdue.edu/policies/scratchpurge> — `docs/snippets/scratch_space.md:10`.
+- **Acceptable Use:** scratch snippet states using scratch as long-term storage or
+  circumventing purging "is considered a violation of Acceptable Research Resource Use"
+  — `docs/snippets/scratchpurge.md:71-73` (anchors to
+  `#acceptable-purdue-it-research-resource-use`). `[UNCONFIRMED: no direct link to a Purdue IT
+  AUP URL is present on the Gautschi pages read; the reference is an in-page anchor.]`
+- **Data-sensitivity guidance:** `[UNCONFIRMED]` — no explicit data-classification/sensitivity
+  (e.g. HIPAA/export-control/regulated-data) statement found in the Gautschi page set read.
+- **Network-drive access requires campus network/VPN** (CIFS "Z: drive") —
+  `docs/userguides/gautschi/faqs.md:29`.
+- **Data-retention / access removal:** losing Gautschi access removes mailing-list
+  subscription; copy data out first — `faqs.md:18`.
+- **Cluster lifetime:** hardware "service through 2030" / "Retires in 2030" — `overview.md:12`,
+  `overview.md:28,34-37`.
+
+## 6. UNIX / GENERAL
+
+- **Default shell:** `[UNCONFIRMED]` — no Gautschi page states the default login shell.
+  Submission-script examples use `#!/bin/bash` (e.g. `simple_job.md:18`,
+  `creating_the_submission_script.md:16`) and some generic examples `#!/bin/sh -l`
+  (`main.py:277`). The env-var snippet documents both bash (`export`) and tcsh/csh (`setenv`)
+  syntax — `docs/snippets/environment_variables.md:41-51`, implying csh/tcsh users exist.
+- **Home is CWD at login:** "Your home directory becomes your current working directory, by
+  default, when you log in." — `docs/snippets/home_directory.md:4`.
+- **Gautschi home is isolated:** the Gautschi home directory is exclusive to Gautschi front-
+  ends/compute nodes; not shared with or synced to other RCAC clusters — `faqs.md:32`.
+- **Scratch is per-cluster:** only `/scratch/gautschi` is mounted on Gautschi; no other
+  cluster's scratch is available — `docs/snippets/scratch_space.md:26-27`.
+- **Env-var best practice:** use `$HOME`, `$RCAC_SCRATCH`, etc. instead of hard-coded paths
+  (paths may change) — `docs/snippets/environment_variables.md:4`,
+  `docs/snippets/scratch_space.md:19`.
+- **Module gotcha:** the generic guidance "do not put `module load` in your bash profile (can
+  break ThinLinc init)" lives in the `module_system` macro (`main.py:587`) which Gautschi does
+  not invoke — `[UNCONFIRMED for Gautschi]` but standard RCAC advice.
+- **GUI apps:** launch via ThinLinc (Applications → Cluster Software) — `faqs.md:38-41`.
+- **X11 forwarding:** supported via `ssh -Y`; `$DISPLAY` must be left as SSH sets it —
+  `main.py:159,162`.
+- **App-specific gotchas documented:** Firefox lock ("Firefox is already running") and Jupyter
+  "database is locked" recovery — `faqs.md:76-82` (snippets `firefox_lock.md`, `jupyter_lock.md`).
+
+---
+
+## Summary of `[UNCONFIRMED]` items
+1. Exact GPU-node CPU memory (1 TB vs 1031 vs 1032 GB — internal inconsistency).
+2. "BoilerKey" — term never used; docs say "Purdue Login MFA" / SSH keys.
+3. Default Slurm walltime / default nodes-cores for Gautschi (generic macro value not
+   attributable to Gautschi).
+4. `sinfo`, `sacct`, `jobinfo`, `mybalance`, `showpartitions`, `wait_time`, `wholenode` — not
+   in Gautschi docs.
+5. Literal "Lmod" naming and full module command set (`unload`/`purge`/`show`/`help`) not on a
+   Gautschi page (module_system macro unused by Gautschi).
+6. Exact OpenMPI version (only "OpenMPI" + "GCC 14.1.0" stated).
+7. Official home quota (25 GB) and scratch quota (100 TB / 2000k files) — shown only as
+   illustrative `myquota` example output in a shared snippet.
+8. Data Depot mount path / quota; Purdue IT AUP direct URL; data-sensitivity/classification
+   policy; default login shell.
+
+## Documentation-error warnings (do NOT propagate into generated shared context)
+- `--partition=a10` in `gpu_jobs.md` and `mpi_jobs.md` — invalid Gautschi partition (use `ai`
+  or `smallgpu`).
+- `#SBATCH -A standby` in `mpi_jobs.md:94` — `standby` is a QOS (`-q standby`), not an account.
+</content>
+</invoke>
diff --git a/spec/agentic-ai-docs/research/04-mcp-servers.md b/spec/agentic-ai-docs/research/04-mcp-servers.md
new file mode 100644
index 00000000..ae655666
--- /dev/null
+++ b/spec/agentic-ai-docs/research/04-mcp-servers.md
@@ -0,0 +1,354 @@
+# Research: The three public RCAC MCP servers
+
+Source of truth: the GitHub repos themselves (README, SECURITY.md, ROADMAP.md,
+`pyproject.toml`, and selected source files), fetched via `gh` on 2026-07-14.
+Anything not stated by the source is marked `[UNVERIFIED]`. Commands/config in
+fenced blocks are copied verbatim from the repos.
+
+Common facts across all three:
+
+- All three are **Python** projects built with `fastmcp` (FastMCP `>=2.0.0,<3`)
+  and `cmdkit`, packaged with `hatchling`, version `0.1.0`, source under
+  `src/<pkg>/`, console entry point `<pkg> = "<pkg>:main"`.
+- All three are **installed/run with `uvx` straight from Git** (no PyPI release,
+  no npm, no required Docker for the desktop path). `uvx git+https://…` clones,
+  builds, and runs in one step.
+- **License: MIT** — declared in each README and in SPDX source headers
+  (`SPDX-License-Identifier: MIT`). Note: `rcac-mcp` and `rcac-docs-mcp` have **no
+  standalone `LICENSE` file** at repo root (GitHub's license API returns 404);
+  `globus-mcp` is detected as MIT by GitHub.
+- None are archived. Only `globus-mcp` has a tagged release (`v0.1.0`).
+
+---
+
+## 1. `rcac-mcp` — PurdueRCAC/rcac-mcp
+
+Repo: <https://github.com/PurdueRCAC/rcac-mcp>
+Description: "Prototype MCP server implementation enabling agentic workflows to
+connect with RCAC systems." Default branch `main`; also a `wip` branch.
+Last pushed 2026-02-12.
+
+### 1. Purpose
+The RCAC MCP Server "enables agentic development with HPC clusters and storage
+services." It gives an AI agent/harness a set of tools to operate on an RCAC HPC
+cluster — run shell commands, move/read/write files, inspect storage quota and
+paths, and drive Slurm (submit/monitor/cancel jobs) — plus a local full-text
+documentation search. In the default desktop mode it runs **locally as a stdio
+subprocess** and executes everything **on the cluster over the user's existing
+SSH**, so no new service or credential is introduced.
+
+### 2. Language / package / install
+- Language: Python (`requires-python >=3.14`), package name `rcac-mcp`, entry
+  point `rcac-mcp`.
+- Deps: `fastmcp`, `cmdkit`, `pyjwt`, `fabric` (SSH), `pyyaml`, `jinja2`.
+- Install/run (desktop, via `uvx` from Git — no separate install step needed):
+  the MCP client launches `uvx git+https://github.com/purduercac/rcac-mcp`.
+- License: MIT (README + SPDX headers; no root `LICENSE` file).
+
+### 3. How to connect it to a harness
+**stdio subprocess** (default) for Claude Desktop / Cursor / Warp. Exact
+`mcpServers` block from the README:
+
+```json
+{
+  "mcpServers": {
+    "rcac": {
+      "command": "uvx",
+      "args": ["git+https://github.com/purduercac/rcac-mcp", "--ssh-host", "cluster.rcac.purdue.edu"]
+    }
+  }
+}
+```
+
+"This runs the server locally in `stdio` mode, executing commands on the cluster
+over SSH using your existing `~/.ssh/config` and keys." You may instead set
+`RCAC_SSH_HOST` in the environment and omit `--ssh-host`.
+
+Optional **hosted HTTP** mode (for a shared, authenticated instance):
+
+```bash
+rcac-mcp -t http --ssh-host cluster.rcac.purdue.edu
+```
+
+With JWT auth + delegate execution, and client-token generation:
+
+```bash
+export JWT_SECRET="your-secret-key-at-least-32-characters"
+rcac-mcp -t http -a jwt -e delegate
+
+# Generate a token for clients
+rcac-mcp --generate-token --lifetime 86400
+```
+
+Docker Compose + TLS is documented for production-like deploys (`docker compose
+up`, served at `https://mcp.rcac.dev:8443`).
+`[UNVERIFIED]` the README does not give a `claude mcp add …` or `codex mcp …`
+one-liner — only the `mcpServers` JSON block and the HTTP CLI invocations above.
+
+### 4. Tools exposed (verbatim from README "Available Tools")
+Shell & Filesystem:
+- `run_command(command, cwd, timeout)`, `list_directory(path, show_hidden)`,
+  `read_file(path, encoding, max_size)`, `write_file(path, content, append,
+  create_dirs)`, `upload_file(local_path, remote_path)`,
+  `download_file(remote_path, local_path)`
+
+RCAC Cluster:
+- `myquota()`, `storage_paths()`, `jobinfo(job_id)`, `jobcmd(job_id)`,
+  `jobenv(job_id)`, `jobscript(job_id)`, `showpartitions()`,
+  `average_wait(partition, account)`
+
+Slurm:
+- `sbatch(...)`, `squeue(...)`, `scancel(...)`, `sacct(...)`, `sinfo(...)`,
+  `scontrol_show_job(job_id)`, `scontrol_show_node(node)`, `slist()` (accounts &
+  usage, RCAC-specific), `sfeatures()` (node hardware features, RCAC-specific)
+
+Documentation:
+- `doc_search(query, category)` — full-text search over RCAC docs
+- `doc_load(path)` — load a full documentation page
+
+Build the local docs index first (FTS5, from a local RCAC-Docs clone):
+
+```bash
+rcac-mcp --index-docs --docs-path /path/to/RCAC-Docs
+```
+
+DB defaults to `~/.config/rcac-mcp/docs.db` (override with `--docs-output` or
+`RCAC_DOCS_DB`); re-running is incremental.
+
+### 5. Architecture — local-first, confirmed
+SECURITY.md defines three execution modes:
+
+| Mode | Transport | Auth | Use |
+|------|-----------|------|-----|
+| `ssh` | stdio | none (single-user) | local MCP client → remote HPC cluster (default) |
+| `local` | http/sse | none | dev/testing only, runs on the server's own `$SHELL` |
+| `delegate` | http/sse | JWT/OIDC | multi-user prod; server runs as root, `sudo -u <user>` per request |
+
+Local-first model **confirmed**: in the default `ssh`/stdio mode the server runs
+on the user's machine, uses the user's existing `~/.ssh/config` + keys, adds **no
+MCP-layer auth and no new credential**, and all commands run as the SSH user on
+the cluster ("Security boundary is the SSH connection itself"). Delegate mode
+isolates concurrent users with `contextvars.ContextVar` and maps token identity
+to a local Unix user via `RCAC_USER_MAP` (`/etc/rcac-mcp/users.map`), wrapping
+commands as `sudo -n -H -u <user>`.
+
+**`/etc/agents.d` context injection — confirmed.** `src/rcac_mcp/resources.py`
+implements a `cluster_context` MCP resource that, over the same SSH executor,
+runs `find /etc/agents.d -maxdepth 1 -name "*.md" -type f | sort`, `cat`s each
+file, concatenates them (with `<!-- Source: <file> -->` headers), and caches the
+result per hostname. `server.py` exposes it as the resource
+`rcac://context` ("Cluster-specific context loaded from /etc/agents.d/*.md").
+So the cluster can drop admin-authored markdown into `/etc/agents.d/` and the
+server surfaces it to the agent as read-only context.
+
+**Plugin / `cluster-mcp[slurm,lmod,…]` direction — `[UNVERIFIED]`.** No public
+artifact in this repo (README, ROADMAP.md, source on `main` or `wip`) mentions
+`cluster-mcp`, a plugin/extras architecture, or an "HPC-only" refocus. An
+org-wide `gh search code --owner PurdueRCAC "cluster-mcp"` returned **zero
+hits**. As of the last push (2026-02-12) the repo still bundles the docs-search
+tools (`doc_search`/`doc_load`), i.e. it has **not** yet been split into
+HPC-only + a plugin catalog. Treat the plugin/`cluster-mcp` framing as roadmap
+intent not yet reflected in the public code. (Note the docs-search capability was
+subsequently extracted into the separate `rcac-docs-mcp` repo, pushed
+2026-06-26 — see §3 below.)
+
+### 6. Status / caveats
+Repo description and README both call it a **prototype**. Version `0.1.0`, **no
+tagged release**. ROADMAP.md is actually the completed plan for the docs-search
+feature (status `complete`, `local-to-mcp-process`), not a product roadmap.
+`local` mode is explicitly "dev/testing only, NEVER expose to a network without
+auth." A live `wip` branch exists.
+
+---
+
+## 2. `globus-mcp` — PurdueRCAC/globus-mcp
+
+Repo: <https://github.com/PurdueRCAC/globus-mcp>. Last pushed 2026-04-12;
+tagged release `v0.1.0` "Auth, Consent, and Globus Compute."
+
+### 1. Purpose
+"Globus MCP Server gives AI agents federated data transfer and remote code
+execution across research storage systems at institutions worldwide." It wraps
+the **Globus CLI** (data transfer) and the **Globus Compute SDK** (remote Python
+execution on HPC endpoints), so an agent can search endpoints, browse remote
+filesystems, run async transfers, and submit Python functions to Compute
+endpoints.
+
+### 2. Language / package / install
+- Language: Python (`requires-python >=3.11,<3.14`), package name `globus-mcp`,
+  entry point `globus-mcp`.
+- Deps: `fastmcp`, `cmdkit`, `globus-compute-sdk>=4.0.0,<5` (Globus CLI wrapped
+  at runtime).
+- Optional prerequisite: **Globus Connect Personal** for transfers to/from the
+  local machine.
+- Install/run: `uvx` from Git (handled automatically by the MCP client).
+- License: MIT.
+
+### 3. How to connect it to a harness
+**stdio subprocess** for Claude Desktop / Cursor / Warp. Exact `mcpServers` block
+from the README:
+
+```json
+{
+  "mcpServers": {
+    "globus": {
+      "command": "uvx",
+      "args": ["git+https://github.com/purduercac/globus-mcp"]
+    }
+  }
+}
+```
+
+"The `uvx` invocation handles installation automatically. On first use, the
+server's `globus_login()` and `compute_login()` tools will walk users through
+authentication via the browser." Auth is **interactive Globus OAuth**, done
+through tool calls at runtime (not config). `[UNVERIFIED]` no `claude mcp add`,
+`codex mcp`, or hosted-HTTP endpoint is documented — this server is
+stdio/local-only in the README, plus `globus-mcp` for dev.
+
+### 4. Tools exposed (verbatim from README "Available Tools")
+Identity & Auth: `whoami()`, `globus_login()`, `session_consent(scopes)`
+Endpoints: `endpoint_search(query)`, `endpoint_show(endpoint_id)`,
+`endpoint_local_id()`
+Filesystem: `ls(endpoint_id, path)`, `stat(endpoint_id, path)`,
+`mkdir(endpoint_id, path)`, `rename(endpoint_id, source_path, dest_path)`,
+`rm(endpoint_id, path)` (sync), `delete(endpoint_id, path)` (async)
+Transfers: `transfer(...)`, `transfer_batch(...)`, `task_list()`,
+`task_show(task_id)`, `task_wait(task_id)`, `task_cancel(task_id)`,
+`task_event_list(task_id)`
+Compute (remote code execution): `compute_login()`, `compute_endpoint_list()`,
+`compute_endpoint_status(endpoint_id)`, `compute_submit(...)`,
+`compute_batch_submit(...)`, `compute_status(task_ids)`, `compute_result(task_id)`
+
+### 5. Architecture — local-first, confirmed
+Runs as a **local stdio subprocess** of the harness. It uses the **user's own
+Globus identity**: auth is obtained interactively via browser OAuth through
+`globus_login()`/`compute_login()`, and endpoint-specific access is unlocked via
+`session_consent(scopes)` (the server returns a structured `ConsentRequired`
+error carrying the needed scopes, the agent grants consent, then retries). For
+Compute with a `requirements` list, the server auto-provisions a cached `uv`
+virtualenv on the remote endpoint. No new RCAC-hosted service or credential store
+is introduced — it rides on the user's Globus auth and local Globus tooling.
+
+### 6. Status / caveats
+Prominent README banner: **"⚠️ Beta Software … has not reached a stable v1.0.0
+release. APIs, tool signatures, and behavior may change without notice. Use with
+caution in production workflows."** Version `0.1.0`; the one tagged release is
+`v0.1.0`.
+
+---
+
+## 3. `rcac-docs-mcp` — PurdueRCAC/rcac-docs-mcp
+
+Repo: <https://github.com/PurdueRCAC/rcac-docs-mcp>. Last pushed 2026-06-26.
+Description: "MCP service for RCAC Documentation site with full-text search and
+load tools."
+
+### 1. Purpose
+"A single-purpose FastMCP server that exposes Purdue RCAC's documentation to AI
+agents via full-text search." It indexes the RCAC-Docs content (user guides,
+software catalog, datasets, blog posts, workshops) into an FTS5/BM25 SQLite index
+and exposes exactly two tools so agents ground their advice in current
+authoritative docs rather than general knowledge. It runs **unauthenticated** and
+is **hosted at `docs.rcac.purdue.edu/mcp`**.
+
+### 2. Language / package / install
+- Language: Python (`requires-python >=3.14`), package name `rcac-docs-mcp`,
+  entry point `rcac-docs-mcp`.
+- Deps: `fastmcp`, `cmdkit`, `pyyaml`, `jinja2`.
+- Install/run (local): `uvx` from Git.
+- License: MIT (README + no root `LICENSE` file, so GitHub license API 404s).
+
+### 3. How to connect it to a harness
+Two supported paths.
+
+**(a) Hosted remote HTTP endpoint (recommended for most users).** A shared,
+no-auth instance is hosted at **`docs.rcac.purdue.edu/mcp`**. Per the README:
+"Point an HTTP-capable MCP client at that URL — no token or credentials are
+required." `[UNVERIFIED]` the README gives the URL but **no** literal client
+config JSON or `claude mcp add --transport http …` line for the hosted endpoint;
+use your harness's standard "add remote/HTTP MCP server" flow pointed at
+`https://docs.rcac.purdue.edu/mcp`.
+
+**(b) Local stdio subprocess.** Exact `mcpServers` block from the README:
+
+```json
+{
+  "mcpServers": {
+    "rcac-docs": {
+      "command": "uvx",
+      "args": ["git+https://github.com/PurdueRCAC/rcac-docs-mcp"]
+    }
+  }
+}
+```
+
+The local server needs a search index before it can answer; build it first (see
+§5). Transports and serve commands (verbatim):
+
+```bash
+rcac-docs-mcp                      # serve over stdio (local clients)
+rcac-docs-mcp -t http -H 0.0.0.0   # serve over HTTP (hosted)
+```
+
+(`rcac-docs-mcp -t http` alone serves streamable HTTP on `localhost:8000` for
+dev.)
+
+### 4. Tools exposed (verbatim — "exactly two tools")
+- `doc_search(query, category=None)` — FTS5 / BM25 full-text search over indexed
+  RCAC documentation. Returns up to 20 BM25-ranked results with path, title,
+  heading, and a matching snippet. Supports `OR`, quoted phrases, prefix
+  wildcards (`contai*`); `category` is a path-prefix filter (`userguides`,
+  `software`, `datasets`, `blog`, `workshops`).
+- `doc_load(path)` — return the full rendered markdown of one document by its
+  relative path (as shown in `doc_search` results).
+
+### 5. Architecture — hosted HTTP + local-first, confirmed
+Runs unauthenticated over two transports: **`stdio`** (default, local clients)
+and **`http`** (streamable HTTP, for the hosted deployment). Unlike `rcac-mcp`
+and `globus-mcp`, this server **does not SSH anywhere and needs no user
+credentials** — it only reads a local SQLite index, so the hosted instance can be
+fully public/no-auth.
+
+A "**site**" is one directory holding both a clone of RCAC-Docs (`repo/`) and the
+index (`index.db`); resolved from `--site` → `RCAC_DOCS_SITE` → default
+`~/.local/share/rcac-docs-mcp`. Env vars: `RCAC_DOCS_SITE`, `RCAC_DOCS_URL`
+(default `https://github.com/PurdueRCAC/RCAC-Docs`), `MCP_BASE_URL` (public URL
+for absolute icon links). Build the index (two-step operator flow):
+
+```bash
+rcac-docs-mcp --update-site   # clone or git-pull <site>/repo
+rcac-docs-mcp --index         # build/refresh <site>/index.db from <site>/repo
+```
+
+`--update-site` does `git pull --rebase --autostash origin main`; `--index` is
+incremental (SHA-256 hashing, stale-doc pruning). The indexing pipeline walks
+`docs/`, parses YAML frontmatter, resolves `--8<--` snippet includes, renders
+Jinja2 macros/templates from the docs repo's `main.py` + `mkdocs.yml extra:`,
+strips the `<!-- more -->` blog marker, chunks on `##` (H2) boundaries, and
+upserts into SQLite; search uses an FTS5 virtual table with BM25 + `snippet()`.
+This is the same doc-search capability that lives inside `rcac-mcp`, factored out
+into its own hostable service.
+
+### 6. Status / caveats
+Version `0.1.0`, no tagged release; single-purpose and intentionally minimal
+("exactly two tools"). No explicit "beta" banner, but pre-1.0. When run locally
+without a built index, the tools return a helpful message explaining how to build
+one. Many integration tests depend on a git-submodule fixture
+(`tests/fixtures/RCAC-Docs`) that skips cleanly when uninitialized.
+
+---
+
+## Org scan — other agentic/MCP-related PurdueRCAC repos
+From `gh repo list PurdueRCAC --limit 200`:
+
+- **`agentbase`** (private, updated 2026-05-19) — "Core framework for agentic
+  content search over internal knowledge bases." The most relevant adjacent
+  project; private, so contents `[UNVERIFIED]`. Likely the internal-KB analogue
+  of the public docs-search MCP work.
+- **`genai-studio`** (public) — "Reference configurations for Purdue GenAI
+  Studio." AI-adjacent but not MCP.
+- **`CANARI`** (public) — "CANARI framework developed at RCAC" — unclear scope,
+  possibly AI-related; `[UNVERIFIED]`.
+- No other repos reference MCP or `cluster-mcp`. The three servers above are the
+  only public MCP servers in the org.
diff --git a/spec/agentic-ai-docs/research/05-harness-configs.md b/spec/agentic-ai-docs/research/05-harness-configs.md
new file mode 100644
index 00000000..d0f5e74d
--- /dev/null
+++ b/spec/agentic-ai-docs/research/05-harness-configs.md
@@ -0,0 +1,415 @@
+# Agentic Coding Harness Configuration on HPC — Per-Harness Reference
+
+Research date: 2026-07-14. External/current-docs research. Config keys verified against the
+cited official docs; anything not confirmed there is marked `[UNVERIFIED]`.
+
+Scope: for each of the five harnesses — config file paths + format, permissions/sandbox
+(including a DENY of destructive ops and login-node lockdown), MCP wiring (stdio + remote),
+context-file convention (and AGENTS.md support), and install/run on a Linux login node.
+
+---
+
+## Comparison table
+
+| harness | config path | format | permission mechanism | MCP config | context-file name |
+|---|---|---|---|---|---|
+| **Claude Code** | `~/.claude/settings.json` (user), `.claude/settings.json` + `.claude/settings.local.json` (project), `/etc/claude-code/managed-settings.json` (managed, Linux) | JSON | `permissions.allow` / `permissions.deny` / `permissions.ask` arrays; `defaultMode`; OS sandbox (`sandbox.*`) | `claude mcp add …` / `.mcp.json` (project) / `~/.claude.json` (user/local); stdio + http/sse/ws | `CLAUDE.md` (does **not** read AGENTS.md natively) |
+| **Codex CLI** | `~/.codex/config.toml` (user), `.codex/config.toml` (project), profile files `~/.codex/<name>.config.toml` | TOML | `approval_policy` + `sandbox_mode` (read-only / workspace-write / danger-full-access); OS sandbox | `[mcp_servers.NAME]` in config.toml, or `codex mcp add`; stdio + streamable HTTP | `AGENTS.md` (native standard) |
+| **Gemini CLI** | `/etc/gemini-cli/settings.json` (system), `~/.gemini/settings.json` (user), `.gemini/settings.json` (project) | JSON | `tools.core` (allow) / `tools.exclude` (deny) with `run_shell_command(<prefix>)`; `approvalMode`; sandbox (`tools.sandbox`) | `mcpServers` in settings.json; stdio + SSE (`url`) + streamable HTTP (`httpUrl`) | `GEMINI.md`; configurable via `context.fileName` (can include `AGENTS.md`) |
+| **opencode** | `~/.config/opencode/opencode.json` (global), `opencode.json[c]` (project), `/etc/opencode/` (system) | JSON / JSONC | `permission` object; per-tool + per-bash-pattern map `{ "rm *": "deny" }` (allow/ask/deny) | `mcp` object; `type:"local"` (stdio) + `type:"remote"` (http) | `AGENTS.md` (native; `CLAUDE.md` fallback) + `instructions` array |
+| **Warp** | Desktop-app UI: Settings > Agents > Profiles / MCP servers; rules in Warp Drive (cloud) | UI + JSON (MCP) | Agent Profiles: autonomy (Agent Decides / Always Ask / Always Allow) + regex allowlist/**denylist** | Settings > Agents > MCP servers, JSON (`mcpServers`); stdio (`command`) + remote (`url`) | `AGENTS.md` (ALL-CAPS required; `WARP.md` legacy) + Global Rules in Warp Drive |
+
+**Biggest HPC caveat up front:** Warp is a *locally-installed desktop terminal app* (macOS/
+Linux/Windows) — you cannot install it on a headless login node. You run Warp on your
+workstation and SSH into the cluster. The other four are true CLIs that run headless over SSH.
+
+---
+
+## 1. Claude Code (Anthropic CLI)
+
+Docs: <https://code.claude.com/docs/en/settings> · <https://code.claude.com/docs/en/permissions>
+· <https://code.claude.com/docs/en/mcp> · <https://code.claude.com/docs/en/memory> ·
+<https://code.claude.com/docs/en/sandboxing>
+
+### Config files (JSON)
+| Scope | Path |
+|---|---|
+| User | `~/.claude/settings.json` |
+| Project (shared, committed) | `.claude/settings.json` |
+| Project local (gitignored) | `.claude/settings.local.json` |
+| Managed (Linux/WSL) | `/etc/claude-code/managed-settings.json` (+ drop-in dir `/etc/claude-code/managed-settings.d/*.json`) |
+| Managed CLAUDE.md (Linux) | `/etc/claude-code/CLAUDE.md` |
+
+Precedence (high→low): managed → CLI args → local → project → user. **Permission rules merge
+across scopes; a deny at any scope wins.** Schema: `"$schema": "https://json.schemastore.org/claude-code-settings.json"`.
+
+### Permissions / sandbox
+`permissions.allow` / `permissions.deny` / `permissions.ask` arrays. Evaluation order is
+**deny → ask → allow** (first match wins; a broad deny cannot carry allowlist exceptions).
+Rule syntax: `Tool` or `Tool(specifier)`.
+- Bash: `Bash(rm -rf:*)` or `Bash(rm -rf *)` (the `:*` suffix == trailing ` *`). Claude Code
+  is shell-operator-aware, so `Bash(safe *)` does **not** authorize `safe && evil`; each
+  subcommand must match. A bare `Bash` deny removes the tool entirely.
+- Files: `Read(...)` / `Edit(...)` use gitignore semantics; `//abs`, `~/home`, `/settings-relative`, `path`.
+- Web: `WebFetch(domain:example.com)`. MCP: `mcp__server__tool`.
+
+`defaultMode` (in settings) selects a permission mode: `default` (prompt), `acceptEdits`,
+`plan` (read-only exploration), `auto`, `dontAsk` (auto-deny unless pre-allowed),
+`bypassPermissions`. Lock down bypass with `permissions.disableBypassPermissionsMode: "disable"`
+and `permissions.disableAutoMode: "disable"` (best in managed settings). `rm -rf /` / `rm -rf ~`
+prompt even in bypass mode as a circuit breaker.
+
+OS-level **sandbox** (Bash-only, defense-in-depth): `sandbox.enabled`, `sandbox.network`
+(`allowedDomains` / `deniedDomains`), `sandbox.filesystem` (`allowRead` / `denyRead`),
+`autoAllowBashIfSandboxed` (default true). On Linux it uses namespace-based isolation
+(bubblewrap-style) — may be restricted on hardened login nodes; deny rules still apply without it.
+
+**Minimal login-node config** (`~/.claude/settings.json` or a managed file):
+```json
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "defaultMode": "default",
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(sudo:*)",
+      "Bash(srun:*)", "Bash(sbatch:*)",
+      "Read(./.env)", "Read(~/.ssh/**)"
+    ],
+    "ask": ["Bash(git push:*)"],
+    "additionalDirectories": ["/scratch/$USER"]
+  },
+  "disableBypassPermissionsMode": "disable"
+}
+```
+(Note: `defaultMode` also exists as a top-level key; it is documented under `permissions` in the
+managed examples. `disableBypassPermissionsMode` sits under `permissions` — shown flat here per docs.)
+
+### MCP
+`claude mcp add` (scopes: `local` default → `~/.claude.json`; `project` → `.mcp.json`; `user`).
+```bash
+# local stdio server
+claude mcp add --transport stdio myserver -- npx -y some-mcp-server
+# remote streamable HTTP
+claude mcp add --transport http notion https://mcp.notion.com/mcp \
+  --header "Authorization: Bearer TOKEN"
+```
+`.mcp.json` (project, committed) block:
+```json
+{
+  "mcpServers": {
+    "local-tool": { "command": "/path/to/server", "args": [], "env": {} },
+    "remote-api": { "type": "http", "url": "https://mcp.example.com/mcp",
+                    "headers": { "Authorization": "Bearer ${API_KEY}" } }
+  }
+}
+```
+An entry with `url` but no `type` is an error (defaults to stdio). `type: "streamable-http"` is
+an accepted alias for `http`. Env expansion `${VAR:-default}` supported. SSE (`--transport sse`)
+is deprecated. `claude mcp login <name> --no-browser` works over SSH (prints URL to paste).
+
+### Context files
+`CLAUDE.md` load order (broad→specific): managed `/etc/claude-code/CLAUDE.md` → user
+`~/.claude/CLAUDE.md` → project `./CLAUDE.md` or `./.claude/CLAUDE.md` → `./CLAUDE.local.md`;
+plus ancestor dirs walked up from cwd. Import more files with `@path/to/file` (relative/absolute,
+max 4 hops). `.claude/rules/*.md` (optionally `paths:` frontmatter-scoped).
+**Claude Code does NOT read `AGENTS.md` natively** — bridge it with `@AGENTS.md` at the top of
+`CLAUDE.md`, or `ln -s AGENTS.md CLAUDE.md`. To wire in `/etc/agents.d/*.md`, deploy the managed
+`/etc/claude-code/CLAUDE.md` and import each: `@/etc/agents.d/rcac.md`. Load CLAUDE.md from
+`--add-dir` dirs with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`.
+
+### Install & run
+`npm install -g @anthropic-ai/claude-code`, or native installer
+`curl -fsSL https://claude.ai/install.sh | bash`. Runs headless over SSH; non-interactive with
+`claude -p "…"`. Fully supported on Linux login nodes.
+
+---
+
+## 2. OpenAI Codex CLI
+
+Docs: <https://learn.chatgpt.com/docs/config-file/config-basic> ·
+<https://learn.chatgpt.com/docs/config-file/config-reference> ·
+<https://learn.chatgpt.com/docs/sandboxing> · <https://developers.openai.com/codex/> (redirects
+to learn.chatgpt.com). AGENTS.md: <https://developers.openai.com/codex/agent-configuration/agents-md>.
+
+### Config file (TOML)
+- User: `~/.codex/config.toml` (override home with `CODEX_HOME`).
+- Project: `.codex/config.toml`.
+- Profiles: separate files `~/.codex/<profile-name>.config.toml`, selected with `codex --profile <name>`.
+  (As of Codex 0.134.0+ the legacy inline `[profiles.name]` block is removed — use profile files.)
+
+### Permissions / sandbox
+Two orthogonal knobs (no per-command allow/deny list like the others — control is via sandbox +
+approvals):
+```toml
+approval_policy = "on-request"   # untrusted | on-request | never  (granular table also supported)
+sandbox_mode    = "workspace-write"   # read-only | workspace-write | danger-full-access
+
+[sandbox_workspace_write]
+writable_roots         = ["/scratch/USER"]
+network_access         = false        # network OFF by default in workspace-write
+exclude_tmpdir_env_var = false
+exclude_slash_tmp      = false
+```
+`model = "gpt-5.6"`. CLI flags: `--sandbox <mode>`, `--ask-for-approval <policy>`.
+Enforcement: macOS = Seatbelt; **Linux/WSL2 = requires `bubblewrap` (`bwrap`) on PATH** — a key
+HPC gotcha, since bwrap/user-namespaces are often absent or disabled on login nodes. Windows in
+PowerShell uses a native sandbox. `[UNVERIFIED]` whether an older `on-failure` approval value is
+still accepted (current reference lists `untrusted`/`on-request`/`never`).
+
+**Login-node lockdown** (`~/.codex/config.toml`): read-only, never auto-run:
+```toml
+approval_policy = "untrusted"
+sandbox_mode    = "read-only"
+```
+If `bwrap` is unavailable, keep `sandbox_mode="read-only"` + `approval_policy="untrusted"` so
+nothing runs without an explicit approval; do **not** use `danger-full-access` on shared nodes.
+
+### MCP
+`[mcp_servers.NAME]` blocks in `config.toml`, or `codex mcp add` / `codex mcp list`.
+```toml
+# local stdio
+[mcp_servers.example_stdio]
+command = "python -m example_server"
+args    = ["--flag", "value"]
+env     = { API_KEY = "secret" }
+enabled = true
+startup_timeout_sec = 10
+tool_timeout_sec    = 60
+
+# remote streamable HTTP
+[mcp_servers.example_http]
+url = "https://api.example.com/mcp"
+bearer_token_env_var = "MCP_TOKEN"
+http_headers = { Authorization = "Bearer token" }
+enabled = true
+```
+
+### Context files
+`AGENTS.md` (native — Codex is a first-class member of the agents.md standard). Discovered and
+merged from `~/.codex/AGENTS.md` (user) → repo root → current working directory. Config keys:
+`project_doc_max_bytes` (per-file cap), `project_doc_fallback_filenames` (extra names to try),
+and `experimental_instructions_file` (point at an arbitrary instructions file — a route to wire
+in `/etc/agents.d/*.md`). `project_doc_fallback_filenames` can also add cluster-standard names.
+
+### Install & run
+`npm install -g @openai/codex` · `brew install --cask codex` · shell installer
+`curl -fsSL https://chatgpt.com/codex/install.sh | sh`. Prebuilt binaries for macOS
+(arm64/x86_64) and Linux (x86_64/arm64). Headless/non-interactive: `codex exec "…"`. Runs on
+Linux login nodes (Ubuntu 20.04+/Debian 10+; Windows only via WSL2).
+
+---
+
+## 3. Gemini CLI (Google)
+
+Docs: <https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/settings.md> ·
+`docs/tools/mcp-server.md` · `docs/tools/shell.md` · `docs/cli/gemini-md.md` ·
+`docs/cli/enterprise.md` (all under the repo).
+
+### Config files (JSON) — precedence low→high
+1. System defaults `system-defaults.json`
+2. User `~/.gemini/settings.json`
+3. Workspace `<project>/.gemini/settings.json`
+4. **System overrides** (final say): Linux `/etc/gemini-cli/settings.json`, macOS
+   `/Library/Application Support/GeminiCli/settings.json`, Windows
+   `C:\ProgramData\gemini-cli\settings.json`. Override path via `GEMINI_CLI_SYSTEM_SETTINGS_PATH`.
+
+Newer builds use a nested structure (`tools.*`, `security.*`, `context.*`, `mcpServers`, `mcp`);
+older flat keys (`coreTools`, `excludeTools`, `contextFileName`) still appear in the wild.
+
+### Permissions / sandbox
+Command control is via the shell tool allow/deny lists with **prefix matching** on
+`run_shell_command(<prefix>)`:
+```json
+{
+  "tools": {
+    "core":    ["run_shell_command(git)", "run_shell_command(npm)"],
+    "exclude": ["run_shell_command(rm)", "run_shell_command(sudo)", "run_shell_command(curl)"]
+  }
+}
+```
+`tools.exclude` beats `tools.core`; chained commands (`&&`, `||`, `;`) are split and each part
+validated — any disallowed part blocks the whole line. `approvalMode` governs prompting;
+`security.disableYoloMode` prevents auto-approve-everything mode. Sandbox: `tools.sandbox`
+(bool/`"docker"`/`"podman"`/`"sandbox-exec"`), `tools.sandboxAllowedPaths`,
+`tools.sandboxNetworkAccess`, `security.toolSandboxing`. **HPC gotcha:** Gemini's `--sandbox`
+relies on Docker/Podman (or macOS Seatbelt) — container runtimes are usually unavailable on HPC
+login nodes, so rely on `tools.exclude` + default `approvalMode` instead of the sandbox.
+
+Minimal login-node config (`~/.gemini/settings.json`):
+```json
+{
+  "tools": { "exclude": ["run_shell_command(rm)", "run_shell_command(sudo)"] },
+  "security": { "disableYoloMode": true }
+}
+```
+
+### MCP
+`mcpServers` in settings.json. stdio uses `command`; remote SSE uses `url`; streamable HTTP uses
+`httpUrl`. Per-server tool filtering with `includeTools`/`excludeTools`; `trust: true` skips
+confirmations. Global gate: `mcp.allowed` / `mcp.excluded`.
+```json
+{
+  "mcpServers": {
+    "pythonTools": { "command": "python", "args": ["-m", "my_mcp_server"],
+                     "cwd": "./mcp", "env": { "DB": "$DB_CONNECTION_STRING" }, "timeout": 15000 },
+    "httpServer":  { "httpUrl": "http://localhost:3000/mcp",
+                     "headers": { "Authorization": "Bearer TOKEN" } },
+    "sseServer":   { "url": "https://api.example.com/sse",
+                     "headers": { "Authorization": "Bearer TOKEN" } }
+  }
+}
+```
+
+### Context files
+`GEMINI.md` — global `~/.gemini/GEMINI.md`, plus project + ancestor dirs (and just-in-time when a
+tool touches a subtree). **Configurable filename**, which is how Gemini adopts the shared
+standard: `{"context": {"fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]}}` (older key:
+`contextFileName`). `context.loadMemoryFromIncludeDirectories` and `context.discoveryMaxDirs`
+tune discovery. To wire in `/etc/agents.d/*.md`, either symlink into the search path or add its
+filename to `context.fileName` and place a copy at a discovered location `[UNVERIFIED]` whether an
+absolute path list is accepted directly.
+
+### Install & run
+`npm install -g @google/gemini-cli` (or `npx https://github.com/google-gemini/gemini-cli`).
+Headless: `gemini -p "…"` / `--yolo` (avoid on shared nodes). Runs on Linux login nodes over SSH.
+
+---
+
+## 4. opencode
+
+Docs: <https://opencode.ai/docs/config/> · <https://opencode.ai/docs/permissions/> ·
+<https://opencode.ai/docs/mcp-servers/> · <https://opencode.ai/docs/rules/> · <https://opencode.ai/docs/>
+
+### Config files (JSON / JSONC)
+- Global: `~/.config/opencode/opencode.json` (or `.jsonc`); TUI: `~/.config/opencode/tui.json`.
+- Project: `opencode.json` / `opencode.jsonc` in repo root.
+- System-managed: Linux `/etc/opencode/`, macOS `/Library/Application Support/opencode/`.
+- Overrides: `OPENCODE_CONFIG` (file), `OPENCODE_CONFIG_DIR` (dir). Schema: `"$schema": "https://opencode.ai/config.json"`.
+
+### Permissions
+`permission` key: a string applied to all, or an object keyed by tool
+(`read, edit, glob, grep, bash, task, skill, lsp, question, webfetch, websearch,
+external_directory, doom_loop`). Values `allow` / `ask` / `deny`. `bash` accepts a **pattern map**
+(glob `*`, `?`); **last matching pattern wins**, so put the catch-all first:
+```json
+{
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "ls *": "allow", "cat *": "allow", "git status": "allow",
+      "git push *": "ask",
+      "rm -rf *": "deny", "sudo *": "deny", "srun *": "deny", "sbatch *": "deny"
+    },
+    "edit": "ask",
+    "webfetch": "ask"
+  }
+}
+```
+Most tools default to `allow`; `doom_loop` and `external_directory` default to `ask`; reading
+`.env*` is denied by default. No OS sandbox — permission rules are the enforcement layer.
+
+### MCP
+`mcp` object. Local (stdio) uses `type:"local"` + `command` **array**; remote uses `type:"remote"`
++ `url`.
+```json
+{
+  "mcp": {
+    "local-tool":  { "type": "local", "command": ["npx", "-y", "my-mcp"],
+                     "environment": { "MY_ENV": "val" }, "enabled": true },
+    "remote-api":  { "type": "remote", "url": "https://mcp.example.com",
+                     "headers": { "Authorization": "Bearer KEY" }, "enabled": true }
+  }
+}
+```
+Local extras: `cwd`, `timeout` (ms, default 5000). Remote extras: `oauth`, `timeout`.
+
+### Context files
+Reads `AGENTS.md` (project root) and `~/.config/opencode/AGENTS.md` (global); falls back to
+`CLAUDE.md` / `~/.claude/CLAUDE.md`. **Native agents.md support.** Additional files via the
+`instructions` array (local globs + remote URLs), which is the clean way to wire in shared docs:
+```json
+{ "instructions": ["docs/standards.md", "packages/*/AGENTS.md", "/etc/agents.d/rcac.md"] }
+```
+
+### Install & run
+`curl -fsSL https://opencode.ai/install | bash` · `npm install -g opencode-ai` ·
+`brew install anomalyco/tap/opencode` (also AUR/pacman). It is a terminal TUI, but the process
+runs on the host you launch it on, so it works over SSH on a login node; non-interactive
+`opencode run "…"` and a headless `opencode serve` are available. `[UNVERIFIED]` in docs that SSH
+is explicitly blessed, but it is a standard terminal program (needs a real terminal emulator on
+your side).
+
+---
+
+## 5. Warp
+
+Docs: <https://docs.warp.dev/agent-platform/capabilities/agent-profiles-permissions> ·
+<https://docs.warp.dev/agent-platform/capabilities/mcp> ·
+<https://docs.warp.dev/agent-platform/capabilities/rules> ·
+<https://docs.warp.dev/getting-started/getting-started-with-warp>
+
+### Config model
+Warp is a **desktop terminal application** (macOS 10.14+, Windows 10 1903+, Linux glibc≥2.31),
+configured through its GUI (Settings) and cloud "Warp Drive" — not a dotfile-first CLI. There is
+no `~/.warp/config.*` you edit for agent behavior; MCP is the one place you paste JSON.
+
+### Permissions (Agent Profiles)
+Settings > Agents > Profiles. Per-permission-type autonomy: **Agent Decides** / **Always Ask** /
+**Always Allow**, applied to: apply diffs, read files, create plans, execute commands, full
+terminal use, ask questions. Command control uses **regex**:
+- **Allowlist** — auto-run without confirmation, e.g. `ls(\s.*)?`, `grep(\s.*)?`.
+- **Denylist** — always require approval; default denylist already blocks `rm(\s.*)?`,
+  `curl(\s.*)?`, `wget(\s.*)?`, `eval(\s.*)?`.
+- **Denylist beats both the allowlist and "Agent decides."**
+Gotcha: **Run-until-completion** (`Cmd/Ctrl+Shift+I`) *ignores the denylist entirely* — dangerous
+on a login node. Profiles can be team-managed for shared policy.
+
+### MCP
+Settings > Agents > MCP servers (also Warp Drive / Command Palette "Open MCP Servers"). JSON under
+an `mcpServers` key; local CLI/stdio uses `command`+`args`(+`env`,`working_directory`); remote
+uses `url`(+`headers`).
+```json
+{
+  "filesystem":  { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] },
+  "externalDocs":{ "url": "http://localhost:4000/mcp/stream", "headers": { "my-header": "val" } }
+}
+```
+
+### Rules / context
+Global Rules live in Warp Drive (Personal > Rules). Project Rules are `AGENTS.md` files in the repo
+(root or subdirectories); `WARP.md` is the legacy name. **The filename must be ALL CAPS**
+(`AGENTS.md`, not `agents.md`). Precedence: subdirectory AGENTS.md → root AGENTS.md → Global Rules.
+Native agents.md support, so a cluster-provided `AGENTS.md` is read automatically.
+
+### Install & run — the HPC caveat
+Install locally: direct download, `brew install --cask warp` (macOS), WinGet (Windows), or Linux
+packages (`.deb`/`.rpm`/`.AppImage`/pacman). **You cannot run Warp headless on a login node** — it
+is a GUI app that needs a display and (on first launch) internet + account login. HPC usage: run
+Warp on your workstation, then SSH into the RCAC cluster; Warp advertises "Feature support over
+SSH," so Agent Mode operates within the remote session while the app stays local. This makes the
+per-cluster settings-file story different from the four CLIs: publish an `AGENTS.md` in the repo
+(read automatically) and document the recommended Profile denylist; there is no server-side Warp
+config file to ship.
+
+---
+
+## HPC deployment notes (cross-cutting)
+
+- **Login-node safety:** deny `rm -rf`, `sudo`, and (arguably) scheduler-launch commands
+  (`srun`/`sbatch`) so agents don't spawn jobs unattended. Claude Code and opencode express this
+  as per-command deny rules; Gemini as `tools.exclude`; Codex has no per-command list — use
+  `sandbox_mode="read-only"` + `approval_policy="untrusted"`; Warp ships a default regex denylist.
+- **OS sandboxes are the weak spot on HPC:** Codex needs `bubblewrap` on Linux; Gemini needs
+  Docker/Podman; Claude Code uses Linux namespaces — all of which are frequently disabled on
+  shared login nodes. Treat the permission/approval layer (not the sandbox) as the primary control
+  there, and point writable roots at `/scratch/$USER`.
+- **Shared `AGENTS.md`:** Codex, opencode, and Warp read `AGENTS.md` natively; Gemini reads it if
+  added to `context.fileName`; Claude Code needs `@AGENTS.md` import or a symlink. A single repo
+  `AGENTS.md` therefore covers 4/5 with a one-line Claude bridge.
+- **Wiring `/etc/agents.d/*.md`:** Claude Code → managed `/etc/claude-code/CLAUDE.md` with
+  `@/etc/agents.d/*.md` imports; opencode → `instructions` array (accepts absolute paths/globs);
+  Codex → `experimental_instructions_file` / `project_doc_fallback_filenames`; Gemini →
+  `context.fileName`; Warp → repo `AGENTS.md` only (no arbitrary include path).
+</content>
+</invoke>
diff --git a/spec/agentic-ai-docs/research/06-context-and-conventions.md b/spec/agentic-ai-docs/research/06-context-and-conventions.md
new file mode 100644
index 00000000..7e9c1f4f
--- /dev/null
+++ b/spec/agentic-ai-docs/research/06-context-and-conventions.md
@@ -0,0 +1,309 @@
+---
+title: "Context files, harness conventions, and peer prior art"
+slug: agentic-ai-docs
+research_task: "06 — /etc/agents.d intent, AGENTS.md convention mapping, peer-center prior art"
+date: 2026-07-14
+sources:
+  - glentner/pearc26-hello-computer (outline/03-approach.md, outline/04-discussion.md, rules/*, tips/*)
+  - Gautschi user guide (overview, storage, software, run_jobs/queues) + main.py macros / snippets
+  - NERSC, TACC, ALCF, NCSA docs (web)
+  - agents.md open standard
+---
+
+# Research 06 — Shared context, harness conventions, and prior art
+
+## 1. Paper intent for `/etc/agents.d` + per-file content outlines
+
+### 1.1 What the authors intend `/etc/agents.d` to be
+
+From `outline/03-approach.md` ("System-Wide Configurations"), the `/etc/agents.d`
+directory hierarchy is RCAC's mechanism to **inject HPC-specific context into the
+well-known rules-file locations agentic tools already look for**, so "the agent absorbs
+the cluster's policies before the user asks their first question." The paper names two
+kinds of content that belong there:
+
+1. **Facts / "which command for what"** — quota checks (`myquota`), batch submission
+   (`sbatch`), loading software via environment modules, which filesystems serve which
+   purpose.
+2. **Prohibitions** — "don't run computationally intensive work on login nodes, don't
+   store sensitive data in world-readable locations, don't submit jobs without time
+   limits."
+
+So each file is a **cluster-context brief**, not a tutorial: declarative facts + explicit
+prohibitions, written *to the agent*. It is the local-knowledge layer that fixes the
+paper's central failure mode — the agent that confidently emits "a Slurm script that
+would work perfectly… on a cluster we don't operate" (`04-discussion.md` §4.1/§4.4).
+
+### 1.2 Framing / voice to carry into the files (from `04-discussion.md`)
+
+- **Proactive engagement, not prohibition / "mostly harmless"** — "We don't pretend they
+  don't exist or discourage their use" (03); confinement already exists (cgroups, health
+  checks, root-squash, quotas) so agents "accelerate the pace of potential errors, which
+  means existing hardening must be strengthened, not invented" (§4.5).
+- **Context engineering ("Tea, Earl Grey, Hot")** — structure information so the agent
+  produces reliable output *from the outset*; specificity beats generality. `/etc/agents.d`
+  is that engineered specificity supplied by the center rather than the user.
+- **Verify, don't forbid / augmented not outsourced ("I Know Kung Fu", "The Answer is 42")**
+  — "use AI to accelerate your learning, not to bypass it… ask *why*, not just *what*";
+  "Verification isn't optional; it's the core competency." Files should tell the agent to
+  prefer center-verified facts and flag uncertainty over inventing flags.
+- **Don't cross the streams (§4.5)** — the concrete blast-radius risks the prohibitions
+  target: `rm -rf` of a project dir, allocation exhaustion in hours, secrets logged into a
+  persistent context window.
+
+### 1.3 What the authors' own `rules/` + `tips/` teach about good rules content
+
+These are the authors' *battle-tested* agent files; the patterns are the template for tone
+and structure:
+
+- **`rules/file_deletion.md`** — a hard prohibition + the safe alternative (use `del`/
+  `/bin/rm` deliberately, never bare `rm`), with a rationale and a scoped exception. Pattern:
+  *state the danger, give the safe path, name the exception.*
+- **`rules/session_logs.md` / `planning_docs.md` / `structural_docs.md`** — "capture what
+  was requested + done + why"; keep index/structural docs in sync. Maps to RCAC's
+  reproducibility interest (§4.5 "capturing agent interactions that contribute to
+  scientific outcomes").
+- **`rules/wip_commits.md`** — branch discipline, commit-often, "force-push OK here but
+  **never on `main`**." Pattern: *explicit allow + explicit hard prohibition in the same
+  breath.*
+- **`tips/agent-text-editing-pitfalls.md`** — agents silently truncate trailing content in
+  diffs → "review diffs, request minimal edits, verify after." Reinforces *verify output*.
+- **`tips/long-horizon-tasks.md`** — structured memory files (YAML front-matter, session
+  prompt templates) beat one long context. This is the same "context engineering" the paper
+  sells; RCAC's `/etc/agents.d/*.md` are exactly these persistent "memory anchors."
+- **`tips/warp-conversation-history.md`** — recovering verbatim inputs; the caveat "don't
+  rely on it, log promptly" mirrors "verification is the whole game."
+
+Common shape to reuse in every RCAC file: **short declarative facts → the correct
+command/path → an explicit "do not …" list → a rationale line.** Each file self-contained
+and skimmable, front-matter optional.
+
+### 1.4 Proposed content outlines (section headings + one-line intent)
+
+Cluster-context oriented (facts + prohibitions), **not tutorials**. Grounded in verified
+Gautschi facts: Rocky Linux 9, Lmod, 8 AMD EPYC "Genoa" front-ends; partitions
+`cpu`/`ai`/`highmem` (+ `profiling`/`smallgpu`); QOS `normal`/`standby` (cpu) &
+`normal`/`preemptible` (ai); `-A` (see `slist`), `-p`, `-q` all required; home 25 GB w/
+daily snapshots, `$RCAC_SCRATCH`=`/scratch/gautschi/$USER` (huge, **not** backed up, purged
+~60 days), `/tmp` node-local, Depot + Fortress (hsi/htar) for long-term; `myquota`,
+`findscratch`.
+
+#### `unix.md` — the login-node OS/shell environment
+- **Operating system & shell** — Rocky Linux 9, `bash` default, standard GNU coreutils;
+  what an agent can assume is present.
+- **Front-end nodes are shared** — 8 multi-tenant login nodes; intended for editing,
+  compiling, job submission, light pre/post-processing only.
+- **Do NOT run real compute on login nodes** *(prohibition)* — no heavy/parallel/
+  long-running work on front-ends; move it to Slurm (CPU/memory limits enforced).
+- **No elevated privileges** *(prohibition)* — no `sudo`/root; can't install system
+  packages; use environment modules and user space instead.
+- **Access & session model** — SSH-key access, ThinLinc for GUI; the agent inherits the
+  user's existing SSH access, nothing more.
+- **Process hygiene** *(prohibition)* — no unbounded background processes / runaway loops;
+  clean up temp processes; watch for agent retry storms.
+
+#### `filesystems.md` — where data lives and what is safe
+- **Home directory** — path + 25 GB quota + daily snapshots (recoverable); for code/config,
+  not large data.
+- **Scratch (`$RCAC_SCRATCH`)** — `/scratch/gautschi/$USER`, large high-performance parallel
+  FS for job I/O; **not backed up, purged ~60 days** — never treat as durable *(prohibition)*.
+- **`/tmp` / node-local** — ephemeral, per-node, cleared after the job.
+- **Long-term storage (Depot, Fortress)** — group/archive space; move keepers off scratch via
+  `hsi`/`htar`.
+- **Check before you write** — use `myquota`, `findscratch`, `du -h --max-depth=1`; respect
+  quotas (file-count and size).
+- **Prohibitions** — no big data in home; no secrets/sensitive data in world-readable paths;
+  no bulk/`rm -rf` deletes without user confirmation.
+
+#### `lmod.md` — the software environment
+- **Software comes from modules, not the package manager** *(prohibition on apt/yum/system
+  installs)* — RCAC uses Lmod.
+- **Discovering software** — `module avail`, `module spider <name>` for versions/prereqs.
+- **Loading & managing** — `module load/list/purge`; the `(D)` default marker; pin versions
+  and load the same modules inside job scripts.
+- **Recommended toolchain** — GCC 14.1.0 + OpenMPI; hierarchical modules.
+- **Python/Conda** — use the `anaconda` modules and user environments; don't pollute base.
+- **Prohibitions / pitfalls** — never invent a module name or version; verify with
+  `module spider` before claiming a package exists.
+
+#### `slurm.md` — the scheduler
+- **Scheduler basics** — Slurm; batch (`sbatch`) vs interactive (`salloc`/`sinteractive`);
+  `squeue`/`scancel`/`sacct`; `jobinfo`.
+- **Every Gautschi job needs four parts** *(the key gotcha)* — resources + account (`-A`,
+  discover via `slist`) + QOS (`-q`) + **partition (`-p`, mandatory)**.
+- **Partitions** — `cpu`, `ai`, `highmem` (+ `profiling`, `smallgpu`): what each is for and
+  node type.
+- **QOS & charging** — `normal`/`standby` on `cpu`; `normal`/`preemptible` on `ai`; time
+  limits per QOS; checkpoint `preemptible` jobs.
+- **Always set a time limit and realistic resources** *(prohibition on no-`--time` jobs)* —
+  memory is allocated proportional to cores.
+- **Prohibitions** — don't emit PBS/LSF/other-scheduler flags; don't invent partitions/QOS;
+  don't run compute on login nodes; confirm before bulk/`scancel` of others' jobs; don't
+  exhaust the allocation.
+
+#### `policies.md` — rules, data handling, and cautions
+- **Acceptable use** — bound by Purdue IT / RCAC AUP; link the policy of record.
+- **Data handling & sensitivity** *(prohibition)* — no regulated/sensitive/export-controlled
+  data without prior approval.
+- **Secrets & credentials** *(prohibition)* — never store API keys/tokens/private keys in
+  world-readable or shared paths; never paste them into prompts/agent context.
+- **Resource stewardship** — recap: no heavy compute on login nodes; Slurm jobs carry time
+  limits; steward the allocation.
+- **Destructive operations require confirmation** *(prohibition)* — `rm -rf`, mass moves,
+  bulk `scancel`; the agent must confirm with the user.
+- **Account integrity & getting help** — no account/credential sharing (the agent acts *as
+  you*); verify AI output before running; report bad AI commands to `rcac-help@purdue.edu`.
+
+---
+
+## 2. The context-file convention and how one canonical set maps onto every harness
+
+### 2.1 The `AGENTS.md` open standard (the anchor to cite)
+
+`AGENTS.md` (<https://agents.md/>) is an **open, tool-agnostic format** — "a README for
+agents": plain Markdown with flexible headings, placed at the **repo root** (or system/home
+root for a global config), with nested files allowed and "the closest `AGENTS.md` to the
+edited file wins." Its philosophy is *separation of concerns* — `README.md` is for humans,
+`AGENTS.md` is the detailed context agents need. The site reports **60k+ projects** and
+**~25–30+ tools** consuming it, explicitly including **OpenAI Codex, Gemini CLI, Cursor,
+Aider, VS Code, GitHub Copilot, Zed, Warp, JetBrains Junie, opencode/Windsurf**, etc. Its
+migration FAQ is the load-bearing quote for our strategy: **"Rename existing files to
+`AGENTS.md` and create symbolic links for backward compatibility."**
+
+### 2.2 The well-known per-harness filenames (the fan-out targets)
+
+Each harness historically reads its *own* context filename and its own settings/permissions
+format. For our five:
+
+| Harness | Context file it reads | Settings / permissions file |
+|---|---|---|
+| **Claude Code** | `CLAUDE.md` (and `@path` imports); also reads `AGENTS.md` in recent versions | `.claude/settings.json` (`permissions.allow`/`deny`/`ask`) |
+| **OpenAI Codex** | `AGENTS.md` natively | `~/.codex/config.toml` |
+| **Gemini CLI** | `GEMINI.md` (context filename is configurable → can point at `AGENTS.md`) | `.gemini/settings.json` |
+| **opencode** | `AGENTS.md` natively | `opencode.json` |
+| **Warp** | `WARP.md` / Warp Rules (Warp also added `AGENTS.md` support) | Warp Rules / drive config |
+
+The key fact: **`AGENTS.md` is already the common denominator** — Codex and opencode read it
+natively, Gemini can be pointed at it, Warp supports it, and Claude Code reads `CLAUDE.md`
+which the standard tells you to *symlink to `AGENTS.md`* (this repo does exactly that:
+`CLAUDE.md -> AGENTS.md`, `.claude -> .agents`).
+
+### 2.3 Recommended mapping strategy (one canonical source → every harness)
+
+RCAC's canonical source of truth is **five separate topic files** in `/etc/agents.d/`
+(`unix.md`, `filesystems.md`, `lmod.md`, `slurm.md`, `policies.md`). Surface them two ways
+depending on deployment mode (per GOAL R8/R12):
+
+1. **On-cluster mode (harness runs on a Gautschi login node).** Concatenate the five files,
+   in a stable order, into a single canonical **`AGENTS.md`** placed at a system/global
+   context location, then **symlink the other well-known names to it**:
+   `CLAUDE.md → AGENTS.md`, `GEMINI.md → AGENTS.md`, `WARP.md → AGENTS.md`. This is the
+   standard's own prescribed pattern and exactly the trick used in the paper repo and this
+   RCAC-Docs repo. Concatenation (not five separate files) is preferred because most
+   harnesses load a *single* root context file; the `/etc/agents.d/*.md` split is a
+   *maintenance/source* convenience, collapsed at deploy time. Puppet performs the copy +
+   concat + symlink onto the hosts (out of scope for the docs feature, but the mechanism to
+   describe).
+2. **Local mode (harness on the user's laptop, targeting the cluster over MCP + SSH).** The
+   HPC MCP server (`rcac-mcp`) **reads `/etc/agents.d/` over SSH and injects the markdown as
+   agent context** at connect time (GOAL R8) — no local file placement needed. The path is
+   configurable.
+
+**Permissions** are *not* portable across harnesses — each settings format is different — so
+R11's per-harness settings files must be authored natively (`.claude/settings.json`,
+`config.toml`, `.gemini/settings.json`, `opencode.json`, Warp Rules), each (a) wiring in the
+shared context (via `AGENTS.md`/symlink or an import directive) and (b) encoding the same
+starting-point deny/allow policy (deny destructive ops + login-node heavy compute; require
+Slurm time limits; no secrets in world-readable paths; confirm destructive actions). The
+*context* is DRY via `AGENTS.md`; the *permissions* are parallel translations of one policy.
+
+**Net recommendation:** treat `/etc/agents.d/*.md` as the DRY source, concatenate to a single
+canonical `AGENTS.md`, symlink every other harness's context filename to it (cite the
+agents.md FAQ), inject the same files over SSH via MCP for local mode, and hand-translate the
+one permission policy into each harness's native settings file.
+
+---
+
+## 3. Prior-art survey — what peer HPC centers publish about agentic AI
+
+Verdict up front: **the space is early but no longer empty.** Two centers (NERSC, TACC) now
+publish explicit agentic-AI guidance; the tone at both is *permit-with-guardrails +
+verify*, matching RCAC's stance almost exactly. Others (ALCF, NCSA) had nothing agent-facing
+visible at survey time. RCAC would be an early mover but not a first mover — and can credibly
+cite NERSC/TACC as convergent practice.
+
+### 3.1 NERSC — a full, dedicated page (strongest prior art)
+**URL:** <https://docs.nersc.gov/development/coding-agents/>
+
+A complete, RCAC-shaped guide titled around **AI Coding Tools / coding agents**. Tone is
+**cautiously permissive**: *"The goal is not to let a model operate unsupervised. The goal is
+to use these tools to reduce repetitive work while keeping humans in control."* Notable
+because it independently arrives at nearly every RCAC pillar:
+
+- **Login-node rule** — small interactive debugging OK; no long-running/resource-intensive
+  work on login nodes.
+- **Sandboxing / write scope** — recommends **workspace-write mode**, confining agent writes
+  to `$HOME`/`$SCRATCH`; sensitive `$CFS` data read-only or copied out.
+- **Secrets** — *"Do not paste credentials, tokens, or private keys into prompts."*
+- **Verification mandate** — *"Users are responsible for validating generated code, commands,
+  configurations, and scientific results"*; a whole section **"Slurm and Module Advice Needs
+  Verification"** and **"Verification Is the Whole Game."**
+- **AUP boundary** — agents "must not be given prohibited data, must not bypass access
+  controls," must stay in approved project scope.
+- Rich section set incl. **Context Engineering**, **Sandboxing and Approval Boundaries**,
+  **Common AI Mistakes on HPC Systems**, **Prompt Template for NERSC Tasks**, and *"If You
+  Only Remember Four Things."* References Claude Code by name. (No MCP-server section
+  observed — an opening for RCAC to differentiate.)
+
+This page is the closest analog to RCAC's planned content and a strong structural model /
+tone reference; RCAC's differentiators are the **published `/etc/agents.d` context**,
+**per-harness settings**, and **MCP servers** — which NERSC does not appear to cover.
+
+### 3.2 TACC — a concise policy block in the Good Conduct Guide
+**URL:** <https://docs.tacc.utexas.edu/basics/conduct/#ai> ("AI Tools on TACC Resources")
+
+Short, blunt, policy-flavored — folded into the login-node conduct rules. Verbatim rules:
+- *"All AI-assisted workloads must be executed on compute nodes only."*
+- *"YOU are responsible for all your processes initiated on TACC resources, including those
+  launched via AI tools or agents."*
+- *"All Service Units (SUs) consumed by AI-related workloads will be charged against your
+  allocation."*
+- Suggested workflow: grab a compute node via **`idev`**, then point the AI tool at the
+  allocated node. Warning: violations → *"degraded access… or administrative action."*
+
+Tone is firmer/more enforcement-y than NERSC, but the substance is identical to RCAC's
+(no login-node compute; user is accountable; allocation is charged). Good source for the
+acceptable-use/etiquette page (R2) — note TACC pushes *all* AI work to compute nodes, a
+stricter line than RCAC's "light work on login nodes OK."
+
+### 3.3 ALCF — nothing agent-facing found
+**URL:** <https://docs.alcf.anl.gov/> (returned HTTP 403 to the fetcher). ALCF publishes
+extensive *AI-for-science* (training/inference) material but no agentic coding-assistant /
+AI-agent acceptable-use guidance was locatable. Treat as "no prior art at survey time."
+
+### 3.4 NCSA — nothing agent-facing found
+**URLs:** <https://docs.ncsa.illinois.edu/> and the Delta guide
+<https://docs.ncsa.illinois.edu/systems/delta/en/latest/>. No mention of AI coding agents,
+LLM assistants, or MCP servers surfaced. Treat as "no prior art at survey time."
+
+### 3.5 MCP-for-HPC prior art
+WebSearch was blocked in this environment (org policy on the search feature), so a broad
+sweep for third-party "MCP + Slurm" projects couldn't be completed here. From the material
+available: **no peer center documents an MCP server for cluster/Slurm operations** — NERSC,
+TACC, ALCF, NCSA pages contain no MCP references. This makes RCAC's `rcac-mcp` /
+`rcac-docs-mcp` / `globus-mcp` documentation a genuine **differentiator / white space** and
+supports the paper's "local-first MCP" framing as novel published practice. (Recommend a
+follow-up unrestricted web search to confirm no community "slurm-mcp" prior art before
+claiming first-mover status in the docs.)
+
+### 3.6 Takeaways for the RCAC docs
+- **Not first, but early.** Cite NERSC + TACC as convergent peer practice; it de-risks the
+  stance and lends authority ("centers including NERSC and TACC…").
+- **Tone converges on RCAC's:** permit + guardrails + *verification is the whole game* +
+  login-node discipline + secrets prohibition + user-accountability. RCAC can adopt this
+  register confidently.
+- **RCAC's white space:** published `/etc/agents.d` context files, per-harness settings, and
+  documented MCP servers — none of the four peers publish these. Lead with them.
+- **One caution to mirror TACC/NERSC precisely:** the login-node line. TACC = compute nodes
+  only; NERSC = light interactive OK. RCAC should state its own line explicitly (GOAL R5:
+  light on front-ends, real work via Slurm) rather than leave it implied.
diff --git a/tools/agent_context/clusters/gautschi.yml b/tools/agent_context/clusters/gautschi.yml
new file mode 100644
index 00000000..91e6baae
--- /dev/null
+++ b/tools/agent_context/clusters/gautschi.yml
@@ -0,0 +1,52 @@
+# Agentic-AI context data model for Gautschi.
+# Edit this file (not docs/snippets/agentic-ai/gautschi/**) and re-run
+# tools/generate_agent_context.py. Encode only facts the cluster's own user guide
+# confirms; leave uncertain values null so the templates emit a "verify live" note
+# rather than a guess. A literal [NEEDS CLARIFICATION] anywhere makes the generator fail.
+cluster: gautschi
+title: Gautschi
+login_host: gautschi.rcac.purdue.edu
+os: Rocky Linux 9
+scratch_path: /scratch/gautschi
+
+filesystems:
+  home:
+    tech: ZFS
+    snapshots: automatic snapshots (recoverable)
+  scratch:
+    tech: Lustre
+    purge_days: 60
+  depot: true
+  fortress: true
+
+toolchain:
+  compiler: GCC 14.1.0
+  mpi: OpenMPI
+
+scheduler:
+  standby_max_hours: 4
+
+qos:
+  - normal
+  - standby
+  - preemptible
+
+partitions:
+  - name: cpu
+    use: "CPU jobs (192-core nodes)"
+    notes: "QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h)"
+  - name: ai
+    use: "GPU jobs (8× H100 per node)"
+    notes: "QOS `normal` or `preemptible`; up to 2 weeks"
+  - name: smallgpu
+    use: "Small GPU jobs (2× L40S per node)"
+    notes: "up to 24 h"
+  - name: highmem
+    use: "Large-memory jobs (1.5 TB nodes)"
+    notes: "up to 24 h; job must use more than 48 cores"
+  - name: profiling
+    use: "Hardware performance profiling"
+    notes: "whole-node; up to 24 h"
+
+anti_patterns:
+  - "**Do NOT** use `--partition=a10` — it is not a Gautschi partition. The valid GPU partitions are `ai` and `smallgpu`."
diff --git a/tools/agent_context/clusters/gilbreth.yml b/tools/agent_context/clusters/gilbreth.yml
new file mode 100644
index 00000000..9822bd76
--- /dev/null
+++ b/tools/agent_context/clusters/gilbreth.yml
@@ -0,0 +1,55 @@
+# Agentic-AI context data model for Gilbreth.
+# Edit this file (not docs/snippets/agentic-ai/gilbreth/**) and re-run
+# tools/generate_agent_context.py. Facts verified against docs/userguides/gilbreth/.
+cluster: gilbreth
+title: Gilbreth
+login_host: gilbreth.rcac.purdue.edu
+os: Rocky 9
+scratch_path: /scratch/gilbreth
+
+filesystems:
+  home:
+    tech: GPFS
+    snapshots: nightly snapshots kept for 7 days, weekly for 4 weeks, and monthly for 3 months (recoverable)
+  scratch:
+    tech: null
+    purge_days: 60
+  depot: true
+  fortress: true
+
+# The default toolchain is contradictory in the Gilbreth docs (overview says Intel
+# 17.0.1.132 + Intel MPI; the shared module macro says GCC + OpenMPI). Leave null so the
+# template tells the agent to discover it with `module avail` / `module load rcac`
+# rather than pinning a possibly-stale version.
+toolchain: null
+
+scheduler:
+  standby_max_hours: 4
+
+qos:
+  - normal
+  - standby
+  - training
+
+# GPU-purchase partitions from run_jobs/queues.md (Gilbreth is GPU-focused; GPU type is
+# selected by partition). Per-partition node/GPU specs are the confirmed queues.md values.
+partitions:
+  - name: a10
+    use: "A10 GPU jobs (3× A10 24 GB per node)"
+    notes: "QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h)"
+  - name: a30
+    use: "A30 GPU jobs (3× A30 24 GB per node)"
+    notes: "QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h)"
+  - name: a100-40gb
+    use: "A100-40GB GPU jobs (2–4× A100 40 GB per node)"
+    notes: "QOS `normal` or `standby`; up to 2 weeks; NVLink nodes need `--constraint=nvlink`"
+  - name: a100-80gb
+    use: "A100-80GB GPU jobs (2× A100 80 GB per node)"
+    notes: "QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h)"
+  - name: training
+    use: "Shared multi-GPU training pool (4 GPUs/node; V100/A100/H100)"
+    notes: "QOS `training` only; up to 24 h; for demonstrated >2-GPU workflows"
+
+anti_patterns:
+  - "**Do NOT** assume a `preemptible` QOS — Gilbreth has none; the low-priority QOS is `standby`, and the shared multi-GPU pool uses `-q training`."
+  - "**Do NOT** pick a GPU type with a `--gres` type string — on Gilbreth the GPU type is chosen by **partition** (`a10`/`a30`/`a100-40gb`/`a100-80gb`); request a count with `--gpus-per-node=N`."
diff --git a/tools/agent_context/clusters/negishi.yml b/tools/agent_context/clusters/negishi.yml
new file mode 100644
index 00000000..762f2dbd
--- /dev/null
+++ b/tools/agent_context/clusters/negishi.yml
@@ -0,0 +1,49 @@
+# Agentic-AI context data model for Negishi.
+# Edit this file (not docs/snippets/agentic-ai/negishi/**) and re-run
+# tools/generate_agent_context.py. Facts verified against docs/userguides/negishi/.
+cluster: negishi
+title: Negishi
+login_host: negishi.rcac.purdue.edu
+os: Rocky Linux 8
+scratch_path: /scratch/negishi
+
+filesystems:
+  home:
+    tech: GPFS
+    snapshots: nightly snapshots kept for 7 days, weekly for 4 weeks, and monthly for 3 months (recoverable)
+  scratch:
+    # Negishi docs describe scratch only as a "high-performance, large-capacity
+    # parallel filesystem" — the specific technology is not stated, so leave it null.
+    tech: null
+    purge_days: 60
+  depot: true
+  fortress: true
+
+toolchain:
+  compiler: GCC 12.2.0
+  mpi: OpenMPI
+
+scheduler:
+  standby_max_hours: 4
+
+qos:
+  - normal
+  - standby
+
+# Batch partitions from run_jobs/queues.md. The interactive `login` partition is
+# omitted here (its canonical name is ambiguous in the docs and interactive sessions
+# use `sinteractive`); the agent context stays focused on batch submission.
+partitions:
+  - name: cpu
+    use: "CPU jobs (128-core nodes, 256 GB)"
+    notes: "QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h)"
+  - name: highmem
+    use: "Large-memory jobs (1 TB nodes)"
+    notes: "QOS `normal`; up to 24 h; job must use more than 64 of 128 cores"
+  - name: gpu
+    use: "GPU jobs (3× AMD MI210 per node)"
+    notes: "QOS `normal`; up to 24 h; request cores proportional to GPUs used"
+
+anti_patterns:
+  - "**Do NOT** assume `ai`/`smallgpu` partitions or a `preemptible` QOS — those are from other RCAC clusters. Negishi's GPU partition is `gpu` (AMD MI210), and the low-priority QOS is `standby`."
+  - "**Do NOT** request unlimited memory with `--mem=0`; set an explicit value (use `--exclusive` for a whole node)."
diff --git a/tools/agent_context/templates/agents.d/filesystems.md.j2 b/tools/agent_context/templates/agents.d/filesystems.md.j2
new file mode 100644
index 00000000..c97c3303
--- /dev/null
+++ b/tools/agent_context/templates/agents.d/filesystems.md.j2
@@ -0,0 +1,62 @@
+{% set longterm_label = "Data Depot and Fortress" if (filesystems.depot and filesystems.fortress) else ("Data Depot" if filesystems.depot else "Fortress") %}
+# Filesystems ({{ title }})
+
+{{ title }} mounts several filesystems, each with a different purpose, technology, and
+durability. Put data in the right place, and never assume a path is durable without
+checking.
+
+## Home — `/home/$USER` (`$HOME`)
+
+- **Technology:** {{ filesystems.home.tech }}, with {{ filesystems.home.snapshots }}.
+- **Use for:** source code, scripts, configuration, small files. It is
+  medium-performance and space-limited.
+- **Do NOT** stage large datasets or run heavy parallel job I/O here.
+
+## Scratch — `{{ scratch_path }}/$USER` (`$RCAC_SCRATCH`)
+
+- **Technology:** {% if filesystems.scratch.tech %}{{ filesystems.scratch.tech }}, a high-performance parallel filesystem{% else %}a high-performance, large-capacity parallel filesystem{% endif %}.
+- **Use for:** active job input/output and large working data. Point writable working
+  files here (`$RCAC_SCRATCH`), not at home. Find the path with `findscratch`.
+- **Not backed up, and purged after {{ filesystems.scratch.purge_days }} days of inactivity** (by last access and
+  content-modification time; touching metadata does not protect a file). Use
+  `purgelist` to see files scheduled for purge.
+{% if filesystems.depot or filesystems.fortress %}
+- **Do NOT** treat scratch as durable storage — move anything you want to keep to {% if filesystems.depot and filesystems.fortress %}Data
+  Depot or Fortress{% elif filesystems.depot %}Data Depot{% else %}Fortress{% endif %}.
+{% else %}
+- **Do NOT** treat scratch as durable storage — move anything you want to keep to
+  durable project or archive storage.
+{% endif %}
+
+## Node-local — `/tmp`
+
+- Ephemeral, per-node storage that exists only while your job runs on that node; not
+  backed up, not recoverable.
+{% if filesystems.depot or filesystems.fortress %}
+
+## Long-term — {{ longterm_label }}
+
+{% if filesystems.depot %}
+- **Data Depot** is group project space on **GPFS** (typically under `/depot`), for
+  active research data you need to keep.
+{% endif %}
+{% if filesystems.fortress %}
+- **Fortress** is the HPSS archive for long-term/cold storage; move data with `hsi`
+  and `htar`.
+{% endif %}
+{% endif %}
+
+## Check before you write
+
+- Run **`myquota`** to read home and scratch usage and limits before writing large
+  amounts of data. **Do NOT assume specific quota numbers** — they differ per user and
+  change over time; read them from `myquota`.
+- Reference paths with environment variables (`$HOME`, `$RCAC_SCRATCH`), not
+  hard-coded strings, since paths can change.
+
+## Prohibitions
+
+- **Do NOT** store secrets, credentials, or sensitive/regulated data in world-readable
+  paths.
+- **Do NOT** perform bulk or recursive deletes (`rm -rf`) without confirming with the
+  user first.
diff --git a/tools/agent_context/templates/agents.d/lmod.md.j2 b/tools/agent_context/templates/agents.d/lmod.md.j2
new file mode 100644
index 00000000..8fe95866
--- /dev/null
+++ b/tools/agent_context/templates/agents.d/lmod.md.j2
@@ -0,0 +1,36 @@
+# Software Modules — Lmod ({{ title }})
+
+Software on {{ title }} is provided through **environment modules** (Lmod), not the
+system package manager.
+
+## Finding and loading software
+
+- `module avail` — list available modules.
+- `module spider <name>` — search for a package and see its versions and
+  prerequisites.
+- `module load <name>/<version>` — load a specific version; `(D)` marks the default.
+- `module list` — show what is currently loaded; `module purge` clears everything.
+
+Load the same modules inside your job scripts that you used interactively, so batch
+jobs run in the environment you tested.
+
+## Recommended toolchain
+
+{% if toolchain %}
+The recommended compiler and MPI stack is **{{ toolchain.compiler }} with {{ toolchain.mpi }}**. Check
+`module avail` for the exact versions available.
+{% else %}
+Do not assume a default compiler or MPI version. Check `module avail` (and, where
+provided, `module load rcac`) for the recommended stack, and verify with `module list`.
+{% endif %}
+
+## Prohibitions
+
+- **Do NOT** install software with `apt`, `yum`, `dnf`, or `sudo` — you do not have
+  root, and system package managers are not the mechanism here. Use modules, or install
+  into user space.
+- **Do NOT invent module names or versions.** Verify a package and version exist with
+  `module spider` (or `module avail`) before claiming it is available or writing it
+  into a job script.
+- For Python, prefer the `anaconda` modules and user environments rather than modifying
+  a base installation.
diff --git a/tools/agent_context/templates/agents.d/policies.md.j2 b/tools/agent_context/templates/agents.d/policies.md.j2
new file mode 100644
index 00000000..d70a8545
--- /dev/null
+++ b/tools/agent_context/templates/agents.d/policies.md.j2
@@ -0,0 +1,45 @@
+# Policies and Safety ({{ title }})
+
+You are acting as a specific user on shared, audited research infrastructure.
+Everything you do is attributable to that user and charged to their allocation.
+
+## Acceptable use
+
+- Use of {{ title }} is bound by Purdue IT's Acceptable Use Policy and RCAC's resource
+  policies. Stay within the user's approved allocations and project scope.
+
+## Data handling
+
+- **Do NOT** place sensitive, regulated, or export-controlled data on the cluster
+  without prior approval, and **do NOT** store any sensitive data in world-readable
+  locations.
+
+## Secrets and credentials
+
+- **Do NOT** read, print, or transmit private keys, API tokens, or passwords, and
+  **do NOT** write them into files, prompts, or your own context. Treat anything under
+  `~/.ssh` and any `.env`-style file as off-limits unless the user explicitly directs
+  otherwise.
+
+## Resource stewardship
+
+- No heavy compute on login nodes; submit through Slurm with time limits (see
+  `slurm.md`). Watch allocation balances with `slist` — a runaway resubmission loop can
+  exhaust an allocation quickly.
+
+## Destructive operations require confirmation
+
+- **Confirm with the user before any destructive or irreversible action:** `rm -rf`,
+  mass file moves, permission changes on shared paths, or bulk `scancel`.
+
+## Containers are not a sandbox here
+
+- {{ title }} uses **Apptainer** (not Docker). RCAC's Apptainer configuration
+  **auto-mounts {% if filesystems.depot %}`/home`, `/depot`, and `/scratch`{% else %}`/home` and `/scratch`{% endif %}** into containers, and those mounts
+  are writable — running inside a container does **not** protect the user's real files
+  from being edited or deleted. Do not assume container isolation.
+
+## Getting help
+
+- Verify AI-generated commands before running them. Report incorrect or harmful AI
+  output to **rcac-help@purdue.edu**.
diff --git a/tools/agent_context/templates/agents.d/slurm.md.j2 b/tools/agent_context/templates/agents.d/slurm.md.j2
new file mode 100644
index 00000000..c0233127
--- /dev/null
+++ b/tools/agent_context/templates/agents.d/slurm.md.j2
@@ -0,0 +1,60 @@
+# Slurm Scheduler ({{ title }})
+
+All real computation on {{ title }} runs as **Slurm** jobs. Never run compute on a login
+node (see `unix.md`) — submit it here.
+
+## Every {{ title }} job needs four things
+
+A job request must specify **resources**, an **account**, a **QOS**, and a
+**partition**. On {{ title }} you MUST explicitly set **both the account
+(`-A`/`--account=`) and the partition (`-p`/`--partition=`)**; also set the QOS
+(`-q`/`--qos=`) and always a time limit (`--time`).
+
+- Discover the accounts you can charge (and their balances) with **`slist`** — do not
+  guess an account name.
+- Set a realistic `--time`; memory is allocated in proportion to the cores you request.
+
+## Partitions
+
+| Partition | For | Notes |
+|-----------|-----|-------|
+{% for p in partitions %}
+| `{{ p.name }}` | {{ p.use }} | {{ p.notes }} |
+{% endfor %}
+
+## QOS and charging
+
+{% if 'normal' in qos %}
+- **`normal`** — the default; normal priority, charged against your account.
+{% endif %}
+{% if 'standby' in qos %}
+- **`standby`** — access to idle resources at low priority, **not charged**, max {{ scheduler.standby_max_hours }}
+  hours. Request it with **`-q standby`** (it is a QOS, **not** an account).
+{% endif %}
+{% if 'preemptible' in qos %}
+- **`preemptible`** — `ai` partition only; cheaper GPU-hours, but jobs can be preempted
+  (killed) to make room for `normal` jobs — checkpoint your work.
+{% endif %}
+{% if 'training' in qos %}
+- **`training`** — required for the `training` partition (`-q training`); low priority,
+  **not charged**, max 24 hours.
+{% endif %}
+
+## Common commands
+
+`sbatch` (submit a batch script), `squeue -u $USER` (your jobs), `scontrol show job
+<id>` (job detail), `scontrol hold`/`release`, `scancel <id>` (cancel), `sinteractive`
+(interactive job), `srun` (launch tasks).
+
+## Prohibitions
+
+{% for ap in anti_patterns %}
+- {{ ap }}
+{% endfor %}
+- **Do NOT** write `-A standby` or `#SBATCH -A standby` — `standby` is a QOS
+  (`-q standby`), not an account.
+- **Do NOT** emit flags for other schedulers (PBS/Torque `#PBS`, LSF `#BSUB`) — this is
+  Slurm.
+- **Do NOT** invent partition or QOS names; the valid sets are listed above.
+- **Do NOT** submit jobs without a `--time` limit, and **do NOT** `scancel` jobs you do
+  not own or run bulk cancellations without confirming with the user.
diff --git a/tools/agent_context/templates/agents.d/unix.md.j2 b/tools/agent_context/templates/agents.d/unix.md.j2
new file mode 100644
index 00000000..50faf610
--- /dev/null
+++ b/tools/agent_context/templates/agents.d/unix.md.j2
@@ -0,0 +1,36 @@
+# Unix Environment ({{ title }})
+
+{{ title }} runs **{{ os }}** with a standard GNU/bash userland. You are acting as a
+specific user, over that user's existing SSH access — you have exactly their
+privileges and nothing more.
+
+## The login (front-end) nodes are shared
+
+Connecting to `{{ login_host }}` places you on one of several shared front-end
+nodes, used simultaneously by many people. They are for **editing, compiling,
+submitting jobs, and light pre- and post-processing only**.
+
+- **Do NOT run large, long, multi-threaded, parallel, or CPU-intensive work on a
+  login node.** Submit it to Slurm instead (see `slurm.md`). Heavy work on a front end
+  degrades the system for everyone and may be killed by administrators.
+- **Do NOT start unbounded background processes or retry loops.** Clean up stray
+  processes, and watch for your own retry storms.
+
+## No elevated privileges
+
+- **Do NOT use `sudo` or attempt to gain root.** You cannot install system packages.
+- Install software into user space, or preferably use the environment modules system
+  (see `lmod.md`).
+
+## Ground yourself before acting
+
+Prefer checking the real state of the system over assuming it. These commands are
+read-only, cheap, and safe — run them eagerly before you plan or act:
+
+- `myquota` — home and scratch usage and limits.
+- `slist` — the accounts you can charge and their balances.
+- `sfeatures` — node and GPU hardware features.
+- `module avail` / `module list` — available and currently-loaded software.
+
+Grounding your plan in real output prevents the most common failure mode: confidently
+acting on an assumption that is wrong for this cluster.
diff --git a/tools/agent_context/templates/claude/settings.json.j2 b/tools/agent_context/templates/claude/settings.json.j2
new file mode 100644
index 00000000..cfeb70c8
--- /dev/null
+++ b/tools/agent_context/templates/claude/settings.json.j2
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Bash(myquota:*)",
+      "Bash(slist:*)",
+      "Bash(sfeatures:*)",
+      "Bash(module list:*)",
+      "Bash(module avail:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(sudo:*)",
+      "Read(./.env)",
+      "Read(~/.ssh/**)"
+    ],
+    "additionalDirectories": ["{{ scratch_path }}"]
+  },
+  "disableBypassPermissionsMode": "disable"
+}
diff --git a/tools/agent_context/templates/codex/config.toml.j2 b/tools/agent_context/templates/codex/config.toml.j2
new file mode 100644
index 00000000..00dfc9af
--- /dev/null
+++ b/tools/agent_context/templates/codex/config.toml.j2
@@ -0,0 +1,21 @@
+# ~/.codex/config.toml — recommended cluster-side config for Codex on {{ title }}.
+#
+# Codex has no per-command allow/deny list; safety comes from the approval policy and
+# the sandbox mode. On shared login nodes where bubblewrap is unavailable, prefer
+# approval_policy = "untrusted" and sandbox_mode = "read-only" so nothing runs without
+# an explicit approval. Codex reads AGENTS.md natively for the shared context.
+#
+# The only MCP server configured here is the hosted documentation server over plain
+# HTTP (no local tooling / no uvx). An agent running on the cluster already has direct
+# shell and Slurm access, so it does NOT need the rcac-mcp SSH bridge — that server is
+# for running an agent locally (see the Local page).
+
+approval_policy = "on-request"
+sandbox_mode    = "workspace-write"
+
+[sandbox_workspace_write]
+writable_roots = ["{{ scratch_path }}"]
+network_access = false
+
+[mcp_servers.rcac_docs]
+url = "https://docs.rcac.purdue.edu/mcp"
diff --git a/tools/agent_context/templates/gemini/settings.json.j2 b/tools/agent_context/templates/gemini/settings.json.j2
new file mode 100644
index 00000000..5c0559ac
--- /dev/null
+++ b/tools/agent_context/templates/gemini/settings.json.j2
@@ -0,0 +1,25 @@
+{
+  "tools": {
+    "core": [
+      "run_shell_command(myquota)",
+      "run_shell_command(slist)",
+      "run_shell_command(sfeatures)",
+      "run_shell_command(module)"
+    ],
+    "exclude": [
+      "run_shell_command(rm)",
+      "run_shell_command(sudo)"
+    ]
+  },
+  "security": {
+    "disableYoloMode": true
+  },
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"]
+  },
+  "mcpServers": {
+    "rcac-docs": {
+      "httpUrl": "https://docs.rcac.purdue.edu/mcp"
+    }
+  }
+}
diff --git a/tools/agent_context/templates/opencode/opencode.json.j2 b/tools/agent_context/templates/opencode/opencode.json.j2
new file mode 100644
index 00000000..3b0c6a15
--- /dev/null
+++ b/tools/agent_context/templates/opencode/opencode.json.j2
@@ -0,0 +1,22 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "myquota": "allow",
+      "slist": "allow",
+      "sfeatures": "allow",
+      "module list": "allow",
+      "module avail *": "allow",
+      "rm -rf *": "deny",
+      "sudo *": "deny"
+    }
+  },
+  "mcp": {
+    "rcac-docs": {
+      "type": "remote",
+      "url": "https://docs.rcac.purdue.edu/mcp",
+      "enabled": true
+    }
+  }
+}
diff --git a/tools/generate_agent_context.py b/tools/generate_agent_context.py
new file mode 100644
index 00000000..2c467a29
--- /dev/null
+++ b/tools/generate_agent_context.py
@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Generate the per-cluster agentic-AI context and settings files from a data model.
+
+Single source of truth: one small YAML per cluster under
+``tools/agent_context/clusters/`` plus the shared Jinja2 templates under
+``tools/agent_context/templates/``. This script renders them into the deployable tree
+``docs/snippets/agentic-ai/<cluster>/`` (the same files RCAC ships to ``/etc/agents.d``
+and the per-harness settings paths), and assembles the concatenated ``AGENTS.md``.
+
+Run from anywhere (paths are resolved relative to this file):
+
+    python tools/generate_agent_context.py
+
+Do NOT hand-edit the generated files under docs/snippets/agentic-ai/<cluster>/ — edit
+the cluster YAML or the templates and regenerate. Any literal ``[NEEDS CLARIFICATION]``
+left in a cluster YAML aborts generation (override with --allow-incomplete for drafts).
+"""
+import glob
+import os
+import shutil
+import sys
+
+import yaml
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+AC_DIR = os.path.join(ROOT_DIR, "tools", "agent_context")
+CLUSTERS_DIR = os.path.join(AC_DIR, "clusters")
+TEMPLATES_DIR = os.path.join(AC_DIR, "templates")
+OUTPUT_ROOT = os.path.join(ROOT_DIR, "docs", "snippets", "agentic-ai")
+
+# Topic files, in the order they are concatenated into AGENTS.md.
+TOPIC_FILES = ["unix", "filesystems", "lmod", "slurm", "policies"]
+
+# (template path relative to TEMPLATES_DIR, output path relative to the cluster dir)
+CONFIG_TEMPLATES = [
+    ("claude/settings.json.j2", "claude/settings.json"),
+    ("codex/config.toml.j2", "codex/config.toml"),
+    ("gemini/settings.json.j2", "gemini/settings.json"),
+    ("opencode/opencode.json.j2", "opencode/opencode.json"),
+]
+
+_MARKER = (
+    "Note: generated by tools/generate_agent_context.py from "
+    "tools/agent_context/clusters/{cluster}.yml. Manual changes will be lost!"
+)
+
+
+def _md_marker(cluster):
+    return "<!-- %s -->\n" % _MARKER.format(cluster=cluster)
+
+
+def _toml_marker(cluster):
+    return "# %s\n" % _MARKER.format(cluster=cluster)
+
+
+def _find_needs_clarification(cluster, data):
+    """Return a list of (path, value) where an unresolved marker string survives."""
+    found = []
+
+    def walk(value, path):
+        if isinstance(value, dict):
+            for key, child in value.items():
+                walk(child, "%s.%s" % (path, key))
+        elif isinstance(value, list):
+            for i, child in enumerate(value):
+                walk(child, "%s[%d]" % (path, i))
+        elif isinstance(value, str) and "[NEEDS CLARIFICATION" in value:
+            found.append((path, value))
+
+    walk(data, cluster)
+    return found
+
+
+def _assemble_agents_md(title, bodies):
+    """Concatenate topic bodies into the single AGENTS.md, matching the deployed shape."""
+    assembled = (
+        "# %s Agent Context\n\n"
+        "This file is the assembled agent context for Purdue RCAC's **%s**\n"
+        "cluster, concatenated from the topic files in `/etc/agents.d/`. It is the\n"
+        "canonical guidance an agent should follow when operating on %s. Read it\n"
+        "before acting.\n" % (title, title, title)
+    )
+    for name in TOPIC_FILES:
+        assembled += "\n<!-- Source: %s.md -->\n\n" % name + bodies[name]
+    return assembled
+
+
+def main():
+    allow_incomplete = "--allow-incomplete" in sys.argv
+
+    env = Environment(
+        loader=FileSystemLoader(TEMPLATES_DIR),
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+        undefined=StrictUndefined,
+    )
+
+    cluster_files = sorted(glob.glob(os.path.join(CLUSTERS_DIR, "*.yml")))
+    if not cluster_files:
+        sys.exit("❌ no cluster data files found in %s" % CLUSTERS_DIR)
+
+    generated = []
+    for cluster_file in cluster_files:
+        with open(cluster_file, encoding="utf-8") as fh:
+            data = yaml.safe_load(fh)
+        cluster = data["cluster"]
+
+        incomplete = _find_needs_clarification(cluster, data)
+        if incomplete and not allow_incomplete:
+            print("❌ %s has unresolved [NEEDS CLARIFICATION]:" % cluster, file=sys.stderr)
+            for path, value in incomplete:
+                print("     %s: %s" % (path, value), file=sys.stderr)
+            sys.exit("Resolve them in %s (or pass --allow-incomplete for a draft)." % cluster_file)
+
+        outdir = os.path.join(OUTPUT_ROOT, cluster)
+        # Regenerate the cluster tree from scratch so removed inputs prune cleanly.
+        if os.path.isdir(outdir):
+            shutil.rmtree(outdir)
+
+        # Render the topic bodies once; reused for the standalone files and AGENTS.md.
+        bodies = {
+            name: env.get_template("agents.d/%s.md.j2" % name).render(**data)
+            for name in TOPIC_FILES
+        }
+
+        agents_d = os.path.join(outdir, "agents.d")
+        os.makedirs(agents_d, exist_ok=True)
+        for name in TOPIC_FILES:
+            with open(os.path.join(agents_d, "%s.md" % name), "w", encoding="utf-8") as fh:
+                fh.write(_md_marker(cluster) + bodies[name])
+
+        with open(os.path.join(agents_d, "AGENTS.md"), "w", encoding="utf-8") as fh:
+            fh.write(_md_marker(cluster) + _assemble_agents_md(data["title"], bodies))
+
+        for tmpl_path, out_path in CONFIG_TEMPLATES:
+            rendered = env.get_template(tmpl_path).render(**data)
+            if out_path.endswith(".toml"):
+                rendered = _toml_marker(cluster) + rendered
+            # JSON cannot carry a comment marker; the tree-level GENERATED.md documents it.
+            dest = os.path.join(outdir, out_path)
+            os.makedirs(os.path.dirname(dest), exist_ok=True)
+            with open(dest, "w", encoding="utf-8") as fh:
+                fh.write(rendered)
+
+        generated.append(cluster)
+
+    print(
+        "✅ generated agentic-AI context for %d cluster(s): %s"
+        % (len(generated), ", ".join(generated))
+    )
+
+
+if __name__ == "__main__":
+    main()