chore(release): v1.3.3 dev->main merge

.github/CICD.md

@@ -187,6 +187,29 @@ This ensures:
 - Each APK is built against the exact assets produced in the same run
 - Formplayer build outputs do not pollute git history
 
+### Documentation Site
+
+**Workflow**: `.github/workflows/docs.yml`
+
+Builds and publishes the Docusaurus site in [`docs/`](../docs/) to [opendataensemble.org](https://opendataensemble.org/) via GitHub Pages.
+
+#### Triggers
+
+| Event | Result |
+|-------|--------|
+| Pull request to `main` or `dev` touching `docs/**` | Validate and build only |
+| Push to `main` touching `docs/**` | Validate, build, and deploy |
+| `workflow_dispatch` | Validate and build |
+
+#### Notes
+
+- The deployed branch is main, so the published docs track the released version of ODE. Changes on dev and pull requests are validated by CI but are not deployed.
+- The site is an independent **npm** project inside the pnpm monorepo: `cache-dependency-path` points at `docs/package-lock.json`, which is force-included in the root `.gitignore` so `npm ci` is reproducible.
+- `docs/docs/` is the Docusaurus content root. URLs are unchanged from the previous standalone `OpenDataEnsemble/docs` repository — `routeBasePath` is still `/docs`.
+- `actions/upload-pages-artifact@v4` is used deliberately: v5 excludes dotfiles by default, which would drop `static/.nojekyll` and `static/CNAME` from the artifact.
+- The upload path is `docs/build` (repo-root relative). `defaults.run.working-directory` does not apply to `uses:` steps.
+- No secrets are required. The deploy job needs `contents: read`, `pages: write`, and `id-token: write`.
+
 ### SBOM (CycloneDX) on releases
 
 **Workflow**: `.github/workflows/sbom-release.yml`

.github/QUICK_REFERENCE.md

@@ -2,7 +2,7 @@
 
 Quick reference for common CI/CD operations in the Open Data Ensemble monorepo.
 
-## 🚀 Synkronus Docker Images
+## Synkronus Docker Images
 
 ### Pull Images
 
@@ -50,7 +50,7 @@ docker run -d \
 
 `dev` is not the pre-release channel. Release pointer tags move only when a GitHub Release is published; `latest-pre-release` requires the release to be marked as a pre-release.
 
-## 🔄 Triggering Builds
+## Triggering Builds
 
 ### Automatic Triggers
 
@@ -70,7 +70,7 @@ Relevant paths include `synkronus/`, `synkronus-portal/`, shared `packages/`, th
 
 Manual runs publish only an immutable `sha-{short}` tag; they do not move `latest`, `latest-pre-release`, `main`, or `dev`.
 
-## 📦 Creating Releases
+## Creating Releases
 
 ### Quick Release (Latest)
 ```bash
@@ -91,7 +91,7 @@ Creates:
 - `v1.0.0`
 - `v1.0`
 
-## 🔍 Monitoring
+## Monitoring
 
 ### View Workflow Runs
 ```
@@ -112,7 +112,7 @@ gh run list --workflow=synkronus-docker.yml
 gh run view <run-id>
 ```
 
-## 🐛 Troubleshooting
+## Troubleshooting
 
 ### Build Failed
 
@@ -144,7 +144,7 @@ echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
 docker manifest inspect ghcr.io/opendataensemble/synkronus:latest
 ```
 
-## 🔐 Authentication
+## Authentication
 
 ### GitHub CLI
 ```bash
@@ -160,7 +160,7 @@ echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
 gh auth token | docker login ghcr.io -u USERNAME --password-stdin
 ```
 
-## 📊 Image Information
+## Image Information
 
 ### View Image Details
 ```bash
@@ -180,7 +180,7 @@ docker images ghcr.io/opendataensemble/synkronus
 dive ghcr.io/opendataensemble/synkronus:latest
 ```
 
-## 🚢 Deployment
+## Deployment
 
 ### Coolify
 
@@ -216,7 +216,7 @@ spec:
         image: ghcr.io/opendataensemble/synkronus:latest
 ```
 
-## 🔄 Rollback
+## Rollback
 
 ### Quick Rollback
 ```bash
@@ -232,7 +232,7 @@ docker run -d [same options] ghcr.io/opendataensemble/synkronus:v1.0.0
 2. Select previous version
 3. Click "Redeploy"
 
-## 📝 Best Practices
+## Best Practices
 
 ### Production
 - ✅ Pin specific versions: `v1.0.0`
@@ -253,15 +253,15 @@ docker run -d [same options] ghcr.io/opendataensemble/synkronus:v1.0.0
 - ✅ Keep workflows updated
 - ✅ Document changes
 
-## 🔗 Quick Links
+## Quick Links
 
 - [Full CI/CD Documentation](CICD.md)
 - [Synkronus Docker Guide](../synkronus/DOCKER.md)
 - [Synkronus Deployment Guide](../synkronus/DEPLOYMENT.md)
 - [GitHub Actions Docs](https://docs.github.com/en/actions)
 - [GHCR Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
 
-## 💡 Tips
+## Tips
 
 ### Speed Up Local Development
 ```bash

.github/pull_request_template.md

@@ -1,75 +1,36 @@
-# Pull Request Title
+<!-- PR title must follow Conventional Commits: <type>(<scope>): <subject> -->
 
-<!-- PR Title must follow Conventional Commits format: <type>(<scope>): <subject> -->
+## What & Why
 
-## Description
-
-<!-- Provide a clear description of what changed and why -->
+Short description of what changed and why.
 
 ## Type of Change
 
-- [ ] Bug Fix
-- [ ] New Feature / Enhancement
-- [ ] Refactor / Code Cleanup
-- [ ] Documentation Update
-- [ ] Maintenance / Chore
-- [ ] Other (please specify):
-
----
-
-## Component(s) Affected
-
-- [ ] **formulus** (React Native mobile app)
-- [ ] **formulus-formplayer** (React web app)
-- [ ] **synkronus** (Go backend server)
-- [ ] **synkronus-cli** (Command-line utility)
-- [ ] **Documentation**
-- [ ] **DevOps / CI/CD**
-- [ ] **Other:** <!-- Please specify -->
-
----
+- [ ] Bug fix
+- [ ] New feature / enhancement
+- [ ] Refactor / cleanup
+- [ ] Documentation
+- [ ] Chore / other
 
-## Related Issue(s)
+## Component(s) Changed
 
-<!-- Use keywords: Closes #123, Fixes #456, Resolves #789 -->
-
-**Closes/Fixes/Resolves:** <!-- e.g., Closes #123 -->
-
----
+- [ ] formulus (React Native mobile app)
+- [ ] formulus-formplayer (form WebView UI)
+- [ ] synkronus (Go backend)
+- [ ] synkronus-cli (command-line client)
+- [ ] synkronus-portal (web admin UI)
+- [ ] desktop (Tauri app)
+- [ ] packages (tokens / components)
+- [ ] Documentation / DevOps / CI
 
 ## Testing
 
-- [ ] Unit tests added/updated
-- [ ] Integration tests added/updated
+- [ ] Added/updated tests
 - [ ] Manually tested
-- [ ] Tested on multiple platforms (if applicable)
 - [ ] Not applicable
 
----
-
-## Breaking Changes
-
-- [ ] This PR introduces breaking changes
-- [ ] This PR does NOT introduce breaking changes
-
-**If breaking changes, please describe migration steps:**
-
----
-
-## Documentation Updates
-
-- [ ] Documentation has been updated
-- [ ] Documentation update is not required
-
----
-
 ## Checklist
 
-- [ ] Code follows project style guidelines
-- [ ] All existing tests pass
-- [ ] New tests added for new functionality
-- [ ] PR title follows Conventional Commits format
-
----
-
-**Thank you for contributing to Open Data Ensemble (ODE)!**
+- [ ] Pre-flight checks for changed packages passed (lint / format / tests)
+- [ ] Breaking changes (if any) have migration steps
+- [ ] Related issue linked, e.g. `Closes #123`

.github/workflows/docs.yml

@@ -0,0 +1,102 @@
+name: Docs
+
+on:
+  pull_request:
+    branches: [main, dev]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  push:
+    branches: [main, dev]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Do not cancel an in-flight production deploy when another push lands.
+  cancel-in-progress: ${{ github.event_name != 'push' }}
+
+permissions:
+  contents: read
+
+env:
+  NODE_VERSION: '24'
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check links and doc IDs
+        run: npm run test
+
+      - name: Build site
+        env:
+          CI: true
+        run: npm run build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: validate
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read # checkout (job permissions replace the workflow defaults)
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        run: npm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        with:
+          # Action paths are relative to the repo root, not defaults.run.working-directory.
+          path: docs/build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.github/workflows/formulus-android.yml

@@ -19,7 +19,6 @@ on:
       - 'packages/tokens/**'
       - 'packages/components/**'
       - 'packages/observation-query/**'
-      - '.github/workflows/formulus-android.yml'
   release:
     types: [published]
 
@@ -83,6 +82,7 @@ jobs:
     needs: build-formplayer-assets
     permissions:
       contents: write
+      pull-requests: write
 
     steps:
       - name: Checkout repository
@@ -250,3 +250,16 @@ jobs:
             formulus/android/app/build/outputs/bundle/release/*.aab
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  prepare-next-native-build-code:
+    name: Prepare next Formulus build code
+    if: github.event_name == 'release' && needs.build-android.result == 'success'
+    needs: build-android
+    permissions:
+      contents: write
+      pull-requests: write
+    uses: ./.github/workflows/prepare-next-formulus-build-code.yml
+    with:
+      target_branch: ${{ github.event.release.target_commitish }}
+      dry_run: false
+    secrets: inherit