gigaclaw 1.4.0

package/templates/.github/workflows/run-job.yml

@@ -0,0 +1,89 @@
+name: Agent Job
+
+on:
+  create:
+
+jobs:
+  run-agent:
+    runs-on: ${{ vars.RUNS_ON || 'ubuntu-latest' }}
+    if: github.ref_type == 'branch' && startsWith(github.ref_name, 'job/')
+    permissions:
+      contents: write
+      packages: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+          sparse-checkout: |
+            package-lock.json
+            logs/*/job.config.json
+          sparse-checkout-cone-mode: false
+
+      - name: Get gigaclaw version
+        id: version
+        run: |
+          VERSION=$(jq -r '.packages["node_modules/gigaclaw"].version // "latest"' package-lock.json)
+          echo "tag=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Read job config overrides
+        id: job-config
+        run: |
+          JOB_ID="${{ github.ref_name }}"
+          JOB_ID="${JOB_ID#job/}"
+          CONFIG_FILE="logs/${JOB_ID}/job.config.json"
+          if [ -f "$CONFIG_FILE" ]; then
+            echo "llm_provider=$(jq -r '.llm_provider // empty' "$CONFIG_FILE")" >> $GITHUB_OUTPUT
+            echo "llm_model=$(jq -r '.llm_model // empty' "$CONFIG_FILE")" >> $GITHUB_OUTPUT
+            echo "agent_backend=$(jq -r '.agent_backend // empty' "$CONFIG_FILE")" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Login to GHCR
+        if: startsWith(vars.JOB_IMAGE_URL, 'ghcr.io/')
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run gigaclaw Agent
+        env:
+          ALL_SECRETS: ${{ toJson(secrets) }}
+          JOB_IMAGE_URL: ${{ vars.JOB_IMAGE_URL }}
+          GIGACLAW_VERSION: ${{ steps.version.outputs.tag }}
+          LLM_MODEL: ${{ steps.job-config.outputs.llm_model || vars.LLM_MODEL }}
+          LLM_PROVIDER: ${{ steps.job-config.outputs.llm_provider || vars.LLM_PROVIDER }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          AGENT_BACKEND: ${{ steps.job-config.outputs.agent_backend || vars.AGENT_BACKEND || '' }}
+        run: |
+          AGENT_BACKEND="${AGENT_BACKEND:-pi}"
+          if [ -n "$JOB_IMAGE_URL" ]; then
+            IMAGE="${JOB_IMAGE_URL}:latest"
+          elif [ "$AGENT_BACKEND" = "claude-code" ]; then
+            IMAGE="gignaati/gigaclaw:claude-code-job-${GIGACLAW_VERSION}"
+          else
+            IMAGE="gignaati/gigaclaw:pi-coding-agent-job-${GIGACLAW_VERSION}"
+          fi
+          echo "Using image: $IMAGE"
+
+          # Build SECRETS JSON from AGENT_* (excluding AGENT_LLM_*) secrets
+          export SECRETS=$(echo "$ALL_SECRETS" | jq -c '
+            [to_entries[] | select(.key | startswith("AGENT_")) | select(.key | startswith("AGENT_LLM_") | not)]
+            | map({key: (.key | sub("^AGENT_"; "")), value: .value}) | from_entries')
+
+          # Build LLM_SECRETS JSON from AGENT_LLM_* secrets
+          export LLM_SECRETS=$(echo "$ALL_SECRETS" | jq -c '
+            [to_entries[] | select(.key | startswith("AGENT_LLM_"))]
+            | map({key: (.key | sub("^AGENT_LLM_"; "")), value: .value}) | from_entries')
+
+          docker run --rm \
+            -e REPO_URL="${{ github.server_url }}/${{ github.repository }}.git" \
+            -e BRANCH="${{ github.ref_name }}" \
+            -e SECRETS \
+            -e LLM_SECRETS \
+            -e LLM_MODEL="${LLM_MODEL}" \
+            -e LLM_PROVIDER="${LLM_PROVIDER}" \
+            -e OPENAI_BASE_URL="${OPENAI_BASE_URL}" \
+            -e AGENT_BACKEND="${AGENT_BACKEND}" \
+            "$IMAGE"

package/templates/.github/workflows/upgrade-event-handler.yml

@@ -0,0 +1,62 @@
+name: Upgrade Event Handler
+
+on:
+  workflow_dispatch:
+    inputs:
+      target_version:
+        description: 'Target version to install (empty for latest stable)'
+        required: false
+        default: ''
+
+concurrency:
+  group: event-handler-deploy
+  cancel-in-progress: false
+
+jobs:
+  upgrade:
+    runs-on: self-hosted
+    timeout-minutes: 20
+    steps:
+      - name: Upgrade gigaclaw
+        run: |
+          docker exec gigaclaw-event-handler bash -c '
+            export GH_TOKEN=$(grep "^GH_TOKEN=" /app/.env | cut -d= -f2-)
+            echo "${GH_TOKEN}" | gh auth login --with-token
+            gh auth setup-git
+
+            REPO_URL=$(git -C /app remote get-url origin)
+            WORK_DIR=$(mktemp -d)
+            git clone --depth 1 "$REPO_URL" "$WORK_DIR"
+            cd "$WORK_DIR"
+
+            git config user.name "gigaclaw"
+            git config user.email "gigaclaw@users.noreply.github.com"
+
+            npm install --omit=dev
+            OLD_VERSION=$(node -p "require(\"./node_modules/gigaclaw/package.json\").version")
+
+            TARGET="${{ github.event.inputs.target_version }}"
+            if [ -n "$TARGET" ] && echo "$TARGET" | grep -q "-"; then
+              # Beta: npm update cannot upgrade an exact-pinned dependency, must use install
+              npm install "gigaclaw@${TARGET}" --prefer-online
+            else
+              # Stable: npm update resolves to latest within semver range
+              npm update gigaclaw --prefer-online
+            fi
+
+            NEW_VERSION=$(node -p "require(\"./node_modules/gigaclaw/package.json\").version")
+
+            if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
+              BRANCH="upgrade/gigaclaw-${NEW_VERSION}-$(date +%s)"
+              git add -A
+              git checkout -b "$BRANCH"
+              git commit -m "chore: upgrade gigaclaw to $NEW_VERSION"
+              git push origin "$BRANCH"
+              gh pr create --title "chore: upgrade gigaclaw" --body "Automated upgrade via upgrade-event-handler workflow." --base main --head "$BRANCH"
+              gh pr merge "$BRANCH" --squash --auto --delete-branch
+            else
+              echo "No changes — gigaclaw is already up to date."
+            fi
+
+            rm -rf "$WORK_DIR"
+          '

package/templates/.gitignore.template

@@ -0,0 +1,45 @@
+# Credentials - NEVER commit these
+
+.env
+.env.local
+*.pem
+*.key
+
+.claude/*
+!.claude/skills
+
+# Pi system prompt (generated at runtime from SOUL.md)
+.pi/SYSTEM.md
+
+# Skills dependencies (installed at runtime in Docker for correct arch)
+skills/*/node_modules/
+
+# Node
+node_modules/
+
+# Next.js
+.next/
+.next-new/
+.next-old/
+out/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Logs
+*.log
+
+# Temporary files
+tmp/
+temp/
+.tmp/
+
+# Data (SQLite memory, etc.)
+data/

