Address code review feedback - add missing zod file titles and clarify cleanup logic

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

content/docs/references/system/api/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "API Configuration"
+  "title": "Api"
 }

content/docs/references/system/discovery/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "Discovery"
+  "title": "Service Discovery"
 }

content/docs/references/system/job/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "Job"
+  "title": "Jobs"
 }

content/docs/references/system/organization/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "Organization"
+  "title": "Organizations"
 }

content/docs/references/system/plugin/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "Plugin"
+  "title": "Plugins"
 }

content/docs/references/system/policy/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "Policy"
+  "title": "Policies"
 }

content/docs/references/system/realtime/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "Realtime"
+  "title": "Real-time Communication"
 }

content/docs/references/system/role/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "Role"
+  "title": "Roles"
 }

content/docs/references/system/tenant/meta.json

@@ -1,3 +1,3 @@
 {
-  "title": "Tenant"
+  "title": "Tenants"
 }

packages/spec/scripts/build-docs.ts

@@ -52,14 +52,22 @@ const ZOD_FILE_TITLES: Record<string, string> = {
   'datasource': 'Datasources',
   'driver': 'Drivers',
   'auth': 'Authentication',
+  'identity': 'Identity',
+  'role': 'Roles',
+  'policy': 'Policies',
+  'organization': 'Organizations',
+  'tenant': 'Tenants',
   'webhook': 'Webhooks',
-  'api': 'API Configuration',
+  'events': 'Events',
+  'job': 'Jobs',
+  'realtime': 'Real-time Communication',
+  'discovery': 'Service Discovery',
+  'plugin': 'Plugins',
   'translation': 'Translations',
   'audit': 'Audit',
   'territory': 'Territories',
   'license': 'Licenses',
   'plan': 'Plans',
-  'rbac': 'Role-Based Access Control',
   // API
   'contract': 'API Contracts'
 };
@@ -171,7 +179,9 @@ function generateMarkdown(schemaName: string, schema: any) {
 }
 
 // 2. Clean up old documentation structure
-// Remove old .mdx files and subdirectories from category roots
+// IMPORTANT: This removes old .mdx files and subdirectories to ensure a clean state.
+// Only category roots are cleaned (data/, ui/, system/, ai/, api/). The root meta.json is preserved.
+// All necessary directories and files are regenerated in step 3, so this is safe.
 Object.keys(CATEGORIES).forEach(category => {
   const dir = path.join(DOCS_ROOT, category);
   if (fs.existsSync(dir)) {
@@ -180,14 +190,14 @@ Object.keys(CATEGORIES).forEach(category => {
       const entryPath = path.join(dir, entry);
       const stat = fs.statSync(entryPath);
 
-      // Remove old .mdx files from category root
+      // Remove old .mdx files from category root (these will be moved to subfolders)
       if (stat.isFile() && entry.endsWith('.mdx')) {
         fs.unlinkSync(entryPath);
         console.log(`Removed old file: ${category}/${entry}`);
       }
-      // Remove old subdirectories (but keep meta.json)
+      // Remove old subdirectories (will be recreated with correct structure in step 3)
+      // Note: meta.json is preserved as it's not a directory
       else if (stat.isDirectory()) {
-        // We'll recreate the directories we need, so remove all existing ones
         fs.rmSync(entryPath, { recursive: true, force: true });
         console.log(`Removed old directory: ${category}/${entry}`);
       }