@arthai/agents 1.0.0

package/skills/railway/metrics/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: metrics
+description: This skill should be used when the user asks about resource usage, CPU, memory, network, disk, or service performance. Covers questions like "how much memory is my service using" or "is my service slow".
+allowed-tools: Bash(railway:*)
+---
+
+# Service Metrics
+
+Query resource usage metrics for Railway services.
+
+## When to Use
+
+- User asks "how much memory is my service using?"
+- User asks about CPU usage, network traffic, disk usage
+- User wants to debug performance issues
+- User asks "is my service healthy?" (combine with `service` skill)
+
+## Prerequisites
+
+Get environmentId and serviceId from linked project:
+
+```bash
+railway status --json
+```
+
+Extract:
+- `environment.id` → environmentId
+- `service.id` → serviceId (optional - omit to get all services)
+
+## MetricMeasurement Values
+
+| Measurement | Description |
+|-------------|-------------|
+| CPU_USAGE | CPU usage (cores) |
+| CPU_LIMIT | CPU limit (cores) |
+| MEMORY_USAGE_GB | Memory usage in GB |
+| MEMORY_LIMIT_GB | Memory limit in GB |
+| NETWORK_RX_GB | Network received in GB |
+| NETWORK_TX_GB | Network transmitted in GB |
+| DISK_USAGE_GB | Disk usage in GB |
+| EPHEMERAL_DISK_USAGE_GB | Ephemeral disk usage in GB |
+| BACKUP_USAGE_GB | Backup usage in GB |
+
+## MetricTag Values (for groupBy)
+
+| Tag | Description |
+|-----|-------------|
+| DEPLOYMENT_ID | Group by deployment |
+| DEPLOYMENT_INSTANCE_ID | Group by instance |
+| REGION | Group by region |
+| SERVICE_ID | Group by service |
+
+## Query
+
+```graphql
+query metrics(
+  $environmentId: String!
+  $serviceId: String
+  $startDate: DateTime!
+  $endDate: DateTime
+  $sampleRateSeconds: Int
+  $averagingWindowSeconds: Int
+  $groupBy: [MetricTag!]
+  $measurements: [MetricMeasurement!]!
+) {
+  metrics(
+    environmentId: $environmentId
+    serviceId: $serviceId
+    startDate: $startDate
+    endDate: $endDate
+    sampleRateSeconds: $sampleRateSeconds
+    averagingWindowSeconds: $averagingWindowSeconds
+    groupBy: $groupBy
+    measurements: $measurements
+  ) {
+    measurement
+    tags {
+      deploymentInstanceId
+      deploymentId
+      serviceId
+      region
+    }
+    values {
+      ts
+      value
+    }
+  }
+}
+```
+
+## Example: Last Hour CPU and Memory
+
+Use heredoc to avoid shell escaping issues:
+
+```bash
+bash <<'SCRIPT'
+START_DATE=$(date -u -v-1H +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d "1 hour ago" +"%Y-%m-%dT%H:%M:%SZ")
+ENV_ID="your-environment-id"
+SERVICE_ID="your-service-id"
+
+VARS=$(jq -n \
+  --arg env "$ENV_ID" \
+  --arg svc "$SERVICE_ID" \
+  --arg start "$START_DATE" \
+  '{environmentId: $env, serviceId: $svc, startDate: $start, measurements: ["CPU_USAGE", "MEMORY_USAGE_GB"]}')
+
+scripts/railway-api.sh \
+  'query metrics($environmentId: String!, $serviceId: String, $startDate: DateTime!, $measurements: [MetricMeasurement!]!) {
+    metrics(environmentId: $environmentId, serviceId: $serviceId, startDate: $startDate, measurements: $measurements) {
+      measurement
+      tags { deploymentId region serviceId }
+      values { ts value }
+    }
+  }' \
+  "$VARS"
+SCRIPT
+```
+
+## Example: All Services in Environment
+
+Omit serviceId and use groupBy to get metrics for all services:
+
+```bash
+bash <<'SCRIPT'
+START_DATE=$(date -u -v-1H +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d "1 hour ago" +"%Y-%m-%dT%H:%M:%SZ")
+ENV_ID="your-environment-id"
+
+VARS=$(jq -n \
+  --arg env "$ENV_ID" \
+  --arg start "$START_DATE" \
+  '{environmentId: $env, startDate: $start, measurements: ["CPU_USAGE", "MEMORY_USAGE_GB"], groupBy: ["SERVICE_ID"]}')
+
+scripts/railway-api.sh \
+  'query metrics($environmentId: String!, $startDate: DateTime!, $measurements: [MetricMeasurement!]!, $groupBy: [MetricTag!]) {
+    metrics(environmentId: $environmentId, startDate: $startDate, measurements: $measurements, groupBy: $groupBy) {
+      measurement
+      tags { serviceId region }
+      values { ts value }
+    }
+  }' \
+  "$VARS"
+SCRIPT
+```
+
+## Time Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| startDate | Required. ISO 8601 format (e.g., `2024-01-01T00:00:00Z`) |
+| endDate | Optional. Defaults to now |
+| sampleRateSeconds | Sample interval (e.g., 60 for 1-minute samples) |
+| averagingWindowSeconds | Averaging window for smoothing |
+
+**Tip:** For last hour, calculate startDate as `now - 1 hour` in ISO format.
+
+## Output Interpretation
+
+```json
+{
+  "data": {
+    "metrics": [
+      {
+        "measurement": "CPU_USAGE",
+        "tags": { "deploymentId": "...", "serviceId": "...", "region": "us-west1" },
+        "values": [
+          { "ts": "2024-01-01T00:00:00Z", "value": 0.25 },
+          { "ts": "2024-01-01T00:01:00Z", "value": 0.30 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- `ts` - timestamp in ISO format
+- `value` - metric value (cores for CPU, GB for memory/disk/network)
+
+## Composability
+
+- **Get IDs**: Use `status` skill or `railway status --json`
+- **Check service health**: Use `service` skill for deployment status
+- **View logs**: Use `deployment` skill if metrics show issues
+- **Scale service**: Use `environment` skill to adjust resources
+
+## Error Handling
+
+### Empty/Null Metrics
+
+Services without active deployments return empty metrics arrays. When processing with jq, handle nulls:
+
+```bash
+# Safe iteration - skip nulls
+jq -r '.data.metrics[]? | select(.values != null and (.values | length) > 0) | ...'
+
+# Check if metrics exist before processing
+jq -e '.data.metrics | length > 0' response.json && echo "has metrics"
+```
+
+### No Metrics Data
+
+Service may be new or have no traffic. Check:
+- Service has active deployment (stopped services have no metrics)
+- Time range includes deployment period
+
+### Invalid Service/Environment ID
+
+Verify IDs with `railway status --json`.
+
+### Permission Denied
+
+User needs access to the project to query metrics.

package/skills/railway/metrics/references/environment-config.md

@@ -0,0 +1,183 @@
+# Environment Config Reference
+
+The `EnvironmentConfig` object is used to configure services, volumes, and shared variables in Railway.
+
+## Structure
+
+```json
+{
+  "services": {
+    "<serviceId>": {
+      "source": { ... },
+      "build": { ... },
+      "deploy": { ... },
+      "variables": { ... },
+      "networking": { ... }
+    }
+  },
+  "sharedVariables": { ... },
+  "volumes": { ... },
+  "buckets": { ... }
+}
+```
+
+Only include fields being changed. The patch is merged with existing config.
+
+Apply changes via CLI: `echo '<json>' | railway environment edit --json`
+
+## Service Config
+
+### Source
+| Field | Type | Description |
+|-------|------|-------------|
+| `image` | string | Docker image (e.g., `nginx:latest`) |
+| `repo` | string | Git repository URL |
+| `branch` | string | Git branch to deploy |
+| `commitSha` | string | Specific commit SHA |
+| `rootDirectory` | string | Root directory (monorepos) |
+| `checkSuites` | boolean | Wait for GitHub check suites |
+| `autoUpdates.type` | disabled \| patch \| minor | Auto-update policy for Docker images |
+
+### Build
+| Field | Type | Description |
+|-------|------|-------------|
+| `builder` | NIXPACKS \| DOCKERFILE \| RAILPACK | Build system |
+| `buildCommand` | string | Command for Nixpacks builds |
+| `dockerfilePath` | string | Path to Dockerfile |
+| `watchPatterns` | string[] | Patterns to trigger deploys |
+| `nixpacksConfigPath` | string | Path to nixpacks config |
+
+### Deploy
+| Field | Type | Description |
+|-------|------|-------------|
+| `startCommand` | string | Container start command |
+| `multiRegionConfig` | object | Region → replica config. See [Multi-Region Config](#multi-region-config). |
+| `healthcheckPath` | string | Health check endpoint |
+| `healthcheckTimeout` | number | Seconds to wait for health |
+| `restartPolicyType` | ON_FAILURE \| ALWAYS \| NEVER | Restart behavior |
+| `restartPolicyMaxRetries` | number | Max restart attempts |
+| `cronSchedule` | string | Cron schedule for cron jobs |
+| `sleepApplication` | boolean | Sleep when inactive |
+
+### Variables
+| Field | Type | Description |
+|-------|------|-------------|
+| `value` | string | Variable value |
+| `isOptional` | boolean | Allow empty value |
+
+Set to `null` to delete a variable.
+
+For variable references, see [variables.md](variables.md).
+
+### Lifecycle
+| Field | Type | Description |
+|-------|------|-------------|
+| `isDeleted` | boolean | Mark for deletion (requires ADMIN) |
+| `isCreated` | boolean | Mark as newly created |
+
+## Multi-Region Config
+
+Controls replica count per region. Structure: region name → `{ numReplicas }` or `null` to remove.
+
+```json
+{
+  "multiRegionConfig": {
+    "us-west2": { "numReplicas": 3 },
+    "europe-west4-drams3a": { "numReplicas": 2 }
+  }
+}
+```
+
+### Available Regions
+
+| Name | Location | Aliases |
+|------|----------|---------|
+| `us-west2` | US West (California) | "us west", "california" |
+| `us-east4-eqdc4a` | US East (Virginia) | "us east", "virginia" |
+| `europe-west4-drams3a` | EU West (Amsterdam) | "europe", "eu", "amsterdam" |
+| `asia-southeast1-eqsg3a` | Southeast Asia (Singapore) | "asia", "singapore" |
+
+### Interpreting User Requests
+
+- "add 3 replicas to europe" → `{ "europe-west4-drams3a": { "numReplicas": 3 } }`
+- "add a replica to all regions" → set `numReplicas: 1` for all 4 regions
+- "remove from asia" → `{ "asia-southeast1-eqsg3a": null }`
+- "increase replicas to 5" (no region specified) → query current config first, update existing region(s)
+
+**Important:** When user doesn't specify a region, query the current `multiRegionConfig` and modify the existing region(s). Don't assume a default region.
+
+## Common Operations
+
+### Set Build Command
+```json
+{ "services": { "<serviceId>": { "build": { "buildCommand": "npm run build" } } } }
+```
+
+### Set Start Command
+```json
+{ "services": { "<serviceId>": { "deploy": { "startCommand": "node server.js" } } } }
+```
+
+### Set Replicas
+```json
+{ "services": { "<serviceId>": { "deploy": { "multiRegionConfig": { "us-west2": { "numReplicas": 3 } } } } } }
+```
+
+### Add Variables
+```json
+{ "services": { "<serviceId>": { "variables": { "API_KEY": { "value": "xxx" } } } } }
+```
+
+### Delete Variable
+```json
+{ "services": { "<serviceId>": { "variables": { "OLD_VAR": null } } } }
+```
+Via CLI: `echo '{"services":{"<serviceId>":{"variables":{"OLD_VAR":null}}}}' | railway environment edit --json`
+
+### Add Shared Variable
+```json
+{ "sharedVariables": { "DATABASE_URL": { "value": "postgres://..." } } }
+```
+
+### Change Docker Image
+```json
+{ "services": { "<serviceId>": { "source": { "image": "nginx:latest" } } } }
+```
+
+### Connect GitHub Repo
+```json
+{ "services": { "<serviceId>": { "source": { "repo": "owner/repo", "branch": "main" } } } }
+```
+
+### Change Git Branch
+```json
+{ "services": { "<serviceId>": { "source": { "branch": "develop" } } } }
+```
+
+### Set Health Check
+```json
+{ "services": { "<serviceId>": { "deploy": { "healthcheckPath": "/health", "healthcheckTimeout": 30 } } } }
+```
+
+### Change Builder
+```json
+{ "services": { "<serviceId>": { "build": { "builder": "DOCKERFILE", "dockerfilePath": "./Dockerfile" } } } }
+```
+
+### Delete Service
+```json
+{ "services": { "<serviceId>": { "isDeleted": true } } }
+```
+Via CLI: `echo '{"services":{"<serviceId>":{"isDeleted":true}}}' | railway environment edit --json`
+
+### Delete Volume
+```json
+{ "volumes": { "<volumeId>": { "isDeleted": true } } }
+```
+
+### New Service Instance
+```json
+{ "services": { "<serviceId>": { "isCreated": true, "source": { "image": "nginx" } } } }
+```
+
+**Note:** `isCreated: true` is required for new service instances.

package/skills/railway/metrics/references/monorepo.md

@@ -0,0 +1,216 @@
+# Monorepo Reference
+
+Railway supports two types of monorepo deployments with different configuration approaches.
+
+## Key Decision: Root Directory vs Custom Commands
+
+| Approach | When to Use | What Happens |
+|----------|-------------|--------------|
+| **Root Directory** | Isolated apps (no shared code) | Only that directory's code is available |
+| **Custom Commands** | Shared monorepos (TypeScript, workspaces) | Full repo available, filter at build/start |
+
+**Critical:** Setting root directory means code outside that directory is NOT available during build. For monorepos with shared packages, use custom commands instead.
+
+## Isolated Monorepo
+
+Apps are completely independent - no shared code between directories.
+
+```
+├── frontend/        # React app (standalone)
+│   ├── package.json
+│   └── src/
+└── backend/         # Python API (standalone)
+    ├── requirements.txt
+    └── main.py
+```
+
+### Configuration
+
+Set **Root Directory** for each service:
+- Frontend service: `/frontend`
+- Backend service: `/backend`
+
+Each service only sees its own directory's code.
+
+### When to Use
+
+- Frontend and backend in different languages
+- No shared packages or dependencies
+- Each app has its own package.json/requirements.txt
+- Apps don't import from sibling directories
+
+## Shared Monorepo
+
+Apps share code from common packages or the root.
+
+```
+├── package.json           # Root workspace config
+├── packages/
+│   ├── frontend/
+│   │   ├── package.json
+│   │   └── src/
+│   ├── backend/
+│   │   ├── package.json
+│   │   └── src/
+│   └── shared/            # Shared utilities
+│       ├── package.json
+│       └── src/
+└── tsconfig.json          # Shared TS config
+```
+
+### Configuration
+
+Do NOT set root directory. Instead, use custom build and start commands:
+
+**pnpm:**
+```
+Build: pnpm --filter backend build
+Start: pnpm --filter backend start
+```
+
+**npm workspaces:**
+```
+Build: npm run build --workspace=packages/backend
+Start: npm run start --workspace=packages/backend
+```
+
+**yarn workspaces:**
+```
+Build: yarn workspace backend build
+Start: yarn workspace backend start
+```
+
+**bun:**
+```
+Build: bun run --filter backend build
+Start: bun run --filter backend start
+```
+
+**Turborepo:**
+```
+Build: turbo run build --filter=backend
+Start: turbo run start --filter=backend
+```
+
+### When to Use
+
+- TypeScript/JavaScript monorepo with workspaces
+- Packages import from sibling packages (`@myapp/shared`)
+- Shared tsconfig.json, eslint config at root
+- Using pnpm, yarn workspaces, npm workspaces, or bun
+- Using Turborepo, Nx, or similar build tools
+
+## Watch Paths
+
+Prevent changes in one package from triggering rebuilds of other services.
+
+Set watch paths for each service to only rebuild when relevant files change:
+
+| Service | Watch Paths |
+|---------|-------------|
+| frontend | `/packages/frontend/**`, `/packages/shared/**` |
+| backend | `/packages/backend/**`, `/packages/shared/**` |
+
+Include shared packages in watch paths if the service depends on them.
+
+### Pattern Format
+
+Uses gitignore-style patterns:
+```
+/packages/backend/**     # All files in backend
+/packages/shared/**      # All files in shared (if depends on it)
+!**/*.md                 # Ignore markdown changes
+```
+
+## Configuration Examples
+
+### Isolated: React + Python API
+
+Two separate apps, no shared code.
+
+**Frontend service:**
+- Root Directory: `/frontend`
+- No custom commands needed (Railpack auto-detects)
+
+**Backend service:**
+- Root Directory: `/backend`
+- No custom commands needed
+
+### Shared: TypeScript Monorepo with pnpm
+
+Frontend and backend share a `@myapp/shared` package.
+
+**Frontend service:**
+- Root Directory: (leave empty)
+- Build Command: `pnpm --filter frontend build`
+- Start Command: `pnpm --filter frontend start`
+- Watch Paths: `/packages/frontend/**`, `/packages/shared/**`
+
+**Backend service:**
+- Root Directory: (leave empty)
+- Build Command: `pnpm --filter backend build`
+- Start Command: `pnpm --filter backend start`
+- Watch Paths: `/packages/backend/**`, `/packages/shared/**`
+
+### Shared: Turborepo
+
+**Frontend service:**
+- Root Directory: (leave empty)
+- Build Command: `turbo run build --filter=frontend`
+- Start Command: `turbo run start --filter=frontend`
+- Watch Paths: `/apps/frontend/**`, `/packages/**`
+
+**Backend service:**
+- Root Directory: (leave empty)
+- Build Command: `turbo run build --filter=backend`
+- Start Command: `turbo run start --filter=backend`
+- Watch Paths: `/apps/backend/**`, `/packages/**`
+
+## Common Mistakes
+
+### Using Root Directory for Shared Monorepos
+
+**Wrong:**
+```
+Root Directory: /packages/backend
+```
+This breaks builds because `@myapp/shared` isn't available.
+
+**Right:**
+```
+Root Directory: (empty)
+Build Command: pnpm --filter backend build
+Start Command: pnpm --filter backend start
+```
+
+### Forgetting Watch Paths
+
+Without watch paths, changing `frontend/` triggers a rebuild of `backend/`.
+
+Always set watch paths for monorepos to avoid unnecessary builds.
+
+### Missing Shared Packages in Watch Paths
+
+If `backend` imports from `shared`, include both in watch paths:
+```
+/packages/backend/**
+/packages/shared/**
+```
+
+Otherwise changes to `shared` won't trigger backend rebuilds.
+
+## Detecting Monorepo Type
+
+Check for these indicators:
+
+**Isolated monorepo:**
+- Separate package.json in each directory
+- No workspace config in root package.json
+- No imports between directories
+
+**Shared monorepo:**
+- Root package.json with `workspaces` field
+- `pnpm-workspace.yaml` exists
+- Packages import from each other (`@myapp/shared`)
+- Shared tsconfig.json at root
+- turbo.json or nx.json at root