docs(gcp): add credentials DX examples

packages/gcp/src/credentials.ts

@@ -1,10 +1,47 @@
 /**
  * GCP credentials — hand-written.
  *
- * API-compatible port of the distilled repo's gcp credentials module: a
- * plain externally-supplied OAuth2 bearer access token (no ADC, no
+ * A plain externally-supplied OAuth2 bearer access token (no ADC, no
  * service-account signing, no refresh flow — the token is minted outside
  * the SDK, e.g. `gcloud auth print-access-token`).
+ *
+ * ### DX
+ *
+ * **Example:** Env token (`GOOGLE_ACCESS_TOKEN`, optional `GOOGLE_PROJECT_ID`)
+ * ```typescript
+ * import * as storage from "@distilled.cloud/gcp/storage_v1";
+ * import { CredentialsFromEnv } from "@distilled.cloud/gcp/Credentials";
+ * import * as Effect from "effect/Effect";
+ *
+ * const object = yield* storage
+ *   .getObjects({ bucket: "my-bucket", object: "hello.txt" })
+ *   .pipe(Effect.provide(CredentialsFromEnv));
+ * ```
+ *
+ * **Example:** Explicit token
+ * ```typescript
+ * import * as pubsub from "@distilled.cloud/gcp/pubsub_v1";
+ * import { fromAccessToken } from "@distilled.cloud/gcp/Credentials";
+ * import * as Effect from "effect/Effect";
+ *
+ * const published = yield* pubsub
+ *   .publishProjectsTopics({
+ *     topic: "projects/my-project/topics/events",
+ *     body: { messages: [{ data: btoa("hello") }] },
+ *   })
+ *   .pipe(
+ *     Effect.provide(
+ *       fromAccessToken({
+ *         accessToken: process.env.GOOGLE_ACCESS_TOKEN!,
+ *         project: "my-project",
+ *       }),
+ *     ),
+ *   );
+ * ```
+ *
+ * Per-service modules are `@distilled.cloud/gcp/<name>_<version>` (for
+ * example `storage_v1`, `pubsub_v1`, `compute_v1`). This package's root
+ * export is credentials, protocol, and errors only.
  */
 import { ConfigError } from "@distilled.cloud/core/errors";
 import * as EffectConfig from "effect/Config";