PRD.md - Product Requirements & Feature Inventory

Everything built on top of the base OpenClaw platform. Canonical reference for what exists, where it lives, and how it works. Operational use cases and workflow playbooks live in docs/USE-CASES-WORKFLOWS.md.

Operational Use Cases & Workflows
Architecture Overview
OpenClaw Platform Configuration
CRM System
Fathom Meeting Integration
Skills
Tools
Shared Modules
Scripts & Automations
Cron Jobs
Memory System
Integrations
Databases
Environment Variables
Test Infrastructure
Configuration Files
Other Directories

Architecture Overview

The workspace is a monorepo-style project layered on top of OpenClaw. The base platform provides the agent framework, gateway, and skill system. Everything below is custom.

clawd/
├── crm/                  # Personal CRM (tracked directly inside this repo)
├── data/                 # Workspace databases (cron-log, video-pitches, business-meta-analysis)
├── docs/                 # Setup guides (Slack, workspace file organization)
├── life/                 # (empty directory, reserved for future use)
├── memory/               # Daily notes, state files, reference data
├── reference/            # Static reference data (recycling, competitors)
├── scripts/              # Shell automation scripts
├── shared/               # Shared Node.js utility modules
├── skills/               # OpenClaw skills (22 installed)
├── skills-preview/       # Skills in development (2)
├── state/                # Mutable runtime state files
├── tests/                # Test suite (unit, integration, skill, tool, script tests)
├── tools/                # Standalone utility scripts and databases
├── youtube-analysis/     # YouTube competitor analysis and content strategy
├── .learnings/           # Self-improvement corrections and learnings
└── [Root .md files]      # Core config (AGENTS, TOOLS, MEMORY, SOUL, etc.)

Key patterns:

SQLite for all persistent local data (WAL mode, foreign keys)
Vector embeddings standardized on Google gemini-embedding-001 (768-dim) across all stores (KB, CRM, business-meta-analysis, OpenClaw memory index)
Telegram as the primary notification and interaction channel
All cron jobs logged to a central database with Telegram notifications
Shared modules (shared/) for common functionality across tools and skills
gog CLI for all Google Workspace access (Gmail, Calendar, Drive, etc.)

OpenClaw Platform Configuration

Config location: ~/.openclaw/ Gateway launchd: ~/Library/LaunchAgents/ai.openclaw.gateway.plist Version: 2026.2.15 (as of Feb 17, 2026)

Gateway

Port: 18789
Mode: Local (loopback only, not exposed to network)
Auth: Token-based
Tailscale: Off
Logs: ~/.openclaw/logs/gateway.log and gateway.err.log
Binary: /opt/homebrew/lib/node_modules/openclaw/dist/index.js
Launchd: RunAtLoad + KeepAlive (auto-restart)

Model Providers

Provider	Models	Context	Pricing
Anthropic	Opus 4.6 (primary), Sonnet 4.5, Haiku 4.5	200K (1M via API tier 4+)	Pay-per-token
Google	Gemini 3 Pro, Gemini 3 Flash	2M / 1M	Free
X.AI	Grok Beta	131K	$5/$15 per 1M tokens

Model fallback chain:

Main: Opus → Sonnet → Gemini Pro → Gemini Flash → Haiku
Subagents: Sonnet → Gemini Flash → Haiku → Gemini Pro

Agent Settings

Primary model: anthropic/claude-opus-4-6
Max concurrent agents: 4
Max concurrent subagents: 8
Subagent primary model: Sonnet 4.5
Context pruning: cache-ttl mode, 1h TTL
Heartbeat interval: 1 hour
Memory backend: builtin (Gemini embeddings)
CLI backend: Cursor agent at ~/.local/bin/agent

Plugins

Plugin	Status	Purpose
`telegram`	Enabled	Telegram channel integration
`slack`	Enabled	Slack channel integration (socket mode)
`google-gemini-cli-auth`	Enabled	Google Gemini CLI authentication
`memory-core`	Enabled	Core memory backend
`memory-lancedb`	Disabled	Alternative memory backend

Channels

Telegram: DM policy "pairing", group allowlist, partial stream mode
Slack: Socket mode, allowlist policy, history limit 50

Skill Management

Skills installed via clawdhub CLI
Install directory: ~/clawd/skills/
Lock file: ~/clawd/.clawdhub/lock.json (tracks installed versions)
Skills discovered via SKILL.md files in skill directories

CRM System

Location: crm/ (tracked directly in this repo) Database: ~/clawd/crm/data/contacts.db Skill interface: skills/crm-query/ Stats: ~1,174 contacts tracked

What It Does

A personal CRM that automatically discovers contacts from email and calendar, tracks relationships with vector-based semantic search, integrates with Box for document relevance, supports AI-assisted email drafting, and provides a natural language query interface via Telegram. Operational CRM workflows (querying, follow-ups, meeting processing, and drafting handoffs) are documented in docs/USE-CASES-WORKFLOWS.md.

Contact Discovery

Scans Gmail and Google Calendar (last 365 days) via the gog CLI
Filters out newsletters, automated senders, large meetings (>10 people), internal domains (forwardfuture.ai)
Learning system (pattern-learner.js): builds skip patterns from approve/reject decisions, suggests auto-add mode after 50 decisions
Anti-injection security: sanitizes email content, blocks prompt injection patterns

Database Schema

Table	Purpose
`contacts`	Core contact info (name, email, company, role, priority, relationship_score)
`interactions`	Log of meetings, emails, calls, messages (includes `fathom_meeting_id` FK)
`follow_ups`	Scheduled reminders with due dates, snoozing, status tracking
`contact_context`	Timeline entries with 768-dim vector embeddings, direction, response time, topic tags
`contact_summaries`	LLM-generated relationship summaries with embeddings
`meetings`	Fathom meeting data (title, summary, transcript, attendees, action items)
`meeting_action_items`	Structured action items with assignee, ownership flag, status, due date, Todoist link
`merge_suggestions`	Duplicate contact detection with score, reasons, accept/decline workflow
`relationship_profiles`	Structured relationship analysis (type, style, topics, sentiment trend, interaction counts)
`learning_patterns`	Learned filtering patterns from approve/reject decisions
`rejected_contacts`	Tracking rejected candidate contacts with rejection counts
`sources`	Contact discovery source tracking
`meta`	Key-value store for sync cursors, last-handled timestamps, etc.
`box_files`	Box file metadata (name, path, extension, owner, etag, web URL, soft-delete flag)
`box_file_chunks`	Extracted text chunks with embeddings for semantic search
`box_file_collaborators`	Collaborator emails and roles per Box file
`contact_document_links`	Cached relevance links between contacts and Box files
`box_sync_state`	Box sync checkpoints
`email_draft_requests`	Gmail draft proposals with approval workflow (proposed→approved→drafted)
`urgent_notifications`	Urgent email notification tracking with feedback loop — stores each notification sent, dedup state, and natural language feedback for few-shot classifier learning

Architecture: Handler Modules (`crm/src/handlers/`)

The CRM query system is organized into modular handler files mixed into the main CRMService:

Handler	Purpose
`contacts.js`	Contact lookup, company queries, merge operations, sync triggers, stats
`follow-ups.js`	Follow-up creation, listing, marking done, snoozing
`interactions.js`	Interaction logging from natural language, nudge generation
`topics.js`	Semantic topic search across all contacts, source inspection (`show source #N`)
`documents.js`	Box document relevance queries per contact

Intent Detection (`crm/src/intent-detector.js`)

Natural language intent detector supporting these query types:

Intent	Example
`contact`	"Tell me about Mark", "Who is Sarah?"
`topic`	"Who have I talked to about fundraising?"
`log_interaction`	"I met with John today about the project"
`create_follow_up`	"Follow up with Lisa in 2 weeks"
`list_follow_ups`	"Show my follow-ups", "Follow-ups"
`mark_follow_up_done`	"Mark follow-up #3 done"
`snooze_follow_up`	"Snooze follow-up #2"
`nudges`	"Who needs attention?", "Who should I reach out to?"
`contact_documents`	"Show docs for Mark", "What files for Acme?"
`show_source`	"Show source #3" (evidence inspection from last query)
`merge_suggestions`	"Show duplicates"
`merge_accept` / `merge_decline`	"Accept merge #5"
`merge`	"Merge John and Jonathan"
`company`	"Who do I know at Google?"
`sync`	"Scan for new contacts"
`stats`	"How many contacts?", "Stats"

Scripts

Script	Purpose
`sync.js`	Manual contact discovery scan
`daily-sync.js`	Automated daily sync (runs via OpenClaw cron at 2am PST)
`batch-scan.js`	Batch contact scanning with rate limiting, classification, auto-approval, context updates, candidate export, Telegram notifications, incremental progress saving
`batch-scan-context.js`	Phase 5: scans recent inbound emails, matches to existing contacts, extracts context entries via LLM, generates embeddings, updates relationship summaries
`batch-scan-helpers.js`	Shared utilities for batch scanning (chunking, date parsing, email extraction, candidate classification, contact approval)
`process-context.js`	Extract timeline entries from emails using LLM
`backfill-context.js`	Full-history email backfill for all contacts, relationship profile generation
`box-sync.js`	Box folder sync - indexes files, extracts content, generates embeddings, computes contact relevance. Flags: `--force`, `--max-files=N`, `--rebuild-links`
`fathom-sync.js`	Sync Fathom meetings - `--poll` and `--backfill` modes
`fathom-after-meetings.js`	Calendar-aware Fathom polling - checks today's meetings, triggers poll after meeting end + buffer (default 20 min). Replaces static scheduling with dynamic, meeting-aware triggers.
`fathom-approve.js`	Approve verified action items from Fathom, push to Todoist
`schedule-fathom-poll.js`	Legacy: dynamically schedule Fathom polling via launchd (superseded by `fathom-after-meetings.js`)
`merge-contacts.js`	Merge duplicate contacts by ID or email
`query.js`	CLI query interface for natural language queries
`verify-context-system.js`	Verification script for context system
`urgent-email-check.js`	Scan recently-ingested inbound emails for urgency. Pre-filters noise senders, classifies via LLM with few-shot learning from feedback, sends notifications to CRM topic 709. Gates on notification windows (weekdays 5-9pm, weekends 7am-9pm PST).
`health-check.js`	CRM database health monitor. Checks integrity, detects contact count drops (> 20% = alert), verifies key tables, monitors ingestion activity. Stores baseline in meta table. Runs after nightly ingestion.
`restore-from-backups.js`	One-time recovery script that merges data from two partially-corrupt backups, picking the best available version of each table.
`urgent-feedback.js`	Process natural language feedback on urgent notifications. Interprets Matt's reply via LLM to extract verdict (useful/noise) and generalized reasoning. Supports `--id <N>` or `--latest`.
`migrate.js`	General database migration runner - calls Schema to run all pending migrations
`migrate-context.js`	Migration script for `contact_context` table and indexes
`seed-test-data.js`	Seeds database with fake test data (contacts, interactions, follow-ups) for development
`fathom-poll-oneshot.sh`	Ephemeral one-shot Fathom poll trigger - runs `fathom-sync.js --poll` then self-unloads its launchd plist
`run-context-tests.sh`	Test runner for the context system - installs deps, runs migration, executes tests

