Add repo conventions and cron documentation

README.md

@@ -0,0 +1,57 @@
+# openclaw-ops
+
+Operational repo for Ben's OpenClaw workspace.
+
+This repo is the versioned source of truth for:
+- custom skills
+- scripts and helpers
+- cron/automation definitions
+- docs and runbooks
+- core workspace guidance files
+
+It intentionally does **not** track volatile runtime state, private memory, auth artifacts, or mailbox data.
+
+## What is tracked
+
+- `skills/` — custom AgentSkills and helper scripts
+- `scripts/` — reusable operational scripts
+- `docs/` — runbooks, architecture notes, integration docs
+- `cron/` — documented recurring jobs and schedules
+- selected workspace guidance files:
+  - `AGENTS.md`
+  - `SOUL.md`
+  - `USER.md`
+  - `TOOLS.md`
+  - `PROJECTS.md`
+  - `HEARTBEAT.md`
+  - `IDENTITY.md`
+
+## What is not tracked
+
+- `MEMORY.md`
+- `memory/`
+- `state/`
+- `mail/`
+- runtime/local directories like `.openclaw/`, `.opencode/`, `tmp/`
+- generated caches and auth material
+
+## Working pattern
+
+Recommended workflow:
+1. Make changes in the workspace.
+2. Commit small, coherent units of work.
+3. Push when the task is complete or the checkpoint is useful.
+
+Default philosophy:
+- commit often
+- push deliberately
+- never commit secrets
+- keep operational state out of git unless intentionally templated
+
+## Repo conventions
+
+See `docs/repo-conventions.md` for commit/push guidance and repo hygiene.
+
+## Cron / automation
+
+See `cron/README.md` for the current recurring-job layout and documentation pattern.

cron/README.md

@@ -0,0 +1,30 @@
+# Cron / Automation
+
+This directory documents recurring jobs and their schedules.
+
+Goal: make it obvious what runs, when it runs, why it exists, and what script/skill it depends on.
+
+## Layout
+
+- `*.md` — one file per recurring job
+- each file should record:
+  - job name
+  - purpose
+  - schedule
+  - entrypoint command/script
+  - dependencies
+  - expected output/behavior
+  - notes on state or alerting
+
+## Current documented jobs
+
+- `daily-overview.md`
+- `github-notifications.md`
+- `capmetro-monitor.md`
+- `gmail-unread-poll.md`
+
+## Notes
+
+This folder is documentation-first.
+
+It does not need to mirror the exact runtime scheduler format as long as it clearly explains the active pattern and entrypoints.

cron/capmetro-monitor.md

@@ -0,0 +1,31 @@
+# CapMetro Monitor
+
+## Purpose
+
+Watch for CapMetro service changes relevant to Ben's commute, especially Route 5 and MetroRail-related monitoring assets.
+
+## Entrypoints
+
+- Skill: `skills/capmetro-monitor/`
+- Primary monitor: `skills/capmetro-monitor/scripts/monitor.sh`
+- Change check: `skills/capmetro-monitor/scripts/check-changes.sh`
+- Route status helper: `skills/capmetro-monitor/scripts/route5-status.sh`
+- Additional watch scripts:
+  - `skills/capmetro-monitor/scripts/watch-departure.sh`
+  - `skills/capmetro-monitor/scripts/watch-departure-v2.sh`
+  - `skills/capmetro-monitor/scripts/monitor-route5.js`
+
+## Schedule
+
+- Recurring
+- Exact active runtime schedule should be recorded here when finalized
+
+## Expected behavior
+
+- Checks for service changes and commute-relevant updates
+- Translates transit-operator language into plain English summaries
+- Supports route/status-specific helper workflows
+
+## Notes
+
+Prefer GTFS-driven or documented skill behavior over ad hoc scraping where possible. If the operational entrypoint changes, update this doc.

cron/daily-overview.md