package/templates/.pi/extensions/env-sanitizer/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Env Sanitizer Extension - Protects credentials from AI agent access
+ *
+ * Uses Pi's spawnHook to filter sensitive env vars from bash subprocess calls
+ * while keeping them available in the main process for:
+ * - Anthropic SDK (needs ANTHROPIC_API_KEY at init)
+ * - GitHub CLI (needs GH_TOKEN)
+ * - Other extensions that may need credentials
+ *
+ * Dynamically filters all keys defined in the SECRETS JSON env var.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createBashTool } from "@mariozechner/pi-coding-agent";
+
+// Parse SECRETS JSON to get list of keys to filter
+function getSecretKeys(): string[] {
+  const keys: string[] = [];
+  if (process.env.SECRETS) {
+    try {
+      const secrets = JSON.parse(process.env.SECRETS);
+      keys.push(...Object.keys(secrets));
+    } catch {
+      // Invalid JSON, ignore
+    }
+  }
+  // Always filter SECRETS itself
+  keys.push("SECRETS");
+  return [...new Set(keys)]; // Dedupe
+}
+
+export default function (pi: ExtensionAPI) {
+  const secretKeys = getSecretKeys();
+
+  // Override bash tool with filtered environment for subprocesses
+  const bashTool = createBashTool(process.cwd(), {
+    spawnHook: ({ command, cwd, env }) => {
+      // Filter all secret keys from subprocess environment
+      const filteredEnv = { ...env };
+      for (const key of secretKeys) {
+        delete filteredEnv[key];
+      }
+      return { command, cwd, env: filteredEnv };
+    },
+  });
+
+  pi.registerTool(bashTool);
+}

