From 2ead3fabe9b78b7c4df7a3697dae926d458d4b17 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 08:00:18 -0500
Subject: [PATCH 01/18] docs: Split large architecture document into multiple
 documents

Organize separate subjects.
---
 docs/architecture.md | 136 -------------------------------------------
 docs/development.md  |  94 ++++++++++++++++++++++++++++++
 docs/plugins.md      |  22 +++++++
 docs/testing.md      |  19 ++++++
 4 files changed, 135 insertions(+), 136 deletions(-)
 create mode 100644 docs/development.md
 create mode 100644 docs/plugins.md
 create mode 100644 docs/testing.md

diff --git a/docs/architecture.md b/docs/architecture.md
index bcc267e3..9ef10f5b 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -54,139 +54,3 @@ Native code executes JavaScript in the WebView to:
 -   Update editor settings
 -   Handle media selection
 -   Process API responses
-
-## Development Mode
-
-Development mode (`?dev_mode` query parameter) enables debugging features and bypasses certain production behaviors to simplify development and testing:
-
--   **Development notice is displayed** - A warning notice appears to inform developers that they're running in development mode.
--   **Mock GBKit global is provided** - If the native bridge (`window.GBKit`) is not available, a mock object is automatically provided to allow the editor to load without native integration.
--   **React Dev Tools integration** - The editor connects to the React Dev Tools standalone server for component inspection and debugging. See the React Dev Tools section below for setup instructions.
-
-Add the `?dev_mode` query parameter to the editor URL:
-
-```
-http://localhost:3000/?dev_mode
-```
-
-### React Dev Tools
-
-The [React Developer Tools](https://react.dev/learn/react-developer-tools) allow inspecting React components, view props and state, and debug the component tree during development. GutenbergKit supports the standalone DevTools server for both browser and native WebView debugging.
-
-1. Start the standalone DevTools server:
-
-    ```bash
-    make dev-tools
-    ```
-
-    This opens a standalone window that will display your React component tree.
-
-2. Start the development server:
-
-    ```bash
-    make dev-server
-    ```
-
-3. For Android emulators only, set up port forwarding:
-
-    ```bash
-    adb reverse tcp:8097 tcp:8097
-    ```
-
-4. Load the editor with development mode enabled:
-
-    Browser or iOS simulator:
-
-    ```
-    http://localhost:5173/?dev_mode
-    ```
-
-    Android emulator:
-
-    ```
-    http://10.0.2.2:5173/?dev_mode
-    ```
-
-    The editor will automatically connect to the DevTools server, and your component tree will appear in the standalone window.
-
-## Logging Configuration
-
-The logger utility (`src/utils/logger.js`) supports different log levels that can be controlled via:
-
--   The `logLevel` editor configuration option, for controlling the client console;
--   And Node.js environment variables (`LOG_LEVEL=<level>`), for project scripts.
-
-The default log level is `info`. The project's demo app defaults to `debug`. Available log levels are:
-
--   `error`: Logs only error messages
--   `warn`: Logs warnings and errors
--   `info`: Logs informational messages, warnings, and errors
--   `debug`: Logs detailed debugging information, informational messages, warnings, and errors
-
-## Plugin Support
-
-GutenbergKit bundles `@wordpress` modules locally for offline capability and fast load times. The editor can optionally load plugin-provided blocks and custom editor assets from a remote server when configured.
-
-### How Plugin Loading Works
-
-When the `plugins` configuration option is enabled:
-
-1. Core `@wordpress` packages are loaded from bundled code
-2. Plugin scripts and styles are fetched from the site's editor assets endpoint
-3. Custom blocks and editor extensions are registered dynamically
-4. The editor integrates both core and custom functionality
-
-This approach provides:
-
--   **Offline-first**: Core editor works without network connectivity
--   **Extensibility**: Supports custom blocks and plugins when connected
--   **Performance**: Core packages load instantly from local bundle
-
-### Configuration
-
-Enable plugins by setting the `plugins` configuration option. The editor will fetch assets from the configured `editorAssetsEndpoint` or fall back to the default Jetpack endpoint. The demo app UI allows adding site-specific editor configurations, which enables the `plugins` configuration option.
-
-## Testing
-
-### JavaScript Testing
-
--   Framework: Vitest
--   Test files: `*.test.{js,jsx}`
--   Run tests: `make test-js`
-
-### Native Testing
-
-**iOS:**
-
--   XCTest framework
--   Run: `make test-swift-package`
-
-**Android:**
-
--   JUnit framework
--   Run: `make test-android`
-
-## Frequently Asked Questions
-
-### Why do I encounter a `GBKit global not available after timeout` error when opening the GutenbergKit editor in a browser?
-
-This error occurs when the editor is unable to communicate with the native bridge. This is expected when opening the editor in a browser, as the native bridge is not available. GutenbergKit is designed to be used in a native host app that provides the native bridge. The GutenbergKit project includes a demo app that can be used to test the editor.
-
-It is possible to circumvent this this error by adding the `?dev_mode` query parameter to the editor URL in your browser. This will bypass the native bridge requirement and allow the editor to load without the native bridge. However, some features may not work as expected when using this mode.
-
-### Why do I encounter an `Importing a module script failed.` error?
-
-This [generally indicates](https://github.com/vitejs/vite/discussions/17738) that Vite is attempting to load a cached dependency that no longer exists or is corrupted.
-
-Often times this is paired with a following warning in the Vite development server console that looks like this:
-
-```
-The file does not exist at "[path]" which is in the optimize deps directory. The dependency might be incompatible with the dep optimizer. Try adding it to `optimizeDeps.exclude`.
-```
-
-Usually, clearing Vite's cache resolves this issue. This can be accomplished by either:
-
--   Stopping the development server and restarting it via the `make dev-server-force` command to force Vite to re-bundle dependencies.
--   Deleting the `node_modules/.vite` directory (or `node_modules` entirely) and restarting the development server via `make dev-server`.
-
-You may also need to clear your browser cache to ensure no stale files are used.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 00000000..c7ec64b7
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,94 @@
+# Development Guide
+
+## Development Mode
+
+Development mode (`?dev_mode` query parameter) enables debugging features and bypasses certain production behaviors to simplify development and testing:
+
+-   **Development notice is displayed** - A warning notice appears to inform developers that they're running in development mode.
+-   **Mock GBKit global is provided** - If the native bridge (`window.GBKit`) is not available, a mock object is automatically provided to allow the editor to load without native integration.
+-   **React Dev Tools integration** - The editor connects to the React Dev Tools standalone server for component inspection and debugging. See the React Dev Tools section below for setup instructions.
+
+Add the `?dev_mode` query parameter to the editor URL:
+
+```
+http://localhost:3000/?dev_mode
+```
+
+## React Dev Tools
+
+The [React Developer Tools](https://react.dev/learn/react-developer-tools) allow inspecting React components, view props and state, and debug the component tree during development. GutenbergKit supports the standalone DevTools server for both browser and native WebView debugging.
+
+1. Start the standalone DevTools server:
+
+    ```bash
+    make dev-tools
+    ```
+
+    This opens a standalone window that will display your React component tree.
+
+2. Start the development server:
+
+    ```bash
+    make dev-server
+    ```
+
+3. For Android emulators only, set up port forwarding:
+
+    ```bash
+    adb reverse tcp:8097 tcp:8097
+    ```
+
+4. Load the editor with development mode enabled:
+
+    Browser or iOS simulator:
+
+    ```
+    http://localhost:5173/?dev_mode
+    ```
+
+    Android emulator:
+
+    ```
+    http://10.0.2.2:5173/?dev_mode
+    ```
+
+    The editor will automatically connect to the DevTools server, and your component tree will appear in the standalone window.
+
+## Logging Configuration
+
+The logger utility (`src/utils/logger.js`) supports different log levels that can be controlled via:
+
+-   The `logLevel` editor configuration option, for controlling the client console;
+-   And Node.js environment variables (`LOG_LEVEL=<level>`), for project scripts.
+
+The default log level is `info`. The project's demo app defaults to `debug`. Available log levels are:
+
+-   `error`: Logs only error messages
+-   `warn`: Logs warnings and errors
+-   `info`: Logs informational messages, warnings, and errors
+-   `debug`: Logs detailed debugging information, informational messages, warnings, and errors
+
+## Troubleshooting
+
+### Why do I encounter a `GBKit global not available after timeout` error when opening the GutenbergKit editor in a browser?
+
+This error occurs when the editor is unable to communicate with the native bridge. This is expected when opening the editor in a browser, as the native bridge is not available. GutenbergKit is designed to be used in a native host app that provides the native bridge. The GutenbergKit project includes a demo app that can be used to test the editor.
+
+It is possible to circumvent this this error by adding the `?dev_mode` query parameter to the editor URL in your browser. This will bypass the native bridge requirement and allow the editor to load without the native bridge. However, some features may not work as expected when using this mode.
+
+### Why do I encounter an `Importing a module script failed.` error?
+
+This [generally indicates](https://github.com/vitejs/vite/discussions/17738) that Vite is attempting to load a cached dependency that no longer exists or is corrupted.
+
+Often times this is paired with a following warning in the Vite development server console that looks like this:
+
+```
+The file does not exist at "[path]" which is in the optimize deps directory. The dependency might be incompatible with the dep optimizer. Try adding it to `optimizeDeps.exclude`.
+```
+
+Usually, clearing Vite's cache resolves this issue. This can be accomplished by either:
+
+-   Stopping the development server and restarting it via the `make dev-server-force` command to force Vite to re-bundle dependencies.
+-   Deleting the `node_modules/.vite` directory (or `node_modules` entirely) and restarting the development server via `make dev-server`.
+
+You may also need to clear your browser cache to ensure no stale files are used.
diff --git a/docs/plugins.md b/docs/plugins.md
new file mode 100644
index 00000000..cc3c5c40
--- /dev/null
+++ b/docs/plugins.md
@@ -0,0 +1,22 @@
+# Plugin Support
+
+GutenbergKit bundles `@wordpress` modules locally for offline capability and fast load times. The editor can optionally load plugin-provided blocks and custom editor assets from a remote server when configured.
+
+## How Plugin Loading Works
+
+When the `plugins` configuration option is enabled:
+
+1. Core `@wordpress` packages are loaded from bundled code
+2. Plugin scripts and styles are fetched from the site's editor assets endpoint
+3. Custom blocks and editor extensions are registered dynamically
+4. The editor integrates both core and custom functionality
+
+This approach provides:
+
+-   **Offline-first**: Core editor works without network connectivity
+-   **Extensibility**: Supports custom blocks and plugins when connected
+-   **Performance**: Core packages load instantly from local bundle
+
+## Configuration
+
+Enable plugins by setting the `plugins` configuration option. The editor will fetch assets from the configured `editorAssetsEndpoint` or fall back to the default Jetpack endpoint. The demo app UI allows adding site-specific editor configurations, which enables the `plugins` configuration option.
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 00000000..aa6d693f
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,19 @@
+# Testing
+
+## JavaScript Testing
+
+-   Framework: Vitest
+-   Test files: `*.test.{js,jsx}`
+-   Run tests: `make test-js`
+
+## Native Testing
+
+### iOS
+
+-   XCTest framework
+-   Run: `make test-swift-package`
+
+### Android
+
+-   JUnit framework
+-   Run: `make test-android`

From ba08f5d5a1fef4a70462bea3afcf1d259523cbf9 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 08:01:37 -0500
Subject: [PATCH 02/18] docs: Define Gutenberg with a link

Some may not recognize Gutenberg.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d7238a8c..5c762539 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # GutenbergKit
 
-An experimental Gutenberg block editor for native iOS and Android apps relying upon web technologies.
+An experimental [Gutenberg](https://github.com/WordPress/gutenberg) block editor for native iOS and Android apps relying upon web technologies.
 
 <img width="320" alt="GutenbergKit running on an iPhone" src="./docs/gutenberg-kit-preview.png">
 

From 035d313baf20dc7f5c1abd05d461a9901b866140 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 08:02:30 -0500
Subject: [PATCH 03/18] docs: Fix typo

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5c762539..10995ec3 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ An experimental [Gutenberg](https://github.com/WordPress/gutenberg) block editor
 
 To see all available development commands, run `make help` (or simply `make`) in your terminal. This will display a list of all available build, test, and development commands.
 
-### Preqrequisites
+### Prerequisites
 
 In order to build GutenbergKit, the following tools must be installed on your development machine:
 

From fa3a104f9d0ee9a7e3bba83e40f8c5e7f667f720 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 09:19:45 -0500
Subject: [PATCH 04/18] docs: Focus README.md on general information

---
 CONTRIBUTING.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 114 +++++++-----------------------------------
 2 files changed, 145 insertions(+), 97 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..2ea7f1b2
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,128 @@
+# Contributing to GutenbergKit
+
+Thank you for your interest in contributing to GutenbergKit! This guide will help you get started with development.
+
+## Prerequisites
+
+In order to build GutenbergKit, the following tools must be installed on your development machine:
+
+-   [Node.js](https://nodejs.org/en/download/) - Required for building the web app; recommend using [Node Version Manager](https://github.com/nvm-sh/nvm).
+-   [Xcode](https://developer.apple.com/xcode/) - Required if building the iOS demo app.
+-   [Android Studio](https://developer.android.com/studio) - Required if building the Android demo app.
+
+## Development Commands
+
+To see all available development commands, run `make help` (or simply `make`) in your terminal. This will display a list of all available build, test, and development commands.
+
+## Web App
+
+Install the GutenbergKit dependencies and start the development server by running the following command in your terminal:
+
+```bash
+make dev-server
+```
+
+Once finished, the web app can now be accessed in your browser by visiting the URL logged in your terminal. However, it is **recommended to use a native host app for testing** changes made to the editor for a more realistic experience. A demo app is included in the GutenbergKit project, along with instructions on how to use it below.
+
+## Demo App
+
+This demo app is useful for quickly testing changes made to the editor.
+
+### iOS
+
+The iOS demo app loads the development server by default.
+
+1. Start the development server by running `make dev-server`.
+1. Launch Xcode and open the `ios/Demo-iOS/Gutenberg.xcodeproj` project.
+1. Select the `Gutenberg` target.
+1. Run the app.
+
+Alternatively, you can load a production build of the web app bundled with the GutenbergKit package by running `make build` and disabling the `GUTENBERG_EDITOR_URL` environment variable by navigating to _Product_ → _Scheme_ → _Edit Scheme_ in Xcode.
+
+<details>
+<summary>Example Xcode environment variable</summary>
+
+<img width="725" alt="Example Xcode environment variable" src="./docs/example-xcode-env-variable.png">
+
+</details>
+
+### Android
+
+The Android demo app loads the production build of the web app bundled with the GutenbergKit package by default—i.e., the output of the project's `make build` command. It can be configured to load the development server by setting a `GUTENBERG_EDITOR_URL` environment variable in the `android/local.properties` file.
+
+1. Start the development server by running `make dev-server`.
+1. Launch Android Studio and open the `android` project.
+1. Modify the `android/local.properties` file to include an environment variable named `GUTENBERG_EDITOR_URL` with the development server URL.
+1. Run the app on an emulator.
+
+<details>
+<summary>Example Android local.properties</summary>
+
+```
+GUTENBERG_EDITOR_URL=http://10.0.2.2:5173/
+```
+
+</details>
+
+> [!NOTE]
+> Android emulators route `http://10.0.2.2` to the host machine's IP address, allowing easy access to the development server from the emulator. For iOS simulators, the localhost URL is `http://localhost`. Appending the correct Vite development server port is required, which Vite logs when starting the server.
+>
+> To run the demo app on a physical device, see the [physical device setup guide](./docs/physical-device-setup.md).
+
+## Testing
+
+Important, high-level test cases are [documented](./docs/test-cases.md) for manual testing guidance. Additionally, automated tests are included in the project to ensure code quality and functionality.
+
+To run the JavaScript tests, run the following command in your terminal:
+
+```bash
+make test-js
+```
+
+To run the Swift tests, run the following command in your terminal:
+
+```bash
+make test-swift
+```
+
+To run the Android tests, run the following command in your terminal:
+
+```bash
+make test-android
+```
+
+## Code Quality
+
+Before submitting a pull request, ensure your code passes linting and formatting checks:
+
+```bash
+# Format JavaScript code
+make format
+
+# Auto-fix linting errors
+make lint-js-fix
+
+# Verify linting passes
+make lint-js
+```
+
+## Production Builds
+
+To build GutenbergKit for production run the following command in your terminal:
+
+```bash
+make build
+```
+
+Once finished, the Swift and Kotlin packages are ready to publish. Consuming iOS or Android host apps can then include the GutenbergKit package as a dependency.
+
+## Releases
+
+See the [release documentation](./docs/releases.md) for more information.
+
+## Additional Resources
+
+-   [Architecture Overview](./docs/architecture.md) - Project organization and communication patterns
+-   [Development Guide](./docs/development.md) - Development mode, debugging, and logging
+-   [Plugin Support](./docs/plugins.md) - How plugin loading works
+-   [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
diff --git a/README.md b/README.md
index 10995ec3..c00d99b7 100644
--- a/README.md
+++ b/README.md
@@ -1,110 +1,30 @@
 # GutenbergKit
 
-An experimental [Gutenberg](https://github.com/WordPress/gutenberg) block editor for native iOS and Android apps relying upon web technologies.
+<img width="250" style="display:block; margin-left:auto; margin-right:auto;" alt="GutenbergKit running on an iPhone" src="./docs/gutenberg-kit-preview.png">
 
-<img width="320" alt="GutenbergKit running on an iPhone" src="./docs/gutenberg-kit-preview.png">
+GutenbergKit brings the WordPress block editor to native mobile applications. It bridges WordPress's web-based Gutenberg editor with native iOS and Android apps, enabling a consistent editing experience across platforms.
 
-## Development
+The architecture consists of three main layers:
 
-To see all available development commands, run `make help` (or simply `make`) in your terminal. This will display a list of all available build, test, and development commands.
+-   **Web Layer**: React-based editor using WordPress Gutenberg packages
+-   **Bridge Layer**: Bidirectional communication between web and native code
+-   **Native Layer**: Platform-specific implementations (Swift for iOS, Kotlin for Android)
 
-### Prerequisites
+## Getting Started
 
-In order to build GutenbergKit, the following tools must be installed on your development machine:
+### Using GutenbergKit
 
--   [Node.js](https://nodejs.org/en/download/) - Required for building the web app; recommend using [Node Version Manager](https://github.com/nvm-sh/nvm).
--   [Xcode](https://developer.apple.com/xcode/) - Required if building the iOS demo app.
--   [Android Studio](https://developer.android.com/studio) - Required if building the Android demo app.
+To integrate GutenbergKit into your iOS or Android app, include the package as a dependency:
 
-### Web App
+-   **iOS**: Add the Swift package from the `ios/` directory
+-   **Android**: Add the Kotlin library from the `android/` directory
 
-Install the GutenbergKit dependencies and start the development server by running the following command in your terminal:
+See the [architecture overview](./docs/architecture.md) for details on project organization and communication patterns.
 
-```bash
-make dev-server
-```
+### Contributing
 
-Once finished, the web app can now be accessed in your browser by visiting the URL logged in your terminal. However, it is **recommended to use a native host app for testing** changes made to the editor for a more realistic experience. A demo app is included in the GutenbergKit project, along with instructions on how to use it below.
+We welcome contributions! See the [Contributing Guide](./CONTRIBUTING.md) for setup instructions, development workflow, and how to submit changes.
 
-### Demo App
-
-This demo app is useful for quickly testing changes made to the editor.
-
-#### iOS
-
-The iOS demo app loads the development server by default.
-
-1. Start the development server by running `make dev-server`.
-1. Launch Xcode and open the `ios/Demo-iOS/Gutenberg.xcodeproj` project.
-1. Select the `Gutenberg` target.
-1. Run the app.
-
-Alternatively, you can load a production build of the web app bundled with the GutenbergKit package by running `make build` and disabling the `GUTENBERG_EDITOR_URL` environment variable by navigating to _Product_ → _Scheme_ → _Edit Scheme_ in Xcode.
-
-<details>
-<summary>Example Xcode environment variable</summary>
-
-<img width="725" alt="Example Xcode environment variable" src="./docs/example-xcode-env-variable.png">
-
-</details>
-
-#### Android
-
-The Android demo app loads the production build of the web app bundled with the GutenbergKit package by default—i.e., the output of the project's `make build` command. It can be configured to load the development server by setting a `GUTENBERG_EDITOR_URL` environment variable in the `android/local.properties` file.
-
-1. Start the development server by running `make dev-server`.
-1. Launch Android Studio and open the `android` project.
-1. Modify the `android/local.properties` file to include an environment variable named `GUTENBERG_EDITOR_URL` with the development server URL.
-1. Run the app on an emulator.
-
-<details>
-<summary>Example Android local.properties</summary>
-
-```
-GUTENBERG_EDITOR_URL=http://10.0.2.2:5173/
-```
-
-</details>
-
-> [!NOTE]
-> Android emulators route `http://10.0.2.2` to the host machine's IP address, allowing easy access to the development server from the emulator. For iOS simulators, the localhost URL is `http://localhost`. Appending the correct Vite development server port is required, which Vite logs when starting the server.
->
-> To run the demo app on a physical device, see the [physical device setup guide](./docs/physical-device-setup.md).
-
-See the [architecture overview](./docs/architecture.md) for additional details regarding project organization and development tips.
-
-## Testing
-
-Important, high-level test cases are [documented](./docs/test-cases.md) for manual testing guidance. Additionally, automated tests are included in the project to ensure code quality and functionality.
-
-To run the JavaScript tests, run the following command in your terminal:
-
-```bash
-make test-js
-```
-
-To run the Swift tests, run the following command in your terminal:
-
-```bash
-make test-swift
-```
-
-To run the Android tests, run the following command in your terminal:
-
-```bash
-make test-android
-```
-
-## Production
-
-To build GutenbergKit for production run the following command in your terminal:
-
-```bash
-make build
-```
-
-Once finished, the Swift and Kotlin packages are ready to publish. Consuming iOS or Android host apps can then include the GutenbergKit package as a dependency.
-
-## Releases
-
-See the [release documentation](./docs/releases.md) for more information.
+-   [Architecture Overview](./docs/architecture.md) - Project structure and communication patterns
+-   [Plugin Support](./docs/plugins.md) - How to load custom blocks and editor assets
+-   [Development Guide](./docs/development.md) - Development mode, debugging, and logging

From dd01f6458c569c51ffce84d96abea1a96804bab0 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 09:53:40 -0500
Subject: [PATCH 05/18] docs: Expand documentation to cover non-code
 contributions

---
 CONTRIBUTING.md                               | 132 +++---------------
 README.md                                     |   6 -
 docs/code/README.md                           |  17 +++
 docs/{ => code}/architecture.md               |   0
 .../development-tools.md}                     |  29 +---
 docs/code/getting-started.md                  |  78 +++++++++++
 docs/{ => code}/physical-device-setup.md      |   0
 docs/{ => code}/plugins.md                    |   0
 docs/{ => code}/preloading.md                 |   0
 docs/code/testing.md                          |  62 ++++++++
 docs/code/troubleshooting.md                  |  30 ++++
 docs/testing.md                               |  19 ---
 12 files changed, 206 insertions(+), 167 deletions(-)
 create mode 100644 docs/code/README.md
 rename docs/{ => code}/architecture.md (100%)
 rename docs/{development.md => code/development-tools.md} (57%)
 create mode 100644 docs/code/getting-started.md
 rename docs/{ => code}/physical-device-setup.md (100%)
 rename docs/{ => code}/plugins.md (100%)
 rename docs/{ => code}/preloading.md (100%)
 create mode 100644 docs/code/testing.md
 create mode 100644 docs/code/troubleshooting.md
 delete mode 100644 docs/testing.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2ea7f1b2..3bcdc363 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,128 +1,28 @@
 # Contributing to GutenbergKit
 
-Thank you for your interest in contributing to GutenbergKit! This guide will help you get started with development.
+Thank you for your interest in contributing to GutenbergKit!
 
-## Prerequisites
+## How Can I Contribute?
 
-In order to build GutenbergKit, the following tools must be installed on your development machine:
+Whether you're looking to write code, improve documentation, or help triage issues, there are many ways to contribute:
 
--   [Node.js](https://nodejs.org/en/download/) - Required for building the web app; recommend using [Node Version Manager](https://github.com/nvm-sh/nvm).
--   [Xcode](https://developer.apple.com/xcode/) - Required if building the iOS demo app.
--   [Android Studio](https://developer.android.com/studio) - Required if building the Android demo app.
+-   **Code**: See the [Code Contributions](./docs/code/README.md) guide to get started
+-   **Documentation**: Help improve our [docs](./docs/)
+-   **Triage**: Review and label [open issues](https://github.com/wordpress-mobile/GutenbergKit/issues)
 
-## Development Commands
+## Development Resources
 
-To see all available development commands, run `make help` (or simply `make`) in your terminal. This will display a list of all available build, test, and development commands.
+-   [Getting Started](./docs/code/getting-started.md) - Prerequisites and setup
+-   [Development Tools](./docs/code/development-tools.md) - Debugging and development features
+-   [Testing](./docs/code/testing.md) - Running tests and code quality
+-   [Architecture](./docs/code/architecture.md) - Project structure and patterns
 
-## Web App
+## Guidelines
 
-Install the GutenbergKit dependencies and start the development server by running the following command in your terminal:
-
-```bash
-make dev-server
-```
-
-Once finished, the web app can now be accessed in your browser by visiting the URL logged in your terminal. However, it is **recommended to use a native host app for testing** changes made to the editor for a more realistic experience. A demo app is included in the GutenbergKit project, along with instructions on how to use it below.
-
-## Demo App
-
-This demo app is useful for quickly testing changes made to the editor.
-
-### iOS
-
-The iOS demo app loads the development server by default.
-
-1. Start the development server by running `make dev-server`.
-1. Launch Xcode and open the `ios/Demo-iOS/Gutenberg.xcodeproj` project.
-1. Select the `Gutenberg` target.
-1. Run the app.
-
-Alternatively, you can load a production build of the web app bundled with the GutenbergKit package by running `make build` and disabling the `GUTENBERG_EDITOR_URL` environment variable by navigating to _Product_ → _Scheme_ → _Edit Scheme_ in Xcode.
-
-<details>
-<summary>Example Xcode environment variable</summary>
-
-<img width="725" alt="Example Xcode environment variable" src="./docs/example-xcode-env-variable.png">
-
-</details>
-
-### Android
-
-The Android demo app loads the production build of the web app bundled with the GutenbergKit package by default—i.e., the output of the project's `make build` command. It can be configured to load the development server by setting a `GUTENBERG_EDITOR_URL` environment variable in the `android/local.properties` file.
-
-1. Start the development server by running `make dev-server`.
-1. Launch Android Studio and open the `android` project.
-1. Modify the `android/local.properties` file to include an environment variable named `GUTENBERG_EDITOR_URL` with the development server URL.
-1. Run the app on an emulator.
-
-<details>
-<summary>Example Android local.properties</summary>
-
-```
-GUTENBERG_EDITOR_URL=http://10.0.2.2:5173/
-```
-
-</details>
-
-> [!NOTE]
-> Android emulators route `http://10.0.2.2` to the host machine's IP address, allowing easy access to the development server from the emulator. For iOS simulators, the localhost URL is `http://localhost`. Appending the correct Vite development server port is required, which Vite logs when starting the server.
->
-> To run the demo app on a physical device, see the [physical device setup guide](./docs/physical-device-setup.md).
-
-## Testing
-
-Important, high-level test cases are [documented](./docs/test-cases.md) for manual testing guidance. Additionally, automated tests are included in the project to ensure code quality and functionality.
-
-To run the JavaScript tests, run the following command in your terminal:
-
-```bash
-make test-js
-```
-
-To run the Swift tests, run the following command in your terminal:
-
-```bash
-make test-swift
-```
-
-To run the Android tests, run the following command in your terminal:
-
-```bash
-make test-android
-```
-
-## Code Quality
-
-Before submitting a pull request, ensure your code passes linting and formatting checks:
-
-```bash
-# Format JavaScript code
-make format
-
-# Auto-fix linting errors
-make lint-js-fix
-
-# Verify linting passes
-make lint-js
-```
-
-## Production Builds
-
-To build GutenbergKit for production run the following command in your terminal:
-
-```bash
-make build
-```
-
-Once finished, the Swift and Kotlin packages are ready to publish. Consuming iOS or Android host apps can then include the GutenbergKit package as a dependency.
+-   Run `make format` and `make lint-js` before submitting changes
+-   Ensure tests pass with `make test-js`
+-   Follow the existing code style and patterns
 
 ## Releases
 
-See the [release documentation](./docs/releases.md) for more information.
-
-## Additional Resources
-
--   [Architecture Overview](./docs/architecture.md) - Project organization and communication patterns
--   [Development Guide](./docs/development.md) - Development mode, debugging, and logging
--   [Plugin Support](./docs/plugins.md) - How plugin loading works
--   [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
+See the [release documentation](./docs/releases.md) for information about the release process.
diff --git a/README.md b/README.md
index c00d99b7..b9d2bd8c 100644
--- a/README.md
+++ b/README.md
@@ -19,12 +19,6 @@ To integrate GutenbergKit into your iOS or Android app, include the package as a
 -   **iOS**: Add the Swift package from the `ios/` directory
 -   **Android**: Add the Kotlin library from the `android/` directory
 
-See the [architecture overview](./docs/architecture.md) for details on project organization and communication patterns.
-
 ### Contributing
 
 We welcome contributions! See the [Contributing Guide](./CONTRIBUTING.md) for setup instructions, development workflow, and how to submit changes.
-
--   [Architecture Overview](./docs/architecture.md) - Project structure and communication patterns
--   [Plugin Support](./docs/plugins.md) - How to load custom blocks and editor assets
--   [Development Guide](./docs/development.md) - Development mode, debugging, and logging
diff --git a/docs/code/README.md b/docs/code/README.md
new file mode 100644
index 00000000..99bdfc69
--- /dev/null
+++ b/docs/code/README.md
@@ -0,0 +1,17 @@
+# Code Contributions
+
+This guide is for developers who want to contribute code to GutenbergKit.
+
+## Getting Started
+
+-   [Getting Started](./getting-started.md) - Prerequisites, setup, and running the demo apps
+-   [Development Tools](./development-tools.md) - Development mode, React DevTools, and logging
+-   [Testing](./testing.md) - Running tests and ensuring code quality
+-   [Troubleshooting](./troubleshooting.md) - Common issues and solutions
+
+## Reference
+
+-   [Architecture](./architecture.md) - Project structure and communication patterns
+-   [Plugins](./plugins.md) - Plugin loading and custom blocks
+-   [Preloading](./preloading.md) - Asset preloading
+-   [Physical Device Setup](./physical-device-setup.md) - Running on physical devices
diff --git a/docs/architecture.md b/docs/code/architecture.md
similarity index 100%
rename from docs/architecture.md
rename to docs/code/architecture.md
diff --git a/docs/development.md b/docs/code/development-tools.md
similarity index 57%
rename from docs/development.md
rename to docs/code/development-tools.md
index c7ec64b7..5297f349 100644
--- a/docs/development.md
+++ b/docs/code/development-tools.md
@@ -1,4 +1,6 @@
-# Development Guide
+# Development Tools
+
+This guide covers debugging tools and development features available in GutenbergKit.
 
 ## Development Mode
 
@@ -67,28 +69,3 @@ The default log level is `info`. The project's demo app defaults to `debug`. Ava
 -   `warn`: Logs warnings and errors
 -   `info`: Logs informational messages, warnings, and errors
 -   `debug`: Logs detailed debugging information, informational messages, warnings, and errors
-
-## Troubleshooting
-
-### Why do I encounter a `GBKit global not available after timeout` error when opening the GutenbergKit editor in a browser?
-
-This error occurs when the editor is unable to communicate with the native bridge. This is expected when opening the editor in a browser, as the native bridge is not available. GutenbergKit is designed to be used in a native host app that provides the native bridge. The GutenbergKit project includes a demo app that can be used to test the editor.
-
-It is possible to circumvent this this error by adding the `?dev_mode` query parameter to the editor URL in your browser. This will bypass the native bridge requirement and allow the editor to load without the native bridge. However, some features may not work as expected when using this mode.
-
-### Why do I encounter an `Importing a module script failed.` error?
-
-This [generally indicates](https://github.com/vitejs/vite/discussions/17738) that Vite is attempting to load a cached dependency that no longer exists or is corrupted.
-
-Often times this is paired with a following warning in the Vite development server console that looks like this:
-
-```
-The file does not exist at "[path]" which is in the optimize deps directory. The dependency might be incompatible with the dep optimizer. Try adding it to `optimizeDeps.exclude`.
-```
-
-Usually, clearing Vite's cache resolves this issue. This can be accomplished by either:
-
--   Stopping the development server and restarting it via the `make dev-server-force` command to force Vite to re-bundle dependencies.
--   Deleting the `node_modules/.vite` directory (or `node_modules` entirely) and restarting the development server via `make dev-server`.
-
-You may also need to clear your browser cache to ensure no stale files are used.
diff --git a/docs/code/getting-started.md b/docs/code/getting-started.md
new file mode 100644
index 00000000..b93eb764
--- /dev/null
+++ b/docs/code/getting-started.md
@@ -0,0 +1,78 @@
+# Getting Started
+
+This guide will help you set up your development environment for GutenbergKit.
+
+## Prerequisites
+
+In order to build GutenbergKit, the following tools must be installed on your development machine:
+
+-   [Node.js](https://nodejs.org/en/download/) - Required for building the web app; recommend using [Node Version Manager](https://github.com/nvm-sh/nvm).
+-   [Xcode](https://developer.apple.com/xcode/) - Required if building the iOS demo app.
+-   [Android Studio](https://developer.android.com/studio) - Required if building the Android demo app.
+
+## Development Commands
+
+To see all available development commands, run `make help` (or simply `make`) in your terminal. This will display a list of all available build, test, and development commands.
+
+## Web App
+
+Install the GutenbergKit dependencies and start the development server by running the following command in your terminal:
+
+```bash
+make dev-server
+```
+
+Once finished, the web app can now be accessed in your browser by visiting the URL logged in your terminal. However, it is **recommended to use a native host app for testing** changes made to the editor for a more realistic experience. A demo app is included in the GutenbergKit project, along with instructions on how to use it below.
+
+## Demo App
+
+This demo app is useful for quickly testing changes made to the editor.
+
+### iOS
+
+The iOS demo app loads the development server by default.
+
+1. Start the development server by running `make dev-server`.
+1. Launch Xcode and open the `ios/Demo-iOS/Gutenberg.xcodeproj` project.
+1. Select the `Gutenberg` target.
+1. Run the app.
+
+Alternatively, you can load a production build of the web app bundled with the GutenbergKit package by running `make build` and disabling the `GUTENBERG_EDITOR_URL` environment variable by navigating to _Product_ → _Scheme_ → _Edit Scheme_ in Xcode.
+
+<details>
+<summary>Example Xcode environment variable</summary>
+
+<img width="725" alt="Example Xcode environment variable" src="../example-xcode-env-variable.png">
+
+</details>
+
+### Android
+
+The Android demo app loads the production build of the web app bundled with the GutenbergKit package by default—i.e., the output of the project's `make build` command. It can be configured to load the development server by setting a `GUTENBERG_EDITOR_URL` environment variable in the `android/local.properties` file.
+
+1. Start the development server by running `make dev-server`.
+1. Launch Android Studio and open the `android` project.
+1. Modify the `android/local.properties` file to include an environment variable named `GUTENBERG_EDITOR_URL` with the development server URL.
+1. Run the app on an emulator.
+
+<details>
+<summary>Example Android local.properties</summary>
+
+```
+GUTENBERG_EDITOR_URL=http://10.0.2.2:5173/
+```
+
+</details>
+
+> [!NOTE]
+> Android emulators route `http://10.0.2.2` to the host machine's IP address, allowing easy access to the development server from the emulator. For iOS simulators, the localhost URL is `http://localhost`. Appending the correct Vite development server port is required, which Vite logs when starting the server.
+>
+> To run the demo app on a physical device, see the [physical device setup guide](./physical-device-setup.md).
+
+## Production Builds
+
+To build GutenbergKit for production run the following command in your terminal:
+
+```bash
+make build
+```
diff --git a/docs/physical-device-setup.md b/docs/code/physical-device-setup.md
similarity index 100%
rename from docs/physical-device-setup.md
rename to docs/code/physical-device-setup.md
diff --git a/docs/plugins.md b/docs/code/plugins.md
similarity index 100%
rename from docs/plugins.md
rename to docs/code/plugins.md
diff --git a/docs/preloading.md b/docs/code/preloading.md
similarity index 100%
rename from docs/preloading.md
rename to docs/code/preloading.md
diff --git a/docs/code/testing.md b/docs/code/testing.md
new file mode 100644
index 00000000..eafff50f
--- /dev/null
+++ b/docs/code/testing.md
@@ -0,0 +1,62 @@
+# Testing
+
+This guide covers automated testing and code quality tools in GutenbergKit.
+
+## Automated Tests
+
+Important, high-level test cases are [documented](../test-cases.md) for manual testing guidance. Additionally, automated tests are included in the project to ensure code quality and functionality.
+
+### JavaScript Tests
+
+-   Framework: Vitest
+-   Test files: `*.test.{js,jsx}`
+
+To run the JavaScript tests:
+
+```bash
+make test-js
+```
+
+### Swift Tests
+
+-   Framework: Swift Testing
+
+To run the Swift tests:
+
+```bash
+make test-swift
+```
+
+### Android Tests
+
+-   Framework: JUnit
+
+To run the Android tests:
+
+```bash
+make test-android
+```
+
+## Code Quality
+
+Before submitting a pull request, ensure your code passes formatting and linting checks.
+
+### Formatting
+
+Format JavaScript code using Prettier:
+
+```bash
+make format
+```
+
+### Linting
+
+Lint JavaScript code using ESLint:
+
+```bash
+# Auto-fix linting errors
+make lint-js-fix
+
+# Verify linting passes
+make lint-js
+```
diff --git a/docs/code/troubleshooting.md b/docs/code/troubleshooting.md
new file mode 100644
index 00000000..300ac055
--- /dev/null
+++ b/docs/code/troubleshooting.md
@@ -0,0 +1,30 @@
+# Troubleshooting
+
+This guide covers common issues and solutions when developing GutenbergKit.
+
+## GBKit global not available after timeout
+
+**Error:** `GBKit global not available after timeout`
+
+This error occurs when the editor is unable to communicate with the native bridge. This is expected when opening the editor in a browser, as the native bridge is not available. GutenbergKit is designed to be used in a native host app that provides the native bridge. The GutenbergKit project includes a demo app that can be used to test the editor.
+
+**Solution:** Add the `?dev_mode` query parameter to the editor URL in your browser. This will bypass the native bridge requirement and allow the editor to load without the native bridge. However, some features may not work as expected when using this mode.
+
+## Importing a module script failed
+
+**Error:** `Importing a module script failed.`
+
+This [generally indicates](https://github.com/vitejs/vite/discussions/17738) that Vite is attempting to load a cached dependency that no longer exists or is corrupted.
+
+Often times this is paired with a following warning in the Vite development server console that looks like this:
+
+```
+The file does not exist at "[path]" which is in the optimize deps directory. The dependency might be incompatible with the dep optimizer. Try adding it to `optimizeDeps.exclude`.
+```
+
+**Solution:** Clear Vite's cache by either:
+
+-   Stopping the development server and restarting it via the `make dev-server-force` command to force Vite to re-bundle dependencies.
+-   Deleting the `node_modules/.vite` directory (or `node_modules` entirely) and restarting the development server via `make dev-server`.
+
+You may also need to clear your browser cache to ensure no stale files are used.
diff --git a/docs/testing.md b/docs/testing.md
deleted file mode 100644
index aa6d693f..00000000
--- a/docs/testing.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Testing
-
-## JavaScript Testing
-
--   Framework: Vitest
--   Test files: `*.test.{js,jsx}`
--   Run tests: `make test-js`
-
-## Native Testing
-
-### iOS
-
--   XCTest framework
--   Run: `make test-swift-package`
-
-### Android
-
--   JUnit framework
--   Run: `make test-android`

From 0374d1b75c1c738800d79f1dc2b4d5c5abc8a9a5 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:02:08 -0500
Subject: [PATCH 06/18] docs: Add integrations guides

---
 README.md           |   2 +
 docs/integration.md | 301 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 303 insertions(+)
 create mode 100644 docs/integration.md

diff --git a/README.md b/README.md
index b9d2bd8c..3f00c1a1 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,8 @@ To integrate GutenbergKit into your iOS or Android app, include the package as a
 -   **iOS**: Add the Swift package from the `ios/` directory
 -   **Android**: Add the Kotlin library from the `android/` directory
 
+See the [Integration Guide](./docs/integration.md) for detailed setup instructions and code examples.
+
 ### Contributing
 
 We welcome contributions! See the [Contributing Guide](./CONTRIBUTING.md) for setup instructions, development workflow, and how to submit changes.
diff --git a/docs/integration.md b/docs/integration.md
new file mode 100644
index 00000000..d49f1d6d
--- /dev/null
+++ b/docs/integration.md
@@ -0,0 +1,301 @@
+# Integration Guide
+
+This guide covers how to integrate GutenbergKit into your iOS or Android app.
+
+## iOS Integration
+
+### Adding the Package
+
+Add the GutenbergKit Swift package from the `ios/` directory to your Xcode project.
+
+### Basic Setup
+
+Create an `EditorViewController` with a configuration:
+
+```swift
+import GutenbergKit
+
+let configuration = EditorConfigurationBuilder(
+    postType: "post",
+    siteURL: URL(string: "https://example.com")!,
+    siteApiRoot: URL(string: "https://example.com/wp-json")!
+)
+    .setTitle("My Post")
+    .setContent("<!-- wp:paragraph --><p>Hello world</p><!-- /wp:paragraph -->")
+    .setAuthHeader("Bearer your-token")
+    .build()
+
+let editorViewController = EditorViewController(configuration: configuration)
+editorViewController.delegate = self
+```
+
+### Configuration Options
+
+Use `EditorConfigurationBuilder` to configure the editor:
+
+```swift
+let configuration = EditorConfigurationBuilder(
+    postType: "post",
+    siteURL: siteURL,
+    siteApiRoot: apiRoot
+)
+    // Content
+    .setTitle("Post Title")
+    .setContent("<p>Initial content</p>")
+    .setPostID(123)
+
+    // Features
+    .setShouldUseThemeStyles(true)
+    .setShouldUsePlugins(true)
+    .setShouldHideTitle(false)
+    .setNativeInserterEnabled(true)
+
+    // Authentication
+    .setAuthHeader("Bearer token")
+
+    // Localization
+    .setLocale("en")
+
+    // Debugging
+    .setLogLevel(.debug)
+    .setEnableNetworkLogging(true)
+
+    .build()
+```
+
+### Implementing the Delegate
+
+Implement `EditorViewControllerDelegate` to handle editor events:
+
+```swift
+extension YourViewController: EditorViewControllerDelegate {
+    func editorDidLoad(_ viewController: EditorViewController) {
+        // Editor finished loading
+    }
+
+    func editor(_ viewController: EditorViewController, didUpdateContentWithState state: EditorState) {
+        // Content changed - state.isEmpty indicates if editor is empty
+    }
+
+    func editor(_ viewController: EditorViewController, didUpdateHistoryState state: EditorState) {
+        // Undo/redo state changed - use state.hasUndo and state.hasRedo
+    }
+
+    func editor(_ viewController: EditorViewController, didRequestMediaFromSiteMediaLibrary config: OpenMediaLibraryAction) {
+        // User requested media picker - present your media library UI
+    }
+
+    func editor(_ viewController: EditorViewController, didEncounterCriticalError error: Error) {
+        // Handle critical errors
+    }
+}
+```
+
+### Getting and Setting Content
+
+```swift
+// Set content
+editorViewController.setContent("<!-- wp:paragraph --><p>New content</p><!-- /wp:paragraph -->")
+
+// Get content
+let content = try await editorViewController.getContent()
+
+// Get title and content together
+let result = try await editorViewController.getTitleAndContent()
+print("Title: \(result.title), Content: \(result.content)")
+```
+
+### Performance Optimization
+
+Pre-warm the editor for faster first load:
+
+```swift
+// Call early in your app lifecycle
+EditorViewController.warmup(configuration: configuration)
+```
+
+For the fastest loading, pre-fetch dependencies:
+
+```swift
+let service = EditorService(configuration: configuration)
+let dependencies = try await service.prepare { progress in
+    print("Loading: \(progress.fractionCompleted * 100)%")
+}
+
+// Pass dependencies for instant loading
+let editorViewController = EditorViewController(
+    configuration: configuration,
+    dependencies: dependencies
+)
+```
+
+## Android Integration
+
+### Adding the Library
+
+Add the GutenbergKit library from the `android/Gutenberg/` directory to your project.
+
+### Basic Setup
+
+Create a `GutenbergView` and start the editor:
+
+```kotlin
+import org.wordpress.gutenberg.GutenbergView
+import org.wordpress.gutenberg.EditorConfiguration
+
+val gutenbergView = GutenbergView(context)
+gutenbergView.initializeWebView()
+
+val configuration = EditorConfiguration.builder()
+    .setTitle("My Post")
+    .setContent("<!-- wp:paragraph --><p>Hello world</p><!-- /wp:paragraph -->")
+    .setPostType("post")
+    .setSiteURL("https://example.com")
+    .setSiteApiRoot("https://example.com/wp-json")
+    .setAuthHeader("Bearer your-token")
+    .build()
+
+gutenbergView.start(configuration)
+```
+
+### Configuration Options
+
+Use `EditorConfiguration.builder()` to configure the editor:
+
+```kotlin
+val configuration = EditorConfiguration.builder()
+    // Content
+    .setTitle("Post Title")
+    .setContent("<p>Initial content</p>")
+    .setPostId(123)
+    .setPostType("post")
+
+    // Features
+    .setThemeStyles(true)
+    .setPlugins(true)
+    .setHideTitle(false)
+
+    // Site settings
+    .setSiteURL("https://example.com")
+    .setSiteApiRoot("https://example.com/wp-json")
+    .setSiteApiNamespace(arrayOf("wp/v2"))
+
+    // Authentication
+    .setAuthHeader("Bearer token")
+    .setCookies(mapOf("session" to "value"))
+
+    // Localization
+    .setLocale("en")
+
+    // Caching
+    .setEnableAssetCaching(true)
+    .setCachedAssetHosts(setOf("example.com", "cdn.example.com"))
+
+    // Debugging
+    .setEnableNetworkLogging(true)
+
+    .build()
+```
+
+### Setting Up Listeners
+
+Register listeners to handle editor events:
+
+```kotlin
+gutenbergView.setEditorDidBecomeAvailable { view ->
+    // Editor finished loading
+}
+
+gutenbergView.setContentChangeListener {
+    // Content changed
+}
+
+gutenbergView.setHistoryChangeListener { hasUndo, hasRedo ->
+    // Undo/redo state changed
+}
+
+gutenbergView.setOpenMediaLibraryListener { config ->
+    // User requested media picker
+    // config.allowedTypes, config.multiple, etc.
+}
+
+gutenbergView.setLogJsExceptionListener { exception ->
+    // Handle JavaScript exceptions
+}
+```
+
+### Getting and Setting Content
+
+```kotlin
+// Set content
+gutenbergView.setContent("<!-- wp:paragraph --><p>New content</p><!-- /wp:paragraph -->")
+
+// Get title and content
+gutenbergView.getTitleAndContent(
+    originalContent = "",
+    callback = object : TitleAndContentCallback {
+        override fun onResult(title: CharSequence, content: CharSequence) {
+            // Use title and content
+        }
+    },
+    completeComposition = true
+)
+```
+
+### Performance Optimization
+
+Pre-warm the editor for faster first load:
+
+```kotlin
+// Call early in your app lifecycle
+GutenbergView.warmup(context, configuration)
+```
+
+Enable asset caching for plugin and theme styles:
+
+```kotlin
+val configuration = EditorConfiguration.builder()
+    .setEnableAssetCaching(true)
+    .setCachedAssetHosts(setOf("example.com", "cdn.example.com"))
+    .build()
+```
+
+## Common Patterns
+
+### Plugin Support
+
+Load custom blocks and editor assets from your site:
+
+```swift
+// iOS
+let configuration = EditorConfigurationBuilder(...)
+    .setShouldUsePlugins(true)
+    .setEditorAssetsEndpoint(URL(string: "https://example.com/editor-assets")!)
+    .build()
+```
+
+```kotlin
+// Android
+val configuration = EditorConfiguration.builder()
+    .setPlugins(true)
+    .setEditorAssetsEndpoint("https://example.com/editor-assets")
+    .build()
+```
+
+### Theme Styles
+
+Apply your site's theme styles to the editor:
+
+```swift
+// iOS
+let configuration = EditorConfigurationBuilder(...)
+    .setShouldUseThemeStyles(true)
+    .build()
+```
+
+```kotlin
+// Android
+val configuration = EditorConfiguration.builder()
+    .setThemeStyles(true)
+    .build()
+```

From d3a02ed0c1028992aa2ac63ab7a14b91e7de372d Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:03:19 -0500
Subject: [PATCH 07/18] docs: Note theme styles requires editor settings

---
 docs/integration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/integration.md b/docs/integration.md
index d49f1d6d..f9fd7b93 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -284,7 +284,7 @@ val configuration = EditorConfiguration.builder()
 
 ### Theme Styles
 
-Apply your site's theme styles to the editor:
+Apply your site's theme styles to the editor. This requires valid editor settings that provide theme style configuration (colors, typography, etc.) from your WordPress site's block editor settings endpoint or elsewhere.
 
 ```swift
 // iOS

From 86f19332fa496856f52c9ba7e2de3634fcf4cd8b Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:07:06 -0500
Subject: [PATCH 08/18] docs: Note required native dependencies

---
 docs/integration.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/integration.md b/docs/integration.md
index f9fd7b93..1100064f 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -2,6 +2,23 @@
 
 This guide covers how to integrate GutenbergKit into your iOS or Android app.
 
+## Requirements
+
+### iOS
+
+-   **Platform**: iOS 17+ / macOS 14+
+-   **Dependencies** (automatically resolved via Swift Package Manager):
+    -   [SwiftSoup](https://github.com/scinfu/SwiftSoup) - HTML parsing
+    -   [SVGView](https://github.com/exyte/SVGView) - SVG rendering for block icons
+
+### Android
+
+-   **Platform**: minSdk 24 (Android 7.0), targetSdk 34
+-   **Dependencies** (managed via Gradle):
+    -   `androidx.webkit:webkit` - Enhanced WebView features
+    -   `com.google.code.gson:gson` - JSON serialization
+    -   `kotlinx-coroutines-android` - Async operations
+
 ## iOS Integration
 
 ### Adding the Package

From f25bbc858fb2785ffb76ad255310160d519e19cc Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:16:51 -0500
Subject: [PATCH 09/18] docs: Simplify native integration examples

Mitigate stale documentation.
---
 docs/integration.md | 69 ++-------------------------------------------
 1 file changed, 2 insertions(+), 67 deletions(-)

diff --git a/docs/integration.md b/docs/integration.md
index 1100064f..72ce18e4 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -48,37 +48,7 @@ editorViewController.delegate = self
 
 ### Configuration Options
 
-Use `EditorConfigurationBuilder` to configure the editor:
-
-```swift
-let configuration = EditorConfigurationBuilder(
-    postType: "post",
-    siteURL: siteURL,
-    siteApiRoot: apiRoot
-)
-    // Content
-    .setTitle("Post Title")
-    .setContent("<p>Initial content</p>")
-    .setPostID(123)
-
-    // Features
-    .setShouldUseThemeStyles(true)
-    .setShouldUsePlugins(true)
-    .setShouldHideTitle(false)
-    .setNativeInserterEnabled(true)
-
-    // Authentication
-    .setAuthHeader("Bearer token")
-
-    // Localization
-    .setLocale("en")
-
-    // Debugging
-    .setLogLevel(.debug)
-    .setEnableNetworkLogging(true)
-
-    .build()
-```
+The `EditorConfigurationBuilder` provides many options for customizing the editor. See [`EditorConfiguration.swift`](../ios/Sources/GutenbergKit/Sources/Model/EditorConfiguration.swift) for all available options.
 
 ### Implementing the Delegate
 
@@ -177,42 +147,7 @@ gutenbergView.start(configuration)
 
 ### Configuration Options
 
-Use `EditorConfiguration.builder()` to configure the editor:
-
-```kotlin
-val configuration = EditorConfiguration.builder()
-    // Content
-    .setTitle("Post Title")
-    .setContent("<p>Initial content</p>")
-    .setPostId(123)
-    .setPostType("post")
-
-    // Features
-    .setThemeStyles(true)
-    .setPlugins(true)
-    .setHideTitle(false)
-
-    // Site settings
-    .setSiteURL("https://example.com")
-    .setSiteApiRoot("https://example.com/wp-json")
-    .setSiteApiNamespace(arrayOf("wp/v2"))
-
-    // Authentication
-    .setAuthHeader("Bearer token")
-    .setCookies(mapOf("session" to "value"))
-
-    // Localization
-    .setLocale("en")
-
-    // Caching
-    .setEnableAssetCaching(true)
-    .setCachedAssetHosts(setOf("example.com", "cdn.example.com"))
-
-    // Debugging
-    .setEnableNetworkLogging(true)
-
-    .build()
-```
+The `EditorConfiguration.builder()` provides many options for customizing the editor. See [`EditorConfiguration.kt`](../android/Gutenberg/src/main/java/org/wordpress/gutenberg/EditorConfiguration.kt) for all available options.
 
 ### Setting Up Listeners
 

From 617e0aa9705cb5a392ce15bd2b5fa0ec77e31efd Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:18:30 -0500
Subject: [PATCH 10/18] docs: Further explain theme styles require editor
 settings

---
 docs/integration.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/integration.md b/docs/integration.md
index 72ce18e4..20a47ab6 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -236,18 +236,26 @@ val configuration = EditorConfiguration.builder()
 
 ### Theme Styles
 
-Apply your site's theme styles to the editor. This requires valid editor settings that provide theme style configuration (colors, typography, etc.) from your WordPress site's block editor settings endpoint or elsewhere.
+Apply your site's theme styles to the editor. This requires valid editor settings (JSON) that provide theme style configuration (colors, typography, etc.) from your WordPress site's block editor settings endpoint (`/wp-block-editor/v1/settings`) or elsewhere.
 
 ```swift
 // iOS
+// Fetch editor settings JSON from your WordPress site
+let editorSettingsJSON = try await fetchEditorSettings()
+
 let configuration = EditorConfigurationBuilder(...)
     .setShouldUseThemeStyles(true)
+    .setEditorSettings(editorSettingsJSON)
     .build()
 ```
 
 ```kotlin
 // Android
+// Fetch editor settings JSON from your WordPress site
+val editorSettingsJSON = fetchEditorSettings()
+
 val configuration = EditorConfiguration.builder()
     .setThemeStyles(true)
+    .setEditorSettings(editorSettingsJSON)
     .build()
 ```

From 13583860ec1d879503c3c66f073ce8d5c47ab3d5 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:19:45 -0500
Subject: [PATCH 11/18] docs: Remove discarded inline styles

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3f00c1a1..e6783143 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # GutenbergKit
 
-<img width="250" style="display:block; margin-left:auto; margin-right:auto;" alt="GutenbergKit running on an iPhone" src="./docs/gutenberg-kit-preview.png">
+<img width="250" alt="GutenbergKit running on an iPhone" src="./docs/gutenberg-kit-preview.png">
 
 GutenbergKit brings the WordPress block editor to native mobile applications. It bridges WordPress's web-based Gutenberg editor with native iOS and Android apps, enabling a consistent editing experience across platforms.
 

From 36fb367383683f436dc498042350f7be66a5c6ce Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:24:20 -0500
Subject: [PATCH 12/18] docs: Link to WordPress projects

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e6783143..1351b313 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 <img width="250" alt="GutenbergKit running on an iPhone" src="./docs/gutenberg-kit-preview.png">
 
-GutenbergKit brings the WordPress block editor to native mobile applications. It bridges WordPress's web-based Gutenberg editor with native iOS and Android apps, enabling a consistent editing experience across platforms.
+GutenbergKit brings the [WordPress](https://wordpress.org/) block editor to native mobile applications. It bridges WordPress's web-based [Gutenberg](https://github.com/WordPress/gutenberg/) editor with native iOS and Android apps, enabling a consistent editing experience across platforms.
 
 The architecture consists of three main layers:
 

From c65a986598a813bf4160047e845e5c4ae059bc83 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:27:27 -0500
Subject: [PATCH 13/18] docs: Note Swift and Android test commands

---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3bcdc363..214aaaf9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,7 +20,7 @@ Whether you're looking to write code, improve documentation, or help triage issu
 ## Guidelines
 
 -   Run `make format` and `make lint-js` before submitting changes
--   Ensure tests pass with `make test-js`
+-   Ensure tests pass with `make test-js`, `make test-swift-package`, and `make test-android`
 -   Follow the existing code style and patterns
 
 ## Releases

From 5a331d9204c9fe343ecc2c466605a1380ba04931 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:28:30 -0500
Subject: [PATCH 14/18] docs: Clarify development mode

---
 docs/code/development-tools.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/code/development-tools.md b/docs/code/development-tools.md
index 5297f349..1be71604 100644
--- a/docs/code/development-tools.md
+++ b/docs/code/development-tools.md
@@ -7,7 +7,7 @@ This guide covers debugging tools and development features available in Gutenber
 Development mode (`?dev_mode` query parameter) enables debugging features and bypasses certain production behaviors to simplify development and testing:
 
 -   **Development notice is displayed** - A warning notice appears to inform developers that they're running in development mode.
--   **Mock GBKit global is provided** - If the native bridge (`window.GBKit`) is not available, a mock object is automatically provided to allow the editor to load without native integration.
+-   **Make GBKit global optional** - If the native bridge (`window.GBKit`) is not available, the editor is allowed to load without native integration, but some features may be limited.
 -   **React Dev Tools integration** - The editor connects to the React Dev Tools standalone server for component inspection and debugging. See the React Dev Tools section below for setup instructions.
 
 Add the `?dev_mode` query parameter to the editor URL:

From 6bdba2c44bebb0a9a64d2eda2116f146dd12dc92 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:29:38 -0500
Subject: [PATCH 15/18] docs: Clarify testing commands

---
 docs/code/testing.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/code/testing.md b/docs/code/testing.md
index eafff50f..77f66273 100644
--- a/docs/code/testing.md
+++ b/docs/code/testing.md
@@ -24,7 +24,7 @@ make test-js
 To run the Swift tests:
 
 ```bash
-make test-swift
+make test-swift-package
 ```
 
 ### Android Tests
@@ -43,7 +43,7 @@ Before submitting a pull request, ensure your code passes formatting and linting
 
 ### Formatting
 
-Format JavaScript code using Prettier:
+Format code using Prettier:
 
 ```bash
 make format

From b7eae1b96e0a89da3170bf165610e6f5ff414545 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Mon, 22 Dec 2025 10:39:31 -0500
Subject: [PATCH 16/18] docs: Note the WordPress #mobile Slack channel

---
 README.md           | 4 ++++
 docs/code/README.md | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/README.md b/README.md
index 1351b313..f4865a87 100644
--- a/README.md
+++ b/README.md
@@ -24,3 +24,7 @@ See the [Integration Guide](./docs/integration.md) for detailed setup instructio
 ### Contributing
 
 We welcome contributions! See the [Contributing Guide](./CONTRIBUTING.md) for setup instructions, development workflow, and how to submit changes.
+
+## Get Involved
+
+Join the conversation in the [#mobile](https://wordpress.slack.com/archives/C02RQC4LY) channel on [WordPress Slack](https://make.wordpress.org/chat/).
diff --git a/docs/code/README.md b/docs/code/README.md
index 99bdfc69..00347351 100644
--- a/docs/code/README.md
+++ b/docs/code/README.md
@@ -15,3 +15,7 @@ This guide is for developers who want to contribute code to GutenbergKit.
 -   [Plugins](./plugins.md) - Plugin loading and custom blocks
 -   [Preloading](./preloading.md) - Asset preloading
 -   [Physical Device Setup](./physical-device-setup.md) - Running on physical devices
+
+## Get Involved
+
+Have questions or want to discuss development? Join the [#mobile](https://wordpress.slack.com/archives/C02RQC4LY) channel on [WordPress Slack](https://make.wordpress.org/chat/).

From 70276a3ab40630ee4ba2afaea5d7b0a85d1493e1 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Tue, 23 Dec 2025 17:13:02 -0500
Subject: [PATCH 17/18] fix: iOS integration guides references root
 Package.swift

---
 README.md           | 2 +-
 docs/integration.md | 8 +++++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f4865a87..29beb6aa 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ The architecture consists of three main layers:
 
 To integrate GutenbergKit into your iOS or Android app, include the package as a dependency:
 
--   **iOS**: Add the Swift package from the `ios/` directory
+-   **iOS**: Add the Swift package from the repository root
 -   **Android**: Add the Kotlin library from the `android/` directory
 
 See the [Integration Guide](./docs/integration.md) for detailed setup instructions and code examples.
diff --git a/docs/integration.md b/docs/integration.md
index 20a47ab6..d936d502 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -23,7 +23,13 @@ This guide covers how to integrate GutenbergKit into your iOS or Android app.
 
 ### Adding the Package
 
-Add the GutenbergKit Swift package from the `ios/` directory to your Xcode project.
+Add GutenbergKit as a Swift Package dependency in Xcode:
+
+1. Go to **File → Add Package Dependencies...**
+2. Enter the GutenbergKit repository URL
+3. Select the `GutenbergKit` library product
+
+Note: The `Package.swift` is at the repository root, not in the `ios/` directory.
 
 ### Basic Setup
 

From c99f1be78bb2d85ae098bc7885ea90e5693bd308 Mon Sep 17 00:00:00 2001
From: David Calhoun <github@davidcalhoun.me>
Date: Tue, 23 Dec 2025 17:17:01 -0500
Subject: [PATCH 18/18] docs: Android integration guides reference Maven for
 production

---
 README.md           |  2 +-
 docs/integration.md | 28 +++++++++++++++++++++++++++-
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 29beb6aa..f56f046f 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ The architecture consists of three main layers:
 To integrate GutenbergKit into your iOS or Android app, include the package as a dependency:
 
 -   **iOS**: Add the Swift package from the repository root
--   **Android**: Add the Kotlin library from the `android/` directory
+-   **Android**: Add the Kotlin library as a Maven dependency or include the `android/Gutenberg/` module
 
 See the [Integration Guide](./docs/integration.md) for detailed setup instructions and code examples.
 
diff --git a/docs/integration.md b/docs/integration.md
index d936d502..708aca17 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -126,7 +126,33 @@ let editorViewController = EditorViewController(
 
 ### Adding the Library
 
-Add the GutenbergKit library from the `android/Gutenberg/` directory to your project.
+There are two ways to add GutenbergKit to your Android project:
+
+**Option 1: Maven dependency (recommended for production)**
+
+Add the Automattic Maven repository to your `settings.gradle.kts`:
+
+```kotlin
+dependencyResolutionManagement {
+    repositories {
+        maven {
+            url = uri("https://a8c-libs.s3.amazonaws.com/android")
+        }
+    }
+}
+```
+
+Then add the dependency to your `build.gradle.kts`:
+
+```kotlin
+dependencies {
+    implementation("org.wordpress.gutenbergkit:android:<version>")
+}
+```
+
+**Option 2: Local module (for development)**
+
+Include the `android/Gutenberg/` module directly in your project.
 
 ### Basic Setup