gin-skills 1.0.0 → 1.0.1

package/README.md

@@ -78,8 +78,10 @@ gin-skills versions   # Show all published npm versions
 | `mobile-app-review` | `--skills mobile-app-review` | Mobile App Store Review Checklist: Comprehensive pre-submission audit for Apple App Store and Google Play Store. |
 | `mongodb` | `--skills mongodb` | MongoDB & Mongoose Best Practices: Production patterns for schema design, indexing, aggregation pipelines, transactions, connection management, and... |
 | `nestjs-architecture` | `--skills nestjs-architecture` | NestJS Feature-Based Architecture: Production patterns for organizing NestJS backends — feature modules, core infrastructure, shared utilities, gua... |
+| `openclaw-builder` | `--skills openclaw-builder` | Guide for setting up, configuring, and extending OpenClaw — an AI gateway for connecting LLM agents to messaging channels (Telegram, Discord, Whats... |
 | `react-fsd-architecture` | `--skills react-fsd-architecture` | Feature-Sliced Design (FSD) Architecture: Architectural methodology for organizing frontend projects by business features — layers, slices, segment... |
 | `react-native-expo` | `--skills react-native-expo` | React Native Expo (Sty AI Mobile): Production patterns for the Sty AI React Native app — Expo SDK 54, Expo Router v5, React Query v5, Zustand v5, R... |
+| `react-native-performance` | `--skills react-native-performance` | React Native Performance Optimization: Comprehensive guide — rendering, memory leaks, bundle size, startup, animations, navigation, algorithms, and... |
 | `react-query` | `--skills react-query` | TanStack React Query Best Practices: Comprehensive guide for writing production-quality React Query code — query keys, mutations, caching, optimist... |
 | `review-code` | `--skills review-code` | Code Review: Comprehensive code review and quality analysis for fullstack monorepos (NestJS backend, Next.js frontend, React Native mobile). |
 | `security-scanner` | `--skills security-scanner` | Security Scanner: Comprehensive security audit for fullstack monorepos — NestJS backend, Next.js frontend, and React Native mobile app. |

package/bin/cli.js

@@ -2,7 +2,7 @@
 
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { existsSync, readdirSync, statSync, mkdirSync, copyFileSync, rmSync, readFileSync } from 'fs';
+import { existsSync, readdirSync, statSync, mkdirSync, copyFileSync, rmSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -15,6 +15,14 @@ const SRC_SKILLS  = join(PACKAGE_DIR, 'skills');
 const SRC_AGENTS  = join(PACKAGE_DIR, 'agents');
 const PKG         = JSON.parse(readFileSync(join(PACKAGE_DIR, 'package.json'), 'utf-8'));
 
+// ─── Skills that require environment variables ───────────────────────────────
+const SKILL_ENV_VARS = {
+  'ai-asset-generator': [
+    { key: 'KIE_AI_API_KEY', desc: 'KIE AI API key for image/video generation', url: 'https://kie.ai' },
+    { key: 'STY_AI_API_KEY', desc: 'Sty AI API key for background removal', url: 'https://api.styai.app' },
+  ],
+};
+
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
 function getDirs(dir) {
@@ -114,6 +122,56 @@ async function runInstall({ target, skills, agents, verb = 'Installed' }) {
   spinner.succeed(chalk.bold.green(`${verb}! ${count} item(s)`));
   console.log();
   log.info(`Target: ${chalk.cyan(target)}`);
+
+  // Check if any installed skills need env vars
+  const neededVars = [];
+  for (const skill of skills) {
+    if (SKILL_ENV_VARS[skill]) {
+      neededVars.push(...SKILL_ENV_VARS[skill].map(v => ({ ...v, skill })));
+    }
+  }
+
+  if (neededVars.length > 0) {
+    const envExamplePath = join(target, '.env.example');
+    const envPath = join(target, '.env');
+
+    // Build .env.example content
+    const lines = ['# Environment variables required by installed skills', ''];
+    const grouped = {};
+    for (const v of neededVars) {
+      if (!grouped[v.skill]) grouped[v.skill] = [];
+      grouped[v.skill].push(v);
+    }
+    for (const [skill, vars] of Object.entries(grouped)) {
+      lines.push(`# ─── ${skill} ───`);
+      for (const v of vars) {
+        lines.push(`# ${v.desc}`);
+        lines.push(`# Get from: ${v.url}`);
+        lines.push(`${v.key}=`);
+        lines.push('');
+      }
+    }
+
+    // Write .env.example (always overwrite with latest)
+    writeFileSync(envExamplePath, lines.join('\n'));
+
+    // Create .env from .env.example if it doesn't exist yet
+    if (!existsSync(envPath)) {
+      copyFileSync(envExamplePath, envPath);
+    }
+
+    console.log();
+    console.log(chalk.bold.yellow('  ⚠  Environment variables required:'));
+    console.log();
+    for (const v of neededVars) {
+      console.log(`    ${chalk.yellow(v.key)}`);
+      console.log(`    ${chalk.dim(v.desc)} — ${chalk.cyan(v.url)}`);
+      console.log();
+    }
+    console.log(`  ${chalk.dim('Fill in your keys in:')} ${chalk.cyan(envPath)}`);
+  }
+
+  console.log();
   log.dim('Restart Claude Code (or run /agents) to pick up changes.');
   console.log();
 }

package/landing/index.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>GinStudio Skills — Supercharge Claude Code</title>
-  <meta name="description" content="Install production-ready skills and agents for Claude Code with one command. <!-- AUTO:META_COUNTS -->15 skills, 6 agents<!-- /AUTO:META_COUNTS -->, interactive TUI.">
+  <meta name="description" content="Install production-ready skills and agents for Claude Code with one command. <!-- AUTO:META_COUNTS -->17 skills, 6 agents<!-- /AUTO:META_COUNTS -->, interactive TUI.">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
@@ -689,7 +689,7 @@
     <div class="container">
       <div class="hero-badge fade-up">
         <span class="dot"></span>
-        <!-- AUTO:BADGE -->v1.0 &mdash; 15 Skills &middot; 6 Agents<!-- /AUTO:BADGE -->
+        <!-- AUTO:BADGE -->v1.0 &mdash; 17 Skills &middot; 6 Agents<!-- /AUTO:BADGE -->
       </div>
       <h1 class="fade-up"><span>Supercharge</span> Claude Code<br>with One Command</h1>
       <p class="hero-sub fade-up">
@@ -718,7 +718,7 @@
 
       <!-- AUTO:STATS -->
       <div class="stats-bar fade-up">
-        <div class="stat"><span class="stat-number">15</span><span class="stat-label">Skills</span></div>
+        <div class="stat"><span class="stat-number">17</span><span class="stat-label">Skills</span></div>
         <div class="stat"><span class="stat-number">6</span><span class="stat-label">Agents</span></div>
         <div class="stat"><span class="stat-number">1</span><span class="stat-label">Command</span></div>
         <div class="stat"><span class="stat-number">MIT</span><span class="stat-label">License</span></div>
@@ -787,7 +787,7 @@
     <div class="container">
       <div class="section-header fade-up">
         <div class="section-tag">Skills</div>
-        <h2><!-- AUTO:SKILL_COUNT -->15<!-- /AUTO:SKILL_COUNT --> Production-Ready Skills</h2>
+        <h2><!-- AUTO:SKILL_COUNT -->17<!-- /AUTO:SKILL_COUNT --> Production-Ready Skills</h2>
         <p>Deep domain knowledge that Claude Code loads automatically when relevant. Click to copy the install command.</p>
       </div>
       <div class="skills-grid" id="skillsGrid"></div>
@@ -1179,7 +1179,7 @@
     <div class="container">
       <div class="cta-box fade-up">
         <h2>Ready to Supercharge<br>Your Workflow?</h2>
-        <p>One command. <!-- AUTO:CTA_COUNTS -->15 skills. 6 agents.<!-- /AUTO:CTA_COUNTS --> Zero configuration.</p>
+        <p>One command. <!-- AUTO:CTA_COUNTS -->17 skills. 6 agents.<!-- /AUTO:CTA_COUNTS --> Zero configuration.</p>
         <div class="cta-install-cmd" onclick="copyInstall()" role="button" tabindex="0" aria-label="Copy install command">
           <span class="dollar">$</span>
           <span class="cmd-text">npx gin-skills</span>
@@ -1220,10 +1220,10 @@
   <footer class="footer">
     <div class="container">
       <div class="footer-content">
-        <div class="footer-brand">GinStudio Skills v1.0.0</div>
+        <div class="footer-brand">GinStudio Skills v1.0.1</div>
         <div class="footer-links">
           <a href="https://www.npmjs.com/package/gin-skills" target="_blank" rel="noopener">npm</a>
-          <a href="https://gitlab.com/ginstudio/skills" target="_blank" rel="noopener">GitLab</a>
+          <a href="https://github.com/vuduynhiennn/ginskills" target="_blank" rel="noopener">GitHub</a>
           <a href="#features">Features</a>
           <a href="#skills">Skills</a>
           <a href="#agents">Agents</a>
@@ -1248,12 +1248,14 @@
       { name: 'mobile-app-review', desc: 'Mobile App Store Review Checklist: Comprehensive pre-submission audit for Apple App Store and Google Play Store.', color: 'var(--cyan)' },
       { name: 'mongodb', desc: 'MongoDB & Mongoose Best Practices: Production patterns for schema design, indexing, aggregation pipelines, transactions, connection management, and...', color: 'var(--green)' },
       { name: 'nestjs-architecture', desc: 'NestJS Feature-Based Architecture: Production patterns for organizing NestJS backends — feature modules, core infrastructure, shared utilities, gua...', color: 'var(--rose)' },
-      { name: 'react-fsd-architecture', desc: 'Feature-Sliced Design (FSD) Architecture: Architectural methodology for organizing frontend projects by business features — layers, slices, segment...', color: 'var(--purple)' },
-      { name: 'react-native-expo', desc: 'React Native Expo (Sty AI Mobile): Production patterns for the Sty AI React Native app — Expo SDK 54, Expo Router v5, React Query v5, Zustand v5, R...', color: 'var(--amber)' },
-      { name: 'react-query', desc: 'TanStack React Query Best Practices: Comprehensive guide for writing production-quality React Query code — query keys, mutations, caching, optimist...', color: 'var(--blue)' },
-      { name: 'review-code', desc: 'Code Review: Comprehensive code review and quality analysis for fullstack monorepos (NestJS backend, Next.js frontend, React Native mobile).', color: 'var(--cyan)' },
-      { name: 'security-scanner', desc: 'Security Scanner: Comprehensive security audit for fullstack monorepos — NestJS backend, Next.js frontend, and React Native mobile app.', color: 'var(--green)' },
-      { name: 'ui-ux-pro-max', desc: 'UI/UX design intelligence.', color: 'var(--rose)' },
+      { name: 'openclaw-builder', desc: 'Guide for setting up, configuring, and extending OpenClaw — an AI gateway for connecting LLM agents to messaging channels (Telegram, Discord, Whats...', color: 'var(--purple)' },
+      { name: 'react-fsd-architecture', desc: 'Feature-Sliced Design (FSD) Architecture: Architectural methodology for organizing frontend projects by business features — layers, slices, segment...', color: 'var(--amber)' },
+      { name: 'react-native-expo', desc: 'React Native Expo (Sty AI Mobile): Production patterns for the Sty AI React Native app — Expo SDK 54, Expo Router v5, React Query v5, Zustand v5, R...', color: 'var(--blue)' },
+      { name: 'react-native-performance', desc: 'React Native Performance Optimization: Comprehensive guide — rendering, memory leaks, bundle size, startup, animations, navigation, algorithms, and...', color: 'var(--cyan)' },
+      { name: 'react-query', desc: 'TanStack React Query Best Practices: Comprehensive guide for writing production-quality React Query code — query keys, mutations, caching, optimist...', color: 'var(--green)' },
+      { name: 'review-code', desc: 'Code Review: Comprehensive code review and quality analysis for fullstack monorepos (NestJS backend, Next.js frontend, React Native mobile).', color: 'var(--rose)' },
+      { name: 'security-scanner', desc: 'Security Scanner: Comprehensive security audit for fullstack monorepos — NestJS backend, Next.js frontend, and React Native mobile app.', color: 'var(--purple)' },
+      { name: 'ui-ux-pro-max', desc: 'UI/UX design intelligence.', color: 'var(--amber)' },
     ];
     /* /AUTO:SKILLS_DATA */
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gin-skills",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Install GinStudio skills and agents for Claude Code",
   "homepage": "https://skills.ginstudio.asia",
   "repository": {
@@ -16,11 +16,17 @@
   ],
   "license": "MIT",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "gen-readme": "node scripts/gen-readme.mjs",
     "check-upstream": "node scripts/check-upstream.mjs",
     "deploy": "npx wrangler pages deploy landing --project-name ginskill --branch main",
-    "prepublishOnly": "node scripts/gen-readme.mjs"
+    "prepublishOnly": "npm version patch --no-git-tag-version && node scripts/gen-readme.mjs",
+    "postpublish": "git add -A && git commit -m \"chore: release v$(node -p \"require('./package.json').version\")\" && git tag v$(node -p \"require('./package.json').version\") && git push && git push --tags && npm run deploy",
+    "release:minor": "npm version minor --no-git-tag-version && npm publish",
+    "release:major": "npm version major --no-git-tag-version && npm publish"
   },
   "bin": {
     "gin-skills": "bin/cli.js"

package/skills/openclaw-builder/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: openclaw-builder
+description: |
+  Guide for setting up, configuring, and extending OpenClaw — an AI gateway for connecting LLM agents to messaging channels (Telegram, Discord, WhatsApp, Signal, etc.), automation (cron, webhooks, heartbeat), browser control, skills, and multi-agent workflows.
+  - MANDATORY TRIGGERS: setup openclaw, configure openclaw, install openclaw, openclaw telegram, openclaw discord, openclaw channel, openclaw gateway, openclaw cron, openclaw webhook, openclaw heartbeat, openclaw skills, openclaw agent, openclaw browser, openclaw memory, openclaw session, how to use openclaw, openclaw config, add skill to openclaw, install skill openclaw, openclaw mcp, openclaw acp, openclaw plugin, extend openclaw, openclaw builder, multi-agent openclaw, openclaw model, openclaw api key, openclaw anthropic, openclaw openai, dm scope, session isolation, openclaw security, openclaw exec, openclaw elevated, openclaw sandbox, openclaw remote, openclaw tailscale, openclaw vps, openclaw slash commands, openclaw /new, openclaw /status, openclaw directive
+  - Use this skill when the user wants to: install/setup OpenClaw, connect a messaging channel, configure the gateway, set up automation, add skills or agents, work with ACP/plugins, set up multi-agent routing, or troubleshoot OpenClaw issues.
+argument-hint: "[topic: getting-started | channels | automation | gateway | skills | acp | multi-agent | browser | memory | cli | plugins]"
+---
+
+# OpenClaw Builder
+
+Fetch live docs or load local guides based on what the user needs.
+
+## Tutorial Routing
+
+Run this to load the relevant guide:
+
+```bash
+cat skills/skills/openclaw-builder/docs/$TOPIC
+```
+
+Or fetch live docs from openclaw.ai:
+
+```bash
+python3 skills/skills/openclaw-builder/scripts/fetch-docs.py <page-path>
+```
+
+---
+
+## Local Guides (bundled)
+
+| Topic | File | When to use |
+|-------|------|-------------|
+| Adding skills | `docs/skills-guide.md` | User wants to install/add/enable a skill |
+| ACP setup | `docs/acp-guide.md` | User wants to connect an IDE or use ACP protocol |
+| Multi-agent | `docs/multi-agent-guide.md` | User wants multiple agents, routing, or personas |
+| Automation (cron/heartbeat) | `docs/automation-guide.md` | User wants scheduled tasks, reminders, or heartbeat |
+| Hooks | `docs/hooks-guide.md` | User wants event-driven automation, custom hooks |
+| Plugins | `docs/plugins-guide.md` | User wants to install/create plugins, add channels |
+| Workspace & Memory | `docs/workspace-memory-guide.md` | User asks about memory, workspace files, MEMORY.md |
+| Gateway config | `docs/config-guide.md` | User wants to configure openclaw.json, channels, tools |
+| Channels setup | `docs/channels-guide.md` | User wants to setup Telegram, Discord, WhatsApp, Signal |
+| Models & Auth | `docs/models-auth-guide.md` | User wants to set API keys, model providers, DM scope |
+| Browser control | `docs/browser-guide.md` | User wants to use/configure browser automation |
+| Webhooks | `docs/webhooks-guide.md` | User wants external HTTP triggers, GitHub/Gmail webhooks |
+| Sandboxing | `docs/sandboxing-guide.md` | User wants Docker isolation for agent tools |
+| Security | `docs/security-guide.md` | User asks about security, hardening, audit, secrets |
+| Slash commands | `docs/commands-guide.md` | User asks about /commands, directives, /think, /model |
+| Remote gateway | `docs/remote-gateway-guide.md` | User wants Tailscale, VPS, Docker, remote access |
+| Exec & Elevated | `docs/exec-guide.md` | User wants exec tool, elevated mode, bash, approvals |
+
+**Load a local guide:**
+```bash
+cat skills/skills/openclaw-builder/docs/skills-guide.md
+cat skills/skills/openclaw-builder/docs/acp-guide.md
+cat skills/skills/openclaw-builder/docs/multi-agent-guide.md
+cat skills/skills/openclaw-builder/docs/automation-guide.md
+cat skills/skills/openclaw-builder/docs/hooks-guide.md
+cat skills/skills/openclaw-builder/docs/plugins-guide.md
+cat skills/skills/openclaw-builder/docs/workspace-memory-guide.md
+cat skills/skills/openclaw-builder/docs/config-guide.md
+cat skills/skills/openclaw-builder/docs/channels-guide.md
+cat skills/skills/openclaw-builder/docs/models-auth-guide.md
+cat skills/skills/openclaw-builder/docs/browser-guide.md
+cat skills/skills/openclaw-builder/docs/webhooks-guide.md
+cat skills/skills/openclaw-builder/docs/sandboxing-guide.md
+cat skills/skills/openclaw-builder/docs/security-guide.md
+cat skills/skills/openclaw-builder/docs/commands-guide.md
+cat skills/skills/openclaw-builder/docs/remote-gateway-guide.md
+cat skills/skills/openclaw-builder/docs/exec-guide.md
+```
+
+---
+
+## Live Docs Pages (fetch-docs.py)
+
+For anything not covered by local guides, fetch fresh from docs.openclaw.ai:
+
+| Topic | Page path |
+|-------|-----------|
+| Getting started | `start/getting-started` |
+| All docs index | `index` |
+| Gateway config | `gateway/configuration` |
+| Gateway config reference | `gateway/configuration-reference` |
+| Telegram | `channels/telegram` |
+| Discord | `channels/discord` |
+| WhatsApp | `channels/whatsapp` |
+| Signal | `channels/signal` |
+| Slack | `channels/slack` |
+| Cron jobs | `automation/cron-jobs` |
+| Webhooks | `automation/webhook` |
+| Heartbeat | `gateway/heartbeat` |
+| Hooks | `automation/hooks` |
+| Skills system | `tools/skills` |
+| Skills config | `tools/skills-config` |
+| ClawHub | `tools/clawhub` |
+| Plugins | `tools/plugin` |
+| ACP CLI | `cli/acp` |
+| Agent runtime | `concepts/agent` |
+| Memory | `concepts/memory` |
+| Browser tool | `cli/browser` |
+| Session management | `concepts/session` |
+| Channels index | `channels/index` |
+
+For unknown topics: fetch `index` first to discover the right page.
+
+---
+
+## Workflow
+
+1. Identify what the user wants (setup / extend / troubleshoot)
+2. Check local guides first — faster than fetching
+3. If not covered → fetch live docs with `fetch-docs.py`
+4. Guide step-by-step based on content
+5. Verify: `openclaw gateway status` or `openclaw doctor`

package/skills/openclaw-builder/docs/acp-guide.md

@@ -0,0 +1,117 @@
+# ACP — Agent Client Protocol
+
+## What is ACP?
+
+ACP (Agent Client Protocol) is how IDEs and editors connect to the OpenClaw Gateway. It bridges prompts from an IDE over stdio → Gateway over WebSocket. OpenClaw maps ACP sessions to Gateway session keys.
+
+Reference: https://agentclientprotocol.com
+
+## How It Works
+
+```
+IDE/Editor  →  openclaw acp (stdio)  →  OpenClaw Gateway (WebSocket)  →  Agent
+```
+
+ACP does not pick agents directly — it routes by Gateway session key.
+
+## Basic Usage
+
+```bash
+# Connect to local Gateway
+openclaw acp
+
+# Connect to remote Gateway
+openclaw acp --url wss://gateway-host:18789 --token <token>
+
+# Use token file (safer — token not visible in process list)
+openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
+
+# Attach to a specific agent session
+openclaw acp --session agent:main:main
+openclaw acp --session agent:design:main
+
+# Attach by label
+openclaw acp --session-label "support inbox"
+```
+
+## Targeting Agents
+
+Use agent-scoped session keys:
+
+```bash
+openclaw acp --session agent:<agentId>:main
+```
+
+Examples:
+- `agent:main:main` — default agent
+- `agent:coding:main` — agent named "coding"
+- `agent:qa:bug-123` — custom session thread
+
+## Editor Setup
+
+### Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "OpenClaw ACP": {
+      "type": "custom",
+      "command": "openclaw",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Target specific agent:
+
+```json
+{
+  "agent_servers": {
+    "OpenClaw ACP": {
+      "type": "custom",
+      "command": "openclaw",
+      "args": ["acp", "--url", "wss://gateway-host:18789", "--token-file", "~/.openclaw/gateway.token", "--session", "agent:coding:main"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Claude Code / Codex via sessions_spawn
+
+From within an OpenClaw agent session, spawn a coding agent via ACP:
+
+```
+sessions_spawn(runtime="acp", agentId="<acp-agent-id>", task="...", thread=true, mode="session")
+```
+
+This is the recommended way to use Claude Code or Codex inside OpenClaw — no manual ACP setup needed.
+
+## Debug / Test
+
+```bash
+# Interactive ACP client (test without an IDE)
+openclaw acp client
+
+# Point at remote Gateway
+openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
+```
+
+## Session Mapping
+
+| Flag | Behavior |
+|------|----------|
+| (none) | Isolated session with `acp:<uuid>` prefix |
+| `--session <key>` | Use specific Gateway session key |
+| `--session-label <label>` | Resolve existing session by label |
+| `--reset-session` | Fresh session id for same key |
+
+## Security Notes
+
+- Prefer `--token-file` over `--token` (token visible in process list)
+- Use env vars: `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`
+- ACP child processes receive `OPENCLAW_SHELL=acp` for context-specific rules

package/skills/openclaw-builder/docs/automation-guide.md

@@ -0,0 +1,135 @@
+# Automation — Cron Jobs & Heartbeat
+
+## Cron vs Heartbeat — When to Use Each
+
+| | Cron | Heartbeat |
+|---|---|---|
+| Timing | Exact schedule | Approximate interval |
+| Context | Isolated session (no history) | Main session (has context) |
+| Use case | Precise tasks, background chores | Proactive check-ins, inbox scans |
+| Config | `openclaw cron add ...` | `agents.defaults.heartbeat` |
+
+## Heartbeat
+
+Runs periodic agent turns in the **main session** — agent checks for anything needing attention.
+
+### Quick Config
+
+```json5
+// ~/.openclaw/openclaw.json
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m",           // interval (0m to disable)
+        target: "last",         // deliver to last used channel (default: "none")
+        lightContext: true,     // only inject HEARTBEAT.md (faster, cheaper)
+        activeHours: { start: "08:00", end: "23:00" }, // optional time window
+      }
+    }
+  }
+}
+```
+
+### HEARTBEAT.md
+
+Create in workspace root — agent reads this every heartbeat:
+
+```markdown
+# Heartbeat checklist
+
+- Quick scan: anything urgent in inbox?
+- Calendar events in next 2 hours?
+- If nothing: reply HEARTBEAT_OK
+```
+
+**Rules:**
+- Agent replies `HEARTBEAT_OK` if nothing to do (stripped, not delivered)
+- Agent sends alert text if something needs attention
+- Keep file small to avoid token bloat
+- Empty file = heartbeat skipped (saves API calls)
+
+### Manual Wake
+
+```bash
+openclaw system event --text "Check urgent follow-ups" --mode now
+```
+
+## Cron Jobs
+
+Runs tasks on a schedule — isolated sessions, full agent turns.
+
+### Quick Start
+
+```bash
+# One-shot reminder in 20 minutes
+openclaw cron add \
+  --name "Reminder" \
+  --at "20m" \
+  --session main \
+  --system-event "Reminder: check expense reports" \
+  --wake now \
+  --delete-after-run
+
+# Recurring daily job — deliver to Telegram
+openclaw cron add \
+  --name "Morning brief" \
+  --cron "0 7 * * *" \
+  --tz "Asia/Ho_Chi_Minh" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --announce \
+  --channel telegram \
+  --to "YOUR_CHAT_ID"
+
+# List all jobs
+openclaw cron list
+
+# Run a job immediately
+openclaw cron run <job-id>
+```
+
+### Schedule Types
+
+| Type | Example | Description |
+|------|---------|-------------|
+| `--at "20m"` | In 20 minutes | One-shot relative |
+| `--at "2026-03-08T09:00:00Z"` | Exact datetime | One-shot absolute |
+| `--cron "0 7 * * *"` | Every day 7am | Cron expression |
+
+### Session Targets
+
+- `--session main` — runs during next heartbeat (use `--system-event`)
+- `--session isolated` — dedicated isolated session (use `--message`)
+
+### Delivery Options
+
+```bash
+--announce               # deliver to channel
+--channel telegram       # which channel
+--to "CHAT_ID"           # recipient
+
+# Webhook instead
+--delivery webhook --to "https://your-webhook.com"
+```
+
+### Management
+
+```bash
+openclaw cron list                    # list all jobs
+openclaw cron run <id>                # run now
+openclaw cron edit <id> --message "new prompt"
+openclaw cron runs --id <id>          # view run history
+openclaw cron remove <id>
+```
+
+### Config (openclaw.json)
+
+```json5
+{
+  cron: {
+    enabled: true,
+    sessionRetention: "24h",  // keep isolated run sessions for 24h
+  }
+}
+```