Praxis Settings Global Config
The praxis-settings-* skill family is the canonical Codex skill surface for @praxisui/settings-panel and projects/praxis-settings-panel; do not create parallel praxis-settings-panel-* guidance unless this family cannot express a proven contract gap.
Use this skill for the global configuration editor inside @praxisui/settings-panel. Global config is a governed platform configuration surface, not a screen-local settings form.
Canonical Boundary
GlobalConfigService in @praxisui/core owns effective runtime config, storage readiness, and save/clear APIs.
GlobalConfigAdminService reads effective config and persists partial updates.
GlobalConfigEditorComponent owns the visual editor, dynamic form sections, AI provider/model controls, validation, dirty/busy state, and save/clear UX.
buildGlobalConfigFormConfig owns the dynamic form schema for editable global config fields.
- Remote persistence belongs to the configured global config storage, commonly
/api/praxis/config/** from praxis-config-starter.
praxis-config-starter owns /api/praxis/config/ui persistence in ui_user_config, including tenant/user/environment scope, ETag preconditions, payload limits, write authorization, and secret sanitization.
Use praxis-config-runtime-persistence when save, clear, reload, tenant/user/environment scope, ETag, or remote config storage semantics depend on praxis-config-starter. Use praxis-config-ai-registry-manifests or praxis-config-agentic-authoring-streaming when global settings affect AI provider/model, registry, or authoring backend contracts.
Required Inventory
Inspect:
praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.component.ts
praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-admin.service.ts
praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.schema.ts
praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.models.ts
praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.tokens.ts
praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/open-global-config-editor.ts
praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/*.spec.ts
praxis-ui-angular/projects/praxis-settings-panel/src/lib/i18n/global-config-editor.i18n.ts
praxis-ui-angular/projects/praxis-core/src/lib/services/global-config.service.ts
praxis-ui-angular/projects/praxis-core/src/lib/services/config-storage.service.ts
praxis-ui-angular/projects/praxis-core/src/lib/tokens/global-config.providers.ts
praxis-ui-angular/projects/praxis-core/src/lib/tokens/global-config.token.ts
praxis-ui-angular/projects/praxis-core/src/lib/models/global-config.model.ts
praxis-ui-angular/projects/praxis-core/src/lib/services/global-config.service.spec.ts
praxis-ui-angular/docs/global-config.md
When remote persistence is touched, also inspect:
praxis-config-starter/src/main/java/org/praxisplatform/config/controller/UserConfigController.java
praxis-config-starter/src/main/java/org/praxisplatform/config/service/UserConfigService.java
praxis-config-starter/src/main/java/org/praxisplatform/config/service/UiConfigWriteAuthorizer.java
praxis-config-starter/src/main/java/org/praxisplatform/config/domain/UiUserConfig.java
Current Contract
GlobalConfigService.ready() loads the active storage key before consumers rely on effective config.
- The storage key is
praxis:global-config or praxis:global-config:{tenant} when a tenant is set or resolved.
setTenant() changes the active key and invalidates the loaded config/cache state.
- Effective config is built from configured provider values plus the stored config overlay. Runtime getters such as
getCrud(), getDynamicFields(), getTable(), getPages(), getDialog(), and get(path) read that merged effective snapshot.
GlobalConfig.pages.defaults (layoutPreset, themePreset, shellPreset, columns, gap, paddingInline, autoRows) defines corporate defaults for <praxis-dynamic-page> and Page Builder editors when the corresponding WidgetPageDefinition properties are omitted.
saveGlobalConfig(partial) deep-merges the partial over the current effective config, persists the merged config through ASYNC_CONFIG_STORAGE, updates the in-memory snapshot, and emits config changes.
clearGlobalConfig() clears the active storage key, reloads effective config from provider/server defaults, resets the stored snapshot, and emits config changes.
hasStoredConfig() is meaningful only after the service is ready because it reflects the loaded storage snapshot.
GlobalConfigAdminService must use public GlobalConfigService getters and save/clear APIs; do not reach into cache internals or duplicate merge logic.
GlobalConfigEditorComponent.getSettingsValue() returns only changed fields by comparing currentValues with initialValues.
- Changed form fields are nested by
dataAttributes.globalPath; generated safe names are an implementation detail and must not become persisted contract.
onSave() validates compact table appearance and dynamic page CSS length values (pages.defaults.gap, pages.defaults.paddingInline) before save, toggles busy state, delegates to GlobalConfigAdminService.save(partial), updates the baseline after success, and returns undefined on blocked/failed saves.
clearStoredConfig() delegates to GlobalConfigAdminService.clearStoredConfig(), reloads effective config, resets forms from the fresh snapshot, and refreshes the stored/source indicator.
Rules
- Preserve tenant/global storage semantics; do not store global config in a host-local singleton when the configured storage contract exists.
- Save partial config intentionally. Do not overwrite unrelated global config branches when editing CRUD, dynamic-fields, table, dynamic-pages, cache, dialog, or AI settings.
clearStoredConfig() must return to server/provider defaults and refresh effective config.
- Every editable dynamic form field must declare
dataAttributes.globalPath. Add a new editable path only when a runtime consumer reads that path from GlobalConfigService or the same change adds that canonical runtime consumption.
- Keep
buildGlobalConfigFormConfig field names as safe names derived from global paths; do not persist or document safe names as public config paths.
- Compact table appearance fields and dynamic page CSS length fields (
pages.defaults.gap, pages.defaults.paddingInline) must normalize whitespace and reject invalid CSS length values before persistence.
GlobalConfigEditorComponent.buildSectionConfig must strip inner section title values and propagate this.formConfig.actions so each accordion section renders frameless without duplicating the accordion header or recreating hidden form action chrome.
- AI provider/model settings must use the AI provider catalog and backend test/model APIs where available; do not persist only opaque display strings.
- AI model requests should include
apiKey only when the user typed a new key. Stored keys are server-side state and must not be exposed back into the editor as raw values.
- Preserve
apiKeyLast4, hasStoredApiKey, and safe status labels as UI state only. They are not the persisted secret.
- Backend error details for AI keys, model fetching, and save failures must not leak raw upstream or encryption messages into visible editor copy.
- Keep dynamic form fields and validation aligned with runtime config consumers.
- Put authoring chrome text in Settings Panel i18n catalogs; avoid hardcoded visible strings.
- Open the editor through
openGlobalConfigEditor(settingsPanelService, options) / SettingsPanelService.open; do not create a separate drawer or dialog host for global config.
GLOBAL_CONFIG_DYNAMIC_FORM_COMPONENT intentionally keeps settings-panel from depending directly on dynamic-form. Preserve this injection-token bridge and its ComponentMetadataRegistry.get('praxis-dynamic-form')?.componentType fallback so hosts that register Dynamic Form in the component registry do not need manual provider boilerplate.
Remote Persistence Rules
ApiConfigStorage maps praxis:global-config* keys to component type praxis-global-config-editor and component id equal to the storage key.
/api/praxis/config/ui requires X-Tenant-ID. X-User-ID, X-Env, X-Updated-By, and scope=user|tenant govern the resolved record.
- Reads use
If-None-Match and may return 304 Not Modified; ApiConfigStorage must reuse the cached payload in that case.
- Saves and clears use cached
ETag as If-Match when available. A 412 Precondition Failed is a real concurrency signal; do not mask it as a successful save.
UserConfigService owns user-vs-tenant resolution, payload size limits, ETag generation, precondition checks, and AI key sanitization before writing ui_user_config.
UserConfigController sanitizes secret fields again for response. UI code must treat returned key material as status metadata, not as the raw credential.
- If bootstrap uses
providePraxisGlobalConfigBootstrap, preserve the auth gate, tenant resolver, headers factory, errorPolicy, and blocking mode semantics.
Validation
Prefer focused checks:
npx ng test praxis-settings-panel --watch=false --progress=false --include=projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.component.spec.ts
npx ng test praxis-settings-panel --watch=false --progress=false --include=projects/praxis-settings-panel/src/lib/global-config-editor/global-config-admin.dialog.spec.ts
npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/services/global-config.service.spec.ts
For persistence changes, validate save, clear, reload/reopen, and runtime consumption. A successful form submit is not enough if the next open reads a different effective value.
For /api/praxis/config/ui changes, add a focused praxis-config-starter validation that proves tenant/user scope, ETag/If-Match, delete, and sanitized AI key response behavior. Use praxis-config-runtime-persistence for the backend-specific test selection.
1---2name: praxis-settings-global-config3description: Use when changing or reviewing @praxisui/settings-panel or praxis-settings-panel package Global Config Editor, GlobalConfigAdminService, openGlobalConfigEditor, global config schema, AI provider/model settings, cache/persistence settings, dynamic-fields/table/CRUD global policies, stored config clear/save behavior, or `/api/praxis/config/**`-backed global config persistence.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-settings-global-config6---78# Praxis Settings Global Config910The `praxis-settings-*` skill family is the canonical Codex skill surface for `@praxisui/settings-panel` and `projects/praxis-settings-panel`; do not create parallel `praxis-settings-panel-*` guidance unless this family cannot express a proven contract gap.1112Use this skill for the global configuration editor inside `@praxisui/settings-panel`. Global config is a governed platform configuration surface, not a screen-local settings form.1314## Canonical Boundary1516- `GlobalConfigService` in `@praxisui/core` owns effective runtime config, storage readiness, and save/clear APIs.17- `GlobalConfigAdminService` reads effective config and persists partial updates.18- `GlobalConfigEditorComponent` owns the visual editor, dynamic form sections, AI provider/model controls, validation, dirty/busy state, and save/clear UX.19- `buildGlobalConfigFormConfig` owns the dynamic form schema for editable global config fields.20- Remote persistence belongs to the configured global config storage, commonly `/api/praxis/config/**` from `praxis-config-starter`.21- `praxis-config-starter` owns `/api/praxis/config/ui` persistence in `ui_user_config`, including tenant/user/environment scope, ETag preconditions, payload limits, write authorization, and secret sanitization.2223Use `praxis-config-runtime-persistence` when save, clear, reload, tenant/user/environment scope, ETag, or remote config storage semantics depend on `praxis-config-starter`. Use `praxis-config-ai-registry-manifests` or `praxis-config-agentic-authoring-streaming` when global settings affect AI provider/model, registry, or authoring backend contracts.2425## Required Inventory2627Inspect:2829- `praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.component.ts`30- `praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-admin.service.ts`31- `praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.schema.ts`32- `praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.models.ts`33- `praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.tokens.ts`34- `praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/open-global-config-editor.ts`35- `praxis-ui-angular/projects/praxis-settings-panel/src/lib/global-config-editor/*.spec.ts`36- `praxis-ui-angular/projects/praxis-settings-panel/src/lib/i18n/global-config-editor.i18n.ts`37- `praxis-ui-angular/projects/praxis-core/src/lib/services/global-config.service.ts`38- `praxis-ui-angular/projects/praxis-core/src/lib/services/config-storage.service.ts`39- `praxis-ui-angular/projects/praxis-core/src/lib/tokens/global-config.providers.ts`40- `praxis-ui-angular/projects/praxis-core/src/lib/tokens/global-config.token.ts`41- `praxis-ui-angular/projects/praxis-core/src/lib/models/global-config.model.ts`42- `praxis-ui-angular/projects/praxis-core/src/lib/services/global-config.service.spec.ts`43- `praxis-ui-angular/docs/global-config.md`4445When remote persistence is touched, also inspect:4647- `praxis-config-starter/src/main/java/org/praxisplatform/config/controller/UserConfigController.java`48- `praxis-config-starter/src/main/java/org/praxisplatform/config/service/UserConfigService.java`49- `praxis-config-starter/src/main/java/org/praxisplatform/config/service/UiConfigWriteAuthorizer.java`50- `praxis-config-starter/src/main/java/org/praxisplatform/config/domain/UiUserConfig.java`5152## Current Contract5354- `GlobalConfigService.ready()` loads the active storage key before consumers rely on effective config.55- The storage key is `praxis:global-config` or `praxis:global-config:{tenant}` when a tenant is set or resolved.56- `setTenant()` changes the active key and invalidates the loaded config/cache state.57- Effective config is built from configured provider values plus the stored config overlay. Runtime getters such as `getCrud()`, `getDynamicFields()`, `getTable()`, `getPages()`, `getDialog()`, and `get(path)` read that merged effective snapshot.58- `GlobalConfig.pages.defaults` (`layoutPreset`, `themePreset`, `shellPreset`, `columns`, `gap`, `paddingInline`, `autoRows`) defines corporate defaults for `<praxis-dynamic-page>` and Page Builder editors when the corresponding `WidgetPageDefinition` properties are omitted.59- `saveGlobalConfig(partial)` deep-merges the partial over the current effective config, persists the merged config through `ASYNC_CONFIG_STORAGE`, updates the in-memory snapshot, and emits config changes.60- `clearGlobalConfig()` clears the active storage key, reloads effective config from provider/server defaults, resets the stored snapshot, and emits config changes.61- `hasStoredConfig()` is meaningful only after the service is ready because it reflects the loaded storage snapshot.62- `GlobalConfigAdminService` must use public `GlobalConfigService` getters and save/clear APIs; do not reach into cache internals or duplicate merge logic.63- `GlobalConfigEditorComponent.getSettingsValue()` returns only changed fields by comparing `currentValues` with `initialValues`.64- Changed form fields are nested by `dataAttributes.globalPath`; generated safe names are an implementation detail and must not become persisted contract.65- `onSave()` validates compact table appearance and dynamic page CSS length values (`pages.defaults.gap`, `pages.defaults.paddingInline`) before save, toggles busy state, delegates to `GlobalConfigAdminService.save(partial)`, updates the baseline after success, and returns `undefined` on blocked/failed saves.66- `clearStoredConfig()` delegates to `GlobalConfigAdminService.clearStoredConfig()`, reloads effective config, resets forms from the fresh snapshot, and refreshes the stored/source indicator.6768## Rules6970- Preserve tenant/global storage semantics; do not store global config in a host-local singleton when the configured storage contract exists.71- Save partial config intentionally. Do not overwrite unrelated global config branches when editing CRUD, dynamic-fields, table, dynamic-pages, cache, dialog, or AI settings.72- `clearStoredConfig()` must return to server/provider defaults and refresh effective config.73- Every editable dynamic form field must declare `dataAttributes.globalPath`. Add a new editable path only when a runtime consumer reads that path from `GlobalConfigService` or the same change adds that canonical runtime consumption.74- Keep `buildGlobalConfigFormConfig` field names as safe names derived from global paths; do not persist or document safe names as public config paths.75- Compact table appearance fields and dynamic page CSS length fields (`pages.defaults.gap`, `pages.defaults.paddingInline`) must normalize whitespace and reject invalid CSS length values before persistence.76- `GlobalConfigEditorComponent.buildSectionConfig` must strip inner section `title` values and propagate `this.formConfig.actions` so each accordion section renders frameless without duplicating the accordion header or recreating hidden form action chrome.77- AI provider/model settings must use the AI provider catalog and backend test/model APIs where available; do not persist only opaque display strings.78- AI model requests should include `apiKey` only when the user typed a new key. Stored keys are server-side state and must not be exposed back into the editor as raw values.79- Preserve `apiKeyLast4`, `hasStoredApiKey`, and safe status labels as UI state only. They are not the persisted secret.80- Backend error details for AI keys, model fetching, and save failures must not leak raw upstream or encryption messages into visible editor copy.81- Keep dynamic form fields and validation aligned with runtime config consumers.82- Put authoring chrome text in Settings Panel i18n catalogs; avoid hardcoded visible strings.83- Open the editor through `openGlobalConfigEditor(settingsPanelService, options)` / `SettingsPanelService.open`; do not create a separate drawer or dialog host for global config.84- `GLOBAL_CONFIG_DYNAMIC_FORM_COMPONENT` intentionally keeps `settings-panel` from depending directly on `dynamic-form`. Preserve this injection-token bridge and its `ComponentMetadataRegistry.get('praxis-dynamic-form')?.componentType` fallback so hosts that register Dynamic Form in the component registry do not need manual provider boilerplate.8586## Remote Persistence Rules8788- `ApiConfigStorage` maps `praxis:global-config*` keys to component type `praxis-global-config-editor` and component id equal to the storage key.89- `/api/praxis/config/ui` requires `X-Tenant-ID`. `X-User-ID`, `X-Env`, `X-Updated-By`, and `scope=user|tenant` govern the resolved record.90- Reads use `If-None-Match` and may return `304 Not Modified`; `ApiConfigStorage` must reuse the cached payload in that case.91- Saves and clears use cached `ETag` as `If-Match` when available. A `412 Precondition Failed` is a real concurrency signal; do not mask it as a successful save.92- `UserConfigService` owns user-vs-tenant resolution, payload size limits, ETag generation, precondition checks, and AI key sanitization before writing `ui_user_config`.93- `UserConfigController` sanitizes secret fields again for response. UI code must treat returned key material as status metadata, not as the raw credential.94- If bootstrap uses `providePraxisGlobalConfigBootstrap`, preserve the auth gate, tenant resolver, headers factory, `errorPolicy`, and blocking mode semantics.9596## Validation9798Prefer focused checks:99100- `npx ng test praxis-settings-panel --watch=false --progress=false --include=projects/praxis-settings-panel/src/lib/global-config-editor/global-config-editor.component.spec.ts`101- `npx ng test praxis-settings-panel --watch=false --progress=false --include=projects/praxis-settings-panel/src/lib/global-config-editor/global-config-admin.dialog.spec.ts`102- `npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/services/global-config.service.spec.ts`103104For persistence changes, validate save, clear, reload/reopen, and runtime consumption. A successful form submit is not enough if the next open reads a different effective value.105106For `/api/praxis/config/ui` changes, add a focused `praxis-config-starter` validation that proves tenant/user scope, ETag/If-Match, delete, and sanitized AI key response behavior. Use `praxis-config-runtime-persistence` for the backend-specific test selection.