zero-slop 2.10.0 → 2.10.1

package/README.md

@@ -30,12 +30,12 @@
 
 <p align="center">
   <a href="https://github.com/manavmishra/ZeroSlop/actions/workflows/validate.yml"><img alt="Validate" src="https://github.com/manavmishra/ZeroSlop/actions/workflows/validate.yml/badge.svg"></a>
-  <img alt="Version 2.10.0" src="https://img.shields.io/badge/version-2.10.0-72528F?color=C15732">
+  <img alt="Version 2.10.1" src="https://img.shields.io/badge/version-2.10.1-72528F?color=C15732">
   <a href="https://www.npmjs.com/package/zero-slop"><img alt="npm version" src="https://img.shields.io/npm/v/zero-slop?color=C15732"></a>
   <a href="https://www.npmjs.com/package/zero-slop"><img alt="npm downloads" src="https://img.shields.io/npm/dm/zero-slop?color=17634F"></a>
   <a href="https://github.com/manavmishra/ZeroSlop/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/manavmishra/ZeroSlop?style=flat&color=C15732"></a>
   <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-141412"></a>
-  <a href="https://hol.org/guard/plugins"><img alt="Listed in the HOL plugin registry" src="https://img.shields.io/badge/HOL%20registry-listed-2C6E8F"></a>
+  <a href="https://hol.org/registry/plugins/manav-mishra%2Fzero-slop"><img alt="Listed in the HOL plugin registry" src="https://img.shields.io/badge/HOL%20registry-listed-2C6E8F"></a>
 </p>
 
 ```sh
@@ -136,7 +136,7 @@ https://mcp.zero-slop.ai/mcp
 Edit a file through MCP:
 
 ```sh
-npx --yes zero-slop@2.10.0 deslop draft.md --genre professional
+npx --yes zero-slop@2.10.1 deslop draft.md --genre professional
 ```
 
 Use `-` for stdin and `--json` for structured output. `--require-approved` exits nonzero
@@ -254,8 +254,8 @@ stress case took 2.2932 seconds, and learning from an 8,000-word edit took
 0.1592 seconds. The measurements and machine details are in
 [`bench/performance-results.json`](bench/performance-results.json).
 
-Across 12 interleaved runs against 2.7.7, we measured 2.57% higher median throughput,
-which is effectively unchanged. The separate two-way replay used
+Across 12 interleaved runs against 2.7.7, we measured 0.71% lower median throughput,
+within the 5% regression limit. The separate two-way replay used
 Zero Slop v2.6.0.
 
 The [RAID+ audit](bench/raid-plus-corpus/README.md) checks how the scorer responds

package/SECURITY.md

@@ -48,11 +48,25 @@ draft or rewrite.
 
 The REST endpoint `https://mcp.zero-slop.ai/v1/deslop` calls this same pipeline.
 It accepts at most 128 KiB of UTF-8 JSON and one trimmed draft of 20,000 Unicode code
-points. REST and MCP share the capacity limiter; adding a transport does not create
-an independent allowance. The limiter operates per Cloudflare location and is not
-a strict global quota. REST errors omit request content. Responses use `no-store`,
+points. REST and MCP share an edge capacity limiter. That limiter operates per
+Cloudflare location; a separate atomic budget reservation gates every hosted
+editing-model call across REST, MCP, CLI and the browser demo. Adding a transport
+does not create an independent editing allowance. REST errors omit request content. Responses use `no-store`,
 and there is no stored response replay or idempotency cache.
 
