ci: centralize QBit source scanning

Co-Authored-By: Codex <noreply@openai.com>

.circleci/config.yml

@@ -1,60 +1,14 @@
 version: 2.1
-
+setup: true
 orbs:
-   qqq-orb: kingsrook/qqq-orb@0.6.9
-
-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.7.12
 workflows:
-   test_only:
-      jobs:
-         - qqq-orb/mvn_test_only:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              filters:
-                 branches:
-                    ignore: /(develop|release\/.*)/
-
-   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+$/]
+  setup:
+    jobs:
+    - qqq-orb/generate_pipeline:
+        orb_version: 0.7.12
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            only: /^v\d+\.\d+\.\d+$/

.github/workflows/codeql.yml

@@ -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@c288a8864fe9054f68410e1d78f5863aea4c4d22

.github/workflows/release-rc.yml

@@ -1,25 +1,74 @@
-# 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:
+'on':
   workflow_dispatch:
     inputs:
       dry_run:
-        description: Print the plan without merging or creating branches
+        description: Plan a cut without changing release state
         type: boolean
         default: false
+      finalize:
+        description: Retry finalization of an existing cut; do not cut another RC
+        type: boolean
+        default: false
+      recover:
+        description: Recover the same published RC after a deployment timeout; never
+          reupload
+        type: boolean
+        default: false
+      circle_build:
+        description: Original Circle publisher build number (recovery only)
+        type: string
+        default: ''
+      merge_sha:
+        description: Existing cut merge_sha (finalize retry only)
+        type: string
+        default: ''
+      bump_sha:
+        description: Existing cut bump_sha (finalize retry only)
+        type: string
+        default: ''
+      branch:
+        description: Existing cut branch (finalize retry only)
+        type: string
+        default: ''
+      version:
+        description: Existing cut version (finalize retry only)
+        type: string
+        default: ''
   pull_request:
-    types: [closed]
-    branches: [develop]
-
+    types:
+    - closed
+    branches:
+    - develop
+  repository_dispatch:
+    types:
+    - qbit-rc-published
 permissions:
   contents: write
-
+  actions: read
+  checks: read
 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
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
+      || (github.event_name == 'pull_request' && github.event.pull_request.merged
+      == true && github.event.pull_request.base.ref == 'develop' && contains(github.event.pull_request.labels.*.name,
+      'release:rc'))
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-release-rc.yml@cc30f599e63c8e41629c99d23395bac1adb8bc44
     with:
-      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
+      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false
+        }}
+      finalize: ${{ github.event_name == 'repository_dispatch' || (github.event_name
+        == 'workflow_dispatch' && inputs.finalize) }}
+      recover: ${{ github.event_name == 'workflow_dispatch' && inputs.recover || false
+        }}
+      circle_build: ${{ github.event_name == 'workflow_dispatch' && inputs.circle_build
+        || '' }}
+      merge_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.merge_sha
+        || inputs.merge_sha || '' }}
+      bump_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.bump_sha
+        || inputs.bump_sha || '' }}
+      branch: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch
+        || inputs.branch || '' }}
+      version: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.version
+        || inputs.version || '' }}
+    secrets: inherit

.qqq-ci.yml

@@ -0,0 +1,16 @@
+profile: qbit
+orb_version: 0.7.12
+default_branch: develop
+java_version: '21'
+browsers: true
+api_checks: false
+docs_only: false
+release_on_main: false
+release_tag_policy: stable
+test_branch_policy: non-release
+publish:
+  snapshot: true
+  release_candidate: true
+  release: true
+  asciidoc: false
+release_completion: true

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased / 0.2.0
 
+- Read the CRM QBit metadata version from the Maven-filtered artifact version so release metadata matches the build.
+
+- Adopt QQQ 4.1.0-RC.7 native help bundles, replacing the RC.6 stand-in loader with host-neutral CRM help, live references and the core coverage gate.
+
 - Upgrade to Java 21, QQQ 4.1.0-RC.6 and qbit-build-parent 2.1.2.
 - Add Maven wrapper, CI configuration, architecture guardrails and coverage gates.
 - Rename tables, joins, widgets and CRM processes to `crm_` snake_case, with inferred snake_case SQL columns.

README.md

@@ -174,6 +174,24 @@ Later phases complete the following behavior:
 
 The later intake APIs, public subscription routes, collaboration integration, real email transport, durable jobs and the remaining P2 security/integration work are not part of this phase.
 
