@arthai/agents 1.0.0

package/skills/railway/domain/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/environment/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: environment
+description: This skill should be used when the user asks "what's the config", "show me the configuration", "what variables are set", "environment config", "service config", "railway config", or wants to add/set/delete variables, change build/deploy settings, scale replicas, connect repos, or delete services.
+allowed-tools: Bash(railway:*)
+---
+
+# Environment Configuration
+
+Read and edit Railway environment configuration using the CLI.
+
+## Prerequisites
+
+Requires Railway CLI **v4.27.3+**. Check with:
+```bash
+railway --version
+```
+
+If below 4.27.3, upgrade:
+```bash
+railway upgrade
+```
+
+## Quick Actions
+
+**When user asks "what's the config" or "show configuration":**
+
+```bash
+railway environment config --json
+```
+
+Present: source (repo/image), build settings, deploy settings, variables per service.
+
+**When user asks "what variables" or "show env vars":**
+
+Same command — `railway environment config --json` includes variables per service and shared variables.
+
+For **rendered** (resolved) variable values: `railway variables --json`
+
+## When to Use
+
+- User wants to create a new environment
+- User wants to duplicate an environment (e.g., "copy production to staging")
+- User wants to switch to a different environment
+- User asks about current build/deploy settings, variables, replicas, health checks, domains
+- User asks to change service source (Docker image, branch, commit, root directory)
+- User wants to connect a service to a GitHub repo
+- User wants to deploy from a GitHub repo (create empty service first via `new` skill, then use this)
+- User asks to change build or start command
+- User wants to add/update/delete environment variables
+- User wants to change replica count or configure health checks
+- User asks to delete a service, volume, or bucket
+- Auto-fixing build errors detected in logs
+
+## Create Environment
+
+Create a new environment in the linked project:
+
+```bash
+railway environment new <name>
+```
+
+Duplicate an existing environment:
+
+```bash
+railway environment new staging --duplicate production
+```
+
+With service-specific variables:
+
+```bash
+railway environment new staging --duplicate production --service-variable api PORT=3001
+```
+
+## Switch Environment
+
+Link a different environment to the current directory:
+
+```bash
+railway environment <name>
+```
+
+Or by ID:
+
+```bash
+railway environment <environment-id>
+```
+
+## Get Context
+
+**JSON output** — project/environment IDs and service list:
+```bash
+railway status --json
+```
+
+Extract:
+- `project.id` — project ID
+- `environment.id` — environment ID
+
+**Plain output** — linked service name:
+```bash
+railway status
+```
+
+Shows `Service: <name>` line with the currently linked service.
+
+### Resolve Service ID
+
+Get service IDs from the environment config:
+```bash
+railway environment config --json | jq '.services | keys'
+```
+
+Map service IDs to names via status:
+```bash
+railway status --json
+```
+
+The `project.services` array contains `{ id, name }` for each service. Match against the service keys from `environment config`.
+
+## Read Configuration
+
+Fetch current environment configuration:
+
+```bash
+railway environment config --json
+```
+
+### Response Structure
+
+```json
+{
+  "services": {
+    "<serviceId>": {
+      "source": { "repo": "...", "branch": "main" },
+      "build": { "buildCommand": "npm run build", "builder": "NIXPACKS" },
+      "deploy": {
+        "startCommand": "npm start",
+        "multiRegionConfig": { "us-west2": { "numReplicas": 1 } }
+      },
+      "variables": { "NODE_ENV": { "value": "production" } },
+      "networking": { "serviceDomains": {}, "customDomains": {} }
+    }
+  },
+  "sharedVariables": { "DATABASE_URL": { "value": "..." } }
+}
+```
+
+For complete field reference, see [reference/environment-config.md](references/environment-config.md).
+
+For variable syntax and service wiring patterns, see [reference/variables.md](references/variables.md).
+
+## Get Rendered Variables
+
+`environment config` returns **unrendered** variables — template syntax like `${{shared.DOMAIN}}` is preserved. This is correct for management/editing.
+
+To see **rendered** (resolved) values as they appear at runtime:
+
+```bash
+# Current linked service
+railway variables --json
+
+# Specific service
+railway variables --service <service-name> --json
+```
+
+**When to use:**
+- Debugging connection issues (see actual URLs/ports)
+- Verifying variable resolution is correct
+- Viewing Railway-injected values (RAILWAY_*)
+
+## Edit Configuration
+
+Pass a JSON patch to `railway environment edit` to apply changes. The patch is merged with existing config and committed immediately, triggering deploys.
+
+```bash
+railway environment edit --json <<< '<json-patch>'
+```
+
+With a commit message:
+
+```bash
+railway environment edit -m "description of change" --json <<< '<json-patch>'
+```
+
+### Examples
+
+**Set build command:**
+```bash
+railway environment edit --json <<< '{"services":{"SERVICE_ID":{"build":{"buildCommand":"npm run build"}}}}'
+```
+
+**Add variable:**
+```bash
+railway environment edit -m "add API_KEY" --json <<< '{"services":{"SERVICE_ID":{"variables":{"API_KEY":{"value":"secret"}}}}}'
+```
+
+**Delete variable:**
+```bash
+railway environment edit --json <<< '{"services":{"SERVICE_ID":{"variables":{"OLD_VAR":null}}}}'
+```
+
+**Delete service:**
+```bash
+railway environment edit --json <<< '{"services":{"SERVICE_ID":{"isDeleted":true}}}'
+```
+
+**Set replicas:**
+```bash
+railway environment edit --json <<< '{"services":{"SERVICE_ID":{"deploy":{"multiRegionConfig":{"us-west2":{"numReplicas":3}}}}}}'
+```
+
+**Add shared variable:**
+```bash
+railway environment edit --json <<< '{"sharedVariables":{"DATABASE_URL":{"value":"postgres://..."}}}'
+```
+
+### Batching Multiple Changes
+
+Include multiple fields in a single patch to apply them atomically:
+
+```bash
+railway environment edit -m "configure build, start, and env" --json <<< '{"services":{"SERVICE_ID":{"build":{"buildCommand":"npm run build"},"deploy":{"startCommand":"npm start"},"variables":{"NODE_ENV":{"value":"production"}}}}}'
+```
+
+## Error Handling
+
+### Command Not Found
+
+If `railway environment edit` is not recognized, upgrade the CLI:
+
+```bash
+railway upgrade
+```
+
+### Service Not Found
+
+```
+Service "foo" not found in project. Available services: api, web, worker
+```
+
+### Invalid Configuration
+
+Common issues:
+
+- `buildCommand` and `startCommand` cannot be identical
+- `buildCommand` only valid with NIXPACKS builder
+- `dockerfilePath` only valid with DOCKERFILE builder
+
+### No Permission
+
+```
+You don't have permission to modify this environment. Check your Railway role.
+```
+
+### No Linked Project
+
+```
+No project linked. Run `railway link` to link a project.
+```
+
+## Composability
+
+- **Create service**: Use `service` skill
+- **View logs**: Use `deployment` skill
+- **Add domains**: Use `domain` skill
+- **Deploy local code**: Use `deploy` skill

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