Merge remote-tracking branch 'origin/develop' into AI-1580

# Conflicts:
#	CLAUDE.md
#	apps/temporal/package.json

Author: alex-struk

.claude/skills/create-pr/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: create-pr
+description: "Create a single pull request for the current branch using gh. Trigger phrases: create a PR, open a pull request, create pull request, open a PR, submit a PR. Do NOT invoke for: splitting a branch into multiple PRs (use split-branch-into-prs), committing only, or pushing without a PR."
+---
+
+# Create Pull Request
+
+Opens one PR for the current branch against `develop` (unless the user specifies another base), using the repo PR template and documentation checklist.
+
+## Always Follow
+
+- Use `gh` for all GitHub operations
+- Never update git config
+- Do not force-push to `main`/`master`; warn if the user requests it
+- Do not commit unless the user explicitly asked to commit
+- Never commit secrets (`.env`, credentials, tokens)
+- Fill the PR body from `.github/PULL_REQUEST_TEMPLATE.md` structure
+- Confirm documentation and wiki checklist items were addressed (or explicitly N/A) before opening the PR
+- When documentation or wiki updates are needed, follow the [documentation](../documentation/SKILL.md) skill first
+
+## Workflows
+
+1. **[Create PR](Workflows/create-pr.md)** — Inspect branch state, push if needed, open the PR with `gh pr create`

.claude/skills/create-pr/Workflows/create-pr.md

@@ -0,0 +1,92 @@
+# Create PR
+
+Create a single pull request for the current branch.
+
+## Prerequisites
+
+- User explicitly asked to create/open a PR
+- Branch has commits to include (or user confirmed empty-diff intent is wrong and work is committed)
+
+## Steps
+
+1. **Gather branch state in parallel:**
+
+```bash
+git status
+git diff
+git branch -vv
+git log --oneline -10
+git rev-parse --abbrev-ref HEAD
+```
+
+Also determine the base branch (default `develop` unless the user specified another) and the full commit range:
+
+```bash
+git log develop...HEAD --oneline
+git diff develop...HEAD
+```
+
+If the branch does not track a remote or is behind/ahead in a way that matters, note that before pushing.
+
+2. **Confirm documentation readiness:**
+
+- If the change affects behavior, APIs, setup, ownership, or contributor routing, ensure docs were updated per the [documentation](../../documentation/SKILL.md) skill.
+- If the change affects system boundaries, doc routing, or where contributors should edit, ensure `docs-md/wiki/` was updated or confirmed not needed.
+- If wiki files changed, run `npm run docs:wiki:check`.
+
+3. **Push the branch if needed:**
+
+```bash
+git push -u origin HEAD
+```
+
+4. **Draft the PR:**
+
+- Title format: `JIRA_BOARD-NUMBER: short title` (e.g. `AI-1296: Add repo wiki`)
+- Summary links the Jira ticket when known
+- Changes summarize **all** commits on the branch, not only the latest
+- Testing lists what was run or how to verify
+- Checklist matches `.github/PULL_REQUEST_TEMPLATE.md`
+
+5. **Create the PR:**
+
+```bash
+gh pr create --base develop --title "AI-###: Title" --body "$(cat <<'EOF'
+## Summary
+
+[AI-###](https://citz-do.atlassian.net/browse/AI-###)
+
+Brief description of why this change exists.
+
+## Changes
+
+- Bullet list of what changed
+
+## Testing
+
+- How it was tested
+
+## Checklist
+
+By submitting this pull request, I acknowledge that I have attempted to meet the following:
+
+> - a self-review of my code
+> - commented code particularly in hard-to-understand areas
+> - documentation updated where required (`docs-md/`, READMEs, and/or public `docs/` site), including the repo wiki (`docs-md/wiki/`) when boundaries, routing, or contributor guidance changed — or confirmed not needed
+> - changes tested to the best of my ability
+> - no new errors or non-functional code
+
+EOF
+)"
+```
+
+Use `--draft` only when the user asks for a draft PR.
+
+6. **Return the PR URL** to the user.
+
+## Common Pitfalls
+
+- Creating a PR without updating docs/wiki when boundaries or contributor guidance changed
+- Summarizing only the latest commit instead of the full branch diff
+- Forcing push or amending commits the user did not ask to amend
+- Pasting secrets into the PR body or logs