+## In-app help
+
+CRM registers [help/qbit-crm.yaml](src/main/resources/help/qbit-crm.yaml) from
+`CrmQBitProducer`. The bundle uses the `QBIT` layer and the current artifact version.
+Registration only adds metadata and works without a `helpContent` table; QQQ's
+startup sync skips hosts without that table. Hosts with help storage load help
+and call `HelpBundles.syncOnStartup(qInstance)` after defining their metadata.
+
+To customize wording or describe your deployment, register a separate `HOST`
+bundle with the same entry keys (and roles). HOST text takes precedence over QBIT
+text; the sync preserves user edits for review. Keep live `{{...}}` references
+when referring to labels, defaults or enum values.
+
+`CrmPublicationHelpTest` runs `HelpBundleAssertions` against the produced and
+validated CRM instance, including generated record actions, and also requires
+widget and possible-value help. `CrmTablesGuardrailTest` checks every table's
+row-creation guidance. Run both through `./mvnw -q verify`.
+
 ## Source layout
 
 `CrmQBitProducer` discovers entity, process and widget producers. `core/` holds contacts, companies, forms, lists and consent; `deals/`, `activities/`, `email/` and `scoring/` hold their respective metadata and behavior. `actions/` defines the streamed record actions and their inputs/summaries. `security/` defines permissions, `sync/` holds external mappings and currency utilities, and `widgets/` contains widget producers/renderers. SQL is shipped under `src/main/resources/db/liquibase/qbit-crm/`.

pom.xml

@@ -22,7 +22,7 @@
 <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.2.0-RC.4</revision>
+      <revision>0.2.0-SNAPSHOT</revision>
       <maven.compiler.source>21</maven.compiler.source>
       <maven.compiler.target>21</maven.compiler.target>
       <jacoco.version>0.8.15</jacoco.version>
@@ -135,7 +135,35 @@
    </dependencies>
 
    <build>
