newo 1.2.2 → 1.4.0

package/.env.example

@@ -1,8 +1,8 @@
 # NEWO endpoints
 NEWO_BASE_URL=https://app.newo.ai
 
-# Project you want to sync
-NEWO_PROJECT_ID=b78188ba-0df0-46a8-8713-f0d7cff0a06e
+# Project you want to sync (optional - leave blank to sync all accessible projects)
+# NEWO_PROJECT_ID=b78188ba-0df0-46a8-8713-f0d7cff0a06e
 
 # Auth (choose one)
 # 1) Recommended: API key that can be exchanged for tokens:

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0] - 2025-08-20
+
+### Added
+- **Multi-Project Support**: Major feature allowing users to work with multiple NEWO projects
+  - Optional `NEWO_PROJECT_ID` environment variable - if not set, pulls all accessible projects
+  - New API endpoint: `GET /api/v1/designer/projects` to list all accessible projects
+  - Projects stored in organized folder structure: `./projects/{project-idn}/`
+  - Each project folder contains `metadata.json` with complete project information
+  - Project-specific `flows.yaml` files for individual project structure exports
+- **Enhanced Project Structure**:
+  - Changed from single `./project/` to multi-project `./projects/{project-idn}/` hierarchy
+  - Backward compatibility maintained for existing single-project workflows
+  - Improved organization with project-specific metadata and flows
+
+### Changed
+- **Folder Structure**: Project files now stored in `./projects/{project-idn}/` instead of `./project/`
+- **CLI Behavior**: `newo pull` now downloads all projects by default (unless NEWO_PROJECT_ID specified)
+- **CI/CD Paths**: GitHub Actions workflow paths updated from `project/**/*` to `projects/**/*`
+- **Help Documentation**: Updated CLI help text to reflect multi-project capabilities
+- **API Integration**: Enhanced sync logic to handle both single and multi-project scenarios
+
+### Technical Details
+- **New API Functions**:
+  - `listProjects()`: Fetch all accessible projects from NEWO platform
+  - `pullSingleProject()`: Pull individual project with metadata generation
+  - `metadataPath()`: Generate project-specific metadata file paths
+- **Enhanced Sync Engine**:
+  - Multi-project mapping in `.newo/map.json` with backward compatibility
+  - Project-specific hash tracking for efficient change detection
+  - Automatic project metadata collection and storage
+- **File System Updates**:
+  - Updated `fsutil.js` with multi-project path utilities
+  - Enhanced `skillPath()` function to include project identifier
+  - New `projectDir()` and `metadataPath()` helper functions
+
+### Migration Guide
+- **Existing Users**: Single-project setups continue to work with `NEWO_PROJECT_ID` set
+- **New Users**: Leave `NEWO_PROJECT_ID` unset to access all projects automatically
+- **File Paths**: Update any scripts referencing `./project/` to use `./projects/{project-idn}/`
+- **CI/CD**: Update workflow paths from `project/**/*` to `projects/**/*`
+
+### Example Usage
+```bash
+# Pull all accessible projects (new default behavior)
+npx newo pull
+
+# Pull specific project (original behavior)
+NEWO_PROJECT_ID=your-project-id npx newo pull
+
+# Push changes from any project structure
+npx newo push
+
+# Status works with both single and multi-project setups
+npx newo status
+```
+
+## [1.3.0] - 2025-08-20
+
+### Added
+- **AKB Import Feature**: New `import-akb` command to import knowledge base articles from structured text files
+  - Parse multi-article files with standardized format (separated by `---`)
+  - Extract article metadata: ID, category, summary, keywords, and pricing data
+  - Import articles to NEWO personas via `/api/v1/akb/append-manual` endpoint
+  - Support for verbose logging with `--verbose` flag
+  - Progress tracking with success/failure counts
+- **Enhanced CLI**: Added `import-akb <file> <persona_id>` command with validation and error handling
+- **New API Endpoint**: `importAkbArticle()` function for AKB article imports
+- **Documentation**: Comprehensive AKB format documentation in README.md
+
+### Changed
+- Updated help text to include new `import-akb` command
+- Enhanced CLI command parsing to handle AKB import arguments
+- Updated project documentation with AKB import workflow and examples
+
+### Technical Details
+- **New Files**: 
+  - `src/akb.js`: AKB file parser and article formatter
+  - Article parsing supports category/subcategory structure with pricing data
+- **API Integration**: 
+  - Articles mapped with `topic_name` (descriptive title) and `source` (article ID)
+  - Full category content stored in `topic_summary`
+  - Structured metadata in `topic_facts` array
+- **Error Handling**: Comprehensive validation for file paths, persona IDs, and API responses
+
+### Example Usage
+```bash
+# Import AKB articles from file to specific persona
+npx newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9
+
+# With verbose logging
+npx newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9 --verbose
+```
+
+### AKB File Format
+```
+---
+# r001
+## Category / Subcategory / Description
+## Summary description of the category
+## Keywords; separated; by; semicolons
+
+<Category type="Category Name">
+Item Name: $Price [Modifiers: modifier1, modifier2]
+Another Item: $Price [Modifiers: modifier3]
+</Category>
+---
+```
+
+## [1.2.2] - 2025-08-12
+
+### Changed
+- Updated README with API key image
+- Removed unused files and .DS_Store entries
+- Package version bump
+
+### Fixed
+- Repository cleanup and organization
+
+## [1.2.1] - Previous Release
+
+### Added
+- Initial NEWO CLI functionality
+- Two-way sync between NEWO platform and local files
+- Support for .guidance and .jinja file types
+- SHA256-based change detection
+- Project structure export to flows.yaml
+- GitHub Actions CI/CD integration
+- Robust authentication with token refresh

package/README.md

@@ -44,6 +44,8 @@ npm install
 4. **Create** a new **Connector** for this Integration
 5. **Copy** your API key (it will look like: `458663bd41f2d1...`)
 
+![How to get your NEWO API Key](assets/newo-api-key.png)
+
 ### Step 2: Setup Environment
 ```bash
 cp .env.example .env
@@ -52,32 +54,42 @@ cp .env.example .env
 
 Required environment variables:
 - `NEWO_BASE_URL` (default `https://app.newo.ai`)
-- `NEWO_PROJECT_ID` (your project UUID from NEWO)
 - `NEWO_API_KEY` (your API key from Step 1)
 
-Optional (advanced):
+Optional environment variables:
+- `NEWO_PROJECT_ID` (specific project UUID - if not set, pulls all accessible projects)
 - `NEWO_ACCESS_TOKEN` (direct access token)
 - `NEWO_REFRESH_TOKEN` (refresh token)
 - `NEWO_REFRESH_URL` (custom refresh endpoint)
 
 ## Commands
 ```bash
-npx newo pull     # download project -> ./project
-npx newo status   # list modified files
-npx newo push     # upload modified *.guidance/*.jinja back to NEWO
+npx newo pull                              # download all projects -> ./projects/ OR specific project if NEWO_PROJECT_ID set
+npx newo status                            # list modified files
+npx newo push                              # upload modified *.guidance/*.jinja back to NEWO
+npx newo import-akb <file> <persona_id>    # import AKB articles from file
+npx newo meta                              # get project metadata (debug, requires NEWO_PROJECT_ID)
 ```
 
+### Project Structure
 Files are stored as:
-- `./project/<AgentIdn>/<FlowIdn>/<SkillIdn>.guidance` (AI guidance scripts)
-- `./project/<AgentIdn>/<FlowIdn>/<SkillIdn>.jinja` (NSL/Jinja template scripts)
+- **Multi-project mode** (no NEWO_PROJECT_ID): `./projects/<ProjectIdn>/<AgentIdn>/<FlowIdn>/<SkillIdn>.guidance|.jinja`
+- **Single-project mode** (NEWO_PROJECT_ID set): `./projects/<ProjectIdn>/<AgentIdn>/<FlowIdn>/<SkillIdn>.guidance|.jinja`
+
+Each project folder contains:
+- `metadata.json` - Project metadata (title, description, version, etc.)
+- `flows.yaml` - Complete project structure export for external tools
+- Agent/Flow/Skill hierarchy with `.guidance` (AI prompts) and `.jinja` (NSL templates)
 
 Hashes are tracked in `.newo/hashes.json` so only changed files are pushed.
-Project structure is also exported to `flows.yaml` for reference.
 
 ## Features
+- **Multi-project support**: Pull all accessible projects or specify a single project
 - **Two-way sync**: Pull NEWO projects to local files, push local changes back
 - **Change detection**: SHA256 hashing prevents unnecessary uploads
 - **Multiple file types**: `.guidance` (AI prompts) and `.jinja` (NSL templates)
+- **Project metadata**: Each project includes `metadata.json` with complete project info
+- **AKB import**: Import knowledge base articles from structured text files
 - **Project structure export**: Generates `flows.yaml` with complete project metadata
 - **Robust authentication**: API key exchange with automatic token refresh
 - **CI/CD ready**: GitHub Actions workflow included
@@ -90,8 +102,8 @@ on:
   push:
     branches: [ main ]
     paths:
