@arthai/agents 1.0.0

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

package/skills/railway/domain/references/monorepo.md

@@ -0,0 +1,216 @@
+# Monorepo Reference
+
+Railway supports two types of monorepo deployments with different configuration approaches.
+
+## Key Decision: Root Directory vs Custom Commands
+
+| Approach | When to Use | What Happens |
+|----------|-------------|--------------|
+| **Root Directory** | Isolated apps (no shared code) | Only that directory's code is available |
+| **Custom Commands** | Shared monorepos (TypeScript, workspaces) | Full repo available, filter at build/start |
+
+**Critical:** Setting root directory means code outside that directory is NOT available during build. For monorepos with shared packages, use custom commands instead.
+
+## Isolated Monorepo
+
+Apps are completely independent - no shared code between directories.
+
+```
+├── frontend/        # React app (standalone)
+│   ├── package.json
+│   └── src/
+└── backend/         # Python API (standalone)
+    ├── requirements.txt
+    └── main.py
+```
+
+### Configuration
+
+Set **Root Directory** for each service:
+- Frontend service: `/frontend`
+- Backend service: `/backend`
+
+Each service only sees its own directory's code.
+
+### When to Use
+
+- Frontend and backend in different languages
+- No shared packages or dependencies
+- Each app has its own package.json/requirements.txt
+- Apps don't import from sibling directories
+
+## Shared Monorepo
+
+Apps share code from common packages or the root.
+
+```
+├── package.json           # Root workspace config
+├── packages/
+│   ├── frontend/
+│   │   ├── package.json
+│   │   └── src/
+│   ├── backend/
+│   │   ├── package.json
+│   │   └── src/
+│   └── shared/            # Shared utilities
+│       ├── package.json
+│       └── src/
+└── tsconfig.json          # Shared TS config
+```
+
+### Configuration
+
+Do NOT set root directory. Instead, use custom build and start commands:
+
+**pnpm:**
+```
+Build: pnpm --filter backend build
+Start: pnpm --filter backend start
+```
+
+**npm workspaces:**
+```
+Build: npm run build --workspace=packages/backend
+Start: npm run start --workspace=packages/backend
+```
+
+**yarn workspaces:**
+```
+Build: yarn workspace backend build
+Start: yarn workspace backend start
+```
+
+**bun:**
+```
+Build: bun run --filter backend build
+Start: bun run --filter backend start
+```
+
+**Turborepo:**
+```
+Build: turbo run build --filter=backend
+Start: turbo run start --filter=backend
+```
+
+### When to Use
+
+- TypeScript/JavaScript monorepo with workspaces
+- Packages import from sibling packages (`@myapp/shared`)
+- Shared tsconfig.json, eslint config at root
+- Using pnpm, yarn workspaces, npm workspaces, or bun
+- Using Turborepo, Nx, or similar build tools
+
+## Watch Paths
+
+Prevent changes in one package from triggering rebuilds of other services.
+
+Set watch paths for each service to only rebuild when relevant files change:
+
+| Service | Watch Paths |
+|---------|-------------|
+| frontend | `/packages/frontend/**`, `/packages/shared/**` |
+| backend | `/packages/backend/**`, `/packages/shared/**` |
+
+Include shared packages in watch paths if the service depends on them.
+
+### Pattern Format
+
+Uses gitignore-style patterns:
+```
+/packages/backend/**     # All files in backend
+/packages/shared/**      # All files in shared (if depends on it)
+!**/*.md                 # Ignore markdown changes
+```
+
+## Configuration Examples
+
+### Isolated: React + Python API
+
+Two separate apps, no shared code.
+
+**Frontend service:**
+- Root Directory: `/frontend`
+- No custom commands needed (Railpack auto-detects)
+
+**Backend service:**
+- Root Directory: `/backend`
+- No custom commands needed
+
+### Shared: TypeScript Monorepo with pnpm
+
+Frontend and backend share a `@myapp/shared` package.
+
+**Frontend service:**
+- Root Directory: (leave empty)
+- Build Command: `pnpm --filter frontend build`
+- Start Command: `pnpm --filter frontend start`
+- Watch Paths: `/packages/frontend/**`, `/packages/shared/**`
+
+**Backend service:**
+- Root Directory: (leave empty)
+- Build Command: `pnpm --filter backend build`
+- Start Command: `pnpm --filter backend start`
+- Watch Paths: `/packages/backend/**`, `/packages/shared/**`
+
+### Shared: Turborepo
+
+**Frontend service:**
+- Root Directory: (leave empty)
+- Build Command: `turbo run build --filter=frontend`
+- Start Command: `turbo run start --filter=frontend`
+- Watch Paths: `/apps/frontend/**`, `/packages/**`
+
+**Backend service:**
+- Root Directory: (leave empty)
+- Build Command: `turbo run build --filter=backend`
+- Start Command: `turbo run start --filter=backend`
+- Watch Paths: `/apps/backend/**`, `/packages/**`
+
+## Common Mistakes
+
+### Using Root Directory for Shared Monorepos
+
+**Wrong:**
+```
+Root Directory: /packages/backend
+```
+This breaks builds because `@myapp/shared` isn't available.
+
+**Right:**
+```
+Root Directory: (empty)
+Build Command: pnpm --filter backend build
+Start Command: pnpm --filter backend start
+```
+
+### Forgetting Watch Paths
+
+Without watch paths, changing `frontend/` triggers a rebuild of `backend/`.
+
+Always set watch paths for monorepos to avoid unnecessary builds.
+
+### Missing Shared Packages in Watch Paths
+
+If `backend` imports from `shared`, include both in watch paths:
+```
+/packages/backend/**
+/packages/shared/**
+```
+
+Otherwise changes to `shared` won't trigger backend rebuilds.
+
+## Detecting Monorepo Type
+
+Check for these indicators:
+
+**Isolated monorepo:**
+- Separate package.json in each directory
+- No workspace config in root package.json
+- No imports between directories
+
+**Shared monorepo:**
+- Root package.json with `workspaces` field
+- `pnpm-workspace.yaml` exists
+- Packages import from each other (`@myapp/shared`)
+- Shared tsconfig.json at root
+- turbo.json or nx.json at root

package/skills/railway/domain/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` |