aios-core 3.4.0 → 3.5.0

package/.aios-core/development/tasks/squad-creator-sync-synkra.md

@@ -3,81 +3,313 @@ task: Sync Squad to Synkra
 responsavel: "@squad-creator"
 responsavel_type: agent
 atomic_layer: task
-status: placeholder
+status: active
 sprint: 8
+story: SQS-5
+version: 1.0.0
 Entrada: |
-  - name: Nome do squad para sincronizar
-  - pricing: Modelo de preco (free | premium | subscription)
+  - squad_path: Caminho do squad para sincronizar (obrigatório)
+  - visibility: public | private (default: private)
+  - official: Flag para marcar como oficial (--official, apenas SynkraAI)
+  - dry_run: Preview sem sincronizar (--dry-run)
 Saida: |
-  - api_url: URL na Synkra API
-  - dashboard_url: URL do dashboard de gestao
-  - status: Sucesso ou erro
+  - sync_result: Resultado do sync (created | updated | skipped)
+  - squad_url: URL do squad no marketplace (quando público)
+  - squad_id: ID único do squad
+  - checksum: Checksum do squad sincronizado
 Checklist:
-  - "[ ] Implementar em Sprint 8 (SQS-5)"
+  - "[x] Validar squad localmente"
+  - "[x] Obter token de autenticação"
+  - "[x] Calcular checksum"
+  - "[x] Enviar para Synkra API"
+  - "[x] Exibir URL do marketplace"
 ---
 
 # *sync-squad-synkra
 
-> **PLACEHOLDER** - Implementation scheduled for Sprint 8 (Story SQS-5)
+Sincroniza um squad local para o Synkra API marketplace.
 
-## Planned Functionality
+## Uso
 
-Syncs a local squad to the Synkra API marketplace for distribution and monetization.
+```bash
+@squad-creator
+
+# Sync privado (apenas workspace)
+*sync-squad-synkra ./squads/meu-squad
+
+# Sync público (visível para todos)
+*sync-squad-synkra ./squads/meu-squad --public
+
+# Preview sem sincronizar
+*sync-squad-synkra ./squads/meu-squad --dry-run
+
+# Sync com verbosidade
+*sync-squad-synkra ./squads/meu-squad --verbose
+```
 
-## Planned Usage
+## Autenticação
+
+Requer autenticação com Synkra API:
 
 ```bash
-@squad-creator
+export SYNKRA_API_TOKEN="seu-token"
+```
 
-*sync-squad-synkra meu-squad
-# → Syncs to api.synkra.dev/squads (free tier)
+Ou configure em `.env`:
 
-*sync-squad-synkra meu-squad --pricing premium --price 9.99
-# → Syncs as premium squad with pricing
+```env
+SYNKRA_API_URL=https://api.synkra.dev/api
+SYNKRA_API_TOKEN=seu-token
+```
+
+Para obter um token:
+1. Acesse https://synkra.dev/settings/api-keys
+2. Crie uma nova API key com permissões de sync
+3. Configure a variável de ambiente
+
+## Output Exemplo
 
-*sync-squad-synkra meu-squad --update
-# → Updates existing squad in marketplace
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *sync-squad-synkra
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Squad: ./squads/meu-squad/
 
-## Planned Features
+Step 1: Local Validation
+  ✓ Found squad.yaml
+  ✓ Name: meu-squad
+  ✓ Version: 1.0.0
+  ✓ Schema validation: PASSED
 
-1. **Authentication**
-   - Require Synkra API key
-   - Validate account permissions
-   - Support team accounts
+Step 2: Calculate Checksum
+  ✓ Checksum: a1b2c3d4e5f6...
 
-2. **Pricing Models**
-   - Free: Available to all users
-   - Premium: One-time purchase
-   - Subscription: Monthly/yearly
+Step 3: Sync to Synkra API
+  ✓ Visibility: private
+  ✓ API URL: https://api.synkra.dev/api
 
-3. **Version Management**
-   - Semantic versioning
-   - Changelog generation
-   - Update existing squads
+Syncing to Synkra API...
 
-4. **Analytics Dashboard**
-   - Download statistics
-   - Revenue tracking (for paid)
-   - User feedback
+✅ Squad synced successfully!
 
