CrepuscularIRIS · 20bytes · Apr 26, 2026 · Apr 26, 2026
diff --git a/.env.example b/.env.example
@@ -0,0 +1,59 @@
+# Copy to .env.local for this repo, or put the same variables in ~/.hermes/.env.
+# Do not commit real API keys.
+
+# Identity
+BEATLESS_GITHUB_AUTHOR=your-github-login
+ZOTERO_WEB_USERNAME=your-zotero-web-name
+
+# Runtime paths
+BEATLESS_WORKSPACE=~/workspace
+BEATLESS_RESEARCH_DIR=~/research
+BEATLESS_BLOG_DIR=~/blog
+# Strong boundary: generated blog output only. Do not point this at src/content/blogs.
+BEATLESS_BLOG_POSTS_SUBDIR=src/content/auto-research
+BEATLESS_OBSIDIAN_VAULT=~/obsidian-vault
+BEATLESS_HERMES_SHARED=~/.hermes/shared
+
+# Claude Code execution
+CLAUDE_BIN=claude
+BEATLESS_CLAUDE_MODEL=sonnet
+BEATLESS_CLAUDE_MAX_BUDGET_USD=5.00
+BEATLESS_GITHUB_PR_QUALITY_THRESHOLD=7.0
+BEATLESS_GEMINI_MODEL=gemini-3.1-pro-preview
+BEATLESS_CODEX_MODEL=gpt-5.5
+BEATLESS_CODEX_REASONING_EFFORT=xhigh
+
+# GitHub
+GH_TOKEN=
+
+# Zotero
+ZOTERO_API_KEY=
+ZOTERO_USER_ID=
+ZOTERO_AUTO_HARVEST_COLLECTION=
+ZOTERO_A_TIER_COLLECTION=
+ZOTERO_SCOUTING_COLLECTION=
+ZOTERO_DEFAULT_COLLECTION=
+
+# Optional model/provider keys used by Hermes or Claude plugins
+ANTHROPIC_API_KEY=
+KIMI_API_KEY=
+KIMI_BASE_URL=https://api.kimi.com/coding
+STEPFUN_API_KEY=
+STEPFUN_BASE_URL=https://api.stepfun.com/step_plan/v1
+STEPFUN_MODEL=step-3.5-flash
+MINIMAX_API_KEY=
+MINIMAX_BASE_URL=https://api.minimaxi.com/anthropic
+MINIMAX_MODEL=MiniMax-M2.7
+MINIMAX_MODEL_HIGHSPEED=MiniMax-M2.7-highspeed
+MINIMAX_TTS_MODEL=speech-2.8-hd
+MINIMAX_TTS_MODEL_HD=speech-02-hd
+MINIMAX_TTS_MODEL_TURBO=speech-02-turbo
+MINIMAX_VOICE_CLONE_MODEL=voice_clone
+MINIMAX_VOICE_DESIGN_MODEL=voice_design
+MINIMAX_IMAGE_MODEL=image-01
+MINIMAX_MUSIC_MODEL=music-2.5+
+MINIMAX_MUSIC_MODEL_ALT=music-2.5
+MINIMAX_VIDEO_MODEL_T2V=MiniMax-Hailuo-2.3
+MINIMAX_VIDEO_MODEL_I2V=MiniMax-Hailuo-2.3
+MINIMAX_VIDEO_MODEL_SEF=MiniMax-Hailuo-02
+MINIMAX_VIDEO_MODEL_S2V=S2V-01
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,21 @@
 .claude/
+.codex
+.env
+.env.local
+.env.*.local
+.mcp.json
+README.local.md
+
+# Local external clones / scratch links
+gsd-2
+gsd-2/
+gsd-2.empty-before-link/
 
 scripts/__pycache__/
