@miranda0808/maya-codex 0.1.0

package/payload/tools/integrations/zapier.md

@@ -0,0 +1,150 @@
+# Zapier
+
+Workflow automation platform connecting apps without code.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API for Zaps, tasks, and webhooks |
+| MCP | ✓ | Available via Zapier MCP server |
+| CLI | - | Not available |
+| SDK | - | API and webhooks only |
+
+## Authentication
+
+- **Type**: API Key
+- **Header**: `X-API-Key: {api_key}`
+- **Get key**: Settings > API in Zapier account
+
+## Common Agent Operations
+
+### List Zaps
+
+```bash
+GET https://api.zapier.com/v1/zaps
+```
+
+### Get Zap details
+
+```bash
+GET https://api.zapier.com/v1/zaps/{zap_id}
+```
+
+### Turn Zap on/off
+
+```bash
+POST https://api.zapier.com/v1/zaps/{zap_id}/on
+POST https://api.zapier.com/v1/zaps/{zap_id}/off
+```
+
+### Get task history
+
+```bash
+GET https://api.zapier.com/v1/zaps/{zap_id}/tasks
+```
+
+### Get profile info
+
+```bash
+GET https://api.zapier.com/v1/profiles/me
+```
+
+## Webhooks (Triggers)
+
+### Catch Hook (receive data)
+
+Create a "Webhooks by Zapier" trigger to receive data:
+
+```bash
+POST https://hooks.zapier.com/hooks/catch/{webhook_id}/
+
+{
+  "event": "user.created",
+  "user_id": "123",
+  "email": "user@example.com"
+}
+```
+
+### Send data to Zapier
+
+Most common: trigger a Zap from your app:
+
+```bash
+POST https://hooks.zapier.com/hooks/catch/{account_id}/{hook_id}/
+
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "plan": "pro"
+}
+```
+
+## Common Marketing Automations
+
+### Lead capture to CRM
+```
+Typeform → Zapier → HubSpot
+```
+
+### New customer notifications
+```
+Stripe (new customer) → Zapier → Slack
+```
+
+### Email sequence triggers
+```
+Form submission → Zapier → Customer.io
+```
+
+### Social proof automation
+```
+New review → Zapier → Twitter/Slack
+```
+
+### Referral tracking
+```
+New referral → Zapier → Spreadsheet + Slack
+```
+
+## Webhook Payload Structure
+
+When sending to Zapier, structure data as flat JSON:
+
+```json
+{
+  "customer_name": "John Doe",
+  "customer_email": "john@example.com",
+  "plan_name": "Pro",
+  "plan_price": 99,
+  "signup_date": "2024-01-15"
+}
+```
+
+## Key Concepts
+
+- **Zap** - Automated workflow
+- **Trigger** - Event that starts a Zap
+- **Action** - Task performed by Zap
+- **Task** - Single action execution
+- **Filter** - Conditional logic
+- **Path** - Branching logic
+
+## When to Use
+
+- Connecting marketing tools without code
+- Automating lead routing
+- Syncing data between platforms
+- Triggering notifications
+- Building marketing workflows
+
+## Rate Limits
+
+- 100 requests per minute
+- Task limits by plan tier
+
+## Relevant Skills
+
+- email-sequence
+- analytics-tracking
+- referral-program

package/payload/tools/meta/README.md

@@ -0,0 +1,55 @@
+# Meta Tool Maintenance
+
+## Source
+
+- Vendored from the upstream `marketingskills` repository: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)
+- Local CLI file: `tools/clis/meta-ads.js`
+- Approved Maya boundary: `tools/meta/meta-fetch.ps1`
+- Current local API base in the vendored file: `https://graph.facebook.com/v18.0`
+
+## Usage Boundary
+
+- Agents should prefer `tools/meta/meta-fetch.ps1` for Meta reads.
+- `meta-fetch.ps1` is the Maya-owned boundary for validation, read-only allowlisting, output sanitization, and cache writes.
+- Keep secrets in environment variables only.
+- Do not place raw tokens, headers, or unsafe debug output in prompts, logs, state files, or cache files.
+
+## Maintenance Policy
+
+- Treat `tools/clis/meta-ads.js` as vendored upstream code.
+- Do not hand-maintain feature changes in the vendored file unless there is an urgent local fix.
+- When the tool stops working, Meta deprecates an API version, or we need a newer endpoint or field, check the exact upstream tool first.
+- Prefer replacing the local vendored file from upstream over accumulating local drift.
+
+## Update Triggers
+
+Review the upstream `meta-ads.js` when any of the following happens:
+
+- Meta returns version deprecation or unsupported endpoint errors.
+- Expected fields disappear or response shapes change.
+- We need a newer Graph API version than the one pinned in the vendored file.
+- The upstream `marketingskills` repo updates the same tool.
+
+## Safe Update Workflow
+
+1. Compare the local `tools/clis/meta-ads.js` with the upstream `meta-ads.js` in `coreyhaines31/marketingskills`.
+2. Prefer a clean vendor refresh instead of manually mixing old and new logic.
+3. Re-run dry-run and read-only verification commands after updating.
+4. Keep any future Maya-specific safety behavior in wrappers under `tools/meta/`, not inside the vendored CLI unless strictly necessary.
+
+## Verification After A Bump
+
+Run at minimum:
+
+```powershell
+node --check 'tools/clis/meta-ads.js'
+powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action list -DryRun
+powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action insights -Id 123 -DatePreset last_30d -DryRun
+```
+
+Confirm:
+
+- syntax still passes
+- dry-run masks authorization data
+- command structure still matches expected usage
+- no local secrets are written to files, prompts, logs, or outputs