package/templates/.pi/extensions/env-sanitizer/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "env-sanitizer",
+  "private": true,
+  "type": "module"
+}

package/templates/CLAUDE.md

@@ -0,0 +1,29 @@
+# Templates Directory — Scaffolding Only
+
+This directory contains files that get copied into user projects when they run `npx gigaclaw init`. It is **not** where event handler logic, API routes, or core features live.
+
+## Rules
+
+- **NEVER** add event handler code, API route handlers, or core logic here. All of that belongs in the NPM package (`api/`, `lib/`, `config/`, `bin/`).
+- Templates exist solely to scaffold a new user's project folder with thin wiring and user-editable configuration.
+- Files here may be modified to fix wiring, update configuration defaults, or adjust scaffolding — but never to implement features.
+
+## What belongs here
+
+- **Next.js wiring**: `next.config.mjs`, `instrumentation.js`, catch-all route, middleware — thin re-exports from `gigaclaw/*`
+- **User-editable config**: `config/SOUL.md`, `config/JOB_PLANNING.md`, `config/CRONS.json`, `config/TRIGGERS.json`, etc.
+- **GitHub Actions workflows**: `.github/workflows/`
+- **Docker files**: `docker/`, `docker-compose.yml`
+- **UI page shells**: `app/` pages that import components from the package
+- **Client components**: `app/components/` for components that must live in the user's project (e.g., `login-form.jsx`, `setup-form.jsx`) because they depend on user-side packages like `next-auth/react`
+
+## What does NOT belong here
+
+- Route handlers with business logic
+- Library code (`lib/`)
+- Database operations
+- LLM/AI integrations
+- Tool implementations
+- Anything that should be shared across all users via `npm update gigaclaw`
+
+If you're adding a feature to the event handler, put it in the package. Templates just wire into it.

package/templates/CLAUDE.md.template