+      <resources>
+         <!-- help bundles carry the artifact version (QQQ help bundle provenance) -->
+         <resource>
+            <directory>src/main/resources</directory>
+            <filtering>true</filtering>
+            <includes>
+               <include>help/*.yaml</include>
+               <include>qbit-crm.properties</include>
+            </includes>
+         </resource>
+         <resource>
+            <directory>src/main/resources</directory>
+            <filtering>false</filtering>
+            <excludes>
+               <exclude>help/*.yaml</exclude>
+               <exclude>qbit-crm.properties</exclude>
+            </excludes>
+         </resource>
+      </resources>
       <plugins>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+               <systemPropertyVariables combine.children="append">
+                  <qbit.artifactVersion>${project.version}</qbit.artifactVersion>
+               </systemPropertyVariables>
+            </configuration>
+         </plugin>
          <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-checkstyle-plugin</artifactId>
@@ -204,14 +232,14 @@
    <profiles>
       <!-- Built against qqq 4.1 (QBitMetaDataProducer). Until qbit-build-parent  -->
       <!-- imports the released 4.1 BOM, this profile is active by default and     -->
-      <!-- imports qqq-bom-pom 4.1.0-RC.6 ahead of the parent's 4.0.0 BOM.         -->
+      <!-- imports qqq-bom-pom 4.1.0-RC.7 ahead of the parent's 4.0.0 BOM.         -->
       <profile>
          <id>qqq-snapshot</id>
          <activation>
             <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
-            <qqq.snapshot.version>4.1.0-RC.6</qqq.snapshot.version>
+            <qqq.snapshot.version>4.1.0-RC.7</qqq.snapshot.version>
          </properties>
          <dependencyManagement>
             <dependencies>

src/main/java/com/kingsrook/qbits/crm/CrmQBitProducer.java

@@ -26,9 +26,12 @@
 package com.kingsrook.qbits.crm;
 
 
+import java.io.IOException;
+import java.io.InputStream;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Properties;
 import com.kingsrook.qbits.crm.activities.customizers.ActivityLastDateCustomizer;
 import com.kingsrook.qbits.crm.activities.model.Activity;
 import com.kingsrook.qbits.crm.core.customizers.CurrencyRateDateCustomizer;
@@ -43,7 +46,6 @@ import com.kingsrook.qbits.crm.deals.customizers.DealStageChangeCustomizer;
 import com.kingsrook.qbits.crm.deals.model.Deal;
 import com.kingsrook.qbits.crm.deals.model.DealProduct;
 import com.kingsrook.qbits.crm.email.CrmEmailProcessIdentity;
-import com.kingsrook.qbits.crm.help.CrmHelpBundleStandIn;
 import com.kingsrook.qbits.crm.scoring.AutoAssignCustomizer;
 import com.kingsrook.qbits.crm.security.CrmDataPolicy;
 import com.kingsrook.qbits.crm.security.CrmPermissions;
@@ -66,6 +68,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordFeature
 import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordFeaturesMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordOwnership;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
@@ -86,12 +89,40 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
 {
    public static final String GROUP_ID    = "com.kingsrook.qbits";
    public static final String ARTIFACT_ID = "crm";
-   public static final String VERSION     = "0.2.0-SNAPSHOT";
+   public static final String VERSION     = loadVersion();
 
    private CrmQBitConfig qBitConfig;
 
 
 
+   /*******************************************************************************
+    ** Read the artifact version from the Maven-filtered properties resource.
+    *******************************************************************************/
+   private static String loadVersion()
+   {
+      try(InputStream inputStream = CrmQBitProducer.class.getClassLoader().getResourceAsStream("qbit-crm.properties"))
+      {
+         if(inputStream == null)
+         {
+            throw new IllegalStateException("Missing qbit-crm.properties; build with Maven to provide the artifact version");
+         }
+         Properties properties = new Properties();
+         properties.load(inputStream);
+         String version = properties.getProperty("version");
+         if(version == null || version.isBlank() || version.contains("${"))
+         {
+            throw new IllegalStateException("Missing or unfiltered version in qbit-crm.properties; build with Maven to provide the artifact version");
+         }
+         return (version);
+      }
+      catch(IOException e)
+      {
+         throw new IllegalStateException("Could not read artifact version from qbit-crm.properties", e);
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Produce the QBitMetaData for the CRM QBit.
     *******************************************************************************/
@@ -384,7 +415,8 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
       }
       qInstance.withProcessLifecycleListener(new QCodeReference(CrmEmailProcessIdentity.class));
       registerHooks(qInstance);
-      CrmHelpBundleStandIn.apply(output);
+      // Registration is metadata-only; core startup sync guards hosts without helpContent.
+      HelpBundles.register(qInstance, "help/qbit-crm.yaml");
       return (output);
    }
 

src/main/java/com/kingsrook/qbits/crm/help/CrmHelpBundleStandIn.java

