@cdmbase/wiki-browser 12.0.18-alpha.34 → 12.0.18-alpha.35

package/lib/templates/content/content-manifest.json

@@ -582,6 +582,18 @@
       "updatedAt": "Recently",
       "frontmatter": {}
     },
+    {
+      "contentId": "adminide-modules-preferences-pagesettings-troubleshootingsettingswithpageexplainplan",
+      "slug": "preferences-pagesettings-troubleshootingsettingswithpageexplainplan",
+      "filePath": "/content/docs/adminide-modules/preferences/pageSettings/troubleshootingSettingsWithPageExplainPlan.md",
+      "relativePath": "adminide-modules/preferences/pageSettings/troubleshootingSettingsWithPageExplainPlan.md",
+      "categoryId": "adminide-modules",
+      "title": "TroubleshootingSettingsWithPageExplainPlan",
+      "description": "",
+      "author": "Documentation",
+      "updatedAt": "Recently",
+      "frontmatter": {}
+    },
     {
       "contentId": "adminide-modules-preferences-permissions-roles-permissions",
       "slug": "preferences-permissions-roles-permissions",
@@ -4045,6 +4057,15 @@
           "updatedAt": "Recently",
           "categoryId": "adminide-modules"
         },
+        {
+          "id": "adminide-modules-preferences-pagesettings-troubleshootingsettingswithpageexplainplan",
+          "title": "TroubleshootingSettingsWithPageExplainPlan",
+          "description": "",
+          "slug": "preferences-pagesettings-troubleshootingsettingswithpageexplainplan",
+          "author": "Documentation",
+          "updatedAt": "Recently",
+          "categoryId": "adminide-modules"
+        },
         {
           "id": "adminide-modules-preferences-usesettingsloader",
           "title": "Use Setting Loader",
@@ -5447,6 +5468,7 @@
     "adminide-modules-preferences-machine-configuration": "/content/docs/adminide-modules/preferences/machine-configuration.md",
     "adminide-modules-preferences-pagesettings-generatecdecodeuri": "/content/docs/adminide-modules/preferences/pageSettings/generateCdecodeUri.md",
     "adminide-modules-preferences-pagesettings-migratingfromusesettings": "/content/docs/adminide-modules/preferences/pageSettings/migratingFromUseSettings.md",
+    "adminide-modules-preferences-pagesettings-troubleshootingsettingswithpageexplainplan": "/content/docs/adminide-modules/preferences/pageSettings/troubleshootingSettingsWithPageExplainPlan.md",
     "adminide-modules-preferences-permissions-roles-permissions": "/content/docs/adminide-modules/preferences/permissions/Roles-Permissions.md",
     "adminide-modules-preferences-permissions-settinguserpermissions": "/content/docs/adminide-modules/preferences/permissions/settingUserPermissions.md",
     "adminide-modules-preferences-preference-dependency": "/content/docs/adminide-modules/preferences/preference-dependency.md",
@@ -5907,6 +5929,21 @@
                     "author": "Documentation",
                     "updatedAt": "Recently",
                     "frontmatter": {}
+                  },
+                  {
+                    "type": "file",
+                    "name": "troubleshootingSettingsWithPageExplainPlan",
+                    "title": "TroubleshootingSettingsWithPageExplainPlan",
+                    "path": "adminide-modules/preferences/pageSettings/troubleshootingSettingsWithPageExplainPlan.md",
+                    "contentId": "adminide-modules-preferences-pagesettings-troubleshootingsettingswithpageexplainplan",
+                    "slug": "preferences-pagesettings-troubleshootingsettingswithpageexplainplan",
+                    "categoryId": "adminide-modules",
+                    "filePath": "/content/docs/adminide-modules/preferences/pageSettings/troubleshootingSettingsWithPageExplainPlan.md",
+                    "relativePath": "adminide-modules/preferences/pageSettings/troubleshootingSettingsWithPageExplainPlan.md",
+                    "description": "",
+                    "author": "Documentation",
+                    "updatedAt": "Recently",
+                    "frontmatter": {}
                   }
                 ]
               },
@@ -10213,6 +10250,12 @@
                   "path": "/help/adminide-modules/preferences-pagesettings-migratingfromusesettings",
                   "children": [],
                   "isFile": true
+                },
+                {
+                  "title": "TroubleshootingSettingsWithPageExplainPlan",
+                  "path": "/help/adminide-modules/preferences-pagesettings-troubleshootingsettingswithpageexplainplan",
+                  "children": [],
+                  "isFile": true
                 }
               ],
               "isFile": false

