docs(okf): add agent knowledge bundle for FirebaseUI-Android

okf-bundle/ci-workflows/android.md

@@ -0,0 +1,46 @@
+---
+type: Reference
+title: Android CI workflow
+description: Shape and triage notes for .github/workflows/android.yml.
+tags: [ci, gradle, android]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# Android CI
+
+Workflow: [.github/workflows/android.yml](../../.github/workflows/android.yml)
+
+## Triggers
+
+- `pull_request`
+- `push`
+
+## Job shape
+
+| Step | Detail |
+|------|--------|
+| Runner | `ubuntu-latest`, 30m timeout |
+| Checkout | `actions/checkout` (pinned) |
+| Cache | `~/.gradle/caches`, `~/.gradle/wrapper` keyed on Gradle files |
+| JDK | Temurin **21** |
+| Build | `./scripts/build.sh` |
+| On failure | `./scripts/print_build_logs.sh` |
+
+<a id="what-buildsh-runs"></a>
+
+## What `build.sh` runs
+
+Canonical owner for the CI unit-path step list. Script: [scripts/build.sh](../../scripts/build.sh).
+
+1. Copy `library/google-services.json` → `app/` and `proguard-tests/`
+2. `./gradlew --max-workers=2 clean`
+3. `./gradlew --max-workers=2 assembleDebug`
+4. `./gradlew --max-workers=2 checkstyle`
+5. `./gradlew --max-workers=2 testDebugUnitTest -x :e2eTest:testDebugUnitTest`
+
+`proguard-tests:build` is currently commented out (re-enable before release). Green Android CI does **not** prove ProGuard/R8 packaging.
+
+## Agent notes
+
+- Match this path locally with `./scripts/build.sh` — [agent command policy](../testing/agent-command-policy.md).
+- Do not treat this job as e2e coverage; that is [e2e.md](e2e.md).

okf-bundle/ci-workflows/e2e.md

@@ -0,0 +1,35 @@
+---
+type: Reference
+title: E2E CI workflow
+description: Shape and triage notes for .github/workflows/e2e_test.yml.
+tags: [ci, e2e, emulator, auth]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# E2E CI
+
+Workflow: [.github/workflows/e2e_test.yml](../../.github/workflows/e2e_test.yml)
+
+## Triggers
+
+- `pull_request` only (not `push`)
+
+## Job shape
+
+| Step | Detail |
+|------|--------|
+| Runner | `ubuntu-latest`, 30m timeout |
+| Checkout | `actions/checkout` (pinned) |
+| Caches | Gradle caches/wrapper; `~/.cache/firebase/emulators` |
+| Node | **20** |
+| JDK | Temurin **21** |
+| Tools | `npm i -g firebase-tools` |
+| Emulator | `./scripts/start-firebase-emulator.sh` (`CI` set → background + readiness poll) |
+| Tests | `./gradlew e2eTest` |
+| On failure | `./scripts/print_build_logs.sh` |
+
+## Agent notes
+
+- Local procedure and suite semantics: [running e2e](../testing/running-e2e.md).
+- Auth emulator only — do not invent multi-emulator CI.
+- Unit CI excludes `:e2eTest`; this job is the canonical e2e gate for Auth UI changes.

okf-bundle/ci-workflows/index.md

