@arthai/agents 1.0.0

package/skills/railway/projects/references/railpack.md

@@ -0,0 +1,257 @@
+# Railpack Reference
+
+Railpack is Railway's default builder. Zero-config for most projects.
+
+Full docs: https://railpack.com/llms.txt
+
+## Detection
+
+Railpack analyzes source code to detect language, framework, and build requirements automatically.
+
+Supported: Node, Python, Go, PHP, Java, Ruby, Rust, Elixir, Gleam, Deno, C/C++, static files.
+
+## Static Sites
+
+### Detection Patterns
+
+Railpack serves static files via Caddy when it detects:
+1. `Staticfile` in root (can specify `root: dist`)
+2. `index.html` in root
+3. `public/` directory
+4. `RAILPACK_STATIC_FILE_ROOT` env var set
+
+### Root Directory Priority
+
+1. `RAILPACK_STATIC_FILE_ROOT` env var
+2. `root` in `Staticfile`
+3. `public/` directory
+4. Current directory (if index.html exists)
+
+### Common Patterns
+
+Railpack auto-detects common static build outputs. Only set `RAILPACK_STATIC_FILE_ROOT` for non-standard output directories.
+
+| Framework | Build Output | Config Needed |
+|-----------|--------------|---------------|
+| Plain HTML | root | None (auto-detected) |
+| Vite | dist | None (auto-detected) |
+| Astro (static) | dist | None (auto-detected) |
+| Create React App | build | None (auto-detected) |
+| Angular | dist/<project> | `RAILPACK_STATIC_FILE_ROOT=dist/<project>` (non-standard path) |
+| Custom output | varies | Set if output dir is non-standard |
+
+### Custom Caddyfile
+
+Put a `Caddyfile` in project root to override default serving behavior.
+
+## Node.js
+
+### Detection
+- `package.json` in root
+
+### Version Priority
+1. `RAILPACK_NODE_VERSION` env var
+2. `engines.node` in package.json
+3. `.nvmrc` or `.node-version`
+4. Default: Node 22
+
+### Package Manager Detection
+1. `packageManager` field in package.json (enables Corepack)
+2. Lock file: `pnpm-lock.yaml`, `bun.lockb`, `yarn.lock`
+3. Default: npm
+
+### Build Command
+Auto-detected from package.json `scripts.build`. Override via `buildCommand` in service settings.
+
+### Start Command
+Auto-detected:
+1. `scripts.start` in package.json
+2. `main` field in package.json
+3. `index.js` or `index.ts` in root
+
+Override via `startCommand` in service settings.
+
+### Framework Detection
+
+| Framework | Detection | Notes |
+|-----------|-----------|-------|
+| Next.js | `next` in dependencies | Caches `.next/cache` |
+| Vite | `vite` in devDependencies | Static or SSR mode |
+| Astro | `astro` in dependencies | Caches `.astro` |
+| Nuxt | `nuxt` in dependencies | Auto start command |
+| Remix | `@remix-run/*` in deps | - |
+
+### Static Site Mode (SPA)
+
+For frameworks like Vite, CRA, Astro (static), Angular:
+- Railpack builds then serves via Caddy
+- Set `RAILPACK_SPA_OUTPUT_DIR` if output isn't `dist`
+
+## Python
+
+### Detection
+- `requirements.txt`, `pyproject.toml`, `Pipfile`, or `uv.lock`
+
+### Version Priority
+1. `RAILPACK_PYTHON_VERSION` env var
+2. `.python-version` file
+3. `requires-python` in pyproject.toml
+4. Default: Python 3.12
+
+### WSGI/ASGI Auto-Config
+
+| Framework | Start Command |
+|-----------|---------------|
+| Django | `gunicorn <project>.wsgi` |
+| FastAPI | `uvicorn main:app --host 0.0.0.0` |
+| Flask | `gunicorn app:app` |
+
+Override via `startCommand` in service settings.
+
+## Go
+
+### Detection
+- `go.mod` in root
+
+### Build
+Compiles to binary automatically. For `cmd/` structure, set binary name or use `RAILPACK_GO_BIN`.
+
+## Rust
+
+### Detection
+- `Cargo.toml` in root
+
+### Build
+Release build by default. Binary auto-detected from Cargo.toml.
+
+## Configuration
+
+### Preferred: Service Settings
+
+Use `environment` skill to set:
+- `buildCommand` - Custom build command
+- `startCommand` - Custom start command
+
+These are stored in Railway and don't pollute your codebase.
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `RAILPACK_STATIC_FILE_ROOT` | Static file serving directory |
+| `RAILPACK_SPA_OUTPUT_DIR` | SPA build output (defaults to `dist`) |
+| `RAILPACK_NODE_VERSION` | Node.js version |
+| `RAILPACK_PYTHON_VERSION` | Python version |
+| `RAILPACK_GO_BIN` | Go binary name |
+| `RAILPACK_PACKAGES` | Additional Mise packages (`pkg@version`) |
+| `RAILPACK_BUILD_APT_PACKAGES` | System packages for build |
+| `RAILPACK_DEPLOY_APT_PACKAGES` | System packages for runtime |
+
+### railpack.json
+
+Advanced config for custom build steps:
+
+```json
+{
+  "$schema": "https://schema.railpack.com",
+  "packages": {
+    "ffmpeg": "latest"
+  },
+  "deploy": {
+    "aptPackages": ["libmagic1"]
+  }
+}
+```
+
+### railway.toml
+
+Alternative config format:
+
+```toml
+[build]
+builder = "RAILPACK"
+buildCommand = "npm run build"
+
+[deploy]
+startCommand = "npm start"
+```
+
+## Minimal Project Scaffolding
+
+When no code exists, suggest these patterns:
+
+### Static HTML
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My Site</title>
+</head>
+<body>
+  <h1>Hello Railway</h1>
+</body>
+</html>
+```
+
+### Vite React
+```bash
+npm create vite@latest . -- --template react
+```
+
+### Astro
+```bash
+npm create astro@latest
+```
+
+### Python FastAPI
+```python
+# main.py
+from fastapi import FastAPI
+app = FastAPI()
+
+@app.get("/")
+def root():
+    return {"message": "Hello Railway"}
+```
+
+```txt
+# requirements.txt
+fastapi
+uvicorn
+```
+
+### Go HTTP Server
+```go
+// main.go
+package main
+
+import (
+    "fmt"
+    "net/http"
+    "os"
+)
+
+func main() {
+    port := os.Getenv("PORT")
+    if port == "" {
+        port = "8080"
+    }
+    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+        fmt.Fprintf(w, "Hello Railway")
+    })
+    http.ListenAndServe(":"+port, nil)
+}
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Static site 404s | Check output dir - set `RAILPACK_STATIC_FILE_ROOT` if non-standard |
+| Wrong build command | Use `environment` skill to set `buildCommand` |
+| Wrong start command | Use `environment` skill to set `startCommand` |
+| Missing system package | Add to `RAILPACK_BUILD_APT_PACKAGES` or `RAILPACK_DEPLOY_APT_PACKAGES` |
+| Wrong Node version | Set `RAILPACK_NODE_VERSION` or add `.nvmrc` |
+| Wrong Python version | Set `RAILPACK_PYTHON_VERSION` or add `.python-version` |

