@arthai/agents 1.0.0

package/skills/railway/service/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: service
+description: This skill should be used when the user asks about service status, wants to rename a service, change service icons, link services, or create services with Docker images. For creating services with local code, prefer the `new` skill. For GitHub repo sources, use `new` skill to create empty service then `environment` skill to configure source.
+allowed-tools: Bash(railway:*)
+---
+
+# Service Management
+
+Check status, update properties, and advanced service creation.
+
+## When to Use
+
+- User asks about service status, health, or deployments
+- User asks "is my service deployed?"
+- User wants to rename a service or change service icon
+- User wants to link a different service
+- User wants to deploy a Docker image as a new service (advanced)
+
+**Note:** For creating services with local code (the common case), prefer the `new` skill which handles project setup, scaffolding, and service creation together.
+
+**For GitHub repo sources:** Use `new` skill to create empty service, then `environment` skill to configure source.repo via staged changes API.
+
+## Create Service
+
+Create a new service via GraphQL API. There is no CLI command for this.
+
+### Get Context
+
+```bash
+railway status --json
+```
+
+Extract:
+- `project.id` - for creating the service
+- `environment.id` - for staging the instance config
+
+### Create Service Mutation
+
+```graphql
+mutation serviceCreate($input: ServiceCreateInput!) {
+  serviceCreate(input: $input) {
+    id
+    name
+  }
+}
+```
+
+### ServiceCreateInput Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `projectId` | String! | Project ID (required) |
+| `name` | String | Service name (auto-generated if omitted) |
+| `source.image` | String | Docker image (e.g., `nginx:latest`) |
+| `source.repo` | String | GitHub repo (e.g., `user/repo`) |
+| `branch` | String | Git branch for repo source |
+| `environmentId` | String | If set and is a fork, only creates in that env |
+
+### Example: Create empty service
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'mutation createService($input: ServiceCreateInput!) {
+    serviceCreate(input: $input) { id name }
+  }' \
+  '{"input": {"projectId": "PROJECT_ID"}}'
+SCRIPT
+```
+
+### Example: Create service with image
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'mutation createService($input: ServiceCreateInput!) {
+    serviceCreate(input: $input) { id name }
+  }' \
+  '{"input": {"projectId": "PROJECT_ID", "name": "my-service", "source": {"image": "nginx:latest"}}}'
+SCRIPT
+```
+
+### Connecting a GitHub Repo
+
+**Do NOT use serviceCreate with source.repo** - use staged changes API instead.
+
+Flow:
+1. Create empty service: `serviceCreate(input: {projectId: "...", name: "my-service"})`
+2. Use `environment` skill to configure source via staged changes API
+3. Apply to trigger deployment
+
+### After Creating: Configure Instance
+
+Use `environment` skill to configure the service instance:
+
+```json
+{
+  "services": {
+    "<serviceId>": {
+      "isCreated": true,
+      "source": { "image": "nginx:latest" },
+      "variables": {
+        "PORT": { "value": "8080" }
+      }
+    }
+  }
+}
+```
+
+**Critical:** Always include `isCreated: true` for new service instances.
+
+Then use `environment` skill to apply and deploy.
+
+For variable references, see [reference/variables.md](references/variables.md).
+
+## Check Service Status
+
+```bash
+railway service status --json
+```
+
+Returns current deployment status for the linked service.
+
+### Deployment History
+
+```bash
+railway deployment list --json --limit 5
+```
+
+### Present Status
+
+Show:
+- **Service**: name and current status
+- **Latest Deployment**: status (SUCCESS, FAILED, DEPLOYING, CRASHED, etc.)
+- **Deployed At**: when the current deployment went live
+- **Recent Deployments**: last 3-5 with status and timestamps
+
+### Deployment Statuses
+
+| Status | Meaning |
+|--------|---------|
+| SUCCESS | Deployed and running |
+| FAILED | Build or deploy failed |
+| DEPLOYING | Currently deploying |
+| BUILDING | Build in progress |
+| CRASHED | Runtime crash |
+| REMOVED | Deployment removed |
+
+## Update Service
+
+Update service name or icon via GraphQL API.
+
+### Get Service ID
+
+```bash
+railway status --json
+```
+
+Extract `service.id` from the response.
+
+### Update Name
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
+    serviceUpdate(id: $id, input: $input) { id name }
+  }' \
+  '{"id": "SERVICE_ID", "input": {"name": "new-name"}}'
+SCRIPT
+```
+
+### Update Icon
+
+Icons can be image URLs or animated GIFs.
+
+| Type | Example |
+|------|---------|
+| Image URL | `"icon": "https://example.com/logo.png"` |
+| Animated GIF | `"icon": "https://example.com/animated.gif"` |
+| Devicons | `"icon": "https://devicons.railway.app/github"` |
+
+**Railway Devicons:** Query `https://devicons.railway.app/{query}` for common developer icons (e.g., `github`, `postgres`, `redis`, `nodejs`). Browse all at https://devicons.railway.app
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
+    serviceUpdate(id: $id, input: $input) { id icon }
+  }' \
+  '{"id": "SERVICE_ID", "input": {"icon": "https://devicons.railway.app/github"}}'
+SCRIPT
+```
+
+### ServiceUpdateInput Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | String | Service name |
+| `icon` | String | Emoji or image URL (including animated GIFs) |
+
+## Link Service
+
+Switch the linked service for the current directory:
+
+```bash
+railway service link
+```
+
+Or specify directly:
+
+```bash
+railway service link <service-name>
+```
+
+## Composability
+
+- **Create service with local code**: Use `new` skill (handles scaffolding + creation)
+- **Configure service**: Use `environment` skill (variables, commands, image, etc.)
+- **Delete service**: Use `environment` skill with `isDeleted: true`
+- **Apply changes**: Use `environment` skill
+- **View logs**: Use `deployment` skill
+- **Deploy local code**: Use `deploy` skill
+
+## Error Handling
+
+### No Service Linked
+```
+No service linked. Run `railway service link` to link a service.
+```
+
+### No Deployments
+```
+Service exists but has no deployments yet. Deploy with `railway up`.
+```
+
+### Service Not Found
+```
+Service "foo" not found. Check available services with `railway status`.
+```
+
+### Project Not Found
+User may not be in a linked project. Check `railway status`.
+
+### Permission Denied
+User needs at least DEVELOPER role to create services.
+
+### Invalid Image
+Docker image must be accessible (public or with registry credentials).

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