@@ -0,0 +1,139 @@
+# ADR-0042 — Prefill the official examples repository and discover branches
+
+- Status: **Accepted**
+- Date: 2026-08-27
+- Extends: [ADR-0040](0040-sha-pinned-connected-github-import.md)
+- Extends: [ADR-0041](0041-separate-official-examples-repository.md)
+
+## Context
+
+The connected GitHub importer accepts any canonical public repository URL and
+an optional branch, tag, or commit. That generic input is powerful, but an
+empty repository field and free-form ref field make the first import harder
+than necessary for a novice. The separately governed official collection now
+has a stable public identity at <https://github.com/PyBLE-dev/examples>, so the
+app can offer that identity as a starting value without coupling to the
+maintainer's local checkout or granting the repository additional trust.
+
+GitHub exposes public branch names through a paginated, unauthenticated REST
+endpoint. Branch discovery is mutable navigation metadata, not an immutable
+source identity: a selected name must still be resolved again and pinned to a
+full commit SHA before any tree or blob is browsed. Unauthenticated requests
+are also rate- and resource-limited, so “all branches” needs a complete,
+explicitly bounded result rather than an unbounded or silently partial list.
+
+ADR-0040 deliberately preserved explicit tag and commit refs. Removing those
+inputs would break existing advanced and reproducible-import workflows.
+
+## Decision
+
+1. **Prefill, but keep the repository editable.** Every newly opened GitHub
+   import action initializes **Public repository URL** to
+   `https://github.com/PyBLE-dev/examples`. The user may replace it with any
+   other canonical public GitHub repository root accepted by the existing
+   parser. Reopening the action starts again from the official value; the app
+   does not persist a previous repository in this increment.
+
+2. **Treat the official value as ordinary untrusted input.** The prefill is a
+   local UI convenience, not an allowlist, trust signal, compatibility claim,
+   build input, or link to `/Users/vyv/Working/SciLabPro/PyBLE-Examples`. It
+   crosses the same exact-host network boundary and the same SHA pinning,
+   object validation, size, UTF-8, overwrite, session, and board-write gates as
+   every custom repository. It causes no automatic file selection, source
+   fetch, import, editor open, Save, or Run.
+
+3. **Make branches the normal ref workflow.** The normal control is a
+   searchable, keyboard- and screen-reader-operable branch-only chooser. The
+   app reads the repository's reported default branch, places it first, marks
+   it as the default, and initially selects it. Remaining exact branch names
+   use deterministic code-point order. Branch names are opaque technical
+   values and are never localized or rewritten.
+
+4. **Retain advanced explicit refs.** A clearly labelled advanced action
+   switches to manual branch, tag, or commit entry. The existing ref
+   validation and blank-default behavior remain available there. Switching
+   modes or changing the manual ref invalidates any pinned snapshot,
+   navigation, selection, review, and overwrite consent. This preserves
+   ADR-0040's compatibility while keeping the default surface novice-focused.
+
+5. **Discover only after a user opens the importer.** App launch and ordinary
+   Files navigation make no GitHub request. Opening the explicit **Import
+   examples from GitHub** action may automatically discover branches for the
+   prefilled repository. Editing the URL immediately cancels and clears that
+   catalog and every dependent snapshot. It does not request on each
+   keystroke; the user explicitly loads or refreshes branches for an edited
+   canonical URL.
+
+6. **Return a complete bounded catalog or none.** Discovery first reads public
+   repository metadata for `default_branch`, then serially requests
+   `GET /repos/{owner}/{repo}/branches?per_page=100&page=N` without a
+   `protected` filter. It accepts at most 512 branch names over at most six
+   pages, at most 512 KiB per branch page, and at most 2 MiB for all branch-page
+   bodies. A 513th branch, another next page after the sixth, duplicate or
+   invalid name, malformed page, or exceeded byte bound returns a typed failure
+   and publishes no partial catalog. An empty catalog is displayed honestly
+   and cannot be browsed in branch mode.
+
+7. **Keep pagination inside the exact-host boundary.** The client validates
+   GitHub's `Link` pagination metadata, including exact HTTPS host, repository
+   branch path, `per_page`, and strictly increasing `page`. It never directly
+   follows a response-provided URL; it constructs the next exact
+   `api.github.com` request from validated local values. Each page uses the
+   existing absolute request deadline, cancellation, response-body, error,
+   and rate-limit rules.
+
+8. **Pin after selection.** A branch catalog and any commit SHA contained in a
+   branch-list response are advisory and moving. Browse passes only the chosen
+   name to the existing resolution operation, requires the returned full
+   commit and root-tree SHAs, displays the pinned commit, and derives every
+   subsequent tree/blob read from that immutable snapshot.
+
+9. **Share cancellation and rate state.** Branch loading is a distinct visible
+   network phase. Repository edits, refresh, mode changes, cancellation, and
+   dismissal advance the presentation generation and cancel any active
+   discovery. Late pages cannot repopulate the chooser. A GitHub-supplied
+   positive rate-limit delay gates branch load/refresh and all other
+   network-producing actions on the surface under ADR-0040's existing rule.
+
+10. **Specify and test the complete interaction.** ARB owns branch labels,
+    loading, refresh, default, empty, advanced-mode, and bound/error text.
+    Automated tests cover the editable prefill, custom-repository parity,
+    initial/default selection, branch-only results, advanced tag/commit
+    compatibility, bounded pagination, no partial publication, cancellation,
+    stale-result suppression, rate gating, immutable resolution, compact/wide
+    layouts, keyboard use, semantics, and 2× text.
+
+## Consequences
+
+- A novice can open the importer and choose an official branch without knowing
+  Git ref syntax or copying a URL.
+- Experienced users retain exact tags and commits for reproducible imports.
+- Large or changing repositories fail explicitly instead of showing a partial
+  list that could be mistaken for all branches.
+- Opening the importer uses additional public GitHub requests, but no other app
+  workflow becomes network-dependent and the existing rate-limit guidance
+  remains authoritative.
+- The official repository remains independently released and untrusted at the
+  importer boundary; this decision creates no filesystem or build coupling.
+
+## Alternatives considered
+
+- **Remove tags and commits entirely.** Rejected because it breaks the
+  explicit-ref contract and makes immutable, release-specific imports harder.
+- **Request branches after every URL keystroke.** Rejected because it wastes
+  the unauthenticated request budget and creates avoidable stale-response races.
+- **Follow `Link` URLs directly.** Rejected because response-provided URLs must
+  not widen the exact-host request boundary.
+- **Show only the first 100 branches.** Rejected because a partial list would
+  contradict the selector's “available branches” meaning.
+- **Make the official repository trusted or board-aware.** Rejected because
+  repository ownership is not evidence that source is safe for a particular
+  board or should execute automatically.
+
+## Related
+
+- [App requirements §4.9](../specifications/App/specs.md#49-github-public-repo-import-libgithub_import--fr-import)
+- [App TDD §10](../specifications/App/TDD.md#10-github-import-design-libgithub_import)
+- [PRD §9.7](../specifications/prd.md#97-github-public-repo-import-https)
+
+<!-- SPDX-License-Identifier: MIT -->
@@ -45,5 +45,6 @@ Each ADR captures one significant decision: its context, the choice, and the con
 | [0039](0039-admit-waveshare-single-page-largest-block-transient.md) | Admit the characterized Waveshare single-page largest-block transient with a fixed 98304 floor in a V5 source era, with byte-identity-conditioned evidence carry-forward | Accepted |
 | [0040](0040-sha-pinned-connected-github-import.md) | Ship GitHub import first as a SHA-pinned, bounded connected-board subset while durable local files and provenance remain deferred | Accepted |
 | [0041](0041-separate-official-examples-repository.md) | Maintain the official user-facing runnable examples in a separately governed repository while PyBLE retains only its importer fixtures and bundled offline examples | Accepted |
+| [0042](0042-prefill-official-examples-and-discover-branches.md) | Prefill the editable official examples repository and provide bounded, branch-only discovery while retaining advanced explicit refs | Accepted |
 
-Decided 2026-06-30 (0001–0005); 0006 accepted 2026-07-01; 0007, 0008, 0009 and 0010 accepted 2026-07-02; 0011 accepted 2026-07-03; 0012 accepted 2026-07-25; 0013 accepted 2026-07-27; 0014, 0015, 0016, and 0017 accepted 2026-07-28; 0018–0022 accepted 2026-07-29; 0023 and 0024 accepted 2026-08-01; 0025 and 0026 accepted 2026-08-02; 0027–0029 accepted 2026-08-03; 0030 accepted 2026-08-11; 0031–0033 accepted 2026-08-12; 0034 accepted 2026-08-13; 0035 and 0036 accepted 2026-08-16; 0037 and 0038 accepted 2026-08-20; 0039 accepted 2026-08-21; 0040 accepted 2026-08-22; 0041 accepted 2026-08-25.
+Decided 2026-06-30 (0001–0005); 0006 accepted 2026-07-01; 0007, 0008, 0009 and 0010 accepted 2026-07-02; 0011 accepted 2026-07-03; 0012 accepted 2026-07-25; 0013 accepted 2026-07-27; 0014, 0015, 0016, and 0017 accepted 2026-07-28; 0018–0022 accepted 2026-07-29; 0023 and 0024 accepted 2026-08-01; 0025 and 0026 accepted 2026-08-02; 0027–0029 accepted 2026-08-03; 0030 accepted 2026-08-11; 0031–0033 accepted 2026-08-12; 0034 accepted 2026-08-13; 0035 and 0036 accepted 2026-08-16; 0037 and 0038 accepted 2026-08-20; 0039 accepted 2026-08-21; 0040 accepted 2026-08-22; 0041 accepted 2026-08-25; 0042 accepted 2026-08-27.
@@ -1,6 +1,6 @@
 # PyBLE App — Technical Design Document (TDD)
 
-Status: **DRAFT** · Owner: project maintainer · Last updated: 2026-08-22
+Status: **DRAFT** · Owner: project maintainer · Last updated: 2026-08-27
 
 ## 0. Naming note (acronym clash)
 
@@ -345,20 +345,23 @@ The full design later stores the exact bytes locally as the source of truth and
 records provenance; those durable parts remain deferred to A-24/full A-33.
 
 **Public API (implemented connected subset):** an injected `GithubApi` with
+`listBranches(locator) → GithubBranchCatalog`,
 `resolve(locator) → PinnedRepository`, `listDirectory(repository, treeSha,
 path)`, and `fetchFile(repository, entry)`. `githubApiProvider` is the sole
 production composition point: it owns and closes the `http.Client` and exposes
 only `GithubApi`. `GithubRepositoryClient` implements that board-independent
-REST seam. The adaptive view owns ephemeral repository/ref input, lazy
+REST seam. The adaptive view owns the editable official repository initial
+value, branch/manual-ref mode, ephemeral ref input, lazy
 navigation, selection, retry, focus, and visible-step state; it delegates
 board review/commit/cancellation to `GithubBoardImporter`. That service owns
 safe target derivation, complete-listing conflict snapshots, bounded all-fetch
 validation, the session-bound sequential PUT loop, progress/result accounting,
 and Files refresh. It knows no widget, BLE transport, editor, or persistence
 type.
 
-**Key state:** presentation scope holds the canonical repo locator,
-requested/default ref, full pinned commit SHA, current remote-directory stack,
+**Key state:** presentation scope holds the canonical repo locator, complete
+branch catalog, chosen ref mode/value, full pinned commit SHA, current
+remote-directory stack,
 lazy entries, folder-local selection, retry/focus data, and visible
 browse/review/result state. One `GithubBoardImporter` instance is constructed
 per opened action with the captured board `cwd`, stable `Connection` facade,
@@ -692,6 +695,11 @@ data store. The boundary values are:
 
 ```dart
 record RepositoryLocator(Uri canonicalRoot, String owner, String repo);
+record GithubBranchCatalog(
+  RepositoryLocator locator,
+  String defaultBranch,
+  List<String> branchNames,
+);
 record PinnedRepository(
   RepositoryLocator locator,
   String requestedRef,
@@ -735,6 +743,11 @@ The fetched `_ImportCandidate` is deliberately a private service value rather
 than public/provider state: it exists only inside one bounded `commit()` call
 and is released at terminal return.
 
+`GithubBranchCatalog.branchNames` is immutable and contains exact, validated
+technical ref values. Discovery may observe moving branch tips, but exposes no
+branch-list commit identity because `resolve(locator, ref:)` remains the sole
+operation that publishes an immutable browse pin.
+
 `GithubEntryKind.regularFile` is granted only to a Git tree entry with
 `type = blob` and mode `100644` or `100755`; a directory is `type = tree` and
 mode `040000`. Symlink mode `120000`, submodule `type = commit` / mode `160000`,
@@ -754,6 +767,15 @@ targets the new `cwd`.
 
 ### 10.2 Canonical input and immutable snapshot resolution
 
+The presentation owns the local constant
+`https://github.com/PyBLE-dev/examples` and initializes each new import action's
+repository controller from it. The value is editable and is not fetched from,
+or coupled to, the sibling examples checkout. App launch and ordinary Files
+navigation never request it. Opening the user-invoked importer may call
+`listBranches`; editing the URL clears and cancels the catalog without issuing
+a request per keystroke, and an explicit load/refresh retrieves branches for
+the new canonical value.
+
 `RepositoryLocator.parse` accepts only HTTPS, exact host `github.com`, default
 port, no user-info/query/fragment, and exactly two non-empty decoded path
 segments. One trailing slash is removed. `.git`, `tree`/`blob` subpaths,
@@ -793,25 +815,49 @@ rejected above 512 direct entries before the directory model reaches the eager
 tablet view. These are hard resource ceilings, not pagination: the subset never
 silently presents a partial folder.
 
+Before normal-mode resolution, `listBranches(locator)` reads repository
+metadata for `default_branch`, then serially reads the public branches endpoint
+with `per_page=100` and increasing `page`. It publishes only a complete
+`GithubBranchCatalog`: at most 512 exact names over six pages, 512 KiB per
+branch page, and 2 MiB across branch-page bodies. Invalid/duplicate names,
+malformed metadata or pagination, a 513th name, or a further page fails without
+publishing accumulated names. `Link` metadata is accepted only when its next
+URL is HTTPS on exact host `api.github.com`, has the exact repository branches
+path and expected page parameters, and advances by one; the returned URL is
+never followed directly. The adapter constructs the next request from its
+validated locator and page number. The reported default is first and selected;
+remaining branches use `String.compareTo`. An empty catalog is displayed and
+cannot Browse in branch mode.
+
+The normal ref control is a searchable branch-only chooser. A localized
+advanced action exposes the retained manual branch/tag/commit field, including
+ADR-0040's blank-default behavior. Mode/value changes invalidate the pinned
+snapshot and all dependent state. In both modes the chosen value passes to
+`resolve`; catalog metadata never substitutes for full commit/root-tree
+resolution.
+
 ### 10.3 Lazy browse, selection, and adaptive state
 
 The user-visible lifecycle remains:
 
 ```text
-enterRepository → resolving → browsing → selecting → reviewing
+enterRepository → loadingBranches → choosingRef → resolving → browsing
+  → selecting → reviewing
   → awaitingOverwrite → fetching → recheckingBoard → uploading
   → complete | partial | cancelled | failed
 ```
 
 The implementation does not introduce a second Riverpod workflow controller.
 The adaptive `StatefulWidget` owns presentation-only state: a
 `browse | review | result` surface step,
-`resolving | loadingDirectory | checkingBoardTargets` operation phase,
+`loadingBranches | resolving | loadingDirectory | checkingBoardTargets`
+operation phase,
 directory stack, selection, failure/retry/focus data, and the current
 progress/result. Resolve/list operations capture the view's increasing
-epoch and a `GithubCancellation`; cancel, ref refresh, directory change, or
-disposal advances that epoch, and a late completion cannot repopulate the
-view. `GithubBoardImporter` separately owns its fetch/commit generation,
+epoch and a `GithubCancellation`; repository edit, branch refresh, ref-mode
+change, cancel, directory change, or disposal advances that epoch, and a late
+completion cannot repopulate the view. `GithubBoardImporter` separately owns
+its fetch/commit generation,
 active cancellation token, and duplicate-commit lock, publishing typed
 fetch/recheck/upload progress and terminal results through callbacks/returns.
 Together these values render every lifecycle state above distinctly. At most