package/skills/railway/projects/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/projects/scripts/railway-api.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Railway GraphQL API helper
+# Usage: railway-api.sh '<graphql-query>' ['<variables-json>']
+
+set -e
+
+if ! command -v jq &>/dev/null; then
+  echo '{"error": "jq not installed. Install with: brew install jq"}'
+  exit 1
+fi
+
+CONFIG_FILE="$HOME/.railway/config.json"
+
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo '{"error": "Railway config not found. Run: railway login"}'
+  exit 1
+fi
+
+TOKEN=$(jq -r '.user.token' "$CONFIG_FILE")
+
+if [[ -z "$TOKEN" || "$TOKEN" == "null" ]]; then
+  echo '{"error": "No Railway token found. Run: railway login"}'
+  exit 1
+fi
+
+if [[ -z "$1" ]]; then
+  echo '{"error": "No query provided"}'
+  exit 1
+fi
+
+# Build payload with query and optional variables
+if [[ -n "$2" ]]; then
+  PAYLOAD=$(jq -n --arg q "$1" --argjson v "$2" '{query: $q, variables: $v}')
+else
+  PAYLOAD=$(jq -n --arg q "$1" '{query: $q}')
+fi
+
+curl -s https://backboard.railway.com/graphql/v2 \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD"

package/skills/railway/railway-docs/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: railway-docs
+description: This skill should be used when the user asks about Railway features, how Railway works, or shares a docs.railway.com URL. Fetches up-to-date Railway docs to answer accurately.
+---
+
+# Railway Docs
+
+Fetch up-to-date Railway documentation to answer questions accurately.
+
+## When to Use
+
+- User asks how something works on Railway (projects, deployments, volumes, etc.)
+- User shares a docs.railway.com URL
+- User needs current info about Railway features or pricing
+- Before answering Railway questions from memory - check the docs first
+
+## LLM-Optimized Sources
+
+Start here for comprehensive, up-to-date info:
+
+| Source             | URL                                         |
+| ------------------ | ------------------------------------------- |
+| **Full docs**      | `https://docs.railway.com/api/llms-docs.md` |
+| **llms.txt index** | `https://railway.com/llms.txt`              |
+| **Templates**      | `https://railway.com/llms-templates.md`     |
+| **Changelog**      | `https://railway.com/llms-changelog.md`     |
+| **Blog**           | `https://blog.railway.com/llms-blog.md`     |
+
+## Fetching Specific Pages
+
+Append `.md` to any docs.railway.com URL:
+
+```
+https://docs.railway.com/guides/projects
+→ https://docs.railway.com/guides/projects.md
+```
+
+## Common Doc Paths
+
+| Topic       | URL                                              |
+| ----------- | ------------------------------------------------ |
+| Projects    | `https://docs.railway.com/guides/projects.md`    |
+| Deployments | `https://docs.railway.com/guides/deployments.md` |
+| Volumes     | `https://docs.railway.com/guides/volumes.md`     |
+| Variables   | `https://docs.railway.com/guides/variables.md`   |
+| CLI         | `https://docs.railway.com/reference/cli-api.md`  |
+| Pricing     | `https://docs.railway.com/reference/pricing.md`  |

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