@@ -1,135 +0,0 @@
-/*
- * 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.
- */
-
-package com.kingsrook.qbits.crm.help;
-
-
-import java.io.IOException;
-import java.io.InputStream;
-import java.util.LinkedHashMap;
-import java.util.Map;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
-import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
-import com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent;
-import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
-
-
-/*******************************************************************************
- ** STAND-IN(core=QRun-IO/qqq#1198, removeBy=4.1.0-RC.9)
- ** Load the future bundle format with core's Jackson YAML parser. RC.6 lacks
- ** process/PVS help slots: action content is applied to frontend steps instead;
- ** enum entries remain in the bundle for the central loader.
- *******************************************************************************/
-public final class CrmHelpBundleStandIn
-{
-   /*******************************************************************************
-    ** Utility class.
-    *******************************************************************************/
-   private CrmHelpBundleStandIn()
-   {
-   }
-
-
-   /*******************************************************************************
-    ** Validate the resource eagerly so malformed shipped help fails production.
-    *******************************************************************************/
-   public static Map<String, JsonNode> entries() throws QException
-   {
-      try(InputStream stream = CrmHelpBundleStandIn.class.getResourceAsStream("/help/qbit-crm.yaml"))
-      {
-         JsonNode bundle = new ObjectMapper(new YAMLFactory()).readTree(stream);
-         if(!"qbit-crm".equals(bundle.path("bundle").asText()) || bundle.path("version").asInt() != 1
-            || !"QBIT".equals(bundle.path("layer").asText()))
-         {
-            throw (new IOException("Invalid CRM bundle header"));
-         }
-         Map<String, JsonNode> entries = new LinkedHashMap<>();
-         for(JsonNode entry : bundle.path("entries"))
-         {
-            String key = entry.path("key").asText();
-            if(key.isBlank() || entry.path("summary").asText().isBlank() || entry.path("summary").asText().length() > 120
-               || entry.path("content").asText().isBlank() || entries.put(key, entry) != null)
-            {
-               throw (new IOException("Invalid or duplicate help entry: " + key));
-            }
-         }
-         return (entries);
-      }
-      catch(IOException | IllegalArgumentException e)
-      {
-         throw (new QException("Could not load help/qbit-crm.yaml", e));
-      }
-   }
-
-
-   /*******************************************************************************
-    ** Apply help to the objects produced by this QBit only.
-    *******************************************************************************/
-   public static void apply(MetaDataProducerMultiOutput output) throws QException
-   {
-      Map<String, JsonNode> entries = entries();
-      for(QTableMetaData table : output.getEach(QTableMetaData.class))
-      {
-         table.withHelpContent("help", content(entries, "table:" + table.getName() + ";slot:help"));
-         for(var field : table.getFields().values())
-         {
-            String key = "table:" + table.getName() + ";field:" + field.getName();
-            if(entries.containsKey(key))
-            {
-               field.withHelpContent(content(entries, key));
-            }
-         }
-      }
-      for(QProcessMetaData process : output.getEach(QProcessMetaData.class))
-      {
-         QHelpContent help = content(entries, "process:" + process.getName() + ";slot:help");
-         for(var step : process.getStepList())
-         {
-            if(step instanceof QFrontendStepMetaData frontend)
-            {
-               frontend.withHelpContent(help.clone());
-            }
-         }
-      }
-      for(QAppMetaData app : output.getEach(QAppMetaData.class))
-      {
-         app.withHelpContent("help", content(entries, "app:" + app.getName() + ";slot:help"));
-      }
-   }
-
-
-   /*******************************************************************************
-    ** RC.6 has no summary property, so retain the summary in the bundle only.
-    *******************************************************************************/
-   private static QHelpContent content(Map<String, JsonNode> entries, String key) throws QException
-   {
-      if(!entries.containsKey(key))
-      {
-         throw (new QException("Missing CRM help entry: " + key));
-      }
-      return (new QHelpContent().withContentAsMarkdown(entries.get(key).get("content").asText()));
-   }
-}

src/main/java/com/kingsrook/qbits/crm/widgets/CrmHomeWidgets.java

@@ -76,6 +76,11 @@ public class CrmHomeWidgets extends MetaDataProducer<MetaDataProducerMultiOutput
       {
          widget.getPermissionRules().withCustomPermissionChecker(new QCodeReference(CrmGoalsVisibility.class));
       }
+      if("crm_setup".equals(name))
+      {
+         widget.withPermissionRules(CrmPermissions.hasAccessRules(CrmPermissions.MANAGE_BASE))
+            .getPermissionRules().withCustomPermissionChecker(new QCodeReference(CrmSetupVisibility.class));
+      }
       return (widget);
    }
 }

src/main/java/com/kingsrook/qbits/crm/widgets/CrmSetupStatus.java

@@ -23,8 +23,6 @@ package com.kingsrook.qbits.crm.widgets;
 
 import java.util.ArrayList;
 import java.util.List;
-import com.kingsrook.qbits.crm.api.CrmApi;
-import com.kingsrook.qbits.crm.api.CrmReadiness;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 
@@ -89,6 +87,16 @@ public final class CrmSetupStatus
 
 
 
+   /*******************************************************************************
+    ** True when any business setup step still needs attention.
+    *******************************************************************************/
+   public static boolean isIncomplete() throws QException
+   {
+      return (load().stream().anyMatch(item -> item.state() == State.TODO));
+   }
+
+
+
    /*******************************************************************************
     ** Build the items for the current user.
     *******************************************************************************/
@@ -160,14 +168,6 @@ public final class CrmSetupStatus
          ? new Item("Base currency", "crm_currency", State.TODO, "None: amounts have no currency prefix and conversions do nothing.", "Add your currency with Base currency ticked and rate 1.")
          : new Item("Base currency", "crm_currency", State.OK, base.getFirst().getValueString("currencyCode") + " is the base currency.", null));
 
