[feature] Add an Agentic AI documentation section (guidance, MCP, shared context) for Gautschi - #275
Open
glentner wants to merge 30 commits into
Open
[feature] Add an Agentic AI documentation section (guidance, MCP, shared context) for Gautschi#275glentner wants to merge 30 commits into
glentner wants to merge 30 commits into
Conversation
…nvention consistency)
…breadcrumbs, sweep
Human review of the rendered section (pre /docs-review) requested four changes; applied across the drafted pages and recorded in GOAL/PLAN/TECH: 1. Paper as a measured footer reference (GitHub replication package) on the hub, not the lead; DOI deferred until on the ACM DL. 2. Measured, professional tone: removed "mostly harmless" and pop-culture framing throughout; kept the single load-bearing "Tea, Earl Grey, hot" prompting example. 3. Distinguished the cluster MCP (rcac-mcp: background SSH bridge, pure tool-calling, for the CLI harnesses) from Warp (desktop terminal; user SSHs in and the agent rides the live session; does not use the cluster MCP; wire in /etc/agents.d once SSH'd). Neutralized the "MCP + SSH" umbrella label to "over SSH". 4. Framed per-harness settings as RCAC-deployed to system-managed paths and enforced (transparency), not user-installed; honest caveats for Codex (no managed path) and Warp (no settings file -> inline team-managed Agent Profile). Deleted the misleading warp/AGENTS.md snippet. Verified via adversarial multi-lens review + --strict build (clean), HPC accuracy preserved (a10/-A standby only in prohibitions), breadcrumbs regenerated.
…ot rcac-mcp Follow-up to the human-review pass. The published per-harness settings are cluster-side (for an agent running on the Gautschi nodes), so registering the local-side rcac-mcp SSH bridge there was wrong: it needs uvx (not on the nodes' PATH) and is pointless for an agent that already has direct shell/Slurm access. - codex/gemini/opencode cluster-side configs now register the hosted, no-auth documentation MCP (https://docs.rcac.purdue.edu/mcp, doc_search/doc_load) over plain HTTP using each harness's remote-HTTP schema (httpUrl / url / type:remote); the rcac-mcp (uvx + --ssh-host) entries were removed. - settings.md now states the cluster-side vs local-side split explicitly, adds the Claude .mcp.json HTTP docs server, and points local rcac-mcp users to the Local page. rcac-mcp remains the local-side registration on running_agents/local.md. - GOAL/PLAN/TECH updated to record the refinement.
glentner
added
the
harness-feedback
| - 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 |
Collaborator
There was a problem hiding this comment.
We need this entry on index page of Gautschi as well.
Collaborator
|
Member
Author
|
Ah, on (1) yes. On (2) that's a great question and I'm not sure how to handle this. I'm starting with Gautschi for now. All of this is (will be) true of Gautschi. Other clusters will have slightly different context files but most of the content is the same. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Researchers already run agentic coding tools (Claude Code, Codex, Gemini CLI, opencode, Warp) on and against RCAC clusters, but the docs site had zero public guidance on it — no acceptable-use rules, no setup, no mention of our MCP servers, and no account of the context we inject into agents. This PR builds RCAC's documentation pillar for agentic AI, following the strategy of proactive engagement, not prohibition (verify, don't forbid).
It adds a new top-level Agentic AI section plus a cross-linked Using AI Agents chapter in the Gautschi user guide, and — as a shared construction exercise — authors the first real canonical shared-context and per-harness settings files for Gautschi (the source of truth Puppet copies to
/etc/agents.dand the HPC MCP server injects over SSH).Scope is Gautschi only (other clusters are an explicit follow-up). No MCP-server code, no Puppet pipeline, no theme/CSS/JS changes, no blog post.
Reader-facing outcome: stance + acceptable use + best-practices/limitations; a Running Agents guide organized by deployment mode (on-cluster login nodes vs. local via MCP + SSH) covering all five harnesses; an MCP-servers page (
rcac-mcp,globus-mcp,rcac-docs-mcp); and the Gautschi/etc/agents.dcontext files + per-harness settings published verbatim with a feedback path.Artifacts
spec/agentic-ai-docs/GOAL.mdspec/agentic-ai-docs/PLAN.md·TECH.mdspec/agentic-ai-docs/research/spec/agentic-ai-docs/REVIEW.mdPhases completed
rcac-mcp/globus-mcp/rcac-docs-mcp)/etc/agents.dfilesVerification
Blind adversarial review (fresh context, graded against
GOAL.md+ invariants, by rendering — seeREVIEW.md). Verdict: approved (cycle 1), no CONFIRMED defects.hammerable:false):mkdocs build --strict | strict_check.py→ PASS, 0 warnings. All 11 new pages are inmkdocs.ymlnav:; snippet--8<--includes expand verbatim in the built HTML; macros render; content-level a11y (one H1/page, heading descent, table header rows, relative links / absolute assets) verified.rcac-mcp; Apptainer-not-Docker with the auto-bind-mount caveat).uvxinstall commands couldn't be verified against the private repos from the review sandbox — a maintainer with repo access should confirm; (2) filesystem-technology labels (/homeZFS,/depotGPFS,/scratchLustre) match the human-corrected facts inGOAL.mdbut aren't stated on the gold-standard storage page.origin/main(after PR [harness] Add the RCAC-Docs documentation factory (spec-driven authoring lifecycle) #273 merged) with zero conflicts; the--strictgate was re-verified andstrict-baseline.txttrimmed to empty (origin's4f3e3574fixed all 7 prior warnings). Details inREVIEW.md→ "Post-rebase integration".🔧 Harness feedback — 1 open finding (route later via
/docs-harness)docs-review's scope/branch-hygiene check is optional, so bundled non-content commits nearly slipped past review (target:.agents/skills/docs-review/SKILL.md).Full detail in
spec/agentic-ai-docs/META.md. Do not resolve here.🤖 Generated with Claude Code