diff --git a/CHANGELOG.md b/CHANGELOG.md
index 907444b..cb2c1ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,3 +10,8 @@
- Apply CRM, management and admin permission rules and source-QBit metadata, including an RC.6 widget provenance adapter.
- Ship PostgreSQL DDL, 33 Liquibase changesets, and H2 persistence and schema tests. 0.2.0 is a fresh install; there is no upgrade path from 0.1.0.
- Correct installation instructions and document the existing P1 behavior and remaining limitations.
+- Add `crm-defaults.changelog.sql`: insert-only starter data (Sales Pipeline and stages, lifecycle stages, lead sources, industries, win/loss reasons, contact roles, activity types and outcomes, USD base currency). See UPGRADE.md.
+- Add a Setup card to the CRM home (default pipeline, stages, lifecycle stages, base currency, email delivery).
+- Every table help now says how its rows get created; `crm_external_mapping` is documented as not written by the CRM yet.
+- Stamp `crm_currency.rateLastUpdatedDate` when a rate is set or changed; the field is now read-only.
+- Add `CrmTablesGuardrailTest` and a Liquibase-driven defaults test (liquibase-core as a test dependency).
diff --git a/README.md b/README.md
index 358ead9..380fa16 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,16 @@ The shipped help bundle and health adapter are temporary core integration adapte
Permissions are independent grants. Every CRM-produced table, process and widget has explicit `QPermissionRules` with `DenyBehavior.HIDDEN` and QBit provenance. `security.CrmPermissions.ALL` lists the grants for host administration and tests. The app and widget provenance adapters supply core's `SourceQBitAware` interface because RC.6's app and widget classes lack it.
+## Starter defaults
+
+Include `db/liquibase/qbit-crm/crm-defaults.changelog.sql` in the host changelog after `crm.changelog.sql` and, on a tenant-enabled install, after `crm-tenancy.changelog.sql` as well:
+
+```yaml
+- include: { file: db/liquibase/qbit-crm/crm-defaults.changelog.sql }
+```
+
+It seeds, insert-only: the activity types and call/meeting outcomes; the default `Sales Pipeline` (Qualification 10%, Discovery 25%, Proposal 50%, Negotiation 75%, Closed Won 100%, Closed Lost 0%); lifecycle stages (the code looks up `Lead` and `Opportunity` by name); lead sources (`Website` is the web-form default); industries; win and loss reasons (prefixed `Won:` / `Lost:` because names are unique); contact roles; and a USD base currency. Lists are seeded only while empty, so a configured host is unchanged. The lifecycle stages (they change what intake and Convert lead assign) and the base currency are seeded only on a fresh install (no contact, respectively no deal, yet), and the stages only when `Sales Pipeline` is the only pipeline. Rollbacks are empty, so they never delete host rows. Tenant-enabled hosts seed per tenant (the changelog skips tenant-keyed tables). The Setup card on the CRM home shows what is still missing.
+
## Tables
All 34 table names and table-backed possible-value sources use `crm_` snake_case. The 23 enum possible-value sources retain their enum names. Relationship columns have indexes; the reference DDL does not impose foreign-key constraints or host-specific tenant columns. Unique constraints match the current QQQ metadata.
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000..6d03e74
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,24 @@
+# Upgrading
+
+## Starter defaults (Unreleased / 0.2.0)
+
+The CRM now ships `db/liquibase/qbit-crm/crm-defaults.changelog.sql`, a separate insert-only changelog. Without it,
+converting a lead fails with "no default pipeline found", new web leads and converted contacts silently get no
+lifecycle stage, and amounts have no currency prefix.
+
+What a host must do:
+
+1. Add one line to its master changelog, after `crm.changelog.sql` and, on tenant-enabled installs, after `crm-tenancy.changelog.sql` (the file checks for `tenant_key` columns, so the order matters):
+
+ ```yaml
+ - include: { file: db/liquibase/qbit-crm/crm-defaults.changelog.sql }
+ ```
+
+2. Review what it seeds (see README, "Starter defaults"). Existing configuration is never touched: lists are seeded
+ only while their table is empty, the pipeline only when no pipeline exists, its stages only when it is the only pipeline and no stage or deal exists. Lifecycle stages and the base currency are seeded only on a fresh install (no contact, respectively no deal, yet), because they change what intake and Convert lead assign. Rollbacks are empty.
+3. Tenant-enabled hosts (the `crm-tenancy` changelog added `tenant_key` columns): the changelog skips those tables
+ (marks them ran), because rows without a tenant key are invisible to tenants. Insert the same rows once per tenant
+ with `tenant_key` set. The Setup card on the CRM home shows what is still missing.
+4. `crm_currency.rate_last_updated_date` is now written by the CRM when a rate is set or changed and is read-only in
+ the UI. Existing values are kept.
+5. No schema change. `crm_external_mapping` is documented as not written by the CRM yet.
diff --git a/pom.xml b/pom.xml
index 7aeb01b..a65cf4e 100644
--- a/pom.xml
+++ b/pom.xml
@@ -113,6 +113,13 @@
test
+
+ org.liquibase
+ liquibase-core
+ 4.33.0
+ test
+
+
org.junit.jupiter
junit-jupiter
diff --git a/src/main/java/com/kingsrook/qbits/crm/CrmQBitProducer.java b/src/main/java/com/kingsrook/qbits/crm/CrmQBitProducer.java
index 72a177c..8e7e223 100644
--- a/src/main/java/com/kingsrook/qbits/crm/CrmQBitProducer.java
+++ b/src/main/java/com/kingsrook/qbits/crm/CrmQBitProducer.java
@@ -31,9 +31,11 @@ import java.util.Locale;
import java.util.Map;
import com.kingsrook.qbits.crm.activities.customizers.ActivityLastDateCustomizer;
import com.kingsrook.qbits.crm.activities.model.Activity;
+import com.kingsrook.qbits.crm.core.customizers.CurrencyRateDateCustomizer;
import com.kingsrook.qbits.crm.core.customizers.FormSubmissionAutoLinkCustomizer;
import com.kingsrook.qbits.crm.core.model.Company;
import com.kingsrook.qbits.crm.core.model.Contact;
+import com.kingsrook.qbits.crm.core.model.Currency;
import com.kingsrook.qbits.crm.core.model.FormSubmission;
import com.kingsrook.qbits.crm.deals.customizers.DealInitializationCustomizer;
import com.kingsrook.qbits.crm.deals.customizers.DealProductRecalculationCustomizer;
@@ -232,6 +234,15 @@ public class CrmQBitProducer implements QBitMetaDataProducer
addOrComposeCustomizer(table, TableCustomizers.POST_INSERT_RECORD, new QCodeReference(DealInitializationCustomizer.class));
}
+ ///////////////////////////////////////////////////////////////
+ // stamp the exchange-rate date when a rate is set or changed //
+ ///////////////////////////////////////////////////////////////
+ if(tableName.equals(Currency.TABLE_NAME))
+ {
+ addOrComposeCustomizer(table, TableCustomizers.PRE_INSERT_RECORD, new QCodeReference(CurrencyRateDateCustomizer.OnInsert.class));
+ addOrComposeCustomizer(table, TableCustomizers.PRE_UPDATE_RECORD, new QCodeReference(CurrencyRateDateCustomizer.OnUpdate.class));
+ }
+
///////////////////////////////////////////////////////////////
// wire deal product recalculation //
///////////////////////////////////////////////////////////////
diff --git a/src/main/java/com/kingsrook/qbits/crm/core/customizers/CurrencyRateDateCustomizer.java b/src/main/java/com/kingsrook/qbits/crm/core/customizers/CurrencyRateDateCustomizer.java
new file mode 100644
index 0000000..e76cf6b
--- /dev/null
+++ b/src/main/java/com/kingsrook/qbits/crm/core/customizers/CurrencyRateDateCustomizer.java
@@ -0,0 +1,117 @@
+/*
+ * 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.core.customizers;
+
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.customizers.AbstractPreInsertCustomizer;
+import com.kingsrook.qqq.backend.core.actions.customizers.AbstractPreUpdateCustomizer;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ ** Stamps crm_currency.rateLastUpdatedDate whenever a rate is set or changed, so
+ ** the date says when the exchange rate was last touched. Editing only the name,
+ ** symbol or active flag leaves it alone.
+ *******************************************************************************/
+public final class CurrencyRateDateCustomizer
+{
+ public static final String RATE_FIELD = "exchangeRateToBase";
+ public static final String DATE_FIELD = "rateLastUpdatedDate";
+
+
+
+ /*******************************************************************************
+ ** Utility class.
+ *******************************************************************************/
+ private CurrencyRateDateCustomizer()
+ {
+ }
+
+
+
+ /*******************************************************************************
+ ** A new currency has a rate from the moment it exists.
+ *******************************************************************************/
+ public static class OnInsert extends AbstractPreInsertCustomizer
+ {
+ /*******************************************************************************
+ **
+ *******************************************************************************/
+ @Override
+ public List apply(List records) throws QException
+ {
+ Instant now = Instant.now();
+ for(QRecord record : records)
+ {
+ record.setValue(DATE_FIELD, now);
+ }
+ return (records);
+ }
+ }
+
+
+
+ /*******************************************************************************
+ ** An update that carries a different rate than the stored one moves the date.
+ *******************************************************************************/
+ public static class OnUpdate extends AbstractPreUpdateCustomizer
+ {
+ /*******************************************************************************
+ **
+ *******************************************************************************/
+ @Override
+ public List apply(List records) throws QException
+ {
+ if(isPreview || oldRecordList == null)
+ {
+ return (records);
+ }
+
+ Instant now = Instant.now();
+ for(QRecord record : records)
+ {
+ QRecord oldRecord = getOldRecordMap().get(record.getValue("id"));
+ if(oldRecord != null && record.getValues().containsKey(RATE_FIELD)
+ && !sameRate(ValueUtils.getValueAsBigDecimal(record.getValue(RATE_FIELD)), ValueUtils.getValueAsBigDecimal(oldRecord.getValue(RATE_FIELD))))
+ {
+ record.setValue(DATE_FIELD, now);
+ }
+ }
+ return (records);
+ }
+ }
+
+
+
+ /*******************************************************************************
+ ** Numeric equality, so 1 and 1.000000 are the same rate.
+ *******************************************************************************/
+ static boolean sameRate(BigDecimal a, BigDecimal b)
+ {
+ return (a == null ? b == null : b != null && a.compareTo(b) == 0);
+ }
+
+}
diff --git a/src/main/java/com/kingsrook/qbits/crm/core/model/Currency.java b/src/main/java/com/kingsrook/qbits/crm/core/model/Currency.java
index 49d3c61..e23c776 100644
--- a/src/main/java/com/kingsrook/qbits/crm/core/model/Currency.java
+++ b/src/main/java/com/kingsrook/qbits/crm/core/model/Currency.java
@@ -106,7 +106,7 @@ public class Currency extends QRecordEntity
@QField(isRequired = true, defaultValue = "true")
private Boolean isActive;
- @QField()
+ @QField(isEditable = false)
private Instant rateLastUpdatedDate;
@QField(isEditable = false)
diff --git a/src/main/java/com/kingsrook/qbits/crm/widgets/CrmHomeRenderer.java b/src/main/java/com/kingsrook/qbits/crm/widgets/CrmHomeRenderer.java
index 2dc529a..7f10ff3 100644
--- a/src/main/java/com/kingsrook/qbits/crm/widgets/CrmHomeRenderer.java
+++ b/src/main/java/com/kingsrook/qbits/crm/widgets/CrmHomeRenderer.java
@@ -92,6 +92,8 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
{
case "crm_today":
return (new RenderWidgetOutput(new ParentWidgetData().withChildWidgetNameList(CrmHomeWidgets.TODAY).withLabel("Today")));
+ case "crm_setup":
+ return (new RenderWidgetOutput(setup()));
case "crm_open_pipeline":
return (new RenderWidgetOutput(statistic(sum(DEAL, dealStatus(false), AMOUNT), true)));
case "crm_won_month":
@@ -247,6 +249,22 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
}
+ /*******************************************************************************
+ ** The Setup card: each piece of configuration the CRM needs, its state and the
+ ** next step, every cell linking to the table that fixes it.
+ *******************************************************************************/
+ private TableData setup() throws QException
+ {
+ List