requestshield 0.0.0-stage → 1.1.0-qat.281

package/README.md

@@ -1,3 +1,296 @@
-# Temporary Holding Version
+# RequestShield CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Manage RequestShield applications and secrets, inspect account billing estimates,
+discover SDK integration settings, and install integration guidance for Codex or Claude.
+
+Requires Node.js 22.13 or newer and npm. Run `npx requestshield --version` to see
+the CLI version.
+
+## Install and get started
+
+```console
+npx requestshield login
+npx requestshield app list
+npx requestshield contract
+npx requestshield agent setup --codex
+```
+
+To install globally, run `npm install --global requestshield`, then use
+`requestshield` in place of `npx requestshield`.
+
+Use an existing App Key or create an application with
+`requestshield app create "Checkout API"`. Store its returned API Secret in your
+backend secret manager. Never put API Secrets or tokens in frontend code, URLs,
+logs, command arguments or committed files.
+
+To run a pinned CLI version without a global installation:
+
+```console
+npx requestshield@1.0.0 --help
+```
+
+## Commands
+
+Run `requestshield --help`, `requestshield app --help` or
+`requestshield app create --help` for help at each level. Names containing spaces
+must be quoted. Commands for existing applications require an exact App Key.
+
+| Command after `requestshield` | Purpose |
+| --- | --- |
+| `--help`, `-h` | Show help. |
+| `--version`, `-v` | Show the CLI version. |
+| `login [--no-open]` | Sign in through your browser. |
+| `logout` | Remove your saved local session. |
+| `auth status` | Inspect local session status. |
+| `app create <name>` | Create an application and its initial secret. |
+| `app list` | List applications. |
+| `app get <app-key>` | Inspect an application. |
+| `app rename <app-key> <name>` | Rename an application. |
+| `app enable <app-key>` | Enable an application. |
+| `app disable <app-key>` | Disable an application while keeping its secret. |
+| `secret rotate <app-key>` | Replace the current secret. |
+| `secret reveal <app-key>` | Retrieve the current active secret. |
+| `secret revoke <app-key>` | Revoke the current secret. |
+| `agent setup [--codex \| --claude] [--force]` | Install integration guidance. |
+| `agent status [--codex \| --claude]` | Inspect installed Skill files. |
+| `update check` | Check for a newer CLI version. |
+| `update apply [--yes]` | Install the available version globally. |
+| `contract` | Read the SDK integration contract. |
+| `service status` | Check service availability. |
+| `usage <app-key>` | Read approximate recent request counts. |
+| `billing get <app-key>` | Read account usage, quota and estimated cost. |
+
+Use `login`, `logout`, `app`, `secret` and `contract` exactly as shown;
+`signin`, `signout`, plural group names and `contract get` are not supported.
+
+All result commands support `--json`. Stdout contains one JSON document;
+progress, prompts and warnings go to stderr. Help and version are text.
+Most results use `{data: ...}`; `auth status` returns its local status directly.
+Errors use `{error: {code, message}}`. `--json` does not skip confirmation.
+Redirected output is plain text; `NO_COLOR` or `TERM=dumb` disables colors and icons.
+
+## Sign in and inspect your session
+
+`requestshield login` opens your browser. Sign in, verify your email if needed,
+and approve the displayed permissions. The browser must be on the same computer
+as the CLI. With `--no-open`, open the printed URL yourself. Press Ctrl+C to cancel.
+
+The CLI saves your session securely and renews it when needed. Follow any prompt
+to sign in again; never send passwords, tokens or callback URLs to support.
+
+```console
+requestshield auth status --json
+requestshield logout
+```
+
+Status is a local check and does not contact RequestShield. JSON includes `state`
+and `localOnly: true`, plus `expiresAt` and `scopes` when applicable. States are
+`signed_out`, `valid`, `expired`, `refresh_uncertain`, `config_mismatch`, `invalid`
+and `configuration_error`. Local `valid` status does not confirm online access.
+Logout removes your saved CLI session; your browser stays signed in.
+
+## Applications and secrets
+
+Create, rename and enable do not prompt. Disable, rotate, revoke and reveal
+require confirmation; pass `--yes` only when you intend that action.
+
+Rotate keeps the App Key and replaces its secret. Reveal retrieves the current
+secret. Revoke invalidates the current secret. Disable keeps the secret; enable
+requires an active secret. Without `--output`, create, rotate and reveal display
+the API Secret without saving it. Store it directly in protected backend configuration.
+
+Mutations except reveal accept `--idempotency-key <key>`. The CLI generates and
+prints a key to stderr before sending a request. If its result is uncertain,
+repeat the identical command and arguments with that same key within seven days.
+A new key starts a new operation. After seven days, inspect the application first.
+A repeated create or rotate can return `apiSecret: null`; retrieve it separately
+with `secret reveal` if needed. Requests are never retried automatically.
+
+Changes may take a moment. Check `requestshield app get <app-key>` before relying
+on a change. Application status describes your settings, not traffic or proof
+that an endpoint is protected.
+
+| Status | Meaning |
+| --- | --- |
+| `pending` | Your latest changes are being applied. |
+| `enabled` | The application and its secret are enabled. |
+| `disabled` | The application is disabled. |
+| `revoked` | The application's secret has been revoked. |
+| `attention_required` | Changes could not be confirmed. Retry later or contact support. |
+
+`app list` accepts `--limit <1-100>`, `--cursor <cursor>` or `--all`. `--all`
+cannot be combined with `--cursor`. JSON list output is
+`{data: Application[], nextCursor}`; detail and rename return `{data: Application}`.
+Each Application contains `appKey`, `name`, `status`, `createdAt` and `updatedAt`.
+
+### Save credentials to a file
+
+Use `--output <file>` on create, reveal or rotate to save credentials without
+printing the secret, including with `--json`:
+
+```console
+requestshield app create "Checkout API" --output ../requestshield-secrets/checkout.env --json
+requestshield secret reveal YOUR_APP_KEY --output ../requestshield-secrets/recovered.env --yes
+requestshield secret rotate YOUR_APP_KEY --output ../requestshield-secrets/rotated.env --yes
+```
+
+The UTF-8 ENV file contains `INTELLIFEND_REQUESTSHIELD_APP_KEY` and
+`INTELLIFEND_REQUESTSHIELD_API_SECRET`. The CLI restricts file access to the current
+operating-system user. Keep the file outside source control. Configure your backend
+launcher or container to load it; saving the file does not configure the backend.
+An existing backend process must receive the updated configuration after rotation.
+
+Supply a new file, using an absolute path or a path relative to your current
+directory. Missing directories are created. Existing files are never overwritten;
+directories, symbolic links, junctions and `-` for stdout are not supported destinations.
+Reveal and rotate still require confirmation or `--yes`.
+
+JSON returns `{data: {appKey, outputPath, secretStored: true}}`; create and rotate
+also return the application's `status`. `outputPath` is absolute. Neither the
+JSON nor the text result contains the API Secret when `--output` is used.
+
+| Failure | Code | Exit | Recovery |
+| --- | --- | --- | --- |
+| Destination exists | `OUTPUT_EXISTS` | 2 | Choose a new file. No application or secret request was sent. |
+| File cannot be prepared or saved | `OUTPUT_WRITE_FAILED` | 7 | Follow the message: fix the path or permissions before retrying; if the request succeeded, use `secret reveal APP_KEY --output NEW_FILE`. |
+| Replayed create/rotate returned no secret | `OUTPUT_SECRET_UNAVAILABLE` | 7 | Use `secret reveal APP_KEY --output NEW_FILE`; do not create or rotate again. |
+
+On failure the CLI attempts to remove its unfinished file and warns if it cannot.
+An interrupted process can leave an unfinished file. Use a new output path when
+retrying, keeping the same application arguments and idempotency key for an
+uncertain mutation. Changing only `--output` does not change the API request.
+
+## SDK integration contract
+
+```console
+requestshield contract
+requestshield contract --json
+```
+
+This public read requires no login and changes no local files. The schema-2 JSON
+has a `{data: ...}` envelope containing `schemaVersion: 2`, `contractVersion`,
+`services`, `browser`, `backend` and `documentation`.
+
+- `data.services.challengeUrl`: configure this URL in both SDKs.
+- `data.browser.scriptUrlVersion`: immutable Browser SDK script URL.
+- `data.browser.scriptUrlLatest`: script URL that follows Browser SDK updates.
+- `data.browser.sdkVersion` and `data.browser.integrity`: version and SHA-384 SRI
+  for the versioned script only. Latest can serve a different release.
+- `data.browser.availableModes`: supported frontend modes for the pinned release at
+  `scriptUrlVersion`. Check current public documentation for latest capabilities.
+- `data.browser.tokenHeader` and `cspAdditions`: shared integration settings.
+  Merge CSP additions into your existing policy; they cover both script choices, including `'wasm-unsafe-eval'` and a `blob:` worker source.
+- `data.backend`: SDK version, minimum JDK, Maven repository and core/Spring Boot
+  3 MVC starter coordinates.
+- `data.documentation`: Browser SDK, Java SDK, domains/CSP and optional release notes.
+
+Frontend and backend each choose Seamless or Manual independently. For the backend,
+Seamless uses the Spring Boot 3 MVC starter; Manual uses Java core directly.
+The text output labels those backend modes alongside their Maven coordinates.
+For a new integration, prefer Seamless on both sides when supported, otherwise
+Manual on both sides. Mixed pairs are supported; keep an existing integration or
+an explicit supported choice. `BLOCK`/`MONITOR` are separate enforcement policies.
+
+Choose versioned when you need controlled upgrades or SRI. Use latest to receive
+updates automatically. Use the URLs exactly as returned. Attach the supplied
+integrity value only to `scriptUrlVersion`; do not attach it to `scriptUrlLatest`.
+The former `browser.scriptUrl` and schema 1 are no longer supported.
+
+| Failure | Code | Exit |
+| --- | --- | --- |
+| Contract unavailable (HTTP 404) | `CONTRACT_NOT_PUBLISHED` | 1 |
+| Network, timeout or HTTP failure | `CONTRACT_FETCH_FAILED` | 1 |
+| Invalid or unsupported contract | `CONTRACT_INVALID` | 1 |
+| CLI integration settings unavailable | `CONTRACT_CONFIG_INVALID` | 2 |
+
+For an unsupported schema, update the CLI and retry. If the problem continues,
+contact support. Contract metadata does not confirm service availability or
+application protection.
+
+## Service status and usage
+
+```console
+requestshield service status --json
+requestshield usage pk_example --json
+requestshield usage pk_example --from 2026-09-17T08:00:00Z --to 2026-09-17T09:00:00Z
+```
+
+Service status checks Management API and Challenge Service without signing in.
+Each check has a five-second deadline. JSON returns `{data: {checkedAt, checks}}`;
+each check contains `service`, `url`, `status`, `latencyMs`, nullable `httpStatus`
+and nullable `reason`. Reasons are `timeout`, `network_error`, `http_error` and
+`invalid_response`. Exit 0 means both passed; exit 1 includes a failed-check report.
+`SERVICE_CONFIG_INVALID` exits 2. Test a protected request separately to verify
+your application integration.
+
+Usage requires sign-in and an owned App Key. It defaults to the last 24 hours;
+provide both `--from` and `--to` for a range within the last 90 days. Use UTC
+times ending in `Z`, with seconds and optionally up to three fractional digits.
+The end must follow the start and cannot be in the future. The range includes
+requests completed at the start and excludes requests completed at the end.
+
+Counts are approximate monitoring data, not billing totals. Data may be delayed
+or incomplete. Retries count separately; successful challenge verifications are
+attempts, not unique challenges. Zero means no recorded requests, not proof of no
+traffic. A failed query returns an error. The report preserves your requested
+range and includes only available recorded activity, even if collection began
+after the start. The 90-day query window does not guarantee complete history.
+
+Usage reports cover API v2 requests only. API v1 activity is not included.
+If your browser and backend use different API versions, the report may show
+only part of your application's activity.
+
+Usage JSON includes `appKey`, `from`, `to`, `approximate: true` and `operations`.
+The operation keys are `challenge_create`, `challenge_verify` and `token_consume`,
+each containing `requests`, `success`, `rejected` and `error` counts.
+
+## Billing
+
+```console
+requestshield billing get pk_example
+requestshield billing get pk_example --json
+```
+
+Sign in and supply an App Key you own. The report covers the **whole account**,
+including its applications; it does not allocate costs to the requested app.
+It shows the current plan and subscription billing period, included allowance,
+approximate usage, remaining quota, overage and estimated cost in its currency.
+The CLI reads billing estimates directly; `usage` monitoring totals are separate.
+
+Billing counts authenticated API v2 token verification requests, including
+rejected requests and retries. API v1 activity, unauthenticated requests and
+service errors are excluded.
+
+Express includes 10,000 calls per period at no charge. Pro includes 100,000 calls
+for USD 100 per period, plus USD 0.001 per additional call. The estimate includes
+the period's base price and observed overage before taxes; it is not a final
+invoice or a forecast of the rest of the period. Exceeding the allowance does not
+automatically block requests.
+
+JSON returns `{data: ...}` with `appKey`, `scope: "account"`, subscription
+`status`, `plan` (`free` for Express, `pro`, or `null`), `billingPeriod`,
+`includedAllowance`, `usage`, `remainingQuota`, `overage`,
+`unit: "token_verification_requests"`, `approximate: true`, `reportedAt`,
+`usageThrough` and `estimatedCost`. `billingPeriod` contains UTC `start` and `end`.
+`estimatedCost` contains `currency` and integer `baseAmountMinor`,
+`overageAmountMinor` and `totalAmountMinor`; USD minor units are cents.
+
+Absent or inapplicable data is `null`, displayed as unavailable, never zero.
+Without a current subscription, the plan, period, quantities and cost can be
+unavailable. Failed billing reads return an error. `reportedAt` is the report
+time and `usageThrough` is the usage query cutoff, not a guarantee that all
+activity has arrived. Counts may be delayed or incomplete. Zero means no
+billable requests were recorded for the queried interval.
+
+## Agent setup and updates
+
+`agent setup` installs the RequestShield Skill to `~/.agents/skills/requestshield`
+for Codex or `~/.claude/skills/requestshield` for Claude. Select an agent with
+`--codex` or `--claude`; `--force` replaces its existing Skill. Start a new agent
+task after installing. `agent status` checks files for both agents by default and
+reports `installed`, `missing` or `invalid`; it does not prove the agent loaded them.
+
+`update check` reads the npm registry without installing. `update apply` asks before
+installing the exact available version globally with npm; `--yes` confirms it.
+A global update does not change a pinned `npx` invocation. Installations without
+automatic update support return `outcome: "unavailable"` and make no changes.