-## Synkra API Endpoints
+  Status:   created
+  ID:       550e8400-e29b-41d4-a716-446655440000
+  Checksum: a1b2c3d4e5f6...
 
-```http
-POST   /api/v1/squads           # Create new squad
-PUT    /api/v1/squads/{id}      # Update existing
-GET    /api/v1/squads/{id}      # Get squad info
-DELETE /api/v1/squads/{id}      # Remove squad
-GET    /api/v1/squads/me        # List my squads
+Next steps:
+  - View squad: *describe-squad meu-squad
+  - Make public: *sync-squad-synkra ./squads/meu-squad --public
 ```
 
-## Related Story
+## Flags
+
+| Flag | Descrição | Default |
+|------|-----------|---------|
+| `--public` | Torna o squad visível no marketplace público | false |
+| `--private` | Mantém squad privado (apenas workspace) | true |
+| `--dry-run` | Preview sem enviar para API | false |
+| `--verbose` | Output detalhado | false |
+| `--official` | Marca como squad oficial (apenas SynkraAI team) | false |
+| `--force` | Ignora warnings e força sync | false |
+
+## Workflow
+
+```
+┌──────────────────────────────────────────────────┐
+│              *sync-squad-synkra                   │
+├──────────────────────────────────────────────────┤
+│                                                   │
+│  1. Parse Arguments                               │
+│     ↓                                             │
+│  2. Find squad.yaml                               │
+│     ↓                                             │
+│  3. Validate with squad-validator.js              │
+│     ↓ (fail → abort)                              │
+│  4. Calculate SHA-256 checksum                    │
+│     ↓                                             │
+│  5. Check SYNKRA_API_TOKEN                        │
+│     ↓ (missing → abort)                           │
+│  6. If --dry-run: show preview and exit           │
+│     ↓                                             │
+│  7. POST to /api/squads/sync                      │
+│     ↓                                             │
+│  8. Display result and marketplace URL            │
+│                                                   │
+└──────────────────────────────────────────────────┘
+```
+
+## API Integration
+
+### Request
+
+```javascript
+POST ${SYNKRA_API_URL}/squads/sync
+Authorization: Bearer ${SYNKRA_API_TOKEN}
+Content-Type: application/json
+
+{
+  "squadData": {
+    "name": "meu-squad",
+    "version": "1.0.0",
+    "description": "...",
+    "author": "...",
+    "license": "MIT",
+    "components": {...},
+    "tags": [...]
+  },
+  "isPublic": false,
+  "isOfficial": false
+}
+```
+
+### Response (Success)
+
+```json
+{
+  "success": true,
+  "data": {
+    "action": "created",
+    "squad_id": "meu-squad",
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "version": "1.0.0"
+  },
+  "duration_ms": 150
+}
+```
+
+### Response (Error)
+
+```json
+{
+  "success": false,
+  "error": "Validation failed: Missing required field: version"
+}
+```
+
+## Implementation Guide
+
+### For Agent Execution
+
+```javascript
+// 1. Parse squad path from arguments
+const squadPath = args[0] || '.';
+const flags = parseFlags(args);
+
+// 2. Find and read squad.yaml
+const squadYamlPath = path.join(squadPath, 'squad.yaml');
+if (!fs.existsSync(squadYamlPath)) {
+  error(`squad.yaml not found in ${squadPath}`);
+  return;
+}
+
+// 3. Validate with squad-validator.js
+const { validateSquad } = await import('.aios-core/development/scripts/squad/squad-validator.js');
+const validation = await validateSquad(squadYamlPath);
+
+if (!validation.valid) {
+  error(`Validation failed: ${validation.errors.join(', ')}`);
+  return;
+}
+
+if (validation.warnings.length > 0 && !flags.force) {
+  warn(`Warnings: ${validation.warnings.join(', ')}`);
+  // Consider prompting user to continue
+}
+
+// 4. Read and parse squad data
+const squadContent = fs.readFileSync(squadYamlPath, 'utf8');
+const squadData = parseYaml(squadContent);
+
+// 5. Calculate checksum
+const checksum = crypto.createHash('sha256')
+  .update(squadContent)
+  .digest('hex');
+
+// 6. Check authentication
+const apiToken = process.env.SYNKRA_API_TOKEN;
+const apiUrl = process.env.SYNKRA_API_URL || 'https://api.synkra.dev/api';
 
-- **SQS-5:** SquadSyncService (Sprint 8)
+if (!apiToken) {
+  error('SYNKRA_API_TOKEN not set. See task docs for authentication.');
+  return;
+}
+
+// 7. Dry run check
+if (flags.dryRun) {
+  output(`
+DRY RUN - Would sync:
+  Squad: ${squadData.name}
+  Version: ${squadData.version}
+  Checksum: ${checksum}
+  Visibility: ${flags.public ? 'public' : 'private'}
+  `);
+  return;
+}
+
+// 8. Call Synkra API
+const response = await fetch(`${apiUrl}/squads/sync`, {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${apiToken}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    squadData: {
+      ...squadData,
+      checksum,
+      raw_content: squadContent
+    },
+    isPublic: flags.public,
+    isOfficial: flags.official
+  })
+});
+
+const result = await response.json();
+
+// 9. Display result
+if (result.success) {
+  output(`
+✅ Squad synced successfully!
+
+  Status:   ${result.data.action}
+  ID:       ${result.data.id}
+  Squad ID: ${result.data.squad_id}
+  `);
+
+  if (flags.public) {
+    output(`  URL: https://synkra.dev/squads/${result.data.squad_id}`);
+  }
+} else {
+  error(`Sync failed: ${result.error}`);
+}
+```
+
+## Error Handling
+
+| Error | Causa | Solução |
+|-------|-------|---------|
+| `squad.yaml not found` | Caminho inválido | Verifique o path do squad |
+| `Validation failed` | Squad não passa na validação | Execute `*validate-squad` primeiro |
+| `SYNKRA_API_TOKEN not set` | Token não configurado | Configure a variável de ambiente |
+| `401 Unauthorized` | Token inválido ou expirado | Gere novo token em synkra.dev |
+| `403 Forbidden` | Sem permissão para operação | Verifique permissões da API key |
+| `Squad not found or not owned` | Tentando atualizar squad de outro workspace | Verifique ownership |
+
+## Related Tasks
+
+- `*create-squad` - Criar novo squad local
+- `*validate-squad` - Validar squad antes de sync
+- `*describe-squad` - Ver detalhes do squad
+- `*list-squads` - Listar squads disponíveis
+
+## Related Story
 
-## Current Status
+- **SQS-5:** SquadSyncService for Synkra API (Sprint 8)
 
-This task is a placeholder. The full implementation will be done in Sprint 8.
+## Changelog
 
-The Synkra API is under development at:
-- https://api.synkra.dev (planned)
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0.0 | 2025-12-23 | Full implementation (Story SQS-5) |
+| 0.1.0 | 2025-12-18 | Initial placeholder |

package/.aios-core/install-manifest.yaml

@@ -7,10 +7,10 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 3.4.0
-generated_at: "2025-12-23T02:05:10.189Z"
+version: 3.5.0
+generated_at: "2025-12-23T20:58:00.734Z"
 generator: scripts/generate-install-manifest.js
-file_count: 564
+file_count: 568
 files:
   - path: cli/commands/generate/index.js
     hash: sha256:36f8e38ab767fa5478d8dabac548c66dc2c0fc521c216e954ac33fcea0ba597b
@@ -425,9 +425,9 @@ files:
     type: agent
     size: 9866
   - path: development/agents/squad-creator.md
-    hash: sha256:a7942dcbbe235784ebe9c3b69d1845c7ceed4c7519d33d77e9be8d585ebcd7d4
+    hash: sha256:b2d40ad818043acd04cb00eb2e5ff778498c65dc91bf81eb6675467fcd60c514
     type: agent
-    size: 9943
+    size: 10367
   - path: development/agents/ux-design-expert.md
     hash: sha256:ce2f28bbd7350f1ca7d1b01ae26924928e496314afb551cafb55604233117954
     type: agent
@@ -505,9 +505,9 @@ files:
     type: script
     size: 9449
   - path: development/scripts/squad/index.js
-    hash: sha256:dfbce334b3a0668f448dbaa7732a8827ade6a95ae15956da19c47d5eb92fa642
+    hash: sha256:e76b9c8be107210f33e7689bb8098e47e6970ce6816e6e9e4d0d5a948f7627f3
     type: script
-    size: 1592
+    size: 2649
   - path: development/scripts/squad/README.md
     hash: sha256:55e0226c3baffe16fd24f3d19179326c43e8dc525697c0b5c972cf15825f7c14
     type: script
@@ -516,6 +516,10 @@ files:
     hash: sha256:101cbb7d6ded0d6f991b29ac63dfee2c7bb86cbc8c4fefef728b7d12c3352829
     type: script
     size: 29548
+  - path: development/scripts/squad/squad-downloader.js
+    hash: sha256:a62dd5d40ef24426ffdabdcbe0a0a3a7e7e2b1757eba9749a41d3fd4c0e690f8
+    type: script
+    size: 15335
   - path: development/scripts/squad/squad-generator.js
     hash: sha256:6d47ee7e0c662ffd7a8c5975ceca3e71addb54f59fb771d55402d0d57ce3d7d8
     type: script
@@ -524,6 +528,14 @@ files:
     hash: sha256:7093b9457c93da6845722bf7eac660164963d5007c459afae2149340a7979f1f
     type: script
     size: 10549
+  - path: development/scripts/squad/squad-migrator.js
+    hash: sha256:883899cb84117b66074004fb683ba5f9cefebc57eeb9758f79784e0a92afcd90
+    type: script
+    size: 19520
+  - path: development/scripts/squad/squad-publisher.js
+    hash: sha256:329c00fb9d1085675a319e8314a5be9e1ee92c617691c47041f58d994982e029
+    type: script
+    size: 18724
   - path: development/scripts/squad/squad-validator.js
     hash: sha256:a19af336adf8caaa79f98e52ab78aee57a9a0a0041f3c4b6c9663a321c0a7f64
     type: script
@@ -557,9 +569,9 @@ files:
     type: script
     size: 6348
   - path: development/tasks/add-mcp.md
-    hash: sha256:a77a71c540241affac9219f3d19cecd052db84d5b430a4ad7820b6034b3b9ba6
+    hash: sha256:8a19ae5f343b68d7aace6a8400a18349fb7b4ebc92cecdab33e2a7f4f0d88512
     type: task
-    size: 6559
+    size: 10205
   - path: development/tasks/advanced-elicitation.md
     hash: sha256:fbd55c3cbafb1336eafb8968c0f34035c2f352b22c45c150c7a327c7697438f9
     type: task
@@ -997,9 +1009,9 @@ files:
     type: task
     size: 4700
   - path: development/tasks/setup-mcp-docker.md
-    hash: sha256:5acbcafde17dc8c9f020d47862fc4f72536c6d8a710d49c28856b515b5363230
+    hash: sha256:2d81956e164d5e62f2e5be6b0c25d37b85fded3dc25a8393fb1cdc44d1dfbddc
     type: task
-    size: 14913
+    size: 16304
   - path: development/tasks/setup-project-docs.md
     hash: sha256:61ddcbba5e7836480f65ad23ea2e8eb3f5347deff1e68610a2084b2c4a38b918
     type: task
@@ -1021,21 +1033,25 @@ files:
     type: task
     size: 12698
   - path: development/tasks/squad-creator-download.md
-    hash: sha256:48c364b2709229d24b5b517e6b9f6894aad82d37613f1631445e94d3c6e1c581
+    hash: sha256:909088d7b585fbb8b465e0b0238ab49546c51876a6752a30f7bf7bf1bf22ef24
     type: task
-    size: 1503
+    size: 3856
   - path: development/tasks/squad-creator-list.md
     hash: sha256:c0b52c5a8a79b3ed757789e633f42a5458bac18bbcf1aa544fc1f5295151b446
     type: task
     size: 6555
+  - path: development/tasks/squad-creator-migrate.md
+    hash: sha256:c0f669b2d490c698d7b448408019558ff02a46c5232c8e6ce58cd7b5131d4565
+    type: task
+    size: 8712
   - path: development/tasks/squad-creator-publish.md
-    hash: sha256:5bd5b1798dd375557b2279823b829973749d571b14b1ecb9a6e846b686b6bd96
+    hash: sha256:f54cd24b45796ac9d3cee8876a1edca316f5560878201e828cad43d9e951ddc6
     type: task
-    size: 1905
+    size: 4918
   - path: development/tasks/squad-creator-sync-synkra.md
-    hash: sha256:d9f82aab934080d7ab9cbee2077d8536d5221426e374ad57f8b5e96a6086b835
+    hash: sha256:9e3cb982b6de771daf22788eb43d06bf7a197c32f15be4860946407b824ef150
     type: task
-    size: 1921
+    size: 8633
   - path: development/tasks/squad-creator-validate.md
     hash: sha256:c07c44217e882cae387d849658e091046e32735a62f6d28e496b4eb042121b98
     type: task

package/.claude/rules/mcp-usage.md

@@ -30,11 +30,13 @@ AIOS uses Docker MCP Toolkit as the primary MCP infrastructure:
 | **playwright** | Browser automation, screenshots, web testing |
 | **desktop-commander** | Docker container operations via docker-gateway |
 
-### Inside Docker Desktop (via desktop-commander)
+### Inside Docker Desktop (via docker-gateway)
+
 | MCP | Purpose |
 |-----|---------|
 | **EXA** | Web search, research, company/competitor analysis |
 | **Context7** | Library documentation lookup |
+| **Apify** | Web scraping, Actors, social media data extraction |
 
 ## CRITICAL: Tool Selection Priority
 
@@ -106,11 +108,69 @@ mcp__docker-gateway__resolve-library-id
 mcp__docker-gateway__get-library-docs
 ```
 
