@arthai/agents 1.0.0

package/skills/railway/deployment/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: deployment
+description: This skill should be used when the user wants to manage Railway deployments, view logs, or debug issues. Covers deployment lifecycle (remove, stop, redeploy, restart), deployment visibility (list, status, history), and troubleshooting (logs, errors, failures, crashes, why deploy failed). NOT for deleting services - use environment skill with isDeleted for that.
+allowed-tools: Bash(railway:*)
+---
+
+# Deployment Management
+
+Manage existing Railway deployments: list, view logs, redeploy, or remove.
+
+**Important:** "Remove deployment" (`railway down`) stops the current deployment but keeps the service. To delete a service entirely, use the `environment` skill with `isDeleted: true`.
+
+## When to Use
+
+- User says "remove deploy", "take down service", "stop deployment", "railway down"
+- User wants to "redeploy", "restart the service", "restart deployment"
+- User asks to "list deployments", "show deployment history", "deployment status"
+- User asks to "see logs", "show logs", "check errors", "debug issues"
+
+## List Deployments
+
+```bash
+railway deployment list --limit 10 --json
+```
+
+Shows deployment IDs, statuses, and metadata. Use to find specific deployment IDs for logs or debugging.
+
+### Specify Service
+
+```bash
+railway deployment list --service backend --limit 10 --json
+```
+
+## View Logs
+
+### Deploy Logs
+
+```bash
+railway logs --lines 100 --json
+```
+
+In non-interactive mode, streaming is auto-disabled and CLI fetches logs then exits.
+
+### Build Logs
+
+```bash
+railway logs --build --lines 100 --json
+```
+
+For debugging build failures or viewing build output.
+
+### Logs for Failed/In-Progress Deployments
+
+By default `railway logs` shows the last successful deployment. Use `--latest` for current:
+
+```bash
+railway logs --latest --lines 100 --json
+```
+
+### Filter Logs
+
+```bash
+# Errors only
+railway logs --lines 50 --filter "@level:error" --json
+
+# Text search
+railway logs --lines 50 --filter "connection refused" --json
+
+# Combined
+railway logs --lines 50 --filter "@level:error AND timeout" --json
+```
+
+### Time-Based Filtering
+
+```bash
+# Logs from last hour
+railway logs --since 1h --lines 100 --json
+
+# Logs between 30 and 10 minutes ago
+railway logs --since 30m --until 10m --lines 100 --json
+
+# Logs from specific timestamp
+railway logs --since 2024-01-15T10:00:00Z --lines 100 --json
+```
+
+Formats: relative (`30s`, `5m`, `2h`, `1d`, `1w`) or ISO 8601 timestamps.
+
+### Logs from Specific Deployment
+
+Deploy logs:
+```bash
+railway logs <deployment-id> --lines 100 --json
+```
+
+Build logs:
+```bash
+railway logs --build <deployment-id> --lines 100 --json
+```
+
+Get deployment ID from `railway deployment list`.
+
+**Note:** The deployment ID is a positional argument, NOT `--deployment <id>`. The `--deployment` flag is a boolean that selects deploy logs (vs `--build` for build logs).
+
+## Redeploy
+
+Redeploy the most recent deployment:
+
+```bash
+railway redeploy --service <name> -y
+```
+
+The `-y` flag skips confirmation. Useful when:
+- Config changed via environment skill
+- Need to restart without new code
+- Previous deploy succeeded but service misbehaving
+
+### Restart Container Only
+
+Restart without rebuilding (picks up external resource changes):
+
+```bash
+railway restart --service <name> -y
+```
+
+Use when external resources (S3 files, config maps) changed but code didn't.
+
+## Remove Deployment
+
+Takes down the current deployment. The service remains but has no running deployment.
+
+```bash
+# Remove deployment for linked service
+railway down -y
+
+# Remove deployment for specific service
+railway down --service web -y
+railway down --service api -y
+```
+
+This is what users mean when they say "remove deploy", "take down", or "stop the deployment".
+
+**Note:** This does NOT delete the service. To delete a service entirely, use the `environment` skill with `isDeleted: true`.
+
+## CLI Options
+
+### deployment list
+
+| Flag | Description |
+|------|-------------|
+| `-s, --service <NAME>` | Service name or ID |
+| `-e, --environment <NAME>` | Environment name or ID |
+| `--limit <N>` | Max deployments (default 20, max 1000) |
+| `--json` | JSON output |
+
+### logs
+
+| Flag | Description |
+|------|-------------|
+| `-s, --service <NAME>` | Service name or ID |
+| `-e, --environment <NAME>` | Environment name or ID |
+| `-d, --deployment` | Show deploy logs (default, boolean flag) |
+| `-b, --build` | Show build logs (boolean flag) |
+| `-n, --lines <N>` | Number of lines (required) |
+| `-f, --filter <QUERY>` | Filter using query syntax |
+| `--since <TIME>` | Start time (relative or ISO 8601) |
+| `--until <TIME>` | End time (relative or ISO 8601) |
+| `--latest` | Most recent deployment (even if failed) |
+| `--json` | JSON output |
+| `[DEPLOYMENT_ID]` | Specific deployment (optional) |
+
+### redeploy
+
+| Flag | Description |
+|------|-------------|
+| `-s, --service <NAME>` | Service name or ID |
+| `-y, --yes` | Skip confirmation |
+
+### restart
+
+| Flag | Description |
+|------|-------------|
+| `-s, --service <NAME>` | Service name or ID |
+| `-y, --yes` | Skip confirmation |
+
+### down
+
+| Flag | Description |
+|------|-------------|
+| `-s, --service <NAME>` | Service name or ID |
+| `-e, --environment <NAME>` | Environment name or ID |
+| `-y, --yes` | Skip confirmation |
+
+## Presenting Logs
+
+When showing logs:
+- Include timestamps
+- Highlight errors and warnings
+- For build failures: show error and suggest fixes
+- For runtime crashes: show stack trace context
+- Summarize patterns (e.g., "15 timeout errors in last 100 logs")
+
+## Composability
+
+- **Push new code**: Use `deploy` skill
+- **Check service status**: Use `status` skill
+- **Fix config issues**: Use `environment` skill
+- **Create new service**: Use `new` skill
+
+## Error Handling
+
+### No Service Linked
+```
+No service linked. Run `railway service` to select one.
+```
+
+### No Deployments Found
+```
+No deployments found. Deploy first with `railway up`.
+```
+
+### No Logs Found
+Deployment may be too old (log retention limits) or service hasn't produced output.

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