diff --git a/README.md b/README.md
index 211cf74..2945f1b 100644
--- a/README.md
+++ b/README.md
@@ -1,71 +1,75 @@
 # Google Stock Index Lookup
 
-## Description
-This Python library provides command line tools to lookup the current value of
-a stock index via a Google search and output the information as a single line.
-It leverages the Playwright library to scrape data from Google search results
-and parse the relevant information.
+Small command-line tools that query Google Search for an index and print a single summary line.
 
-## Prerequisites
+## What It Does
+- Runs a Google search for an index (currently `FTSE All Share` and `SPTMI`).
+- Parses the finance summary from the results page.
+- Prints one line in this format:
+
+```text
+<Index title>: <price> (<percent_change>%)  <timestamp>
+```
+
+Examples:
+
+```shell
+$ ./ftse_all_share
+FTSE All-Share Index: 5650.94 (0.31%)  17 Feb, 14:57 GMT
+
+$ ./s_and_p_total_market
+S&P Total Market Index (TMI): 6789.00 (-0.60%)  17 Feb, 09:57 GMT
+```
+
+## Requirements
 - Python 3
-- Playwright Python package
+- `playwright`
+- `lxml`
+- Playwright Chromium browser
 
 ## Installation
-1. Clone this repository to your local machine.
-
 ```shell
 git clone https://git.4angle.com/edward/google-stocks.git
 cd google-stocks
-```
-
-2. Install the required Python packages:
-
-```shell
-pip install playwright
+python3 -m pip install playwright lxml
+python3 -m playwright install chromium
 ```
 
 ## Usage
-
-### Lookup a Stock Index
-To lookup the current value of a stock index and display it as a single line,
-you can use the provided scripts.
-
-#### FTSE All Share Example
+Run from the repository root:
 
 ```shell
-ftse_all_share
+./ftse_all_share
+./s_and_p_total_market
 ```
 
-Sample Output:
-```
-FTSE All-Share Index: 4153.35 (0.85%)
-```
+## How It Works
+- Entrypoints:
+  - `ftse_all_share` (query: `FTSE All Share`)
+  - `s_and_p_total_market` (query: `SPTMI`)
+- Core logic: `google_stocks/__init__.py`
+  - launches headless Chromium via Playwright
+  - saves raw SERP HTML to `~/lib/google_stocks/*_serp.html`
+  - parses the `data-attrid="Price"` section into structured fields
 
-#### S&P Total Market Example
+## Local Data and Auth
+The tool uses and writes files in your home directory:
+- auth state: `~/lib/auth/google.json`
+- captured SERP HTML: `~/lib/google_stocks/`
+
+Create directories if needed:
 
 ```shell
-s_and_p_total_market
+mkdir -p ~/lib/auth ~/lib/google_stocks
 ```
 
-Sample Output:
-```
-S&P Total Market Index (TMI): 4329.32 (0.64%)
-```
-
-## Customization
-You can customize the tool by modifying the scripts in the repository. Each
-script corresponds to a specific stock index lookup.
+## Notes
+- Parsing depends on Google SERP markup, which can change.
+- If output breaks, inspect the newest saved SERP in `~/lib/google_stocks/`.
+- Values and timestamps are reported in the market context shown by Google (for this project, `gl=uk`).
 
 ## Contributing
-Feel free to contribute to this project by opening issues or submitting pull
-requests.
+Issues and PRs are welcome.
 
 ## License
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
-for details.
-
-## Author
-Edward Betts (edward@4angle.com)
-
-## Acknowledgments
-- Playwright: [https://playwright.dev/](https://playwright.dev/)
+MIT. See `LICENSE`.