@effected/github 0.14.0 → 0.15.0

package/index.d.ts

@@ -9,12 +9,9 @@ import { SemVer } from "@effected/semver";
  * Why a GitHub call failed, as a value you can branch on.
  *
  * @remarks
- * This discriminant is what replaces string-matching an error message. The
- * package this replaces carried a free-form `reason` string and nothing else
- * structural, so consumers grepped it: one repo lowercased a GraphQL message and
- * tested `includes("already") || includes("exists")`, and another re-issued an
- * existence check after every failed branch creation because it could not tell
- * "someone else created it" from "that failed".
+ * Branch on this discriminant instead of string-matching an error message:
+ * `alreadyExists` tells "someone else created it" apart from "that failed", so
+ * an upsert needs no follow-up existence check.
  *
  * @public
  */
@@ -75,8 +72,8 @@ declare const GitHubError_base: Schema.Class<GitHubError, Schema.TaggedStruct<"G
    * @remarks
    * Written by the client from `retry-after` or the rate-limit reset, and read
    * by exactly one thing: the retry `Schedule`. It is a policy input, not
-   * information for a caller — which is why it is optional and why the
-   * `retryable` boolean it used to travel with is now a derived getter.
+   * information for a caller. Whether a failure is worth retrying at all is the
+   * derived `retryable` getter.
    */
   readonly retryAfterMillis: Schema.optionalKey<Schema.Int>;
   /**
@@ -95,16 +92,9 @@ declare const GitHubError_base: Schema.Class<GitHubError, Schema.TaggedStruct<"G
  * Every REST failure this package produces, from every resource.
  *
  * @remarks
- * One error class, not one per resource. Across the six repos surveyed for this
- * port, consumers read `reason` about forty times, `status` twice, `operation`
- * twice, and matched a resource-specific `_tag` exactly **once** — at a call
- * site that disappears entirely now that `GitBranch.upsert` exists. Eighteen
- * near-identical error classes and thirteen near-identical mapper closures
- * bought that one match.
- *
- * What replaces them is {@link GitHubErrorKind} for routing and `operation` for
- * identification. This mirrors `@effected/git`, where the rule is that no
- * consumer ever string-matches stderr because classification happens once.
+ * One error class, not one per resource: {@link GitHubErrorKind} routes and
+ * `operation` identifies what was attempted. This mirrors `@effected/git`,
+ * where classification happens once so no consumer string-matches stderr.
  *
  * @public
  */