+## Apify MCP Usage (via Docker)
+
+### Use Apify for:
+1. Searching Actors in Apify Store (web scrapers, automation tools)
+2. Running web scrapers for social media (Instagram, TikTok, LinkedIn, etc.)
+3. Extracting data from e-commerce sites
+4. Automated data collection from any website
+5. RAG-enabled web browsing for AI context
+
+### Access pattern (7 tools available):
+
+```text
+mcp__docker-gateway__apify-slash-rag-web-browser  # RAG-enabled web browsing
+mcp__docker-gateway__search-actors                 # Search for Actors
+mcp__docker-gateway__call-actor                    # Run an Actor
+mcp__docker-gateway__fetch-actor-details           # Get Actor info/schema
+mcp__docker-gateway__get-actor-output              # Get results from Actor run
+mcp__docker-gateway__search-apify-docs             # Search Apify documentation
+mcp__docker-gateway__fetch-apify-docs              # Fetch documentation page
+```
+
+### When to use Apify vs other tools:
+| Task | Tool |
+|------|------|
+| General web search | EXA (`web_search_exa`) |
+| Scrape specific website | Apify (`call-actor`) |
+| Social media data extraction | Apify (use specialized Actors) |
+| Library documentation | Context7 |
+
+---
+
 ## Rationale
 
 - **Native tools** execute on the LOCAL system (Windows/Mac/Linux)
 - **docker-gateway** executes inside Docker containers (Linux)
 - Using docker-gateway for local operations causes path mismatches and failures
 - Native tools are faster and more reliable for local file operations