@@ -0,0 +1,34 @@
+# Daily Overview Reminder
+
+## Purpose
+
+Provide a daily operational overview that summarizes:
+- open projects
+- pending reminders
+- yesterday summary
+- behavioral rules pending review
+
+## Trigger
+
+- Scheduled reminder / automation
+- Current reminder text requests reading `memory/behavior-rules-pending.md` before the behavioral-rules section
+
+## Inputs
+
+- `state/projects.json`
+- reminder/runtime state if present
+- `memory/YYYY-MM-DD.md`
+- `memory/behavior-rules-pending.md`
+
+## Expected behavior
+
+- Summarize open projects
+- Report pending reminders, if any
+- Summarize the prior day
+- Review pending behavioral rules
+- Add an Approval Queue with `Approve / Reject?` per candidate rule
+- If none exist, explicitly say: `No pending candidate rules.`
+
+## Notes
+
+This job mixes tracked code/docs with untracked local memory/state. The implementation should rely on local runtime files without committing those files to git.

cron/github-notifications.md

@@ -0,0 +1,33 @@
+# GitHub Notifications Check
+
+## Purpose
+
+Review GitHub notifications for PR activity and major releases, with filtering to reduce noise.
+
+## Entrypoint
+
+- Skill: `skills/github-notifications/`
+- Main wrapper: `skills/github-notifications/scripts/cron-wrapper.sh`
+- Check script: `skills/github-notifications/scripts/check.sh`
+- Optional dismissal helper: `skills/github-notifications/scripts/auto-dismiss.sh`
+
+## Schedule
+
+- Recurring
+- Exact active schedule should be recorded here when finalized in the runtime scheduler
+
+## Expected behavior
+
+- Checks notification state
+- Surfaces relevant PR activity
+- Highlights major releases and selected dev builds
+- Uses local state to avoid duplicate alerts
+
+## State
+
+- Local generated state file is ignored from git
+- Current ignored file pattern: `skills/**/state.json`
+
+## Notes
+
+If runtime behavior changes, update this file alongside the skill or wrapper changes.

cron/gmail-unread-poll.md

@@ -0,0 +1,24 @@
+# Gmail Unread Poll
+
+## Purpose
+
+Poll unread Gmail state for triage/review workflows.
+
+## Entrypoint
+
+- Script: `scripts/gmail-unread-poll.sh`
+
+## Schedule
+
+- Recurring or ad hoc, depending on how the scheduler is configured
+- Record the exact active schedule here if it becomes a standing job
+
+## Expected behavior
+
+- Checks unread Gmail state
+- Supports lightweight inbox monitoring/triage workflows
+- May feed reminder or review flows depending on runtime usage
+
+## Notes
+
+Do not commit mailbox contents, auth artifacts, or generated local state.

docs/repo-conventions.md

@@ -0,0 +1,70 @@
+# Repo Conventions
+
+## Purpose
+
+Keep OpenClaw automation durable, reviewable, and easy to recover on another machine.
+
+## Commit rules
+
+Prefer small, descriptive commits.
+
+Examples:
+- `add gmail unread poll helper`
+- `document capmetro monitor workflow`
+- `tighten model selector validation`
+- `add cron docs for github notifications`
+
+Avoid vague messages like:
+- `updates`
+- `misc fixes`
+- `stuff`
+
+## Push rules
+
+Default pattern:
+- commit locally when work reaches a coherent checkpoint
+- push when the task is complete, reviewable, or worth backing up remotely
+
+Do not auto-push every tiny edit by default.
+
+## What belongs in git
+
+Commit:
+- reusable scripts
+- custom skills
+- docs/runbooks
+- cron wrappers and automation definitions
+- config examples and templates
+
+Usually do not commit:
+- secrets
+- auth artifacts
+- local caches
+- volatile machine state
+- private journal/memory data
+- mailbox content or exports
+
+## Sensitive-but-trackable files
+
+These may be appropriate in a private repo, but should be treated carefully:
+- `TOOLS.md`
+- `USER.md`
+- infrastructure notes
+- internal URLs and hostnames
+
+If the repo is ever made less private, review those first.
+
+## Suggested maintenance loop
+
+After meaningful work:
+1. `git status`
+2. review changed files
+3. commit with a precise message
+4. push when appropriate
+
+## Future enhancements
+
+Potential later upgrades:
+- pre-commit checks for obvious secrets
+- periodic backup tags
+- release notes for major automation milestones