-      ///////////////////////////////////////////////////////
-      // email: sequences and list mail need a delivery path //
-      ///////////////////////////////////////////////////////
-      CrmReadiness readiness = CrmApi.readiness();
-      items.add(readiness == CrmReadiness.NOT_CONFIGURED
-         ? new Item("Email delivery", "crm_email_template", State.OPTIONAL, "No email path: sequences and list email cannot send.",
-            "Install and configure the email qbit, or set a messaging provider on the CRM configuration.")
-         : new Item("Email delivery", "crm_email_template", State.OK, readiness == CrmReadiness.QBIT_EMAIL ? "Sends through the email qbit." : "Sends through core messaging.", null));
       return (items);
    }
 

src/main/java/com/kingsrook/qbits/crm/widgets/CrmSetupVisibility.java

@@ -0,0 +1,64 @@
+/*
+ * 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.
+ */
+
+
+package com.kingsrook.qbits.crm.widgets;
+
+
+import com.kingsrook.qbits.crm.security.CrmPermissions;
+import com.kingsrook.qqq.backend.core.actions.permissions.CustomPermissionChecker;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
+
+
+/*******************************************************************************
+ ** Show the Setup card only to CRM settings holders (crm.manage) and only while
+ ** a business setup step is still missing. Evaluated at request time, so a
+ ** completed setup drops the card from per-session metadata and from render.
+ *******************************************************************************/
+public class CrmSetupVisibility implements CustomPermissionChecker
+{
+   /*******************************************************************************
+    ** Require crm.hasAccess and crm.manage.hasAccess, then an incomplete setup.
+    *******************************************************************************/
+   @Override
+   public void checkPermissionsThrowing(AbstractActionInput input, MetaDataWithPermissionRules metadata) throws QPermissionDeniedException
+   {
+      if(QContext.getQSession() == null || !QContext.getQSession().hasPermission(CrmPermissions.APP_ACCESS) || !QContext.getQSession().hasPermission(CrmPermissions.MANAGE))
+      {
+         throw (new QPermissionDeniedException("CRM settings access is required."));
+      }
+      try
+      {
+         if(CrmSetupStatus.isIncomplete())
+         {
+            return;
+         }
+      }
+      catch(QException e)
+      {
+         throw (new QPermissionDeniedException("Setup status is not available.", e));
+      }
+      throw (new QPermissionDeniedException("CRM setup is complete."));
+   }
+}

src/main/resources/qbit-crm.properties

@@ -0,0 +1 @@
+version=${project.version}

src/test/java/com/kingsrook/qbits/crm/CrmPublicationHelpTest.java

@@ -23,7 +23,6 @@ package com.kingsrook.qbits.crm;
 
 import java.util.ArrayList;
 import java.util.List;
-import com.kingsrook.qbits.crm.help.CrmHelpBundleStandIn;
 import com.kingsrook.qqq.api.actions.GetTableApiFieldsAction;
 import com.kingsrook.qqq.api.model.APIVersion;
 import com.kingsrook.qqq.api.model.actions.GetTableApiFieldsInput;
@@ -33,8 +32,8 @@ import com.kingsrook.qqq.api.model.metadata.tables.ApiTableMetaDataContainer;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.instances.QInstanceValidator;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
-import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSourceType;
-import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
+import com.kingsrook.qqq.backend.core.testing.HelpBundleAssertions;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -101,52 +100,29 @@ class CrmPublicationHelpTest extends BaseTest
 
 
    /*******************************************************************************
-    ** Help covers app every table main field process and enum.
+    ** Native registration is safe without help tables and covers all CRM metadata.
     *******************************************************************************/
    @Test
