requestshield 0.1.5 → 0.1.7

package/README.md

@@ -1,8 +1,8 @@
 # RequestShield CLI
 
 Customer-facing CLI for IntelliFend RequestShield. It allows customers to sign
-in, rotate application credentials, install the RequestShield Skill for Codex
-or Claude, and update an npm-installed CLI.
+in, manage applications and their credentials, install the RequestShield Skill
+for Codex or Claude, and update an npm-installed CLI.
 
 Current package version: `0.1.5`.
 
@@ -12,124 +12,211 @@ Current package version: `0.1.5`.
 - A RequestShield customer management API.
 - npm for local development and publishing.
 
-The management API defaults to `https://api.intellifend.ai`. Set
-`REQUESTSHIELD_API_URL` to use a different management API during development.
+The public npm package installs only `requestshield`, using production
+configuration. QAT and STG runners are available only in this repository:
+
+| Command | Environment | Configuration file |
+| --- | --- | --- |
+| `requestshield` | PROD | `config/.env.prod`; API URL is `https://api.intellifend.ai`, while production OAuth values remain unconfigured. |
+| `npx requestshield-qat <args>` from `requestshield-cli/dev/` | QAT | `config/.env.qat`; includes the public Stytch Test issuer/client ID and Management API QAT URL. |
+| `npx requestshield-stg <args>` from `requestshield-cli/dev/` | STG | `config/.env.stg`; requires the actual STG API and OAuth values before use. |
+
+The private `dev/package.json` resolves these `npx` commands to this checkout's
+wrappers without a separate install, link or publish step. They are local source
+runners, not packages fetched from the registry. From the parent
+`requestshield-cli/` directory, use `npx --offline --prefix ./dev requestshield-qat <args>`
+(or `requestshield-stg`). The matching `npm run requestshield-qat -- <args>` and
+`npm run requestshield-stg -- <args>` scripts are alternatives. A bare QAT/STG
+`npx` command from the parent directory does not select the private child package
+and may search dependencies or the registry instead.
+
+Each runner reads its package-relative file directly with Node.js `parseEnv`.
+It does not load a `.env` from the current working directory or read OAuth/API
+settings from `process.env`. Shell variables cannot switch the selected profile
+or override its configuration. Missing STG/PROD values fail explicitly and never
+fall back to QAT.
+
+These files contain only public product settings: `OAUTH_ISSUER`,
+`OAUTH_CLIENT_ID`, `API_URL` and optional `OAUTH_AUTHORIZATION_ISSUER`. They must never contain
+access tokens, refresh tokens, client secrets or application API secrets. Release
+maintainers must populate the production public settings before publishing a
+working production sign-in flow. The npm package includes only `.env.prod`;
+QAT/STG files and the private development package are excluded.
 
 ## Implemented commands
 
+Examples use the production command. From `requestshield-cli/`, substitute
+`npx --offline --prefix ./dev requestshield-qat` or `requestshield-stg` for local
+QAT/STG runs. Plain `npx requestshield-qat` requires `requestshield-cli/dev/`.
+
 ```console
-requestshield signin
-requestshield keys create [--yes]
-requestshield contract
-requestshield apps list [--json]
+requestshield signin [--no-open]
+requestshield auth status [--json]
+requestshield signout
+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]
+requestshield apps list [--json] [--limit <1-100>] [--cursor <cursor> | --all]
 requestshield apps get <app-key>
-requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
-requestshield get billing <app-key>
-requestshield agent setup [--force]
-requestshield agent setup --codex [--force]
-requestshield agent setup --claude [--force]
+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]
+requestshield agent setup [--codex | --claude] [--force]
 requestshield update check
 requestshield --help
 requestshield --version
 ```
 
+`contract`, `challenge volume` and `get billing` return `COMMAND_UNAVAILABLE`
+before configuration, authentication or network access. Their Management API
+endpoints are not implemented. `server` and `credentials status` are also absent
+from the supported command surface.
+
 ### Sign in
 
 ```console
 requestshield signin
 ```
 
