@arthai/agents 1.0.0

package/skills/railway/central-station/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/central-station/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/database/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: database
+description: This skill should be used when the user wants to add a database (Postgres, Redis, MySQL, MongoDB), says "add postgres", "add redis", "add database", "connect to database", or "wire up the database". For other templates (Ghost, Strapi, n8n, etc.), use the templates skill.
+allowed-tools: Bash(railway:*)
+---
+
+# Database
+
+Add official Railway database services. These are maintained templates with pre-configured volumes, networking, and connection variables.
+
+For non-database templates, see the `templates` skill.
+
+## When to Use
+
+- User asks to "add a database", "add Postgres", "add Redis", etc.
+- User needs a database for their application
+- User asks about connecting to a database
+- User says "add postgres and connect to my server"
+- User says "wire up the database"
+
+## Decision Flow
+
+**ALWAYS check for existing databases FIRST before creating.**
+
+```
+User mentions database
+        │
+  Check existing DBs first
+  (query env config for source.image)
+        │
+   ┌────┴────┐
+ Exists    Doesn't exist
+    │           │
+    │      Create database
+    │      (CLI or API)
+    │           │
+    │      Wait for deployment
+    │           │
+    └─────┬─────┘
+          │
+    User wants to
+    connect service?
+          │
+    ┌─────┴─────┐
+   Yes         No
+    │           │
+Wire vars    Done +
+via env     suggest wiring
+skill
+```
+
+## Check for Existing Databases
+
+Before creating a database, check if one already exists.
+
+For full environment config structure, see [environment-config.md](references/environment-config.md).
+
+```bash
+railway status --json
+```
+
+Then query environment config and check `source.image` for each service:
+
+```graphql
+query environmentConfig($environmentId: String!) {
+  environment(id: $environmentId) {
+    config(decryptVariables: false)
+  }
+}
+```
+
+The `config.services` object contains each service's configuration. Check `source.image` for:
+
+- `ghcr.io/railway/postgres*` or `postgres:*` → Postgres
+- `ghcr.io/railway/redis*` or `redis:*` → Redis
+- `ghcr.io/railway/mysql*` or `mysql:*` → MySQL
+- `ghcr.io/railway/mongo*` or `mongo:*` → MongoDB
+
+## Available Databases
+
+| Database | Template Code |
+|----------|---------------|
+| PostgreSQL | `postgres` |
+| Redis | `redis` |
+| MySQL | `mysql` |
+| MongoDB | `mongodb` |
+
+## Prerequisites
+
+Get project context:
+```bash
+railway status --json
+```
+
+Extract:
+- `id` - project ID
+- `environments.edges[0].node.id` - environment ID
+
+Get workspace ID (not in status output):
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'query getWorkspace($projectId: String!) {
+    project(id: $projectId) { workspaceId }
+  }' \
+  '{"projectId": "PROJECT_ID"}'
+SCRIPT
+```
+
+## Adding a Database
+
+### Step 1: Fetch Template
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'query template($code: String!) {
+    template(code: $code) {
+      id
+      name
+      serializedConfig
+    }
+  }' \
+  '{"code": "postgres"}'
+SCRIPT
+```
+
+This returns the template's `id` and `serializedConfig` needed for deployment.
+
+### Step 2: Deploy Template
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'mutation deployTemplate($input: TemplateDeployV2Input!) {
+    templateDeployV2(input: $input) {
+      projectId
+      workflowId
+    }
+  }' \
+  '{
+    "input": {
+      "templateId": "TEMPLATE_ID",
+      "serializedConfig": SERIALIZED_CONFIG,
+      "projectId": "PROJECT_ID",
+      "environmentId": "ENVIRONMENT_ID",
+      "workspaceId": "WORKSPACE_ID"
+    }
+  }'
+SCRIPT
+```
+
+**Important:** `serializedConfig` is the exact object from the template query, not a string.
+
+## Connecting to the Database
+
+After deployment, other services connect using reference variables.
+
+For complete variable reference syntax and wiring patterns, see [variables.md](references/variables.md).
+
+### Backend Services (Server-side)
+
+Use the private/internal URL for server-to-server communication:
+
+| Database | Variable Reference |
+|----------|-------------------|
+| PostgreSQL | `${{Postgres.DATABASE_URL}}` |
+| Redis | `${{Redis.REDIS_URL}}` |
+| MySQL | `${{MySQL.MYSQL_URL}}` |
+| MongoDB | `${{MongoDB.MONGO_URL}}` |
+
+### Frontend Applications
+
+**Important:** Frontends run in the user's browser and cannot access Railway's private network. They must use public URLs or go through a backend API.
+
+For direct database access from frontend (not recommended):
+- Use the public URL variables (e.g., `${{MongoDB.MONGO_PUBLIC_URL}}`)
+- Requires TCP proxy to be enabled
+
+Better pattern: Frontend → Backend API → Database
+
+## Example: Add PostgreSQL
+
+```bash
+bash <<'SCRIPT'
+# 1. Get context
+railway status --json
+# Extract project.id and environment.id
+
+# 2. Get workspace ID
+scripts/railway-api.sh \
+  'query { project(id: "proj-id") { workspaceId } }' '{}'
+
+# 3. Fetch Postgres template
+scripts/railway-api.sh \
+  'query { template(code: "postgres") { id serializedConfig } }' '{}'
+
+# 4. Deploy template
+scripts/railway-api.sh \
+  'mutation deploy($input: TemplateDeployV2Input!) {
+    templateDeployV2(input: $input) { projectId workflowId }
+  }' \
+  '{"input": {"templateId": "...", "serializedConfig": {...}, "projectId": "...", "environmentId": "...", "workspaceId": "..."}}'
+SCRIPT
+```
+
+### Then Connect From Another Service
+
+Use `environment` skill to add the variable reference:
+
+```json
+{
+  "services": {
+    "<backend-service-id>": {
+      "variables": {
+        "DATABASE_URL": { "value": "${{Postgres.DATABASE_URL}}" }
+      }
+    }
+  }
+}
+```
+
+## Response
+
+Successful deployment returns:
+```json
+{
+  "data": {
+    "templateDeployV2": {
+      "projectId": "e63baedb-e308-49e9-8c06-c25336f861c7",
+      "workflowId": "deployTemplate/project/e63baedb-e308-49e9-8c06-c25336f861c7/xxx"
+    }
+  }
+}
+```
+
+## What Gets Created
+
+Each database template creates:
+- A service with the database image
+- A volume for data persistence
+- Environment variables for connection strings
+- TCP proxy for external access (where applicable)
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Template not found | Invalid template code | Use: `postgres`, `redis`, `mysql`, `mongodb` |
+| Permission denied | User lacks access | Need DEVELOPER role or higher |
+| Project not found | Invalid project ID | Run `railway status --json` for correct ID |
+
+## Example Workflows
+
+### "add postgres and connect to the server"
+
+1. Check existing DBs via env config query
+2. If postgres exists: Skip to step 5
+3. If not exists: Deploy postgres template (fetch template → deploy)
+4. Wait for deployment to complete
+5. Identify target service (ask if multiple, or use linked service)
+6. Use `environment` skill to stage: `DATABASE_URL: { "value": "${{Postgres.DATABASE_URL}}" }`
+7. Apply changes
+
+### "add postgres"
+
+1. Check existing DBs via env config query
+2. If exists: "Postgres already exists in this project"
+3. If not exists: Deploy postgres template
+4. Inform user: "Postgres created. Connect a service with: `DATABASE_URL=${{Postgres.DATABASE_URL}}`"
+
+### "connect the server to redis"
+
+1. Check existing DBs via env config query
+2. If redis exists: Wire up REDIS_URL via environment skill → apply
+3. If no redis: Ask "No Redis found. Create one?"
+   - Deploy redis template
+   - Wire REDIS_URL → apply
+
+## Composability
+
+- **Connect services**: Use `environment` skill to add variable references
+- **View database service**: Use `service` skill
+- **Check logs**: Use `deployment` skill