vybekiit 0.7.25 → 0.7.27

package/dist/global-skills/workers-best-practices/SKILL.md

@@ -1,115 +1,55 @@
 ---
 name: workers-best-practices
-description: Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
+description: Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
 ---
 
-Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. **Prefer retrieval over pre-training** for any Workers code task — writing or reviewing.
+Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. **Prefer retrieval over pre-training** when writing or reviewing Workers code.
 
-## Retrieval Sources
+Use the project's installed versions, generated types, and Wrangler compatibility settings as the baseline for existing code. Retrieve relevant Cloudflare documentation to verify API, configuration, runtime behavior, and limit claims.
 
-Fetch the **latest** versions before writing or reviewing Workers code. Do not rely on baked-in knowledge for API signatures, config fields, or binding shapes.
+## References
 
-| Source | How to retrieve | Use for |
-|--------|----------------|---------|
-| Workers best practices | Fetch `https://developers.cloudflare.com/workers/best-practices/workers-best-practices/` | Canonical rules, patterns, anti-patterns |
-| Workers types | See `references/review.md` for retrieval steps | API signatures, handler types, binding types |
-| Wrangler config schema | `node_modules/wrangler/config-schema.json` | Config fields, binding shapes, allowed values |
-| Cloudflare docs | Search tool or `https://developers.cloudflare.com/workers/` | API reference, compatibility dates/flags |
+Read the sections relevant to the task:
 
-## FIRST: Fetch Latest References
+| Reference | When to use it |
+|-----------|----------------|
+| [Configuration and observability](references/configuration.md) | Compatibility dates, bindings, generated types, secrets, logs, and traces |
+| [Runtime patterns](references/runtime-patterns.md) | Streaming, promise lifetime, request state, service calls, security, and runtime tests |
+| [Platform API checks](references/platform-apis.md) | Handler signatures, platform classes, binding access, and serialization |
 
