DX-1211: rewrite Auth interface docstrings (prerequisites, side-effects, failure modes)

Apply docstringRules.md to the public Auth interface in ably.d.ts so silent and
architectural call-site prerequisites are discoverable at the call site:

- revokeTokens: basic-auth (API key, not token) requirement; non-code "revocable
  tokens enabled on the key" prerequisite, with a feature-page @see.
- requestToken: token-issuing prerequisite (authCallback/authUrl/key); callback
  contract detail (content-types, size flags) offloaded to the @see.
- createTokenRequest: a local API key must be available to sign the request.
- authorize: re-authenticates the live connection (resolves once the token takes
  effect on a connected connection), token-issuing prerequisite, and the RSA10a
  key-immutability rule (authorize() cannot change the API key).
- clientId: adds the canonical @see.

Folded prose, no numeric error codes; every behavioural method carries one simple
@example and every member an @see to the canonical JS API reference. TypeDoc
(treatWarningsAsErrors), eslint, and prettier are clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: umair-ably

ably.d.ts

@@ -1986,15 +1986,22 @@ export declare interface RealtimeClient {
 export declare interface Auth {
   /**
    * A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string, except it cannot contain a `*`. This option is primarily intended to be used in situations where the library is instantiated with a key. Note that a `clientId` may also be implicit in a token used to instantiate the library. An error is raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. Find out more about [identified clients](https://ably.com/docs/core-features/authentication#identified-clients).
+   *
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#client-id
    */
   clientId: string;
 
   /**
-   * Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token has been obtained. Also stores any {@link TokenParams} and {@link AuthOptions} passed in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any {@link TokenParams} and {@link AuthOptions} objects passed in entirely replace, as opposed to being merged with, the current client library saved values.
+   * Instructs the library to get a new token immediately. On a realtime client it re-authenticates the live connection, or initiates a connection if not connected, and the returned promise resolves only once the new token has taken effect on a `connected` connection, rejecting with an {@link ErrorInfo} if re-authentication fails or the connection cannot be (re)established. The client must be able to issue tokens, so a `key`, `authUrl`, or `authCallback` must be configured in {@link ClientOptions}, otherwise the call rejects with an {@link ErrorInfo}; `authorize()` cannot change the API key, so passing an `authOptions.key` that differs from the one the client was constructed with also rejects. Any {@link TokenParams} and {@link AuthOptions} passed in are stored as the new defaults for all subsequent token requests and entirely replace, rather than merge with, the current saved values.
    *
    * @param tokenParams - A {@link TokenParams} object.
    * @param authOptions - An {@link AuthOptions} object.
    * @returns A promise which, upon success, will be fulfilled with a {@link TokenDetails} object. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   * @example
+   * ```ts
+   * const tokenDetails = await realtime.auth.authorize({ clientId: 'bob' });
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#authorize
    */
   authorize(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise<TokenDetails>;
   /**
@@ -2017,11 +2024,16 @@ export declare interface Auth {
     callback: StandardCallback<TokenDetails>,
   ): void;
   /**
-   * Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams} and {@link AuthOptions}. Note this can only be used when the API `key` value is available locally. Otherwise, the Ably {@link TokenRequest} must be obtained from the key owner. Use this to generate an Ably {@link TokenRequest} in order to implement an Ably Token request callback for use by other clients. Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication).
+   * Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams} and {@link AuthOptions}. Use this to implement an Ably Token request callback for use by other clients. An API `key` value must be available locally to sign the request, supplied either in the client's {@link ClientOptions} or as `key` in the `authOptions` argument; without one the call rejects with an {@link ErrorInfo}, since a token-authenticated client cannot construct token requests itself and must instead obtain the {@link TokenRequest} from the key owner. Both {@link TokenParams} and {@link AuthOptions} are optional; when omitted or `null`, the client library's stored defaults (those set at construction or by a later `authorize` call) are used, and any values passed in replace, rather than merge with, those defaults.
    *
    * @param tokenParams - A {@link TokenParams} object.
    * @param authOptions - An {@link AuthOptions} object.
    * @returns A promise which, upon success, will be fulfilled with a {@link TokenRequest} object. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   * @example
+   * ```ts
+   * const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'bob' });
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#create-token-request
    */
   createTokenRequest(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise<TokenRequest>;
   /**
@@ -2044,11 +2056,16 @@ export declare interface Auth {
     callback: StandardCallback<TokenRequest>,
   ): void;
   /**
-   * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication).
+   * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both are optional; when omitted or `null`, the client's stored defaults are used, as specified in the {@link ClientOptions} at instantiation or later updated by an `authorize` request, and any values passed in are used instead of, rather than merged with, those defaults. The client must have a usable way to obtain a token, so the resolved {@link AuthOptions} must include one of `authCallback`, `authUrl`, or `key`; a client given only a literal token or `tokenDetails` with no renewal mechanism cannot request a new token and the call rejects with an {@link ErrorInfo}.
    *
    * @param TokenParams - A {@link TokenParams} object.
    * @param authOptions - An {@link AuthOptions} object.
    * @returns A promise which, upon success, will be fulfilled with a {@link TokenDetails} object. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   * @example
+   * ```ts
+   * const tokenDetails = await realtime.auth.requestToken({ clientId: 'bob' });
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#request-token
    */
   requestToken(TokenParams?: TokenParams, authOptions?: AuthOptions): Promise<TokenDetails>;
   /**
@@ -2071,11 +2088,21 @@ export declare interface Auth {
     callback: StandardCallback<TokenDetails>,
   ): void;
   /**
-   * Revokes the tokens specified by the provided array of {@link TokenRevocationTargetSpecifier}s. Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. See the [token revocation docs](https://ably.com/docs/core-features/authentication#token-revocation) for more information.
+   * Revokes the tokens specified by the provided array of {@link TokenRevocationTargetSpecifier}s.
+   * The client must be authenticated with an API key (basic auth), not a token; a
+   * token-authenticated client cannot revoke tokens and the call rejects with an {@link ErrorInfo}.
+   * Only tokens issued by an API key that had revocable tokens enabled before the token was issued
+   * can be revoked.
    *
    * @param specifiers - An array of {@link TokenRevocationTargetSpecifier} objects.
    * @param options - A set of options which are used to modify the revocation request.
    * @returns A promise which, upon success, will be fulfilled with a {@link BatchResult} containing information about the result of the token revocation request for each provided [`TokenRevocationTargetSpecifier`]{@link TokenRevocationTargetSpecifier}. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   * @example
+   * ```ts
+   * const result = await rest.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]);
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#revoke-tokens
+   * @see https://ably.com/docs/auth/revocation
    */
   revokeTokens(
     specifiers: TokenRevocationTargetSpecifier[],