Documented how collection settings combine across configuration plugins

app/MindWork AI Studio/Plugins/configuration/plugin.lua

@@ -219,6 +219,24 @@ CONFIG["DATA_SOURCES"] = {}
 
 CONFIG["SETTINGS"] = {}
 
+-- ------
+-- How settings combine when your organization deploys more than one configuration
+-- ------
+--
+-- A configuration with a higher PRIORITY is applied later and wins. This works per
+-- setting: everything a later configuration does not mention keeps the value of the
+-- configuration below it.
+--
+-- For a setting that holds a list or a table, the winning configuration replaces the
+-- whole collection instead of merging the entries. A department configuration that
+-- lists a single entry therefore drops every entry the base configuration had set for
+-- that setting. That is intentional: replacing is the only way a department can take
+-- something back that the base configuration has set.
+--
+-- The affected settings below carry a note. The one exception is
+-- DataApp.EnabledPreviewFeatures, which adds up across configurations.
+-- ------
+
 -- Configure the update check interval:
 -- Allowed values are: NO_CHECK, DISABLE_UPDATES, ONCE_STARTUP, HOURLY, DAILY, WEEKLY
 -- NO_CHECK disables automatic checks, but users can still check and install updates manually.
@@ -277,6 +295,12 @@ CONFIG["SETTINGS"] = {}
 -- Configure the enabled preview features:
 -- Allowed values are can be found in https://github.com/MindWorkAI/AI-Studio/blob/main/app/MindWork%20AI%20Studio/Settings/DataModel/PreviewFeatures.cs
 -- Examples are PRE_WRITER_MODE_2024 and PRE_RAG_2024.
+--
+-- Adds up, does not replace: this is the one setting where all configurations
+-- contribute together. Enable one preview feature for the whole organization and
+-- another one for a single department, and users of that department get both. Each
+-- configuration keeps its own contribution, so removing one of them only withdraws
+-- the features that this configuration had enabled.
 -- CONFIG["SETTINGS"]["DataApp.EnabledPreviewFeatures"] = { "PRE_RAG_2024" }
 
 -- Configure the preselected provider.
@@ -321,6 +345,12 @@ CONFIG["SETTINGS"] = {}
 -- CONFIG["SETTINGS"]["DataChat.PreselectedDataSourcesAutomaticValidation"] = true
 
 -- Must contain IDs from CONFIG["DATA_SOURCES"] or user-configured data sources.
+-- IDs from another configuration of your organization work as well: they are resolved
+-- against every known data source, not only against the ones defined here. IDs that
+-- resolve to nothing are ignored.
+--
+-- Replaces, does not merge: a configuration with a higher priority replaces this list
+-- completely. To keep an entry of the base configuration, list that ID here again.
 -- CONFIG["SETTINGS"]["DataChat.PreselectedDataSourceIds"] = {
 --     "00000000-0000-0000-0000-000000000000",
 -- }
@@ -356,6 +386,11 @@ CONFIG["SETTINGS"] = {}
 --   JOB_POSTING_ASSISTANT, BIAS_DAY_ASSISTANT, ERI_ASSISTANT,
 --   DOCUMENT_ANALYSIS_ASSISTANT, SLIDE_BUILDER_ASSISTANT, VISUAL_BRIEFING_ASSISTANT, I18N_ASSISTANT,
 --   LOG_VIEWER_ASSISTANT
+--
+-- Replaces, does not merge: a configuration with a higher priority replaces this list
+-- completely. This is what lets a department show an assistant again that the base
+-- configuration hides. The department configuration must then list every other
+-- assistant that is supposed to stay hidden, otherwise those become visible too.
 -- CONFIG["SETTINGS"]["DataApp.HiddenAssistants"] = { "ERI_ASSISTANT", "I18N_ASSISTANT" }
 
 -- Configure organization defaults for the Visual Briefing Assistant.
@@ -424,6 +459,11 @@ CONFIG["SETTINGS"] = {}
 -- no user-run security audit is required.
 -- You can generate the exact hash with the build-script command:
 --   dotnet run --project app/Build -- assistant-plugin-hash "<plugin-dir>" --lua-snippet