-Starts the device authorization flow. The CLI prints the verification URL and
-user code without opening the browser automatically. After authorization, the
-session is stored for the current operating-system user.
-
-For CI or automation, provide `REQUESTSHIELD_ACCESS_TOKEN`. A token supplied by
-the environment is used directly and is not persisted by the CLI.
-
-### Create new keys
+Opens the configured login portal in your browser using Authorization Code with
+S256 PKCE. Sign in, verify your email if needed, then approve the displayed
+permissions. The browser must run on the same machine as the CLI. Use
+`requestshield signin --no-open` to open the printed authorization URL yourself.
+If automatic browser opening fails, the CLI also prints that URL.
+
+The CLI listens only on `127.0.0.1` at a dynamically allocated port and waits up
+to ten minutes. The browser callback carries an authorization code, state and
+optional issuer metadata, not access or refresh tokens. The CLI exchanges that
+code and its PKCE verifier directly with the configured identity provider,
+without a client secret. With `offline_access` granted, the exchange returns
+access and refresh tokens; the refresh token stays in the protected local session
+file. Sign-in succeeds only after saving that session. Closing the browser does
+not cancel the command; press Ctrl+C to stop.
+
+The selected runner reads only its environment's configuration file. QAT's public
+settings are included in the repository. Production and STG sign-in still require
+their actual public settings in the corresponding file.
+Discovery must match `OAUTH_ISSUER` and use
+an HTTPS token endpoint on that issuer's origin; an HTTP loopback authorization page is allowed for local
+development. The requested permissions are `offline_access`,
+`theair:applications:read`, `theair:applications:write`, `theair:secrets:read`, and
+`theair:secrets:write`. The CLI does not request `full_access`.
+
+If the provider includes `iss` in its authorization response, the CLI compares
+it exactly with `OAUTH_AUTHORIZATION_ISSUER`, falling back to `OAUTH_ISSUER` when
+the optional setting is absent or blank. This is an opaque identifier, not a URL
+to fetch or normalize. Stytch's QAT response uses its project identifier, which
+differs from the HTTPS discovery issuer; the QAT file pins that value explicitly.
+This setting does not change discovery, token transport or the version-1 session
+format and its API URL/discovery issuer/client ID binding.
+
+Access and rotating refresh tokens are stored in an owner-only session file,
+bound to the API URL, issuer and client ID. Commands refresh an access token
+when it has less than 60 seconds remaining. Refresh is serialized between CLI
+processes and credentials are replaced atomically. Older device-flow records
+and records for another environment require a new sign-in. An uncertain refresh
+result requires a new sign-in rather than retrying a potentially consumed token;
+the previous credential file is retained if writing or replacing the new file
+fails. If a filesystem durability check fails after the atomic replacement, the
+CLI reports uncertain persistence: the new record may already be stored. It does
+not roll back to a potentially consumed refresh token or repeat the exchange.
+
+Each profile keeps a separate session. On Windows, the base directory is
+`%LOCALAPPDATA%/IntelliFend/RequestShield`; on macOS/Linux it is
+`$XDG_STATE_HOME/intellifend/requestshield` (default
+`~/.local/state/intellifend/requestshield`). Production retains `session.json`,
+while QAT uses `qat/session.json` and STG uses `stg/session.json` beneath that base.
+Existing sessions are not moved or deleted. A session remains usable only when
+its saved issuer, client ID and API URL exactly match the selected file; changing
+those values requires a new sign-in. A command
+that crashes while holding the refresh lock can leave `session.json.lock` beside
+it. The CLI deliberately does not steal that lock from a possibly suspended
+process. If it remains locked, confirm every RequestShield command has exited
+before removing only the lock file, then sign in again if requested.
+
+Authenticated commands use the private saved session. The CLI does not accept
+`REQUESTSHIELD_ACCESS_TOKEN` or other credential overrides from the shell or
+configuration files. A separate non-interactive authentication mechanism is not
+implemented.
+
+### Local session status and sign-out
 
 ```console
-requestshield keys create
+requestshield auth status --json
+requestshield signout
 ```
 