-   void helpCoversAppEveryTableMainFieldProcessAndEnum() throws Exception
+   void helpCoversOwnedMetadataWithoutHelpTable()
    {
-      var entries = CrmHelpBundleStandIn.entries();
       var instance = QContext.getQInstance();
-      assertThat(entries).containsKey("app:crm;slot:help");
-      for(var table : instance.getTables().values())
+      assertThat(instance.getTable("helpContent")).isNull();
+      assertThat(HelpBundles.of(instance).getBundles()).singleElement().satisfies(bundle ->
       {
-         assertThat(entries).containsKey("table:" + table.getName() + ";slot:help");
-         assertThat(table.getHelpContent().get("help")).isNotEmpty();
-         if(CrmAppMetaData.MAIN_TABLES.contains(table.getName()))
-         {
-            for(var field : table.getFields().values())
-            {
-               assertThat(entries).containsKey("table:" + table.getName() + ";field:" + field.getName());
-               assertThat(field.getHelpContents()).as(table.getName() + "." + field.getName()).isNotEmpty();
-            }
-         }
-      }
-      for(var process : instance.getProcesses().values())
-      {
-         if(process.getName().startsWith("crm_"))
-         {
-            assertThat(entries).containsKey("process:" + process.getName() + ";slot:help");
-            // Core creates dotted bulk-process names after QBit production; they retain core screen help.
-            if(!process.getName().contains("."))
-            {
-               process.getStepList().stream().filter(QFrontendStepMetaData.class::isInstance).map(QFrontendStepMetaData.class::cast)
-                  .forEach(step -> assertThat(step.getHelpContents()).isNotEmpty());
-            }
-         }
-      }
-      for(var pvs : instance.getPossibleValueSources().values())
-      {
-         if(pvs.getType() == QPossibleValueSourceType.ENUM && pvs.getName().startsWith("Crm"))
-         {
-            assertThat(entries).containsKey("possibleValueSource:" + pvs.getName() + ";slot:help");
-         }
-      }
-      entries.values().forEach(entry ->
-      {
-         assertThat(entry.get("summary").asText()).hasSizeLessThanOrEqualTo(120).isNotBlank();
-         assertThat(entry.get("content").asText()).isNotBlank();
+         assertThat(bundle.getId()).isEqualTo("qbit-crm");
+         assertThat(bundle.getVersion()).isEqualTo(System.getProperty("qbit.artifactVersion")).isEqualTo(CrmQBitProducer.VERSION);
+         assertThat(bundle.getLayer().name()).isEqualTo("QBIT");
       });
+      HelpBundles.syncOnStartup(instance);
+      HelpBundleAssertions.forInstance(instance)
+         .bundles("help/qbit-crm.yaml")
+         .owning(target -> target.name().equals("crm") || target.name().startsWith("crm_") || target.name().startsWith("Crm"))
+         .assertComplete();
+      // Core's gate validates these entries but does not require widget or possible-value coverage.
+      var entries = HelpBundles.of(instance).resolveWinningEntries();
+      instance.getWidgets().keySet().stream().filter(name -> name.startsWith("crm_")).forEach(name ->
+         assertThat(entries).containsKey(new HelpBundles.EntryKey("widget:" + name + ";slot:label", "ALL_SCREENS")));
+      instance.getPossibleValueSources().keySet().stream().filter(name -> name.startsWith("crm_") || name.startsWith("Crm")).forEach(name ->
+         assertThat(entries).containsKey(new HelpBundles.EntryKey("possibleValueSource:" + name + ";slot:help", "ALL_SCREENS")));
    }
 }
-

src/test/java/com/kingsrook/qbits/crm/CrmQBitProducerTest.java

@@ -62,7 +62,7 @@ class CrmQBitProducerTest extends BaseTest
       assertThat(metaData).isNotNull();
       assertThat(metaData.getGroupId()).isEqualTo(CrmQBitProducer.GROUP_ID);
       assertThat(metaData.getArtifactId()).isEqualTo(CrmQBitProducer.ARTIFACT_ID);
-      assertThat(metaData.getVersion()).isEqualTo(CrmQBitProducer.VERSION);
+      assertThat(metaData.getVersion()).isEqualTo(System.getProperty("qbit.artifactVersion")).isEqualTo(CrmQBitProducer.VERSION);
    }
 
 
