requestshield 0.1.4 → 0.1.5

package/skills/requestshield/references/integration-planning.md

@@ -1,389 +1,389 @@
-# Integration planning
-
-Use this reference before writing or removing RequestShield integration code. It owns the
-planning steps that are too detailed for `SKILL.md`.
-
-## Workflow by operation
-
-- **Install** -> `integration-planning.md` full flow: **Credentials check** ->
-  **Detect existing integration** -> **Contract check** -> **Gate** -> **Then act on
-  what you found** -> **Choosing the mode** -> **Installing** -> **Verifying** ->
-  **Negative test**.
-- **Verify / Troubleshoot** -> `integration-planning.md` (Detect existing integration
-  only) -> **Verifying**. If a reason code, degraded result, browser mode, backend path,
-  or unknown state is involved, read only the matching reference files.
-- **Uninstall** -> `integration-planning.md` (Detect existing integration only) ->
-  **Uninstalling**.
-
-Do not couple browser mode to backend path. They are independent axes:
-
-- Browser mode: Seamless (`browser-seamless.md`) or Manual (`browser-manual.md`).
-- Backend path: Spring Boot 3 starter (`backend-spring-boot.md`) or Java core SDK
-  (`backend-java-core.md`).
-
-Either browser mode may pair with either supported backend path. The backend stack
-selects the backend path. The way the browser issues the protected request selects the
-browser mode.
-
-## Credentials check
-
-The **pre-edit** check: confirm a credential source exists before touching backend
-integration code. This step belongs to the Install full flow.
-
-- **Install** — always, before editing backend code.
-- **Verify / Troubleshoot** — do not run this as part of the operation route. Start with
-  **Detect existing integration only**, then use `troubleshooting.md` if the evidence
-  points to a credential failure.
-- **Uninstall** — do not run this step; detect the existing integration only.
-
-Diagnosing a credential *failure* is a different question, and `troubleshooting.md`
-owns it — go there for `consume_unauthorized`, `unknown_customer`, or a backend
-rejecting every token, whether or not this check has already passed.
-
-RequestShield requires:
-
-- an App Key
-- an API Secret
-
-Check for credential sources without printing, reading, or echoing their values. Confirm
-presence only; never print, cat, or echo either value:
-
-```bash
-# Presence check only. Never print secret values.
-
-if env | grep -Eq '^(INTELLIFEND_)?REQUESTSHIELD_(APP_KEY|KEY)='; then
-  echo "RequestShield App Key: present"
-else
-  echo "RequestShield App Key: not found in current environment"
-fi
-
-if env | grep -Eq '^(INTELLIFEND_)?REQUESTSHIELD_(API_SECRET|SECRET)='; then
-  echo "RequestShield API Secret: present"
-else
-  echo "RequestShield API Secret: not found in current environment"
-fi
-```
-
-Common variable names are `INTELLIFEND_REQUESTSHIELD_APP_KEY`,
-`REQUESTSHIELD_APP_KEY`, `REQUESTSHIELD_KEY`,
-`INTELLIFEND_REQUESTSHIELD_API_SECRET`, `REQUESTSHIELD_API_SECRET`, and
-`REQUESTSHIELD_SECRET`. A matching non-canonical name is only a credential candidate.
-Confirm that the backend actually reads or maps that variable before treating it as a
-valid RequestShield credential.
-
-If the App Key is known, also confirm server-side credential state without exposing the
-secret:
-
-```bash
-requestshield credentials status <app-key>
-```
-
-A credential that is not present in the current shell is not necessarily missing from
-the deployed backend. It may be injected at runtime by a secret manager, CI/CD system,
-container runtime, Kubernetes Secret, or deployment environment.
-
-Report only what was confirmed:
-
-| Finding | Action |
-| --- | --- |
-| Both credential sources are confirmed | Continue. Never read their values. |
-| A non-canonical variable is found and its backend mapping is confirmed | Report the mapping and continue. |
-| Credentials are provisioned, but the runtime source is unknown | Ask how the deployed backend receives them before editing backend integration code. |
-| No credential source can be confirmed | Report the uncertainty and ask before proceeding. |
-| No credential pair has been provisioned | Ask the user to provision credentials before continuing with backend setup. |
-
-If no pair has been provisioned yet, the user creates it. You may run the read-only
-`requestshield apps list` to see whether an application already exists. Everything that
-mints or changes a secret stays with the user; see **Key and secret management** in
-`SKILL.md`.
-
-## Detect existing integration
-
-Search for existing RequestShield code before install, verify/troubleshoot, or uninstall.
-Use `rg` when available. Use `rg -l` for filename-only discovery.
-
-
-Browser markers:
-
-```bash
-rg -l "data-app-key|data-protect|IntelliFend|X-IntelliFend-Token" \
-  -g "*.html" -g "*.htm" -g "*.js" -g "*.jsx" -g "*.ts" -g "*.tsx" \
-  -g "*.vue" -g "*.svelte" -g "*.astro" \
-  -g "*.erb" -g "*.haml" -g "*.php" -g "*.jinja*" -g "*.j2" -g "*.twig" \
-  -g "*.hbs" -g "*.ejs" -g "*.pug" -g "*.blade.php" \
-  -g "!node_modules/**" -g "!**/skills/**" -g "!**/.requestshield/**" .
-```
-
-The tag often lives in a server-rendered layout rather than a static `.html` — a Django,
-Rails, Laravel, or Thymeleaf base template — so a scan limited to `.html`/`.js` reports
-"not integrated" on a codebase that already has one, and the install then adds a second
-tag. If the app's templates use an extension not listed above, add it before concluding.
-
-Backend markers:
-
-```bash
-rg -l "RequestShieldClient|RequestShieldProtected|intellifend|requestshield" \
-  -g "*.java" -g "*.kt" -g "*.xml" -g "*.yml" -g "*.yaml" \
-  -g "*.gradle" -g "*.gradle.kts" \
-  -g "!**/skills/**" -g "!**/.requestshield/**" .
-```
-
-`rg -l` returns candidate filenames only. Do not follow it with `cat`, an unrestricted
-`sed`, plain `rg -n` without `-o`, or another command that exposes complete matching
-lines or the entire file.
-
-Locate known markers without returning the rest of their lines:
-
-```bash
-rg -n -o \
-  "data-app-key|data-protect|IntelliFend|getToken|X-IntelliFend-Token" \
-  <browser-candidate-file>
-
-rg -n -o \
-  "RequestShieldClient|RequestShieldProtected|verify|isAllowed|intellifend|requestshield" \
-  <backend-candidate-file>
-
-rg -n -o \
-  "(INTELLIFEND_)?REQUESTSHIELD_(APP_KEY|KEY|API_SECRET|SECRET)" \
-  <candidate-configuration-file>
-```
--o prints only the matched marker or environment-variable name, not the surrounding
-value. Environment-variable names are safe to report; their values are not.
-
-When configuration context is required, inspect it only through a secret-aware parser
-or redacted view that masks sensitive values before stdout reaches the agent. Its output
-may contain the filename, line number, configuration key, environment-variable name,
-App Key when needed to identify the integration, and whether the source is an
-environment reference, secret-manager reference, or literal.
-
-Replace every API Secret, RequestShield token, session value, CSRF value,
-authorization credential, and other credential literal with <redacted>.
-
-If no secret-aware parser or redacted view is available, do not read the candidate
-configuration file verbatim. Ask the user for a sanitized excerpt instead. Switching
-to rg -l and then reading the entire candidate file is not safe.
-
-The exclusions matter when this skill is installed inside the repo being scanned —
-browser and backend reference files contain marker strings and would otherwise read as
-an existing integration.
-
-Report one of:
-
-- **Not integrated**: no browser or backend markers.
-- **Browser only**: tokens may be obtained or attached, but no backend enforcement was
-  found. This looks protected and is not.
-- **Backend only**: enforcement exists, but no page sends a token. In BLOCK mode this can
-  reject legitimate users.
-- **Fully integrated**: browser mode and backend path are both present. Name both.
-
-If a script tag already exists, update it instead of adding a second one. The SDK
-initializes from `document.currentScript`; two tags mean two configurations, and the
-last one to run wins rather than the two merging.
-
-## Contract check
-
-Run this **after** detection and **before** the Gate: detection says what the codebase
-already does, the contract says what the platform currently allows, and the browser-mode
-decision needs both.
-
-```bash
-requestshield contract
-```
-
-It is authoritative for `browser.script_url`, `browser.token_header`,
-`browser.available_modes`, `backend.supported_languages`, and `backend.min_jdk`. Use
-those values verbatim; a stale hardcoded script URL produces a page that loads nothing
-and fails silently.
-
-Treat every array as an **allow-list**. There is no "unavailable" flag, so something is
-unavailable when it is absent — and an absent, empty, or unparseable array is
-unavailable, not permission. If the contract is missing or returns `ok: false`, stop and
-report what the CLI returned.
-
-### Backend consequences — these feed the Gate
-
-- `backend.supported_languages` missing the customer's backend language → **stop.** No
-  backend path exists, and a browser-only install protects nothing.
-- `backend.min_jdk` above the project's Java target → **stop.** The JDK upgrade is the
-  prerequisite; do not fall back to an older SDK version.
-
-### Browser-mode consequences — these decide the mode
-
-Read `browser.available_modes` together with what detection found in the codebase:
-
-| Released modes | Codebase today | Do this |
-| --- | --- | --- |
-| **One mode** | already uses that mode | Keep it. Nothing to change on the browser side. |
-| **One mode** | uses the *other* mode | **This is a finding, not a preference.** The mode in the codebase is not released, so it cannot be relied on. Report it and migrate the client to the released mode. |
-| **One mode** | not integrated | No choice to make. Install that mode, and say which one and why. |
-| **Both modes** | already uses one of them | **Keep the mode already in use.** Change it only for a concrete reason — the transport is one Seamless cannot cover, or the user asks. A mode switch rewrites working call sites and risks leaving an endpoint half-migrated. |
-| **Both modes** | not integrated | A genuine choice. Go to **Choosing the mode** below. |
-| **Neither** | any | **Stop.** No browser mode is released; report the contract output. |
-
-Per-endpoint, not per-repo: a page may legitimately run Seamless on one endpoint and
-Manual on another. Apply the table to the operation being worked on, not to the codebase
-as a whole.
-
-## Gate
-
-The backend path is decided by the backend stack, not by browser preference. Establish
-this before proposing edits. Discovering a backend blocker after the browser half is
-written leaves tokens flowing with nothing enforcing them.
-
-An integration is one backend path plus one browser mode, and they are independent
-choices. A non-Spring-MVC backend does not rule out Seamless mode; it only rules out the
-Spring Boot 3 starter backend path.
-
-Backend path:
-
-| Backend path | Requirement | Reference |
-| --- | --- | --- |
-| **Spring Boot 3 starter** | Spring Boot 3 with Spring MVC, and Java 17+ | `backend-spring-boot.md` |
-| **Java core SDK** | Java 17+ | `backend-java-core.md` |
-
-Browser mode:
-
-| Browser mode | Use when | Reference |
-| --- | --- | --- |
-| **Seamless** | The page reaches the endpoint with `fetch` or async `XMLHttpRequest` | `browser-seamless.md` |
-| **Manual** | The call needs explicit token timing, or a non-header carrier | `browser-manual.md` |
-
-Either browser mode pairs with either backend path. The token travels in
-`X-IntelliFend-Token` regardless. Java below 17 blocks both backend paths, and no amount
-of browser-side work substitutes for backend enforcement.
-
-### Run the check
-
-Find the build file for the module that serves the protected endpoint, not the first one
-in the tree. In a monorepo, locate the route first:
-
-```bash
-find . -maxdepth 4 \( -name pom.xml -o -name "build.gradle*" \) \
-  -not -path "*/node_modules/*" -not -path "*/build/*" -not -path "*/target/*"
-rg -n "/api/register" -g "*.java" -g "*.kt" .
-```
-
-One build file, inspect it. Several, and the route cannot be tied to one of them — or
-several backends could plausibly serve it — **stop and ask which service owns the
-endpoint.** Two backends in a monorepo can differ in both Java version and framework, so
-a guess here invalidates the whole integration rather than needing a tweak.
-
-Use repo-wide build-file scans only for discovery. Do not combine a route found in one
-module with Java or Spring evidence from another module.
-
-#### Java target version
-
-Read the *project's target*, never the machine's JDK.
-
-```bash
-rg -n "maven\.compiler\.(release|source|target)|<release>|<java\.version>" <owning-pom.xml>
-rg -n "languageVersion|sourceCompatibility|jvmToolchain|JavaVersion" <owning-build.gradle*>
-```
-
-- **Maven** — `maven.compiler.release`, or the compiler plugin's `<release>`, is
-  authoritative. Spring Boot's parent POM exposes `<java.version>`, which is the
-  idiomatic place in a Boot app. **Check the parent POM too** when the module inherits;
-  the value is often not in the module's own file.
-- **Gradle** — `java.toolchain.languageVersion = JavaLanguageVersion.of(21)` and
-  `kotlin { jvmToolchain(21) }` are both authoritative, and both easy to miss because
-  they sit inside a block rather than on a property line.
-- **When the build file says nothing** — `.java-version`, `.sdkmanrc`, `.tool-versions`,
-  a `setup-java` step's `java-version` in `.github/workflows/`, or a JDK base image in a
-  `Dockerfile`. These are **hints, not answers**: they describe an environment, which can
-  differ from what the build compiles against. A build file that yields only hints is the
-  ambiguous row below — ask.
-- `java -version` reports the **local** JDK. A repo targeting 11 builds fine on a machine
-  with 21 installed, so it is a last-resort hint and never evidence.
-
-Java below 17 blocks **both** backend paths. Report the version and its source and name
-the upgrade as the prerequisite; do not fall back to an older SDK version or write a
-partial browser-only integration.
-
-#### Spring Boot 3, and separately Spring MVC
-
-Two conditions. Both must hold for the Spring Boot starter.
-
-```bash
-rg -n "spring-boot-starter-parent|spring-boot-dependencies|org\.springframework\.boot" \
-  <owning-pom.xml-or-build.gradle*> | rg "3\.[0-9]+"
-rg -n "spring-boot-starter-web[\"' :<]|spring-boot-starter-webflux|spring-webmvc" \
-  <owning-pom.xml-or-build.gradle*>
-```
-
-Read the parent version, the `spring-boot-dependencies` BOM version, or the Gradle plugin
-version. **Spring Boot 2.x does not qualify** — the starter is a Boot 3 artifact, so a
-2.x app needs the core SDK path even though it is Spring.
-
-Then MVC versus WebFlux — the trap worth checking every time:
-
-- `spring-boot-starter-web` → Spring MVC. The starter is available when the app is also
-  Spring Boot 3 on Java 17+.
-- `spring-boot-starter-webflux` with no `-web` → **not** Spring MVC. The starter protects
-  Spring MVC handler methods, so `@RequestShieldProtected` does not apply. Such an app is
-  Spring Boot 3 on Java 17+ and still needs the Java core SDK — say so explicitly,
-  because "Spring Boot 3, Java 21" reads like a starter green light and quietly is not.
-  Browser mode is unaffected; Seamless remains available when the request transport
-  matches.
-- **Both present** → determine which stack serves the protected route. A
-  `@RestController` returning `Mono`/`Flux`, or a `RouterFunction`, indicates the
-  reactive path. Ask if it stays unclear.
-
-Also not Spring MVC, and therefore the Java core SDK backend path: **Quarkus, Micronaut,
-Dropwizard, Helidon, Ktor, Vert.x, Jakarta EE / JAX-RS on its own, and a plain servlet
-application.**
-
-## Then act on what you found
-
-This decision chooses the backend path only. Pick the browser mode separately from how
-the page issues the protected request.
-
-| Detected | Do this |
-| --- | --- |
-| Java < 17, or no Java backend | Stop before editing. Report the finding and its source; no backend path is available, so nothing can enforce. Name the upgrade as the prerequisite. |
-| Java 17+, no Spring Boot 3 MVC | Use Java core SDK. It is the only backend option; state it rather than asking a fake choice. |
-| Java 17+ and Spring Boot 3 MVC | Both backend paths are viable. Recommend the starter and confirm once. |
-| Ambiguous module, missing build file, version only in environment hints, or unclear MVC/WebFlux ownership | Ask, showing what you found. |
-
-Always report the evidence with file and line references:
-
-```text
-Backend: theair-customer-backend/build.gradle.kts
-  Java 21           - java.toolchain.languageVersion (line 14)
-  Spring Boot 3.2.1 - org.springframework.boot plugin (line 3)
-  Spring MVC        - spring-boot-starter-web (line 20)
-Backend path: Spring Boot 3 starter. Browser mode still depends on released modes and request transport.
-```
-
-Detection is inference from build files. If any line would read "unknown", ask rather
-than assume.
-
-## Choosing the mode
-
-Reach this section only when **Contract check** left a genuine choice: both modes
-released, and this operation not already integrated. If it landed on any other row of
-that table, the mode is already decided — do not re-open it here.
-
-This is the browser half. Backend path does not constrain it. Both browser modes deliver
-the token in `X-IntelliFend-Token`, which either backend path reads.
-
-| | **Seamless** | **Manual** |
-| --- | --- | --- |
-| Browser | `data-protect` lists exact endpoints; the SDK attaches tokens to matching `fetch` and async XHR requests. | `await IntelliFend.getToken()` at each protected call site, attached in application code. |
-| Requires | The request travels by `fetch` or async XHR from page scope. | Nothing beyond the SDK and a supported carrier. |
-| Code touched | One line of HTML. | Every protected call site, plus every retry path. |
-| Backend work | Identical either way: whichever backend path the Gate selected. | Identical either way: whichever backend path the Gate selected. |
-
-Released-mode availability was already settled at **Contract check**. One question is
-left: does the protected request travel by `fetch` or asynchronous `XMLHttpRequest` from
-page scope? Native form POST, `sendBeacon`, WebSocket/EventSource, synchronous XHR,
-`no-cors`, and service-worker-owned requests are not intercepted — read
-`browser-seamless.md` for the full coverage list.
-
-Recommend Seamless when that check passes. It touches one line instead of every call
-site, so there is no missed call site or retry path. If it fails, use Manual and give
-the reason; that is a finding, not a preference.
-
-A given protected operation uses one mode, not both. Different endpoints on the same
-page may use different modes when necessary. Never use two backend verification paths on
-one request; `@RequestShieldProtected` and manual `RequestShieldClient.verify()` both
-consume the token, so the second returns `token_replayed`.
+# Integration planning
+
+Use this reference before writing or removing RequestShield integration code. It owns the
+planning steps that are too detailed for `SKILL.md`.
+
+## Workflow by operation
+
+- **Install** -> `integration-planning.md` full flow: **Credentials check** ->
+  **Detect existing integration** -> **Contract check** -> **Gate** -> **Then act on
+  what you found** -> **Choosing the mode** -> **Installing** -> **Verifying** ->
+  **Negative test**.
+- **Verify / Troubleshoot** -> `integration-planning.md` (Detect existing integration
+  only) -> **Verifying**. If a reason code, degraded result, browser mode, backend path,
+  or unknown state is involved, read only the matching reference files.
+- **Uninstall** -> `integration-planning.md` (Detect existing integration only) ->
+  **Uninstalling**.
+
+Do not couple browser mode to backend path. They are independent axes:
+
+- Browser mode: Seamless (`browser-seamless.md`) or Manual (`browser-manual.md`).
+- Backend path: Spring Boot 3 starter (`backend-spring-boot.md`) or Java core SDK
+  (`backend-java-core.md`).
+
+Either browser mode may pair with either supported backend path. The backend stack
+selects the backend path. The way the browser issues the protected request selects the
+browser mode.
+
+## Credentials check
+
+The **pre-edit** check: confirm a credential source exists before touching backend
+integration code. This step belongs to the Install full flow.
+
+- **Install** — always, before editing backend code.
+- **Verify / Troubleshoot** — do not run this as part of the operation route. Start with
+  **Detect existing integration only**, then use `troubleshooting.md` if the evidence
+  points to a credential failure.
+- **Uninstall** — do not run this step; detect the existing integration only.
+
+Diagnosing a credential *failure* is a different question, and `troubleshooting.md`
+owns it — go there for `consume_unauthorized`, `unknown_customer`, or a backend
+rejecting every token, whether or not this check has already passed.
+
+RequestShield requires:
+
+- an App Key
+- an API Secret
+
+Check for credential sources without printing, reading, or echoing their values. Confirm
+presence only; never print, cat, or echo either value:
+
+```bash
+# Presence check only. Never print secret values.
+
+if env | grep -Eq '^(INTELLIFEND_)?REQUESTSHIELD_(APP_KEY|KEY)='; then
+  echo "RequestShield App Key: present"
+else
+  echo "RequestShield App Key: not found in current environment"
+fi
+
+if env | grep -Eq '^(INTELLIFEND_)?REQUESTSHIELD_(API_SECRET|SECRET)='; then
+  echo "RequestShield API Secret: present"
+else
+  echo "RequestShield API Secret: not found in current environment"
+fi
+```
+
+Common variable names are `INTELLIFEND_REQUESTSHIELD_APP_KEY`,
+`REQUESTSHIELD_APP_KEY`, `REQUESTSHIELD_KEY`,
+`INTELLIFEND_REQUESTSHIELD_API_SECRET`, `REQUESTSHIELD_API_SECRET`, and
+`REQUESTSHIELD_SECRET`. A matching non-canonical name is only a credential candidate.
+Confirm that the backend actually reads or maps that variable before treating it as a
+valid RequestShield credential.
+
+If the App Key is known, also confirm server-side credential state without exposing the
+secret:
+
+```bash
+requestshield credentials status <app-key>
+```
+
+A credential that is not present in the current shell is not necessarily missing from
+the deployed backend. It may be injected at runtime by a secret manager, CI/CD system,
+container runtime, Kubernetes Secret, or deployment environment.
+
+Report only what was confirmed:
+
+| Finding | Action |
+| --- | --- |
+| Both credential sources are confirmed | Continue. Never read their values. |
+| A non-canonical variable is found and its backend mapping is confirmed | Report the mapping and continue. |
+| Credentials are provisioned, but the runtime source is unknown | Ask how the deployed backend receives them before editing backend integration code. |
+| No credential source can be confirmed | Report the uncertainty and ask before proceeding. |
+| No credential pair has been provisioned | Ask the user to provision credentials before continuing with backend setup. |
+
+If no pair has been provisioned yet, the user creates it. You may run the read-only
+`requestshield apps list` to see whether an application already exists. Everything that
+mints or changes a secret stays with the user; see **Key and secret management** in
+`SKILL.md`.
+
+## Detect existing integration
+
+Search for existing RequestShield code before install, verify/troubleshoot, or uninstall.
+Use `rg` when available. Use `rg -l` for filename-only discovery.
+
+
+Browser markers:
+
+```bash
+rg -l "data-app-key|data-protect|IntelliFend|X-IntelliFend-Token" \
+  -g "*.html" -g "*.htm" -g "*.js" -g "*.jsx" -g "*.ts" -g "*.tsx" \
+  -g "*.vue" -g "*.svelte" -g "*.astro" \
+  -g "*.erb" -g "*.haml" -g "*.php" -g "*.jinja*" -g "*.j2" -g "*.twig" \
+  -g "*.hbs" -g "*.ejs" -g "*.pug" -g "*.blade.php" \
+  -g "!node_modules/**" -g "!**/skills/**" -g "!**/.requestshield/**" .
+```
+
+The tag often lives in a server-rendered layout rather than a static `.html` — a Django,
+Rails, Laravel, or Thymeleaf base template — so a scan limited to `.html`/`.js` reports
+"not integrated" on a codebase that already has one, and the install then adds a second
+tag. If the app's templates use an extension not listed above, add it before concluding.
+
+Backend markers:
+
+```bash
+rg -l "RequestShieldClient|RequestShieldProtected|intellifend|requestshield" \
+  -g "*.java" -g "*.kt" -g "*.xml" -g "*.yml" -g "*.yaml" \
+  -g "*.gradle" -g "*.gradle.kts" \
+  -g "!**/skills/**" -g "!**/.requestshield/**" .
+```
+
+`rg -l` returns candidate filenames only. Do not follow it with `cat`, an unrestricted
+`sed`, plain `rg -n` without `-o`, or another command that exposes complete matching
+lines or the entire file.
+
+Locate known markers without returning the rest of their lines:
+
+```bash
+rg -n -o \
+  "data-app-key|data-protect|IntelliFend|getToken|X-IntelliFend-Token" \
+  <browser-candidate-file>
+
+rg -n -o \
+  "RequestShieldClient|RequestShieldProtected|verify|isAllowed|intellifend|requestshield" \
+  <backend-candidate-file>
+
+rg -n -o \
+  "(INTELLIFEND_)?REQUESTSHIELD_(APP_KEY|KEY|API_SECRET|SECRET)" \
+  <candidate-configuration-file>
+```
+-o prints only the matched marker or environment-variable name, not the surrounding
+value. Environment-variable names are safe to report; their values are not.
+
+When configuration context is required, inspect it only through a secret-aware parser
+or redacted view that masks sensitive values before stdout reaches the agent. Its output
+may contain the filename, line number, configuration key, environment-variable name,
+App Key when needed to identify the integration, and whether the source is an
+environment reference, secret-manager reference, or literal.
+
+Replace every API Secret, RequestShield token, session value, CSRF value,
+authorization credential, and other credential literal with <redacted>.
+
+If no secret-aware parser or redacted view is available, do not read the candidate
+configuration file verbatim. Ask the user for a sanitized excerpt instead. Switching
+to rg -l and then reading the entire candidate file is not safe.
+
+The exclusions matter when this skill is installed inside the repo being scanned —
+browser and backend reference files contain marker strings and would otherwise read as
+an existing integration.
+
+Report one of:
+
+- **Not integrated**: no browser or backend markers.
+- **Browser only**: tokens may be obtained or attached, but no backend enforcement was
+  found. This looks protected and is not.
+- **Backend only**: enforcement exists, but no page sends a token. In BLOCK mode this can
+  reject legitimate users.
+- **Fully integrated**: browser mode and backend path are both present. Name both.
+
+If a script tag already exists, update it instead of adding a second one. The SDK
+initializes from `document.currentScript`; two tags mean two configurations, and the
+last one to run wins rather than the two merging.
+
+## Contract check
+
+Run this **after** detection and **before** the Gate: detection says what the codebase
+already does, the contract says what the platform currently allows, and the browser-mode
+decision needs both.
+
+```bash
+requestshield contract
+```
+
+It is authoritative for `browser.script_url`, `browser.token_header`,
+`browser.available_modes`, `backend.supported_languages`, and `backend.min_jdk`. Use
+those values verbatim; a stale hardcoded script URL produces a page that loads nothing
+and fails silently.
+
+Treat every array as an **allow-list**. There is no "unavailable" flag, so something is
+unavailable when it is absent — and an absent, empty, or unparseable array is
+unavailable, not permission. If the contract is missing or returns `ok: false`, stop and
+report what the CLI returned.
+
+### Backend consequences — these feed the Gate
+
+- `backend.supported_languages` missing the customer's backend language → **stop.** No
+  backend path exists, and a browser-only install protects nothing.
+- `backend.min_jdk` above the project's Java target → **stop.** The JDK upgrade is the
+  prerequisite; do not fall back to an older SDK version.
+
+### Browser-mode consequences — these decide the mode
+
+Read `browser.available_modes` together with what detection found in the codebase:
+
+| Released modes | Codebase today | Do this |
+| --- | --- | --- |
+| **One mode** | already uses that mode | Keep it. Nothing to change on the browser side. |
+| **One mode** | uses the *other* mode | **This is a finding, not a preference.** The mode in the codebase is not released, so it cannot be relied on. Report it and migrate the client to the released mode. |
+| **One mode** | not integrated | No choice to make. Install that mode, and say which one and why. |
+| **Both modes** | already uses one of them | **Keep the mode already in use.** Change it only for a concrete reason — the transport is one Seamless cannot cover, or the user asks. A mode switch rewrites working call sites and risks leaving an endpoint half-migrated. |
+| **Both modes** | not integrated | A genuine choice. Go to **Choosing the mode** below. |
+| **Neither** | any | **Stop.** No browser mode is released; report the contract output. |
+
+Per-endpoint, not per-repo: a page may legitimately run Seamless on one endpoint and
+Manual on another. Apply the table to the operation being worked on, not to the codebase
+as a whole.
+
+## Gate
+
+The backend path is decided by the backend stack, not by browser preference. Establish
+this before proposing edits. Discovering a backend blocker after the browser half is
+written leaves tokens flowing with nothing enforcing them.
+
+An integration is one backend path plus one browser mode, and they are independent
+choices. A non-Spring-MVC backend does not rule out Seamless mode; it only rules out the
+Spring Boot 3 starter backend path.
+
+Backend path:
+
+| Backend path | Requirement | Reference |
+| --- | --- | --- |
+| **Spring Boot 3 starter** | Spring Boot 3 with Spring MVC, and Java 17+ | `backend-spring-boot.md` |
+| **Java core SDK** | Java 17+ | `backend-java-core.md` |
+
+Browser mode:
+
+| Browser mode | Use when | Reference |
+| --- | --- | --- |
+| **Seamless** | The page reaches the endpoint with `fetch` or async `XMLHttpRequest` | `browser-seamless.md` |
+| **Manual** | The call needs explicit token timing, or a non-header carrier | `browser-manual.md` |
+
+Either browser mode pairs with either backend path. The token travels in
+`X-IntelliFend-Token` regardless. Java below 17 blocks both backend paths, and no amount
+of browser-side work substitutes for backend enforcement.
+
+### Run the check
+
+Find the build file for the module that serves the protected endpoint, not the first one
+in the tree. In a monorepo, locate the route first:
+
+```bash
+find . -maxdepth 4 \( -name pom.xml -o -name "build.gradle*" \) \
+  -not -path "*/node_modules/*" -not -path "*/build/*" -not -path "*/target/*"
+rg -n "/api/register" -g "*.java" -g "*.kt" .
+```
+
+One build file, inspect it. Several, and the route cannot be tied to one of them — or
+several backends could plausibly serve it — **stop and ask which service owns the
+endpoint.** Two backends in a monorepo can differ in both Java version and framework, so
+a guess here invalidates the whole integration rather than needing a tweak.
+
+Use repo-wide build-file scans only for discovery. Do not combine a route found in one
+module with Java or Spring evidence from another module.
+
+#### Java target version
+
+Read the *project's target*, never the machine's JDK.
+
+```bash
+rg -n "maven\.compiler\.(release|source|target)|<release>|<java\.version>" <owning-pom.xml>
+rg -n "languageVersion|sourceCompatibility|jvmToolchain|JavaVersion" <owning-build.gradle*>
+```
+
+- **Maven** — `maven.compiler.release`, or the compiler plugin's `<release>`, is
+  authoritative. Spring Boot's parent POM exposes `<java.version>`, which is the
+  idiomatic place in a Boot app. **Check the parent POM too** when the module inherits;
+  the value is often not in the module's own file.
+- **Gradle** — `java.toolchain.languageVersion = JavaLanguageVersion.of(21)` and
+  `kotlin { jvmToolchain(21) }` are both authoritative, and both easy to miss because
+  they sit inside a block rather than on a property line.
+- **When the build file says nothing** — `.java-version`, `.sdkmanrc`, `.tool-versions`,
+  a `setup-java` step's `java-version` in `.github/workflows/`, or a JDK base image in a
+  `Dockerfile`. These are **hints, not answers**: they describe an environment, which can
+  differ from what the build compiles against. A build file that yields only hints is the
+  ambiguous row below — ask.
+- `java -version` reports the **local** JDK. A repo targeting 11 builds fine on a machine
+  with 21 installed, so it is a last-resort hint and never evidence.
+
+Java below 17 blocks **both** backend paths. Report the version and its source and name
+the upgrade as the prerequisite; do not fall back to an older SDK version or write a
+partial browser-only integration.
+
+#### Spring Boot 3, and separately Spring MVC
+
+Two conditions. Both must hold for the Spring Boot starter.
+
+```bash
+rg -n "spring-boot-starter-parent|spring-boot-dependencies|org\.springframework\.boot" \
+  <owning-pom.xml-or-build.gradle*> | rg "3\.[0-9]+"
+rg -n "spring-boot-starter-web[\"' :<]|spring-boot-starter-webflux|spring-webmvc" \
+  <owning-pom.xml-or-build.gradle*>
+```
+
+Read the parent version, the `spring-boot-dependencies` BOM version, or the Gradle plugin
+version. **Spring Boot 2.x does not qualify** — the starter is a Boot 3 artifact, so a
+2.x app needs the core SDK path even though it is Spring.
+
+Then MVC versus WebFlux — the trap worth checking every time:
+
+- `spring-boot-starter-web` → Spring MVC. The starter is available when the app is also
+  Spring Boot 3 on Java 17+.
+- `spring-boot-starter-webflux` with no `-web` → **not** Spring MVC. The starter protects
+  Spring MVC handler methods, so `@RequestShieldProtected` does not apply. Such an app is
+  Spring Boot 3 on Java 17+ and still needs the Java core SDK — say so explicitly,
+  because "Spring Boot 3, Java 21" reads like a starter green light and quietly is not.
+  Browser mode is unaffected; Seamless remains available when the request transport
+  matches.
+- **Both present** → determine which stack serves the protected route. A
+  `@RestController` returning `Mono`/`Flux`, or a `RouterFunction`, indicates the
+  reactive path. Ask if it stays unclear.
+
+Also not Spring MVC, and therefore the Java core SDK backend path: **Quarkus, Micronaut,
+Dropwizard, Helidon, Ktor, Vert.x, Jakarta EE / JAX-RS on its own, and a plain servlet
+application.**
+
+## Then act on what you found
+
+This decision chooses the backend path only. Pick the browser mode separately from how
+the page issues the protected request.
+
+| Detected | Do this |
+| --- | --- |
+| Java < 17, or no Java backend | Stop before editing. Report the finding and its source; no backend path is available, so nothing can enforce. Name the upgrade as the prerequisite. |
+| Java 17+, no Spring Boot 3 MVC | Use Java core SDK. It is the only backend option; state it rather than asking a fake choice. |
+| Java 17+ and Spring Boot 3 MVC | Both backend paths are viable. Recommend the starter and confirm once. |
+| Ambiguous module, missing build file, version only in environment hints, or unclear MVC/WebFlux ownership | Ask, showing what you found. |
+
+Always report the evidence with file and line references:
+
+```text
+Backend: theair-customer-backend/build.gradle.kts
+  Java 21           - java.toolchain.languageVersion (line 14)
+  Spring Boot 3.2.1 - org.springframework.boot plugin (line 3)
+  Spring MVC        - spring-boot-starter-web (line 20)
+Backend path: Spring Boot 3 starter. Browser mode still depends on released modes and request transport.
+```
+
+Detection is inference from build files. If any line would read "unknown", ask rather
+than assume.
+
+## Choosing the mode
+
+Reach this section only when **Contract check** left a genuine choice: both modes
+released, and this operation not already integrated. If it landed on any other row of
+that table, the mode is already decided — do not re-open it here.
+
+This is the browser half. Backend path does not constrain it. Both browser modes deliver
+the token in `X-IntelliFend-Token`, which either backend path reads.
+
+| | **Seamless** | **Manual** |
+| --- | --- | --- |
+| Browser | `data-protect` lists exact endpoints; the SDK attaches tokens to matching `fetch` and async XHR requests. | `await IntelliFend.getToken()` at each protected call site, attached in application code. |
+| Requires | The request travels by `fetch` or async XHR from page scope. | Nothing beyond the SDK and a supported carrier. |
+| Code touched | One line of HTML. | Every protected call site, plus every retry path. |
+| Backend work | Identical either way: whichever backend path the Gate selected. | Identical either way: whichever backend path the Gate selected. |
+
+Released-mode availability was already settled at **Contract check**. One question is
+left: does the protected request travel by `fetch` or asynchronous `XMLHttpRequest` from
+page scope? Native form POST, `sendBeacon`, WebSocket/EventSource, synchronous XHR,
+`no-cors`, and service-worker-owned requests are not intercepted — read
+`browser-seamless.md` for the full coverage list.
+
+Recommend Seamless when that check passes. It touches one line instead of every call
+site, so there is no missed call site or retry path. If it fails, use Manual and give
+the reason; that is a finding, not a preference.
+
+A given protected operation uses one mode, not both. Different endpoints on the same
+page may use different modes when necessary. Never use two backend verification paths on
+one request; `@RequestShieldProtected` and manual `RequestShieldClient.verify()` both
+consume the token, so the second returns `token_replayed`.