-Asks the customer to type `ROTATE`, then calls the management API to deactivate
-the previous credentials and create a new `appKey` and `apiSecret`.
-
-- `appKey` is the public application identifier.
-- `apiSecret` is a backend-only secret displayed once.
-- The CLI does not save the returned `apiSecret`.
-- `--yes` skips the confirmation prompt for non-interactive automation.
+Status reads only the selected profile's saved session. It never refreshes,
+contacts the provider or prints credentials. JSON includes `profile`, `apiUrl`,
+`issuer`, `clientId`, `state` and `localOnly: true`; applicable records also include
+`expiresAt` and `scopes`. States are `signed_out`, `valid`, `expired`,
+`refresh_uncertain`, `config_mismatch`, `invalid` and `configuration_error`.
+`valid` describes local expiry and binding checks, not current provider acceptance.
 
-Store the Secret Key in a backend secret manager immediately after creation.
+Sign-out removes only the selected local session under its lock. It does not
+revoke the provider grant, sign out the browser or remove another profile's session.
 
-### Get the integration contract
+### Applications and credentials
 
 ```console
-requestshield contract
-```
-
-Returns the current authoritative integration contract as JSON, including any
-additional SDK-version or CSP fields supplied by the API. The command requires a
-saved sign-in session and validates the core browser, backend, and release fields
-before printing the response.
-
-### List applications
-
-```console
-requestshield apps list
-```
-
-Lists the applications the signed-in user is allowed to access:
-
-```text
-APP KEY  NAME                STATUS
-app_123  Production Website  pending
-app_456  Staging Website     active
-```
-
-Use `--json` to print the stable `{ "data": [...], "nextCursor": null }`
-response shape. The CLI allowlists `appKey`, `name`, `status`, `createdAt`, and
-`updatedAt`; it never prints an API Secret returned accidentally by the service.
-
-### Get an application
-
-```console
-requestshield apps get app_123
-```
-
-Returns `app_key`, `name`, and the application's current status as JSON.
-Valid statuses are:
-
-- `ready` — the application key was just created and no traffic has been received.
-- `active` — the application is receiving traffic.
-- `deactivated` — the application has been deactivated.
-
-The requested App Key must exactly match the key in the API response.
-
-### Get challenge volume
-
-```console
-requestshield challenge volume app_123 \
-  --from 2026-08-01T00:00:00Z \
-  --to 2026-08-27T23:59:59Z \
-  --granularity day
-```
-
-Returns challenge/request volume as JSON. Times must be ISO-8601 timestamps, and
-`--from` cannot be later than `--to`. Granularity values such as `hour` and `day`
-are passed to the API, which owns the supported set.
-
-Challenge volume proves that traffic reached the platform; it does not prove
-that the protected backend rejects requests without a valid token.
-
-### Get billing information
-
-```console
-requestshield get billing app_123
+requestshield keys create --app-name "Checkout"
+requestshield apps list --json --all
+requestshield apps get <app-key>
+requestshield apps rename <app-key> --name "Checkout API"
+requestshield apps disable <app-key>
+requestshield apps enable <app-key>
+requestshield keys rotate <app-key>
+requestshield keys reveal <app-key>
+requestshield keys revoke <app-key>
 ```
 