@@ -0,0 +1,308 @@
+# My Giga Bot Agent
+> Powered by **[Giga Bot](https://github.com/gignaati/gigabot)** — India's Autonomous AI Agent Platform by [Gignaati](https://www.gignaati.com)
+
+## Overview
+
+This is an autonomous AI agent powered by [Giga Bot](https://github.com/gignaati/gigabot). It uses a **two-layer architecture**:
+
+1. **Event Handler** — A Next.js server that orchestrates everything: web UI, Telegram chat, cron scheduling, webhook triggers, and job creation.
+2. **Docker Agent** — A container that runs the Pi coding agent for autonomous task execution. Each job gets its own branch, container, and PR.
+
+All core logic lives in the `gigabot` npm package. This project is a scaffolded shell — thin Next.js wiring, user-editable configuration, GitHub Actions workflows, and Docker files.
+
+## Directory Structure
+
+```
+project-root/
+├── CLAUDE.md                          # This file (project documentation)
+├── next.config.mjs                    # Next.js config (wraps withGigabot())
+├── instrumentation.js                 # Server startup hook (re-exports from package)
+├── middleware.js                       # Auth middleware (re-exports from package)
+├── .env                               # API keys and tokens (gitignored)
+├── package.json
+│
+├── app/                               # Next.js app directory (page shells + client components)
+│   ├── api/[...gigabot]/route.js   # Catch-all API route (re-exports from package)
+│   ├── stream/chat/route.js           # Chat streaming endpoint (session auth)
+│   └── components/                    # Client-side components
+│
+├── config/                            # Agent configuration (user-editable)
+│   ├── SOUL.md                        # Personality, identity, and values
+│   ├── JOB_PLANNING.md                # Event handler LLM system prompt
+│   ├── JOB_AGENT.md                   # Agent runtime environment docs
+│   ├── JOB_SUMMARY.md                 # Prompt for summarizing completed jobs
+│   ├── HEARTBEAT.md                   # Self-monitoring / heartbeat behavior
+│   ├── SKILL_BUILDING_GUIDE.md             # Guide for building agent skills
+│   ├── CRONS.json                     # Scheduled job definitions
+│   └── TRIGGERS.json                  # Webhook trigger definitions
+│
+├── .github/workflows/                 # GitHub Actions
+├── docker/                            # Docker files (job agent + event handler)
+├── skills/                            # All available agent skills
+│   └── active/                        # Symlinks to active skills (shared by Pi + Claude Code)
+├── .pi/skills → skills/active         # Pi reads skills from here
+├── .claude/skills → skills/active     # Claude Code reads skills from here
+├── cron/                              # Scripts for command-type cron actions
+├── triggers/                          # Scripts for command-type trigger actions
+├── logs/                              # Per-job output (logs/<JOB_ID>/job.md + session .jsonl)
+└── data/                              # SQLite database (data/gigabot.sqlite)
+```
+
+## Two-Layer Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                                                                         │
+│  ┌──────────────────┐         ┌──────────────────┐                     │
+│  │  Event Handler   │ ──1──►  │     GitHub       │                     │
+│  │  (creates job)   │         │ (job/* branch)   │                     │
+│  └────────▲─────────┘         └────────┬─────────┘                     │
+│           │                            │                               │
+│           │                            2 (triggers run-job.yml)        │
+│           │                            │                               │
+│           │                            ▼                               │
+│           │                   ┌──────────────────┐                     │
+│           │                   │  Docker Agent    │                     │
+│           │                   │  (runs Pi, PRs)  │                     │
+│           │                   └────────┬─────────┘                     │
+│           │                            │                               │
+│           │                            3 (creates PR)                  │
+│           │                            │                               │
+│           │                            ▼                               │
+│           │                   ┌──────────────────┐                     │
+│           │                   │     GitHub       │                     │
+│           │                   │   (PR opened)    │                     │
+│           │                   └────────┬─────────┘                     │
+│           │                            │                               │
+│           │                            4a (auto-merge.yml)             │
+│           │                            4b (notify-pr-complete.yml)     │
+│           │                            │                               │
+│           5 (notification → web UI     │                               │
+│              and Telegram)             │                               │
+│           └────────────────────────────┘                               │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Event Handler** (this Next.js server): Receives requests (web UI, Telegram, webhooks, cron timers), creates jobs by pushing a `job/<uuid>` branch to GitHub, and manages the web interface.
+
+**Docker Agent**: A container spun up by GitHub Actions (`run-job.yml`) that clones the job branch, runs the Pi coding agent with the job prompt, commits results, and opens a PR.
+
+## Job Lifecycle
+
+1. **Job created** — Event handler calls `createJob()` (via chat, cron, trigger, or API)
+2. **Branch pushed** — A `job/<uuid>` branch is created with `logs/<uuid>/job.md` containing the task prompt
+3. **Workflow triggers** — `run-job.yml` fires on `job/*` branch creation
+4. **Container runs** — Docker agent clones the branch, builds `SYSTEM.md` from `config/SOUL.md` + `config/AGENT.md`, runs Pi with the job prompt, and logs the session to `logs/<uuid>/`
+5. **PR created** — Agent commits results and opens a pull request
+6. **Auto-merge** — `auto-merge.yml` squash-merges the PR if all changed files fall within `ALLOWED_PATHS` prefixes (default: `/logs`)
+7. **Notification** — `notify-pr-complete.yml` sends job results back to the event handler, which creates a notification in the web UI and sends a Telegram message
+
+## Action Types
+
+Both cron jobs and webhook triggers use the same dispatch system. Every action has a `type` field:
+
+| | `agent` (default) | `command` | `webhook` |
+|---|---|---|---|
+| **Uses LLM** | Yes — spins up Pi in Docker | No | No |
+| **Runtime** | Minutes to hours | Milliseconds to seconds | Milliseconds to seconds |
+| **Cost** | LLM API calls + GitHub Actions | Free (runs on event handler) | Free (runs on event handler) |
+| **Use case** | Tasks that need to think, reason, write code | Shell scripts, file operations | Call external APIs, forward webhooks |
+
+If the task needs to *think*, use `agent`. If it just needs to *do*, use `command`. If it needs to *call an external service*, use `webhook`.
+
+### Agent action
+```json
+{ "type": "agent", "job": "Analyze the logs and write a summary report" }
+```
+Creates a Docker Agent job. The `job` string is passed as-is to the LLM as its task prompt.
+
+### Command action
+```json
+{ "type": "command", "command": "node cleanup.js --older-than 7d" }
+```
+Runs a shell command on the event handler. Working directory: `cron/` for crons, `triggers/` for triggers.
+
+### Webhook action
+```json
+{
+  "type": "webhook",
+  "url": "https://api.example.com/notify",
+  "method": "POST",
+  "headers": { "Authorization": "Bearer token" },
+  "vars": { "source": "my-agent" }
+}
+```
+Makes an HTTP request. `GET` skips the body. `POST` (default) sends `{ ...vars }` or `{ ...vars, data: <incoming payload> }` when triggered by a webhook.
+
+## Cron Jobs
+
+Defined in `config/CRONS.json`, loaded at server startup by `node-cron`.
+
+```json
+[
+  {
+    "name": "Daily Check",
+    "schedule": "0 9 * * *",
+    "type": "agent",
+    "job": "Review recent activity and summarize findings",
+    "enabled": true
+  }
+]
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name |
+| `schedule` | Yes | Cron expression (e.g., `0 9 * * *` = daily at 9am) |
+| `type` | No | `agent` (default), `command`, or `webhook` |
+| `job` | For agent | Task prompt passed to the LLM |
+| `command` | For command | Shell command (runs in `cron/` directory) |
+| `url` | For webhook | Target URL |
+| `method` | For webhook | `GET` or `POST` (default: `POST`) |
+| `headers` | For webhook | Custom request headers |
+| `vars` | For webhook | Key-value pairs merged into request body |
+| `enabled` | No | Set `false` to disable (default: `true`) |
+| `llm_provider` | No | Override LLM provider for this cron (agent type only) |
+| `llm_model` | No | Override LLM model for this cron (agent type only) |
+
+## Webhook Triggers
+
+Defined in `config/TRIGGERS.json`, loaded at server startup. Triggers fire on POST requests to watched paths (after auth, before route handler, fire-and-forget).
+
+```json
+[
+  {
+    "name": "GitHub Push",
+    "watch_path": "/webhook/github-push",
+    "enabled": true,
+    "actions": [
+      {
+        "type": "agent",
+        "job": "Review the push to {{body.ref}}: {{body.head_commit.message}}"
+      }
+    ]
+  }
+]
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name |
+| `watch_path` | Yes | URL path to watch (e.g., `/webhook/github-push`) |
+| `actions` | Yes | Array of actions to fire (same fields as cron actions) |
+| `enabled` | No | Set `false` to disable (default: `true`) |
+
+**Template tokens** for `job` and `command` strings:
+
+| Token | Resolves to |
+|-------|-------------|
+| `{{body}}` | Entire request body as JSON |
+| `{{body.field}}` | Nested field from request body |
+| `{{query}}` | All query parameters as JSON |
+| `{{query.field}}` | Specific query parameter |
+| `{{headers}}` | All request headers as JSON |
+| `{{headers.field}}` | Specific request header |
+
+## API Endpoints
+
+All API routes are under `/api/`, handled by the catch-all route.
+
+| Endpoint | Method | Auth | Purpose |
+|----------|--------|------|---------|
+| `/api/create-job` | POST | `x-api-key` | Create a new autonomous agent job |
+| `/api/telegram/webhook` | POST | `TELEGRAM_WEBHOOK_SECRET` | Telegram bot webhook |
+| `/api/telegram/register` | POST | `x-api-key` | Register Telegram webhook URL |
+| `/api/github/webhook` | POST | `GH_WEBHOOK_SECRET` | Receive notifications from GitHub Actions |
+| `/api/jobs/status` | GET | `x-api-key` | Check status of running/queued jobs |
+| `/api/ping` | GET | Public | Health check |
+
+**`x-api-key`**: Database-backed API keys generated through the web UI (Settings > Secrets). Keys are SHA-256 hashed, verified with timing-safe comparison. Format: `tpb_` prefix + 64 hex characters.
+
+## Web Interface
+
+Accessible after login at `APP_URL`. Routes: `/` (chat), `/chats` (history), `/chat/[chatId]` (resume chat), `/settings/crons`, `/settings/triggers`, `/settings/secrets` (API keys), `/swarm` (job monitor), `/notifications`, `/login` (auth / first-time admin setup).
+
+## Authentication
+
+NextAuth v5 with Credentials provider (email/password), JWT in httpOnly cookies. First visit creates admin account. Browser UI uses Server Actions with `requireAuth()`. API routes use `x-api-key` header. Chat streaming uses a dedicated route at `/stream/chat` with `auth()` session check.
+
+## Database
+
+SQLite via Drizzle ORM at `data/gigabot.sqlite`. Auto-initialized and auto-migrated on server startup. Tables: `users`, `chats`, `messages`, `notifications`, `subscriptions`, `settings` (key-value store, also stores API keys). Column naming: camelCase in JS → snake_case in SQL.
+
+## GitHub Actions Workflows
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `run-job.yml` | `job/*` branch created | Runs the Docker agent container |
+| `rebuild-event-handler.yml` | Push to `main` | Rebuilds server (fast path or Docker restart) |
+| `upgrade-event-handler.yml` | Manual `workflow_dispatch` | Creates PR to upgrade gigabot package |
+| `build-image.yml` | `docker/pi-coding-agent-job/**` changes | Builds Pi coding agent Docker image to GHCR |
+| `auto-merge.yml` | Job PR opened | Squash-merges if changes are within `ALLOWED_PATHS` |
+| `notify-pr-complete.yml` | After `auto-merge.yml` | Sends job completion notification |
+| `notify-job-failed.yml` | `run-job.yml` fails | Sends failure notification |
+
+## GitHub Secrets & Variables
+
+### Secrets (prefix-based naming)
+
+| Prefix | Purpose | Visible to LLM? | Example |
+|--------|---------|------------------|---------|
+| `AGENT_` | Protected credentials for Docker agent | No (filtered by env-sanitizer) | `AGENT_GH_TOKEN`, `AGENT_ANTHROPIC_API_KEY` |
+| `AGENT_LLM_` | LLM-accessible credentials for Docker agent | Yes | `AGENT_LLM_BRAVE_API_KEY` |
+| *(none)* | Workflow-only secrets (never passed to container) | N/A | `GH_WEBHOOK_SECRET` |
+
+`AGENT_*` secrets are collected into a `SECRETS` JSON object by `run-job.yml` (prefix stripped) and exported as env vars in the container. `AGENT_LLM_*` go into `LLM_SECRETS` and are not filtered from the LLM's bash environment.
+
+### Repository Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `APP_URL` | Public URL for the event handler | Required |
+| `AUTO_MERGE` | Set to `"false"` to disable auto-merge | Enabled |
+| `ALLOWED_PATHS` | Comma-separated path prefixes for auto-merge | `/logs` |
+| `JOB_IMAGE_URL` | Docker image for job agent (GHCR URLs trigger auto-builds) | Default gigabot image |
+| `EVENT_HANDLER_IMAGE_URL` | Docker image for event handler | Default gigabot image |
+| `RUNS_ON` | GitHub Actions runner label | `ubuntu-latest` |
+| `LLM_PROVIDER` | LLM provider for Docker agent | `anthropic` |
+| `LLM_MODEL` | LLM model name for Docker agent | Provider default |
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `APP_URL` | Public URL for webhooks and Telegram | Yes |
+| `AUTH_SECRET` | NextAuth session encryption (auto-generated) | Yes |
+| `GH_TOKEN` | GitHub PAT for creating branches/files | Yes |
+| `GH_OWNER` | GitHub repository owner | Yes |
+| `GH_REPO` | GitHub repository name | Yes |
+| `TELEGRAM_BOT_TOKEN` | Telegram bot token | For Telegram |
+| `TELEGRAM_WEBHOOK_SECRET` | Telegram webhook validation secret | No |
+| `TELEGRAM_CHAT_ID` | Default chat ID for notifications | For Telegram |
+| `GH_WEBHOOK_SECRET` | GitHub Actions webhook auth | For notifications |
+| `LLM_PROVIDER` | `anthropic`, `openai`, `google`, or `custom` | No (default: `anthropic`) |
+| `LLM_MODEL` | Model name override | No |
+| `LLM_MAX_TOKENS` | Max tokens for LLM responses | No (default: 4096) |
+| `ANTHROPIC_API_KEY` | Anthropic API key | For anthropic provider |
+| `OPENAI_API_KEY` | OpenAI API key / Whisper | For openai provider |
+| `OPENAI_BASE_URL` | Custom OpenAI-compatible base URL | For custom provider |
+| `GOOGLE_API_KEY` | Google API key | For google provider |
+| `CUSTOM_API_KEY` | Custom provider API key | For custom provider |
+| `DATABASE_PATH` | Override SQLite DB location | No |
+
+## Customization
+
+User-editable config files in `config/`: `SOUL.md` (personality), `JOB_PLANNING.md` (LLM system prompt), `JOB_AGENT.md` (runtime docs), `JOB_SUMMARY.md` (job summaries), `HEARTBEAT.md` (self-monitoring), `SKILL_BUILDING_GUIDE.md` (skill guide), `CRONS.json` (scheduled jobs), `TRIGGERS.json` (webhook triggers).
+
+Skills in `skills/` are activated by symlinking into `skills/active/`. Both `.pi/skills` and `.claude/skills` point to `skills/active/`. Scripts for command-type actions go in `cron/` and `triggers/`.
+
+### Markdown includes and variables
+
+Config markdown files support includes and built-in variables (processed by the package's `render-md.js`):
+
+| Syntax | Description |
+|--------|-------------|
+| `{{ filepath.md }}` | Include another file (relative to project root, recursive with circular detection) |
+| `{{datetime}}` | Current ISO timestamp |
+| `{{skills}}` | Dynamic bullet list of active skill descriptions from `skills/active/*/SKILL.md` frontmatter — never hardcode skill names, this is resolved at runtime |

package/templates/app/api/[...gigaclaw]/route.js

@@ -0,0 +1 @@
+export { GET, POST } from 'gigaclaw/api';

package/templates/app/api/auth/[...nextauth]/route.js

@@ -0,0 +1 @@
+export { GET, POST } from 'gigaclaw/auth';

package/templates/app/chat/[chatId]/page.js

@@ -0,0 +1,9 @@
+import { auth } from 'gigaclaw/auth';
+import { ChatPage } from 'gigaclaw/chat';
+
+export default async function ChatRoute({ params }) {
+  // Next.js 15: params is synchronous — no await needed
+  const { chatId } = params;
+  const session = await auth();
+  return <ChatPage session={session} needsSetup={false} chatId={chatId} />;
+}

package/templates/app/chats/page.js

@@ -0,0 +1,7 @@
+import { auth } from 'gigaclaw/auth';
+import { ChatsPage } from 'gigaclaw/chat';
+
+export default async function ChatsRoute() {
+  const session = await auth();
+  return <ChatsPage session={session} />;
+}

package/templates/app/code/[codeWorkspaceId]/page.js

@@ -0,0 +1,9 @@
+import { auth } from 'gigaclaw/auth';
+import { CodePage } from 'gigaclaw/code';
+
+export default async function CodeRoute({ params }) {
+  const session = await auth();
+  // Next.js 15: params is synchronous — no await needed
+  const { codeWorkspaceId } = params;
+  return <CodePage session={session} codeWorkspaceId={codeWorkspaceId} />;
+}

package/templates/app/components/ascii-logo.jsx

@@ -0,0 +1,12 @@
+export function AsciiLogo() {
+  return (
+    <pre className="text-foreground text-[clamp(0.45rem,1.5vw,0.85rem)] leading-snug text-left mb-8 select-none">{`  _____ _             ____        _
+ / ____(_)           |  _ \      | |
+| |  __ _  __ _  __ _| |_) | ___ | |_
+| | |_ | |/ _\` |/ _\` |  _ < / _ \| __|
+| |__| | | (_| | (_| | |_) | (_) | |_
+ \_____|_|\__, |\__,_|____/ \___/ \__|
+           __/ |
+          |___/   Powered by Gignaati`}</pre>
+  );
+}