@arthai/agents 1.0.0

package/skills/railway/status/references/variables.md

@@ -0,0 +1,170 @@
+# Variables Reference
+
+Variables in Railway support references to other services, shared variables, and Railway-provided values.
+
+## Template Syntax
+
+```
+${{NAMESPACE.VAR}}
+```
+
+| Namespace | Description |
+|-----------|-------------|
+| `shared` | Shared variables (project-wide) |
+| `<serviceName>` | Variables from another service (case-sensitive) |
+
+## Examples
+
+**Reference shared variable:**
+```json
+{ "value": "${{shared.DOMAIN}}" }
+```
+
+**Reference another service's variable:**
+```json
+{ "value": "${{api.API_KEY}}" }
+```
+
+**Combine with text:**
+```json
+{ "value": "https://${{shared.DOMAIN}}/api" }
+```
+
+## Railway-Provided Variables
+
+Railway injects these into every service automatically.
+
+### Networking
+| Variable | Description | Example | Availability |
+|----------|-------------|---------|--------------|
+| `RAILWAY_PUBLIC_DOMAIN` | Public domain | `myapp.up.railway.app` | Only if service has a domain |
+| `RAILWAY_PRIVATE_DOMAIN` | Private DNS (internal only) | `myapp.railway.internal` | Always |
+| `RAILWAY_TCP_PROXY_DOMAIN` | TCP proxy domain | `roundhouse.proxy.rlwy.net` | Only if TCP proxy enabled |
+| `RAILWAY_TCP_PROXY_PORT` | TCP proxy port | `11105` | Only if TCP proxy enabled |
+
+**Note:** `RAILWAY_PUBLIC_DOMAIN` is only available if the service has a domain configured.
+Check the service's environment config to verify a domain exists before referencing it.
+
+### Context
+| Variable | Description |
+|----------|-------------|
+| `RAILWAY_PROJECT_ID` | Project ID |
+| `RAILWAY_PROJECT_NAME` | Project name |
+| `RAILWAY_ENVIRONMENT_ID` | Environment ID |
+| `RAILWAY_ENVIRONMENT_NAME` | Environment name |
+| `RAILWAY_SERVICE_ID` | Service ID |
+| `RAILWAY_SERVICE_NAME` | Service name |
+| `RAILWAY_DEPLOYMENT_ID` | Deployment ID |
+| `RAILWAY_REPLICA_ID` | Replica ID |
+| `RAILWAY_REPLICA_REGION` | Region (e.g., `us-west2`) |
+
+### Volume (if attached)
+| Variable | Description |
+|----------|-------------|
+| `RAILWAY_VOLUME_NAME` | Volume name |
+| `RAILWAY_VOLUME_MOUNT_PATH` | Mount path |
+
+### Git (if deployed from GitHub)
+| Variable | Description |
+|----------|-------------|
+| `RAILWAY_GIT_COMMIT_SHA` | Commit SHA |
+| `RAILWAY_GIT_BRANCH` | Branch name |
+| `RAILWAY_GIT_REPO_NAME` | Repository name |
+| `RAILWAY_GIT_REPO_OWNER` | Repository owner |
+| `RAILWAY_GIT_AUTHOR` | Commit author |
+| `RAILWAY_GIT_COMMIT_MESSAGE` | Commit message |
+
+## Wiring Services Together
+
+### Frontend → Backend (public network)
+Use when: Browser makes requests to API (browser can't access private network)
+
+```json
+{
+  "services": {
+    "<frontendId>": {
+      "variables": {
+        "API_URL": { "value": "https://${{backend.RAILWAY_PUBLIC_DOMAIN}}" }
+      }
+    }
+  }
+}
+```
+
+### Service → Database (private network)
+Use when: Backend connects to database (faster, no egress cost, more secure)
+
+Railway databases auto-generate connection URL variables. Use the private versions:
+
+| Database | Variable Reference |
+|----------|-------------------|
+| Postgres | `${{Postgres.DATABASE_URL}}` |
+| MySQL | `${{MySQL.DATABASE_URL}}` |
+| Redis | `${{Redis.REDIS_URL}}` |
+| Mongo | `${{Mongo.MONGO_URL}}` |
+
+**Postgres/MySQL example:**
+```json
+{
+  "services": {
+    "<apiId>": {
+      "variables": {
+        "DATABASE_URL": { "value": "${{Postgres.DATABASE_URL}}" }
+      }
+    }
+  }
+}
+```
+
+**Redis example:**
+```json
+{
+  "services": {
+    "<apiId>": {
+      "variables": {
+        "REDIS_URL": { "value": "${{Redis.REDIS_URL}}" }
+      }
+    }
+  }
+}
+```
+
+**Mongo example:**
+```json
+{
+  "services": {
+    "<apiId>": {
+      "variables": {
+        "MONGO_URL": { "value": "${{Mongo.MONGO_URL}}" }
+      }
+    }
+  }
+}
+```
+
+**Note:** Service names are case-sensitive. Match the exact name from your project (e.g., "Postgres", "Redis").
+
+### Service → Service (private network)
+Use when: Microservices communicate internally
+
+```json
+{
+  "services": {
+    "<workerServiceId>": {
+      "variables": {
+        "API_INTERNAL_URL": { "value": "http://${{api.RAILWAY_PRIVATE_DOMAIN}}:${{api.PORT}}" }
+      }
+    }
+  }
+}
+```
+
+## When to Use Public vs Private
+
+| Use Case | Domain | Reason |
+|----------|--------|--------|
+| Browser → API | Public | Browser can't access private network |
+| Service → Service | Private | Faster, no egress, more secure |
+| Service → Database | Private | Databases should never be public |
+| External webhook → Service | Public | External services need public access |
+| Cron job → API | Private | Internal communication |

package/skills/railway/templates/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: templates
+description: This skill should be used when the user wants to add a service from a template, find templates for a specific use case, or deploy tools like Ghost, Strapi, n8n, Minio, Uptime Kuma, etc. For databases (Postgres, Redis, MySQL, MongoDB), prefer the database skill.
+allowed-tools: Bash(railway:*)
+---
+
+# Templates
+
+Search and deploy services from Railway's template marketplace.
+
+## When to Use
+
+- User asks to "add Postgres", "add Redis", "add a database"
+- User asks to "add Ghost", "add Strapi", "add n8n", or any other service
+- User wants to find templates for a use case (e.g., "CMS", "storage", "monitoring")
+- User asks "what templates are available?"
+- User wants to deploy a pre-configured service
+
+## Common Template Codes
+
+| Category | Template | Code |
+|----------|----------|------|
+| **Databases** | PostgreSQL | `postgres` |
+| | Redis | `redis` |
+| | MySQL | `mysql` |
+| | MongoDB | `mongodb` |
+| **CMS** | Ghost | `ghost` |
+| | Strapi | `strapi` |
+| **Storage** | Minio | `minio` |
+| **Automation** | n8n | `n8n` |
+| **Monitoring** | Uptime Kuma | `uptime-kuma` |
+
+For other templates, use the search query below.
+
+## Prerequisites
+
+Get project context:
+```bash
+railway status --json
+```
+
+Extract:
+- `id` - project ID
+- `environments.edges[0].node.id` - environment ID
+
+Get workspace ID:
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'query getWorkspace($projectId: String!) {
+    project(id: $projectId) { workspaceId }
+  }' \
+  '{"projectId": "PROJECT_ID"}'
+SCRIPT
+```
+
+## Search Templates
+
+List available templates with optional filters:
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'query templates($first: Int, $verified: Boolean) {
+    templates(first: $first, verified: $verified) {
+      edges {
+        node {
+          name
+          code
+          description
+          category
+        }
+      }
+    }
+  }' \
+  '{"first": 20, "verified": true}'
+SCRIPT
+```
+
+### Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `first` | Int | Number of results (max ~100) |
+| `verified` | Boolean | Only verified templates |
+| `recommended` | Boolean | Only recommended templates |
+
+### Rate Limit
+
+10 requests per minute. Don't spam searches.
+
+## Get Template Details
+
+Fetch a specific template by code:
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'query template($code: String!) {
+    template(code: $code) {
+      id
+      name
+      description
+      serializedConfig
+    }
+  }' \
+  '{"code": "postgres"}'
+SCRIPT
+```
+
+Returns:
+- `id` - template ID (needed for deployment)
+- `serializedConfig` - service configuration (needed for deployment)
+
+## Deploy Template
+
+### Step 1: Fetch Template
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'query template($code: String!) {
+    template(code: $code) {
+      id
+      serializedConfig
+    }
+  }' \
+  '{"code": "postgres"}'
+SCRIPT
+```
+
+### Step 2: Deploy to Project
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'mutation deployTemplate($input: TemplateDeployV2Input!) {
+    templateDeployV2(input: $input) {
+      projectId
+      workflowId
+    }
+  }' \
+  '{
+    "input": {
+      "templateId": "TEMPLATE_ID_FROM_STEP_1",
+      "serializedConfig": SERIALIZED_CONFIG_FROM_STEP_1,
+      "projectId": "PROJECT_ID",
+      "environmentId": "ENVIRONMENT_ID",
+      "workspaceId": "WORKSPACE_ID"
+    }
+  }'
+SCRIPT
+```
+
+**Important:** `serializedConfig` is the exact JSON object from the template query, not a string.
+
+## Connecting Services
+
+After deploying a template, connect other services using reference variables.
+
+For complete variable syntax and wiring patterns, see [variables.md](references/variables.md).
+
+### Pattern
+
+```
+${{ServiceName.VARIABLE_NAME}}
+```
+
+### Common Database Variables
+
+| Service | Connection Variable |
+|---------|---------------------|
+| PostgreSQL (Postgres) | `${{Postgres.DATABASE_URL}}` |
+| Redis | `${{Redis.REDIS_URL}}` |
+| MySQL | `${{MySQL.MYSQL_URL}}` |
+| MongoDB | `${{MongoDB.MONGO_URL}}` |
+
+### Backend vs Frontend
+
+**Backend services** can use private URLs (internal network):
+```
+${{Postgres.DATABASE_URL}}
+```
+
+**Frontend applications** run in the browser and cannot access Railway's private network. Options:
+1. Use public URL variables (e.g., `${{MongoDB.MONGO_PUBLIC_URL}}`)
+2. Better: Route through a backend API
+
+## Example: Add PostgreSQL
+
+```bash
+bash <<'SCRIPT'
+# 1. Get context
+railway status --json
+# → project.id = "proj-123", environment.id = "env-456"
+
+# 2. Get workspace ID
+scripts/railway-api.sh \
+  'query { project(id: "proj-123") { workspaceId } }' '{}'
+# → workspaceId = "ws-789"
+
+# 3. Fetch Postgres template
+scripts/railway-api.sh \
+  'query { template(code: "postgres") { id serializedConfig } }' '{}'
+# → id = "template-abc", serializedConfig = {...}
+
+# 4. Deploy
+scripts/railway-api.sh \
+  'mutation deploy($input: TemplateDeployV2Input!) {
+    templateDeployV2(input: $input) { projectId workflowId }
+  }' \
+  '{"input": {
+    "templateId": "template-abc",
+    "serializedConfig": {...},
+    "projectId": "proj-123",
+    "environmentId": "env-456",
+    "workspaceId": "ws-789"
+  }}'
+SCRIPT
+```
+
+## Example: Search for CMS Templates
+
+```bash
+bash <<'SCRIPT'
+# Search verified templates
+scripts/railway-api.sh \
+  'query {
+    templates(first: 50, verified: true) {
+      edges {
+        node { name code description category }
+      }
+    }
+  }' '{}'
+# Filter results for "CMS" category or search descriptions
+SCRIPT
+```
+
+## What Gets Created
+
+Templates typically create:
+- Service with pre-configured image/source
+- Environment variables (connection strings, secrets)
+- Volume for persistent data (databases)
+- TCP proxy for external access (where needed)
+
+## Response
+
+Successful deployment returns:
+```json
+{
+  "data": {
+    "templateDeployV2": {
+      "projectId": "proj-123",
+      "workflowId": "deployTemplate/project/proj-123/xxx"
+    }
+  }
+}
+```
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Template not found | Invalid code | Search templates or check spelling |
+| Rate limit exceeded | Too many searches | Wait 1 minute, then retry |
+| Permission denied | User lacks access | Need DEVELOPER role or higher |
+| Project not found | Invalid project ID | Run `railway status --json` |
+
+## Composability
+
+- **Connect services**: Use `environment` skill to add variable references
+- **View deployed service**: Use `service` skill
+- **Check logs**: Use `deployment` skill
+- **Add domains**: Use `domain` skill

package/skills/railway/templates/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.