-Returns the selected application's current plan, billing cycle, charges, quota,
-and usage as JSON. The command is read-only and requires a saved sign-in session.
+Create makes a new application and initial secret. Rotate replaces the current
+secret while preserving the App Key. Reveal retrieves the current active secret;
+revoke invalidates that secret. Disable changes the application's administrative
+state while retaining its secret; enable requires an active secret.
+
+Create, rename and enable run without a confirmation prompt. Disable, rotate,
+revoke and reveal require confirmation; `--yes` explicitly skips that prompt.
+App names are not unique; commands targeting an existing app require its exact
+App Key. The App Key is public. Create, rotate and reveal print a backend-only
+API secret when supplied by the service; store it directly in a backend secret
+manager. The CLI never saves that secret.
+
+Mutations except reveal accept `--idempotency-key`. The CLI generates a fresh
+key for each invocation when omitted and prints it to stderr before dispatch,
+leaving JSON stdout intact. Retain it for interruption or crash recovery. The CLI
+never automatically retries a mutation.
+For an uncertain result, repeat the **identical command and arguments with the
+same key printed in the error**, within seven days of the original attempt.
+A new key starts a new operation. After seven days, inspect the application before
+acting. Create/rotate replay returns `apiSecret: null`; the CLI suggests explicit
+`keys reveal` and never reveals or rotates automatically.
+
+Enable, disable and revoke return HTTP `202` acceptance. Publication is
+asynchronous; acceptance and an `enabled` status do not prove global propagation.
+
+### List and inspect applications
+
+List defaults to one page. `--limit` accepts 1–100; `--cursor` continues a previous
+page. `--all` traverses at most 100 pages and rejects repeated cursors or an
+unfinished traversal at that bound. It cannot be combined with `--cursor`.
+
+`apps list --json` returns `{ "data": [...], "nextCursor": null }` (or a cursor
+for an incomplete single-page listing). `apps get` and rename return
+`{ "data": { ... } }`. Application objects have exactly `appKey`, `name`,
+`status`, `createdAt` and `updatedAt`; unexpected fields and secrets are not printed.
+
+| Status | Meaning |
+| --- | --- |
+| `attention_required` | Publication is blocked or uncertain. |
+| `pending` | The latest configuration is awaiting publication. |
+| `disabled` | The saved administrative state disables the application. |
+| `revoked` | The enabled application has a revoked secret. |
+| `enabled` | The saved application and active secret are enabled. |
+
+These aggregate states describe configuration, not traffic, backend enforcement
+or exact secret state while pending, blocked or disabled.
 
 ### Install the Agent Skill
 
@@ -161,7 +248,10 @@ Existing Skill content is preserved. Add `--force` to replace it:
 requestshield agent setup --codex --force
 ```
 
-Restart the selected agent or start a new task after installation.
+Restart the selected agent or start a new task after installation. Published
+packages use their bundled skill. Repository runners resolve the canonical
+`../skills/requestshield` using source-checkout markers; they do not depend on
+the working directory or require a staged packaging copy.
 
 ### Check for updates
 
@@ -174,7 +264,7 @@ When a newer version exists, the CLI displays the current and latest versions
 and asks:
 
 ```text
-Update to RequestShield <version>? (y/N):
+Install RequestShield <version> globally with npm? (y/N):
 ```
 
 Entering `y` runs the equivalent of:
@@ -184,7 +274,9 @@ npm install --global @intellifend/requestshield@<latest-version>
 ```
 
 This command requires an interactive terminal, Node.js, and npm. It updates a
-global npm installation; it does not replace a standalone Windows executable.
+global npm installation. Repository checkouts and pinned `npx` invocations are
+managed separately. QAT/STG `update check` prints local Git/source guidance and
+returns without querying the registry, prompting or installing anything.
 
 ## Install with npm
 
@@ -196,6 +288,11 @@ requestshield --help
 requestshield --version
 ```
 
+The public package exposes only the `requestshield` executable and production
+configuration. Internal QAT/STG runners require this repository's private `dev/`
+package and are not installed by the public package. Source changes do not alter
+versions already published.
+
 Run a specific version without installing globally:
 
 ```console
@@ -214,231 +311,272 @@ npm package.
 
 ## Local development
 
-From the `requestshield-cli` directory:
+Use Node.js >=22.21 for repository development. Install workspace dependencies
+from the repository root; the CLI check includes contract tests that require the
+sibling Management API package's dependencies.
 
 ```console
-npm install
-npm run lint
-npm run typecheck
-npm test
-npm run build
+corepack pnpm install
+cd requestshield-cli
+npm run check
 node src/main.mjs --help
 node src/main.mjs --version
+npm run requestshield-qat -- --help
+npm run requestshield-stg -- --help
 ```
 