Core Service (`crm/src/`)

Module	Purpose
`index.js`	Main `CRMService` class - wires together all DB modules, intelligence, ingestion, context, handlers, Box, and Gmail. Singleton entry point.
`config.js`	CRM configuration management - loads `.env`, resolves paths, provides defaults for all CRM settings
`intent-detector.js`	Natural language intent detection - classifies queries into 16 intent types (contact, topic, follow-up, nudge, merge, sync, stats, documents, etc.)
`query-helpers.js`	Shared query helper methods mixed into CRMService - contact resolution by email/name, date parsing, formatting

Database Access Layer (`crm/src/db/`)

Module	Purpose
`schema.js`	Database schema creation and all migrations (20 tables, indexes, column additions)
`contacts.js`	Contact CRUD - search, create, update, delete, by-email/name lookup
`interactions.js`	Interaction logging - create, query by contact/date/type
`followups.js`	Follow-up CRUD - create, list pending/overdue, snooze, mark done
`merge-suggestions.js`	Duplicate detection - suggest, accept, decline merge candidates
`learning.js`	Pattern storage for learned contact filtering rules
`email-draft-requests.js`	Email draft proposal lifecycle - propose, approve, mark drafted/cancelled/error
`meeting-action-items.js`	Action item storage - create, query by meeting/contact/assignee, mark done, Todoist linking
`rejections.js`	Rejected contact candidate tracking with counts
`meta.js`	Key-value store for sync cursors, last-handled timestamps, and runtime state

Contact Ingestion Pipeline (`crm/src/ingestion/`)

Discovers contacts from email and calendar, classifies them, and manages the approval workflow.

Module	Purpose
`email-scanner.js`	Scans Gmail thread metadata via `gog` CLI to discover contact candidates
`calendar-scanner.js`	Scans Google Calendar events via `gog` CLI to discover contacts from meetings
`contact-extractor.js`	Merges email and calendar candidates, deduplicates, extracts contact info
`batch-approver.js`	Batch approval workflow for new contact candidates with interactive approve/reject
`ingest-utils.js`	Shared ingestion utilities - date parsing, clamping, helper functions

Telegram Interface (`crm/src/telegram/`)

Bot UI for CRM interactions via Telegram.

Module	Purpose
`commands.js`	Telegram command handlers - routes messages to CRM query handlers, manages conversation flow
`menu.js`	Interactive menu system - inline keyboard menus, pagination, selection for contact actions
`formatters.js`	Output formatting - contact display, truncation, emoji, Telegram-safe markdown

Context System (`crm/src/context/`)

Extracts and stores relationship context from email history with semantic search.

Module	Purpose
`email-fetcher.js`	Fetches emails via `gog` CLI
`email-body.js`	Email body extraction and cleaning
`extractor.js`	Extracts timeline entries with direction/topics using LLM
`embeddings.js`	Embedding generation (Google/OpenAI)
`storage.js`	Stores timeline entries with deduplication
`search.js`	Semantic and text search over context entries
`summary-storage.js`	Stores relationship summaries
`relationship-summarizer.js`	Generates LLM-powered relationship summaries
`response-generator.js`	Generates natural language responses to queries

Box Integration (`crm/src/box/`)

Indexes Box files and links them to CRM contacts via hybrid relevance scoring.

Module	Purpose
`client.js`	Box API v2.0 client - folder listing, tree traversal (max depth 5), file download, collaborator lookup. Bearer token auth.
`relevance.js`	Hybrid relevance scoring: collaborator match (45%), semantic similarity (25%), lexical match (20%), recency (10%). Returns ranked results with component breakdowns and human-readable reasons.
`storage.js`	SQLite storage for files, chunks, collaborators, contact-document links, and sync state
`sync-service.js`	Full sync workflow: folder scan → file processing (content extraction, chunking, embedding) → cleanup → contact linking. Skips unchanged files via etag. Batch embeddings (8 at a time).

Config: BOX_ENABLED, BOX_ACCESS_TOKEN, BOX_ROOT_FOLDER_ID in ~/.openclaw/.env (available via CRM compatibility symlink) Cache: File downloads cached to ~/clawd/crm/data/box-cache/

Gmail Draft System (`crm/src/gmail/`)

AI-assisted email drafting with CRM context and a two-phase approval workflow. Draft-only - no send operations.

Module	Purpose
`gmail-client.js`	Minimal Gmail wrapper via `gog` CLI - thread search, thread fetch, draft creation/update. Read-only + draft operations.
`email-draft-coordinator.js`	Main workflow orchestrator: search Gmail by subject → score candidates (Jaro-Winkler similarity + recency) → extract CRM/Fathom context → generate suggestion → store as "proposed". Approval flow: proposed → approved → drafted (Gmail draft created).
`reply-suggester.js`	LLM-based reply generation using Gemini Flash Lite. Takes thread context, CRM contact info, CRM evidence, and Fathom meeting summaries. Outputs structured JSON with subject, body, assumptions, questions, and facts used.

Safety gate: GMAIL_DRAFT_WRITES_ENABLED=true required to create Gmail drafts Workflow: User provides subject → AI proposes reply → user reviews in Telegram → approval creates Gmail draft

Relationship Intelligence (`crm/src/intelligence/`)

Module	Purpose
`contact-classifier.js`	Classifies contacts by relevance/priority
`contact-filter.js`	Filters contacts based on learned patterns
`relationship-profiler.js`	Generates relationship profiles (type, communication style, key topics)
`relationship-scorer.js`	Calculates 0–100 health scores based on recency, frequency, priority, interaction quality
`nudge-generator.js`	Generates relationship health nudges for contacts needing attention
`pattern-learner.js`	Learns from approval/rejection decisions to improve filtering

Utilities (`crm/src/utils/`)

Module	Purpose
`gog-runner.js`	Wrapper for `gog` CLI with retry/backoff
`llm.js`	Unified multi-provider LLM client (Google/OpenAI/Anthropic). Supports Gemini thinking budget. Used across CRM for text generation.
`openclaw-config.js`	Thin wrapper re-exporting `loadApiCredentials()` and `loadEmbeddingCredentials()` from shared config
`openclaw-wake.js`	Wake OpenClaw gateway with a message via CLI
`string-similarity.js`	String similarity calculations for contact matching (Jaro-Winkler)

Natural Language Queries

Supports queries like "What do I know about Mark?" via intent detection and semantic search over context embeddings. Accessed through the crm-query skill or Telegram (topic 709).

Fathom Meeting Integration

Location: crm/src/fathom/

What It Does

Automatically processes Fathom meeting recordings into CRM contacts, interactions, context entries, and action items with an approval workflow.

Components

Component	File	Purpose
API Client	`api-client.js`	Fetches meetings, transcripts, summaries, action items from Fathom API
API Keys	`api-keys.js`	Manages Fathom API key loading from config
Calendar	`calendar.js`	Calendar integration helpers - fetches today's events via `gog`, filters for likely Fathom meetings (timed, has external attendees, 15+ min, ≤10 attendees)
After-Meetings Logic	`after-meetings-logic.js`	Pure logic for computing fire times (meeting end + buffer) and determining when polls should run
Processor	`processor.js`	Matches attendees to CRM contacts by email, extracts insights via Gemini 2.5 Flash Lite, creates context entries with embeddings, updates relationship summaries
Notifier	`notifier.js`	Sends Telegram notifications, manages approval queue for action items
Todoist Client	`todoist.js`	Creates Todoist tasks from approved action items

Workflow

See docs/USE-CASES-WORKFLOWS.md for the step-by-step operational flow ("Meeting -> CRM context -> action items -> Todoist"). This section keeps component and implementation inventory in one place.

Modes

Flag	Purpose
`--poll`	Fetch new meetings since last poll (for cron)
`--backfill`	Pull historical meetings (default 90 days)

Scripts

Script	Purpose
`fathom-sync.js`	Main entry point for polling and backfill
`fathom-after-meetings.js`	Calendar-aware triggering - runs frequently, checks today's meetings, fires poll after meeting end + buffer. Tracks last handled fire time in meta table to avoid duplicate runs.
`fathom-approve.js`	Approve pending action items, push to Todoist
`schedule-fathom-poll.js`	Legacy: dynamically schedule polling via launchd (superseded by `fathom-after-meetings.js`)

Skills

Location: skills/ (22 installed) and skills-preview/ (2 in development)

Installed Skills

browser-control

Purpose: Chrome browser automation via Puppeteer + CDP (Chrome DevTools Protocol). Connects to a running Chrome instance with a real user profile (cookies/sessions intact), not headless.
Commands:
- node scripts/browse.js navigate "<url>" [--wait load|networkidle|domcontentloaded|<ms>]
- node scripts/browse.js screenshot [--full-page] [--output path.png]
- node scripts/browse.js extract [--selector "css"] [--attribute href]
- node scripts/browse.js click --selector "css"
- node scripts/browse.js type --selector "css" --text "..." [--clear] [--enter] [--delay ms]
- node scripts/browse.js tabs
- node scripts/browse.js eval "<js expression>"
- node scripts/browse.js pdf [--output path.pdf]
- node scripts/browse.js wait <ms>
Config: Chrome must be running with remote debugging (bash scripts/launch-chrome.sh). Uses dedicated debug profile at ~/clawd/data/chrome-debug-profile/ (separate from personal Chrome).
Dependencies: puppeteer-core v24.2.0
Port: 9222 (configurable)

