newo 3.3.2 → 3.4.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.4.0] - 2025-12-25
+
+### Added
+
+- **Project Registry**: Browse and install project templates from NEWO registries
+  - `newo list-registries` - List available registries (production, staging, development, etc.)
+  - `newo list-registry-items <registry-idn>` - Browse project templates in a registry with version info
+  - `newo add-project <idn> --item <template-idn>` - Install project from registry template
+  - Support for multiple registries: production, staging, development, testing, and custom registries
+  - Version selection with `--version` flag or automatic latest version detection
+  - Auto-update support with `--auto-update` flag for automatic updates when new versions are published
+  - Grouped display showing unique projects with version counts and active installations
+  - `--all` flag to show all versions of each project template
+
+- **Registry Types** (`src/types.ts`):
+  - `Registry` - Registry metadata (id, idn, account_id, is_public)
+  - `RegistryItem` - Project template with versioning (id, idn, version, project_image, active_project_count)
+  - `RegistryItemProjectImage` - Project image metadata for templates
+  - `AddProjectFromRegistryRequest` - Request type for registry-based project installation
+
+- **Registry API Functions** (`src/api.ts`):
+  - `listRegistries()` - Fetch available registries
+  - `listRegistryItems()` - Fetch project templates from a specific registry
+  - `addProjectFromRegistry()` - Create project from registry template
+
+- **Registry Command Handlers** (`src/cli/commands/`):
+  - `list-registries.ts` - Display registries in formatted table
+  - `list-registry-items.ts` - Display projects with version grouping and sorting
+  - `add-project.ts` - Install templates with validation and progress feedback
+
+### Enhanced
+
+- **Help Command**: Added registry commands documentation and examples
+- **CLAUDE.md**: Updated with registry feature documentation, API endpoints, and data flow
+
 ## [3.3.0] - 2025-10-20
 
 ### Added
@@ -78,15 +113,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 100% entity match validation (projects, agents, flows, skills)
   - 100% file integrity verification (SHA256 checksums on attributes)
   - 100% webhook creation success (all 5 webhooks verified)
-  - Migration time: ~30 minutes (vs 8-10 hours manual process)
+  - Significant time reduction compared to manual migration process
 - **Entity Count Verification**: Automated comparison validates all entity types
 - **Webhook Creation**: Batch webhook creation from YAML files tested and verified
 
 ### Performance
 
-- **Migration Speed**: 96% time reduction compared to manual migration
-  - Automated process: ~30 minutes
-  - Manual process: 8-10 hours
+- **Migration Automation**: 100% automated with zero manual steps required
 - **Reliability**: 100% success rate across multiple test migrations
 - **Data Integrity**: Full SHA256 verification ensures zero data loss
 

package/README.md

@@ -8,8 +8,8 @@
 **NEWO CLI** - Professional command-line tool for NEWO AI Agent development. Features **modular architecture**, **IDN-based file management**, and **comprehensive multi-customer support**.
 
 Sync NEWO "Project → Agent → Flow → Skills" structure to local files with:
-- 🚀 **Account migration** - Fully automated account copying with 100% accuracy in ~30 minutes (NEW v3.3.0)
-- 🏗️ **Complete entity management** - Create, edit, and delete agents, flows, skills, events, and states (NEW v2.0+)
+- 🚀 **Account migration** - Fully automated account copying with 100% accuracy
+- 🏗️ **Complete entity management** - Create, edit, and delete agents, flows, skills, events, and states
 - 🔄 **Intelligent synchronization** - Pull projects, attributes, and conversations automatically
 - 🎯 **IDN-based naming** - Skills named as `{skillIdn}.jinja/.guidance` for better organization
 - 📊 **Real-time progress** - Live progress tracking during large operations (1,000+ skills)
@@ -19,11 +19,11 @@ Sync NEWO "Project → Agent → Flow → Skills" structure to local files with:
 - ⚡ **Smart change detection** - SHA256-based efficient sync with hash consistency
 - 🛡️ **File validation** - Multiple file detection with clear warnings and safe handling
 - 🧠 **AI skill formats** - Support for `.guidance` (AI prompts) and `.jinja` (NSL templates)
-- 📡 **Webhook automation** - Automatic webhook creation from YAML configuration (NEW v3.3.0)
+- 📡 **Webhook automation** - Automatic webhook creation from YAML configuration
 - 📊 **Knowledge base import** - Bulk import AKB articles from structured text files
 - 💬 **Conversation history** - Extract and sync user conversations and personas
-- 🧪 **Sandbox testing** - Interactive agent testing with conversation continuation (NEW v3.1.0)
-- ✅ **Migration verification** - Automated validation of migration completeness (NEW v3.3.0)
+- 🧪 **Sandbox testing** - Interactive agent testing with conversation continuation
+- ✅ **Migration verification** - Automated validation of migration completeness
 - 🔧 **CI/CD ready** - GitHub Actions integration for automated deployments
 
 ---
@@ -152,7 +152,7 @@ NEWO_REFRESH_URL=custom_refresh_endpoint   # Custom refresh endpoint
 | `newo import-akb` | Import knowledge base articles | • Structured text parsing<br>• Bulk article import<br>• Validation and error reporting |
 | `newo meta` | Get project metadata (debug) | • Project structure analysis<br>• Metadata validation |
 
-### Account Migration Commands (NEW v3.3.0)
+### Account Migration Commands
 
 **Enterprise-grade account migration with 100% automation:**
 
@@ -179,7 +179,7 @@ newo push --customer DEST_IDN
 # 4. Verify success
 newo verify --source SOURCE_IDN --dest DEST_IDN
 