+The editor fails closed when its shared daily budget or per-client limit is reached,
+or when budget enforcement is unavailable. Capacity is reserved before inference;
+failed or timed-out model calls are not refunded because their usage may be unknown.
+No automatic model retry or paid-model fallback is used. Local scoring is not metered.
+The service derives a keyed daily hash of the trusted connection IP to coordinate
+abuse limits. This separate counter stores the daily hash and counts, never the raw
+IP or draft, and does not join them to analytics. Shared networks can share a limit.
+Active daily identifiers expire after the UTC day. Cloudflare's SQLite recovery
+history may retain earlier database states for up to 30 days; this history contains
+no drafts or raw IP addresses.
+The project budget bounds Zero Slop's reserved model usage, not other applications'
+usage or the account's existing hosting charges.
+
 REST adds completed results, failures, and capacity rejections to the existing
 aggregate counters. It does not increment MCP initialization or tool-call counts.
 REST logs contain only event name, outcome, character count, and elapsed time.
@@ -66,6 +80,13 @@ detected phrases, IP addresses, raw user agents, cookies, email addresses, and s
 user or session identifiers are excluded. Initializations are reported as connections,
 not unique people. Analytics Engine retains the dataset for three months.
 
+Hosted events also record the entry channel (MCP, CLI, REST, or the web editor),
+approval category and model-attempt count. The CLI sends a fixed app-family and
+major-version header on its existing hosted requests; this is self-reported
+attribution, not identity. Offline commands send no analytics. The web endpoint
+does not claim to measure the browser's final source checks. Internal signed
+gateway model calls are excluded from the web channel to prevent double counting.
+
 Telemetry writes are non-blocking and wrapped so an analytics failure cannot fail an
 MCP call. The daily report uses sampling-aware aggregate queries and degrades to a
 clearly labeled missing section if the dataset cannot be read.

package/SKILL.md

@@ -2,7 +2,7 @@
 name: zero-slop
 license: MIT
 metadata:
-  version: "2.10.0"
+  version: "2.10.1"
   author: manavmishra
 description: Turn drafts into sharp, natural prose or inspect them without rewriting. Zero Slop runs inside the user's existing AI assistant; Claude, GPT, or another compatible model reads and edits in context while local tools point to exact phrases and protect the source. Use when the user asks to humanize or de-slop writing, inspect AI-sounding patterns, fix text that reads like ChatGPT, polish outward-facing prose, draft social or LinkedIn content, or apply a final quality check to prose the agent generated. The workflow preserves facts, voice, and format and learns privately from repeated, reason-labelled human edits.
 ---

package/bin/lib/deslop.mjs