package/payload/tools/meta/meta-cache-schema.md

@@ -0,0 +1,65 @@
+# Meta Cache Schema
+
+## Purpose
+
+Sanitized cache files written by `tools/meta/meta-fetch.ps1` for read-only Meta Ads data access.
+
+## Location
+
+- Cache directory: `outputs/meta-cache/`
+- One JSON file per non-dry-run fetch
+
+## Schema
+
+```json
+{
+  "schema_version": 1,
+  "source": "meta-ads",
+  "safe_account_alias": "acct-***6789",
+  "fetched_at": "2026-03-12T10:00:00.0000000+08:00",
+  "date_range": {
+    "date_preset": "last_30d"
+  },
+  "normalized_params": {
+    "resource": "campaigns",
+    "action": "insights",
+    "account_id": "acct-***6789",
+    "id": "120000000000000001",
+    "adset_id": null,
+    "date_preset": "last_30d"
+  },
+  "forbidden_fields": [
+    "authorization",
+    "access_token",
+    "token",
+    "secret",
+    "password",
+    "api_key"
+  ],
+  "payload": {}
+}
+```
+
+## Required Fields
+
+- `schema_version`: cache schema version number
+- `source`: upstream tool source
+- `safe_account_alias`: masked account identifier
+- `fetched_at`: ISO-8601 fetch timestamp
+- `normalized_params`: normalized request parameters used for the fetch
+- `forbidden_fields`: sensitive fields that must never appear in cache payloads
+- `payload`: sanitized response payload
+
+## Optional Fields
+
+- `date_range`: included when the underlying fetch uses a date window or preset
+
+## Security Rules
+
+Cache files must never contain:
+
+- raw access tokens
+- authorization headers
+- secrets, passwords, or API keys
+- unsafe debug dumps
+- raw environment variable values

package/payload/tools/meta/meta-fetch.ps1