+hermes-scripts/__pycache__/
+dashboard/backend/__pycache__/
+dashboard/backend/.venv/
+dashboard/frontend/node_modules/
 
 runtime/scheduler/.scheduler.lock
 runtime/jobs/*
@@ -13,3 +28,6 @@ runtime/nlm/*
 runtime/soak/*
 !runtime/soak/.gitkeep
 .gemini-tasks/
+
+# Local/deprecated runtime archives
+archive/
diff --git a/AUDIT-20260422.md b/AUDIT-20260422.md
@@ -38,16 +38,16 @@ These can conflict if both are active. The Hermes system is the v3 design; the h
 
 ## 2. Issues Found
 
-### Issue 1: Path drift — `yarizakurahime` references remain
+### Issue 1: Path drift — `<previous-local-user>` references remain
 **Severity**: HIGH — will cause failures on this machine
 **Files affected**:
-- `scripts/heartbeat-driver.sh:13` — `SHARED_DIR="/home/yarizakurahime/..."`
+- `scripts/heartbeat-driver.sh:13` — `SHARED_DIR="/home/<previous-local-user>/..."`
 - `scripts/cron-driver.sh:7,12` — usage comment + `LOG_DIR`
-- `scripts/harness/notify-user.sh:24` — `cd /home/yarizakurahime/claw`
+- `scripts/harness/notify-user.sh:24` — `cd /home/<previous-local-user>/claw`
 - `scripts/harness/gateway-supervisor.sh:3,4,5` — LOG, GWLOG, CMD paths
 - `scripts/openclaw/gateway-supervisor.sh:3,4,5` — same as above (duplicate)
 
-**Fix**: `sed -i 's|/home/yarizakurahime|/home/lingxufeng|g'` on all affected files.
+**Fix**: `sed -i 's|/home/<previous-local-user>|/home/<your-user>|g'` on all affected files.
 **Status**: [x] FIXED 2026-04-22 — 25+ files, ~88 replacements across scripts/, agents/, docs/
 
 ### Issue 2: Heartbeat contract mismatch
@@ -129,7 +129,7 @@ These can conflict if both are active. The Hermes system is the v3 design; the h
 
 | # | Issue | Severity | Fix | Done? |
 |---|-------|----------|-----|-------|
-| 1 | Path drift (yarizakurahime) | HIGH | sed replace in 25+ files (~88 refs) | [x] FIXED 2026-04-22 |
+| 1 | Path drift (<previous-local-user>) | HIGH | sed replace in 25+ files (~88 refs) | [x] FIXED 2026-04-22 |
 | 2 | Heartbeat contract mismatch | MEDIUM | Legacy — Hermes cron is primary | [ ] WONTFIX (legacy v2) |
 | 3 | Result file missing in auto-pr.sh | LOW | Add .result output | [x] FIXED 2026-04-22 |
 | 4 | Interactive rebase | HIGH | Non-interactive squash | [x] FIXED 2026-04-22 |
@@ -149,7 +149,7 @@ These can conflict if both are active. The Hermes system is the v3 design; the h
 | 11 | github-pr.py label coverage | Added "help wanted" and "bug" labels (was only "good first issue") |
 | 12 | github-pr.py empty output | Structured status reporting: PIPELINE_ERROR on empty stdout, status JSON file, PR URL extraction |
 | 13 | exp-status.md missing Agent | Added Agent to allowed-tools frontmatter |
-| 14 | Git email | Changed global git email from [email protected] to [email protected] (GitHub verified primary) |
+| 14 | Git email | Changed global git email from <private-email> to <verified-email> (GitHub verified primary) |
 | 15 | MiniMax skill pack | Installed 7 MiniMax skills via hermes skills tap + install |
 | 16 | Hermes skills cleanup | Disabled codex + opencode skills (claude-code only); skills.disabled in config.yaml |
 | 17 | PR Pipeline interval | Shortened from 150m to 60m |

diff --git a/README.md b/README.md
@@ -1,83 +1,135 @@
-# Beatless — Autonomous Agent Constellation
+# Beatless
 
-Hybrid AI orchestration system for open-source contribution, technical blogging, and ML research. Hermes Agent handles scheduling and information gathering; Claude Code handles deep execution.
+Autonomous agent orchestration for open-source contribution, technical writing, and ML research.
 
-## Current State: Constellation v3
+Beatless is a hybrid control plane: a lightweight scheduler watches for useful work, then routes deep execution to Claude Code, Codex, Gemini, GitHub, Zotero, and local experiment workspaces.
 
-```
-Hermes Agent (Kimi K2.6 orchestrator)
-  ├── Cron: 4 active jobs
-  │     ├── GitHub Response    — hourly PR comment triage
-  │     ├── GitHub PR Pipeline — hourly issue discovery → full PR submission
-  │     ├── Auto Research      — 4h experiment analysis cycles
-  │     └── Blog Maintenance   — 12h content audit + writing (MiniMax M2.7)
-  │
-  ├── Models
-  │     ├── Kimi K2.6      — orchestration, planning, review
-  │     ├── Step 3.5 Flash — fast execution, tool chains, web search
-  │     └── MiniMax M2.7   — writing, image gen, TTS, video, documents
-  │
-  └── Wake-gate scripts → Claude Code (on-demand)
-        ├── /github-pr       — 12-phase PR pipeline with triple review
-        ├── /pr-followup     — maintainer comment response
-        └── /exp-*           — ML experiment lifecycle (see below)
-```
+![Beatless framework](docs/assets/framework.png)
 
-## Experiment Command Pack (exp-*)
+## What It Does
 
-Five commands encoding a two-path research methodology for ML experiments:
+| Area | Purpose |
+| --- | --- |
+| GitHub response | Watch open PRs and surface maintainer comments that need action. |
+| GitHub PR pipeline | Discover issues, evaluate repositories, implement fixes, review, and prepare PRs. |
+| Research automation | Resume or halt experiment workspaces based on recorded state. |
+| Paper workflow | Harvest papers, deduplicate against Zotero, and sync metadata into notes. |
+| Dashboard | Show agents, pipelines, experiment status, GPU state, and recent activity. |
+| CLI bridges | Route Claude Code agents through local Codex and Gemini CLIs. |
 
-| Command | Purpose |
-|---------|---------|
-| `/exp-status` | Workspace readiness diagnostic (GPU, data, plugins) |
-| `/exp-init` | Initialize experiment branch, planning files, baseline run |
-| `/exp-discover` | Generate hypotheses via idea-first or application-first path |
-| `/exp-run` | Autonomous experiment loop (quick: single-GPU / full: dual-GPU A/B) |
-| `/exp-review` | Multi-agent review with continue/pivot/rollback/halt verdict |
+## Architecture
 
-Integrates: Codex (code edits), Gemini (literature + direction review), Superpowers (brainstorming), GSD (verification), Planning-with-files (state persistence).
+Beatless separates scheduling from execution.
 
-## PR Pipeline
+- Hermes handles cron, wake gates, lightweight status checks, and routing.
+- Claude Code handles long-running reasoning and command execution.
+- Codex focuses on code edits, feasibility checks, and review.
+- Gemini focuses on literature grounding, large-context review, and critique.
+- Zotero and Obsidian hold research inputs and reading outputs.
+- The dashboard reads JSON state from local collectors and renders it through a decoupled frontend.
 
-12-phase process from issue discovery to PR submission:
+## Repository Layout
 
-1. Discover claimable issues (good first issue, help wanted, bug)
-2. Evaluate repo (CONTRIBUTING.md, recent PRs, test infrastructure)
-3. Fork, clone, baseline tests
-4. Implement fix (Codex write-mode)
-5. Triple review (Gemini correctness + Codex architecture + Claude quality gate)
-6. Submit PR with evidence-based scoring
+| Module | Description |
+| --- | --- |
+| `commands/exp` | Slash commands for experiment status, init, discovery, run, and review. |
+| `commands/agents` | Claude Code agent wrappers for Codex CLI and Gemini CLI. |
+| `hermes-scripts` | Wake-gate scripts for GitHub, Zotero, research, blog, and preflight checks. |
+| `dashboard` | FastAPI backend, SSE stream, and Vite frontend. |
+| `pipelines` | Pipeline behavior specs and operating rules. |
+| `docs`, `design`, `plan` | Architecture notes, migration status, and design records. |
 
-Quality controls: anti-inflation (no self-review), revert-test-reapply verification, minimum 7.5/10 score gate.
+## Quick Start
 
-## Repository Structure
+Create local configuration:
 
+```bash
+cp .env.example .env.local
 ```
-commands/exp/           # Active: exp-* command pack (903 lines)
-design/                 # Architecture: CONSTELLATION v1 → v3 evolution
-standards/              # PR guidelines, contribution protocols
-pipelines/              # Active pipeline specs (github-pr.md, blog-maintenance.md)
-docs/                   # HERMES integration, migration status
-agents/aoi/             # Aoi — scheduler persona (SOUL.md)
-archive/                # Deprecated v2 infrastructure
-  ├── v2-deprecated/    #   Heartbeat agents, shell runners, harness scripts
-  └── deprecated-commands/  #   research-analyze.md, research-train-loop.md
+
+Fill only the variables you need. Keep real keys in `.env.local` or your private runtime environment. Do not commit secrets.
+
+Run the local preflight:
+
+```bash
+python3 hermes-scripts/preflight.py
 ```
 
-## Planned (Next Stages)
+Run safe dry-runs:
+
+```bash
+python3 hermes-scripts/auto-research.py --dry-run
+python3 hermes-scripts/github-response.py --dry-run
+python3 hermes-scripts/github-pr.py --dry-run --issue-limit 1 --approved-limit 1 --per-query-limit 1 --skip-closed-pr-history
+python3 hermes-scripts/paper-harvest.py --dry-run --max-new 1
+```
+
+## Dashboard
+
+Start the local dashboard:
+
+```bash
+cd dashboard
+./start.sh
+```
+
+Default endpoints:
+
+- UI: `http://127.0.0.1:3720`
+- API: `http://127.0.0.1:3721/api/status`
+- SSE: `http://127.0.0.1:3721/api/events`
 
-- **Aoi** — Digital persona on [OpenRoom](https://github.com/MiniMax-AI/OpenRoom) platform. Currently scheduler-only; planned evolution into embodied agent with visual presence.
-- **OpenRoom Integration** — MiniMax-powered desktop environment for Aoi. Workspace, apps, real-time interaction.
-- **Beatless Framework Rewrite** — Current repo serves as architecture documentation and archive. Future rewrite planned to consolidate the Hermes + ClaudeCode hybrid pattern into a clean framework.
+The dashboard is intentionally decoupled:
+
+- backend collectors produce JSON only;
+- the frontend consumes the `/api/*` contract;
+- SSE pushes full state every 10 seconds;
+- the default host is local-only.
+
+## Experiment Commands
+
+| Command | Role |
+| --- | --- |
+| `/exp-status` | Check workspace readiness, runtime state, and integration availability. |
+| `/exp-init` | Initialize planning files, branch state, and baseline expectations. |
+| `/exp-discover` | Generate research hypotheses unless the workspace is already halted. |
+| `/exp-run` | Execute or resume an experiment loop with halt/rollback guards. |
+| `/exp-review` | Review the latest round and choose continue, pivot, rollback, or halt. |
+
+Smoke workspaces halt after one verified run. Real experiment workspaces should provide a substantive `program.md` or `Task.md`.
+
+## Public-Repo Safety
+
+This repository is designed to keep machine-specific state out of Git.
+
+Ignored local-only files include:
+
+- `.env`, `.env.local`, and `.env.*.local`
+- `.mcp.json`
+- local dependency folders and Python caches
+- local GSD clones or scratch links
+- local runtime archives
+
+Use `.env.example` as the public template and keep provider keys, Zotero IDs, GitHub tokens, and local paths in private configuration.
 
 ## Requirements
 
-- [Hermes Agent](https://github.com/NousResearch/hermes-agent) v0.10.0+ (gateway + cron)
-- Claude Code CLI (`claude`) with Opus/Sonnet
-- GitHub CLI (`gh`, authenticated)
-- Codex and Gemini available as Claude Code plugins
-- `uv` for Python, `pnpm` for JS/TS
+- Python with `uv`
+- Node.js and npm
+- GitHub CLI (`gh`)
+- Claude Code CLI (`claude`)
+- Codex CLI (`codex`)
+- Gemini CLI (`gemini`)
+- Optional: Hermes Agent, Zotero API access, NVIDIA tooling for GPU experiments
 
 ## License
 
 MIT
+
+## GitHub Impact
+
+Star growth can be viewed with GitHub Star History:
+
+[![Star History Chart](https://api.star-history.com/svg?repos=20bytes/Beatless&type=Date)](https://star-history.com/#20bytes/Beatless&Date)
+
+Direct link: [https://star-history.com/#20bytes/Beatless&Date](https://star-history.com/#20bytes/Beatless&Date)
diff --git a/archive/ACCEPTANCE_CHECKLIST.md b/archive/ACCEPTANCE_CHECKLIST.md