-The current `build` script validates the syntax of the `.mjs` source files. It
-does not generate a standalone executable.
+From `requestshield-cli/`, select the private runner explicitly:
 
-### Test the update flow locally
+```console
+npx --offline --prefix ./dev requestshield-qat --help
+npx --offline --prefix ./dev requestshield-stg --help
+```
 
-The manual update test mocks the registry and install operation, so it does not
-publish a package or change the installed version:
+For plain `npx` commands, change to `requestshield-cli/dev/`:
 
-```powershell
-$env:REQUESTSHIELD_MOCK_LATEST_VERSION = "0.1.6"
-npm run test:update-check:manual
-Remove-Item Env:REQUESTSHIELD_MOCK_LATEST_VERSION
+```console
+cd dev
+npx requestshield-qat --help
+npx requestshield-stg --help
 ```
 
-After entering `y`, the test prints `[MOCK] Would install ...`.
+`dev/package.json` is private and exposes only local QAT/STG wrappers. No
+additional installation or linking is needed. Keep this working directory for
+the plain `npx` commands; they resolve the current checkout rather than a
+published QAT/STG artifact. To keep package resolution offline, use:
+
+```console
+npx --offline requestshield-qat --help
+```
+
+Both invocation forms run `dev/main-qat.mjs` or `dev/main-stg.mjs` and read the
+parent package's fixed `config/.env.qat` or `config/.env.stg` file
+(`../config/.env.qat` or `../config/.env.stg` from `dev/`). To change an internal
+endpoint or public client, edit that file; do not set shell overrides. All three
+profile files use the same public keys:
+
+```dotenv
+OAUTH_ISSUER=https://identity.example.com
+# Optional exact callback iss; blank uses OAUTH_ISSUER.
+OAUTH_AUTHORIZATION_ISSUER=
+OAUTH_CLIENT_ID=public-client-id
+API_URL=https://management.example.com
+```
+
+Do not put credentials in these files. Session storage remains private and
+separate from package configuration.
 
-## Packaging the RequestShield Skill
+`npm run test:contract` exercises the real Management router in
+`management-api/test/core/cli-contract.spec.mjs`; `npm run check` includes it.
+These isolated tests use synthetic credentials and do not prove live acceptance.
 
-The canonical Skill is stored at `../skills/requestshield`. Do not maintain a
-second source copy inside this package.
+`npm run build` validates source syntax and creates the standalone runtime
+package in `build/`. The package gate runs this build after its other checks.
+See [Build and inspect the package](#build-and-inspect-the-package) for the output
+layout and tarball commands.
 
-Before npm creates the package, the `prepack` hook temporarily copies the
-canonical Skill to `skills/requestshield`. The `postpack` hook removes that
-generated copy after packaging.
+### Source CLI + Stytch Test + Management QAT
 
-Inspect the files that npm will publish:
+Use the current source build for this workflow; the source package version does
+not establish that these changes have been published to npm. `config/.env.qat`
+contains the public configuration:
+
+| Setting | QAT file value |
+| --- | --- |
+| Discovery issuer (`OAUTH_ISSUER`) | `https://incongruous-cherry-0283.customers.stytch.dev` |
+| Authorization response issuer (`OAUTH_AUTHORIZATION_ISSUER`) | `stytch.com/project-test-968146e2-6f34-4936-9d1c-a7e966813c70` |
+| Public client ID | `connected-app-test-5ff62ca4-c0eb-48c3-84e5-06ae8f669998` |
+| API URL | `https://management-api-qat.intellifend.ai` |
+
+From the repository root:
 
 ```console
-npm pack --dry-run
+cd requestshield-cli
+npx --offline --prefix ./dev requestshield-qat signin
+npx --offline --prefix ./dev requestshield-qat apps list --json
 ```
 
