@cdmbase/wiki-browser 12.0.18-alpha.10

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

@@ -0,0 +1,1289 @@
+# How to Use PageSettings with cdecode URIs
+
+This comprehensive guide explains how to properly use PageSettings with cdecode URIs, including URI generation, configuration parameters, and best practices. **Stop manually constructing URI objects** and use the `generateCdecodeUri` utility instead.
+
+## Table of Contents
+
+- [Why Use generateCdecodeUri?](#why-use-generatecdecodeuri)
+- [Understanding Key Concepts](#understanding-key-concepts)
+    - [target (ConfigurationTarget)](#target-configurationtarget)
+    - [schemaId (ContributionSchemaId)](#schemaid-contributionschemaid)
+    - [meta\_\* Parameters](#meta_-parameters)
+    - [idField Parameter](#idfield-parameter)
+    - [fragment (ConfigFragmentName)](#fragment-configfragmentname)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Real Examples](#real-examples)
+- [Migration Guide](#migration-guide)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Why Use generateCdecodeUri?
+
+### ❌ Don't Do This (Manual Construction)
+
+```typescript
+// WRONG: Manual URI construction is error-prone
+resourceUri: {
+    $mid: 1,
+    path: `//applications/${envConfig.APPLICATION_ID}`,
+    scheme: 'cdecode',
+    authority: 'default',
+    query: 'meta_idField=appId',
+    fragment: 'uiSettings',
+}
+```
+
+**Problems with manual construction:**
+
+- Easy to make mistakes in path formatting
+- Inconsistent handling of special characters
+- Doesn't handle reserved parameters correctly
+- Hard to maintain when URI structure changes
+- Missing proper type safety
+
+### ✅ Do This Instead (Use generateCdecodeUri)
+
+```typescript
+// CORRECT: Type-safe, validated URI generation
+import { generateCdecodeUri, DEFAULT_CONTRIBUTION_TENANT_ID } from '@adminide-stack/core';
+import { ConfigCollectionName, ConfigFragmentName } from 'common';
+
+const resourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID, // or 'default'
+    {
+        resourceType: ConfigCollectionName.Applications,
+        resourceId: envConfig.APPLICATION_ID,
+        idField: 'appId', // Automatically converts to meta_idField query param
+    },
+    {}, // Additional query parameters (optional)
+    ConfigFragmentName.UiSettings as string, // Fragment (optional)
+);
+
+// Use with query
+const { data } = useGetPageSettingsQuery({
+    variables: {
+        resourceUri: resourceUri.toJSON(), // Convert to JSON format
+        options: {
+            /* ... */
+        },
+    },
+});
+```
+
+## Understanding Key Concepts
+
+Before diving into URI generation, it's crucial to understand the key parameters used with PageSettings queries. These parameters control what data you retrieve and where it's stored.
+
+### target (ConfigurationTarget)
+
+`ConfigurationTarget` defines the **scope** or **level** at which configuration settings are stored and retrieved.
+
+#### What is ConfigurationTarget?
+
+Think of ConfigurationTarget as the "layer" where settings live in a hierarchical configuration system, similar to VS Code's settings hierarchy (User → Workspace → Folder).
+
+```typescript
+export enum ConfigurationTarget {
+    USER = 1, // User-level settings (global across all orgs)
+    APPLICATION = 2, // Application-level defaults
+    MACHINE = 3, // Machine-specific settings
+    ORGANIZATION = 4, // Organization-level settings
+    ORGANIZATION_RESOURCE = 5, // Resource-specific within org (e.g., project, team)
+    DEFAULT = 6, // System/marketplace defaults (read-only)
+    MEMORY = 7, // Temporary in-memory settings
+    RESOURCE_OVERRIDABLE = 8, // Resource-specific overrides
+}
+```
+
+#### Common Target Values
+
+| Target                  | Numeric Value | Use Case                    | Example                     |
+| ----------------------- | ------------- | --------------------------- | --------------------------- |
+| `USER`                  | 1             | Personal user preferences   | Theme, editor settings      |
+| `APPLICATION`           | 2             | App-wide defaults           | Default port, app version   |
+| `ORGANIZATION`          | 4             | Org-level settings          | Billing, org features       |
+| `ORGANIZATION_RESOURCE` | 5             | Project/team settings       | Project config, team access |
+| `DEFAULT`               | 6             | Marketplace/system defaults | Extension contributions     |
+
+#### When to Use Each Target
+
+```typescript
+// USER - Personal preferences
+target: ConfigurationTarget.USER;
+// URI: cdecode://default/userId#settings
+
+// ORGANIZATION - Org-wide settings
+target: ConfigurationTarget.ORGANIZATION;
+// URI: cdecode://default/orgName#settings
+
+// ORGANIZATION_RESOURCE - Specific resource (project, team)
+target: ConfigurationTarget.ORGANIZATION_RESOURCE;
+// URI: cdecode://default/orgName/project/projectId#settings
+
+// DEFAULT - Marketplace extensions (most common for templates/contributions)
+target: 6; // or ConfigurationTarget.DEFAULT
+// Used when includeMarketplace: true
+```
+
+#### Automatic Target Determination
+
+The system can automatically determine the target from your URI using `determineConfigurationTarget()`:
+
+```typescript
+import { determineConfigurationTarget, parseCdecodeUri } from '@adminide-stack/core';
+
+const uri = generateCdecodeUri('default', {
+    organization: 'myorg',
+    resourceType: ConfigCollectionName.Projects,
+    resourceId: 'proj123',
+});
+
+const parsed = parseCdecodeUri(uri);
+const target = determineConfigurationTarget(parsed);
+// Returns: ConfigurationTarget.ORGANIZATION_RESOURCE
+```
+
+**Rule of thumb:**
+
+- Has `resourceType`? → `ORGANIZATION_RESOURCE`
+- Has `organization` only? → `ORGANIZATION`
+- Neither? → `USER`
+
+---
+
+### schemaId (ContributionSchemaId)
+
+`schemaId` specifies the **type of configuration schema** you're querying. It determines which JSON schema is used to validate and structure the settings.
+
+#### What is schemaId?
+
+Each `schemaId` represents a different "category" or "type" of configuration with its own validation schema and purpose.
+
+```typescript
+export enum ContributionSchemaId {
+    Configuration = 'configuration', // General app configuration
+    UiLayout = 'uiLayout', // UI contributions (menus, commands, templates)
+    Permission = 'permission', // Permission rules
+    Policy = 'policy', // Policy definitions
+    UserRole = 'userRole', // Role-based access control
+    Secrets = 'secrets', // Secret/credential storage
+    SubscriptionPlan = 'subscriptionPlan', // Billing plans
+}
+```
+
+#### Common schemaId Values
+
+| schemaId        | Purpose                          | Typical configKey Examples                                           |
+| --------------- | -------------------------------- | -------------------------------------------------------------------- |
+| `uiLayout`      | UI contributions from extensions | `marketplace.templates`, `credential.templates`, `commands.registry` |
+| `configuration` | Application settings             | `editor.fontSize`, `app.theme`, `server.port`                        |
+| `permission`    | Access control                   | `resource.permissions`, `user.roles`                                 |
+| `policy`        | Security policies                | `security.rules`, `data.policies`                                    |
+| `secrets`       | Sensitive credentials            | `api.keys`, `tokens`                                                 |
+
+#### When to Use Each schemaId
+
+```typescript
+// UiLayout - Most common for extension contributions and templates
+options: {
+    schemaId: ContributionSchemaId.UiLayout,
+    configKey: 'marketplace.templates',
+    includeMarketplace: true,  // Include installed extensions
+}
+// Use for: Templates, commands, menus, UI contributions from extensions
+
+// Configuration - General app settings
+options: {
+    schemaId: ContributionSchemaId.Configuration,
+    configKey: 'editor.fontSize',
+}
+// Use for: App preferences, feature flags, general settings
+
+// Permission - Access control
+options: {
+    schemaId: ContributionSchemaId.Permission,
+    configKey: 'project.access',
+}
+// Use for: User permissions, resource access rules
+
+// Secrets - Sensitive data (be careful with client-side usage!)
+options: {
+    schemaId: ContributionSchemaId.Secrets,
+    configKey: 'api.credentials',
+}
+// Use for: API keys, tokens (usually server-side)
+```
+
+#### schemaId and includeMarketplace
+
+When using `schemaId: 'uiLayout'`, you almost always want `includeMarketplace: true`:
+
+```typescript
+// Fetching extension contributions (templates, commands, etc.)
+options: {
+    schemaId: ContributionSchemaId.UiLayout,
+    configKey: 'deepSearch.templates',
+    includeMarketplace: true,  // ← Include installed extensions!
+}
+```
+
+**Why?** Extension contributions are stored separately from user settings and need to be explicitly included.
+
+---
+
+### meta\_\* Parameters
+
+`meta_*` parameters are **reserved query parameters** with special handling in cdecode URIs. They provide metadata about how to interpret the URI.
+
+#### Reserved Parameters
+
+| Parameter             | Type     | Purpose                                  | Example                  |
+| --------------------- | -------- | ---------------------------------------- | ------------------------ |
+| `meta_idField`        | string   | Specifies which field is the resource ID | `appId`, `email`, `slug` |
+| `meta_extensionNames` | string[] | Filter by specific extensions            | `['ext1', 'ext2']`       |
+| `meta_schemaId`       | string   | Alternative way to specify schema        | `'uiLayout'`             |
+
+#### meta_idField
+
+**Problem:** Not all resources use `_id` as their primary key.
+
+```typescript
+// Applications use 'appId' instead of '_id'
+// Accounts might use 'email' or 'accountId'
+// Slugs might use 'slug'
+```
+
+**Solution:** Use `idField` in params (auto-converts to `meta_idField`):
+
+```typescript
+// CORRECT: Use idField in params
+const uri = generateCdecodeUri('default', {
+    resourceType: ConfigCollectionName.Applications,
+    resourceId: 'my-app-123',
+    idField: 'appId', // ← Automatically becomes meta_idField=appId
+});
+// Generates: cdecode://default//applications/my-app-123?meta_idField=appId
+
+// WRONG: Don't add to query manually
+const uri = generateCdecodeUri(
+    'default',
+    { resourceType: ConfigCollectionName.Applications, resourceId: 'my-app-123' },
+    { meta_idField: 'appId' }, // ❌ This triggers a warning!
+);
+```
+
+#### meta_extensionNames
+
+Filter results to specific extensions:
+
+```typescript
+// Query only specific extensions
+options: {
+    schemaId: ContributionSchemaId.UiLayout,
+    configKey: 'commands',
+    includeMarketplace: true,
+    // Server-side filtering by extension names
+}
+
+// In query parameters (advanced)
+const query = {
+    meta_extensionNames: ['my-extension', 'other-extension']
+};
+```
+
+#### Why meta\_\* is Reserved
+
+These parameters have **special processing logic**:
+
+- They're handled differently during URI parsing
+- They affect query execution on the server
+- They're validated separately from user-defined parameters
+
+**Never use these names for your own parameters!**
+
+```typescript
+// ❌ WRONG: Using reserved parameter names
+const query = {
+    meta_myCustomField: 'value', // Don't prefix with meta_!
+};
+
+// ✅ CORRECT: Use regular parameter names
+const query = {
+    myCustomField: 'value', // OK
+};
+```
+
+---
+
+### idField Parameter
+
+`idField` tells the system which field to use as the **primary identifier** for a resource.
+
+#### Why idField Matters
+
+Different resource types use different ID fields:
+
+| Resource Type       | ID Field | Example                      |
+| ------------------- | -------- | ---------------------------- |
+| Most resources      | `_id`    | `"507f1f77bcf86cd799439011"` |
+| Applications        | `appId`  | `"my-app-name"`              |
+| Accounts (by email) | `email`  | `"user@example.com"`         |
+| Slugs               | `slug`   | `"my-project"`               |
+| Organizations       | `name`   | `"acme-corp"`                |
+
+#### How to Use idField
+
+```typescript
+// Application URI with appId
+const appUri = generateCdecodeUri(
+    'default',
+    {
+        resourceType: ConfigCollectionName.Applications,
+        resourceId: 'yantra-app',
+        idField: 'appId', // ← Tells system to look up by appId, not _id
+    },
+    {},
+    ConfigFragmentName.UiSettings,
+);
+// Result: cdecode://default//applications/yantra-app?meta_idField=appId#uiSettings
+
+// Account URI with email
+const accountUri = generateCdecodeUri('default', {
+    organization: 'acme',
+    resourceType: ConfigCollectionName.Accounts,
+    resourceId: 'john@acme.com',
+    idField: 'email', // ← Look up account by email
+});
+// Result: cdecode://default/acme/accounts/john@acme.com?meta_idField=email
+
+// Default behavior (no idField = uses _id)
+const projectUri = generateCdecodeUri('default', {
+    organization: 'acme',
+    resourceType: ConfigCollectionName.Projects,
+    resourceId: '507f1f77bcf86cd799439011',
+    // No idField = defaults to _id
+});
+// Result: cdecode://default/acme/projects/507f1f77bcf86cd799439011
+```
+
+#### idField Auto-Conversion
+
+When you specify `idField` in params:
+
+1. It's **removed** from the path parameters
+2. It's **added** to the query string as `meta_idField`
+3. The server uses it to determine which field to query
+
+```typescript
+// Input params
+{
+    resourceType: ConfigCollectionName.Applications,
+    resourceId: 'my-app',
+    idField: 'appId'  // This param...
+}
+
+// Becomes URI
+// path: //applications/my-app
+// query: meta_idField=appId  // ...becomes this query param
+```
+
+#### Common idField Values by Resource
+
+```typescript
+// Applications
+idField: 'appId';
+
+// Accounts (by email)
+idField: 'email';
+
+// Accounts (by username)
+idField: 'username';
+
+// Organizations (by name)
+idField: 'name';
+
+// Projects/Resources with slugs
+idField: 'slug';
+
+// Most other resources (default)
+// idField: undefined (uses _id)
+```
+
+---
+
+### fragment (ConfigFragmentName)
+
+`fragment` specifies the **section** or **view** of the resource you're accessing. Think of it as a "tab" or "page" within a resource.
+
+#### What is a Fragment?
+
+In a URI, the fragment comes after the `#` symbol:
+
+```
+cdecode://default/myorg/projects/proj123#settings
+                                        ↑
+                                    fragment
+```
+
+Fragments represent different **aspects** or **views** of the same resource.
+
+#### Common Fragment Values
+
+```typescript
+export enum ConfigFragmentName {
+    Settings = 'settings', // Main settings page
+    UiSettings = 'uiSettings', // UI-specific settings
+    Permissions = 'permissions', // Access control view
+    Policies = 'policies', // Policy configuration
+    // ... more fragments
+}
+```
+
+#### Fragment Use Cases
+
+| Fragment      | Purpose           | Example Usage                  |
+| ------------- | ----------------- | ------------------------------ |
+| `settings`    | General settings  | Org settings, project settings |
+| `uiSettings`  | UI contributions  | Extension templates, commands  |
+| `permissions` | Access control    | Who can access this resource   |
+| `policies`    | Security policies | Data access rules              |
+
+#### How to Use Fragments
+
+```typescript
+// Application UI settings (for extensions/templates)
+const appUri = generateCdecodeUri(
+    'default',
+    {
+        resourceType: ConfigCollectionName.Applications,
+        resourceId: 'my-app',
+        idField: 'appId',
+    },
+    {},
+    ConfigFragmentName.UiSettings, // ← Fourth parameter
+);
+// Result: cdecode://default//applications/my-app?meta_idField=appId#uiSettings
+
+// Organization general settings
+const orgUri = generateCdecodeUri('default', { organization: 'acme' }, {}, ConfigFragmentName.Settings);
+// Result: cdecode://default/acme#settings
+
+// Project permissions
+const projectUri = generateCdecodeUri(
+    'default',
+    {
+        organization: 'acme',
+        resourceType: ConfigCollectionName.Projects,
+        resourceId: 'proj123',
+    },
+    {},
+    ConfigFragmentName.Permissions,
+);
+// Result: cdecode://default/acme/projects/proj123#permissions
+```
+
+#### Fragment as String
+
+You can also pass fragments as strings:
+
+```typescript
+// Using enum (recommended)
+ConfigFragmentName.Settings;
+
+// Using string (also works)
+'settings' as string;
+
+// Why cast to string? TypeScript strict typing
+ConfigFragmentName.UiSettings as string;
+```
+
+#### Fragment vs schemaId
+
+**Don't confuse these!**
+
+- **Fragment** = URI component (what "view" of the resource)
+- **schemaId** = Query option (what "type" of config schema)
+
+```typescript
+// Fragment in URI
+const uri = generateCdecodeUri(
+    'default',
+    { organization: 'acme' },
+    {},
+    'uiSettings', // ← Fragment (part of URI)
+);
+
+// schemaId in options
+const { data } = useGetPageSettingsQuery({
+    variables: {
+        resourceUri: uri.toJSON(),
+        options: {
+            schemaId: 'uiLayout', // ← schemaId (query option)
+            configKey: 'templates',
+        },
+    },
+});
+```
+
+**Common pattern:**
+
+```typescript
+fragment: ConfigFragmentName.UiSettings; // URI fragment
+schemaId: ContributionSchemaId.UiLayout; // Query schema
+```
+
+---
+
+## Quick Start
+
+### Basic Imports
+
+```typescript
+import { generateCdecodeUri, DEFAULT_CONTRIBUTION_TENANT_ID } from '@adminide-stack/core';
+import { ConfigCollectionName, ConfigFragmentName, ContributionSchemaId } from 'common';
+import { useGetPageSettingsQuery } from 'common/graphql';
+```
+
+### Function Signature
+
+```typescript
+generateCdecodeUri(
+    authority: string | IAuthorityComponent,
+    params: ICdecodeUriPathSegment,
+    query?: { [key: string]: string | number | string[] },
+    fragment?: ConfigFragmentName | string
+): URI
+```
+
+### Parameters Explained
+
+#### 1. **authority** (string | IAuthorityComponent)
+
+The tenant/authority identifier. Use `DEFAULT_CONTRIBUTION_TENANT_ID` or `'default'` for most cases.
+
+```typescript
+// Simple string authority
+const uri = generateCdecodeUri('default', {
+    /* ... */
+});
+
+// Or use constant
+const uri = generateCdecodeUri(DEFAULT_CONTRIBUTION_TENANT_ID, {
+    /* ... */
+});
+
+// Object format (advanced)
+const uri = generateCdecodeUri(
+    {
+        domain: 'cdecode.com',
+        region: 'us-west-2',
+        bucketOrAppName: 'myApp',
+    },
+    {
+        /* ... */
+    },
+);
+```
+
+#### 2. **params** (ICdecodeUriPathSegment)
+
+The resource path parameters:
+
+```typescript
+interface ICdecodeUriPathSegment {
+    organization?: string | null; // Organization name
+    resourceGroup?: string | null; // Project/workspace name
+    resourceType?: ConfigCollectionName; // Type of resource
+    resourceId?: string | null; // Specific resource ID
+    idField?: string; // ID field name (auto-converts to meta_idField)
+}
+```
+
+#### 3. **query** (optional)
+
+Additional query parameters as key-value pairs:
+
+```typescript
+const query = {
+    param1: 'value1',
+    param2: 123,
+    meta_extensionNames: ['ext1', 'ext2'], // Arrays supported
+};
+```
+
+**Reserved parameters** (handled automatically):
+
+- `meta_idField` - Use `idField` in params instead
+- `meta_extensionNames` - Always treated as array
+- `meta_schemaId` - Always treated as string
+
+#### 4. **fragment** (optional)
+
+The URI fragment (usually a ConfigFragmentName):
+
+```typescript
+ConfigFragmentName.Settings; // 'settings'
+ConfigFragmentName.UiSettings; // 'uiSettings'
+ConfigFragmentName.Permissions; // 'permissions'
+```
+
+## Common Patterns
+
+### Pattern 1: Application Settings
+
+**Use Case:** Fetching marketplace templates, UI layouts, or app-level settings
+
+```typescript
+const resourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        resourceType: ConfigCollectionName.Applications,
+        resourceId: config.APPLICATION_ID,
+        idField: 'appId', // Important: apps use 'appId' not '_id'
+    },
+    {},
+    ConfigFragmentName.UiSettings,
+);
+
+const { data } = useGetPageSettingsQuery({
+    variables: {
+        resourceUri: resourceUri.toJSON(),
+        options: {
+            schemaId: ContributionSchemaId.UiLayout,
+            configKey: 'marketplace.templates',
+            includeMarketplace: true,
+        },
+    },
+});
+```
+
+**Generates:** `cdecode://default//applications/${appId}?meta_idField=appId#uiSettings`
+
+### Pattern 2: Organization Settings
+
+**Use Case:** Organization-level configurations
+
+```typescript
+const resourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        organization: orgName,
+    },
+    {},
+    ConfigFragmentName.Settings,
+);
+
+const { data } = useGetPageSettingsQuery({
+    variables: {
+        resourceUri: resourceUri.toJSON(),
+        options: {
+            schemaId: ContributionSchemaId.Settings,
+            configKey: 'org.preferences',
+        },
+    },
+});
+```
+
+**Generates:** `cdecode://default/${orgName}#settings`
+
+### Pattern 3: Project Settings
+
+**Use Case:** Project-specific settings (environment tags, project config)
+
+```typescript
+const resourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        organization: orgName,
+        resourceGroup: projectId,
+        resourceType: ConfigCollectionName.Projects,
+        resourceId: projectId,
+    },
+    {},
+    ConfigFragmentName.Settings,
+);
+
+const { data } = useGetPageSettingsQuery({
+    variables: {
+        resourceUri: resourceUri.toJSON(),
+        options: {
+            schemaId: ContributionSchemaId.Settings,
+        },
+    },
+});
+```
+
+**Generates:** `cdecode://default/${orgName}/${projectId}/projects/${projectId}#settings`
+
+### Pattern 4: User Resource Settings
+
+**Use Case:** User-specific resources (accounts, profiles)
+
+```typescript
+const resourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        organization: orgName,
+        resourceType: ConfigCollectionName.Accounts,
+        resourceId: userId,
+    },
+    {},
+    ConfigFragmentName.Settings,
+);
+```
+
+**Generates:** `cdecode://default/${orgName}/accounts/${userId}#settings`
+
+### Pattern 5: Wildcard Queries
+
+**Use Case:** Querying all resources of a type
+
+```typescript
+// For deep search templates across all resources
+const resourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        organization: '*', // Wildcard
+    },
+    {},
+    ConfigFragmentName.Settings,
+);
+```
+
+**Generates:** `cdecode://default/*#settings`
+
+### Pattern 6: Reusable URI Generation
+
+**Best Practice:** Generate URIs outside components for reusability
+
+```typescript
+// At module level or in a constants file
+const genApplicationResourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        resourceType: ConfigCollectionName.Applications,
+        resourceId: config.APPLICATION_ID,
+        idField: 'appId',
+    },
+    {},
+    ConfigFragmentName.UiSettings,
+);
+
+// Use in multiple hooks/components
+export function useMarketplaceTemplates() {
+    const { data } = useGetPageSettingsQuery({
+        variables: {
+            resourceUri: genApplicationResourceUri.toJSON(),
+            options: {
+                schemaId: ContributionSchemaId.UiLayout,
+                configKey: 'marketplace.templates',
+                includeMarketplace: true,
+            },
+        },
+    });
+    // ...
+}
+
+export function useCredentialTemplates() {
+    const { data } = useGetPageSettingsQuery({
+        variables: {
+            resourceUri: genApplicationResourceUri.toJSON(),
+            options: {
+                schemaId: ContributionSchemaId.UiLayout,
+                configKey: 'credential.templates',
+                includeMarketplace: true,
+            },
+        },
+    });
+    // ...
+}
+```
+
+## Real Examples
+
+### Example 1: useTemplates Hook (Correct ✅)
+
+**File:** `packages-modules/account/browser/src/hooks/useTemplates.ts`
+
+```typescript
+import { DEFAULT_CONTRIBUTION_TENANT_ID, generateCdecodeUri } from '@adminide-stack/core';
+import { ConfigCollectionName, ConfigFragmentName, ContributionSchemaId } from 'common';
+import { useGetPageSettingsQuery } from 'common/graphql';
+
+// Generate once at module level
+const genResourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        resourceType: ConfigCollectionName.Applications,
+        resourceId: config.APPLICATION_ID,
+        idField: 'appId',
+    },
+    {},
+    ConfigFragmentName.UiSettings as string,
+);
+
+export function useTemplates() {
+    // Fetch marketplace templates
+    const { data: marketplaceData } = useGetPageSettingsQuery({
+        variables: {
+            resourceUri: genResourceUri.toJSON(),
+            options: {
+                schemaId: ContributionSchemaId.UiLayout,
+                configKey: 'marketplace.templates.codeAssistant',
+                includeMarketplace: true,
+            },
+        },
+        fetchPolicy: 'no-cache',
+    });
+
+    // Fetch credential templates
+    const { data: credentialData } = useGetPageSettingsQuery({
+        variables: {
+            resourceUri: genResourceUri.toJSON(),
+            options: {
+                schemaId: ContributionSchemaId.UiLayout,
+                configKey: 'credential.templates',
+            },
+        },
+        fetchPolicy: 'no-cache',
+    });
+
+    return {
+        marketplaceTemplates: marketplaceData?.pageSettings?.settings || [],
+        credentialTemplates: credentialData?.pageSettings?.settings || [],
+    };
+}
+```
+
+### Example 2: CredentialsTable (Correct ✅)
+
+**File:** `packages/credentials/browser/src/components/CredentialsTable.tsx`
+
+```typescript
+import { generateCdecodeUri, DEFAULT_CONTRIBUTION_TENANT_ID } from '@adminide-stack/core';
+import { ConfigCollectionName, ConfigFragmentName } from 'common';
+import { useGetPageSettingsQuery } from 'common/graphql';
+
+function CredentialsTable({ selectedProjectId, orgName }) {
+    // Generate URI dynamically based on selected project
+    const editableSettingsInput = useMemo(() => {
+        if (selectedProjectId) {
+            return generateCdecodeUri(
+                DEFAULT_CONTRIBUTION_TENANT_ID,
+                {
+                    resourceType: ConfigCollectionName.Projects,
+                    resourceId: selectedProjectId,
+                    resourceGroup: selectedProjectId,
+                    organization: orgName,
+                },
+                {},
+                ConfigFragmentName.Settings,
+            );
+        }
+        return null;
+    }, [selectedProjectId, orgName]);
+
+    const { data: settingsData } = useGetPageSettingsQuery({
+        variables: {
+            resourceUri: editableSettingsInput!,
+        },
+        skip: !editableSettingsInput,
+        fetchPolicy: 'no-cache',
+    });
+
+    // Use settingsData...
+}
+```
+
+### Example 3: FormCatalogWrapper (WRONG ❌ - Needs Migration)
+
+**File:** `packages/credentials/browser/src/pages/FormCatalogWrapper.tsx`
+
+```typescript
+// BEFORE (INCORRECT ❌)
+export const queryParamsGenerator = (params) => {
+    return {
+        pageSettings: {
+            resourceUri: {
+                $mid: 1,
+                path: `//${ConfigCollectionName.Applications}/${config.APPLICATION_ID}`,
+                scheme: 'cdecode',
+                authority: 'default',
+                query: 'meta_idField=appId',
+                fragment: 'uiSettings',
+            },
+            options: {
+                configKey: 'credential.templates',
+                target: 6,
+                schemaId: 'uiLayout',
+                includeMarketplace: true,
+            },
+        },
+    };
+};
+
+// AFTER (CORRECT ✅)
+import { generateCdecodeUri, DEFAULT_CONTRIBUTION_TENANT_ID } from '@adminide-stack/core';
+import { ConfigCollectionName, ConfigFragmentName, ContributionSchemaId } from 'common';
+
+const genResourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        resourceType: ConfigCollectionName.Applications,
+        resourceId: config.APPLICATION_ID,
+        idField: 'appId',
+    },
+    {},
+    ConfigFragmentName.UiSettings,
+);
+
+export const queryParamsGenerator = (params) => {
+    return {
+        pageSettings: {
+            resourceUri: genResourceUri.toJSON(),
+            options: {
+                configKey: 'credential.templates',
+                target: 6,
+                schemaId: ContributionSchemaId.UiLayout,
+                includeMarketplace: true,
+            },
+        },
+    };
+};
+```
+
+### Example 4: Deep Search Config (Mixed - Partially Correct)
+
+**File:** `packages-modules/account/browser/src/hooks/useDeepSearchConfig.ts`
+
+```typescript
+// CURRENT (INCORRECT ❌) - Manual construction
+export function useDeepSearchConfig() {
+    const { data } = useGetPageSettingsQuery({
+        variables: {
+            resourceUri: {
+                scheme: 'cdecode',
+                authority: 'default',
+                path: '*',
+                query: 'deepSearch.templates',
+                fragment: 'settings',
+            },
+            options: {
+                schemaId: 'uiLayout',
+                configKey: 'deepSearch.templates',
+                includeMarketplace: true,
+            },
+        },
+    });
+}
+
+// SHOULD BE (CORRECT ✅)
+import { generateCdecodeUri, DEFAULT_CONTRIBUTION_TENANT_ID } from '@adminide-stack/core';
+import { ConfigFragmentName } from 'common';
+
+const deepSearchResourceUri = generateCdecodeUri(
+    DEFAULT_CONTRIBUTION_TENANT_ID,
+    {
+        organization: '*', // Wildcard for all orgs
+    },
+    {},
+    ConfigFragmentName.Settings,
+);
+
+export function useDeepSearchConfig() {
+    const { data } = useGetPageSettingsQuery({
+        variables: {
+            resourceUri: deepSearchResourceUri.toJSON(),
+            options: {
+                schemaId: ContributionSchemaId.UiLayout,
+                configKey: 'deepSearch.templates',
+                includeMarketplace: true,
+            },
+        },
+        fetchPolicy: 'cache-first',
+    });
+}
+```
+
+## Migration Guide
+
+### Step 1: Add Imports
+
+```typescript
+import { generateCdecodeUri, DEFAULT_CONTRIBUTION_TENANT_ID } from '@adminide-stack/core';
+import { ConfigCollectionName, ConfigFragmentName, ContributionSchemaId } from 'common';
+```
+
+### Step 2: Identify Manual URI Objects
+
+Search your codebase for:
+
+- `resourceUri: { $mid: 1, path: `, scheme: 'cdecode'`
+- Manual path construction like `path: \`//applications/${id}\``
+- Manual query strings like `query: 'meta_idField=appId'`
+
+### Step 3: Convert to generateCdecodeUri
+
+#### Conversion Table
+
+| Manual Construction              | generateCdecodeUri Equivalent                                                                                    |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `path: '//applications/${id}'`   | `{ resourceType: ConfigCollectionName.Applications, resourceId: id, idField: 'appId' }`                          |
+| `path: '/org'`                   | `{ organization: 'org' }`                                                                                        |
+| `path: '/org/proj/accounts/123'` | `{ organization: 'org', resourceGroup: 'proj', resourceType: ConfigCollectionName.Accounts, resourceId: '123' }` |
+| `query: 'meta_idField=appId'`    | `idField: 'appId'` in params                                                                                     |
+| `fragment: 'settings'`           | `ConfigFragmentName.Settings`                                                                                    |
+| `authority: 'default'`           | `DEFAULT_CONTRIBUTION_TENANT_ID`                                                                                 |
+
+### Step 4: Update Query Variables
+
+```typescript
+// Before
+variables: {
+    resourceUri: { $mid: 1, path: '//...', scheme: 'cdecode', authority: 'default' }
+}
+
+// After
+variables: {
+    resourceUri: generatedUri.toJSON()  // Don't forget .toJSON()!
+}
+```
+
+### Step 5: Test
+
+- Verify queries still return expected data
+- Check browser network tab for correct URI format
+- Ensure TypeScript compilation succeeds
+
+## Best Practices
+
+### ✅ Do's
+
+1. **Generate URIs at module level when possible**
+
+    ```typescript
+    // At top of file, outside components
+    const APP_RESOURCE_URI = generateCdecodeUri(
+        DEFAULT_CONTRIBUTION_TENANT_ID,
+        { resourceType: ConfigCollectionName.Applications, resourceId: APP_ID, idField: 'appId' },
+        {},
+        ConfigFragmentName.UiSettings,
+    );
+    ```
+
+2. **Use memoization for dynamic URIs**
+
+    ```typescript
+    const resourceUri = useMemo(() => generateCdecodeUri(authority, { organization: orgId }), [orgId]);
+    ```
+
+3. **Always call `.toJSON()` when passing to queries**
+
+    ```typescript
+    resourceUri: myUri.toJSON(); // Required!
+    ```
+
+4. **Use ConfigCollectionName enum**
+
+    ```typescript
+    resourceType: ConfigCollectionName.Applications; // Not: 'applications'
+    ```
+
+5. **Use ConfigFragmentName enum**
+
+    ```typescript
+    fragment: ConfigFragmentName.Settings; // Not: 'settings'
+    ```
+
+6. **Use idField for non-\_id fields**
+    ```typescript
+    {
+        resourceType: ConfigCollectionName.Applications,
+        resourceId: appId,
+        idField: 'appId' // Automatically becomes meta_idField query param
+    }
+    ```
+
+### ❌ Don'ts
+
+1. **Don't manually construct URI objects**
+
+    ```typescript
+    // WRONG
+    resourceUri: { $mid: 1, path: '//...', scheme: 'cdecode' }
+    ```
+
+2. **Don't manually build query strings**
+
+    ```typescript
+    // WRONG
+    query: 'meta_idField=appId&param=value'
+
+    // RIGHT
+    { idField: 'appId' }, { param: 'value' }
+    ```
+
+3. **Don't use string literals for collections**
+
+    ```typescript
+    // WRONG
+    resourceType: 'applications';
+
+    // RIGHT
+    resourceType: ConfigCollectionName.Applications;
+    ```
+
+4. **Don't forget .toJSON()**
+
+    ```typescript
+    // WRONG
+    resourceUri: generateCdecodeUri(...)
+
+    // RIGHT
+    resourceUri: generateCdecodeUri(...).toJSON()
+    ```
+
+5. **Don't mix path construction styles**
+
+    ```typescript
+    // WRONG
+    path: `//${resourceType}/${resourceId}`; // Manual path
+
+    // RIGHT
+    {
+        (resourceType, resourceId);
+    } // Use params
+    ```
+
+## Troubleshooting
+
+### Issue: Query returns no data
+
+**Check:**
+
+1. Did you call `.toJSON()` on the URI?
+2. Is the `idField` correct for your resource type?
+3. Does your resource ID actually exist?
+4. Is the fragment correct?
+
+```typescript
+// Debug by logging
+const uri = generateCdecodeUri(...);
+console.log('Generated URI:', uri.toString());
+console.log('URI JSON:', uri.toJSON());
+```
+
+### Issue: TypeScript errors
+
+**Solution:** Ensure you're importing types correctly:
+
+```typescript
+import { ConfigCollectionName, ConfigFragmentName } from 'common';
+import type { ICdecodeUriPathSegment } from '@adminide-stack/core';
+```
+
+### Issue: Reserved parameter warnings
+
+**Solution:** Use the appropriate param field instead of query:
+
+```typescript
+// WRONG - Reserved parameter in query
+{ resourceType: ..., resourceId: ... }, { meta_idField: 'appId' }
+
+// RIGHT - Use idField in params
+{ resourceType: ..., resourceId: ..., idField: 'appId' }, {}
+```
+
+### Issue: Empty/null resource IDs
+
+**Solution:** Handle conditional URI generation:
+
+```typescript
+const resourceUri = useMemo(() => {
+    if (!projectId) return null;
+
+    return generateCdecodeUri(DEFAULT_CONTRIBUTION_TENANT_ID, {
+        organization: orgName,
+        resourceType: ConfigCollectionName.Projects,
+        resourceId: projectId,
+    });
+}, [projectId, orgName]);
+
+// Skip query if no URI
+const { data } = useGetPageSettingsQuery({
+    variables: { resourceUri: resourceUri?.toJSON() },
+    skip: !resourceUri, // Important!
+});
+```
+
+### Issue: URI doesn't match expected format
+
+**Debug approach:**
+
+```typescript
+const uri = generateCdecodeUri(authority, params, query, fragment);
+
+// Log different formats
+console.log('String:', uri.toString());
+console.log('Path:', uri.path);
+console.log('Query:', uri.query);
+console.log('Fragment:', uri.fragment);
+console.log('JSON:', uri.toJSON());
+
+// Parse it back to verify
+import { parseCdecodeUri } from '@adminide-stack/core';
+const parsed = parseCdecodeUri(uri);
+console.log('Parsed segments:', parsed.pathSegments);
+console.log('Parsed query:', parsed.queryData);
+```
+
+## Reference: ConfigCollectionName Values
+
+```typescript
+enum ConfigCollectionName {
+    Applications = 'applications',
+    Accounts = 'accounts',
+    Projects = 'projects',
+    Teams = 'teams',
+    Organizations = 'organizations',
+    Workflows = 'workflows',
+    // ... check common package for full list
+}
+```
+
+## Reference: ConfigFragmentName Values
+
+```typescript
+enum ConfigFragmentName {
+    Settings = 'settings',
+    UiSettings = 'uiSettings',
+    Permissions = 'permissions',
+    // ... check common package for full list
+}
+```
+
+## Summary Checklist
+
+Before using `GetPageSettingsQuery`, verify:
+
+- [ ] Using `generateCdecodeUri` instead of manual construction
+- [ ] Imported necessary types and enums from `@adminide-stack/core` and `common`
+- [ ] Using `DEFAULT_CONTRIBUTION_TENANT_ID` or appropriate authority
+- [ ] Using `ConfigCollectionName` enum for resource types
+- [ ] Using `ConfigFragmentName` enum for fragments
+- [ ] Using `idField` in params for non-\_id identifiers
+- [ ] Calling `.toJSON()` when passing URI to query
+- [ ] Handling null/undefined cases with `skip` option
+- [ ] Using `useMemo` for dynamic URIs to prevent unnecessary re-generation
+
+## Additional Resources
+
+- [cdecodeUri.ts](../../packages/adminide-core/src/utils/cdecodeUri.ts) - Implementation source
+- [cdecodeUri.test.ts](../../packages/adminide-core/src/utils/cdecodeUri.test.ts) - Unit tests with examples
+- [README-PageSettings.md](./README-PageSettings.md) - PageSettings usage guide
+
+---
+
+**Last Updated:** January 18, 2026  
+**Version:** 1.0.0