.claude/skills/docs-sync/CONVENTIONS.md

@@ -0,0 +1,38 @@
+# Docs Conventions
+
+## Topic taxonomy (docs-md/)
+
+| Folder | Scope |
+| --- | --- |
+| `architecture/` | System-level design: HITL architecture, database services/roles, transaction/audit compliance, blob storage, document content hash, ephemeral document cleanup, reference data tables, template models, shared packages, audit table, HA |
+| `auth/` | Authentication (OAuth/Keycloak, API keys) and group resource authorization |
+| `groups/` | Group management APIs, membership requests, group frontend pages/context |
+| `workflows/` | DAG workflow engine, graph types, node/activity/OCR-provider guides, workflow builder, node catalog, lineage, config overrides, Temporal worker concurrency, Temporal payload footprint (gzip codec + OCR payload refs), `templates/` example configs |
+| `extraction/` | OCR/extraction: Azure AI models, classifiers, enrichment, field formatting, image normalization, confusion profiles/matrices, OCR improvement pipeline, OCR failure handling, OCR result views, ground truth, HITL datasets |
+| `operations/` | OpenShift deployment, environment configuration, backups, Azure infrastructure, secrets, npm hardening |
+| `monitoring/` | PLG stack, Helm charts, Promtail, dashboards, metrics, alerting, logging |
+| `benchmarking/` | Benchmarking system, load testing runbooks |
+| `frontend/` | Frontend-wide concerns: BC Design System migration, confirmation-modal and sentence-case standardization, header/upload UI, UI patterns not tied to one feature |
+| `archive/` | Historical/point-in-time artifacts only — see `archive/README.md` |
+| `wiki/` | Routing layer — rules in `wiki/README.md`, canonical agent rules in `AGENTS.md` (Repo Wiki section) |
+
+- New docs go in the matching folder. Create a new folder only when several related docs don't fit anywhere above; add it to `docs-md/README.md` and this table in the same PR.
+- Filenames: `SCREAMING_SNAKE.md` for reference docs (matches the majority convention).
+
+## Content rules
+
+- Current shipped behavior only. Requirements/user stories → `feature-docs/`; pre-implementation designs → historical once shipped.
+- No placeholders, no "future work" sections, no stubs. If describing target/planned UX is genuinely needed (e.g. design reference), open with an explicit status disclaimer stating what is and isn't implemented.
+- Reference code by repo-relative path. Prefer stable anchors (file paths, exported names) over line numbers.
+- Relative markdown links between docs; they must resolve from the doc's own folder.
+- The system is generic — no document-type-specific implementation guidance.
+- When code changes make a doc inaccurate, the doc is updated in the same PR (CLAUDE.md rule).
+
+## Archive policy
+
+A doc is archived (not deleted) when it stops describing current behavior: reports, one-off analyses, completed plans/status trackers, superseded requirements. Process is in [Workflows/Archive.md](Workflows/Archive.md). Delete only docs with no historical value.
+
+## Wiki boundary (summary — full rules in docs-md/wiki/README.md)
+
+- Wiki topic pages: short synthesis + `canonical_sources` links. 180-line soft limit. No runbooks, schemas, endpoint lists, or implementation guides.
+- Every wiki change: append a grep-friendly `log.md` entry (`## [YYYY-MM-DD] operation | Title`), update `sources.md` if canonical areas changed, record contradictions in `open-questions.md`, run `npm run docs:wiki:check`.

.claude/skills/docs-sync/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: docs-sync
+description: "Keeps docs-md/ and the repo wiki synchronized with the codebase: update docs affected by code changes, audit docs for accuracy, add new docs in the right topic folder, archive stale docs. Trigger phrases: sync docs, update docs for this change, audit docs, docs maintenance, archive doc, document this feature. Do NOT invoke for: editing the docs/ HTML site (use docs-site), writing feature requirements (use requirements-refiner), or wiki-only content questions (read docs-md/wiki/README.md directly)."
+---
+
+# Docs Sync
+
+Maintains `docs-md/` (canonical developer reference docs, organized by topic) and `docs-md/wiki/` (routing layer for humans and LLM agents) so they stay accurate against the codebase.
+
+## Workflows
+
+| Task | Workflow |
+| --- | --- |
+| Code changed — update the affected docs | [Workflows/Ingest.md](Workflows/Ingest.md) |
+| Verify docs are accurate against code (periodic or targeted) | [Workflows/Audit.md](Workflows/Audit.md) |
+| Document something new | [Workflows/AddDoc.md](Workflows/AddDoc.md) |
+| Retire a stale / point-in-time doc | [Workflows/Archive.md](Workflows/Archive.md) |
+
+## Always Follow
+
+1. Read [CONVENTIONS.md](CONVENTIONS.md) before editing any doc — it defines the topic taxonomy, naming, archive policy, and wiki boundary.
+2. Docs describe **current shipped behavior only**. Verify every concrete claim (paths, commands, env vars, endpoints, model/field names) against code before writing it. Never document unverified or planned behavior without an explicit status disclaimer.
+3. Canonical docs first, wiki second: update the `docs-md/` topic doc, then reflect routing/boundary changes in the wiki per `docs-md/wiki/README.md` (ingest workflow). The wiki never duplicates implementation detail.
+4. After touching `docs-md/wiki/`: run `npm run docs:wiki:check`.
+5. After moving/renaming/deleting any doc: run `bash .claude/skills/docs-sync/scripts/check-doc-links.sh` and fix reported dangling links; also grep code, READMEs, and `docs/_pages/` for references to the old path (`grep -rn "docs-md/<OLDNAME>" --include='*.ts' --include='*.md' --include='*.html' --include='*.sh' --include='*.yml' apps packages docs scripts tools deployments README.md`).
+6. Use `git mv` for moves so history is preserved.
+7. Never commit generated `docs/wiki*.html` (gitignored; built by `docs/build.sh` at deploy time).

.claude/skills/docs-sync/Workflows/AddDoc.md

@@ -0,0 +1,34 @@
+# AddDoc — document something new
+
+Use when a shipped subsystem/feature has no reference doc.
+
+## Steps
+
+1. **Confirm it's a real gap.** Search existing docs first — coverage may live under a non-obvious name:
+   ```bash
+   grep -rlni "<subsystem keywords>" docs-md --include='*.md'
+   ```
+   If a doc partially covers it, extend that doc instead of creating a near-duplicate.
+
+2. **Research the code** until you can describe the shipped behavior: entry points, key modules, data flow, configuration. Verify everything you plan to state.
+
+3. **Pick folder and name** from the taxonomy in [CONVENTIONS.md](../CONVENTIONS.md): `docs-md/<topic>/<SCREAMING_SNAKE>.md`.
+
+4. **Write the doc.** Match the conventions of 2–3 neighbors in the folder. Typical shape: title, short overview, key code paths, how it works / how to use it, configuration (env vars, keys), links to related docs. Shipped behavior only — no placeholders, no future-work sections.
+
+5. **Link it into the system:**
+   - Cross-link from the most related existing docs where a reader would need it.
+   - If `docs-md/README.md`'s folder description no longer covers the folder's contents, update it.
+   - Wiki: if the doc adds a canonical area, add it to the relevant topic page's `canonical_sources` and to `docs-md/wiki/sources.md`; log an `ingest` entry in `docs-md/wiki/log.md`.
+
+6. **Verify:**
+   ```bash
+   npm run docs:wiki:check
+   bash .claude/skills/docs-sync/scripts/check-doc-links.sh
+   ```
+
+## Common Pitfalls
+
+- Writing a doc for something `feature-docs/` already specs — feature-docs is requirements history; the new doc describes shipped behavior and should not copy requirements text.
+- Duplicating a runbook into the wiki — the wiki only routes to it.
+- Document-type-specific guidance — the platform is generic; keep examples generic.

