Feature/najuna wip

.cursor/skills/ode-custom-app-form-validation/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ode-custom-app-form-validation
+description: >-
+  Helps validate ODE custom app form definitions (JSON Schema draft-07 + UI schema)
+  and CI integration. Use when the user asks to validate forms, add validate-forms
+  scripts, or check schema/ui consistency for Synkronus bundles. Prefer official docs
+  at opendataensemble.org and the custom-app template repo on GitHub.
+---
+
+# ODE custom app — form validation
+
+## When to use
+
+- Adding or maintaining **`schema.json`** / **`ui.json`** for ODE custom apps.
+- Setting up **CI** to fail on invalid forms.
+- Explaining **draft-07**, `scope` references, or ODE-specific **`format`** rules.
+
+## What to do
+
+1. Point to **[Form specifications](https://opendataensemble.org/docs/reference/form-specifications)** as the normative reference for question types and UI structure.
+2. Ensure **UI `scope`** paths match **JSON Schema** properties; **`required`** arrays align with product intent.
+3. For automation, describe a **Node** (or other) script pattern: load each form folder, `JSON.parse`, validate schema with a draft-07 validator, and check structural rules (both files present, cross-references). Link **[custom_app](https://github.com/OpenDataEnsemble/custom_app)** for AI context, not as a code dependency.
+4. Do **not** invent Synkronus-specific validation rules beyond public docs.
+
+## Official links
+
+- [Form specifications](https://opendataensemble.org/docs/reference/form-specifications)
+- [Custom applications](https://opendataensemble.org/docs/guides/custom-applications)

.cursor/skills/ode-custom-jsonforms-extension/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: ode-custom-jsonforms-extension
+description: >-
+  Guides adding ODE custom JSON Forms extensions (custom renderers, testers, ext.json,
+  dynamic functions). Use when extending forms with non-standard controls or wiring
+  extension manifests. Official behavior is documented on opendataensemble.org.
+---
+
+# ODE custom JSON Forms extensions
+
+## When to use
+
+- Custom **control** rendering (tester + renderer pattern).
+- **`ext.json`** (or app-level extension manifest) and module paths.
+- **Dynamic choice lists** or helper **functions** referenced from the UI schema.
+
+## What to do
+
+1. Read **[Custom extensions](https://opendataensemble.org/docs/guides/custom-extensions)** and **[Dynamic choice lists](https://opendataensemble.org/docs/guides/dynamic-choice-lists)** on the docs site.
+2. Keep **bundled JS** compatible with the Formulus WebView (no Node-only APIs in runtime code).
+3. Align **`format`** in schema with the renderer contract described in docs.
+4. For AI-only context summaries, **[CONTEXT_ODE_FORMS.md](https://github.com/OpenDataEnsemble/custom_app/blob/main/CONTEXT_ODE_FORMS.md)** in **custom_app** may help — still verify against **opendataensemble.org**.
+
+## Do not
+
+- Assume vanilla **jsonforms.io** examples work without checking ODE’s registered renderers and extension loading rules.

.cursor/skills/ode-synk-bundle-publish/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: ode-synk-bundle-publish
+description: >-
+  Guides publishing and managing ODE app bundles with the Synkronus CLI (synk):
+  config, auth, upload, versions. Use when deploying custom app zips or automating
+  bundle uploads. Official reference is opendataensemble.org and OpenDataEnsemble/ode docs.
+---
+
+# Synkronus CLI — app bundle publish
+
+## When to use
+
+- Uploading a **custom app** ZIP to Synkronus.
+- Managing **bundle versions** or scripting **CI** upload steps.
+- Configuring **`synk`** (`~/.synkronus.yaml`, `synk config use`, etc.).
+
+## What to do
+
+1. Use **[Synkronus CLI](https://opendataensemble.org/docs/reference/synkronus-cli)** as the primary command reference.
+2. Ensure the ZIP matches **[App bundle format](https://opendataensemble.org/docs/reference/app-bundle-format)** before upload.
+3. Store **API URLs and tokens** in CI secrets; never embed production credentials in source.
+4. For bundle structure reminders, see **[CONTEXT_BUNDLE_AND_CI.md](https://github.com/OpenDataEnsemble/custom_app/blob/main/CONTEXT_BUNDLE_AND_CI.md)** in **custom_app** (summary only).
+
+## Related
+
+- [App bundles (using)](https://opendataensemble.org/docs/using/app-bundles)
+- [Deployment](https://opendataensemble.org/docs/guides/deployment)

.gitattributes

@@ -0,0 +1,25 @@
+# Normalize line endings: LF in repo and working tree (avoids CRLF churn on Windows).
+* text=auto eol=lf
+
+# Shell / Docker (explicit LF)
+*.sh text eol=lf
+*.bash text eol=lf
+Dockerfile text eol=lf
+*.dockerfile text eol=lf
+
+# Windows scripts: CRLF so cmd.exe treats them correctly
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# Binary assets
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.ico binary
+*.pdf binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary

.github/CICD.md

@@ -34,26 +34,40 @@ Images are published to **GitHub Container Registry (GHCR)**:
 
 #### Tagging Strategy
 
-| Branch/Event | Tags Generated | Description |
-|--------------|----------------|-------------|
-| `main` | `latest`, `main-{sha}` | Latest stable release |
-| `dev` | `dev`, `dev-{sha}` | Development pre-release |
-| Feature branches | `{branch-name}`, `{branch-name}-{sha}` | Feature-specific builds |
-| Pull Requests | `pr-{number}` | PR validation builds (not pushed) |
-| Manual with version | `v{version}`, `v{major}.{minor}`, `latest` | Versioned release |
+Image tags are computed by `docker/metadata-action`. The highest-priority tag per event is also used as the primary tag in manifest verification.
+
+| Event | Tags produced | Published? |
+|-------|--------------|------------|
+| Release published, **not** prerelease | `v{X.Y.Z}`, `v{X.Y}`, `v{X}`, `latest` | Yes |
+| Release published, **is** prerelease | `v{X.Y.Z}-{pre}`, `latest-pre-release` | Yes |
+| Push → `main` | `main`, `sha-{short}` | Yes |
+| Push → `dev` | `dev`, `sha-{short}` | Yes |
+| Push → other branch | `{branch-name}`, `sha-{short}` | Yes |
+| `workflow_dispatch` | `sha-{short}` | Yes |
+| Pull request | `pr-{number}` | No (build only) |
+
+Moving pointer tags:
+
+- **`latest`** — always points to the most recent **non-prerelease** GitHub Release. Never moved by branch pushes.
+- **`latest-pre-release`** — always points to the most recent **prerelease** GitHub Release (e.g. `-alpha.N`, `-rc.N`).
+- **`main`** / **`dev`** — track the tip of the respective branch.
+
+`workflow_dispatch` intentionally produces only `sha-{short}` so that manual runs cannot accidentally reassign `latest`, `main`, `dev`, or any other pointer tag.
 
 #### Build Features
 
-- **Multi-platform**: Builds for `linux/amd64` and `linux/arm64`
-- **Build Cache**: Uses GitHub Actions cache for faster builds
-- **Attestation**: Generates build provenance for security
-- **Metadata**: Includes OCI-compliant labels and annotations
+- **Multi-platform**: Builds for `linux/amd64` and `linux/arm64` using Buildah
+- **Attestation**: Generates SLSA build provenance and pushes it to GHCR
+- **Metadata**: Includes OCI-compliant labels (title, description, vendor, source, revision)
+- **Verification**: After push, the manifest list and per-arch layers are pulled to confirm correctness
 
 #### Permissions Required
 
 The workflow requires these permissions:
 - `contents: read` - To checkout the repository
 - `packages: write` - To publish to GHCR
+- `id-token: write` - For OIDC-based build provenance attestation
+- `attestations: write` - To push attestation records to GHCR
 
 #### Secrets Used
 
@@ -139,12 +153,22 @@ node scripts/sbom/generate-sboms.mjs --out sbom-dist
 
 ## Using Published Images
 
-### Pull Latest Release
+### Pull Latest Stable Release
+
+Points to the most recent non-prerelease GitHub Release.
 
 ```bash
 docker pull ghcr.io/opendataensemble/synkronus:latest
 ```
 
+### Pull Latest Pre-release
+
+Points to the most recent prerelease GitHub Release (e.g. `-alpha.N`, `-rc.N`).
+
+```bash
+docker pull ghcr.io/opendataensemble/synkronus:latest-pre-release
+```
+
 ### Pull Specific Version
 
 ```bash
@@ -153,30 +177,46 @@ docker pull ghcr.io/opendataensemble/synkronus:v1.0.0
 
 ### Pull Development Build
 
+Tracks the tip of the `dev` branch (rebuilt on every push to `dev`).
+
 ```bash
 docker pull ghcr.io/opendataensemble/synkronus:dev
 ```
 
+### Pull Main Branch Build
+
+Tracks the tip of the `main` branch between releases.
+
+```bash
+docker pull ghcr.io/opendataensemble/synkronus:main
+```
+
 ### Pull Feature Branch Build
 
 ```bash
 docker pull ghcr.io/opendataensemble/synkronus:feature-xyz
 ```
 
-## Manual Release Process
+## Release Process
 
-To create a versioned release:
+Versioned images are produced by publishing a **GitHub Release** (the workflow listens for `release: [published]`).
 
-1. Go to **Actions** → **Synkronus Docker Build & Publish**
-2. Click **Run workflow**
-3. Select the `main` branch
-4. Enter version (e.g., `v1.0.0`)
-5. Click **Run workflow**
+1. Go to **Releases** → **Draft a new release**
+2. Create a new tag following semver, prefixed with `v`:
+   - Stable release: `v1.0.0`
+   - Pre-release: `v1.0.0-rc.1`, `v1.0.1-alpha.7`, etc.
+3. Select the target commit (typically tip of `main` for stable, tip of `dev` for pre-release)
+4. Tick **Set as a pre-release** for alpha/beta/rc tags
+5. Click **Publish release**
 
 This will create:
-- `ghcr.io/opendataensemble/synkronus:latest`
-- `ghcr.io/opendataensemble/synkronus:v1.0.0`
-- `ghcr.io/opendataensemble/synkronus:v1.0`
+
+| Release kind | Tags produced |
+|-------|--------------|
+| Stable (`v1.0.0`) | `v1.0.0`, `v1.0`, `v1`, `latest` |
+| Pre-release (`v1.0.0-rc.1`) | `v1.0.0-rc.1`, `latest-pre-release` |
+
+> Note: `workflow_dispatch` is available for manual runs but intentionally **does not** create any pointer tags (only `sha-{short}`) — it is for debugging the build pipeline, not for publishing releases.
 
 ## Image Visibility
 
@@ -240,10 +280,11 @@ echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
 
 ### For Deployments
 
-1. **Pin versions in production**: Use specific version tags, not `latest`
-2. **Test pre-releases**: Use `dev` tag for staging environments
-3. **Monitor image sizes**: Keep images lean for faster deployments
-4. **Use health checks**: Always configure health checks in deployments
+1. **Pin versions in production**: Use specific version tags (`v{X.Y.Z}`), not `latest`
+2. **Staging/QA upcoming releases**: Use `latest-pre-release` to track the most recent prerelease (alpha/rc)
+3. **Bleeding-edge integration**: Use `dev` for builds from the tip of the `dev` branch
+4. **Monitor image sizes**: Keep images lean for faster deployments
+5. **Use health checks**: Always configure health checks in deployments
 
 ## Formplayer Asset Synchronization
 
@@ -279,6 +320,27 @@ This will:
 
 The `build:rn` script automatically handles cleaning, so no need to run `clean-rn-assets` separately.
 
+## ODE Desktop (Tauri)
+
+**Workflow file**: `.github/workflows/ode-desktop.yml`
+
+### Triggers
+
+- **Pull requests** and **pushes** to `main` / `dev` when files under `desktop/**` change (or the workflow file itself)
+- **Manual dispatch**
+
+### Path filters
+
+Runs only when `desktop/**` or `.github/workflows/ode-desktop.yml` changes.
+
+### What it runs
+
+From `desktop/`: `pnpm lint`, `pnpm format:check`, `pnpm test`, `pnpm typecheck`, `pnpm codegen:synk-client`, then **fails** if `desktop/src/generated` drifts from the regenerated OpenAPI client. From `desktop/src-tauri/`: `cargo fmt --check`, `cargo clippy -D warnings`, `cargo test`.
+
+### Formplayer embed
+
+After building formplayer (`npm run build` in `formulus-formplayer`), copy its `build/` into the desktop app with `pnpm copy:formplayer` from `desktop/` (see `desktop/README.md`). Copied assets are gitignored under `desktop/public/formplayer_dist/`.
+
 ## Future Enhancements
 
 Potential improvements to the CI/CD pipeline:

.github/workflows/e2e-attachments.yml

@@ -0,0 +1,103 @@
+# E2E attachment-sync harness (skeleton).
+#
+# Intentionally runs on `workflow_dispatch` ONLY. The jobs below stand
+# up the Compose rig and the language runtimes the eventual tests will
+# need, then exit 0. They pin the shape of the CI integration so that
+# wiring in real tests is a drop-in change.
+#
+# See e2e/README.md for the three-layer test design.
+
+name: E2E — attachments
+
+on:
+  workflow_dispatch:
+  # When the layer 1 contract tests land, enable this:
+  # pull_request:
+  #   paths:
+  #     - 'synkronus/**'
+  #     - 'synkronus-cli/**'
+  #     - 'e2e/**'
+  #     - '.github/workflows/e2e-attachments.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: e2e-attachments-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  contract:
+    name: Layer 1 — Synkronus contract
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: synkronus/go.mod
+          cache: true
+
+      - name: Start Compose (postgres + synkronus)
+        run: |
+          docker compose \
+            -f docker-compose.yml \
+            -f e2e/docker-compose.e2e.yml \
+            --profile e2e up --build --wait
+
+      - name: Smoke — /health responds
+        env:
+          SYNKRONUS_HOST_PORT: 18080
+        run: |
+          curl --fail --retry 10 --retry-delay 2 --retry-connrefused \
+            "http://127.0.0.1:${SYNKRONUS_HOST_PORT}/health"
+
+      # TODO: replace with `go test ./e2e/contracts/... -tags=e2e` once
+      # the contract package lands.
+      - name: Contract tests (placeholder)
+        run: echo "No contract tests wired yet — see e2e/README.md"
+
+      - name: Tear down Compose
+        if: always()
+        run: |
+          docker compose \
+            -f docker-compose.yml \
+            -f e2e/docker-compose.e2e.yml \
+            --profile e2e down -v
+
+  headless:
+    name: Layer 2 — Formulus headless
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: contract
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: formulus/package-lock.json
+
+      - name: Start Compose (postgres + synkronus)
+        run: |
+          docker compose \
+            -f docker-compose.yml \
+            -f e2e/docker-compose.e2e.yml \
+            --profile e2e up --build --wait
+
+      # TODO: replace with `npm --prefix e2e/headless test` once the
+      # headless harness lands.
+      - name: Headless tests (placeholder)
+        run: echo "No headless tests wired yet — see e2e/README.md"
+
+      - name: Tear down Compose
+        if: always()
+        run: |
+          docker compose \
+            -f docker-compose.yml \
+            -f e2e/docker-compose.e2e.yml \
+            --profile e2e down -v