@@ -0,0 +1,324 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [ValidateSet('accounts', 'campaigns', 'adsets', 'ads', 'audiences')]
+  [string]$Resource,
+
+  [Parameter(Mandatory = $true)]
+  [string]$Action,
+
+  [string]$AccountId,
+  [string]$Id,
+  [string]$AdsetId,
+  [string]$DatePreset = 'last_30d',
+  [switch]$DryRun
+)
+
+$ErrorActionPreference = 'Stop'
+
+$allowedActions = @{
+  accounts = @('list')
+  campaigns = @('list', 'insights')
+  adsets = @('list')
+  ads = @('list')
+  audiences = @('list')
+}
+
+if (-not $allowedActions.ContainsKey($Resource) -or $Action -notin $allowedActions[$Resource]) {
+  throw "Unsupported operation '$Resource $Action'. Allowed read-only operations: accounts list, campaigns list|insights, adsets list, ads list, audiences list."
+}
+
+if (-not $env:META_ACCESS_TOKEN) {
+  throw 'META_ACCESS_TOKEN environment variable is required.'
+}
+
+$effectiveAccountId = if ($AccountId) { $AccountId } else { $env:META_AD_ACCOUNT_ID }
+
+switch ("$Resource/$Action") {
+  'campaigns/list' {
+    if (-not $effectiveAccountId) { throw 'META_AD_ACCOUNT_ID or -AccountId is required for campaigns list.' }
+  }
+  'campaigns/insights' {
+    if (-not $Id) { throw '-Id is required for campaigns insights.' }
+  }
+  'adsets/list' {
+    if (-not $effectiveAccountId) { throw 'META_AD_ACCOUNT_ID or -AccountId is required for adsets list.' }
+  }
+  'ads/list' {
+    if (-not $AdsetId) { throw '-AdsetId is required for ads list.' }
+  }
+  'audiences/list' {
+    if (-not $effectiveAccountId) { throw 'META_AD_ACCOUNT_ID or -AccountId is required for audiences list.' }
+  }
+}
+
+function Get-SafeAccountAlias([string]$Value) {
+  if (-not $Value) { return 'none' }
+  $trimmed = $Value.Trim()
+  if ($trimmed.Length -le 4) { return "acct-$trimmed" }
+  return "acct-***$($trimmed.Substring($trimmed.Length - 4))"
+}
+
+function Sanitize-Data($InputObject) {
+  if ($null -eq $InputObject) { return $null }
+
+  if ($InputObject -is [System.Collections.IDictionary]) {
+    $result = [ordered]@{}
+    foreach ($key in $InputObject.Keys) {
+      $keyText = [string]$key
+      $value = $InputObject[$key]
+      if ($keyText -match '(?i)authorization|access_token|token|secret|password|api[_-]?key') {
+        $result[$keyText] = '***'
+      } else {
+        $result[$keyText] = Sanitize-Data $value
+      }
+    }
+    return $result
+  }
+
+  if ($InputObject -is [pscustomobject]) {
+    $result = [ordered]@{}
+    foreach ($property in $InputObject.PSObject.Properties) {
+      $name = [string]$property.Name
+      $value = $property.Value
+      if ($name -match '(?i)authorization|access_token|token|secret|password|api[_-]?key') {
+        $result[$name] = '***'
+      } else {
+        $result[$name] = Sanitize-Data $value
+      }
+    }
+    return $result
+  }
+
+  if ($InputObject -is [System.Collections.IEnumerable] -and -not ($InputObject -is [string])) {
+    $items = @()
+    foreach ($item in $InputObject) {
+      $items += ,(Sanitize-Data $item)
+    }
+    return $items
+  }
+
+  if ($InputObject -is [string] -and $InputObject -eq $env:META_ACCESS_TOKEN) {
+    return '***'
+  }
+
+  return $InputObject
+}
+
+function Get-JsonKey($Object) {
+  return (($Object | ConvertTo-Json -Depth 20 -Compress) -replace '\s+', '')
+}
+
+function Get-RequestPolicy([string]$ResourceName, [string]$ActionName, [string]$Preset) {
+  if ($ResourceName -eq 'campaigns' -and $ActionName -eq 'insights') {
+    $safeClosedPresets = @('yesterday')
+    if ($Preset -notin $safeClosedPresets) {
+      return [ordered]@{
+        cache_bypass = $true
+        coverage_type = 'intraday'
+        is_complete = $false
+        ttl_minutes = 0
+      }
+    }
+
+    return [ordered]@{
+      cache_bypass = $false
+      coverage_type = 'complete_day'
+      is_complete = $true
+      ttl_minutes = 360
+    }
+  }
+
+  return [ordered]@{
+    cache_bypass = $false
+    coverage_type = 'complete_snapshot'
+    is_complete = $true
+    ttl_minutes = 15
+  }
+}
+
+$repoRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+$cliPath = Join-Path $repoRoot 'tools\clis\meta-ads.js'
+$cacheRoot = Join-Path $repoRoot 'outputs\meta-cache'
+
+if (-not (Test-Path $cliPath)) {
+  throw "Vendored CLI not found at $cliPath"
+}
+
+$normalizedParams = [ordered]@{
+  resource = $Resource
+  action = $Action
+  account_id = if ($effectiveAccountId) { Get-SafeAccountAlias $effectiveAccountId } else { $null }
+  id = if ($Id) { $Id } else { '' }
+  adset_id = if ($AdsetId) { Get-SafeAccountAlias $AdsetId } else { $null }
+  date_preset = if ($Resource -eq 'campaigns' -and $Action -eq 'insights') { $DatePreset } else { $null }
+}
+$requestKey = Get-JsonKey $normalizedParams
+$policy = Get-RequestPolicy -ResourceName $Resource -ActionName $Action -Preset $DatePreset
+
+function Find-FreshCacheEntry {
+  param(
+    [string]$CacheDirectory,
+    [string]$WantedKey
+  )
+
+  if (-not (Test-Path $CacheDirectory)) {
+    return $null
+  }
+
+  $now = Get-Date
+  foreach ($file in Get-ChildItem $CacheDirectory -Filter '*.json' -File -ErrorAction SilentlyContinue) {
+    try {
+      $doc = Get-Content $file.FullName -Raw | ConvertFrom-Json
+    }
+    catch {
+      continue
+    }
+
+    if (-not $doc.normalized_params) {
+      continue
+    }
+
+    $docKey = Get-JsonKey (Sanitize-Data $doc.normalized_params)
+    if ($docKey -ne $WantedKey) {
+      continue
+    }
+
+    if (-not $doc.expires_at) {
+      continue
+    }
+
+    try {
+      $expiresAt = [datetimeoffset]::Parse([string]$doc.expires_at)
+    }
+    catch {
+      continue
+    }
+
+    if ($expiresAt -le [datetimeoffset]$now) {
+      continue
+    }
+
+    return [ordered]@{
+      file = $file.FullName
+      document = $doc
+    }
+  }
+
+  return $null
+}
+
+function Invoke-MetaCli {
+  param([switch]$UseDryRun)
+
+  $cliArgs = @($cliPath, $Resource, $Action)
+  if ($effectiveAccountId -and $Resource -in @('campaigns', 'adsets', 'audiences')) {
+    $cliArgs += @('--account-id', $effectiveAccountId)
+  }
+  if ($Id) {
+    $cliArgs += @('--id', $Id)
+  }
+  if ($AdsetId) {
+    $cliArgs += @('--adset-id', $AdsetId)
+  }
+  if ($Resource -eq 'campaigns' -and $Action -eq 'insights' -and $DatePreset) {
+    $cliArgs += @('--date-preset', $DatePreset)
+  }
+  if ($UseDryRun) {
+    $cliArgs += '--dry-run'
+  }
+
+  $rawOutput = & node @cliArgs 2>&1
+  $exitCode = $LASTEXITCODE
+  $textOutput = ($rawOutput | Out-String).Trim()
+
+  if ($exitCode -ne 0) {
+    $safeError = $textOutput -replace [regex]::Escape($env:META_ACCESS_TOKEN), '***'
+    throw "meta-ads.js failed: $safeError"
+  }
+
+  try {
+    return $textOutput | ConvertFrom-Json
+  }
+  catch {
+    throw "meta-ads.js returned non-JSON output: $textOutput"
+  }
+}
+
+function Build-Result {
+  param(
+    [string]$CacheStatus,
+    [string]$CoverageType,
+    [bool]$IsComplete,
+    [object]$Payload,
+    [string]$AsOf,
+    [string]$ExpiresAt,
+    [string]$CachePath
+  )
+
+  $result = [ordered]@{
+    source = 'meta-ads'
+    dry_run = [bool]$DryRun
+    cache_status = $CacheStatus
+    safe_account_alias = Get-SafeAccountAlias $effectiveAccountId
+    as_of = $AsOf
+    expires_at = $ExpiresAt
+    coverage_type = $CoverageType
+    is_complete = $IsComplete
+    normalized_params = $normalizedParams
+    payload = $Payload
+    forbidden_fields = @('authorization', 'access_token', 'token', 'secret', 'password', 'api_key')
+  }
+
+  if ($CachePath) {
+    $result['cache_path'] = $CachePath
+  }
+
+  return $result
+}
+
+$cacheEntry = $null
+if (-not $policy.cache_bypass) {
+  $cacheEntry = Find-FreshCacheEntry -CacheDirectory $cacheRoot -WantedKey $requestKey
+}
+
+if ($cacheEntry) {
+  $doc = $cacheEntry.document
+  $payload = Sanitize-Data $doc.payload
+  $result = Build-Result -CacheStatus 'hit' -CoverageType ([string]$doc.coverage_type) -IsComplete ([bool]$doc.is_complete) -Payload $payload -AsOf ([string]$doc.as_of) -ExpiresAt ([string]$doc.expires_at) -CachePath $cacheEntry.file
+  ($result | ConvertTo-Json -Depth 20)
+  exit 0
+}
+
+$livePayload = Sanitize-Data (Invoke-MetaCli -UseDryRun:$DryRun)
+$cacheStatus = if ($policy.cache_bypass) { 'bypass' } else { 'miss' }
+$asOf = (Get-Date).ToString('o')
+$expiresAt = if ($policy.ttl_minutes -gt 0) { (Get-Date).AddMinutes($policy.ttl_minutes).ToString('o') } else { $null }
+$cachePath = $null
+
+if (-not $DryRun -and -not $policy.cache_bypass) {
+  New-Item -ItemType Directory -Force -Path $cacheRoot | Out-Null
+  $stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+  $fileName = "meta-$Resource-$Action-$stamp.json"
+  $cachePath = Join-Path $cacheRoot $fileName
+
+  $cacheDocument = [ordered]@{
+    schema_version = 1
+    source = 'meta-ads'
+    cache_status = $cacheStatus
+    safe_account_alias = Get-SafeAccountAlias $effectiveAccountId
+    as_of = $asOf
+    fetched_at = $asOf
+    expires_at = $expiresAt
+    coverage_type = $policy.coverage_type
+    is_complete = $policy.is_complete
+    date_range = if ($Resource -eq 'campaigns' -and $Action -eq 'insights') { @{ date_preset = $DatePreset } } else { $null }
+    normalized_params = $normalizedParams
+    forbidden_fields = @('authorization', 'access_token', 'token', 'secret', 'password', 'api_key')
+    payload = $livePayload
+  }
+
+  ($cacheDocument | ConvertTo-Json -Depth 20) | Set-Content $cachePath
+}
+
+$result = Build-Result -CacheStatus $cacheStatus -CoverageType $policy.coverage_type -IsComplete $policy.is_complete -Payload $livePayload -AsOf $asOf -ExpiresAt $expiresAt -CachePath $cachePath
+($result | ConvertTo-Json -Depth 20)

