diff --git a/README.md b/README.md
index f4b36f33..89e17c6e 100644
--- a/README.md
+++ b/README.md
@@ -1,140 +1,44 @@
# NHS Notify Web CMS Repository
-[](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml)
-[](https://sonarcloud.io/summary/new_code?id=repository-template)
+[](https://github.com/NHSDigital/nhs-notify-web-cms/actions/workflows/cicd-1-pull-request.yaml)
+[](https://sonarcloud.io/summary/new_code?id=NHSDigital_nhs-notify-web-cms)
## About this project
-- This site includes the content for the public NHS Notify web site
+- This site includes the content for the public [N]HS Notify web site](https://notify.nhs.uk/)
- It uses Jekyll to generate static web HTML files from markdown content
-- the source code for the web site is in /docs folder
-- page content is inside the `/docs/pages` folder
-- page css is inside `/docs/_sass` folder
-
-## Getting Started - First time setup
-
-This is only needed once.
-
-To get started, please create a new GitHub workspace from the main branch.
-
-This will setup a development environment for you to edit the web site in. The first time this runs, it will take approximately 10 minutes. You do not need to install ANY tools on your local computer.
+- The source code for the web site is in `/docs` directory
+- Page content is inside the `/docs/pages` directory
+- Page CSS is inside `/docs/_sass` directory
+- The webpage is published to GitHub Pages using [this GitHub Actions workflow](.github/workflows/jekyll-gh-pages.yml)
### Pre-requisites
- A GitHub account
-- For submitting changes, code must be signed.
-- To sign code using GitHub code spaces, please configure GPG signing for the repository, from your Settings page.
-
-### 1. From a web browser, visit the Web CMS GitHub Repository page
-
-[https://github.com/NHSDigital/nhs-notify-web-cms](https://github.com/NHSDigital/nhs-notify-web-cms)
-
-### 2. Click Code
-
-Click the green `<> Code` button.
-
-
-
-### 3. Create Codespace on main
-
-Click create code space on main
-
-
-
-### 4. Wait
-
-- a new browser tab should open
-- you will need to wait around 5 - 10 minutes
-
-When it first starts it will look something like this. At it will say opening remote at the bottom left.
-
-
-
-### 5. Launch workspace
-
-You will see a box pop up bottom right notifying you there is a workspace file.
-
-- click the Green button to `Open Workspace`
-
-
-
-### 6 . Open parent git repository
-
-Another box will pop up saying a parent git repository has been found. Click the Green `Yes` button to open it.
-
-
-
-An option should appear at the top of the screen, select the `nhs-notify-web-cms` repository.
-
-
-
-### 5. Test it works
-
-You should be able to run a live version of your changes before you submit them (via a Pull request) for updating the live content.
-
-To do this, click the Run and Debug button, and then click the "Play" icon. Alternatively you can press F5 (warning, if you are not "clicked" in the window, it will refresh your page instead of launching the site).
-
-- click the run and debug button:
-
-
-
-- click the green "Play" button to the left of where it says `Attach (NHS Notify`
-
-
-
-- after a few seconds, you should see moving text at the bottom of the screen and it say `server running`
-
-
-
-- a box should appear bottom right saying your application is running. Click the green `Open in browser button`
-
-
-
-- a new browser tab will open (with a random address), this is live updating as you change the content of the site.
-
-
-
-### 6. Make a preview change
-
-- In the previous browser tab, click on the file `Explorer` button to show the file list.
-
-
-
-- Click on the `pages` folder, and then `index.md`. This will open the content of the home page.
-
-
-
-- you can now edit this page. To see a basic preview side by side, click the markdown preview button
-
-
-
-- this will open a preview to the right
-
-
-
-- If you now edit some text in the left, it will update in the basic preview on the right in real time. If you click `File` - `Save` (or `Ctrl-S`) this will save the file.
-
-- Saving the file will update the Full preview site in the other browser tab.
-
-- Open the other tab, and Press `F5` to refresh the page.
+- For submitting changes; [**code must be signed** with a GPG key](setup/gpg.md) linked to your GitHub account.
-### 7. Making a change permanent and live
+#### Setup guides
-You must:
+- [GPG setup for Codespaces](setup/gpg.md)
+- [First-time Codespaces setup](setup/codespaces.md)
+- [GitHub Copilot quick start](setup/copilot.md)
+- [FAQ](setup/faq.md)
-- create a new branch in your workspace
-- commit the changes to your new branch
-- push (publish) the new branch to your remote
-- create a Pull Request for requesting that your remote branch is merged into main
-- await approval
+### Making a changes checklist
-## Making further changes
+- Create a new branch in your workspace
+- Commit the changes to your new branch
+- Push (publish) the new branch to your remote
+- Create a Pull Request for requesting that your remote branch is merged into main
+- Seek and await approvals
+- Do not merge changes if all checks or are not passing.
+ 
-### Open existing CodeSpaces
+### Open existing Codespaces
-- You can reuse existing CodeSpaces that have been setup.
-- Visit [https://github.com/codespaces](https://github.com/codespaces) to see a list of code spaces
-- Active code spaces are charged. Everyone gets 150 hours free per month.
+- You can reuse existing Codespaces that have been setup.
+- Visit [https://github.com/codespaces](https://github.com/codespaces) to see a list of Codespaces
+- Active Codespaces are charged. Everyone gets 150 hours free per month.
- Click on the `three dots` and then click `stop codespace` to change it to inactive
-- A stopped code space does not loose data
-- You can delete a CodeSpace, but this will loose any data that you have not pushed (published) to a remote git branch.
+- A stopped code space does **not** loose data
+- You can delete a Codespace, but this **will** loose any data that you have not pushed (published) to a remote git branch.
diff --git a/assets/img/FAQ-bug-ticket.png b/assets/img/FAQ-bug-ticket.png
new file mode 100644
index 00000000..8e3e5402
Binary files /dev/null and b/assets/img/FAQ-bug-ticket.png differ
diff --git a/assets/img/FAQ-git-scan-secrets-fail.png b/assets/img/FAQ-git-scan-secrets-fail.png
new file mode 100644
index 00000000..4d44e615
Binary files /dev/null and b/assets/img/FAQ-git-scan-secrets-fail.png differ
diff --git a/assets/img/FAQ-git-scan-secrets-fail2.png b/assets/img/FAQ-git-scan-secrets-fail2.png
new file mode 100644
index 00000000..0b2219bf
Binary files /dev/null and b/assets/img/FAQ-git-scan-secrets-fail2.png differ
diff --git a/assets/img/FAQ-git-scan-secrets-pass.png b/assets/img/FAQ-git-scan-secrets-pass.png
new file mode 100644
index 00000000..b76e311c
Binary files /dev/null and b/assets/img/FAQ-git-scan-secrets-pass.png differ
diff --git a/assets/img/FAQ-task-ticket.png b/assets/img/FAQ-task-ticket.png
new file mode 100644
index 00000000..e9cbce1d
Binary files /dev/null and b/assets/img/FAQ-task-ticket.png differ
diff --git a/assets/img/README-pr-review.png b/assets/img/README-pr-review.png
new file mode 100644
index 00000000..6d300d8d
Binary files /dev/null and b/assets/img/README-pr-review.png differ
diff --git a/assets/img/copilot-howto.png b/assets/img/copilot-howto.png
new file mode 100644
index 00000000..71153367
Binary files /dev/null and b/assets/img/copilot-howto.png differ
diff --git a/scripts/config/pre-commit.yaml b/scripts/config/pre-commit.yaml
index 432760e5..b0fc3622 100644
--- a/scripts/config/pre-commit.yaml
+++ b/scripts/config/pre-commit.yaml
@@ -1,6 +1,6 @@
repos:
- repo: https://github.com/NHSDigital/nhs-notify-shared-modules
- rev: 3.0.9
+ rev: 3.1.2
hooks:
- id: scan-secrets
args: [check=staged-changes]
diff --git a/scripts/config/sonar-scanner.properties b/scripts/config/sonar-scanner.properties
index 147891dc..ee1e849c 100644
--- a/scripts/config/sonar-scanner.properties
+++ b/scripts/config/sonar-scanner.properties
@@ -4,6 +4,8 @@ sonar.host.url=https://sonarcloud.io
sonar.qualitygate.wait=true
sonar.sourceEncoding=UTF-8
sonar.sources=.
+sonar.coverage.exclusions=**/*
+sonar.cpd.exclusions=**/*
#sonar.python.coverage.reportPaths=.coverage/coverage.xml
#sonar.[javascript|typescript].lcov.reportPaths=.coverage/lcov.info
diff --git a/scripts/config/vale/styles/config/vocabularies/words/accept.txt b/scripts/config/vale/styles/config/vocabularies/words/accept.txt
index 51dc5eb1..5502fb06 100644
--- a/scripts/config/vale/styles/config/vocabularies/words/accept.txt
+++ b/scripts/config/vale/styles/config/vocabularies/words/accept.txt
@@ -2,21 +2,26 @@
[cC]yber
[iI]nset
[Uu][Rr][Ll]
+ad-hoc
APIM
Bitwarden
bot
bundler
Burkina
clientRef
+Codespace
+Codespaces
Cohorting
ctrl
Dependabot
endfor
+Fireship
fullName
Futuna
Gitleaks
Grype
idempotence
+J[Ii][Rr][Aa]
Maarten
Marino
namePrefix
@@ -33,6 +38,7 @@ Podman
precompiled
Python
realtime
+rebasing
Rica
rollout
Sao
@@ -49,4 +55,5 @@ Trufflehog
unnotified
urlset
validation_failed
+VSCode
Wayfinder
diff --git a/setup/codespaces.md b/setup/codespaces.md
new file mode 100644
index 00000000..ac0e0c3e
--- /dev/null
+++ b/setup/codespaces.md
@@ -0,0 +1,105 @@
+# First-Time Codespaces Setup
+
+Use this guide for first-time setup in GitHub Codespaces.
+
+## 1. From a web browser, visit the Web CMS GitHub Repository page
+
+[https://github.com/NHSDigital/nhs-notify-web-cms](https://github.com/NHSDigital/nhs-notify-web-cms)
+
+## 2. Click Code
+
+Click the green `<> Code` button.
+
+
+
+## 3. Create Codespace on main
+
+Click create code space on main
+
+
+
+## 4. Wait
+
+- a new browser tab should open
+- you will need to wait around 5 - 10 minutes
+
+When it first starts it will look something like this. At it will say opening remote at the bottom left.
+
+
+
+## 5. Launch workspace
+
+You will see a box pop up bottom right notifying you there is a workspace file.
+
+- click the Green button to `Open Workspace`
+
+
+
+## 6. Open parent git repository
+
+Another box will pop up saying a parent git repository has been found. Click the Green `Yes` button to open it.
+
+
+
+An option should appear at the top of the screen, select the `nhs-notify-web-cms` repository.
+
+
+
+## Confirm it works
+
+You should be able to run a live version of your changes before you submit them (via a Pull request) for updating the live content.
+
+To do this, click the Run and Debug button, and then click the "Play" icon. Alternatively you can press F5 (warning, if you are not "clicked" in the window, it will refresh your page instead of launching the site).
+
+- click the run and debug button:
+
+
+
+- click the green "Play" button to the left of where it says `Attach (NHS Notify`
+
+
+
+- after a few seconds, you should see moving text at the bottom of the screen and it say `server running`
+
+
+
+- a box should appear bottom right saying your application is running. Click the green `Open in browser button`
+
+
+
+- a new browser tab will open (with a random address), this is live updating as you change the content of the site.
+
+
+
+## Make a preview change
+
+- In the previous browser tab, click on the file `Explorer` button to show the file list.
+
+
+
+- Click on the `pages` folder, and then `index.md`. This will open the content of the home page.
+
+
+
+- you can now edit this page. To see a basic preview side by side, click the markdown preview button
+
+
+
+- this will open a preview to the right
+
+
+
+- If you now edit some text in the left, it will update in the basic preview on the right in real time. If you click `File` - `Save` (or `Ctrl-S`) this will save the file.
+
+- Saving the file will update the Full preview site in the other browser tab.
+
+- Open the other tab, and Press `F5` to refresh the page.
+
+## Open existing Codespaces
+
+- You can reuse existing Codespaces that have been setup.
+- Visit [https://github.com/codespaces](https://github.com/codespaces) to see a list of Codespaces
+- Active Codespaces are charged. Everyone gets 150 hours free per month.
+- Click on the `three dots` and then click `stop codespace` to change it to inactive
+- A stopped code space does **not** loose data
+- You can delete a Codespace, but this **will** loose any data that you have not pushed (published) to a remote git branch.
diff --git a/setup/copilot.md b/setup/copilot.md
new file mode 100644
index 00000000..ea779a90
--- /dev/null
+++ b/setup/copilot.md
@@ -0,0 +1,11 @@
+# GitHub Copilot Quick Start
+
+GitHub Copilot is available inside your Codespace and can help you draft, edit, and improve content faster.
+
+
+## Recommended guidance
+
+For team guidance on safe and effective AI use, read:
+
+- [NHS Engineering AI Coding Assistant User Guide](https://nhs.sharepoint.com/sites/X26_EngineeringCOE/SitePages/AI-Coding-Assistants---User-Guide.aspx?web=1&isSPOFile=1&ovuser=37c354b2-85b0-47f5-b222-07b48d774ee3%2Caiden.vaines2%40nhs.net&OR=Teams-HL&CT=1777458253077&clickparams=eyJBcHBOYW1lIjoiVGVhbXMtRGVza3RvcCIsIkFwcFZlcnNpb24iOiI1MC8yNjA0MDQwMTcxOCIsIkhhc0ZlZGVyYXRlZFVzZXIiOmZhbHNlfQ%3D%3D&linkOpenTime=1777458253084)
+- [Making the best use of AI](https://nhsd-confluence.digital.nhs.uk/spaces/RIS/pages/1336633374/Team+SKYNET+Making+the+best+use+of+AI)
diff --git a/setup/faq.md b/setup/faq.md
new file mode 100644
index 00000000..29f1f774
--- /dev/null
+++ b/setup/faq.md
@@ -0,0 +1,145 @@
+# FAQ
+
+## I've not used git or VSCode (Codespaces) before
+
+- You could start at for a brief 4 minute crash course in Git.
+- There is a great overview of what Codespaces is here .
+- Fireship has a 100 seconds of VSCode video which shows the key features.
+
+## Something is not working. What should I try first?
+
+Turn it off and on again - restart your Codespace first. This fixes most issues, including GPG signing, stale environment variables, and preview problems.
+
+1. Visit [https://github.com/codespaces](https://github.com/codespaces)
+2. Find your Codespace in the list
+3. Click the three dots menu on the right
+4. Select **Stop Codespace**
+5. Reopen the Codespace
+
+## When I try to commit my changes it says "Git: Scan secrets…" and fails?
+
+This repository has 'pre-commit hooks' that run a series of checks before every commit. When VSCode runs these hooks and one fails, the output is heavily truncated and can look misleading, for example:
+
+
+
+Despite saying "Passed", this message is incomplete. Click **Show Command Output** to see the full results and identify which check actually failed.
+
+
+
+In the example above, the failure is "Check markdown format" flagging incorrect heading levels in a file.
+
+Fix the issue reported, save and stage the file, and try committing again.
+
+### Running the checks manually
+
+You can run the pre-commit checks at any time from the terminal at the repository root:
+
+```bash
+make githooks-run
+```
+
+
+
+## How do I check whether GPG commit signing is working?
+
+Run these two commands in the Codespace terminal:
+
+```bash
+git config --list --show-origin | grep -E 'commit.gpgsign|gpg.program|user.signingkey|user.name|user.email|credential.helper'
+
+git config --show-origin --get commit.gpgsign
+```
+
+The second command should return `file:.git/config true`.
+
+If it returns `false` or nothing:
+
+- Complete all steps in [GPG setup](gpg.md)
+- Confirm GitHub **Settings > Codespaces > GPG verification** is set to **All repositories**
+- Restart your Codespace and re-check
+
+## My commit is being rejected because it is not signed
+
+This usually means GPG verification was not active when the Codespace started. Restart the Codespace and try committing again.
+
+If you've already pushed the commit to remote, you'll need to re-sign that commit. Use this flow in your Codespace terminal:
+
+```bash
+git rebase -i HEAD~
+```
+
+Replace `` with how many commits back you need to go (for example, use `1` to re-sign the last commit).
+
+In the editor that opens:
+
+1. Change `pick` to `reword` for the commit(s) you need to re-sign
+2. Save and close the editor
+3. Edit the commit message (or just save if you don't need to change it)
+4. When rebasing is complete, force push your changes:
+
+```bash
+git push --force-with-lease
+```
+
+This re-signs the commit and updates the remote branch. The `--force-with-lease` flag is safer than `--force` as it prevents overwriting others' work.
+
+## Where can I get help with using AI or GitHub Copilot?
+
+See [Copilot quick start](copilot.md) and the linked Team AI guidance.
+
+## How do I bring my branch up to date with work already merged into main?
+
+Use this flow in your Codespace terminal:
+
+```bash
+git checkout main
+git pull
+git checkout your-branch-name
+git merge main
+```
+
+If there are no conflicts, complete the merge commit and continue your work.
+
+If there are conflicts, resolve them in VS Code:
+
+1. Open Source Control (left sidebar)
+2. Open each conflicted file listed under merge changes
+3. Use the buttons in the editor such as **Accept Current**, **Accept Incoming**, or **Accept Both**
+4. Review the file and make any final manual edits
+5. Save the file
+6. Stage the resolved files
+
+Then commit your resolution:
+
+```bash
+git commit
+```
+
+If you are stuck at any point, ask the team for help rather than guessing a conflict resolution.
+
+## Where should I ask for ad-hoc guidance, support, or direction?
+
+Use this Teams chat for ad-hoc guidance, support, and direction:
+
+- [Team support chat](https://teams.microsoft.com/l/chat/19:b837810869a04ba195f98024229f874f@thread.v2/conversations?context=%7B%22contextType%22%3A%22chat%22%7D)
+
+## How do I create a Jira bug ticket for issues I need support on?
+
+Use the Jira project shortcut and include enough detail so someone else can reproduce and fix the issue.
+
+
+
+Please include the following:
+
+1. What is not working
+2. What it should be doing instead
+3. Exact steps to reproduce the problem - clear reproduction steps and branch details make triage much faster.
+4. What you expected to happen
+5. What actually happened
+6. Your working branch name
+
+## How do I create a Jira ticket for features, changes, or new functionality?
+
+For any new features, changes, or functionality you're developing, raise a Jira task for prioritisation in a development cell.
+
+
diff --git a/setup/gpg.md b/setup/gpg.md
new file mode 100644
index 00000000..290fe4e6
--- /dev/null
+++ b/setup/gpg.md
@@ -0,0 +1,80 @@
+# GPG Setup for GitHub Codespaces
+
+GPG signing proves that commits are genuinely from you. You only need to do this once.
+
+## Step 1: Generate a GPG key inside your Codespace terminal
+
+Open the terminal in your Codespace and run:
+
+```bash
+gpg --full-generate-key
+```
+
+Choose these options:
+
+- `RSA and RSA` (default)
+- Key size: `4096`
+- Expiry: `0` (does not expire), or choose a duration you prefer
+- Enter your name and the email address linked to your GitHub account
+- Set a passphrase (or leave blank for no passphrase)
+
+Then find the key ID you just created:
+
+```bash
+gpg --list-secret-keys --keyid-format=long
+```
+
+The key ID is the long string after `rsa4096/` on the `sec` line, for example `3AA5C34371567BD2`.
+
+Export your public key (replace `YOUR_KEY_ID`):
+
+```bash
+gpg --armor --export YOUR_KEY_ID
+```
+
+Copy the full output, including:
+
+- `-----BEGIN PGP PUBLIC KEY BLOCK-----`
+- `-----END PGP PUBLIC KEY BLOCK-----`
+
+## Step 2: Add the key to your GitHub account
+
+1. Click your profile photo (top right of any GitHub page)
+2. Go to **Settings**
+3. In the left sidebar, click **SSH and GPG keys**
+4. Click **New GPG key**
+5. Paste the key you copied and click **Add GPG key**
+
+## Step 3: Tell Codespaces to use GPG signing for all repositories
+
+1. In GitHub, go to **Settings** then **Codespaces**
+2. Under **GPG verification**, select **All repositories**
+3. Click **Save**
+
+## Step 4: Restart your Codespace
+
+GPG settings take effect after a restart.
+
+1. Visit [https://github.com/codespaces](https://github.com/codespaces)
+2. Find your Codespace
+3. Click the three dots menu and select **Stop Codespace**
+4. Reopen the Codespace
+
+## Verify GPG is configured
+
+Run these commands in the Codespace terminal:
+
+```bash
+git config --list --show-origin | grep -E 'commit.gpgsign|gpg.program|user.signingkey|user.name|user.email|credential.helper'
+
+git config --show-origin --get commit.gpgsign
+```
+
+The second command should return `true`.
+
+- If it returns `false` or nothing, restart your Codespace and try again.
+- If it still fails, check that your GPG key is added in **Settings > SSH and GPG keys** and that Codespaces GPG verification is set to **All repositories**.
+
+## Reference
+
+- [Managing GPG verification for GitHub Codespaces](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces)