docs: refine JSDoc usage guidance

.agents/skills/jsdocs/SKILL.md

@@ -81,6 +81,12 @@ Use a normal multiline JSDoc comment in TypeScript source:
 - `**When to use**` describes the positive use case for the documented API. Do not use it as a routing section for sibling APIs. If neighboring APIs need to be mentioned, put that boundary in `@see` tag text instead.
 - `**When to use**` is important when the API has close alternatives, trade-offs, or `@see` tags. If `@see` tags are present, inspect the referenced APIs and add `**When to use**` when it clarifies the documented API's own use case.
 - `**When to use**` must start with one of these practical guidance forms: `Use to`, `Use when`, `Use as`, or `Use with`. Avoid bullet lists and vague openers such as `Use this...` or `Useful for...`.
+- Prefer reader-centered `**When to use**` wording, especially `Use when you ...`,
+  when the sentence describes a user's goal. Avoid third-person noun-phrase
+  subjects such as `the input is ...`, `a service needs ...`, or
+  `values should ...` when they would become awkward in generated prompts.
+- A good `**When to use**` sentence should still read naturally if reused as
+  a user intent prompt, for example after `I need ...` or `I have ...`.
 - Keep `short` and `**When to use**` distinct: the short description says what
   the API is or does; `**When to use**` says when to choose it.
 - Add internal `@see` tags only for semantically useful related public APIs.

.changeset/remove-types-mergerecord.md

@@ -0,0 +1,5 @@
+---
+"effect": patch
+---
+
+Remove the `Types.MergeRecord` alias. Use `Types.MergeLeft` instead.

.changeset/schema-parser-adapter-errors.md

@@ -0,0 +1,5 @@
+---
+"effect": patch
+---
+
+Align Schema adapter failures: `Schema` result, promise, and sync adapters now surface `SchemaError`, while `SchemaParser` result, promise, and sync adapters expose `SchemaIssue.Issue`. Mark `SchemaParser` option adapters as internal because their error details are discarded.

packages/ai/anthropic/src/AnthropicConfig.ts

@@ -29,8 +29,8 @@ import type { HttpClient } from "effect/unstable/http/HttpClient"
  *
  * **When to use**
  *
- * Use when a layer or integration needs to provide or read Anthropic client
- * configuration through Effect's context.
+ * Use when you need to provide or read Anthropic client configuration through
+ * Effect's context from a layer or integration.
  *
  * @see {@link withClientTransform} for scoping an HTTP client transformation
  *

packages/ai/anthropic/src/AnthropicLanguageModel.ts

@@ -7,13 +7,12 @@
  *
  * **When to use**
  *
- * Use when create an Anthropic-backed model with {@link model}
- * - Build or provide a `LanguageModel.LanguageModel` layer with {@link layer}
- *   or {@link make}
- * - Supply default request options through {@link Config}
- * - Override configuration for a scoped operation with {@link withConfigOverride}
- * - Attach Anthropic provider options for prompt caching, document citations,
- *   reasoning signatures, MCP metadata, and server-side tools
+ * Use when you need an Anthropic-backed model. Create a model with {@link model},
+ * build or provide a `LanguageModel.LanguageModel` layer with {@link layer} or
+ * {@link make}, supply default request options through {@link Config}, override
+ * configuration for a scoped operation with {@link withConfigOverride}, or attach
+ * Anthropic provider options for prompt caching, document citations, reasoning
+ * signatures, MCP metadata, and server-side tools.
  *
  * **Gotchas**
  *
@@ -82,13 +81,14 @@ export type Model = typeof Generated.Model.Type
  *
  * **When to use**
  *
- * Use when you need to provide or override Anthropic model configuration on a
- * per-request basis via `Context.Service`.
+ * Use when you need scoped Anthropic model request defaults or per-operation
+ * overrides from Effect context.
  *
  * **Details**
  *