@@ -0,0 +1,19 @@
+# CI workflows
+
+GitHub Actions job shape and failure triage for FirebaseUI-Android.
+
+## Jobs
+
+* [Android CI](android.md) — `android.yml`: JDK 21, Gradle cache, `./scripts/build.sh`
+* [E2E Tests](e2e.md) — `e2e_test.yml`: firebase-tools, Auth emulator, `./gradlew e2eTest`
+
+## Shared dependencies
+
+* [Agent command policy](../testing/agent-command-policy.md) — allowlisted commands for agents
+* [Running e2e — e2e agent rule](../testing/running-e2e.md#e2e-agent-rule) — emulator + `e2eTest` only
+* [Validation checklist](../testing/validation-checklist.md) — local handoff sequence matching CI
+
+## Related
+
+* [Running e2e tests](../testing/running-e2e.md) — local runbook
+* [Repo tooling](../repo-tooling/index.md) — Gradle modules, versioning

okf-bundle/documentation-policy.md

@@ -0,0 +1,74 @@
+---
+type: Reference
+title: OKF documentation and commit policy
+description: Canonical rules for durable vs ephemeral knowledge, commit messages, and post-update bundle consistency.
+tags: [okf, documentation, policy, commits, work-queue]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# OKF documentation and commit policy
+
+Single source of truth for OKF knowledge and commit wording. Other OKF docs/work queues link here; do not restate.
+
+## Durable vs ephemeral
+
+| Kind | Where it lives | What it contains |
+|------|----------------|------------------|
+| **Durable** | OKF reference docs (design, runbooks, registries, workflows) | Stable API names, module layout, SDK/tooling versions, verification **methods**, architecture, canonical commands |
+| **Ephemeral** | Explicit **work-queue** docs only | Session phase/probe IDs, **planned commit subjects** (`commit_subject`), gate state, `next_work_type`, snapshot labels, dated banners, run counts |
+
+**Rules**
+
+1. General OKF docs get **durable only** updates: no phase IDs, **commit subjects**, session e2e counts, or gate snapshots.
+2. Ephemeral state lives **only** in work queues. When an item closes, durable outcomes move to reference docs; queue rows may archive/delete.
+3. Durable docs may link to a work queue for current status; do not duplicate ephemeral fields.
+4. Create a work-queue doc only when active cross-cutting work needs gate tracking. Do not invent empty queues for completed migrations.
+
+## Commits as documentation
+
+We treat **git commits** as durable documentation: they are the canonical record of what changed, when, and why — for humans and agents reviewing history later, not only for the current PR thread.
+
+Commit messages use [Conventional Commits](https://www.conventionalcommits.org/) and describe durable product/process deliverables: what changed and why, not probe IDs, gates, e2e counts, or “phase X complete”.
+
+Scopes commonly used in this repo: `auth`, `firestore`, `database`, `storage`, `common`, `ci`, `deps`, `docs`. Prefer the Gradle module name when the change is module-scoped.
+
+Examples from [CONTRIBUTING.md](../CONTRIBUTING.md):
+
+```text
+fix(auth): fixed a bug with email sign-in!
+feat(auth): add support for passkey authentication
+```
+
+## Pull requests
+
+When a PR contains **exactly one commit**, the **PR title must match that commit's subject line exactly** (character-for-character). Multi-commit PRs use a summary title that describes the overall change set.
+
+PR process expectations live in [.github/PULL_REQUEST_TEMPLATE.md](../.github/PULL_REQUEST_TEMPLATE.md) and [CONTRIBUTING.md](../CONTRIBUTING.md). New features that affect Auth UX should consider [FirebaseUI-iOS](https://github.com/firebase/FirebaseUI-iOS) parity.
+
+## OKF update contract
+
+OKF markdown edits require an **independent bundle consistency pass**. Use a fresh context with:
+
+1. A short summary of what changed and which files were touched.
+2. Instruction to scan the **entire** `okf-bundle/` tree.
+
+Confirm:
+
+| Check | Requirement |
+|-------|-------------|
+| **Canonical location** | Each topic has one owning doc; others link to it ([agent command policy](testing/agent-command-policy.md) for **all** agent shell commands; [change authoring](testing/change-authoring-workflow.md) for workflow/gates/frozen tree; [change authoring § validation evidence (blocking)](testing/change-authoring-workflow.md#validation-evidence-blocking); [running e2e](testing/running-e2e.md) for emulator + `e2eTest` detail; [iteration vocabulary](testing/iteration-vocabulary.md) for term ids only; [validation checklist](testing/validation-checklist.md) for command sequence; this file for doc/commit policy) |
+| **DRY** | No duplicated procedures, policy paragraphs, or ephemeral snapshots outside work queues |
+| **Link hygiene** | Cross-links resolve; indexes list canonical entry points |
+| **Durability** | No ephemeral fields leaked into general reference docs |
+
+Fix violations before handoff/merge. Work-queue edits still follow this split.
+
+## Work-queue documents
+
+Work queues are **intentionally ephemeral**: phases, **commit subjects**, gates, active coordination. They are not policy or finalized registry/design homes.
+
+Work queues record **gates**, **`next_work_type`**, **`validation_tier`**, and **`commit_subject`** using field names and allowed values from [iteration vocabulary](testing/iteration-vocabulary.md). Gate semantics and workflow rules: [change authoring workflow](testing/change-authoring-workflow.md). They do **not** name agent roles, dispatch instructions, or session choreography — those are out of scope for the public repo.
+
+Record **`commit_subject`** (the planned Conventional Commit subject line) **before** `git commit`, in the same staged changeset as the item being memorialized. Do not record SHAs — they are unstable under history rewrite. After commit, the subject in git and in the queue must match character-for-character ([PR title rule](#pull-requests) for single-commit PRs).
+
+New work queues link here in frontmatter/opening section; do not copy policy inline.

okf-bundle/index.md

@@ -0,0 +1,29 @@
+---
+okf_version: '0.1'
+---
+
+# FirebaseUI-Android knowledge bundle
+
+Agent-oriented knowledge for [firebase/FirebaseUI-Android](https://github.com/firebase/FirebaseUI-Android). Human-facing docs stay in `README.md`, `CONTRIBUTING.md`, module READMEs, and `docs/`.
+
+- [Documentation/commit policy](/documentation-policy.md) — durable vs ephemeral, commits as documentation, PR titles, OKF consistency
+
+# CI workflows
+
+- [CI workflows](/ci-workflows/index.md) — GitHub Actions job shape (`android.yml`, `e2e_test.yml`), failure log triage
+
+# Testing
+
+- [Agent command policy](/testing/agent-command-policy.md) — allowlisted shell commands for agents (Gradle, scripts, emulator, validation)
+- [Change authoring workflow](/testing/change-authoring-workflow.md) — verified product change loop (unit-focused → area-focused review → commit); [§ validation evidence (blocking)](/testing/change-authoring-workflow.md#validation-evidence-blocking)
+- [Iteration vocabulary](/testing/iteration-vocabulary.md) — work type, tier, and queue field identifiers
+- [Running e2e tests](/testing/running-e2e.md) — Auth emulator + `./gradlew e2eTest`
+- [Validation checklist](/testing/validation-checklist.md) — assemble, checkstyle, unit tests, e2e
+
+# Modules
+
+- [Modules](/modules/index.md) — auth, firestore, database, storage, common, and supporting Gradle modules
+
+# Repo tooling
+
+- [Repo tooling](/repo-tooling/index.md) — Gradle layout, versioning (`Config.kt`), release/branch pointers

okf-bundle/modules/auth.md

@@ -0,0 +1,55 @@
+---
+type: Reference
+title: Auth module notes
+description: Durable agent notes for firebase-ui-auth (Compose, configuration DSL, MFA, Credential Manager, tests).
+tags: [auth, compose, modules]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# `:auth` — firebase-ui-auth
+
+Primary Auth UI library. **v10+** is Kotlin + Jetpack Compose + Material 3 (breaking vs 9.x Views).
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `com.firebase.ui.auth` | Core entrypoints (`FirebaseAuthUI`, flow/state types) |
+| `…/configuration` | `authUIConfiguration {}` DSL, `AuthProvider.*`, theme, validators, string provider |
+| `…/ui/screens` | Compose screens (`FirebaseAuthScreen`, email/phone/MFA, etc.) |
+| `…/ui/components` | Shared Compose widgets |
+| `…/ui/method_picker` | Provider picker |
+| `…/credentialmanager` | Android Credential Manager / password credentials |
+| `…/mfa` | MFA enrollment/challenge support |
+| `…/data`, `…/util` | Supporting types/helpers |
+
+Unit tests: `auth/src/test/…`. E2e: `e2eTest/src/test/…` — [running e2e](../testing/running-e2e.md).
+
+## Public integration surfaces
+
+Agents changing Auth should know both consumer APIs (do not break without migration notes):
+
+1. **High-level** — `FirebaseAuthScreen` + `authUIConfiguration { }` (Compose-first).
+2. **Low-level** — `AuthFlowController` for Activity-hosted flows.
+
+Consumer setup skill (outside this repo’s product code): `.agents/skills/firebaseui-android-getting-started/SKILL.md`.
+
+Human docs: [auth/README.md](../../auth/README.md), [docs/upgrade-to-10.0.md](../../docs/upgrade-to-10.0.md).
+
+## Validation
+
+Tier commands and handoff sequence: [validation checklist](../testing/validation-checklist.md). Auth UI / emulator path requires e2e — [running e2e § when required](../testing/running-e2e.md#when-e2e-is-required). Allowlist: [agent command policy](../testing/agent-command-policy.md).
+
+## Architectural facts (durable)
+
+- Configuration is Kotlin DSL (`AuthProvider.Email()`, etc.), not 9.x `IdpConfig` builders.
+- Theming uses `AuthUITheme` / Material 3, not XML Auth themes as the primary path.
+- State is reactive (`Flow`-oriented Auth state), not only `AuthStateListener` callbacks.
+- Credential Manager integration lives under `credentialmanager/` — treat password-save/retrieve as Auth-critical surface.
+- MFA (SMS/TOTP) has dedicated screens and e2e coverage (`MfaEnrollmentScreenTest`, `MfaChallengeScreenTest`, …).
+
+## Related
+
+* [Modules index](index.md)
+* [E2e CI](../ci-workflows/e2e.md)
+* [Change authoring](../testing/change-authoring-workflow.md)

okf-bundle/modules/common.md

@@ -0,0 +1,26 @@
+---
+type: Reference
+title: Common module notes
+description: Durable agent notes for shared firebase-ui-common adapter primitives.
+tags: [common, modules]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# `:common` — firebase-ui-common
+
+Published shared Java primitives used by Firestore and Realtime Database UI adapters (`POM_ARTIFACT_ID=firebase-ui-common`). Not a primary consumer README surface like auth/firestore/database/storage — treat it as a shared library dependency those modules consume.
+
+## Key types
+
+| Type | Role |
+|------|------|
+| `BaseObservableSnapshotArray` | Base observable snapshot list |
+| `BaseCachingSnapshotParser` / `BaseSnapshotParser` | Parser bases |
+| `BaseChangeEventListener` / `ChangeEventType` | Change-event plumbing |
+| `Preconditions` | Shared precondition helpers |
+
+## Validation
+
+No `src/test` / `androidTest` today — empty-suite trap: [agent command policy](../testing/agent-command-policy.md#empty-unit-suite-trap). Commands and tiers: [validation checklist](../testing/validation-checklist.md) (module matrix).
+
+**Module-specific:** changes here can break `:firestore` and `:database`. Prefer also running `./gradlew :firestore:testDebugUnitTest` (real JVM suite) when the shared API is consumed there. Database has no JVM unit suite — [database.md](database.md).

okf-bundle/modules/database.md

@@ -0,0 +1,35 @@
+---
+type: Reference
+title: Database module notes
+description: Durable agent notes for firebase-ui-database adapters and paging.
+tags: [database, modules]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# `:database` — firebase-ui-database
+
+Java library binding Realtime Database references to RecyclerView / ListView (and AndroidX Paging).
+
+## Key types
+
+| Type | Role |
+|------|------|
+| `FirebaseRecyclerAdapter` | RecyclerView adapter |
+| `FirebaseListAdapter` | ListView adapter |
+| `FirebaseRecyclerOptions` / `FirebaseListOptions` | Options builders |
+| `FirebaseArray` / `FirebaseIndexArray` | Observable arrays (including indexed keys/values) |
+| `SnapshotParser` family | Snapshot → model mapping |
+| `paging/*` | Paging adapters/sources |
+
+Human docs: [database/README.md](../../database/README.md).
+
+## Tests / validation
+
+- No JVM `src/test`. Instrumented tests live under `database/src/androidTest` (human/device only — not CI / not allowlisted).
+- Empty-suite trap: [agent command policy](../testing/agent-command-policy.md#empty-unit-suite-trap).
+- Commands and tiers: [validation checklist](../testing/validation-checklist.md) (module matrix).
+
+## Related
+
+* Shared primitives: [common.md](common.md)
+* Firestore counterpart: [firestore.md](firestore.md)

okf-bundle/modules/firestore.md

@@ -0,0 +1,35 @@
+---
+type: Reference
+title: Firestore module notes
+description: Durable agent notes for firebase-ui-firestore adapters and paging.
+tags: [firestore, modules]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# `:firestore` — firebase-ui-firestore
+
+Java library binding Cloud Firestore queries to RecyclerView (and AndroidX Paging).
+
+## Key types
+
+| Type | Role |
+|------|------|
+| `FirestoreRecyclerAdapter` | Lifecycle-aware RecyclerView adapter |
+| `FirestoreRecyclerOptions` | Query/options builder for the adapter |
+| `FirestoreArray` / `ObservableSnapshotArray` | Observable snapshot list |
+| `SnapshotParser` / `ClassSnapshotParser` / `CachingSnapshotParser` | Document → model mapping |
+| `paging/*` (`FirestorePagingAdapter`, `FirestorePagingSource`, …) | AndroidX Paging integration |
+
+Human docs: [firestore/README.md](../../firestore/README.md).
+
+## Tests / validation
+
+- JVM unit suite: `firestore/src/test`
+- Instrumented: `firestore/src/androidTest` — human/device only (not CI / not allowlisted)
+- Tier commands and evidence: [validation checklist](../testing/validation-checklist.md)
+- Auth emulator e2e is **not** required for Firestore-only changes — [running e2e § when required](../testing/running-e2e.md#when-e2e-is-required)
+
+## Related
+
+* Shared adapter primitives: [common.md](common.md)
+* Parallel Realtime Database adapters: [database.md](database.md)

okf-bundle/modules/index.md

@@ -0,0 +1,30 @@
+# Modules
+
+Published library modules and supporting Gradle projects. Human-facing usage docs: module `README.md` files and [docs/](../../docs/).
+
+## Published libraries
+
+| Module | Artifact | Language / UI | OKF notes |
+|--------|----------|---------------|-----------|
+| `:auth` | `firebase-ui-auth` | Kotlin, Jetpack Compose (v10+) | [auth.md](auth.md) |
+| `:firestore` | `firebase-ui-firestore` | Java, RecyclerView / Paging | [firestore.md](firestore.md) |
+| `:database` | `firebase-ui-database` | Java, RecyclerView / ListView / Paging | [database.md](database.md) |
+| `:storage` | `firebase-ui-storage` | Java, Glide | [storage.md](storage.md) |
+| `:common` | `firebase-ui-common` | Java (shared adapter primitives) | [common.md](common.md) |
+
+Version and SDK floors: `buildSrc/.../Config.kt` — [repo tooling](../repo-tooling/index.md).
+
+## Supporting modules
+
+| Module | Role |
+|--------|------|
+| `:library` | Umbrella / publish aggregation (`prepareArtifacts`) |
+| `:app` | Demo app (Auth Compose sample) |
+| `:e2eTest` | Auth emulator e2e (Robolectric + Compose UI test) |
+| `:proguard-tests` | R8/ProGuard packaging checks (disabled in CI unit path — [Android CI](../ci-workflows/android.md)) |
+| `:lint`, `:internal:lint`, `:internal:lintchecks` | Custom lint plumbing |
+| `buildSrc` | Shared `Config` (version, SDK levels, submodule list) |
+
+## Cross-cutting note (v10 Auth)
+
+FirebaseUI Auth **10.x** is a Compose rewrite (breaking vs 9.x Views). User migration: [docs/upgrade-to-10.0.md](../../docs/upgrade-to-10.0.md). Firestore/database/storage remain View-based; there is no active Compose migration work-queue for those modules unless one is opened later ([documentation policy § work queues](../documentation-policy.md#work-queue-documents)).