requestshield 0.1.5 → 0.1.7

package/skills/requestshield/references/cli.md

@@ -1,183 +1,107 @@
 # `requestshield` CLI reference
 
-Every RequestShield platform action goes through this CLI. There is no supported way
-to create keys, read the contract, or check traffic by hand-crafting HTTP calls, so if
-a task needs one of these values, run the command rather than guessing.
-
-Commands marked **auth** require a signed-in session (`requestshield signin`). The CLI
-also exposes local commands that do not need platform API access, such as `--help`,
-`--version`, and agent setup. Check once with `auth status` before a multi-step
-platform task instead of discovering it halfway through an edit.
-
-Most commands print JSON shaped `{"ok": true, "data": {...}}`. Parse `data`; treat
-`ok: false` as a hard stop and surface the message rather than continuing with edits.
-
-## Contents
-
-- [General](#general)
-- [Authentication](#authentication)
-- [Key management](#key-management)
-- [Integration contract](#integration-contract)
-- [Applications](#applications)
-- [Credentials](#credentials)
-- [Service and monitoring](#service-and-monitoring)
-- [Billing](#billing)
-- [Agent integration](#agent-integration)
-
-## General
-
-| Command | Purpose |
-| --- | --- |
-| `requestshield --help` | Usage and the full command list. Run this if a command below is rejected — the installed CLI may be older or newer than this file. |
-| `requestshield --version` | Installed CLI version, e.g. `requestshield 1.0.0`. |
-| `requestshield update check` | Latest available version. Use it when behaviour disagrees with this reference. |
-
-## Authentication
-
-```bash
-requestshield signin
-requestshield auth status
+Check `requestshield --version` and `requestshield --help` against this guide.
+An older published version may not contain these commands. Use the CLI for its
+supported application and credential operations; do not invent endpoints for
+unavailable commands.
+
+## Authentication and local commands
+
+```console
+requestshield signin [--no-open]
+requestshield auth status [--json]
+requestshield signout
+requestshield --help
+requestshield --version
 ```
 
-**auth/API.**
-
-`signin` is interactive and stores a session on the machine. **Never try to automate
-it or ask for the user's credentials** — if the user is signed out, tell them to run it
-themselves and wait.
-
-`auth status` returns `{"ok":true,"data":{"authenticated":true,"customer_id":"customer_456"}}`.
-The `customer_id` is useful context to echo back so the user can confirm they are
-operating on the right account before you create or deactivate anything.
-
-## Key management
-
-**The user runs these, not you.** They print the API Secret or change state for a live
-App Key, so hand over the exact command and let them run it in their own terminal. See
-"Key and secret management" in `SKILL.md` for the hand-off and the follow-up
-presence check.
-
-```bash
-requestshield keys create --app-name <name>
-requestshield keys deactive --app-key <app-key>      # or --app-name <name>
-requestshield app key rotate --app-key <app-key>     # or --app-name <name>
-```
-
-`keys create` returns both halves:
-
-```
-App Key: app_123
-Secret Key: rs_sk_xxxxx
-Save this Secret Key now. It will not be shown again.
-```
-
-The Secret Key appears exactly once. Warn the user *before* they run the command that
-they need somewhere to put it, and afterwards point them at the environment variable
-rather than repeating the value. Never ask them to paste the secret back — confirm it
-only by presence. See the secret-handling rules in `SKILL.md`.
-
-`keys deactive` (spelled that way in the CLI) needs at least one of `--app-key` or
-`--app-name`; if both are given, `--app-key` wins. Deactivation stops traffic being
-verified for that key, so name the affected app explicitly when you hand the command
-over and make sure the user means that key.
-
-`app key rotate` issues a new Secret Key for an existing App Key and deactivates the
-previous one. This is the correct response to a leaked or lost secret — it keeps the
-App Key stable, so no browser or config change is needed beyond the new secret. Like
-`keys create`, the user runs it.
-
-## Integration contract
-
-```bash
-requestshield contract
-```
-
-**auth.** The authoritative integration surface — run this before writing any
-integration code. The block below is an **illustration of the shape only**; never read
-values out of it, and in particular do not treat its `available_modes` as the modes your
-customer has:
-
-```json
-{"ok":true,"data":{
-  "contract_version":"2026-08-27",
-  "browser":{"script_url":"https://.../intellifend.js","token_header":"X-IntelliFend-Token",
-             "available_modes":["manual"]},
-  "backend":{"supported_languages":["java"],"min_jdk":17},
-  "release_state":"..."}}
-```
-
-Use `script_url` and `token_header` verbatim. Check `available_modes` before committing
-to seamless or manual — a mode absent from that list is not released, and writing an
-integration against it produces code that will not work. Check `supported_languages`
-before promising a backend integration for a stack that is not listed; the browser side
-alone provides no protection, so an unsupported backend means the honest answer is
-"not yet supported here".
+Sign-in uses the user's browser on the same computer. Let the user complete it;
+never ask for their password, tokens or callback URL. `auth status --json` reads
+local metadata only and does not contact the provider or refresh credentials.
+It returns `profile`, `apiUrl`, `issuer`, `clientId`, `state`, `localOnly: true`
+and applicable `expiresAt`/`scopes`, never tokens or a customer/account identity.
+States are `signed_out`, `valid`, `expired`, `refresh_uncertain`, `config_mismatch`,
+`invalid` and `configuration_error`. Local validity is not provider acceptance.
+Sign-out removes only the selected local session, not the browser session or
+provider grant.
 
 ## Applications
 
-```bash
-requestshield apps list
+```console
+requestshield apps list [--json] [--limit <1-100>] [--cursor <cursor> | --all]
 requestshield apps get <app-key>
+requestshield apps rename <app-key> --name <name> [--idempotency-key <key>]
+requestshield apps enable <app-key> [--idempotency-key <key>]
+requestshield apps disable <app-key> [--idempotency-key <key>] [--yes]
 ```
 
-**auth.** `apps list` returns the applications the current user can access, each with
-`appKey`, `name`, `status`, `createdAt`, and `updatedAt`; JSON output also includes
-`nextCursor`. Use it to resolve a human-supplied app name to a key rather than asking
-the user to retype one.
-
-`apps get <app-key>` returns `app_key`, `name`, and `status`. Status distinguishes a
-key that has never seen traffic (`ready`) from one in normal service (`active`) — which
-is exactly the difference between "the integration is not wired up yet" and "it is
-working", so check it before spending time debugging code.
-
-## Credentials
-
-```bash
-requestshield credentials status <app-key>
-```
-
-**auth.** Returns metadata only — `provisioned`, `active`, `shared` — and never the
-secret value. Use it to answer "is the secret configured?" without anyone having to
-paste a credential. A key that is `provisioned: false` explains backend failures far
-faster than reading code.
-
-## Service and monitoring
-
-```bash
-requestshield server
-requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
-```
-
-**auth.** `server` reports `healthy` or `degraded`. Check it first when an integration
-that was working starts behaving oddly — a degraded platform explains fail-open
-behaviour on the backend without anything being wrong in the customer's code.
-
-`challenge volume` is runtime evidence that the browser/platform half is active. It is
-not proof that the protected backend enforces a blocking decision; the controlled
-negative test in `SKILL.md` provides that evidence. Times are ISO-8601
-(`2026-08-01T00:00:00Z`); `--granularity` takes values such as `hour` or `day`. A
-`challenge_count` of zero after the user has exercised the endpoint means the browser
-half is not firing — that is a browser-side bug, not a backend one, so start with the
-mode's reference file.
-
-## Billing
-
-```bash
-requestshield get billing <app-key>
+These commands require sign-in. Existing-app commands use exact App Keys; names
+are not unique. List defaults to one page. `--all` follows at most 100 pages and
+fails for repeated cursors or unfinished traversal at that bound. It cannot be
+combined with `--cursor`. For name discovery, inspect all necessary pages and
+resolve ambiguity with the user before choosing an App Key.
+
+JSON list output is `{data:Application[],nextCursor}`. Detail and rename output
+is `{data:Application}`. Application has exactly `appKey`, `name`, `status`,
+`createdAt`, `updatedAt`. Status is `pending`, `enabled`, `disabled`, `revoked`
+or `attention_required`; it describes configuration, not traffic or enforcement.
+Pending, attention and disabled states do not expose the exact credential state.
+Disable retains the secret; enable requires an active one.
+
+## Key and secret management
+
+Have the user run commands that print secrets in their own terminal so secret
+values stay out of tool output and transcripts. Give the exact command and
+confirm storage by presence only.
+
+```console
+requestshield keys create --app-name <name> [--idempotency-key <key>]
+requestshield keys rotate <app-key> [--idempotency-key <key>] [--yes]
+requestshield keys reveal <app-key> [--yes]
+requestshield keys revoke <app-key> [--idempotency-key <key>] [--yes]
 ```
 
-**auth.** Current plan and usage for the explicitly selected application. Read-only;
-surface it when the user asks about cost or limits.
-
-## Agent integration
-
-```bash
-requestshield agent setup
-requestshield agent setup --agent claude
-requestshield agent setup --agent codex
+Create makes a new application and initial secret. Rotate preserves the App Key
+and replaces the secret. Reveal retrieves the current active secret; use it to
+recover a lost issuance response. Exposure requires rotation, not reveal.
+Revoke invalidates the current secret. Create, rotate and reveal can display an
+API secret; the CLI never persists it. Store it in backend secret storage.
+
+Create, rename and enable have no prompt. Disable, rotate, revoke and reveal
+require confirmation; `--yes` skips it. These commands can change live state or
+disclose secrets, so ensure the target and action match the user's request.
+
+All mutations except reveal accept an idempotency key. A fresh key is generated
+per invocation when omitted and printed to stderr before dispatch so interrupted
+commands can reuse it; JSON stdout is unchanged. There is no automatic mutation retry. On uncertainty,
+repeat the identical request and key printed in the error within seven days.
+A new key is a new operation. After seven days inspect state before acting.
+Create/rotate replay can have `apiSecret: null`; the CLI directs explicit reveal
+without running it. HTTP 202 and `enabled` do not prove global propagation.
+
+## Agent setup and updates
+
+```console
+requestshield agent setup [--codex | --claude] [--force]
+requestshield update check
 ```
 
-Local setup. Installs this skill for the named agent. With no `--agent`, the CLI detects
-which agent is in use. Run it when the user wants the skill available in another repo or
-for the other agent; it is the supported alternative to copying files by hand. It should
-not require a RequestShield App Key or API Secret, and it must not create, rotate, or
-deactivate customer credentials.
+Agent setup copies the skill to `~/.agents/skills/requestshield` for Codex or
+`~/.claude/skills/requestshield` for Claude. With neither flag, it detects the
+agent or asks if both are available. `--force` replaces an existing installation.
+It does not edit repository `AGENTS.md` or customer application code.
+
+Production update check queries npm and asks before a global installation.
+Explain that target before accepting an update; it does not update a pinned
+invocation or source checkout. Repository-only QAT/STG runners return local
+source-update guidance without registry access or installation.
+
+## Unavailable commands
+
+Integration contract, service health, credential-status metadata, challenge
+volume and billing are not implemented CLI capabilities. `contract`,
+`challenge volume` and `get billing` fail with `COMMAND_UNAVAILABLE` before
+configuration, authentication or network access. `server` and
+`credentials status` are unsupported. Use the published SDK documentation for
+the chosen release and safe browser/backend observations for integration checks.
+Do not infer traffic or enforcement from `apps get` status.

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

@@ -71,12 +71,10 @@ Common variable names are `INTELLIFEND_REQUESTSHIELD_APP_KEY`,
 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>
-```
+If the App Key is known, inspect its aggregate application configuration with
+`requestshield apps get <app-key>`. That status does not prove the exact credential
+state or that the deployed backend has received its secret. The CLI has no separate
+credential-status command; check runtime injection by presence only.
 
 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,
@@ -182,47 +180,22 @@ 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.
+After detecting the current integration, consult the customer Browser SDK and Java
+SDK documentation for the selected release. Confirm the script URL, token header,
+supported browser modes, backend languages and minimum Java version before editing.
+The CLI integration-contract command is unavailable; do not require it as a preflight
+or fabricate its output.
 
-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. |
+The documented backend paths here require Java 17 or newer. The Spring Boot starter
+also requires Spring Boot 3 with Spring MVC; Java core is a separate supported path.
+Do not promise support for another backend language without its release documentation.
+A browser-only installation does not enforce protection.
 
-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.
+Select a browser mode supported by the selected release and the request transport.
+Keep an existing supported mode unless the transport requires a change or the user
+requests one. If release documentation is missing, resolve that evidence before
+making the dependent integration change. A page may use different modes for different
+operations, but each operation uses exactly one mode.
 
 ## Gate
 
@@ -347,7 +320,7 @@ the page issues the protected request.
 Always report the evidence with file and line references:
 
 ```text
-Backend: theair-customer-backend/build.gradle.kts
+Backend: 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)

package/skills/requestshield/references/troubleshooting.md

@@ -4,23 +4,22 @@ Work outward from the request, not from the code. Most reports of "RequestShield
 broken" are one of four things: the browser never attached a token, CORS stripped the
 header, the backend never verified it, or one token was verified twice.
 
-## First three checks
+## First checks
 
-```bash
-requestshield server                          # platform healthy or degraded?
-requestshield apps get <app-key>              # status: ready (no traffic yet) or active?
-requestshield credentials status <app-key>    # provisioned and active?
+```console
+requestshield auth status --json
+requestshield apps get <app-key>
 ```
 
-`status: ready` means the platform has never seen traffic for that key — the integration
-is not wired up yet, so debugging backend enforcement logic is premature. Start at the
-browser.
+Session status is local only. Application status is configuration state, not
+traffic: `pending`, `enabled`, `disabled`, `revoked` or `attention_required`.
+It cannot prove that the browser sent a request or that a deployed backend has the
+current secret. Inspect browser requests and safe backend decision metrics separately.
+The CLI has no service-health or credential-status command.
 
-Run `credentials status` even when the pre-edit Credentials check in
-`integration-planning.md` passed during the install. That check greps the **local
-shell**; it says nothing about what the deployed backend actually receives, and a secret
-can be rotated, or missed by the deploy environment, after it passed. This is the check
-that answers `consume_unauthorized`.
+Confirm runtime secret injection by presence only. A secret absent from the current
+shell may still be supplied by the deployed environment; a rotated secret may not
+have reached that backend yet. Never read or print the value to diagnose this.
 
 ## Reason codes
 
@@ -40,10 +39,10 @@ name.
 | `token_tampered` | Token failed integrity checks | Something modified the value in transit — a proxy rewriting headers, or application code trimming or re-encoding it. Pass the value through unchanged. |
 | `token_expired` | Token too old | The page held a token instead of obtaining a fresh one per request, or a very slow round trip. |
 | `token_replayed` | Already consumed | The same token verified twice: a retry reusing the first token, or two verification paths on one request (`@RequestShieldProtected` plus a manual `verify()`, or a filter plus a controller). |
-| `consume_unauthorized` | Backend credentials rejected | API Secret wrong, rotated, or not injected — check `credentials status` and the environment variable. |
+| `consume_unauthorized` | Backend credentials rejected | API Secret wrong, rotated, or not injected — confirm runtime secret injection and recent rotations without reading the value. |
 | `invalid_request` | Malformed verification request | Usually a mis-set `challenge-server-url`. |
 | `not_found` | Token unknown to the platform | Cross-environment mismatch — a staging page's token verified against production, or the reverse. |
-| `service_unavailable` | Platform unreachable | Check `requestshield server`. See degraded behaviour below. |
+| `service_unavailable` | Platform unreachable | Check backend connectivity and safe health metrics. See degraded behaviour below. |
 
 ## "It blocks everything"
 
@@ -61,7 +60,7 @@ cheap and rules out a whole class:
    strips it before it ever leaves.
 4. **Header present but empty** → the SDK ran and could not obtain a token. Check the CSP
    includes `worker-src 'self' blob:` and that `connect-src` allows the challenge host,
-   then check `requestshield server`. (In Manual mode an empty token means the header
+   then check connectivity and safe backend health observations. (In Manual mode an empty token means the header
    should be omitted, not sent empty — see `browser-manual.md`.)
 5. **Header present and populated** → backend half. Compare the App Key on both sides
    character for character, then confirm the secret is actually injected at runtime.
@@ -89,20 +88,16 @@ platform outage cannot take down a customer's checkout flow.
 
 Communicate the consequence clearly: during a degraded window, traffic passes without
 real verification. Log the degraded rate as its own metric so it is visible, and check
-`requestshield server` when it rises. Never "fix" a degraded result by overriding
+backend connectivity and service health through established monitoring when it rises. Never "fix" a degraded result by overriding
 `isAllowed()` — that converts a platform incident into a customer-facing outage.
 
-## Confirming traffic reaches the platform
-
-```bash
-requestshield challenge volume <app-key> --from 2026-08-01T00:00:00Z \
-  --to 2026-08-27T23:59:59Z --granularity day
-```
+## Confirming traffic and enforcement
 
-Challenge volume is runtime evidence that the browser/platform half is active. It does
-not prove that the backend enforces a blocking decision. Report static correctness,
-platform traffic, and backend enforcement separately. Use the controlled negative test
-in `SKILL.md` to prove enforcement.
+Use browser network observations and existing safe backend metrics in an authorized
+environment. Do not record raw tokens or secrets. CLI challenge-volume analytics are
+unavailable; application status is not a traffic measurement. Report static correctness,
+observed requests and backend enforcement separately. Use the controlled negative
+test in `SKILL.md` to demonstrate enforcement.
 
 ## Secret exposure
 
@@ -110,9 +105,10 @@ If the API Secret appears in a repo, a log, a build artifact, or a chat transcri
 rotate it — deleting the line does not un-expose it:
 
 ```bash
-requestshield app key rotate --app-key <app-key>
+requestshield keys rotate <app-key>
 ```
 
 The App Key is unchanged, so no browser edit is needed. Deploy the new secret to backend
-secret storage; the previous one is deactivated automatically. Warn the user that the new
-secret is displayed once.
+secret storage. Rotation replaces the previous secret, but publication is asynchronous.
+Warn the user that the new secret is displayed and must stay out of transcripts. A lost
+response can be recovered with explicit reveal; an exposed secret requires rotation.