-      - 'project/**/*.guidance'
-      - 'project/**/*.jinja'
+      - 'projects/**/*.guidance'
+      - 'projects/**/*.jinja'
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -110,11 +122,47 @@ jobs:
           # NEWO_REFRESH_URL: ${{ secrets.NEWO_REFRESH_URL }}
 ```
 
+## AKB Import
+
+Import knowledge base articles from structured text files into NEWO personas:
+
+```bash
+npx newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9
+```
+
+### AKB File Format
+```
+---
+# r001
+## Category / Subcategory / Description
+## Summary description of the category
+## Keywords; separated; by; semicolons
+
+<Category type="Category Name">
+Item Name: $Price [Modifiers: modifier1, modifier2]
+Another Item: $Price [Modifiers: modifier3]
+</Category>
+---
+```
+
+Each article will be imported with:
+- **topic_name**: The descriptive category title
+- **source**: The article ID (e.g., "r001") 
+- **topic_summary**: The full category content with pricing
+- **topic_facts**: Array containing category, summary, and keywords
+- **confidence**: 100
+- **labels**: ["rag_context"]
+
+Use `--verbose` flag to see detailed import progress.
+
 ## API Endpoints
+- `GET /api/v1/designer/projects` - List all accessible projects
+- `GET /api/v1/designer/projects/by-id/{projectId}` - Get specific project metadata
 - `GET /api/v1/bff/agents/list?project_id=...` - List project agents
 - `GET /api/v1/designer/flows/{flowId}/skills` - List skills in flow
 - `GET /api/v1/designer/skills/{skillId}` - Get skill content
 - `PUT /api/v1/designer/flows/skills/{skillId}` - Update skill content
 - `GET /api/v1/designer/flows/{flowId}/events` - List flow events (for flows.yaml)
 - `GET /api/v1/designer/flows/{flowId}/states` - List flow states (for flows.yaml)
-- `POST /api/v1/auth/api-key/token` - Exchange API key for access tokens
+- `POST /api/v1/auth/api-key/token` - Exchange API key for access tokens
+- `POST /api/v1/akb/append-manual` - Import AKB articles

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "newo",
-  "version": "1.2.2",
-  "description": "NEWO CLI: sync flows/skills between NEWO and local files",
+  "version": "1.4.0",
+  "description": "NEWO CLI: sync flows/skills between NEWO and local files, multi-project support, import AKB articles",
   "type": "module",
   "bin": {
     "newo": "src/cli.js"
@@ -9,6 +9,7 @@
   "files": [
     "src/**/*.js",
     "README.md",
+    "CHANGELOG.md",
     ".env.example"
   ],
   "keywords": [
@@ -18,7 +19,12 @@
     "agent",
     "automation",
     "sync",
-    "local-development"
+    "local-development",
+    "akb",
+    "knowledge-base",
+    "import",
+    "multi-project",
+    "workspace"
   ],
   "author": "sabbah13",
   "license": "MIT",
@@ -40,10 +46,17 @@
     "js-yaml": "^4.1.0",
     "minimist": "^1.2.8"
   },
+  "devDependencies": {
+    "mocha": "^10.2.0"
+  },
   "scripts": {
     "dev": "node ./src/cli.js",
     "pull": "node ./src/cli.js pull",
     "push": "node ./src/cli.js push",
-    "status": "node ./src/cli.js status"
+    "status": "node ./src/cli.js status",
+    "test": "mocha test/*.test.js --timeout 60000",
+    "test:api": "mocha test/api.test.js --timeout 30000",
+    "test:sync": "mocha test/sync.test.js --timeout 60000",
+    "test:integration": "mocha test/integration.test.js --timeout 120000"
   }
 }

package/src/akb.js

@@ -0,0 +1,112 @@
+import fs from 'fs-extra';
+
+/**
+ * Parse AKB file and extract articles
+ * @param {string} filePath - Path to AKB file
+ * @returns {Array} Array of parsed articles
+ */
+function parseAkbFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const articles = [];
+  
+  // Split by article separators (---)
+  const sections = content.split(/^---\s*$/gm).filter(section => section.trim());
+  
+  for (const section of sections) {
+    const lines = section.split('\n').filter(line => line.trim());
+    if (lines.length === 0) continue;
+    
+    const article = parseArticleSection(lines);
+    if (article) {
+      articles.push(article);
+    }
+  }
+  
+  return articles;
+}
+
+/**
+ * Parse individual article section
+ * @param {Array} lines - Lines of the article section
+ * @returns {Object|null} Parsed article object
+ */
+function parseArticleSection(lines) {
+  let topicName = '';
+  let category = '';
+  let summary = '';
+  let keywords = '';
+  let topicSummary = '';
+  
+  // Find topic name (# r001)
+  const topicLine = lines.find(line => line.match(/^#\s+r\d+/));
+  if (!topicLine) return null;
+  
+  topicName = topicLine.replace(/^#\s+/, '').trim();
+  
+  // Extract category/subcategory/description (first ## line)
+  const categoryLine = lines.find(line => line.startsWith('## ') && line.includes(' / '));
+  if (categoryLine) {
+    category = categoryLine.replace(/^##\s+/, '').trim();
+  }
+  
+  // Extract summary (second ## line)
+  const summaryLineIndex = lines.findIndex(line => line.startsWith('## ') && line.includes(' / '));
+  if (summaryLineIndex >= 0 && summaryLineIndex + 1 < lines.length) {
+    const nextLine = lines[summaryLineIndex + 1];
+    if (nextLine.startsWith('## ') && !nextLine.includes(' / ')) {
+      summary = nextLine.replace(/^##\s+/, '').trim();
+    }
+  }
+  
+  // Extract keywords (third ## line)
+  const keywordsLineIndex = lines.findIndex((line, index) => 
+    index > summaryLineIndex + 1 && line.startsWith('## ') && !line.includes(' / ')
+  );
+  if (keywordsLineIndex >= 0) {
+    keywords = lines[keywordsLineIndex].replace(/^##\s+/, '').trim();
+  }
+  
+  // Extract category content
+  const categoryStartIndex = lines.findIndex(line => line.includes('<Category type='));
+  const categoryEndIndex = lines.findIndex(line => line.includes('</Category>'));
+  
+  if (categoryStartIndex >= 0 && categoryEndIndex >= 0) {
+    const categoryLines = lines.slice(categoryStartIndex, categoryEndIndex + 1);
+    topicSummary = categoryLines.join('\n');
+  }
+  
+  // Create topic_facts array
+  const topicFacts = [
+    category,
+    summary,
+    keywords
+  ].filter(fact => fact.trim() !== '');
+  
+  return {
+    topic_name: category, // Use the descriptive title as topic_name
+    persona_id: null, // Will be set when importing
+    topic_summary: topicSummary,
+    topic_facts: topicFacts,
+    confidence: 100,
+    source: topicName, // Use the ID (r001) as source
+    labels: ["rag_context"]
+  };
+}
+
+/**
+ * Convert parsed articles to API format for bulk import
+ * @param {Array} articles - Parsed articles
+ * @param {string} personaId - Target persona ID
+ * @returns {Array} Array of articles ready for API import
+ */
+function prepareArticlesForImport(articles, personaId) {
+  return articles.map(article => ({
+    ...article,
+    persona_id: personaId
+  }));
+}
+
+export {
+  parseAkbFile,
+  prepareArticlesForImport
+};

package/src/api.js

@@ -58,6 +58,11 @@ export async function makeClient(verbose = false) {
   return client;
 }
 
+export async function listProjects(client) {
+  const r = await client.get(`/api/v1/designer/projects`);
+  return r.data;
+}
+
 export async function listAgents(client, projectId) {
   const r = await client.get(`/api/v1/bff/agents/list`, { params: { project_id: projectId } });
   return r.data;
@@ -90,4 +95,9 @@ export async function listFlowEvents(client, flowId) {
 export async function listFlowStates(client, flowId) {
   const r = await client.get(`/api/v1/designer/flows/${flowId}/states`);
   return r.data;
+}
+
+export async function importAkbArticle(client, articleData) {
+  const r = await client.post('/api/v1/akb/append-manual', articleData);
+  return r.data;
 }

package/src/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import minimist from 'minimist';
 import dotenv from 'dotenv';
-import { makeClient, getProjectMeta } from './api.js';
+import { makeClient, getProjectMeta, importAkbArticle } from './api.js';
 import { pullAll, pushChanged, status } from './sync.js';
+import { parseAkbFile, prepareArticlesForImport } from './akb.js';
+import path from 'path';
 
 dotenv.config();
 const { NEWO_PROJECT_ID } = process.env;
@@ -15,16 +17,24 @@ async function main() {
   if (!cmd || ['help', '-h', '--help'].includes(cmd)) {
     console.log(`NEWO CLI
 Usage:
