Update project documentation to match template.

README.md

@@ -1,80 +1,114 @@
 # @guardian/prosemirror-elements
 
-This Prosemirror plugin adds the ability to add custom 'elements' to a document.
+A [ProseMirror](https://prosemirror.net/) plugin that makes modelling arbitrary nested content simple. It allows structured, non-text content to be modelled as first-class citizens of the ProseMirror schema. This content is called 'elements'.
 
+## Contents
 
-- [@guardian/prosemirror-elements](#guardianprosemirror-elements)
-  - [Why does this exist?](#why-does-this-exist)
-  - [Setup](#setup)
-  - [Run](#run)
-  - [Test](#test)
-  - [Release](#release)
-    - [Testing locally in applications using `prosemirror-elements`](#testing-locally-in-applications-using-prosemirror-elements)
-  - [Adding a new element using prosemirror-elements](#adding-a-new-element-using-prosemirror-elements)
-  - [How prosemirror-elements works](#how-prosemirror-elements-works)
-  - [Troubleshooting when developing this library](#troubleshooting-when-developing-this-library)
-    - [Problems with `yarn link`](#problems-with-yarn-link)
+- [Introduction](#1-introduction)
+- [Getting Started](#2-getting-started)
+- [How It Works](#3-how-it-works)
+- [Useful Links](#4-useful-links)
+- [Terminology](#5-terminology)
 
+## 1. Introduction
 
-## Why does this exist?
+Modelling non-text content in ProseMirror can be tricky. prosemirror-elements provides an abstraction that makes it easy to write custom elements that:
 
-Modelling non-text content in Prosemirror can be tricky. `prosemirror-elements` provides an abstraction that makes it easy to write custom elements that:
+- Contain user-defined fields that model many different kinds of content, including rich text, plain text, dropdowns, checkboxes, repeating groups, and arbitrary custom data.
+- Are first-class citizens of the ProseMirror schema — nested rich text fields participate fully in collaborative editing, selections, decorations, and marks.
+- Are renderer-agnostic — React bindings are provided as a default, but the core is framework-independent.
 
-- contain user-defined fields that model many different kinds of content, including rich text fields and arbitrary data
-- are first class citizens of the Prosemirror schema (for example, nested rich text fields play nicely with collaborative editing)
-- are renderer-agnostic (we use React as a default)
+![ProseMirror Elements Demo](./docs/assets/prosemirror-elements-demo.gif)
 
-## Working on composer prosemirror-elements
-A note for guardian developers - in https://github.com/guardian/flexible-content/pull/4410 a number of elements were moved from this repo into the flexible-content
-repo to improve the developer feedback loop when working on the elements. If you are making a change intended for composer then you should make the changes within the
-flexible-content repo. 
+The library is used by Guardian editorial tools to power structured content such as images, pullquotes, callouts, embeds, recipes, and more.
 
-## Setup
+> **Note for Guardian developers:** Many element definitions used in Composer have been moved into the [flexible-content](https://github.com/guardian/flexible-content) repo (see [PR #4410](https://github.com/guardian/flexible-content/pull/4410)). If you are making a change intended for Composer, make the changes there instead.
+
+## 2. Getting Started
+
+This section provides instructions for setting up and contributing to the plugin code. For integrating it into consuming code, see the [Quick-Start Guide](./docs/quick-start.md).
+
+### Setup
 
 1. Ensure you have `dev-nginx` and `yarn` installed on your local machine.
 2. Run the setup script: `./script/setup.sh`
 
-## Run
+### Running locally
 
 1. Ensure nginx is running.
 2. `yarn start` builds the project locally, spins up a webserver on https://prosemirror-elements.local.dev-gutools.co.uk, and watches for file changes.
 
-## Test
+### Testing
 
 - Run the unit tests via Jest with `yarn test:unit`.
 - Run the integration tests via Cypress with `yarn test:integration`.
   - You'll need to be running the application via `yarn start` simultaneously for the tests to work – make sure the server is responding on http://localhost:7890 before running the tests.
   - For reasons we're not yet able to determine, Cypress won't run your tests immediately when you select them in the GUI. Hit the 'refresh' button and they should run normally.
 
-## Release
+### Releasing
+
+This repository uses [changesets](https://github.com/changesets/changesets) for version management.
+
+1. Run `yarn changeset add` and follow the prompts to create a changeset file.
+2. Commit the changeset file with your PR.
+3. When merged, Changesets will open a release PR. Approve and merge it to publish to npm.
+
+### Testing locally in consuming applications
+
+We recommend [yalc](https://github.com/wclr/yalc) for testing local changes:
 
-This repository uses [changesets](https://github.com/changesets/changesets) for version management
+1. Install yalc globally: `npm i yalc -g` or `yarn global add yalc`.
+2. Build and push to yalc: `yarn yalc`
+3. In the consuming project: `yalc add @guardian/prosemirror-elements`
 
-To release a new version with your changes, run `yarn changeset add` and follow the prompts. This will create a new changeset file in the `.changeset` directory. Commit this file with your PR.
+Re-run `yarn yalc` in this repo after each local change.
 
-When your PR is merged, Changesets will create a PR to release the new version. Please feel free to approve and release a changesets PR that has been created as a result of your work.
+> **Why not `yarn link`?** ProseMirror and its dependencies sometimes use `instanceof` checks. `yarn link` can cause duplicate dependency copies, breaking these checks. See the [Troubleshooting](#troubleshooting) section for a known workaround.
 
-### Testing locally in applications using `prosemirror-elements`
+### Adding a new element
 
-We've found yalc useful in testing local changes to prosemirror-elements in applications that use it.
+See the [Quick-Start Guide](docs/quick-start.md) for a step-by-step walkthrough of creating an element with fields and a React UI.
 
-Setup:
+## 3. How It Works
 
-1. Install `yalc` globally with `npm i yalc -g` or `yarn global add yalc`.
-2. Run `yarn yalc` in your local project from your current branch, to build the project and push changes to yalc.
-3. Run `yalc add @guardian/prosemirror-elements` within the project consuming prosemirror-elements locally.
+### Overview
 
-Note: any changes you make to your local prosemirror-elements branch must be republished (step 3). Don't forget to run `yarn yalc` again!
+For an explanation of the plugin's core functionality, see [How prosemirror-elements works](docs/how-it-works.md).
 
-## Adding a new element using prosemirror-elements
+### Core technologies
 
-[Quick-Start Guide](https://github.com/guardian/prosemirror-elements/blob/main/docs/quick-start.md)
+- **[ProseMirror](https://prosemirror.net/)** — the underlying rich-text editor framework.
+- **TypeScript** — the project is written entirely in TypeScript.
 
-## How prosemirror-elements works
+### Architecture
 
-[How prosemirror-elements works](https://github.com/guardian/prosemirror-elements/blob/main/docs/how-it-works.md)
+The project is structured into three main areas:
 
-## Troubleshooting when developing this library
+- **`src/plugin/`** — The core ProseMirror plugin: field definitions, node spec generation, field views, validation helpers, and the plugin itself.
+- **`src/renderers/react/`** — React bindings — `createReactElementSpec`, field components, stores, and wrapper controls.
+- **`src/elements/`** — Built-in element definitions (e.g. image, pullquote, callout, embed, tweet, table, recipe, code, etc.). These are included for reference and no longer used in production.
+
+## 4. Useful Links
+
+- [Quick-Start Guide](docs/quick-start.md) — creating your first element
+- [How prosemirror-elements works](docs/how-it-works.md) — detailed technical walkthrough
+- [Vision](docs/vision.md) — project goals and design philosophy
+- [ADRs](docs/decision-records/) – records of significant decisions made during project development
+- [ProseMirror documentation](https://prosemirror.net/docs/) 
+
+## 5. Terminology
+
+- **Element** — A structured, non-text content block within a ProseMirror document (e.g. an image, pullquote, or embed). Composed of one or more Fields.
+- **Field** — A single data unit within an Element. Field types include text, rich text, custom, dropdown, checkbox, repeater, and nested element.
+- **Field View** — The ProseMirror view-layer representation of a Field — manages how a field is rendered and how user input is captured.
+- **NodeSpec** — A ProseMirror schema definition for a node type. `prosemirror-elements` generates NodeSpecs from element and field definitions. [ProseMirror documentation](https://prosemirror.net/docs/ref/#model.NodeSpec)
+- **Content Expression** — A ProseMirror string that defines what child nodes a node may contain (e.g. `"block+"`, `"text*"`). [ProseMirror documentation](https://prosemirror.net/docs/guide/#schema.content_expressions).
+- **Repeater Field** — A field type that allows zero or more repeated groups of child fields (e.g. a list of books, each with title and ISBN).
+- **Custom Field** — A field that stores arbitrary data as ProseMirror node attributes rather than document content. Updates are always last-write-wins.
+- **Element Spec** — The combination of a field description object and a renderer component that together define an element.
+- **Data Transformer** — A function that converts between an element's external data representation (plain JS object) and its internal ProseMirror node representation.
+
+## Troubleshooting
 
 ### Problems with `yarn link`
 
@@ -104,3 +138,4 @@ const mySchema = new Schema({
   marks,
 });
 ```
+