@deslop/scope 0.1.1208 → 0.1.1222

package/README.md

@@ -1,24 +1,11 @@
-# @deslop/scope
+# Scope
 
-An Effect development debugger: a private OTLP/HTTP JSON receiver on port 4318 whose traces and logs agents query through an OAuth-protected MCP endpoint on port 5000.
+An Effect development debugger: a public OTLP/HTTP JSON receiver, queried by agents through an OAuth-protected MCP endpoint reached through the [gateway](../gateway/README.md), and read by people at `https://scope.mp281x.xyz`.
 
-```bash
-npx @deslop/scope@latest                                    # http://127.0.0.1:4318, data in ~/.deslop/scope
-claude mcp add --transport http scope https://scope.mp281x.xyz/mcp
-claude mcp login scope --no-browser
-codex mcp add scope --url https://scope.mp281x.xyz/mcp
-codex mcp login --no-browser scope
-```
-
-Trusted local exporters use `http://127.0.0.1:4318/v1/traces` and `/v1/logs` with `content-type: application/json`; never publish port 4318 to the internet. The public port serves MCP and authenticated ingestion. `HOST` changes the bind address; `PORT` changes the public port. Authorization uses Deslop Auth; no pasted API keys.
-
-## Connection diagnostics
-
-Stored OAuth credentials do not prove the MCP connection works. Check the client's MCP status and tool discovery: Scope exposes the tools below. If startup reports `OAuth authorization required`, sign in again with that client's login command above. An auth-store reset invalidates previously saved credentials.
-
-Open the printed authorization URL in a browser on the same worker as the client. Leave it waiting: it shows a QR code and a code, which you scan with a phone where you are signed in or enter at https://auth.mp281x.xyz. The worker's browser completes its localhost callback. Do not move the callback to the phone.
-
-The public `/.well-known/oauth-protected-resource/mcp` document names the authorization server. A request without credentials gets a 401 discovery challenge; a rejected bearer adds `error="invalid_token"` and requires sign-in again. An unavailable authorization server returns 503 with `Retry-After`, not a false invalid-token challenge.
+- **Runs** on dev as a service; entries under `entries/` in its data directory for three days by exporter time, at most 10 MB per export.
+- **Exporters**: `https://scope.mp281x.xyz/v1/traces` and `/v1/logs`, `content-type: application/json`, from any origin without credentials; apps pass `--traces https://scope.mp281x.xyz`, phones export there directly.
+- **MCP and the web page** need a Deslop sign-in through [Auth](../auth/README.md); no API keys.
+- **Web page**: the traces of the last three days by service, each opened as a waterfall with its spans' attributes and logs; its RPCs (`scope.services`, `scope.traces`, `scope.trace`) answer what `list_services`, `find` and `read_trace` do.
 
 | Tool              | Returns                                                                                                    |
 | ----------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -27,10 +14,11 @@ The public `/.well-known/oauth-protected-resource/mcp` document names the author
 | `measure_latency` | Span count, errors and p50, p95 and max latency over the whole window                                      |
 | `read_trace`      | One stored trace whole, including earlier runs, with parent order, offsets and logs                        |
 
-Entries persist under `~/.deslop/scope/entries/` for three days, by their exporter time.
-
 ## Ingestion health
 
-Start with `list_services`. `lastEventAt` and `runStartedAt` are Unix nanoseconds from the exporter clock, not receiver arrival times; a zero run marker means the exporter supplied no valid run start. `entries` counts records from that service's latest run. A missing service has no retained telemetry, not proof that it is healthy.
+Start with `list_services`.
 
-Rejected requests are counted on both ingestion ports by route, HTTP status and credential-header presence (`authorization`, `cookie` or `none`). These counts cannot identify the exporting app, and anonymous public visitors also produce 401s. No credentials or request bodies are kept. `since` and each rejection's `lastAt` are receiver-clock Unix milliseconds; counters reset when Scope restarts. Scope does not export its own diagnostic traffic back into itself.
+- **Times**: `lastEventAt` and `runStartedAt` are exporter-clock Unix nanoseconds; a zero run marker means no valid run start was exported.
+- **`entries`** counts the latest run only; a missing service has no retained telemetry, which proves nothing about its health.
+- **Rejections** per route, status and credential header (`authorization`, `cookie`, `none`); they can't name the app. No credentials or bodies kept. `since` and `lastAt` are receiver-clock Unix milliseconds; counters reset on restart.
+- **No self-export**: Scope's own diagnostic traffic stays out of it.