(docs): Document FDE integration with RFE/AFE and pre-filled questions

README.md

@@ -2,7 +2,7 @@
 
 # OpenMRS ESM Fast Data Entry App
 
-The Fast Data Entry App is a module for the [OpenMRS](https://openmrs.org/) healthcare platform which allows for a natural workflow when entering many pre-recorded forms at a time. It is not meant for point-of-care workflows, but rather as a way to do retrospective data entry.
+The Fast Data Entry App is a module for the [OpenMRS](https://openmrs.org/) healthcare platform which allows for a natural workflow when entering many pre-recorded forms at a time. It is not meant for point-of-care workflows, but rather as a way to do retrospective data entry. For more detailed information, see the [FDE Wiki Documentation](https://openmrs.atlassian.net/wiki/spaces/docs/pages/150962486/Key+O3+Repositories#Fast-Data-Entry).
 
 ## Overview
 Currently the app consists of three main parts, a Forms Page to list available forms, Fast Data Entry which allows the rapid input of forms, and Group Sessions which enable recording information about a group session as well as individual forms for the session participants.
@@ -39,6 +39,122 @@ This app also contains a Group Builder for quickly putting together a group of p
 
 https://user-images.githubusercontent.com/5445264/190840219-ec032792-0479-4676-8312-24064edb6afc.mov
 
+### Pre-Filled Questions
+
+In many retrospective workflows, certain fields on a form may have the **same value across multiple patients** (e.g., *session date*, *facility name*, or *session type*). Rather than forcing the data clerk to re-enter these values repeatedly, the Fast Data Entry (FDE) app supports **pre-filled questions**.
+
+These are configured in the `specificQuestions` schema. The schema allows you to:
+
+* Identify **which forms** the question applies to.
+* Point to the **question ID** within the form schema.
+* Optionally define a **default answer**.
+* Optionally limit the set of **answer choices** (for coded inputs).
+
+#### Example Schema
+
+```json
+"specificQuestions": [
+  {
+    "forms": [
+      "547c0814-eb78-3280-91a8-8d7c574e0301",
+      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
+    ],
+    "questionId": "placeOfConsultation"
+  },
+  {
+    "forms": [
+      "547c0814-eb78-3280-91a8-8d7c574e0301",
+      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
+    ],
+    "questionId": "practitionerAffiliation"
+  },
+  {
+    "forms": [
+      "547c0814-eb78-3280-91a8-8d7c574e0301",
+      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
+    ],
+    "questionId": "typeOfSession",
+    "defaultAnswer": "9bc5ecea-7c82-11e9-8f9e-2a86e4085a59",
+    "answers": [
+      "9bc5ecea-7c82-11e9-8f9e-2a86e4085a59",
+      "3a826502-6d4a-4e84-82e2-13deb0a5f958"
+    ]
+  },
+  {
+    "forms": [
+      "547c0814-eb78-3280-91a8-8d7c574e0301",
+      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
+    ],
+    "questionId": "sessionFormat"
+  },
+  {
+    "forms": [
+      "547c0814-eb78-3280-91a8-8d7c574e0301",
+      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
+    ],
+    "questionId": "targetGroupProgramType"
+  }
+]
+```
+
+#### Schema Keys
+
+* **`forms`**: Array of form UUIDs. The pre-fill rule applies only to these forms.
+* **`questionId`**: The field identifier in the form schema to pre-fill. Must exist in the published form schema.
+* **`defaultAnswer`** *(optional)*: A concept UUID or value to use as the default answer.
+* **`answers`** *(optional, for coded inputs)*: Array of concept UUIDs to restrict the available answer options.
+
+#### Use Cases
+
+1. **Shared Values Across Patients**
+
+   * *Example*: *“Date of Consultation”* is the same for all 20 patients in a session. Instead of retyping it 20 times, pre-fill once.
+
+2. **Default Answers**
+
+   * *Example*: *“Type of Session”* defaults to *Counseling*. Users can override if necessary.
+
+3. **Restricting Options** (multi-select)
+
+   * *Example*: A schema defines four session formats, but only two are relevant in this workflow. The `answers` array limits options to those two.
+
+4. **Multiple Forms, One Rule**
+
+   * A single pre-fill definition can target the same field across multiple forms.
+
+#### Important Notes
+
+* Forms must be **published** before pre-filled values will display.
+* The `questionId` must **match an existing field** in the form schema.
+* Concepts used in `defaultAnswer` or `answers` must exist in the database; otherwise, the UI will show empty values
+
+## Integration with Form Engines
+
+Since all forms in OpenMRS are submitted via a form engine, **FDE** relies on one of two wrapper modules:
+
+- [Form Engine App](https://github.com/openmrs/openmrs-esm-patient-chart/tree/main/packages/esm-form-engine-app)  
+- [Form Entry App](https://github.com/openmrs/openmrs-esm-patient-chart/tree/main/packages/esm-form-entry-app)  
+
+⚠️ **Important**: The Fast Data Entry (FDE) feature is supported **only by JSON schema–based form engines** 
+(e.g., the React Form Engine or the Angular Form Engine).  
+A distribution can activate **only one wrapper module** at a time.  
+
+👉 For example, the **O3 Reference Application** uses the **React Form Engine**
+
+#### Adopting a Form Engine with FDE
+
+1. **Add the wrapper module** (`Form Engine App` or `Form Entry App`) to the frontend modules in your distribution.  
+2. **Do not add both wrappers** at the same time. They depend on the same OpenMRS extension framework resources (e.g., `extension-slots`), and will conflict.  
+3. Once the wrapper is loaded, **FDE automatically integrates** with the form engine.
+
+
+#### Why This Works
+
+Because the form engines themselves have been extended to support FDE, the FDE module remains **generic and independent**. Its flexibility comes from the **OpenMRS extension system**, particularly:
+
+- **`form-widget-slot`** → provide an entry point for rendering forms.  
+- **`ampath-form-action` event** → used by both form engines to synchronize form operations with FDE.  
+
 
 ## Running this code