package/payload/tools/meta/meta-fetch.test.ps1

@@ -0,0 +1,38 @@
+$ErrorActionPreference = 'Stop'
+Set-ExecutionPolicy -Scope Process Bypass -Force
+
+$wrapper = Join-Path $PSScriptRoot 'meta-fetch.ps1'
+
+if (-not (Test-Path $wrapper)) {
+  throw 'meta-fetch.ps1 is missing'
+}
+
+$oldToken = $env:META_ACCESS_TOKEN
+$oldAccount = $env:META_AD_ACCOUNT_ID
+$env:META_ACCESS_TOKEN = 'super-secret-token'
+$env:META_AD_ACCOUNT_ID = '1234567890'
+
+try {
+  $output = & $wrapper -Resource campaigns -Action list -DryRun 2>&1
+  $text = ($output | Out-String)
+
+  if ($LASTEXITCODE -ne 0) {
+    throw "Expected dry run to succeed but exit code was $LASTEXITCODE. Output: $text"
+  }
+
+  if ($text -match 'super-secret-token') {
+    throw 'Dry run output leaked META_ACCESS_TOKEN'
+  }
+
+  if ($text -notmatch '"dry_run"\s*:\s*true') {
+    throw "Expected dry_run marker in output. Output: $text"
+  }
+
+  if ($text -notmatch '"cache_status"\s*:\s*"miss"') {
+    throw "Expected cache_status miss marker in dry-run output. Output: $text"
+  }
+}
+finally {
+  $env:META_ACCESS_TOKEN = $oldToken
+  $env:META_AD_ACCOUNT_ID = $oldAccount
+}