-Before reviewing or writing Workers code, retrieve the current best practices page and relevant type definitions. If the project's `node_modules` has an older version, **prefer the latest published version**.
+For missing evidence, consult [Workers best practices](https://developers.cloudflare.com/workers/best-practices/workers-best-practices/) or find the affected product in the [Cloudflare docs directory](https://developers.cloudflare.com/directory/). Use the installed Wrangler schema for config fields. A newer type package does not supersede the project's configured target.
 
-```bash
-# Fetch latest workers types
-mkdir -p /tmp/workers-types-latest && \
-  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
-  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
-# Types at /tmp/workers-types-latest/package/index.d.ts
-```
+## Keep Compatibility Dates Current
 
-## Reference Documentation
+Use today's date for new Workers. Encourage periodic updates for existing Workers, reviewing compatibility changes and running relevant tests. Assess existing behavior against its configured date and flags; see [compatibility guidance](references/configuration.md#keep-compatibility_date-current).
 
-- `references/rules.md` — all best practice rules with code examples and anti-patterns
-- `references/review.md` — type validation, config validation, binding access patterns, review process
+## Enable Observability
 
-## Rules Quick Reference
-
-### Configuration
-
-| Rule | Summary |
-|------|---------|
-| Compatibility date | Set `compatibility_date` to today on new projects; update periodically on existing ones |
-| nodejs_compat | Enable the `nodejs_compat` flag — many libraries depend on Node.js built-ins |
-| wrangler types | Run `wrangler types` to generate `Env` — never hand-write binding interfaces |
-| Secrets | Use `wrangler secret put`, never hardcode secrets in config or source |
-| wrangler.jsonc | Use JSONC config for non-secret settings — newer features are JSON-only |
-
-### Request & Response Handling
-
-| Rule | Summary |
-|------|---------|
-| Streaming | Stream large/unknown payloads — never `await response.text()` on unbounded data |
-| waitUntil | Use `ctx.waitUntil()` for post-response work; do not destructure `ctx` |
-
-### Architecture
-
-| Rule | Summary |
-|------|---------|
-| Bindings over REST | Use in-process bindings (KV, R2, D1, Queues) — not the Cloudflare REST API |
-| Queues & Workflows | Move async/background work off the critical path |
-| Service bindings | Use service bindings for Worker-to-Worker calls — not public HTTP |
-| Hyperdrive | Always use Hyperdrive for external PostgreSQL/MySQL connections |
-
-### Observability
-
-| Rule | Summary |
-|------|---------|
-| Logs & Traces | Enable `observability` in config with `head_sampling_rate`; use structured JSON logging |
-
-### Code Patterns
-
-| Rule | Summary |
-|------|---------|
-| No global request state | Never store request-scoped data in module-level variables |
-| Floating promises | Every Promise must be `await`ed, `return`ed, `void`ed, or passed to `ctx.waitUntil()` |
-
-### Security
-
-| Rule | Summary |
-|------|---------|
-| Web Crypto | Use `crypto.randomUUID()` / `crypto.getRandomValues()` — never `Math.random()` for security |
-| No passThroughOnException | Use explicit try/catch with structured error responses |
+Enable [Workers Logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/) and [Traces](https://developers.cloudflare.com/workers/observability/traces/) when creating or preparing a Worker for production. Set `observability.enabled` and `observability.traces.enabled` to `true`; the top-level setting alone does not enable traces. Use structured JSON logging and configure sampling for the workload. During reviews, flag missing logs or traces. See the [configuration example](references/configuration.md#enable-workers-logs-and-traces).
 
 ## Anti-Patterns to Flag
 
-| Anti-pattern | Why it matters |
-|-------------|----------------|
-| `await response.text()` on unbounded data | Memory exhaustion — 128 MB limit |
-| Hardcoded secrets in source or config | Credential leak via version control |
-| `Math.random()` for tokens/IDs | Predictable, not cryptographically secure |
-| Bare `fetch()` without `await` or `waitUntil` | Floating promise — dropped result, swallowed error |
-| Module-level mutable variables for request state | Cross-request data leaks, stale state, I/O errors |
-| Cloudflare REST API from inside a Worker | Unnecessary network hop, auth overhead, added latency |
-| `ctx.passThroughOnException()` as error handling | Hides bugs, makes debugging impossible |
-| Hand-written `Env` interface | Drifts from actual wrangler config bindings |
-| Direct string comparison for secret values | Timing side-channel — use `crypto.subtle.timingSafeEqual` |
-| Destructuring `ctx` (`const { waitUntil } = ctx`) | Loses `this` binding — throws "Illegal invocation" at runtime |
-| `any` on `Env` or handler params | Defeats type safety for all binding access |
-| `as unknown as T` double-cast | Hides real type incompatibilities — fix the design |
-| `implements` on platform base classes (instead of `extends`) | Legacy — loses `this.ctx`, `this.env`. Applies to DurableObject, WorkerEntrypoint, Workflow |
-| `env.X` inside platform base class | Should be `this.env.X` in classes extending DurableObject, WorkerEntrypoint, etc. |
-
-## Review Workflow
-
-1. **Retrieve** — fetch latest best practices page, workers types, and wrangler schema
-2. **Read full files** — not just diffs; context matters for binding access patterns
-3. **Check types** — binding access, handler signatures, no `any`, no unsafe casts (see `references/review.md`)
-4. **Check config** — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
-5. **Check patterns** — streaming, floating promises, global state, serialization boundaries
-6. **Check security** — crypto usage, secret handling, timing-safe comparisons, error handling
-7. **Validate with tools** — `npx tsc --noEmit`, lint for `no-floating-promises`
-8. **Reference rules** — see `references/rules.md` for each rule's correct pattern
+| Anti-pattern | Consequence and preferred pattern |
+|-------------|-----------------------------------|
+| `await response.text()` or similar buffering on unbounded data | Can exhaust Worker memory; [stream large or unbounded bodies](references/runtime-patterns.md#stream-request-and-response-bodies). |
+| Hardcoded secrets in source or config | Leaks credentials through version control; use Wrangler secrets. |
+| `Math.random()` for security-sensitive tokens or IDs | Predictable values; use `crypto.randomUUID()` or `crypto.getRandomValues()`. |
+| Async work started without awaiting, returning, or attaching it to `ctx.waitUntil()` | Work can be dropped and errors missed; tie it to the request or background-work lifetime. |
+| Module-level mutable request state | Leaks data across requests and can cause I/O ownership errors; pass request state explicitly. |
+| Cloudflare REST API calls for operations available through Worker bindings | Adds network and authentication overhead; use the available binding. |
+| `ctx.passThroughOnException()` used as general error handling | Can conceal Worker failures by forwarding to the origin; use explicit error handling and structured error responses. |
+| Hand-written `Env` that duplicates Wrangler bindings | Can drift from configuration; generate binding types with `wrangler types`. |
+| Direct string comparison of secret values | Can expose timing differences; use the [Web Crypto comparison pattern](references/runtime-patterns.md#use-web-crypto-for-secure-token-generation). |
+| Destructuring `ctx` methods, such as `const { waitUntil } = ctx` | Loses the receiver; call `ctx.waitUntil(...)`. |
+| `any` on `Env` or handler parameters | Hides binding and handler contract errors; use the project's generated and platform types. |
+| `as unknown as T` to force a platform type match | Hides incompatibilities; fix the underlying contract. |
+| `implements` used in place of extending a platform base class | Does not inherit runtime behavior, `this.ctx`, or `this.env`; use the appropriate base class. |
+| Unbound `env.X` in a platform class method | Bindings are available through `this.env.X`; see [binding access patterns](references/platform-apis.md#binding-access--the-most-common-error). |
+| Applying one serialization rule across Queues, Workflow steps, storage, and WebSockets | Can reject valid payloads or accept unsupported ones; check the [specific API and encoding](references/platform-apis.md#serialization-boundaries). |
+
+## Validation
+
+Use the project's existing checks for affected Workers behavior: type-check binding or handler contract changes, and run relevant runtime tests for behavior changes. Preserve required repository checks; a narrow edit does not require a full Workers audit.
 
 ## Scope
 
@@ -118,10 +58,3 @@ This skill covers Workers-specific best practices and code review. For related t
 - **Durable Objects**: load the `durable-objects` skill
 - **Workflows**: see [Rules of Workflows](https://developers.cloudflare.com/workflows/build/rules-of-workflows/)
 - **Wrangler CLI commands**: load the `wrangler` skill
-
-## Principles
-
-- **Be certain.** Retrieve before flagging. If unsure about an API, config field, or pattern, fetch the docs first.
-- **Provide evidence.** Reference line numbers, tool output, or docs links.
-- **Focus on what developers will copy.** Workers code in examples and docs gets pasted into production.
-- **Correctness over completeness.** A concise example that works beats a comprehensive one with errors.

package/dist/global-skills/workers-best-practices/references/configuration.md

@@ -0,0 +1,139 @@
+# Workers Configuration and Observability
+
+Use the project's Wrangler configuration and installed `node_modules/wrangler/config-schema.json` to check fields and binding declarations. Consult current product docs when a field or compatibility requirement needs verification. Doc paths below are relative to `https://developers.cloudflare.com`.
+
+- [Configuration](#configuration): compatibility dates, Node.js compatibility, generated types, secrets, and config format
+- [Binding consistency](#binding-code-consistency): configuration and code agree
+- [Observability](#observability): enable logs and traces, configure sampling, and emit structured logs
+
+## Configuration
+
+### Keep compatibility_date current
+
+Set `compatibility_date` to today on new projects. Encourage periodic updates on existing projects to adopt new runtime behavior and fixes. Review the intervening compatibility changes and run relevant tests when advancing the date.
+
+**Check**: `compatibility_date` exists and supports the affected feature with the configured flags. Recommend updates as maintenance; flag a compatibility defect when the configured date or flags do not support the required behavior.
+
+```jsonc
+// wrangler.jsonc
+{
+  "compatibility_date": "$today",  // Replace with today's date (YYYY-MM-DD)
+  "compatibility_flags": ["nodejs_compat"]
+}
+```
+
+**Retrieve**: current compatibility dates at `/workers/configuration/compatibility-dates/`.
+
+### Enable nodejs_compat
+
+The `nodejs_compat` flag enables Node.js built-in modules (`node:crypto`, `node:buffer`, `node:stream`). Many libraries require it. Missing this flag causes cryptic import errors at runtime.
+
+**Check**: `compatibility_flags` includes `"nodejs_compat"`.
+
+```jsonc
+{
+  "compatibility_flags": ["nodejs_compat"]
+}
+```
+
+### Generate binding types with wrangler types
+
+Never hand-write the `Env` interface. Run `wrangler types` to generate it from the wrangler config. Re-run after adding or renaming any binding.
+
+**Check**: no manually defined `Env` or `interface Env` that duplicates wrangler config bindings. Look for `satisfies ExportedHandler<Env>` pattern on the default export.
+
+```ts
+// Generated by wrangler types — always matches actual config
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const value = await env.MY_KV.get("key");
+    return new Response(value);
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+Anti-pattern:
+```ts
+// Hand-written Env that drifts from actual bindings
+interface Env {
+  MY_KV: KVNamespace;  // What if the binding name changed?
+}
+```
+
+### Store secrets with wrangler secret
+
+Secrets must never appear in wrangler config or source code. Use `wrangler secret put` and access via `env` at runtime. Non-secret config goes in `vars`.
+
+**Check**: no string literals that look like API keys, tokens, or credentials. Verify `.env` is in `.gitignore` for local dev.
+
+```jsonc
+{
+  "vars": {
+    "API_BASE_URL": "https://api.example.com"  // Non-secret: OK in config
+  }
+  // Secrets set via: wrangler secret put API_KEY
+}
+```
+
+Anti-pattern:
+```jsonc
+{
+  "vars": {
+    "API_KEY": "sk-live-abc123..."  // Secret in version control
+  }
+}
+```
+
+### Use wrangler.jsonc for config
+
+Prefer `wrangler.jsonc` over `wrangler.toml`. Newer features are JSON-only. JSONC supports comments for documenting config decisions.
+
+**Check**: project uses `wrangler.jsonc` (or `wrangler.json`). Flag `wrangler.toml` in new projects.
+
+---
+
+### Binding-code consistency
+
+For executable Worker examples, verify `name`, `compatibility_date`, and `main` against the target Wrangler schema.
+
+1. Every `env.X` reference in code has a corresponding binding declaration in config
+2. Names match exactly (case-sensitive)
+3. For Durable Objects: `class_name` matches the exported class name
+
+An unused binding alone is not a finding; establish a concrete configuration or runtime consequence before recommending a change.
+
+For a new Durable Object class, verify its migration entry and exported class name against the target Wrangler schema.
+
+## Observability
+
+### Enable Workers Logs and Traces
+
+Enable Workers Logs and Traces in Wrangler config before deploying to production. Set `observability.enabled` and `observability.traces.enabled` to `true`; the top-level setting alone does not enable traces. Use `head_sampling_rate` to control volume and cost. Use structured JSON logging — `console.log(JSON.stringify({...}))` — so logs are searchable. Use `console.error` for errors (appears at error severity in the dashboard).
+
+**Check**: logs and traces are enabled in the target deployment environment, with neither disabled by an environment override. Check `observability.enabled`, `observability.logs.enabled`, and `observability.traces.enabled`, accounting for their defaults. Logging uses structured JSON, not string concatenation.
+
+```jsonc
+{
+  "observability": {
+    "enabled": true,
+    "logs": { "enabled": true, "head_sampling_rate": 1 },
+    "traces": { "enabled": true, "head_sampling_rate": 0.01 }
+  }
+}
+```
+
+```ts
+// Structured JSON — searchable and filterable
+console.log(JSON.stringify({ message: "incoming request", method: request.method, path: url.pathname }));
+
+// Error severity
+console.error(JSON.stringify({ message: "request failed", error: e instanceof Error ? e.message : String(e) }));
+```
+
+Anti-pattern:
+```ts
+// Unstructured string logs — hard to query
+console.log("Got a request to " + url.pathname);
+```
+
+**Retrieve**: [Workers Logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/) and [Traces](https://developers.cloudflare.com/workers/observability/traces/) for current config options.

package/dist/global-skills/workers-best-practices/references/platform-apis.md

@@ -0,0 +1,51 @@
+# Workers Platform API Checks
+
+Use the project's installed and generated types to check affected handlers and bindings. Consult current Cloudflare docs when API or runtime compatibility remains uncertain.
+
+- [Type validation](#type-validation): binding types, handler signatures, and platform classes
+- [Serialization boundaries](#serialization-boundaries): encoding and supported values for each API
+
+## Type Validation
+
+### Env interface
+
+- Every binding must have a specific type. Flag `any`, `unknown`, `object`, or `Record<string, unknown>` on bindings.
+- Binding types that accept generic parameters (Durable Object namespaces, Queues, Service bindings for RPC) must include them. Read the type definition to confirm which types are generic.
+- Use the project's generated binding types; see [configuration guidance](configuration.md#generate-binding-types-with-wrangler-types).
+
+### Handler and class signatures
+
+Verify affected signatures against the project's target type definitions; consult current docs if runtime support or compatibility remains uncertain.
+
+- Correct import path (most Workers platform classes import from `"cloudflare:workers"`)
+- Generic type parameter on base classes (e.g., `DurableObject<Env>`)
+- `ExecutionContext` as the third param in module export handlers (needed for `ctx.waitUntil()`)
+- `fetch()` handlers must return `Promise<Response>`
+
+### Binding access — the most common error
+
+- **Module export handlers** (`fetch`, `scheduled`, `queue`, `email`): bindings via `env.X` parameter
+- **Platform base classes** (`WorkerEntrypoint`, `DurableObject`, `Workflow`, `Agent`): bindings via `this.env.X`
+
+Flag `env.X` inside a class extending a platform base class. Flag `this.env.X` inside a module export handler.
+
+### Stale class patterns
+
+Old patterns survive in codebases long after APIs change.
+
+- **`extends` vs `implements`**: platform classes use `extends`, not `implements`. The `implements` pattern is legacy and loses `this.ctx`, `this.env`.
+- **Import paths**: verify module specifiers match what types actually export. Common mistake: wrong path for `"cloudflare:workers"` vs `"cloudflare:workflows"`.
+- **Renamed properties**: e.g., `this.state` to `this.ctx` in Durable Objects. Search types to confirm.
+- **Constructor signatures**: base class constructors change. Verify expected parameters.
+
+## Serialization Boundaries
+
+Check the API and encoding at each boundary. Structured clone support does not imply JSON compatibility or SQL parameter support.
+
+| Boundary | What to check |
+|----------|---------------|
+| [Queue messages](https://developers.cloudflare.com/queues/configuration/javascript-apis/#queuescontenttype) | Match the body to `contentType`: `json` requires JSON-compatible data, `text` a string, `bytes` an `ArrayBuffer`, and `v8` supports structured-clone values such as `Map` and `Date`. Check the configured compatibility date when relying on the default encoding. |
+| [Workflow step results](https://developers.cloudflare.com/workflows/build/workers-api/) | Verify the step result against the documented serialization contract and the project's Workflow types before flagging a value. |
+| [Durable Object KV storage](https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/#put-1) | `storage.put()` supports structured-clone values; do not apply a blanket ban on `Map` or `Set`. |
+| [Durable Object SQL](https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/#exec) | Check bound parameters against the SQL API's supported types. Encode objects explicitly for the intended column representation. |
+| [WebSocket messages](https://developers.cloudflare.com/workers/runtime-apis/websockets/#send) | Use `send()` with a string, `ArrayBuffer`, or `ArrayBufferView`; encode objects, for example with `JSON.stringify()`. |

package/dist/global-skills/workers-best-practices/references/{rules.md → runtime-patterns.md}

@@ -1,96 +1,12 @@
-# Workers Best Practices — Rules
+# Workers Runtime Patterns
 
-Each rule has an imperative summary, what to check, the correct pattern, and an anti-pattern where applicable. Code examples are plain TypeScript — no MDX components.
+Consult the sections relevant to the affected behavior. Examples show preferred patterns and common mistakes; **Retrieve** links identify documentation to check when an API, behavior, or limit is uncertain. Doc paths are relative to `https://developers.cloudflare.com`.
 
-When a rule involves config fields or API signatures that may evolve, a **Retrieve** callout reminds you to check the latest docs or types before flagging. All doc paths are relative to `https://developers.cloudflare.com`.
-
----
-
-## Configuration
-
-### Keep compatibility_date current
-
-Set `compatibility_date` to today on new projects. Update periodically on existing ones to access new APIs and fixes.
-
-**Check**: `compatibility_date` exists. Flag if older than 6 months.
-
-```jsonc
-// wrangler.jsonc
-{
-  "compatibility_date": "$today",  // Replace with today's date (YYYY-MM-DD)
-  "compatibility_flags": ["nodejs_compat"]
-}
-```
-
-**Retrieve**: current compatibility dates at `/workers/configuration/compatibility-dates/`.
-
-### Enable nodejs_compat
-
-The `nodejs_compat` flag enables Node.js built-in modules (`node:crypto`, `node:buffer`, `node:stream`). Many libraries require it. Missing this flag causes cryptic import errors at runtime.
-
-**Check**: `compatibility_flags` includes `"nodejs_compat"`.
-
-```jsonc
-{
-  "compatibility_flags": ["nodejs_compat"]
-}
-```
-
-### Generate binding types with wrangler types
-
-Never hand-write the `Env` interface. Run `wrangler types` to generate it from the wrangler config. Re-run after adding or renaming any binding.
-
-**Check**: no manually defined `Env` or `interface Env` that duplicates wrangler config bindings. Look for `satisfies ExportedHandler<Env>` pattern on the default export.
-
-```ts
-// Generated by wrangler types — always matches actual config
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    const value = await env.MY_KV.get("key");
-    return new Response(value);
-  },
-} satisfies ExportedHandler<Env>;
-```
-
-Anti-pattern:
-```ts
-// Hand-written Env that drifts from actual bindings
-interface Env {
-  MY_KV: KVNamespace;  // What if the binding name changed?
-}
-```
-
-### Store secrets with wrangler secret
-
-Secrets must never appear in wrangler config or source code. Use `wrangler secret put` and access via `env` at runtime. Non-secret config goes in `vars`.
-
-**Check**: no string literals that look like API keys, tokens, or credentials. Verify `.env` is in `.gitignore` for local dev.
-
-```jsonc
-{
-  "vars": {
-    "API_BASE_URL": "https://api.example.com"  // Non-secret: OK in config
-  }
-  // Secrets set via: wrangler secret put API_KEY
-}
-```
-
-Anti-pattern:
-```jsonc
-{
-  "vars": {
-    "API_KEY": "sk-live-abc123..."  // Secret in version control
-  }
-}
-```
-
-### Use wrangler.jsonc for config
-
-Prefer `wrangler.jsonc` over `wrangler.toml`. Newer features are JSON-only. JSONC supports comments for documenting config decisions.
-
-**Check**: project uses `wrangler.jsonc` (or `wrangler.json`). Flag `wrangler.toml` in new projects.
-
----
+- [Request and response handling](#request--response-handling): streaming, memory use, and post-response work
+- [Architecture](#architecture): bindings, Queues, Workflows, and database connections
+- [Code patterns](#code-patterns): request state, promise lifetime, and platform limits
+- [Security](#security): Web Crypto and error handling
+- [Development and testing](#development--testing): tests in the Workers runtime
 
 ## Request & Response Handling
 
@@ -141,6 +57,10 @@ return new Response(text);
 
 **Retrieve**: streaming APIs at `/workers/runtime-apis/streams/`.
 
+### Use Zod 4.5.0 or later
+
+**Check**: Workers using Zod for runtime validation depend on [Zod 4.5.0 or later](https://github.com/colinhacks/zod/releases/tag/v4.5.0); older versions retain substantially more heap per schema, so check the installed version when investigating high memory usage or OOMs.
+
 ### Use waitUntil for work after the response
 
 `ctx.waitUntil()` performs background work (analytics, cache writes, webhooks) after the response is sent. Keeps response fast. 30-second time limit after response.
@@ -234,7 +154,7 @@ export class AuthService extends WorkerEntrypoint {
 const auth = await env.AUTH_SERVICE.verifyToken(token);
 ```
 
-**Retrieve**: verify `WorkerEntrypoint` import path and signature against latest `@cloudflare/workers-types`.
+**Retrieve**: verify uncertain `WorkerEntrypoint` import paths or signatures against the project's target types, consulting current docs when runtime compatibility needs clarification.
 
 ### Use Hyperdrive for external database connections
 
@@ -263,42 +183,6 @@ async fetch(request: Request, env: Env): Promise<Response> {
 
 ---
 
-## Observability
-
-### Enable Workers Logs and Traces
-
-Enable `observability` in wrangler config before deploying to production. Use `head_sampling_rate` to control volume and cost. Use structured JSON logging — `console.log(JSON.stringify({...}))` — so logs are searchable. Use `console.error` for errors (appears at error severity in the dashboard).
-
-**Check**: `observability.enabled` is `true` in config. Logging uses structured JSON, not string concatenation.
-
-```jsonc
-{
-  "observability": {
-    "enabled": true,
-    "logs": { "head_sampling_rate": 1 },
-    "traces": { "enabled": true, "head_sampling_rate": 0.01 }
-  }
-}
-```
-
-```ts
-// Structured JSON — searchable and filterable
-console.log(JSON.stringify({ message: "incoming request", method: request.method, path: url.pathname }));
-
-// Error severity
-console.error(JSON.stringify({ message: "request failed", error: e instanceof Error ? e.message : String(e) }));
-```
-
-Anti-pattern:
-```ts
-// Unstructured string logs — hard to query
-console.log("Got a request to " + url.pathname);
-```
-
-**Retrieve**: `/workers/observability/logs/workers-logs/` and `/workers/observability/traces/` for current config options.
-
----
-
 ## Code Patterns
 
 ### Do not store request-scoped state in global scope
@@ -334,15 +218,7 @@ export default {
 
 A Promise that is not `await`ed, `return`ed, or passed to `ctx.waitUntil()` is a floating promise. Causes: dropped results, swallowed errors, unfinished work. The runtime may terminate the isolate before it completes.
 
-**Check**: every `fetch()`, `env.*.put()`, `env.*.send()`, and any other async call is handled. Enable `no-floating-promises` lint rule.
-
-```bash
-# ESLint
-npx eslint --rule '{"@typescript-eslint/no-floating-promises": "error"}' src/
-
-# oxlint
-npx oxlint --deny typescript/no-floating-promises src/
-```
+**Check**: async calls in the affected execution path are awaited, returned, or attached to the appropriate lifetime. Use the project's existing floating-promise lint check, such as Oxlint's [typescript/no-floating-promises](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-floating-promises.html), when available and relevant; otherwise inspect the promise paths directly. Adding lint tooling is a separate change, not a prerequisite for reviewing this behavior.
 
 ```ts
 // Correct: await when you need the result