chore: repo cleanup by archiving plans / reports

docs/plans/archive/docs_workflow_update.md

@@ -0,0 +1,84 @@
+# 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**:
+        - Replace hardcoded `/charon/` paths in generated HTML navigation with dynamic repository name variable.
+        - Use `${{ github.event.repository.name }}` within the workflow to construct the base path, ensuring case-sensitivity compatibility (e.g., `Charon` vs `charon`).
+
+## 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).