package/config/.env.qat

@@ -0,0 +1,7 @@
+# Public QAT settings for the QAT npm release and source runner. Never add secrets.
+API_URL=https://management-api-qat.intellifend.ai
+CHALLENGE_URL=https://challenge-dev.intellifend.ai
+DOCS_URL=https://docs-qat.intellifend.ai
+OAUTH_ISSUER=https://incongruous-cherry-0283.customers.stytch.dev
+OAUTH_AUTHORIZATION_ISSUER=stytch.com/project-test-968146e2-6f34-4936-9d1c-a7e966813c70
+OAUTH_CLIENT_ID=connected-app-test-5ff62ca4-c0eb-48c3-84e5-06ae8f669998

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "requestshield",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0-qat.281",
+  "description": "Customer CLI for IntelliFend RequestShield.",
+  "type": "module",
+  "bin": {
+    "requestshield": "src/main.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "qat"
+  },
+  "files": [
+    "src/",
+    "config/.env.qat",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "license": "UNLICENSED",
+  "requestshield": {
+    "profile": "qat"
+  }
+}

package/skills/requestshield/SKILL.md

@@ -0,0 +1,240 @@
+---
+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
+
+The browser transports a short-lived token; the backend verifies it before the
+protected business operation runs. Configure both halves independently, land them in
+the same change, and verify both. Protect the mutation itself, not a read-only route
+in front of it.
+
+## Before touching integration files
+
+Run `requestshield --version`. If unavailable, explain that CLI operations need a
+compatible installation; do not invent replacement HTTP calls. Read
+[the CLI reference](references/cli.md) before invoking commands.
+
+- Run relevant read-only commands automatically.
+- Explain the exact action and target and obtain fresh confirmation under
+  **Interactive questions** before `login`, `logout`, `app create`, `app enable`,
+  `app disable`, `secret rotate`, `secret reveal`, or `secret revoke`, even when requested.
+- A direct request for the exact `app rename`, `agent setup`, or `update apply` action
+  and target needs no additional confirmation; use `--yes` where needed. Read-only
+  requests never authorize writes.
+
+Endpoint/mode selection, enforcement-mode changes, shared-environment tests, and
+uninstall scope retain their separate approval requirements.
+
+### Interactive questions
+
+For choices and confirmations, use the host's native interactive-question tool.
+Discover supported options first; use single-select for one choice, multi-select for
+several, and exactly **Yes**/**No** for binary confirmation. If multi-select is
+unavailable, ask an interactive Yes/No for each candidate. Do not request typed
+selections in chat. If no permitted tool is available, explain and pause that step.
+
+Keep pending questions active and continue independent authorized work. When supported,
+wait in 60-second check-in intervals; timeouts, defaults, highlighted options, and
+silence are not answers. Reissue a question only if the host reports it expired.
+Resume dependent work automatically after an explicit answer.
+
+## Classify the request
+
+Match the user’s intent and follow its complete sequence and linked sections.
+
+| Intent | Sounds like | Do this |
+| --- | --- | --- |
+| **General information** | "what is RequestShield", "what is Seamless mode", "Seamless or Manual", "what version", "how much does it cost", "what quotas or limits apply" | Answer from **General information** below. Use read-only sources only; do not require login or run account-changing commands. |
+| **Integration contract** | "which SDK", "SDK URL", "integration manifest" | Run `requestshield contract --json` without login. Use the returned release metadata and documentation links; it reports no account or service-health information. |
+| **Authentication** | "how can I log in", "sign me in", "sign me out" | For how-to questions, explain the CLI commands without running them. For an explicit sign-in request, follow the [sign-in steps](references/integration-planning.md#sign-in). For an explicit sign-out request, explain the action, obtain confirmation under **Interactive questions**, then run `requestshield logout`. |
+| **Key / secret management** | "create an app key", "I need an API Secret", "rotate the secret", "deactivate a key" | Follow **Key and secret management** below for target selection, confirmation, execution, and result handling. |
+| **Install** | "add RequestShield", "protect /api/register" | Follow **Installing** below (which runs the planning flow in `references/integration-planning.md`) → **Static install verification**. Do not provision credentials or run runtime or negative tests as part of Install. |
+| **Uninstall** | "remove it", "roll it back" | Follow `references/integration-planning.md` (**Detect existing integration** only) → **Uninstalling** → rerun **Detect existing integration** as the static uninstall check. |
+| **Change mode** | "switch to Seamless", "use the annotation instead of `verify()`" | Follow `references/integration-planning.md` **Detect existing integration** → **Contract check** → **Gate** → **Choosing the modes** (the request is the explicit preference for that layer only) → remove the old path and add the new one for that layer in the same change → static **Verifying**. |
+| **Verify / troubleshoot** | "is it set up right?", "why is it not blocking?", a reason code | `references/integration-planning.md` (**Detect existing integration** only) → **Verifying** (static-only; do not exercise the endpoint). For a reason code, also read `references/troubleshooting.md`. |
+| **Test / enforcement test** | "test RequestShield", "is RequestShield working?", "check if it actually blocks", "test protection on this endpoint" | `references/integration-planning.md` (**Detect existing integration** only) → static **Verifying** → control request → **The negative test**. |
+| **Usage** | "how much traffic", "how many challenges", "request volume" | First complete the [sign-in steps](references/integration-planning.md#sign-in). Run `requestshield usage <app-key> --json` for the exact requested app. See [Recent usage](references/cli.md#recent-usage) for query limits and interpretation. |
+| **Billing** | "am I being charged", "what plan", "what are my limits" | For account-specific billing, first complete the [sign-in steps](references/integration-planning.md#sign-in). Run `requestshield billing get <app-key> --json` for an owned App Key. Follow [Account billing](references/cli.md#account-billing): preserve account-wide scope, approximate quantities, unavailable values and the estimate-versus-invoice distinction. |
+| **Service health** | "is the service up", "is it degraded" | Run `requestshield service status --json` without login or an App Key. Interpret results using [Service liveness](references/cli.md#service-liveness). |
+| **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`. Follow [Agent setup and updates](references/cli.md#agent-setup-and-updates). |
+| **Anything else** | | Look the command up in `references/cli.md`. If it is not there, run `requestshield --help` rather than guessing at a flag. |
+
+### General information
+
+Use the matching browser reference for concepts and modes, `requestshield --version`
+for CLI version, `update check` for available updates, and `contract --json` plus its
+release documentation for SDK capabilities. Apply updates only when requested.
+
+Use verified current official sources for pricing, plans, and quotas. Never infer
+allowances or remaining quota from usage, app status, or SDK limitations. If unavailable,
+say so and direct the user to their billing/support channel. Clarify whether “quota”
+means plan allowance, usage, API rate limits, or technical limitations.
+
+## Key and secret management
+
+1. Before any key or secret management action, complete the
+   [sign-in steps](references/integration-planning.md#sign-in). For creation, confirm the
+   application name. For existing applications, resolve the exact App Key with
+   `app list --all --json` and `app get <app-key> --json`; names are not unique.
+2. Follow [Key and secret management in the CLI reference](references/cli.md#key-and-secret-management)
+   for confirmation, execution, delivery, sanitized results, and idempotent retries.
+   Create uses a new private file via `--output`; rotate/reveal use a private
+   user-visible terminal whose output is unavailable to the agent. Never read either
+   destination. Credential delivery does not configure or activate the backend.
+3. Recommend the deployment's secret manager or protected runtime environment settings,
+   using `INTELLIFEND_REQUESTSHIELD_APP_KEY` and `INTELLIFEND_REQUESTSHIELD_API_SECRET`.
+   Supply the same public App Key to `data-app-key` or `IntelliFend.init({ appKey })`
+   through the browser framework's public configuration; for Vite, recommend
+   `VITE_INTELLIFEND_REQUESTSHIELD_APP_KEY`. Configure the runtime only when requested.
+
+The API Secret stays backend-only. Never put it in browser code, client-visible
+responses, source files, committed ENV/CI files, image layers, logs, artifacts, or chat.
+Reveal recovers a lost issuance response; exposure requires approved rotation. Deleting
+an exposed value does not make the secret safe again.
+
+## Installing
+
+If the user has not already selected an explicit, intentionally narrow endpoint set,
+follow [Discover and select protected endpoints](references/integration-planning.md#discover-and-select-protected-endpoints)
+before continuing.
+
+Once the selected endpoint set is explicit, run the remaining planning flow before
+writing integration code: **Detect existing integration** →
+**Contract check** → **Gate** → **Then act on what you found** → **Choosing the modes**.
+
+1. **Browser side** — follow the selected mode's reference:
+   [Seamless](references/browser-seamless.md) or [Manual](references/browser-manual.md).
+2. **Backend side** — follow the selected path's reference:
+   [Spring Boot 3 starter](references/backend-spring-boot.md) or
+   [Java core SDK](references/backend-java-core.md). Enforce before the mutation.
+3. **Static install verification** — run **Verifying**, then focused builds/tests
+   without starting a credential-dependent runtime. Fix failures before finishing.
+
+Install ends here. Report source checks and build/test results separately; runtime
+activation and enforcement remain unverified. Credential configuration, runtime
+requests, and negative testing require a separate request.
+
+## Verifying
+
+Run **Detect existing integration** in `references/integration-planning.md`.
+Inspect the existing modes; do not reopen mode selection.
+
+Check:
+- One SDK initialization before protected requests; report App Key bindings or placeholders.
+- Seamless matches exact origins and configured paths, including whole-segment `:name`
+  parameters; Manual obtains a fresh token for every request/retry.
+- One backend verification path gates each mutation; configuration uses environment references.
+- CORS/CSP support the selected transport.
+- No tokens or secrets in logs, URLs, analytics, or error reporting.
+
+Run relevant static checks and report build/test results separately.
+Verify does not exercise endpoints; runtime enforcement remains unverified.
+
+If a check fails, report it, follow [Troubleshooting](references/troubleshooting.md),
+apply one correction at a time, and rerun Verify. Changes to `MONITOR`/`BLOCK`
+require explicit approval.
+
+### The negative test — the only proof of enforcement
+
+Run only after static Verify passes, using the existing runtime configuration.
+Confirm under **Interactive questions** before testing a shared environment.
+Use an authorized local/staging environment or a reversible test operation;
+do not test production casually or invent data that creates a real account.
+
+1. **Establish enforcement and observability.**
+   For Spring Boot, confirm effective `BLOCK`, including method overrides.
+   For Java core, confirm `!result.isAllowed()` rejects before the mutation.
+   See the corresponding backend reference.
+
+   Observe decisions for the backend instance and App Key under test:
+   - Spring Boot: `intellifend.requestshield.requests`, distinguishing
+     `outcome=allowed, reason=ok` from
+     `outcome=degraded, reason=service_unavailable`.
+   - Java core: safe metrics/logs from `isDegraded()` and `getReason().getCode()`.
+
+   Service health alone is insufficient. Never record tokens, API Secrets,
+   session values, or CSRF values.
+
+2. **Send a control request** through the integrated browser path with a fresh token.
+   Confirm success, the intended mutation, and a non-degraded `ok` backend decision.
+   Use a new token for every attempt. If the control fails, stop before the
+   tokenless comparison and follow [Troubleshooting](references/troubleshooting.md);
+   do not start credential management.
+
+3. **Repeat without the token.** Preserve valid authentication, session, CSRF,
+   route, method, body, and other headers; remove only `X-IntelliFend-Token`.
+   Use a client that bypasses the Browser SDK so it cannot attach another token.
+
+4. **Evaluate the result.**
+   - Spring Boot: HTTP 403, `CHALLENGE_FAILED`, reason `missing_token`,
+     and no handler side effect.
+   - Java core: rejection from `!result.isAllowed()` corresponding to
+     `missing_token`, before any mutation.
+   - Unrelated or unattributable 4xx: inconclusive.
+   - Degraded results, or unavailable degradation evidence: inconclusive.
+     Follow [degraded-result guidance](references/troubleshooting.md#degraded-results-are-allowed-by-design)
+     and repeat with a fresh control after recovery.
+   - A 2xx or mutation confirms a bypass only when degradation is ruled out
+     for that request; follow [Troubleshooting](references/troubleshooting.md).
+
+Report static checks, browser transport, and backend enforcement separately.
+Usage counts and application status are not enforcement proof.
+
+## Uninstalling
+
+Run **Detect existing integration** in `references/integration-planning.md`.
+Present protected operations by exact method/path and current state, without priority.
+Use **Present a multi-select and wait** to obtain the selected scope, then confirm
+the exact removal list under **Interactive questions** before editing.
+
+- **All operations selected:** remove RequestShield scripts, token calls/headers,
+  backend dependencies and enforcement, configuration references, and its CSP/CORS entries.
+- **Some operations selected:** remove only their browser and backend protection.
+  Preserve shared setup and protection for remaining operations.
+
+Preserve unrelated code, request logic, and configuration. Rerun detection over the
+same scope. Inspect remaining candidates using the reference's redacted method;
+remove confirmed integration-owned leftovers and repeat detection.
+
+Complete only when selected operations have no active integration markers and
+remaining operations retain both protection halves. Report static detection and
+build/test results separately; source removal does not prove deployed removal.
+
+Application disable or secret revocation is a separate credential-management action
+requiring its own approval.
+
+## Non-negotiables
+
+- Browser code must not interpret a token or decide to allow, block, or retry around
+  enforcement. Choose frontend/backend modes independently; supported mixed pairs work.
+- Use one fresh token per request, including retries, and forward non-empty tokens
+  unchanged. Do not trim, re-encode, inspect, cache, persist, log, or put them in URLs.
+  Reuse returns `token_replayed`. If Manual `getToken()` returns empty, omit the header
+  and let the backend apply its configured policy.
+- Verify once per request: never combine `@RequestShieldProtected` and a manual
+  `RequestShieldClient.verify()` on the same handler.
+- Explain and obtain explicit approval under **Interactive questions** before changing
+  effective `MONITOR`/`BLOCK` mode, including global or method overrides. A diagnosis,
+  recommendation, default, or silence is not approval.
+- Follow **Key and secret management** for secret handling and credential actions.
+
+## Reference files
+
+| File | Read it when |
+| --- | --- |
+| `references/cli.md` | Any CLI invocation — exact syntax, output shape, auth requirements |
+| `references/integration-planning.md` | Sign-in, ranked endpoint discovery and multi-selection, existing-integration detection, contract check, backend gating, 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 Manual on a supported Java 17+ backend — the explicit verify() path |
+| `references/troubleshooting.md` | A block, a degraded result, or a reason code to explain |
+
+## For agent setup
+
+Follow [Agent setup and updates](references/cli.md#agent-setup-and-updates).
+Setup installs guidance only; it does not create credentials or change customer code.
+`assets/AGENTS.codex.md` is an optional template for a separately requested repository
+instruction change.