clawdhub

Purpose: Search, install, update, and publish skills from clawdhub.com
Commands: clawdhub search, install, update, list, publish
Config: Requires clawdhub npm package installed globally
API: ClawdHub registry (https://clawdhub.com)

crm-query

Purpose: Natural language CRM queries - contacts, relationships, follow-ups, interaction logging
Commands: cd ~/clawd/crm && node scripts/query.js "<question>"
Database: ~/clawd/crm/data/contacts.db
API: OpenClaw API for embeddings/LLM, optional gog CLI for email/calendar

beehiiv

Purpose: Beehiiv newsletter platform API -- subscriber management, post analytics, segments, automations, custom fields, tiers, referral program, webhooks
Commands: Documentation-only (curl templates)
Config: Requires BEEHIIV_API_KEY and BEEHIIV_PUBLICATION_ID environment variables
API: Beehiiv REST API v2

hubspot

Purpose: HubSpot CRM/CMS API integration - contacts, companies, deals, content management
Commands: Documentation-only (curl/PowerShell templates)
Config: Requires HUBSPOT_ACCESS_TOKEN environment variable
API: HubSpot REST API

humanizer (v2.1.1)

Purpose: Removes AI writing patterns based on Wikipedia's "Signs of AI writing" guide
Detects: 24 patterns including inflated symbolism, promotional language, em dash overuse, rule of three, AI vocabulary, etc.
Commands: None (invoked via agent skill call)
Config: None required

knowledge-base

Purpose: RAG system - ingest articles, videos, tweets, PDFs; query via natural language
Commands:
- node scripts/ingest.js "<url>" [--tags X] [--title Y] [--type Z] [--no-browser] [--dry-run]
- node scripts/ingest-and-crosspost.js "<url>" [--tags X] [--no-slack] - Combines ingestion + Slack #ai_trends cross-post in a single deterministic script. Keeps untrusted page content out of the agent loop. Cleans summaries for Slack (strips metadata, tracking params). Used by Telegram KB topic automation.
- node scripts/query.js "<question>" [--limit N] [--threshold X] [--tags Y]
- node scripts/list.js [--tag X] [--type Y] [--recent N]
- node scripts/delete.js <source_id>
- node scripts/stats.js
- node scripts/bulk-ingest.js <file> [--tags X] [--retries N]
Database: ~/clawd/skills/knowledge-base/data/knowledge.db
API: OpenClaw (embeddings), FxTwitter (X/Twitter URLs), optional Firecrawl, Apify, Grok
Lock file: ~/clawd/skills/knowledge-base/data/.ingest.lock
Config: Requires summarize CLI (brew install steipete/tap/summarize)

financials

Purpose: Financial data queries from CSV exports (source-agnostic) - query revenue, expenses, P&L, balance sheet, invoices, bills, AR/AP via natural language
Commands:
- node scripts/query.js "<financial question>" - Natural language query from cache
- node scripts/query.js --report ProfitAndLoss|BalanceSheet - Specific reports
- node scripts/query.js --invoices open / --bills open / --expenses --days 30
- node scripts/query.js --accounts / --sync-status
- node scripts/import.js <file.csv> [--delete] - Import financial CSV exports
- node scripts/import.js --dir <path> - Import all CSVs from a directory
- node scripts/generate-reports.js [--year N] [--period ytd|last_year] - Generate P&L and Balance Sheet from transactions
Data flow: Matt exports CSVs from the accounting system (Transaction List, Account List) and sends via Telegram financials topic (2774). Import script auto-detects type, imports, generates P&L/Balance Sheet, deletes source file.
Database: ~/clawd/skills/financials/data/financials.db
Confidentiality: Financial data is strictly confidential - only shared with Matt directly (DM or financials topic). Council digests reference financial health directionally, not specific dollar amounts.
Cron: Monthly reminder on the 1st at 10am PST to export fresh financial data
Council: Feeds financial signals (revenue, expenses, net income, cash position, AR/AP, burn rate, overdue invoices) into nightly business meta-analysis; CFO reviewer persona analyzes the data
Tests: node --test tests/*.test.js (45 tests covering DB, reports, import, client)

model-usage-tracker

Purpose: Track AI model usage, costs, and token consumption across providers (Anthropic, OpenAI, Google, xAI)
Commands:
- ./log-usage.js <model> <tokens_in> <tokens_out> <task_type> <description>
- ./generate-report.js [--days N] [--model X] [--task-type Y]
Storage: JSONL log at ~/.openclaw/logs/model-usage.jsonl

nano-banana-pro-2

Purpose: Image generation/editing via Google Gemini 3 Pro Image API
Commands:
- uv run scripts/generate_image.py --prompt "<desc>" --filename "out.png" [--resolution 1K|2K|4K]
- Supports single generation, single edit (with -i), multi-image composition (up to 14 images)
Config: Requires uv (brew install uv), GEMINI_API_KEY
Output: MEDIA:<path> line for agent runtimes

self-improving-agent

Purpose: Log learnings, errors, and corrections for continuous improvement
Storage: Markdown files in .learnings/ (LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md)
Hooks: activator.sh (UserPromptSubmit), error-detector.sh (PostToolUse)
Commands: scripts/extract-skill.sh <skill-name> [--dry-run]

summarize

Purpose: Summarize URLs, local files, and YouTube links
Commands: summarize "<url>" [--model X] [--length Y] [--extract-only] [--json] [--firecrawl auto]
Config: Requires summarize CLI (brew install steipete/tap/summarize)
API: Multiple LLM providers (OpenAI, Anthropic, xAI, Google)

todoist

Purpose: Task management via Todoist CLI - tasks, projects, labels, comments, natural language due dates
Commands: todoist [today], todoist tasks, todoist add, todoist done, todoist search, etc.
Config: Requires todoist-ts-cli npm package, TODOIST_API_TOKEN

video-idea-pipeline

Purpose: Convert video ideas into researched Asana cards with X/Twitter tweets and KB sources
Workflow: Agent searches X → queries KB → creates Asana task in Video Pipeline project
Trigger: User says "potential video idea" in Slack/Telegram
Dependencies: x-research-v2 skill, knowledge-base skill, Asana API

x-research-v2

Purpose: X/Twitter research - search, profiles, threads, single tweets, watchlists, caching
Commands:
- bun run x-search.ts search "<query>" [--sort X] [--min-likes N] [--pages N] [--limit N] [--save] [--json]
- bun run x-search.ts profile <username>, thread <id>, tweet <id>, watchlist, cache clear
Config: Requires bun runtime, X_BEARER_TOKEN
API: X/Twitter API v2 (~$0.005/tweet read), 350ms rate limiting
Cache: File-based at data/cache/ (15-min TTL)

x-analytics

Purpose: X/Twitter per-post analytics - collect and query detailed engagement metrics (impressions/views, likes, replies, retweets, bookmarks, shares, follows, unfollows, media views, URL clicks, profile clicks, app installs, email shares)
Commands:
- python3 ~/clawd/tools/social-tracker/x_collect.py - Collect analytics for last 30 days
- python3 ~/clawd/tools/social-tracker/x_collect.py --backfill 90 - Backfill last 90 days
- python3 ~/clawd/tools/social-tracker/x_query.py summary - Overall stats
- python3 ~/clawd/tools/social-tracker/x_query.py top [--metric X] [-n N] - Top posts
- python3 ~/clawd/tools/social-tracker/x_query.py post POST_ID - Single post details
- python3 ~/clawd/tools/social-tracker/x_query.py trends [--days N] - Aggregate trends
- python3 ~/clawd/tools/social-tracker/x_query.py list [--sort X] [--limit N] - List all posts
Database: tools/social-tracker/db/social_growth.db (tables: x_posts with public_metrics view counts, x_post_stats hourly snapshots)
View tracking: Dual collection — public_metrics.impression_count stored in x_posts.view_count (always available), plus impressions from analytics endpoint in hourly snapshots (richer metrics, 30-day window). Falls back to public_metrics when analytics unavailable.
Auth: OAuth 1.0a via X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET in ~/.openclaw/.env
Note: Audience demographics (age, gender, device, country) are dashboard-only, not available via API

x-search

Purpose: Backward-compatible wrapper around x-research-v2
Fallback: Grok x_search if X API unavailable, Cursor agent as default/best-effort
Commands: ./search.sh "<query>" or search.py "<query>"
Config: XSEARCH_PROVIDER env var (cursor, xai, direct)

excalidraw

Purpose: Generate hand-drawn style diagrams, flowcharts, and architecture diagrams as PNG images from Excalidraw JSON
Commands: node scripts/render.js <input.excalidraw> <output.png>
Features: Element types (rectangle, ellipse, diamond, arrow, line, text), arrow binding with auto-edge calculation, inline labels on shapes, multi-segment routing, styling (hachure/cross-hatch/solid fills, roughness control)
Templates: Flowchart with decision branches, layered architecture diagram
Config: None required

gemini-video-watch

Purpose: Upload and analyze videos with Gemini 3 Pro - local files, Telegram uploads, YouTube URLs, or direct video URLs
Commands: node scripts/watch.js "<video_path_or_url>" --prompt "<prompt>" [--model X] [--temperature X] [--delete-file]
Features: Resumable upload to Gemini Files API, native YouTube URL support (no download), auto-download for direct video URLs, customizable model/temperature/tokens
Config: Requires GEMINI_API_KEY (from ~/.openclaw/openclaw.json or env var)

x-trending-scraper

Purpose: Fetch trending/viral tweets with real engagement metrics
Commands: ./scrape-trending.sh [query] [min_views] or python3 scrape_trending.py "<query>" <min_views>
Dependencies: x-research-v2 skill, bun runtime

youtube-sub-ratio

Purpose: Analyze YouTube videos by subscriber-to-view conversion ratio
Commands: ./analyze.sh [days] [min_views] [top_n]
Note: Subscriber data lags 24-72+ hours; best for videos 5+ days old
Config: Requires YouTube API OAuth token at ~/clawd/tools/social-tracker/token.json

Preview Skills (In Development)

content-draft-generator

Purpose: Generate content drafts based on reference content analysis
Workflow: Analyze references → extract patterns → generate context questions → create meta-prompt → two-phase generation (interview + 3 variations)
Storage: File-based in references/, content-breakdown/, content-anatomy/, etc.

research

Purpose: Deep research via Gemini CLI in background subagent (uses Google AI subscription instead of Claude tokens)
Commands: Spawns gemini --yolo subagent
Output: Saves to ~/clawd/research/<slug>/research.md
Trigger: User says "Research: [topic]" or asks for deep research

Tools

Location: tools/

Video Pitches Database (`tools/video-pitches/`)

SQLite-backed system for tracking video pitch ideas with semantic search. Enforces the video pitch hard gate rule in AGENTS.md (must search before pitching; skip if >40% similarity match).

Script	Purpose
`add.js`	Add a pitch - generates Gemini embeddings, auto-IDs (YYYY-MM-DD-NNN), auto-slug
`search.js`	Semantic + keyword search (70% cosine similarity, 30% keyword matching)
`list.js`	List recent pitches with filters (type, status, date range)
`update.js`	Update status: pitched, accepted, rejected, produced, duplicate
`migrate.js`	Migrate from JSON (`memory/video-pitches.json`) to SQLite
`db.js`	Database module with schema, embedding storage, similarity calculations

Database: ~/clawd/data/video-pitches.db

Social Tracker (`tools/social-tracker/`)

YouTube analytics collection, querying, and charting. Instagram per-post analytics. X/Twitter per-post analytics. Also tracks Instagram and TikTok profile growth.

Script	Purpose
`collect.py`	Main YouTube analytics collection - OAuth via Google credentials, daily snapshots, incremental updates and backfill. Collects video metadata (title, description, tags, category, duration) and daily analytics (views, watch time, avg view duration/percentage, likes, dislikes, comments, shares, subscribers gained/lost, thumbnail impressions, thumbnail CTR)
`query.py`	CLI for querying YouTube analytics: `list`, `video`, `top`, `trends`, `summary`, `live [VIDEO_ID]` (real-time stats from Data API, defaults to latest video)
`charts.py`	Generate PNG charts (trend per video, top videos bar chart, daily channel-wide) with dark theme
`ig_collect.py`	Instagram per-post analytics collector - Meta Graph API, fetches insights for all posts (views, reach, likes, comments, saves, shares, follows, reel view time) and account-level daily snapshots (followers, following, media count, profile views, website clicks, reach, accounts engaged). Run with `--refresh` to extend token (updates both local and canonical .env).
`ig_query.py`	CLI for querying Instagram per-post data: `summary`, `top [--metric views\|reach\|likes\|shares\|saved\|engagement] [-n 10]`, `post MEDIA_ID`, `trends [--days 30]`, `list [--sort date\|views\|likes\|reach] [--type VIDEO]`
`x_collect.py`	X/Twitter per-post analytics collector - X API v2 Enterprise analytics endpoint with OAuth 1.0a. Stores public_metrics view counts from tweets endpoint as fallback. Fetches detailed metrics (impressions/views, likes, retweets, bookmarks, shares, follows, unfollows, media views, URL clicks, profile clicks, app installs, email shares). Supports `--backfill N` and `--ids ID1,ID2`.
`x_query.py`	CLI for querying X/Twitter per-post data: `summary`, `top [--metric impressions\|likes\|retweets\|bookmarks\|follows] [-n 10]`, `post POST_ID`, `trends [--days 30]`, `list [--sort impressions\|likes] [--limit N]`
`social_query.py`	Query Instagram/TikTok profile growth data: `summary`, `growth`, `history` commands
`social_scrape.py`	Scrape public Instagram/TikTok profile metrics (followers, posts, likes, bio)
`quick_sub_ratio.py`	Quick subscriber-to-view ratio analysis via YouTube Analytics API (no local storage)
`top_subscriber_ratio.py`	Top videos by sub-to-view ratio from stored database data

Databases: db/views.db (YouTube videos + daily_stats with description/tags/category), db/social_growth.db (IG per-post + IG account daily snapshots + X/Twitter per-post with public_metrics + IG/TT profile growth), db/youtube_data.db Charts: Generated PNGs saved to charts/ directory Stats: ~963 YouTube videos, ~190 Instagram posts tracked Auth: YouTube OAuth via gog credentials (token.json); Instagram via Meta Graph API long-lived token (~/.openclaw/.env, refresh every 60 days with ig_collect.py --refresh); X/Twitter via OAuth 1.0a user context (X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET in ~/.openclaw/.env)

Cron Log (`tools/cron-log/`)

Centralized cron job logging system. Every cron job in the workspace logs to this database.

Script	Purpose
`log-start.js`	Log cron job start, returns run ID
`log-end.js`	Log completion with status (success/failure), duration, summary, optional error message
`query.js`	Query cron run history by job name, status, date range, limit
`checkpoint.js`	Step-level idempotency for multi-step cron jobs. Tracks checkpoints per job+job-id+step. Statuses: started/done/skipped/failed. Exit code 3 = terminal checkpoint found (caller can skip). Prevents regression of terminal statuses.
`should-run.js`	Job-level idempotency helper. Checks if a job+job-id already succeeded. Exit code 0 = should run, 2 = should skip (already succeeded).
`check-persistent-failures.js`	Detects jobs with persistent failures (consecutive failures or high failure rate). Alerts via Telegram. Integrated into health check cycle and platform council for deeper root-cause analysis.
`cleanup-stale.js`	Cleans up stale "running" status jobs that crashed or were interrupted by machine sleep/shutdown. Can run standalone or be called by log-start.js.
`db.js`	SQLite connection and schema management

Database: ~/clawd/data/cron-log.db

Standalone Tools

Tool	Purpose
`business-meta-analysis/`	Advisory-only analysis engine that aggregates business signals across 14 OpenClaw data sources (YouTube, Instagram post performance, Instagram account growth, X/Twitter post analytics, X/Twitter trend signals, CRM, cron reliability, HubSpot pipeline + contacts, Slack, Asana, email, Fathom meetings, financials, Beehiiv newsletter). Uses parallel independent expert architecture: 8 domain-filtered experts (GrowthStrategist, RevenueGuardian, SkepticalOperator, TeamDynamicsArchitect, AutomationScout, CFO, ContentStrategist, MarketAnalyst) analyze their relevant data slices in parallel, then a synthesizer merges their findings into ranked recommendations. Each expert only sees signals from their tagged sources plus a cross-domain brief. Calls model provider APIs directly (auto-detects from openclaw.json: prefers Anthropic, falls back to OpenAI/Google). Stores full analysis snapshots and recommendation history in SQLite, delivers digest reports to Telegram group `-1003725393532` thread `1827`. Learns from feedback.
`agent-wrapper.sh`	Wraps cursor-agent CLI to log prompt/response sizes to `/tmp/openclaw/agent-usage.log`
`session-activity.js`	Visualize session transcripts - tokens, tool calls, subagent costs, error breakdowns. Saves metrics to `~/clawd/metrics/YYYY-MM-DD.json`
`asana-fetch.js`	Fetch tasks from Asana projects (default: Video Pipeline). Shows task details, completion status, due dates, assignees
`asana-quick-fetch.py`	Compatibility wrapper that delegates to `asana-fetch.js`
`log-parser.py`	Parse JSON log lines from OpenClaw logs - extracts model calls, tokens, subagent spawns, displays formatted table
`log-viewer.sh`	View OpenClaw logs with filtering, watch mode, date selection, usage log mode (`-u`), color output
`usage-parser.py`	Parse `model-usage.jsonl` for token counts by task type (subagent/conversation/direct), color-coded output
`slack-post.js`	Post messages to Slack channels via API. Works from any context (Telegram sessions, subagents, cron jobs). Supports channel names or IDs, threaded replies. Usable as CLI or `require()` module.
`slack-react.js`	Add emoji reactions to Slack messages. Supports channel + timestamp targeting and optional `--emoji` override (defaults to eyes). Usable as CLI or `require()` module.
`usage-dashboard.js`	Centralized usage dashboard - model tokens/costs, cron reliability, database sizes, X API calls, session activity. Flags: `--days N`, `--all`, `--section <name>`, `--json`.
`log-hub.js`	Unified log viewer. Reads `~/clawd/data/logs/all.jsonl` and supports filters (`--event`, `--level`, `--contains`, `--since`, `--limit`, `--json`) for single-pane troubleshooting.
`log-ingest.js`	Nightly JSONL -> SQLite ingestor for structured logs. Reads unified stream (`all.jsonl` + rotated `all.jsonl.N`) and writes deduped rows to `~/clawd/data/logs.db`.
`gateway-log-ingest.js`	Nightly raw-log -> SQLite ingestor for OpenClaw gateway logs. Reads `~/.openclaw/logs/gateway.log` and `gateway.err.log` (+ rotations) into `~/clawd/data/logs.db` table `gateway_log_lines`.
`redact-message.js`	CLI tool for redacting secrets from outbound notification messages. Reads from stdin or args, uses `notification-redaction.js`. Usage: `echo "..." \| node tools/redact-message.js` or `node tools/redact-message.js "message text"`
`log-event.js`	CLI tool for logging structured JSONL events to `~/clawd/data/logs/<event_name>.jsonl`, mirrored into unified stream `~/clawd/data/logs/all.jsonl`. Accepts `--event`, `--level`, and `--field key=value` args. Auto-parses field values (JSON, numbers, booleans, strings).
`openclaw-slack-status.js`	Diagnostic tool for OpenClaw Slack connection status. Finds gateway PID, lists established TCP connections, probes TLS certificates to identify services (Slack, Telegram, etc.), tails gateway.log for recent `[slack]` lines. Outputs JSON or human-readable format.

Patches (`tools/patches/`)

Documentation of patches applied to enhance OpenClaw logging. Notes deprecated patches and current logging methods.

Shared Modules

Location: shared/

Reusable Node.js utilities used across CRM, skills, and tools.

Module	Purpose
`db.js`	SQLite database opener - WAL mode, foreign keys, auto-creates directories. Includes `addColumnIfMissing()` helper
`embeddings.js`	Unified `EmbeddingGenerator` class - Google `gemini-embedding-001` (768-dim) or OpenAI `text-embedding-3-small` (1536-dim), LRU cache, batch generation, retry with exponential backoff
`config.js`	API credential loader from `~/.openclaw/openclaw.json`. Exports `loadApiCredentials()` and `loadEmbeddingCredentials()` with provider preference
`args.js`	CLI argument parser - handles `--key value` and `--key=value` formats, supports defaults
`reranker.js`	`Reranker` class - LLM-based reranking using Gemini Flash for two-stage search (retrieve → rerank), scores results 0–1
`review-council.js`	Reusable review-council workflow for multi-agent analysis. Provides the sequential draft-review-consensus pipeline (used by security and platform councils via OpenClaw agent), plus exported utilities (mapWithConcurrency, compactPayload, callWithRetries, parseJsonFromText) reused by the business meta-analysis independent council. Emits per-agent progress events (`review_council_progress`) into the standard JSONL log stream.
`cursor-council.js`	Shared Cursor agent CLI infrastructure for council scripts. Provides `runCursorAgent()` (agent analysis pass), `runSummarizer()` (structured JSON output pass), and `parseJsonFromResponse()` (robust JSON extraction from LLM text). Used by security-council-v2.js and platform-council-v2.js.
`workspace-state.js`	PID-based lock management for workspace state. Detects stale locks from crashed processes and provides safe lock acquisition/release. Used by auto-git-sync.sh and business meta-analysis.
`council-recommendations.js`	Shared recommendation ID management for council systems. Generates unique recommendation IDs and provides deduplication logic.
`telegram-delivery.js`	Telegram message delivery helper with formatting and error handling. Wraps message tool for consistent delivery patterns.
`env-utils.js`	Environment variable utilities for runtime overrides (CLAWD_LOG_LEVEL, CLAWD_LOG_DIR, etc.).
`REVIEW-COUNCIL-LEARNINGS.md`	Review council operational learnings and reliability runbook. Documents isolation handling, model drift patterns, and consensus output requirements.
`content-sanitizer.js`	Content sanitization module - detects and blocks prompt injection attempts, sanitizes untrusted content from web pages, tweets, Slack/Telegram messages, Asana/HubSpot records, transcripts, KB excerpts, uploaded files
`fs.js`	File system utilities - safe file operations with atomic writes, directory creation helpers
`notification-redaction.js`	Notification-specific secret redaction - sanitizes outbound messages before sending to Telegram/Slack/email, wraps `secret-redaction.js` with notification-safe defaults
`secret-redaction.js`	Secret detection and redaction - identifies credential-looking strings (API keys, bearer tokens, passwords) and replaces with `[REDACTED]` placeholders
`event-log.js`	Structured JSONL event logging - writes events to `~/clawd/data/logs/<event_name>.jsonl` and mirrors every record to unified stream `~/clawd/data/logs/all.jsonl`. Includes timestamps, hostname, log level filtering, auto-redaction of secrets, field type parsing, string truncation.
`interaction-store.js`	Centralized SQLite store for all API and LLM interactions - stores full request/response bodies in `~/clawd/data/interactions.db` with `llm_calls` and `api_calls` tables. Fire-and-forget `logLlmCall()` and `logApiCall()` functions. Used alongside JSONL logging for structured query access.
`log-rotation.js`	Log rotation for JSONL files and interactions DB - rotates .jsonl files exceeding 50MB (keeps last 3 rotations), archives interactions DB rows older than 90 days into monthly archive DBs. CLI: `node shared/log-rotation.js [--dry-run]`
`log-ingest-utils.js`	Shared helper utilities for log ingest tools (positive integer normalization and safe regex escaping) to keep `log-ingest.js` and `gateway-log-ingest.js` behavior aligned.
`event_log.py`	Python equivalent of event-log.js - writes per-event JSONL logs and mirrors to `~/clawd/data/logs/all.jsonl` for unified searching. Used by Python tools (social-tracker, nano-banana-pro-2) that can't import Node.js modules.

Scripts & Automations

Location: scripts/

Script	Purpose
`auto-git-sync.sh`	Auto-commit and push changes to GitHub. Syncs two repos in order: `~/.openclaw/`, `~/clawd/` (which now includes `crm/`). Pulls before pushing, handles merge conflicts, sends Telegram notification on failure. Uses cron-log for tracking. Validates main branch and remote state before push.
`backup-databases.sh`	Discovers all `.db`/`.sqlite` files across workspace, backs up to Google Drive ("OpenClaw Backups" folder), creates `manifest.json` for restore, keeps last 7 backups. Also backs up JSONL event logs (including unified stream `all.jsonl`), honors `CLAWD_LOG_DIR` / `CLAWD_UNIFIED_LOG_FILE`, and ensures unified log file exists before staging.
`action-items-briefing.js`	Asana-based action-items briefing for daily prep. Reads `data/asana-sync.db` and emits OVERDUE, ACTION ITEMS, and WAITING ON sections.
`nightly-log-ingest.sh`	Deterministic nightly ingest of logs into SQLite. Runs both `tools/log-ingest.js --json` (structured JSONL) and `tools/gateway-log-ingest.js --json` (gateway raw logs), records run state in cron-log, and posts completion/failure summary to cron-updates.
`council-deeper-dive.js`	Council recommendation detail lookup and optional Telegram send for platform/security council recommendations. Usage: `node scripts/council-deeper-dive.js --council <platform
`restore-databases.sh`	Restores SQLite databases from Google Drive backup using `manifest.json`. Supports `--list` (preview) and `--force` (skip prompts) modes.
`daily-crm-ingestion.sh`	Deterministic daily CRM ingestion (2am PST). Runs `batch-scan.js` with 1-day lookback, concurrency 3, 1500ms delay. Parses structured summary line for contacts_added, new_candidates, context_entries_added, errors. Sends Telegram notifications. Uses cron-log + `should-run` for idempotency.
`openclaw-update-check.sh`	Deterministic OpenClaw update check. Runs `openclaw update status` (read-only), posts output to Telegram updates thread. Uses cron-log for idempotency.
`sunday-trash-reminder.sh`	Sunday recycling/trash reminder. Calculates recycling type (PAPER/CONTAINER) using a weekly cycle anchored to Jan 31, 2026. Sends reminder DM to Matt. Uses cron-log for idempotency.
`weekly-letter-reminder.sh`	Weekly company letter reminder. Sends reminder DM to Matt. Uses cron-log for idempotency.
`security-review.sh`	Automated security checks - file permissions (.env, .db files, openclaw.json, system prompts), gateway binds to loopback only, auth enabled, no secrets in git-tracked files, security modules wired in, backup encryption, prompt injection patterns, .gitignore rules intact, error log review for auth failures. Outputs JSON findings array. Exit codes: 0=passed, 1=findings, 2=error. Uses `lib/security-review-checks.sh` for check implementations.
`security-council-v2.js`	Security council using Cursor agent CLI for direct codebase analysis + Opus summarizer for structured JSON output. Runs security-review.sh, inspects files/permissions/code directly, analyzes from four security perspectives (offensive, defensive, data privacy, operational realism). Replaces the multi-agent review-council approach. Usage: `node scripts/security-council-v2.js [--dry-run] [--json]`
`security-council.js`	Removed. Replaced by security-council-v2.js.
`rotate-logs.sh`	Daily log rotation - rotates JSONL files exceeding 50MB and archives interactions DB rows older than 90 days. Calls `shared/log-rotation.js`. Usage: `./scripts/rotate-logs.sh [--dry-run]`
`disk-space-check.sh`	Weekly disk space monitoring - checks available space on `/`, warns at 20GB free, sends urgent Telegram alert at 10GB. Reports log and DB sizes. Usage: `./scripts/disk-space-check.sh`
`cron-health-check.sh`	Monitors OpenClaw cron jobs for error/timeout states, detects persistent failures, and sends Telegram alerts with dedup. Runs every 30 minutes. Integrates with `tools/cron-log/check-persistent-failures.js` for deeper analysis.
`urgent-email-check.sh`	Cron wrapper for urgent email notification check. Called after Email Refresh; the Node script handles time-window gating internally. Reports failures to cron-updates.
`manage-actions.js`	Action item management CLI. Commands: `list`, `done`, `archive`, `archive-stale`, `stats`. Supports filtering by status, assignee, and overdue items. Used to clean up stale action items and track completion.
`morning-council-status.js`	Morning status check for council systems. Queries LLM interaction logs and validates multi-agent health. Used by morning council cron jobs.
`platform-council-v2.js`	Platform health council using Cursor agent CLI for direct codebase analysis + Opus summarizer for structured JSON output. Analyzes 9 areas: cron health, code quality, test coverage, prompt quality, dependencies, storage, skill integrity, config consistency, and CRM data integrity (contact count drops, database corruption, ingestion pipeline health). Usage: `node scripts/platform-council-v2.js [--dry-run] [--json]`
`platform-council.js`	Removed. Replaced by platform-council-v2.js.
`pre-commit`	Git pre-commit hook. Prevents committing sensitive Chrome profile data and large binary files. Installed in `.git/hooks/pre-commit`.
`lib/security-review-checks.sh`	Security check implementations for `security-review.sh`. Individual check functions sourced by main script.

Cron Jobs

All cron jobs follow a standardized pattern (defined in AGENTS.md):

Log start: cd ~/clawd/tools/cron-log && node log-start.js --job "<name>" → capture run ID
Execute task
Log end: cd ~/clawd/tools/cron-log && node log-end.js --run-id <ID> --status <success|failure> --summary "..."
Send Telegram notification to group -1003725393532 topic 1126 (cron-updates)

For workflow-level behavior (triggers, flow steps, and failure handling), see docs/USE-CASES-WORKFLOWS.md.

OpenClaw Cron Jobs (`~/.openclaw/cron/jobs.json`)

Jobs are configured in ~/.openclaw/cron/jobs.json (count changes over time). All use agentTurn payloads with cron logging and Telegram reporting.

Daily Jobs

Job	Schedule	Purpose
Daily Brief (7am)	Weekdays 7am PST	Generate comprehensive daily brief: meetings, action items, content performance
Morning Council Status Check	Daily 7:10am PST	Validate council system health after nightly runs
Daily CRM Ingestion	Daily 2am PST	Deep CRM contact ingestion from email/calendar
Daily Config Review	Daily 3:20am PST	Review workspace .md files for drift, duplication, stale references
Nightly Security Review	Daily 3:30am PST	Cursor agent CLI security analysis + Opus summarizer. Runs security-review.sh, analyzes findings, alerts on critical/high issues
Daily Platform Health Council	Daily 4am PST	Cursor agent CLI platform health analysis + Opus summarizer. Analyzes cron health, code quality, test coverage, prompt quality, dependencies, storage, skill integrity, config consistency, CRM data integrity
Nightly Business Meta Analysis	Daily 4:30am PST	Independent parallel experts (8 personas) analyze 14 data sources, produce ranked recommendations. Sends digest to Telegram meta-analysis topic
Social Tracker: YouTube Collect	Daily 1:30am PST	Collect YouTube analytics (views, watch time, engagement)
Social Tracker: Instagram Collect	Daily 1am PST	Collect Instagram per-post analytics and account daily snapshots
Social Tracker: X Collect	Daily 1:15am PST	Collect X/Twitter per-post analytics with dual view tracking
Daily Video Catalog Refresh	Daily 6am PST	Refresh 90-day video catalog
Daily Log Rotation	Daily 5:30am PST	Rotate JSONL event logs over 50MB, archive interactions DB rows older than 90 days
Nightly Structured Log Ingest	Daily 5:15am PST	Ingest structured JSONL (`data/logs/all.jsonl` + rotations) and gateway raw logs (`~/.openclaw/logs/gateway*.log`) into `data/logs.db` for query-friendly analysis
OpenClaw Update Check	Daily 9pm PST	Check for OpenClaw platform updates
E2E Tests: Tier 1 (Nightly)	Daily 11pm PST	Skill integration tests (embeddings, reranker, KB, CRM, financials, cron-log, video pitches) - no LLMs, live APIs only
PRD Documentation Sync	Daily 1am PST	Scan workspace for changes, verify database counts and version numbers, update PRD.md. Sends change report to Telegram self-improvement topic.
Nightly Security Review	Daily 3:30am PST	Cursor agent CLI security analysis + Opus summarizer for structured JSON output. Runs security-review.sh, inspects files/permissions/code, produces findings report, alerts on critical/high issues

Hourly Jobs

Job	Schedule	Purpose
Hourly Database Backup	Every hour	Creates encrypted backups via `backup-databases.sh` and uploads to Google Drive "OpenClaw Backups"

Multiple-Times-Hourly Jobs

Job	Schedule	Purpose
Cron Health Check	Every 30 min	Monitors cron jobs for error/timeout states, detects persistent failures, alerts to Telegram

Multiple-Times-Daily Jobs

Job	Schedule	Purpose
Fathom After-Meetings	Every 5 min, 7am–5pm PST	Calendar-aware Fathom polling - checks if meetings ended, triggers sync after buffer period
Email Refresh	Every 30 min, 7am–8pm PST	Lightweight CRM context refresh — fetches new inbound emails from existing contacts, updates context entries and relationship summaries. Also triggers urgent email notification check (time-window gated).
Action Item Completion Check	8am, 12pm, 4pm PST	Checks if pending "waiting on" action items have been fulfilled via email
Slack Sync	Every 3 hours	Sync Slack messages to business-meta-analysis DB
Asana Sync	Every 4 hours	Sync Asana tasks to business-meta-analysis DB and asana-sync.db
HubSpot Sync	Every 4 hours	Sync HubSpot deals and contacts to business-meta-analysis DB
Social Scrape: Instagram & TikTok Followers	Daily 1:45am PST	Profile growth tracking via web scraping

Weekly Jobs

Job	Schedule	Purpose
Weekly Memory Synthesis	Sunday 3:40am PST	Synthesize daily notes into MEMORY.md
Weekly Company Letter Reminder	Sunday 9am PST	Remind about company letter
Weekly Earnings Preview	Sunday 9am PST	Preview upcoming tech/AI earnings reports
Sunday Trash Reminder	Sunday 10am PST	Recycling/trash collection reminder
Weekly Disk Space Check	Sunday 2am PST	Check disk space, alert if below 20GB (warning) or 10GB (urgent)
E2E Tests: Tier 2 (Weekly)	Saturday 10pm PST	Agent turns with live LLMs, costs ~$1-2
E2E Tests: Tier 3 (Weekly)	Saturday 10:30pm PST	Full pipeline with Telegram round-trip, costs ~$2-3

Monthly Jobs

Job	Schedule	Purpose
Monthly Financial Data Reminder	1st of month, 10am PST	DM Matt to export fresh financial data (Transaction List + Account List) for CFO analysis

One-Time / Event Jobs

Earnings report jobs are scheduled as one-time tasks (deleteAfterRun: true) when Matt requests coverage of specific companies. These are created dynamically from the weekly earnings preview and auto-delete after running. Check ~/.openclaw/cron/jobs.json for currently scheduled jobs.

Launchd Services

Plist	Schedule	Purpose
`ai.openclaw.gateway`	Always-on (RunAtLoad + KeepAlive)	OpenClaw gateway server on port 18789

Memory System

Location: memory/

Structure

Path	Purpose
`memory/YYYY-MM-DD.md`	Daily notes - raw capture of conversations, events, tasks. Written first, always.
`MEMORY.md` (root)	Synthesized wisdom - distilled patterns, preferences, lessons. Only loaded in direct chats with Matt.
`memory/heartbeat-state.json`	Heartbeat check timestamps (email, calendar, weather, errorLog, securityAudit)
`memory/tasks/`	Task history - append-only, structured format per `SCHEMA.md`
`memory/tasks/SCHEMA.md`	Task history schema definition
`memory/health/`	Health tracking - food logs (`food-log.json`, `food-log.md`), README

State & Reference Files

File	Purpose
`ai-tweet-feedback.json`	AI tweet feedback patterns (what performs well)
`ai-tweets-search-strategy.json`	Search strategy for AI tweet curation
`ai-tweets-shared.json`	History of shared AI tweets (dedup)
`video-pitches.json`	Video pitch catalog (backup; primary is SQLite DB)
`youtube-competitor-tracking.json`	YouTube competitor tracking data
`matthewberman-twitter-profile.md`	Twitter/X profile reference
`family.md`	Family reference info
`video-catalog-90d.md`	Rolling 90-day video catalog (refreshed daily by cron)
`kb_log.md`	Knowledge base ingestion log
`security-audit-2026-02-10.md`	Security audit findings summary
`security-audit-full-2026-02-10.md`	Full security audit report
`security-review-log.md`	Security review log history

How It Works

Write first: Daily notes (YYYY-MM-DD.md) capture everything in the moment
Synthesize weekly: Cron job (Sunday 3:40am PST) distills daily notes into MEMORY.md
Heartbeat tracking: Checks stored in heartbeat-state.json with timestamps for each check type
Task history: Append-only format, one section per task, never edited after writing

Integrations

Group ID: -1003725393532
Primary interface for CRM queries, notifications, approvals, and cron updates

Topic	ID	Purpose
AI Tweets	225	Curating and drafting AI tweets
Video Ideas	366	Video pitch discussion and feedback tracking
Self-Improvement	403	OpenClaw self-improvement, council digests, debugging
Earnings	694	Financial tracking (revenue, sponsorships, YouTube earnings)
Personal CRM	709	Contact management, relationship tracking, follow-up nudges
Updates	1051	General status updates and announcements
Cron Updates	1126	Automated cron job success/failure notifications
Knowledge Base	1173	KB ingestion and querying notifications
Health	1207	Food logging, symptoms, health tracking reminders
Meta-Analysis	1827	Business meta-analysis digest reports
Meeting Prep	1964	Daily meeting briefings (cron-owned)
Email	2229	Email-related queries and draft proposals
Financials	2774	Financial CSV imports and data queries (confidential - Matt only)

Media handling: Download to /tmp/openclaw-media/, include MEDIA:<path> in reply, delete temp after send.

Slack

Channel	ID	Purpose
ai_trends	C09BJG12CNT	AI trend tracking
video_edits	C070JQGDX7E	Video edit coordination
general	C05PBHL1E2V	General team communication
live_show	C098BRV2D4K	Live show coordination

Auth: Bot token + user token (for sending as Matt) Attribution: Bot messages no prefix; user token messages prefix with 🦞 OpenClaw: Workflows:

Task assignment: Brief acknowledgment ("On it", "Got it"), then work silently and reply with one complete message - no intermediate thinking or status updates
KB saves: Tagged mention + "save" in reply to URL → ingest via KB skill
Video idea triggers: Tagged mention + "potential video idea" → video-idea-pipeline

Google Workspace (via `gog` CLI)

CLI Location: /opt/homebrew/bin/gog
Services: Gmail, Calendar, Drive, Docs, Sheets, Slides, Contacts, Tasks, People, Chat, Classroom
Auth: OAuth tokens in ~/Library/Application Support/gogcli/
Usage: CRM email/calendar scanning, database backups to Drive, file operations
Install: brew install drizzle-team/tap/gog then gog auth login

Asana

Workspace: forwardfuture.ai (1206497863248146)
Projects:
- The Ad Bank / Sponsorship Queue (1212346778656423)
- Video Pipeline (1212455754265217)
- FF Team Meeting (1209311439712808)
- 1:1 with teammate (1208324818579051)
Workflow: "Put Link in Asana" - fetch content, extract info, create task (default: Video Pipeline)
Update rule: Add new info as comments, don't edit description

Todoist

Integration: Via todoist-ts-cli npm package
Usage: Quick task capture, Fathom action items after approval
Install: npm install -g todoist-ts-cli then todoist auth <token>

Financial Data

Skill: skills/financials/
Company: Forward Future Inc
Features: P&L, Balance Sheet, transaction queries, expense analysis, revenue breakdowns, customer/vendor analysis - all via natural language
Data flow: Monthly CSV exports from the accounting system (Transaction List by Date + Account List) sent via Telegram financials topic, then auto-imported, P&L/Balance Sheet generated, and council analysis runs
Council integration: CFO reviewer persona analyzes financial signals (revenue trends, burn rate, cash position, AR/AP, overdue invoices) alongside CRM, YouTube, and HubSpot pipeline data
Confidentiality: Financial data restricted to Matt only (DM or financials topic 2774). Council digests use directional language, not specific numbers.
Cron: Monthly reminder on the 1st at 10am PST
Database: skills/financials/data/financials.db

HubSpot

Skill: skills/hubspot/
Features: Contact, company, deal, and content management via REST API
Sync: tools/business-meta-analysis/sync/hubspot-sync.cjs — paginated sync of deals (with owner, type, description) and contacts (email, name, company, jobtitle, phone, lifecycle stage) to ~/clawd/data/hubspot-sync.db
Config: HUBSPOT_ACCESS_TOKEN in .env

Beehiiv

Skill: skills/beehiiv/
Features: Newsletter platform API -- subscriber management, post analytics, segments, automations, referral program, webhooks, custom fields, tiers
Sync: tools/business-meta-analysis/sync/beehiiv-sync.cjs — syncs publication stats (subscriber counts, open/click rates, churn) and post-level data (subject lines, publish dates, open/click rates, recipients, unsubscribes) to ~/clawd/data/beehiiv-sync.db
Config: BEEHIIV_API_KEY and BEEHIIV_PUBLICATION_ID in .env

Fathom

Integration: API client + polling + Telegram approval flow
Purpose: Meeting recording → transcript extraction → CRM contact matching → insight extraction → action item verification → Todoist task creation
Config: FATHOM_API_KEY in CRM .env

X/Twitter

Skills: x-research-v2 (primary), x-search (legacy wrapper), x-trending-scraper, x-analytics (per-post analytics)
Auth: Pay-per-use X API via X_BEARER_TOKEN (app-only, for search/research); OAuth 1.0a via X_API_KEY/X_API_SECRET/X_ACCESS_TOKEN/X_ACCESS_TOKEN_SECRET (user context, for analytics)
Features: Search, profile lookup, thread analysis, watchlists, trending topics, engagement metrics, per-post analytics (impressions, likes, retweets, bookmarks, shares, follows, media views, URL clicks, profile clicks)
Analytics: x_collect.py / x_query.py in tools/social-tracker/ - stores hourly snapshots with view counts in social_growth.db. Dual view tracking via public_metrics and analytics endpoint.
Default: Cursor agent best-effort mode (don't use live xAI unless needed)

Databases

All databases are SQLite with WAL mode enabled.

Operational logging model is hybrid: structured event logs are canonical in JSONL (~/clawd/data/logs/all.jsonl plus per-event files), while SQLite is used for query-heavy datasets (cron-log.db, interactions.db, and domain databases).

Database	Location	Purpose
CRM	`~/clawd/crm/data/contacts.db`	Contacts, interactions, follow-ups, context (with vectors), meetings, action items, relationship profiles, Box files/chunks/collaborators/links, email draft requests, merge suggestions, meta state
Video Pitches	`~/clawd/data/video-pitches.db`	Video pitch ideas with embeddings for semantic search
Business Meta-Analysis	`~/clawd/data/business-meta-analysis.db`	Source catalog, signal runs, analysis artifacts, recommendations, feedback, deeper-dive requests, weight policies
YouTube Analytics	`tools/social-tracker/db/views.db`	YouTube video analytics (views, watch time, avg view duration/percentage, likes, dislikes, comments, shares, subs gained/lost, thumbnail impressions/CTR) + video metadata (description, tags, category) - ~963 videos tracked
YouTube Data	`tools/social-tracker/db/youtube_data.db`	YouTube video metadata
Social Growth	`tools/social-tracker/db/social_growth.db`	Instagram/TikTok follower metrics + Instagram per-post analytics (ig_media, ig_media_stats with follows/reel view time) + Instagram account daily snapshots (ig_account_stats) + X/Twitter per-post analytics (x_posts with public_metrics view counts, x_post_stats hourly snapshots with 21 metrics)
Cron Log	`~/clawd/data/cron-log.db`	Cron job run history (start/end times, status, summaries)
HubSpot Sync	`~/clawd/data/hubspot-sync.db`	Cached HubSpot deals (with owner, type, description) and contacts (email, name, company, jobtitle, phone, lifecycle stage) with paginated sync
Beehiiv Sync	`~/clawd/data/beehiiv-sync.db`	Cached Beehiiv publication stats (daily subscriber snapshots) and post performance (open/click rates, recipients, unsubscribes)
Asana Sync	`~/clawd/data/asana-sync.db`	Cached Asana tasks (with assignee, notes, tags, section) used by business meta-analysis sync jobs and `scripts/action-items-briefing.js`
Knowledge Base	`skills/knowledge-base/data/knowledge.db`	RAG content with embeddings (~15 sources)
Financials	`skills/financials/data/financials.db`	Financial data: transactions, accounts, generated P&L and Balance Sheet reports. Tables: reports, accounts, transactions, invoices, bills, sync_log
Interactions	`~/clawd/data/interactions.db`	Centralized store of all API calls and LLM interactions with full request/response bodies. Tables: `llm_calls`, `api_calls`. Archived monthly by `log-rotation.js`.
Structured Logs	`~/clawd/data/logs.db`	Query-friendly mirror of both unified structured JSONL logs (`structured_logs` table) and OpenClaw gateway raw logs (`gateway_log_lines` table). Populated nightly by `tools/log-ingest.js` and `tools/gateway-log-ingest.js`.
Model Usage	`~/.openclaw/logs/model-usage.jsonl`	API usage and cost tracking (JSONL, not SQLite)
X Research Cache	`skills/x-research-v2/data/cache/`	File-based search result cache (15-min TTL)
CRM Learning	`~/clawd/crm/data/learning.json`	Learned contact filtering patterns
Video Pitches Count	`~/clawd/data/video-pitches.db`	~30 pitches tracked
Cron Log Runs	`~/clawd/data/cron-log.db`	~325 runs logged

Backup: Hourly via backup-databases.sh -> Google Drive ("OpenClaw Backups" folder), keeps last 7 backups with manifest.json. Backs up all workspace DB files (including ~/clawd/data/logs.db) plus JSONL event logs from ~/clawd/data/logs/, including unified stream all.jsonl.

Log rotation: Daily via scripts/rotate-logs.sh - rotates JSONL files over 50MB, archives interactions DB rows older than 90 days.

Disk monitoring: Weekly via scripts/disk-space-check.sh - alerts to Telegram if disk space drops below 20GB (warning) or 10GB (urgent).

Environment Variables

Canonical `.env` (`~/.openclaw/.env`)

Variable	Purpose
`ASANA_PAT`	Asana Personal Access Token
`HUBSPOT_ACCESS_TOKEN`	HubSpot Private App token
`BRAVE_API_KEY`	Brave Search API key
`XAI_API_KEY`	xAI/Grok API key
`X_BEARER_TOKEN`	X/Twitter API bearer token (app-only, for x-research-v2)
`X_API_KEY`	X OAuth 1.0a Consumer Key (for analytics endpoint)
`X_API_SECRET`	X OAuth 1.0a Consumer Key Secret
`X_ACCESS_TOKEN`	X OAuth 1.0a User Access Token
`X_ACCESS_TOKEN_SECRET`	X OAuth 1.0a User Access Token Secret
`GEMINI_API_KEY`	Google Gemini API key
`SLACK_APP_TOKEN`	Slack app-level token
`SLACK_BOT_TOKEN`	Slack bot token
`SLACK_USER_TOKEN`	Slack user token (send as Matt)
`TODOIST_API_TOKEN`	Todoist API token
`OPENCLAW_GATEWAY_TOKEN`	Gateway auth token
`FIRECRAWL_API_KEY`	Firecrawl web scraping (optional)
`APIFY_API_TOKEN`	Apify scraping (optional)
`BEEHIIV_API_KEY`	Beehiiv API key
`BEEHIIV_PUBLICATION_ID`	Beehiiv publication ID

CRM Environment (from canonical `.env`)

Variable	Purpose
`DATABASE_PATH`	SQLite database path
`EMAIL_ACCOUNTS`	Email accounts to scan
`EXCLUDED_EMAILS`	Emails to exclude from scanning
`GOG_CLI_PATH`	Path to `gog` CLI
`FATHOM_API_KEY`	Fathom meeting API key
`TELEGRAM_*`	Telegram notification settings
`BOX_ENABLED`	Enable/disable Box integration
`BOX_ACCESS_TOKEN`	Box API bearer token
`BOX_ROOT_FOLDER_ID`	Root folder ID to sync from Box
`GMAIL_DRAFT_WRITES_ENABLED`	Safety gate for Gmail draft creation (must be `true` to create drafts)
Various scan/tuning params	Gmail/Calendar scanning configuration

Compatibility paths: ~/clawd/.env, ~/clawd/crm/.env, and ~/clawd/tools/social-tracker/.env are symlinks to ~/.openclaw/.env for legacy script compatibility.

Optional Logging Runtime Overrides

Variable	Purpose
`CLAWD_LOG_LEVEL`	Minimum structured event level (`debug`, `info`, `warn`, `error`)
`CLAWD_LOG_DIR`	Base directory for structured event logs (default `~/clawd/data/logs`)
`CLAWD_UNIFIED_LOG_FILE`	Unified JSONL stream filename inside `CLAWD_LOG_DIR` (default `all.jsonl`)
`CLAWD_STRUCTURED_LOG_DB`	SQLite destination for structured log ingest (default `~/clawd/data/logs.db`)
`CLAWD_GATEWAY_LOG_DIR`	Source directory for gateway raw logs (default `~/.openclaw/logs`)
`COUNCIL_PROGRESS_EVENT_LOGS`	Enable/disable structured council progress events (`review_council_progress`) in unified logs (default enabled)

Platform Config (`~/.openclaw/openclaw.json`)

Contains API keys for Anthropic, Google, xAI, Brave Search, Telegram bot token, Slack tokens, gateway auth token, and skill-specific keys. Template at openclaw.json.example.

Test Infrastructure

Location: tests/

Test Categories

Category	What's Tested
CRM Unit Tests	Config, context system (email-body, email-fetcher, embeddings, extractor, search, storage, summary-storage, relationship-summarizer, response-generator), intelligence modules (contact-classifier), ingestion (batch-approver, ingest-utils), Telegram integration (formatters, menu, email-drafts), DB (meeting-action-items), Gmail (email-draft-coordinator), Box (relevance), Fathom (api-client, api-keys, after-meetings-logic, notifier, processor, todoist), security fixes
CRM Integration Tests	Anti-injection security, context pipeline, Telegram workflow, end-to-end workflows
Shared Module Tests	args, config, db, embeddings, event-log, fs, notification-redaction, reranker, security-council, security-fixes
Skill Tests	clawdhub, humanizer, nano-banana-pro-2, x-search, x-trending-scraper, youtube-sub-ratio, todoist, hubspot, summarize, crm-query, content-draft-generator, self-improving-agent, gemini-video-watch
Tool Tests	agent-wrapper, asana-fetch, log-parser, log-viewer, usage-parser, social-tracker, slack-post, cron-log, business-meta-analysis (deeper-dive, meta-analysis, multi-agent-helpers, persistence, review-council, x-signals), video-pitches (db)
Script Tests	auto-git-sync, backup-databases, restore-databases, action-items-briefing, nightly-business-meta-analysis, log-hub, log-ingest, gateway-log-ingest, nightly-log-ingest, council-deeper-dive, security-review, security-council, openclaw-update-check

Test Infrastructure

File	Purpose
`run-all-tests.sh`	Master test runner
`run-tests.sh`	Individual test execution
`verify-setup.sh`	Setup verification
`delegation-rules.json`	Test delegation rules
`test-scenarios.md`	Test scenario documentation
`TEST-COVERAGE.md`	Test coverage inventory and status
`.github/workflows/tests.yml`	GitHub Actions CI workflow

Configuration Files

Root-level .md files that define workspace behavior:

File	Purpose
`AGENTS.md`	Rules of engagement - safety, security, task execution, model strategy, message consolidation, group chat protocol, cron standards, heartbeat, error reporting, video pitch hard gate
`SOUL.md`	Personality - direct communication, real opinions, brevity mandatory, humor welcome, not a sycophant
`IDENTITY.md`	Identity - name: Clawd, creature: AI with lobster energy, emoji: 🦞
`USER.md`	User info - Matt, PST timezone, early bird (~7am), three email accounts (personal, YouTube, work)
`TOOLS.md`	Environment config - all channel/topic IDs, API token locations, topic behavior guides, Asana project IDs, external tool paths
`MEMORY.md`	Synthesized preferences - Matt's preferences, project history, workflow patterns, operational lessons, strategic notes, email triage patterns, infrastructure notes
`HEARTBEAT.md`	Periodic checklist - monthly security audit, weekly gateway check, daily error log skim and git backup
`SUBAGENT-POLICY.md`	Subagent policy - when to use (searches, API calls, multi-step), when to work directly (simple replies), failure handling (report + retry once)
`RESTORE.md`	New machine setup - prerequisites, clone steps, secret config, dependency install, database restore from Google Drive, channel pairing, verification
`PRD.md`	This file - full feature inventory

Other Directories

`youtube-analysis/`

YouTube competitor analysis and content strategy data.

File	Purpose
`fetch-competitors.py`	Fetches competitor YouTube data using `yt-dlp`
`video-data.json`	Competitor video metadata
`transcripts.json`	Competitor video transcripts
`complete_transcripts.md`	Full transcript analysis
`transcript-analysis-summary.md`	Transcript analysis summary
`SUCCESS-BLUEPRINT-GEMINI.md`	Content success blueprint (Gemini analysis)
`SUCCESS-BLUEPRINT-OPUS.md`	Content success blueprint (Opus analysis)
`VIDEO-IDEAS.md`	Generated video ideas
`VIDEO-IDEAS-TRENDING.md`	Trending video ideas
`transcript-fetch-summary.md`	Summary report of the transcript fetching process

`data/`

Workspace-wide databases and runtime data:

cron-log.db - Cron job run history
video-pitches.db - Video pitch ideas with embeddings
business-meta-analysis.db - Business intelligence analysis snapshots and recommendations
logs.db - SQLite mirror of structured logs and gateway raw logs (ingested nightly from data/logs/all.jsonl + ~/.openclaw/logs/gateway*.log)
chrome-debug-profile/ - Dedicated Chrome user profile for the browser-control skill. Separate from personal Chrome to isolate cookies/sessions. Launched via skills/browser-control/scripts/launch-chrome.sh.
logs/ - Structured JSONL event logs (slack_post, kb_ingest_end, security_review, etc.) plus unified stream all.jsonl for single-pane log review (included in hourly Drive backups)

`life/`

Empty directory, reserved for future use.

`docs/`

File	Purpose
`WORKSPACE-FILES.md`	Guide to workspace file organization, prompt injection rules
`USE-CASES-WORKFLOWS.md`	Operational guide for major use cases, custom functionality, and workflow playbooks
`OPUS-PROMPTING-GUIDE.md`	Opus 4.6 prompting best practices - consult before writing/editing prompts
`SECURITY-BEST-PRACTICES.md`	Security guide covering gateway hardening, channel access control, credential management, prompt injection defense, automated monitoring, data protection, tool sandboxing, and operational hygiene
`SLACK-SETUP.md`	Slack integration setup with security model
`slack-config-snippet.json`	Slack config example

`reference/`

File	Purpose
`recycling.md`	Mill Valley recycling schedule (alternating weeks)
`youtube-competitors.md`	Competitor monitoring reference (Theo, Wes Roth, AI Search)
`moltbot/`	Clone of the OpenClaw platform source repo - used as a reference for understanding platform internals (gateway, channels, agent system, cron, memory, CLI)

`.learnings/`

Captured corrections and learnings for the self-improving agent. Currently contains one entry: asana_link_workflow (how to handle "put link in Asana" requests).

`state/`

Mutable runtime state files. Contains README.md with guidelines for state file usage.

`.clawdhub/`

Skill registry lock file (lock.json) tracking installed skill versions and installation timestamps.

Last updated: 2026-02-17 (OpenClaw 2026.2.15; added E2E test suite with 3 tiers and cron scheduling, cron health monitoring, persistent failure detection, action item management CLI, workspace state locking, structured event logging instrumented across 90+ files, daily log rotation cron job, morning council status check, council recommendations module, telegram delivery helper, env utilities module)

mberman84/PRD.md

PRD.md - Product Requirements & Feature Inventory

Table of Contents

Architecture Overview

OpenClaw Platform Configuration

Gateway

Model Providers

Agent Settings

Plugins

Channels

Skill Management

CRM System

What It Does

Contact Discovery

Database Schema

Architecture: Handler Modules (crm/src/handlers/)

Intent Detection (crm/src/intent-detector.js)

Scripts

Core Service (crm/src/)

Database Access Layer (crm/src/db/)

Contact Ingestion Pipeline (crm/src/ingestion/)

Telegram Interface (crm/src/telegram/)

Context System (crm/src/context/)

Box Integration (crm/src/box/)

Gmail Draft System (crm/src/gmail/)

Relationship Intelligence (crm/src/intelligence/)

Utilities (crm/src/utils/)

Natural Language Queries

Fathom Meeting Integration

What It Does

Components

Workflow

Modes

Scripts

Skills

Installed Skills

browser-control

clawdhub

crm-query

beehiiv

hubspot

humanizer (v2.1.1)

knowledge-base

financials

model-usage-tracker

nano-banana-pro-2

self-improving-agent

summarize

todoist

video-idea-pipeline

x-research-v2

x-analytics

x-search

excalidraw

gemini-video-watch

x-trending-scraper

youtube-sub-ratio

Preview Skills (In Development)

content-draft-generator

research

Tools

Video Pitches Database (tools/video-pitches/)

Social Tracker (tools/social-tracker/)

Cron Log (tools/cron-log/)

Standalone Tools

Patches (tools/patches/)

Shared Modules

Scripts & Automations

Cron Jobs

OpenClaw Cron Jobs (~/.openclaw/cron/jobs.json)

Daily Jobs

Hourly Jobs

Multiple-Times-Hourly Jobs

Multiple-Times-Daily Jobs

Weekly Jobs

Monthly Jobs

One-Time / Event Jobs

Launchd Services

Memory System

Structure

Architecture: Handler Modules (`crm/src/handlers/`)

Intent Detection (`crm/src/intent-detector.js`)

Core Service (`crm/src/`)

Database Access Layer (`crm/src/db/`)

Contact Ingestion Pipeline (`crm/src/ingestion/`)

Telegram Interface (`crm/src/telegram/`)

Context System (`crm/src/context/`)

Box Integration (`crm/src/box/`)

Gmail Draft System (`crm/src/gmail/`)

Relationship Intelligence (`crm/src/intelligence/`)

Utilities (`crm/src/utils/`)

Video Pitches Database (`tools/video-pitches/`)

Social Tracker (`tools/social-tracker/`)

Cron Log (`tools/cron-log/`)

Patches (`tools/patches/`)

OpenClaw Cron Jobs (`~/.openclaw/cron/jobs.json`)

Google Workspace (via `gog` CLI)

Canonical `.env` (`~/.openclaw/.env`)

CRM Environment (from canonical `.env`)

Platform Config (`~/.openclaw/openclaw.json`)

`youtube-analysis/`

`data/`

`life/`

`docs/`

`reference/`

`.learnings/`

`state/`

`.clawdhub/`