-- EXA and Context7 run inside Docker for isolation and consistent environment
+- EXA, Context7, and Apify run inside Docker for isolation and consistent environment
 - playwright runs directly for better browser integration with host system
+
+---
+
+## Known Issues
+
+### Docker MCP Secrets Bug (Dec 2025)
+
+**Issue:** Docker MCP Toolkit's secrets store and template interpolation do not work properly. Credentials set via `docker mcp secret set` are NOT passed to containers.
+
+**Symptoms:**
+- `docker mcp tools ls` shows "(N prompts)" instead of "(N tools)"
+- MCP server starts but fails authentication
+- Verbose output shows `-e ENV_VAR` without values
+
+**Workaround:** Edit `~/.docker/mcp/catalogs/docker-mcp.yaml` directly with hardcoded env values:
+```yaml
+{mcp-name}:
+  env:
+    - name: API_TOKEN
+      value: 'actual-token-value'
+```
+
+**Affected MCPs:** Any MCP requiring authentication (Apify, Notion, Slack, etc.)
+
+**Working MCPs:** EXA works because its key is in `~/.docker/mcp/config.yaml` under `apiKeys`
+
+For detailed instructions, see `*add-mcp` task or ask @devops for assistance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aios-core",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework",
   "main": "index.js",
   "module": "index.esm.js",