-# Complete! Account migrated in ~30 minutes
+# Complete! Account fully migrated
 ```
 
 **What Gets Migrated:**
@@ -191,7 +191,7 @@ newo verify --source SOURCE_IDN --dest DEST_IDN
 - ✅ All metadata and configuration
 
 **Benefits:**
-- **Time Savings**: ~30 minutes vs 8-10 hours manual
+- **Automation**: 100% automated with zero manual steps
 - **Accuracy**: 100% entity match verified
 - **Reliability**: Tested with 1,084-skill account
 - **Safety**: Source account read-only, never modified

package/dist/api.d.ts

@@ -1,5 +1,5 @@
 import { type AxiosInstance } from 'axios';
-import type { ProjectMeta, Agent, Skill, FlowEvent, FlowState, AkbImportArticle, CustomerProfile, CustomerAttribute, CustomerAttributesResponse, UserPersonaResponse, UserPersona, ChatHistoryParams, ChatHistoryResponse, CreateAgentRequest, CreateAgentResponse, CreateFlowRequest, CreateFlowResponse, CreateSkillRequest, CreateSkillResponse, CreateFlowEventRequest, CreateFlowEventResponse, CreateFlowStateRequest, CreateFlowStateResponse, CreateSkillParameterRequest, CreateSkillParameterResponse, CreateCustomerAttributeRequest, CreateCustomerAttributeResponse, CreatePersonaRequest, CreatePersonaResponse, CreateProjectRequest, CreateProjectResponse, PublishFlowRequest, PublishFlowResponse, Integration, Connector, CreateSandboxPersonaRequest, CreateSandboxPersonaResponse, CreateActorRequest, CreateActorResponse, SendChatMessageRequest, ConversationActsParams, ConversationActsResponse, ScriptAction, IntegrationSetting, CreateConnectorRequest, CreateConnectorResponse, UpdateConnectorRequest, OutgoingWebhook, IncomingWebhook, PersonaSearchResponse, AkbTopicsResponse } from './types.js';
+import type { ProjectMeta, Agent, Skill, FlowEvent, FlowState, AkbImportArticle, CustomerProfile, CustomerAttribute, CustomerAttributesResponse, UserPersonaResponse, UserPersona, ChatHistoryParams, ChatHistoryResponse, CreateAgentRequest, CreateAgentResponse, CreateFlowRequest, CreateFlowResponse, CreateSkillRequest, CreateSkillResponse, CreateFlowEventRequest, CreateFlowEventResponse, CreateFlowStateRequest, CreateFlowStateResponse, CreateSkillParameterRequest, CreateSkillParameterResponse, CreateCustomerAttributeRequest, CreateCustomerAttributeResponse, CreatePersonaRequest, CreatePersonaResponse, CreateProjectRequest, CreateProjectResponse, PublishFlowRequest, PublishFlowResponse, Integration, Connector, CreateSandboxPersonaRequest, CreateSandboxPersonaResponse, CreateActorRequest, CreateActorResponse, SendChatMessageRequest, ConversationActsParams, ConversationActsResponse, ScriptAction, IntegrationSetting, CreateConnectorRequest, CreateConnectorResponse, UpdateConnectorRequest, OutgoingWebhook, IncomingWebhook, PersonaSearchResponse, AkbTopicsResponse, Registry, RegistryItem, AddProjectFromRegistryRequest } from './types.js';
 export declare function makeClient(verbose?: boolean, token?: string): Promise<AxiosInstance>;
 export declare function listProjects(client: AxiosInstance): Promise<ProjectMeta[]>;
 export declare function listAgents(client: AxiosInstance, projectId: string): Promise<Agent[]>;
@@ -85,4 +85,7 @@ export declare function createIncomingWebhook(client: AxiosInstance, webhookData
     id: string;
     url: string;
 }>;
+export declare function listRegistries(client: AxiosInstance): Promise<Registry[]>;
+export declare function listRegistryItems(client: AxiosInstance, registryId: string): Promise<RegistryItem[]>;
+export declare function addProjectFromRegistry(client: AxiosInstance, projectData: AddProjectFromRegistryRequest): Promise<CreateProjectResponse>;
 //# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -356,4 +356,18 @@ export async function createIncomingWebhook(client, webhookData) {
     const response = await client.post('/api/v1/webhooks/incoming', webhookData);
     return response.data;
 }
+// Registry API Functions
+export async function listRegistries(client) {
+    const response = await client.get('/api/v1/designer/registries');
+    return response.data;
+}
+export async function listRegistryItems(client, registryId) {
+    const response = await client.get(`/api/v1/designer/registries/${registryId}/items`);
+    return response.data;
+}
+export async function addProjectFromRegistry(client, projectData) {
+    // Uses the same endpoint as createProject, but with registry fields populated
+    const response = await client.post('/api/v1/designer/projects', projectData);
+    return response.data;
+}
 //# sourceMappingURL=api.js.map

package/dist/cli/commands/add-project.d.ts

@@ -0,0 +1,3 @@
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+export declare function handleAddProjectCommand(customerConfig: MultiCustomerConfig, args: CliArgs, verbose?: boolean): Promise<void>;
+//# sourceMappingURL=add-project.d.ts.map

package/dist/cli/commands/add-project.js

@@ -0,0 +1,136 @@
+/**
+ * Add Project from Registry Command Handler - Installs a project template from registry
+ */
+import { makeClient, listRegistries, listRegistryItems, addProjectFromRegistry } from '../../api.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+export async function handleAddProjectCommand(customerConfig, args, verbose = false) {
+    try {
+        const selectedCustomer = requireSingleCustomer(customerConfig, args.customer);
+        // Parse arguments
+        const projectIdn = args._[1];
+        const registryIdn = args.registry || 'production';
+        const registryItemIdn = args.item;
+        const registryItemVersion = args.version || null;
+        const title = args.title || projectIdn || registryItemIdn;
+        const description = args.description || '';
+        const isAutoUpdateEnabled = Boolean(args['auto-update']);
+        // Validate required arguments
+        if (!registryItemIdn) {
+            console.error('Error: Registry item IDN is required');
+            console.error('');
+            console.error('Usage: newo add-project <project-idn> --item <registry-item-idn> [options]');
+            console.error('');
+            console.error('Options:');
+            console.error('  --item <idn>           Registry item/template IDN (required)');
+            console.error('  --registry <idn>       Registry to use (default: production)');
+            console.error('  --version <version>    Specific version to install (default: latest)');
+            console.error('  --title <title>        Project title (default: project IDN)');
+            console.error('  --description <desc>   Project description');
+            console.error('  --auto-update          Enable automatic updates from registry');
+            console.error('');
+            console.error('Examples:');
+            console.error('  newo add-project my_weather --item weather_integration');
+            console.error('  newo add-project my_calcom --item cal_com_integration --registry production');
+            console.error('  newo add-project my_zoho --item zoho_integration --version 1.0.2 --auto-update');
+            console.error('');
+            console.error('Run "newo list-registries" to see available registries');
+            console.error('Run "newo list-registry-items <registry-idn>" to see available project templates');
+            process.exit(1);
+        }
+        // Use registry item IDN as project IDN if not specified
+        const finalProjectIdn = projectIdn || registryItemIdn;
+        if (verbose) {
+            console.log(`📦 Adding project from registry`);
+            console.log(`   Project IDN: ${finalProjectIdn}`);
+            console.log(`   Title: ${title}`);
+            console.log(`   Registry: ${registryIdn}`);
+            console.log(`   Item: ${registryItemIdn}`);
+            console.log(`   Version: ${registryItemVersion || 'latest'}`);
+            console.log(`   Auto-update: ${isAutoUpdateEnabled}`);
+            console.log(`   Customer: ${selectedCustomer.idn}`);
+        }
+        // Get access token and create client
+        const accessToken = await getValidAccessToken(selectedCustomer);
+        const client = await makeClient(verbose, accessToken);
+        // Validate registry exists
+        console.log(`🔍 Validating registry "${registryIdn}"...`);
+        const registries = await listRegistries(client);
+        const registry = registries.find((r) => r.idn === registryIdn);
+        if (!registry) {
+            console.error(`❌ Registry "${registryIdn}" not found`);
+            console.error('');
+            console.error('Available registries:');
+            for (const r of registries) {
+                console.error(`  • ${r.idn}`);
+            }
+            process.exit(1);
+        }
+        // Validate registry item exists and find version
+        console.log(`🔍 Validating project template "${registryItemIdn}"...`);
+        const items = await listRegistryItems(client, registry.id);
+        const matchingItems = items.filter((item) => item.idn === registryItemIdn);
+        if (matchingItems.length === 0) {
+            console.error(`❌ Project template "${registryItemIdn}" not found in "${registryIdn}" registry`);
+            console.error('');
+            console.error('Run "newo list-registry-items ' + registryIdn + '" to see available templates');
+            process.exit(1);
+        }
+        // Find the specific version or latest
+        let selectedItem;
+        if (registryItemVersion) {
+            selectedItem = matchingItems.find((item) => item.version === registryItemVersion);
+            if (!selectedItem) {
+                console.error(`❌ Version "${registryItemVersion}" not found for "${registryItemIdn}"`);
+                console.error('');
+                console.error('Available versions:');
+                const sortedItems = [...matchingItems].sort((a, b) => new Date(b.published_at).getTime() - new Date(a.published_at).getTime());
+                for (const item of sortedItems.slice(0, 10)) {
+                    console.error(`  • ${item.version} (published: ${new Date(item.published_at).toISOString().split('T')[0]})`);
+                }
+                if (sortedItems.length > 10) {
+                    console.error(`  ... and ${sortedItems.length - 10} more`);
+                }
+                process.exit(1);
+            }
+        }
+        else {
+            // Get latest version (sorted by published_at desc)
+            const sortedItems = [...matchingItems].sort((a, b) => new Date(b.published_at).getTime() - new Date(a.published_at).getTime());
+            selectedItem = sortedItems[0];
+        }
+        if (!selectedItem) {
+            console.error(`❌ Could not determine version for "${registryItemIdn}"`);
+            process.exit(1);
+        }
+        console.log(`📥 Installing "${registryItemIdn}" v${selectedItem.version} as "${finalProjectIdn}"...`);
+        // Create project from registry
+        const projectData = {
+            idn: finalProjectIdn,
+            title,
+            version: '',
+            description,
+            is_auto_update_enabled: isAutoUpdateEnabled,
+            registry_idn: registryIdn,
+            registry_item_idn: registryItemIdn,
+            registry_item_version: registryItemVersion
+        };
+        const response = await addProjectFromRegistry(client, projectData);
+        console.log('');
+        console.log(`✅ Project installed successfully!`);
+        console.log(`   Project IDN: ${finalProjectIdn}`);
+        console.log(`   Project ID: ${response.id}`);
+        console.log(`   Source: ${registryItemIdn} v${selectedItem.version}`);
+        console.log(`   Registry: ${registryIdn}`);
+        if (isAutoUpdateEnabled) {
+            console.log(`   Auto-update: Enabled`);
+        }
+        console.log('');
+        console.log(`💡 Run "newo pull" to sync the project locally`);
+    }
+    catch (error) {
+        console.error('❌ Failed to add project from registry:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=add-project.js.map

package/dist/cli/commands/help.js

@@ -18,7 +18,10 @@ Core Commands:
   newo import-akb <file> <persona_id> [--customer <idn>]  # import AKB articles from structured text file
 
 Project Management:
-  newo create-project <idn> [--title <title>] [--description <desc>] [--version <version>] [--auto-update]  # create project on platform ✅
+  newo create-project <idn> [--title <title>] [--description <desc>] [--version <version>] [--auto-update]  # create empty project on platform
+  newo list-registries [--customer <idn>]                                   # list available project registries (production, staging, etc.)
+  newo list-registry-items <registry-idn> [--all]                           # list available project templates in a registry
+  newo add-project <idn> --item <template-idn> [--registry <registry>] [--version <v>] [--auto-update]  # install project from registry template
 
 Entity Management (Full Lifecycle Support):
   newo create-agent <idn> --project <project-idn> [--title <title>] [--description <desc>]    # create agent → push to platform ✅
@@ -122,6 +125,14 @@ Usage Examples:
   # Import AKB articles:
   newo import-akb articles.txt da4550db-2b95-4500-91ff-fb4b60fe7be9
 
+  # Project Registry - Install templates from registry (NEW):
+  newo list-registries                             # See available registries
+  newo list-registry-items production              # Browse production templates
+  newo list-registry-items production --all        # See all versions
+  newo add-project my_calcom --item cal_com_integration                        # Install latest version
+  newo add-project my_zoho --item zoho_integration --version 1.0.2            # Install specific version
+  newo add-project my_weather --item weather_integration --auto-update         # With auto-updates
+
   # Sandbox testing (NEW v3.1.0):
   newo sandbox "Hello, I want to order pizza"                    # Start new conversation
   newo sandbox --actor abc123... "I want 2 large pizzas"         # Continue conversation

package/dist/cli/commands/list-registries.d.ts

@@ -0,0 +1,3 @@
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+export declare function handleListRegistriesCommand(customerConfig: MultiCustomerConfig, args: CliArgs, verbose?: boolean): Promise<void>;
+//# sourceMappingURL=list-registries.d.ts.map

package/dist/cli/commands/list-registries.js

@@ -0,0 +1,39 @@
+/**
+ * List Registries Command Handler - Lists available project registries
+ */
+import { makeClient, listRegistries } from '../../api.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+export async function handleListRegistriesCommand(customerConfig, args, verbose = false) {
+    try {
+        const selectedCustomer = requireSingleCustomer(customerConfig, args.customer);
+        if (verbose) {
+            console.log(`📋 Fetching registries for customer: ${selectedCustomer.idn}`);
+        }
+        // Get access token and create client
+        const accessToken = await getValidAccessToken(selectedCustomer);
+        const client = await makeClient(verbose, accessToken);
+        console.log('🔍 Fetching available project registries...\n');
+        const registries = await listRegistries(client);
+        if (registries.length === 0) {
+            console.log('No registries found.');
+            return;
+        }
+        console.log(`✅ Found ${registries.length} registries:\n`);
+        // Display registries in a table-like format
+        console.log('  IDN                     │ Public │ ID');
+        console.log('  ────────────────────────┼────────┼────────────────────────────────────');
+        for (const registry of registries) {
+            const publicStatus = registry.is_public ? 'Yes' : 'No';
+            const idnPadded = registry.idn.padEnd(22);
+            const publicPadded = publicStatus.padEnd(6);
+            console.log(`  ${idnPadded} │ ${publicPadded} │ ${registry.id}`);
+        }
+        console.log('\n💡 Use "newo list-registry-items <registry-idn>" to see available projects in a registry');
+    }
+    catch (error) {
+        console.error('❌ Failed to list registries:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=list-registries.js.map

package/dist/cli/commands/list-registry-items.d.ts

@@ -0,0 +1,3 @@
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+export declare function handleListRegistryItemsCommand(customerConfig: MultiCustomerConfig, args: CliArgs, verbose?: boolean): Promise<void>;
+//# sourceMappingURL=list-registry-items.d.ts.map

package/dist/cli/commands/list-registry-items.js

@@ -0,0 +1,112 @@
+/**
+ * List Registry Items Command Handler - Lists available projects in a registry
+ */
+import { makeClient, listRegistries, listRegistryItems } from '../../api.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+function groupItemsByIdn(items) {
+    const groups = new Map();
+    for (const item of items) {
+        const existing = groups.get(item.idn) || [];
+        existing.push(item);
+        groups.set(item.idn, existing);
+    }
+    const result = [];
+    for (const [idn, versions] of groups) {
+        // Sort versions by published_at descending (newest first)
+        const sortedVersions = [...versions].sort((a, b) => new Date(b.published_at).getTime() - new Date(a.published_at).getTime());
+        const latestItem = sortedVersions[0];
+        if (!latestItem)
+            continue;
+        // Sum up active project counts across all versions
+        const totalActiveProjects = versions.reduce((sum, v) => sum + v.active_project_count, 0);
+        result.push({
+            idn,
+            versions: sortedVersions,
+            latestVersion: latestItem.version,
+            totalActiveProjects
+        });
+    }
+    // Sort by IDN alphabetically
+    return result.sort((a, b) => a.idn.localeCompare(b.idn));
+}
+export async function handleListRegistryItemsCommand(customerConfig, args, verbose = false) {
+    try {
+        const selectedCustomer = requireSingleCustomer(customerConfig, args.customer);
+        // Parse arguments
+        const registryIdn = args._[1];
+        const showAllVersions = Boolean(args.all || args.a);
+        if (!registryIdn) {
+            console.error('Error: Registry IDN is required');
+            console.error('Usage: newo list-registry-items <registry-idn> [--all]');
+            console.error('');
+            console.error('Examples:');
+            console.error('  newo list-registry-items production');
+            console.error('  newo list-registry-items staging --all');
+            console.error('');
+            console.error('Run "newo list-registries" to see available registries');
+            process.exit(1);
+        }
+        if (verbose) {
+            console.log(`📋 Fetching items from registry: ${registryIdn}`);
+            console.log(`   Customer: ${selectedCustomer.idn}`);
+            console.log(`   Show all versions: ${showAllVersions}`);
+        }
+        // Get access token and create client
+        const accessToken = await getValidAccessToken(selectedCustomer);
+        const client = await makeClient(verbose, accessToken);
+        // First, get registries to find the ID
+        console.log(`🔍 Fetching registry "${registryIdn}"...`);
+        const registries = await listRegistries(client);
+        const registry = registries.find((r) => r.idn === registryIdn);
+        if (!registry) {
+            console.error(`❌ Registry "${registryIdn}" not found`);
+            console.error('');
+            console.error('Available registries:');
+            for (const r of registries) {
+                console.error(`  • ${r.idn}`);
+            }
+            process.exit(1);
+        }
+        console.log(`📦 Fetching projects from "${registryIdn}" registry (this may take a moment)...\n`);
+        const items = await listRegistryItems(client, registry.id);
+        if (items.length === 0) {
+            console.log(`No projects found in "${registryIdn}" registry.`);
+            return;
+        }
+        if (showAllVersions) {
+            // Show all versions
+            console.log(`✅ Found ${items.length} project versions in "${registryIdn}" registry:\n`);
+            console.log('  Project IDN            │ Version  │ Active │ Published');
+            console.log('  ───────────────────────┼──────────┼────────┼────────────────────');
+            for (const item of items) {
+                const idnPadded = item.idn.substring(0, 21).padEnd(21);
+                const versionPadded = item.version.substring(0, 8).padEnd(8);
+                const activePadded = String(item.active_project_count).padEnd(6);
+                const published = new Date(item.published_at).toISOString().split('T')[0];
+                console.log(`  ${idnPadded} │ ${versionPadded} │ ${activePadded} │ ${published}`);
+            }
+        }
+        else {
+            // Group by project IDN and show only latest version
+            const grouped = groupItemsByIdn(items);
+            console.log(`✅ Found ${grouped.length} unique projects in "${registryIdn}" registry:\n`);
+            console.log('  Project IDN            │ Latest   │ Active │ Versions');
+            console.log('  ───────────────────────┼──────────┼────────┼──────────');
+            for (const group of grouped) {
+                const idnPadded = group.idn.substring(0, 21).padEnd(21);
+                const versionPadded = group.latestVersion.substring(0, 8).padEnd(8);
+                const activePadded = String(group.totalActiveProjects).padEnd(6);
+                const versionCount = String(group.versions.length).padEnd(8);
+                console.log(`  ${idnPadded} │ ${versionPadded} │ ${activePadded} │ ${versionCount}`);
+            }
+            console.log('\n💡 Use --all flag to see all versions');
+        }
+        console.log(`\n💡 Use "newo add-project <idn> --registry ${registryIdn} --item <project-idn>" to install a project`);
+    }
+    catch (error) {
+        console.error('❌ Failed to list registry items:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=list-registry-items.js.map

package/dist/cli.js

@@ -38,6 +38,9 @@ import { handlePushAkbCommand } from './cli/commands/push-akb.js';
 import { handleMigrateAccountCommand } from './cli/commands/migrate-account.js';
 import { handleVerifyMigrationCommand } from './cli/commands/verify-migration.js';
 import { handleCreateWebhooksCommand } from './cli/commands/create-webhooks.js';
+import { handleListRegistriesCommand } from './cli/commands/list-registries.js';
+import { handleListRegistryItemsCommand } from './cli/commands/list-registry-items.js';
+import { handleAddProjectCommand } from './cli/commands/add-project.js';
 dotenv.config();
 async function main() {
     try {
@@ -168,6 +171,15 @@ async function main() {
             case 'create-webhooks':
                 await handleCreateWebhooksCommand(customerConfig, args, verbose);
                 break;
+            case 'list-registries':
+                await handleListRegistriesCommand(customerConfig, args, verbose);
+                break;
+            case 'list-registry-items':
+                await handleListRegistryItemsCommand(customerConfig, args, verbose);
+                break;
+            case 'add-project':
+                await handleAddProjectCommand(customerConfig, args, verbose);
+                break;
             default:
                 console.error('Unknown command:', cmd);
                 console.error('Run "newo --help" for usage information');

package/dist/types.d.ts

@@ -703,4 +703,42 @@ export interface AkbYamlTopic {
     labels: string[];
     topic_summary: string;
 }
+export interface Registry {
+    readonly id: string;
+    readonly idn: string;
+    readonly account_id: string;
+    readonly is_public: boolean;
+}
+export interface RegistryItemProjectImage {
+    readonly id: string;
+    readonly idn: string;
+    readonly image_hash: string;
+    readonly storage_id: string;
+    readonly customer_idn: string;
+    readonly account_id: string;
+    readonly created_at: string;
+}
+export interface RegistryItem {
+    readonly id: string;
+    readonly idn: string;
+    readonly version: string;
+    readonly project_image: RegistryItemProjectImage;
+    readonly account_id: string;
+    readonly account_idn: string | null;
+    readonly account_email: string | null;
+    readonly is_public: boolean;
+    readonly active_project_count: number;
+    readonly created_at: string;
+    readonly published_at: string;
+}
+export interface AddProjectFromRegistryRequest {
+    idn: string;
+    title: string;
+    version?: string;
+    description?: string;
+    is_auto_update_enabled?: boolean;
+    registry_idn: string;
+    registry_item_idn: string;
+    registry_item_version: string | null;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newo",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "description": "NEWO CLI: Professional command-line tool with modular architecture for NEWO AI Agent development. Features account migration, integration management, webhook automation, AKB knowledge base, project attributes, sandbox testing, IDN-based file management, real-time progress tracking, intelligent sync operations, and comprehensive multi-customer support.",
   "type": "module",
   "bin": {

package/src/api.ts

@@ -52,7 +52,10 @@ import type {
   OutgoingWebhook,
   IncomingWebhook,
   PersonaSearchResponse,
-  AkbTopicsResponse
+  AkbTopicsResponse,
+  Registry,
+  RegistryItem,
+  AddProjectFromRegistryRequest
 } from './types.js';
 
 // Per-request retry tracking to avoid shared state issues
@@ -552,4 +555,25 @@ export async function createIncomingWebhook(
 ): Promise<{ id: string; url: string }> {
   const response = await client.post('/api/v1/webhooks/incoming', webhookData);
   return response.data;
+}
+
+// Registry API Functions
+
+export async function listRegistries(client: AxiosInstance): Promise<Registry[]> {
+  const response = await client.get<Registry[]>('/api/v1/designer/registries');
+  return response.data;
+}
+
+export async function listRegistryItems(client: AxiosInstance, registryId: string): Promise<RegistryItem[]> {
+  const response = await client.get<RegistryItem[]>(`/api/v1/designer/registries/${registryId}/items`);
+  return response.data;
+}
+
+export async function addProjectFromRegistry(
+  client: AxiosInstance,
+  projectData: AddProjectFromRegistryRequest
+): Promise<CreateProjectResponse> {
+  // Uses the same endpoint as createProject, but with registry fields populated
+  const response = await client.post<CreateProjectResponse>('/api/v1/designer/projects', projectData);
+  return response.data;
 }

package/src/cli/commands/add-project.ts

@@ -0,0 +1,159 @@
+/**
+ * Add Project from Registry Command Handler - Installs a project template from registry
+ */
+import { makeClient, listRegistries, listRegistryItems, addProjectFromRegistry } from '../../api.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs, Registry, RegistryItem, AddProjectFromRegistryRequest } from '../../types.js';
+
+export async function handleAddProjectCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean = false
+): Promise<void> {
+  try {
+    const selectedCustomer = requireSingleCustomer(customerConfig, args.customer as string | undefined);
+
+    // Parse arguments
+    const projectIdn = args._[1] as string;
+    const registryIdn = args.registry as string || 'production';
+    const registryItemIdn = args.item as string;
+    const registryItemVersion = args.version as string | null || null;
+    const title = args.title as string || projectIdn || registryItemIdn;
+    const description = args.description as string || '';
+    const isAutoUpdateEnabled = Boolean(args['auto-update']);
+
+    // Validate required arguments
+    if (!registryItemIdn) {
+      console.error('Error: Registry item IDN is required');
+      console.error('');
+      console.error('Usage: newo add-project <project-idn> --item <registry-item-idn> [options]');
+      console.error('');
+      console.error('Options:');
+      console.error('  --item <idn>           Registry item/template IDN (required)');
+      console.error('  --registry <idn>       Registry to use (default: production)');
+      console.error('  --version <version>    Specific version to install (default: latest)');
+      console.error('  --title <title>        Project title (default: project IDN)');
+      console.error('  --description <desc>   Project description');
+      console.error('  --auto-update          Enable automatic updates from registry');
+      console.error('');
+      console.error('Examples:');
+      console.error('  newo add-project my_weather --item weather_integration');
+      console.error('  newo add-project my_calcom --item cal_com_integration --registry production');
+      console.error('  newo add-project my_zoho --item zoho_integration --version 1.0.2 --auto-update');
+      console.error('');
+      console.error('Run "newo list-registries" to see available registries');
+      console.error('Run "newo list-registry-items <registry-idn>" to see available project templates');
+      process.exit(1);
+    }
+
+    // Use registry item IDN as project IDN if not specified
+    const finalProjectIdn = projectIdn || registryItemIdn;
+
+    if (verbose) {
+      console.log(`📦 Adding project from registry`);
+      console.log(`   Project IDN: ${finalProjectIdn}`);
+      console.log(`   Title: ${title}`);
+      console.log(`   Registry: ${registryIdn}`);
+      console.log(`   Item: ${registryItemIdn}`);
+      console.log(`   Version: ${registryItemVersion || 'latest'}`);
+      console.log(`   Auto-update: ${isAutoUpdateEnabled}`);
+      console.log(`   Customer: ${selectedCustomer.idn}`);
+    }
+
+    // Get access token and create client
+    const accessToken = await getValidAccessToken(selectedCustomer);
+    const client = await makeClient(verbose, accessToken);
+
+    // Validate registry exists
+    console.log(`🔍 Validating registry "${registryIdn}"...`);
+    const registries = await listRegistries(client);
+    const registry = registries.find((r: Registry) => r.idn === registryIdn);
+
+    if (!registry) {
+      console.error(`❌ Registry "${registryIdn}" not found`);
+      console.error('');
+      console.error('Available registries:');
+      for (const r of registries) {
+        console.error(`  • ${r.idn}`);
+      }
+      process.exit(1);
+    }
+
+    // Validate registry item exists and find version
+    console.log(`🔍 Validating project template "${registryItemIdn}"...`);
+    const items = await listRegistryItems(client, registry.id);
+    const matchingItems = items.filter((item: RegistryItem) => item.idn === registryItemIdn);
+
+    if (matchingItems.length === 0) {
+      console.error(`❌ Project template "${registryItemIdn}" not found in "${registryIdn}" registry`);
+      console.error('');
+      console.error('Run "newo list-registry-items ' + registryIdn + '" to see available templates');
+      process.exit(1);
+    }
+
+    // Find the specific version or latest
+    let selectedItem: RegistryItem | undefined;
+    if (registryItemVersion) {
+      selectedItem = matchingItems.find((item: RegistryItem) => item.version === registryItemVersion);
+      if (!selectedItem) {
+        console.error(`❌ Version "${registryItemVersion}" not found for "${registryItemIdn}"`);
+        console.error('');
+        console.error('Available versions:');
+        const sortedItems = [...matchingItems].sort((a, b) =>
+          new Date(b.published_at).getTime() - new Date(a.published_at).getTime()
+        );
+        for (const item of sortedItems.slice(0, 10)) {
+          console.error(`  • ${item.version} (published: ${new Date(item.published_at).toISOString().split('T')[0]})`);
+        }
+        if (sortedItems.length > 10) {
+          console.error(`  ... and ${sortedItems.length - 10} more`);
+        }
+        process.exit(1);
+      }
+    } else {
+      // Get latest version (sorted by published_at desc)
+      const sortedItems = [...matchingItems].sort((a, b) =>
+        new Date(b.published_at).getTime() - new Date(a.published_at).getTime()
+      );
+      selectedItem = sortedItems[0];
+    }
+
+    if (!selectedItem) {
+      console.error(`❌ Could not determine version for "${registryItemIdn}"`);
+      process.exit(1);
+    }
+
+    console.log(`📥 Installing "${registryItemIdn}" v${selectedItem.version} as "${finalProjectIdn}"...`);
+
+    // Create project from registry
+    const projectData: AddProjectFromRegistryRequest = {
+      idn: finalProjectIdn,
+      title,
+      version: '',
+      description,
+      is_auto_update_enabled: isAutoUpdateEnabled,
+      registry_idn: registryIdn,
+      registry_item_idn: registryItemIdn,
+      registry_item_version: registryItemVersion
+    };
+
+    const response = await addProjectFromRegistry(client, projectData);
+
+    console.log('');
+    console.log(`✅ Project installed successfully!`);
+    console.log(`   Project IDN: ${finalProjectIdn}`);
+    console.log(`   Project ID: ${response.id}`);
+    console.log(`   Source: ${registryItemIdn} v${selectedItem.version}`);
+    console.log(`   Registry: ${registryIdn}`);
+    if (isAutoUpdateEnabled) {
+      console.log(`   Auto-update: Enabled`);
+    }
+    console.log('');
+    console.log(`💡 Run "newo pull" to sync the project locally`);
+
+  } catch (error: unknown) {
+    console.error('❌ Failed to add project from registry:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/src/cli/commands/help.ts

@@ -19,7 +19,10 @@ Core Commands:
   newo import-akb <file> <persona_id> [--customer <idn>]  # import AKB articles from structured text file
 
 Project Management:
-  newo create-project <idn> [--title <title>] [--description <desc>] [--version <version>] [--auto-update]  # create project on platform ✅
+  newo create-project <idn> [--title <title>] [--description <desc>] [--version <version>] [--auto-update]  # create empty project on platform
+  newo list-registries [--customer <idn>]                                   # list available project registries (production, staging, etc.)
+  newo list-registry-items <registry-idn> [--all]                           # list available project templates in a registry
+  newo add-project <idn> --item <template-idn> [--registry <registry>] [--version <v>] [--auto-update]  # install project from registry template
 
 Entity Management (Full Lifecycle Support):
   newo create-agent <idn> --project <project-idn> [--title <title>] [--description <desc>]    # create agent → push to platform ✅
@@ -123,6 +126,14 @@ Usage Examples:
   # Import AKB articles:
   newo import-akb articles.txt da4550db-2b95-4500-91ff-fb4b60fe7be9
 
+  # Project Registry - Install templates from registry (NEW):
+  newo list-registries                             # See available registries
+  newo list-registry-items production              # Browse production templates
+  newo list-registry-items production --all        # See all versions
+  newo add-project my_calcom --item cal_com_integration                        # Install latest version
+  newo add-project my_zoho --item zoho_integration --version 1.0.2            # Install specific version
+  newo add-project my_weather --item weather_integration --auto-update         # With auto-updates
+
   # Sandbox testing (NEW v3.1.0):
   newo sandbox "Hello, I want to order pizza"                    # Start new conversation
   newo sandbox --actor abc123... "I want 2 large pizzas"         # Continue conversation

package/src/cli/commands/list-registries.ts

@@ -0,0 +1,53 @@
+/**
+ * List Registries Command Handler - Lists available project registries
+ */
+import { makeClient, listRegistries } from '../../api.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs } from '../../types.js';
+
+export async function handleListRegistriesCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean = false
+): Promise<void> {
+  try {
+    const selectedCustomer = requireSingleCustomer(customerConfig, args.customer as string | undefined);
+
+    if (verbose) {
+      console.log(`📋 Fetching registries for customer: ${selectedCustomer.idn}`);
+    }
+
+    // Get access token and create client
+    const accessToken = await getValidAccessToken(selectedCustomer);
+    const client = await makeClient(verbose, accessToken);
+
+    console.log('🔍 Fetching available project registries...\n');
+
+    const registries = await listRegistries(client);
+
+    if (registries.length === 0) {
+      console.log('No registries found.');
+      return;
+    }
+
+    console.log(`✅ Found ${registries.length} registries:\n`);
+
+    // Display registries in a table-like format
+    console.log('  IDN                     │ Public │ ID');
+    console.log('  ────────────────────────┼────────┼────────────────────────────────────');
+
+    for (const registry of registries) {
+      const publicStatus = registry.is_public ? 'Yes' : 'No';
+      const idnPadded = registry.idn.padEnd(22);
+      const publicPadded = publicStatus.padEnd(6);
+      console.log(`  ${idnPadded} │ ${publicPadded} │ ${registry.id}`);
+    }
+
+    console.log('\n💡 Use "newo list-registry-items <registry-idn>" to see available projects in a registry');
+
+  } catch (error: unknown) {
+    console.error('❌ Failed to list registries:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/src/cli/commands/list-registry-items.ts

@@ -0,0 +1,149 @@
+/**
+ * List Registry Items Command Handler - Lists available projects in a registry
+ */
+import { makeClient, listRegistries, listRegistryItems } from '../../api.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+import type { MultiCustomerConfig, CliArgs, Registry, RegistryItem } from '../../types.js';
+
+interface GroupedItem {
+  idn: string;
+  versions: RegistryItem[];
+  latestVersion: string;
+  totalActiveProjects: number;
+}
+
+function groupItemsByIdn(items: RegistryItem[]): GroupedItem[] {
+  const groups = new Map<string, RegistryItem[]>();
+
+  for (const item of items) {
+    const existing = groups.get(item.idn) || [];
+    existing.push(item);
+    groups.set(item.idn, existing);
+  }
+
+  const result: GroupedItem[] = [];
+
+  for (const [idn, versions] of groups) {
+    // Sort versions by published_at descending (newest first)
+    const sortedVersions = [...versions].sort((a, b) =>
+      new Date(b.published_at).getTime() - new Date(a.published_at).getTime()
+    );
+
+    const latestItem = sortedVersions[0];
+    if (!latestItem) continue;
+
+    // Sum up active project counts across all versions
+    const totalActiveProjects = versions.reduce((sum, v) => sum + v.active_project_count, 0);
+
+    result.push({
+      idn,
+      versions: sortedVersions,
+      latestVersion: latestItem.version,
+      totalActiveProjects
+    });
+  }
+
+  // Sort by IDN alphabetically
+  return result.sort((a, b) => a.idn.localeCompare(b.idn));
+}
+
+export async function handleListRegistryItemsCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean = false
+): Promise<void> {
+  try {
+    const selectedCustomer = requireSingleCustomer(customerConfig, args.customer as string | undefined);
+
+    // Parse arguments
+    const registryIdn = args._[1] as string;
+    const showAllVersions = Boolean(args.all || args.a);
+
+    if (!registryIdn) {
+      console.error('Error: Registry IDN is required');
+      console.error('Usage: newo list-registry-items <registry-idn> [--all]');
+      console.error('');
+      console.error('Examples:');
+      console.error('  newo list-registry-items production');
+      console.error('  newo list-registry-items staging --all');
+      console.error('');
+      console.error('Run "newo list-registries" to see available registries');
+      process.exit(1);
+    }
+
+    if (verbose) {
+      console.log(`📋 Fetching items from registry: ${registryIdn}`);
+      console.log(`   Customer: ${selectedCustomer.idn}`);
+      console.log(`   Show all versions: ${showAllVersions}`);
+    }
+
+    // Get access token and create client
+    const accessToken = await getValidAccessToken(selectedCustomer);
+    const client = await makeClient(verbose, accessToken);
+
+    // First, get registries to find the ID
+    console.log(`🔍 Fetching registry "${registryIdn}"...`);
+    const registries = await listRegistries(client);
+    const registry = registries.find((r: Registry) => r.idn === registryIdn);
+
+    if (!registry) {
+      console.error(`❌ Registry "${registryIdn}" not found`);
+      console.error('');
+      console.error('Available registries:');
+      for (const r of registries) {
+        console.error(`  • ${r.idn}`);
+      }
+      process.exit(1);
+    }
+
+    console.log(`📦 Fetching projects from "${registryIdn}" registry (this may take a moment)...\n`);
+
+    const items = await listRegistryItems(client, registry.id);
+
+    if (items.length === 0) {
+      console.log(`No projects found in "${registryIdn}" registry.`);
+      return;
+    }
+
+    if (showAllVersions) {
+      // Show all versions
+      console.log(`✅ Found ${items.length} project versions in "${registryIdn}" registry:\n`);
+
+      console.log('  Project IDN            │ Version  │ Active │ Published');
+      console.log('  ───────────────────────┼──────────┼────────┼────────────────────');
+
+      for (const item of items) {
+        const idnPadded = item.idn.substring(0, 21).padEnd(21);
+        const versionPadded = item.version.substring(0, 8).padEnd(8);
+        const activePadded = String(item.active_project_count).padEnd(6);
+        const published = new Date(item.published_at).toISOString().split('T')[0];
+        console.log(`  ${idnPadded} │ ${versionPadded} │ ${activePadded} │ ${published}`);
+      }
+    } else {
+      // Group by project IDN and show only latest version
+      const grouped = groupItemsByIdn(items);
+
+      console.log(`✅ Found ${grouped.length} unique projects in "${registryIdn}" registry:\n`);
+
+      console.log('  Project IDN            │ Latest   │ Active │ Versions');
+      console.log('  ───────────────────────┼──────────┼────────┼──────────');
+
+      for (const group of grouped) {
+        const idnPadded = group.idn.substring(0, 21).padEnd(21);
+        const versionPadded = group.latestVersion.substring(0, 8).padEnd(8);
+        const activePadded = String(group.totalActiveProjects).padEnd(6);
+        const versionCount = String(group.versions.length).padEnd(8);
+        console.log(`  ${idnPadded} │ ${versionPadded} │ ${activePadded} │ ${versionCount}`);
+      }
+
+      console.log('\n💡 Use --all flag to see all versions');
+    }
+
+    console.log(`\n💡 Use "newo add-project <idn> --registry ${registryIdn} --item <project-idn>" to install a project`);
+
+  } catch (error: unknown) {
+    console.error('❌ Failed to list registry items:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/src/cli.ts

@@ -38,6 +38,9 @@ import { handlePushAkbCommand } from './cli/commands/push-akb.js';
 import { handleMigrateAccountCommand } from './cli/commands/migrate-account.js';
 import { handleVerifyMigrationCommand } from './cli/commands/verify-migration.js';
 import { handleCreateWebhooksCommand } from './cli/commands/create-webhooks.js';
+import { handleListRegistriesCommand } from './cli/commands/list-registries.js';
+import { handleListRegistryItemsCommand } from './cli/commands/list-registry-items.js';
+import { handleAddProjectCommand } from './cli/commands/add-project.js';
 import type { CliArgs, NewoApiError } from './types.js';
 
 dotenv.config();
@@ -204,6 +207,18 @@ async function main(): Promise<void> {
         await handleCreateWebhooksCommand(customerConfig, args, verbose);
         break;
 
+      case 'list-registries':
+        await handleListRegistriesCommand(customerConfig, args, verbose);
+        break;
+
+      case 'list-registry-items':
+        await handleListRegistryItemsCommand(customerConfig, args, verbose);
+        break;
+
+      case 'add-project':
+        await handleAddProjectCommand(customerConfig, args, verbose);
+        break;
+
       default:
         console.error('Unknown command:', cmd);
         console.error('Run "newo --help" for usage information');

package/src/types.ts

@@ -831,4 +831,47 @@ export interface AkbYamlTopic {
   updated_at: string;
   labels: string[];
   topic_summary: string;
+}
+
+// Registry Types (for project marketplace/templates)
+export interface Registry {
+  readonly id: string;
+  readonly idn: string;
+  readonly account_id: string;
+  readonly is_public: boolean;
+}
+
+export interface RegistryItemProjectImage {
+  readonly id: string;
+  readonly idn: string;
+  readonly image_hash: string;
+  readonly storage_id: string;
+  readonly customer_idn: string;
+  readonly account_id: string;
+  readonly created_at: string;
+}
+
+export interface RegistryItem {
+  readonly id: string;
+  readonly idn: string;
+  readonly version: string;
+  readonly project_image: RegistryItemProjectImage;
+  readonly account_id: string;
+  readonly account_idn: string | null;
+  readonly account_email: string | null;
+  readonly is_public: boolean;
+  readonly active_project_count: number;
+  readonly created_at: string;
+  readonly published_at: string;
+}
+
+export interface AddProjectFromRegistryRequest {
+  idn: string;
+  title: string;
+  version?: string;
+  description?: string;
+  is_auto_update_enabled?: boolean;
+  registry_idn: string;
+  registry_item_idn: string;
+  registry_item_version: string | null;
 }