diff --git a/docs/plans/docs_workflow_update.md b/docs/plans/docs_workflow_update.md
new file mode 100644
index 00000000..450d519f
--- /dev/null
+++ b/docs/plans/docs_workflow_update.md
@@ -0,0 +1,134 @@
+# Docs Workflow Update Plan
+
+## 1. Introduction
+The current documentation workflow only validates and deploys on pushes to `main`. This leaves other branches without validation of documentation changes, potentially leading to broken docs being merged. This plan outlines the updates to ensure documentation is built/validated on all relevant branches and PRs, while deployment remains restricted to `main`.
+
+## 2. Research Findings
+- **Current File**: `.github/workflows/docs.yml`
+- **Build Method**: Uses `npm install -g marked` to convert Markdown to HTML.
+- **Deploy Method**: Uses `actions/upload-pages-artifact` and `actions/deploy-pages`.
+- **Triggers**: Currently limited to `push: branches: [main]`.
+
+## 3. Technical Specifications
+
+### Workflow Triggers (`on`)
+The workflow triggers need to be expanded to cover:
+- Pull Requests targeting `main` or `development`.
+- Pushes to `main`, `development`, `feature/**`, and `hotfix/**`.
+
+```yaml
+on:
+ push:
+ branches:
+ - main
+ - development
+ - 'feature/**'
+ - 'hotfix/**'
+ paths:
+ - 'docs/**'
+ - 'README.md'
+ - '.github/workflows/docs.yml'
+ pull_request:
+ branches:
+ - main
+ - development
+ paths:
+ - 'docs/**'
+ - 'README.md'
+ - '.github/workflows/docs.yml'
+ workflow_dispatch:
+```
+
+### Concurrency
+Update concurrency to be scoped by branch. This allows parallel builds for different feature branches.
+Use `cancel-in-progress: true` for all branches except `main` to save resources on rapid fast-forward pushes, but ensure robust deployments for `main`.
+
+```yaml
+concurrency:
+ group: "pages-${{ github.ref }}"
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+```
+
+### Job Constraints
+- **Job `build`**: Should run on all triggers. No changes needed to conditions.
+- **Job `deploy`**: Must be restricted to `main` branch pushes only.
+
+```yaml
+ deploy:
+ name: Deploy to GitHub Pages
+ if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ needs: build
+ # ... steps ...
+```
+
+## 4. Implementation Tasks
+1. **Modify `.github/workflows/docs.yml`**:
+ - Update `on` triggers.
+ - Update `concurrency` block with `group: "pages-${{ github.ref }}"` and conditional `cancel-in-progress`.
+ - Add `if` condition to `deploy` job.
+ - **Fix 404 Link Error**:
+ - Pass the repository name as an environment variable to the run step to avoid mixing GitHub Actions syntax with shell variables inside the heredoc.
+ - **Correct Heredoc Usage**: Change the heredoc delimiter from quoted (`'HEADER'`) to unquoted (`HEADER`) to allow shell variable expansion (`${REPO_NAME}`).
+ - **Code Snippet**:
+
+```yaml
+ - name: 📝 Build documentation site
+ # Pass the repository name explicitly as an env var to handle casing (e.g. 'Charon' vs 'charon')
+ env:
+ REPO_NAME: ${{ github.event.repository.name }}
+ run: |
+ # ... (previous setup) ...
+
+ # Add simple styling to all HTML files
+ for html_file in _site/*.html _site/docs/*.html; do
+ if [ -f "$html_file" ] && [ "$html_file" != "_site/index.html" ]; then
+ # Add a header with navigation to each page
+ # NOTE: using unquoted HEADER to allow expansion of $REPO_NAME
+ temp_file="${html_file}.tmp"
+ cat > "$temp_file" << HEADER
+
+
+
+
+
+ Charon - Documentation
+
+
+
+
+
+
+ HEADER
+
+ # ... (rest of the script) ...
+```
+
+## 5. Acceptance Criteria
+- [ ] Pushing to a feature branch triggers the `build` job but skips `deploy`.
+- [ ] Multiple feature branch pushes run in parallel (checked via Actions tab).
+- [ ] Rapid pushes to the same feature branch cancel previous runs.
+- [ ] Opening a PR triggers the `build` job.
+- [ ] Pushing to `main` triggers both `build` and `deploy`.
+- [ ] Pushing to `main` does not cancel in-progress runs (safe deployment).
+- [ ] Generated HTML links typically point to `/${REPO_NAME}/...` to work correctly on GitHub Pages subpaths.