[DOCS] Update README for non-dev maintenance

README.md

@@ -26,7 +26,7 @@ A Streamlit app for optimising carbon removal portfolios across different method
   - [Option 2: Local](#option-2-work-locally)
   - [Quick reference](#quick-reference-where-is-each-parameter)
   - [File structure](#file-structure-what-each-file-does)
-  - [Understanding inputs_aggregated.csv](#understanding-inputs_aggregatedcsv)
+  - [Understanding inputs.csv](#understanding-inputscsv)
 - [Maintenance cases](#maintenance-cases)
   - [Before you start](#before-you-start)
   - [Case 1 - Modify existing coefficient values](#case-1--modify-existing-coefficient-values)
@@ -36,7 +36,7 @@ A Streamlit app for optimising carbon removal portfolios across different method
   - [Case 5 - Add a new resource group](#case-5--add-a-new-resource-group-new-category)
   - [Case 6 - Change whether a resource is optional](#case-6--change-whether-a-resource-is-optional-secondary-for-a-method)
   - [Case 7 - Rename a method or resource](#case-7--rename-a-method-or-resource)
-  - [Case 8 - Edit tooltip texts](#case-8--edit-tooltip-texts-hover-descriptions)
+  - [Case 8 - Edit tooltip, method note, and section intro texts](#case-8--edit-tooltip-method-note-and-section-intro-texts)
   - [Case 9 - Remove a method or resource](#case-9--remove-a-method-or-resource)
   - [Case 10 - Change the display order](#case-10--change-the-display-order-of-methods-or-resources)
   - [After any change - checklist](#after-any-change--checklist)
@@ -65,7 +65,7 @@ This guide is for Carbon Gap staff who need to update the tool's data: **no codi
 All the data the tool uses (CDR methods, resources, coefficients) comes from a single file:
 
 ```
-data/inputs_aggregated.csv
+data/inputs.csv
 ```
 
 Every time the app starts, it computes a fingerprint (hash) of the CSV and compares it to the last known value. If they differ, meaning the CSV has been modified, it automatically regenerates all the data files used by the application before loading. You do not need to run anything manually.
@@ -96,7 +96,7 @@ In the **Resource inputs** tab, users can add custom resource batches — named
 
 For example, a user might add a batch called "Basalt A" linked to the reference group "Basalt mineral" and assign it to the Enhanced weathering method. The optimiser will then use the batch's custom coefficients instead of the standard reference values for that method.
 
-Custom batches are stored in the session and saved when exporting a scenario. They do **not** require any change to `inputs_aggregated.csv`.
+Custom batches are stored in the session and saved when exporting a scenario. They do **not** require any change to `inputs.csv`.
 
 ---
 
@@ -121,21 +121,21 @@ This is the simplest option for non-coders with admin access to the Hugging Face
 **Steps:**
 
 1. Go to the Hugging Face **Space** (Carbon Dioxide Removal Toolkit) → click the **Files** tab
-2. Open `data/inputs_aggregated.csv` and click **Edit** (pencil icon)
+2. Open `data/inputs.csv` and click **Edit** (pencil icon)
    *OR*
-   Upload a new version of the file: click **Delete** `data/inputs_aggregated.csv`, then go to **data** folder → click **+ Contribute** → Upload Files
-4. Commit the change directly on Hugging Face (checkbox *Commit directly to the main branch*): the Space will restart automatically
-5. **Check the logs** to confirm the update ran:
+   Upload a new version of the file: click **Delete** `data/inputs.csv`, then go to **data** folder → click **+ Contribute** → Upload Files
+3. Commit the change directly on Hugging Face (checkbox *Commit directly to the main branch*): the Space will restart automatically
+4. **Check the logs** to confirm the update ran:
    - In the Space, click: **Logs** (The button at the very top, next to *Running*)
    - You should see:
      ```
-     inputs_aggregated.csv has changed - running data/update.py ...
+     inputs.csv has changed - running data/update.py ...
      [... update details ...]
      Data files updated successfully.
      ```
-6. If the logs show this message, the app is running with the new data. If not, something went wrong: try option 2 or contact a developer. You may also not have waited long enough or, conversely, you may have waited too long before checking the logs: check whether the app has successfully applied your changes.
+5. If the logs show this message, the app is running with the new data. If not, something went wrong: try Option 2 or contact a developer. You may also not have waited long enough or, conversely, you may have waited too long before checking the logs: check whether the app has successfully applied your changes.
 
-> **Note:** with this option, only `inputs_aggregated.csv` needs to be uploaded. The app handles the rest automatically on restart.
+> **Note:** with this option, only `inputs.csv` needs to be uploaded. The app handles the rest automatically on restart.
 
 ### Option 2: Work locally
 
@@ -143,10 +143,10 @@ Use this option when making bigger changes where you want to preview the result
 
 **Step 1: Get the project on your machine**
 
-If you do not already have git installed:
-- Mac: install it via https://git-scm.com/download/mac
-- Windows: install it via https://git-scm.com/download/win
-- 
+Before starting, make sure you have **Python** (version 3.9 or later) and **git** installed on your machine:
+- Python: https://www.python.org/downloads/ (tick *Add Python to PATH* during installation on Windows)
+- git — Mac: https://git-scm.com/download/mac — Windows: https://git-scm.com/download/win
+
 Then in a terminal, navigate to the folder where you want to put the project and run:
 ```
 git clone <repository URL>
@@ -179,7 +179,7 @@ You only need to do this once per machine. After that, just activate the environ
 
 **Step 2: Edit the CSV**
 
-Open `data/inputs_aggregated.csv` in Excel or any spreadsheet editor. Make your changes and save.
+Open `data/inputs.csv` in Excel or any spreadsheet editor. Make your changes and save.
 
 > ⚠️ **Commas in names:** if a method name, resource name, or group name contains a comma, the CSV parser will misread it. Wrap the value in double quotes in the CSV (e.g. `"Biochar, pyrolysis"`) or, preferably, avoid commas entirely and use a dash or slash instead.
 
@@ -224,32 +224,34 @@ Hugging Face will detect the push and rebuild the Space automatically.
 
 | I want to change… | File | Where exactly |
 |---|---|---|
-| A coefficient value (min / median / max) | `data/inputs_aggregated.csv` | Columns `min`, `median`, `max`: find the row by `Implementation` + `Resource` |
-| The name of a CDR method | `data/inputs_aggregated.csv` | Column `Implementation |
-| Which group a CDR method belongs to | `data/inputs_aggregated.csv` | Column `Method group` |
-| The name of a resource | `data/inputs_aggregated.csv` | Column `Resource` |
-| Which group a resource belongs to | `data/inputs_aggregated.csv` | Column `Resource group` |
-| The unit of a resource group | `data/inputs_aggregated.csv` | Column `Unit`: must be consistent across all rows for that group |
-| Whether a resource is optional for a method | `data/inputs_aggregated.csv` | Column `Is secondary`: `TRUE` = optional, `FALSE` = always active |
-| The display order of methods or resources | `data/inputs_aggregated.csv` | Row order: in the app, groups are displayed in the order their first row is encountered in the CSV; within a group, methods or resources are displayed in the order their rows appear. Move rows up/down to reorder |
+| A coefficient value (min / median / max) | `data/inputs.csv` | Columns `min`, `median`, `max`: find the row by `Implementation` + `Resource` |
+| The name of a CDR method | `data/inputs.csv` | Column `Implementation` |
+| Which group a CDR method belongs to | `data/inputs.csv` | Column `Method group` |
+| The name of a resource | `data/inputs.csv` | Column `Resource` |
+| Which group a resource belongs to | `data/inputs.csv` | Column `Resource group` |
+| The unit of a resource group | `data/inputs.csv` | Column `Unit`: must be consistent across all rows for that group |
+| Whether a resource is optional for a method | `data/inputs.csv` | Column `Is secondary`: `TRUE` = optional, `FALSE` = always active |
+| The display order of methods or resources | `data/inputs.csv` | Row order: in the app, groups are displayed in the order their first row is encountered in the CSV; within a group, methods or resources are displayed in the order their rows appear. Move rows up/down to reorder |
 | The app's UI colours (background, buttons, links) | `.streamlit/config.toml` | `primaryColor`, `backgroundColor`, `secondaryBackgroundColor`, `textColor` |
 | The chart colours (Plotly graphs) | `config/config.py` | `CRRA_COLORS` dictionary |
 | The app's UI font | `.streamlit/config.toml` | `font` - accepted values: `"sans-serif"`, `"serif"`, `"monospace"` |
 | The chart font (Plotly graphs) | `config/config.py` | `CRRA_FONT` variable |
 | The app's UI colours and font (fine-tuned overrides) | `assets/styles.css` | `:root` block at the top of the file - change the hex values next to each variable name |
-| The tooltip text on a method name | `data/tooltips.xlsx` | Sheet **Methods**: column `Tooltip` |
-| The tooltip text on a resource name | `data/tooltips.xlsx` | Sheet **Resources**: column `Tooltip` |
+| The tooltip text on a method name | `data/ui_text.xlsx` | Sheet **Methods**: column `Tooltip` |
+| The tooltip text on a resource name | `data/ui_text.xlsx` | Sheet **Resources**: column `Tooltip` |
+| The text shown in "Why is this method disabled?" for a specific method | `data/ui_text.xlsx` | Sheet **Methods**: column `Note` — supports basic HTML (see [Case 8](#case-8--edit-tooltip-method-note-and-section-intro-texts)) |
+| The "OBJECTIVE" intro paragraph at the top of a tab | `data/ui_text.xlsx` | Sheet **Section Intros**: column `Text`, row selected by `Tab` — supports basic HTML (see [Case 8](#case-8--edit-tooltip-method-note-and-section-intro-texts)) |
 | UI spacing, font sizes, button styles | `assets/styles.css` | Standard CSS: search for the element name |
 | Python library versions | `requirements.txt` | One line per library: see Library Maintenance Guide below |
 
-> After any change to `inputs_aggregated.csv`, start the app - it detects the change and updates automatically. After changes to `config/config.py`, `assets/styles.css`, or `data/tooltips.xlsx`, simply restart the app.
+> After any change to `inputs.csv`, start the app - it detects the change and updates automatically. After changes to `config/config.py`, `assets/styles.css`, or `data/ui_text.xlsx`, simply restart the app.
 
 ### File structure (what each file does)
 
 | File | What it is | Do you edit it? |
 |------|-----------|-----------------|
-| `data/inputs_aggregated.csv` | **Main data file**: all methods, resources and coefficients | ✅ Yes |
-| `data/tooltips.xlsx` | Tooltip texts shown on hover in the app | ✅ Yes |
+| `data/inputs.csv` | **Main data file**: all methods, resources and coefficients | ✅ Yes |
+| `data/ui_text.xlsx` | Tooltip texts (on hover), "why is this method disabled?" notes, and each tab's intro paragraph | ✅ Yes |
 | `data/update.py` | Orchestration script: runs both generators below and updates the hash file | ❌ No |
 | `data/generate_model_data.py` | Generates `cost_sliders.json`, `method_groups.json`, `secondary_resources.json` from the CSV | ❌ No |
 | `data/generate_resource_template.py` | Generates `resource_template.xlsx` from the CSV | ❌ No |
@@ -257,10 +259,11 @@ Hugging Face will detect the push and rebuild the Space automatically.
 | `data/method_groups.json` | Auto-generated. CDR method categories | ❌ No (auto) |
 | `data/secondary_resources.json` | Auto-generated. Optional resource assignments | ❌ No (auto) |
 | `data/resource_template.xlsx` | Auto-generated. Excel template for users | ❌ No (auto) |
+| `data/.csv_hash` | Auto-generated. Stores a fingerprint of `inputs.csv` to detect changes on restart | ❌ No (auto) |
 
 > ⚠️ **Never edit the auto-generated files directly**: your changes will be overwritten the next time `update.py` is run.
 
-### Understanding `inputs_aggregated.csv`
+### Understanding `inputs.csv`
 
 Each row represents **one resource used by one CDR method**, with the following columns:
 
@@ -284,6 +287,8 @@ Each row represents **one resource used by one CDR method**, with the following
 
 > **Naming convention — "Other" methods:** any CDR method whose name starts with `Other` receives special treatment in the optimiser. Instead of appearing as a fixed method, the LP automatically creates **one variant per custom resource batch** the user adds that is linked to that method. This is intended for generic CDR pathways where the type of resource is user-defined. If you add a method using this naming convention, make sure it is intentional.
 
+> **Resource group and OR-substitutable resources:** when a CDR method has two or more **primary** resources (`Is secondary = FALSE`) that belong to the same `Resource group`, the optimizer treats them as **interchangeable (OR)**. The method can satisfy its resource need from either one, or any mix of the two, rather than requiring all of them simultaneously. Users will see a hint like *"only one of Other land, Arable land is required"* in the "Why is this method disabled?" panel. This behaviour is automatic: it is triggered purely by two active primary resources sharing the same `Resource group` for the same method. **If you add a resource to an existing group for a method that already has a primary resource in that group, you are creating an OR relationship — make sure this is intentional.** If it is not, create a new resource group instead (see Case 5).
+
 ---
 
 ## Maintenance cases
@@ -314,14 +319,14 @@ You should see `(venv)` at the start of your terminal line.
 **Option 1 - On Hugging Face**
 
 1. In the Space, click the **Files** tab.
-2. Open `data/inputs_aggregated.csv` → click the **pencil icon** to edit inline.
+2. Open `data/inputs.csv` → click the **pencil icon** to edit inline.
 3. Find the row with the correct `Implementation` and `Resource`. Edit the `min`, `median`, and/or `max` columns.
 4. Scroll down → **Commit directly to main branch** → **Commit changes to main**.
 5. The Space restarts. Click **Logs** to confirm: `Data files updated successfully.`
 
 **Option 2 - Locally**
 
-1. Open `data/inputs_aggregated.csv` in Excel or a text editor.
+1. Open `data/inputs.csv` in Excel or a text editor.
 2. Find the row with the correct `Implementation` and `Resource`.
 3. Edit the `min`, `median`, and/or `max` columns.
 4. Save the file, then start the app to verify:
@@ -341,13 +346,13 @@ You should see `(venv)` at the start of your terminal line.
 
 **Option 1 - On Hugging Face**
 
-1. In the Space, click **Files** → open `data/inputs_aggregated.csv` → click the pencil icon.
-2. Add a new row, making sure to include all the expected columns (see [Understanding inputs_aggregated.csv](#understanding-inputs_aggregatedcsv)).
+1. In the Space, click **Files** → open `data/inputs.csv` → click the pencil icon.
+2. Add a new row, making sure to include all the expected columns (see [Understanding inputs.csv](#understanding-inputscsv)).
 3. Commit directly to main → Space restarts. Check Logs for `Data files updated successfully.`
 
 **Option 2 - Locally**
 
-1. Open `data/inputs_aggregated.csv` and add a new row (see [Understanding inputs_aggregated.csv](#understanding-inputs_aggregatedcsv)).
+1. Open `data/inputs.csv` and add a new row (see [Understanding inputs.csv](#understanding-inputscsv)).
 2. Save the file, then start the app to verify:
    ```
    streamlit run app.py
@@ -367,15 +372,15 @@ You should see `(venv)` at the start of your terminal line.
 
 **Option 1 - On Hugging Face**
 
-1. In the Space, click **Files** → open `data/inputs_aggregated.csv` → click the pencil icon.
-2. Add **one row per resource** the new method uses (see [Understanding inputs_aggregated.csv](#understanding-inputs_aggregatedcsv)). Use an existing `Method group` or create a new one.
+1. In the Space, click **Files** → open `data/inputs.csv` → click the pencil icon.
+2. Add **one row per resource** the new method uses (see [Understanding inputs.csv](#understanding-inputscsv)). Use an existing `Method group` or create a new one.
 3. Place the rows where you want the method to appear: display order follows row order in the CSV.
 4. Commit directly to main → Space restarts. Check Logs for `Data files updated successfully.`
 
 **Option 2 - Locally**
 
-1. Open `data/inputs_aggregated.csv`.
-2. Add one row per resource used by the new method. Fill in all columns (see [Understanding inputs_aggregated.csv](#understanding-inputs_aggregatedcsv)).
+1. Open `data/inputs.csv`.
+2. Add one row per resource used by the new method. Fill in all columns (see [Understanding inputs.csv](#understanding-inputscsv)).
 3. Save the file, then start the app to verify:
    ```
    streamlit run app.py
@@ -395,10 +400,12 @@ You should see `(venv)` at the start of your terminal line.
 
 > ⚠️ **"Other" resource naming:** if you name the resource starting with `Other ` (capital O + space — e.g. `Other land`, `Other water`), it will be **hidden from the standard resource display** in the app. Users won't see it as a standalone input row, but it will still be available as a reference group when they use the "Add resource" dialog. Only use this prefix if you specifically want the resource to be hidden from direct input.
 
+> ⚠️ **Adding to an existing Resource group may create an OR relationship:** if the method you are adding this resource to already has a primary resource (`Is secondary = FALSE`) in the same `Resource group`, the optimizer will treat the two resources as interchangeable. See [Understanding inputs.csv](#understanding-inputscsv) for details. If this is not the intended behavior, create a new Resource group instead (Case 5).
+
 **Option 1 - On Hugging Face**
 
 1. Decide which **Resource group** the new resource belongs to. If it belongs to an existing group, use the exact same name. If it needs its own group, see Case 5.
-2. In the Space, click **Files** → open `data/inputs_aggregated.csv` → pencil icon.
+2. In the Space, click **Files** → open `data/inputs.csv` → pencil icon.
 3. Add one row per method that uses this resource (see column descriptions in Case 2).
 4. **Check the unit:** all resources in a group must share the same unit (e.g., all `Land` resources use `Mha/MtCO2`). If the unit differs, create a new group (Case 5).
 5. Commit directly to main → Space restarts. Check Logs.
@@ -406,7 +413,7 @@ You should see `(venv)` at the start of your terminal line.
 **Option 2 - Locally**
 
 1. Decide which Resource group the new resource belongs to.
-2. Open `data/inputs_aggregated.csv` and add one row per method that uses this resource.
+2. Open `data/inputs.csv` and add one row per method that uses this resource.
 3. Verify the unit is consistent with the rest of the group.
 4. Save, then start the app to verify:
    ```
@@ -423,7 +430,7 @@ You should see `(venv)` at the start of your terminal line.
 
 ### Case 5 - Add a new resource group (new category)
 
-**When to use:** Your new resource doesn't fit any existing category.
+**When to use:** Your new resource doesn't fit any existing category. Also use this case when the new resource belongs to the same physical category as an existing one but should **not** be treated as interchangeable with it by the optimizer — keeping it in a separate group avoids the automatic OR relationship (see [Understanding inputs.csv](#understanding-inputscsv)).
 
 **Option 1 - On Hugging Face**
 
@@ -439,16 +446,18 @@ Same steps as Case 4, but write a **new group name** in the `Resource group` col
 
 **When to use:** You want to make a resource optional (user can enable/disable it) or make it always required.
 
+> ⚠️ **Changing a resource from optional to always active may create an OR relationship:** if you set `Is secondary` to `FALSE` for a resource, and the same method already has another primary resource (`Is secondary = FALSE`) in the same `Resource group`, the optimizer will treat the two as interchangeable. See [Understanding inputs.csv](#understanding-inputscsv) for details. If this is not intended, consider moving the resource to a different group (Case 5).
+
 **Option 1 - On Hugging Face**
 
-1. In the Space, click **Files** → open `data/inputs_aggregated.csv` → pencil icon.
+1. In the Space, click **Files** → open `data/inputs.csv` → pencil icon.
 2. Find the row with the correct `Implementation` and `Resource`.
 3. Change `Is secondary` to `TRUE` (optional) or `FALSE` (always active).
 4. Commit directly to main → Space restarts. Check Logs.
 
 **Option 2 - Locally**
 
-1. Open `data/inputs_aggregated.csv`.
+1. Open `data/inputs.csv`.
 2. Find the row with the correct `Implementation` and `Resource`.
 3. Change `Is secondary` to `TRUE` (optional) or `FALSE` (always active).
 4. Save, then start the app to verify:
@@ -473,16 +482,16 @@ Same steps as Case 4, but write a **new group name** in the `Resource group` col
 **Option 1 - On Hugging Face**
 
 Editing inline is not recommended for a rename because Find & Replace is not available in the browser editor. Instead:
-1. Download `data/inputs_aggregated.csv` from the Files tab.
+1. Download `data/inputs.csv` from the Files tab.
 2. Open it in Excel. Use **Find & Replace** (Ctrl+H / Cmd+H) to replace the old name with the new name in the `Implementation` / `Resource` columns and, if the group name changed, in `Method group` / `Resource group`.
-3. Also download `data/tooltips.xlsx`, update the name in the `Method` or `Resource` column of the relevant sheet, and save.
+3. Also download `data/ui_text.xlsx`, update the name in the `Method` or `Resource` column of the relevant sheet, and save.
 4. Upload both files via **Files** → `data/` folder → **+ Contribute** → **Upload Files** → Commit.
 5. Space restarts → check Logs.
 
 **Option 2 - Locally**
 
-1. Open `data/inputs_aggregated.csv`. Use **Find & Replace** (Ctrl+H / Cmd+H) to replace the old name everywhere in the file.
-2. Open `data/tooltips.xlsx` and update the name in the `Method` or `Resource` column of the relevant sheet. Save.
+1. Open `data/inputs.csv`. Use **Find & Replace** (Ctrl+H / Cmd+H) to replace the old name everywhere in the file.
+2. Open `data/ui_text.xlsx` and update the name in the `Method` or `Resource` column of the relevant sheet. Save.
 3. Start the app to verify:
    ```
    streamlit run app.py
@@ -496,34 +505,60 @@ Editing inline is not recommended for a rename because Find & Replace is not ava
 
 ---
 
-### Case 8 - Edit tooltip texts (hover descriptions)
+### Case 8 - Edit tooltip, method note, and section intro texts
+
+**When to use:** You want to add, update, or remove any of the editable text in the app: hover tooltips, the guidance note shown under "Why is this method disabled?" for a specific method, or the "OBJECTIVE" intro paragraph at the top of a tab.
+
+Everything is in the same file, `data/ui_text.xlsx`, across three sheets:
+
+| Sheet | Columns | Controls |
+|---|---|---|
+| **Resources** | `Resource`, `Tooltip` | Hover tooltip on a resource name |
+| **Methods** | `Method`, `Tooltip`, `Note` | `Tooltip` = hover tooltip on a method name. `Note` = the message shown at the top of that method's "Why is this method disabled?" panel (Method constraints tab) — e.g. explaining that Mineral OAE needs a specific mineral feedstock added as a custom resource. Leave empty for no note. |
+| **Section Intros** | `Tab`, `Text` | The "OBJECTIVE" paragraph shown at the top of a tab. One row per tab — see the `Tab` key table below. |
+
+> ℹ️ **The "Why is this method disabled?" panel shows two types of text that come from different sources.** The resource hints — e.g. *"Other land: Add as new resource in Resource inputs"* or *"only one of Other land, Arable land is required"* — are **auto-generated** from `inputs.csv` (based on which resources are missing and whether an OR relationship exists). They cannot be changed in `ui_text.xlsx`. The optional free-text `Note` from `ui_text.xlsx` appears above those hints with a lightbulb icon — that is the only part you can edit here. To change the resource hints, you need to change the resource or group structure in `inputs.csv`.
+
+> ⚠️ **Exact name match:** the name in column `Resource` or `Method` must match **exactly** the name used in `inputs.csv` (same spelling, same capitalisation). If you rename a method or resource in the CSV, remember to update the name in `ui_text.xlsx` too.
+
+> ⚠️ **`Tab` keys, not tab titles:** the `Tab` column in **Section Intros** uses the internal page name, not the label shown in the sidebar. Use exactly one of:
+> | `Tab` value | Corresponding tab in the app |
+> |---|---|
+> | `tab1_inputs` | Resource inputs |
+> | `tab2_constraints` | Method constraints |
+> | `tab3_coefficients` | Resource coefficients |
+> | `tab4_optimization` | Portfolio generation |
+> | `tab5_sensitivity` | Sensitivity analysis |
+> A row with any other value is simply ignored.
+
+> ⚠️ **These texts contain HTML, not just plain text.** `Tooltip` cells are plain text, but `Note` and `Text` (Section Intros) are rendered as HTML, so you'll see markup like `<strong>bold</strong>`, `<br>` for a line break, and `<li>...</li>` for a bullet-style line. Keep these tags when editing around them — deleting a `<` or `>` by accident will make the raw tag appear as text on the page instead of being applied as formatting. You can add more of the same tags (`<strong>`, `<br>`, `<li>`) but avoid pasting anything more advanced (scripts, styles, other tags) since it is not sanitised before display.
 
-**When to use:** You want to add, update, or remove the short description that appears when a user hovers over a resource or method name in the app.
+> ⚠️ **`tab2_constraints`'s text has a placeholder:** its `Text` cell contains `{CO2_UNIT}`, which the app replaces with the actual CO₂ unit (e.g. `MtCO₂`) when displayed. Keep the `{CO2_UNIT}` placeholder (braces included) if you want that value to appear; removing it just removes the unit from the sentence, it won't break anything.
 
-> ⚠️ The name in column `Resource` or `Method` must match **exactly** the name used in `inputs_aggregated.csv` (same spelling, same capitalisation). If you rename a method or resource in the CSV, remember to update the name in `tooltips.xlsx` too.
+> If a cell is left empty, or a sheet/row is missing entirely, that piece of text is simply skipped (no tooltip / no note / no intro paragraph) — nothing crashes.
 
 **Option 1 - On Hugging Face**
 
 The `.xlsx` file cannot be edited inline on Hugging Face. Instead:
-1. In the Files tab, open the `data/` folder → download `tooltips.xlsx`.
-2. Open it in Excel. Go to the relevant sheet (**Resources** or **Methods**).
-3. Find the row with the name you want to edit. Fill in or change the `Tooltip` column. Leave it empty to remove a tooltip.
+1. In the Files tab, open the `data/` folder → download `ui_text.xlsx`.
+2. Open it in Excel. Go to the relevant sheet (**Resources**, **Methods**, or **Section Intros**).
+3. Find the row with the name (or `Tab` key) you want to edit. Fill in or change the `Tooltip` / `Note` / `Text` column. Leave it empty to remove that text.
 4. Save the file.
 5. Back in the Files tab, go to `data/` → **+ Contribute** → **Upload Files**.
-6. Upload your edited `tooltips.xlsx` → Commit directly to main.
-7. The Space restarts. **No update script runs for tooltips** - the file is read directly by the app on each restart.
+6. Upload your edited `ui_text.xlsx` → Commit directly to main.
+7. The Space restarts. **No update script runs for this file** - it is read directly by the app on each restart.
 
 **Option 2 - Locally**
 
-1. Open `data/tooltips.xlsx` in Excel.
-2. Go to the relevant sheet (**Resources** or **Methods**).
-3. Find the row with the name you want to edit. Fill in or change the `Tooltip` column. Leave it empty to remove a tooltip.
+1. Open `data/ui_text.xlsx` in Excel.
+2. Go to the relevant sheet (**Resources**, **Methods**, or **Section Intros**).
+3. Find the row with the name (or `Tab` key) you want to edit. Fill in or change the `Tooltip` / `Note` / `Text` column. Leave it empty to remove that text.
 4. Save the file.
 5. Restart the app (`Ctrl+C` then `streamlit run app.py`). **No need to run `update.py`.**
 6. Commit and push:
    ```
-   git add data/tooltips.xlsx
-   git commit -m "Update tooltip texts"
+   git add data/ui_text.xlsx
+   git commit -m "Update tooltip / method note / section intro texts"
    git push
    ```
 
@@ -537,19 +572,19 @@ The `.xlsx` file cannot be edited inline on Hugging Face. Instead:
 
 **Option 1 - On Hugging Face**
 
-1. Download `data/inputs_aggregated.csv` from the Files tab.
+1. Download `data/inputs.csv` from the Files tab.
 2. Open it in Excel. Delete all rows where the `Implementation` column matches the method to remove, **or** all rows where the `Resource` column matches the resource to remove.
    - To remove a method: delete every row for that `Implementation` value.
    - To remove a resource from one method only: delete only the row(s) matching both the `Implementation` and `Resource`.
    - To remove a resource entirely: delete every row where the `Resource` column matches, across all methods.
-3. Also open `data/tooltips.xlsx` and delete the corresponding row in the **Methods** or **Resources** sheet if a tooltip exists for the removed item.
+3. Also open `data/ui_text.xlsx` and delete the corresponding row in the **Methods** or **Resources** sheet if a tooltip exists for the removed item.
 4. Upload both modified files via **Files** → `data/` → **+ Contribute** → **Upload Files** → Commit directly to main.
 5. Space restarts → check Logs for `Data files updated successfully.`
 
 **Option 2 - Locally**
 
-1. Open `data/inputs_aggregated.csv` and delete the relevant rows (see Option 1 above for which rows to target).
-2. Open `data/tooltips.xlsx` and delete the corresponding tooltip row if one exists. Save.
+1. Open `data/inputs.csv` and delete the relevant rows (see Option 1 above for which rows to target).
+2. Open `data/ui_text.xlsx` and delete the corresponding tooltip row if one exists. Save.
 3. Start the app to verify:
    ```
    streamlit run app.py
@@ -570,14 +605,14 @@ The `.xlsx` file cannot be edited inline on Hugging Face. Instead:
 **Option 1 - On Hugging Face**
 
 Moving rows is easier in Excel than in a browser editor:
-1. Download `data/inputs_aggregated.csv` from the Files tab.
+1. Download `data/inputs.csv` from the Files tab.
 2. Open it in Excel. Move the relevant rows up or down - the app reads the CSV from top to bottom.
 3. Upload the updated file via **Files** → `data/` → **+ Contribute** → **Upload Files** → Commit.
 4. Space restarts → check Logs for `Data files updated successfully.`
 
 **Option 2 - Locally**
 
-1. Open `data/inputs_aggregated.csv`.
+1. Open `data/inputs.csv`.
 2. Move the relevant rows up or down.
 3. Save, then start the app to verify:
    ```
@@ -594,17 +629,32 @@ Moving rows is easier in Excel than in a browser editor:
 
 ### After any change - checklist
 
-**Option 1 (Hugging Face direct):**
-- [ ] Edited and committed `inputs_aggregated.csv` on Hugging Face
+**For changes to `inputs.csv` (Cases 1–7, 9–10):**
+
+Option 1 (Hugging Face direct):
+- [ ] Edited and committed `inputs.csv` on Hugging Face
 - [ ] Checked the Space logs: confirmed `Data files updated successfully.`
 - [ ] Verified the change appears correctly in the app
 
-**Option 2 (local):**
-- [ ] Saved `inputs_aggregated.csv`
+Option 2 (local):
+- [ ] Saved `inputs.csv`
 - [ ] Started the app locally (`streamlit run app.py`): confirmed `Data files updated successfully.` in the terminal
 - [ ] Verified the change appears correctly in the app
 - [ ] Committed all modified files (CSV, JSON files, templates) and pushed
 
+**For changes to `ui_text.xlsx` (Case 8):**
+
+Option 1 (Hugging Face direct):
+- [ ] Downloaded, edited, and re-uploaded `ui_text.xlsx` on Hugging Face
+- [ ] Space has restarted (no update script runs for this file — `Data files updated successfully.` will **not** appear in the logs; this is normal)
+- [ ] Verified the updated text appears correctly in the app
+
+Option 2 (local):
+- [ ] Saved `data/ui_text.xlsx`
+- [ ] Restarted the app (`Ctrl+C` then `streamlit run app.py`) — no need to run `update.py`
+- [ ] Verified the updated text appears correctly in the app
+- [ ] Committed `data/ui_text.xlsx` and pushed
+
 ---
 
 ## Library Maintenance Guide