package/lib/templates/content/docs/adminide-modules/preferences/pageSettings/troubleshootingSettingsWithPageExplainPlan.md

@@ -0,0 +1,691 @@
+# Troubleshooting Settings with `pageExplainPlan`
+
+When settings or extensions are not showing up as expected, the `pageExplainPlan` GraphQL query is the **primary debugging tool**. It reveals exactly which configuration subjects will be loaded, in what order they merge, and which extensions are resolved — without actually performing the merge. Think of it as a **dry-run** for `pageSettings`.
+
+---
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Understanding the Query](#understanding-the-query)
+3. [Understanding the Response](#understanding-the-response)
+4. [Troubleshooting: Missing Extensions](#troubleshooting-missing-extensions)
+5. [Troubleshooting: Missing or Wrong Settings](#troubleshooting-missing-or-wrong-settings)
+6. [Common Pitfalls](#common-pitfalls)
+7. [Reference: ConfigurationTarget Values](#reference-configurationtarget-values)
+8. [Reference: Extension Resolution Flow](#reference-extension-resolution-flow)
+9. [Reference: Schema IDs (`ContributionSchemaId`)](#reference-schema-ids-contributionschemaid)
+10. [Reference: Fragment Names (`ConfigFragmentName`)](#reference-fragment-names-configfragmentname)
+11. [Reference: Collection Names (`ConfigCollectionName`)](#reference-collection-names-configcollectionname)
+12. [Reference: Extension Names (`ConfigExtensionName`)](#reference-extension-names-configextensionname)
+13. [Reference: URI Construction Pattern](#reference-uri-construction-pattern)
+14. [Advanced: Comparing with `pageSettings`](#advanced-comparing-with-pagesettings)
+
+---
+
+## Quick Start
+
+Open your GraphQL console (e.g. GraphQL Playground, Apollo Sandbox) and run:
+
+```graphql
+query GetPageExplainPlan($resourceUri: URIInput!, $options: PageSettingsOptionsInput) {
+    pageExplainPlan(resourceUri: $resourceUri, options: $options) {
+        target
+        targetName
+        fragmentData
+        mergeOrder
+        effectiveExtensions {
+            effectiveExtensions
+            userDisabledPublicExtensions
+            hasUserCustomizations
+            installedExtensionSlugs
+            defaultPublicExtensions
+            userExtensionOverrides
+            finalExtensionsList {
+                name
+                type
+                source
+            }
+        }
+        subjects {
+            typeName
+            target
+            resource
+            description
+        }
+    }
+}
+```
+
+### Variables — Organization-level settings
+
+```json
+{
+    "resourceUri": {
+        "scheme": "cdecode",
+        "authority": "default",
+        "path": "/<your-org-slug>",
+        "fragment": "settings"
+    },
+    "options": {
+        "schemaId": "configuration",
+        "includeMarketplace": true,
+        "target": 4
+    }
+}
+```
+
+> **Important:** Replace `<your-org-slug>` with your actual organization name/slug (the path segment after `/`).
+
+---
+
+## Understanding the Query
+
+### `resourceUri` fields
+
+| Field       | Description                           | Example                                      |
+| ----------- | ------------------------------------- | -------------------------------------------- |
+| `scheme`    | Always `"cdecode"`                    | `"cdecode"`                                  |
+| `authority` | Tenant identifier                     | `"default"`                                  |
+| `path`      | Organization + optional resource path | `"/my-org"` or `"/my-org/projects/proj-123"` |
+| `fragment`  | Data fragment to load                 | `"settings"` or `"policies"`                 |
+
+### `options` fields
+
+| Field                | Type      | Default               | Description                                                                               |
+| -------------------- | --------- | --------------------- | ----------------------------------------------------------------------------------------- |
+| `schemaId`           | `String`  | `"uilayout"`          | Schema to query against. Use `"configuration"` for extension/app settings.                |
+| `target`             | `Int`     | _(inferred from URI)_ | Configuration target level. See [reference table](#reference-configurationtarget-values). |
+| `includeMarketplace` | `Boolean` | `false`               | **Must be `true`** to see extension-related subjects and `effectiveExtensions`.           |
+| `configKey`          | `String`  | —                     | Dot-separated key to narrow results (e.g. `"timetracker.timesheet"`).                     |
+| `overrides`          | `Object`  | —                     | Override identifier, e.g. `{ "overrideIdentifier": "desktop" }`.                          |
+
+### Choosing the right `target`
+
+| Value   | Name                    | When to use                                                   |
+| ------- | ----------------------- | ------------------------------------------------------------- |
+| `1`     | `USER`                  | Debugging user-level settings                                 |
+| `2`     | `APPLICATION`           | Debugging tenant/application settings                         |
+| `3`     | `MACHINE`               | Debugging machine-specific settings                           |
+| **`4`** | **`ORGANIZATION`**      | **Most common — debugging org-level settings and extensions** |
+| `5`     | `ORGANIZATION_RESOURCE` | Debugging project/team/resource-level settings                |
+
+---
+
+## Understanding the Response
+
+### `target` / `targetName`
+
+Confirms the configuration target that was resolved. If you set `target: 4` in options, you should see:
+
+```json
+"target": 4,
+"targetName": "ORGANIZATION"
+```
+
+If the `targetName` doesn't match what you expect, the URI path may be causing a different target to be inferred.
+
+### `mergeOrder`
+
+The order in which configuration layers are merged (left-to-right, later wins):
+
+```json
+"mergeOrder": [
+  "SystemConfiguration",
+  "PublicExtensionConfigurations",
+  "ApplicationConfiguration",
+  "UserConfiguration",
+  "OrganizationConfiguration"
+]
+```
+
+**Key merge order variants for `ORGANIZATION` target:**
+
+| Scenario                                                                       | Merge Order                                                                                 |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `includeMarketplace: false`                                                    | `System → Application → User → Organization`                                                |
+| `includeMarketplace: true`, no user customizations, no private extensions      | `System → PublicExtensionConfigs → Application → User → Organization`                       |
+| `includeMarketplace: true`, no user customizations, **has** private extensions | `System → PublicExtensionConfigs → OrgMarketExtConfigs → Application → User → Organization` |
+| `includeMarketplace: true`, **has** user customizations                        | `System → EffectiveExtensionConfigs → Application → User → Organization`                    |
+
+### `subjects`
+
+Each subject represents a configuration source that will be loaded and merged:
+
+```json
+{
+    "typeName": "DefaultConfiguration",
+    "target": 6,
+    "resource": "mongo-db-file:///configuration_registry?schemaId=configuration&target=4&isMarketplace=false&source=system",
+    "description": "System defaults from contribution registry (non-marketplace)"
+}
+```
+
+**Key fields to check:**
+
+- **`typeName`** — The type of configuration (`DefaultConfiguration`, `OrganizationConfiguration`, etc.)
+- **`resource`** — The actual URI that will be used to read data. If `null`, that subject won't be loaded.
+- **`description`** — Human-readable explanation of what this subject provides.
+
+### `effectiveExtensions`
+
+Only populated when `includeMarketplace: true`. This is the **core** data for debugging missing extensions:
+
+```json
+{
+    "effectiveExtensions": ["ext-a", "ext-b", "ext-c"],
+    "userDisabledPublicExtensions": ["ext-d"],
+    "hasUserCustomizations": true,
+    "installedExtensionSlugs": ["private-ext-1"],
+    "defaultPublicExtensions": { "ext-a": true, "ext-b": true, "ext-d": true, "ext-e": false },
+    "userExtensionOverrides": { "ext-d": false, "ext-e": true },
+    "finalExtensionsList": [
+        { "name": "ext-a", "type": "PUBLIC", "source": "DEFAULT_ENABLED" },
+        { "name": "ext-b", "type": "PUBLIC", "source": "DEFAULT_ENABLED" },
+        { "name": "ext-e", "type": "PUBLIC", "source": "USER_ENABLED" },
+        { "name": "private-ext-1", "type": "PRIVATE", "source": "INSTALLED" }
+    ]
+}
+```
+
+---
+
+## Troubleshooting: Missing Extensions
+
+### Step 1 — Run the query with `includeMarketplace: true`
+
+If you forget this flag (or set it to `false`), `effectiveExtensions` will be `null` and no extension configuration subjects will appear. This is the **most common mistake**.
+
+### Step 2 — Check `defaultPublicExtensions`
+
+This shows **all** public extensions from `system_extension` and their default enabled state.
+
+**Is your extension listed here?**
+
+- ✅ **Yes, with value `true`** → Extension is default-enabled. Go to Step 3.
+- ✅ **Yes, with value `false`** → Extension is default-disabled. It will only appear if the user explicitly enables it (see Step 4).
+- ❌ **Not listed** → Extension is **not registered** in `system_extension`. The extension needs to be published and its `configuration` contribution registered in the `configuration_registry` collection.
+
+**How to fix a missing extension in `defaultPublicExtensions`:**
+
+1. Verify the extension is published to the marketplace.
+2. Check the `configuration_registry` collection for an entry with `extensionName: "system_extension"` that includes an `extensions.<your-extension-slug>` property.
+3. Ensure the property has `scope: 3` (ORGANIZATION) or higher.
+
+### Step 3 — Check `userDisabledPublicExtensions`
+
+If your extension is in this array, the user has **explicitly disabled** it at the organization level.
+
+```json
+"userDisabledPublicExtensions": ["my-extension"]
+```
+
+**How to verify:** Check the organization settings document (collection: typically `organizations` or the settings fragment) for:
+
+```json
+{ "extensions.my-extension": false }
+```
+
+**How to fix:** Remove or set the override to `true` in the org settings.
+
+### Step 4 — Check `userExtensionOverrides`
+
+This shows any overrides the user has set in their org settings:
+
+```json
+"userExtensionOverrides": {
+  "ext-d": false,
+  "ext-e": true
+}
+```
+
+- `false` → User disabled this extension (it will be removed from effective list even if default-enabled).
+- `true` → User enabled this extension (it will be added to effective list even if default-disabled).
+
+### Step 5 — Check `installedExtensionSlugs`
+
+These are **private/installed** extensions from the `installed_extensions` collection.
+
+**Is your private extension listed here?**
+
+- ✅ **Yes** → It should be in `effectiveExtensions`. If not, check that `settings.effectiveEnabled` is `true` in the installed extension document.
+- ❌ **Not listed** → The extension is not installed for this org, OR `settings.effectiveEnabled` is `false`, OR the `orgId` couldn't be resolved.
+
+**How to fix a missing installed extension:**
+
+1. Check `installed_extensions` collection for a document with matching `orgId` and `sourceDocumentId`.
+2. Verify `settings.effectiveEnabled: true`.
+3. If your org slug isn't resolving, check the `slugService` — the `orgId` from the URI path is resolved via `slugService.resolveOrganizationSlug()`.
+
+### Step 6 — Check `effectiveExtensions` (the final list)
+
+This is the **final computed list** of extensions that will be loaded. It combines:
+
+```
+effectiveExtensions = (default-enabled public - user-disabled) + user-enabled + installed private
+```
+
+If your extension is **not** in `effectiveExtensions` but **is** in `defaultPublicExtensions` with `true`:
+→ It was removed by a user override. Check `userDisabledPublicExtensions`.
+
+If your extension is **not** in `effectiveExtensions` and **not** in `defaultPublicExtensions`:
+→ It's neither registered as a public extension nor installed as a private one.
+
+### Step 7 — Check `finalExtensionsList` for type/source details
+
+This gives a comprehensive breakdown with categorization:
+
+| `type`    | `source`          | Meaning                                     |
+| --------- | ----------------- | ------------------------------------------- |
+| `PUBLIC`  | `DEFAULT_ENABLED` | Public extension enabled by default         |
+| `PUBLIC`  | `USER_ENABLED`    | Public extension enabled by user override   |
+| `PRIVATE` | `INSTALLED`       | Private extension from installed_extensions |
+
+### Step 8 — Check extension configuration subjects
+
+Look at the `subjects` array for extension-related entries. They use `typeName: "DefaultConfiguration"` but have different `resource` URIs:
+
+| What to look for in `resource` URI | Subject type                                                 |
+| ---------------------------------- | ------------------------------------------------------------ |
+| `source=system`                    | System defaults (non-marketplace)                            |
+| `source=public`                    | Public extension configurations                              |
+| `source=installed`                 | Installed/private extension configurations                   |
+| `source=effective`                 | Filtered effective extensions (when user has customizations) |
+
+**Example — No user customizations (public + installed separately):**
+
+```json
+[
+    {
+        "typeName": "DefaultConfiguration",
+        "resource": "...&source=public&extensionNames=ext-a,ext-b",
+        "description": "Public extension configurations..."
+    },
+    {
+        "typeName": "DefaultConfiguration",
+        "resource": "...&source=installed&extensionNames=private-ext",
+        "description": "Installed (private) extension configurations..."
+    },
+    { "typeName": "DefaultConfiguration", "resource": "...&source=system", "description": "System defaults..." }
+]
+```
+
+**Example — User has customizations (effective only):**
+
+```json
+[
+    {
+        "typeName": "DefaultConfiguration",
+        "resource": "...&source=effective&extensionNames=ext-a,ext-b,private-ext",
+        "description": "Customized extension configurations..."
+    },
+    { "typeName": "DefaultConfiguration", "resource": "...&source=system", "description": "System defaults..." }
+]
+```
+
+If the `resource` for your extension subject is `null`, the URI generation failed — check server logs for errors.
+
+---
+
+## Troubleshooting: Missing or Wrong Settings
+
+### Problem: Settings value not what I expect
+
+1. Run `pageExplainPlan` and look at the `mergeOrder`.
+2. Later entries **override** earlier ones. For example, if `OrganizationConfiguration` is last, org-level settings win.
+3. Run `pageSettings` with the same variables to see the actual merged result.
+4. Compare: the value in the final merged settings comes from the **last subject** in `mergeOrder` that defines that key.
+
+### Problem: `subjects` has `null` resource for a configuration layer
+
+This means the URI for that configuration layer could not be built. Common causes:
+
+| Subject                                                | Likely cause                                                                                      |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `UserConfiguration` resource is `null`                 | No `accountId` in the request context. The user might not be authenticated.                       |
+| `ApplicationConfiguration` resource is `null`          | The `slugService.convertToResourceUri` failed. Check if the tenant/application exists.            |
+| `OrganizationConfiguration` resource is `null`         | The org slug in the URI path couldn't be resolved. Verify the path segment matches an actual org. |
+| `OrganizationResourceConfiguration` resource is `null` | The resource type/id in the URI path couldn't be resolved.                                        |
+
+### Problem: `fragmentData` is wrong
+
+If you see `fragmentData: "settings"` but expected `"policies"`, check:
+
+- The `fragment` field in your `resourceUri` input.
+- The fragment is the part after `#` in a URI. Set it explicitly: `"fragment": "settings"` or `"fragment": "policies"`.
+
+---
+
+## Common Pitfalls
+
+### 1. Forgetting `includeMarketplace: true`
+
+**Symptom:** `effectiveExtensions` is `null`, no extension subjects in the plan.
+**Fix:** Set `"includeMarketplace": true` in options.
+
+### 2. Wrong `target` value
+
+**Symptom:** Fewer subjects than expected, or the `mergeOrder` is too short.
+**Fix:** Use `target: 4` for org-level, `target: 5` for resource-level.
+
+### 3. Org slug in URI path doesn't resolve
+
+**Symptom:** `OrganizationConfiguration` subject has `null` resource; `effectiveExtensions` is empty or `null`.
+**Fix:** Verify the URI path starts with `/<valid-org-slug>`. The slug must match an organization in the database.
+
+### 4. Using `schemaId: "uilayout"` instead of `"configuration"`
+
+**Symptom:** Extensions show up but their configuration settings don't appear in `pageSettings`.
+**Fix:** Use `"schemaId": "configuration"` to get extension configuration settings.
+
+### 5. Extension not in `system_extension`
+
+**Symptom:** Extension doesn't appear in `defaultPublicExtensions`.
+**Fix:** Ensure the extension registers its `extensions.<slug>` property in the `system_extension` configuration contribution with `scope: 3` (ORGANIZATION).
+
+### 6. Installed extension has `effectiveEnabled: false`
+
+**Symptom:** Extension doesn't appear in `installedExtensionSlugs`.
+**Fix:** Update the `installed_extensions` document to set `settings.effectiveEnabled: true`.
+
+---
+
+## Reference: ConfigurationTarget Values
+
+| Value | Name                    | Description                                   |
+| ----- | ----------------------- | --------------------------------------------- |
+| `1`   | `USER`                  | User-specific settings                        |
+| `2`   | `APPLICATION`           | Tenant/application-level settings             |
+| `3`   | `MACHINE`               | Machine-specific settings                     |
+| `4`   | `ORGANIZATION`          | Organization-level settings                   |
+| `5`   | `ORGANIZATION_RESOURCE` | Resource-level settings (project, team, etc.) |
+| `6`   | `DEFAULT`               | System defaults                               |
+| `7`   | `MEMORY`                | In-memory (transient)                         |
+
+---
+
+## Reference: Extension Resolution Flow
+
+The `getEffectiveExtensions` method follows this sequence:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  1. Query installed_extensions collection               │
+│     Filter: orgId + settings.effectiveEnabled = true    │
+│     Result: installedExtensionSlugs[]                   │
+├─────────────────────────────────────────────────────────┤
+│  2. Read organization settings document                 │
+│     Look for: extensions.* keys (flat or nested)        │
+│     Result: userExtensionOverrides {}                   │
+├─────────────────────────────────────────────────────────┤
+│  3. Load system_extension from configuration_registry   │
+│     Filter: extensions.* keys with scope >= ORGANIZATION│
+│     Result: defaultPublicExtensions {}                  │
+├─────────────────────────────────────────────────────────┤
+│  4. Calculate effective extensions                       │
+│                                                         │
+│     effective = (default enabled public)                 │
+│               - (user disabled)                         │
+│               + (user enabled, was default-disabled)    │
+│               + (installed private extensions)          │
+│                                                         │
+│     Result: effectiveExtensions[]                       │
+├─────────────────────────────────────────────────────────┤
+│  5. Build finalExtensionsList with type/source metadata │
+│     PUBLIC/DEFAULT_ENABLED                              │
+│     PUBLIC/USER_ENABLED                                 │
+│     PRIVATE/INSTALLED                                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Advanced: Comparing with `pageSettings`
+
+After using `pageExplainPlan` to understand the plan, run `pageSettings` with the **same variables** to see the actual merged result:
+
+```graphql
+query GetPageSettings($uri: URIInput!, $options: PageSettingsOptionsInput) {
+    pageSettings(uri: $uri, options: $options) {
+        target
+        settings
+        subjects {
+            __typename
+            resource
+            contents
+            keys
+            target
+            overrides {
+                identifiers
+                contents
+            }
+        }
+        explainPlan {
+            mergeOrder
+            targetName
+            effectiveExtensions {
+                effectiveExtensions
+                hasUserCustomizations
+            }
+        }
+    }
+}
+```
+
+With variables:
+
+```json
+{
+    "uri": {
+        "scheme": "cdecode",
+        "authority": "default",
+        "path": "/<your-org-slug>",
+        "fragment": "settings"
+    },
+    "options": {
+        "schemaId": "configuration",
+        "includeMarketplace": true,
+        "target": 4
+    }
+}
+```
+
+**Comparison checklist:**
+
+1. `pageExplainPlan.mergeOrder` should match `pageSettings.explainPlan.mergeOrder`.
+2. For each subject in `pageExplainPlan.subjects`, there should be a corresponding entry in `pageSettings.subjects`.
+3. If a subject has `resource: null` in the plan, the corresponding `pageSettings` subject may be missing or have empty `contents`.
+4. Check `pageSettings.subjects[].keys` — if your expected setting key isn't listed, the configuration for that extension didn't load.
+
+---
+
+## Example: Full Debugging Session
+
+**Scenario:** Extension `my-org/workflow-ext` settings are not appearing.
+
+**Step 1:** Run `pageExplainPlan`:
+
+```json
+{
+    "resourceUri": {
+        "scheme": "cdecode",
+        "authority": "default",
+        "path": "/my-org",
+        "fragment": "settings"
+    },
+    "options": {
+        "schemaId": "configuration",
+        "includeMarketplace": true,
+        "target": 4
+    }
+}
+```
+
+**Step 2:** Check `effectiveExtensions.defaultPublicExtensions`:
+
+```json
+"defaultPublicExtensions": {
+  "my-org/workflow-ext": true,
+  "my-org/other-ext": true
+}
+```
+
+✅ Extension is registered and default-enabled.
+
+**Step 3:** Check `effectiveExtensions.userDisabledPublicExtensions`:
+
+```json
+"userDisabledPublicExtensions": ["my-org/workflow-ext"]
+```
+
+❌ **Found it!** The user/org has disabled this extension.
+
+**Step 4:** Check `effectiveExtensions.userExtensionOverrides`:
+
+```json
+"userExtensionOverrides": {
+  "my-org/workflow-ext": false
+}
+```
+
+Confirmed — someone set `extensions.my-org/workflow-ext: false` in the organization settings.
+
+**Step 5:** Fix by updating the organization settings:
+
+```json
+{ "extensions.my-org/workflow-ext": true }
+```
+
+Or remove the override entirely so the default (`true`) takes effect.
+
+**Step 6:** Re-run `pageExplainPlan` to confirm the extension now appears in `effectiveExtensions`.
+
+---
+
+## Reference: Schema IDs (`ContributionSchemaId`)
+
+Every metadata schema attached to an extension has a `schemaId` that determines **what kind of contribution** it represents. The enum lives in `common` (`generated-models.ts`).
+
+| Enum Key           | Value                | Purpose                                                                                                                                         | Used For                                                          |
+| ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `Configuration`    | `'configuration'`    | **Application settings / preferences.** Key-value settings that appear in the Settings editor.                                                  | App settings, user preferences, feature flags, integration config |
+| `UiLayout`         | `'uiLayout'`         | **UI layout contributions.** Defines how pages/views are rendered — project dashboards, marketplace pages, AI providers, forms, workflows, etc. | Page templates, credential forms, dashboard layouts               |
+| `Policy`           | `'policy'`           | **Access control & governance rules.** Defines policies like RBAC, data governance, security, usage limits.                                     | Access control, data governance, security policies, usage limits  |
+| `SubscriptionPlan` | `'subscriptionPlan'` | **Billing / subscription plan definitions.** Payment policies, feature entitlements, pricing tiers.                                             | Subscription plans, payment policies, feature entitlements        |
+| `UserRole`         | `'userRole'`         | **User role definitions.** Defines roles and their permissions within the platform.                                                             | Role definitions for RBAC                                         |
+| `Permission`       | `'permission'`       | **Permission definitions.** Fine-grained permissions that can be assigned to roles.                                                             | Permission rules for access control                               |
+| `Secrets`          | `'secrets'`          | **Secret / credential management.** Defines environment variables and secrets an extension needs.                                               | API keys, tokens, connection strings                              |
+| `Integration`      | `'integration'`      | **Integration configuration.** Used for third-party service integrations.                                                                       | OAuth, webhooks, external service config                          |
+| `Dummy`            | `'dummy'`            | **Test / placeholder schema.** Used in tests or as a no-op placeholder.                                                                         | Testing only                                                      |
+
+### Additional Schema IDs (not in the enum, used as string literals)
+
+These are used in the form-builder but aren't part of the `ContributionSchemaId` enum:
+
+| Value                  | Purpose                                                                                       |
+| ---------------------- | --------------------------------------------------------------------------------------------- |
+| `'stepper-form'`       | Multi-step wizard forms (stepper UI). Used with `FormType.MULTI_FORM`.                        |
+| `'form-page-builder'`  | Drag-and-drop page builder forms. Used with `FormType.MULTI_FORM`.                            |
+| `'commands'`           | Command palette contributions (actions users can trigger). Used with `FormType.CONTRIBUTION`. |
+| `'menus'`              | Menu contributions (context menus, title bars, etc.). Used with `FormType.CONTRIBUTION`.      |
+| `'credentials'`        | Credential form schemas (OAuth, API key, etc.). Used with `FormType.CONTRIBUTION`.            |
+| `'postgresql-builder'` | PostgreSQL database schema builder. Used with `FormType.DATABASE_BUILDER`.                    |
+| `'mysql-builder'`      | MySQL database schema builder. Used with `FormType.DATABASE_BUILDER`.                         |
+| `'mongodb-builder'`    | MongoDB/general database schema builder. Used with `FormType.DATABASE_BUILDER`.               |
+
+---
+
+## Reference: Fragment Names (`ConfigFragmentName`)
+
+The `fragment` in the `resourceUri` (and in configuration URIs) determines **which slice of the configuration document** to load. Defined in `common` (`generated-models.ts`).
+
+| Enum Key              | Value                   | Purpose                                        |
+| --------------------- | ----------------------- | ---------------------------------------------- |
+| `Settings`            | `'settings'`            | General extension/app settings (most common)   |
+| `UiSettings`          | `'uiSettings'`          | UI-specific settings (layout, theme, display)  |
+| `Policies`            | `'policies'`            | Policy configuration data                      |
+| `Permissions`         | `'permissions'`         | Permission configuration data                  |
+| `Roles`               | `'roles'`               | Role definitions                               |
+| `ContributionRoles`   | `'contributionRoles'`   | Roles defined by extension contributions       |
+| `Resources`           | `'resources'`           | Resource-level configuration                   |
+| `ApplicationPolicies` | `'applicationPolicies'` | Application-level policy rules                 |
+| `BillingPlanPolicies` | `'billingPlanPolicies'` | Billing/subscription plan policy rules         |
+| `OrgMembers`          | `'orgMembers'`          | Organization members document with role values |
+| `PaymentPolicies`     | `'paymentPolicies'`     | Payment-specific policy rules                  |
+| `SubscriptionPlan`    | `'subscriptionPlan'`    | Subscription plan data                         |
+| `TeamMembers`         | `'teamMembers'`         | Team members document with role values         |
+
+### How `schemaId` and `fragment` relate
+
+| Scenario                   | `schemaId`           | `fragment`           |
+| -------------------------- | -------------------- | -------------------- |
+| Extension app settings     | `'configuration'`    | `'settings'`         |
+| UI layout / page templates | `'uiLayout'`         | `'uiSettings'`       |
+| Access control policies    | `'policy'`           | `'policies'`         |
+| Permission rules           | `'permission'`       | `'permissions'`      |
+| User roles                 | `'userRole'`         | `'roles'`            |
+| Subscription/billing plans | `'subscriptionPlan'` | `'subscriptionPlan'` |
+| Secrets/credentials        | `'secrets'`          | `'settings'`         |
+
+---
+
+## Reference: Collection Names (`ConfigCollectionName`)
+
+The collection name determines **which MongoDB collection** stores the configuration data. Defined in `common` (`generated-models.ts`).
+
+| Enum Key                    | Value                         | Purpose                                        |
+| --------------------------- | ----------------------------- | ---------------------------------------------- |
+| `Organizations`             | `'organizations'`             | Organization-level configuration (most common) |
+| `Application`               | `'application'`               | Application/tenant-level configuration         |
+| `Applications`              | `'applications'`              | Multi-app configuration                        |
+| `Projects`                  | `'projects'`                  | Project-level configuration                    |
+| `Teams`                     | `'teams'`                     | Team-level configuration                       |
+| `Accounts`                  | `'accounts'`                  | User account configuration                     |
+| `Clients`                   | `'clients'`                   | Client/API-key configuration                   |
+| `Workspaces`                | `'workspaces'`                | Workspace-level configuration                  |
+| `Tasks`                     | `'tasks'`                     | Task-level configuration                       |
+| `Tags`                      | `'tags'`                      | Tag/label configuration                        |
+| `Machines`                  | `'machines'`                  | Machine-specific configuration                 |
+| `IntegrationWorkflow`       | `'integrationWorkflow'`       | Integration workflow configuration             |
+| `Integrationconfigurations` | `'integrationconfigurations'` | Integration service configuration              |
+| `Post`                      | `'POST'`                      | Post/content configuration                     |
+
+---
+
+## Reference: Extension Names (`ConfigExtensionName`)
+
+The extension name determines **which sub-document** within a configuration collection holds the data.
+
+| Enum Key      | Value           | Purpose                       |
+| ------------- | --------------- | ----------------------------- |
+| `Settings`    | `'settings'`    | General settings sub-document |
+| `Policies`    | `'policies'`    | Policy sub-document           |
+| `Permissions` | `'permissions'` | Permissions sub-document      |
+| `Userrole`    | `'userrole'`    | User role sub-document        |
+
+---
+
+## Reference: URI Construction Pattern
+
+A full configuration URI follows this pattern:
+
+```
+cdecode://<authority>/<org-slug>[/<resource-path>]#<fragmentName>
+```
+
+When the system resolves settings internally it builds a MongoDB query URI like:
+
+```
+mongo-db-file:///configuration_registry?schemaId=<schemaId>&target=<target>&isMarketplace=<bool>&source=<source>
+```
+
+### Example URIs by schema type
+
+| Schema             | URI Fragment        | Options                                       |
+| ------------------ | ------------------- | --------------------------------------------- |
+| App settings       | `#settings`         | `{ schemaId: 'configuration', target: 4 }`    |
+| UI layout          | `#uiSettings`       | `{ schemaId: 'uiLayout', target: 4 }`         |
+| Policies           | `#policies`         | `{ schemaId: 'policy', target: 4 }`           |
+| Permissions        | `#permissions`      | `{ schemaId: 'permission', target: 4 }`       |
+| Roles              | `#roles`            | `{ schemaId: 'userRole', target: 4 }`         |
+| Subscription plans | `#subscriptionPlan` | `{ schemaId: 'subscriptionPlan', target: 4 }` |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cdmbase/wiki-browser",
-    "version": "12.0.18-alpha.34",
+    "version": "12.0.18-alpha.35",
     "description": "Sample core for higher packages to depend on",
     "license": "ISC",
     "author": "CDMBase LLC",
@@ -65,7 +65,7 @@
             }
         ]
     },
-    "gitHead": "1e021fb8d6fcdf2175710999bff071692302a201",
+    "gitHead": "251e8b5529d82c2cefc13184761e35eb0e1cee2f",
     "typescript": {
         "definition": "lib/index.d.ts"
     }