+--
+-- Replaces, does not merge: a configuration with a higher priority replaces this list
+-- completely, so a department configuration listing two approvals withdraws every
+-- approval of the base configuration. Those assistant plugins then require a security
+-- audit again. Repeat the approvals of the base configuration here to keep them.
 -- CONFIG["SETTINGS"]["DataAssistantPluginAudit.EnterpriseApprovedPlugins"] = {
 --     {
 --         ["PluginHash"] = "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF",
@@ -463,6 +503,11 @@ CONFIG["SETTINGS"] = {}
 -- MINDWORK_AI_STUDIO_EXTERNAL_HTTP_CUSTOM_ROOT_CERTIFICATE_BUNDLE_PATH=/path/in/sandbox/company-root-cas.pem
 -- MINDWORK_AI_STUDIO_EXTERNAL_HTTP_CUSTOM_ROOT_CERTIFICATE_ALLOWED_HOSTS=*.intra.example.org;data.example.org
 --
+-- Replaces, does not merge: a configuration with a higher priority replaces the host
+-- list completely. Deploy this setting in one configuration only, or repeat every host
+-- of the base configuration. Otherwise, hosts of the base configuration silently stop
+-- trusting your root certificates.
+--
 -- CONFIG["SETTINGS"]["DataApp.ExternalHttpCustomRootCertificatesEnabled"] = true
 -- CONFIG["SETTINGS"]["DataApp.ExternalHttpCustomRootCertificateBundlePath"] = "/path/in/sandbox/company-root-cas.pem"
 -- CONFIG["SETTINGS"]["DataApp.ExternalHttpCustomRootCertificateAllowedHosts"] = { "*.intra.example.org", "eri.example.org" }
@@ -497,6 +542,11 @@ CONFIG["SETTINGS"] = {}
 -- Allowed provider keys are: OPEN_AI, ANTHROPIC, MISTRAL, GOOGLE, X, DEEP_SEEK, ALIBABA_CLOUD,
 --   PERPLEXITY, OPEN_ROUTER, FIREWORKS, GROQ, HUGGINGFACE, SELF_HOSTED, HELMHOLTZ, GWDG
 -- Allowed confidence values are: UNTRUSTED, VERY_LOW, LOW, MODERATE, MEDIUM, HIGH
+--
+-- Replaces, does not merge: a configuration with a higher priority replaces the whole
+-- table. Every configuration that sets this must therefore list all providers it wants
+-- to cover. A partial table is not completed from the configuration below it, and the
+-- providers left out fall back to the app default.
 -- CONFIG["SETTINGS"]["DataConfidence.CustomConfidenceScheme"] = {
 --     ["OPEN_AI"] = "MODERATE",
 --     ["ANTHROPIC"] = "MODERATE",
@@ -522,6 +572,10 @@ CONFIG["SETTINGS"] = {}
 -- These IDs may refer to LLM providers, embedding providers, or transcription providers
 -- defined in this configuration. Trusted providers are treated like self-hosted providers
 -- only for data-source security checks and related local data warnings.
+--
+-- Replaces, does not merge: a configuration with a higher priority replaces this list
+-- completely, so providers trusted by the base configuration lose that status. Repeat
+-- them here to keep them trusted.
 -- CONFIG["SETTINGS"]["DataSourceSecuritySettings.TrustedProviderIds"] = {
 --     "00000000-0000-0000-0000-000000000000",
 --     "00000000-0000-0000-0000-000000000001",

documentation/Enterprise IT.md

@@ -311,6 +311,29 @@ Two guarantees are independent of the priority:
 - A local configuration plugin never wins against one your IT department deployed, whatever priority it declares. Local plugins are always applied afterwards, and they may not take over a setting or an object that belongs to one of your configurations.
 - Two plugins must not share the same plugin ID. If that happens, AI Studio keeps the one your IT department deployed and logs a warning for the other.
 
+### Settings that hold a list or a table
+
+For a setting that holds a list or a table, the winning configuration replaces the whole collection. It does not merge the entries. A department configuration that lists a single entry drops every entry the base configuration had set for that setting.
+
+This is intentional: replacing is the only way a department can take something back. A department that wants an assistant to be visible again can only achieve that by not listing it.
+
+Plan for it in these settings:
+
+| Setting | What a partial list costs you |
+|---|---|
+| `DataApp.HiddenAssistants` | Assistants hidden by the base configuration become **visible** again |
+| `DataAssistantPluginAudit.EnterpriseApprovedPlugins` | Approvals of the base configuration are withdrawn, so those assistant plugins require a security audit again |
+| `DataSourceSecuritySettings.TrustedProviderIds` | Providers trusted by the base configuration lose that status |
+| `DataApp.ExternalHttpCustomRootCertificateAllowedHosts` | Hosts of the base configuration stop trusting your root certificates |
+| `DataConfidence.CustomConfidenceScheme` | Providers left out fall back to the AI Studio default confidence |
+| `DataChat.PreselectedDataSourceIds` | Data sources preselected by the base configuration are no longer preselected |
+
+The rule of thumb: whenever a configuration with a higher priority touches one of these settings, it has to repeat every entry it wants to keep. Watch `DataApp.HiddenAssistants` in particular, because it is the only one in this list that opens something up instead of restricting it.
+
+`DataApp.EnabledPreviewFeatures` is the exception. Preview features add up: enable one for the whole organization and another one for a single department, and users of that department get both. Each configuration keeps its own contribution, so removing one of them only withdraws the features that this configuration had enabled.
+
+One clarification for `DataChat.PreselectedDataSourceIds`: the IDs are not limited to the data sources of the same configuration. They are resolved against every known data source, including those of your other configurations and the ones a user configured. IDs that resolve to nothing are ignored.
+
 ## Example AI Studio configuration
 The latest example of an AI Studio configuration via configuration plugin can always be found in the repository in the `app/MindWork AI Studio/Plugins/configuration` folder. Here are the links to the files: