requestshield 0.1.4 → 0.1.6

package/skills/requestshield/SKILL.md

@@ -1,307 +1,299 @@
----
-name: requestshield
-description: Install, verify, troubleshoot, or remove IntelliFend RequestShield bot protection in a customer codebase — the browser SDK in Seamless or Manual mode, plus Java backend enforcement via the Spring Boot 3 starter or the Java core SDK — driving the `requestshield` CLI for sign-in, app keys, the integration contract, and traffic checks. Use this skill whenever the user mentions RequestShield, IntelliFend, `X-IntelliFend-Token`, `IntelliFend.getToken()`, `data-protect`, `@RequestShieldProtected`, App Key or API Secret setup, or asks to protect an endpoint such as registration, sign-in, password reset, checkout, or form submission from bots, scripted abuse, or credential stuffing — even when they never name the product. Also use it before hand-editing any file that already contains a RequestShield script tag, `verify()` call, or protection annotation.
----
-
-# RequestShield integration
-
-Every RequestShield integration has two halves, and the split is the thing to
-understand before writing any code:
-
-1. **The browser** obtains a short-lived token and transports it with the protected
-   request, as the `X-IntelliFend-Token` header.
-2. **The backend** evaluates that token and enforces the decision before the protected
-   operation runs.
-
-The browser half is a *transport*, never a gate. A page that obtains tokens whose
-backend never verifies them has zero protection while looking fully integrated — the
-most common way this integration silently fails. Equally, an annotation on a handler
-creates no browser configuration. **Browser configuration and backend protection are
-configured independently, and neither one implies the other.** Land both halves in the
-same change and verify both.
-
-Protect the operation that performs the business mutation — registration, sign-in,
-password reset, checkout, form submission — not a read-only route in front of it.
-
-## Before touching integration files
-
-```bash
-requestshield --version          # is the CLI present?
-requestshield auth status        # {"authenticated":true,...} — most commands need this
-```
-
-
-If `requestshield --version` fails, the CLI is not installed. **Stop and say so.** Ask
-the user to install it; do not substitute hand-crafted HTTP calls, and do not fall back
-to the example values in this skill — the contract is the only authoritative source for
-the script URL, header name, and released modes, and a guessed script URL produces a
-page that silently loads nothing.
-
-If `auth status` shows the user signed out, ask them to run `requestshield signin`
-themselves — it is interactive. Never script around it or ask for credentials.
-
-Those commands are the preflight for integration-changing work. For read-only CLI
-questions, go to **Classify the request** and run only the matching command.
-
-## Classify the request
-
-Only **Install** and **Uninstall** are step-locked sequences. Every other intent is a
-single CLI call or a short answer. Match on what the user wants, not on exact wording.
-
-| Intent | Sounds like | Do this |
-| --- | --- | --- |
-| **General info** | "what version", "is there a newer CLI", "am I up to date" | `requestshield --version`, then `requestshield update check`. Report both and the gap between them. No credentials check, no repo scan. |
-| **Authentication** | "sign me in", or preflight `auth status` came back unauthenticated | Ask the user to run `requestshield signin` in their own terminal, and wait. It is interactive — never automate it, never run it for them, never ask for credentials. Re-run `auth status` once they confirm. |
-| **Key / secret management** | "create an app key", "I need an API Secret", "rotate the secret", "deactivate a key" | **Hand the command over; do not run it.** → "Key and secret management" below. |
-| **Install** | "add RequestShield", "protect /api/register" | `references/integration-planning.md` full flow → **Installing** → **Verifying** → **Negative test**. Do not reorder or skip a step. |
-| **Uninstall** | "remove it", "roll it back" | `references/integration-planning.md` (Detect existing integration only) → **Uninstalling**. |
-| **Verify / troubleshoot** | "is it set up right?", "why is it not blocking?", a reason code | `references/integration-planning.md` (Detect existing integration only) → **Verifying**. For a reason code, also read `references/troubleshooting.md`. |
-| **Challenge volume** | "how much traffic", "how many challenges", "show me the volume" | Ask for the time range first. `challenge volume` takes `--from`/`--to`/`--granularity`; a guessed window produces a confident wrong answer. Then run it with the App Key. |
-| **Billing** | "am I being charged", "what plan", "what are my limits" | `requestshield get billing`. |
-| **Service health** | "is the service up", "is it degraded" | `requestshield server`. |
-| **Agent setup** | "set this up for Codex too", "install the skill for Claude" | Run `requestshield agent setup` for auto-detection, or pass the requested agent: `--agent codex` or `--agent claude`. This installs agent guidance; it does not mint keys or edit customer application code. |
-| **Anything else** | | Look the command up in `references/cli.md`. If it is not there, run `requestshield --help` rather than guessing at a flag. |
-
-Full CLI surface, output shapes, and which commands need auth: `references/cli.md`.
-
-
-For Install, `references/integration-planning.md` owns the full planning sequence:
-Credentials check, Detect existing integration, Contract check, Gate, Then act on what
-you found, and Choosing the mode. Keep the browser-mode and backend-path decisions
-independent.
-
-## Key and secret management
-
-`keys create`, `app key rotate`, and `keys deactive` are the one place you do **not**
-drive the CLI. Two independent reasons, and each is sufficient on its own:
-
-- `keys create` and `app key rotate` print the API Secret to stdout exactly once. A
-  command you run puts that value in your tool output and transcript.
-- `keys deactive` and `app key rotate` change state for a live App Key. Deactivating the
-  wrong one stops verifying real traffic.
-
-So hand it over. Tell the user which command to run in their own terminal:
-
-```bash
-requestshield keys create --app-name <name>          # new App Key + API Secret pair
-requestshield app key rotate --app-key <app-key>     # new secret, App Key unchanged
-requestshield keys deactive --app-key <app-key>      # stops verification for that key
-```
-
-Warn them **before** they run secret creation or rotation that the secret appears once
-and they need somewhere to put it. Afterwards, confirm by presence only and use
-`requestshield credentials status <app-key>` for the server-side view. Never ask the
-user to paste the secret back, and never read it out of a file or the environment.
-
-A lost or exposed secret cannot be re-displayed. The fix is `app key rotate`, run by
-the user. Deleting a leaked value from a repo, log, artifact, or transcript does not
-un-expose it.
-
-## Installing
-
-For Install, run the full planning flow in `references/integration-planning.md` before
-writing integration code: **Credentials check** → **Detect existing integration** →
-**Contract check** → **Gate** → **Then act on what you found** → **Choosing the mode**.
-It must settle the App Key, the existing-integration state, the contract values, the
-backend path, and the browser mode before step 1 below.
-
-1. **Browser side** — add the hosted script once in `<head>`, using the `script_url`
-   from `requestshield contract`, then follow the chosen browser reference:
-   - Seamless → `references/browser-seamless.md`
-   - Manual → `references/browser-manual.md`
-2. **Backend side** — add the dependency, configure `app-key` and `api-secret` from
-   environment variables, and enforce the decision before the mutation:
-   - Spring Boot 3 starter → `references/backend-spring-boot.md`
-   - Java core SDK → `references/backend-java-core.md`
-3. **Cross-origin API**, if the protected endpoint is on another origin — its CORS
-   response must allow the page origin, intended methods, and `X-IntelliFend-Token`.
-4. **CSP**, if the app sends one — merge, never replace. See
-   `references/browser-manual.md`.
-5. **Verify** — run the checklist below, then the negative test when safe.
-
-## Handling the App Key and API Secret
-
-These two values have opposite handling rules:
-
-- **App Key** is public. It belongs in the browser script tag and backend configuration.
-  The same value must appear on both sides or every token fails.
-- **API Secret** is backend-only. It must reach the backend through an environment
-  variable or secret manager. Never write it into a source file, a committed `.env`, an
-  image layer, a CI config in the repo, or the chat transcript — and never echo it back
-  after reading it.
-
-You never run the commands that display the API Secret, and you never read it back. The
-hand-off and warning are in **Key and secret management** above. Afterwards refer to it
-only as "the secret you just received".
-
-If a secret has already reached a repo, a log, an artifact, or this transcript, the fix
-is `requestshield app key rotate --app-key <app-key>`, run by the user.
-
-## Verifying
-
-For standalone Verify / Troubleshoot, first run **Detect existing integration only** in
-`references/integration-planning.md`. You are observing which browser mode and backend
-path are in use, not choosing them — **Credentials check**, **Contract check**,
-**Gate**, and **Choosing the mode** belong to the Install flow unless troubleshooting
-evidence specifically points to a credential failure or an unreleased mode.
-
-Then the static checks. They are deterministic and catch most real breakage.
-
-- Exactly **one** SDK script tag, in `<head>`, loaded before any bundle that can issue a
-  protected request, with a real `data-app-key`.
-- Seamless: every protected endpoint appears in `data-protect`, spelled as the exact
-  origin and pathname the browser actually requests — case and trailing slash included.
-- Manual: every protected call site obtains a fresh token immediately before the request
-  and attaches it, including retry paths.
-- Neither mode applied twice to the same operation.
-- Backend: the dependency resolves, the App Key matches the browser's, the secret comes
-  from the environment, and the decision gates the mutation rather than only being
-  logged. Exactly one verification path per request.
-- Cross-origin endpoints: CORS allows `X-IntelliFend-Token`.
-- No token or secret in logs, analytics, URLs, or error reporting.
-
-Structural correctness is not proof of enforcement. For runtime evidence, exercise the
-endpoint and confirm the platform saw the traffic:
-
-```bash
-requestshield challenge volume <app-key> \
-  --from <start> \
-  --to <end> \
-  --granularity hour
-```
-
-Report static correctness and platform traffic separately. A flat zero after real
-traffic means the browser half is not firing; go back to the selected browser reference
-before changing backend code.
-
-### The negative test — the only proof of enforcement
-
-Neither static checks nor `challenge volume` can prove the backend refuses a tokenless
-mutation. The proof is a request the backend should reject.
-
-Before running it, establish:
-
-1. `requestshield server` is healthy. This reports platform health only; it does not prove
-   that the backend under test can reach the Challenge Server or that its local circuit
-   has closed. A healthy platform can still produce a degraded result at that backend.
-2. The endpoint's effective mode is `BLOCK`, not `MONITOR`. Include any method-level
-   override when resolving the effective mode. `MONITOR` allows every request by design.
-3. A valid control request is available. Its authentication, session, CSRF state, route,
-   method, and body must remain valid during the comparison.
-4. Establish a way to observe degradation for the backend instance and App Key under
-   test. For the Spring Boot starter, use the `intellifend.requestshield.requests` metric and distinguish
-   `outcome=allowed, reason=ok` from `outcome=degraded, reason=service_unavailable`. For
-   the Java core SDK, use existing safe metrics or logs derived from `isDegraded()` and
-   `getReason().getCode()`. Never log the raw token, API Secret, session, or CSRF value.
-
-**Confirm with the user before running this anywhere shared.** It exercises a real
-mutation, so use a local or staging environment, or an endpoint whose write can be
-undone. Do not fire it at production to "just check", and do not invent a body that
-could create a real account.
-
-First, send the control request through the normal integrated path with a fresh
-RequestShield token. Confirm that it succeeds, reaches the intended mutation, and records
-a non-degraded `ok` decision at the backend. A successful response produced by degraded
-fail-open is not a valid control. Use a new token for every control attempt because
-RequestShield tokens are single-use.
-
-Then repeat the same request while preserving its valid authentication, session, CSRF
-state, route, method, body, and other relevant headers. Remove only
-`X-IntelliFend-Token`. Send it through a client that bypasses the Browser SDK so Seamless
-mode cannot attach another token:
-
-```bash
-curl -i -X POST https://<host>/api/register \
-  -H '<the same valid authentication and CSRF context>' \
-  -H 'Content-Type: application/json' \
-  -d '{ ...the same valid test body... }'
-```
-
-Attribute the result to RequestShield rather than treating every 4xx as a pass.
-Authentication, authorization, CSRF, and request validation can independently return a
-401, 403, or 400 before the protected mutation.
-
-- **Spring Boot 3 starter:** pass only when the response is HTTP 403 with
-  `CHALLENGE_FAILED` and reason `missing_token`, and the handler produced no side effect.
-- **Java core SDK:** read the handler before testing. Confirm that its
-  `!result.isAllowed()` branch rejects before the mutation, then verify that the
-  observed rejection corresponds to RequestShield's `missing_token` decision and
-  produced no side effect.
-- **Any unrelated or unattributable 4xx:** inconclusive, not a pass. Fix the control
-  request or add safe RequestShield-specific observability before drawing a conclusion.
-- **Any backend-specific degraded evidence, including `service_unavailable`:**
-  inconclusive. The SDK intentionally allows the request under its availability policy; 
-  restore the backend's Challenge Server connectivity, wait for its circuit to recover, 
-  and repeat with a new control token.
-
-A `2xx`, or evidence that the mutation happened, is a confirmed missing-token
-enforcement bypass only when backend-specific degradation has been ruled out for that
-request. If backend-specific degradation evidence is absent or cannot be checked, 
-report the test as inconclusive—not as proof that enforcement is absent. When degradation 
-is ruled out, treat the bypass as the finding and go to `references/troubleshooting.md`.
-
-## Uninstalling
-
-Run `references/integration-planning.md` Detect existing integration only before this
-section. Remove only what RequestShield introduced, and confirm the list with the user
-first:
-
-1. The script tag, including `data-protect` and any other RequestShield attributes.
-2. Manual-mode `getToken()` calls and the header lines they feed — leave the surrounding
-   request intact.
-3. The backend dependency, client configuration, and the enforcement: `verify()` calls
-   or `@RequestShieldProtected` annotations.
-4. RequestShield entries in the CSP header and in CORS allowed headers — leave every
-   other source and header in place.
-5. Configuration keys and environment variable references.
-
-Then ask whether to also deactivate the keys server-side:
-`requestshield keys deactive --app-key <app-key>`. That is not reversible the way a
-code edit is, so it stays the user's explicit call.
-
-## Non-negotiables
-
-These separate an integration that protects traffic from one that only looks like it:
-
-- **Enforcement lives in the backend.** Application code in the browser must never
-  decide to allow, block, retry around, or interpret a token.
-- **Browser configuration and backend protection are independent.** Neither implies the
-  other.
-- **One browser mode and one backend path are selected independently.** Seamless is not
-  Spring Boot, and Manual is not Java core. Either browser mode may pair with either
-  supported backend path.
-- **One token per protected request; a new token before every retry.** Tokens are
-  single-use; replaying one returns `token_replayed` and blocks the request.
-- **One verification per request.** Never combine `@RequestShieldProtected` with a
-  manual `RequestShieldClient.verify()` on the same handler.
-- **Forward a non-empty token unchanged.** Do not trim, re-encode, inspect, cache,
-  persist, log, or place it in a URL.
-- When `getToken()` returns an empty string in Manual mode, omit the header and let the
-  backend apply its configured policy.
-- **The API Secret stays at the backend.** Never put it in browser code,
-  client-visible responses, source control, logs, build artifacts, or chat transcripts.
-- **You never run a command that mints, rotates, or deactivates a key.** Hand those
-  commands to the user and verify by presence only.
-
-## Reference files
-
-| File | Read it when |
-| --- | --- |
-| `references/cli.md` | Any CLI invocation — exact syntax, output shape, auth requirements |
-| `references/integration-planning.md` | Credentials check, existing-integration detection, the contract check, backend gating (Java version, Spring Boot 3 MVC vs WebFlux, other frameworks), and browser-mode selection |
-| `references/browser-manual.md` | Installing or auditing Manual mode; CSP rules |
-| `references/browser-seamless.md` | Installing or auditing Seamless mode; matching and coverage limits |
-| `references/backend-spring-boot.md` | Backend work on Spring Boot 3 MVC — the annotation path |
-| `references/backend-java-core.md` | Backend work on any other Java 17 backend — the `verify()` path |
-| `references/troubleshooting.md` | A block, a degraded result, or a reason code to explain |
-
-## For agent setup
-
-`requestshield agent setup` installs this skill for the detected or requested agent.
-Use `--agent codex` or `--agent claude` when the user names the target agent. For Codex
-repositories that also use `AGENTS.md`, the CLI can write the managed block from
-`assets/AGENTS.codex.md` so repo-local guidance points back to the installed skill and
-the same reference files.
-
-Agent setup installs guidance only. It does not mint keys, rotate secrets, deactivate
-keys, or edit customer application code.
+---
+name: requestshield
+description: Install, verify, troubleshoot, or remove IntelliFend RequestShield bot protection in a customer codebase — the browser SDK in Seamless or Manual mode, plus Java backend enforcement via the Spring Boot 3 starter or the Java core SDK — using the `requestshield` CLI for sign-in, applications and credentials, with SDK documentation and runtime observations for integration checks. Use this skill whenever the user mentions RequestShield, IntelliFend, `X-IntelliFend-Token`, `IntelliFend.getToken()`, `data-protect`, `@RequestShieldProtected`, App Key or API Secret setup, or asks to protect an endpoint such as registration, sign-in, password reset, checkout, or form submission from bots, scripted abuse, or credential stuffing — even when they never name the product. Also use it before hand-editing any file that already contains a RequestShield script tag, `verify()` call, or protection annotation.
+---
+
+# RequestShield integration
+
+Every RequestShield integration has two halves, and the split is the thing to
+understand before writing any code:
+
+1. **The browser** obtains a short-lived token and transports it with the protected
+   request, as the `X-IntelliFend-Token` header.
+2. **The backend** evaluates that token and enforces the decision before the protected
+   operation runs.
+
+The browser half is a *transport*, never a gate. A page that obtains tokens whose
+backend never verifies them has zero protection while looking fully integrated — the
+most common way this integration silently fails. Equally, an annotation on a handler
+creates no browser configuration. **Browser configuration and backend protection are
+configured independently, and neither one implies the other.** Land both halves in the
+same change and verify both.
+
+Protect the operation that performs the business mutation — registration, sign-in,
+password reset, checkout, form submission — not a read-only route in front of it.
+
+## Before touching integration files
+
+```bash
+requestshield --version          # is the CLI present?
+requestshield auth status --json # local session metadata, no provider check
+```
+
+
+If `requestshield --version` fails, explain that CLI account/app operations need
+an installed compatible version. Do not substitute invented HTTP calls. SDK URLs,
+headers, modes and backend requirements come from the customer documentation for
+the chosen SDK release; the integration-contract CLI command is unavailable.
+
+If local status is `signed_out`, ask the user to complete `requestshield signin`
+themselves. Never ask for credentials. `valid` is a local state only; an expired
+session may refresh during the next authenticated command.
+
+Those commands are the preflight for integration-changing work. For read-only CLI
+questions, go to **Classify the request** and run only the matching command.
+
+## Classify the request
+
+Only **Install** and **Uninstall** are step-locked sequences. Every other intent is a
+single CLI call or a short answer. Match on what the user wants, not on exact wording.
+
+| Intent | Sounds like | Do this |
+| --- | --- | --- |
+| **General info** | "what version", "is there a newer CLI", "am I up to date" | Use `requestshield --version`. For an explicitly requested update check, explain that production `update check` can offer a global npm installation; accept it only within the user’s requested scope. |
+| **Authentication** | "sign me in", or preflight `auth status` came back unauthenticated | Ask the user to run `requestshield signin` in their own terminal, and wait. It is interactive — never automate it, never run it for them, never ask for credentials. Re-run `auth status` once they confirm. |
+| **Key / secret management** | "create an app key", "I need an API Secret", "rotate the secret", "deactivate a key" | **Hand the command over; do not run it.** → "Key and secret management" below. |
+| **Install** | "add RequestShield", "protect /api/register" | `references/integration-planning.md` full flow → **Installing** → **Verifying** → **Negative test**. Do not reorder or skip a step. |
+| **Uninstall** | "remove it", "roll it back" | `references/integration-planning.md` (Detect existing integration only) → **Uninstalling**. |
+| **Verify / troubleshoot** | "is it set up right?", "why is it not blocking?", a reason code | `references/integration-planning.md` (Detect existing integration only) → **Verifying**. For a reason code, also read `references/troubleshooting.md`. |
+| **Challenge volume** | "how much traffic", "how many challenges" | Explain that the CLI analytics command is unavailable. Use existing authorized monitoring; do not infer volume from app status. |
+| **Billing** | "am I being charged", "what plan", "what are my limits" | Explain that billing is unavailable in this CLI; use the customer’s established billing/support channel. |
+| **Service health** | "is the service up", "is it degraded" | No service-health CLI command exists. Inspect authorized health/monitoring evidence without exposing credentials. |
+| **Agent setup** | "set this up for Codex too", "install the skill for Claude" | Run `requestshield agent setup` for auto-detection, or pass the requested agent: `--codex` or `--claude`. This installs agent guidance; it does not mint keys or edit customer application code. |
+| **Anything else** | | Look the command up in `references/cli.md`. If it is not there, run `requestshield --help` rather than guessing at a flag. |
+
+Full CLI surface, output shapes, and which commands need auth: `references/cli.md`.
+
+
+For Install, `references/integration-planning.md` owns the full planning sequence:
+Credentials check, Detect existing integration, Contract check, Gate, Then act on what
+you found, and Choosing the mode. Keep the browser-mode and backend-path decisions
+independent.
+
+## Key and secret management
+
+Commands that display API secrets should run in the user's terminal so their
+values never enter the agent's tool output or conversation. State-changing
+commands must match the user's requested application and action.
+
+```console
+requestshield keys create --app-name <name>
+requestshield keys rotate <app-key>
+requestshield keys reveal <app-key>
+requestshield keys revoke <app-key>
+requestshield apps disable <app-key>
+```
+
+Create makes a new application. Rotate keeps the App Key and replaces its secret.
+Reveal retrieves the current active secret when a prior response was lost; an
+exposed secret instead requires rotation. Revoke invalidates the secret, while
+application disable retains it. Acceptance is asynchronous, not proof of immediate
+propagation. Explain the impact and storage requirement before the user runs a
+command, then confirm secret presence only. Never ask them to paste a secret back.
+
+Create/rename/enable do not prompt. Disable/rotate/revoke/reveal require confirmation
+or `--yes`. Mutations other than reveal accept `--idempotency-key`; uncertain results
+must be retried with identical arguments and the same key within seven days, never
+a fresh key. A replay may return `apiSecret: null`; use explicit reveal rather than
+automatically creating or rotating again. See `references/cli.md`.
+
+## Installing
+
+For Install, run the full planning flow in `references/integration-planning.md` before
+writing integration code: **Credentials check** → **Detect existing integration** →
+**Contract check** → **Gate** → **Then act on what you found** → **Choosing the mode**.
+It must settle the App Key, the existing-integration state, the contract values, the
+backend path, and the browser mode before step 1 below.
+
+1. **Browser side** — add the hosted script once in `<head>`, using the `script_url`
+   from the published customer documentation for that SDK release, then follow the chosen browser reference:
+   - Seamless → `references/browser-seamless.md`
+   - Manual → `references/browser-manual.md`
+2. **Backend side** — add the dependency, configure `app-key` and `api-secret` from
+   environment variables, and enforce the decision before the mutation:
+   - Spring Boot 3 starter → `references/backend-spring-boot.md`
+   - Java core SDK → `references/backend-java-core.md`
+3. **Cross-origin API**, if the protected endpoint is on another origin — its CORS
+   response must allow the page origin, intended methods, and `X-IntelliFend-Token`.
+4. **CSP**, if the app sends one — merge, never replace. See
+   `references/browser-manual.md`.
+5. **Verify** — run the checklist below, then the negative test when safe.
+
+## Handling the App Key and API Secret
+
+These two values have opposite handling rules:
+
+- **App Key** is public. It belongs in the browser script tag and backend configuration.
+  The same value must appear on both sides or every token fails.
+- **API Secret** is backend-only. It must reach the backend through an environment
+  variable or secret manager. Never write it into a source file, a committed `.env`, an
+  image layer, a CI config in the repo, or the chat transcript — and never echo it back
+  after reading it.
+
+You never run the commands that display the API Secret, and you never read it back. The
+hand-off and warning are in **Key and secret management** above. Afterwards refer to it
+only as "the secret you just received".
+
+If a secret has already reached a repo, a log, an artifact, or this transcript, the fix
+is `requestshield keys rotate <app-key>`, run by the user.
+
+## Verifying
+
+For standalone Verify / Troubleshoot, first run **Detect existing integration only** in
+`references/integration-planning.md`. You are observing which browser mode and backend
+path are in use, not choosing them — **Credentials check**, **Contract check**,
+**Gate**, and **Choosing the mode** belong to the Install flow unless troubleshooting
+evidence specifically points to a credential failure or an unreleased mode.
+
+Then the static checks. They are deterministic and catch most real breakage.
+
+- Exactly **one** SDK script tag, in `<head>`, loaded before any bundle that can issue a
+  protected request, with a real `data-app-key`.
+- Seamless: every protected endpoint appears in `data-protect`, spelled as the exact
+  origin and pathname the browser actually requests — case and trailing slash included.
+- Manual: every protected call site obtains a fresh token immediately before the request
+  and attaches it, including retry paths.
+- Neither mode applied twice to the same operation.
+- Backend: the dependency resolves, the App Key matches the browser's, the secret comes
+  from the environment, and the decision gates the mutation rather than only being
+  logged. Exactly one verification path per request.
+- Cross-origin endpoints: CORS allows `X-IntelliFend-Token`.
+- No token or secret in logs, analytics, URLs, or error reporting.
+
+Structural correctness is not proof of enforcement. For runtime evidence,
+exercise the endpoint in an authorized environment and inspect the browser request
+and backend decision without recording tokens. The CLI challenge-volume command
+is unavailable, and application status does not establish traffic. Report static
+checks, observed requests and backend enforcement separately.
+
+### The negative test — the only proof of enforcement
+
+Neither static checks nor observed browser traffic can prove the backend refuses a
+tokenless mutation. The proof is a request the backend should reject.
+
+Before running it, establish:
+
+1. The backend under test can reach its configured verification service and safe
+   metrics show a non-degraded control request. A platform-wide health report alone
+   would not establish that this backend’s local circuit has closed.
+2. The endpoint's effective mode is `BLOCK`, not `MONITOR`. Include any method-level
+   override when resolving the effective mode. `MONITOR` allows every request by design.
+3. A valid control request is available. Its authentication, session, CSRF state, route,
+   method, and body must remain valid during the comparison.
+4. Establish a way to observe degradation for the backend instance and App Key under
+   test. For the Spring Boot starter, use the `intellifend.requestshield.requests` metric and distinguish
+   `outcome=allowed, reason=ok` from `outcome=degraded, reason=service_unavailable`. For
+   the Java core SDK, use existing safe metrics or logs derived from `isDegraded()` and
+   `getReason().getCode()`. Never log the raw token, API Secret, session, or CSRF value.
+
+**Confirm with the user before running this anywhere shared.** It exercises a real
+mutation, so use a local or staging environment, or an endpoint whose write can be
+undone. Do not fire it at production to "just check", and do not invent a body that
+could create a real account.
+
+First, send the control request through the normal integrated path with a fresh
+RequestShield token. Confirm that it succeeds, reaches the intended mutation, and records
+a non-degraded `ok` decision at the backend. A successful response produced by degraded
+fail-open is not a valid control. Use a new token for every control attempt because
+RequestShield tokens are single-use.
+
+Then repeat the same request while preserving its valid authentication, session, CSRF
+state, route, method, body, and other relevant headers. Remove only
+`X-IntelliFend-Token`. Send it through a client that bypasses the Browser SDK so Seamless
+mode cannot attach another token:
+
+```bash
+curl -i -X POST https://<host>/api/register \
+  -H '<the same valid authentication and CSRF context>' \
+  -H 'Content-Type: application/json' \
+  -d '{ ...the same valid test body... }'
+```
+
+Attribute the result to RequestShield rather than treating every 4xx as a pass.
+Authentication, authorization, CSRF, and request validation can independently return a
+401, 403, or 400 before the protected mutation.
+
+- **Spring Boot 3 starter:** pass only when the response is HTTP 403 with
+  `CHALLENGE_FAILED` and reason `missing_token`, and the handler produced no side effect.
+- **Java core SDK:** read the handler before testing. Confirm that its
+  `!result.isAllowed()` branch rejects before the mutation, then verify that the
+  observed rejection corresponds to RequestShield's `missing_token` decision and
+  produced no side effect.
+- **Any unrelated or unattributable 4xx:** inconclusive, not a pass. Fix the control
+  request or add safe RequestShield-specific observability before drawing a conclusion.
+- **Any backend-specific degraded evidence, including `service_unavailable`:**
+  inconclusive. The SDK intentionally allows the request under its availability policy; 
+  restore the backend's Challenge Server connectivity, wait for its circuit to recover, 
+  and repeat with a new control token.
+
+A `2xx`, or evidence that the mutation happened, is a confirmed missing-token
+enforcement bypass only when backend-specific degradation has been ruled out for that
+request. If backend-specific degradation evidence is absent or cannot be checked, 
+report the test as inconclusive—not as proof that enforcement is absent. When degradation 
+is ruled out, treat the bypass as the finding and go to `references/troubleshooting.md`.
+
+## Uninstalling
+
+Run `references/integration-planning.md` Detect existing integration only before this
+section. Remove only what RequestShield introduced, and confirm the list with the user
+first:
+
+1. The script tag, including `data-protect` and any other RequestShield attributes.
+2. Manual-mode `getToken()` calls and the header lines they feed — leave the surrounding
+   request intact.
+3. The backend dependency, client configuration, and the enforcement: `verify()` calls
+   or `@RequestShieldProtected` annotations.
+4. RequestShield entries in the CSP header and in CORS allowed headers — leave every
+   other source and header in place.
+5. Configuration keys and environment variable references.
+
+Application disable is a separate action: `requestshield apps disable <app-key>`.
+Perform or hand it off only when the user requested that live-state change; removing
+integration code does not itself authorize revocation or disable.
+
+## Non-negotiables
+
+These separate an integration that protects traffic from one that only looks like it:
+
+- **Enforcement lives in the backend.** Application code in the browser must never
+  decide to allow, block, retry around, or interpret a token.
+- **Browser configuration and backend protection are independent.** Neither implies the
+  other.
+- **One browser mode and one backend path are selected independently.** Seamless is not
+  Spring Boot, and Manual is not Java core. Either browser mode may pair with either
+  supported backend path.
+- **One token per protected request; a new token before every retry.** Tokens are
+  single-use; replaying one returns `token_replayed` and blocks the request.
+- **One verification per request.** Never combine `@RequestShieldProtected` with a
+  manual `RequestShieldClient.verify()` on the same handler.
+- **Forward a non-empty token unchanged.** Do not trim, re-encode, inspect, cache,
+  persist, log, or place it in a URL.
+- When `getToken()` returns an empty string in Manual mode, omit the header and let the
+  backend apply its configured policy.
+- **The API Secret stays at the backend.** Never put it in browser code,
+  client-visible responses, source control, logs, build artifacts, or chat transcripts.
+- **Keep displayed secrets out of tool output.** Hand create/rotate/reveal to the
+  user and verify by presence only. Match other live-state changes to user intent.
+
+## Reference files
+
+| File | Read it when |
+| --- | --- |
+| `references/cli.md` | Any CLI invocation — exact syntax, output shape, auth requirements |
+| `references/integration-planning.md` | Credentials check, existing-integration detection, the contract check, backend gating (Java version, Spring Boot 3 MVC vs WebFlux, other frameworks), and browser-mode selection |
+| `references/browser-manual.md` | Installing or auditing Manual mode; CSP rules |
+| `references/browser-seamless.md` | Installing or auditing Seamless mode; matching and coverage limits |
+| `references/backend-spring-boot.md` | Backend work on Spring Boot 3 MVC — the annotation path |
+| `references/backend-java-core.md` | Backend work on any other Java 17 backend — the `verify()` path |
+| `references/troubleshooting.md` | A block, a degraded result, or a reason code to explain |
+
+## For agent setup
+
+`requestshield agent setup` installs this skill for the detected or requested agent.
+Use `--codex` or `--claude` when the user names the target agent. Setup installs
+into the agent’s personal skill directory; it does not edit repository `AGENTS.md`.
+`assets/AGENTS.codex.md` is an optional template for a separately requested
+repository instruction change.
+
+Agent setup installs guidance only. It does not mint keys, rotate secrets, deactivate
+keys, or edit customer application code.