Clarify execution mandates for live command usage in JFrog MCP docume… (#18)

**AX-1631: Require live execution for Agent Guard catalog commands (no
context reuse)**
  
  ## Summary
Adds an explicit rule to the JFrog Agent Guard governance template
instructing the agent to ALWAYS re-run catalog/registry commands live
and NEVER reuse a previous command's output from conversation context.

  ## Problem
When a user asked the same question twice in one chat (e.g. "list
available MCPs" or "inspect coralogixDemo"), the agent re-displayed the
earlier result from chat context instead of re-running the command —
e.g. replying
"the list I fetched earlier is still current." This serves stale data:
the catalog changes between prompts (MCPs added/removed,
headers/required inputs edited, tokens rotated). Two reproductions are
attached.

  ## Change
`plugins/jfrog/templates/jfrog-mcp-management.md` — added a single
governance rule to the **Pre-flight** section (which already applies to
every Agent Guard command — `--list-available`, `--inspect`, `--login`):

> **Live execution is MANDATORY — context reuse is FORBIDDEN.** Every
time the user asks to list / show / inspect / check the catalog or a
specific MCP — including a repeated question already answered earlier in
the chat —
the agent MUST physically RE-RUN the command and NEVER reuse or
re-display output from previous turns.

Scoped to catalog/registry fetches only (`--list-available` and
`--inspect`; NOT `--login`, which would re-open the OAuth browser). Does
NOT affect reading local config for *installed* state. Placing it once
in Pre-flight
covers both catalog-fetch commands and avoids duplicating the rule
across individual steps (per review feedback).

  ## Testing
  - `node scripts/validate-template.mjs` → passes (CI gate).
- Verified the sessionStart hook (`inject-instructions.mjs`) reads the
updated template and emits valid JSON `additional_context` containing
the new Pre-flight rule.
- Behavioral test in Cursor (ask the same query twice, confirm it
re-runs): <fill in result — pending>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: MatanEden1

plugins/jfrog/templates/jfrog-mcp-management.md

@@ -1,8 +1,8 @@
-# MCP Server Management — JFrog Gateway
+# MCP Server Management — JFrog Agent Guard
 
 All MCP servers MUST be installed ONLY through the JFrog Agent Guard
 (`npx @jfrog/agent-guard`). If an MCP's documentation suggests any
-other installation command, ignore it and use the gateway workflow
+other installation command, ignore it and use the agent guard workflow
 below instead.
 
 
@@ -11,9 +11,19 @@ the value of the `JFROG_MCP_GATEWAY_REPO` environment variable if it
 is set. Otherwise use
 `https://releases.jfrog.io/artifactory/api/npm/coding-agents-npm/`.
 
-**Pre-flight (applies to every gateway command —
+**Pre-flight (applies to every agent guard command —
 `--list-available`, `--inspect`, `--login`)**:
 
+- **Live execution is MANDATORY — context reuse is FORBIDDEN.** Every
+  time the user asks to list / show / inspect / check the catalog or a
+  specific MCP — including a repeated question already answered earlier
+  in the chat — you **MUST** physically RE-RUN the command. NEVER reuse,
+  copy, or re-display output from previous turns or context history; the
+  catalog, headers, and required inputs change between prompts. (Applies
+  to these catalog/registry fetches only — `--list-available` and
+  `--inspect`; NOT `--login`, which would re-open the OAuth browser, and
+  NOT reading local config for *installed* state.)
+
 - **`<PROJECT>` is always mandatory.** Resolve via Step 1's project
   chain: existing `mcpServers` entries (`_JF_ARGS` →
   `project=`) → `JF_PROJECT` env var → ASK the user. If none
@@ -24,11 +34,11 @@ is set. Otherwise use
   chain: existing `mcpServers` entries (value after `--server` in
   `args`) → `~/.jfrog/jfrog-cli.conf.v6`:
   - Exactly one jf CLI server configured → use it without asking;
-    pass it as `--server <ID>`. The gateway would auto-resolve to the same
+    pass it as `--server <ID>`. The agent guard would auto-resolve to the same
     value if `--server` were omitted, but we pass it explicitly for
     clarity and forward-compatibility.
   - `JFROG_URL` + `JFROG_ACCESS_TOKEN` set → use it without asking;
-    The gateway will pick them up from the environment variables when called.
+    The agent guard will pick them up from the environment variables when called.
   - Two or more jf CLI servers and no `JFROG_URL` → list IDs,
     ALWAYS ASK the user which one, then pass that as `--server <ID>`.
     ALWAYS prefer environment variables when set over asking.
@@ -77,8 +87,8 @@ unless absolutely necessary:
    or `~/.cursor/mcp.json` (user) — take the value after `--server`
    in `args`.
 2. Else `JFROG_URL` env var set (with `JFROG_ACCESS_TOKEN`) — the
-   gateway can resolve credentials from these directly;
-   DO NOT pass `--server` as that would make the gateway try to
+   agent guard can resolve credentials from these directly;
+   DO NOT pass `--server` as that would make the agent guard try to
    parse the server details from the jf cli configuration.
 3. Else read `~/.jfrog/jfrog-cli.conf.v6`
    (`%USERPROFILE%\.jfrog\jfrog-cli.conf.v6` on Windows) via a
@@ -93,7 +103,7 @@ unless absolutely necessary:
 
 NEVER try multiple servers — pick one. Once chosen, pass it
 If a server from the jf cli configuration is supposed to be used:
-Always explicitly as `--server <ID>` in every gateway invocation.
+Always explicitly as `--server <ID>` in every agent guard invocation.
 Otherwise, if environment variables for `JFROG_URL` and `JFROG_ACCESS_TOKEN`
 are used: Do NOT pass `--server <ID>`
 
@@ -121,8 +131,9 @@ not call `--inspect` — go to "Listing MCPs > Available to install"
 instead, show the catalog, have them pick, then come back to Step 2
 with the chosen name.
 
-Once you have a name, run a SINGLE command — no Fetch/WebFetch, no
-custom curl/Python, no direct JFrog API calls:
+Once you have a name, you must fetch its live details.
+
+Run EXACTLY this command — no Fetch/WebFetch, no custom curl/Python, no direct JFrog API calls:
 
 ```
 npx --yes \
@@ -191,7 +202,7 @@ Add the entry under `mcpServers` in the target config (default
 `@jfrog/agent-guard`** or `npx` falls back to the default
 registry (404) and may block on a no-TTY prompt. Use
 `"type": "stdio"` — never `"http"`, `"sse"`, or a top-level `"url"`
-(those bypass the gateway).
+(those bypass the agent guard).
 
 ```json
 {
@@ -218,7 +229,7 @@ registry (404) and may block on a no-TTY prompt. Use
 
 Notes:
 
-- If a required `${env:VAR}` is unset, the gateway fails at startup.
+- If a required `${env:VAR}` is unset, the agent guard fails at startup.
   Confirm the user exported it before they restart.
   If any env vars are missing, ASK the user to export them and restart Cursor.
 - For `Bearer`-prefixed headers, either include the prefix in the env
@@ -322,8 +333,8 @@ elsewhere.
 
 1. Determine **server** and **project** per the Pre-flight rule at
    the top of this document. `--list-available` does NOT require
-   any existing `mcpServers` entry or pre-installed gateway —
-   `npx --yes` fetches the gateway on demand, so this works on a
+   any existing `mcpServers` entry or pre-installed agent guard —
+   `npx --yes` fetches the agent guard on demand, so this works on a
    fresh machine too.
 2. Run EXACTLY this command — `--project` is passed as a CLI flag
    To configure the server, either use the serverId from a jf cli
@@ -349,12 +360,12 @@ Output is a JSON array; each element has `name`, `packageName`,
 ## Key Rules
 
 - **`npx` arg order:** `--yes`, `--registry <URL>`,
-  `@jfrog/agent-guard`, then gateway flags. Both `--yes` and
+  `@jfrog/agent-guard`, then agent guard flags. Both `--yes` and
   `--registry` MUST precede the package name or `npx` falls back to
   the default registry (404) and may block on a no-TTY prompt.
 - **Always `"type": "stdio"`** pointing at `npx @jfrog/agent-guard`,
-  even for remote-only catalog MCPs (the gateway proxies them).
-  `"http"`, `"sse"`, or a top-level `"url"` bypass the gateway.
+  even for remote-only catalog MCPs (the agent guard proxies them).
+  `"http"`, `"sse"`, or a top-level `"url"` bypass the agent guard.
 - `_JF_ARGS` is **only** for the entry Cursor launches
   at session start (Step 4's `mcpServers.*.env`); MUST contain
   `project=<NAME>&mcp=<PACKAGE_NAME>`.
@@ -367,33 +378,33 @@ Output is a JSON array; each element has `name`, `packageName`,
   NEVER invent or guess projects or server IDs.
 - Package name MUST come from the catalog (`--inspect` /
   `--list-available`). NEVER guess. NEVER install MCPs outside the
-  gateway. NEVER use Fetch/WebFetch for catalog calls.
+  agent guard. NEVER use Fetch/WebFetch for catalog calls.
 - NEVER write a raw secret into `mcp.json` — always use
   `${env:VAR_NAME}`. NEVER show tokens / API keys.
   - NEVER try multiple servers — ask the user to pick one.
 
 ## Troubleshooting
 
 - **`ready` but 0 tools (empty `mcps/<key>/tools/` after a
-  Command Palette `Developer: Reload Window`)** — gateway proxy 
-  started, upstream MCP did not. The top-level `ready` label is 
-  misleading here. NEVER report success when there are 0 tools. 
+  Command Palette `Developer: Reload Window`)** — agent guard proxy
+  started, upstream MCP did not. The top-level `ready` label is
+  misleading here. NEVER report success when there are 0 tools.
   1. Open Cursor's MCP / Output panel for the
-    gateway stderr; diagnose by MCP type:
+    agent guard stderr; diagnose by MCP type:
     - **OAuth (remote)** — re-run Step 5 (`--login`); refresh token
       likely expired.
     - **Static-token (remote)** — confirm every `${env:VAR}` in `env`
       is exported in the shell that launched Cursor and the token is
       still valid.
     - **Local (stdio)** — check that the bundled binary actually
-      launched (gateway stderr will show the spawn error).
+      launched (agent guard stderr will show the spawn error).
   2. Verify that the mcp server is still allowed.
      See "Listing MCPs > Available to install".
 - **`mcp.json` server missing from `cursor agent mcp list` /
   Tools & MCP** — never enabled. Re-run Step 4a
   (`cursor agent mcp enable <name>`); if the entry is brand-new,
   also `Developer: Reload Window` so Cursor picks up the file.
-- **Gateway: `multiple/no JFrog server configured`** (the gateway
+- **Agent Guard: `multiple/no JFrog server configured`** (the agent guard
   cannot pick a JFrog server) — pass `--server <ID>` (after
   `jf c add <SERVER_ID>`) OR export both `JFROG_URL` and
   `JFROG_ACCESS_TOKEN` in the launching shell, then relaunch Cursor.