firebase · russellwheatley · Aug 4, 2026 · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
diff --git a/okf-bundle/ci-workflows/index.md b/okf-bundle/ci-workflows/index.md
@@ -0,0 +1,28 @@
+# CI workflows
+
+GitHub Actions job map for FirebaseUI-iOS. Local command ownership stays in [agent command policy](../testing/agent-command-policy.md) and [running tests](../testing/running-tests.md).
+
+## Workflows
+
+| Workflow | Path | Purpose |
+|----------|------|---------|
+| SwiftUI Auth | [`swiftui-auth.yml`](../../.github/workflows/swiftui-auth.yml) | SwiftFormat check, SPM package unit tests, integration + UI tests with Auth emulator |
+| Database | [`database.yml`](../../.github/workflows/database.yml) | CocoaPods `xcodebuild` test, SPM scheme build, `pod lib lint` |
+| Firestore | [`firestore.yml`](../../.github/workflows/firestore.yml) | Same shape as Database for Firestore UI |
+| Storage | [`storage.yml`](../../.github/workflows/storage.yml) | Same shape as Database for Storage UI |
+| Samples | [`sample.yml`](../../.github/workflows/sample.yml) | Build SwiftUI + UIKit sample apps |
+| Issue labels / stale | [`issue-labels.yml`](../../.github/workflows/issue-labels.yml), [`stale-issue.yml`](../../.github/workflows/stale-issue.yml) | Repo hygiene (not product validation) |
+
+## Detail docs
+
+* [SwiftUI Auth CI](swiftui-auth.md) — jobs, Xcode pin, emulator, artifacts
+* [UIKit modules CI](uikit-modules.md) — Database / Firestore / Storage job matrix
+* [Samples CI](samples.md) — sample build destinations
+
+## Shared pins (as of authoring)
+
+* **Xcode 26.2** selected in module/sample/SwiftUI workflows
+* **Simulator:** `iPhone 17 Pro` for most test jobs; SwiftUI sample build uses `iPhone 17`
+* **Simulator prep script:** [`.github/workflows/scripts/prepare-ios-simulator.sh`](../../.github/workflows/scripts/prepare-ios-simulator.sh)
+
+When pins drift, update these OKF docs in the same change that updates CI — do not leave agents on stale device/Xcode names.
diff --git a/okf-bundle/ci-workflows/samples.md b/okf-bundle/ci-workflows/samples.md
@@ -0,0 +1,23 @@
+---
+type: Reference
+title: Samples CI
+description: Job shape for .github/workflows/sample.yml.
+tags: [ci, samples]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# Samples CI
+
+Workflow: [`.github/workflows/sample.yml`](../../.github/workflows/sample.yml).
+
+## Jobs
+
+| Job | Area | Notes |
+|-----|------|-------|
+| `swiftui` | `samples/swiftui/FirebaseSwiftUISample` | `xcodebuild` **build**; destination `iPhone 17` |
+| `swift` | `samples/swift` (`FirebaseUI-demo-swift`) | CocoaPods install then `xcodebuild` **`clean build test`**; destination `iPhone 17 Pro` |
+| `objc` | `samples/objc` (`FirebaseUI-demo-objc`) | CocoaPods install then `xcodebuild` **`clean build`**; destination `iPhone 17 Pro` |
+
+Copy **exact** `xcodebuild` / `pod` steps from the workflow when validating sample changes locally — [running tests § samples](../testing/running-tests.md#sample-builds).
+
+Samples are CI smoke checks for the demo apps (the Swift UIKit sample also runs its test target). They are not a substitute for `./swiftui-tests.sh` or `./test.sh`.
diff --git a/okf-bundle/ci-workflows/swiftui-auth.md b/okf-bundle/ci-workflows/swiftui-auth.md
@@ -0,0 +1,43 @@
+---
+type: Reference
+title: SwiftUI Auth CI
+description: Job shape and triage notes for .github/workflows/swiftui-auth.yml.
+tags: [ci, swiftui, auth, emulator]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# SwiftUI Auth CI
+
+Workflow: [`.github/workflows/swiftui-auth.yml`](../../.github/workflows/swiftui-auth.yml).
+
+Local mirror: [`./swiftui-tests.sh`](../../swiftui-tests.sh) — [running tests](../testing/running-tests.md#swiftui-auth-tests). Emulator defaults: [firebase testing project](../testing/firebase-testing-project.md).
+
+## Jobs
+
+| Job | What | Notes |
+|-----|------|-------|
+| `format-check` | `brew install swiftformat` + `./lint-swift.sh` | Paths in `lint-swift.sh` |
+| `unit-tests` | `xcodebuild test -scheme FirebaseUI-Package` on prepared simulator | Coverage on; uploads log/xcresult on failure |
+| `integration-tests` | Auth emulator + `FirebaseSwiftUIExampleTests` | Node 20, Java 17, `firebase-tools`; `parallel-testing-enabled NO` |
+| `ui-tests` | Auth emulator + `build-for-testing` / `test-without-building` for `FirebaseSwiftUIExampleUITests` | Same emulator setup; uploads emulator debug log on failure |
+
+## Environment
+
+| Variable / pin | Value |
+|----------------|-------|
+| `XCODE_VERSION` | `26.2` |
+| `IOS_SIMULATOR_DEVICE` | `iPhone 17 Pro` |
+| Runner | `macos-26` |
+| Emulator project (script default) | `flutterfire-e2e-tests` |
+| Emulator port probe | `http://localhost:9099` |
+
+## Path filters
+
+PRs/pushes run when `FirebaseSwiftUI/**`, `samples/swiftui/**`, `e2eTest/**`, `Package.swift`, `Package.resolved`, Gemfile, or this workflow change.
+
+## Triage
+
+1. Prefer downloading failure artifacts (logs / `.xcresult` / `firebase-debug.log`) over re-running blind.
+2. Format failures → `./format-swift.sh` then `./lint-swift.sh`.
+3. Emulator failures → confirm Firebase CLI, port `9099`, and project id; locally use `./swiftui-tests.sh --integration`.
+4. Simulator resolution failures → inspect `prepare-ios-simulator.sh` output and `xcrun simctl list devices available`.
diff --git a/okf-bundle/ci-workflows/uikit-modules.md b/okf-bundle/ci-workflows/uikit-modules.md
@@ -0,0 +1,41 @@
+---
+type: Reference
+title: UIKit modules CI
+description: Job shape for Database, Firestore, and Storage UI GitHub Actions workflows.
+tags: [ci, database, firestore, storage, cocoapods, spm]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# UIKit modules CI
+
+Workflows (same job shape):
+
+* [`.github/workflows/database.yml`](../../.github/workflows/database.yml)
+* [`.github/workflows/firestore.yml`](../../.github/workflows/firestore.yml)
+* [`.github/workflows/storage.yml`](../../.github/workflows/storage.yml)
+
+Local mirror for the CocoaPods test job: [`./test.sh <Module>`](../../test.sh) after `bundle exec pod install` in the module directory — [running tests](../testing/running-tests.md#uikit-module-tests).
+
+## Jobs (per module)
+
+| Job | What |
+|-----|------|
+| `xcodebuild` | In module dir: Bundler + `pod install --repo-update`, then repo-root `./test.sh <Module>` |
+| `spm` | Repo-root `xcodebuild -scheme <Module> -sdk iphonesimulator` with CI destination |
+| `pod` | `bundle exec pod lib lint <Module>.podspec` |
+
+## Environment
+
+| Pin | Value |
+|-----|-------|
+| Runner | `macos-15` |
+| Xcode | `/Applications/Xcode_26.2.app` via `xcode-select` |
+| Destination (spm / test.sh) | `iPhone 17 Pro` (see scripts/workflows for exact string) |
+
+## Path filters
+
+Each workflow watches its `Firebase<Module>UI/**`, podspec, `test.sh`, `Package.swift` / `Package.resolved`, Gemfile, and its workflow file.
+
+## Dual-path reminder
+
+A green `xcodebuild` CocoaPods job does **not** prove the SPM product compiles (and vice versa). Agents must satisfy the [distribution path gate](../testing/running-tests.md#distribution-path-gate-blocking) when shared sources change.
diff --git a/okf-bundle/documentation-policy.md b/okf-bundle/documentation-policy.md
@@ -0,0 +1,66 @@
+---
+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 boundaries, 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 test 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.
+
+## 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, test counts, or "phase X complete".
+
+Common scopes in this repo (non-exhaustive): `auth`, `database`, `firestore`, `storage`, `swiftui`, `ci`, `sample`, `docs`, `okf`.
+
+## 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.
+
+Also follow [`PULL_REQUEST_TEMPLATE.md`](../PULL_REQUEST_TEMPLATE.md) and [`CONTRIBUTING.md`](../CONTRIBUTING.md) (CLA, feature parity with FirebaseUI-Android where the change is user-facing).
+
+## 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 tests](testing/running-tests.md) for test command detail; [iteration vocabulary](testing/iteration-vocabulary.md) for term ids only; [change authoring § quality standards](testing/change-authoring-workflow.md#quality-standards) for review-findings resolution; [coverage design](testing/coverage-design.md) for coverage expectations; [SPM and CocoaPods workflow](packaging/spm-and-cocoapods-workflow.md) for distribution; [firebase testing project](testing/firebase-testing-project.md) for Auth emulator defaults; 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.
diff --git a/okf-bundle/index.md b/okf-bundle/index.md
@@ -0,0 +1,32 @@
+---
+okf_version: '0.1'
+---
+
+# FirebaseUI-iOS knowledge bundle
+
+Agent-oriented knowledge for this repository. Prefer these docs over improvised shell diagnostics or copying patterns from other FirebaseUI / React Native Firebase repos without re-deriving commands from this tree.
+
+- [Documentation/commit policy](documentation-policy.md) — durable vs ephemeral, commits as documentation, PR titles, OKF consistency
+
+# Testing
+
+- [Agent command policy](testing/agent-command-policy.md) — allowlisted shell commands (install, lint, unit, integration, UI, CocoaPods)
+- [Change authoring workflow](testing/change-authoring-workflow.md) — verified 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 tests](testing/running-tests.md) — canonical SwiftUI and UIKit test commands, narrowing, emulator
+- [Validation checklist](testing/validation-checklist.md) — lint, SPM package tests, CocoaPods module tests, samples, pod lint
+- [Coverage design](testing/coverage-design.md) — where coverage is produced and how to treat it
+- [Firebase testing project](testing/firebase-testing-project.md) — Auth emulator project id, ports, local vs CI
+
+# CI workflows
+
+- [CI workflows](ci-workflows/index.md) — GitHub Actions job map, Xcode/simulator pins, artifact triage
+
+# Packaging
+
+- [SPM and CocoaPods workflow](packaging/spm-and-cocoapods-workflow.md) — dual distribution rules, product matrix, release scripts
+- [SPM / CocoaPods work queue](packaging/spm-cocoapods-work-queue.md) — ephemeral dual-distribution tracker
+
+# Packages
+
+- [Packages index](packages/index.md) — Auth SwiftUI, Database UI, Firestore UI, Storage UI
diff --git a/okf-bundle/packages/auth-swiftui/index.md b/okf-bundle/packages/auth-swiftui/index.md
@@ -0,0 +1,46 @@
+---
+type: Reference
+title: FirebaseAuthSwiftUI package notes
+description: Agent reference for SwiftUI Auth core and provider packages.
+tags: [auth, swiftui, spm]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# Auth SwiftUI
+
+SPM products: `FirebaseAuthSwiftUI`, `FirebaseAuthUIComponents`, `FirebaseGoogleSwiftUI`, `FirebaseFacebookSwiftUI`, `FirebasePhoneAuthSwiftUI`, `FirebaseAppleSwiftUI`, `FirebaseTwitterSwiftUI`, `FirebaseOAuthSwiftUI`.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `FirebaseSwiftUI/FirebaseAuthSwiftUI/` | Core Auth UI (`AuthService`, flows, strings); package unit tests under `Tests/` |
+| `FirebaseSwiftUI/FirebaseAuthUIComponents/` | Shared UI components/resources |
+| `FirebaseSwiftUI/Firebase*SwiftUI/` | Provider packages + their `Tests/` |
+| `e2eTest/FirebaseSwiftUIExample/` | Integration + UI test host app |
+| `samples/swiftui/FirebaseSwiftUISample/` | Manual/sample app |
+| `GETTING_STARTED.md` / `FirebaseSwiftUI/README.md` | User-facing docs |
+
+## Validation
+
+| Intent | Command |
+|--------|---------|
+| Lint | `./lint-swift.sh` |
+| Package unit | `./swiftui-tests.sh --unit` |
+| Integration / UI | `./swiftui-tests.sh --integration` / `--ui` |
+| Area / pre-merge | `./swiftui-tests.sh --lint --all` |
+
+Allowlist: [agent command policy](../../testing/agent-command-policy.md). Detail: [running tests](../../testing/running-tests.md#swiftui-auth-tests). Emulator project: [firebase testing project](../../testing/firebase-testing-project.md). CI: [swiftui-auth CI](../../ci-workflows/swiftui-auth.md).
+
+## Agent notes
+
+* Swift 6 language mode is set on these targets in `Package.swift` — treat concurrency/isolation errors as product issues.
+* Provider packages depend on `FirebaseAuthSwiftUI` + `FirebaseAuthUIComponents`; keep public Auth configuration APIs stable unless versioning intentionally.
+* Version stamp for Swift releases: `FirebaseSwiftUI/FirebaseAuthSwiftUI/Sources/Version.swift` via [`release-swift.sh`](../../../release-swift.sh) (human release process).
+* Feature parity with FirebaseUI-Android Auth UI where applicable ([`CONTRIBUTING.md`](../../../CONTRIBUTING.md)).
+* Emulator-backed tests use project `flutterfire-e2e-tests` by default.
+
+## Related
+
+* [SPM and CocoaPods workflow](../../packaging/spm-and-cocoapods-workflow.md) — Auth is SPM-only for consumers
+* [`.agents/skills/firebaseui-ios-getting-started/SKILL.md`](../../../.agents/skills/firebaseui-ios-getting-started/SKILL.md) — getting-started skill (user docs adjacent)
diff --git a/okf-bundle/packages/database-ui/index.md b/okf-bundle/packages/database-ui/index.md
@@ -0,0 +1,41 @@
+---
+type: Reference
+title: FirebaseDatabaseUI package notes
+description: Agent reference for Realtime Database UIKit bindings.
+tags: [database, uikit, cocoapods, spm]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# Database UI
+
+CocoaPods: `FirebaseDatabaseUI` / `FirebaseUI/Database`. SPM product: `FirebaseDatabaseUI`.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `FirebaseDatabaseUI/Sources/` | ObjC implementation + public headers |
+| `FirebaseDatabaseUI/FirebaseDatabaseUITests/` | XCTest (array/data source behavior) |
+| `FirebaseDatabaseUI/Podfile` | Local workspace deps (`Firebase/Database`) |
+| `FirebaseDatabaseUI.podspec` | CocoaPods publish metadata |
+| `FirebaseDatabaseUI/README.md` | User-facing API overview |
+
+Key types: `FUIArray`, `FUISortedArray`, `FUIIndexArray`, `FUITableViewDataSource`, `FUICollectionViewDataSource`, index variants — see module README.
+
+## Validation
+
+```bash
+cd FirebaseDatabaseUI && bundle exec pod install && cd ..
+./test.sh FirebaseDatabaseUI
+xcodebuild -scheme FirebaseDatabaseUI -sdk iphonesimulator \
+  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro'
+bundle exec pod lib lint FirebaseDatabaseUI.podspec   # when podspec/packaging changes
+```
+
+CI: [uikit-modules CI](../../ci-workflows/uikit-modules.md). Distribution: [SPM and CocoaPods workflow](../../packaging/spm-and-cocoapods-workflow.md).
+
+## Agent notes
+
+* Array/data-source updates are concurrency-sensitive (batch updates vs Firebase child events). Prefer regression tests in `FirebaseDatabaseUITests` when touching `FUIArray` / collection data sources.
+* Keep SPM header search paths / `publicHeadersPath` intact when moving headers (`Package.swift` target settings).
+* Do not "fix" desyncs by skipping UI updates without tests — recent history includes desync crash fixes that require lockstep item/UI updates.
diff --git a/okf-bundle/packages/firestore-ui/index.md b/okf-bundle/packages/firestore-ui/index.md
@@ -0,0 +1,38 @@
+---
+type: Reference
+title: FirebaseFirestoreUI package notes
+description: Agent reference for Firestore UIKit bindings.
+tags: [firestore, uikit, cocoapods, spm]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+# Firestore UI
+
+CocoaPods: `FirebaseFirestoreUI` / `FirebaseUI/Firestore`. SPM product: `FirebaseFirestoreUI`.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `FirebaseFirestoreUI/Sources/` | ObjC implementation + public headers |
+| `FirebaseFirestoreUI/FirebaseFirestoreUITests/` | XCTest |
+| `FirebaseFirestoreUI/Podfile` | Local workspace deps |
+| `FirebaseFirestoreUI.podspec` | CocoaPods publish metadata |
+| `FirebaseFirestoreUI/README.md` | User-facing API overview |
+
+## Validation
+
+```bash
+cd FirebaseFirestoreUI && bundle exec pod install && cd ..
+./test.sh FirebaseFirestoreUI
+xcodebuild -scheme FirebaseFirestoreUI -sdk iphonesimulator \
+  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro'
+bundle exec pod lib lint FirebaseFirestoreUI.podspec   # when podspec/packaging changes
+```
+
+CI: [uikit-modules CI](../../ci-workflows/uikit-modules.md). Distribution: [SPM and CocoaPods workflow](../../packaging/spm-and-cocoapods-workflow.md).
+
+## Agent notes
+
+* Same dual-distribution rules as Database UI — CocoaPods test path + SPM scheme when shared sources change.
+* Preserve public header layout for both podspec `source_files` / header maps and SPM `publicHeadersPath`.
diff --git a/okf-bundle/packages/index.md b/okf-bundle/packages/index.md
@@ -0,0 +1,10 @@
+# Packages
+
+Durable, topic-owned notes for FirebaseUI-iOS libraries (RNFB-equivalent of `okf-bundle/packages/`). User-facing guides remain in module READMEs / `GETTING_STARTED.md`; OKF pages capture **agent** constraints, test entrypoints, and sharp edges.
+
+| Package | Doc | Tree |
+|---------|-----|------|
+| Auth SwiftUI (+ providers) | [auth-swiftui](auth-swiftui/index.md) | `FirebaseSwiftUI/**` |
+| Database UI | [database-ui](database-ui/index.md) | `FirebaseDatabaseUI/**` |
+| Firestore UI | [firestore-ui](firestore-ui/index.md) | `FirebaseFirestoreUI/**` |
+| Storage UI | [storage-ui](storage-ui/index.md) | `FirebaseStorageUI/**` |