.claude/skills/docs-sync/Workflows/Archive.md

@@ -0,0 +1,33 @@
+# Archive — retire a stale or point-in-time doc
+
+Use when a doc stops describing current behavior: completed plans and status trackers, one-off reports/analyses, docs for removed code.
+
+## Steps
+
+1. **Confirm it qualifies.** Archive policy is in [CONVENTIONS.md](../CONVENTIONS.md). If only parts are stale, fix the doc instead ([Audit.md](Audit.md)). Delete outright only when a doc has no historical value (rare).
+
+2. **Move with history:**
+   ```bash
+   git mv docs-md/<topic>/<DOC>.md docs-md/archive/<DOC>.md
+   ```
+
+3. **Update `docs-md/archive/README.md`:** add a row to the Contents table — what it was, and the canonical alternative (the doc/code that now answers those questions).
+
+4. **Repair inbound references.** Find everything pointing at the old path and either re-point to the canonical alternative or to the archive path (for historical citations):
+   ```bash
+   grep -rn "<DOC>.md" --include='*.md' --include='*.ts' --include='*.tsx' --include='*.html' --include='*.sh' --include='*.yml' --include='*.yaml' apps packages docs docs-md scripts tools deployments README.md .claude
+   ```
+
+5. **Wiki:** remove the doc from any `canonical_sources` lists and `sources.md`; if a whole topic became historical, set the topic page `status: archived`. Append a `maintenance` entry to `docs-md/wiki/log.md`.
+
+6. **Verify:**
+   ```bash
+   npm run docs:wiki:check
+   bash .claude/skills/docs-sync/scripts/check-doc-links.sh
+   ```
+
+## Common Pitfalls
+
+- Leaving the archived doc listed as a canonical source in the wiki — the validator may pass (file still exists) but routing is now wrong.
+- Archiving a doc that is the only coverage of still-shipped behavior — extract the still-true content into the topic folder first.
+- Using `mv` instead of `git mv`, losing file history.

.claude/skills/docs-sync/Workflows/Audit.md

@@ -0,0 +1,39 @@
+# Audit — verify docs against the codebase
+
+Use for a periodic accuracy pass, or a targeted check of one topic folder ("audit the monitoring docs").
+
+## Steps
+
+1. **Pick scope.** One doc, one topic folder, or all of `docs-md/` (excluding `archive/` and `wiki/`).
+
+2. **For each doc, verify concrete claims against code.** Check with Grep/Read — never from memory:
+   - file/directory paths exist
+   - commands and npm scripts exist and are spelled right
+   - env var names match code (`grep -rn "process.env.<NAME>"` / config files)
+   - API endpoints, methods, and DTOs match controllers
+   - Prisma model/field names match `apps/shared/prisma/schema.prisma`
+   - workflow node types and activity names match the registries in `apps/temporal/src/` and `packages/graph-workflow/`
+   - helm values, ports, manifest paths match `deployments/`
+
+3. **Fix in place.** Surgical edits; preserve the doc's voice. Don't restructure working content. Content explicitly marked as target design / design reference keeps its content — verify the status disclaimer is still accurate instead.
+
+4. **Classify outcomes:**
+   - accurate → done
+   - fixed → done
+   - describes removed code or is point-in-time → run [Archive.md](Archive.md)
+   - reveals an undocumented subsystem → run [AddDoc.md](AddDoc.md)
+
+5. **For large scopes** (whole tree), fan out subagents — one per doc or per folder batch — each with the checklist above, returning findings + fixes. Cross-check anything a subagent flags as uncertain yourself.
+
+6. **Verify and record:**
+   ```bash
+   npm run docs:wiki:check
+   bash .claude/skills/docs-sync/scripts/check-doc-links.sh
+   ```
+   If wiki structure or the source registry changed, append a `lint` entry to `docs-md/wiki/log.md`.
+
+## Common Pitfalls
+
+- Trusting a doc's own cross-references as evidence — verify against code, not other docs.
+- "Fixing" intentionally deferred abstractions: this team defers abstractions until a documented duplication threshold; their absence is not an inaccuracy or a gap.
+- Deleting design-reference content because it isn't implemented — it's kept intentionally with a status disclaimer.