-  newo pull           # download project -> ./project
-  newo push           # upload modified *.guidance/*.jinja back to NEWO
-  newo status         # show modified files
-  newo meta           # get project metadata (debug)
+  newo pull                    # download all projects -> ./projects/ OR specific project if NEWO_PROJECT_ID set
+  newo push                    # upload modified *.guidance/*.jinja back to NEWO
+  newo status                  # show modified files
+  newo meta                    # get project metadata (debug, requires NEWO_PROJECT_ID)
+  newo import-akb <file> <persona_id>  # import AKB articles from file
   
 Flags:
-  --verbose, -v       # enable detailed logging
+  --verbose, -v                # enable detailed logging
   
 Env:
-  NEWO_BASE_URL, NEWO_PROJECT_ID, NEWO_API_KEY, NEWO_REFRESH_URL (optional)
+  NEWO_BASE_URL, NEWO_PROJECT_ID (optional), NEWO_API_KEY, NEWO_REFRESH_URL (optional)
+  
+Notes:
+  - multi-project support: pull downloads all accessible projects or single project based on NEWO_PROJECT_ID
+  - If NEWO_PROJECT_ID is set, pull downloads only that project
+  - If NEWO_PROJECT_ID is not set, pull downloads all projects accessible with your API key
+  - Projects are stored in ./projects/{project-idn}/ folders
+  - Each project folder contains metadata.json and flows.yaml
 `);
     return;
   }
@@ -32,8 +42,8 @@ Env:
   const client = await makeClient(verbose);
 
   if (cmd === 'pull') {
-    if (!NEWO_PROJECT_ID) throw new Error('NEWO_PROJECT_ID is not set in env');
-    await pullAll(client, NEWO_PROJECT_ID, verbose);
+    // If PROJECT_ID is set, pull single project; otherwise pull all projects
+    await pullAll(client, NEWO_PROJECT_ID || null, verbose);
   } else if (cmd === 'push') {
     await pushChanged(client, verbose);
   } else if (cmd === 'status') {
@@ -42,6 +52,50 @@ Env:
     if (!NEWO_PROJECT_ID) throw new Error('NEWO_PROJECT_ID is not set in env');
     const meta = await getProjectMeta(client, NEWO_PROJECT_ID);
     console.log(JSON.stringify(meta, null, 2));
+  } else if (cmd === 'import-akb') {
+    const akbFile = args._[1];
+    const personaId = args._[2];
+    
+    if (!akbFile || !personaId) {
+      console.error('Usage: newo import-akb <file> <persona_id>');
+      console.error('Example: newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9');
+      process.exit(1);
+    }
+    
+    const filePath = path.resolve(akbFile);
+    
+    try {
+      if (verbose) console.log(`📖 Parsing AKB file: ${filePath}`);
+      const articles = parseAkbFile(filePath);
+      console.log(`✓ Parsed ${articles.length} articles from ${akbFile}`);
+      
+      if (verbose) console.log(`🔧 Preparing articles for persona: ${personaId}`);
+      const preparedArticles = prepareArticlesForImport(articles, personaId);
+      
+      let successCount = 0;
+      let errorCount = 0;
+      
+      console.log(`📤 Importing ${preparedArticles.length} articles...`);
+      
+      for (const [index, article] of preparedArticles.entries()) {
+        try {
+          if (verbose) console.log(`  [${index + 1}/${preparedArticles.length}] Importing ${article.topic_name}...`);
+          await importAkbArticle(client, article);
+          successCount++;
+          if (!verbose) process.stdout.write('.');
+        } catch (error) {
+          errorCount++;
+          console.error(`\n❌ Failed to import ${article.topic_name}:`, error?.response?.data || error.message);
+        }
+      }
+      
+      if (!verbose) console.log(''); // new line after dots
+      console.log(`✅ Import complete: ${successCount} successful, ${errorCount} failed`);
+      
+    } catch (error) {
+      console.error('❌ AKB import failed:', error.message);
+      process.exit(1);
+    }
   } else {
     console.error('Unknown command:', cmd);
     process.exit(1);

package/src/fsutil.js

@@ -1,7 +1,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 
-export const ROOT_DIR = path.join(process.cwd(), 'project');
+export const ROOT_DIR = path.join(process.cwd(), 'projects');
 export const STATE_DIR = path.join(process.cwd(), '.newo');
 export const MAP_PATH = path.join(STATE_DIR, 'map.json');
 export const HASHES_PATH = path.join(STATE_DIR, 'hashes.json');
@@ -11,9 +11,17 @@ export async function ensureState() {
   await fs.ensureDir(ROOT_DIR);
 }
 
-export function skillPath(agentIdn, flowIdn, skillIdn, runnerType = 'guidance') {
+export function projectDir(projectIdn) {
+  return path.join(ROOT_DIR, projectIdn);
+}
+
+export function skillPath(projectIdn, agentIdn, flowIdn, skillIdn, runnerType = 'guidance') {
   const extension = runnerType === 'nsl' ? '.jinja' : '.guidance';
-  return path.join(ROOT_DIR, agentIdn, flowIdn, `${skillIdn}${extension}`);
+  return path.join(ROOT_DIR, projectIdn, agentIdn, flowIdn, `${skillIdn}${extension}`);
+}
+
+export function metadataPath(projectIdn) {
+  return path.join(ROOT_DIR, projectIdn, 'metadata.json');
 }
 
 export async function writeFileAtomic(filepath, content) {

package/src/sync.js

@@ -1,31 +1,35 @@
-import { listAgents, listFlowSkills, updateSkill, listFlowEvents, listFlowStates } from './api.js';
-import { ensureState, skillPath, writeFileAtomic, readIfExists, MAP_PATH } from './fsutil.js';
+import { listProjects, listAgents, listFlowSkills, updateSkill, listFlowEvents, listFlowStates, getProjectMeta } from './api.js';
+import { ensureState, skillPath, writeFileAtomic, readIfExists, MAP_PATH, projectDir, metadataPath } from './fsutil.js';
 import fs from 'fs-extra';
 import { sha256, loadHashes, saveHashes } from './hash.js';
 import yaml from 'js-yaml';
 import path from 'path';
 
-export async function pullAll(client, projectId, verbose = false) {
-  await ensureState();
-  if (verbose) console.log(`🔍 Fetching agents for project ${projectId}...`);
+export async function pullSingleProject(client, projectId, projectIdn, verbose = false) {
+  if (verbose) console.log(`🔍 Fetching agents for project ${projectId} (${projectIdn})...`);
   const agents = await listAgents(client, projectId);
   if (verbose) console.log(`📦 Found ${agents.length} agents`);
 
-  const idMap = { projectId, agents: {} };
+  // Get and save project metadata
+  const projectMeta = await getProjectMeta(client, projectId);
+  await writeFileAtomic(metadataPath(projectIdn), JSON.stringify(projectMeta, null, 2));
+  if (verbose) console.log(`✓ Saved metadata for ${projectIdn}`);
+
+  const projectMap = { projectId, projectIdn, agents: {} };
 
   for (const agent of agents) {
     const aKey = agent.idn;
-    idMap.agents[aKey] = { id: agent.id, flows: {} };
+    projectMap.agents[aKey] = { id: agent.id, flows: {} };
 
     for (const flow of agent.flows ?? []) {
-      idMap.agents[aKey].flows[flow.idn] = { id: flow.id, skills: {} };
+      projectMap.agents[aKey].flows[flow.idn] = { id: flow.id, skills: {} };
 
       const skills = await listFlowSkills(client, flow.id);
       for (const s of skills) {
-        const file = skillPath(agent.idn, flow.idn, s.idn, s.runner_type);
+        const file = skillPath(projectIdn, agent.idn, flow.idn, s.idn, s.runner_type);
         await writeFileAtomic(file, s.prompt_script || '');
         // Store complete skill metadata for push operations
-        idMap.agents[aKey].flows[flow.idn].skills[s.idn] = {
+        projectMap.agents[aKey].flows[flow.idn].skills[s.idn] = {
           id: s.id,
           title: s.title,
           idn: s.idn,
@@ -39,23 +43,66 @@ export async function pullAll(client, projectId, verbose = false) {
     }
   }
 
-  await fs.writeJson(MAP_PATH, idMap, { spaces: 2 });
+  // Generate flows.yaml for this project
+  if (verbose) console.log(`📄 Generating flows.yaml for ${projectIdn}...`);
+  await generateFlowsYaml(client, agents, projectIdn, verbose);
+
+  return projectMap;
+}
+
+export async function pullAll(client, projectId = null, verbose = false) {
+  await ensureState();
+  
+  if (projectId) {
+    // Single project mode
+    const projectMeta = await getProjectMeta(client, projectId);
+    const projectMap = await pullSingleProject(client, projectId, projectMeta.idn, verbose);
+    
+    const idMap = { projects: { [projectMeta.idn]: projectMap } };
+    await fs.writeJson(MAP_PATH, idMap, { spaces: 2 });
+    
+    // Generate hash tracking for this project
+    const hashes = {};
+    for (const [agentIdn, agentObj] of Object.entries(projectMap.agents)) {
+      for (const [flowIdn, flowObj] of Object.entries(agentObj.flows)) {
+        for (const [skillIdn, skillMeta] of Object.entries(flowObj.skills)) {
+          const p = skillPath(projectMeta.idn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
+          const content = await fs.readFile(p, 'utf8');
+          hashes[p] = sha256(content);
+        }
+      }
+    }
+    await saveHashes(hashes);
+    return;
+  }
+
+  // Multi-project mode
+  if (verbose) console.log(`🔍 Fetching all projects...`);
+  const projects = await listProjects(client);
+  if (verbose) console.log(`📦 Found ${projects.length} projects`);
+
+  const idMap = { projects: {} };
+  const allHashes = {};
 
-  // Generate flows.yaml
-  if (verbose) console.log('📄 Generating flows.yaml...');
-  await generateFlowsYaml(client, agents, verbose);
+  for (const project of projects) {
+    if (verbose) console.log(`\n📁 Processing project: ${project.idn} (${project.title})`);
+    const projectMap = await pullSingleProject(client, project.id, project.idn, verbose);
+    idMap.projects[project.idn] = projectMap;
 
-  const hashes = {};
-  for (const [agentIdn, agentObj] of Object.entries(idMap.agents)) {
-    for (const [flowIdn, flowObj] of Object.entries(agentObj.flows)) {
-      for (const [skillIdn, skillMeta] of Object.entries(flowObj.skills)) {
-        const p = skillPath(agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
-        const content = await fs.readFile(p, 'utf8');
-        hashes[p] = sha256(content);
+    // Collect hashes for this project
+    for (const [agentIdn, agentObj] of Object.entries(projectMap.agents)) {
+      for (const [flowIdn, flowObj] of Object.entries(agentObj.flows)) {
+        for (const [skillIdn, skillMeta] of Object.entries(flowObj.skills)) {
+          const p = skillPath(project.idn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
+          const content = await fs.readFile(p, 'utf8');
+          allHashes[p] = sha256(content);
+        }
       }
     }
   }
-  await saveHashes(hashes);
+
+  await fs.writeJson(MAP_PATH, idMap, { spaces: 2 });
+  await saveHashes(allHashes);
 }
 
 export async function pushChanged(client, verbose = false) {
@@ -74,59 +121,68 @@ export async function pushChanged(client, verbose = false) {
   let pushed = 0;
   let scanned = 0;
   
-  for (const [agentIdn, agentObj] of Object.entries(idMap.agents)) {
-    if (verbose) console.log(`  📁 Scanning agent: ${agentIdn}`);
-    for (const [flowIdn, flowObj] of Object.entries(agentObj.flows)) {
-      if (verbose) console.log(`    📁 Scanning flow: ${flowIdn}`);
-      for (const [skillIdn, skillMeta] of Object.entries(flowObj.skills)) {
-        const p = skillPath(agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
-        scanned++;
-        if (verbose) console.log(`      📄 Checking: ${p}`);
-        
-        const content = await readIfExists(p);
-        if (content === null) {
-          if (verbose) console.log(`        ⚠️  File not found: ${p}`);
-          continue;
-        }
-        
-        const h = sha256(content);
-        const oldHash = oldHashes[p];
-        if (verbose) {
-          console.log(`        🔍 Hash comparison:`);
-          console.log(`          Old: ${oldHash || 'none'}`);
-          console.log(`          New: ${h}`);
-        }
-        
-        if (oldHash !== h) {
-          if (verbose) console.log(`        🔄 File changed, preparing to push...`);
+  // Handle both old single-project format and new multi-project format
+  const projects = idMap.projects || { '': idMap };
+  
+  for (const [projectIdn, projectData] of Object.entries(projects)) {
+    if (verbose && projectIdn) console.log(`📁 Scanning project: ${projectIdn}`);
+    
+    for (const [agentIdn, agentObj] of Object.entries(projectData.agents)) {
+      if (verbose) console.log(`  📁 Scanning agent: ${agentIdn}`);
+      for (const [flowIdn, flowObj] of Object.entries(agentObj.flows)) {
+        if (verbose) console.log(`    📁 Scanning flow: ${flowIdn}`);
+        for (const [skillIdn, skillMeta] of Object.entries(flowObj.skills)) {
+          const p = projectIdn ? 
+            skillPath(projectIdn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type) :
+            skillPath('', agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
+          scanned++;
+          if (verbose) console.log(`      📄 Checking: ${p}`);
           
-          // Create complete skill object with updated prompt_script
-          const skillObject = {
-            id: skillMeta.id,
-            title: skillMeta.title,
-            idn: skillMeta.idn,
-            prompt_script: content,
-            runner_type: skillMeta.runner_type,
-            model: skillMeta.model,
-            parameters: skillMeta.parameters,
-            path: skillMeta.path
-          };
+          const content = await readIfExists(p);
+          if (content === null) {
+            if (verbose) console.log(`        ⚠️  File not found: ${p}`);
+            continue;
+          }
           
+          const h = sha256(content);
+          const oldHash = oldHashes[p];
           if (verbose) {
-            console.log(`        📤 Pushing skill object:`);
-            console.log(`          ID: ${skillObject.id}`);
-            console.log(`          Title: ${skillObject.title}`);
-            console.log(`          IDN: ${skillObject.idn}`);
-            console.log(`          Content length: ${content.length} chars`);
-            console.log(`          Content preview: ${content.substring(0, 100).replace(/\n/g, '\\n')}...`);
+            console.log(`        🔍 Hash comparison:`);
+            console.log(`          Old: ${oldHash || 'none'}`);
+            console.log(`          New: ${h}`);
           }
           
-          await updateSkill(client, skillObject);
-          console.log(`↑ Pushed ${p}`);
-          newHashes[p] = h;
-          pushed++;
-        } else if (verbose) {
-          console.log(`        ✓ No changes`);
+          if (oldHash !== h) {
+            if (verbose) console.log(`        🔄 File changed, preparing to push...`);
+            
+            // Create complete skill object with updated prompt_script
+            const skillObject = {
+              id: skillMeta.id,
+              title: skillMeta.title,
+              idn: skillMeta.idn,
+              prompt_script: content,
+              runner_type: skillMeta.runner_type,
+              model: skillMeta.model,
+              parameters: skillMeta.parameters,
+              path: skillMeta.path
+            };
+            
+            if (verbose) {
+              console.log(`        📤 Pushing skill object:`);
+              console.log(`          ID: ${skillObject.id}`);
+              console.log(`          Title: ${skillObject.title}`);
+              console.log(`          IDN: ${skillObject.idn}`);
+              console.log(`          Content length: ${content.length} chars`);
+              console.log(`          Content preview: ${content.substring(0, 100).replace(/\n/g, '\\n')}...`);
+            }
+            
+            await updateSkill(client, skillObject);
+            console.log(`↑ Pushed ${p}`);
+            newHashes[p] = h;
+            pushed++;
+          } else if (verbose) {
+            console.log(`        ✓ No changes`);
+          }
         }
       }
     }
@@ -149,33 +205,42 @@ export async function status(verbose = false) {
   const hashes = await loadHashes();
   let dirty = 0;
 
-  for (const [agentIdn, agentObj] of Object.entries(idMap.agents)) {
-    if (verbose) console.log(`  📁 Checking agent: ${agentIdn}`);
-    for (const [flowIdn, flowObj] of Object.entries(agentObj.flows)) {
-      if (verbose) console.log(`    📁 Checking flow: ${flowIdn}`);
-      for (const [skillIdn, skillMeta] of Object.entries(flowObj.skills)) {
-        const p = skillPath(agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
-        const exists = await fs.pathExists(p);
-        if (!exists) { 
-          console.log(`D  ${p}`); 
-          dirty++; 
-          if (verbose) console.log(`      ❌ Deleted: ${p}`);
-          continue; 
-        }
-        const content = await fs.readFile(p, 'utf8');
-        const h = sha256(content);
-        const oldHash = hashes[p];
-        if (verbose) {
-          console.log(`      📄 ${p}`);
-          console.log(`        Old hash: ${oldHash || 'none'}`);
-          console.log(`        New hash: ${h}`);
-        }
-        if (oldHash !== h) { 
-          console.log(`M  ${p}`); 
-          dirty++; 
-          if (verbose) console.log(`      🔄 Modified: ${p}`);
-        } else if (verbose) {
-          console.log(`      ✓ Unchanged: ${p}`);
+  // Handle both old single-project format and new multi-project format
+  const projects = idMap.projects || { '': idMap };
+
+  for (const [projectIdn, projectData] of Object.entries(projects)) {
+    if (verbose && projectIdn) console.log(`📁 Checking project: ${projectIdn}`);
+    
+    for (const [agentIdn, agentObj] of Object.entries(projectData.agents)) {
+      if (verbose) console.log(`  📁 Checking agent: ${agentIdn}`);
+      for (const [flowIdn, flowObj] of Object.entries(agentObj.flows)) {
+        if (verbose) console.log(`    📁 Checking flow: ${flowIdn}`);
+        for (const [skillIdn, skillMeta] of Object.entries(flowObj.skills)) {
+          const p = projectIdn ? 
+            skillPath(projectIdn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type) :
+            skillPath('', agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
+          const exists = await fs.pathExists(p);
+          if (!exists) { 
+            console.log(`D  ${p}`); 
+            dirty++; 
+            if (verbose) console.log(`      ❌ Deleted: ${p}`);
+            continue; 
+          }
+          const content = await fs.readFile(p, 'utf8');
+          const h = sha256(content);
+          const oldHash = hashes[p];
+          if (verbose) {
+            console.log(`      📄 ${p}`);
+            console.log(`        Old hash: ${oldHash || 'none'}`);
+            console.log(`        New hash: ${h}`);
+          }
+          if (oldHash !== h) { 
+            console.log(`M  ${p}`); 
+            dirty++; 
+            if (verbose) console.log(`      🔄 Modified: ${p}`);
+          } else if (verbose) {
+            console.log(`      ✓ Unchanged: ${p}`);
+          }
         }
       }
     }
@@ -183,7 +248,7 @@ export async function status(verbose = false) {
   console.log(dirty ? `${dirty} changed file(s).` : 'Clean.');
 }
 
-async function generateFlowsYaml(client, agents, verbose = false) {
+async function generateFlowsYaml(client, agents, projectIdn, verbose = false) {
   const flowsData = { flows: [] };
 
   for (const agent of agents) {
@@ -278,7 +343,7 @@ async function generateFlowsYaml(client, agents, verbose = false) {
   // Post-process to fix enum formatting
   yamlContent = yamlContent.replace(/"(!enum "[^"]+")"/g, '$1');
   
-  const yamlPath = path.join('flows.yaml');
-  await fs.writeFile(yamlPath, yamlContent, 'utf8');
-  console.log(`✓ Generated flows.yaml`);
+  const yamlPath = path.join(projectDir(projectIdn), 'flows.yaml');
+  await writeFileAtomic(yamlPath, yamlContent);
+  console.log(`✓ Generated flows.yaml for ${projectIdn}`);
 }