@@ -134,7 +124,7 @@ export declare class GitHubError extends GitHubError_base {
    * @remarks
    * The single classification step for the whole package — every resource
    * method's failures come through here, so the taxonomy cannot drift between
-   * resources the way thirteen hand-written mapper closures did.
+   * resources.
    *
    * `nowMillis` is passed in rather than read from the wall clock so the
    * function stays pure and total: the rate-limit reset header is an absolute
@@ -201,9 +191,8 @@ declare const GitHubGraphQLError_base: Schema.Class<GitHubGraphQLError, Schema.T
    *
    * @remarks
    * `"alreadyExists"` exists here for the same reason it exists on the REST
-   * error: without it a consumer lowercases the message and greps it for
-   * `"already"` and `"exists"`, which is exactly what one surveyed repo did to
-   * make project creation idempotent.
+   * error: it lets a caller make a create idempotent without lowercasing the
+   * message and grepping it.
    */
   readonly kind: Schema.Literals<readonly ["alreadyExists", "notFound", "rejected", "unauthorized", "rateLimited", "transport", "decode"]>;
   /** The document's name, e.g. `"linkedIssues"` — never the literal `"graphql"`. */
@@ -223,7 +212,7 @@ declare const GitHubGraphQLError_base: Schema.Class<GitHubGraphQLError, Schema.T
  * @remarks
  * Separate from `GitHubError` because GraphQL genuinely answers differently:
  * a 200 response can still carry failures, and it carries a **list** of them.
- * `errors` is the one structured field a surveyed consumer actually read.
+ * `errors` carries every entry GitHub reported, in order.
  *
  * @public
  */
@@ -250,25 +239,29 @@ export declare class GitHubGraphQLError extends GitHubGraphQLError_base {
  *
  * @remarks
  * This is the mechanism that makes `client.graphql` return a **domain value**
- * rather than an `unknown` the caller casts. The package this replaces took a
- * query string and a caller-chosen type parameter with nothing connecting them,
- * so every consumer wrote its own response interface and hoped.
+ * rather than an `unknown` the caller casts: the response schema ties the
+ * query to its decoded type.
  *
- * The kit owns the documents its resources need; a consumer with a domain of
- * its own — silk-sync-action's ProjectV2 work, for instance — builds its own
- * `GraphQLDocument` and gets the same typing and the same error taxonomy
- * without this package having to know about its schema.
+ * This package owns the documents its resource services need; a consumer with a
+ * domain of its own (GitHub Projects, say) builds its own `GraphQLDocument` and
+ * gets the same typing and the same error taxonomy.
  *
  * @example
  * ```ts
- * import { GraphQLDocument } from "@effected/github";
- * import { Schema } from "effect";
- *
- * const ViewerLogin = GraphQLDocument.make({
- *   name: "viewerLogin",
- *   document: `query { viewer { login } }`,
- *   response: Schema.Struct({ viewer: Schema.Struct({ login: Schema.String }) }),
- * })<{ readonly login: string }>();
+ * import { GitHubClient, GraphQLDocument } from "@effected/github";
+ * import { Effect, Schema } from "effect";
+ *
+ * const OwnerLogin = GraphQLDocument.make({
+ *   name: "ownerLogin",
+ *   document: `query ($owner: String!) { repositoryOwner(login: $owner) { login } }`,
+ *   response: Schema.Struct({ repositoryOwner: Schema.NullOr(Schema.Struct({ login: Schema.String })) }),
+ * })<{ readonly owner: string }>();
+ *
+ * const login = Effect.gen(function* () {
+ *   const client = yield* GitHubClient;
+ *   const data = yield* client.graphql(OwnerLogin, { owner: "effect-ts" });
+ *   return data.repositoryOwner?.login;
+ * });
  * ```
  *
  * @public
@@ -324,11 +317,8 @@ declare const RateLimitSnapshot_base: Schema.Class<RateLimitSnapshot, Schema.Str
  * one. Read it through the client's `rateLimit` member when you want to pace
  * yourself — **nothing in this package throttles on your behalf.**
  *
- * The package this replaces coupled the writer and the reader through an
- * optional shared `Ref` service that both resolved with `Effect.serviceOption`,
- * so an application that forgot to provide it got two private cells and a
- * silently dead feature. Here the cell lives inside the client layer that writes
- * it, and this is the only way to read it.
+ * The cell lives inside the client layer that writes it, so there is nothing
+ * extra to provide: reading it through the client is the only way.
  *
  * @public
  */
@@ -379,15 +369,22 @@ declare const RetryPolicy_base: Schema.Class<RetryPolicy, Schema.Struct<{
  *
  * @remarks
  * There is exactly **one** retry policy in this package, and it is wired into
- * the client so every resource inherits it and no resource carries its own. The
- * package this replaces shipped four mutually inconsistent policies — a
- * hand-rolled recursive loop, a second exported `Schedule` that ignored
- * server-advised delays, a per-operation branch retry layered on top of the
- * client's, and a rate-limiter retry with no predicate at all, which cheerfully
- * retried permission denials — and consumers added two more on top.
+ * the client so every resource inherits it and no resource carries its own.
  *
- * Only failures that report `retryable` are retried, which for `GitHubError` means a transport failure or a rate limit. A 404, a
- * validation rejection and an authorization failure fail on the first attempt.
+ * Only failures that report `retryable` are retried, which for `GitHubError`
+ * means a transport failure or a rate limit. A 404, a validation rejection and
+ * an authorization failure fail on the first attempt.
+ *
+ * @example
+ * ```ts
+ * import { GitHubClient, RetryPolicy } from "@effected/github";
+ * import { Duration, Redacted } from "effect";
+ *
+ * const layer = GitHubClient.layerFromToken({
+ *   token: Redacted.make("ghp_example"),
+ *   retry: RetryPolicy.make({ ...RetryPolicy.default, maxRetries: 2, maxDelay: Duration.seconds(10) }),
+ * });
+ * ```
  *
  * @public
  */
@@ -427,9 +424,7 @@ export declare class RetryPolicy extends RetryPolicy_base {
    * Built on `Schedule.modifyDelay`, whose callback receives the schedule's
    * `Metadata` — including the **input that failed**. That is what makes a
    * header-driven policy expressible as a `Schedule` at all: the delay is a
-   * function of the error, not only of the attempt number. Not knowing this was
-   * available is why the package this replaces hand-rolled a recursive retry
-   * loop instead of using `Effect.retry`.
+   * function of the error, not only of the attempt number.
    */
   schedule<E extends RetryableFailure>(): Schedule.Schedule<number, E>;
 }
@@ -459,7 +454,7 @@ type Route = keyof Endpoints;
  * @remarks
  * octokit's own `RequestParameters` carries an `[parameter: string]: unknown`
  * index signature, so intersecting it would silently accept every misspelled
- * parameter. These three are the ones the surveyed call sites genuinely need:
+ * parameter. These three are the ones callers need:
  * `headers` for a release asset's `content-type` and the attestations API
  * version pin, `mediaType.format` for raw content reads, and `baseUrl` for the
  * `uploads.github.com` host that release-asset uploads go to. Everything else a
@@ -500,8 +495,7 @@ type Data<R extends Route> = Endpoints[R]["response"]["data"];
  * The subset of routes that paginate.
  *
  * @remarks
- * Handing a non-paginating route to a paginating call is a **compile** error,
- * which the string-keyed surface this package replaces could not express.
+ * Handing a non-paginating route to a paginating call is a **compile** error.
  *
  * Intersected with `Rest.Route` because `plugin-paginate-rest` generates its
  * map from its own `@octokit/types` pin, which can trail the one this package
@@ -536,10 +530,8 @@ declare const PageOptions_base: Schema.Class<PageOptions, Schema.Struct<{
  * How far a paginated read should go.
  *
  * @remarks
- * Both fields are honored by every paginating method in this package. The
- * package it replaces accepted them on the client and then passed `{}` at six
- * of its eight call sites, so callers silently got 100-item pages and an
- * unbounded walk with no way to say otherwise.
+ * Both fields are honored by every paginating method in this package. Unset,
+ * a read requests 100-item pages and walks until GitHub stops.
  *
  * `perPage` is **validated, not clamped**: GitHub caps a page at 100 and
  * silently ignores anything larger, so a caller asking for 250 has a bug whose
@@ -702,19 +694,17 @@ interface GitHubFixtures {
    * A missing fixture is a **test wiring** mistake, not a condition the code
    * under test should handle, so the default kills the fiber rather than
    * entering the error channel — the same treatment an absent `graphql`
-   * fixture has always had.
+   * fixture gets.
    *
-   * The default used to be `"fail"`, and the reason it changed is worth
-   * knowing before you set it back: **a typed failure is only loud in code
-   * that does not catch.** A consumer whose methods each catch `GitHubError`
-   * and report it — a per-resource sync, say — turns a missing stub into a
-   * *different execution path* rather than a failure, and the assertions then
-   * fail for a new reason with nothing in any message naming a fixture. That
-   * cost `@spencerbeggs/reposets` 28 tests reading as ordinary logic bugs.
+   * Prefer `"die"` to `"fail"`: **a typed failure is only loud in code that
+   * does not catch.** Code whose methods each catch `GitHubError` and report
+   * it — a per-resource sync, say — turns a missing stub into a *different
+   * execution path* rather than a failure, and the assertions then fail for a
+   * new reason with nothing in any message naming a fixture.
    *
    * - `"die"` — defect naming the route. Loud in every consumer.
-   * - `"fail"` — the old behaviour: `GitHubError.notFound`. Rarely what you
-   *   want now that a recorded `GitHubError` value stubs a failure explicitly:
+   * - `"fail"` — fail with `GitHubError.notFound`. Rarely what you want, since
+   *   a recorded `GitHubError` value stubs a failure explicitly:
    *   `{ "GET /repos/{owner}/{repo}": GitHubError.notFound("read", "repo") }`
    *   says which route fails and why, where absence says only "unwired".
    * - `"empty"` — serve `{}` for a request and no items for a paginated read.
@@ -735,11 +725,6 @@ interface GitHubFixtures {
    * **params** they were called with, which is what lets a suite assert that a
    * method sent the right `owner`/`repo`/body rather than only the right
    * route. `graphql` records the document name as `route`.
-   *
-   * Recording params was added for the resource modules ported in from
-   * `@spencerbeggs/reposets`, whose ~80-line hand-rolled harness existed
-   * because every one of their methods goes through `request` and a fixture
-   * could assert nothing about them.
    */
   readonly requested?: Array<RecordedCall> | undefined;
 }
@@ -754,12 +739,27 @@ declare const GitHubClient_base: Context.ServiceClass<GitHubClient, "@effected/g
  * literal and gets both sides typed, with no callback, no type parameter to
  * invent, and no cast.
  *
- * That is the whole point of this package. The surface it replaces was
- * `rest<T>(operation: string, fn: (octokit: any) => Promise<{ data: T }>)`,
- * where `T` was whatever the caller wrote and nothing connected it to the
- * endpoint. Four consumer repos paid for that with sixteen cast sites and three
- * hand-written octokit interfaces, one of which gave up and typed its methods as
- * `Record<string, (p: unknown) => Promise<{ data: unknown }>>`.
+ * Nothing here asks the caller to invent a response type: the route literal is
+ * the only thing written, and a mismatch between a route and its parameters is
+ * a compile error.
+ *
+ * @example
+ * ```ts
+ * import { GitHubClient } from "@effected/github";
+ * import { Effect, Redacted } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const client = yield* GitHubClient;
+ *   const release = yield* client.request("GET /repos/{owner}/{repo}/releases/latest", {
+ *     owner: "effect-ts",
+ *     repo: "effect",
+ *   });
+ *   return release.tag_name;
+ * });
+ *
+ * const layer = GitHubClient.layerFromToken({ token: Redacted.make("ghp_example") });
+ * Effect.runPromise(program.pipe(Effect.provide(layer)));
+ * ```
  *
  * @public
  */
@@ -782,10 +782,7 @@ export declare class GitHubClient extends GitHubClient_base {
    * provides a provider instead of mutating the environment and a non-Actions
    * consumer can source the token however it likes.
    *
-   * Construction fails with core's `ConfigError` — an honest "no token is
-   * configured". The layer this replaces failed with a **wire-failure** error
-   * type instead, which is why one consumer wrapped it in `Layer.orDie` under a
-   * five-line comment explaining that the error did not mean what it said.
+   * Construction fails with core's `ConfigError` when no token is configured.
    */
   static readonly layerFromConfig: (options?: Omit<GitHubClientOptions, "token"> & {
     readonly name?: string | undefined;
@@ -810,17 +807,11 @@ export declare class GitHubClient extends GitHubClient_base {
    * A double over recorded responses that **pages them for real**.
    *
    * @remarks
-   * The one recorded-response double in this package, and the single narrow
-   * exception to the no-behavior-reimplementing-doubles rule — safe precisely
-   * because it reimplements nothing: it builds a `PageSource` over the recorded
+   * The recorded-response double in this package. It reimplements no behavior:
+   * it builds a `PageSource` over the recorded
    * array and hands it to the same `paginate` engine the live client uses, so
    * `perPage` and `maxPages` cannot behave differently here than in production.
    *
-   * The double it replaces named its pagination parameters `_options` and
-   * ignored them, returning every recorded page regardless of what the caller
-   * asked for — which made every truncation path in every consumer
-   * structurally untestable.
-   *
    * `fixtures.requested` is appended to as the test runs, so a suite can assert
    * which routes were walked and at what page size.
    */
@@ -875,33 +866,26 @@ declare const Repo_base: Context.ServiceClass<Repo, "@effected/github/Repo", Rep
  * `{ owner, repo }` argument**, which is what makes a read like
  * `GitHubRepository.defaultBranch` a single expression instead of a preamble.
  *
- * The package this replaces read `process.env.GITHUB_REPOSITORY` in three
- * places — inside the client, inside the App layer, and transitively in every
- * caller of `client.repo` — which is most of what coupled a GitHub API client to
- * the GitHub Actions runtime. Here the coordinate is a value, the env-driven way
- * to get one is a layer variant **named for being env-driven**, and a program
- * that acts on several repositories uses {@link Repo.provide}:
+ * The coordinate is a plain value. The only env-driven way to get one is
+ * {@link Repo.layerFromConfig}, which is named for being env-driven, and a
+ * program that acts on several repositories uses {@link Repo.provide}.
+ *
+ * The service shape is entirely one immutable value (a `RepoRef`), with no
+ * methods, so `Layer.succeed` is the correct test double.
  *
  * @example
  * ```ts
- * import { Repo } from "@effected/github";
+ * import { Repo, RepoRef } from "@effected/github";
  * import { Effect } from "effect";
  *
  * declare const syncOne: Effect.Effect<void, never, Repo>;
- * declare const targets: ReadonlyArray<Repo["Service"]>;
+ * declare const targets: ReadonlyArray<RepoRef>;
  *
  * const syncAll = Effect.forEach(targets, (target) => syncOne.pipe(Repo.provide(target)), {
  *   concurrency: 4,
  * });
  * ```
  *
- * **A deliberate exception to "no non-effectful members on a service shape."**
- * This shape is entirely one immutable value: there is nothing to leave
- * unimplemented, so `Layer.mock` has nothing to degrade and `Layer.succeed` is
- * the correct double. The rule exists to stop a sync member from quietly
- * degrading a *mixed* shape's partial mock. The boundary to hold: the moment a
- * method appears here, this is a service again and the rule applies.
- *
  * @public
  */
 export declare class Repo extends Repo_base {
@@ -943,10 +927,7 @@ declare const StorageRecordInput_base: Schema.Class<StorageRecordInput, Schema.S
  * What to record about a published artifact.
  *
  * @remarks
- * These are the fields the endpoint actually accepts. The version this replaces
- * declared a `version` field the endpoint has no notion of — a fabricated key
- * that a `Record<string, unknown>` body accepted silently and the generated
- * types reject outright.
+ * These are the fields the storage-record endpoint accepts.
  *
  * @public
  */
@@ -957,9 +938,8 @@ export declare class StorageRecordInput extends StorageRecordInput_base {}
  * @remarks
  * The endpoint is org-scoped rather than repository-scoped, but the
  * organization is resolved from {@link Repo}'s `owner` per call like every
- * other resource — an earlier version took it as a positional argument, the
- * one method on the surface that did. `Repo.provide` covers the cross-org
- * case, exactly as it covers the cross-repository one.
+ * other resource. `Repo.provide` covers the cross-org case, exactly as it
+ * covers the cross-repository one.
  *
  * @public
  */
@@ -969,11 +949,16 @@ interface ArtifactMetadataShape {
 }
 declare const ArtifactMetadata_base: Context.ServiceClass<ArtifactMetadata, "@effected/github/ArtifactMetadata", ArtifactMetadataShape>;
 /**
- * Artifact metadata.
+ * Records where published artifacts are stored, at the organization level.
+ *
+ * @remarks
+ * Provide it with {@link ArtifactMetadata.layer}, which needs a `GitHubClient`;
+ * `createStorageRecord` also needs a `Repo` in `R`.
  *
  * @public
  */
 export declare class ArtifactMetadata extends ArtifactMetadata_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<ArtifactMetadata, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<ArtifactMetadataShape>) => ArtifactMetadataShape;
@@ -1012,8 +997,7 @@ export declare class AttestationListEntry extends AttestationListEntry_base {}
  * @remarks
  * Upload and listing only. Building a statement, signing it and producing the
  * bundle belong to `@effected/sbom`; assembling those into a pipeline belongs to
- * the consumer. That split is what dissolves the five-service knot the previous
- * package needed a mega-layer to test.
+ * the consumer.
  *
  * @public
  */
@@ -1034,11 +1018,17 @@ interface AttestationShape {
 }
 declare const Attestation_base: Context.ServiceClass<Attestation, "@effected/github/Attestation", AttestationShape>;
 /**
- * Attestations.
+ * Uploads signed attestation bundles to a repository and lists what is attested
+ * about a subject digest.
+ *
+ * @remarks
+ * Provide it with {@link Attestation.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`.
  *
  * @public
  */
 export declare class Attestation extends Attestation_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<Attestation, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<AttestationShape>) => AttestationShape;
@@ -1084,8 +1074,8 @@ declare const CheckRunOutput_base: Schema.Class<CheckRunOutput, Schema.Struct<{
  * GitHub's limits are **byte** limits, and that distinction is the whole reason
  * this class exists rather than a struct: `✅`, `❌`, `🦋` and `│` cost several
  * bytes each, so a character-count check passes while the request comes back
- * 422 saying *"summary exceeds a maximum bytesize of 65535"*. One consumer hit
- * exactly that and wrote the truncation by hand.
+ * 422 saying *"summary exceeds a maximum bytesize of 65535"*. Use
+ * {@link CheckRunOutput.truncated} to cut an output to fit.
  *
  * @public
  */
@@ -1140,7 +1130,11 @@ export declare class CheckRunRef extends CheckRunRef_base {}
  */
 type ConcludeCheckRun = (conclusion: (typeof CheckConclusion.literals)[number], output?: CheckRunOutput) => Effect.Effect<void>;
 /**
- * Check runs.
+ * Create, update and conclude GitHub check runs on a commit, including a
+ * bracket that always concludes the run.
+ *
+ * @remarks
+ * Every member resolves the target repository from the `Repo` service in `R`.
  *
  * @public
  */
@@ -1174,30 +1168,46 @@ interface CheckRunShape {
    * Neither an interrupt nor an existing failure is replaced by whatever went
    * wrong while reporting it.
    *
-   * `use` keeps its own `R` and its own `A`, unlike the version this replaces,
-   * whose callback was `R`-less and so forced consumers to build
-   * self-contained layers just to use the bracket.
+   * `use` keeps its own `R` and its own `A`, so the bracket composes with
+   * whatever services the wrapped work needs.
    *
    * @example
    * ```ts
-   * check.withCheckRun("lint", sha, (id, conclude) =>
+   * import { CheckRun, CheckRunOutput } from "@effected/github";
+   * import { Effect } from "effect";
+   *
+   * const lintWithCheck = (sha: string) =>
    *   Effect.gen(function* () {
-   *     const findings = yield* lint();
-   *     yield* conclude(deriveConclusion(findings), report(findings));
-   *     return findings;
-   *   }),
-   * );
+   *     const check = yield* CheckRun;
+   *     return yield* check.withCheckRun("lint", sha, (_id, conclude) =>
+   *       Effect.gen(function* () {
+   *         const findings = 3; // run the linter here
+   *         // An advisory result: record "neutral" instead of the default "success".
+   *         yield* conclude(
+   *           "neutral",
+   *           CheckRunOutput.make({ title: "lint", summary: `${findings} findings` }),
+   *         );
+   *         return findings;
+   *       }),
+   *     );
+   *   });
    * ```
    */
   readonly withCheckRun: <A, E, R>(name: string, headSha: string, use: (id: number, conclude: ConcludeCheckRun) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | GitHubError, R | Repo>;
 }
 declare const CheckRun_base: Context.ServiceClass<CheckRun, "@effected/github/CheckRun", CheckRunShape>;
 /**
- * Check runs.
+ * Create, update and conclude GitHub check runs, including the
+ * {@link CheckRunShape.withCheckRun} bracket that always reaches a terminal state.
+ *
+ * @remarks
+ * Provide it with {@link CheckRun.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`.
  *
  * @public
  */
 export declare class CheckRun extends CheckRun_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<CheckRun, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<CheckRunShape>) => CheckRunShape;
@@ -1251,8 +1261,8 @@ interface CodeScanningShape {
    * the repository's workflows afterwards. A caller that treats "default setup
    * is off" as "no CodeQL workflow exists" will be wrong, and one that counts
    * workflows to decide whether a repository has any CI will count that one.
-   * Reported by `@spencerbeggs/reposets` (dogfood round 8, 2026-08-14) from a
-   * real organization, not inferred from the API description.
+   * Observed against a real organization, not inferred from the API
+   * description.
    */
   readonly configure: (setup: CodeScanningSetup) => Effect.Effect<void, GitHubError, Repo>;
   /**
@@ -1268,12 +1278,19 @@ interface CodeScanningShape {
 }
 declare const CodeScanning_base: Context.ServiceClass<CodeScanning, "@effected/github/CodeScanning", CodeScanningShape>;
 /**
- * CodeQL default setup.
+ * Configure CodeQL default setup and read the languages GitHub detects in a
+ * repository.
+ *
+ * @remarks
+ * Provide it with {@link CodeScanning.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`.
  *
  * @public
  */
 export declare class CodeScanning extends CodeScanning_base {
   /**
+   * The live service, built over a `GitHubClient`.
+   *
    * @remarks
    * The callback is written `(client) => make(client)` rather than passed as
    * `make` directly, and that is load-bearing: a static initializer runs while
@@ -1295,10 +1312,11 @@ export declare class CodeScanning extends CodeScanning_base {
  * @public
  */
 interface DeploymentEnvironmentInfo {
+  /** The environment's name. */
   readonly name: string;
 }
 /**
- * Deployment environments.
+ * Create or update, list and delete a repository's deployment environments.
  *
  * @public
  */
@@ -1330,12 +1348,30 @@ interface DeploymentEnvironmentShape {
 }
 declare const DeploymentEnvironment_base: Context.ServiceClass<DeploymentEnvironment, "@effected/github/DeploymentEnvironment", DeploymentEnvironmentShape>;
 /**
- * Deployment environments.
+ * Create or update, list and delete a repository's deployment environments.
+ *
+ * @remarks
+ * Provide it with {@link DeploymentEnvironment.layer}, which needs a
+ * `GitHubClient`; each method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { DeploymentEnvironment } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const environments = yield* DeploymentEnvironment;
+ *   yield* environments.upsert("production", { wait_timer: 10 });
+ *   return yield* environments.list();
+ * });
+ * ```
  *
  * @public
  */
 export declare class DeploymentEnvironment extends DeploymentEnvironment_base {
   /**
+   * The live service, built over a `GitHubClient`.
+   *
    * @remarks
    * `(client) => make(client)` rather than `make`: a static initializer runs
    * while the module body is still evaluating, so naming a `const` declared
@@ -1372,25 +1408,19 @@ interface GitBranchShape {
    * Point `name` at `sha`, creating it if needed.
    *
    * @remarks
-   * **One call, one intent.** Creating a branch that may already exist is the
-   * single most-repeated dance in the surveyed consumers: the marketplace
-   * manager spent a seven-line comment and a nine-line workaround on it, doing
-   * `getSha` → `exists` → `create` → on failure `exists` again → `reset`, up to
-   * four round trips, because the error it caught carried no structured
-   * "already exists". silk-release-action wrote the mirror image of the same
-   * dance a few files away.
-   *
-   * This is one round trip in the common case and two in the raced one, and the
-   * recovery **resets** rather than inheriting a branch a concurrent creator
-   * rooted somewhere else — which is the semantics that comment was defending.
+   * **One call, one intent.** Creating a branch that may already exist needs no
+   * `exists` check, no catch and no second attempt: this creates the ref, and
+   * when GitHub answers `alreadyExists` it resets the ref to `sha`. It is one
+   * round trip in the common case and two in the raced one, and the recovery
+   * **resets** rather than inheriting a branch a concurrent creator rooted
+   * somewhere else. The result says which happened: `"created"` or `"reset"`.
    *
    * **A reset is observable, and open pull requests react to it.** Resetting a
    * branch to its PR's base — `upsert(branch, targetHead)` — makes that PR's
    * head equal its base, and GitHub **auto-closes a PR whose diff is empty**.
-   * The window is invisible at this call site: a consumer ran
-   * `upsert(releaseBranch, mainHead)` intending to re-add content with a commit
-   * ~3 seconds later, and GitHub closed the open release PR inside that window
-   * while the run reported success. When the end state is "the target head plus
+   * The window is invisible at this call site: `upsert(releaseBranch, mainHead)`
+   * followed a few seconds later by a commit that re-adds content can lose an
+   * open release PR in between while the run reports success. When the end state is "the target head plus
    * a commit", build the commit first — `GitCommit.get` the target for its
    * `treeSha`, `createTree` on it, `createCommit` with the target as parent —
    * and upsert **once**, straight to the finished sha, so the ref never rests
@@ -1427,12 +1457,32 @@ interface GitBranchShape {
 }
 declare const GitBranch_base: Context.ServiceClass<GitBranch, "@effected/github/GitBranch", GitBranchShape>;
 /**
- * Branches, as refs.
+ * Create, move, read and delete branch refs through GitHub's Git Database API,
+ * with an `upsert` that needs no existence check.
+ *
+ * @remarks
+ * Provide it with {@link GitBranch.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`. Branch names are accepted as `main`,
+ * `heads/main` or `refs/heads/main`.
+ *
+ * @example
+ * ```ts
+ * import { GitBranch } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const ensureBranch = (name: string, sha: string) =>
+ *   Effect.gen(function* () {
+ *     const branches = yield* GitBranch;
+ *     return yield* branches.upsert(name, sha); // "created" | "reset"
+ *   });
+ * ```
  *
  * @public
  */
 export declare class GitBranch extends GitBranch_base {
   /**
+   * The live service, built over a `GitHubClient`.
+   *
    * @remarks
    * The callback is written `(client) => make(client)` rather than passed as
    * `make` directly, and that is load-bearing: a static initializer runs while
@@ -1499,10 +1549,8 @@ declare const CommitRef_base: Schema.Class<CommitRef, Schema.Struct<{
  * A commit, projected to the three fields callers actually use.
  *
  * @remarks
- * `treeSha` is here because two surveyed call sites dropped to a raw octokit
- * cast for it alone, both with the comment *"the Git Data API's `base_tree`
- * wants a tree SHA, not a commit SHA"* — the same eight lines written twice, in
- * two files, for one string.
+ * `treeSha` is here because the Git Data API's `base_tree` wants a tree SHA,
+ * not a commit SHA.
  *
  * @public
  */
@@ -1544,9 +1592,7 @@ interface GitCommitShape {
    * `GitBranch.upsert` straight to the finished commit. Do **not** spell a
    * rebase as `upsert(branch, targetHead)` followed by `commitFiles`: between
    * those calls the branch *is* the target head, an open pull request from it
-   * has an empty diff, and GitHub auto-closes PRs in that state — a real
-   * consumer lost its open release PR to that ~3-second window while the run
-   * went green.
+   * has an empty diff, and GitHub auto-closes PRs in that state.
    */
   readonly commitFiles: (options: {
     readonly branch: string;
@@ -1556,11 +1602,33 @@ interface GitCommitShape {
 }
 declare const GitCommit_base: Context.ServiceClass<GitCommit, "@effected/github/GitCommit", GitCommitShape>;
 /**
- * Commits, trees and blobs.
+ * Read commits and build trees and commits through GitHub's Git Database API,
+ * including a one-call "commit these files onto a branch".
+ *
+ * @remarks
+ * Provide it with {@link GitCommit.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`. No local git runs: this is the REST API,
+ * not `@effected/git`.
+ *
+ * @example
+ * ```ts
+ * import { FileContent, GitCommit } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const writeNotes = Effect.gen(function* () {
+ *   const commits = yield* GitCommit;
+ *   return yield* commits.commitFiles({
+ *     branch: "docs/notes",
+ *     message: "docs: add notes",
+ *     changes: [FileContent.make({ path: "NOTES.md", content: "# Notes\n" })],
+ *   }); // the new commit's sha
+ * });
+ * ```
  *
  * @public
  */
 export declare class GitCommit extends GitCommit_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitCommit, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<GitCommitShape>) => GitCommitShape;
@@ -1671,9 +1739,8 @@ export declare class InstallationToken extends InstallationToken_base {
    * Whether this token is spent, `skew` before its stated expiry.
    *
    * @remarks
-   * Modelled **and enforced**. The package this replaces persisted `expiresAt`
-   * and read it nowhere, so a long `main` phase that outlived the hour simply
-   * started answering 401 with no explanation.
+   * `skew` defaults to one minute, so a token is treated as spent slightly early
+   * rather than answering 401 mid-request.
    */
   isExpired(nowMillis: number, skew?: Duration.Duration): boolean;
   /** The committer identity a commit made with this token should carry. */
@@ -1689,10 +1756,10 @@ declare const BotIdentity_base: Schema.Class<BotIdentity, Schema.Struct<{
  * Who a bot commits as.
  *
  * @remarks
- * A **pure class**, not a service member. The package this replaces put
- * `botIdentity(source?)` on the `GitHubApp` service shape as a plain synchronous
- * method, which makes it required in every `Layer.mock` and silently degrades
- * every partial double to a full implementation.
+ * A **pure class**, not a `GitHubApp` service member: a synchronous method on
+ * the service shape would be required in every `Layer.mock` and would silently
+ * degrade every partial double to a full implementation. Get one from
+ * `InstallationToken.botIdentity` or `AppIdentity.botIdentity`.
  *
  * @public
  */
@@ -1781,9 +1848,28 @@ declare const GitHubApp_base: Context.ServiceClass<GitHubApp, "@effected/github/
  * `@effected/commands`' service, for the same reason.
  *
  * The JWT signer is `universal-github-app-jwt` — zero dependencies, and
- * `@octokit/auth-app`'s own JWT dependency. Taking it directly rather than
- * taking `auth-app` leaves behind roughly half a megabyte of OAuth app, user and
- * device-flow machinery that this package never calls.
+ * `@octokit/auth-app`'s own JWT dependency.
+ *
+ * @example
+ * ```ts
+ * import { GitHubApp, GitHubClient } from "@effected/github";
+ * import { Effect, Redacted } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const client = yield* GitHubClient;
+ *   const accessible = yield* client.request("GET /installation/repositories", { per_page: 1 });
+ *   return accessible.total_count;
+ * });
+ *
+ * // Mints an installation token on build, re-mints before expiry, revokes on release.
+ * const layer = GitHubApp.clientLayer({
+ *   appId: "12345",
+ *   privateKey: Redacted.make("-----BEGIN PRIVATE KEY-----\n..."),
+ *   owner: "my-org",
+ * });
+ *
+ * Effect.runPromise(Effect.provide(program, layer));
+ * ```
  *
  * @public
  */
@@ -1806,11 +1892,12 @@ export declare class GitHubApp extends GitHubApp_base {
    * The token's lifetime is the layer's scope: it is minted on build and
    * **revoked on release**, best-effort, so a workflow does not leave live
    * credentials behind. It is also **re-minted automatically** a minute before
-   * it expires, which the package this replaces did not do — it persisted
-   * `expiresAt` and read it nowhere, so a `main` phase outliving the hour
-   * started answering 401 with nothing explaining why.
+   * it expires, so a long-running program does not start answering 401 when
+   * the hour ends.
    *
-   * A failure to obtain credentials surfaces to the caller as a
+   * Building the layer mints the first token, so a misconfigured app fails
+   * construction with `GitHubAppError`. After that, a failure to obtain
+   * credentials surfaces to the caller as a
    * `GitHubError { kind: "unauthorized" }` carrying the `GitHubAppError` as its
    * cause: from a request's point of view, "could not authenticate" is an
    * authorization failure, and widening every method's error channel to say so
@@ -1837,22 +1924,19 @@ interface GitHubAppShape {
    * Mint an installation token.
    *
    * @remarks
-   * Used by `@effected/github-actions`' token bridge in a workflow's `pre`
-   * phase. Touches: nothing else on this shape.
+   * `installationId` is used when given; otherwise the installation is
+   * discovered from `owner`, or from the app's only installation.
    */
   readonly token: (request: TokenRequest) => Effect.Effect<InstallationToken, GitHubAppError>;
   /**
-   * Mint a token that is revoked when the scope closes.
+   * Mint a token that is revoked, best-effort, when the scope closes.
    *
    * @remarks
-   * Touches: `token`, `revoke`.
+   * Mints through `token` and releases through `revoke`.
    */
   readonly scopedToken: (request: TokenRequest) => Effect.Effect<InstallationToken, GitHubAppError, Scope.Scope>;
   /**
    * Revoke a token now.
-   *
-   * @remarks
-   * Used by the token bridge's `post` phase. Touches: nothing else.
    */
   readonly revoke: (token: Redacted.Redacted<string>) => Effect.Effect<void, GitHubAppError>;
   /**
@@ -1861,17 +1945,12 @@ interface GitHubAppShape {
    * @remarks
    * Supply `installationToken` when you have one: `GET /users/{slug}[bot]`
    * rejects an app JWT, so without it the lookup runs unauthenticated at
-   * GitHub's 60-requests-per-hour-per-IP limit. Touches: nothing else.
+   * GitHub's 60-requests-per-hour-per-IP limit.
    */
   readonly identity: (request: AppCredentials & {
     readonly installationToken?: Redacted.Redacted<string> | undefined;
   }) => Effect.Effect<AppIdentity, GitHubAppError>;
-  /**
-   * Every installation of the app.
-   *
-   * @remarks
-   * Touches: nothing else.
-   */
+  /** Every installation of the app. */
   readonly installations: (credentials: AppCredentials) => Effect.Effect<ReadonlyArray<Installation>, GitHubAppError>;
 }
 //#endregion
@@ -1949,14 +2028,14 @@ declare const CommitComparison_base: Schema.Class<CommitComparison, Schema.Struc
  */
 export declare class CommitComparison extends CommitComparison_base {}
 /**
- * Reading commits.
+ * Read commits, list them, compare two refs and list the files a commit touched.
  *
  * @public
  */
 interface GitHubCommitShape {
-  /** One commit. */
+  /** Read one commit by sha or ref. */
   readonly get: (ref: string) => Effect.Effect<CommitSummary, GitHubError, Repo>;
-  /** Commits on a ref, newest first. */
+  /** List commits reachable from `ref` (the default branch when omitted), newest first, optionally limited to those touching `path`. */
   readonly list: (options?: {
     readonly ref?: string | undefined;
     readonly path?: string | undefined;
@@ -1968,8 +2047,9 @@ interface GitHubCommitShape {
    * @remarks
    * GitHub paginates this **by commit**, while the single-commit read paginates
    * **by file** at 300 per page — so a one-commit comparison is permanently
-   * truncated at 300 files no matter what you pass. That is GitHub's constraint,
-   * recorded here rather than discovered later.
+   * truncated at 300 files no matter what you pass. That is GitHub's
+   * constraint; use {@link GitHubCommitShape.changedFiles} to page every file
+   * of one commit.
    */
   readonly compare: (base: string, head: string) => Effect.Effect<CommitComparison, GitHubError, Repo>;
   /** The files one commit touched, paginated by file. */
@@ -1979,11 +2059,30 @@ interface GitHubCommitShape {
 }
 declare const GitHubCommit_base: Context.ServiceClass<GitHubCommit, "@effected/github/GitHubCommit", GitHubCommitShape>;
 /**
- * Commits, as GitHub reports them.
+ * Read commits, compare refs and list changed files through GitHub's commits
+ * API.
+ *
+ * @remarks
+ * Provide it with {@link GitHubCommit.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`. For commits as Git Database objects (trees,
+ * parents), use `GitCommit` instead.
+ *
+ * @example
+ * ```ts
+ * import { GitHubCommit } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const changedSinceMain = Effect.gen(function* () {
+ *   const commits = yield* GitHubCommit;
+ *   const comparison = yield* commits.compare("main", "feature");
+ *   return comparison.files.map((file) => file.path);
+ * });
+ * ```
  *
  * @public
  */
 export declare class GitHubCommit extends GitHubCommit_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubCommit, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<GitHubCommitShape>) => GitHubCommitShape;
@@ -1993,7 +2092,7 @@ export declare class GitHubCommit extends GitHubCommit_base {
 //#endregion
 //#region src/GitHubContent.d.ts
 /**
- * Reading a file out of a repository.
+ * Read a text file out of a repository at a ref.
  *
  * @public
  */
@@ -2001,6 +2100,11 @@ interface GitHubContentShape {
   /**
    * A text file's contents at `ref`, or the default branch when `ref` is
    * omitted.
+   *
+   * @remarks
+   * Fails `notFound` when the path does not exist, and `rejected` when it is a
+   * directory, is not a regular file, or is too large for the contents API
+   * (which answers an empty body above roughly a megabyte).
    */
   readonly getFile: (path: string, options?: {
     readonly ref?: string | undefined;
@@ -2012,11 +2116,29 @@ interface GitHubContentShape {
 }
 declare const GitHubContent_base: Context.ServiceClass<GitHubContent, "@effected/github/GitHubContent", GitHubContentShape>;
 /**
- * Repository file contents.
+ * Read a text file out of a repository at a ref, with absence as an `Option`
+ * when you want it.
+ *
+ * @remarks
+ * Provide it with {@link GitHubContent.layer}, which needs a `GitHubClient`;
+ * each method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { GitHubContent } from "@effected/github";
+ * import { Effect, Option } from "effect";
+ *
+ * const readme = Effect.gen(function* () {
+ *   const content = yield* GitHubContent;
+ *   const file = yield* content.getFileOption("README.md", { ref: "main" });
+ *   return Option.getOrElse(file, () => "");
+ * });
+ * ```
  *
  * @public
  */
 export declare class GitHubContent extends GitHubContent_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubContent, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<GitHubContentShape>) => GitHubContentShape;
@@ -2035,11 +2157,9 @@ declare const CommentMarker_base: Schema.Class<CommentMarker, Schema.Struct<{
  * The hidden marker that makes a comment findable again.
  *
  * @remarks
- * A pure class, not a hardcoded string. The surface this replaces baked
- * `<!-- savvy-web:${key} -->` into the library — one vendor's name, inside a
- * package meant to be general. Here the namespace is the caller's, the marker is
- * testable without a client, and the library has no opinion about whose comments
- * these are.
+ * The marker is `<!-- namespace:key -->`, an HTML comment appended to the body.
+ * The namespace is the caller's, so the library has no opinion about whose
+ * comments these are, and a marker is testable without a client.
  *
  * @public
  */
@@ -2055,13 +2175,14 @@ declare const CommentRecord_base: Schema.Class<CommentRecord, Schema.Struct<{
   readonly url: Schema.String;
 }>, {}>;
 /**
- * A comment this package wrote or found.
+ * A comment this package wrote or found: its id, body and web URL.
  *
  * @public
  */
 export declare class CommentRecord extends CommentRecord_base {}
 /**
- * Sticky comments on a pull request or issue.
+ * Post, update, find and delete comments on a pull request or issue, including
+ * a "sticky" comment kept current through a marker.
  *
  * @public
  */
@@ -2080,22 +2201,42 @@ interface PullRequestCommentShape {
    * Find the marked comment.
    *
    * @remarks
-   * **Paginates.** The version this replaces requested a single page of 100 and
-   * stopped, so on a busy pull request the marker silently vanished and every
-   * update posted a new comment instead.
+   * **Paginates**, so the marker is found on a busy pull request too; pass
+   * `page` to bound the walk.
    */
   readonly find: (issueNumber: number, marker: CommentMarker, options?: {
     readonly page?: PageOptions | undefined;
   }) => Effect.Effect<Option.Option<CommentRecord>, GitHubError, Repo>;
+  /** Delete a comment by id. */
   readonly delete: (commentId: number) => Effect.Effect<void, GitHubError, Repo>;
 }
 declare const PullRequestComment_base: Context.ServiceClass<PullRequestComment, "@effected/github/PullRequestComment", PullRequestCommentShape>;
 /**
- * Sticky comments.
+ * Post, update, find and delete comments on a pull request or issue, including
+ * a "sticky" comment kept current through a `CommentMarker`.
+ *
+ * @remarks
+ * Provide it with {@link PullRequestComment.layer}, which needs a `GitHubClient`;
+ * each method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { CommentMarker, PullRequestComment } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const marker = CommentMarker.make({ namespace: "my-action", key: "report" });
+ *
+ * const report = (pullNumber: number, body: string) =>
+ *   Effect.gen(function* () {
+ *     const comments = yield* PullRequestComment;
+ *     return yield* comments.upsert(pullNumber, marker, body); // edits the marked comment in place
+ *   });
+ * ```
  *
  * @public
  */
 export declare class PullRequestComment extends PullRequestComment_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<PullRequestComment, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<PullRequestCommentShape>) => PullRequestCommentShape;
@@ -2131,10 +2272,8 @@ declare const LinkedIssue_base: Schema.Class<LinkedIssue, Schema.Struct<{
    * branch or commit messages.
    *
    * @remarks
-   * This is the field the whole document exists for. The version this replaces
-   * could not express `userLinkedOnly`, so one consumer re-declared the query
-   * with the field aliased twice to get it — the single largest duplicated
-   * document in the survey.
+   * Resolved by querying the pull request's closing references twice, once with
+   * `userLinkedOnly`, and marking the issues present in the second result.
    */
   readonly userLinked: Schema.Boolean;
 }>, {}>;
@@ -2162,19 +2301,28 @@ declare const CommentOnceResult_base: Schema.Class<CommentOnceResult, Schema.Str
  */
 export declare class CommentOnceResult extends CommentOnceResult_base {}
 /**
- * Issues.
+ * Read, list, close and comment on issues, and resolve the issues a pull
+ * request closes.
  *
  * @public
  */
 interface GitHubIssueShape {
+  /** Read one issue. Fails `notFound` when it does not exist. */
   readonly get: (number: number) => Effect.Effect<IssueInfo, GitHubError, Repo>;
+  /**
+   * List issues, paginated. `state` is omitted from the request when unset, so GitHub's default applies.
+   *
+   * @remarks
+   * GitHub's issues endpoint also returns pull requests; this does not filter them out.
+   */
   readonly list: (options?: {
     readonly state?: "open" | "closed" | "all" | undefined;
     readonly labels?: ReadonlyArray<string> | undefined;
     readonly page?: PageOptions | undefined;
   }) => Effect.Effect<ReadonlyArray<IssueInfo>, GitHubError, Repo>;
+  /** Close an issue. `reason` is sent as `state_reason` when given; unset, GitHub chooses. */
   readonly close: (number: number, reason?: "completed" | "not_planned") => Effect.Effect<void, GitHubError, Repo>;
-  /** Post a comment. */
+  /** Post a comment and return its id. */
   readonly comment: (number: number, body: string) => Effect.Effect<number, GitHubError, Repo>;
   /**
    * Post a marked comment once: create it, or skip if it already exists.
@@ -2204,10 +2352,10 @@ interface GitHubIssueShape {
    * Has `prNumber` already been cross-referenced on this issue?
    *
    * @remarks
-   * The idempotence guard one consumer wrote a bespoke timeline query for,
-   * so that re-running a workflow does not comment twice.
+   * An idempotence guard over the issue's timeline, so that re-running a
+   * workflow does not comment twice.
    *
-   * Two hazards before building on it (effected#306):
+   * Two hazards before building on it:
    *
    * - **An issue obtained from `linkedIssues(pr)` answers `true` from the
    *   outset** — the closing link itself puts a cross-reference on the
@@ -2224,11 +2372,30 @@ interface GitHubIssueShape {
 }
 declare const GitHubIssue_base: Context.ServiceClass<GitHubIssue, "@effected/github/GitHubIssue", GitHubIssueShape>;
 /**
- * Issues.
+ * Read, list, close and comment on issues, and resolve the issues a pull
+ * request closes.
+ *
+ * @remarks
+ * Provide it with {@link GitHubIssue.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { GitHubIssue } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const closeWontFix = (number: number) =>
+ *   Effect.gen(function* () {
+ *     const issues = yield* GitHubIssue;
+ *     yield* issues.comment(number, "Closing as not planned.");
+ *     yield* issues.close(number, "not_planned");
+ *   });
+ * ```
  *
  * @public
  */
 export declare class GitHubIssue extends GitHubIssue_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubIssue, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<GitHubIssueShape>) => GitHubIssueShape;
@@ -2250,7 +2417,7 @@ declare const ReleaseInfo_base: Schema.Class<ReleaseInfo, Schema.Struct<{
   readonly uploadUrl: Schema.String;
 }>, {}>;
 /**
- * A release.
+ * A release, projected to the fields callers read.
  *
  * @public
  */
@@ -2270,11 +2437,12 @@ declare const ReleaseAsset_base: Schema.Class<ReleaseAsset, Schema.Struct<{
  */
 export declare class ReleaseAsset extends ReleaseAsset_base {}
 /**
- * Releases and their assets.
+ * Create, read, list and update releases, and upload and list their assets.
  *
  * @public
  */
 interface GitHubReleaseShape {
+  /** Create a release for `tag`. Unset fields are left to GitHub's defaults. */
   readonly create: (input: {
     readonly tag: string;
     readonly name?: string | undefined;
@@ -2283,12 +2451,15 @@ interface GitHubReleaseShape {
     readonly prerelease?: boolean | undefined;
     readonly generateReleaseNotes?: boolean | undefined;
   }) => Effect.Effect<ReleaseInfo, GitHubError, Repo>;
+  /** Read the release for `tag`. Fails `notFound` when there is none. */
   readonly getByTag: (tag: string) => Effect.Effect<ReleaseInfo, GitHubError, Repo>;
   /** As {@link GitHubReleaseShape.getByTag}, with absence as `Option.none`. */
   readonly getByTagOption: (tag: string) => Effect.Effect<Option.Option<ReleaseInfo>, GitHubError, Repo>;
+  /** List releases, paginated. */
   readonly list: (options?: {
     readonly page?: PageOptions | undefined;
   }) => Effect.Effect<ReadonlyArray<ReleaseInfo>, GitHubError, Repo>;
+  /** Patch a release by id; only the fields given are sent. */
   readonly update: (id: number, patch: {
     readonly name?: string | undefined;
     readonly body?: string | undefined;
@@ -2317,17 +2488,36 @@ interface GitHubReleaseShape {
     readonly contentType: string;
     readonly label?: string | undefined;
   }) => Effect.Effect<ReleaseAsset, GitHubError, Repo>;
+  /** List a release's assets, paginated. */
   readonly listAssets: (id: number, options?: {
     readonly page?: PageOptions | undefined;
   }) => Effect.Effect<ReadonlyArray<ReleaseAsset>, GitHubError, Repo>;
 }
 declare const GitHubRelease_base: Context.ServiceClass<GitHubRelease, "@effected/github/GitHubRelease", GitHubReleaseShape>;
 /**
- * Releases.
+ * Create, read, list and update GitHub releases, and upload and list their
+ * assets.
+ *
+ * @remarks
+ * Provide it with {@link GitHubRelease.layer}, which needs a `GitHubClient`;
+ * each method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { GitHubRelease } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const publish = Effect.gen(function* () {
+ *   const releases = yield* GitHubRelease;
+ *   const release = yield* releases.create({ tag: "v1.2.3", generateReleaseNotes: true });
+ *   return release.url;
+ * });
+ * ```
  *
  * @public
  */
 export declare class GitHubRelease extends GitHubRelease_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubRelease, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<GitHubReleaseShape>) => GitHubReleaseShape;
@@ -2340,11 +2530,9 @@ export declare class GitHubRelease extends GitHubRelease_base {
  * Everything GitHub reports about a repository.
  *
  * @remarks
- * The **generated** response type, not a hand-written projection. One surveyed
- * consumer declared a sixteen-field interface for this endpoint and round-tripped
- * those fields back through `PATCH` — and every one of the sixteen already
- * existed, verbatim, in the OpenAPI types the package now leans on. Re-declaring
- * them would have been the same mistake with our name on it.
+ * The **generated** response type for `GET /repos/{owner}/{repo}`, not a
+ * hand-written projection, so every field GitHub documents is available with
+ * its documented type.
  *
  * @public
  */
@@ -2363,10 +2551,9 @@ type RepositoryPatch = Omit<Params<"PATCH /repos/{owner}/{repo}">, "owner" | "re
  * The shape you actually have when you are applying only what a user
  * configured. Octokit's generated params spell an optional field as
  * `has_issues?: boolean`, **not** `has_issues?: boolean | undefined`, so under
- * `exactOptionalPropertyTypes` — on in this repo and in the silk tsconfig base
- * — a `Partial<T>` built from your own settings schema does not assign to
- * `RepositoryPatch` at all. This type does, and {@link repositoryPatch} turns
- * it into one.
+ * `exactOptionalPropertyTypes` a `Partial<T>` built from your own settings
+ * schema does not assign to `RepositoryPatch` at all. This type does, and
+ * {@link repositoryPatch} turns it into one.
  *
  * @public
  */
@@ -2377,10 +2564,7 @@ type RepositoryPatchDraft = { readonly [K in keyof RepositoryPatch]?: Repository
  *
  * @remarks
  * The supported spelling for "apply only what was configured" — the natural
- * shape for a sync action, and the one the checker cannot follow on its own.
- * Without it a consumer under the recommended tsconfig is quietly pushed toward
- * `as`, which is a real cost in a package whose stated design property is that
- * the route is the key and there are no casts.
+ * shape for a sync action, without a cast at the call site.
  *
  * Dropping the key rather than sending `undefined` is what the wire needs:
  * `PATCH` treats an absent field as "leave it alone", while an explicit `null`
@@ -2433,12 +2617,9 @@ export declare const SECURITY_ANALYSIS_STATUS_FIELDS: ReadonlySet<string>;
  * `PATCH /repos/{owner}/{repo}` route accepts none of them, and
  * `has_discussions` is the treacherous one: the REST **read** returns it, so
  * routing its write to the PATCH looks symmetric, but the PATCH silently
- * ignores unknown body fields and answers 200 — reported as applied on every
- * run while the repository never changed (effected#358). Setting any of these
- * forces a second round trip to learn the repository's node id.
- *
- * Field names verified against `UpdateRepositoryInput` by live introspection,
- * 2026-08-15.
+ * ignores unknown body fields and answers 200, so the write would look applied
+ * while the repository never changed. Setting any of these forces a second
+ * round trip to learn the repository's node id.
  *
  * @public
  */
@@ -2490,7 +2671,8 @@ interface AppliedSettings {
   readonly graphql: ReadonlyArray<string>;
 }
 /**
- * The repository itself.
+ * Read and update a repository's settings, and look up its default branch, node
+ * id and owner type.
  *
  * @public
  */
@@ -2503,8 +2685,7 @@ interface GitHubRepositoryShape {
    * The default branch's name.
    *
    * @remarks
-   * One surveyed consumer spent eight lines of hand-written octokit interface
-   * plus eleven lines of code to read this one string.
+   * Reads the repository payload and returns `default_branch`.
    */
   readonly defaultBranch: Effect.Effect<string, GitHubError, Repo>;
   /**
@@ -2512,7 +2693,7 @@ interface GitHubRepositoryShape {
    *
    * @remarks
    * Needed as `repositoryId` by the `createLinkedBranch` and `createPullRequest`
-   * mutations, which is why a second consumer cast `repos.get` for it alone.
+   * mutations.
    */
   readonly nodeId: Effect.Effect<string, GitHubError, Repo>;
   /**
@@ -2536,13 +2717,14 @@ interface GitHubRepositoryShape {
    * @remarks
    * `updateSettings` is the thin, faithfully-typed PATCH and returns what
    * GitHub then reports. This is the **applicator**: it takes an open map,
-   * routes each key to whichever API can actually set it, and returns nothing.
+   * routes each key to whichever API can actually set it, and returns an
+   * {@link AppliedSettings} naming the keys that were sent through each.
    *
-   * Two settings — `has_sponsorships` and `has_pull_requests` — have never
-   * existed on the REST endpoint and are only reachable through GraphQL's
-   * `updateRepository`, which addresses a repository by **node id**. So a map
-   * touching either costs an extra read; a map touching neither does not, which
-   * is the common case.
+   * Three settings — `has_sponsorships`, `has_pull_requests` and
+   * `has_discussions` ({@link GRAPHQL_ONLY_SETTINGS}) — are only reachable
+   * through GraphQL's `updateRepository`, which addresses a repository by **node
+   * id**. So a map touching any of them costs an extra read; a map touching none
+   * does not, which is the common case.
    *
    * The map is open by design. GitHub's settings surface is large and moving,
    * and a closed type here would date the package — but it also means a typo is
@@ -2553,11 +2735,31 @@ interface GitHubRepositoryShape {
 }
 declare const GitHubRepository_base: Context.ServiceClass<GitHubRepository, "@effected/github/GitHubRepository", GitHubRepositoryShape>;
 /**
- * Repository settings and coordinates.
+ * Read and update a repository's settings, including settings only GraphQL can
+ * write, and look up its default branch, node id and owner type.
+ *
+ * @remarks
+ * Provide it with {@link GitHubRepository.layer}, which needs a `GitHubClient`;
+ * every member also needs a `Repo` in `R`. `settings`, `defaultBranch`, `nodeId`
+ * and `ownerType` are `Effect` values, not functions.
+ *
+ * @example
+ * ```ts
+ * import { GitHubRepository } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const repository = yield* GitHubRepository;
+ *   const branch = yield* repository.defaultBranch;
+ *   const applied = yield* repository.applySettings({ has_wiki: false, has_discussions: true });
+ *   return { branch, applied }; // applied.rest, applied.graphql
+ * });
+ * ```
  *
  * @public
  */
 export declare class GitHubRepository extends GitHubRepository_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubRepository, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<GitHubRepositoryShape>) => GitHubRepositoryShape;
@@ -2597,7 +2799,7 @@ export declare class SemverTag extends SemverTag_base {}
  *
  * @remarks
  * The default covers the three shapes `@effected/workspaces`' `ReleaseTag`
- * produces and the surveyed repos actually cut: `v1.2.3`, `pkg@v1.2.3` and
+ * produces: `v1.2.3`, `pkg@v1.2.3` and
  * `@scope/pkg@1.2.3`. Taking the substring after the **last** `@` is what makes
  * the scoped form work, since the scope itself contains one.
  *
@@ -2633,7 +2835,7 @@ interface GitTagShape {
   readonly upsert: (tag: string, sha: string) => Effect.Effect<void, GitHubError, Repo>;
   /** Delete the tag ref. */
   readonly delete: (tag: string) => Effect.Effect<void, GitHubError, Repo>;
-  /** Every tag, newest GitHub-order first. `prefix` filters client-side. */
+  /** Every tag, in GitHub's order. `prefix` filters client-side. */
   readonly list: (options?: {
     readonly prefix?: string | undefined;
     readonly page?: PageOptions | undefined;
@@ -2649,10 +2851,9 @@ interface GitTagShape {
    * The newest version-shaped tag.
    *
    * @remarks
-   * Replaces thirty-five lines at one surveyed call site that ran **one
-   * `Effect.result` per parse and another per comparison** to answer this. Both
-   * are synchronous in `@effected/semver` (`parseResult`, `compare`), so this is
-   * a single pass over the page stream with no round trips at all.
+   * Parsing and comparison are both synchronous in `@effected/semver`
+   * (`parseResult`, `compare`), so this is a single pass over the page stream
+   * with no extra round trips.
    *
    * **"Newest" means highest version, not most recent.** That is the right
    * answer for a single-versioned repository and the wrong instrument for a
@@ -2660,8 +2861,7 @@ interface GitTagShape {
    * ordering and recency are unrelated: a `pkg-a@2.0.0` tag outranks a
    * `pkg-b@1.4.0` cut yesterday, so the result can sit several releases behind
    * the actual head and never move. Nothing about the failure is visible —
-   * a stale-but-plausible tag comes back, and one consumer pinned its release
-   * boundary two releases back, permanently. In a monorepo, filter by the
+   * a stale-but-plausible tag comes back. In a monorepo, filter by the
    * package's tag prefix (see {@link LatestSemverOptions}) so the comparison
    * runs within one version line, or order by tagged-commit date instead.
    */
@@ -2669,11 +2869,29 @@ interface GitTagShape {
 }
 declare const GitTag_base: Context.ServiceClass<GitTag, "@effected/github/GitTag", GitTagShape>;
 /**
- * Tags.
+ * Create, move, resolve, list and delete tag refs through GitHub's Git Database
+ * API, and find the newest version-shaped tag.
+ *
+ * @remarks
+ * Provide it with {@link GitTag.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { GitTag } from "@effected/github";
+ * import { Effect, Option } from "effect";
+ *
+ * const latest = Effect.gen(function* () {
+ *   const tags = yield* GitTag;
+ *   const newest = yield* tags.latestSemver({ prefix: "v" });
+ *   return Option.map(newest, (tag) => tag.version.toString());
+ * });
+ * ```
  *
  * @public
  */
 export declare class GitTag extends GitTag_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitTag, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<GitTagShape>) => GitTagShape;
@@ -2722,28 +2940,32 @@ declare const PullRequestInfo_base: Schema.Class<PullRequestInfo, Schema.Struct<
  *
  * @remarks
  * This is the **domain** shape, and the only pull-request type this package
- * exports. The wire shape GitHub actually answers with is the private
- * `RawPull` interface further down this module, and the two are deliberately
- * different: `RawPull` nests `head`/`base` as `{ ref, sha }` and spells the
- * link `html_url`, where this class flattens them to `head`/`headSha` and
- * spells it `url`. Reading the wrong one produces code that typechecks against
- * a member set the boundary will never hand it. If you are writing a test
- * double or a fixture, this is the type you build.
+ * exports. It flattens GitHub's nested `head`/`base` objects to
+ * `head`/`headSha` and `base`/`baseSha`, and spells the link `url`. If you are
+ * writing a test double or a fixture, this is the type you build.
  *
  * @public
  */
 export declare class PullRequestInfo extends PullRequestInfo_base {}
-/** What {@link PullRequestShape.upsert} did. @public */
+/**
+ * What {@link PullRequestShape.upsert} did.
+ *
+ * @public
+ */
 interface UpsertedPullRequest {
+  /** The pull request, as created or as updated. */
   readonly pullRequest: PullRequestInfo;
+  /** `true` when a new pull request was opened, `false` when an open one was updated. */
   readonly created: boolean;
 }
 /**
- * Pull requests.
+ * Read, list, create, update, merge and label pull requests, and control
+ * auto-merge.
  *
  * @public
  */
 interface PullRequestShape {
+  /** Read one pull request. Fails `notFound` when it does not exist. */
   readonly get: (number: number) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
   /**
    * Open, closed or all pull requests, optionally filtered.
@@ -2752,10 +2974,8 @@ interface PullRequestShape {
    * `head` accepts **either** the qualified `owner:ref` GitHub's filter wants
    * or a bare `ref`, which is qualified with the current repo's owner on the
    * way out. So for a pull request opened **from the current repository**,
-   * feeding this method `PullRequestInfo.head` — which is the bare
-   * `raw.head.ref` — round-trips correctly, and a consumer filtering the full
-   * list client-side because the raw REST route ignores an unqualified ref no
-   * longer needs to.
+   * feeding this method `PullRequestInfo.head` (the bare branch name)
+   * round-trips correctly; GitHub's own route ignores an unqualified ref.
    *
    * **The round trip does not hold for a fork-originated pull request.**
    * `PullRequestInfo` projects only the ref and drops the source owner, so
@@ -2777,9 +2997,7 @@ interface PullRequestShape {
    * Each entry is a full {@link CommitFile} — path **and** status, plus the
    * line counts and any pre-rename path — the same projection
    * `GitHubCommit.changedFiles` returns, because GitHub answers both
-   * endpoints with the same `diff-entry` shape. An earlier version projected
-   * to the path alone, and consumers who needed the status fell back to a raw
-   * route.
+   * endpoints with the same `diff-entry` shape.
    */
   readonly listFiles: (number: number, options?: {
     readonly page?: PageOptions | undefined;
@@ -2788,14 +3006,12 @@ interface PullRequestShape {
    * The pull requests associated with a commit.
    *
    * @remarks
-   * Named for the question it answers, because the previous surface had this
-   * method and one consumer never found it — dropping to a raw octokit callback
-   * with the only `noExplicitAny` suppression in the entire survey. It also
-   * paginates now, which the previous one did not.
+   * Paginated: pass `page` to bound the walk.
    */
   readonly listAssociatedWithCommit: (sha: string, options?: {
     readonly page?: PageOptions | undefined;
   }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError, Repo>;
+  /** Open a pull request from `head` into `base`. */
   readonly create: (input: {
     readonly title: string;
     readonly head: string;
@@ -2803,13 +3019,20 @@ interface PullRequestShape {
     readonly body?: string | undefined;
     readonly draft?: boolean | undefined;
   }) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  /** Patch a pull request; only the fields given are sent. */
   readonly update: (number: number, patch: {
     readonly title?: string | undefined;
     readonly body?: string | undefined;
     readonly state?: "open" | "closed" | undefined;
     readonly base?: string | undefined;
   }) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
-  /** Update the open pull request for `head`→`base`, or open one. */
+  /**
+   * Update the open pull request for `head`→`base`, or open one.
+   *
+   * @remarks
+   * When a pull request is already open, only `title` and `body` are updated;
+   * `draft` applies only when a new pull request is opened.
+   */
   readonly upsert: (input: {
     readonly title: string;
     readonly head: string;
@@ -2817,12 +3040,15 @@ interface PullRequestShape {
     readonly body?: string | undefined;
     readonly draft?: boolean | undefined;
   }) => Effect.Effect<UpsertedPullRequest, GitHubError, Repo>;
+  /** Merge a pull request and return the merge commit sha. `method` defaults to GitHub's choice. */
   readonly merge: (number: number, options?: {
     readonly method?: "merge" | "squash" | "rebase" | undefined;
     readonly commitTitle?: string | undefined;
     readonly commitMessage?: string | undefined;
   }) => Effect.Effect<string, GitHubError, Repo>;
+  /** Add labels to a pull request (as an issue), keeping the ones already there. */
   readonly addLabels: (number: number, labels: ReadonlyArray<string>) => Effect.Effect<void, GitHubError, Repo>;
+  /** Request reviews from users and/or teams (team slugs). */
   readonly requestReviewers: (number: number, reviewers: {
     readonly users?: ReadonlyArray<string> | undefined;
     readonly teams?: ReadonlyArray<string> | undefined;
@@ -2831,20 +3057,42 @@ interface PullRequestShape {
    * Turn auto-merge on or off.
    *
    * @remarks
-   * An explicit call, not an option on `create`/`update`. The previous surface
-   * fired these mutations from an `Effect.tap` **after** the create succeeded,
-   * so a create that worked could still surface an auto-merge failure as if the
-   * create had failed.
+   * An explicit call, not an option on `create`/`update`, so a create that
+   * worked is never reported as failed because auto-merge was refused. Pass
+   * `"off"` to disable it.
    */
   readonly setAutoMerge: (pullRequest: PullRequestInfo, method: "merge" | "squash" | "rebase" | "off") => Effect.Effect<void, GitHubGraphQLError, Repo>;
 }
 declare const PullRequest_base: Context.ServiceClass<PullRequest, "@effected/github/PullRequest", PullRequestShape>;
 /**
- * Pull requests.
+ * Read, list, create, update, merge and label pull requests, and control
+ * auto-merge.
+ *
+ * @remarks
+ * Provide it with {@link PullRequest.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { PullRequest } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const openOrUpdate = Effect.gen(function* () {
+ *   const pulls = yield* PullRequest;
+ *   const { pullRequest, created } = yield* pulls.upsert({
+ *     title: "chore: release",
+ *     head: "changeset-release/main",
+ *     base: "main",
+ *   });
+ *   yield* pulls.setAutoMerge(pullRequest, "squash");
+ *   return created;
+ * });
+ * ```
  *
  * @public
  */
 export declare class PullRequest extends PullRequest_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<PullRequest, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<PullRequestShape>) => PullRequestShape;
@@ -2875,10 +3123,12 @@ type SecretScope = "actions" | "dependabot" | "codespaces";
  * @public
  */
 interface SecretInfo {
+  /** The secret's name. */
   readonly name: string;
 }
 /**
- * Repository and environment secrets.
+ * Write, list and delete Actions, Dependabot and Codespaces secrets on a
+ * repository, and Actions secrets on its environments.
  *
  * @public
  */
@@ -2898,7 +3148,8 @@ interface RepositorySecretShape {
 }
 declare const RepositorySecret_base: Context.ServiceClass<RepositorySecret, "@effected/github/RepositorySecret", RepositorySecretShape>;
 /**
- * Secrets, encrypted client-side before they leave the process.
+ * Write, list and delete repository and environment secrets, encrypted
+ * client-side before they leave the process.
  *
  * @remarks
  * Every write is a **two-step**: fetch the store's public key, then `PUT` a
@@ -2914,10 +3165,27 @@ declare const RepositorySecret_base: Context.ServiceClass<RepositorySecret, "@ef
  * the type; this module performs the single `Redacted.value` unwrap, at the
  * moment of encryption, and the sealed box is what continues.
  *
+ * Provide it with {@link RepositorySecret.layer}, which needs a `GitHubClient`;
+ * each method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { RepositorySecret } from "@effected/github";
+ * import { Effect, Redacted } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const secrets = yield* RepositorySecret;
+ *   yield* secrets.set("NPM_TOKEN", Redacted.make("npm_example"), "actions");
+ *   return yield* secrets.list("actions"); // names only; values are never returned
+ * });
+ * ```
+ *
  * @public
  */
 export declare class RepositorySecret extends RepositorySecret_base {
   /**
+   * The live service, built over a `GitHubClient`.
+   *
    * @remarks
    * `(client) => make(client)` rather than `make`: a static initializer runs
    * while the module body is still evaluating, so naming a `const` declared
@@ -2932,7 +3200,9 @@ export declare class RepositorySecret extends RepositorySecret_base {
 //#endregion
 //#region src/RepositorySecurity.d.ts
 /**
- * The three repository security features that have their own endpoints.
+ * Read and toggle the three repository security features that have their own
+ * endpoints: Dependabot alerts, Dependabot security fixes and private
+ * vulnerability reporting.
  *
  * @public
  */
@@ -2952,7 +3222,8 @@ interface RepositorySecurityShape {
 }
 declare const RepositorySecurity_base: Context.ServiceClass<RepositorySecurity, "@effected/github/RepositorySecurity", RepositorySecurityShape>;
 /**
- * Repository security features with dedicated endpoints.
+ * Read and toggle Dependabot alerts, Dependabot security fixes and private
+ * vulnerability reporting.
  *
  * @remarks
  * These are **not** `security_and_analysis` fields and cannot ride along on the
@@ -2975,10 +3246,28 @@ declare const RepositorySecurity_base: Context.ServiceClass<RepositorySecurity,
  * every other failure still fails. A 404 from the other two is a real failure
  * and stays one, which is why the mapping is not applied uniformly.
  *
+ * Provide it with {@link RepositorySecurity.layer}, which needs a
+ * `GitHubClient`; each method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { RepositorySecurity } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const harden = Effect.gen(function* () {
+ *   const security = yield* RepositorySecurity;
+ *   yield* security.setVulnerabilityAlerts(true);
+ *   yield* security.setPrivateVulnerabilityReporting(true);
+ *   return yield* security.vulnerabilityAlerts(); // true
+ * });
+ * ```
+ *
  * @public
  */
 export declare class RepositorySecurity extends RepositorySecurity_base {
   /**
+   * The live service, built over a `GitHubClient`.
+   *
    * @remarks
    * `(client) => make(client)` rather than `make`: a static initializer runs
    * while the module body is still evaluating, so naming a `const` declared
@@ -2993,7 +3282,7 @@ export declare class RepositorySecurity extends RepositorySecurity_base {
 //#endregion
 //#region src/RepositoryVariable.d.ts
 /**
- * A variable, as listing returns it.
+ * A variable's name and value, as listing returns it.
  *
  * @remarks
  * Unlike a secret this carries its **value**: variables are readable, so a
@@ -3004,11 +3293,14 @@ export declare class RepositorySecurity extends RepositorySecurity_base {
  * @public
  */
 interface VariableInfo {
+  /** The variable's name. */
   readonly name: string;
+  /** The variable's current value. */
   readonly value: string;
 }
 /**
- * Repository and environment variables.
+ * Create or update, list and delete Actions variables on a repository and on
+ * its environments.
  *
  * @public
  */
@@ -3029,9 +3321,7 @@ interface RepositoryVariableShape {
    * treating any error as absence would turn a permissions problem into a
    * spurious create.
    *
-   * **The 404-for-absent behaviour is documented, not probed.** Neither this
-   * suite nor the first consumer's has issued this read against real GitHub —
-   * both run against doubles.
+   * The 404-for-absent behaviour is GitHub's documented contract.
    *
    * Only `notFound` selects the create branch: a successful read selects the
    * update branch, and any other failure propagates rather than being guessed
@@ -3055,7 +3345,8 @@ interface RepositoryVariableShape {
 }
 declare const RepositoryVariable_base: Context.ServiceClass<RepositoryVariable, "@effected/github/RepositoryVariable", RepositoryVariableShape>;
 /**
- * Repository and environment variables.
+ * Create or update, list and delete Actions variables on a repository and on
+ * its environments.
  *
  * @remarks
  * No encryption and no public key, unlike secrets — but also **no upsert**,
@@ -3063,10 +3354,27 @@ declare const RepositoryVariable_base: Context.ServiceClass<RepositoryVariable,
  * the create and update routes are different endpoints with different verbs and
  * neither tolerates the other's case.
  *
+ * Provide it with {@link RepositoryVariable.layer}, which needs a
+ * `GitHubClient`; each method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { RepositoryVariable } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const variables = yield* RepositoryVariable;
+ *   yield* variables.set("DEPLOY_REGION", "eu-west-1"); // creates or updates
+ *   return yield* variables.list();
+ * });
+ * ```
+ *
  * @public
  */
 export declare class RepositoryVariable extends RepositoryVariable_base {
   /**
+   * The live service, built over a `GitHubClient`.
+   *
    * @remarks
    * `(client) => make(client)` rather than `make`: a static initializer runs
    * while the module body is still evaluating, so naming a `const` declared
@@ -3092,7 +3400,9 @@ export declare class RepositoryVariable extends RepositoryVariable_base {
  * @public
  */
 interface RulesetInfo {
+  /** The ruleset's numeric id. */
   readonly id: number;
+  /** The ruleset's name. */
   readonly name: string;
   /** `"Repository"` for the repository's own, `"Organization"` for an inherited one. */
   readonly source_type?: string | undefined;
@@ -3108,15 +3418,22 @@ interface RulesetInfo {
  * @public
  */
 interface RulesetPayload {
+  /** The ruleset's name, which `upsert` matches on. */
   readonly name: string;
+  /** What it applies to: `"branch"`, `"tag"` or `"push"`. */
   readonly target: string;
+  /** `"active"`, `"evaluate"` or `"disabled"`. */
   readonly enforcement: string;
+  /** Which refs it applies to. Passed to GitHub as given. */
   readonly conditions?: unknown;
+  /** The rules it enforces. Passed to GitHub as given. */
   readonly rules?: unknown;
+  /** Actors allowed to bypass it. Passed to GitHub as given. */
   readonly bypass_actors?: unknown;
 }
 /**
- * Repository rulesets, and the lookups their bypass actors need.
+ * Create or update, list and delete repository rulesets, and look up the team
+ * and role ids their bypass actors need.
  *
  * @public
  */
@@ -3149,7 +3466,8 @@ interface RulesetShape {
 }
 declare const Ruleset_base: Context.ServiceClass<Ruleset, "@effected/github/Ruleset", RulesetShape>;
 /**
- * Repository rulesets.
+ * Create or update, list and delete repository rulesets, and look up the team
+ * and role ids their bypass actors need.
  *
  * @remarks
  * ## An inherited ruleset is never written to
@@ -3161,14 +3479,34 @@ declare const Ruleset_base: Context.ServiceClass<Ruleset, "@effected/github/Rule
  * that never mentioned the organization.
  *
  * {@link RulesetShape.upsert} filters on `source_type` before matching, so an
- * inherited ruleset can never be the target of a write. This arrived as a fix
- * for a live defect in the consumer this module was ported from, where the
- * filter was absent.
+ * inherited ruleset can never be the target of a write.
+ *
+ * Provide it with {@link Ruleset.layer}, which needs a `GitHubClient`; each
+ * method also needs a `Repo` in `R`.
+ *
+ * @example
+ * ```ts
+ * import { Ruleset } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * const protectMain = Effect.gen(function* () {
+ *   const rulesets = yield* Ruleset;
+ *   yield* rulesets.upsert({
+ *     name: "protect-main",
+ *     target: "branch",
+ *     enforcement: "active",
+ *     conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+ *     rules: [{ type: "deletion" }],
+ *   });
+ * });
+ * ```
  *
  * @public
  */
 export declare class Ruleset extends Ruleset_base {
   /**
+   * The live service, built over a `GitHubClient`.
+   *
    * @remarks
    * `(client) => make(client)` rather than `make`: a static initializer runs
    * while the module body is still evaluating, so naming a `const` declared
@@ -3205,7 +3543,9 @@ declare const PermissionGap_base: Schema.Class<PermissionGap, Schema.Struct<{
  */
 export declare class PermissionGap extends PermissionGap_base {}
 declare const ExtraPermission_base: Schema.Class<ExtraPermission, Schema.Struct<{
+  /** The permission's name, e.g. `"contents"`. */
   readonly permission: Schema.String;
+  /** What the token has. */
   readonly granted: Schema.Literals<readonly ["read", "write", "admin"]>;
   /** What was asked for, when anything was. */
   readonly required: Schema.optionalKey<Schema.Literals<readonly ["read", "write", "admin"]>>;
@@ -3255,17 +3595,12 @@ declare const TokenPermissions_base: Schema.Class<TokenPermissions, Schema.Struc
  * The permissions a token was granted, and what they satisfy.
  *
  * @remarks
- * **A pure class, not a service.** The version this replaces was a
- * `Context.Service` whose live layer was a `Layer.succeed` with zero octokit
- * calls and an empty `R` — a `read < write < admin` comparator behind a service
- * boundary that bought nothing. It cost something, though: its test double
- * reimplemented the entire ranking and every assertion branch, making it the
- * heaviest of the thirty-eight doubles in the package.
- *
- * Here there is no service, no layer and no double: a caller holds the
- * permissions GitHub already gave it (`InstallationToken.permissions`) and
- * compares them. The only `Effect`s are the two assertions, and they exist only
- * because failing typed is more useful than returning a boolean.
+ * **A pure class, not a service.** It compares permission levels
+ * (`read < write < admin`), so there is no layer and no test double: a caller
+ * holds the permissions GitHub already gave it (`InstallationToken.permissions`)
+ * and compares them. The only `Effect`s are the two assertions, which fail with
+ * `TokenPermissionError` because failing typed is more useful than returning a
+ * boolean.
  *
  * @example
  * ```ts
@@ -3308,11 +3643,13 @@ export declare class TokenPermissions extends TokenPermissions_base {
 //#endregion
 //#region src/WorkflowDispatch.d.ts
 declare const WorkflowRunStatus_base: Schema.Class<WorkflowRunStatus, Schema.Struct<{
+  /** The run's numeric id. */
   readonly id: Schema.Int;
   /** `queued`, `in_progress`, `completed`, … */
   readonly status: Schema.String;
   /** Set once `status` is `completed`. */
   readonly conclusion: Schema.optionalKey<Schema.String>;
+  /** The run's web URL. */
   readonly url: Schema.String;
 }>, {}>;
 /**
@@ -3331,9 +3668,8 @@ export declare class WorkflowRunStatus extends WorkflowRunStatus_base {
  * `state` is GitHub's own value — `active`, `disabled_manually`,
  * `disabled_inactivity`, and so on. It is reported rather than interpreted:
  * whether a *disabled* workflow counts for a given GitHub feature is that
- * feature's rule, not this package's, and encoding a guess here would put an
- * unverified server-side behaviour in a library that cannot test it. Callers
- * that care filter on it themselves.
+ * feature's rule, not this package's. Callers that care filter on it
+ * themselves.
  *
  * @public
  */
@@ -3348,7 +3684,7 @@ interface WorkflowInfo {
   readonly state: string;
 }
 /**
- * How long to wait for a dispatched run.
+ * How often to poll for a dispatched run, and how long to keep polling.
  *
  * @public
  */
@@ -3359,13 +3695,15 @@ interface PollOptions {
   readonly timeout?: Duration.Duration | undefined;
 }
 /**
- * Triggering workflows.
+ * Dispatch workflows, wait for the run they start, and list the repository's
+ * workflows.
  *
  * @public
  */
 interface WorkflowDispatchShape {
   /** Fire a `workflow_dispatch` event. GitHub answers 204 with no run id. */
   readonly dispatch: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<void, GitHubError, Repo>;
+  /** Read one workflow run's status. */
   readonly runStatus: (runId: number) => Effect.Effect<WorkflowRunStatus, GitHubError, Repo>;
   /**
    * Every workflow defined in the repository.
@@ -3386,10 +3724,11 @@ interface WorkflowDispatchShape {
    * Dispatch, find the run it created, and wait for it to finish.
    *
    * @remarks
-   * The wait is `Effect.repeat` with a predicate over the **success** value.
-   * The version this replaces encoded "not finished yet" as a sentinel *error*
-   * baked into a user-visible error union — control flow in the error channel,
-   * which every consumer then had to know not to treat as a failure.
+   * The wait is `Effect.repeat` with a predicate over the **success** value, so
+   * "not finished yet" is never an error. If the run is not found finished
+   * within `poll.timeout`, it fails with a `rejected` `GitHubError` (status
+   * 408). The run is matched by branch, creation time and workflow path, so
+   * concurrent dispatches of the same workflow on the same ref can be confused.
    */
   readonly dispatchAndWait: (workflow: string, ref: string, options?: {
     readonly inputs?: Record<string, string> | undefined;
@@ -3398,11 +3737,33 @@ interface WorkflowDispatchShape {
 }
 declare const WorkflowDispatch_base: Context.ServiceClass<WorkflowDispatch, "@effected/github/WorkflowDispatch", WorkflowDispatchShape>;
 /**
- * Workflow dispatch.
+ * Dispatch workflows, wait for the run they start, and list the repository's
+ * workflows.
+ *
+ * @remarks
+ * Provide it with {@link WorkflowDispatch.layer}, which needs a `GitHubClient`;
+ * each method also needs a `Repo` in `R`. `list` is an `Effect` value, not a
+ * function.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowDispatch } from "@effected/github";
+ * import { Duration, Effect } from "effect";
+ *
+ * const release = Effect.gen(function* () {
+ *   const workflows = yield* WorkflowDispatch;
+ *   const run = yield* workflows.dispatchAndWait("release.yml", "main", {
+ *     inputs: { dryRun: "false" },
+ *     poll: { interval: Duration.seconds(15), timeout: Duration.minutes(20) },
+ *   });
+ *   return run.conclusion;
+ * });
+ * ```
  *
  * @public
  */
 export declare class WorkflowDispatch extends WorkflowDispatch_base {
+  /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<WorkflowDispatch, never, GitHubClient>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<WorkflowDispatchShape>) => WorkflowDispatchShape;