.claude/skills/docs-sync/Workflows/Ingest.md

@@ -0,0 +1,37 @@
+# Ingest — update docs after a code change
+
+Use when code changed (a diff, a merged PR, a feature you just implemented) and the docs must catch up.
+
+## Steps
+
+1. **Scope the change.** List what actually changed:
+   ```bash
+   git diff --stat <base>...HEAD   # or the working-tree diff
+   ```
+   Identify affected surfaces: endpoints, env vars, Prisma models, workflow nodes/activities, UI routes, deploy manifests, npm scripts.
+
+2. **Find the affected docs.** Map each changed surface to its topic folder (taxonomy in [CONVENTIONS.md](../CONVENTIONS.md)). Search rather than guess:
+   ```bash
+   grep -rln "<changed symbol/path/env var>" docs-md --include='*.md'
+   ```
+   Check `docs-md/<topic>/` listings for docs whose subject overlaps the change.
+
+3. **Update each affected doc.** Verify the new behavior in code first, then edit. Follow the content rules in CONVENTIONS.md. If the change makes a whole doc obsolete, switch to [Archive.md](Archive.md). If the change introduces a new undocumented subsystem, switch to [AddDoc.md](AddDoc.md).
+
+4. **Wiki ingest** (only if the change affects navigation, boundaries, or drift risks — most small changes don't):
+   - Update the relevant `docs-md/wiki/<topic>.md` routing context and `canonical_sources`; bump its `updated:` date.
+   - Update `docs-md/wiki/sources.md` if new canonical areas appeared.
+   - Append to `docs-md/wiki/log.md`: `## [YYYY-MM-DD] ingest | <title>`.
+   - Record contradictions in `docs-md/wiki/open-questions.md`.
+
+5. **Verify:**
+   ```bash
+   npm run docs:wiki:check
+   bash .claude/skills/docs-sync/scripts/check-doc-links.sh
+   ```
+
+## Common Pitfalls
+
+- Updating the wiki but not the canonical doc — canonical source first, always.
+- Documenting the diff instead of the resulting behavior. Docs describe the current state, not the change history.
+- Forgetting non-markdown references: code comments, seed scripts, and configmaps reference `docs-md/` paths too.

.claude/skills/docs-sync/scripts/check-doc-links.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Checks that every relative markdown link in docs-md/ resolves to an existing file.
+# Prints "OK" or a list of dangling links (file: link). Exit 1 if any dangle.
+set -e
+cd "$(git rev-parse --show-toplevel)"
+
+fail=0
+while IFS= read -r -d '' f; do
+  dir=$(dirname "$f")
+  # extract markdown link targets: ](target)
+  grep -oE '\]\([^)[:space:]]+\)' "$f" 2>/dev/null | sed -E 's/^\]\(//; s/\)$//' | while IFS= read -r target; do
+    case "$target" in
+      http://*|https://*|mailto:*|\#*) continue ;;
+    esac
+    clean="${target%%#*}"
+    clean="${clean%%\?*}"
+    [ -z "$clean" ] && continue
+    if [ "${clean#/}" != "$clean" ]; then
+      resolved=".$clean"   # repo-root-absolute style
+    else
+      resolved="$dir/$clean"
+    fi
+    if [ ! -e "$resolved" ]; then
+      echo "DANGLING $f: $target"
+    fi
+  done
+done < <(find docs-md -name '*.md' -not -path 'docs-md/archive/*' -print0) | sort | tee /tmp/doc-link-check.out
+
+if [ -s /tmp/doc-link-check.out ]; then
+  echo "--- $(wc -l < /tmp/doc-link-check.out) dangling link(s) found"
+  exit 1
+else
+  echo "OK: all relative links in docs-md resolve (archive/ excluded)"
+fi