package/vendor/shared-installer/manifests/claude-files.json

@@ -0,0 +1,13 @@
+{
+  "files": [
+    {
+      "source": "templates/claude/CLAUDE.md",
+      "destination": "CLAUDE.md",
+      "template": true
+    },
+    {
+      "source": ".agents/skills",
+      "destination": ".claude/skills"
+    }
+  ]
+}

package/vendor/shared-installer/manifests/codex-files.json

@@ -0,0 +1,13 @@
+{
+  "files": [
+    {
+      "source": "templates/codex/AGENTS.md",
+      "destination": "AGENTS.md",
+      "template": true
+    },
+    {
+      "source": ".agents/skills",
+      "destination": ".agent/skills"
+    }
+  ]
+}

package/vendor/shared-installer/manifests/common-files.json

@@ -0,0 +1,13 @@
+{
+  "files": [
+    "MAYA.md",
+    "MAYA-CATALOG.md",
+    "MAYA-DEPENDENCIES.md",
+    "commands",
+    ".maya",
+    "templates",
+    "campaigns/README.md",
+    "research/README.md",
+    "tools"
+  ]
+}

package/vendor/shared-installer/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@miranda0808/shared-installer",
+  "version": "0.1.0",
+  "private": true,
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "manifests",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18.18 <23"
+  }
+}
+

package/vendor/shared-installer/src/bootstrap.js

@@ -0,0 +1,12 @@
+"use strict";
+
+const { readFile } = require("./fs");
+
+async function renderBootstrap(operation) {
+  const content = await readFile(operation.sourcePath, "utf8");
+  return content;
+}
+
+module.exports = {
+  renderBootstrap,
+};