docs: reorganise reference section into features

Move form definition formats and session cache under features/code-based,
move form definition options under features, and restore page elements as
a top-level feature. Add lists documentation to form definition options.
Reference section now contains only the request lifecycle.

Author: alexluckett

docs/BUILDING_THE_PACKAGE.md

@@ -1,10 +1,3 @@
----
-layout: default
-title: Building the package
-render_with_liquid: false
-nav_order: 5
----
-
 # Building the package
 
 1. [Overview](#overview)

docs/contributing.md

@@ -56,3 +56,7 @@ If you would like to fix the bug yourself, contributions are accepted through pu
 ### Adding features
 
 Features should be discussed with the Defra Forms team prior to implementation. This is to prevent wasted effort if the Defra Forms team decides not to accept it, or if we suggest any significant amendments. Reach out to us on [#defra-forms-support](https://defra-digital-team.slack.com) to discuss your requirements. If accepted by the product owner, we welcome a pull request.
+
+## Building and publishing the package
+
+See the [Building the package](./BUILDING_THE_PACKAGE) guide for documentation on the build pipeline, path alias resolution, and the npm publish workflow.

docs/features/code-based/form-definition-formats.md

@@ -0,0 +1,102 @@
+# Form definition formats
+
+Form definitions are retrieved by `forms-engine-plugin` using the `formsService` plugin registration option. The plugin calls `getFormDefinition()` on every page request, which must return a JavaScript object matching the form definition schema.
+
+Two approaches are available:
+
+- **File-based loading** — store form definitions as YAML or JSON files in your repository and use the built-in `FileFormService`
+- **Custom service** — implement your own `formsService` to load definitions from an API, database, or any other source
+
+## File-based loading
+
+The built-in `FileFormService` loads form definitions from disk. YAML is recommended for forms with multi-line HTML content, as it natively supports block scalars. JSON is more portable but requires manually escaping quotes and line breaks in string values.
+
+### Registering forms
+
+```js
+import { FileFormService } from '@defra/forms-engine-plugin/file-form-service.js'
+
+const now = new Date()
+const user = { id: 'user', displayName: 'Username' }
+const author = { createdAt: now, createdBy: user, updatedAt: now, updatedBy: user }
+
+const loader = new FileFormService()
+
+await loader.addForm('src/definitions/example-form.yaml', {
+  id: '95e92559-968d-44ae-8666-2b1ad3dffd31',
+  title: 'Example form',
+  slug: 'example-form',
+  organisation: 'Defra',
+  teamName: 'Team name',
+  teamEmail: 'team@defra.gov.uk',
+  submissionGuidance: "Thanks for your submission, we'll be in touch",
+  notificationEmail: 'team@defra.gov.uk',
+  ...author,
+  live: author
+})
+
+const formsService = loader.toFormsService()
+```
+
+Pass the resulting `formsService` as a plugin registration option:
+
+```js
+await server.register({
+  plugin,
+  options: {
+    services: { formsService },
+    // ...
+  }
+})
+```
+
+Call `loader.addForm()` once per form definition file. The `slug` controls the URL path — a form with `slug: 'example-form'` is served at `/example-form/*`.
+
+### YAML vs JSON
+
+```yaml
+# example-form.yaml — YAML supports multi-line content natively
+name: "Form name"
+pages:
+  - title: "Page title"
+    components:
+      - type: "Html"
+        content: |
+          <h1 class="govuk-heading-l">Heading</h1>
+          <p class="govuk-body">Body text</p>
+```
+
+```jsonc
+// example-form.json — JSON requires escaped quotes and no newlines in strings
+{
+  "name": "Form name",
+  "pages": [
+    {
+      "title": "Page title",
+      "components": [
+        {
+          "type": "Html",
+          "content": "<h1 class=\"govuk-heading-l\">Heading</h1><p class=\"govuk-body\">Body text</p>"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Custom formsService
+
+To load form definitions from an API, database, or CMS, implement a custom `formsService` and pass it at plugin registration. The interface requires four methods:
+
+```ts
+interface FormsService {
+  getFormMetadata: (slug: string) => Promise<FormMetadata>
+  getFormMetadataById: (id: string) => Promise<FormMetadata>
+  getFormDefinition: (id: string, state: FormStatus) => Promise<FormDefinition | undefined>
+  getFormSecret: (formId: string, secretName: string) => Promise<string>
+}
+```
+
+`getFormMetadata` is called on every page request and should be fast. `getFormDefinition` is only called when the metadata signals the definition has changed, so it can do heavier lifting.
+
+See [Custom Services](./custom-services) for a full implementation guide.

docs/features/code-based/index.md

@@ -31,3 +31,15 @@ Automatically copy query string parameter values into hidden fields on first loa
 ## [Save and Exit](./code-based/save-and-exit)
 
 Show a secondary "Save and exit" button on question pages and handle the persisted session using a route handler you supply, enabling users to leave and resume their journey later.
+
+## [Template Extensions](./code-based/template-extensions)
+
+Add custom globals and filters to the Nunjucks template environment, making them available across all form page templates and LiquidJS page templates.
+
+## [Form Definition Formats](./code-based/form-definition-formats)
+
+Options for loading form definitions — file-based loading with the built-in `FileFormService`, or a custom `formsService` implementation for API and database sources.
+
+## [Session Cache](./code-based/session-cache)
+
+Configuring the server-side session store for production: named catbox cache or a custom `CacheService` subclass.