@@ -114,7 +114,7 @@ class CrmQBitProducerTest extends BaseTest
    {
       assertThat(CrmQBitProducer.GROUP_ID).isEqualTo("com.kingsrook.qbits");
       assertThat(CrmQBitProducer.ARTIFACT_ID).isEqualTo("crm");
-      assertThat(CrmQBitProducer.VERSION).isEqualTo("0.2.0-SNAPSHOT");
+      assertThat(CrmQBitProducer.VERSION).isEqualTo(System.getProperty("qbit.artifactVersion"));
    }
 
    /*******************************************************************************

src/test/java/com/kingsrook/qbits/crm/CrmTablesGuardrailTest.java

@@ -31,8 +31,7 @@ import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
-import com.kingsrook.qbits.crm.help.CrmHelpBundleStandIn;
-import com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -160,18 +159,17 @@ class CrmTablesGuardrailTest extends BaseTest
    @Test
    void everyTableHasEmptyStateHelp() throws Exception
    {
-      assertThat(CrmHelpBundleStandIn.entries()).allSatisfy((key, entry) -> assertThat(entry.path("summary").asText().length()).as(key).isLessThanOrEqualTo(120));
+      HelpBundles.of(qInstance()).getBundles().getFirst().getEntries()
+         .forEach(entry -> assertThat(entry.getSummary()).as(entry.getKey()).hasSizeLessThanOrEqualTo(120));
       for(String table : crmTables())
       {
-         List<QHelpContent> help = qInstance().getTable(table).getHelpContent() == null ? null : qInstance().getTable(table).getHelpContent().get("help");
-         assertThat(help).as(table + " table help").isNotEmpty();
-         assertThat(help.get(0).getContent()).as(table + " help says how rows get created").contains("**How rows get created:**");
+         assertThat(tableHelp(table)).as(table + " help says how rows get created").contains("**How rows get created:**");
       }
       for(String table : NOT_WRITTEN_YET)
       {
-         assertThat(qInstance().getTable(table).getHelpContent().get("help").get(0).getContent()).as(table + " says it is not used yet").contains("not used yet");
+         assertThat(tableHelp(table)).as(table + " says it is not used yet").contains("not used yet");
       }
-      assertThat(qInstance().getApp("crm").getHelpContent()).containsKey("help");
+      assertThat(HelpBundles.of(qInstance()).resolveWinningEntries()).containsKey(new HelpBundles.EntryKey("app:crm;slot:help", "ALL_SCREENS"));
    }
 
 
@@ -184,14 +182,26 @@ class CrmTablesGuardrailTest extends BaseTest
    {
       for(String table : CrmDefaultsChangelogTest.SEEDED_TABLES)
       {
-         assertThat(qInstance().getTable(table).getHelpContent().get("help").get(0).getContent()).as(table).contains("seeds");
+         assertThat(tableHelp(table)).as(table).contains("seeds");
       }
    }
 
 
 
    /*******************************************************************************
-    **
+    ** Read the winning table entry from the registered native bundle.
+    *******************************************************************************/
+   private String tableHelp(String table)
+   {
+      var entry = HelpBundles.of(qInstance()).resolveWinningEntries().get(new HelpBundles.EntryKey("table:" + table + ";slot:help", "ALL_SCREENS"));
+      assertThat(entry).as(table + " table help").isNotNull();
+      return (entry.entry().getContent());
+   }
+
+
+
+   /*******************************************************************************
+    ** Test instance after CRM production.
     *******************************************************************************/
    private com.kingsrook.qqq.backend.core.model.metadata.QInstance qInstance()
    {

src/test/java/com/kingsrook/qbits/crm/widgets/CrmSetupStatusTest.java

@@ -23,12 +23,21 @@ package com.kingsrook.qbits.crm.widgets;
 
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.stream.Collectors;
 import com.kingsrook.qbits.crm.BaseTest;
+import com.kingsrook.qbits.crm.security.CrmPermissions;
+import com.kingsrook.qqq.backend.core.actions.dashboard.RenderWidgetAction;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.TableData;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 
 /*******************************************************************************
@@ -38,19 +47,18 @@ import static org.assertj.core.api.Assertions.assertThat;
 class CrmSetupStatusTest extends BaseTest
 {
    /*******************************************************************************
-    ** Nothing configured: the four things the CRM needs are flagged.
+    ** Nothing configured: the business setup the CRM needs are flagged.
     *******************************************************************************/
    @Test
    void emptyInstallNeedsSetup() throws Exception
    {
       Map<String, CrmSetupStatus.Item> items = items();
-      assertThat(items).containsOnlyKeys("Default pipeline", "Pipeline stages", "Lifecycle stages", "Base currency", "Email delivery");
+      assertThat(items).containsOnlyKeys("Default pipeline", "Pipeline stages", "Lifecycle stages", "Base currency");
       assertThat(items.get("Default pipeline").state()).isEqualTo(CrmSetupStatus.State.TODO);
       assertThat(items.get("Default pipeline").detail()).contains("Convert lead fails");
       assertThat(items.get("Pipeline stages").state()).isEqualTo(CrmSetupStatus.State.TODO);
       assertThat(items.get("Lifecycle stages").detail()).contains("Lead and Opportunity");
       assertThat(items.get("Base currency").state()).isEqualTo(CrmSetupStatus.State.TODO);
-      assertThat(items.get("Email delivery").state()).isNotEqualTo(CrmSetupStatus.State.TODO);
    }
 
 
@@ -106,7 +114,7 @@ class CrmSetupStatusTest extends BaseTest
    {
       assertThat(CrmHomeWidgets.HOME).contains("crm_setup");
       TableData data = (TableData) CrmHomeWidgetsTest.render("crm_setup");
-      assertThat(data.getRows()).hasSize(5);
+      assertThat(data.getRows()).hasSize(4);
       CrmHomeWidgetsTest.assertCell(data, 0, "first", "Default pipeline");
       assertThat(data.getRows().get(0).get("second").toString()).contains("Needs setup");
       
@@ -114,6 +122,76 @@ class CrmSetupStatusTest extends BaseTest
 
 
 
+   /*******************************************************************************
+    ** The checklist is business setup only: no email-provider row.
+    *******************************************************************************/
+   @Test
+   void noEmailProviderRow() throws Exception
+   {
+      assertThat(items().keySet()).noneMatch(label -> label.toLowerCase().contains("email"));
+      TableData data = (TableData) CrmHomeWidgetsTest.render("crm_setup");
+      assertThat(data.getRows().toString()).doesNotContain("email qbit").doesNotContain("Email delivery");
+   }
+
+
+
+   /*******************************************************************************
+    ** Settings holders get the card while setup is incomplete, and not once complete.
+    *******************************************************************************/
+   @Test
+   void settingsHolderSeesCardOnlyWhileIncomplete() throws Exception
+   {
+      assertThat(PermissionsHelper.hasWidgetPermission(new RenderWidgetInput(), "crm_setup")).isTrue();
+
+      completeSetup();
+      assertThat(CrmSetupStatus.isIncomplete()).isFalse();
+      assertThat(PermissionsHelper.hasWidgetPermission(new RenderWidgetInput(), "crm_setup")).isFalse();
+      assertThatThrownBy(() -> renderEnforced()).isInstanceOf(QPermissionDeniedException.class);
+   }
+
+
+
+   /*******************************************************************************
+    ** A CRM user without the settings permission never gets the card, incomplete or not.
+    *******************************************************************************/
+   @Test
+   void nonSettingsUserNeverSeesCard() throws Exception
+   {
+      QContext.getQSession().setPermissions(Set.of(CrmPermissions.APP_ACCESS, CrmPermissions.READ, CrmPermissions.WRITE));
+      assertThat(CrmSetupStatus.isIncomplete()).isTrue();
+      assertThat(PermissionsHelper.hasWidgetPermission(new RenderWidgetInput(), "crm_setup")).isFalse();
+      assertThatThrownBy(() -> renderEnforced()).isInstanceOf(QPermissionDeniedException.class);
+   }
+
+
+
+   /*******************************************************************************
+    ** Render the setup widget the way the UI API does, with permissions enforced.
+    *******************************************************************************/
+   private void renderEnforced() throws Exception
+   {
+      RenderWidgetInput input = new RenderWidgetInput().withWidgetMetaData(QContext.getQInstance().getWidget("crm_setup"));
+      input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      new RenderWidgetAction().execute(input);
+   }
+
+
+
+   /*******************************************************************************
+    ** Seed everything the checklist asks for.
+    *******************************************************************************/
+   private void completeSetup() throws Exception
+   {
+      CrmHomeWidgetsTest.seed("crm_pipeline", new QRecord().withValue("id", 1).withValue("name", "Sales").withValue("isDefault", true));
+      CrmHomeWidgetsTest.seed("crm_pipeline_stage", new QRecord().withValue("id", 2).withValue("pipelineId", 1).withValue("name", "Won").withValue("sortOrder", 2).withValue("isClosedWon", true));
+      CrmHomeWidgetsTest.seed("crm_pipeline_stage", new QRecord().withValue("id", 3).withValue("pipelineId", 1).withValue("name", "Lost").withValue("sortOrder", 3).withValue("isClosedLost", true));
+      CrmHomeWidgetsTest.seed("crm_lifecycle_stage", new QRecord().withValue("id", 1).withValue("name", "Lead"));
+      CrmHomeWidgetsTest.seed("crm_lifecycle_stage", new QRecord().withValue("id", 2).withValue("name", "Opportunity"));
+      CrmHomeWidgetsTest.seed("crm_currency", new QRecord().withValue("currencyCode", "USD").withValue("isBaseCurrency", true));
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/