ci: enroll shared Gitea lifecycle

ci: add the isolated postpublish job to the QRun release caller
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Co-Authored-By: Codex <noreply@openai.com>
2026-11-02 18:58:41 +00:00 · 2026-11-02 15:49:30 +00:00 · 2026-11-02 06:18:22 +00:00 · 2026-11-02 04:11:28 +00:00 · 2026-10-21 19:52:27 -05:00 · 2026-10-21 09:55:07 -05:00
42 changed files with 1134 additions and 1586 deletions
@@ -1,65 +1,14 @@
 version: 2.1
-
+setup: true
 orbs:
-  qqq-orb: kingsrook/qqq-orb@0.6.8
-
-commands:
-  configure-package-install:
-    steps:
-      - run:
-          name: Keep package installation unattended
-          command: |
-            # These build machines are discarded after the job.
-            sudo install -d /etc/needrestart/conf.d
-            printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null
-
+  qqq-orb: kingsrook/qqq-orb@0.8
 workflows:
-
-  test_only:
+  setup:
    jobs:
-      - qqq-orb/mvn_test_only:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          filters:
-            branches:
-              ignore: /(develop|release/.*|integration.*)/
-            tags:
-              only: []
-
-  publish_snapshot:
-    jobs:
-      - qqq-orb/mvn_publish:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          branch_type: snapshot
-          filters:
-            branches:
-              only:
-                - develop
-
-  publish_release_candidate:
-    jobs:
-      - qqq-orb/mvn_publish:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          branch_type: release_candidate
-          filters:
-            branches:
-              only:
-                - /release\/.*/
-
-  publish_release:
-    jobs:
-      - qqq-orb/mvn_publish:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          branch_type: release
-          filters:
-            branches:
-              ignore: /.*/
-            tags:
-              only: [ /^v\d+\.\d+\.\d+$/ ]
+    - qqq-orb/generate_pipeline:
+        orb_version: '0.8'
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            ignore: /.*/
@@ -1,20 +0,0 @@
-# QRun-IO qbit .editorconfig: the Kingsrook layout (3-space indentation, never tabs).
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
-indent_style = space
-indent_size = 3
-tab_width = 3
-
-[*.md]
-trim_trailing_whitespace = false
-
-[*.{yml,yaml}]
-indent_size = 2
-
-[*.{cmd,bat}]
-end_of_line = crlf
@@ -1,3 +0,0 @@
-* text=auto eol=lf
-*.cmd text eol=crlf
-mvnw text eol=lf
@@ -0,0 +1,24 @@
+# Standard QRun release caller (v2, thin contract): every push and manual dispatch delegates to the protected qrun-release-v1 channel. Do not edit per repository.
+name: qrun-release
+on:
+  push: {}
+  workflow_dispatch: {}
+permissions:
+  contents: read
+  actions: read
+jobs:
+  release:
+    uses: self:KofTwentyTwo/platform-ci/.gitea/workflows/java-maven.yaml@qrun-release-v1
+    with:
+      runner: linux-small
+      browsers: true
+      browser-runner: browser-build
+  postpublish:
+    if: ${{ needs.release.outputs.capture == 'true' }}
+    needs: release
+    permissions:
+      contents: write
+      actions: write
+    uses: self:KofTwentyTwo/platform-ci/.gitea/workflows/qrun-source-version.yaml@qrun-release-v1
+    with:
+      runner: linux-small
@@ -1,25 +0,0 @@
-# Weekly, grouped dependency updates. Minor and patch updates arrive as one PR per ecosystem;
-# major updates stay separate so each gets its own review. At most three version-update PRs per
-# ecosystem are open at once. Security updates are enabled in the repository settings and are
-# not limited by this schedule.
-version: 2
-updates:
-  - package-ecosystem: maven
-    directory: /
-    target-branch: develop
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 3
-    groups:
-      maven-minor-and-patch:
-        update-types: [minor, patch]
-
-  - package-ecosystem: github-actions
-    directory: /
-    target-branch: develop
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 3
-    groups:
-      github-actions:
-        update-types: [minor, patch]
@@ -1,31 +0,0 @@
-# GitHub Release Configuration
-# Auto-generates release notes from PR labels
-
-changelog:
-  exclude:
-    labels:
-      - ignore-for-release
-      - duplicate
-      - invalid
-    authors:
-      - dependabot
-      - dependabot[bot]
-  categories:
-    - title: Breaking Changes
-      labels:
-        - breaking-change
-        - breaking
-    - title: New Features
-      labels:
-        - enhancement
-        - feature
-    - title: Bug Fixes
-      labels:
-        - bug
-        - fix
-    - title: Dependencies
-      labels:
-        - dependencies
-    - title: Other Changes
-      labels:
-        - "*"
@@ -0,0 +1,23 @@
+name: CodeQL
+'on':
+  push:
+    branches:
+    - main
+    - develop
+    - release/**
+    - hotfix/**
+  pull_request: {}
+  schedule:
+  - cron: 41 16 * * 0
+  workflow_dispatch: {}
+permissions:
+  contents: read
+  actions: read
+  security-events: write
+  packages: read
+concurrency:
+  group: codeql-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  analyze:
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@17c94592d94c7d56c440277be6fe3526692887a6
@@ -1,25 +0,0 @@
-# Cut the next release candidate (QRun-IO/qqq docs/QRUN-QBIT-REPO-STANDARD.md, C6):
-# run this workflow by hand, or merge a develop PR labelled `release:rc`. It merges develop into
-# the release line and the release/* push runs CircleCI publish_release_candidate.
-name: Release candidate
-
-on:
-  workflow_dispatch:
-    inputs:
-      dry_run:
-        description: Print the plan without merging or creating branches
-        type: boolean
-        default: false
-  pull_request:
-    types: [closed]
-    branches: [develop]
-
-permissions:
-  contents: write
-
-jobs:
-  release-rc:
-    if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release:rc'))
-    uses: QRun-IO/.github/.github/workflows/qbit-release-rc.yml@main
-    with:
-      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
@@ -1,21 +1,31 @@
+# Maven
 target/
-.env
-.idea
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+pom.xml.next
+release.properties
+
+# IDE
+.idea/
 *.iml
+.project
+.classpath
+.settings/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build
 *.class
-*.log
 *.jar
 *.war
-*.nar
 *.ear
-*.zip
-*.tar.gz
-*.rar
-hs_err_pid*
-.DS_Store
-*.sw*
-.flattened-pom.xml
-dependency-reduced-pom.xml
-/.env.local
-/.cache/
-.claude/settings.local.json
+
+# Logs
+*.log
+logs/
@@ -1,3 +0,0 @@
-wrapperVersion=3.3.4
-distributionType=only-script
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip
@@ -0,0 +1,15 @@
+profile: qbit
+orb_version: '0.8'
+default_branch: develop
+java_version: '21'
+browsers: true
+api_checks: false
+docs_only: false
+release_on_main: false
+release_tag_policy: none
+test_branch_policy: all
+publish:
+  snapshot: false
+  release_candidate: false
+  release: false
+  asciidoc: false
@@ -1,51 +0,0 @@
-# AGENTS.md
-
-Guidance for coding agents working in this repository.
-
-## Overview
-
-QBit File Gateway runs an SFTP server (Apache MINA SSHD) that exposes a QQQ application as a
-folder tree: apps, tables, `upload/<bulk-load-profile>/`, `views/`, `reports/`, `results/` and
-`archive/`. Users and service accounts sign in with SSH public keys. All data access goes through
-the `/qqq/v1` UI API with `UiApiInvoker` on the client channel `sftp`, as the signed-in user; never
-through core actions directly. It runs as its own Kubernetes Deployment from the same application
-code and QInstance. Design: `docs/DESIGN.md`.
-
-## Build commands
-
-```bash
-./mvnw compile
-./mvnw test
-./mvnw verify  # Checkstyle; JaCoCo: 70% instructions, 90% classes
-```
-
-Use the Maven 3.9.11 wrapper (Java 21); Maven 3.10 cannot read the parent POM. On Windows use `./mvnw.cmd`.
-
-## Architecture
-
-Package: `com.kingsrook.qbits.filegateway`. Entry point: `FileGatewayQBitProducer implements
-QBitMetaDataProducer<FileGatewayQBitConfig>`.
-
-## Invariants and naming
-
- Data access only through `/qqq/v1` (`UiApiInvoker`, channel `sftp`) as the signed-in user. The
-  gateway writes only its own `file_gateway_*` tables directly.
- SFTP only, SSH-key auth only. No password login of any kind; plain FTP is never allowed.
- Tables use lowercase snake_case with the `file_gateway_` prefix; backend names equal table
-  names. Permissions use the full `file_gateway` prefix. Processes are table or record actions,
-  never navigation entries. One app home.
- No secrets in code or config: host keys come from env-var names.
-
-## Code style
-
-3-space indent, next-line braces, `return (x);`, flower-box Javadoc on classes and methods, fluent `withX()` setters. Follow `checkstyle/` and `CODE_STYLE.md`.
-
-## Dependencies
-
-Parent: `com.kingsrook:qbit-build-parent:2.0.0`. QQQ BOM: `4.1.0-SNAPSHOT` until 4.1.0-RC.6.
-Only allow-listed qbit API artifacts (`qbit-object-storage` `api` package) may be depended on.
-Notifications go through core `QAlerts.notify`, never qbit-alerts classes.
-
-## Release flow
-
-CircleCI uses `kingsrook/qqq-orb@0.6.8`: develop publishes SNAPSHOTs, release/* publishes RCs, and only `vX.Y.Z` GA tags publish releases. RC automation uses workflow_dispatch or a merged develop PR labelled `release:rc`. Feature branches start from develop and return by PR. Never push `hotfix/*` or `release/*` branches by hand; never publish manually.
@@ -1,9 +0,0 @@
-# Changelog
-
-All notable changes are documented here, following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-
- Initial scaffold
@@ -1,51 +1,25 @@
-# CLAUDE.md
+# qbit-template-application

-Guidance for coding agents working in this repository.
+GitHub template repository for scaffolding Application QBits (complete mini-applications
+with tables, processes, widgets, and UI navigation) on the QQQ platform.

-## Overview
+## QQQ 4.0 baseline — 2026-09-24

-QBit File Gateway runs an SFTP server (Apache MINA SSHD) that exposes a QQQ application as a
-folder tree: apps, tables, `upload/<bulk-load-profile>/`, `views/`, `reports/`, `results/` and
-`archive/`. Users and service accounts sign in with SSH public keys. All data access goes through
-the `/qqq/v1` UI API with `UiApiInvoker` on the client channel `sftp`, as the signed-in user; never
-through core actions directly. It runs as its own Kubernetes Deployment from the same application
-code and QInstance. Design: `docs/DESIGN.md`.
+The historical review below predates the 4.0 migration. This template targets Java 21 and the public QQQ 4.0.0 release from Maven Central. The corrected APIs, license references and actual template commands are in README.md and docs/00-getting-started.md. Preserve the documented multi-instance and scaffold limitations.

-## Build commands
+## Knowledge base

-```bash
-./mvnw compile
-./mvnw test
-./mvnw verify  # Checkstyle; JaCoCo: 70% instructions, 90% classes
-```
+Reviewed dossier and platform knowledge live in the second-brain vault:

-Use the Maven 3.9.11 wrapper (Java 21); Maven 3.10 cannot read the parent POM. On Windows use `./mvnw.cmd`.
+- Hub: `R:/Git.Local/KofTwentyTwo/second-brain/knowledge/qqq/qqq-hub.md`
+- This repo's dossier: `R:/Git.Local/KofTwentyTwo/second-brain/knowledge/qqq/repos/qbit-template-application.md`
+- QBit mechanics refresher: `R:/Git.Local/KofTwentyTwo/second-brain/knowledge/qqq/architecture/metadata-model.md`

-## Architecture
+Reviewed at commit `fb9395ac0d07` (branch `main`, 2026-07-04).

-Package: `com.kingsrook.qbits.filegateway`. Entry point: `FileGatewayQBitProducer implements
-QBitMetaDataProducer<FileGatewayQBitConfig>`.
-
-## Invariants and naming
-
- Data access only through `/qqq/v1` (`UiApiInvoker`, channel `sftp`) as the signed-in user. The
-  gateway writes only its own `file_gateway_*` tables directly.
- SFTP only, SSH-key auth only. No password login of any kind; plain FTP is never allowed.
- Tables use lowercase snake_case with the `file_gateway_` prefix; backend names equal table
-  names. Permissions use the full `file_gateway` prefix. Processes are table or record actions,
-  never navigation entries. One app home.
- No secrets in code or config: host keys come from env-var names.
-
-## Code style
-
-3-space indent, next-line braces, `return (x);`, flower-box Javadoc on classes and methods, fluent `withX()` setters. Follow `checkstyle/` and `CODE_STYLE.md`.
-
-## Dependencies
-
-Parent: `com.kingsrook:qbit-build-parent:2.0.0`. QQQ BOM: `4.1.0-SNAPSHOT` until 4.1.0-RC.6.
-Only allow-listed qbit API artifacts (`qbit-object-storage` `api` package) may be depended on.
-Notifications go through core `QAlerts.notify`, never qbit-alerts classes.
-
-## Release flow
-
-CircleCI uses `kingsrook/qqq-orb@0.6.8`: develop publishes SNAPSHOTs, release/* publishes RCs, and only `vX.Y.Z` GA tags publish releases. RC automation uses workflow_dispatch or a merged develop PR labelled `release:rc`. Feature branches start from develop and return by PR. Never push `hotfix/*` or `release/*` branches by hand; never publish manually.
+Key caveat from that review: the scaffold in `src/main` references six qqq APIs that do not
+exist in any qqq version (wrong packages for `MetaDataProducerInterface` /
+`AbstractWidgetRenderer` / `RenderWidgetInput`, plus nonexistent `QInstance.addAppSection`,
+`QProcessMetaData.withInputFields`, `QAppSection.withSourceQBitName`) — it has never compiled,
+and CI on `main` is red. Verify against the qqq checkout (`R:/Git.Local/QRunIO/qqq`) before
+trusting any API usage shown here.
@@ -1,3 +0,0 @@
-# Code of Conduct
-
-See Project level [Code of Conduct](https://github.com/QRun-IO/qqq/blob/develop/CODE_OF_CONDUCT.md)
@@ -1,3 +0,0 @@
-# Code Style Guide
-
-* See Project [Code Style Guide](https://github.com/QRun-IO/qqq/blob/develop/CODE_STYLE.md)
@@ -1,6 +0,0 @@
-# Contributing to QBit File Gateway
-
-* See Project [Contributing](https://github.com/QRun-IO/qqq/blob/develop/CONTRIBUTING.md)
-* Branches follow GitFlow: `feature/*` from `develop`, pull requests to `develop`, `release/*` for release candidates, `vX.Y.Z` tags for releases.
-* Commits are signed and follow Conventional Commits.
-* Build and test locally with `./mvnw verify` (Java 21).
@@ -176,7 +176,7 @@

   END OF TERMS AND CONDITIONS

-   Copyright 2024 Kingsrook, LLC
+   Copyright 2022-2025 QRunIO, LLC

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
@@ -1,6 +1,6 @@
-QBit File Gateway
-Copyright 2026 Kingsrook, LLC
+qBit Template - Application
+Copyright 2022-2025 QRunIO, LLC

-This product includes software developed at Kingsrook, LLC (https://kingsrook.com/).
+This product includes software developed at QRunIO, LLC (https://qrun.io/).

 Licensed under the Apache License, Version 2.0.
@@ -1,56 +1,55 @@
-# QBit File Gateway
+# QBit Template - Application

-An SFTP server for QQQ applications. Users and service accounts sign in with their SSH keys and see
-the application as a folder tree of apps and tables. Uploading a file into a table's
-`upload/<profile>/` folder runs a saved bulk-load profile as that user; getting a file from
-`views/` or `reports/` exports a saved view or runs a saved report. The gateway reaches data only
-through the `/qqq/v1` UI API with the signed-in user's own session (client channel `sftp`), so
-permissions, masking and audits apply exactly as in the UI. Design: [docs/DESIGN.md](docs/DESIGN.md).
+Template repository for creating **Application QBits** - complete, self-contained applications or major functional modules for the QQQ framework.

-This repository currently holds the scaffold; the gateway is built in phases described in the design.
+## When to Use This Template

-## Requirements
+Use this template when building:
+- Complete mini-applications (WMS, OMS, CRM)
+- Major functional modules with multiple tables
+- QBits that require UI navigation (QAppSection)
+- Self-contained features with business logic

-Java 21 and QQQ 4.1.0-SNAPSHOT (UI API invoker and client channels, until 4.1.0-RC.6). The Maven
-wrapper pins Maven 3.9.11.
+## Quick Start

-## Install
+Requires **Java 21**, **Maven 3.8+**, and QQQ **4.0.0**. Create a repository with **Use this template**, customize its Maven coordinates and Java package/classes, then run `mvn clean verify`. Follow the [Getting Started guide](docs/00-getting-started.md) for the full sequence.

-```xml
-<dependency>
-   <groupId>com.kingsrook.qbits</groupId>
-   <artifactId>qbit-file-gateway</artifactId>
-   <version>0.1.0-SNAPSHOT</version>
-</dependency>
+## Structure
+
+```
+src/main/java/com/kingsrook/qbits/example/
+├── ExampleAppQBitConfig.java
+├── ExampleAppQBitProducer.java
+├── model/
+│   ├── ExampleEntity.java
+│   └── ExampleChildEntity.java
+├── processes/
+│   ├── ExampleProcessStep.java
+│   └── ExampleProcessMetaDataProducer.java
+└── widgets/
+    ├── ExampleDashboardWidgetRenderer.java
+    └── ExampleDashboardWidgetMetaDataProducer.java
 ```

-## Tables and permissions
+## Key Characteristics

-Planned tables (none are produced yet), all prefixed `file_gateway_`: accounts, SSH keys, aliases,
-upload jobs, the transfer log and the connection log. Permissions use the full `file_gateway`
-prefix.
+| Feature | Description |
+|---------|-------------|
+| QAppSection | Required - provides UI navigation |
+| Tables | Multiple interconnected business tables |
+| Processes | Full CRUD with business logic |
+| Widgets | Dashboard components |
+| Security | Permission key support |
+| Integration | Hooks for other QBits |

-## Configuration
+## Documentation

-`FileGatewayQBitConfig` holds the optional `tableMetaDataCustomizer`, `sftpEnabled` (only the
-gateway deployment runs the server) and `sftpPort` (default 2222).
+- [Getting Started](docs/00-getting-started.md)
+- [Tables and Relationships](docs/01-tables-and-relationships.md)
+- [Processes](docs/02-processes.md)
+- [Widgets and UI](docs/03-widgets-and-ui.md)

-## Adopting in another app
+## See Also

-```java
-new FileGatewayQBitProducer()
-   .withQBitConfig(new FileGatewayQBitConfig())
-   .produce(qInstance);
-```
-
-## Build
-
-```bash
-./mvnw verify   # Checkstyle; JaCoCo 70% instructions, 90% classes
-```
-
-On Windows, use `./mvnw.cmd`.
-
-## License
-
-[Apache License 2.0](LICENSE). Copyright Kingsrook, LLC.
+- [qbit-template-extension](https://github.com/QRun-IO/qbit-template-extension) - For infrastructure extensions
+- [qbit-template-data](https://github.com/QRun-IO/qbit-template-data) - For reference data providers
@@ -1,4 +0,0 @@
-# Security Policy
-
-* See Project [Security Policy](https://github.com/QRun-IO/qqq/blob/develop/SECURITY.md)
-* Report suspected vulnerabilities privately through GitHub private vulnerability reporting on this repository, never in a public issue.
@@ -1,246 +0,0 @@
-<?xml version="1.0"?>
-<!--
-  ~ QQQ - Low-code Application Framework for Engineers.
-  ~ Copyright (C) 2021-2022.  Kingsrook, LLC
-  ~ 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
-  ~ contact@kingsrook.com
-  ~ https://github.com/Kingsrook/
-  ~
-  ~ Licensed under the Apache License, Version 2.0 (the "License");
-  ~ you may not use this file except in compliance with the License.
-  ~ You may obtain a copy of the License at
-  ~
-  ~     https://www.apache.org/licenses/LICENSE-2.0
-  ~
-  ~ Unless required by applicable law or agreed to in writing, software
-  ~ distributed under the License is distributed on an "AS IS" BASIS,
-  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  ~ See the License for the specific language governing permissions and
-  ~ limitations under the License.
-  -->
-
-<!DOCTYPE module PUBLIC
-        "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
-        "http://checkstyle.sourceforge.net/dtds/configuration_1_3.dtd">
-<!--
-   See reference at https://checkstyle.sourceforge.io/checks.html
-->
-<module name = "Checker">
-   <property name="charset" value="UTF-8"/>
-
-   <property name="severity" value="warning"/>
-
-   <property name="fileExtensions" value="java, properties, xml"/>
-   <!-- Checks for whitespace                        -->
-   <!-- See http://checkstyle.sf.net/config_whitespace.html -->
-   <module name="FileTabCharacter">
-      <property name="eachLine" value="true"/>
-   </module>
-
-   <!--
-   <module name="LineLength">
-      <property name="max" value="100"/>
-      <property name="ignorePattern" value="^package.*|^import.*|a href|href|http://|https://|ftp://"/>
-   </module>
-   -->
-
-   <module name="TreeWalker">
-      <module name="SuppressWarningsHolder"/>
-      <module name="OuterTypeFilename"/>
-      <module name="IllegalTokenText">
-         <property name="tokens" value="STRING_LITERAL, CHAR_LITERAL"/>
-         <property name="format" value="\\u00(09|0(a|A)|0(c|C)|0(d|D)|22|27|5(C|c))|\\(0(10|11|12|14|15|42|47)|134)"/>
-         <property name="message" value="Consider using special escape sequence instead of octal value or Unicode escaped value."/>
-      </module>
-      <module name="AvoidEscapedUnicodeCharacters">
-         <property name="allowEscapesForControlCharacters" value="true"/>
-         <property name="allowByTailComment" value="true"/>
-         <property name="allowNonPrintableEscapes" value="true"/>
-      </module>
-      <module name="AvoidStarImport"/>
-      <module name="OneTopLevelClass"/>
-      <module name="NoLineWrap"/>
-      <module name="EmptyBlock">
-         <property name="option" value="TEXT"/>
-         <property name="tokens" value="LITERAL_TRY, LITERAL_FINALLY, LITERAL_IF, LITERAL_ELSE, LITERAL_SWITCH"/>
-      </module>
-      <module name="NeedBraces"/>
-      <module name="LeftCurly">
-         <property name="option" value="nl"/>
-      </module>
-      <module name="RightCurly">
-         <property name="option" value="alone"/>
-      </module>
-      <!--
-      <module name="WhitespaceAround">
-         <property name="allowEmptyConstructors" value="true"/>
-         <property name="allowEmptyMethods" value="true"/>
-         <property name="allowEmptyTypes" value="true"/>
-         <property name="allowEmptyLoops" value="true"/>
-         <message key="ws.notFollowed"
-          value="WhitespaceAround: ''{0}'' is not followed by whitespace. Empty blocks may only be represented as '{}' when not part of a multi-block statement (4.1.3)"/>
-          <message key="ws.notPreceded"
-          value="WhitespaceAround: ''{0}'' is not preceded with whitespace."/>
-      </module>
-      -->
-      <module name="OneStatementPerLine"/>
-      <module name="MultipleVariableDeclarations"/>
-      <module name="ArrayTypeStyle"/>
-      <module name="MissingSwitchDefault"/>
-      <module name="FallThrough"/>
-      <module name="UpperEll"/>
-      <module name="ModifierOrder"/>
-      <module name="EmptyLineSeparator">
-         <property name="allowNoEmptyLineBetweenFields" value="true"/>
-      </module>
-      <module name="SeparatorWrap">
-         <property name="id" value="SeparatorWrapDot"/>
-         <property name="tokens" value="DOT"/>
-         <property name="option" value="nl"/>
-      </module>
-      <module name="SeparatorWrap">
-         <property name="id" value="SeparatorWrapComma"/>
-         <property name="tokens" value="COMMA"/>
-         <property name="option" value="EOL"/>
-      </module>
-      <module name="SeparatorWrap">
-         <!-- ELLIPSIS is EOL until https://github.com/google/styleguide/issues/258 -->
-         <property name="id" value="SeparatorWrapEllipsis"/>
-         <property name="tokens" value="ELLIPSIS"/>
-         <property name="option" value="EOL"/>
-      </module>
-      <module name="SeparatorWrap">
-         <!-- ARRAY_DECLARATOR is EOL until https://github.com/google/styleguide/issues/259 -->
-         <property name="id" value="SeparatorWrapArrayDeclarator"/>
-         <property name="tokens" value="ARRAY_DECLARATOR"/>
-         <property name="option" value="EOL"/>
-      </module>
-      <module name="SeparatorWrap">
-         <property name="id" value="SeparatorWrapMethodRef"/>
-         <property name="tokens" value="METHOD_REF"/>
-         <property name="option" value="nl"/>
-      </module>
-      <module name="PackageName">
-         <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
-         <message key="name.invalidPattern"
-          value="Package name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="TypeName">
-         <message key="name.invalidPattern"
-          value="Type name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="MemberName">
-         <property name="format" value="^[_a-zA-Z]([a-z0-9A-Z][a-zA-Z0-9]*)?$"/>
-         <message key="name.invalidPattern" value="Member name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="ParameterName">
-         <property name="format" value="^[a-zA-Z]([a-z0-9A-Z][a-zA-Z0-9]*)?$"/>
-         <message key="name.invalidPattern" value="Parameter name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="CatchParameterName">
-         <property name="format" value="^[a-zA-Z]([a-z0-9A-Z][a-zA-Z0-9]*)?$"/>
-         <message key="name.invalidPattern" value="Catch parameter name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="LocalVariableName">
-         <property name="tokens" value="VARIABLE_DEF"/>
-         <property name="format" value="^[a-zA-Z]([a-z0-9A-Z][a-zA-Z0-9]*)?$"/>
-         <message key="name.invalidPattern" value="Local variable name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="ClassTypeParameterName">
-         <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][_A-Z0-9]*$)"/>
-         <message key="name.invalidPattern" value="Class type name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="MethodTypeParameterName">
-         <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][_A-Z0-9]*$)"/>
-         <message key="name.invalidPattern" value="Method type name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="InterfaceTypeParameterName">
-         <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][_A-Z0-9]*$)"/>
-         <message key="name.invalidPattern" value="Interface type name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="NoFinalizer"/>
-      <module name="GenericWhitespace">
-         <message key="ws.followed" value="GenericWhitespace ''{0}'' is followed by whitespace."/>
-         <message key="ws.preceded" value="GenericWhitespace ''{0}'' is preceded with whitespace."/>
-         <message key="ws.illegalFollow" value="GenericWhitespace ''{0}'' should followed by whitespace."/>
-         <message key="ws.notPreceded" value="GenericWhitespace ''{0}'' is not preceded with whitespace."/>
-      </module>
-      <module name="Indentation">
-         <property name="basicOffset" value="3"/>
-         <property name="braceAdjustment" value="0"/>
-         <property name="caseIndent" value="3"/>
-         <property name="throwsIndent" value="6"/>
-         <property name="lineWrappingIndentation" value="3"/>
-         <property name="arrayInitIndent" value="6"/>
-      </module>
-      <!--
-      <module name="AbbreviationAsWordInName">
-         <property name="ignoreFinal" value="false"/>
-         <property name="allowedAbbreviationLength" value="1"/>
-      </module>
-      <module name="OverloadMethodsDeclarationOrder"/>
-      <module name="VariableDeclarationUsageDistance"/>
-      <module name="CustomImportOrder">
-         <property name="sortImportsInGroupAlphabetically" value="true"/>
-         <property name="separateLineBetweenGroups" value="true"/>
-         <property name="customImportOrderRules" value="STATIC###THIRD_PARTY_PACKAGE"/>
-      </module>
-      -->
-      <module name="CustomImportOrder">
-         <property name="customImportOrderRules" value="SPECIAL_IMPORTS###STANDARD_JAVA_PACKAGE###THIRD_PARTY_PACKAGE###STATIC"/>
-         <property name="specialImportsRegExp" value="^javax\."/>
-         <property name="standardPackageRegExp" value="^java\."/>
-         <property name="sortImportsInGroupAlphabetically" value="true"/>
-         <property name="separateLineBetweenGroups" value="false"/>
-      </module>
-      <module name="MethodParamPad"/>
-      <module name="NoWhitespaceBefore">
-         <property name="tokens" value="COMMA, SEMI, POST_INC, POST_DEC, DOT, ELLIPSIS, METHOD_REF"/>
-         <property name="allowLineBreaks" value="true"/>
-      </module>
-      <module name="ParenPad"/>
-      <module name="OperatorWrap">
-         <property name="option" value="NL"/>
-         <property name="tokens" value="BAND, BOR, BSR, BXOR, DIV, EQUAL, GE, GT, LAND, LE, LITERAL_INSTANCEOF, LOR, LT, MINUS, MOD, NOT_EQUAL, PLUS, QUESTION, SL, SR, STAR, METHOD_REF "/>
-      </module>
-      <module name="AnnotationLocation">
-         <property name="id" value="AnnotationLocationMostCases"/>
-         <property name="tokens" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, METHOD_DEF, CTOR_DEF"/>
-      </module>
-      <module name="AnnotationLocation">
-         <property name="id" value="AnnotationLocationVariables"/>
-         <property name="tokens" value="VARIABLE_DEF"/>
-         <property name="allowSamelineMultipleAnnotations" value="true"/>
-      </module>
-      <module name="JavadocMethod">
-         <property name="allowMissingParamTags" value="true"/>
-         <property name="allowMissingReturnTag" value="true"/>
-         <property name="allowedAnnotations" value="Override, Test"/>
-      </module>
-      <module name="MissingJavadocMethod">
-         <property name="scope" value="private"/>
-      </module>
-      <module name="MissingJavadocType">
-         <property name="scope" value="private"/>
-      </module>
-      <module name="MethodName">
-         <property name="format" value="^[a-z][a-zA-Z0-9_]*$"/>
-         <message key="name.invalidPattern"
-          value="Method name ''{0}'' must match pattern ''{1}''."/>
-      </module>
-      <module name="EmptyCatchBlock">
-         <property name="exceptionVariableName" value="expected"/>
-      </module>
-      <module name="CommentsIndentation"/>
-
-      <!-- this would be nice, but requires the the @inheritDoc javadoc tag... -->
-      <module name="MissingOverride"/>
-
-   </module>
-   <module name="Header">
-     <property name="headerFile" value="checkstyle/license.txt"/>
-     <property name="fileExtensions" value="java"/>
-     <property name="ignoreLines" value="3"/>
-   </module>
-   <module name="SuppressWarningsFilter"/>
-</module>
@@ -1,19 +0,0 @@
-/*
- * QQQ - Low-code Application Framework for Engineers.
- * Copyright (C) 2021-2025.  Kingsrook, LLC
- * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
- * contact@kingsrook.com
- * https://github.com/Kingsrook/
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
@@ -0,0 +1,30 @@
+# Getting Started
+
+Targets Java 21, Maven 3.8 or later, and QQQ 4.0.0. Maven resolves the framework dependencies from Maven Central.
+
+1. Choose **Use this template** on GitHub, then clone the repository you created.
+2. In `pom.xml`, set your own `groupId`, `artifactId`, name, description, and version.
+3. Use your IDE's package refactoring to rename `com.kingsrook.qbits.example` throughout `src/`. Rename the `Example*` classes and update their imports and references with the IDE's rename refactoring.
+4. Update the QBit producer's `GROUP_ID`, `ARTIFACT_ID`, and `VERSION` constants to match your project. Give the metadata names their own stable names before combining the QBit with other examples.
+5. Build the generated project:
+
+```bash
+mvn clean verify
+```
+
+The repository provides example Java sources; customization uses normal package/class refactoring. Keep example coordinates unpublished. After customizing, add tests for your QBit's behavior before setting up its publishing workflow.
+
+## Register with a host application
+
+The following uses the original example names; substitute the names chosen above:
+
+```java
+new ExampleAppQBitProducer()
+   .withConfig(new ExampleAppQBitConfig()
+      .withBackendName("rdbms"))
+   .produce(qInstance, "my-application");
+```
+
+Register the configured backend in the host first. If you add table prefixes or multiple QBit instances, update related table references, possible-value-source names, and process/widget names consistently. A table prefix alone does not namespace all metadata.
+
+[Tables and Relationships](01-tables-and-relationships.md) describes the model; the `processes/` and `widgets/` directories contain the remaining examples.
@@ -0,0 +1,50 @@
+# Tables and Relationships
+
+Application QBits typically have multiple interconnected tables representing a business domain.
+
+## Entity Design
+
+Use `@QMetaDataProducingEntity` for automatic metadata generation:
+
+```java
+@QMetaDataProducingEntity(producePossibleValueSource = true)
+public class Order extends QRecordEntity
+{
+   public static final String TABLE_NAME = "order";
+
+   @QField(isPrimaryKey = true)
+   private Integer id;
+
+   @QField(isRequired = true, possibleValueSourceName = "customer")
+   private Integer customerId;
+
+   @QField(isRequired = true)
+   private String status;
+}
+```
+
+## Relationships
+
+Define foreign keys using `possibleValueSourceName`:
+
+```java
+@QField(isRequired = true, possibleValueSourceName = "exampleEntity")
+private Integer exampleEntityId;
+```
+
+## Table Prefixing
+
+Application QBits support optional table prefixing:
+
+```java
+// Without prefix: order, orderLine
+// With prefix "sales": sales_order, sales_orderLine
+
+new MyAppQBitProducer()
+   .withConfig(new MyAppQBitConfig()
+      .withBackendName("rdbms")
+      .withTableNamePrefix("sales"))
+   .produce(qInstance, "sales-app");
+```
+
+The producer applies the prefix to table names. When extending this pattern, also update possible-value-source names, relationship targets, process tables, and navigation references; table renaming alone does not provide complete multi-instance support.
@@ -0,0 +1,7 @@
+# Processes
+
+Start with [ExampleProcessMetaDataProducer](../src/main/java/com/kingsrook/qbits/example/processes/ExampleProcessMetaDataProducer.java) and [ExampleProcessStep](../src/main/java/com/kingsrook/qbits/example/processes/ExampleProcessStep.java). The producer defines the process, its table, inputs, and backend step; the step transforms `PENDING` records to `PROCESSED` and returns them in the output.
+
+In QQQ 4.0, import `MetaDataProducerInterface` from `com.kingsrook.qqq.backend.core.model.metadata`. Define process inputs through `withInputMetaData(new QFunctionInputMetaData().withField(...))`. An `AbstractTransformStep` must implement both `runOnePage(RunBackendStepInput, RunBackendStepOutput)` and `getProcessSummary(RunBackendStepOutput, boolean)`; keep the example's implementations when renaming it.
+
+To make the process discoverable in navigation, add its registered name to a `QAppSection` through `withProcesses(List.of(ExampleProcessMetaDataProducer.NAME))`, then include the section in a `QAppMetaData` registered with `qInstance.addApp(...)`. Use the actual registered name if you introduce a prefix. Add tests for record changes and failure cases when replacing the example business logic.
@@ -0,0 +1,23 @@
+# Widgets and UI
+
+The application producer registers a `QAppMetaData` containing a `QAppSection`. The section references metadata names already registered in the instance; it is not registered directly on `QInstance`.
+
+```java
+QAppSection section = new QAppSection()
+   .withName("exampleSection")
+   .withLabel("Example Application")
+   .withTables(List.of(ExampleEntity.TABLE_NAME, ExampleChildEntity.TABLE_NAME))
+   .withProcesses(List.of(ExampleProcessMetaDataProducer.NAME))
+   .withWidgets(List.of(ExampleDashboardWidgetMetaDataProducer.NAME));
+
+qInstance.addApp(new QAppMetaData()
+   .withName("exampleApp")
+   .withLabel("Example Application")
+   .withSection(section));
+```
+
+Use [ExampleAppQBitProducer](../src/main/java/com/kingsrook/qbits/example/ExampleAppQBitProducer.java) as the starting point. Keep these references consistent when enabling/disabling tables or introducing prefixes.
+
+The widget has two parts: [its metadata producer](../src/main/java/com/kingsrook/qbits/example/widgets/ExampleDashboardWidgetMetaDataProducer.java) declares a statistics widget and its renderer, and [its renderer](../src/main/java/com/kingsrook/qbits/example/widgets/ExampleDashboardWidgetRenderer.java) returns a `RenderWidgetOutput` containing `StatisticsData`. Replace the example count with a query or calculation. Choose a widget type that matches the returned data model.
+
+For QQQ 4.0, `AbstractWidgetRenderer` is in `com.kingsrook.qqq.backend.core.actions.dashboard.widgets`; `RenderWidgetInput` and `RenderWidgetOutput` are in `com.kingsrook.qqq.backend.core.model.actions.widgets`.
@@ -1,4 +0,0 @@
-# QBit File Gateway: design
-
-The design is being written in the spec PR that follows this scaffold. Until it merges, see the
-open spec pull request in this repository.
@@ -1,295 +0,0 @@
-#!/bin/sh
-# ----------------------------------------------------------------------------
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements.  See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership.  The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License.  You may obtain a copy of the License at
-#
-#    http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied.  See the License for the
-# specific language governing permissions and limitations
-# under the License.
-# ----------------------------------------------------------------------------
-
-# ----------------------------------------------------------------------------
-# Apache Maven Wrapper startup batch script, version 3.3.4
-#
-# Optional ENV vars
-# -----------------
-#   JAVA_HOME - location of a JDK home dir, required when download maven via java source
-#   MVNW_REPOURL - repo url base for downloading maven distribution
-#   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
-#   MVNW_VERBOSE - true: enable verbose log; debug: trace the mvnw script; others: silence the output
-# ----------------------------------------------------------------------------
-
-set -euf
-[ "${MVNW_VERBOSE-}" != debug ] || set -x
-
-# OS specific support.
-native_path() { printf %s\\n "$1"; }
-case "$(uname)" in
-CYGWIN* | MINGW*)
-  [ -z "${JAVA_HOME-}" ] || JAVA_HOME="$(cygpath --unix "$JAVA_HOME")"
-  native_path() { cygpath --path --windows "$1"; }
-  ;;
-esac
-
-# set JAVACMD and JAVACCMD
-set_java_home() {
-  # For Cygwin and MinGW, ensure paths are in Unix format before anything is touched
-  if [ -n "${JAVA_HOME-}" ]; then
-    if [ -x "$JAVA_HOME/jre/sh/java" ]; then
-      # IBM's JDK on AIX uses strange locations for the executables
-      JAVACMD="$JAVA_HOME/jre/sh/java"
-      JAVACCMD="$JAVA_HOME/jre/sh/javac"
-    else
-      JAVACMD="$JAVA_HOME/bin/java"
-      JAVACCMD="$JAVA_HOME/bin/javac"
-
-      if [ ! -x "$JAVACMD" ] || [ ! -x "$JAVACCMD" ]; then
-        echo "The JAVA_HOME environment variable is not defined correctly, so mvnw cannot run." >&2
-        echo "JAVA_HOME is set to \"$JAVA_HOME\", but \"\$JAVA_HOME/bin/java\" or \"\$JAVA_HOME/bin/javac\" does not exist." >&2
-        return 1
-      fi
-    fi
-  else
-    JAVACMD="$(
-      'set' +e
-      'unset' -f command 2>/dev/null
-      'command' -v java
-    )" || :
-    JAVACCMD="$(
-      'set' +e
-      'unset' -f command 2>/dev/null
-      'command' -v javac
-    )" || :
-
-    if [ ! -x "${JAVACMD-}" ] || [ ! -x "${JAVACCMD-}" ]; then
-      echo "The java/javac command does not exist in PATH nor is JAVA_HOME set, so mvnw cannot run." >&2
-      return 1
-    fi
-  fi
-}
-
-# hash string like Java String::hashCode
-hash_string() {
-  str="${1:-}" h=0
-  while [ -n "$str" ]; do
-    char="${str%"${str#?}"}"
-    h=$(((h * 31 + $(LC_CTYPE=C printf %d "'$char")) % 4294967296))
-    str="${str#?}"
-  done
-  printf %x\\n $h
-}
-
-verbose() { :; }
-[ "${MVNW_VERBOSE-}" != true ] || verbose() { printf %s\\n "${1-}"; }
-
-die() {
-  printf %s\\n "$1" >&2
-  exit 1
-}
-
-trim() {
-  # MWRAPPER-139:
-  #   Trims trailing and leading whitespace, carriage returns, tabs, and linefeeds.
-  #   Needed for removing poorly interpreted newline sequences when running in more
-  #   exotic environments such as mingw bash on Windows.
-  printf "%s" "${1}" | tr -d '[:space:]'
-}
-
-scriptDir="$(dirname "$0")"
-scriptName="$(basename "$0")"
-
-# parse distributionUrl and optional distributionSha256Sum, requires .mvn/wrapper/maven-wrapper.properties
-while IFS="=" read -r key value; do
-  case "${key-}" in
-  distributionUrl) distributionUrl=$(trim "${value-}") ;;
-  distributionSha256Sum) distributionSha256Sum=$(trim "${value-}") ;;
-  esac
-done <"$scriptDir/.mvn/wrapper/maven-wrapper.properties"
-[ -n "${distributionUrl-}" ] || die "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
-
-case "${distributionUrl##*/}" in
-maven-mvnd-*bin.*)
-  MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/
-  case "${PROCESSOR_ARCHITECTURE-}${PROCESSOR_ARCHITEW6432-}:$(uname -a)" in
-  *AMD64:CYGWIN* | *AMD64:MINGW*) distributionPlatform=windows-amd64 ;;
-  :Darwin*x86_64) distributionPlatform=darwin-amd64 ;;
-  :Darwin*arm64) distributionPlatform=darwin-aarch64 ;;
-  :Linux*x86_64*) distributionPlatform=linux-amd64 ;;
-  *)
-    echo "Cannot detect native platform for mvnd on $(uname)-$(uname -m), use pure java version" >&2
-    distributionPlatform=linux-amd64
-    ;;
-  esac
-  distributionUrl="${distributionUrl%-bin.*}-$distributionPlatform.zip"
-  ;;
-maven-mvnd-*) MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ ;;
-*) MVN_CMD="mvn${scriptName#mvnw}" _MVNW_REPO_PATTERN=/org/apache/maven/ ;;
-esac
-
-# apply MVNW_REPOURL and calculate MAVEN_HOME
-# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
-[ -z "${MVNW_REPOURL-}" ] || distributionUrl="$MVNW_REPOURL$_MVNW_REPO_PATTERN${distributionUrl#*"$_MVNW_REPO_PATTERN"}"
-distributionUrlName="${distributionUrl##*/}"
-distributionUrlNameMain="${distributionUrlName%.*}"
-distributionUrlNameMain="${distributionUrlNameMain%-bin}"
-MAVEN_USER_HOME="${MAVEN_USER_HOME:-${HOME}/.m2}"
-MAVEN_HOME="${MAVEN_USER_HOME}/wrapper/dists/${distributionUrlNameMain-}/$(hash_string "$distributionUrl")"
-
-exec_maven() {
-  unset MVNW_VERBOSE MVNW_USERNAME MVNW_PASSWORD MVNW_REPOURL || :
-  exec "$MAVEN_HOME/bin/$MVN_CMD" "$@" || die "cannot exec $MAVEN_HOME/bin/$MVN_CMD"
-}
-
-if [ -d "$MAVEN_HOME" ]; then
-  verbose "found existing MAVEN_HOME at $MAVEN_HOME"
-  exec_maven "$@"
-fi
-
-case "${distributionUrl-}" in
-*?-bin.zip | *?maven-mvnd-?*-?*.zip) ;;
-*) die "distributionUrl is not valid, must match *-bin.zip or maven-mvnd-*.zip, but found '${distributionUrl-}'" ;;
-esac
-
-# prepare tmp dir
-if TMP_DOWNLOAD_DIR="$(mktemp -d)" && [ -d "$TMP_DOWNLOAD_DIR" ]; then
-  clean() { rm -rf -- "$TMP_DOWNLOAD_DIR"; }
-  trap clean HUP INT TERM EXIT
-else
-  die "cannot create temp dir"
-fi
-
-mkdir -p -- "${MAVEN_HOME%/*}"
-
-# Download and Install Apache Maven
-verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
-verbose "Downloading from: $distributionUrl"
-verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
-
-# select .zip or .tar.gz
-if ! command -v unzip >/dev/null; then
-  distributionUrl="${distributionUrl%.zip}.tar.gz"
-  distributionUrlName="${distributionUrl##*/}"
-fi
-
-# verbose opt
-__MVNW_QUIET_WGET=--quiet __MVNW_QUIET_CURL=--silent __MVNW_QUIET_UNZIP=-q __MVNW_QUIET_TAR=''
-[ "${MVNW_VERBOSE-}" != true ] || __MVNW_QUIET_WGET='' __MVNW_QUIET_CURL='' __MVNW_QUIET_UNZIP='' __MVNW_QUIET_TAR=v
-
-# normalize http auth
-case "${MVNW_PASSWORD:+has-password}" in
-'') MVNW_USERNAME='' MVNW_PASSWORD='' ;;
-has-password) [ -n "${MVNW_USERNAME-}" ] || MVNW_USERNAME='' MVNW_PASSWORD='' ;;
-esac
-
-if [ -z "${MVNW_USERNAME-}" ] && command -v wget >/dev/null; then
-  verbose "Found wget ... using wget"
-  wget ${__MVNW_QUIET_WGET:+"$__MVNW_QUIET_WGET"} "$distributionUrl" -O "$TMP_DOWNLOAD_DIR/$distributionUrlName" || die "wget: Failed to fetch $distributionUrl"
-elif [ -z "${MVNW_USERNAME-}" ] && command -v curl >/dev/null; then
-  verbose "Found curl ... using curl"
-  curl ${__MVNW_QUIET_CURL:+"$__MVNW_QUIET_CURL"} -f -L -o "$TMP_DOWNLOAD_DIR/$distributionUrlName" "$distributionUrl" || die "curl: Failed to fetch $distributionUrl"
-elif set_java_home; then
-  verbose "Falling back to use Java to download"
-  javaSource="$TMP_DOWNLOAD_DIR/Downloader.java"
-  targetZip="$TMP_DOWNLOAD_DIR/$distributionUrlName"
-  cat >"$javaSource" <<-END
-	public class Downloader extends java.net.Authenticator
-	{
-	  protected java.net.PasswordAuthentication getPasswordAuthentication()
-	  {
-	    return new java.net.PasswordAuthentication( System.getenv( "MVNW_USERNAME" ), System.getenv( "MVNW_PASSWORD" ).toCharArray() );
-	  }
-	  public static void main( String[] args ) throws Exception
-	  {
-	    setDefault( new Downloader() );
-	    java.nio.file.Files.copy( java.net.URI.create( args[0] ).toURL().openStream(), java.nio.file.Paths.get( args[1] ).toAbsolutePath().normalize() );
-	  }
-	}
-	END
-  # For Cygwin/MinGW, switch paths to Windows format before running javac and java
-  verbose " - Compiling Downloader.java ..."
-  "$(native_path "$JAVACCMD")" "$(native_path "$javaSource")" || die "Failed to compile Downloader.java"
-  verbose " - Running Downloader.java ..."
-  "$(native_path "$JAVACMD")" -cp "$(native_path "$TMP_DOWNLOAD_DIR")" Downloader "$distributionUrl" "$(native_path "$targetZip")"
-fi
-
-# If specified, validate the SHA-256 sum of the Maven distribution zip file
-if [ -n "${distributionSha256Sum-}" ]; then
-  distributionSha256Result=false
-  if [ "$MVN_CMD" = mvnd.sh ]; then
-    echo "Checksum validation is not supported for maven-mvnd." >&2
-    echo "Please disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
-    exit 1
-  elif command -v sha256sum >/dev/null; then
-    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | sha256sum -c - >/dev/null 2>&1; then
-      distributionSha256Result=true
-    fi
-  elif command -v shasum >/dev/null; then
-    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | shasum -a 256 -c >/dev/null 2>&1; then
-      distributionSha256Result=true
-    fi
-  else
-    echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available." >&2
-    echo "Please install either command, or disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
-    exit 1
-  fi
-  if [ $distributionSha256Result = false ]; then
-    echo "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised." >&2
-    echo "If you updated your Maven version, you need to update the specified distributionSha256Sum property." >&2
-    exit 1
-  fi
-fi
-
-# unzip and move
-if command -v unzip >/dev/null; then
-  unzip ${__MVNW_QUIET_UNZIP:+"$__MVNW_QUIET_UNZIP"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -d "$TMP_DOWNLOAD_DIR" || die "failed to unzip"
-else
-  tar xzf${__MVNW_QUIET_TAR:+"$__MVNW_QUIET_TAR"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -C "$TMP_DOWNLOAD_DIR" || die "failed to untar"
-fi
-
-# Find the actual extracted directory name (handles snapshots where filename != directory name)
-actualDistributionDir=""
-
-# First try the expected directory name (for regular distributions)
-if [ -d "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" ]; then
-  if [ -f "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain/bin/$MVN_CMD" ]; then
-    actualDistributionDir="$distributionUrlNameMain"
-  fi
-fi
-
-# If not found, search for any directory with the Maven executable (for snapshots)
-if [ -z "$actualDistributionDir" ]; then
-  # enable globbing to iterate over items
-  set +f
-  for dir in "$TMP_DOWNLOAD_DIR"/*; do
-    if [ -d "$dir" ]; then
-      if [ -f "$dir/bin/$MVN_CMD" ]; then
-        actualDistributionDir="$(basename "$dir")"
-        break
-      fi
-    fi
-  done
-  set -f
-fi
-
-if [ -z "$actualDistributionDir" ]; then
-  verbose "Contents of $TMP_DOWNLOAD_DIR:"
-  verbose "$(ls -la "$TMP_DOWNLOAD_DIR")"
-  die "Could not find Maven distribution directory in extracted archive"
-fi
-
-verbose "Found extracted Maven distribution directory: $actualDistributionDir"
-printf %s\\n "$distributionUrl" >"$TMP_DOWNLOAD_DIR/$actualDistributionDir/mvnw.url"
-mv -- "$TMP_DOWNLOAD_DIR/$actualDistributionDir" "$MAVEN_HOME" || [ -d "$MAVEN_HOME" ] || die "fail to move MAVEN_HOME"
-
-clean || :
-exec_maven "$@"
@@ -1,189 +0,0 @@
-<# : batch portion
-@REM ----------------------------------------------------------------------------
-@REM Licensed to the Apache Software Foundation (ASF) under one
-@REM or more contributor license agreements.  See the NOTICE file
-@REM distributed with this work for additional information
-@REM regarding copyright ownership.  The ASF licenses this file
-@REM to you under the Apache License, Version 2.0 (the
-@REM "License"); you may not use this file except in compliance
-@REM with the License.  You may obtain a copy of the License at
-@REM
-@REM    http://www.apache.org/licenses/LICENSE-2.0
-@REM
-@REM Unless required by applicable law or agreed to in writing,
-@REM software distributed under the License is distributed on an
-@REM "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-@REM KIND, either express or implied.  See the License for the
-@REM specific language governing permissions and limitations
-@REM under the License.
-@REM ----------------------------------------------------------------------------
-
-@REM ----------------------------------------------------------------------------
-@REM Apache Maven Wrapper startup batch script, version 3.3.4
-@REM
-@REM Optional ENV vars
-@REM   MVNW_REPOURL - repo url base for downloading maven distribution
-@REM   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
-@REM   MVNW_VERBOSE - true: enable verbose log; others: silence the output
-@REM ----------------------------------------------------------------------------
-
-@IF "%__MVNW_ARG0_NAME__%"=="" (SET __MVNW_ARG0_NAME__=%~nx0)
-@SET __MVNW_CMD__=
-@SET __MVNW_ERROR__=
-@SET __MVNW_PSMODULEP_SAVE=%PSModulePath%
-@SET PSModulePath=
-@FOR /F "usebackq tokens=1* delims==" %%A IN (`powershell -noprofile "& {$scriptDir='%~dp0'; $script='%__MVNW_ARG0_NAME__%'; icm -ScriptBlock ([Scriptblock]::Create((Get-Content -Raw '%~f0'))) -NoNewScope}"`) DO @(
-  IF "%%A"=="MVN_CMD" (set __MVNW_CMD__=%%B) ELSE IF "%%B"=="" (echo %%A) ELSE (echo %%A=%%B)
-)
-@SET PSModulePath=%__MVNW_PSMODULEP_SAVE%
-@SET __MVNW_PSMODULEP_SAVE=
-@SET __MVNW_ARG0_NAME__=
-@SET MVNW_USERNAME=
-@SET MVNW_PASSWORD=
-@IF NOT "%__MVNW_CMD__%"=="" ("%__MVNW_CMD__%" %*)
-@echo Cannot start maven from wrapper >&2 && exit /b 1
-@GOTO :EOF
-: end batch / begin powershell #>
-
-$ErrorActionPreference = "Stop"
-if ($env:MVNW_VERBOSE -eq "true") {
-  $VerbosePreference = "Continue"
-}
-
-# calculate distributionUrl, requires .mvn/wrapper/maven-wrapper.properties
-$distributionUrl = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionUrl
-if (!$distributionUrl) {
-  Write-Error "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
-}
-
-switch -wildcard -casesensitive ( $($distributionUrl -replace '^.*/','') ) {
-  "maven-mvnd-*" {
-    $USE_MVND = $true
-    $distributionUrl = $distributionUrl -replace '-bin\.[^.]*$',"-windows-amd64.zip"
-    $MVN_CMD = "mvnd.cmd"
-    break
-  }
-  default {
-    $USE_MVND = $false
-    $MVN_CMD = $script -replace '^mvnw','mvn'
-    break
-  }
-}
-
-# apply MVNW_REPOURL and calculate MAVEN_HOME
-# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
-if ($env:MVNW_REPOURL) {
-  $MVNW_REPO_PATTERN = if ($USE_MVND -eq $False) { "/org/apache/maven/" } else { "/maven/mvnd/" }
-  $distributionUrl = "$env:MVNW_REPOURL$MVNW_REPO_PATTERN$($distributionUrl -replace "^.*$MVNW_REPO_PATTERN",'')"
-}
-$distributionUrlName = $distributionUrl -replace '^.*/',''
-$distributionUrlNameMain = $distributionUrlName -replace '\.[^.]*$','' -replace '-bin$',''
-
-$MAVEN_M2_PATH = "$HOME/.m2"
-if ($env:MAVEN_USER_HOME) {
-  $MAVEN_M2_PATH = "$env:MAVEN_USER_HOME"
-}
-
-if (-not (Test-Path -Path $MAVEN_M2_PATH)) {
-    New-Item -Path $MAVEN_M2_PATH -ItemType Directory | Out-Null
-}
-
-$MAVEN_WRAPPER_DISTS = $null
-if ((Get-Item $MAVEN_M2_PATH).Target[0] -eq $null) {
-  $MAVEN_WRAPPER_DISTS = "$MAVEN_M2_PATH/wrapper/dists"
-} else {
-  $MAVEN_WRAPPER_DISTS = (Get-Item $MAVEN_M2_PATH).Target[0] + "/wrapper/dists"
-}
-
-$MAVEN_HOME_PARENT = "$MAVEN_WRAPPER_DISTS/$distributionUrlNameMain"
-$MAVEN_HOME_NAME = ([System.Security.Cryptography.SHA256]::Create().ComputeHash([byte[]][char[]]$distributionUrl) | ForEach-Object {$_.ToString("x2")}) -join ''
-$MAVEN_HOME = "$MAVEN_HOME_PARENT/$MAVEN_HOME_NAME"
-
-if (Test-Path -Path "$MAVEN_HOME" -PathType Container) {
-  Write-Verbose "found existing MAVEN_HOME at $MAVEN_HOME"
-  Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
-  exit $?
-}
-
-if (! $distributionUrlNameMain -or ($distributionUrlName -eq $distributionUrlNameMain)) {
-  Write-Error "distributionUrl is not valid, must end with *-bin.zip, but found $distributionUrl"
-}
-
-# prepare tmp dir
-$TMP_DOWNLOAD_DIR_HOLDER = New-TemporaryFile
-$TMP_DOWNLOAD_DIR = New-Item -Itemtype Directory -Path "$TMP_DOWNLOAD_DIR_HOLDER.dir"
-$TMP_DOWNLOAD_DIR_HOLDER.Delete() | Out-Null
-trap {
-  if ($TMP_DOWNLOAD_DIR.Exists) {
-    try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
-    catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
-  }
-}
-
-New-Item -Itemtype Directory -Path "$MAVEN_HOME_PARENT" -Force | Out-Null
-
-# Download and Install Apache Maven
-Write-Verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
-Write-Verbose "Downloading from: $distributionUrl"
-Write-Verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
-
-$webclient = New-Object System.Net.WebClient
-if ($env:MVNW_USERNAME -and $env:MVNW_PASSWORD) {
-  $webclient.Credentials = New-Object System.Net.NetworkCredential($env:MVNW_USERNAME, $env:MVNW_PASSWORD)
-}
-[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
-$webclient.DownloadFile($distributionUrl, "$TMP_DOWNLOAD_DIR/$distributionUrlName") | Out-Null
-
-# If specified, validate the SHA-256 sum of the Maven distribution zip file
-$distributionSha256Sum = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionSha256Sum
-if ($distributionSha256Sum) {
-  if ($USE_MVND) {
-    Write-Error "Checksum validation is not supported for maven-mvnd. `nPlease disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties."
-  }
-  Import-Module $PSHOME\Modules\Microsoft.PowerShell.Utility -Function Get-FileHash
-  if ((Get-FileHash "$TMP_DOWNLOAD_DIR/$distributionUrlName" -Algorithm SHA256).Hash.ToLower() -ne $distributionSha256Sum) {
-    Write-Error "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised. If you updated your Maven version, you need to update the specified distributionSha256Sum property."
-  }
-}
-
-# unzip and move
-Expand-Archive "$TMP_DOWNLOAD_DIR/$distributionUrlName" -DestinationPath "$TMP_DOWNLOAD_DIR" | Out-Null
-
-# Find the actual extracted directory name (handles snapshots where filename != directory name)
-$actualDistributionDir = ""
-
-# First try the expected directory name (for regular distributions)
-$expectedPath = Join-Path "$TMP_DOWNLOAD_DIR" "$distributionUrlNameMain"
-$expectedMvnPath = Join-Path "$expectedPath" "bin/$MVN_CMD"
-if ((Test-Path -Path $expectedPath -PathType Container) -and (Test-Path -Path $expectedMvnPath -PathType Leaf)) {
-  $actualDistributionDir = $distributionUrlNameMain
-}
-
-# If not found, search for any directory with the Maven executable (for snapshots)
-if (!$actualDistributionDir) {
-  Get-ChildItem -Path "$TMP_DOWNLOAD_DIR" -Directory | ForEach-Object {
-    $testPath = Join-Path $_.FullName "bin/$MVN_CMD"
-    if (Test-Path -Path $testPath -PathType Leaf) {
-      $actualDistributionDir = $_.Name
-    }
-  }
-}
-
-if (!$actualDistributionDir) {
-  Write-Error "Could not find Maven distribution directory in extracted archive"
-}
-
-Write-Verbose "Found extracted Maven distribution directory: $actualDistributionDir"
-Rename-Item -Path "$TMP_DOWNLOAD_DIR/$actualDistributionDir" -NewName $MAVEN_HOME_NAME | Out-Null
-try {
-  Move-Item -Path "$TMP_DOWNLOAD_DIR/$MAVEN_HOME_NAME" -Destination $MAVEN_HOME_PARENT | Out-Null
-} catch {
-  if (! (Test-Path -Path "$MAVEN_HOME" -PathType Container)) {
-    Write-Error "fail to move MAVEN_HOME"
-  }
-} finally {
-  try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
-  catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
-}
-
-Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
@@ -1,107 +1,37 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!--
-  ~ QQQ - Low-code Application Framework for Engineers.
-  ~ Copyright (C) 2021-2026.  Kingsrook, LLC
-  ~ 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
-  ~ contact@kingsrook.com
-  ~ https://github.com/Kingsrook/
-  ~
-  ~ Licensed under the Apache License, Version 2.0 (the "License");
-  ~ you may not use this file except in compliance with the License.
-  ~ You may obtain a copy of the License at
-  ~
-  ~     https://www.apache.org/licenses/LICENSE-2.0
-  ~
-  ~ Unless required by applicable law or agreed to in writing, software
-  ~ distributed under the License is distributed on an "AS IS" BASIS,
-  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  ~ See the License for the specific language governing permissions and
-  ~ limitations under the License.
-  -->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
-   <properties>
-      <revision>0.1.0-SNAPSHOT</revision>
-      <maven.compiler.source>21</maven.compiler.source>
-      <maven.compiler.target>21</maven.compiler.target>
-      <jacoco.version>0.8.15</jacoco.version>
-      <h2.version>2.2.224</h2.version>
-   </properties>
-
-   <parent>
-      <groupId>com.kingsrook</groupId>
-      <artifactId>qbit-build-parent</artifactId>
-      <version>2.0.0</version>
-   </parent>
-
-   <groupId>com.kingsrook.qbits</groupId>
-   <artifactId>qbit-file-gateway</artifactId>
-   <version>${revision}</version>
-   <packaging>jar</packaging>
-
-   <name>QBit File Gateway</name>
-   <description>QBit that serves QQQ applications as an SFTP folder tree: upload files into saved bulk-load profiles, download saved views and saved reports, with per-user SSH keys and a full transfer audit</description>
-   <url>https://github.com/QRun-IO/qbit-file-gateway</url>
-
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>

-   <licenses>
-      <license>
-         <name>Apache License, Version 2.0</name>
-         <url>https://www.apache.org/licenses/LICENSE-2.0</url>
-         <distribution>repo</distribution>
-      </license>
-   </licenses>
+   <groupId>com.kingsrook.qbits</groupId>
+   <artifactId>qbit-example-app</artifactId>
+   <version>0.1.0-SNAPSHOT</version>
+   <packaging>jar</packaging>

-   <developers>
-      <developer>
-         <id>kingsrook</id>
-         <name>Kingsrook Team</name>
-         <email>contact@kingsrook.com</email>
-         <organization>Kingsrook, LLC</organization>
-         <organizationUrl>https://kingsrook.com</organizationUrl>
-      </developer>
-   </developers>
+   <name>QBit Example Application</name>
+   <description>Template for Application QBits - complete mini-applications with UI navigation</description>

-   <scm>
-      <connection>scm:git:git://github.com/QRun-IO/qbit-file-gateway.git</connection>
-      <developerConnection>scm:git:ssh://github.com:QRun-IO/qbit-file-gateway.git</developerConnection>
-      <url>https://github.com/QRun-IO/qbit-file-gateway</url>
-      <tag>HEAD</tag>
-   </scm>
+   <properties>
+      <maven.compiler.source>21</maven.compiler.source>
+      <maven.compiler.target>21</maven.compiler.target>
+      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+      <qqq.version>4.0.0</qqq.version>
+   </properties>

   <dependencies>
+      <!-- QQQ Backend Core -->
      <dependency>
         <groupId>com.kingsrook.qqq</groupId>
         <artifactId>qqq-backend-core</artifactId>
+         <version>${qqq.version}</version>
      </dependency>

-      <!-- The memory backend is included in qqq-backend-core. -->
-      <dependency>
-         <groupId>com.kingsrook.qqq</groupId>
-         <artifactId>qqq-backend-module-rdbms</artifactId>
-         <scope>test</scope>
-      </dependency>
-      <dependency>
-         <groupId>com.kingsrook.qqq</groupId>
-         <artifactId>qqq-middleware-javalin</artifactId>
-      </dependency>
-      <dependency>
-         <groupId>com.kingsrook.qqq</groupId>
-         <artifactId>qqq-frontend-next</artifactId>
-         <version>1.0.0-RC.14</version>
-         <scope>test</scope>
-      </dependency>
-      <dependency>
-         <groupId>com.h2database</groupId>
-         <artifactId>h2</artifactId>
-         <version>${h2.version}</version>
-         <scope>test</scope>
-      </dependency>
+      <!-- Testing -->
      <dependency>
         <groupId>org.junit.jupiter</groupId>
         <artifactId>junit-jupiter</artifactId>
+         <version>5.10.0</version>
         <scope>test</scope>
      </dependency>
      <dependency>
@@ -110,111 +40,51 @@
         <version>3.27.7</version>
         <scope>test</scope>
      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-module-rdbms</artifactId>
+         <version>${qqq.version}</version>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.h2database</groupId>
+         <artifactId>h2</artifactId>
+         <version>2.2.224</version>
+         <scope>test</scope>
+      </dependency>
   </dependencies>

   <build>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
-            <artifactId>maven-checkstyle-plugin</artifactId>
-            <version>3.3.1</version>
-            <dependencies>
-               <dependency>
-                  <groupId>com.puppycrawl.tools</groupId>
-                  <artifactId>checkstyle</artifactId>
-                  <version>10.12.6</version>
-               </dependency>
-            </dependencies>
-            <configuration>
-               <configLocation>checkstyle/config.xml</configLocation>
-               <headerLocation>checkstyle/license.txt</headerLocation>
-               <encoding>UTF-8</encoding>
-               <consoleOutput>true</consoleOutput>
-               <failsOnError>false</failsOnError>
-               <failOnViolation>true</failOnViolation>
-               <violationSeverity>warning</violationSeverity>
-               <includeTestSourceDirectory>false</includeTestSourceDirectory>
-            </configuration>
-            <executions>
-               <execution>
-                  <id>validate</id>
-                  <phase>validate</phase>
-                  <goals>
-                     <goal>check</goal>
-                  </goals>
-               </execution>
-            </executions>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.11.0</version>
+         </plugin>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <version>3.1.2</version>
         </plugin>
         <plugin>
            <groupId>org.jacoco</groupId>
            <artifactId>jacoco-maven-plugin</artifactId>
-            <version>${jacoco.version}</version>
+            <version>0.8.10</version>
            <executions>
               <execution>
-                  <id>prepare-agent</id>
                  <goals>
                     <goal>prepare-agent</goal>
                  </goals>
               </execution>
               <execution>
                  <id>report</id>
-                  <phase>verify</phase>
+                  <phase>test</phase>
                  <goals>
                     <goal>report</goal>
                  </goals>
               </execution>
-               <execution>
-                  <id>check</id>
-                  <goals>
-                     <goal>check</goal>
-                  </goals>
-                  <configuration>
-                     <rules>
-                        <rule>
-                           <element>BUNDLE</element>
-                           <limits>
-                              <limit>
-                                 <counter>INSTRUCTION</counter>
-                                 <value>COVEREDRATIO</value>
-                                 <minimum>0.70</minimum>
-                              </limit>
-                              <limit>
-                                 <counter>CLASS</counter>
-                                 <value>COVEREDRATIO</value>
-                                 <minimum>0.90</minimum>
-                              </limit>
-                           </limits>
-                        </rule>
-                     </rules>
-                  </configuration>
-               </execution>
            </executions>
         </plugin>
      </plugins>
   </build>
-
-   <profiles>
-      <!-- QQQ 4.1 APIs until qbit-build-parent imports the 4.1 BOM (as in qbit-quick-search and qbit-cdn, ADR-0007). -->
-      <profile>
-         <id>qqq-snapshot</id>
-         <activation>
-            <activeByDefault>true</activeByDefault>
-         </activation>
-         <properties>
-            <!-- STAND-IN(core=QRun-IO/qqq develop after v4.1.0-RC.5, removeBy=4.1.0-RC.6): UiApiInvoker client channels and QAlerts.notify are on develop only; pin the RC when it is cut -->
-            <qqq.snapshot.version>4.1.0-SNAPSHOT</qqq.snapshot.version>
-         </properties>
-         <dependencyManagement>
-            <dependencies>
-               <dependency>
-                  <groupId>com.kingsrook.qqq</groupId>
-                  <artifactId>qqq-bom-pom</artifactId>
-                  <version>${qqq.snapshot.version}</version>
-                  <type>pom</type>
-                  <scope>import</scope>
-               </dependency>
-            </dependencies>
-         </dependencyManagement>
-      </profile>
-   </profiles>
 </project>
@@ -0,0 +1,164 @@
+/*******************************************************************************
+ ** Configuration class for the Example Application QBit.
+ **
+ ** Application QBits support:
+ ** - Backend configuration for data storage
+ ** - Optional table prefixing for multi-instance deployment
+ ** - Feature toggles for optional modules
+ ** - Security key prefix for permission scoping
+ ** - Integration hooks for other QBits
+ *******************************************************************************/
+package com.kingsrook.qbits.example;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitConfig;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+public class ExampleAppQBitConfig implements QBitConfig
+{
+   private String  backendName;
+   private String  tableNamePrefix;
+   private Boolean enableChildModule = true;
+   private String  securityKeyPrefix;
+
+   /////////////////////////////////////////////////////////////////////////
+   // Integration hooks - allow host app to inject custom behavior        //
+   /////////////////////////////////////////////////////////////////////////
+   private QCodeReference onEntityCreatedHandler;
+   private QCodeReference customValidationProvider;
+
+
+
+   /*******************************************************************************
+    ** Validate the configuration before the QBit is produced.
+    *******************************************************************************/
+   @Override
+   public void validate(QInstance qInstance, List<String> errors)
+   {
+      if(!StringUtils.hasContent(backendName))
+      {
+         errors.add("backendName is required for ExampleAppQBit");
+      }
+
+      if(qInstance.getBackend(backendName) == null)
+      {
+         errors.add("Backend not found: " + backendName);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Apply prefix to a table name if configured.
+    *******************************************************************************/
+   public String applyPrefix(String tableName)
+   {
+      if(StringUtils.hasContent(tableNamePrefix))
+      {
+         return tableNamePrefix + "_" + tableName;
+      }
+      return tableName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Get the security key for permission checks.
+    *******************************************************************************/
+   public String getSecurityKey(String baseName)
+   {
+      if(StringUtils.hasContent(securityKeyPrefix))
+      {
+         return securityKeyPrefix + "." + baseName;
+      }
+      return baseName;
+   }
+
+
+
+   //////////////////////////////////////////////////////////////////////////////
+   // Getters and fluent setters                                               //
+   //////////////////////////////////////////////////////////////////////////////
+
+   public String getBackendName()
+   {
+      return backendName;
+   }
+
+
+   public ExampleAppQBitConfig withBackendName(String backendName)
+   {
+      this.backendName = backendName;
+      return this;
+   }
+
+
+   public String getTableNamePrefix()
+   {
+      return tableNamePrefix;
+   }
+
+
+   public ExampleAppQBitConfig withTableNamePrefix(String tableNamePrefix)
+   {
+      this.tableNamePrefix = tableNamePrefix;
+      return this;
+   }
+
+
+   public Boolean getEnableChildModule()
+   {
+      return enableChildModule;
+   }
+
+
+   public ExampleAppQBitConfig withEnableChildModule(Boolean enableChildModule)
+   {
+      this.enableChildModule = enableChildModule;
+      return this;
+   }
+
+
+   public String getSecurityKeyPrefix()
+   {
+      return securityKeyPrefix;
+   }
+
+
+   public ExampleAppQBitConfig withSecurityKeyPrefix(String securityKeyPrefix)
+   {
+      this.securityKeyPrefix = securityKeyPrefix;
+      return this;
+   }
+
+
+   public QCodeReference getOnEntityCreatedHandler()
+   {
+      return onEntityCreatedHandler;
+   }
+
+
+   public ExampleAppQBitConfig withOnEntityCreatedHandler(QCodeReference onEntityCreatedHandler)
+   {
+      this.onEntityCreatedHandler = onEntityCreatedHandler;
+      return this;
+   }
+
+
+   public QCodeReference getCustomValidationProvider()
+   {
+      return customValidationProvider;
+   }
+
+
+   public ExampleAppQBitConfig withCustomValidationProvider(QCodeReference customValidationProvider)
+   {
+      this.customValidationProvider = customValidationProvider;
+      return this;
+   }
+}
@@ -0,0 +1,175 @@
+/*******************************************************************************
+ ** Producer for the Example Application QBit.
+ **
+ ** Application QBits produce:
+ ** - QBitMetaData for identification
+ ** - QAppSection for UI navigation (REQUIRED)
+ ** - Tables, processes, widgets, and other metadata
+ ** - Security configuration
+ *******************************************************************************/
+package com.kingsrook.qbits.example;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerHelper;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
+import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.qbits.SourceQBitAware;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qbits.example.model.ExampleEntity;
+import com.kingsrook.qbits.example.model.ExampleChildEntity;
+
+
+public class ExampleAppQBitProducer implements QBitProducer
+{
+   public static final String GROUP_ID    = "com.kingsrook.qbits";
+   public static final String ARTIFACT_ID = "qbit-example-app";
+   public static final String VERSION     = "0.1.0";
+
+   private ExampleAppQBitConfig config;
+
+
+
+   /*******************************************************************************
+    ** Produce the QBit metadata into the QInstance.
+    *******************************************************************************/
+   @Override
+   public void produce(QInstance qInstance, String namespace) throws QException
+   {
+      /////////////////////////////////////////////////////////////////////////
+      // Validate configuration                                              //
+      /////////////////////////////////////////////////////////////////////////
+      List<String> errors = new ArrayList<>();
+      config.validate(qInstance, errors);
+      if(!errors.isEmpty())
+      {
+         throw new QException("Configuration errors: " + String.join(", ", errors));
+      }
+
+      /////////////////////////////////////////////////////////////////////////
+      // Create and register QBit identity                                   //
+      /////////////////////////////////////////////////////////////////////////
+      QBitMetaData qBitMetaData = new QBitMetaData()
+         .withGroupId(GROUP_ID)
+         .withArtifactId(ARTIFACT_ID)
+         .withVersion(VERSION)
+         .withNamespace(namespace)
+         .withConfig(config);
+      qInstance.addQBit(qBitMetaData);
+
+      /////////////////////////////////////////////////////////////////////////
+      // Discover and produce all component metadata                         //
+      /////////////////////////////////////////////////////////////////////////
+      List<MetaDataProducerInterface<?>> producers =
+         MetaDataProducerHelper.findProducers(getClass().getPackageName());
+
+      for(MetaDataProducerInterface<?> producer : producers)
+      {
+         ///////////////////////////////////////////////////////////////////////
+         // Skip disabled components                                         //
+         ///////////////////////////////////////////////////////////////////////
+         if(!isProducerEnabled(producer))
+         {
+            continue;
+         }
+
+         MetaDataProducerOutput output = producer.produce(qInstance);
+
+         ///////////////////////////////////////////////////////////////////////
+         // Apply table prefix if configured                                  //
+         ///////////////////////////////////////////////////////////////////////
+         if(output instanceof QTableMetaData table)
+         {
+            String prefixedName = config.applyPrefix(table.getName());
+            table.setName(prefixedName);
+            table.setBackendName(config.getBackendName());
+         }
+
+         ///////////////////////////////////////////////////////////////////////
+         // Mark scope for all SourceQBitAware outputs                        //
+         ///////////////////////////////////////////////////////////////////////
+         if(output instanceof SourceQBitAware sqa)
+         {
+            sqa.setSourceQBitName(qBitMetaData.getName());
+         }
+
+         output.addSelfToInstance(qInstance);
+      }
+
+      /////////////////////////////////////////////////////////////////////////
+      // Register QAppMetaData for UI navigation (REQUIRED for app QBits)    //
+      /////////////////////////////////////////////////////////////////////////
+      qInstance.addApp(produceApp(config, qBitMetaData.getName()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Produce the QAppMetaData for UI navigation.
+    **
+    ** This is REQUIRED for Application QBits - it defines how users navigate
+    ** to the tables, processes, and widgets in the UI.
+    *******************************************************************************/
+   private QAppMetaData produceApp(ExampleAppQBitConfig config, String qbitName)
+   {
+      List<String> tables = new ArrayList<>();
+      tables.add(config.applyPrefix(ExampleEntity.TABLE_NAME));
+
+      if(Boolean.TRUE.equals(config.getEnableChildModule()))
+      {
+         tables.add(config.applyPrefix(ExampleChildEntity.TABLE_NAME));
+      }
+
+      QAppSection section = new QAppSection()
+         .withName(config.applyPrefix("exampleSection"))
+         .withLabel("Example Application")
+         .withIcon(new QIcon().withName("dashboard"))
+         .withTables(tables);
+
+      return new QAppMetaData()
+         .withName(config.applyPrefix("exampleApp"))
+         .withLabel("Example Application")
+         .withIcon(new QIcon().withName("dashboard"))
+         .withSection(section);
+   }
+
+
+
+   /*******************************************************************************
+    ** Check if a producer should be enabled based on configuration.
+    *******************************************************************************/
+   private boolean isProducerEnabled(MetaDataProducerInterface<?> producer)
+   {
+      /////////////////////////////////////////////////////////////////////////
+      // Skip child entity if module disabled                                //
+      /////////////////////////////////////////////////////////////////////////
+      if(!Boolean.TRUE.equals(config.getEnableChildModule()))
+      {
+         if(producer.getClass().getSimpleName().contains("ExampleChildEntity"))
+         {
+            return false;
+         }
+      }
+      return true;
+   }
+
+
+
+   //////////////////////////////////////////////////////////////////////////////
+   // Fluent setters                                                           //
+   //////////////////////////////////////////////////////////////////////////////
+
+   public ExampleAppQBitProducer withConfig(ExampleAppQBitConfig config)
+   {
+      this.config = config;
+      return this;
+   }
+}
@@ -0,0 +1,159 @@
+/*******************************************************************************
+ ** Example child entity demonstrating parent-child relationships.
+ **
+ ** This entity shows:
+ ** - Foreign key relationship to parent entity
+ ** - Conditional inclusion via config toggle
+ *******************************************************************************/
+package com.kingsrook.qbits.example.model;
+
+
+import java.time.Instant;
+import com.kingsrook.qqq.backend.core.model.data.QField;
+import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.QMetaDataProducingEntity;
+
+
+@QMetaDataProducingEntity(producePossibleValueSource = true)
+public class ExampleChildEntity extends QRecordEntity
+{
+   public static final String TABLE_NAME = "exampleChildEntity";
+
+   @QField(isPrimaryKey = true)
+   private Integer id;
+
+   @QField(isRequired = true, possibleValueSourceName = "exampleEntity")
+   private Integer exampleEntityId;
+
+   @QField(isRequired = true, maxLength = 100)
+   private String name;
+
+   @QField(maxLength = 500)
+   private String description;
+
+   @QField
+   private Integer sortOrder;
+
+   @QField
+   private Boolean isActive = true;
+
+   @QField
+   private Instant createDate;
+
+   @QField
+   private Instant modifyDate;
+
+
+
+   //////////////////////////////////////////////////////////////////////////////
+   // Fluent setters                                                           //
+   //////////////////////////////////////////////////////////////////////////////
+
+   public ExampleChildEntity withId(Integer id)
+   {
+      this.id = id;
+      return this;
+   }
+
+
+   public ExampleChildEntity withExampleEntityId(Integer exampleEntityId)
+   {
+      this.exampleEntityId = exampleEntityId;
+      return this;
+   }
+
+
+   public ExampleChildEntity withName(String name)
+   {
+      this.name = name;
+      return this;
+   }
+
+
+   public ExampleChildEntity withDescription(String description)
+   {
+      this.description = description;
+      return this;
+   }
+
+
+   public ExampleChildEntity withSortOrder(Integer sortOrder)
+   {
+      this.sortOrder = sortOrder;
+      return this;
+   }
+
+
+   public ExampleChildEntity withIsActive(Boolean isActive)
+   {
+      this.isActive = isActive;
+      return this;
+   }
+
+
+   public ExampleChildEntity withCreateDate(Instant createDate)
+   {
+      this.createDate = createDate;
+      return this;
+   }
+
+
+   public ExampleChildEntity withModifyDate(Instant modifyDate)
+   {
+      this.modifyDate = modifyDate;
+      return this;
+   }
+
+
+
+   //////////////////////////////////////////////////////////////////////////////
+   // Getters                                                                  //
+   //////////////////////////////////////////////////////////////////////////////
+
+   public Integer getId()
+   {
+      return id;
+   }
+
+
+   public Integer getExampleEntityId()
+   {
+      return exampleEntityId;
+   }
+
+
+   public String getName()
+   {
+      return name;
+   }
+
+
+   public String getDescription()
+   {
+      return description;
+   }
+
+
+   public Integer getSortOrder()
+   {
+      return sortOrder;
+   }
+
+
+   public Boolean getIsActive()
+   {
+      return isActive;
+   }
+
+
+   public Instant getCreateDate()
+   {
+      return createDate;
+   }
+
+
+   public Instant getModifyDate()
+   {
+      return modifyDate;
+   }
+}
@@ -0,0 +1,145 @@
+/*******************************************************************************
+ ** Example entity for an Application QBit.
+ **
+ ** This entity demonstrates:
+ ** - Standard QQQ entity patterns
+ ** - PossibleValueSource generation
+ ** - Fields with various types and constraints
+ *******************************************************************************/
+package com.kingsrook.qbits.example.model;
+
+
+import java.time.Instant;
+import com.kingsrook.qqq.backend.core.model.data.QField;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.QMetaDataProducingEntity;
+
+
+@QMetaDataProducingEntity(producePossibleValueSource = true)
+public class ExampleEntity extends QRecordEntity
+{
+   public static final String TABLE_NAME = "exampleEntity";
+
+   @QField(isPrimaryKey = true)
+   private Integer id;
+
+   @QField(isRequired = true, maxLength = 100)
+   private String name;
+
+   @QField(maxLength = 500)
+   private String description;
+
+   @QField(label = "Status")
+   private String status;
+
+   @QField
+   private Boolean isActive = true;
+
+   @QField
+   private Instant createDate;
+
+   @QField
+   private Instant modifyDate;
+
+
+
+   //////////////////////////////////////////////////////////////////////////////
+   // Fluent setters                                                           //
+   //////////////////////////////////////////////////////////////////////////////
+
+   public ExampleEntity withId(Integer id)
+   {
+      this.id = id;
+      return this;
+   }
+
+
+   public ExampleEntity withName(String name)
+   {
+      this.name = name;
+      return this;
+   }
+
+
+   public ExampleEntity withDescription(String description)
+   {
+      this.description = description;
+      return this;
+   }
+
+
+   public ExampleEntity withStatus(String status)
+   {
+      this.status = status;
+      return this;
+   }
+
+
+   public ExampleEntity withIsActive(Boolean isActive)
+   {
+      this.isActive = isActive;
+      return this;
+   }
+
+
+   public ExampleEntity withCreateDate(Instant createDate)
+   {
+      this.createDate = createDate;
+      return this;
+   }
+
+
+   public ExampleEntity withModifyDate(Instant modifyDate)
+   {
+      this.modifyDate = modifyDate;
+      return this;
+   }
+
+
+
+   //////////////////////////////////////////////////////////////////////////////
+   // Getters                                                                  //
+   //////////////////////////////////////////////////////////////////////////////
+
+   public Integer getId()
+   {
+      return id;
+   }
+
+
+   public String getName()
+   {
+      return name;
+   }
+
+
+   public String getDescription()
+   {
+      return description;
+   }
+
+
+   public String getStatus()
+   {
+      return status;
+   }
+
+
+   public Boolean getIsActive()
+   {
+      return isActive;
+   }
+
+
+   public Instant getCreateDate()
+   {
+      return createDate;
+   }
+
+
+   public Instant getModifyDate()
+   {
+      return modifyDate;
+   }
+}
@@ -0,0 +1,46 @@
+/*******************************************************************************
+ ** MetaData producer for the example process.
+ *******************************************************************************/
+package com.kingsrook.qbits.example.processes;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFunctionInputMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qbits.example.model.ExampleEntity;
+
+
+public class ExampleProcessMetaDataProducer implements MetaDataProducerInterface<QProcessMetaData>
+{
+   public static final String NAME = "exampleProcess";
+
+
+
+   /*******************************************************************************
+    ** Produce the process metadata.
+    *******************************************************************************/
+   @Override
+   public QProcessMetaData produce(QInstance qInstance) throws QException
+   {
+      return new QProcessMetaData()
+         .withName(NAME)
+         .withLabel("Example Process")
+         .withTableName(ExampleEntity.TABLE_NAME)
+         .withStepList(List.of(
+            new QBackendStepMetaData()
+               .withName("process")
+               .withCode(new QCodeReference(ExampleProcessStep.class))
+               .withInputData(new QFunctionInputMetaData()
+                  .withField(new QFieldMetaData("confirmAction", QFieldType.BOOLEAN)
+                     .withLabel("Confirm Action")
+                     .withDefaultValue(false)))
+         ));
+   }
+}
@@ -0,0 +1,67 @@
+/*******************************************************************************
+ ** Example process step demonstrating business logic implementation.
+ **
+ ** This shows:
+ ** - Standard process step patterns
+ ** - Input/output handling
+ ** - Logging conventions
+ *******************************************************************************/
+package com.kingsrook.qbits.example.processes;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+public class ExampleProcessStep extends AbstractTransformStep
+{
+   private static final QLogger LOG = QLogger.getLogger(ExampleProcessStep.class);
+
+
+
+   /*******************************************************************************
+    ** Run the process step.
+    *******************************************************************************/
+   @Override
+   public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+   {
+      List<QRecord> records = input.getRecords();
+      LOG.info("Processing records", logPair("count", records.size()));
+
+      for(QRecord record : records)
+      {
+         ///////////////////////////////////////////////////////////////////////
+         // Example business logic - update status                            //
+         ///////////////////////////////////////////////////////////////////////
+         String currentStatus = record.getValueString("status");
+         if("PENDING".equals(currentStatus))
+         {
+            record.setValue("status", "PROCESSED");
+         }
+
+         output.addRecord(record);
+      }
+
+      LOG.info("Processing complete", logPair("processed", records.size()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Return the process summary. Override this method in subclasses to provide
+    ** meaningful summary lines for the result screen.
+    *******************************************************************************/
+   @Override
+   public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput runBackendStepOutput, boolean isForResultScreen)
+   {
+      return (new ArrayList<>());
+   }
+}
@@ -0,0 +1,35 @@
+/*******************************************************************************
+ ** MetaData producer for an example dashboard widget.
+ **
+ ** Widgets provide dashboard components for Application QBits.
+ *******************************************************************************/
+package com.kingsrook.qbits.example.widgets;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.WidgetType;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
+
+
+public class ExampleDashboardWidgetMetaDataProducer implements MetaDataProducerInterface<QWidgetMetaData>
+{
+   public static final String NAME = "exampleDashboardWidget";
+
+
+
+   /*******************************************************************************
+    ** Produce the widget metadata.
+    *******************************************************************************/
+   @Override
+   public QWidgetMetaData produce(QInstance qInstance) throws QException
+   {
+      return new QWidgetMetaData()
+         .withName(NAME)
+         .withLabel("Example Dashboard")
+         .withType(WidgetType.STATISTICS.getType())
+         .withCodeReference(new QCodeReference(ExampleDashboardWidgetRenderer.class));
+   }
+}
@@ -0,0 +1,33 @@
+/*******************************************************************************
+ ** Renderer for the example dashboard widget.
+ **
+ ** This class produces the data displayed in the widget.
+ *******************************************************************************/
+package com.kingsrook.qbits.example.widgets;
+
+
+import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetOutput;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.StatisticsData;
+
+
+public class ExampleDashboardWidgetRenderer extends AbstractWidgetRenderer
+{
+   /*******************************************************************************
+    ** Render the widget data.
+    *******************************************************************************/
+   @Override
+   public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+   {
+      /////////////////////////////////////////////////////////////////////////
+      // Add chart data, counts, or other dashboard information here         //
+      /////////////////////////////////////////////////////////////////////////
+      StatisticsData data = new StatisticsData()
+         .withCount(0)
+         .withCountContext("Total items");
+
+      return (new RenderWidgetOutput(data));
+   }
+}
@@ -1,101 +0,0 @@
-/*
- * QQQ - Low-code Application Framework for Engineers.
- * Copyright (C) 2021-2025.  Kingsrook, LLC
- * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
- * contact@kingsrook.com
- * https://github.com/Kingsrook/
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package com.kingsrook.qbits.filegateway;
-
-
-import com.kingsrook.qqq.backend.core.model.metadata.producers.MetaDataCustomizerInterface;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitConfig;
-import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
-
-
-/*******************************************************************************
- ** Configuration for the file-gateway qbit.
- *******************************************************************************/
-public class FileGatewayQBitConfig implements QBitConfig
-{
-   private MetaDataCustomizerInterface<QTableMetaData> tableMetaDataCustomizer;
-   private boolean sftpEnabled = false;
-   private int     sftpPort    = 2222;
-
-
-
-   /*******************************************************************************
-    ** Getter for the optional table customizer.
-    *******************************************************************************/
-   @Override
-   public MetaDataCustomizerInterface<QTableMetaData> getTableMetaDataCustomizer()
-   {
-      return (tableMetaDataCustomizer);
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for the optional table customizer.
-    *******************************************************************************/
-   public FileGatewayQBitConfig withTableMetaDataCustomizer(MetaDataCustomizerInterface<QTableMetaData> tableMetaDataCustomizer)
-   {
-      this.tableMetaDataCustomizer = tableMetaDataCustomizer;
-      return (this);
-   }
-
-
-
-   /*******************************************************************************
-    ** Whether this process runs the SFTP server (only the gateway deployment does).
-    *******************************************************************************/
-   public boolean getSftpEnabled()
-   {
-      return (sftpEnabled);
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for whether this process runs the SFTP server.
-    *******************************************************************************/
-   public FileGatewayQBitConfig withSftpEnabled(boolean sftpEnabled)
-   {
-      this.sftpEnabled = sftpEnabled;
-      return (this);
-   }
-
-
-
-   /*******************************************************************************
-    ** Getter for the SFTP listen port (default 2222).
-    *******************************************************************************/
-   public int getSftpPort()
-   {
-      return (sftpPort);
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for the SFTP listen port.
-    *******************************************************************************/
-   public FileGatewayQBitConfig withSftpPort(int sftpPort)
-   {
-      this.sftpPort = sftpPort;
-      return (this);
-   }
-}
@@ -1,120 +0,0 @@
-/*
- * QQQ - Low-code Application Framework for Engineers.
- * Copyright (C) 2021-2025.  Kingsrook, LLC
- * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
- * contact@kingsrook.com
- * https://github.com/Kingsrook/
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package com.kingsrook.qbits.filegateway;
-
-
-import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
-import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaDataProducer;
-
-
-/*******************************************************************************
- ** Entry point for the file-gateway qbit; no tables are produced yet.
- *******************************************************************************/
-public class FileGatewayQBitProducer implements QBitMetaDataProducer<FileGatewayQBitConfig>
-{
-   public static final String GROUP_ID    = "com.kingsrook.qbits";
-   public static final String ARTIFACT_ID = "qbit-file-gateway";
-   public static final String VERSION     = "0.1.0";
-
-   private FileGatewayQBitConfig qBitConfig;
-   private String namespace;
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for the config.
-    *******************************************************************************/
-   public FileGatewayQBitProducer withQBitConfig(FileGatewayQBitConfig config)
-   {
-      this.qBitConfig = config;
-      return (this);
-   }
-
-
-
-   /*******************************************************************************
-    ** Getter for the config.
-    *******************************************************************************/
-   @Override
-   public FileGatewayQBitConfig getQBitConfig()
-   {
-      return (qBitConfig);
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for the namespace.
-    *******************************************************************************/
-   public FileGatewayQBitProducer withNamespace(String namespace)
-   {
-      this.namespace = namespace;
-      return (this);
-   }
-
-
-
-   /*******************************************************************************
-    ** Getter for the namespace.
-    *******************************************************************************/
-   @Override
-   public String getNamespace()
-   {
-      return (namespace);
-   }
-
-
-
-   /*******************************************************************************
-    ** Identity and configuration of this qbit.
-    *******************************************************************************/
-   @Override
-   public QBitMetaData getQBitMetaData()
-   {
-      return (new QBitMetaData().withGroupId(GROUP_ID).withArtifactId(ARTIFACT_ID).withVersion(VERSION).withNamespace(namespace).withConfig(qBitConfig));
-   }
-
-
-
-   /*******************************************************************************
-    ** Package-scanned producers have no config: skip them.
-    *******************************************************************************/
-   @Override
-   public boolean isEnabled()
-   {
-      return (qBitConfig != null);
-   }
-
-
-
-   /*******************************************************************************
-    ** Register this qbit and return its metadata, without producing tables.
-    *******************************************************************************/
-   @Override
-   public MetaDataProducerMultiOutput produce(QInstance qInstance)
-   {
-      QBitMetaData qBit = getQBitMetaData();
-      qInstance.addQBit(qBit);
-      return (new MetaDataProducerMultiOutput().with(qBit));
-   }
-}
@@ -1,93 +0,0 @@
-/*
- * QQQ - Low-code Application Framework for Engineers.
- * Copyright (C) 2021-2025.  Kingsrook, LLC
- * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
- * contact@kingsrook.com
- * https://github.com/Kingsrook/
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package com.kingsrook.qbits.filegateway;
-
-
-import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
-import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
-import com.kingsrook.qqq.backend.core.model.metadata.producers.MetaDataCustomizerInterface;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
-import org.junit.jupiter.api.Test;
-import static org.assertj.core.api.Assertions.assertThat;
-
-
-/*******************************************************************************
- ** Verify the scaffold's registration and configuration contract.
- *******************************************************************************/
-class FileGatewayQBitProducerTest
-{
-   /*******************************************************************************
-    ** Produce the identity and exact config into an otherwise empty instance.
-    *******************************************************************************/
-   @Test
-   void producesQBitWithoutTables()
-   {
-      QInstance instance = new QInstance();
-      FileGatewayQBitConfig config = new FileGatewayQBitConfig();
-      FileGatewayQBitProducer producer = new FileGatewayQBitProducer().withQBitConfig(config);
-      MetaDataProducerMultiOutput output = producer.produce(instance);
-      QBitMetaData qBit = instance.getQBits().get("com.kingsrook.qbits:qbit-file-gateway");
-
-      assertThat(qBit).isNotNull();
-      assertThat(qBit.getGroupId()).isEqualTo("com.kingsrook.qbits");
-      assertThat(qBit.getArtifactId()).isEqualTo("qbit-file-gateway");
-      assertThat(qBit.getVersion()).isEqualTo("0.1.0");
-      assertThat(qBit.getConfig()).isSameAs(config);
-      assertThat(producer.getQBitConfig()).isSameAs(config);
-      assertThat(producer.isEnabled()).isTrue();
-      assertThat(producer.getNamespace()).isNull();
-      assertThat(output.getEach(QBitMetaData.class)).containsExactly(qBit);
-      assertThat(output.getEach(QTableMetaData.class)).isEmpty();
-      assertThat(instance.getTables()).isEmpty();
-      assertThat(config.getSftpEnabled()).isFalse();
-      assertThat(config.getSftpPort()).isEqualTo(2222);
-      assertThat(config.getTableMetaDataCustomizer()).isNull();
-   }
-
-
-
-   /*******************************************************************************
-    ** Configured instances may be namespaced; unconfigured scanning is disabled.
-    *******************************************************************************/
-   @Test
-   void supportsNamespacedConfiguration()
-   {
-      assertThat(new FileGatewayQBitProducer().isEnabled()).isFalse();
-      MetaDataCustomizerInterface<QTableMetaData> customizer = (instance, table) -> table;
-      FileGatewayQBitConfig config = new FileGatewayQBitConfig()
-         .withTableMetaDataCustomizer(customizer)
-         .withSftpEnabled(true)
-         .withSftpPort(2022);
-      FileGatewayQBitProducer producer = new FileGatewayQBitProducer()
-         .withQBitConfig(config)
-         .withNamespace("test");
-      QInstance instance = new QInstance();
-      producer.produce(instance);
-
-      assertThat(producer.getNamespace()).isEqualTo("test");
-      assertThat(instance.getQBits().get("com.kingsrook.qbits:qbit-file-gateway:test").getConfig()).isSameAs(config);
-      assertThat(config.getTableMetaDataCustomizer()).isSameAs(customizer);
-      assertThat(config.getSftpEnabled()).isTrue();
-      assertThat(config.getSftpPort()).isEqualTo(2022);
-      assertThat(instance.getTables()).isEmpty();
-   }
-}
Author	SHA1	Message	Date
forge-recovery	43bcb48e84	ci: enroll shared Gitea lifecycle QRun-IO/ci-policy: ci / fork-guard (push) Skipped Details QRun-IO/ci-policy: ci / head-profile (push) Skipped Details QRun-IO/ci-policy: ci / application-template-0 (push) Skipped Details QRun-IO/ci-policy: ci / gradle-1 (push) Skipped Details QRun-IO/ci-policy: ci / java-docker-3 (push) Skipped Details QRun-IO/ci-policy: ci / java-docker-4 (push) Skipped Details QRun-IO/ci-policy: ci / java-frontend-browser-5 (push) Skipped Details QRun-IO/ci-policy: ci / java-maven-7 (push) Skipped Details QRun-IO/ci-policy: ci / node-8 (push) Skipped Details QRun-IO/ci-policy: ci / node-9 (push) Skipped Details QRun-IO/ci-policy: ci / node-10 (push) Skipped Details QRun-IO/ci-policy: ci / node-playwright-11 (push) Skipped Details QRun-IO/ci-policy: ci / repository-policy-12 (push) Skipped Details QRun-IO/ci-policy: ci / source-config-13 (push) Skipped Details QRun-IO/ci-policy: ci / source-config-14 (push) Skipped Details QRun-IO/ci-policy: ci / not-enrolled (push) Skipped Details QRun-IO/ci-policy: native / fork-deny (push) Skipped Details QRun-IO/ci-policy: native / dotnet-0 (push) Skipped Details Shared Java Maven CI / secrets (push) Successful in 15s Details QRun-IO/ci-policy: Shared Java Maven CI / secrets (push) Successful in 15s Details QRun-IO/ci-policy: ci / repository-policy (push) Skipped Details QRun-IO/ci-policy: ci / java-core-2-head (push) Skipped Details QRun-IO/ci-policy: ci / java-docker-3-head (push) Skipped Details QRun-IO/ci-policy: ci / java-maven-6-head (push) Skipped Details QRun-IO/ci-policy: ci / java-maven-7-head (push) Skipped Details QRun-IO/ci-policy: native / native-result (push) Successful in 6s Details Shared Java Maven CI / verify (push) Successful in 53s Details Shared Java Maven CI / gate (push) Successful in 14s Details qrun-release / release (push) Successful in 1h57m26s Details qrun-release / postpublish (push) Skipped Details QRun-IO/ci-policy: Shared Java Maven CI / verify (push) Successful in 52s Details QRun-IO/ci-policy: Shared Java Maven CI / gate (push) Successful in 11s Details QRun-IO/ci-policy: ci / java-maven-6 (push) Successful in 1h58m12s Details QRun-IO/ci-policy: ci / ci-result (push) Successful in 4s Details	2026-11-02 18:58:41 +00:00
forge-recovery Claude Sonnet 5.5 Codex	63e29d4af7	ci: add the isolated postpublish job to the QRun release caller QRun-IO/ci-policy: ci / fork-guard (pull_request) Skipped Details QRun-IO/ci-policy: ci / head-profile (pull_request) Skipped Details QRun-IO/ci-policy: ci / application-template-0 (pull_request) Skipped Details QRun-IO/ci-policy: ci / gradle-1 (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-docker-3 (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-docker-4 (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-frontend-browser-5 (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-maven-7 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-8 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-9 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-10 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-playwright-11 (pull_request) Skipped Details QRun-IO/ci-policy: ci / repository-policy-12 (pull_request) Skipped Details QRun-IO/ci-policy: ci / source-config-13 (pull_request) Skipped Details QRun-IO/ci-policy: ci / source-config-14 (pull_request) Skipped Details QRun-IO/ci-policy: ci / not-enrolled (pull_request) Skipped Details QRun-IO/ci-policy: native / fork-deny (pull_request) Skipped Details QRun-IO/ci-policy: native / dotnet-0 (pull_request) Skipped Details Shared Java Maven CI / secrets (push) Successful in 18s Details QRun-IO/ci-policy: native / native-result (pull_request) Successful in 6s Details QRun-IO/ci-policy: Shared Java Maven CI / secrets (pull_request) Successful in 18s Details QRun-IO/ci-policy: ci / repository-policy (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-core-2-head (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-docker-3-head (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-maven-6-head (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-maven-7-head (pull_request) Skipped Details Shared Java Maven CI / gate (push) Canceled after 0s Details Shared Java Maven CI / verify (push) Canceled after 0s Details qrun-release / release (push) Canceled after 2h46m6s Details qrun-release / postpublish (push) Canceled after 0s Details QRun-IO/ci-policy: Shared Java Maven CI / verify (pull_request) Successful in 42s Details QRun-IO/ci-policy: Shared Java Maven CI / gate (pull_request) Successful in 9s Details QRun-IO/ci-policy: ci / java-maven-6 (pull_request) Successful in 2h58m13s Details QRun-IO/ci-policy: ci / ci-result (pull_request) Successful in 3s Details Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Co-Authored-By: Codex <noreply@openai.com>	2026-11-02 15:49:30 +00:00
forge-recovery Claude Sonnet 5.5 Codex	6ab5872831	ci: move the QRun release caller to the thin v2 contract QRun-IO/ci-policy: Shared Java Maven CI / gate (pull_request) Canceled after 0s Details QRun-IO/ci-policy: ci / java-maven-4 (pull_request) Canceled after 58m23s Details Shared Java Maven CI / gate (push) Canceled after 0s Details Shared Java Maven CI / verify (push) Canceled after 0s Details qrun-release / release (push) Canceled after 58m37s Details QRun-IO/ci-policy: ci / fork-guard (pull_request) Skipped Details QRun-IO/ci-policy: ci / application-template-0 (pull_request) Skipped Details QRun-IO/ci-policy: ci / gradle-1 (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-docker-2 (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-frontend-browser-3 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-5 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-6 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-7 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-playwright-8 (pull_request) Skipped Details QRun-IO/ci-policy: ci / source-config-9 (pull_request) Skipped Details QRun-IO/ci-policy: ci / not-enrolled (pull_request) Skipped Details QRun-IO/ci-policy: native / fork-deny (pull_request) Skipped Details QRun-IO/ci-policy: native / dotnet-0 (pull_request) Skipped Details QRun-IO/ci-policy: ci / ci-result (pull_request) Failing after 5s Details Shared Java Maven CI / secrets (push) Successful in 21s Details QRun-IO/ci-policy: Shared Java Maven CI / secrets (pull_request) Successful in 18s Details QRun-IO/ci-policy: Shared Java Maven CI / verify (pull_request) Failing after 1m17s Details QRun-IO/ci-policy: native / native-result (pull_request) Successful in 7s Details Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Co-Authored-By: Codex <noreply@openai.com>	2026-11-02 06:18:22 +00:00
forge-recoveryandCodex	086eea16c1	ci: add the identical QRun release caller QRun-IO/ci-policy: ci / fork-guard (pull_request) Skipped Details QRun-IO/ci-policy: ci / application-template-0 (pull_request) Skipped Details QRun-IO/ci-policy: ci / gradle-1 (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-docker-2 (pull_request) Skipped Details QRun-IO/ci-policy: ci / java-frontend-browser-3 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-5 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-6 (pull_request) Skipped Details QRun-IO/ci-policy: ci / node-playwright-7 (pull_request) Skipped Details QRun-IO/ci-policy: ci / source-config-8 (pull_request) Skipped Details QRun-IO/ci-policy: ci / not-enrolled (pull_request) Skipped Details QRun-IO/ci-policy: Shared Java Maven CI / verify (pull_request) Failing after 1m19s Details QRun-IO/ci-policy: Shared Java Maven CI / secrets (pull_request) Successful in 22s Details QRun-IO/ci-policy: Shared Java Maven CI / gate (pull_request) Failing after 0s Details QRun-IO/ci-policy: ci / java-maven-4 (pull_request) Failing after 9m2s Details QRun-IO/ci-policy: ci / ci-result (pull_request) Failing after 1s Details Co-Authored-By: Codex <noreply@openai.com>	2026-11-02 04:11:28 +00:00
james.maesandCodex	8e8076ee40	ci: enroll in the shared QQQ orb (#32 ) Co-authored-by: Codex <noreply@openai.com>	2026-10-21 19:52:27 -05:00
james.maesandCodex	3ef965e8a6	ci: use the shared orb pipeline on main (#27 ) * ci: use the shared orb pipeline on main Co-Authored-By: Codex <noreply@openai.com> * ci: use the shared branch-aware CodeQL worker Co-Authored-By: Codex <noreply@openai.com> --------- Co-authored-by: Codex <noreply@openai.com>	2026-10-21 09:55:07 -05:00