- * This service can be used to provide default configuration values or to
- * override configuration on a per-request basis.
+ * The service stores request fields that are merged into Anthropic Messages API
+ * requests. Scoped configuration overrides defaults supplied to `model`,
+ * `make`, or `layer`.
  *
  * @category configuration
  * @since 4.0.0
@@ -669,8 +669,8 @@ export const model = (
  *
  * **When to use**
  *
- * Use when an Effect needs to construct a `LanguageModel.Service` value backed
- * by `AnthropicClient`.
+ * Use when you need to construct a `LanguageModel.Service` value backed by
+ * `AnthropicClient` inside an Effect.
  *
  * **Details**
  *

packages/ai/anthropic/src/AnthropicTool.ts

@@ -104,8 +104,8 @@ export type AnthropicTool =
  *
  * **When to use**
  *
- * Use when you need the model to execute bash commands and require the 2024-10-22
- * version of the Anthropic computer-use beta.
+ * Use when you want the model to execute bash commands with the 2024-10-22
+ * Anthropic computer-use beta.
  *
  * **Details**
  *
@@ -134,8 +134,8 @@ export const Bash_20241022 = Tool.providerDefined({
  *
  * **When to use**
  *
- * Use when you need the model to execute bash commands and require the 2025-01-24
- * version of the Anthropic computer-use beta.
+ * Use when you want the model to execute bash commands with the 2025-01-24
+ * Anthropic computer-use beta.
  *
  * **Details**
  *
@@ -250,8 +250,8 @@ export type CodeExecutionBashCommand = typeof CodeExecutionBashCommand.Type
  *
  * **When to use**
  *
- * Use to validate or construct the `view` command for Anthropic code execution
- * text editor tool calls.
+ * Use when you need the schema for provider-bound code-execution view requests
+ * before distinguishing them from create or replace text-editor commands.
  *
  * **Details**
  *
@@ -277,8 +277,8 @@ export const CodeExecutionTextEditorView = Schema.Struct({
  *
  * **When to use**
  *
- * Use when handling or validating the `view` command for Anthropic's text
- * editor code execution tool.
+ * Use when working at the Anthropic protocol boundary and the code-execution
+ * view request must be distinguished from standalone text-editor view requests.
  *
  * **Details**
  *
@@ -400,8 +400,8 @@ const CodeExecution_20250522_Parameters = Schema.Union([
  *
  * **When to use**
  *
- * Use when validating or constructing the input payload for the 2025-08-25
- * Anthropic code execution tool.
+ * Use when you need the schema for code-execution input at the Anthropic
+ * protocol boundary before sending source code to the 2025-08-25 tool.
  *
  * @see {@link CodeExecution_20250825} for the provider-defined tool that consumes this schema
  *
@@ -419,7 +419,8 @@ export const CodeExecution_20250825_Parameters = Schema.Struct({
  *
  * **When to use**
  *
- * Use when typing input passed to the 2025-08-25 Anthropic code execution tool.
+ * Use when exposing the 2025-08-25 code-execution payload separately from the
+ * provider tool definition, such as at a transport or persistence boundary.
  *
  * **Details**
  *
@@ -442,8 +443,8 @@ export type CodeExecution_20250825_Parameters = typeof CodeExecution_20250825_Pa
  *
  * **When to use**
  *
- * Use when you need the model to execute code in a sandboxed environment and
- * require the 2025-05-22 version of the Anthropic code-execution beta.
+ * Use when you want the model to execute code in a sandboxed environment with
+ * the 2025-05-22 Anthropic code-execution beta.
  *
  * **Details**
  *
@@ -470,8 +471,8 @@ export const CodeExecution_20250522 = Tool.providerDefined({
  *
  * **When to use**
  *
- * Use when you need the model to execute code in a sandboxed environment and
- * require the 2025-08-25 version of the Anthropic code-execution beta.
+ * Use when you want the model to execute code in a sandboxed environment with
+ * the 2025-08-25 Anthropic code-execution beta.
  *
  * **Details**
  *
@@ -514,6 +515,11 @@ export const CodeExecution_20250825 = Tool.providerDefined({
 /**
  * Schema for an `[x, y]` screen coordinate in pixels.
  *
+ * **When to use**
+ *
+ * Use when validating computer-use action payloads that carry a single screen
+ * position and provider-side bounds checks remain acceptable.
+ *
  * **Details**
  *
  * This is a two-number tuple used by computer-use actions that accept screen
@@ -538,6 +544,11 @@ export type Coordinate = typeof Coordinate.Type
 /**
  * Schema for an `[x1, y1, x2, y2]` screen region in pixels.
  *
+ * **When to use**
+ *
+ * Use when validating computer-use action payloads that carry a rectangular
+ * screen region and provider-side bounds checks remain acceptable.
+ *
  * **Details**
  *
  * The tuple represents top-left and bottom-right corners.
@@ -656,6 +667,12 @@ export const ComputerUseKeyAction = Schema.Struct({
 /**
  * Computer-use action payload for pressing a key or key combination.
  *
+ * **When to use**
+ *
+ * Use when typing parsed computer-use key action payloads after schema
+ * validation, where provider-specific key-name validation is handled outside
+ * TypeScript.
+ *
  * **Details**
  *
  * The payload uses `action: "key"` and stores the key or key combination to
@@ -1250,6 +1267,11 @@ const ComputerUse_20250124_Actions = Schema.Union([
 /**
  * Zooms into a specific region of the screen at full resolution.
  *
+ * **When to use**
+ *
+ * Use when building or validating the 2025-11-24 computer-use action for a
+ * zoom-enabled tool definition.
+ *
  * **Details**
  *
  * The encoded payload uses `action: "zoom"` and a `region` tuple.
@@ -1322,7 +1344,7 @@ export const ComputerUse_20241022 = Tool.providerDefined({
  *
  * **When to use**
  *
- * Use when configuring Anthropic computer use for Claude 4 models or Claude
+ * Use when you need Anthropic computer use for Claude 4 models or Claude
  * Sonnet 3.7 with the 2025-01-24 action set.
  *
  * **Details**
@@ -1353,7 +1375,7 @@ export const ComputerUse_20250124 = Tool.providerDefined({
  *
  * **When to use**
  *
- * Use when configuring Anthropic computer use for Claude Opus 4.5 with the
+ * Use when you need Anthropic computer use for Claude Opus 4.5 with the
  * 2025-11-24 action set and zoom-capable screen inspection.
  *
  * **Details**
@@ -1734,6 +1756,11 @@ export const TextEditorCreateCommand = Schema.Struct({
 /**
  * Text editor command payload for creating a new file with the specified content.
  *
+ * **When to use**
+ *
+ * Use when typing parsed text-editor create command payloads after schema
+ * validation and before dispatching to Anthropic tool handlers.
+ *
  * **Gotchas**
  *
  * The command fails if the file already exists or if parent directories are missing.
@@ -1785,6 +1812,11 @@ export const TextEditorStrReplaceCommand = Schema.Struct({
 /**
  * Text editor command payload for replacing one exact, unique string in a file.
  *
+ * **When to use**
+ *
+ * Use when typing parsed text-editor replace command payloads that must carry
+ * one exact `old_str` match.
+ *
  * **Gotchas**
  *
  * The `old_str` must match exactly, including whitespace and indentation, and
@@ -1902,8 +1934,8 @@ const TextEditor_StrReplaceBasedEdit_Args = Schema.Struct({
  *
  * **When to use**
  *
- * Use when configuring the 2024-10-22 `str_replace_editor` compatibility path
- * for Claude 3.5 Sonnet.
+ * Use when you need the 2024-10-22 `str_replace_editor` compatibility path for
+ * Claude 3.5 Sonnet.
  *
  * **Details**
  *
@@ -1930,7 +1962,7 @@ export const TextEditor_20241022 = Tool.providerDefined({
  *
  * **When to use**
  *
- * Use when configuring the 2025-01-24 Claude Sonnet 3.7 text editor tool using
+ * Use when you need the 2025-01-24 Claude Sonnet 3.7 text editor tool using
  * `str_replace_editor`.
  *
  * **Details**
@@ -1958,7 +1990,7 @@ export const TextEditor_20250124 = Tool.providerDefined({
  *
  * **When to use**
  *
- * Use when configuring the 2025-04-29 Claude 4 `str_replace_based_edit_tool`
+ * Use when you need the 2025-04-29 Claude 4 `str_replace_based_edit_tool`
  * version.
  *
  * **Details**
@@ -2023,8 +2055,8 @@ export const TextEditor_20250728 = Tool.providerDefined({
  *
  * **When to use**
  *
- * Use when providing location helps return more relevant results for
- * location-dependent queries like weather, local businesses, or events.
+ * Use when you need to localize search results for location-dependent queries
+ * like weather, local businesses, or events.
  *
  * **Details**
  *
@@ -2069,8 +2101,8 @@ export const WebSearchUserLocation = Schema.Struct({
  *
  * **When to use**
  *
- * Use when configuring `WebSearch_20250305` with search limits, domain filters,
- * or user location.
+ * Use when you need to configure `WebSearch_20250305` with search limits,
+ * domain filters, or user location.
  *
  * **Details**
  *
@@ -2167,7 +2199,7 @@ export type WebSearchParameters = typeof WebSearchParameters.Type
  *
  * **When to use**
  *
- * Use when Claude should search the web for real-time information.
+ * Use when you want Claude to search the web for real-time information.
  *
  * **Details**
  *
@@ -2203,7 +2235,7 @@ export const WebSearch_20250305 = Tool.providerDefined({
  *
  * **When to use**
  *
- * Use when configuring whether web fetch results should include citations.
+ * Use when you need to enable or disable citations on web fetch results.
  *
  * **Details**
  *
@@ -2224,6 +2256,11 @@ export const WebFetchCitationsConfig = Schema.Struct({
 /**
  * Configuration payload for enabling or disabling citations on web fetch results.
  *
+ * **When to use**
+ *
+ * Use when typing parsed web-fetch citation configuration shared between
+ * request arguments and handler code.
+ *
  * **Details**
  *
  * The payload contains the `enabled` flag. `citations` is optional on
@@ -2245,8 +2282,8 @@ export type WebFetchCitationsConfig = typeof WebFetchCitationsConfig.Type
  *
  * **When to use**
  *
- * Use when configuring `WebFetch_20250910` with usage limits, domain filters,
- * citations, or content token limits.
+ * Use when you need to configure `WebFetch_20250910` with usage limits, domain
+ * filters, citations, or content token limits.
  *
  * **Details**
  *
@@ -2294,6 +2331,11 @@ export const WebFetch_20250910_Args = Schema.Struct({
 /**
  * Configuration arguments for the Anthropic web fetch tool, including usage limits, domain filters, citation settings, and token limits.
  *
+ * **When to use**
+ *
+ * Use when typing parsed web-fetch tool configuration shared by the
+ * provider-defined tool and request-building code.
+ *
  * **Gotchas**
  *
  * `allowedDomains` and `blockedDomains` are mutually exclusive.
@@ -2341,6 +2383,11 @@ export const WebFetchParameters = Schema.Struct({
 /**
  * Type of the parameters Claude supplies when invoking the Anthropic web fetch tool.
  *
+ * **When to use**
+ *
+ * Use when typing Claude-supplied web-fetch tool parameters after schema
+ * validation, before enforcing URL provenance or length constraints.
+ *
  * **Details**
  *
  * The payload contains the single `url` parameter for Anthropic web fetch.
@@ -2364,7 +2411,8 @@ export type WebFetchParameters = typeof WebFetchParameters.Type
  *
  * **When to use**
  *
- * Use when Claude should retrieve the content of a specific web page or PDF.
+ * Use when you want Claude to retrieve the content of a specific web page or
+ * PDF.
  *
  * **Details**
  *