@@ -183,9 +183,13 @@ export async function deslop(input, options = {}) {
   let protocolVersion = PROTOCOLS[0];
   let session;
   let toolPending = false;
+  // Hosted CLI attribution only: no identifier, machine data, or extra request.
+  // Other integrations retain their existing clientInfo without posing as CLI.
+  const cliMajorVersion = clientVersion.match(/^(\d{1,4})(?:\.|$)/)?.[1] ?? "unknown";
   const headers = () => ({
     "content-type": "application/json", accept: "application/json, text/event-stream",
     "cache-control": "no-store", "mcp-protocol-version": protocolVersion,
+    ...(clientName === "zero-slop-cli" ? { "user-agent": `zero-slop-cli/${cliMajorVersion}` } : {}),
     ...(session ? { "mcp-session-id": session } : {}),
   });
   // A dropped HTTP connection is not an MCP cancellation notification. Request it
@@ -210,7 +214,9 @@ export async function deslop(input, options = {}) {
       void response.body?.cancel().catch(() => {});
       const retry = response.headers.get("retry-after");
       const retryAfterSeconds = retry && /^\d{1,5}$/.test(retry) ? Number(retry) : undefined;
-      throw new DeslopError("http_error", `The MCP service returned HTTP ${response.status}. No retry was sent.`, {
+      throw new DeslopError("http_error", response.status === 429
+        ? "Zero Slop is busy or at a usage limit. Please wait before trying again. No retry was sent."
+        : `The MCP service returned HTTP ${response.status}. No retry was sent.`, {
         httpStatus: response.status, ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
       });
     }
@@ -243,6 +249,17 @@ export async function deslop(input, options = {}) {
       throw new DeslopError("invalid_response", "The MCP service returned an invalid tool result.");
     }
     if (reply.isError === true) {
+      const gate = reply._meta?.["zero-slop/error"];
+      if (gate && (gate.code === "usage_limit" || gate.code === "budget_unavailable") &&
+          gate.status === (gate.code === "usage_limit" ? 429 : 503)) {
+        const retry = gate.retryAfterSeconds;
+        throw new DeslopError(gate.code, gate.code === "usage_limit"
+          ? "Hosted editing is temporarily busy or at its free usage limit. Please wait before trying again. Keep your source; no retry was sent."
+          : "Hosted capacity could not be checked. Please try again later. Keep your source; no retry was sent.", {
+          httpStatus: gate.status,
+          ...(Number.isInteger(retry) && retry > 0 && retry <= 86_400 ? { retryAfterSeconds: retry } : {}),
+        });
+      }
       throw new DeslopError("tool_error", "Zero Slop could not return a safely checked result. The source was not changed locally.");
     }
     return validateResult(reply.structuredContent);

package/docs/cli.md

@@ -3,7 +3,7 @@
 Use `deslop` for hosted editing with MCP parity. Use `score` for offline checks.
 
 ```sh
-npm install --global zero-slop@2.10.0
+npm install --global zero-slop@2.10.1
 zero-slop deslop draft.md --genre professional
 zero-slop deslop - --genre email < draft.txt
 zero-slop deslop draft.md --json --require-approved
@@ -13,6 +13,16 @@ zero-slop score draft.md -- --json
 Use Node.js 22 or newer for hosted editing. Offline scoring also requires Python 3.
 The npm package includes the skill and its local checks; no separate model ships.
 
+On macOS, [Homebrew](https://github.com/manavmishra/homebrew-zero-slop) installs
+the same npm CLI plus Node and Python:
+
+```sh
+brew install manavmishra/zero-slop/zero-slop
+```
+
+The tap pins a tested npm release; a new npm version may arrive before its
+Homebrew update. Linux Homebrew has not been tested.
+
 `deslop` reads exactly one file or standard input, sends the draft to
 `https://mcp.zero-slop.ai/mcp`, and writes the returned text to standard output.
 It never edits a source file in place. Warnings go to standard error. Capture
@@ -49,6 +59,18 @@ Inspect the [six result statuses](rest-api.md#read-the-result). In particular,
 A timeout or cancellation may not stop hosted processing. The CLI does not replay
 the request. Review any returned status or error before choosing to send the draft again.
 
+Hosted editing shares its free allowance with MCP, REST, and `/try/`. A
+`usage_limit` error exits `1`; JSON errors include `httpStatus: 429` and, when
+provided, `retryAfterSeconds`. Wait at least that long before a manual retry.
+`budget_unavailable` (`503`) means capacity could not be checked, so no new model
+request was started. Offline scoring does not consume this allowance.
+
+Hosted calls are included in aggregate service metrics: channel, result status,
+model attempts, and latency. A fixed CLI-family/major-version header identifies
+the entry channel on the requests already being sent; no extra tracking request
+is made. It does not identify a person or installation. Offline commands send no
+analytics. See the [security policy](../SECURITY.md) for the complete field list.
+
 ## Offline scoring
 
 ```sh

package/docs/rest-api.md

@@ -8,10 +8,14 @@ The [OpenAPI 3.1.2 contract](https://mcp.zero-slop.ai/openapi.json) is generated
 from the schemas used to validate MCP and REST requests and results. Import it
 into an OpenAPI-compatible client or documentation tool.
 
+Use the [API sandbox](https://zero-slop.ai/sandbox/) to inspect a simulated result
+before sending a draft. Its live mode requires an explicit request and uses this
+same endpoint.
+
 ## Send a draft
 
 ```sh
-curl --fail-with-body --max-time 75 https://mcp.zero-slop.ai/v1/deslop \
+curl --fail-with-body --max-time 75 --include https://mcp.zero-slop.ai/v1/deslop \
   -H 'Content-Type: application/json' \
   --data '{"text":"It is important to note that Maya owns the pricing review. The team will decide on Friday.","genre":"professional","audience":"The product team"}'
 ```
@@ -26,9 +30,52 @@ Lengths count Unicode code points; a combined emoji or accented character can co
 Send UTF-8 JSON in the body, never a URL query. The body limit is 128 KiB, including
 JSON escaping. Compressed bodies are not accepted. Unknown properties are ignored.
 
-Call from your application server. The service does not enable cross-origin browser
-requests. Access is free, without an API key, and shares MCP's capacity limiter.
-Capacity is best effort; there is no reserved quota or uptime SLA.
+Call from your application server. Browser access is enabled only for the Zero Slop
+site at `https://zero-slop.ai` and `https://www.zero-slop.ai`; other sites should
+call from their servers. CORS is a browser policy, not authentication.
+
+Access is free, without an API key. REST and MCP share capacity and usage limits,
+including a daily hosted allowance and a short client cooldown. The allowance can
+run out; it does not reserve capacity for an application. Availability is best
+effort, with no uptime SLA. Offline skill checks and CLI scoring stay free and do
+not consume this hosted allowance.
+
+Current safety limits allow at most five model calls per client network per UTC
+day and two per minute, shared across REST, MCP, CLI editing, and `/try/`.
+Shared networks can reach those limits together. A separate global limit reserves
+up to 8,000 estimated Workers AI neurons per UTC day before inference; it can
+stop calls before the client limit is reached. Reservations are conservative and
+are not refunded after timeouts. New model calls pause during the last minute
+before the UTC reset. These are capacity ceilings, not a guaranteed allocation.
+
+The service records aggregate REST call counts, result categories, model attempts,
+quota rejections, and latency. Drafts, rewrites, IP addresses, email addresses and
+stable user identifiers are excluded from this telemetry. Calls are not unique
+users, and model attempts are not billable token counts. See the
+[security policy](../SECURITY.md) for the field list and retention.
+
+## Working language examples
+
+The [example directory](../integrations/api-examples/README.md) contains runnable
+clients with 75-second timeouts, structured error handling, and an explicit check
+before the returned text can pass to an automated step.
+
+| Language | Source | HTTP client |
+|---|---|---|
+| curl | [Shell example](../integrations/api-examples/curl/deslop.sh) | curl; jq reads the result |
+| JavaScript | [Node.js example](../integrations/api-examples/javascript/deslop.mjs) | Built-in `fetch` |
+| TypeScript | [Typed Node.js example](../integrations/api-examples/typescript/deslop.ts) | Built-in `fetch` |
+| Python | [Python example](../integrations/api-examples/python/deslop.py) | Standard-library `urllib.request` |
+| Java | [Java example](../integrations/api-examples/java/src/main/java/Deslop.java) | JDK `HttpClient`; Jackson for JSON |
+| C# | [.NET example](../integrations/api-examples/csharp/Program.cs) | `HttpClient` and `System.Text.Json` |
+| Go | [Go example](../integrations/api-examples/go/main.go) | Standard-library `net/http` |
+| Rust | [Rust example](../integrations/api-examples/rust/src/main.rs) | reqwest and serde_json |
+
+Each example reads one request object from stdin, sends one POST, and preserves
+the complete JSON response. Exit `0` means the approval condition below passed;
+exit `3` means review is required. HTTP and transport failures exit `1`. Check
+the exit code before extracting `text`; an HTTP `200` alone is insufficient.
+These are examples to adapt within an application, not separate SDKs.
 
 ## Read the result
 
@@ -44,9 +91,24 @@ every check.
 | `unchanged_verification_failed` | Keep the original; proposed edits failed source checks |
 | `unchanged_service_unavailable` | Keep the original; the model did not yield a usable edit |
 
-The response also contains `before` and `after` writing reports, `scoreChange`,
-`factsPreserved`, `passedFinalChecks`, `independentModelChecks`, `modelRequests`,
-`rolesCompleted`, `finishingRounds`, `scorerVersion`, `durationMs`, `text`, and `note`.
+The successful response contains these 14 fields:
+
+| Field | Meaning |
+|---|---|
+| `text` | Returned draft, which may be unchanged |
+| `status` | One of the six outcomes above |
+| `before`, `after` | Writing reports: score, flagged phrases, readability, rhythm, punctuation, layout, and register checks |
+| `scoreChange` | After score minus before score |
+| `factsPreserved` | Whether tracked source details survived the checks |
+| `passedFinalChecks` | Whether the rewritten text passed the final checks |
+| `independentModelChecks` | Count of independent model checks; currently zero |
+| `modelRequests` | Editing-model requests made, zero or one |
+| `rolesCompleted` | Completed pipeline responsibilities |
+| `finishingRounds` | Additional local finishing rounds |
+| `scorerVersion` | Deployed Zero Slop release |
+| `durationMs` | Server processing time in milliseconds |
+| `note` | Review guidance, including any limitations |
+
 `scoreChange` is after minus before, so a negative value means the measured score fell.
 The writing score is not a probability that AI wrote the draft.
 
@@ -73,12 +135,30 @@ Errors use `application/problem+json` with `type`, `title`, `status`, `detail`,
 | HTTP status | Meaning |
 |---|---|
 | `400` | Invalid JSON, UTF-8, declared length, or input fields |
+| `403` | `forbidden_origin` or `forbidden_preflight`; use an allowed first-party browser request or call from your server |
 | `405` | Wrong method; use `POST` |
 | `408` | The request body did not arrive within 10 seconds |
 | `413` | The JSON body exceeds 128 KiB |
 | `415` | Unsupported media type or compression |
-| `429` | Shared capacity reached; respect `Retry-After` |
-| `503` | No safely scored result was available |
+| `429` | `capacity_limit` or `usage_limit`; respect `Retry-After` |
+| `503` | `budget_unavailable` if the usage gate could not complete, or `service_unavailable` if no safely scored result was available |
+
+For example, a usage-limit response has this shape; values here are illustrative:
+
+```json
+{
+  "type": "about:blank",
+  "title": "Too Many Requests",
+  "status": 429,
+  "detail": "The free hosted allowance is currently exhausted. Try again after the indicated delay.",
+  "code": "usage_limit",
+  "requestId": "11111111-1111-4111-8111-111111111111"
+}
+```
+
+The `Retry-After` response header gives the minimum delay in seconds. Read it
+from the header rather than parsing `detail`. Keep the problem code and request
+ID for troubleshooting without logging the draft or result.
 
 Allow 75 seconds on the client. The service makes at most one editing-model request;
 scoring and source checks add their own bounded work. A client timeout or cancellation
@@ -92,7 +172,8 @@ calls, may repeat work, and are not guaranteed to return identical text.
 
 The draft is sent to Zero Slop's hosted service and processed in memory. The upstream
 editing service must confirm `stored: false`; drafts and rewrites are not cached or logged by this
-service. Aggregate operational counts remain. See [SECURITY.md](../SECURITY.md) and
+service. Aggregate operational counts and short-lived daily hashed client counters
+support usage limits and abuse controls. See [SECURITY.md](../SECURITY.md) and
 the [hosted-service terms](https://zero-slop.ai/terms/).
 
 `/v1` identifies the HTTP contract. `scorerVersion` identifies the deployed Zero Slop

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-slop",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "description": "Find and fix canned AI writing while preserving the facts, voice, and format.",
   "mcpServers": {
     "zero-slop": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-slop",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "description": "An editing skill, offline writing checks, and a CLI for the hosted Zero Slop MCP pipeline. Find stock AI phrasing, rewrite, and check source details.",
   "bin": {
     "zero-slop": "bin/zero-slop.mjs"

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "zero-slop",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "description": "Find and fix canned AI writing while preserving the facts, voice, and format.",
   "author": {
     "name": "Manav Mishra",