@arthai/agents 1.0.0

package/skills/railway/service/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/service/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/service/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/status/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: status
+description: This skill should be used when the user asks "railway status", "is it running", "what's deployed", "deployment status", or about uptime. NOT for variables ("what variables", "env vars", "add variable") or configuration queries - use environment skill for those.
+allowed-tools: Bash(railway:*), Bash(which:*), Bash(command:*)
+---
+
+# Railway Status
+
+Check the current Railway project status for this directory.
+
+## When to Use
+
+- User asks about Railway status, project, services, or deployments
+- User mentions deploying or pushing to Railway
+- Before any Railway operation (deploy, update service, add variables)
+- User asks about environments or domains
+
+## When NOT to Use
+
+Use the `environment` skill instead when user wants:
+- Detailed service configuration (builder type, dockerfile path, build command, root directory)
+- Deploy config (start command, restart policy, healthchecks, predeploy command)
+- Service source (repo, branch, image)
+- Compare service configs
+- Query or change environment variables
+
+## Check Status
+
+Run:
+```bash
+railway status --json
+```
+
+First verify CLI is installed:
+```bash
+command -v railway
+```
+
+## Handling Errors
+
+### CLI Not Installed
+If `command -v railway` fails:
+
+> Railway CLI is not installed. Install with:
+> ```
+> npm install -g @railway/cli
+> ```
+> or
+> ```
+> brew install railway
+> ```
+> Then authenticate: `railway login`
+
+### Not Authenticated
+If `railway whoami` fails:
+
+> Not logged in to Railway. Run:
+> ```
+> railway login
+> ```
+
+### No Project Linked
+If status returns "No linked project":
+
+> No Railway project linked to this directory.
+>
+> To link an existing project: `railway link`
+> To create a new project: `railway init`
+
+## Presenting Status
+
+Parse the JSON and present:
+- **Project**: name and workspace
+- **Environment**: current environment (production, staging, etc.)
+- **Services**: list with deployment status
+- **Active Deployments**: any in-progress deployments (from `activeDeployments` field)
+- **Domains**: any configured domains
+
+Example output format:
+```
+Project: my-app (workspace: my-team)
+Environment: production
+
+Services:
+- web: deployed (https://my-app.up.railway.app)
+- api: deploying (build in progress)
+- postgres: running
+```
+
+The `activeDeployments` array on each service shows currently running deployments
+with their status (building, deploying, etc.).