-Create a local tarball:
+The prefix selects the local private package; do not omit it from this directory.
+Alternatively, from `requestshield-cli/`, run
+`npm run requestshield-qat -- signin` and
+`npm run requestshield-qat -- apps list --json`.
+
+The private developer package and its runners are excluded from the public npm
+package. Old `REQUESTSHIELD_OAUTH_*`, `REQUESTSHIELD_API_URL` and
+`REQUESTSHIELD_ACCESS_TOKEN` shell variables have no effect on profile selection,
+configuration or credentials.
+
+The current QAT provider opens the deployed portal at
+`https://requestshield-qat.intellifend.ai/oauth/authorize`; this CLI smoke test
+does not require a local portal server.
+If verification or password reset opens another tab, complete it and return to
+the original authorization tab to continue. Email tokens are not shared between
+tabs by the portal.
+
+Provider settings to verify for QAT acceptance:
+
+- Authorization URL `https://requestshield-qat.intellifend.ai/oauth/authorize`.
+- A First Party Public Connected App with redirect `http://127.0.0.1/callback`
+  registered without a port, enabling the CLI's dynamic loopback port.
+- The four custom scopes above plus `offline_access`, with user role permissions
+  and explicit consent; keep full-access and offline-consent bypass disabled.
+- Access-token lifetime at most 900 seconds, audience
+  `urn:theair:management-api:dev`, and access-only template markers
+  `theair_token_use=management_access` and `theair_client_id` matching the client ID.
+- SDK allowed origin and email callbacks matching
+  `https://requestshield-qat.intellifend.ai`.
+
+Public discovery rechecked on 2026-09-16 advertises
+`https://requestshield-qat.intellifend.ai/oauth/authorize`. A read-only QAT run on
+the same date successfully listed all applications (an empty list). Local auth
+status was expired before the command and valid with a later expiry afterward,
+confirming automatic refresh and API acceptance for that session. This does not
+audit every provider setting or verify live mutations, publication or production.
+Source changes do not configure the provider or deploy the portal.
+See the [Stytch CLI guide](https://stytch.com/docs/connected-apps/guides/cli-agents)
+and [refresh contract](https://stytch.com/docs/api-reference/consumer/api/connected-apps/exchange-refresh-token).
+
+Acceptance requires a real browser sign-in, then `apps list --json` accepted by
+QAT. Wait until the access token expires and repeat the command to verify refresh.
+An account with no apps should return an empty list; do not create an app just
+for this test. Local mock checks do not establish provider or deployed API acceptance.
+
+To test local portal changes separately, start the
+[portal](../theair-customer-portal-frontend/README.md) on `http://localhost:5173`
+and coordinate with the provider owner to point the authorization URL to
+`http://localhost:5173/oauth/authorize`, with matching SDK allowed origin and email
+callbacks. That optional provider configuration change is not a prerequisite for
+the default QAT CLI smoke test above.
+
+### Test the update flow locally
+
+The manual update test mocks the registry and install operation, so it does not
+publish a package or change the installed version:
 
 ```console
-npm pack
+npm run test:update-check:manual -- 0.1.6
 ```
 
-## Publish to npm
+After entering `y`, the test prints `[MOCK] Would install ...`.
 
-npm does not allow an existing package version to be overwritten. Check the
-published version, merge the latest team changes, then choose a new version in
-`package.json` before publishing.
+## Build and inspect the package
+
+From `requestshield-cli/`, create and inspect the runtime package:
 
 ```console
-npm view @intellifend/requestshield version
-npm run lint
-npm run typecheck
-npm test
-npm pack --dry-run
-npm publish --access public
+npm run build
+node build/src/main.mjs --help
 ```
 
-Verify the published package:
+The generated, gitignored `build/` directory contains:
 
-```console
-npm view @intellifend/requestshield version
-npm dist-tag ls @intellifend/requestshield
-npx --yes --package=@intellifend/requestshield@0.1.5 requestshield --version
+```text
+build/
+  src/
+  config/.env.prod
+  skills/requestshield/
+  README.md
+  package.json
 ```
 
-## Management API contract
+The CLI remains Node.js ESM; the build copies the runtime files without
+compilation or bundling. The generated `package.json` preserves package metadata,
+the production executable and the file allowlist, while omitting development
+dependencies and source lifecycle scripts. The directory can therefore run and
+be packed independently of the repository's source tooling.
 
-### Start sign-in
+The build creates a directory only, not a `.tgz` archive. Rebuild after changing
+source, configuration, package metadata or Skill content; `build/` is generated
+output and should not be edited directly.
 
-`POST /v1/cli/signin`
+Optionally inspect the npm file list or create a local distribution archive:
 
-```json
-{
-  "client": "requestshield-cli"
-}
+```console
+npm pack ./build --dry-run
+npm pack ./build --pack-destination ./build
 ```
 
-The response contains `deviceCode`, `userCode`, `verificationUri`, `expiresIn`,
-and `interval`.
+The latter writes `build/intellifend-requestshield-<version>.tgz`. Archives are
+generated artifacts, ignored by Git, and are not required in source control or
+before publishing. The package listing should contain `src/main.mjs`,
+`config/.env.prod` and the complete Skill, with no QAT/STG configuration or
+private `dev/` package.
 
-### Poll sign-in
+### Skill source and direct packing
 
-`POST /v1/cli/signin/token` with `{ "deviceCode": "..." }`.
+The canonical Skill is stored at `../skills/requestshield`. The build copies it
+to `build/skills/requestshield`; maintain only the canonical source.
 
-Pending responses use HTTP 400 with `code` set to `authorization_pending` or
-`slow_down`. A successful response contains `accessToken` and optional account
-metadata.
+Direct packing from `requestshield-cli/` remains supported:
 
-### Rotate keys
+```console
+npm pack --dry-run
+npm pack
+```
 
-`POST /v1/cli/keys/rotate` with Bearer authentication and an empty JSON body.
-The response contains `appKey` and the one-time `apiSecret`.
+For this source-package path, `prepack` temporarily copies the canonical Skill to
+`skills/requestshield`, and `postpack` removes that generated copy. The build
+directory already includes its Skill and needs no staging hook.
 
-### List applications
+## Publish to npm
 
-`GET /v1/applications` with Bearer authentication and no request body. The API must
-scope results to the authenticated user.
+npm does not allow an existing package version to be overwritten. Check the
+published version, merge the latest team changes, then choose a new version in
+`package.json` before publishing.
 
-```json
-{
-  "data": [
-    {
-      "appKey": "pk_AAAAAAAAAAAAAAAAAAAAAAAA",
-      "name": "Checkout",
-      "status": "pending",
-      "createdAt": "2026-09-11T00:00:00.000Z",
-      "updatedAt": "2026-09-11T00:00:00.000Z"
-    }
-  ],
-  "nextCursor": null
-}
-```
+Run the release commands from the source `requestshield-cli/` directory. Its
+`prepublishOnly` hook runs the complete package check before publication;
+`build/` is the inspection and packaging output.
 
-Every application requires `appKey`, `name`, `status`, `createdAt`, and `updatedAt`.
-`nextCursor` must be a non-empty string or `null`. An account with no applications
-returns `200` with an empty `data` array. A missing or rejected session returns
-`401`. The response must never contain an API Secret.
-
-### Get an application
-
-`GET /v1/applications/{appKey}` with Bearer authentication and no request body.
-The path segment is URL-encoded by the CLI.
-
-```json
-{
-  "ok": true,
-  "data": {
-    "app_key": "app_123",
-    "name": "Website",
-    "status": "active"
-  }
-}
-```
+`npm publish` packages and uploads the module itself; a separate `npm pack`
+command is optional. CI can install workspace dependencies from the repository
+root and publish from this source package. Store a `.tgz` as a CI artifact only
+when the release workflow needs a separately retained archive.
 
-`status` must be `ready`, `active`, or `deactivated`. The response App Key must
-match the requested key. The CLI rebuilds the output from these three fields so
-unexpected response fields cannot be printed.
-
-### Get challenge volume
-
-`GET /v1/applications/{appKey}/challenge-volume` with Bearer authentication and
-optional `from`, `to`, and `granularity` query parameters.
-
-```json
-{
-  "ok": true,
-  "data": {
-    "app_key": "app_123",
-    "from": "2026-08-01T00:00:00Z",
-    "to": "2026-08-27T23:59:59Z",
-    "granularity": "day",
-    "challenge_count": 125430
-  }
-}
+```console
+npm view @intellifend/requestshield version
+npm run check
+npm pack --dry-run
+npm publish --access public
 ```
 
-The CLI requires a matching App Key, valid ordered timestamps, a non-empty
-granularity, and a non-negative safe-integer `challenge_count`. It rebuilds the
-output from these fields so unexpected API fields cannot be printed.
-
-### Get billing information
-
-`GET /v1/applications/{appKey}/billing` with Bearer authentication and no
-request body.
-
-```json
-{
-  "ok": true,
-  "data": {
-    "plan": {
-      "tier": "pro",
-      "current_cycle": [
-        "2026-07-07T07:07:07",
-        "2027-07-07T07:07:07"
-      ],
-      "billing": 1080,
-      "next_charge": "2027-07-07T07:07:07"
-    },
-    "usage": {
-      "monthly_quota": 100000,
-      "current_usage": 110000,
-      "overage_charge": 10
-    }
-  }
-}
-```
+Verify the published package:
 
-The CLI validates all documented fields and rebuilds the nested result so
-unexpected response fields cannot be printed.
-
-### Get the integration contract
-
-`GET /v1/integration-contract` with Bearer authentication and no request body.
-
-```json
-{
-  "ok": true,
-  "data": {
-    "contract_version": "2026-08-27",
-    "browser": {
-      "script_url": "https://intellifend.ai/intellifend.js",
-      "token_header": "X-IntelliFend-Token",
-      "available_modes": ["manual"]
-    },
-    "backend": {
-      "supported_languages": ["java"],
-      "min_jdk": 17
-    },
-    "release_state": "released"
-  }
-}
+```console
+npm view @intellifend/requestshield version
+npm dist-tag ls @intellifend/requestshield
+npx --yes --package=@intellifend/requestshield@0.1.5 requestshield --version
 ```
 
-The CLI requires these core fields and preserves additional authoritative
-contract fields returned by the API. Credential-shaped fields are rejected.
+## Management API contract
+
+The authoritative HTTP definitions are [OpenAPI](../management-api/openapi.json)
+and the [CLI mapping](../management-api/CLI-CONTRACT.md). All nine app/secret
+operations are covered by the CLI-to-router contract gate.
+
+| CLI command | Method and path |
+| --- | --- |
+| `keys create --app-name <name>` | `POST /v1/applications` with `{name}` |
+| `apps list` | `GET /v1/applications` with optional `limit` and `cursor` |
+| `apps get <app-key>` | `GET /v1/applications/{appKey}` |
+| `apps rename <app-key> --name <name>` | `PATCH /v1/applications/{appKey}` with `{name}` |
+| `apps enable` / `apps disable` | Bodyless `POST /v1/applications/{appKey}/enable` or `/disable` |
+| `keys rotate` / `keys revoke` / `keys reveal` | Bodyless `POST /v1/applications/{appKey}/secret/rotate`, `/revoke` or `/reveal` |
+
+Create and rotate return `{appKey,status,apiSecret}`; a matching replay has a
+null secret. Reveal returns `{apiSecret}` and is not replayed. Application detail
+and rename return `{data:Application}`; list returns `{data:Application[],nextCursor}`.
+Lifecycle acknowledgements are `{status:"accepted"}`. Mutations other than reveal
+send a caller-scoped `Idempotency-Key`.
+
+Only OAuth access tokens authenticate these requests. Sign-in and refresh call
+the identity provider directly; browser sessions, refresh tokens and application
+API secrets cannot authenticate Management. No `/v1/cli/*` route is used.
 
 ## Security notes
 
 - Never place an access token or Secret Key in URLs, command arguments, logs,
   test fixtures, or committed files.
-- The CLI does not persist the Secret Key returned by `keys create`.
+- The three environment files contain public configuration only. OAuth
+  credentials belong exclusively in the protected saved session.
+- The CLI does not persist API secrets returned by create, rotate or reveal.